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

package/README.md

@@ -1,144 +1,148 @@
-# @xgjktech/xg-openclaw-harness-tools
-
-OpenClaw 第三方工具插件：企业计划工具 `xg_plan_write` / `xg_plan_execute`。
-
-用一份持久化的计划（SQLite 落盘）取代内置 `update_plan`（无状态、只回显、不落库），
-`xg_plan_write` 整张维护草稿计划，`xg_plan_execute` 只读查看计划或最近摘要。
-
-## 架构裁决：实时事件当前处于事实性休眠（务必先读）
-
-**当前 OpenClaw 2026.6.10 版本下，实时事件推送链路休眠**：工具 execute/factory 期没有
-正当途径获取真实 runId（详见 `docs/notes-plugin-entry.md` N2），且 0.3.0 已移除工具侧
-`notify.ts`。`xg_plan_write` 落库后不发事件，`xg_plan_execute` 全程只读。
-
-**因此 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_execute"],
-    "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_execute`
-
-只读查看计划。带 planId 返回完整紧凑 view；不带 planId 返回最近 10 条计划摘要，用于跨会话
-找回 planId。更新进度统一使用 `xg_plan_write` 整张重交。
-
-两个工具的完整参数 schema 见 `src/plan-write-tool.ts` / `src/plan-execute-tool.ts`
-中的 `PLAN_WRITE_DESCRIPTION` / `PLAN_EXECUTE_DESCRIPTION`。
-
-## 部署 checklist
-
-- [ ] Node ≥ 22.19.0
-- [ ] monorepo 构建成功（`xg-shared` 先于本插件构建，workspaces 拓扑自动保证）
-- [ ] 插件已安装且被 OpenClaw 识别为已加载的第三方插件（非 bundled）
-- [ ] `tools.deny` 含 `update_plan`
-- [ ] `tools.allow` 含 `xg_plan_write` + `xg_plan_execute`（或经 `group:plugins` / `*` 放行）
-- [ ] 实拉一个 agent，验证工具清单**有本插件两工具、无 update_plan**（步骤见下节）
-- [ ] `<stateDir>/xgjktech/` 可写，首次运行能生成 `plans.sqlite`
-- [ ] （互通）IM 侧已依赖 `@xgjktech/xg-openclaw-shared` 并按 `docs/04-互通设计.md` 接入只读反查
-
-## 实机验证步骤（可复现）+ 当前实际执行情况说明
-
-**验收标准要求部署方按 checklist 实拉一个 agent，确认工具清单里有 `xg_plan_write`/
-`xg_plan_execute`、没有 `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_execute`，**不应包含** `update_plan`。
-5. 调用一次 `xg_plan_write` 建一份最小计划，确认返回 `planId + view`；再用该 planId 调
-   `xg_plan_execute`，确认只读 view 一致。用 `openPlanStoreReadonly` 反查并核对落盘内容。
-
-**本项在本次交付中未在真实 OpenClaw gateway 环境实机执行**——本仓库当前开发环境没有可用的
-真实 OpenClaw gateway/agent 运行环境，因此无法诚实地报告"已实拉 agent 验证通过"。以下是
-已经做过、可以作为间接佐证的验证，但**明确说明这不等于实机验证**：
-
-- 当前 factory 集成测试用**手工构造的 mock `api`**捕获 2 个工具的注册工厂，并提供带
-  `sessionKey`/`deliveryContext` 的 `toolContext`：`xg_plan_write` 写入后通过只读存储反查
-  `origin`，`xg_plan_execute` 校验指定计划的 view 与最近计划列表。**这验证的是插件代码本身
-  可以被正确加载、注册并贯通当前契约**，但 mock `api` 不是真实 OpenClaw gateway 的
-  `tools.allow`/`deny` 策略引擎，**不能**佐证"生产 deny/allow 配置生效后工具清单精确符合
-  预期"这一条——那一条必须在真实 gateway 环境按上面 5 步实测。
-- T6 阶段（`packages/xg-harness-tools/src/integration.test.ts`）用真实的 `SqlitePlanStore`
-  （临时目录）+ 真实工具函数（`buildPlanWriteTool`/`buildPlanExecuteTool`）跑通了完整的
-  写入→整张重交→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/index.js

