@xgjktech/xg-openclaw-harness-tools 0.4.0 → 0.4.1

package/README.md

@@ -1,148 +1,148 @@
-# @xgjktech/xg-openclaw-harness-tools
-
-OpenClaw 第三方工具插件：企业计划工具 `xg_plan_write` / `xg_plan_view`。
-
-用一份持久化的计划（SQLite 落盘）取代内置 `update_plan`（无状态、只回显、不落库），
-`xg_plan_write` 整张维护草稿计划，`xg_plan_view` 只读查看计划或最近摘要。
-
-## 架构裁决：实时事件当前处于事实性休眠（务必先读）
-
-**当前 OpenClaw 2026.6.10 版本下，实时事件推送链路休眠**：工具 execute/factory 期没有
-正当途径获取真实 runId（详见 `docs/notes-plugin-entry.md` N2），且 0.3.0 已移除工具侧
-`notify.ts`。`xg_plan_write` 落库后不发事件，`xg_plan_view` 全程只读。
-
-**因此 IM 侧（或任何下游消费方）不得依赖实时事件感知计划进度。** 当前唯一可靠的主感知路径是：
-
-1. **SQLite 读取**——IM 用 `openPlanStoreReadonly(dbPath)` 按 origin 只读反查
-   `<stateDir>/xgjktech/plans.sqlite` 并推送全量快照，这是权威状态源。
-2. **agent 最终回复**——agent 完成任务后的文本回复本身会体现进度。
-
-事件契约（`PlanEventPayload` / `isPlanEventPayload` / `planEventStream`）在 shared 中原样保留，
-仅用于下游编译兼容。未来恢复实时事件需要重新实现工具侧生产与 IM 侧消费，并单独发布。
-
-## 环境要求
-
-- **Node ≥ 22.19.0**（依赖 `node:sqlite`，与 OpenClaw 自身 `engines` 一致）。
-- monorepo 用 npm workspaces。
-
-## 安装与构建
-
-本仓库是包含 `@xgjktech/xg-openclaw-shared`（存储层+事件契约层）和
-`@xgjktech/xg-openclaw-harness-tools`（本插件）两个 workspace 的 monorepo。**`xg-shared` 必须先于
-本插件构建**（本插件依赖它的编译产物）；npm workspaces 拓扑已保证顺序，直接在仓库根执行：
-
-```bash
-npm install
-npm run build
-```
-
-产物：`packages/xg-harness-tools/dist/`（含 `index.js` 与 `.d.ts`）。
-
-将本插件安装到 OpenClaw 的具体命令/目录约定，请对照 OpenClaw 的第三方插件安装机制
-（global / workspace / config origin，本插件按非 bundled 第三方路径运行）以及
-`package.json` 里的 `openclaw.*` 字段块（`extensions`/`install.localPath` 等）。
-P1 阶段不锁死具体安装命令，避免与实际安装流程漂移（详见 `docs/05-部署文档.md` §3.3）。
-
-## 配置
-
-### 1. 屏蔽内置 update_plan（deny，唯一权威路径）
-
-```jsonc
-{
-  "tools": {
-    "deny": ["update_plan"]
-  }
-}
-```
-
-无论生产 profile / allowlist 取何值（包括 `allow:["*"]`），`deny` 都一票否决，
-与 profile 取值解耦。
-
-### 2. 启用本插件两个工具（allow）
-
-本插件两个工具都以 `optional:true` 注册，**默认不启用**，必须 allowlist 显式命中才会注册：
-
-```jsonc
-{
-  "tools": {
-    "allow": ["xg_plan_write", "xg_plan_view"],
-    "deny": ["update_plan"]
-  }
-}
-```
-
-可直接套用的完整样例见仓库根 [`deploy/tools.config.sample.jsonc`](../../deploy/tools.config.sample.jsonc)（带注释）。
-
-### 3. stateDir 与数据库路径
-
-插件运行时数据库路径固定为：
-
-```
-<stateDir>/xgjktech/plans.sqlite
-```
-
-`stateDir` 取自 OpenClaw 全局状态目录（`api.runtime.state.resolveStateDir()`，默认
-`~/.openclaw/`，`OPENCLAW_STATE_DIR` 覆盖时同步），插件首次运行时通过 `resolvePlanDbPath`
-自动 `mkdir -p` 出 `xgjktech/` 子目录，无需手动创建。IM 插件若要接入同一份数据，应复用
-同一个 `resolvePlanDbPath` 以保证路径约定一致。
-
-## 两个工具说明
-
-### `xg_plan_write`
-
-整张创建或覆盖一份草稿计划（goal + tasks[]）并写入 SQLite。更新时必须重交所有要保留的
-task；写入 schema 不接受 steps，但读取旧计划仍兼容旧 steps 数据。
-
-### `xg_plan_view`
-
-只读查看计划，**不会执行任何任务**。带 planId 返回完整紧凑 view；不带 planId 返回最近 10 条
-计划摘要，用于跨会话找回 planId。更新进度统一使用 `xg_plan_write` 整张重交。
-
-> 工具名用 `view` 而非 `execute` 是有意的：`plan_view`/`plan_write` 都只是台账，不执行、不调度、
-> 无后台运行。二者 description 均明确"保存/查看 ≠ 执行"，且结果带 `reminder` 字段引导模型
-> 继续逐项实际执行任务——避免模型调用计划工具后误以为工作已在后台完成而停住。
-
-两个工具的完整参数 schema 见 `src/plan-write-tool.ts` / `src/plan-view-tool.ts`
-中的 `PLAN_WRITE_DESCRIPTION` / `PLAN_VIEW_DESCRIPTION`。
-
-## 部署 checklist
-
-- [ ] Node ≥ 22.19.0
-- [ ] monorepo 构建成功（`xg-shared` 先于本插件构建，workspaces 拓扑自动保证）
-- [ ] 插件已安装且被 OpenClaw 识别为已加载的第三方插件（非 bundled）
-- [ ] `tools.deny` 含 `update_plan`
-- [ ] `tools.allow` 含 `xg_plan_write` + `xg_plan_view`（或经 `group:plugins` / `*` 放行）
-- [ ] 实拉一个 agent，验证工具清单**有本插件两工具、无 update_plan**（步骤见下节）
-- [ ] `<stateDir>/xgjktech/` 可写，首次运行能生成 `plans.sqlite`
-- [ ] （互通）IM 侧已依赖 `@xgjktech/xg-openclaw-shared` 并按 `docs/04-互通设计.md` 接入只读反查
-
-## 实机验证步骤（可复现）+ 当前实际执行情况说明
-
-**验收标准要求部署方按 checklist 实拉一个 agent，确认工具清单里有 `xg_plan_write`/
-`xg_plan_view`、没有 `update_plan`。以下是可复现的验证步骤：**
-
-1. 按上文"配置"章节把 `tools.deny`/`tools.allow` 写入生产 agent/profile 配置。
-2. 安装并加载本插件（确认加载日志/插件列表里出现 `xg-harness-tools`，origin 为第三方非 bundled）。
-3. 拉起一个真实 agent 会话，触发一次会列出可用工具的动作（例如让 agent 描述自己有哪些工具，
-   或查看 gateway/日志里该次 attempt 实际注册的工具名列表）。
-4. 核对该工具列表：应包含 `xg_plan_write` 与 `xg_plan_view`，**不应包含** `update_plan`。
-5. 调用一次 `xg_plan_write` 建一份最小计划，确认返回 `planId + view`；再用该 planId 调
-   `xg_plan_view`，确认只读 view 一致。用 `openPlanStoreReadonly` 反查并核对落盘内容。
-
-**本项在本次交付中未在真实 OpenClaw gateway 环境实机执行**——本仓库当前开发环境没有可用的
-真实 OpenClaw gateway/agent 运行环境，因此无法诚实地报告"已实拉 agent 验证通过"。以下是
-已经做过、可以作为间接佐证的验证，但**明确说明这不等于实机验证**：
-
-- 当前 factory 集成测试用**手工构造的 mock `api`**捕获 2 个工具的注册工厂，并提供带
-  `sessionKey`/`deliveryContext` 的 `toolContext`：`xg_plan_write` 写入后通过只读存储反查
-  `origin`，`xg_plan_view` 校验指定计划的 view 与最近计划列表。**这验证的是插件代码本身
-  可以被正确加载、注册并贯通当前契约**，但 mock `api` 不是真实 OpenClaw gateway 的
-  `tools.allow`/`deny` 策略引擎，**不能**佐证"生产 deny/allow 配置生效后工具清单精确符合
-  预期"这一条——那一条必须在真实 gateway 环境按上面 5 步实测。
-- T6 阶段（`packages/xg-harness-tools/src/integration.test.ts`）用真实的 `SqlitePlanStore`
-  （临时目录）+ 真实工具函数（`buildPlanWriteTool`/`buildPlanViewTool`）跑通了完整的
-  写入→整张重交→execute 只读查看→SQLite 只读反查链路，但同样不经过 OpenClaw 的工具
-  allowlist/deny 策略引擎。
-
-**结论：部署方在生产环境落实上述配置后，必须按"实机验证步骤"重新执行一次实拉 agent 验证，
-不能以本仓库现有的 mock/集成测试结果代替。**
+# @xgjktech/xg-openclaw-harness-tools
+
+OpenClaw 第三方工具插件：企业计划工具 `xg_plan_write` / `xg_plan_view`。
+
+用一份持久化的计划（SQLite 落盘）取代内置 `update_plan`（无状态、只回显、不落库），
+`xg_plan_write` 整张维护草稿计划，`xg_plan_view` 只读查看计划或最近摘要。
+
+## 架构裁决：实时事件当前处于事实性休眠（务必先读）
+
+**当前 OpenClaw 2026.6.10 版本下，实时事件推送链路休眠**：工具 execute/factory 期没有
+正当途径获取真实 runId（详见 `docs/notes-plugin-entry.md` N2），且 0.3.0 已移除工具侧
+`notify.ts`。`xg_plan_write` 落库后不发事件，`xg_plan_view` 全程只读。
+
+**因此 IM 侧（或任何下游消费方）不得依赖实时事件感知计划进度。** 当前唯一可靠的主感知路径是：
+
+1. **SQLite 读取**——IM 用 `openPlanStoreReadonly(dbPath)` 按 origin 只读反查
+   `<stateDir>/xgjktech/plans.sqlite` 并推送全量快照，这是权威状态源。
+2. **agent 最终回复**——agent 完成任务后的文本回复本身会体现进度。
+
+事件契约（`PlanEventPayload` / `isPlanEventPayload` / `planEventStream`）在 shared 中原样保留，
+仅用于下游编译兼容。未来恢复实时事件需要重新实现工具侧生产与 IM 侧消费，并单独发布。
+
+## 环境要求
+
+- **Node ≥ 22.19.0**（依赖 `node:sqlite`，与 OpenClaw 自身 `engines` 一致）。
+- monorepo 用 npm workspaces。
+
+## 安装与构建
+
+本仓库是包含 `@xgjktech/xg-openclaw-shared`（存储层+事件契约层）和
+`@xgjktech/xg-openclaw-harness-tools`（本插件）两个 workspace 的 monorepo。**`xg-shared` 必须先于
+本插件构建**（本插件依赖它的编译产物）；npm workspaces 拓扑已保证顺序，直接在仓库根执行：
+
+```bash
+npm install
+npm run build
+```
+
+产物：`packages/xg-harness-tools/dist/`（含 `index.js` 与 `.d.ts`）。
+
+将本插件安装到 OpenClaw 的具体命令/目录约定，请对照 OpenClaw 的第三方插件安装机制
+（global / workspace / config origin，本插件按非 bundled 第三方路径运行）以及
+`package.json` 里的 `openclaw.*` 字段块（`extensions`/`install.localPath` 等）。
+P1 阶段不锁死具体安装命令，避免与实际安装流程漂移（详见 `docs/05-部署文档.md` §3.3）。
+
+## 配置
+
+### 1. 屏蔽内置 update_plan（deny，唯一权威路径）
+
+```jsonc
+{
+  "tools": {
+    "deny": ["update_plan"]
+  }
+}
+```
+
+无论生产 profile / allowlist 取何值（包括 `allow:["*"]`），`deny` 都一票否决，
+与 profile 取值解耦。
+
+### 2. 启用本插件两个工具（allow）
+
+本插件两个工具都以 `optional:true` 注册，**默认不启用**，必须 allowlist 显式命中才会注册：
+
+```jsonc
+{
+  "tools": {
+    "allow": ["xg_plan_write", "xg_plan_view"],
+    "deny": ["update_plan"]
+  }
+}
+```
+
+可直接套用的完整样例见仓库根 [`deploy/tools.config.sample.jsonc`](../../deploy/tools.config.sample.jsonc)（带注释）。
+
+### 3. stateDir 与数据库路径
+
+插件运行时数据库路径固定为：
+
+```
+<stateDir>/xgjktech/plans.sqlite
+```
+
+`stateDir` 取自 OpenClaw 全局状态目录（`api.runtime.state.resolveStateDir()`，默认
+`~/.openclaw/`，`OPENCLAW_STATE_DIR` 覆盖时同步），插件首次运行时通过 `resolvePlanDbPath`
+自动 `mkdir -p` 出 `xgjktech/` 子目录，无需手动创建。IM 插件若要接入同一份数据，应复用
+同一个 `resolvePlanDbPath` 以保证路径约定一致。
+
+## 两个工具说明
+
+### `xg_plan_write`
+
+整张创建或覆盖一份草稿计划（goal + tasks[]）并写入 SQLite。更新时必须重交所有要保留的
+task；写入 schema 不接受 steps，但读取旧计划仍兼容旧 steps 数据。
+
+### `xg_plan_view`
+
+只读查看计划，**不会执行任何任务**。带 planId 返回完整紧凑 view；不带 planId 返回最近 10 条
+计划摘要，用于跨会话找回 planId。更新进度统一使用 `xg_plan_write` 整张重交。
+
+> 工具名用 `view` 而非 `execute` 是有意的：`plan_view`/`plan_write` 都只是台账，不执行、不调度、
+> 无后台运行。二者 description 均明确"保存/查看 ≠ 执行"，且结果带 `reminder` 字段引导模型
+> 继续逐项实际执行任务——避免模型调用计划工具后误以为工作已在后台完成而停住。
+
+两个工具的完整参数 schema 见 `src/plan-write-tool.ts` / `src/plan-view-tool.ts`
+中的 `PLAN_WRITE_DESCRIPTION` / `PLAN_VIEW_DESCRIPTION`。
+
+## 部署 checklist
+
+- [ ] Node ≥ 22.19.0
+- [ ] monorepo 构建成功（`xg-shared` 先于本插件构建，workspaces 拓扑自动保证）
+- [ ] 插件已安装且被 OpenClaw 识别为已加载的第三方插件（非 bundled）
+- [ ] `tools.deny` 含 `update_plan`
+- [ ] `tools.allow` 含 `xg_plan_write` + `xg_plan_view`（或经 `group:plugins` / `*` 放行）
+- [ ] 实拉一个 agent，验证工具清单**有本插件两工具、无 update_plan**（步骤见下节）
+- [ ] `<stateDir>/xgjktech/` 可写，首次运行能生成 `plans.sqlite`
+- [ ] （互通）IM 侧已依赖 `@xgjktech/xg-openclaw-shared` 并按 `docs/04-互通设计.md` 接入只读反查
+
+## 实机验证步骤（可复现）+ 当前实际执行情况说明
+
+**验收标准要求部署方按 checklist 实拉一个 agent，确认工具清单里有 `xg_plan_write`/
+`xg_plan_view`、没有 `update_plan`。以下是可复现的验证步骤：**
+
+1. 按上文"配置"章节把 `tools.deny`/`tools.allow` 写入生产 agent/profile 配置。
+2. 安装并加载本插件（确认加载日志/插件列表里出现 `xg-harness-tools`，origin 为第三方非 bundled）。
+3. 拉起一个真实 agent 会话，触发一次会列出可用工具的动作（例如让 agent 描述自己有哪些工具，
+   或查看 gateway/日志里该次 attempt 实际注册的工具名列表）。
+4. 核对该工具列表：应包含 `xg_plan_write` 与 `xg_plan_view`，**不应包含** `update_plan`。
+5. 调用一次 `xg_plan_write` 建一份最小计划，确认返回 `planId + view`；再用该 planId 调
+   `xg_plan_view`，确认只读 view 一致。用 `openPlanStoreReadonly` 反查并核对落盘内容。
+
+**本项在本次交付中未在真实 OpenClaw gateway 环境实机执行**——本仓库当前开发环境没有可用的
+真实 OpenClaw gateway/agent 运行环境，因此无法诚实地报告"已实拉 agent 验证通过"。以下是
+已经做过、可以作为间接佐证的验证，但**明确说明这不等于实机验证**：
+
+- 当前 factory 集成测试用**手工构造的 mock `api`**捕获 2 个工具的注册工厂，并提供带
+  `sessionKey`/`deliveryContext` 的 `toolContext`：`xg_plan_write` 写入后通过只读存储反查
+  `origin`，`xg_plan_view` 校验指定计划的 view 与最近计划列表。**这验证的是插件代码本身
+  可以被正确加载、注册并贯通当前契约**，但 mock `api` 不是真实 OpenClaw gateway 的
+  `tools.allow`/`deny` 策略引擎，**不能**佐证"生产 deny/allow 配置生效后工具清单精确符合
+  预期"这一条——那一条必须在真实 gateway 环境按上面 5 步实测。
+- T6 阶段（`packages/xg-harness-tools/src/integration.test.ts`）用真实的 `SqlitePlanStore`
+  （临时目录）+ 真实工具函数（`buildPlanWriteTool`/`buildPlanViewTool`）跑通了完整的
+  写入→整张重交→execute 只读查看→SQLite 只读反查链路，但同样不经过 OpenClaw 的工具
+  allowlist/deny 策略引擎。
+
+**结论：部署方在生产环境落实上述配置后，必须按"实机验证步骤"重新执行一次实拉 agent 验证，
+不能以本仓库现有的 mock/集成测试结果代替。**

