reply-end-controls/README.md

reply-end-controls

中文說明

專案目標

這個專案要做的是「對話收尾控制元件」。

在每次 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
• 目前正往可維護、可重現的正式實作路徑收斂

---

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 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
• 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