Files

OG T 2524aa983a docs(adr): ADR-091 Telegram 子系統 Round 3 全景審計正式文件

- 11 按鈕 × handler 覆蓋矩陣定版
- 三缺一鐵律（callback格式+handler+能力）升級 ADR 層級
- callback_data 雙格式（nonce vs INFO）正式認定
- Long Polling by design 確認
- approval 三戳鐵律（editMarkup + editText + DB message_id）
- NO_ACTION 不誤標 FAILED 救 MASTER §7.1 #11

對應 commits 877c847 → 4b8be32，git tag v7.3.0
Memory: project_phase7_round3_telegram_subsystem.md

2026-04-19 01:32:52 +08:00

5.7 KiB

Raw Blame History

ADR-091: Telegram 子系統全景審計與 UX 黑洞修復（Phase 7 Round 3）

日期: 2026-04-19 狀態: ✅ 已實施（commits 877c847 → 4b8be32，git tag v7.3.0）上游: ADR-090 監控盲區治理、MASTER Blueprint §7.1 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 按鈕前，必須通過：

callback_data 格式在 parse_callback_data 支援（nonce or INFO）

有對應 handler 分支

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 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 執行完後必須同時完成三件事，否則卡片永遠「執行中」：

editMessageReplyMarkup 移除按鈕
editMessageText 加上 ✅/❌ 結果 + KM/Playbook 增量戳
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）

-- 三條閉環驗證
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 時序

877c847 feat(telegram): drift 按鈕 3 handler + drift card message_id Redis 存（TG-2 + TG-4）
2e988bd fix: drift 執行結果 reply_to 原卡片 + audit log
fdce0a3 fix(approval): NO_ACTION 走 noop 分支標 SUCCESS
68a42a3 refactor(openclaw): 幻覺驗證抽成 helper，sweeper + webhook 雙路徑呼叫
4b8be32 fix: TG-1 INFO_ACTIONS view + AP-1/2/3 approval 三修

Git tag: v7.3.0 at 4b8be32

5.7 KiB Raw Blame History Unescape Escape