# Continuity Plugin：Generic / Manual Integration Runbook

> 目標讀者：**沒有 `force-recall` hook 的宿主 / orchestrator / planner 實作者**
>
> 這份文件專門說明：當你的 host 沒有 `hooks/force-recall/handler.ts` 時，如何仍然安裝 continuity plugin、提供 payload、執行 manual/generic preflight，並驗證 continuity gate block 真的有生效。

> 英文版：`GENERIC_INTEGRATION.md`

---

## 0. 這份 runbook 解決什麼問題

如果你的宿主屬於以下任一情境，請優先看這份：

- 你沒有 `force-recall` hook。
- 你有自己的 planner / preflight / orchestrator。
- 你想手動把 approved-plan 狀態餵給 continuity plugin。
- 你需要一份「最少要給哪些欄位」的 payload 規格。
- 你需要知道如何驗證 continuity block 有真的擋住錯誤結案，而不是只是在文件裡說可以。

一句話總結：

**沒有 `force-recall` 也能裝 continuity plugin，但你必須自己提供 generic continuity input，並把回傳的 block 接進 agent prompt。**

---

## 1. 最小安裝目標

安裝完成後，至少要達到以下結果：

- 你的 host 能 import `plugins/continuity/src/index.mjs`
- 你的 host 能呼叫：
  - `runGenericPreflightContinuityAdapter(...)`，或
  - `runManualContinuityPreflight(...)`
- 你的 host 能把回傳的 `out.block` prepend 到 agent 會看到的 prompt/body
- 當任務完成、但還有下一步且沒有真實 dispatch receipt 時，continuity gate 會擋住「直接結案」
- `cd plugins/continuity && npm test` 可通過

---

## 2. 安裝位置與檔案

建議放在：

```text
<workspace>/plugins/continuity
```

generic/manual 路徑至少需要這些檔案：

```text
plugins/continuity/
  package.json
  src/index.mjs
  src/adapters/generic-preflight.mjs
  src/config/defaults.mjs
  src/config/schema.mjs
  src/continuity/engine.mjs
  src/continuity/evaluator.mjs
  src/continuity/receipt-validator.mjs
  src/continuity/receipt-store.mjs
  src/continuity/types.md
  examples/openclaw.continuity.example.json
  examples/approved-plan-receipt.example.json
  README.zh-TW.md
  README.md
  GENERIC_INTEGRATION.zh-TW.md
```

可先用這個命令確認：

```bash
cd <workspace>
find plugins/continuity -maxdepth 3 -type f | sort
```

---

## 3. generic/manual 路徑會用到哪些 API

`src/index.mjs` 已經 re-export 這幾個你最需要的 API：

- `defaultConfig`
- `normalizeContinuityConfig()`
- `validateContinuityConfig()`
- `buildGenericContinuityInput()`
- `createGenericPreflightContinuityAdapter()`
- `runGenericPreflightContinuityAdapter()`
- `runManualContinuityPreflight()`
- `validateReceipt()`
- `isValidReceipt()`
- `writeReceipt()`

如果你只想最短路徑完成整合，通常會直接用：

- `runGenericPreflightContinuityAdapter(...)`
- `runManualContinuityPreflight(...)`
- `writeReceipt(...)`

---

## 4. continuity input 最小 contract

generic adapter 吃的是 **host-agnostic continuity input**。

依 `src/continuity/types.md`，實務上最少要準備：

- `planId`: string
- `currentTask`: string
- `taskState`: string | null
- `nextDerivedAction`: object | null
- `replyClosureState`: string | null
- `dispatchReceipt`: object | null
- `nextTaskKnown`: boolean
- `sameApprovedPlan`: boolean
- `taskBoundaryStop`: boolean
- `highRiskStop`: boolean

可選欄位：

- `nextTaskId`: string | null
- `nextTaskKey`: string | null
- `derivedAction`: object | null
- `metadata`: object

### 最小可運作 payload 範例

