docs: add handoff and integration entrypoints / 新增 handoff 與 integration 入口文件
This commit is contained in:
Alice (OpenClaw)
79
HANDOFF.md
Normal file
79
HANDOFF.md
Normal file
@@ -0,0 +1,79 @@
|
||||
# HANDOFF
|
||||
|
||||
## What this project is
|
||||
|
||||
`reply-end-controls` is a Telegram-only interaction-control feature.
|
||||
|
||||
Its purpose is to add reply-end buttons to assistant replies:
|
||||
|
||||
- `A. 繼續`
|
||||
- `B. 就這樣吧，不需要額外處理`
|
||||
|
||||
The buttons are meant to:
|
||||
|
||||
- capture user intent about whether a conversation should continue
|
||||
- persist that choice
|
||||
- influence later assistant behavior
|
||||
|
||||
## What already works
|
||||
|
||||
In `openclawtest`, the Telegram + OpenClaw PoC has already proven:
|
||||
|
||||
- buttons can be attached to assistant replies
|
||||
- button clicks can be received as callback queries
|
||||
- callback state can be persisted
|
||||
- button UI can update
|
||||
- acknowledgement replies can be sent
|
||||
- stop/continue can influence later behavior
|
||||
|
||||
## What environment this currently targets
|
||||
|
||||
- Telegram only
|
||||
- OpenClaw runtime in `openclawtest`
|
||||
|
||||
This is not yet a clean cross-agent installable package. It is a successful PoC being pushed toward a cleaner reusable path.
|
||||
|
||||
## Where to start reading
|
||||
|
||||
Read these files first:
|
||||
|
||||
1. `README.md`
|
||||
2. `telegram-v1-design.md`
|
||||
3. `telegram-openclaw-poc-plan.md`
|
||||
4. `reports/telegram-openclaw-poc-success.md`
|
||||
5. `reports/openclaw-patch-inventory.md`
|
||||
6. `reports/openclaw-patch-mapping-matrix.md`
|
||||
7. `reports/next-phase-implementation-plan.md`
|
||||
8. `reports/agent-consumable-minimum.md`
|
||||
|
||||
## Repo structure
|
||||
|
||||
- `src/core/` - reusable state/policy/callback logic
|
||||
- `src/telegram/` - Telegram-specific helper logic
|
||||
- `src/adapters/` - OpenClaw-facing state bridge code
|
||||
- `src/runtime/` - runtime helper layer for current PoC behavior
|
||||
- `scripts/` - apply / rollback and helper scripts
|
||||
- `tests/` - current unit tests
|
||||
- `reports/` - design notes, PoC success, pluginization reports
|
||||
|
||||
## What is still fragile
|
||||
|
||||
- the live OpenClaw integration still uses runtime patching
|
||||
- the feature is not yet a clean installable plugin package
|
||||
- acceptance still includes human verification steps on Telegram UI
|
||||
|
||||
## If you are the next agent
|
||||
|
||||
Your likely next step is not to rediscover the idea.
|
||||
|
||||
Your likely next step is to make the current PoC easier to consume by:
|
||||
|
||||
- reducing runtime patching
|
||||
- tightening the apply/verify/rollback path
|
||||
- making the adapter seam cleaner
|
||||
|
||||
## Important constraint
|
||||
|
||||
Do not mix this project with the governance project.
|
||||
|
||||
They are separate workstreams.
|
||||
65
INTEGRATION.md
Normal file
65
INTEGRATION.md
Normal file
@@ -0,0 +1,65 @@
|
||||
# INTEGRATION
|
||||
|
||||
## Current integration model
|
||||
|
||||
The current working integration path is:
|
||||
|
||||
1. patch OpenClaw Telegram runtime
|
||||
2. restart the `openclawtest` gateway
|
||||
3. send a real Telegram assistant reply
|
||||
4. verify button rendering, callback handling, and state persistence
|
||||
|
||||
## Runtime files currently involved
|
||||
|
||||
See:
|
||||
|
||||
- `reports/openclaw-patch-inventory.md`
|
||||
|
||||
## Apply
|
||||
|
||||
Current patch apply script:
|
||||
|
||||
- `scripts/apply-openclaw-poc-patch.sh <openclaw-dist-dir>`
|
||||
|
||||
Example target dir in `openclawtest`:
|
||||
|
||||
```bash
|
||||
/home/openclawtest/.nvm/versions/node/v22.22.2/lib/node_modules/openclaw/dist
|
||||
```
|
||||
|
||||
## Rollback
|
||||
|
||||
Rollback script:
|
||||
|
||||
- `scripts/rollback-openclaw-poc-patch.sh <openclaw-dist-dir>`
|
||||
|
||||
This expects backup files created by the apply script.
|
||||
|
||||
## Verify
|
||||
|
||||
At minimum, verify these behaviors in Telegram:
|
||||
|
||||
1. assistant replies show both buttons
|
||||
2. clicking `continue` updates UI and writes state
|
||||
3. clicking `stop` updates UI and writes state
|
||||
4. later turns are influenced by stop/continue state
|
||||
|
||||
## Current persisted files in PoC mode
|
||||
|
||||
- `~/.openclaw/reply-end-controls.json`
|
||||
- `~/.openclaw/reply-end-debug.log`
|
||||
|
||||
## Current adapter-related repo modules
|
||||
|
||||
- `src/adapters/openclaw.ts`
|
||||
- `src/adapters/openclaw-state-file.ts`
|
||||
- `src/runtime/openclaw-telegram-bridge.ts`
|
||||
- `src/runtime/openclaw-telegram-poc.ts`
|
||||
|
||||
These do not yet replace the runtime patch end-to-end, but they are the current repo-side ownership points for the logic.
|
||||
|
||||
## Known limitation
|
||||
|
||||
The current integration path is reproducible, but not yet clean enough to call a final plugin package.
|
||||
|
||||
That is the next direction of work.
|
||||
102
reports/agent-consumable-minimum.md
Normal file
102
reports/agent-consumable-minimum.md
Normal file
@@ -0,0 +1,102 @@
|
||||
# Agent-Consumable Minimum
|
||||
|
||||
## Purpose
|
||||
|
||||
Define the minimum bar for saying `reply-end-controls` is ready for another AI agent to use directly, rather than merely continue developing.
|
||||
|
||||
## Current state
|
||||
|
||||
The project is already:
|
||||
|
||||
- understandable by another agent
|
||||
- reproducible as a Telegram/OpenClaw PoC
|
||||
- documented well enough for engineering handoff
|
||||
|
||||
But it is not yet at the point where another agent can simply adopt it as a clean integration without understanding the current patch model.
|
||||
|
||||
## Minimum bar for direct consumption
|
||||
|
||||
Another AI agent should be able to:
|
||||
|
||||
1. understand what the feature does
|
||||
2. understand what environment it targets
|
||||
3. apply it without hand-editing runtime files
|
||||
4. verify it works
|
||||
5. roll it back if needed
|
||||
|
||||
## Required deliverables
|
||||
|
||||
### 1. Clear integration entrypoint
|
||||
|
||||
There must be a single obvious entrypoint explaining:
|
||||
|
||||
- what to install
|
||||
- what to patch
|
||||
- what scripts to run
|
||||
- what runtime assumptions exist
|
||||
|
||||
### 2. Apply path
|
||||
|
||||
Another agent must be able to apply the current PoC without inventing its own patch process.
|
||||
|
||||
Current direction:
|
||||
|
||||
- `scripts/apply-openclaw-poc-patch.sh`
|
||||
|
||||
### 3. Verify path
|
||||
|
||||
Another agent must be able to verify:
|
||||
|
||||
- buttons appear
|
||||
- callback is received
|
||||
- state is written
|
||||
- stop/continue affect later behavior
|
||||
|
||||
Current direction:
|
||||
|
||||
- acceptance instructions
|
||||
- PoC reports
|
||||
|
||||
### 4. Rollback path
|
||||
|
||||
Another agent must be able to revert the patch safely.
|
||||
|
||||
Current direction:
|
||||
|
||||
- `scripts/rollback-openclaw-poc-patch.sh`
|
||||
|
||||
### 5. Integration contract
|
||||
|
||||
Another agent should not need to reverse-engineer the feature from raw runtime patches.
|
||||
|
||||
It should have direct access to:
|
||||
|
||||
- state model
|
||||
- callback contract
|
||||
- Telegram rendering rules
|
||||
- OpenClaw adapter assumptions
|
||||
|
||||
## Missing pieces before this bar is truly met
|
||||
|
||||
The main gaps are:
|
||||
|
||||
- no single `HANDOFF.md` or `INTEGRATION.md` entrypoint yet
|
||||
- the current implementation still relies on runtime patching rather than a clean installable integration unit
|
||||
- acceptance is still partly human-driven instead of fully scripted
|
||||
|
||||
## Recommended next tasks
|
||||
|
||||
1. add `HANDOFF.md`
|
||||
2. add `INTEGRATION.md`
|
||||
3. add a user-facing apply/verify/rollback flow description
|
||||
4. tighten the acceptance steps into a smaller repeatable checklist
|
||||
|
||||
## Completion rule
|
||||
|
||||
We can say the project is ready for another agent to directly use when:
|
||||
|
||||
- the repo contains a single handoff entrypoint
|
||||
- patch application is reproducible
|
||||
- patch rollback is reproducible
|
||||
- verification steps are explicit and bounded
|
||||
- the other agent does not need to inspect OpenClaw runtime internals before getting started
|
||||
Reference in New Issue
Block a user