@xgjktech/xg-openclaw-harness-tools 0.1.0 → 0.3.0

package/README.md

@@ -3,26 +3,22 @@
 OpenClaw 第三方工具插件：企业计划工具 `xg_plan_write` / `xg_plan_execute`。
 
 用一份持久化的计划（SQLite 落盘）取代内置 `update_plan`（无状态、只回显、不落库），
-并把推进进度尽力而为地通知到相关会话/群。
+`xg_plan_write` 整张维护草稿计划，`xg_plan_execute` 只读查看计划或最近摘要。
 
 ## 架构裁决：实时事件当前处于事实性休眠（务必先读）
 
-**当前 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）。
+**当前 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 读取**——用 `openPlanStoreReadonly(dbPath)` 只读反查 `<stateDir>/xgjktech/plans.sqlite`，
-   这是权威、始终正确的状态源（工具每次推进都先落盘、落盘成功才尝试发事件，见 `03-工具契约.md` §2.5）。
+1. **SQLite 读取**——IM 用 `openPlanStoreReadonly(dbPath)` 按 origin 只读反查
+   `<stateDir>/xgjktech/plans.sqlite` 并推送全量快照，这是权威状态源。
 2. **agent 最终回复**——agent 完成任务后的文本回复本身会体现进度。
 
-事件契约（`PlanEventPayload` / `isPlanEventPayload` / `planEventStream`）已按正式设计原样实现并保留，
-**不是搁置未完成**，而是"契约就绪、通路等待宿主开放"：一旦未来某个 OpenClaw 版本给插件暴露了
-获取当次 `runId` 的 API，事件推送即可在**不改本插件代码**的前提下自动激活（`notify.ts` 的判断只看
-`payload.runId` 是否非空）。
+事件契约（`PlanEventPayload` / `isPlanEventPayload` / `planEventStream`）在 shared 中原样保留，
+仅用于下游编译兼容。未来恢复实时事件需要重新实现工具侧生产与 IM 侧消费，并单独发布。
 
 ## 环境要求
 
@@ -94,15 +90,13 @@ P1 阶段不锁死具体安装命令，避免与实际安装流程漂移（详
 
 ### `xg_plan_write`
 
-编写/覆盖一份完整计划（goal + tasks[]，task 可含 steps[]），写入 SQLite。用于任务开始时
-建立计划，或对既有计划做整体重写。
+整张创建或覆盖一份草稿计划（goal + tasks[]）并写入 SQLite。更新时必须重交所有要保留的
+task；写入 schema 不接受 steps，但读取旧计划仍兼容旧 steps 数据。
 
 ### `xg_plan_execute`
 
-推进一份已保存计划的单个状态（`start_task` / `complete_task` / `block_task` /
-`start_step` / `complete_step`），每次一步。落盘顺序：**先读最新状态 → 应用动作 →
-不变量校验 → 落盘 → 尽力而为发事件**（先落盘、事件不影响主流程成败）。`block_task`
-必须携带非空 `note` 说明阻塞原因。
+只读查看计划。带 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`。
@@ -128,25 +122,23 @@ P1 阶段不锁死具体安装命令，避免与实际安装流程漂移（详
 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，确认落盘内容与预期一致。
+5. 调用一次 `xg_plan_write` 建一份最小计划，确认返回 `planId + view`；再用该 planId 调
+   `xg_plan_execute`，确认只读 view 一致。用 `openPlanStoreReadonly` 反查并核对落盘内容。
 
 **本项在本次交付中未在真实 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 步实测。
+- 当前 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`）跑通了完整的
-  写入→推进→落盘→只读反查链路，但同样不经过 OpenClaw 的工具 allowlist/deny 策略引擎。
+  写入→整张重交→execute 只读查看→SQLite 只读反查链路，但同样不经过 OpenClaw 的工具
+  allowlist/deny 策略引擎。
 
 **结论：部署方在生产环境落实上述配置后，必须按"实机验证步骤"重新执行一次实拉 agent 验证，
 不能以本仓库现有的 mock/集成测试结果代替。**

package/dist/index.d.ts.map

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