```js
const source = {
  planId: 'approved-plan-1',
  currentTask: 'task-3',
  taskState: 'complete',
  nextTaskKnown: true,
  sameApprovedPlan: true,
  taskBoundaryStop: true,
  highRiskStop: false,
  nextTaskId: 'task-4',
  nextDerivedAction: {
    type: 'message_subagent',
    task: 'continue with task-4',
  },
  replyClosureState: 'completed',
  dispatchReceipt: null,
  metadata: {
    host: 'custom-orchestrator',
  },
};
```

### 什麼情況下這個 payload 會觸發 gate？

常見高風險情境：

- `taskState = 'complete'`
- `nextTaskKnown = true`
- `sameApprovedPlan = true`
- `nextDerivedAction != null`
- `dispatchReceipt = null`
- `replyClosureState = 'completed'`

這類情況通常代表：**目前 task 做完了、下一步也知道了，但你還沒有真實派發 receipt，卻準備把整件事收掉。**

這正是 continuity gate 要攔的核心情境。

---

## 5. generic adapter 接法

### 最小接法

```js
import plugin from './plugins/continuity/src/index.mjs';

const out = plugin.runGenericPreflightContinuityAdapter({
  config: plugin.defaultConfig,
  source,
});

if (out?.block) {
  agentPromptBody = `${out.block}\n${agentPromptBody}`;
}
```

### 回傳值你至少要看哪些欄位

`out` 常用欄位：

- `out.input`
- `out.result`
- `out.evaluation`
- `out.block`
- `out.meta.adapterName`
- `out.meta.hostAgnostic`

### 什麼時候不該忽略 `out.block`

只要 `out.block` 非空，就表示 plugin 產生了應注入 prompt 的 continuity gate block。

**不要只把 `evaluation` 印 log，就算整合完成。**

真正有完成整合的最低標準，是：

- 有拿到 `out.block`
- 有把它接到 agent prompt/body
- agent 後續真的會看到該 block

---

## 6. manual runner 接法

如果你沒有完整 generic source builder，或者只想先做一次單點 preflight 驗證，可用 manual runner：

```js
import plugin from './plugins/continuity/src/index.mjs';

const out = plugin.runManualContinuityPreflight({
  config: plugin.defaultConfig,
  planId: 'approved-plan-1',
  currentTask: 'task-3',
  taskState: 'complete',
  nextDerivedAction: {
    type: 'message_subagent',
    task: 'continue with task-4',
  },
  replyClosureState: 'completed',
  nextTaskKnown: true,
  sameApprovedPlan: true,
  taskBoundaryStop: true,
  dispatchReceipt: null,
});

if (out?.block) {
  agentPromptBody = `${out.block}\n${agentPromptBody}`;
}
```

### manual runner 適合什麼情況

- 你還沒有完整 planner，但想先驗證 gate 行為
- 你要做 integration smoke test
- 你在 migration 階段，先用手動欄位對接舊宿主

### manual runner 不代表可以跳過正式整合

manual runner 比較像 **preflight harness**，不是完整 host integration 的替代品。

等你確認行為正確後，仍建議回到 generic adapter，把 host 真實資料映射進 source。

---

