Agent Alerts 設定
設計自動化流程、設定託管 webhook，並將運行時的發送工作交給
$agent-alerts-execution。在設定過程中請勿發送，除非使用者要求進行冒煙測試。
開始使用
請引導使用者前往：
https://www.andreas.ink/agent
依照頁面上的流程，在 iPhone 上與 Agent Alerts 完成連線。該流程會產生一個僅供發送的 token，供運行時使用。請勿要求使用者將該 token 貼到對話中。
設定 Webhook
- 為運行時命名，並在公開設定頁面上完成連線流程。
- 為運行時選擇 token 存放位置：
- 託管運行環境：將單次使用的 token 存放在該運行環境的 secret manager 中，變數名稱設為
AGENTALERTS_AGENT_TOKEN。 - 本機 Mac：在使用者同意的
~/.config/agent-alerts/token.env檔案中，放入只有一行內容AGENTALERTS_AGENT_TOKEN=<token>，並將檔案權限設為0600。
- 託管運行環境：將單次使用的 token 存放在該運行環境的 secret manager 中，變數名稱設為
- 請使用者直接在選定的 secret store 中輸入 token，不要透過 AI 對話進行。切勿要求他們將 token 貼到 agent 對話中。
- 使用內建於
../agent-alerts-execution/scripts/send_webhook.sh的端點。僅在設定頁面提供不同的 HTTPS 端點時，才設定AGENTALERTS_WEBHOOK_URL。 - 只允許對該端點進行 HTTPS 連線。
- 僅授權
send_webhook.sh的完整絕對路徑進行無人值守執行，不可授予廣泛的 shell 存取權限。
切勿將 token 放入提示文字、URL、查詢字串、日誌、原始碼檔案、版本追蹤的設定檔、shell 歷史記錄或命令參數中。
準備並驗證測試
將 ../agent-alerts-execution/assets/compact-webhook-payload.json 複製為一個可寫入的酬載檔案，並替換其中的範例值。請使用穩定且唯一的冪等鍵（idempotency key）來標示事件。
驗證酬載：
../agent-alerts-execution/scripts/send_webhook.sh --check payload.json
驗證酬載、token 來源、權限與端點（不實際發送）：
../agent-alerts-execution/scripts/send_webhook.sh --check-config payload.json
然後發送一次非敏感測試：
../agent-alerts-execution/scripts/send_webhook.sh payload.json
對於無人值守的自動化流程，請使用實際儲存的執行器重複執行 --check-config 與測試發送。兩者都必須在無需使用者確認提示的情況下完成。如果執行器無法執行指定的輔助腳本或無法連線到端點，請回報 AGENTALERTS_SCRIPT_NOT_AUTHORIZED 並停止。
設計警示
定義以下項目：
- 訊號來源、資料來源與觸發條件。
good、warning和critical的對應映射。- 跳過條件、靜音時段與排除規則。
- 穩定的
activity_id或通知識別碼。 - 顯示介面：
live_activity、widget及/或notification。 - 操作按鈕文字與安全的目標 URL 或應用程式 deep link。
- 如果警示會在稍後或重複執行，則需一個可持久化的排程器。
Agent Alerts 負責傳送更新，但不會讓 agent 的工作階段保持存活。若警示在未來或重複執行，必須在目前工作階段關閉後，排程器仍保持註冊狀態，否則視為未完成，並回報 AGENTALERTS_SCHEDULER_NOT_DURABLE。
酬載契約
一般警示請使用簡潔的 webhook 主體：
{
"title": "建置完成",
"summary": "所有測試通過。",
"status": "good",
"activity_id": "build-monitor",
"source_name": "Codex",
"surfaces": ["live_activity", "notification"],
"idempotency_key": "build-monitor-2026-07-29T18-30-00Z"
}
Webhook 需要的標頭：
Authorization: Bearer <AGENTALERTS_AGENT_TOKEN>
Content-Type: application/json
Idempotency-Key: <與 idempotency_key 相同>
輔助腳本會自動加上這些標頭，不會在程序參數中暴露 token。請務必使用此輔助腳本，不要手動重新發送請求。
簡潔模式發送的預設行為是：更新一個名為 webhook 的活動、使用正式環境、並同時啟用 live_activity 和 notification（當這些欄位被省略時）。若自動化流程需要不同的結果，請明確設定這些欄位。
對於小工具、控制中心 widget 狀態、建造佈局或其他進階欄位，請使用 webhook 的完整 snake_case 契約，並附上巢狀的 payload 物件。請勿將完整的 payload 物件與簡潔模式的 title、summary、status、source_name 或 deep_link 欄位混用。
文案與傳送規則
保持可見文案的完整性，並遵守以下字數限制：
| 欄位 | 最大字元數 |
|---|---|
source_name | 14 |
title | 32 |
summary | 96 |
請勿依賴自動截斷或自行加上省略號。
live_activity：更新動態島或鎖定畫面。widget：需要其 widget 識別碼、一個小型非機密的快照，並啟用重新載入功能。notification：需要一個穩定的執行緒識別碼來進行分組。- 控制中心 widget 狀態：在活躍的 warning 或 critical 狀態時應設為 true，在已清除或已解決的狀態時設為 false。
運行時交接
寫下一段精確的運行時指令：
使用 $agent-alerts-execution。首先評估已設定的跳過條件。若需要發送，將準備好的 Agent Alerts JSON 寫入已核准的酬載路徑，然後使用已授權的絕對路徑呼叫 send_webhook.sh 並帶入該檔案。僅從 AGENTALERTS_AGENT_TOKEN 或已核准的 token.env 檔案中讀取 token。回傳傳回的狀態、目標、成功與失敗次數，請勿印出任何機密資訊。
設定只有在以下情況才算完成：實際的執行器能在無需互動的情況下驗證設定並發送，必要時排程器是可持久化的，並且回報的結果不會誇大裝置端顯示的送達狀態。