diff --git a/docs/adr/ADR-091-telegram-subsystem-round3.md b/docs/adr/ADR-091-telegram-subsystem-round3.md new file mode 100644 index 00000000..1ae67985 --- /dev/null +++ b/docs/adr/ADR-091-telegram-subsystem-round3.md @@ -0,0 +1,111 @@ +# ADR-091: Telegram 子系統全景審計與 UX 黑洞修復(Phase 7 Round 3) + +**日期**: 2026-04-19 +**狀態**: ✅ 已實施(commits `877c847` → `4b8be32`,git tag `v7.3.0`) +**上游**: [ADR-090 監控盲區治理](./ADR-090-monitoring-blindspot-governance.md)、[MASTER Blueprint §7.1](../superpowers/specs/2026-04-15-MASTER-ai-autonomous-flywheel-v2.md) +**Memory**: `project_phase7_round3_telegram_subsystem.md` + +## Context(背景) + +2026-04-18 深夜統帥連續截圖 Telegram 卡片異常:按鈕按了無反應、卡片永遠顯示「執行中」、responsibility 欄位顯示「未知」、drift 卡片內文與 description 互相矛盾。統帥原話:「**根本他媽的沒有盤查過所有的 Telegram 的按鈕!你就是做爽的而已!**」 + +過往每遇 Telegram bug 都是點對點補丁,從未做過**全景 × 全按鈕型別 × handler 覆蓋矩陣**的完整盤查。本 Round 強制要求:先做全景矩陣,再批次修。 + +## Decision(決策) + +### 1. 建立 Telegram callback 按鈕 × Handler 覆蓋矩陣 + +11 個按鈕型別 vs handler 覆蓋現況: + +| 按鈕型別 | Callback 格式 | Handler 狀態(修前) | 修後 | +|---------|--------------|--------------------|------| +| approve / reject / tune / silence | 4-part nonce | ✅ 原有 | ✅ | +| view | 2-part INFO | 🔴 未在 INFO_ACTIONS 白名單 | ✅ 加入(TG-1) | +| drift_view | 4-part nonce | 🔴 無 handler(UX 黑洞) | ✅ 專屬分派(TG-2) | +| drift_adopt | 4-part nonce | 🔴 無 handler | ✅ 呼叫 `drift_adopt_service` | +| drift_revert | 4-part nonce | 🔴 無 handler | ✅ 呼叫 `drift_remediator.revert` | +| scale / secops_authorize / secops_isolate | 4-part nonce | 🔴 定義但無 handler | ⏸ 下輪補 spec 或移除 | + +### 2. 鐵律:新增按鈕前必通過三缺一檢查 + +由 `feedback_no_ghost_buttons.md` 升級為 ADR 層級規範: + +> **發送任何 Telegram callback 按鈕前,必須通過:** +> 1. callback_data 格式在 `parse_callback_data` 支援(nonce or INFO) +> 2. 有對應 handler 分支 +> 3. handler 所需能力(MCP / service)真實存在 +> +> **三缺一,絕不發送**。沒有 handler 的按鈕 = UX 黑洞 = 用戶認為系統當機。 + +### 3. callback_data 雙格式正式認定 + +| 語義 | 格式 | 範例 | 適用 | +|------|------|------|------| +| 寫操作 | `{action}:{approval_id}:{timestamp}:{random}` | `approve:abc:1234:xyz` | 防重放(nonce) | +| 讀操作 | `{action}:{incident_id}` | `view:inc_123` | INFO_ACTIONS 白名單 | +| **特例:drift** | 走 nonce 格式,語義讀/寫混合 | `drift_view:abc:1234:xyz` | handle_callback Step 1.85 專屬分派 | + +INFO_ACTIONS 白名單位於 [`security_interceptor.py`](../../apps/api/src/services/security_interceptor.py) line 438。新增讀操作按鈕必須加入此集合。 + +### 4. Long Polling 正式採用(非 Webhook) + +- `getWebhookInfo` 回 URL=空是 **by design** +- 單 Pod Leader Election(Redis lock)避免多 Pod 搶 getUpdates 409 +- `/api/v1/telegram/webhook` endpoint 已標註 `[已棄用]`,保留作退路 + +### 5. Approval 執行完成三戳鐵律 + +approval 執行完後必須同時完成三件事,否則卡片永遠「執行中」: + +1. `editMessageReplyMarkup` 移除按鈕 +2. `editMessageText` 加上 ✅/❌ 結果 + KM/Playbook 增量戳 +3. `approval_records.telegram_message_id` 寫入 DB(不只 Redis) + +### 6. NO_ACTION 不是 FAILED + +OpenClaw 決策為 `NO_ACTION`(調查用)時走 noop 分支標 `SUCCESS`,不進 verifier FAILED path,救 MASTER §7.1 #11 auto_execute 成功率。 + +### 7. Responsibility 正規化 + +primary_responsibility 欄位不可留空/None/invalid;空值一律 fallback `INFRA` 或 `BE`。 + +## Consequences(後果) + +### 正面 + +- **9 bugs 中 7 修**(TG-1/2/4 + AP-1/2/3 + Extra NO_ACTION),2 延後(TG-3 refactor、TG-5 by-design) +- **全景盤點成為標準工作流**:未來新增按鈕/handler 必先畫矩陣 +- **UX 黑洞鐵律上 ADR**:三缺一絕不發送,防止下次再出現無 handler 按鈕 +- **NO_ACTION 真實率可測**:MASTER §7.1 #11 不再被誤標污染 + +### 負面 / 未完 + +- `scale / secops_authorize / secops_isolate` 按鈕仍在定義但無 handler,下輪補 action spec 或移除 +- TG-3 handler 重複分派(approve 邏輯散落 4 處)為純 refactor,本輪跳過 +- Webhook endpoint 標註棄用但未刪除(保留退路) + +### 需觀察(24h 真實 traffic) + +```sql +-- 三條閉環驗證 +SELECT COUNT(*) FROM notification_outcomes; +SELECT COUNT(*) FROM approval_records WHERE telegram_message_id IS NOT NULL; +SELECT COUNT(*) FROM automation_operation_log WHERE operation_type='notification_formatted'; +``` + +## 5 Commits 時序 + +1. [`877c847`](https://gitea.wooo.work/owen/awoooi/commit/877c847) feat(telegram): drift 按鈕 3 handler + drift card message_id Redis 存(TG-2 + TG-4) +2. [`2e988bd`](https://gitea.wooo.work/owen/awoooi/commit/2e988bd) fix: drift 執行結果 reply_to 原卡片 + audit log +3. [`fdce0a3`](https://gitea.wooo.work/owen/awoooi/commit/fdce0a3) fix(approval): NO_ACTION 走 noop 分支標 SUCCESS +4. [`68a42a3`](https://gitea.wooo.work/owen/awoooi/commit/68a42a3) refactor(openclaw): 幻覺驗證抽成 helper,sweeper + webhook 雙路徑呼叫 +5. [`4b8be32`](https://gitea.wooo.work/owen/awoooi/commit/4b8be32) fix: TG-1 INFO_ACTIONS view + AP-1/2/3 approval 三修 + +**Git tag**: `v7.3.0` at `4b8be32` + +## 相關文件 + +- MASTER §8 Changelog 2026-04-19 條目:`docs/superpowers/specs/2026-04-15-MASTER-ai-autonomous-flywheel-v2.md` +- Memory 全彙總:`~/.claude/projects/-Users-ogt-awoooi/memory/project_phase7_round3_telegram_subsystem.md` +- 鬼魂按鈕鐵律(feedback):`feedback_no_ghost_buttons.md` +- 上一輪修復:`project_phase7_round2_flywheel_fixes.md`(ADR-090 實施 Round 2)