@xgjktech/xg-openclaw-harness-tools 0.1.0

package/README.md

@@ -0,0 +1,152 @@
+# @xgjktech/xg-openclaw-harness-tools
+
+OpenClaw 第三方工具插件：企业计划工具 `xg_plan_write` / `xg_plan_execute`。
+
+用一份持久化的计划（SQLite 落盘）取代内置 `update_plan`（无状态、只回显、不落库），
+并把推进进度尽力而为地通知到相关会话/群。
+
+## 架构裁决：实时事件当前处于事实性休眠（务必先读）
+
+**当前 OpenClaw 2026.6.10 版本下，缝隙B（实时事件推送）事实性休眠**：`xg_plan_execute`
+的 `execute`/`factory` 期都没有正当途径获取当次 agent run 的真实 `runId`（详见
+`docs/notes-plugin-entry.md` N2 的逐路径排查记录）。工具因此把 `routing.runId` 固定传空串，
+`notify.emitPlanEvent` 据此恒定返回 `{emitted:false,reason:"no runId"}`，**不会真的发出事件**
+（不伪造 runId 是硬性红线，见 `docs/04-互通设计.md` §2.4）。
+
+**因此 IM 侧（或任何下游消费方）不得依赖实时事件感知计划进度。** 当前唯一可靠的主感知路径是：
+
+1. **SQLite 读取**——用 `openPlanStoreReadonly(dbPath)` 只读反查 `<stateDir>/xgjktech/plans.sqlite`，
+   这是权威、始终正确的状态源（工具每次推进都先落盘、落盘成功才尝试发事件，见 `03-工具契约.md` §2.5）。
+2. **agent 最终回复**——agent 完成任务后的文本回复本身会体现进度。
+
+事件契约（`PlanEventPayload` / `isPlanEventPayload` / `planEventStream`）已按正式设计原样实现并保留，
+**不是搁置未完成**，而是"契约就绪、通路等待宿主开放"：一旦未来某个 OpenClaw 版本给插件暴露了
+获取当次 `runId` 的 API，事件推送即可在**不改本插件代码**的前提下自动激活（`notify.ts` 的判断只看
+`payload.runId` 是否非空）。
+
+## 环境要求
+
+- **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[]，task 可含 steps[]），写入 SQLite。用于任务开始时
+建立计划，或对既有计划做整体重写。
+
+### `xg_plan_execute`
+
+推进一份已保存计划的单个状态（`start_task` / `complete_task` / `block_task` /
+`start_step` / `complete_step`），每次一步。落盘顺序：**先读最新状态 → 应用动作 →
+不变量校验 → 落盘 → 尽力而为发事件**（先落盘、事件不影响主流程成败）。`block_task`
+必须携带非空 `note` 说明阻塞原因。
+
+两个工具的完整参数 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` 建一份最小计划，再调用 `xg_plan_execute` 推进一步，确认返回
+   `ok:true` 且 `event` 字段为 `{emitted:false,reason:"no runId"}`（与本文档"架构裁决"章节
+   一致，属预期行为非故障）；用 `openPlanStoreReadonly` 反查该 planId，确认落盘内容与预期一致。
+
+**本项在本次交付中未在真实 OpenClaw gateway 环境实机执行**——本仓库当前开发环境没有可用的
+真实 OpenClaw gateway/agent 运行环境，因此无法诚实地报告"已实拉 agent 验证通过"。以下是
+已经做过、可以作为间接佐证的验证，但**明确说明这不等于实机验证**：
+
+- T2 阶段（`docs/notes-plugin-entry.md` N3.3）用**手工构造的 mock `api`**（捕获
+  `registerTool` 调用、手工构造 `toolContext.sessionKey` 等字段）驱动编译后的 `dist/index.js`
+  跑通过一次注册链路：`register(api)` → 捕获到 2 个工具的 `factory` → 调用 `factory` 拿到
+  `toolContext.sessionKey` → 调用 `execute()` → 返回结果里的 `sessionKey` 与传入值一致、
+  `planCount` 来自真实 `SqlitePlanStore.list()` 查询。**这验证的是插件代码本身可以被正确加载
+  并注册出预期的 2 个工具**，但 mock `api` 不是真实 OpenClaw gateway 的 `tools.allow`/`deny`
+  策略引擎，**不能**佐证"生产 deny/allow 配置生效后工具清单精确符合预期"这一条——那一条
+  必须在真实 gateway 环境按上面 5 步实测。
+- T6 阶段（`packages/xg-harness-tools/src/integration.test.ts`）用真实的 `SqlitePlanStore`
+  （临时目录）+ 真实工具函数（`buildPlanWriteTool`/`buildPlanExecuteTool`）跑通了完整的
+  写入→推进→落盘→只读反查链路，但同样不经过 OpenClaw 的工具 allowlist/deny 策略引擎。
+
+**结论：部署方在生产环境落实上述配置后，必须按"实机验证步骤"重新执行一次实拉 agent 验证，
+不能以本仓库现有的 mock/集成测试结果代替。**

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+declare const _default: import("openclaw/plugin-sdk/tool-plugin").DefinedToolPluginEntry;
+export default _default;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAWA,wBAwDG"}

package/dist/index.js

@@ -0,0 +1,60 @@
+import { defineToolPlugin } from "openclaw/plugin-sdk/tool-plugin";
+import { resolvePlanDbPath, SqlitePlanStore } 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";
+const PLUGIN_ID = "xg-harness-tools";
+export default defineToolPlugin({
+    id: PLUGIN_ID,
+    name: "XG Harness Tools",
+    description: "企业工具插件：计划编写与推进（plan_write / plan_execute）",
+    tools: (tool) => {
+        // store 单例：defineToolPlugin 的 tools(...) 只在插件加载时调用一次，
+        // 闭包在此建一次即可；factory 本身会在每次 agent attempt 重建工具集时重新调用。
+        let store;
+        const getStore = (api) => {
+            if (store === undefined) {
+                const dbPath = resolvePlanDbPath(api.runtime.state.resolveStateDir());
+                store = new SqlitePlanStore(dbPath);
+            }
+            return store;
+        };
+        return [
+            tool({
+                name: "xg_plan_write",
+                label: "【xg-harness】编写计划",
+                description: PLAN_WRITE_DESCRIPTION,
+                parameters: PlanWriteParams,
+                optional: true,
+                factory: ({ api }) => buildPlanWriteTool(getStore(api)),
+            }),
+            tool({
+                name: "xg_plan_execute",
+                label: "【xg-harness】推进计划",
+                description: PLAN_EXECUTE_DESCRIPTION,
+                parameters: PlanExecuteParams,
+                optional: true,
+                // T3 已实证（docs/notes-plugin-entry.md N2）：execute/factory 期均无正当 runId
+                // 获取路径，routing.runId 只能留空——notify.emitPlanEvent 据此走
+                // {emitted:false,reason:"no runId"} 降级分支，不伪造 runId（04-互通设计 §2.4 红线1）。
+                factory: ({ api, toolContext }) => buildPlanExecuteTool({
+                    store: getStore(api),
+                    pluginId: PLUGIN_ID,
+                    emitAgentEvent: (params) => api.agent.events.emitAgentEvent(params),
+                    routing: {
+                        runId: "",
+                        ...(toolContext.sessionKey !== undefined ? { sessionKey: toolContext.sessionKey } : {}),
+                        ...(toolContext.deliveryContext !== undefined
+                            ? { deliveryContext: toolContext.deliveryContext }
+                            : {}),
+                        ...(toolContext.agentAccountId !== undefined
+                            ? { agentAccountId: toolContext.agentAccountId }
+                            : {}),
+                        ...(toolContext.messageChannel !== undefined
+                            ? { messageChannel: toolContext.messageChannel }
+                            : {}),
+                    },
+                }),
+            }),
+        ];
+    },
+});

package/dist/notify.d.ts

@@ -0,0 +1,16 @@
+import type { PluginAgentEventEmitParams, PluginAgentEventEmitResult } from "openclaw/plugin-sdk/plugin-entry";
+import { type PlanEventPayload } from "@xgjktech/xg-openclaw-shared";
+export type EmitAgentEventFn = (params: PluginAgentEventEmitParams) => PluginAgentEventEmitResult;
+/**
+ * 缝隙B 事件发送：尽力而为，不因失败中断主流程（04-互通设计 §2.4 契约）。
+ *
+ * 红线：禁止伪造 runId（架构裁决 2026-07-24）。T3 已实证 factory ctx / execute ctx /
+ * 插件可达的 runtime API 均无正当获取当次 run 真实 runId 的路径（见
+ * docs/notes-plugin-entry.md N2）——payload.runId 缺失时直接跳过发送，不抛异常。
+ */
+export declare function emitPlanEvent(params: {
+    pluginId: string;
+    emitAgentEvent: EmitAgentEventFn;
+    payload: PlanEventPayload;
+}): PluginAgentEventEmitResult;
+//# sourceMappingURL=notify.d.ts.map

package/dist/notify.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"notify.d.ts","sourceRoot":"","sources":["../src/notify.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,0BAA0B,EAC1B,0BAA0B,EAE3B,MAAM,kCAAkC,CAAC;AAC1C,OAAO,EAAmB,KAAK,gBAAgB,EAAE,MAAM,8BAA8B,CAAC;AAEtF,MAAM,MAAM,gBAAgB,GAAG,CAAC,MAAM,EAAE,0BAA0B,KAAK,0BAA0B,CAAC;AAElG;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE;IACpC,QAAQ,EAAE,MAAM,CAAC;IACjB,cAAc,EAAE,gBAAgB,CAAC;IACjC,OAAO,EAAE,gBAAgB,CAAC;CAC3B,GAAG,0BAA0B,CAW7B"}

package/dist/notify.js

@@ -0,0 +1,20 @@
+import { planEventStream } from "@xgjktech/xg-openclaw-shared";
+/**
+ * 缝隙B 事件发送：尽力而为，不因失败中断主流程（04-互通设计 §2.4 契约）。
+ *
+ * 红线：禁止伪造 runId（架构裁决 2026-07-24）。T3 已实证 factory ctx / execute ctx /
+ * 插件可达的 runtime API 均无正当获取当次 run 真实 runId 的路径（见
+ * docs/notes-plugin-entry.md N2）——payload.runId 缺失时直接跳过发送，不抛异常。
+ */
+export function emitPlanEvent(params) {
+    const { pluginId, emitAgentEvent, payload } = params;
+    if (payload.runId.trim() === "") {
+        return { emitted: false, reason: "no runId" };
+    }
+    return emitAgentEvent({
+        runId: payload.runId,
+        stream: planEventStream(pluginId),
+        data: payload,
+        ...(payload.sessionKey ? { sessionKey: payload.sessionKey } : {}),
+    });
+}

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

@@ -0,0 +1,26 @@
+import { Type, type Static } from "typebox";
+import type { AnyAgentTool } from "openclaw/plugin-sdk/plugin-entry";
+import { type PlanStore } from "@xgjktech/xg-openclaw-shared";
+import { type EmitAgentEventFn } from "./notify.js";
+export declare const PlanExecuteParams: Type.TObject<{
+    planId: Type.TString;
+    action: Type.TUnion<[Type.TLiteral<"start_task">, Type.TLiteral<"complete_task">, Type.TLiteral<"block_task">, Type.TLiteral<"start_step">, Type.TLiteral<"complete_step">]>;
+    taskIndex: Type.TInteger;
+    stepIndex: Type.TOptional<Type.TInteger>;
+    note: Type.TOptional<Type.TString>;
+}>;
+export type PlanExecuteParamsT = Static<typeof PlanExecuteParams>;
+export declare const PLAN_EXECUTE_DESCRIPTION: string;
+export declare function buildPlanExecuteTool(deps: {
+    store: PlanStore;
+    pluginId: string;
+    emitAgentEvent: EmitAgentEventFn;
+    routing: {
+        runId: string;
+        sessionKey?: string;
+        deliveryContext?: unknown;
+        agentAccountId?: string;
+        messageChannel?: string;
+    };
+}): AnyAgentTool;
+//# sourceMappingURL=plan-execute-tool.d.ts.map

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

@@ -0,0 +1 @@
+{"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,EAKL,KAAK,SAAS,EAEf,MAAM,8BAA8B,CAAC;AAEtC,OAAO,EAAiB,KAAK,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAEnE,eAAO,MAAM,iBAAiB;;;;;;EAsB7B,CAAC;AAEF,MAAM,MAAM,kBAAkB,GAAG,MAAM,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAElE,eAAO,MAAM,wBAAwB,QAazB,CAAC;AAiFb,wBAAgB,oBAAoB,CAAC,IAAI,EAAE;IACzC,KAAK,EAAE,SAAS,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,cAAc,EAAE,gBAAgB,CAAC;IACjC,OAAO,EAAE;QACP,KAAK,EAAE,MAAM,CAAC;QACd,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,eAAe,CAAC,EAAE,OAAO,CAAC;QAC1B,cAAc,CAAC,EAAE,MAAM,CAAC;QACxB,cAAc,CAAC,EAAE,MAAM,CAAC;KACzB,CAAC;CACH,GAAG,YAAY,CA8Df"}

package/dist/plan-execute-tool.js

@@ -0,0 +1,159 @@
+import { Type } from "typebox";
+import { assertPlanInvariants, PlanInvariantError, } from "@xgjktech/xg-openclaw-shared";
+import { toolJsonResult } from "./tool-json-result.js";
+import { emitPlanEvent } from "./notify.js";
+export const PlanExecuteParams = Type.Object({
+    planId: Type.String({ minLength: 1, description: "要推进的计划 id" }),
+    action: Type.Union([
+        Type.Literal("start_task"),
+        Type.Literal("complete_task"),
+        Type.Literal("block_task"),
+        Type.Literal("start_step"),
+        Type.Literal("complete_step"),
+    ], { description: "推进动作" }),
+    taskIndex: Type.Integer({ minimum: 0, description: "目标 task 在 tasks[] 的下标" }),
+    stepIndex: Type.Optional(Type.Integer({ minimum: 0, description: "start_step/complete_step 时必填，目标 step 下标" })),
+    note: Type.Optional(Type.String({ description: "block_task 时必填，说明阻塞原因；其他动作可选备注" })),
+}, { additionalProperties: false });
+export const PLAN_EXECUTE_DESCRIPTION = [
+    "用途：推进一份已保存的计划，一次推进一步，并把进度实时通知到相关会话/群。",
+    "",
+    "执行纪律（务必遵守）：",
+    "- 一次一步：同一时刻整份计划最多一个进行中的 task，task 内最多一个进行中的 step。",
+    "  想开始新任务前，先把当前任务收尾（completed 或 blocked）。",
+    "- 验证后才 completed：只有真正做完并验证通过，才把 task/step 标 completed；",
+    "  没验证就别标完成。",
+    "- 遇阻塞就停下并记录：卡住时用 action=block_task 并在 note 写清楚卡在哪、需要谁/什么才能继续，",
+    "  不要绕过、不要假装完成。阻塞会被推送到群里等人回复——这正是本工具的价值。",
+    "",
+    "参数：planId + action + taskIndex（+ 视情况 stepIndex / note）。",
+    "每次成功推进都会落盘并发出进度事件；调用方无需手动通知。",
+].join("\n");
+class PlanExecuteValidationError extends Error {
+    code;
+    constructor(code, message) {
+        super(message ?? code);
+        this.name = "PlanExecuteValidationError";
+        this.code = code;
+    }
+}
+function requireTask(plan, taskIndex) {
+    const task = plan.tasks[taskIndex];
+    if (task === undefined) {
+        throw new PlanExecuteValidationError("INDEX_OUT_OF_RANGE", `taskIndex ${taskIndex} 越界`);
+    }
+    return task;
+}
+function requireStep(task, stepIndex) {
+    const step = task.steps?.[stepIndex];
+    if (step === undefined) {
+        throw new PlanExecuteValidationError("INDEX_OUT_OF_RANGE", `stepIndex ${stepIndex} 越界`);
+    }
+    return step;
+}
+function applyAction(plan, params) {
+    const task = requireTask(plan, params.taskIndex);
+    switch (params.action) {
+        case "start_task": {
+            task.status = "in_progress";
+            return;
+        }
+        case "complete_task": {
+            task.status = "completed";
+            return;
+        }
+        case "block_task": {
+            if (params.note === undefined || params.note.trim() === "") {
+                throw new PlanExecuteValidationError("NOTE_REQUIRED", "block_task 必须带非空 note");
+            }
+            task.status = "blocked";
+            task.note = params.note;
+            return;
+        }
+        case "start_step": {
+            if (params.stepIndex === undefined) {
+                throw new PlanExecuteValidationError("STEP_INDEX_REQUIRED", "start_step 必须带 stepIndex");
+            }
+            const step = requireStep(task, params.stepIndex);
+            step.status = "in_progress";
+            return;
+        }
+        case "complete_step": {
+            if (params.stepIndex === undefined) {
+                throw new PlanExecuteValidationError("STEP_INDEX_REQUIRED", "complete_step 必须带 stepIndex");
+            }
+            const step = requireStep(task, params.stepIndex);
+            step.status = "completed";
+            return;
+        }
+    }
+}
+function summarize(plan) {
+    const summary = { total: 0, completed: 0, blocked: 0, inProgress: 0 };
+    for (const task of plan.tasks) {
+        summary.total += 1;
+        if (task.status === "completed")
+            summary.completed += 1;
+        if (task.status === "blocked")
+            summary.blocked += 1;
+        if (task.status === "in_progress")
+            summary.inProgress += 1;
+    }
+    return summary;
+}
+export function buildPlanExecuteTool(deps) {
+    const { store, pluginId, emitAgentEvent, routing } = deps;
+    return {
+        name: "xg_plan_execute",
+        label: "【xg-harness】推进计划",
+        description: PLAN_EXECUTE_DESCRIPTION,
+        parameters: PlanExecuteParams,
+        async execute(_toolCallId, rawParams) {
+            const params = rawParams;
+            try {
+                const plan = store.get(params.planId);
+                if (plan === undefined) {
+                    const result = { ok: false, error: { code: "PLAN_NOT_FOUND" } };
+                    return toolJsonResult(result);
+                }
+                applyAction(plan, params);
+                plan.updatedAt = new Date().toISOString();
+                assertPlanInvariants(plan);
+                store.set(plan);
+                const task = plan.tasks[params.taskIndex];
+                const payload = {
+                    kind: "plan_update",
+                    planId: plan.planId,
+                    goal: plan.goal,
+                    action: params.action,
+                    taskIndex: params.taskIndex,
+                    ...(params.stepIndex !== undefined ? { stepIndex: params.stepIndex } : {}),
+                    taskTitle: task.title,
+                    taskStatus: task.status,
+                    ...(task.status === "blocked" && task.note !== undefined ? { blockedNote: task.note } : {}),
+                    summary: summarize(plan),
+                    runId: routing.runId,
+                    ...(routing.sessionKey !== undefined ? { sessionKey: routing.sessionKey } : {}),
+                    ...(routing.deliveryContext !== undefined ? { deliveryContext: routing.deliveryContext } : {}),
+                    ...(routing.agentAccountId !== undefined ? { agentAccountId: routing.agentAccountId } : {}),
+                    ...(routing.messageChannel !== undefined ? { messageChannel: routing.messageChannel } : {}),
+                };
+                const event = emitPlanEvent({ pluginId, emitAgentEvent, payload });
+                const result = { ok: true, planId: plan.planId, plan, event };
+                return toolJsonResult(result);
+            }
+            catch (e) {
+                const code = e instanceof PlanInvariantError
+                    ? "INVARIANT_VIOLATION"
+                    : e instanceof PlanExecuteValidationError
+                        ? e.code
+                        : "STORE_ERROR";
+                const result = {
+                    ok: false,
+                    error: { code, detail: String(e.message) },
+                };
+                return toolJsonResult(result);
+            }
+        },
+    };
+}

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

@@ -0,0 +1,20 @@
+import { Type, type Static } from "typebox";
+import type { AnyAgentTool } from "openclaw/plugin-sdk/plugin-entry";
+import { type PlanStore } from "@xgjktech/xg-openclaw-shared";
+export declare const PlanWriteParams: Type.TObject<{
+    planId: Type.TOptional<Type.TString>;
+    goal: Type.TString;
+    tasks: Type.TArray<Type.TObject<{
+        title: Type.TString;
+        status: Type.TOptional<Type.TUnion<[Type.TLiteral<"pending">, Type.TLiteral<"in_progress">, Type.TLiteral<"completed">, Type.TLiteral<"blocked">]>>;
+        note: Type.TOptional<Type.TString>;
+        steps: Type.TOptional<Type.TArray<Type.TObject<{
+            text: Type.TString;
+            status: Type.TOptional<Type.TUnion<[Type.TLiteral<"pending">, Type.TLiteral<"in_progress">, Type.TLiteral<"completed">]>>;
+        }>>>;
+    }>>;
+}>;
+export type PlanWriteParamsT = Static<typeof PlanWriteParams>;
+export declare const PLAN_WRITE_DESCRIPTION: string;
+export declare function buildPlanWriteTool(store: PlanStore): AnyAgentTool;
+//# sourceMappingURL=plan-write-tool.d.ts.map

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

@@ -0,0 +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,SAAS,EAKf,MAAM,8BAA8B,CAAC;AAoCtC,eAAO,MAAM,eAAe;;;;;;;;;;;;EAS3B,CAAC;AAEF,MAAM,MAAM,gBAAgB,GAAG,MAAM,CAAC,OAAO,eAAe,CAAC,CAAC;AAE9D,eAAO,MAAM,sBAAsB,QAcvB,CAAC;AAsCb,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,SAAS,GAAG,YAAY,CAwCjE"}

package/dist/plan-write-tool.js

@@ -0,0 +1,106 @@
+import { randomUUID } from "node:crypto";
+import { Type } from "typebox";
+import { assertPlanInvariants, PlanInvariantError, } from "@xgjktech/xg-openclaw-shared";
+import { toolJsonResult } from "./tool-json-result.js";
+const StepInput = Type.Object({
+    text: Type.String({ minLength: 1, description: "单条可执行步骤，动词开头，无占位符" }),
+    status: Type.Optional(Type.Union([Type.Literal("pending"), Type.Literal("in_progress"), Type.Literal("completed")], { default: "pending" })),
+}, { additionalProperties: false });
+const TaskInput = Type.Object({
+    title: Type.String({ minLength: 1, description: "任务标题，bite-size，单次可完成并验证" }),
+    status: Type.Optional(Type.Union([
+        Type.Literal("pending"),
+        Type.Literal("in_progress"),
+        Type.Literal("completed"),
+        Type.Literal("blocked"),
+    ], { default: "pending" })),
+    note: Type.Optional(Type.String({ description: "备注；status=blocked 时必填，说明阻塞原因" })),
+    steps: Type.Optional(Type.Array(StepInput, { description: "可选子步骤" })),
+}, { additionalProperties: false });
+export const PlanWriteParams = Type.Object({
+    planId: Type.Optional(Type.String({ description: "留空=新建计划并返回新 planId；填写=整体改写该计划" })),
+    goal: Type.String({ minLength: 1, description: "计划总目标，一句话说明完成态" }),
+    tasks: Type.Array(TaskInput, { minItems: 1, description: "任务清单，至少一项" }),
+}, { additionalProperties: false });
+export const PLAN_WRITE_DESCRIPTION = [
+    "用途：把一项工作拆成一份可执行计划并持久化保存（跨回合、跨天不丢失）。",
+    "",
+    "何时用：接到多步骤任务、需要先规划再动手时，先用本工具写下计划。",
+    "",
+    "编写纪律（务必遵守）：",
+    "- Bite-size：每个 task 是一次可独立完成并验证的最小工作单元，别写成大而空的阶段。",
+    "- 无占位符：task/step 文案必须是具体动作，禁止 \"TODO/待定/等等\" 这类占位。",
+    "- 可验证：每个 task 应能明确判断\"做完没有\"，把验证方式写进 title 或 note。",
+    "- 顺序清晰：tasks 按依赖顺序排列，读者不需要猜先后。",
+    "",
+    "参数：goal=总目标；tasks=任务清单（含可选 steps 子步骤）。",
+    "留空 planId=新建（返回新 planId 供后续 plan_execute 使用）；填 planId=整体改写。",
+    "不要在这里推进状态——推进用 xg_plan_execute。",
+].join("\n");
+function toStep(input) {
+    return {
+        text: input.text,
+        status: (input.status ?? "pending"),
+    };
+}
+function toTask(input) {
+    const task = {
+        title: input.title,
+        status: (input.status ?? "pending"),
+    };
+    if (input.note !== undefined) {
+        task.note = input.note;
+    }
+    if (input.steps !== undefined) {
+        task.steps = input.steps.map(toStep);
+    }
+    return task;
+}
+function buildPlan(params, existing, planId) {
+    const now = new Date().toISOString();
+    return {
+        planId,
+        goal: params.goal,
+        createdAt: existing?.createdAt ?? now,
+        updatedAt: now,
+        tasks: params.tasks.map(toTask),
+    };
+}
+export function buildPlanWriteTool(store) {
+    return {
+        name: "xg_plan_write",
+        label: "【xg-harness】编写计划",
+        description: PLAN_WRITE_DESCRIPTION,
+        parameters: PlanWriteParams,
+        async execute(_toolCallId, rawParams) {
+            const params = rawParams;
+            try {
+                let existing;
+                if (params.planId !== undefined) {
+                    existing = store.get(params.planId);
+                    if (existing === undefined) {
+                        const result = {
+                            ok: false,
+                            error: { code: "PLAN_NOT_FOUND" },
+                        };
+                        return toolJsonResult(result);
+                    }
+                }
+                const planId = params.planId ?? randomUUID();
+                const plan = buildPlan(params, existing, planId);
+                assertPlanInvariants(plan);
+                store.set(plan);
+                const result = { ok: true, planId: plan.planId, plan };
+                return toolJsonResult(result);
+            }
+            catch (e) {
+                const code = e instanceof PlanInvariantError ? "INVARIANT_VIOLATION" : "STORE_ERROR";
+                const result = {
+                    ok: false,
+                    error: { code, detail: String(e.message) },
+                };
+                return toolJsonResult(result);
+            }
+        },
+    };
+}

package/dist/tool-json-result.d.ts

@@ -0,0 +1,10 @@
+import type { AnyAgentTool } from "openclaw/plugin-sdk/plugin-entry";
+type ToolExecuteReturn = Awaited<ReturnType<NonNullable<AnyAgentTool["execute"]>>>;
+/**
+ * 与 `openclaw/plugin-sdk` 的 `jsonResult` 返回结构一致（AgentToolResult），供工具 execute 使用。
+ * 不直接 import SDK 的 `jsonResult`：部分打包环境下该具名导出会被打成 undefined，调用即崩
+ * （IM 插件 `tool-json-result.ts` 已踩过此坑，见 questions.md Q5）。
+ */
+export declare function toolJsonResult(payload: unknown): ToolExecuteReturn;
+export {};
+//# sourceMappingURL=tool-json-result.d.ts.map

package/dist/tool-json-result.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-json-result.d.ts","sourceRoot":"","sources":["../src/tool-json-result.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kCAAkC,CAAC;AAErE,KAAK,iBAAiB,GAAG,OAAO,CAAC,UAAU,CAAC,WAAW,CAAC,YAAY,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC;AAEnF;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,OAAO,GAAG,iBAAiB,CASlE"}

package/dist/tool-json-result.js

@@ -0,0 +1,15 @@
+/**
+ * 与 `openclaw/plugin-sdk` 的 `jsonResult` 返回结构一致（AgentToolResult），供工具 execute 使用。
+ * 不直接 import SDK 的 `jsonResult`：部分打包环境下该具名导出会被打成 undefined，调用即崩
+ * （IM 插件 `tool-json-result.ts` 已踩过此坑，见 questions.md Q5）。
+ */
+export function toolJsonResult(payload) {
+    if (payload === undefined) {
+        return { content: [{ type: "text", text: "" }] };
+    }
+    const text = typeof payload === "string" ? JSON.stringify(payload) : JSON.stringify(payload, null, 2);
+    return {
+        content: [{ type: "text", text }],
+        details: payload,
+    };
+}

package/openclaw.plugin.json

@@ -0,0 +1,14 @@
+{
+  "id": "xg-harness-tools",
+  "name": "XG Harness Tools",
+  "description": "企业计划工具（plan_write / plan_execute）",
+  "version": "0.1.0",
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": true,
+    "properties": {}
+  },
+  "contracts": {
+    "tools": ["xg_plan_write", "xg_plan_execute"]
+  }
+}

package/package.json

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