From 10fa17efc6cccc7a9c4bad6ac9a933cdcd3de1cb Mon Sep 17 00:00:00 2001
From: "Alice (OpenClaw)" <alice@cowbay.org>
Date: Tue, 12 May 2026 22:00:13 +0800
Subject: [PATCH] =?UTF-8?q?docs:=20add=20plugin-oriented=20reusable=20desi?=
 =?UTF-8?q?gn=20/=20=E6=96=87=E4=BB=B6=E8=A3=9C=E4=B8=8A=E6=8F=92=E4=BB=B6?=
 =?UTF-8?q?=E5=8C=96=E8=88=87=E5=A4=9A=20agent=20=E9=87=8D=E7=94=A8?=
 =?UTF-8?q?=E8=A8=AD=E8=A8=88?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 README.md             |  4 +++
 telegram-v1-design.md | 71 +++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 75 insertions(+)

diff --git a/README.md b/README.md
index c9868e1..6c86609 100644
--- a/README.md
+++ b/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.
diff --git a/telegram-v1-design.md b/telegram-v1-design.md
index 819f878..2d6ff75 100644
--- a/telegram-v1-design.md
+++ b/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: