docs: add Telegram/OpenClaw PoC implementation plan / 新增 Telegram/OpenClaw PoC 實作計畫

2026-05-12 23:41:06 +08:00
parent 588c3a446d
commit bdf24a03ae
1 changed files with 158 additions and 0 deletions
--- a/telegram-openclaw-poc-plan.md
+++ b/telegram-openclaw-poc-plan.md
@@ -0,0 +1,158 @@
+# Telegram + OpenClaw PoC Implementation Plan
+
+## Goal
+
+Build the first working proof of concept for `reply-end-controls` on the real OpenClaw Telegram path.
+
+The PoC only needs to prove three things:
+
+1. every assistant reply can include the two reply-end buttons
+2. Telegram button clicks can be received as callback queries
+3. the selected choice can be written into state and later read back
+
+## Buttons
+
+Required V1 buttons:
+
+- `A. 繼續`
+- `B. 就這樣吧，不需要額外處理`
+
+Suggested callback payloads:
+
+- `rec:continue`
+- `rec:stop`
+
+## Target OpenClaw integration points
+
+### Outbound injection layer
+
+Primary target area:
+
+- Telegram outbound payload construction
+
+Relevant runtime files already identified:
+
+- `channel-C2-7V9Dv.js`
+- `send-sxDwUGaO.js`
+- `delivery-CZV2kWBm.js`
+
+PoC intention:
+
+- locate the point where normal text replies become Telegram send payloads
+- append `reply_markup.inline_keyboard`
+- do not redesign all message types in V1
+
+### Callback receive layer
+
+Primary target area:
+
+- Telegram callback query handler
+
+Relevant runtime file already identified:
+
+- `bot-Ce301bOE.js`
+
+PoC intention:
+
+- intercept callback query data matching `rec:*`
+- normalize into internal state event
+- store the result
+
+## State write strategy
+
+V1 should keep this simple.
+
+Write state into a dedicated conversation/session structure rather than trying to redesign all runtime state.
+
+Minimum stored fields:
+
+```json
+{
+  "replyEndControls": {
+    "lastChoice": "continue | stop",
+    "lastChoiceAt": "ISO timestamp",
+    "sourceMessageId": "string",
+    "sourceCallbackId": "string",
+    "active": true
+  }
+}
+```
+
+## PoC phases
+
+### Phase 1 - visual proof
+
+Goal:
+
+- every assistant Telegram reply includes the two buttons
+
+Done when:
+
+- a real Telegram assistant reply visibly shows both buttons
+
+### Phase 2 - callback proof
+
+Goal:
+
+- clicking either button is received by OpenClaw
+
+Done when:
+
+- callback query with `rec:continue` or `rec:stop` is logged or persisted
+
+### Phase 3 - state proof
+
+Goal:
+
+- the click updates stored reply-end state
+
+Done when:
+
+- state can be read back and shows the latest user choice
+
+### Phase 4 - behavior proof
+
+Goal:
+
+- later assistant behavior changes based on that state
+
+Done when:
+
+- `stop` suppresses proactive continuation
+- `continue` allows normal continuation
+
+## First implementation cut
+
+The very first code change should target only:
+
+- standard Telegram assistant text replies
+
+It does not need to cover:
+
+- media replies
+- polls
+- approval flows
+- system notices
+- every Telegram edge case
+
+## Safety rule
+
+Do not mix this with governance logic.
+
+The reply-end-controls PoC should be kept separate from the governance interceptor project and should not reuse its semantics.
+
+## Recommended implementation order
+
+1. Add inline keyboard to normal Telegram assistant replies
+2. Receive callback queries for `rec:continue` / `rec:stop`
+3. Persist state
+4. Edit message buttons to resolved state
+5. Read the state from a later turn
+
+## Immediate next task
+
+Implement the smallest visible PoC:
+
+- inject the two buttons into standard Telegram assistant replies
+
+That is the fastest path to proving the project is attached to the real Telegram reply chain.