320 lines
8.4 KiB
Markdown
320 lines
8.4 KiB
Markdown
# reply-end-controls
|
||
|
||
## 中文說明
|
||
|
||
### 快速開始
|
||
|
||
如果你是另一個工程型 agent，要直接使用目前這版 PoC，先跑：
|
||
|
||
```bash
|
||
bash scripts/install-openclawtest-poc.sh
|
||
```
|
||
|
||
之後可用：
|
||
|
||
```bash
|
||
npm run verify:openclawtest
|
||
npm run test
|
||
```
|
||
|
||
建議閱讀順序：
|
||
|
||
1. `INSTALL.md`
|
||
2. `HANDOFF.md`
|
||
3. `INTEGRATION.md`
|
||
4. `reports/final-readiness-report.md`
|
||
|
||
### 專案目標
|
||
|
||
這個專案要做的是「對話收尾控制元件」。
|
||
|
||
在每次 assistant 回覆的最後，附上一組明確的互動選項，讓使用者快速決定這輪對話要不要繼續。
|
||
|
||
第一版的核心互動是兩個按鈕：
|
||
|
||
- `A. 繼續`
|
||
- `B. 就這樣吧，不需要額外處理`
|
||
|
||
系統需要能夠接住使用者點擊按鈕後的選擇，並把這個選擇回傳給 assistant 或 runtime，讓後續行為可以根據這個決定調整。
|
||
|
||
如果使用者不是按按鈕，而是直接打新的訊息交辦事情，也必須照常運作，不能因為加了按鈕就強迫使用者先做選擇。
|
||
|
||
### 專案範圍
|
||
|
||
這是一個**獨立開發案**。
|
||
|
||
這個 repo 只處理「對話收尾控制」這件事，包含：
|
||
|
||
- 在回覆尾端附上按鈕
|
||
- 接收按鈕 callback
|
||
- 將使用者選擇映射到對話狀態
|
||
- 保留使用者直接打字而不按按鈕的能力
|
||
|
||
此外，這個專案從一開始就要考慮**插件化**，讓未來不只一個 assistant 可以使用，而是多個 agent / bot / assistant runtime 都可以共用同一套 reply-end-controls 能力。
|
||
|
||
### 專案目標平台
|
||
|
||
這個專案目前 **固定只做 Telegram**。
|
||
|
||
不考慮 Discord、Slack 或其他 channel。
|
||
|
||
所有設計、狀態結構、callback 流程、驗證方式，都以 Telegram 為唯一目標平台。
|
||
|
||
### 預期行為
|
||
|
||
#### 每次 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 已補成正式雙語說明
|
||
- 專案範圍已固定為 Telegram-only
|
||
- 核心設計文件已建立（state / policy / callback contract / OpenClaw adapter / PoC plan）
|
||
- Telegram + OpenClaw PoC 已成功打通：
|
||
- assistant 回覆可附按鈕
|
||
- callback 可接收
|
||
- state 可持久化
|
||
- stop/continue 已能影響後續行為
|
||
- Phase 1 acceptance 已完成，詳見 `reports/phase1-acceptance-success.md`
|
||
- 已達到可供其他工程型 agent 直接接手/使用的程度，詳見 `reports/final-readiness-report.md`
|
||
- 目前正往可維護、可重現的正式實作路徑收斂
|
||
|
||
---
|
||
|
||
## English
|
||
|
||
### Quick Start
|
||
|
||
If you are another engineering-focused agent and want to use the current PoC directly, start with:
|
||
|
||
```bash
|
||
bash scripts/install-openclawtest-poc.sh
|
||
```
|
||
|
||
Then use:
|
||
|
||
```bash
|
||
npm run verify:openclawtest
|
||
npm run test
|
||
```
|
||
|
||
Suggested reading order:
|
||
|
||
1. `HANDOFF.md`
|
||
2. `INTEGRATION.md`
|
||
3. `reports/final-readiness-report.md`
|
||
|
||
### 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 **standalone project**.
|
||
|
||
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
|
||
|
||
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.
|
||
|
||
Discord, Slack, and other channels are explicitly out of scope.
|
||
|
||
All design, state handling, callback flow, and testing will assume Telegram as the only target platform.
|
||
|
||
### Expected behavior
|
||
|
||
#### At the end of every assistant reply
|
||
|
||
The system appends two explicit controls:
|
||
|
||
- Continue
|
||
- Stop here
|
||
|
||
#### If the user taps Continue
|
||
|
||
The runtime should record that the conversation should continue.
|
||
|
||
Possible future uses:
|
||
|
||
- allow follow-up prompting
|
||
- preserve more active short-term continuation
|
||
- avoid premature closure behavior
|
||
|
||
#### If the user taps Stop here
|
||
|
||
The runtime should record that no additional handling is wanted for this turn.
|
||
|
||
Possible future uses:
|
||
|
||
- reduce unnecessary follow-up suggestions
|
||
- mark the reply as closed
|
||
- suppress proactive continuation behavior
|
||
|
||
#### If the user types a new message instead
|
||
|
||
The typed message must take priority.
|
||
|
||
That means:
|
||
|
||
- the user can continue without pressing a button
|
||
- the controls are a convenience, not a forced workflow
|
||
|
||
### 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
|
||
|
||
Phase 1 will likely need at least these layers:
|
||
|
||
1. **Reply payload augmentation**
|
||
- append Telegram inline buttons to assistant replies
|
||
|
||
2. **Callback handling**
|
||
- receive Telegram button click events
|
||
- parse callback data
|
||
|
||
3. **Conversation state storage**
|
||
- remember the most recent reply-end choice for a session or conversation
|
||
|
||
4. **Policy hook**
|
||
- let the assistant/runtime inspect whether the user chose Continue or Stop here
|
||
|
||
### Suggested milestones
|
||
|
||
#### Milestone 1
|
||
|
||
- Telegram proof of concept
|
||
- one reply can render two buttons
|
||
- one button click can be received and logged
|
||
|
||
#### Milestone 2
|
||
|
||
- button choices can be written into session/conversation state
|
||
- typed follow-up still works without relying on buttons
|
||
|
||
#### Milestone 3
|
||
|
||
- assistant/runtime behavior is actually influenced by button state
|
||
- Continue / Stop here behavior is clearly defined for later turns
|
||
|
||
### Current status
|
||
|
||
- repository created
|
||
- README expanded into a formal bilingual project description
|
||
- scope narrowed to Telegram-only
|
||
- Telegram/OpenClaw PoC has succeeded
|
||
- PoC success report: `reports/telegram-openclaw-poc-success.md`
|
||
- Phase 1 acceptance is complete; see `reports/phase1-acceptance-success.md`
|
||
- the project is now ready for direct use by another engineering-focused agent; see `reports/final-readiness-report.md`
|
||
- core design documents now exist (state / policy / callback contract / OpenClaw adapter / PoC plan)
|
||
- the current effort is focused on turning the successful PoC into a cleaner, maintainable implementation path
|