docs: add plugin-oriented reusable design / 文件補上插件化與多 agent 重用設計

README.md

@@ -28,6 +28,8 @@
 - 將使用者選擇映射到對話狀態
 - 保留使用者直接打字而不按按鈕的能力
 
+此外，這個專案從一開始就要考慮**插件化**，讓未來不只一個 assistant 可以使用，而是多個 agent / bot / assistant runtime 都可以共用同一套 reply-end-controls 能力。
+
 ### 專案目標平台
 
 這個專案目前 **固定只做 Telegram**。
@@ -160,6 +162,8 @@ This repository is only for the reply-end control feature, including:
 - mapping user choice into conversation state
 - preserving the ability to type freely instead of pressing a button
 
+From the beginning, this project should also be designed as a **reusable plugin-style component** so multiple agents or assistant runtimes can adopt the same reply-end control behavior instead of implementing it independently.
+
 ### Target platform
 
 This project is **Telegram-only** for now.

telegram-v1-design.md

@@ -6,6 +6,8 @@ This project is Telegram-only.
 
 No Discord, Slack, or cross-channel abstraction is part of V1.
 
+However, the internal architecture should still be **plugin-oriented and reusable** so that multiple agents can adopt the same reply-end-controls behavior later without rewriting the logic.
+
 ## Product behavior
 
 At the end of every assistant reply sent to Telegram, attach two inline buttons:
@@ -125,6 +127,75 @@ Responsibility:
 - inspect `lastChoice`
 - suppress proactive continuation when `stop` is active
 
+## Plugin-oriented design goal
+
+Even though V1 is Telegram-only, implementation should be split so the feature can be reused by other agents.
+
+### Required separation
+
+#### A. Channel-specific layer
+
+Telegram-only code:
+
+- inline keyboard rendering
+- callback query parsing
+- Telegram message edit/update behavior
+
+#### B. Agent-neutral control core
+
+Reusable logic:
+
+- reply-end choice state model
+- state persistence rules
+- Continue/Stop behavior policy
+- helpers for reading and updating `lastChoice`
+
+#### C. Agent integration adapter
+
+Per-agent integration points:
+
+- how a given agent/runtime appends controls to replies
+- how a given agent/runtime consults the stored choice before later turns
+
+This means V1 should not hard-code every behavior directly into Telegram handlers. Telegram should be the transport/integration layer, while the choice model and policy logic should stay reusable.
+
+## Multi-agent reuse target
+
+The design should make it possible for future agents to reuse the same core with minimal custom work:
+
+- Agent A: Telegram assistant using OpenClaw
+- Agent B: another Telegram bot runtime
+- Agent C: future Slack/Discord version, if ever needed later
+
+The shared core should answer:
+
+- what choice was made?
+- when was it made?
+- is the conversation currently in `continue` or `stop` mode?
+- should the next assistant turn suppress proactive continuation?
+
+## Recommended code layout
+
+Suggested V1 layout:
+
+```text
+reply-end-controls/
+├── README.md
+├── telegram-v1-design.md
+├── core/
+│   ├── state-model.md
+│   ├── policy.md
+│   └── callback-contract.md
+├── telegram/
+│   ├── reply-decorator.md
+│   ├── callback-handler.md
+│   └── message-update.md
+└── adapters/
+    └── openclaw.md
+```
+
+V1 does not need all of these files implemented yet, but the structure should guide the implementation so transport-specific code does not swallow the reusable core.
+
 ## Acceptance criteria for V1
 
 V1 is complete when all of the following are true: