yaoyao/docs/macos-app.md

macOS App 与本地服务

App、Web 服务、Vue 界面和 Runner 同仓维护。打开 App 会先核对数据目录及已有监听服务；有可信的已有服务则连接，没有则启动包内服务。默认数据目录为 ~/.hermes-yaoyao，默认 Web 端口为 15300。Hermes 是独立基础运行时，由本地服务检测并按既有托管逻辑启动；隔离电脑另需本机 Docker 或 Podman。

生命周期与权限

• App 单实例；服务和 Runner 各自对实际数据目录持有 SQLite 独占锁。
• 使用私有随机凭据核对服务实例、PID、数据目录、协议及版本。App 自己启动的服务必须匹配内置版本。连接旧版本外部服务时使用其界面和能力声明。
• 老 CLI 服务没有描述文件时，只有确认它同时持有目标 SQLite 文件和监听端口才连接。
• 关闭窗口保留任务；菜单栏和 Dock 可恢复。明确退出等待自己托管的 Runner 和服务结束，不停止外部服务。停止无法确认时显示实际清理错误。
• 服务崩溃有界重启，睡眠恢复后重新核对连接；错误页面提供重试和日志。
• Runner 配置由原生文件选择器导入，通过系统加密存储及私有进程消息传递。Web 页面没有配置解密或桌面启动权限，外部页面不能调用原生桥。

登录启动

“夭夭 → 登录 macOS 时启动”使用系统登录项，默认不开启。用户可另选“登录启动时仅驻留菜单栏”；这个偏好只影响登录启动，手动打开 App 仍显示窗口。正常安装不会改写系统登录项。

源码开发 App 不提供登录项开关；安装包中的开关由系统管理。实际开机/重新登录验收尚未执行，当前验证的是偏好持久化和手动重新打开行为。

更新与回退

App 内置服务随整个 App 更新，不使用源码部署的 LaunchAgent 更新器。菜单“App 更新与回退”显示当前 App/服务版本、托管归属和数据目录。当前采用手动替换 App 的流程，没有启用自动下载安装：

1. 停止任务并退出 App。若连接已有外部服务，单独按它的原有方式停止，确认没有进程写入数据目录。
2. 私有备份整个数据目录和正在使用的 App。电脑工作区可使用 docs/computer-maintenance.md 中的校验备份。
3. 核对新包架构、签名和校验值，再替换 App；启动后核对服务实际版本、健康状态、会话和任务。
4. 出现问题时退出新 App，恢复原 App；包含数据迁移的升级须同时恢复升级前的数据。App 不主动删除原镜像和工作区备份。

此流程保护签名后的 App 资源不被 Web 更新器改写。正式数据升级/回退必须在停止写入的条件下操作，不能拿运行中数据库的普通文件复制充当一致备份。

构建与验收

npm run desktop:build
npm run desktop:test
npm run desktop:pack
codesign --verify --deep --strict desktop-release/mac-arm64/夭夭.app
hdiutil verify desktop-release/Yaoyao-0.3.32-arm64.dmg

开发 App 的 6 项测试通过：真实内置服务启动、账号与 Runner 连接、关闭窗口保持运行、服务崩溃恢复、外部客户端不误停服务、退出清理、加密配置再次启动、偏好保存及手动重新打开、版本不符拒绝、钥匙串失败保护。另有更新器 14 项定向测试通过，包含 App 禁用源码更新及回退。

desktop-release 中现有旧包仍是此前阶段快照。最终完整平台尚需重新打包、严格签名验证并对实际 App 重跑生命周期测试；开发签名、公证、安装、发布分别记录，不混为已交付。