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

package/README.md

@@ -105,6 +105,29 @@ task；写入 schema 不接受 steps，但读取旧计划仍兼容旧 steps 数
 两个工具的完整参数 schema 见 `src/plan-write-tool.ts` / `src/plan-view-tool.ts`
 中的 `PLAN_WRITE_DESCRIPTION` / `PLAN_VIEW_DESCRIPTION`。
 
+## 主动计划提示词注入（before_prompt_build）
+
+插件在 `register` 时挂载 `before_prompt_build` hook，用 `appendSystemContext` 向每个 agent 的
+system prompt 追加一段"主动工作计划"纪律（`src/plan-prompt.ts`）：多步工作先建计划、逐项整张回写、
+blocked 带 note、台账≠执行。内容与工具 description 一致，仅抬升"主动触发"的优先级。
+
+- **与其他注入不冲突**：IM 通道的 `GroupSystemPrompt` 落在 base system prompt，本段追加在其后，
+  纯叠加不覆盖；对内置 runtime 与 Codex runtime 均生效。
+- **如需关闭**：在部署配置里对该插件入口设 `hooks.allowPromptInjection: false`（默认放行）：
+
+  ```jsonc
+  {
+    "plugins": {
+      "entries": {
+        "xg-harness-tools": { "hooks": { "allowPromptInjection": false } }
+      }
+    }
+  }
+  ```
+
+- 若部署方同时手工把 `docs/09-plan-usage-guide.md` 的 System Prompt 模版写进 AGENTS.md/频道
+  systemPrompt，会与本段叠加——冗余无害，可按需取舍。
+
 ## 部署 checklist
 
 - [ ] Node ≥ 22.19.0

package/dist/index.d.ts

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

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAiBA,wBAqDG"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAmBA,QAAA,MAAM,WAAW,kEAqDf,CAAC;AAUH,eAAe,WAAW,CAAC"}

package/dist/index.js

@@ -4,8 +4,9 @@ import { PLAN_WRITE_DESCRIPTION, PlanWriteParams, buildPlanWriteTool } from "./p
 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";
+import { buildPlanPromptInjection } from "./plan-prompt.js";
 const PLUGIN_ID = "xg-harness-tools";
