变更日志

本文件记录 HeyWakeup 的所有重要变更，格式遵循 Keep a Changelog， 版本号遵循 语义化版本 2.0.0。

版本重定义说明：v1.0.0 之前的开发期历史（旧编号 v1.0.0 ~ v1.3）不再单独归档， 可通过 git 历史追溯。自 2026-10-18 起，当前能力全集统一以 v1.0.0 作为首个正式发布版本。

[Unreleased]

新增

• 直分发离线许可证（方案 A）：直分发版新增 Ed25519 离线许可证 key，购买后粘贴即可解锁 Pro； key 只保存在本机钥匙串，无网络请求、不上传设备信息。新增 tools/license-keygen.swift 离线签发工具； 授权页改为「购买 Pro / 输入许可证密钥」，购买入口走 Apsdai 国际站。
• Apsdai 上架物料：新增 docs/apsdai-listing.md（商品字段、文案、邮件模板、 密钥导入、素材与上线清单）、EULA/退款政策页面、/buy/ 购买页与 512×512 logo/截图素材。
• 内部测试 Beta 构建：BETA=1 BETA_EXPIRES=2026-12-31T23:59:59Z ./build.sh 生成 build/HeyWakeup-beta.app，在到期日前解锁 Pro，到期后回到试用结束态；授权页显示有效期， 不再引导 App Store。正式构建会拒绝携带 HWBetaExpiresAt 的包，发布流水线也拒绝 BETA=1。
• URL scheme 自动化：heywakeup://activate?mode=clamshell&minutes=60、deactivate、toggle、 pause、resume、status。activate 只开不关（幂等），toggle 才切换；支持 minutes/hours/seconds/duration，最长 7 天。可直接用于终端、Shortcuts 的「打开 URL」， 也可在菜单栏图标被隐藏时作为紧急出口。Info.plist 已注册 heywakeup scheme。
• 外接屏优先（可选）：设置 → 通用 →「外接显示器时暂停合盖接管」（默认关）。开启后检测到外接屏 时不接管合盖，交给 macOS 原生 clamshell；合盖瞬间不会释放已有标志（避免立刻睡眠）， 开盖后才生效。外接屏存在时，「屏幕常亮」不再因合盖被无条件撤掉。
• 远程会话保护：识别屏幕共享 / VNC / Sunshine / UU Remote 等远控会话（要求同时持有 UserIsActive 或 display 断言，排除 sshd 常驻进程），期间保持显示链路；远程断开后 120s 宽限再结束自动会话，避免刚断开就睡眠、无法重连。
• 会话完整性看门狗：1 秒心跳 + willSleep / didWake 记录。合盖会话期间若系统仍然睡眠 （空档 > 15s），会立即重推合盖标志、在面板显示橙色提示并发送通知，不再"界面显示工作中、实际已睡"。 开盖主动睡眠、熄屏不睡下的手动睡眠不会误报。
• 合盖激活失败不再假装成功：IOPMrootDomain 置位失败时回滚到关闭态，面板提示原因并可直接 改用「熄屏不睡」；不再出现"模式已选中但实际没生效"。
• 兼容性自检与诊断报告（偏好设置 → 通用 → 维护）：非破坏性检查合盖接口、断言读回、电池、 温度、登录项、屏幕与会话完整性；报告包含机型 / 系统 / 合盖通道 / 断言 / pmset / 最近日志， 完全本地生成，不含序列号、主机名、账号或购买凭据。直分发版另支持 HeyWakeup --diagnose > report.txt，方便没有 Apple Silicon 机器时让外部测试者回传现场。
• MAS 构建的「用户选择文件」权限由只读改为读写（用于导出诊断报告）。

修复

