openclaw/approved-plan-continuity-hard-gate

Fork 0

Files

openclaw@cowbay.org 7d62b1b84e feat: export continuity plugin MVP packaging

2026-04-24 17:33:01 +08:00

6.5 KiB

Raw Blame History

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 內：

<workspace>/plugins/continuity

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

<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

目錄結構

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 開始：

{
  "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 端做法是：

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

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

runForceRecallContinuityAdapter
[APPROVED_PLAN_CONTINUITY_GATE]

最小接法示意：

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：

{
  "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 落盤，可用：

import { writeReceipt } from './src/index.mjs';

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

Smoke test / 驗證

至少執行以下驗證：

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 本體最小檢查，也可以：

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

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

把 plugins/continuity 複製到你的 workspace。
確認 hooks/force-recall/handler.ts 會載入 plugins/continuity/src/index.mjs。
視需要調整 continuity config，至少確認：
- planMatchers
- legalTerminalStates
- receiptDir
- adapter.forceRecall.injectBlockLabel
若你的 dispatch 流程會產生 child run/session，請同步寫出 receipt。
跑 smoke test 與 hook preflight 測試。
確認 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。

6.5 KiB Raw Blame History Unescape Escape