package/dist/index.js

@@ -2,11 +2,12 @@ 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";
+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）",
+    description: "企业工具插件：计划编写与查看（plan_write / plan_execute）",
     tools: (tool) => {
         // store 单例：defineToolPlugin 的 tools(...) 只在插件加载时调用一次，
         // 闭包在此建一次即可；factory 本身会在每次 agent attempt 重建工具集时重新调用。
@@ -25,35 +26,15 @@ export default defineToolPlugin({
                 description: PLAN_WRITE_DESCRIPTION,
                 parameters: PlanWriteParams,
                 optional: true,
-                factory: ({ api }) => buildPlanWriteTool(getStore(api)),
+                factory: ({ api, toolContext }) => buildPlanWriteTool(getStore(api), toPlanOrigin(toolContext)),
             }),
             tool({
                 name: "xg_plan_execute",
-                label: "【xg-harness】推进计划",
+                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 }
-                            : {}),
-                    },
-                }),
+                factory: ({ api }) => buildPlanExecuteTool({ store: getStore(api) }),
             }),
         ];
     },

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

@@ -1,26 +1,12 @@
 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";
+import type { PlanStore } from "@xgjktech/xg-openclaw-shared";
 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>;
+    planId: 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

@@ -1 +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"}
+{"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,KAAK,EAAE,SAAS,EAAe,MAAM,8BAA8B,CAAC;AAI3E,eAAO,MAAM,iBAAiB;;EAK7B,CAAC;AAEF,MAAM,MAAM,kBAAkB,GAAG,MAAM,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAElE,eAAO,MAAM,wBAAwB,QAOzB,CAAC;AAOb,wBAAgB,oBAAoB,CAAC,IAAI,EAAE;IAAE,KAAK,EAAE,SAAS,CAAA;CAAE,GAAG,YAAY,CAsC7E"}

package/dist/plan-execute-tool.js

@@ -1,156 +1,47 @@
 import { Type } from "typebox";
-import { assertPlanInvariants, PlanInvariantError, } from "@xgjktech/xg-openclaw-shared";
+import { renderPlanView } from "./plan-view.js";
 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 时必填，说明阻塞原因；其他动作可选备注" })),
+    planId: Type.Optional(Type.String({ description: "要查看的计划 id；留空则列出最近计划" })),
 }, { additionalProperties: false });
 export const PLAN_EXECUTE_DESCRIPTION = [
-    "用途：推进一份已保存的计划，一次推进一步，并把进度实时通知到相关会话/群。",
+    "用途：只读查看已保存的计划；不执行任务，也不修改计划。",
     "",
-    "执行纪律（务必遵守）：",
-    "- 一次一步：同一时刻整份计划最多一个进行中的 task，task 内最多一个进行中的 step。",
-    "  想开始新任务前，先把当前任务收尾（completed 或 blocked）。",
-    "- 验证后才 completed：只有真正做完并验证通过，才把 task/step 标 completed；",
-    "  没验证就别标完成。",
-    "- 遇阻塞就停下并记录：卡住时用 action=block_task 并在 note 写清楚卡在哪、需要谁/什么才能继续，",
-    "  不要绕过、不要假装完成。阻塞会被推送到群里等人回复——这正是本工具的价值。",
+    "- 带 planId：返回该计划当前的完整清单。",
+    "- 不带 planId：返回最近计划的摘要列表，用于忘记或跨会话找回 planId。",
     "",
-    "参数：planId + action + taskIndex（+ 视情况 stepIndex / note）。",
-    "每次成功推进都会落盘并发出进度事件；调用方无需手动通知。",
+    "需要更新进度时，用 xg_plan_write 重新提交整张计划。",
 ].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;
+    const { store } = deps;
     return {
         name: "xg_plan_execute",
-        label: "【xg-harness】推进计划",
+        label: "【xg-harness】查看计划",
         description: PLAN_EXECUTE_DESCRIPTION,
         parameters: PlanExecuteParams,
         async execute(_toolCallId, rawParams) {
             const params = rawParams;
             try {
+                if (params.planId === undefined) {
+                    const result = { ok: true, plans: store.list().slice(0, 10) };
+                    return toolJsonResult(result);
+                }
                 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",
+                const result = {
+                    ok: true,
                     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 } : {}),
+                    view: renderPlanView(plan),
                 };
-                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) },
+                    error: { code: "STORE_ERROR", detail: String(e.message) },
                 };
                 return toolJsonResult(result);
             }

