From 4c5f4cc369415979a287d2ff038b562f1fb1a599 Mon Sep 17 00:00:00 2001 From: "Alice (OpenClaw)" Date: Tue, 12 May 2026 16:53:20 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20bilingual=20README=20/=20=E6=96=87?= =?UTF-8?q?=E4=BB=B6=E6=94=B9=E7=82=BA=E4=B8=AD=E8=8B=B1=E9=9B=99=E8=AA=9E?= =?UTF-8?q?=20README?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 227 +++++++++++++++++++++++++++++++++++++++++++----------- 1 file changed, 181 insertions(+), 46 deletions(-) diff --git a/README.md b/README.md index 75626c3..b3c694a 100644 --- a/README.md +++ b/README.md @@ -1,91 +1,226 @@ # reply-end-controls -Reply end controls for chat responses. +## 中文說明 -## Goal +### 專案目標 -At the end of each assistant reply, attach explicit user controls so the user can quickly choose whether the conversation should continue or stop cleanly. +這個專案要做的是「對話收尾控制元件」。 -The initial product goal is a two-button ending control: +在每次 assistant 回覆的最後，附上一組明確的互動選項，讓使用者快速決定這輪對話要不要繼續。 + +第一版的核心互動是兩個按鈕： - `A. 繼續` - `B. 就這樣吧，不需要額外處理` -The system should capture the user's button selection and feed it back into the assistant/runtime so future behavior can adapt accordingly. +系統需要能夠接住使用者點擊按鈕後的選擇，並把這個選擇回傳給 assistant 或 runtime，讓後續行為可以根據這個決定調整。 -If the user has a new request instead of choosing a button, they should still be able to type normally without any extra workflow. +如果使用者不是按按鈕，而是直接打新的訊息交辦事情，也必須照常運作，不能因為加了按鈕就強迫使用者先做選擇。 -## Scope +### 專案範圍 -This is a separate project from the OpenClaw governance interceptor work. +這是一個**獨立開發案**，和 OpenClaw governance interceptor 不混在一起。 -This repo is for the interaction-control feature only: +這個 repo 只處理「對話收尾控制」這件事，包含： -- rendering reply-end controls +- 在回覆尾端附上按鈕 +- 接收按鈕 callback +- 將使用者選擇映射到對話狀態 +- 保留使用者直接打字而不按按鈕的能力 + +### Phase 1 目標 + +Phase 1 先做 **Telegram**。 + +原因很簡單：Telegram 已經支援 inline keyboard 和 callback payload，是最適合先驗證這個互動模型的平台。 + +### 預期行為 + +#### 每次 assistant 回覆結尾 + +系統附上兩個明確控制： + +- 繼續 +- 就這樣吧 + +#### 如果使用者點「繼續」 + +runtime 應記錄： + +- 這輪對話還要繼續 + +可能的後續用途： + +- 允許 assistant 做後續追問 +- 保留較積極的上下文延續 +- 不要太早進入收尾狀態 + +#### 如果使用者點「就這樣吧，不需要額外處理」 + +runtime 應記錄： + +- 這輪對話可以收尾 +- 不需要 assistant 繼續延伸或追問 + +可能的後續用途： + +- 降低不必要的 follow-up +- 將該次回覆標記為 closed +- 壓制主動延伸行為 + +#### 如果使用者直接打字 + +使用者的新訊息應直接優先處理。 + +這表示： + +- 不必按按鈕也能繼續對話 +- 按鈕只是快速收尾控制，不是強制流程 + +### 非目標 + +這個專案第一版**不打算**處理： + +- 重做整個聊天 UI +- 重寫所有 reply delivery 邏輯 +- 做 claim/evidence 治理 +- 一開始就同時支援所有聊天平台 + +### 初步實作方向 + +Phase 1 可能至少需要以下幾層： + +1. **Reply payload augmentation** + - 把 Telegram inline buttons 附加到 assistant 回覆上 + +2. **Callback handling** + - 接收 Telegram 按鈕點擊事件 + - 解析 callback data + +3. **Conversation state storage** + - 記錄某個 session / conversation 的最近收尾選擇 + +4. **Policy hook** + - 讓 assistant 或 runtime 在下一輪可讀到： + - 使用者剛剛選的是 Continue 還是 Stop here + +### 建議里程碑 + +#### Milestone 1 + +- Telegram PoC 跑起來 +- 一則回覆能附兩個按鈕 +- 點一個按鈕後，系統能收到並記錄 + +#### Milestone 2 + +- 按鈕選擇能寫入 session/conversation state +- 使用者直接打字也能正常接續，不依賴按鈕 + +#### Milestone 3 + +- assistant/runtime 行為真的會受按鈕狀態影響 +- 明確定義 Continue / Stop here 對未來 turn 的行為差異 + +### 目前狀態 + +- repo 已建立 +- README 已補成正式雙語說明 +- 技術設計與實作尚未開始 + +--- + +## English + +### Goal + +This project builds **reply end controls** for chat responses. + +At the end of each assistant reply, the system should attach explicit interaction controls so the user can quickly decide whether the conversation should continue or stop cleanly. + +The initial interaction model is two buttons: + +- `A. Continue` +- `B. Stop here, no further action needed` + +The system must capture the user's button selection and feed it back into the assistant/runtime so later behavior can adapt accordingly. + +If the user wants to assign a new task by typing directly, that typed message must continue to work normally without forcing a button click first. + +### Scope + +This is a **separate project** from the OpenClaw governance interceptor work. + +This repository is only for the reply-end control feature, including: + +- rendering reply-end buttons - receiving button callbacks - mapping user choice into conversation state - preserving the ability to type freely instead of pressing a button -## Phase 1 target +### Phase 1 target -Build the first working version for **Telegram**. +Phase 1 targets **Telegram** first. -Telegram is the first target because it already supports inline buttons and callback payloads, which makes it the easiest place to validate the interaction model. +Telegram is the easiest first platform because it already supports inline keyboards and callback payloads, which makes it a good place to validate the interaction model. -## Expected behavior +### Expected behavior -### At the end of every assistant reply +#### At the end of every assistant reply -The system appends two visible controls: +The system appends two explicit controls: - Continue - Stop here -### If the user taps Continue +#### If the user taps Continue -The runtime records that the user wants to keep going. +The runtime should record that the conversation should continue. Possible future uses: - allow follow-up prompting -- keep short-term task context active -- suppress premature closure behavior +- preserve more active short-term continuation +- avoid premature closure behavior -### If the user taps Stop here +#### If the user taps Stop here -The runtime records that the user does not want additional handling. +The runtime should record that no additional handling is wanted for this turn. Possible future uses: -- avoid unnecessary follow-up suggestions +- reduce unnecessary follow-up suggestions - mark the reply as closed -- reduce proactive continuation behavior +- suppress proactive continuation behavior -### If the user types a new message instead +#### If the user types a new message instead -The typed message takes priority. +The typed message must take priority. -The user must not be forced to press a button before continuing the conversation. +That means: -## Non-goals +- the user can continue without pressing a button +- the controls are a convenience, not a forced workflow -For the initial version, this project does **not** try to: +### Non-goals + +The initial version does **not** aim to: - redesign the full chat UI - replace all reply delivery logic - solve governance / claim verification - support every chat platform at once -## Initial implementation direction +### Initial implementation direction -Phase 1 will likely need these parts: +Phase 1 will likely need at least these layers: 1. **Reply payload augmentation** - append Telegram inline buttons to assistant replies 2. **Callback handling** - - receive button presses from Telegram - - map callback data into internal conversation state + - receive Telegram button click events + - parse callback data 3. **Conversation state storage** - remember the most recent reply-end choice for a session or conversation @@ -93,26 +228,26 @@ Phase 1 will likely need these parts: 4. **Policy hook** - let the assistant/runtime inspect whether the user chose Continue or Stop here -## Suggested milestones +### Suggested milestones -### Milestone 1 +#### Milestone 1 - Telegram proof of concept -- one reply can render the two buttons +- one reply can render two buttons - one button click can be received and logged -### Milestone 2 +#### Milestone 2 -- map button clicks into session state -- confirm typed follow-up still works without pressing a button +- button choices can be written into session/conversation state +- typed follow-up still works without relying on buttons -### Milestone 3 +#### Milestone 3 -- apply button state to runtime behavior -- define exactly how Continue / Stop here influences future turns +- assistant/runtime behavior is actually influenced by button state +- Continue / Stop here behavior is clearly defined for later turns -## Current status +### Current status -- Repository created -- Initial README expanded -- Technical design and implementation not yet started +- repository created +- README expanded into a formal bilingual project description +- technical design and implementation have not started yet