# 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 後，需要重新測試的項目。

只有在完整任務、待決策、單次鎖、停用開關與使用者選擇的輸出端都完成相應驗證後，才能說設定完成。