package/dist/plan-origin.d.ts

@@ -0,0 +1,9 @@
+import type { PlanOrigin } from "@xgjktech/xg-openclaw-shared";
+/** 从工具工厂 ctx 采集来源上下文。全字段皆空时返回 undefined（不落空对象）。 */
+export declare function toPlanOrigin(toolContext: {
+    sessionKey?: string;
+    messageChannel?: string;
+    agentAccountId?: string;
+    deliveryContext?: unknown;
+}): PlanOrigin | undefined;
+//# sourceMappingURL=plan-origin.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"plan-origin.d.ts","sourceRoot":"","sources":["../src/plan-origin.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,8BAA8B,CAAC;AAa/D,mDAAmD;AACnD,wBAAgB,YAAY,CAAC,WAAW,EAAE;IACxC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B,GAAG,UAAU,GAAG,SAAS,CAuBzB"}

package/dist/plan-origin.js

@@ -0,0 +1,33 @@
+function nonEmptyString(value) {
+    return typeof value === "string" && value.trim() !== "" ? value : undefined;
+}
+function readDeliveryField(deliveryContext, field) {
+    if (typeof deliveryContext !== "object" || deliveryContext === null || Array.isArray(deliveryContext)) {
+        return undefined;
+    }
+    return deliveryContext[field];
+}
+/** 从工具工厂 ctx 采集来源上下文。全字段皆空时返回 undefined（不落空对象）。 */
+export function toPlanOrigin(toolContext) {
+    const deliveryContext = toolContext.deliveryContext;
+    const channel = nonEmptyString(readDeliveryField(deliveryContext, "channel")) ??
+        nonEmptyString(toolContext.messageChannel);
+    const to = nonEmptyString(readDeliveryField(deliveryContext, "to"));
+    const accountId = nonEmptyString(readDeliveryField(deliveryContext, "accountId")) ??
+        nonEmptyString(toolContext.agentAccountId);
+    const rawThreadId = readDeliveryField(deliveryContext, "threadId");
+    const threadId = typeof rawThreadId === "number" ? String(rawThreadId) : nonEmptyString(rawThreadId);
+    const sessionKey = nonEmptyString(toolContext.sessionKey);
+    const origin = {};
+    if (channel !== undefined)
+        origin.channel = channel;
+    if (to !== undefined)
+        origin.to = to;
+    if (accountId !== undefined)
+        origin.accountId = accountId;
+    if (threadId !== undefined)
+        origin.threadId = threadId;
+    if (sessionKey !== undefined)
+        origin.sessionKey = sessionKey;
+    return Object.keys(origin).length === 0 ? undefined : origin;
+}

package/dist/plan-view.d.ts

@@ -0,0 +1,3 @@
+import type { Plan } from "@xgjktech/xg-openclaw-shared";
+export declare function renderPlanView(plan: Plan): string;
+//# sourceMappingURL=plan-view.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"plan-view.d.ts","sourceRoot":"","sources":["../src/plan-view.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAA0B,MAAM,8BAA8B,CAAC;AAoBjF,wBAAgB,cAAc,CAAC,IAAI,EAAE,IAAI,GAAG,MAAM,CAejD"}

package/dist/plan-view.js

