From 0c21910ae5a5bce3b93a6de98e384f1644e4a1e7 Mon Sep 17 00:00:00 2001
From: Eve <eve@ai.cowbay.org>
Date: Fri, 24 Apr 2026 19:41:57 +0800
Subject: [PATCH] docs(continuity): clarify generic host adapter paths

---
 plugins/continuity/AGENT_GUIDE.zh-TW.md       | 76 ++++++++++++++-----
 plugins/continuity/HOOK.md                    | 33 ++++++--
 .../examples/openclaw.continuity.example.json |  4 +
 plugins/continuity/package.json               |  2 +-
 4 files changed, 87 insertions(+), 28 deletions(-)

diff --git a/plugins/continuity/AGENT_GUIDE.zh-TW.md b/plugins/continuity/AGENT_GUIDE.zh-TW.md
index 3e7de8a..2628fb8 100644
--- a/plugins/continuity/AGENT_GUIDE.zh-TW.md
+++ b/plugins/continuity/AGENT_GUIDE.zh-TW.md
@@ -16,6 +16,7 @@
 - 你需要 agent 在同一個 approved plan 內，判斷是否還有 **下一個要派發的 task**。
 - 你需要用 **dispatch receipt** 證明「真的有派出下一步」，而不是只在回覆裡口頭說會繼續。
 - 你已經在用 `hooks/force-recall/handler.ts`，希望把 approved-plan continuity gate 注入 agent prompt。
+- 你沒有 `force-recall` hook，但有自己的 preflight / planner / orchestrator，想直接呼叫通用 continuity adapter。
 
 ### 可先不裝的情況
 
@@ -23,7 +24,7 @@
 
 - 你的 workspace 沒有 approved-plan / auto-chain / dispatch 這類流程。
 - 你只需要一般單回合聊天，不需要 continuity hard gate。
-- 你沒有 `force-recall` hook，也暫時不打算自己補 glue code。
+- 你沒有 `force-recall` hook，且也不打算在自己的 host / orchestrator 補 generic glue code。
 
 ---
 
@@ -31,11 +32,11 @@
 
 安裝完成後，應達到這個最小結果：
 
-- `hooks/force-recall/handler.ts` 能載入 `plugins/continuity/src/index.mjs`
-- hook 在 preflight 時會呼叫 `runForceRecallContinuityAdapter(...)`
+- 你的 host（例如 `force-recall` hook 或自家 preflight）能載入 `plugins/continuity/src/index.mjs`
+- host 在 preflight 時會呼叫 `runForceRecallContinuityAdapter(...)`、`runGenericPreflightContinuityAdapter(...)` 或 `runManualContinuityPreflight(...)` 其中之一
 - agent prompt 內可看到 `[APPROVED_PLAN_CONTINUITY_GATE] ... [/APPROVED_PLAN_CONTINUITY_GATE]`
 - 當 approved plan 任務完成，但沒有真實下一步 dispatch receipt 時，gate 會擋下錯誤結案
-- plugin 自身測試與 hook smoke test 可通過
+- plugin 自身測試與對應 host smoke test 可通過
 
 ---
 
@@ -49,7 +50,7 @@
 <workspace>/plugins/continuity
 ```
 
-以目前 MVP 的預期 layout：
+建議 layout（可依宿主調整）：
 
 ```text
 <workspace>/
@@ -86,7 +87,7 @@
 - [ ] 你的 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
+- [ ] 你接受目前 `force-recall` 是最成熟 adapter，但不是唯一宿主
 - [ ] 你知道 receipt 只是「最小 contract」，不是完整 workflow engine
 
 可先用以下命令確認：
@@ -275,11 +276,11 @@ mkdir -p state/approved-plan-continuity
 
 ---
 
-## 7. 如何接 `force-recall` hook
+## 7. 如何接 host / hook（`force-recall` 只是其中一種）
 
 ## 7.1 你要確認的整合點
 
-MVP 的主要整合點是：
+目前最成熟的整合點仍是：
 
 ```text
 hooks/force-recall/handler.ts
@@ -309,9 +310,9 @@ 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 最小接法範例
+## 7.2 最小接法範例（force-recall）
 
-如果你要自己補接，最小概念如下：
+如果你走既有 `force-recall` 路徑，最小概念如下：
 
 ```js
 import plugin from './plugins/continuity/src/index.mjs';
