diff --git a/README.md b/README.md index 095d2c0..fcd311e 100644 --- a/README.md +++ b/README.md @@ -8,6 +8,8 @@ Reusable OpenClaw skill for `/auto-continue` (`/ac`) session-level auto-followup ### 這個 repo 內有什麼 - `openclaw-auto-continue/SKILL.md` — **給 Agent 看的** skill 指引 +- `openclaw-auto-continue/references/installation-guide.md` — **給要落地 `/ac` 指令的人 / agent 看** 的安裝指南 +- `openclaw-auto-continue/references/runtime-integration.md` — `/ac` runtime integration 說明 - `openclaw-auto-continue.skill` — 已打包好的 skill 檔 ### 其他電腦怎麼用 @@ -97,7 +99,8 @@ cp -R openclaw-auto-continue ~/.openclaw/workspace/skills/ 一句話: - `README.md` 是給人 / operator 看的 - `openclaw-auto-continue/SKILL.md` 是給 agent 看的 -- `references/runtime-integration.md` 是給要落地 runtime 的人 / agent 看的 +- `references/installation-guide.md` 是給要從頭做到尾落地 `/ac` 的人 / agent 看的 +- `references/runtime-integration.md` 是給要理解 runtime 接法的人 / agent 看的 --- @@ -105,6 +108,8 @@ cp -R openclaw-auto-continue ~/.openclaw/workspace/skills/ ### What this repo contains - `openclaw-auto-continue/SKILL.md` — the **agent-facing** skill instructions +- `openclaw-auto-continue/references/installation-guide.md` — end-to-end guide for making `/ac` real on another machine +- `openclaw-auto-continue/references/runtime-integration.md` — runtime integration notes for `/ac` - `openclaw-auto-continue.skill` — packaged skill artifact ### For humans: how to use on another computer @@ -194,4 +199,5 @@ If an OpenClaw agent is deciding how to use this repo: In short: - `README.md` is the human/operator guide - `openclaw-auto-continue/SKILL.md` is the agent-facing guide -- `references/runtime-integration.md` is for runtime integration work +- `references/installation-guide.md` is for end-to-end `/ac` installation work +- `references/runtime-integration.md` is for runtime integration details diff --git a/openclaw-auto-continue/SKILL.md b/openclaw-auto-continue/SKILL.md index 76698a7..5bc4fc1 100644 --- a/openclaw-auto-continue/SKILL.md +++ b/openclaw-auto-continue/SKILL.md @@ -124,7 +124,7 @@ A practical verification flow: 3. Give the agent a multi-step but low-risk task 4. Confirm the agent continues without waiting after every intermediate step -If the target machine does not recognize `/ac`, read `references/runtime-integration.md` and treat it as a runtime integration problem, not a skill-discovery problem. +If the target machine does not recognize `/ac`, read `references/installation-guide.md` first, then `references/runtime-integration.md` if deeper implementation detail is needed. Treat it as a runtime integration problem, not a skill-discovery problem. If you need concrete implementation evidence, the verified live installation path was: - `/home/chchang/.nvm/versions/node/v22.22.0/lib/node_modules/openclaw/dist/commands-handlers.runtime-Akj_Dqoi.js` diff --git a/openclaw-auto-continue/references/installation-guide.md b/openclaw-auto-continue/references/installation-guide.md new file mode 100644 index 0000000..f7c49f9 --- /dev/null +++ b/openclaw-auto-continue/references/installation-guide.md @@ -0,0 +1,285 @@ +# Installation Guide: build `/auto-continue` (`/ac`) into a target OpenClaw runtime + +This guide is written so an agent can follow it end-to-end and add `/auto-continue` (`/ac`) support to another OpenClaw machine. + +Use this when the target machine has the skill/docs but the live runtime does not actually recognize `/ac`. + +## Goal + +After following this guide, the target machine should support: + +- `/ac status` +- `/ac on` +- `/ac off` +- `/auto-continue status` +- `/auto-continue on` +- `/auto-continue off` + +with session-level behavior equivalent to: + +- on: + - `queueMode = "followup"` + - `queueDebounceMs = 0` + - `queueCap = 1` + - `queueDrop = "summarize"` +- off: + - remove those session queue fields + - clear queued followup/lane items for that session + +--- + +## Phase 0 — Preconditions + +Before editing code, confirm all of these: + +1. You can access the target machine's OpenClaw installation. +2. You know which installation is actually running. +3. You can restart the OpenClaw service/process after changes. +4. You can test from a real chat surface after deployment. + +If any of these are unknown, stop and resolve them first. + +--- + +## Phase 1 — Locate the live runtime + +Do **not** assume the checked-out repo is the runtime. + +Find the actual OpenClaw installation used by the running service. On the verified machine, the live handler existed at: + +- `/home/chchang/.nvm/versions/node/v22.22.0/lib/node_modules/openclaw/dist/commands-handlers.runtime-Akj_Dqoi.js` + +What matters is not this exact path, but the principle: + +- identify the real running install +- patch the command handler in the live runtime or rebuild/redeploy the source that produces it + +### Verification checklist + +Before patching, confirm: +- which binary/service launches OpenClaw +- which code/dist that service is using +- whether slash commands are already handled in that runtime + +--- + +## Phase 2 — Find the command handler entry point + +Search the target runtime for the existing slash-command dispatch logic. + +You need the place where incoming messages/commands are parsed and existing commands are handled. + +Typical target shape: +- a function that receives inbound text +- a branch that recognizes slash commands +- session lookup/load logic +- persistence/save logic for session state + +If the target runtime already has command handlers, add `/auto-continue` and `/ac` there. + +--- + +## Phase 3 — Add `/ac` command recognition + +Add recognition for both: + +- `/auto-continue` +- `/ac` + +and their argument forms: + +- `/ac on` +- `/ac off` +- `/ac status` +- `/auto-continue on` +- `/auto-continue off` +- `/auto-continue status` + +### Parse rule + +Normalize input into one of: +- `status` +- `on` +- `off` + +Recommended default: +- if no argument is supplied, treat it as `status` + +--- + +## Phase 4 — Add handler behavior + +Implement behavior equivalent to the following pseudocode: + +```js +if (command is /ac or /auto-continue) { + authorizeSender(); + + const action = parseAction(arg); // status | on | off + const sessionEntry = await loadSessionEntry(sessionKey); + + if (action === 'status') { + return replyWithCurrentQueueMode(sessionEntry); + } + + if (action === 'on') { + sessionEntry.queueMode = 'followup'; + sessionEntry.queueDebounceMs = 0; + sessionEntry.queueCap = 1; + sessionEntry.queueDrop = 'summarize'; + await saveSessionEntry(sessionEntry); + return replyEnabled(); + } + + if (action === 'off') { + delete sessionEntry.queueMode; + delete sessionEntry.queueDebounceMs; + delete sessionEntry.queueCap; + delete sessionEntry.queueDrop; + await saveSessionEntry(sessionEntry); + await clearQueuedItemsForSession(sessionKey); + return replyDisabled(); + } +} +``` + +### Required semantics + +#### `status` +Return enough information to confirm whether the session is: +- default / unset, or +- using `followup` + +#### `on` +Must persist session settings so the behavior survives beyond the immediate in-memory branch. + +#### `off` +Must: +- remove the session-level queue config +- clear queued followup/lane items for that session so old queued actions do not keep running + +--- + +## Phase 5 — Preserve safety boundaries + +`/ac` must **not** bypass: +- approvals +- safety checks +- destructive action confirmation +- decision gates that still require the user + +This is a queue/followup behavior switch, not unrestricted autonomy. + +--- + +## Phase 6 — Deploy the change + +Use the deployment path appropriate for the target machine: + +### Option A — patch live dist directly +Use this only when you intentionally maintain a live dist patch. + +### Option B — patch source, then rebuild/redeploy +Preferred when the target machine is managed from source. + +After deployment: +1. restart the OpenClaw process/service +2. confirm the restarted service is using the new runtime +3. verify the target chat surface still routes commands normally + +--- + +## Phase 7 — Verify on a real chat + +Use a real chat/session on the target machine. + +### Test 1 — command recognition +Run: + +```text +/ac status +``` + +Expected: +- no unknown-command failure +- a status reply describing the current queue mode + +### Test 2 — enable +Run: + +```text +/ac on +/ac status +``` + +Expected: +- status now shows followup mode or equivalent enabled state + +### Test 3 — practical behavior +Give a low-risk, multi-step task. + +Expected: +- the agent is more likely to continue into the next step +- the agent pauses less between intermediate steps +- approvals/safety still stop it when appropriate + +### Test 4 — disable +Run: + +```text +/ac off +/ac status +``` + +Expected: +- status returns to default/unset behavior +- any queued followup work for that session is cleared + +--- + +## Phase 8 — Troubleshooting + +### Problem: `/ac` is unknown +Likely causes: +- you edited the wrong installation +- service restarted into a different runtime +- the surface does not pass through slash commands +- the handler was added in source but not rebuilt/deployed + +### Problem: `/ac status` works but `/ac on` has no effect +Check: +- whether the session entry is actually being saved +- whether you are testing the same session you enabled +- whether queue fields are being overwritten elsewhere + +### Problem: `/ac off` replies successfully but the agent still continues +Check: +- whether queued followup/lane items were really cleared +- whether a different queue path exists in this runtime +- whether the next message was already in flight before disable completed + +### Problem: it still pauses sometimes even when enabled +That can be normal if the next step is blocked by: +- approval requirements +- safety checks +- destructive actions +- explicit user choice points + +--- + +## Acceptance criteria + +Do not claim completion unless all are true: + +1. `/ac status` is recognized on the target machine +2. `/ac on` changes the session to followup mode +3. `/ac off` removes that mode +4. queued followup items are cleared on disable +5. a real chat test confirms improved auto-continue behavior +6. approvals/safety behavior is unchanged + +--- + +## One-line rule + +**The skill teaches usage, but this installation guide is the procedure that makes `/ac` real on another machine.**