awoooi/docs/awooop/TELEGRAM-INCIDENT-NOTIFICATION-MODEL.md

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 群組，但必須以摘要卡與固定前綴區分。
6. 主機、容器、runner、Nginx、Wazuh、Kali、CI/CD 這類資安 / 維運告警不得直接外送 ps aux、docker stats、stdout/stderr 或完整路徑；必須先轉成 AI 自動化事件包，再只保留可判讀摘要與 top evidence。

AI 自動化告警事件包

IwoooS / AwoooP 是 AI 自動化產品，Telegram 告警不是終點，而是自動化飛輪的入口。任何可觸發值班判斷的告警，至少要能被轉成 ai_automation_alert_card_v1 等級的事件包。

合格告警的定義不是「有送出訊息」，而是能讓 operator 直接看出 AI 已把訊號送進哪一條自動化 lane、產生哪一個候選、目前被哪一道 Gate 擋住、誰要審、驗證要看哪裡，以及後續如何回寫 Timeline / KM / PlayBook。未做到這件事的訊息只能算 raw observability，不能算 AWOOOI 產品層告警。

事件包必填欄位：

欄位	說明
事件類型	例如 host_resource_pressure、runner_build_resource_pressure、wazuh_intrusion_signal、kali_assessment_signal、nginx_config_drift。
影響判讀	用一到三行說明現在影響的是服務可用性、入侵風險、部署風險、資料完整性或觀測盲點。
視覺化摘要	使用條狀圖、狀態列、矩陣或後續圖卡；不得只丟 raw log。Telegram 純文字階段可用 ■■□□ 類視覺 bar，前端 / 報表可再升級圖卡。
AI lane	指定 AI 後續分流 lane，例如 runner 資源壓力、主機入侵、設定漂移、供應鏈風險。
Gate	明確顯示 candidate_only、approval_required、runtime_write_gate=0 或已取得的授權；不得把告警當成 runtime 寫入批准。
Top evidence	最多保留前三個可判讀證據；只放 PID、CPU、服務類型、告警規則、redacted evidence ref，不放完整主機路徑、secret、個人 namespace 或內部對話內容。
建議下一步	指向 AI 要沉澱的候選、owner 欄位、AwoooP Run / Work Item / IwoooS gate，而不是只叫人看 log。
禁止事項	當下不允許的動作要明確列出，例如不 kill process、不 restart Docker / Gitea、不 reload Nginx、不改 firewall、不觸發 Kali active scan。

事件包必須能接到下列產品閉環：

閉環節點	必須可回讀的狀態
AI lane	security_intrusion_triage、runner_build_resource_pressure、nginx_config_drift、supply_chain_drift 等明確 lane。
Candidate	對應候選動作、owner request、dry-run、Work Item 或 Run；不得只有「請人工判斷」。
Gate	candidate_only、approval_required、runtime_write_gate=0/1、批准者與批准理由。
Verifier	post-check、route smoke、receipt readback、Wazuh / SIEM readback、production health 或 no-write 驗證結果。
Learning	Timeline event、KM / PlayBook writeback、trust score / rule learning 或報表沉澱狀態。

不合格告警範例：

• 只貼 CPU、ps aux、docker stats、stdout/stderr、完整路徑或完整 log。
• 只說「AI 選擇不執行」但沒有候選、Gate、owner、verifier 或 learning。
• 把工作視窗、內部對話、個人 namespace、內網位址、secret 片段或未脫敏 raw payload 放進 Telegram 或前端。
• 把 Telegram 送達、UI 可見、CD success 或 smoke success 誤當成 runtime 寫入批准。

Host / runner 資源告警的第一版落地：

• TelegramGateway.send_alert_notification() 會在 HTML 告警出口自動套用 host resource formatter。
• CPU 警告、容器內 root Node.js 進程、含 ps aux 且指向 build 程序的文字，會被轉成 ai_automation_alert_card_v1。
• raw process dump 會被壓成 PID + CPU + 精簡命令，不保留 /workspace/...、完整 node module 路徑或整段 ps aux。
• build 壓力會分流到 runner_build_resource_pressure，預設 candidate_only / runtime_write_gate=0。
• 這只建立 AI 候選與判讀入口，不代表允許 kill process、restart 服務、改 Nginx、改 firewall 或執行 Kali active scan。

與 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 在窗口內只更新卡片，不新增卡片。