@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 拓扑已保证顺序，直接在仓库根执行：

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，唯一权威路径）

{
  "tools": {
    "deny": ["update_plan"]
  }
}

无论生产 profile / allowlist 取何值（包括 allow:["*"]），deny 都一票否决， 与 profile 取值解耦。

2. 启用本插件两个工具（allow）

本插件两个工具都以 optional:true 注册，默认不启用，必须 allowlist 显式命中才会注册：

{
  "tools": {
    "allow": ["xg_plan_write", "xg_plan_execute"],
    "deny": ["update_plan"]
  }
}

可直接套用的完整样例见仓库根 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/集成测试结果代替。