• 触发器挂起永久失效：用户手动停止自动会话后，常驻条件（例如远控软件的后台进程一直存在） 永远等不到“条件解除”，自动接管会永久失效。现在这种手动停止改为 30 分钟冷却后自动恢复； 手动会话 / 显式 pause 仍保持原语义（条件解除或手动恢复），不会到点自动重开。面板按暂停原因显示准确文案 （冷却剩余 / 启动时条件已满足 / 点按恢复），不再一律写“条件解除后自动恢复”。
• 停止来源可归因：stop() 现在记录来源（用户 / 快捷键 / URL / 触发器 / 场景 / 程序调用 / 到时 / 低电量 / 热保护）；诊断报告新增「上次停止」与挂起原因 / 冷却截止时间， 日志不再把用户停止与触发器结束统一写成“用户/触发器”。
• 诊断时间统一为本地时区：诊断日志与报告此前用 UTC（Z），文件名与 pmset 用本地时间， 看起来相差 8 小时；现统一输出带偏移的本地时间（如 +08:00），报告并标注当前时区。 报告新增「可执行文件时间」，便于确认是否来自重新构建后的版本。
• 单测污染真实数据：测试会把会话写入用户的 sessions.json（曾出现 797 次测试会话）， 并把模拟的过热/失败写进 HeyWakeup.log。test.sh 现在以 HEYWAKEUP_TEST_MODE=1 运行， 日志写入临时文件、统计只保留内存。
• 电源通知去抖：IOPS 通知会因电量百分比变化触发，导致合盖期间每 5 分钟误报一次 「电源变化」并重推标志；现只在 AC/电池类型真正切换时回调。
• 屏幕常亮在「合盖不睡」下失效：此前该模式无条件丢弃 display 断言，导致开盖时勾选「屏幕常亮」 也会在系统设定的时间后熄屏；现改为开盖保持、合盖立即撤掉（散热 / 烧屏护栏不变）。
• 屏幕常亮静默失效：电源断言改为按内核实际持有情况对账——睡眠唤醒、屏幕唤醒、快速用户切换后 以及每 15s 检查一次，丢失即重建；apply() 不再「先释放全部再重建」，避免制造断言空窗， 创建失败也会在下次对账时重试（Backlog B5）。
• 屏幕常亮的诊断线索：断言的创建 / 释放 / 丢失重建都会写入诊断日志；「应当常亮却熄屏」时也会记录 当时是否仍持有断言，便于定位是系统锁屏还是断言失效。
• 时间表（跨天）星期判断：22:00–06:00 这类跨午夜窗口的「凌晨段」此前错误地要求当天 在所选星期内，导致「仅周五 22:00–06:00」在周六凌晨不生效；现改为凌晨段按前一天判断。
• 定时器 run loop mode：会话计时（1s）与面板动画时钟（30fps）改用 .common 模式， 避免菜单 / 面板 / 窗口拖拽期间计时暂停。
• 触发规则落盘卡顿：规则持久化改为防抖（约 0.5s 合并多次改动），并在退出时同步刷盘， 避免文本输入 / 步进器高频改动时反复整包编码写盘。
• 对外网络措辞：修正「MAS 版不发起任何网络请求」的不准确表述为「App 自身不上传数据； 内购交易由系统 StoreKit 与 Apple 通信」（privacy / support / user-guide / SECURITY）。

变更

• 场景预设语义：triggerKinds 的 nil（不调整触发器，直接手动会话）与 []（启用触发器并关闭全部规则） 现按定义区分；内置的「演示 / 会议 / 合盖服务器」改为 nil。
• 文档同步：测试数量 210 → 286（README / development / release / plan）； development.md 补充说明 Package.swift 仅编译主程序、不含 Resources 与登录项 helper、产物不可分发。
• 开发内循环：Xcode 15.2 下 swift build -c debug 增量约 2~3 秒；新增 AGENTS.md（模块路由与变更配方） 和 scripts/dev-check.sh（编译 + 本地化，约 3 秒），test.sh 支持 SWIFT_OPT（如 -Onone 快速回归）。
• 会话层拆分（内部重构，行为不变）：SessionController 从 788 行收敛为状态 + 公开 API 的 facade； 合盖/断言时序移到 Services/Session/SessionPowerController，显示策略移到 DisplayPolicy， UserDefaults 移到 SessionPersistence，其余按 Lifecycle / Session / Safety 扩展拆分。286 项单测全绿。
• 测试拆分与过滤：Tests/HeyWakeupTests 按领域拆为 Trigger / Session / Clamshell / Assertion / Store / Mascot / License 七个文件，main.swift 只保留注册表；新增 HEYWAKEUP_TEST_FILTER （支持 suite 名或 test 函数名，list 可列出全部），调试时无需跑全量。
• 触发器拆分（内部重构，行为不变）：TriggerKind 的标题/图标合并为单 switch； 规则评估与阈值采样移到 Services/Triggers/TriggerEvaluator；设置页编辑器/规则操作拆为 TriggersSettingsView+Editors / +Operations。286 项单测全绿。

