approved-plan-continuity-hard-gate/plugins/continuity/README.zh-TW.md

# Continuity Plugin（MVP）

> English version: `README.md`

這個套件把目前 approved-plan continuity hard gate 抽離成一個可安裝、可測試、可在 hook 內重用的 OpenClaw plugin MVP。

目標不是重新發明規則，而是把既有 continuity 判斷、receipt contract、force-recall adapter 收斂成一個可以被其他 OpenClaw workspace 直接帶走的最小可用包。

## 目前能做什麼

- 驗證 continuity config
- 驗證 dispatch receipt contract
- 寫出 receipt 檔案
- 評估 approved-plan continuity gate
- 產生可注入 prompt 的 continuity gate block
- 透過 `force-recall` adapter，把 hook 端的 wrapper/planner 結果轉成 continuity input

## 安裝位置

建議直接放在 OpenClaw workspace 內：

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

以目前 MVP 慣例，相關檔案位置如下：

```text
<workspace>/
  hooks/
    force-recall/
      handler.ts
      HOOK.md
  plugins/
    continuity/
      README.zh-TW.md
      README.md
      HOOK.md
      package.json
      examples/
      src/
      test/
  scripts/
    test_force_recall_long_task_preflight.mjs
```

## 目錄結構

```text
plugins/continuity/
  README.zh-TW.md
  README.md
  HOOK.md
  package.json
  examples/
    approved-plan-receipt.example.json
    openclaw.continuity.example.json
  src/
    index.mjs
    adapters/
      force-recall.mjs
    config/
      defaults.mjs
      schema.mjs
    continuity/
      evaluator.mjs
      receipt-store.mjs
      receipt-validator.mjs
      types.md
  test/
    continuity.config.test.mjs
    continuity.evaluator.test.mjs
    continuity.plugin.test.mjs
    continuity.receipt-store.test.mjs
    continuity.receipt-validator.test.mjs
    continuity.smoke.test.mjs
```

## 公開介面

- `src/config/schema.mjs`
- `src/config/defaults.mjs`
- `src/continuity/evaluator.mjs`
- `src/continuity/receipt-validator.mjs`
- `src/continuity/receipt-store.mjs`
- `src/adapters/force-recall.mjs`
- `src/index.mjs`

`src/index.mjs` 目前會 re-export：

- `defaultConfig`
- `cloneDefaultConfig()`
- `validateContinuityConfig()` / `normalizeContinuityConfig()`
- `evaluateContinuity()` / `buildContinuityGateBlock()`
- `validateReceipt()` / `isValidReceipt()`
- `slugifyReceiptSegment()` / `buildReceiptFilename()` / `writeReceipt()`
- `buildApprovedPlanContinuityInput()`
- `createForceRecallContinuityAdapter()` / `runForceRecallContinuityAdapter()`

## Example config

請從 `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"
    }
  }
}
```

預設值定義在 `src/config/defaults.mjs`。

## Hook 接法

MVP 的主要整合點是 `hooks/force-recall/handler.ts`。

目前 hook 端做法是：

1. 先完成 long-task preflight / gate lock / auto-chain planner
2. 再動態載入 `plugins/continuity/src/index.mjs`
3. 呼叫 `runForceRecallContinuityAdapter({ wrapperResult, autoChainPlanResult, config })`
4. 把 adapter 產出的 block 注入 `bodyForAgent`

`handler.ts` 內已有 plugin 路徑接點，關鍵符號是：

- `runForceRecallContinuityAdapter`
- `[APPROVED_PLAN_CONTINUITY_GATE]`

最小接法示意：

```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}`;
}
```

若要覆蓋 block label，可改 `adapter.forceRecall.injectBlockLabel`。

## Receipt contract

最小 receipt shape 如下：

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

範例可參考 `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 { writeReceipt } from './src/index.mjs';

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

## Smoke test / 驗證

至少執行以下驗證：

```bash
cd plugins/continuity
npm test

cd /path/to/workspace
node scripts/test_force_recall_long_task_preflight.mjs
node --check hooks/force-recall/handler.ts
```

若只想先做 plugin 本體最小檢查，也可以：

```bash
cd plugins/continuity
node test/continuity.smoke.test.mjs
```

## 安裝與套用步驟（給其他 OpenClaw 使用者）

1. 把 `plugins/continuity` 複製到你的 workspace。
2. 確認 `hooks/force-recall/handler.ts` 會載入 `plugins/continuity/src/index.mjs`。
3. 視需要調整 continuity config，至少確認：
   - `planMatchers`
   - `legalTerminalStates`
   - `receiptDir`
   - `adapter.forceRecall.injectBlockLabel`
4. 若你的 dispatch 流程會產生 child run/session，請同步寫出 receipt。
5. 跑 smoke test 與 hook preflight 測試。
6. 確認 agent prompt 內可見 continuity gate block，且 dry-run dispatch 不會被誤判為 pass。

## 目前限制

- 目前是 **approved-plan continuity hard gate** 的 MVP 抽離，不是通用 workflow engine。
- 主要 adapter 只有 `force-recall`，尚未抽象成多 hook / 多事件通用介面。
- config 目前是模組內預設 + 呼叫端傳入，還沒有完整的 OpenClaw plugin 安裝器/註冊流程文件。
- receipt store 只負責寫檔，不含 retention、cleanup、indexing。
- receipt validator 目前只檢查最小 contract，不驗證每個 `nextDerivedAction` 子欄位語意。
- 文件描述的是「依現有 hook 整合」的安裝方式；若未採用 `force-recall` preflight 鏈，仍需自行補 glue code。

## 備註

- 預設 legal terminal states：`waiting_user`、`blocked`、`pending_verification`
- evaluator 保留既有行為，包括 `missing_dispatch_receipt` 與 `missing_auto_next_dispatch`
- adapter 維持與 `hooks/force-recall/handler.ts` 的 continuity input mapping 一致
- `HOOK.md` 說明的是 plugin/hook adapter 契約定位，不是完整安裝說明

## 英文文件

英文版請見 `README.md`。