package/dist/plan-view-tool.js

@@ -7,13 +7,13 @@ export const PlanViewParams = Type.Object({
     planId: Type.Optional(Type.String({ description: "要查看的计划 id；留空则列出最近计划" })),
 }, { additionalProperties: false });
 export const PLAN_VIEW_DESCRIPTION = [
-    "用途：只读查看已保存的计划；不会执行任何任务，也不会修改计划。",
-    "只能看到当前会话来源的计划。",
+    "用途：只读查看已保存的 todo 状态，用于前端 UI 展示、恢复工作上下文和汇报进度；不会执行任何任务，也不会修改计划。",
+    "只能看到当前聊天范围（同一 channel/to）的 todo；在同一部署和 stateDir 下，即使重新创建 agent session，也可找回该范围内的 todo。",
     "",
     "- 带 planId：返回该计划当前的完整清单。",
     "- 不带 planId：返回最近计划的摘要列表，用于忘记或跨会话找回 planId。",
     "",
-    "重要：查看不等于执行。若计划存在未完成任务，你必须继续实际执行它们，完成一项后用 xg_plan_write 回写状态。",
+    "重要：查看只恢复记录，不会自动推进状态。若当前请求需要继续这项工作，再按 todo 状态推进，并在状态变化后用 xg_plan_write 回写。",
 ].join("\n");
 function summarizePlan(plan) {
     const taskCounts = { total: 0, completed: 0, blocked: 0, inProgress: 0 };
@@ -66,7 +66,7 @@ export function buildPlanViewTool(deps) {
                     planId: plan.planId,
                     view: renderPlanView(plan),
                     ...(reminder !== undefined
-                        ? { reminder: `该计划有未完成任务，查看不等于执行。${reminder}` }
+                        ? { reminder: `该 todo 有未完成项；查看只恢复记录，不会自动推进状态。${reminder}` }
                         : {}),
                 };
                 return toolJsonResult(result);

package/dist/plan-view.d.ts

@@ -1,7 +1,7 @@
 import { type Plan } from "@xgjktech/xg-openclaw-shared";
 export declare function renderPlanView(plan: Plan): string;
 /**
- * 生成"下一步该做什么"的引导句，喂给模型防止其只记录不执行。
+ * 生成当前 todo 的状态提醒，帮助模型恢复工作上下文并及时回写状态。
  * 规则：优先 in_progress（继续手头任务）→ 其次 pending（开新任务）→ 只剩 blocked 时提示等待；
  * 全部完成或已取消则返回 undefined。
  */

package/dist/plan-view.js

@@ -28,7 +28,7 @@ export function renderPlanView(plan) {
     return lines.join("\n");
 }
 /**
- * 生成"下一步该做什么"的引导句，喂给模型防止其只记录不执行。
+ * 生成当前 todo 的状态提醒，帮助模型恢复工作上下文并及时回写状态。
  * 规则：优先 in_progress（继续手头任务）→ 其次 pending（开新任务）→ 只剩 blocked 时提示等待；
  * 全部完成或已取消则返回 undefined。
  */
@@ -40,15 +40,15 @@ export function buildPlanReminder(plan) {
         return undefined;
     const inProgress = unfinished.find((task) => task.status === "in_progress");
     if (inProgress !== undefined) {
-        return `下一步：继续执行「${singleLine(inProgress.title)}」并回写状态`;
+        return `当前 todo：继续处理「${singleLine(inProgress.title)}」；状态变化后用 xg_plan_write 回写`;
     }
     const pending = unfinished.find((task) => task.status === "pending");
     if (pending !== undefined) {
-        return `下一步：执行「${singleLine(pending.title)}」并回写状态`;
+        return `当前 todo：待处理「${singleLine(pending.title)}」；开始后将状态更新为 in_progress`;
     }
     const blockedCount = unfinished.filter((task) => task.status === "blocked").length;
     if (blockedCount > 0) {
-        return `计划中有 ${blockedCount} 项 blocked 等待中：请先处理阻塞条件，或与用户确认后调整/取消计划`;
+        return `当前 todo 有 ${blockedCount} 项 blocked，等待 note 中记录的条件满足后再推进`;
     }
     return undefined;
 }

package/dist/plan-write-tool.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"plan-write-tool.d.ts","sourceRoot":"","sources":["../src/plan-write-tool.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,IAAI,EAAE,KAAK,MAAM,EAAE,MAAM,SAAS,CAAC;AAC5C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kCAAkC,CAAC;AACrE,OAAO,EAIL,KAAK,UAAU,EACf,KAAK,SAAS,EAGf,MAAM,8BAA8B,CAAC;AA8BtC,eAAO,MAAM,eAAe;;;;;;;;;EAwB3B,CAAC;AAEF,MAAM,MAAM,gBAAgB,GAAG,MAAM,CAAC,OAAO,eAAe,CAAC,CAAC;AAE9D,eAAO,MAAM,sBAAsB,QAwBvB,CAAC;AA0Eb,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,SAAS,EAAE,MAAM,CAAC,EAAE,UAAU,GAAG,YAAY,CA0HtF"}
+{"version":3,"file":"plan-write-tool.d.ts","sourceRoot":"","sources":["../src/plan-write-tool.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,IAAI,EAAE,KAAK,MAAM,EAAE,MAAM,SAAS,CAAC;AAC5C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kCAAkC,CAAC;AACrE,OAAO,EAIL,KAAK,UAAU,EACf,KAAK,SAAS,EAGf,MAAM,8BAA8B,CAAC;AA8BtC,eAAO,MAAM,eAAe;;;;;;;;;EAwB3B,CAAC;AAEF,MAAM,MAAM,gBAAgB,GAAG,MAAM,CAAC,OAAO,eAAe,CAAC,CAAC;AAE9D,eAAO,MAAM,sBAAsB,QA2BvB,CAAC;AA0Eb,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,SAAS,EAAE,MAAM,CAAC,EAAE,UAAU,GAAG,YAAY,CA0HtF"}

package/dist/plan-write-tool.js

@@ -33,22 +33,25 @@ export const PlanWriteParams = Type.Object({
     cancel: Type.Optional(Type.Boolean({ description: "取消该计划；true 时只需带 planId，不带 goal/tasks" })),
 }, { additionalProperties: false });
 export const PLAN_WRITE_DESCRIPTION = [
-    "用途：维护一份对用户可见、可跨回合保存的任务清单。每次调用都是整张替换，不是增量更新。",
+    "用途：维护模型当前工作的 todo 状态，供前端 UI 展示，并可在后续回合恢复。每次调用都是整张替换，不是增量更新。",
     "",
-    "何时不用（除非用户明确要求追踪）：",
-    "- 纯问答、查询、解释或闲聊。",
-    "- 一两个动作即可完成，或预计当前回合可以直接做完。",
-    "- 不要把分析、思考和试错过程写成 task；只记录需要向用户展示的工作项。",
+    "调用判断：收到执行型请求后，先在内部拆解工作项；满足以下任一条件，必须在开始实际工作前调用本工具，不需要等用户明确要求：",
+    "- 用户明确要求计划、任务清单或进度追踪。",
+    "- 需要等待用户回复、审批或外部系统。",
+    "- 有 3 个或以上用户可感知、可独立汇报完成状态的工作项。",
+    "- 同时包含调查、实施、验证等多个阶段。",
+    "- 涉及多个组件且工作项之间存在依赖，或可能中断后继续。",
     "",
-    "何时用：",
-    "- 工作有 3 个以上可独立完成的任务，且预计需要多轮推进或中断后继续。",
-    "- 需要等待人的回复、审批或外部系统，即使任务较少。",
-    "- 用户明确要求任务清单或进度追踪。",
+    "以下情况直接执行，不建计划：",
+    "- 纯问答、查询、解释或闲聊，不涉及后续执行。",
+    "- 只有 1-2 个原子动作，且无需等待、恢复或向用户展示进度。",
     "",
-    "执行纪律（必须遵守）：",
-    "- 本工具只把计划清单落库：不执行、不调度、无后台运行。保存计划 ≠ 完成工作。",
-    "- 保存后必须立即继续逐个实际执行 tasks：完成一项 → 回写其状态 → 继续下一项，直至全部 completed。",
-    "- 无法当场完成或需等待外部条件的项，标 in_progress（进行中）或 blocked（note 写明原因），后续回合继续。",
+    "判断要求：不要以自己能否在当前回合完成作为判断依据；不要把分析、思考和试错过程写成 task，只记录需要向用户展示的工作项。",
+    "",
+    "工作协议（必须遵守）：",
+    "- 本工具只记录 todo 状态并供 UI 展示：不执行、不调度、无后台运行。保存 todo ≠ 完成工作。",
+    "- 写入后继续处理当前请求；任务开始、完成、暂停或阻塞时，用本工具回写最新整张清单。",
+    "- 无法当场完成或需等待外部条件的项，标 in_progress（进行中）或 blocked（note 写明原因），后续回合恢复时再判断。",
     "",
     "提交规则：",
     "- 新建时不传 planId；更新时传入原 planId。",
@@ -200,7 +203,7 @@ export function buildPlanWriteTool(store, origin) {
                     view: renderPlanView(plan),
                     ...(warnings !== undefined ? { warnings } : {}),
                     ...(reminder !== undefined
-                        ? { reminder: `计划已保存（仅记录，未执行）。${reminder}` }
+                        ? { reminder: `todo 已保存（仅记录，未执行）。${reminder}` }
                         : {}),
                 };
                 return toolJsonResult(result);

package/openclaw.plugin.json

@@ -1,14 +1,14 @@
-{
-  "id": "xg-harness-tools",
-  "name": "XG Harness Tools",
-  "description": "企业工具插件：计划管理与通用动作分发（plan_write / plan_view / action_dispatch）",
-  "version": "0.1.0",
-  "configSchema": {
-    "type": "object",
-    "additionalProperties": true,
-    "properties": {}
-  },
-  "contracts": {
-    "tools": ["xg_plan_write", "xg_plan_view", "xg_action_dispatch"]
-  }
-}
+{
+  "id": "xg-harness-tools",
+  "name": "XG Harness Tools",
+  "description": "企业工具插件：计划管理与通用动作分发（plan_write / plan_view / action_dispatch）",
+  "version": "0.4.1",
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": true,
+    "properties": {}
+  },
+  "contracts": {
+    "tools": ["xg_plan_write", "xg_plan_view", "xg_action_dispatch"]
+  }
+}

package/package.json

@@ -1,55 +1,57 @@
-{
-  "name": "@xgjktech/xg-openclaw-harness-tools",
-  "version": "0.4.0",
-  "description": "企业工具插件：plan_write / plan_view / action_dispatch（OpenClaw 第三方工具插件）",
-  "license": "MIT",
-  "type": "module",
-  "engines": {
-    "node": ">=22.19.0"
-  },
-  "main": "dist/index.js",
-  "types": "dist/index.d.ts",
-  "files": [
-    "dist/**/*",
-    "!dist/*.test.*",
-    "openclaw.plugin.json"
-  ],
-  "publishConfig": {
-    "access": "public",
-    "registry": "https://registry.npmjs.org/"
-  },
-  "scripts": {
-    "build": "tsc -p tsconfig.json",
-    "typecheck": "tsc -p tsconfig.json --noEmit",
-    "pretest": "npm run build",
-    "test": "node --test dist/*.test.js",
-    "prepublishOnly": "npm run build && npm run test"
-  },
-  "dependencies": {
-    "typebox": "1.1.39",
-    "@xgjktech/xg-openclaw-shared": "^0.2.2"
-  },
-  "devDependencies": {
-    "@types/node": "^22.19.0",
-    "openclaw": "2026.6.10",
-    "typescript": "^5.6.0"
-  },
-  "peerDependencies": {
-    "openclaw": ">=2026.6.10"
-  },
-  "peerDependenciesMeta": {
-    "openclaw": {
-      "optional": true
-    }
-  },
-  "openclaw": {
-    "extensions": [
-      "./dist/index.js"
-    ],
-    "installDependencies": false,
-    "install": {
-      "localPath": ".",
-      "defaultChoice": "local"
-    }
-  }
-}
+{
+  "name": "@xgjktech/xg-openclaw-harness-tools",
+  "version": "0.4.1",
+  "description": "企业工具插件：plan_write / plan_view / action_dispatch（OpenClaw 第三方工具插件）",
+  "license": "MIT",
+  "type": "module",
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist/**/*",
+    "!dist/*.test.*",
+    "openclaw.plugin.json"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "scripts": {
+    "clean": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\"",
+    "prebuild": "npm run clean",
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "pretest": "npm run build",
+    "test": "node --test dist/*.test.js",
+    "prepublishOnly": "npm run build && npm run test"
+  },
+  "dependencies": {
+    "typebox": "1.1.39",
+    "@xgjktech/xg-openclaw-shared": "^0.2.2"
+  },
+  "devDependencies": {
+    "@types/node": "^22.19.0",
+    "openclaw": "2026.6.10",
+    "typescript": "^5.6.0"
+  },
+  "peerDependencies": {
+    "openclaw": ">=2026.6.10"
+  },
+  "peerDependenciesMeta": {
+    "openclaw": {
+      "optional": true
+    }
+  },
+  "openclaw": {
+    "extensions": [
+      "./dist/index.js"
+    ],
+    "installDependencies": false,
+    "install": {
+      "localPath": ".",
+      "defaultChoice": "local"
+    }
+  }
+}