-export default defineToolPlugin({
+const pluginEntry = defineToolPlugin({
     id: PLUGIN_ID,
     name: "XG Harness Tools",
     description: "企业工具插件：计划管理与通用动作分发（plan_write / plan_view / action_dispatch）",
@@ -54,3 +55,11 @@ export default defineToolPlugin({
         ];
     },
 });
+// defineToolPlugin 只负责工具注册；主动建计划纪律以 before_prompt_build hook 追加到 system prompt。
+// 就地覆写 register（保留 tool-plugin metadata），先走原工具注册，再挂 prompt 注入。
+const baseRegister = pluginEntry.register;
+pluginEntry.register = (api) => {
+    baseRegister(api);
+    api.on("before_prompt_build", buildPlanPromptInjection);
+};
+export default pluginEntry;

package/dist/plan-prompt.d.ts

@@ -0,0 +1,13 @@
+import type { PluginHookBeforePromptBuildResult } from "openclaw/plugin-sdk/types";
+/**
+ * 追加到 agent system prompt 的"主动建计划"纪律（appendSystemContext）。
+ * 与 IM 通道的 GroupSystemPrompt 纯叠加不冲突：本段拼在 base systemPrompt 之后。
+ * 保持稳定文本，利于 provider 缓存。
+ */
+export declare const PLAN_FIRST_SYSTEM_CONTEXT: string;
+/**
+ * before_prompt_build 钩子处理器：向 agent system prompt 追加主动建计划纪律。
+ * 返回 void 语义由宿主管控，插件侧始终返回该静态段。
+ */
+export declare function buildPlanPromptInjection(): PluginHookBeforePromptBuildResult;
+//# sourceMappingURL=plan-prompt.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"plan-prompt.d.ts","sourceRoot":"","sources":["../src/plan-prompt.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iCAAiC,EAAE,MAAM,2BAA2B,CAAC;AAEnF;;;;GAIG;AACH,eAAO,MAAM,yBAAyB,QAO1B,CAAC;AAEb;;;GAGG;AACH,wBAAgB,wBAAwB,IAAI,iCAAiC,CAE5E"}

package/dist/plan-prompt.js

@@ -0,0 +1,20 @@
+/**
+ * 追加到 agent system prompt 的"主动建计划"纪律（appendSystemContext）。
+ * 与 IM 通道的 GroupSystemPrompt 纯叠加不冲突：本段拼在 base systemPrompt 之后。
+ * 保持稳定文本，利于 provider 缓存。
+ */
+export const PLAN_FIRST_SYSTEM_CONTEXT = [
+    "## 主动工作计划（xg-harness-tools）",
+    "- 开始执行任何多步骤工作之前，应主动调用 xg_plan_write 建立计划，不要等用户要求。",
+    "- 触发情形：目标需要两个或更多连续动作；预计跨多轮或中断后继续；需等待用户、审批或外部系统。",
+    "- 工作流：开工前建计划 → 每完成一项用 xg_plan_write 整张重交回写状态 → 全部完成提交最终版。",
+    "- 无法当场完成：标 in_progress 或 blocked（blocked 必须带 note 写明原因），后续回合继续。",
+    "- xg_plan_write / xg_plan_view 只是台账，不执行、不调度、无后台运行；保存/查看之后必须继续逐项实际执行任务。",
+].join("\n");
+/**
+ * before_prompt_build 钩子处理器：向 agent system prompt 追加主动建计划纪律。
+ * 返回 void 语义由宿主管控，插件侧始终返回该静态段。
+ */
+export function buildPlanPromptInjection() {
+    return { appendSystemContext: PLAN_FIRST_SYSTEM_CONTEXT };
+}

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

@@ -1 +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"}
+{"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,QAStB,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-view-tool.js

@@ -13,6 +13,7 @@ export const PLAN_VIEW_DESCRIPTION = [
     "- 带 planId：返回该计划当前的完整清单。",
     "- 不带 planId：返回最近计划的摘要列表，用于忘记或跨会话找回 planId。",
     "",
+    "若当前要推进的工作还没有对应计划，应先调用 xg_plan_write 建立计划再开始执行。",
     "重要：查看不等于执行。若计划存在未完成任务，你必须继续实际执行它们，完成一项后用 xg_plan_write 回写状态。",
 ].join("\n");
 function summarizePlan(plan) {

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,QA4BvB,CAAC;AA0Eb,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,SAAS,EAAE,MAAM,CAAC,EAAE,UAAU,GAAG,YAAY,CA0HtF"}

package/dist/plan-write-tool.js

@@ -33,17 +33,21 @@ export const PlanWriteParams = Type.Object({
     cancel: Type.Optional(Type.Boolean({ description: "取消该计划；true 时只需带 planId，不带 goal/tasks" })),
 }, { additionalProperties: false });
 export const PLAN_WRITE_DESCRIPTION = [
-    "用途：维护一份对用户可见、可跨回合保存的任务清单。每次调用都是整张替换，不是增量更新。",
+    "用途：为用户可见、可跨回合保存的工作创建或更新任务清单。每次调用都是整张替换，不是增量更新。",
     "",
-    "何时不用（除非用户明确要求追踪）：",
-    "- 纯问答、查询、解释或闲聊。",
-    "- 一两个动作即可完成，或预计当前回合可以直接做完。",
-    "- 不要把分析、思考和试错过程写成 task；只记录需要向用户展示的工作项。",
+    "【主动建计划：不要等用户要求】",
+    "识别到以下任一情形，都应主动调用本工具建立计划，而不是仅用文字回复或直接闷头推进：",
+    "- 目标需要两个或更多连续动作才能完成。",
+    "- 预计需要多轮推进，或可能中断后继续（跨回合/跨天）。",
+    "- 需要等待人的回复、审批或外部系统。",
+    "- 用户交代的是一个完整工作目标，而非单个简单问题。",
+    "",
+    "工作流：开工前先建计划 → 每完成一项就整张重交更新状态 → 全部完成后提交最终版本。",
     "",
-    "何时用：",
-    "- 工作有 3 个以上可独立完成的任务，且预计需要多轮推进或中断后继续。",
-    "- 需要等待人的回复、审批或外部系统，即使任务较少。",
-    "- 用户明确要求任务清单或进度追踪。",
+    "无需建计划的窄例外：",
+    "- 纯单轮问答、查询、解释概念，不产生需要跟踪的工作。",
+    "- 单个动作在当前回合即可直接完成。",
+    "- 不要把分析、思考和试错过程写成 task；只记录需要向用户展示的工作项。",
     "",
     "执行纪律（必须遵守）：",
     "- 本工具只把计划清单落库：不执行、不调度、无后台运行。保存计划 ≠ 完成工作。",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xgjktech/xg-openclaw-harness-tools",
-  "version": "0.4.0",
+  "version": "0.4.2",
   "description": "企业工具插件：plan_write / plan_view / action_dispatch（OpenClaw 第三方工具插件）",
   "license": "MIT",
   "type": "module",