@@ -327,7 +328,44 @@ if (out?.block) {
 }
 ```
 
-## 7.3 實作者要檢查的實際條件
+## 7.3 Generic/manual 最小接法範例
+
+如果你沒有 `force-recall`，也可直接把自己的 preflight 結果餵給 generic adapter：
+
+```js
+import plugin from './plugins/continuity/src/index.mjs';
+
+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,
+  },
+});
+```
+
+若你只是手動做一次 continuity preflight，也可直接呼叫：
+
+```js
+const out = plugin.runManualContinuityPreflight({
+  config: plugin.defaultConfig,
+  planId: 'approved-plan-1',
+  currentTask: 'task-3',
+  taskState: 'complete',
+  nextDerivedAction: { type: 'message_subagent', task: 'continue' },
+  replyClosureState: 'waiting_user',
+});
+```
+
+## 7.4 實作者要檢查的實際條件
 
 - [ ] hook 能動態 import `plugins/continuity/src/index.mjs`
 - [ ] `runForceRecallContinuityAdapter` 是 function
@@ -337,7 +375,7 @@ if (out?.block) {
 - [ ] `out.block` 非空時有 prepend 到 `bodyForAgent`
 - [ ] agent prompt 最終可見 continuity gate block
 
-## 7.4 receipt 與 continuity input 的關係
+## 7.5 receipt 與 continuity input 的關係
 
 如果你的流程真的有派發下一步，請不要只在字串裡描述「已派發」，而要產出真實 `dispatchReceipt`。
 
@@ -360,14 +398,14 @@ if (out?.block) {
 ### Checklist：第一次把 plugin 接進現有 workspace
 
 - [ ] 建立 / 複製 `plugins/continuity`
-- [ ] 確認 `src/index.mjs` 可被 hook 載入
+- [ ] 確認 `src/index.mjs` 可被 host 載入
 - [ ] 確認 continuity example config 可讀
 - [ ] 建立 `state/approved-plan-continuity/`
-- [ ] 確認 `hooks/force-recall/handler.ts` 有 continuity adapter 接點
-- [ ] 確認有 prepend continuity block 到 `bodyForAgent`
+- [ ] 確認你的 host（例如 `hooks/force-recall/handler.ts` 或自家 preflight）有 continuity adapter 接點
+- [ ] 確認有 prepend continuity block 到 `bodyForAgent` 或對應 prompt/body
 - [ ] 若 dispatch 真的發生，補上 receipt 寫檔
 - [ ] 跑 plugin test
-- [ ] 跑 force-recall smoke test
+- [ ] 跑對應 host 的 smoke test
 - [ ] 檢查 injected prompt block 是否存在
 
 ### Checklist：第一次加 receipt 落盤
@@ -553,11 +591,11 @@ find state/approved-plan-continuity -maxdepth 2 -type f | sort
 
 ## 13. 目前限制
 
-這個 MVP 目前有以下限制，安裝前要先接受：
+這個 plugin 目前有以下限制，安裝前要先接受：
 
 - 它是 **approved-plan continuity hard gate** 的抽離版，不是通用 workflow engine。
-- 主要 adapter 目前只有 `force-recall`。
-- 文件描述的是「接在既有 force-recall preflight 鏈上」的路徑；若你的 workspace 沒這條鏈，仍要自己補 glue code。
+- `force-recall` 是目前最成熟的 adapter，但不是唯一 adapter。
+- 若你的 workspace 沒有 `force-recall`，仍需自己把 host 資料接到 generic/manual path。
 - config 目前是模組預設值 + 呼叫端傳入，不是完整 plugin installer / registry 流程。
 - receipt store 目前只負責寫檔，不管 retention、cleanup、indexing。
 - receipt validator 目前只驗證最小 contract，不會深入驗證每種 `nextDerivedAction` 的完整語意。
diff --git a/plugins/continuity/HOOK.md b/plugins/continuity/HOOK.md
index b0646db..85b81f7 100644
--- a/plugins/continuity/HOOK.md
+++ b/plugins/continuity/HOOK.md
@@ -1,20 +1,37 @@
 # HOOK.md
 
-This document reserves the hook adapter contract for the continuity plugin MVP.
+This document defines the hook/host adapter boundary for the continuity plugin.
 
-## Target adapter
+## Target adapters
 
-Primary MVP integration target:
+Current supported adapter paths:
 
 - `force-recall`
+- `generic-preflight`
 
-## Planned responsibilities
+`force-recall` is the current primary OpenClaw integration path, but it is not the only intended host.
 
-- derive continuity input from hook context
-- invoke the plugin evaluator
+## Adapter responsibilities
+
+Adapters should:
+
+- derive or normalize continuity input from host context
+- invoke the shared continuity evaluator/engine
 - return a prompt block / gate result without duplicating continuity rules
+- keep host-specific parsing outside the core evaluator
+
+## Contract boundary
+
+The host-facing contract lives in the plugin engine and adapter exports:
+
+- `normalizeContinuityEngineInput()`
+- `createContinuityEngineContract()`
+- `runForceRecallContinuityAdapter()`
+- `runGenericPreflightContinuityAdapter()`
+- `runManualContinuityPreflight()`
 
 ## Current status
 
-- contract placeholder only
-- implementation deferred to later plan tasks
+- `force-recall` adapter: implemented and parity-oriented
+- `generic-preflight` adapter: implemented for host-agnostic/manual preflight integration
+- full installer/registry integration: intentionally out of scope for this package
diff --git a/plugins/continuity/examples/openclaw.continuity.example.json b/plugins/continuity/examples/openclaw.continuity.example.json
index 4ab8db8..40db2fc 100644
--- a/plugins/continuity/examples/openclaw.continuity.example.json
+++ b/plugins/continuity/examples/openclaw.continuity.example.json
@@ -16,6 +16,10 @@
     "forceRecall": {
       "enabled": true,
       "injectBlockLabel": "APPROVED_PLAN_CONTINUITY_GATE"
+    },
+    "genericPreflight": {
+      "enabled": true,
+      "injectBlockLabel": "APPROVED_PLAN_CONTINUITY_GATE"
     }
   }
 }
diff --git a/plugins/continuity/package.json b/plugins/continuity/package.json
index e9a0e01..b6a0656 100644
--- a/plugins/continuity/package.json
+++ b/plugins/continuity/package.json
@@ -3,7 +3,7 @@
   "version": "0.1.0",
   "private": true,
   "type": "module",
-  "description": "Continuity plugin MVP skeleton for approved-plan dispatch gating.",
+  "description": "Continuity plugin for approved-plan dispatch gating with a minimal host-agnostic engine and adapters.",
   "exports": {
     ".": "./src/index.mjs"
   },