# Telegram 事故通知模型

> 目的：讓 SRE 戰情室一眼分辨「AI 已修復」、「AI 可建議但需批准」、「AI 無法安全修復需人工」與「僅通知」，避免告警、執行 log、Code Review、Drift 與審批結果互相洗版。

## 核心判斷

Telegram 不應是完整執行日誌，也不應承載所有 AI 推理細節。Telegram 的職責是把需要人類注意力的決策摘要送到 SRE 戰情室；完整時間線、工具輸出、重試原因、provider fallback 與 audit 交給 AwoooP Run Monitor / Incident Timeline。

## 四種通知狀態

| 狀態 | 意義 | Telegram 行為 | 操作者動作 |
| --- | --- | --- | --- |
| AI 已自動修復 | 自動化已完成且驗證通過 | 更新原 incident 卡或回覆一次結果 | 檢查即可，不需批准 |
| AI 建議待審批 | AI / 規則已提出可執行建議，但被 Trust / Risk gate 擋下 | 發一張 ACTION REQUIRED 主卡 | 批准、拒絕、靜默或看詳情 |
| AI 無法安全修復 | NO_ACTION、INVALID_TARGET、LLM timeout、MCP 失敗或缺少安全動作 | 發人工接手摘要，不重複刷同一狀態 | 人工排查，或要求重診 |
| 僅通知 | 心跳、報表、Code Review 完成、低風險治理資訊 | 彙總卡或摘要頻道 | 通常不需即時動作 |

## 專業化訊息規則

1. 同一個 `incident_id` 只應有一張主卡。後續狀態使用原卡回覆、編輯按鈕或 AwoooP timeline，不再每一步都新發卡。
2. 主卡第一屏必須顯示「處置狀態」，先回答：AI 是否能修、是否已修、是否需要人工。
3. 同一個 `incident_id` 的相同狀態更新，短時間內要去重。詳細重試與錯誤放到 timeline，不洗 Telegram。
4. P0 / P1 escalation 可以另發升級卡，但內容必須是「目前影響、已嘗試、卡住原因、需要誰做什麼」，不可重貼所有底層 log。
5. Code Review、Config Drift、報表、心跳不應和 incident 執行回覆混在同一種語義；它們可以在同一 SRE 群組，但必須以摘要卡與固定前綴區分。

## 與 AwoooP 的分工

| 介面 | 承載內容 |
| --- | --- |
| Telegram | 決策摘要、升級、人工批准入口 |
| AwoooP Run Monitor | 非同步 Run、provider fallback、tool call、retry、latency |
| Approval Queue | 所有等待批准的高風險動作 |
| Incident Timeline | 事件完整歷程、AI 嘗試、失敗原因、KM / Playbook 回寫 |
| MCP Audit | 工具執行、redaction、permission gate、credential 注入 |

## 2026-05-12 live gate

> Canonical diagnosis and repair waves live in `docs/superpowers/specs/2026-04-15-MASTER-ai-autonomous-flywheel-v2.md` §2.5. This section is only the Telegram-facing contract.

Telegram 卡片目前不能再只顯示「AI 研判 / 建議動作」。每張卡都必須能回查到一筆 truth-chain 狀態，最少包含：

- `source_event_id` / `fingerprint` / `repeat_count` / `first_seen` / `last_seen`
- current stage：received、deduped、evidence、MCP、decision、approval、execution、verification、learning、resolved / manual_required
- evidence quality：sensors attempted / succeeded、failed sensors、Sentry / SignOz / Prometheus refs
- MCP usage：AwoooP Gateway audit、legacy direct MCP、not-used reason
- executor choice：Ansible / MCP / K8s / SSH / no_action，以及 dry-run / diff / rollback evidence
- approval / execution / verification：approval_id、operation op_id、verification_result、KM / Playbook writeback

Live 2026-05-12 evidence shows this gate is not yet green:

- AwoooP Run State 24h is still `legacy_outbound` shadow with `step_total=0`.
- `awooop_mcp_gateway_audit` has 0 rows; legacy `mcp_audit_log` has activity but is not the AwoooP choke point.
- `INC-20260512-B6C589` has incident / approval status mismatch and `8/8` failed SSH sensors.
- Config Drift repeats hourly with the same counts and pending status, but Telegram does not show repeat/update state.
- Outbound mirror visibility must be revalidated after RLS; the app role currently cannot rely on it as a complete truth source.

## 本輪落地

- `TelegramMessage` 主卡新增「處置狀態」。
- `append_incident_update()` 對同一 incident 的相同狀態做 5 分鐘 Redis 去重。
- `append_incident_update()` 對相同的「AI 自動修復失敗 / AI 診斷工具失敗」摘要增加 10 分鐘跨 incident 去重；每個 incident 仍會移除原卡危險按鈕，但 Telegram 不再重複 reply 同一個失敗摘要。
- `TelegramGateway._send_request()` 對成功送出的 legacy `sendMessage` 增加 AwoooP `awooop_outbound_message` 鏡像。鏡像失敗只記錄 `telegram_outbound_mirror_failed`，不能影響 Telegram 正常送達。
- 成本告警、審批執行結果、自愈 rollback 提案已由 direct Bot API 改走 `TelegramGateway._send_request()`，避免繞過 outbound mirror。
- `telegram_gateway.py` 內部歷史直打 `sendMessage` 路徑已收斂；多 Bot `_send_as_bot()` 因需指定 token 保留 direct HTTP，但成功後同樣鏡像到 `awooop_outbound_message`。
- 既有 `詳情 / 重診 / 歷史` 按鈕保留，讓 Telegram 保持輕量，細節回到控制台。

## 後續建議

1. 將 Telegram 群組升級為 Forum topics 或固定 topic lane：`P0/P1 事故`、`人工審批`、`治理/報表`、`CI/Code Review`。
2. AwoooP Approval Queue 顯示與 Telegram 相同的「處置狀態」欄位，避免前後端語義分裂。
3. 將 auto-repair failure 的完整 stdout/stderr 改寫入 Run Timeline，只在 Telegram 顯示最短摘要與詳情連結。
4. 對 firing 告警做 fingerprint 聚合：同一 alertname + target + namespace 在窗口內只更新卡片，不新增卡片。