@@ -0,0 +1,26 @@
+const TASK_STATUS_MARKERS = {
+    pending: "[ ]",
+    in_progress: "[>]",
+    completed: "[x]",
+    blocked: "[!]",
+};
+const STEP_STATUS_MARKERS = {
+    pending: "[ ]",
+    in_progress: "[>]",
+    completed: "[x]",
+};
+/** view 依赖"一行一项"的格式约定；字段内容里的换行统一压成空格，防止伪造出多余的行。 */
+function singleLine(text) {
+    return text.replace(/\s*\r?\n\s*/g, " ");
+}
+export function renderPlanView(plan) {
+    const lines = [`goal: ${singleLine(plan.goal)}`];
+    plan.tasks.forEach((task, taskIndex) => {
+        const note = task.note !== undefined ? ` | note: ${singleLine(task.note)}` : "";
+        lines.push(`T${taskIndex} ${TASK_STATUS_MARKERS[task.status]} ${singleLine(task.title)}${note}`);
+        task.steps?.forEach((step, stepIndex) => {
+            lines.push(`  T${taskIndex}.S${stepIndex} ${STEP_STATUS_MARKERS[step.status]} ${singleLine(step.text)}`);
+        });
+    });
+    return lines.join("\n");
+}

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

@@ -1,6 +1,6 @@
 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 PlanOrigin, type PlanStore } from "@xgjktech/xg-openclaw-shared";
 export declare const PlanWriteParams: Type.TObject<{
     planId: Type.TOptional<Type.TString>;
     goal: Type.TString;
@@ -8,13 +8,9 @@ export declare const PlanWriteParams: 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;
+export declare function buildPlanWriteTool(store: PlanStore, origin?: PlanOrigin): AnyAgentTool;
 //# sourceMappingURL=plan-write-tool.d.ts.map

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,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"}
+{"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,EAGL,KAAK,UAAU,EACf,KAAK,SAAS,EAGf,MAAM,8BAA8B,CAAC;AA2BtC,eAAO,MAAM,eAAe;;;;;;;;EAiB3B,CAAC;AAEF,MAAM,MAAM,gBAAgB,GAAG,MAAM,CAAC,OAAO,eAAe,CAAC,CAAC;AAE9D,eAAO,MAAM,sBAAsB,QAkBvB,CAAC;AAwCb,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,SAAS,EAAE,MAAM,CAAC,EAAE,UAAU,GAAG,YAAY,CA2CtF"}

package/dist/plan-write-tool.js

@@ -1,48 +1,54 @@
 import { randomUUID } from "node:crypto";
 import { Type } from "typebox";
-import { assertPlanInvariants, PlanInvariantError, } from "@xgjktech/xg-openclaw-shared";
+import { assertPlanInvariants, } 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 });
+import { renderPlanView } from "./plan-view.js";
 const TaskInput = Type.Object({
-    title: Type.String({ minLength: 1, description: "任务标题，bite-size，单次可完成并验证" }),
+    title: Type.String({
+        minLength: 1,
+        maxLength: 200,
+        description: "能判断是否完成的具体任务",
+    }),
     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: "可选子步骤" })),
+    note: Type.Optional(Type.String({ maxLength: 1000, description: "备注；blocked 时写明原因" })),
 }, { 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: "任务清单，至少一项" }),
