# AI Agent 语音、手机与手表通知安装懒人包

版本：2026-08-31  
适用环境：macOS  
用途：把这份文件交给能操作本地文件与终端的 AI，请它协助设置 AI Agent 的任务完成、待决策与失败通知。

---

## 给用户

1. 把这份文件上传给你信任、而且能操作这台 Mac 的 AI。
2. 告诉它：「请依照文件执行。先检测与规划，得到我同意后再修改。」
3. AI 会先检查你使用的是 Claude Code、Codex 或其他 AI Agent，以及电脑上是否已有通知设置。
4. 遇到 Pushover 密钥、账号登录、系统权限或不确定的现有设置时，应由你本人操作。

这份懒人包不保证每一种 AI Agent 都支持本地事件通知。如果平台没有正式 hook、事件或插件入口，AI 应停下来说明限制，不能自行建立定时轮询或常驻程序代替。

---

## 以下是交给 AI 的工作说明

你正在协助一位不熟悉程序设置的 macOS 用户。你的任务是建立可信任的 AI Agent 进度通知，让用户不用持续盯着屏幕，也能在正确时刻收到：

- 完整任务已完成，而且知道完成了什么。
- AI Agent 需要人批准、选择或补充资料，而且知道需要决定什么。
- 工作确实无法继续时，知道卡在哪里。

通知输出依用户选择，可包含：

- macOS 本地语音。
- Pushover 发送到 iPhone。
- Apple Watch 通过 iPhone 通知镜像显示或振动。

### 最高优先规则

1. 先检测与规划，得到用户明确同意后才修改。
2. 不覆盖或删除现有设置。先读取、说明冲突，再采用最小修改。
3. 不要求用户把 API token、密码或其他机密贴进对话。只建立权限受限的本地模板，停下来让用户本人填入。
4. 遇到登录、MFA、付费、账号授权、系统隐私权限或密钥输入，立即停下来交回用户。
5. 通知 hook 只提醒，不得代替用户批准、拒绝或回答。
6. 每个事件最多通报一次。不得建立会周期重播的 daemon、launchd 工作或自动重试循环。
7. Pushover 固定使用一般优先级 `priority=0`。不得使用会持续重复直到确认的紧急优先级。
8. 测试一律标示 `TEST`，而且一次只开启一个输出端。
9. 若发现通知重复、事件语义不明或无法安全识别完整任务，立即停用通知并停止修改。
10. 不把未验证的手机送达或 Apple Watch 振动宣称为成功；必须由用户亲自确认。

## 第一阶段：只检测，不修改

请完成以下检查，并把结果用一般用户看得懂的方式列出：

1. 确认操作系统是 macOS，以及当前使用的 shell。
2. 检测已安装的 AI Agent 及版本，例如 Claude Code、Codex 或用户指定的平台。不要自行安装新的 AI Agent。
3. 查阅该版本当前的官方文档，确认可用的完成、权限请求、等待输入与失败事件。不要只依赖记忆中的事件名称。
4. 读取现有设置与 hook，但不得显示机密内容。Claude Code 常见位置包括 `~/.claude/settings.json` 与 `~/.claude/hooks/`；Codex 常见位置包括 `~/.codex/config.toml`、`~/.codex/hooks.json` 与 `~/.codex/hooks/`。实际路径以本地与官方文档为准。
5. 检查是否已有语音、Pushover、通知脚本、后台进程或多个 hook 同时处理相同事件。
6. 确认 `/usr/bin/say`、Python 3 与必要的系统命令是否可用。
7. 询问用户需要哪些输出：只有 Mac 语音，或还要 Pushover、iPhone 与 Apple Watch。
8. 说明预计修改的每一个文件、用途、停用方法、测试方式与仍需用户亲自完成的步骤。

完成检测后停下来，等待用户同意计划。未经同意不要进入下一阶段。

## 第二阶段：建立通知架构

得到同意后，依平台能力实现。优先遵守以下架构，而不是照抄固定路径：