移除

• 未使用的预留声明：DirectLicenseProvider.Key.licenseKey、SleepAssertionManager.isSystemActive/isDisplayActive。

[1.0.0] - 2026-10-18

首个正式发布版本。菜单栏防休眠工具，支持 macOS 12+，Intel 与 Apple Silicon 通用二进制。

新增

• 三态防休眠
  • 熄屏不睡：IOKit 电源断言，屏幕可熄、系统不睡（零权限）
  • 合盖不睡：免 root 的 IOPMrootDomain 合盖控制（零授权、会话级、退出即失效）
  • 关闭：恢复正常休眠
• 定时会话：15 分 / 30 分 / 1 小时 / 2 小时 / 4 小时 / 无限；屏幕常亮可选叠加
• 触发器自动起停：应用运行、指定进程运行（长任务 / AI Agent）、CPU 高负载、网络活动、 音频播放（读电源断言，不触碰 CoreAudio、不弹麦克风授权）、远程控制、接通电源、使用电池、时间表（支持跨天）； 任一满足即自动开启，全部不满足自动关闭；不打断手动会话
• 场景预设：演示 / 下载 / Agent / 会议 / 音乐模式（合盖听歌不中断）/ 远程模式 / 合盖服务器；支持另存与删除
• 使用统计：本地记录每次会话，展示今日 / 本周保持唤醒时长、按模式分布、自动会话次数；可清除
• 安全护栏
  • 低电量自动停：阈值可调（5%–90%），仅电池供电时触发；低电量期间禁止触发器重开
  • 热保护 + 迟滞闭锁：设备过热（ProcessInfo.thermalState 为 serious/critical）停止并闭锁，降温后恢复
  • 合盖强制熄屏：仅「熄屏不睡」保持屏幕常亮，合盖模式交由系统熄屏，避免包内发热
  • 合盖标志重推：会话期间每 60s 重推，睡眠唤醒 / 电源插拔后立即重推，杜绝静默失效
  • 崩溃恢复与退出复位：异常退出后恢复上次手动模式；正常退出 / 崩溃 / 重启均复位系统默认休眠
• 角色「磨磨」：菜单栏与面板状态提示（打盹 / 拉磨 / 守夜），动效由统一时钟推导
• 体验：全局快捷键 ⌃⌥⌘K、系统通知、开机自启（13+ SMAppService，12 回退 LaunchAgent）、 内置轻量更新检查（可配置 appcast）
• 多语言：简体中文 / 繁体中文 / English，中文原文即 key，语言跟随系统
• 授权与试用：直分发版 7 天全功能试用；MAS 版 StoreKit 2 内购，以 Transaction.currentEntitlements 为准
• 双分发构建：./build.sh（直分发）与 ./build-mas.sh（App Sandbox），差异由编译开关 MAS_BUILD 隔离

说明

• 合盖控制为 Apple 未文档化接口（kPMSetClamshellSleepState = selector 12），需逐 macOS 版本回归验证； 详见 docs/architecture.md 附录 B（V1/V3）。
• 工程：单元测试 210 项全部通过（./test.sh，自建断言运行器，无需 XCTest）； 发布流水线 ./scripts/release.sh（签名 / 公证 / DMG）与 ./scripts/release-mas.sh（MAS 归档）已就绪。