docs: add continuity agent guide
This commit is contained in:
641
plugins/continuity/AGENT_GUIDE.zh-TW.md
Normal file
641
plugins/continuity/AGENT_GUIDE.zh-TW.md
Normal file
@@ -0,0 +1,641 @@
|
|||||||
|
# Continuity Plugin MVP：Agent 安裝與操作手冊
|
||||||
|
|
||||||
|
> 目標讀者：OpenClaw agent / 實作者
|
||||||
|
>
|
||||||
|
> 這份文件不是概念介紹，而是可直接照做的 runbook / checklist。
|
||||||
|
> 若你只想知道「要不要裝、怎麼接、怎麼驗證」，先看本文，不必先讀完整 README。
|
||||||
|
|
||||||
|
## 0. 這個 plugin 什麼時候要裝
|
||||||
|
|
||||||
|
### 應安裝的情況
|
||||||
|
|
||||||
|
如果你的 workspace 符合以下任一條件，建議安裝：
|
||||||
|
|
||||||
|
- 你有 **approved-plan** 類型的長任務 / 多步驟任務。
|
||||||
|
- 你不希望 agent 在某個 task 做完後，直接把整件事當成「已完成」結案。
|
||||||
|
- 你需要 agent 在同一個 approved plan 內，判斷是否還有 **下一個要派發的 task**。
|
||||||
|
- 你需要用 **dispatch receipt** 證明「真的有派出下一步」，而不是只在回覆裡口頭說會繼續。
|
||||||
|
- 你已經在用 `hooks/force-recall/handler.ts`，希望把 approved-plan continuity gate 注入 agent prompt。
|
||||||
|
|
||||||
|
### 可先不裝的情況
|
||||||
|
|
||||||
|
以下情況可先不裝，或只當參考：
|
||||||
|
|
||||||
|
- 你的 workspace 沒有 approved-plan / auto-chain / dispatch 這類流程。
|
||||||
|
- 你只需要一般單回合聊天，不需要 continuity hard gate。
|
||||||
|
- 你沒有 `force-recall` hook，也暫時不打算自己補 glue code。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 1. 安裝目標與預期結果
|
||||||
|
|
||||||
|
安裝完成後，應達到這個最小結果：
|
||||||
|
|
||||||
|
- `hooks/force-recall/handler.ts` 能載入 `plugins/continuity/src/index.mjs`
|
||||||
|
- hook 在 preflight 時會呼叫 `runForceRecallContinuityAdapter(...)`
|
||||||
|
- agent prompt 內可看到 `[APPROVED_PLAN_CONTINUITY_GATE] ... [/APPROVED_PLAN_CONTINUITY_GATE]`
|
||||||
|
- 當 approved plan 任務完成，但沒有真實下一步 dispatch receipt 時，gate 會擋下錯誤結案
|
||||||
|
- plugin 自身測試與 hook smoke test 可通過
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 2. 應放到哪裡
|
||||||
|
|
||||||
|
### 標準位置
|
||||||
|
|
||||||
|
把 plugin 放在 workspace 內這個位置：
|
||||||
|
|
||||||
|
```text
|
||||||
|
<workspace>/plugins/continuity
|
||||||
|
```
|
||||||
|
|
||||||
|
以目前 MVP 的預期 layout：
|
||||||
|
|
||||||
|
```text
|
||||||
|
<workspace>/
|
||||||
|
hooks/
|
||||||
|
force-recall/
|
||||||
|
handler.ts
|
||||||
|
HOOK.md
|
||||||
|
plugins/
|
||||||
|
continuity/
|
||||||
|
AGENT_GUIDE.zh-TW.md
|
||||||
|
README.zh-TW.md
|
||||||
|
README.md
|
||||||
|
HOOK.md
|
||||||
|
package.json
|
||||||
|
examples/
|
||||||
|
src/
|
||||||
|
test/
|
||||||
|
scripts/
|
||||||
|
test_force_recall_long_task_preflight.mjs
|
||||||
|
```
|
||||||
|
|
||||||
|
### 本次文件對應的實際路徑
|
||||||
|
|
||||||
|
```text
|
||||||
|
/home/alice/.openclaw/workspace/plugins/continuity
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 3. 安裝前 checklist
|
||||||
|
|
||||||
|
在開始前，先確認：
|
||||||
|
|
||||||
|
- [ ] 你的 workspace 有 `hooks/force-recall/handler.ts`
|
||||||
|
- [ ] 你的 workspace 有 `scripts/test_force_recall_long_task_preflight.mjs`
|
||||||
|
- [ ] 你的 workspace 願意採用 approved-plan continuity hard gate
|
||||||
|
- [ ] 你接受 MVP 目前只優先支援 `force-recall` adapter
|
||||||
|
- [ ] 你知道 receipt 只是「最小 contract」，不是完整 workflow engine
|
||||||
|
|
||||||
|
可先用以下命令確認：
|
||||||
|
|
||||||
|
```bash
|
||||||
|
cd <workspace>
|
||||||
|
ls hooks/force-recall/handler.ts
|
||||||
|
ls scripts/test_force_recall_long_task_preflight.mjs
|
||||||
|
ls plugins/continuity/package.json
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 4. 需要哪些檔案
|
||||||
|
|
||||||
|
### 必要檔案
|
||||||
|
|
||||||
|
至少要有以下檔案：
|
||||||
|
|
||||||
|
```text
|
||||||
|
plugins/continuity/
|
||||||
|
package.json
|
||||||
|
src/index.mjs
|
||||||
|
src/adapters/force-recall.mjs
|
||||||
|
src/config/defaults.mjs
|
||||||
|
src/config/schema.mjs
|
||||||
|
src/continuity/evaluator.mjs
|
||||||
|
src/continuity/receipt-validator.mjs
|
||||||
|
src/continuity/receipt-store.mjs
|
||||||
|
examples/openclaw.continuity.example.json
|
||||||
|
examples/approved-plan-receipt.example.json
|
||||||
|
```
|
||||||
|
|
||||||
|
### 建議一起帶走的檔案
|
||||||
|
|
||||||
|
```text
|
||||||
|
plugins/continuity/
|
||||||
|
README.zh-TW.md
|
||||||
|
README.md
|
||||||
|
HOOK.md
|
||||||
|
AGENT_GUIDE.zh-TW.md
|
||||||
|
test/continuity.config.test.mjs
|
||||||
|
test/continuity.receipt-validator.test.mjs
|
||||||
|
test/continuity.receipt-store.test.mjs
|
||||||
|
test/continuity.evaluator.test.mjs
|
||||||
|
test/continuity.plugin.test.mjs
|
||||||
|
test/continuity.smoke.test.mjs
|
||||||
|
```
|
||||||
|
|
||||||
|
### 如果缺檔，先補哪些
|
||||||
|
|
||||||
|
優先順序：
|
||||||
|
|
||||||
|
1. `src/index.mjs`
|
||||||
|
2. `src/adapters/force-recall.mjs`
|
||||||
|
3. `src/continuity/evaluator.mjs`
|
||||||
|
4. `src/continuity/receipt-validator.mjs`
|
||||||
|
5. `src/continuity/receipt-store.mjs`
|
||||||
|
6. `examples/openclaw.continuity.example.json`
|
||||||
|
7. `test/continuity.smoke.test.mjs`
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 5. 直接安裝步驟
|
||||||
|
|
||||||
|
### 路徑 A：你已經在同一個 repo / workspace 內
|
||||||
|
|
||||||
|
- [ ] 確認 `plugins/continuity` 目錄存在
|
||||||
|
- [ ] 確認 `package.json` 與 `src/index.mjs` 存在
|
||||||
|
- [ ] 確認 `hooks/force-recall/handler.ts` 存在
|
||||||
|
|
||||||
|
驗證命令：
|
||||||
|
|
||||||
|
```bash
|
||||||
|
cd <workspace>
|
||||||
|
find plugins/continuity -maxdepth 3 -type f | sort
|
||||||
|
```
|
||||||
|
|
||||||
|
### 路徑 B：你要複製到另一個 OpenClaw workspace
|
||||||
|
|
||||||
|
在來源 workspace：
|
||||||
|
|
||||||
|
```bash
|
||||||
|
cd <source-workspace>
|
||||||
|
rsync -av plugins/continuity/ <target-workspace>/plugins/continuity/
|
||||||
|
```
|
||||||
|
|
||||||
|
複製後在目標 workspace 驗證：
|
||||||
|
|
||||||
|
```bash
|
||||||
|
cd <target-workspace>
|
||||||
|
find plugins/continuity -maxdepth 3 -type f | sort
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 6. example config 怎麼套
|
||||||
|
|
||||||
|
### Step 1：從 example 複製一份你的 continuity config
|
||||||
|
|
||||||
|
來源範例：
|
||||||
|
|
||||||
|
```text
|
||||||
|
plugins/continuity/examples/openclaw.continuity.example.json
|
||||||
|
```
|
||||||
|
|
||||||
|
範例內容：
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"enabled": true,
|
||||||
|
"planMatchers": ["approved-plan"],
|
||||||
|
"legalTerminalStates": [
|
||||||
|
"waiting_user",
|
||||||
|
"blocked",
|
||||||
|
"pending_verification"
|
||||||
|
],
|
||||||
|
"receiptDir": "state/approved-plan-continuity",
|
||||||
|
"requireRealDispatchReceipt": true,
|
||||||
|
"allowReplyClosureWithoutDispatch": false,
|
||||||
|
"debug": false,
|
||||||
|
"adapter": {
|
||||||
|
"forceRecall": {
|
||||||
|
"enabled": true,
|
||||||
|
"injectBlockLabel": "APPROVED_PLAN_CONTINUITY_GATE"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Step 2：先只改最少必要欄位
|
||||||
|
|
||||||
|
通常只需要先確認這幾個欄位：
|
||||||
|
|
||||||
|
- [ ] `enabled`
|
||||||
|
- [ ] `planMatchers`
|
||||||
|
- [ ] `legalTerminalStates`
|
||||||
|
- [ ] `receiptDir`
|
||||||
|
- [ ] `requireRealDispatchReceipt`
|
||||||
|
- [ ] `allowReplyClosureWithoutDispatch`
|
||||||
|
- [ ] `adapter.forceRecall.enabled`
|
||||||
|
- [ ] `adapter.forceRecall.injectBlockLabel`
|
||||||
|
|
||||||
|
### Step 3：建議的最小套用策略
|
||||||
|
|
||||||
|
#### 情境 A：你就是要沿用目前 approved-plan MVP 行為
|
||||||
|
|
||||||
|
直接照 example 使用，通常不用改：
|
||||||
|
|
||||||
|
- `planMatchers = ["approved-plan"]`
|
||||||
|
- `legalTerminalStates = ["waiting_user", "blocked", "pending_verification"]`
|
||||||
|
- `requireRealDispatchReceipt = true`
|
||||||
|
- `allowReplyClosureWithoutDispatch = false`
|
||||||
|
|
||||||
|
#### 情境 B：你有自己的 plan 名稱
|
||||||
|
|
||||||
|
如果你的 wrapper / planner 用的是別的 plan 名稱，調整：
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"planMatchers": ["your-approved-plan-name"]
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
#### 情境 C：你想改 injected block label
|
||||||
|
|
||||||
|
如果你不想使用預設 label：
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"adapter": {
|
||||||
|
"forceRecall": {
|
||||||
|
"enabled": true,
|
||||||
|
"injectBlockLabel": "YOUR_CONTINUITY_GATE"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Step 4：receiptDir 先建起來
|
||||||
|
|
||||||
|
```bash
|
||||||
|
cd <workspace>
|
||||||
|
mkdir -p state/approved-plan-continuity
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 7. 如何接 `force-recall` hook
|
||||||
|
|
||||||
|
## 7.1 你要確認的整合點
|
||||||
|
|
||||||
|
MVP 的主要整合點是：
|
||||||
|
|
||||||
|
```text
|
||||||
|
hooks/force-recall/handler.ts
|
||||||
|
```
|
||||||
|
|
||||||
|
目前 hook 端流程應該是：
|
||||||
|
|
||||||
|
1. 跑 long-task preflight / wrapper
|
||||||
|
2. 跑 gate lock
|
||||||
|
3. 跑 auto-chain planner
|
||||||
|
4. 載入 continuity plugin
|
||||||
|
5. 呼叫 `runForceRecallContinuityAdapter(...)`
|
||||||
|
6. 把 continuity block prepend 到 `bodyForAgent`
|
||||||
|
|
||||||
|
### 你至少要看到這些關鍵符號
|
||||||
|
|
||||||
|
- `plugins/continuity/src/index.mjs`
|
||||||
|
- `runForceRecallContinuityAdapter`
|
||||||
|
- `APPROVED_PLAN_CONTINUITY_GATE`
|
||||||
|
|
||||||
|
檢查命令：
|
||||||
|
|
||||||
|
```bash
|
||||||
|
cd <workspace>
|
||||||
|
grep -n "runForceRecallContinuityAdapter" hooks/force-recall/handler.ts
|
||||||
|
grep -n "APPROVED_PLAN_CONTINUITY_GATE" hooks/force-recall/handler.ts
|
||||||
|
grep -n "plugins\", \"continuity\", \"src\", \"index.mjs" hooks/force-recall/handler.ts
|
||||||
|
```
|
||||||
|
|
||||||
|
## 7.2 最小接法範例
|
||||||
|
|
||||||
|
如果你要自己補接，最小概念如下：
|
||||||
|
|
||||||
|
```js
|
||||||
|
import plugin from './plugins/continuity/src/index.mjs';
|
||||||
|
|
||||||
|
const out = plugin.runForceRecallContinuityAdapter({
|
||||||
|
config: plugin.defaultConfig,
|
||||||
|
wrapperResult,
|
||||||
|
autoChainPlanResult,
|
||||||
|
});
|
||||||
|
|
||||||
|
if (out?.block) {
|
||||||
|
context.bodyForAgent = `${out.block}\n${context.bodyForAgent}`;
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## 7.3 實作者要檢查的實際條件
|
||||||
|
|
||||||
|
- [ ] hook 能動態 import `plugins/continuity/src/index.mjs`
|
||||||
|
- [ ] `runForceRecallContinuityAdapter` 是 function
|
||||||
|
- [ ] 傳入 `wrapperResult`
|
||||||
|
- [ ] 傳入 `autoChainPlanResult`
|
||||||
|
- [ ] 有傳 `config`（至少先用 `defaultConfig`）
|
||||||
|
- [ ] `out.block` 非空時有 prepend 到 `bodyForAgent`
|
||||||
|
- [ ] agent prompt 最終可見 continuity gate block
|
||||||
|
|
||||||
|
## 7.4 receipt 與 continuity input 的關係
|
||||||
|
|
||||||
|
如果你的流程真的有派發下一步，請不要只在字串裡描述「已派發」，而要產出真實 `dispatchReceipt`。
|
||||||
|
|
||||||
|
最小 receipt shape：
|
||||||
|
|
||||||
|
- `planId`
|
||||||
|
- `currentTask`
|
||||||
|
- `nextDerivedAction`
|
||||||
|
- `dispatchedAt`
|
||||||
|
- `dispatchRunId`
|
||||||
|
- `childSessionKey`
|
||||||
|
- `replyClosureState`
|
||||||
|
|
||||||
|
範例：`plugins/continuity/examples/approved-plan-receipt.example.json`
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 8. 實作時建議直接照抄的操作流程
|
||||||
|
|
||||||
|
### Checklist：第一次把 plugin 接進現有 workspace
|
||||||
|
|
||||||
|
- [ ] 建立 / 複製 `plugins/continuity`
|
||||||
|
- [ ] 確認 `src/index.mjs` 可被 hook 載入
|
||||||
|
- [ ] 確認 continuity example config 可讀
|
||||||
|
- [ ] 建立 `state/approved-plan-continuity/`
|
||||||
|
- [ ] 確認 `hooks/force-recall/handler.ts` 有 continuity adapter 接點
|
||||||
|
- [ ] 確認有 prepend continuity block 到 `bodyForAgent`
|
||||||
|
- [ ] 若 dispatch 真的發生，補上 receipt 寫檔
|
||||||
|
- [ ] 跑 plugin test
|
||||||
|
- [ ] 跑 force-recall smoke test
|
||||||
|
- [ ] 檢查 injected prompt block 是否存在
|
||||||
|
|
||||||
|
### Checklist：第一次加 receipt 落盤
|
||||||
|
|
||||||
|
- [ ] 準備合法 receipt object
|
||||||
|
- [ ] 先用 `validateReceipt()` / `isValidReceipt()` 驗證
|
||||||
|
- [ ] 用 `writeReceipt({ receiptDir, receipt })` 落盤
|
||||||
|
- [ ] 確認 receipt 寫到 `state/approved-plan-continuity/`
|
||||||
|
- [ ] 再跑 continuity smoke test，避免只是「看起來有 receipt」
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 9. 安裝後怎麼跑 smoke test
|
||||||
|
|
||||||
|
### 最小 smoke test
|
||||||
|
|
||||||
|
先跑 plugin 自己的測試：
|
||||||
|
|
||||||
|
```bash
|
||||||
|
cd <workspace>/plugins/continuity
|
||||||
|
npm test
|
||||||
|
```
|
||||||
|
|
||||||
|
如果你只想快速驗證 plugin 主體：
|
||||||
|
|
||||||
|
```bash
|
||||||
|
cd <workspace>/plugins/continuity
|
||||||
|
node test/continuity.smoke.test.mjs
|
||||||
|
```
|
||||||
|
|
||||||
|
### Hook 整合 smoke test
|
||||||
|
|
||||||
|
```bash
|
||||||
|
cd <workspace>
|
||||||
|
node scripts/test_force_recall_long_task_preflight.mjs
|
||||||
|
node --check hooks/force-recall/handler.ts
|
||||||
|
```
|
||||||
|
|
||||||
|
### 建議的完整 smoke test 順序
|
||||||
|
|
||||||
|
照這個順序最容易定位問題：
|
||||||
|
|
||||||
|
1. plugin 單體測試
|
||||||
|
|
||||||
|
```bash
|
||||||
|
cd <workspace>/plugins/continuity
|
||||||
|
npm test
|
||||||
|
```
|
||||||
|
|
||||||
|
2. hook 檔案語法檢查
|
||||||
|
|
||||||
|
```bash
|
||||||
|
cd <workspace>
|
||||||
|
node --check hooks/force-recall/handler.ts
|
||||||
|
```
|
||||||
|
|
||||||
|
3. hook preflight smoke test
|
||||||
|
|
||||||
|
```bash
|
||||||
|
cd <workspace>
|
||||||
|
node scripts/test_force_recall_long_task_preflight.mjs
|
||||||
|
```
|
||||||
|
|
||||||
|
4. 人工檢查 block 是否真的被 inject
|
||||||
|
|
||||||
|
建議檢查測試輸出或 debug prompt，確認有出現：
|
||||||
|
|
||||||
|
```text
|
||||||
|
[APPROVED_PLAN_CONTINUITY_GATE]
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 10. Smoke test 通過標準
|
||||||
|
|
||||||
|
以下條件都成立，才算最小安裝成功：
|
||||||
|
|
||||||
|
- [ ] `npm test` 全通過
|
||||||
|
- [ ] `node --check hooks/force-recall/handler.ts` 通過
|
||||||
|
- [ ] `node scripts/test_force_recall_long_task_preflight.mjs` 通過
|
||||||
|
- [ ] 測試 / 輸出中可看到 continuity gate block
|
||||||
|
- [ ] 沒有 receipt 時，gate 會對缺少 dispatch 的情境做 fail / hard-gate
|
||||||
|
- [ ] 有合法 terminal state（例如 `waiting_user` / `blocked` / `pending_verification`）時，不會誤判
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 11. 失敗時先檢查什麼
|
||||||
|
|
||||||
|
請依這個順序排查，不要一開始就到處改 code。
|
||||||
|
|
||||||
|
### 第一層：路徑 / 檔案是否存在
|
||||||
|
|
||||||
|
- [ ] `plugins/continuity/src/index.mjs` 存在
|
||||||
|
- [ ] `hooks/force-recall/handler.ts` 存在
|
||||||
|
- [ ] `plugins/continuity/examples/openclaw.continuity.example.json` 存在
|
||||||
|
- [ ] `plugins/continuity/examples/approved-plan-receipt.example.json` 存在
|
||||||
|
|
||||||
|
命令：
|
||||||
|
|
||||||
|
```bash
|
||||||
|
cd <workspace>
|
||||||
|
ls plugins/continuity/src/index.mjs
|
||||||
|
ls hooks/force-recall/handler.ts
|
||||||
|
ls plugins/continuity/examples/openclaw.continuity.example.json
|
||||||
|
ls plugins/continuity/examples/approved-plan-receipt.example.json
|
||||||
|
```
|
||||||
|
|
||||||
|
### 第二層：hook 是否真的有接到 plugin
|
||||||
|
|
||||||
|
- [ ] `handler.ts` 有 import / dynamic import continuity plugin
|
||||||
|
- [ ] `handler.ts` 有呼叫 `runForceRecallContinuityAdapter(...)`
|
||||||
|
- [ ] `handler.ts` 有把 `out.block` prepend 到 `bodyForAgent`
|
||||||
|
|
||||||
|
### 第三層：config 是否合理
|
||||||
|
|
||||||
|
優先檢查：
|
||||||
|
|
||||||
|
- [ ] `enabled` 是否為 `true`
|
||||||
|
- [ ] `adapter.forceRecall.enabled` 是否為 `true`
|
||||||
|
- [ ] `planMatchers` 是否對得上你的 approved plan 名稱
|
||||||
|
- [ ] `receiptDir` 是否可寫
|
||||||
|
- [ ] `requireRealDispatchReceipt` 是否符合你預期
|
||||||
|
- [ ] `allowReplyClosureWithoutDispatch` 是否不小心放寬了 gate
|
||||||
|
|
||||||
|
### 第四層：receipt 是否是真的、不是假資料
|
||||||
|
|
||||||
|
最常見問題：
|
||||||
|
|
||||||
|
- 只有「打算 dispatch」但沒有真實 receipt
|
||||||
|
- receipt shape 不完整
|
||||||
|
- `dispatchRunId` / `childSessionKey` 空字串
|
||||||
|
- `replyClosureState` 不在合法狀態
|
||||||
|
- 寫到了錯誤資料夾
|
||||||
|
|
||||||
|
### 第五層：hook 前置資料是否足夠
|
||||||
|
|
||||||
|
因為 continuity adapter 會吃：
|
||||||
|
|
||||||
|
- `wrapperResult`
|
||||||
|
- `autoChainPlanResult`
|
||||||
|
|
||||||
|
所以要檢查：
|
||||||
|
|
||||||
|
- [ ] wrapper 是否真的把 long-task / approved-plan 狀態帶進來
|
||||||
|
- [ ] planner 是否真的產出 `derivedAction`
|
||||||
|
- [ ] `nextDerivedAction` 是否能被 continuity input 建出來
|
||||||
|
- [ ] closure state 是否被正確推導
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 12. 快速除錯命令
|
||||||
|
|
||||||
|
### 看 plugin 測試是否全過
|
||||||
|
|
||||||
|
```bash
|
||||||
|
cd <workspace>/plugins/continuity
|
||||||
|
npm test
|
||||||
|
```
|
||||||
|
|
||||||
|
### 看 hook 語法有沒有壞
|
||||||
|
|
||||||
|
```bash
|
||||||
|
cd <workspace>
|
||||||
|
node --check hooks/force-recall/handler.ts
|
||||||
|
```
|
||||||
|
|
||||||
|
### 看 handler 裡 continuity 關鍵字是否存在
|
||||||
|
|
||||||
|
```bash
|
||||||
|
cd <workspace>
|
||||||
|
grep -n "runForceRecallContinuityAdapter" hooks/force-recall/handler.ts
|
||||||
|
grep -n "APPROVED_PLAN_CONTINUITY_GATE" hooks/force-recall/handler.ts
|
||||||
|
```
|
||||||
|
|
||||||
|
### 看 receipt 資料夾有沒有東西
|
||||||
|
|
||||||
|
```bash
|
||||||
|
cd <workspace>
|
||||||
|
find state/approved-plan-continuity -maxdepth 2 -type f | sort
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 13. 目前限制
|
||||||
|
|
||||||
|
這個 MVP 目前有以下限制，安裝前要先接受：
|
||||||
|
|
||||||
|
- 它是 **approved-plan continuity hard gate** 的抽離版，不是通用 workflow engine。
|
||||||
|
- 主要 adapter 目前只有 `force-recall`。
|
||||||
|
- 文件描述的是「接在既有 force-recall preflight 鏈上」的路徑；若你的 workspace 沒這條鏈，仍要自己補 glue code。
|
||||||
|
- config 目前是模組預設值 + 呼叫端傳入，不是完整 plugin installer / registry 流程。
|
||||||
|
- receipt store 目前只負責寫檔，不管 retention、cleanup、indexing。
|
||||||
|
- receipt validator 目前只驗證最小 contract，不會深入驗證每種 `nextDerivedAction` 的完整語意。
|
||||||
|
- 若你只做 dry-run planning、沒有真實 dispatch receipt，gate 仍可能視為未通過；這是設計目標，不是 bug。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 14. 建議的交付標準：什麼叫「agent 可照做」
|
||||||
|
|
||||||
|
若你要把這個 plugin 交給另一位 agent / 實作者，至少應滿足：
|
||||||
|
|
||||||
|
- [ ] 他不需要回頭爬整段對話，也知道 plugin 的用途
|
||||||
|
- [ ] 他知道檔案應放在哪裡
|
||||||
|
- [ ] 他知道要帶哪些檔案
|
||||||
|
- [ ] 他知道怎麼接 `force-recall` hook
|
||||||
|
- [ ] 他知道 example config 先改哪些欄位
|
||||||
|
- [ ] 他知道怎麼跑 smoke test
|
||||||
|
- [ ] 他知道失敗先查哪幾層
|
||||||
|
- [ ] 他知道目前限制，不會誤以為這是完整 workflow framework
|
||||||
|
|
||||||
|
如果以上 8 點都回答得出來，才算達到「agent 可照做」。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 15. 一頁版執行摘要（超短版）
|
||||||
|
|
||||||
|
如果你趕時間，只做下面這些：
|
||||||
|
|
||||||
|
1. 把 plugin 放到：
|
||||||
|
|
||||||
|
```text
|
||||||
|
<workspace>/plugins/continuity
|
||||||
|
```
|
||||||
|
|
||||||
|
2. 確認 hook 有接：
|
||||||
|
|
||||||
|
- `plugins/continuity/src/index.mjs`
|
||||||
|
- `runForceRecallContinuityAdapter(...)`
|
||||||
|
- prepend `out.block` 到 `bodyForAgent`
|
||||||
|
|
||||||
|
3. 套 example config：
|
||||||
|
|
||||||
|
```text
|
||||||
|
plugins/continuity/examples/openclaw.continuity.example.json
|
||||||
|
```
|
||||||
|
|
||||||
|
4. 建 receipt 目錄：
|
||||||
|
|
||||||
|
```bash
|
||||||
|
mkdir -p <workspace>/state/approved-plan-continuity
|
||||||
|
```
|
||||||
|
|
||||||
|
5. 跑測試：
|
||||||
|
|
||||||
|
```bash
|
||||||
|
cd <workspace>/plugins/continuity && npm test
|
||||||
|
cd <workspace> && node --check hooks/force-recall/handler.ts
|
||||||
|
cd <workspace> && node scripts/test_force_recall_long_task_preflight.mjs
|
||||||
|
```
|
||||||
|
|
||||||
|
6. 確認 prompt 裡有：
|
||||||
|
|
||||||
|
```text
|
||||||
|
[APPROVED_PLAN_CONTINUITY_GATE]
|
||||||
|
```
|
||||||
|
|
||||||
|
7. 確認沒有真實 dispatch receipt 時，不會被錯誤判定為已完成。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 16. 參考文件
|
||||||
|
|
||||||
|
- `plugins/continuity/README.zh-TW.md`
|
||||||
|
- `plugins/continuity/README.md`
|
||||||
|
- `plugins/continuity/HOOK.md`
|
||||||
|
- `plugins/continuity/examples/openclaw.continuity.example.json`
|
||||||
|
- `plugins/continuity/examples/approved-plan-receipt.example.json`
|
||||||
|
- `hooks/force-recall/handler.ts`
|
||||||
|
- `scripts/test_force_recall_long_task_preflight.mjs`
|
||||||
|
|
||||||
|
如需英文版，可再從本文翻成 `AGENT_GUIDE.md`；MVP 階段中文版優先即可。
|
||||||
Reference in New Issue
Block a user