```text
AI Agent 的正式事件
├─ 完整任务完成
├─ 需要人决定
└─ 确实无法继续
          │
          ▼
平台事件接头：解析事件、识别来源与工作内容
          │
          ▼
安全核心：内容遮蔽、单次锁、频率熔断、停用开关
          │
          ├─ macOS 语音
          └─ Pushover → iPhone → Apple Watch
```

### 事件语义

- 不得把每一次回复停止、工具步骤结束或阶段性消息直接称为「完整任务完成」。
- Claude Code 若使用 `Stop`，必须加上明确的完整任务标记或其他可靠闸门；没有标记时保持安静。
- Codex 若使用 `agent-turn-complete`，必须确认当前版本能可靠分辨主任务的最终结果与阶段性输出。
- 待决策通知优先使用平台正式的权限请求或等待输入事件，例如当前版本文档中的 `PermissionRequest`；事件名称必须即时查证。
- 如果平台无法可靠区分事件，安全默认是不通知，并向用户说明限制。

### 通知内容

每则通知都应包含来源与安全摘要，例如：

- `Claude 任务已完成：完成网站文章草稿。`
- `Codex 需要你决定：是否允许修改指定配置文件。`
- `Claude 无法继续：缺少用户提供的输入数据。`

摘要必须：

- 优先使用事件中的公开描述。
- 限制长度，建议不超过 120 个字符。
- 遮蔽 API token、密码、Bearer token、完整本地路径、原始终端命令与其他可能的机密。
- 缺少安全描述时，只说明工具类型并请用户回到屏幕查看，不得朗读或推送原始输入。

### 单次与停用设计

- 每次 hook 只启动一个短生命周期进程，完成通知后立即退出。
- 使用原子单次锁，例如 SQLite 唯一主键，或平台适合的一次性任务标记。
- 再加入短时间频率熔断，避免上游事件 ID 改变时产生大量通知。
- 多窗口语音要使用队列或互斥锁，避免声音重叠。
- 建立一个容易理解的启用文件或停用开关。停用时，语音与推送都不得执行。
- 网络失败可以记录在本地，但不得自动重发 Pushover。

### Pushover 与机密

如果用户选择 Pushover：

1. 建立本地凭证模板，例如 `~/.config/ai-agent-notify/pushover.env`。
2. 将目录权限设为 `700`，凭证文件设为 `600`。
3. 停下来，请用户本人填入 `PUSHOVER_TOKEN` 与 `PUSHOVER_USER`。
4. 不读出、不显示、不记录，也不把凭证写进 repository。
5. 固定使用 `priority=0`，不自动重试。

## 第三阶段：逐层测试

按以下顺序测试，每一层通过后才进入下一层：

1. **停用测试**：通知开关关闭时，所有事件都保持安静。
2. **干跑测试**：只写本地测试记录，不播放声音、不调用网络。
3. **单次锁测试**：同一份假事件送入两次，只有第一次被接受。
4. **完成语义测试**：阶段性回复不通知，完整任务才通知一次。
5. **待决策测试**：同一请求只通知一次，内容能说明需要决定什么，而且原 Agent 仍等待用户操作。
6. **Mac 语音测试**：只播放一则标示 `TEST` 的短语音。
7. **Pushover 测试**：经用户同意后，只发送一则一般优先级、标示 `TEST` 的消息。
8. **iPhone 与 Apple Watch 测试**：请用户本人确认通知权限、Watch App 镜像、专注模式、静音及佩戴解锁状态，并回报是否收到与振动。
9. **总开关测试**：再次停用，确认没有后台进程继续播放或发送。

任何一步失败，都先保持后续输出关闭。不要为了通过测试而放宽完成条件、关闭去重或增加重试。

## 完成时的回报格式

完成后，请向用户提供：

1. 已支持的 AI Agent 与事件种类。
2. 修改或新增的文件及用途。
3. 通知的停用方法。
4. 已通过的测试，以及由谁确认。
5. 尚未验证或平台不支持的部分。
6. 日后升级 AI Agent 后，需要重新测试的项目。

只有在完整任务、待决策、单次锁、停用开关与用户选择的输出端都完成相应验证后，才能说设置完成。