docs: bilingual README / 文件改為中英雙語 README

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
+- preserve more active short-term continuation
-- suppress premature closure behavior
+- 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
+   - receive Telegram button click events
-   - map callback data into internal conversation state
+   - 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
+- button choices can be written into session/conversation state
-- confirm typed follow-up still works without pressing a button
+- typed follow-up still works without relying on buttons
 
-### Milestone 3
+#### Milestone 3
 
-- apply button state to runtime behavior
+- assistant/runtime behavior is actually influenced by button state
-- define exactly how Continue / Stop here influences future turns
+- Continue / Stop here behavior is clearly defined for later turns
 
-## Current status
+### Current status
 
-- Repository created
+- repository created
-- Initial README expanded
+- README expanded into a formal bilingual project description
-- Technical design and implementation not yet started
+- technical design and implementation have not started yet