## 7. 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"
    },
    "genericPreflight": {
      "enabled": true,
      "injectBlockLabel": "APPROVED_PLAN_CONTINUITY_GATE"
    }
  }
}
```

### generic/manual 路徑先檢查這些欄位

- [ ] `enabled = true`
- [ ] `planMatchers` 符合你的 approved plan 名稱
- [ ] `legalTerminalStates` 符合你的 closure policy
- [ ] `receiptDir` 可寫
- [ ] `requireRealDispatchReceipt = true`（通常建議保持）
- [ ] `allowReplyClosureWithoutDispatch = false`（通常建議保持）
- [ ] `adapter.genericPreflight.enabled = true`
- [ ] `adapter.genericPreflight.injectBlockLabel` 有你想要的 label

---

## 8. receipt 怎麼提供

如果你的宿主真的有派發下一步，不要只在 metadata 或 log 裡寫「已派發」，請提供真實 `dispatchReceipt`。

### 最小 receipt shape

依目前 validator，至少要有：

- `planId`
- `currentTask`
- `nextDerivedAction`
- `dispatchedAt`
- `dispatchRunId`
- `childSessionKey`
- `replyClosureState`

對照範例：

```text
plugins/continuity/examples/approved-plan-receipt.example.json
```

範例內容：

```json
{
  "planId": "example-plan",
  "currentTask": "task-01",
  "nextDerivedAction": {
    "kind": "delegate",
    "target": "subagent",
    "task": "placeholder"
  },
  "dispatchedAt": "2026-04-24T16:43:00+08:00",
  "dispatchRunId": "example-run",
  "childSessionKey": "session-placeholder",
  "replyClosureState": "pending_verification"
}
```

### 寫 receipt 前先驗證

```js
import plugin from './plugins/continuity/src/index.mjs';

