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() 與 send_text() 會在最後出口自動套用 host resource formatter；即使呼叫端傳入 Markdown，也必須強制改成脫敏 HTML 卡片。
• TelegramGateway._send_request("sendMessage", ...) 也必須套用同一個 formatter，避免 approval execution、legacy helper 或未來 direct gateway 呼叫繞過 send_alert_notification() / send_text()。
• CPU 警告、容器內 root Node.js 進程、含 ps aux 且指向 build / package install / Prisma generate 程序的文字，會被轉成 ai_automation_alert_card_v1。
• raw process dump 會被壓成 PID + CPU + 精簡命令，不保留 /workspace/...、/opt/hostedtoolcache/...、完整 node_modules 路徑、外部檢查 URL、JSON payload 或整段 ps aux。
• build 壓力會分流到 runner_build_resource_pressure；Prisma / package install 壓力會分流到 runner_prisma_generate_resource_pressure；預設都是 candidate_only / runtime_write_gate=0。
• 這只建立 AI 候選與判讀入口，不代表允許 kill process、restart 服務、改 Nginx、改 firewall 或執行 Kali active scan。

非 host 維運 / 資安訊號的第一版落地：

• TelegramGateway.send_alert_notification() 與 send_text() 現在也會把 Wazuh、Kali、Nginx drift、Backup / Restore / Escrow、Provider freshness、Supply-chain drift 類訊號轉成同一版 ai_automation_alert_card_v1。
• 事件類型固定映射：
  • wazuh_dashboard_api_readback_degraded → siem_observability_readback_degraded
  • wazuh_intrusion_signal → security_intrusion_triage
  • kali_assessment_signal → security_assessment_review
  • nginx_config_drift → public_gateway_config_drift
  • backup_restore_escrow_signal → backup_restore_escrow_triage
  • provider_freshness_signal → source_provider_freshness_triage
  • supply_chain_drift → supply_chain_drift_review
• 所有上述卡片都必須顯示 candidate_only / runtime_write_gate=0，並把下一步導向 owner evidence、reviewer acceptance、rendered diff / freshness / restore / SIEM readback、KM / PlayBook / Verifier 沉澱。
• Wazuh Dashboard 顯示 agent 消失但 agent transport 或 manager service 仍有只讀證據時，必須優先分類為 wazuh_dashboard_api_readback_degraded；在 manager registry counts 未驗收前，不得把它寫成「所有 agent 已消失」或「agent 已恢復」。
• formatter 會在 Telegram 最後出口脫敏 URL、內網 IP、絕對路徑、Bearer token、token / password / secret / api key 類 assignment；Top evidence 最多保留三行摘要。
• 這只把 raw signal 變成 AI 自動化候選，不代表允許 Wazuh 封鎖、Kali active scan、nginx -t / reload、backup / restore / remote delete、provider switch、package upgrade、workflow dispatch 或 production write。

通知出口旁路清冊：

• docs/security/telegram-notification-egress-inventory.snapshot.json 目前固定 repo 內 0 個 direct Bot API sendMessage，分布為 Gitea workflow 0、ops script 0、API direct path 0。
• apps/api/src/services/channel_hub.py 的 interim feedback sender 已改走 TelegramGateway.send_text()，讓 non-shadow interim 訊息進入既有 final-exit formatter、thread reply、錯誤 sanitizer 與 AwoooP outbound mirror path；不再直接讀 TELEGRAM_BOT_TOKEN 或拼 Bot API URL。
• scripts/ops/backup-from-110.sh、scripts/ops/docker-health-monitor.sh、scripts/ops/dr-drill.sh、scripts/ops/pg-backup.sh 的 legacy direct Bot API fallback 已移除；API 不可達時只留下本地 log，不再繞過 DB/log receipt 與 AI automation。
• docs/security/telegram-notification-egress-owner-request-draft.snapshot.json 已讀回 0 份 metadata-only candidate；owner response 欄位只能作為 evidence，不得阻擋低爆炸半徑 controlled apply。
• docs/security/telegram-notification-egress-migration-plan-draft.snapshot.json 已讀回 0 份 migration candidate；migration runtime send / Bot API call / secret read 仍維持 0。
• GET /api/v1/agents/telegram-alert-ai-automation-matrix 會把上述清冊與 readability guard、AI digest policy、AwoooP outbound mirror source contract 合併，讀回 DB/log receipt、AI route、controlled queue、work item、post verifier、learning writeback、manual/default gap 與 direct send gap。
• direct egress 已不再是目前 repo 內已知缺口；後續若新增 direct Bot API 會被 no-new-bypass guard 阻擋，並必須先回到 TelegramGateway / AwoooP receipt path。
• 清冊階段只允許保存 path、line、redacted excerpt、owner 欄位與 reviewer gate；不送 Telegram、不讀 Bot token、不保存 chat secret、不改 workflow / script、不開 runtime gate。
• 後續每個 direct egress 要收斂前，都必須補 owner route、message shape、redaction contract、formatter convergence plan、delivery receipt、fallback mode、rollback owner 與 post-check evidence。

Host / runner 告警卡片必須採用下列第一屏版型：

P1 主機資源壓力｜h110-gitea
ai_automation_alert_card_v1

一眼摘要
├ CPU 使用率：29.8%
├ Load：8.62 ■■■■■■■■
├ 容器 root 進程：3
└ 影響：Prisma generate / package build 程序正在吃 CPU；先確認 CI/CD、runner job 與供應鏈來源，不可直接 kill

AI 自動化判讀
├ Lane：runner_prisma_generate_resource_pressure
├ Gate：candidate_only / runtime_write_gate=0
└ 下一步：建立 Prisma / package install 資源壓力候選，交由 AI 彙整 CI/CD run、套件來源、runner queue 與供應鏈 evidence

Top evidence
├ PID 365 CPU 27.5%：Prisma generate root
├ PID 376 CPU 15.5%：Prisma generate root
└ PID 392 CPU 0%：Prisma generate root

建議下一步
├ 確認是否為 CI/CD / Actions / runner 正常建置或 package install 窗口
├ 若持續超過門檻，先查 runner queue、build job、套件來源、容器資源限制與服務 SLO
└ 同一 host/service 5 分鐘聚合一次，避免洗版

禁止事項
└ 不 kill process、不 restart Docker / Gitea、不 reload Nginx、不改 firewall；除非已有維護窗口與 owner 批准。

與 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 正常送達。
• ai_automation_alert_card_v1 送出後，AwoooP mirror envelope 需帶 ai_automation_alert_card_mirror_v1 metadata，至少包含 event_type、lane、target、gates、runtime_write_gate_count=0 與 delivery_receipt_readback_required=true；不得把 raw alert、完整 Telegram text、token、內網 URL、主機路徑或 raw Wazuh payload 放進 envelope。
• GET /api/v1/platform/runs/ai-alert-cards 只讀查詢 ai_automation_alert_card_v1 delivery readback，可用 project_id、event_type、lane 篩選；此路徑只回 metadata、source refs 與 send status，不回完整 Telegram text，也不代表 Telegram 已實發或 Wazuh registry 已驗收。
• 成本告警、審批執行結果、自愈 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 在窗口內只更新卡片，不新增卡片。