+    planId: Type.Optional(Type.String({ maxLength: 128, description: "留空=新建；填写=整张覆盖该计划" })),
+    goal: Type.String({
+        minLength: 1,
+        maxLength: 500,
+        description: "计划总目标，一句话说明完成态",
+    }),
+    tasks: Type.Array(TaskInput, {
+        minItems: 1,
+        maxItems: 20,
+        description: "完整任务清单；更新时未提交的旧任务会被删除",
+    }),
 }, { additionalProperties: false });
 export const PLAN_WRITE_DESCRIPTION = [
-    "用途：把一项工作拆成一份可执行计划并持久化保存（跨回合、跨天不丢失）。",
+    "用途：维护一份对用户可见、可跨回合保存的任务清单。每次调用都是整张替换，不是增量更新。",
     "",
-    "何时用：接到多步骤任务、需要先规划再动手时，先用本工具写下计划。",
+    "何时不用（除非用户明确要求追踪）：",
+    "- 纯问答、查询、解释或闲聊。",
+    "- 一两个动作即可完成，或预计当前回合可以直接做完。",
+    "- 不要把分析、思考和试错过程写成 task；只记录需要向用户展示的工作项。",
     "",
-    "编写纪律（务必遵守）：",
-    "- Bite-size：每个 task 是一次可独立完成并验证的最小工作单元，别写成大而空的阶段。",
-    "- 无占位符：task/step 文案必须是具体动作，禁止 \"TODO/待定/等等\" 这类占位。",
-    "- 可验证：每个 task 应能明确判断\"做完没有\"，把验证方式写进 title 或 note。",
-    "- 顺序清晰：tasks 按依赖顺序排列，读者不需要猜先后。",
+    "何时用：",
+    "- 工作有 3 个以上可独立完成的任务，且预计需要多轮推进或中断后继续。",
+    "- 需要等待人的回复、审批或外部系统，即使任务较少。",
+    "- 用户明确要求任务清单或进度追踪。",
     "",
-    "参数：goal=总目标；tasks=任务清单（含可选 steps 子步骤）。",
-    "留空 planId=新建（返回新 planId 供后续 plan_execute 使用）；填 planId=整体改写。",
-    "不要在这里推进状态——推进用 xg_plan_execute。",
+    "提交规则：",
+    "- 新建时不传 planId；更新时传入原 planId。",
+    "- 更新时必须重新提交 goal 和所有要保留的 tasks，包括未变化任务及其当前 status/note。只提交变化项会删除其他任务；记不清时先用 xg_plan_execute 查看。",
+    "- goal 用一句话；tasks 通常 3-7 项，每项是能判断是否完成的具体动作，不写 TODO、待定或内部思考。",
+    "- status 为 pending、in_progress、completed 或 blocked。通常只有一项 in_progress，确实并行时可以有多项；blocked 时必须用 note 写明原因和继续所需条件。",
 ].join("\n");
-function toStep(input) {
-    return {
-        text: input.text,
-        status: (input.status ?? "pending"),
-    };
-}
 function toTask(input) {
     const task = {
         title: input.title,
@@ -51,22 +57,26 @@ function toTask(input) {
     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) {
+function buildPlan(params, existing, planId, origin) {
     const now = new Date().toISOString();
-    return {
+    const plan = {
         planId,
         goal: params.goal,
         createdAt: existing?.createdAt ?? now,
         updatedAt: now,
         tasks: params.tasks.map(toTask),
     };
+    // 改写已有计划时保留原 origin（改写是内容编辑，不是重新发起）；
+    // 仅当旧计划本就没有 origin（旧数据补齐）才写入本次采集到的 origin。
+    const resolvedOrigin = existing !== undefined ? (existing.origin ?? origin) : origin;
+    if (resolvedOrigin !== undefined) {
+        plan.origin = resolvedOrigin;
+    }
+    return plan;
 }
-export function buildPlanWriteTool(store) {
+export function buildPlanWriteTool(store, origin) {
     return {
         name: "xg_plan_write",
         label: "【xg-harness】编写计划",
@@ -87,17 +97,20 @@ export function buildPlanWriteTool(store) {
                     }
                 }
                 const planId = params.planId ?? randomUUID();
-                const plan = buildPlan(params, existing, planId);
+                const plan = buildPlan(params, existing, planId, origin);
                 assertPlanInvariants(plan);
                 store.set(plan);
-                const result = { ok: true, planId: plan.planId, plan };
+                const result = {
+                    ok: true,
+                    planId: plan.planId,
+                    view: renderPlanView(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) },
+                    error: { code: "STORE_ERROR", detail: String(e.message) },
                 };
                 return toolJsonResult(result);
             }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xgjktech/xg-openclaw-harness-tools",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "企业工具插件：plan_write / plan_execute 计划工具（OpenClaw 第三方工具插件）",
   "license": "MIT",
   "type": "module",
@@ -27,7 +27,7 @@
   },
   "dependencies": {
     "typebox": "1.1.39",
-    "@xgjktech/xg-openclaw-shared": "^0.1.0"
+    "@xgjktech/xg-openclaw-shared": "^0.2.1"
   },
   "devDependencies": {
     "@types/node": "^22.19.0",

package/dist/notify.d.ts

@@ -1,16 +0,0 @@
-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

@@ -1 +0,0 @@
-{"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

@@ -1,20 +0,0 @@
-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 } : {}),
-    });
-}