@@ -1,14 +1,14 @@
 import { defineToolPlugin } from "openclaw/plugin-sdk/tool-plugin";
 import { resolvePlanDbPath, SqlitePlanStore, SqliteActionStore } from "@xgjktech/xg-openclaw-shared";
 import { PLAN_WRITE_DESCRIPTION, PlanWriteParams, buildPlanWriteTool } from "./plan-write-tool.js";
-import { PLAN_EXECUTE_DESCRIPTION, PlanExecuteParams, buildPlanExecuteTool, } from "./plan-execute-tool.js";
+import { PLAN_VIEW_DESCRIPTION, PlanViewParams, buildPlanViewTool, } from "./plan-view-tool.js";
 import { ACTION_DISPATCH_DESCRIPTION, ActionDispatchParams, buildActionDispatchTool, } from "./action-dispatch-tool.js";
 import { toPlanOrigin } from "./plan-origin.js";
 const PLUGIN_ID = "xg-harness-tools";
 export default defineToolPlugin({
     id: PLUGIN_ID,
     name: "XG Harness Tools",
-    description: "企业工具插件：计划管理与通用动作分发（plan_write / plan_execute / action_dispatch）",
+    description: "企业工具插件：计划管理与通用动作分发（plan_write / plan_view / action_dispatch）",
     tools: (tool) => {
         let planStore;
         let actionStore;
@@ -36,12 +36,12 @@ export default defineToolPlugin({
                 factory: ({ api, toolContext }) => buildPlanWriteTool(getPlanStore(api), toPlanOrigin(toolContext)),
             }),
             tool({
-                name: "xg_plan_execute",
+                name: "xg_plan_view",
                 label: "【xg-harness】查看计划",
-                description: PLAN_EXECUTE_DESCRIPTION,
-                parameters: PlanExecuteParams,
+                description: PLAN_VIEW_DESCRIPTION,
+                parameters: PlanViewParams,
                 optional: true,
-                factory: ({ api, toolContext }) => buildPlanExecuteTool({ store: getPlanStore(api), origin: toPlanOrigin(toolContext) }),
+                factory: ({ api, toolContext }) => buildPlanViewTool({ store: getPlanStore(api), origin: toPlanOrigin(toolContext) }),
             }),
             tool({
                 name: "xg_action_dispatch",

package/dist/{plan-execute-tool.d.ts → plan-view-tool.d.ts}

@@ -1,13 +1,13 @@
 import { Type, type Static } from "typebox";
 import type { AnyAgentTool } from "openclaw/plugin-sdk/plugin-entry";
 import { type PlanOrigin, type PlanStore } from "@xgjktech/xg-openclaw-shared";
-export declare const PlanExecuteParams: Type.TObject<{
+export declare const PlanViewParams: Type.TObject<{
     planId: Type.TOptional<Type.TString>;
 }>;
-export type PlanExecuteParamsT = Static<typeof PlanExecuteParams>;
-export declare const PLAN_EXECUTE_DESCRIPTION: string;
-export declare function buildPlanExecuteTool(deps: {
+export type PlanViewParamsT = Static<typeof PlanViewParams>;
+export declare const PLAN_VIEW_DESCRIPTION: string;
+export declare function buildPlanViewTool(deps: {
     store: PlanStore;
     origin?: PlanOrigin;
 }): AnyAgentTool;
-//# sourceMappingURL=plan-execute-tool.d.ts.map
+//# sourceMappingURL=plan-view-tool.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"plan-view-tool.d.ts","sourceRoot":"","sources":["../src/plan-view-tool.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,KAAK,MAAM,EAAE,MAAM,SAAS,CAAC;AAC5C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kCAAkC,CAAC;AACrE,OAAO,EAGL,KAAK,UAAU,EACf,KAAK,SAAS,EAEf,MAAM,8BAA8B,CAAC;AAKtC,eAAO,MAAM,cAAc;;EAK1B,CAAC;AAEF,MAAM,MAAM,eAAe,GAAG,MAAM,CAAC,OAAO,cAAc,CAAC,CAAC;AAE5D,eAAO,MAAM,qBAAqB,QAQtB,CAAC;AAuBb,wBAAgB,iBAAiB,CAAC,IAAI,EAAE;IAAE,KAAK,EAAE,SAAS,CAAC;IAAC,MAAM,CAAC,EAAE,UAAU,CAAA;CAAE,GAAG,YAAY,CAmD/F"}

package/dist/{plan-execute-tool.js → plan-view-tool.js}

@@ -1,19 +1,19 @@
 import { Type } from "typebox";
 import { isPlanCancelled, } from "@xgjktech/xg-openclaw-shared";
-import { renderPlanView } from "./plan-view.js";
+import { buildPlanReminder, renderPlanView } from "./plan-view.js";
 import { planInScope, scopeKey } from "./plan-scope.js";
 import { toolJsonResult } from "./tool-json-result.js";
-export const PlanExecuteParams = Type.Object({
+export const PlanViewParams = Type.Object({
     planId: Type.Optional(Type.String({ description: "要查看的计划 id；留空则列出最近计划" })),
 }, { additionalProperties: false });
-export const PLAN_EXECUTE_DESCRIPTION = [
-    "用途：只读查看已保存的计划；不执行任务，也不修改计划。",
+export const PLAN_VIEW_DESCRIPTION = [
+    "用途：只读查看已保存的计划；不会执行任何任务，也不会修改计划。",
     "只能看到当前会话来源的计划。",
     "",
     "- 带 planId：返回该计划当前的完整清单。",
     "- 不带 planId：返回最近计划的摘要列表，用于忘记或跨会话找回 planId。",
     "",
-    "需要更新进度时，用 xg_plan_write 重新提交整张计划。",
+    "重要：查看不等于执行。若计划存在未完成任务，你必须继续实际执行它们，完成一项后用 xg_plan_write 回写状态。",
 ].join("\n");
 function summarizePlan(plan) {
     const taskCounts = { total: 0, completed: 0, blocked: 0, inProgress: 0 };
@@ -33,14 +33,14 @@ function summarizePlan(plan) {
         taskCounts,
     };
 }
-export function buildPlanExecuteTool(deps) {
+export function buildPlanViewTool(deps) {
     const { store, origin } = deps;
     const scope = scopeKey(origin);
     return {
-        name: "xg_plan_execute",
+        name: "xg_plan_view",
         label: "【xg-harness】查看计划",
-        description: PLAN_EXECUTE_DESCRIPTION,
-        parameters: PlanExecuteParams,
+        description: PLAN_VIEW_DESCRIPTION,
+        parameters: PlanViewParams,
         async execute(_toolCallId, rawParams) {
             const params = rawParams;
             try {
@@ -60,10 +60,14 @@ export function buildPlanExecuteTool(deps) {
                     const result = { ok: false, error: { code: "PLAN_NOT_FOUND" } };
                     return toolJsonResult(result);
                 }
+                const reminder = buildPlanReminder(plan);
                 const result = {
                     ok: true,
                     planId: plan.planId,
                     view: renderPlanView(plan),
+                    ...(reminder !== undefined
+                        ? { reminder: `该计划有未完成任务，查看不等于执行。${reminder}` }
+                        : {}),
                 };
                 return toolJsonResult(result);
             }

package/dist/plan-view.d.ts

@@ -1,3 +1,9 @@
 import { type Plan } from "@xgjktech/xg-openclaw-shared";
 export declare function renderPlanView(plan: Plan): string;
+/**
+ * 生成"下一步该做什么"的引导句，喂给模型防止其只记录不执行。
+ * 规则：优先 in_progress（继续手头任务）→ 其次 pending（开新任务）→ 只剩 blocked 时提示等待；
+ * 全部完成或已取消则返回 undefined。
+ */
+export declare function buildPlanReminder(plan: Plan): string | undefined;
 //# sourceMappingURL=plan-view.d.ts.map

package/dist/plan-view.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"plan-view.d.ts","sourceRoot":"","sources":["../src/plan-view.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,IAAI,EAGV,MAAM,8BAA8B,CAAC;AAoBtC,wBAAgB,cAAc,CAAC,IAAI,EAAE,IAAI,GAAG,MAAM,CAgBjD"}
+{"version":3,"file":"plan-view.d.ts","sourceRoot":"","sources":["../src/plan-view.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,IAAI,EAGV,MAAM,8BAA8B,CAAC;AAqBtC,wBAAgB,cAAc,CAAC,IAAI,EAAE,IAAI,GAAG,MAAM,CAgBjD;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,IAAI,GAAG,MAAM,GAAG,SAAS,CAsBhE"}

package/dist/plan-view.js

@@ -1,14 +1,15 @@
 import { isPlanCancelled, } from "@xgjktech/xg-openclaw-shared";
+// 状态标记直接用枚举原文，模型可零歧义对账（写读一致），不用符号猜测。
 const TASK_STATUS_MARKERS = {
-    pending: "[ ]",
-    in_progress: "[>]",
-    completed: "[x]",
-    blocked: "[!]",
+    pending: "[pending]",
+    in_progress: "[in_progress]",
+    completed: "[completed]",
+    blocked: "[blocked]",
 };
 const STEP_STATUS_MARKERS = {
-    pending: "[ ]",
-    in_progress: "[>]",
-    completed: "[x]",
+    pending: "[pending]",
+    in_progress: "[in_progress]",
+    completed: "[completed]",
 };
 /** view 依赖"一行一项"的格式约定；字段内容里的换行统一压成空格，防止伪造出多余的行。 */
 function singleLine(text) {
@@ -26,3 +27,28 @@ export function renderPlanView(plan) {
     });
     return lines.join("\n");
 }
+/**
+ * 生成"下一步该做什么"的引导句，喂给模型防止其只记录不执行。
+ * 规则：优先 in_progress（继续手头任务）→ 其次 pending（开新任务）→ 只剩 blocked 时提示等待；
+ * 全部完成或已取消则返回 undefined。
+ */
+export function buildPlanReminder(plan) {
+    if (isPlanCancelled(plan))
+        return undefined;
+    const unfinished = plan.tasks.filter((task) => task.status !== "completed");
+    if (unfinished.length === 0)
+        return undefined;
+    const inProgress = unfinished.find((task) => task.status === "in_progress");
+    if (inProgress !== undefined) {
+        return `下一步：继续执行「${singleLine(inProgress.title)}」并回写状态`;
+    }
+    const pending = unfinished.find((task) => task.status === "pending");
+    if (pending !== undefined) {
+        return `下一步：执行「${singleLine(pending.title)}」并回写状态`;
+    }
+    const blockedCount = unfinished.filter((task) => task.status === "blocked").length;
+    if (blockedCount > 0) {
+        return `计划中有 ${blockedCount} 项 blocked 等待中：请先处理阻塞条件，或与用户确认后调整/取消计划`;
+    }
+    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,QAmBvB,CAAC;AA0Eb,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,SAAS,EAAE,MAAM,CAAC,EAAE,UAAU,GAAG,YAAY,CAsHtF"}
+{"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"}

package/dist/plan-write-tool.js

@@ -2,7 +2,7 @@ import { randomUUID } from "node:crypto";
 import { Type } from "typebox";
 import { assertPlanInvariants, isPlanCancelled, } from "@xgjktech/xg-openclaw-shared";
 import { toolJsonResult } from "./tool-json-result.js";
-import { renderPlanView } from "./plan-view.js";
+import { buildPlanReminder, renderPlanView } from "./plan-view.js";
 import { planInScope, scopeKey } from "./plan-scope.js";
 const TaskInput = Type.Object({
     title: Type.String({
@@ -45,9 +45,14 @@ export const PLAN_WRITE_DESCRIPTION = [
     "- 需要等待人的回复、审批或外部系统，即使任务较少。",
     "- 用户明确要求任务清单或进度追踪。",
     "",
+    "执行纪律（必须遵守）：",
+    "- 本工具只把计划清单落库：不执行、不调度、无后台运行。保存计划 ≠ 完成工作。",
+    "- 保存后必须立即继续逐个实际执行 tasks：完成一项 → 回写其状态 → 继续下一项，直至全部 completed。",
+    "- 无法当场完成或需等待外部条件的项，标 in_progress（进行中）或 blocked（note 写明原因），后续回合继续。",
+    "",
     "提交规则：",
     "- 新建时不传 planId；更新时传入原 planId。",
-    "- 更新计划内容时必须重新提交 goal 和所有要保留的 tasks，包括未变化任务及其当前 status/note。只提交变化项会删除其他任务；记不清时先用 xg_plan_execute 查看。",
+    "- 更新计划内容时必须重新提交 goal 和所有要保留的 tasks，包括未变化任务及其当前 status/note。只提交变化项会删除其他任务；记不清时先用 xg_plan_view 查看。",
     "- goal 用一句话；tasks 通常 3-7 项，每项是能判断是否完成的具体动作，不写 TODO、待定或内部思考。",
     "- status 为 pending、in_progress、completed 或 blocked。通常只有一项 in_progress，确实并行时可以有多项；blocked 时必须用 note 写明原因和继续所需条件。",
     "- 同一件工作只维护一份计划；任务方向变化时，先取消不再推进的旧计划（{planId, cancel:true}）再新建。",
@@ -188,11 +193,15 @@ export function buildPlanWriteTool(store, origin) {
                 const plan = buildPlan(params.goal, params.tasks, existing, planId, origin, new Date().toISOString());
                 assertPlanInvariants(plan);
                 store.set(plan);
+                const reminder = buildPlanReminder(plan);
                 const result = {
                     ok: true,
                     planId: plan.planId,
                     view: renderPlanView(plan),
                     ...(warnings !== undefined ? { warnings } : {}),
+                    ...(reminder !== undefined
+                        ? { reminder: `计划已保存（仅记录，未执行）。${reminder}` }
+                        : {}),
                 };
                 return toolJsonResult(result);
             }

package/openclaw.plugin.json

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

package/package.json

@@ -1,55 +1,55 @@
-{
-  "name": "@xgjktech/xg-openclaw-harness-tools",
-  "version": "0.3.5",
-  "description": "企业工具插件：plan_write / plan_execute / 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.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"
+    }
+  }
 }

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

@@ -1 +0,0 @@
-{"version":3,"file":"plan-execute-tool.d.ts","sourceRoot":"","sources":["../src/plan-execute-tool.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,KAAK,MAAM,EAAE,MAAM,SAAS,CAAC;AAC5C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kCAAkC,CAAC;AACrE,OAAO,EAGL,KAAK,UAAU,EACf,KAAK,SAAS,EAEf,MAAM,8BAA8B,CAAC;AAKtC,eAAO,MAAM,iBAAiB;;EAK7B,CAAC;AAEF,MAAM,MAAM,kBAAkB,GAAG,MAAM,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAElE,eAAO,MAAM,wBAAwB,QAQzB,CAAC;AAuBb,wBAAgB,oBAAoB,CAAC,IAAI,EAAE;IAAE,KAAK,EAAE,SAAS,CAAC;IAAC,MAAM,CAAC,EAAE,UAAU,CAAA;CAAE,GAAG,YAAY,CA+ClG"}