const receiptValidation = plugin.validateReceipt(receipt);
if (!receiptValidation.ok) {
  throw new Error(`Invalid continuity receipt: ${receiptValidation.errors.join('; ')}`);
}
```

### 寫 receipt 範例

```js
await plugin.writeReceipt({
  receiptDir: 'state/approved-plan-continuity',
  receipt,
});
```

### receiptDir 先建立

```bash
cd <workspace>
mkdir -p state/approved-plan-continuity
```

---

## 9. manual/generic preflight 驗證流程

這一段是本文件最重要的實作 checklist。

### Case A：應該被 gate 擋下

測這種輸入：

- task 已完成
- 下一步已知
- 同一 approved plan
- 有 nextDerivedAction
- 沒有 dispatchReceipt
- closure 想直接完成

例如：

```js
const out = plugin.runGenericPreflightContinuityAdapter({
  config: plugin.defaultConfig,
  source: {
    planId: 'approved-plan-1',
    currentTask: 'task-3',
    taskState: 'complete',
    nextTaskKnown: true,
    sameApprovedPlan: true,
    taskBoundaryStop: true,
    nextTaskId: 'task-4',
    nextDerivedAction: { type: 'message_subagent', task: 'continue' },
    replyClosureState: 'completed',
    dispatchReceipt: null,
  },
});
```

你應該預期：

- `out.block` 非空
- `out.evaluation` 顯示這不是可安全直接結案的狀態
- agent prompt 若接上此 block，應被提醒不可把整件事直接收掉

### Case B：有合法 terminal state，不應誤擋

例如：

- `replyClosureState = 'waiting_user'`
- 或 `blocked`
- 或 `pending_verification`

你應該預期：

- 不會把合法等待/阻塞/待驗證情境誤當成錯誤結案

### Case C：有真實 receipt，應與 dry-run 區分

把 `dispatchReceipt` 換成合法 receipt object，再重跑一次。

你要確認：

- plugin 有辨識 receipt
- 行為和 `dispatchReceipt = null` 時不同
- 不是只因為 `nextDerivedAction` 存在，就一律當成已派發

---

## 10. 如何驗證 continuity block 真的有被接進 prompt

這一步很常被忽略，但它才是整合成功與否的分水嶺。

### 最低驗證標準

你至少要證明以下三件事：

1. plugin 有回傳 `out.block`
2. host 有把 `out.block` prepend 到 agent prompt/body
3. 最終 agent 真正看到的 prompt 中，存在：

```text
[APPROVED_PLAN_CONTINUITY_GATE]
```

### 建議做法

- 在 preflight / orchestrator 測試輸出中印出最終 prompt 前段
- 或在 debug mode 下 dump prompt body
- 或加一個 integration smoke test，直接 assert block label 存在

### 不能只驗證什麼

以下都 **不夠**：

- 只看到 `out.evaluation`
- 只看到 console log 說有 run adapter
- 只看到 code 裡有 prepend 那一行，但沒有實際驗證 prompt 結果

---

## 11. 建議 smoke test 順序

### Step 1：plugin 本體測試

```bash
cd <workspace>/plugins/continuity
npm test
```

### Step 2：快速 smoke

```bash
cd <workspace>/plugins/continuity
node test/continuity.smoke.test.mjs
```

### Step 3：你的 generic/manual host integration test

如果你有自家 orchestrator，請至少補一個 smoke case：

- 無 receipt + 想 completed → 應被 gate
- 合法 terminal state → 不應誤擋
- 有合法 receipt → 行為應與無 receipt 不同

### Step 4：人工檢查 prompt block

確認輸出真的含有：

```text
[APPROVED_PLAN_CONTINUITY_GATE]
```

---

## 12. 宿主實作者最常踩的坑

### 坑 1：只有 planner output，沒有實際 prompt injection

這會讓 continuity 只停在「有計算」，沒有真正影響 agent 行為。

### 坑 2：把 dry-run next action 當成已 dispatch

`nextDerivedAction != null` 不等於 `dispatchReceipt != null`。

### 坑 3：payload 缺少 `planId` 或 `currentTask`

`buildGenericContinuityInput()` 若拿不到這些關鍵欄位，可能直接回不出有效 input。

### 坑 4：把合法 terminal state 設定錯

例如你宿主其實接受 `waiting_user`，但 config 沒放進 `legalTerminalStates`，就可能造成誤判。

### 坑 5：receipt 寫檔了，但內容不合法

先 `validateReceipt()`，不要跳過。

### 坑 6：只測 happy path

至少要測：

- 應 fail 的情況
- 應 pass / 不誤擋的情況
- 有 receipt 與無 receipt 的差異

---

## 13. 一頁版 generic/manual checklist

### 安裝

- [ ] 複製 `plugins/continuity` 到 workspace
- [ ] 確認 `src/index.mjs` 可 import
- [ ] 建立 `state/approved-plan-continuity/`

### config

- [ ] 套用 example config
- [ ] 開啟 `adapter.genericPreflight.enabled`
- [ ] 確認 `receiptDir` 可寫

### host 接法

- [ ] 準備 generic continuity payload
- [ ] 呼叫 `runGenericPreflightContinuityAdapter(...)` 或 `runManualContinuityPreflight(...)`
- [ ] 將 `out.block` prepend 到 agent prompt/body

### receipt

- [ ] 真有派發時才產生 receipt
- [ ] 先 `validateReceipt()`
- [ ] 再 `writeReceipt()`

### 驗證

- [ ] `cd plugins/continuity && npm test`
- [ ] 驗證無 receipt 時會擋錯誤結案
- [ ] 驗證合法 terminal state 不誤擋
- [ ] 驗證最終 prompt 含 continuity block

---

## 14. 什麼叫 generic/manual 整合完成

只有在以下條件都成立時，才算真的完成：

- 不是只完成 plugin 安裝，而是 host 真的有呼叫 adapter
- 不是只拿到 evaluation，而是 block 真的有注入 agent prompt
- 不是只做 dry-run，而是實際 dispatch 時可提供真實 receipt
- 不是只測 happy path，而是有驗證 gate fail/pass 的差異
- 文件足夠讓陌生宿主實作者知道自己要準備哪些欄位、怎麼驗證

如果這五點都做到，才算接近「沒有 `force-recall` 的宿主也能照文件安裝」。

---

## 15. 參考文件

- `plugins/continuity/README.zh-TW.md`
- `plugins/continuity/README.md`
- `plugins/continuity/AGENT_GUIDE.zh-TW.md`
- `plugins/continuity/AGENT_GUIDE.md`
- `plugins/continuity/src/continuity/types.md`
- `plugins/continuity/examples/openclaw.continuity.example.json`
- `plugins/continuity/examples/approved-plan-receipt.example.json`

如果你的宿主未來會新增專屬 adapter，也建議保留這份 generic/manual runbook，作為最低整合基準。