@zhushanwen/pi-canvas 0.0.0-stage → 0.2.0

package/src/__tests__/tool-execute.test.ts

@@ -0,0 +1,381 @@
+// tool-execute.test.ts —— 工具 execute 的 marker 往返与错误闭环（设计 §3.1(2) 通道）：
+// 宿主门 / 参数分派 / marker 载荷形状 / enter 引导协议 / mutate 拒绝与通道错误 throw。
+
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+import { CANVAS_MARKER } from "@zhushanwen/extension-protocol";
+
+import {
+  lastMarkerCall,
+  mountCanvas,
+  toolOf,
+  withExtLogEnv,
+  type ToolHarness,
+} from "./helpers/canvas-harness.js";
+
+describe("宿主门（select 前置，禁超时探测）", () => {
+  let harness: ToolHarness;
+  beforeEach(() => {
+    harness = mountCanvas();
+  });
+
+  it("env 缺失：抛「画布需要 taiji 宿主」，select 未被调用", async () => {
+    await withExtLogEnv(undefined, async () => {
+      const enter = toolOf(harness, "canvas_enter");
+      await expect(
+        enter.execute("t1", { statement: "s", criterias: ["c"], scope: [] }, undefined, undefined, harness.ctx),
+      ).rejects.toThrow("画布需要 taiji 宿主");
+      expect(harness.selectMock).not.toHaveBeenCalled();
+    });
+  });
+
+  it("env=1 但 mode=tui：拒绝进入 select（env 泄漏形态）", async () => {
+    await withExtLogEnv("1", async () => {
+      const read = toolOf(harness, "canvas_read");
+      await expect(
+        read.execute("t1", { canvasId: "c1" }, undefined, undefined, {
+          ...harness.ctx,
+          mode: "tui" as const,
+        }),
+      ).rejects.toThrow("画布需要 taiji 宿主");
+      expect(harness.selectMock).not.toHaveBeenCalled();
+    });
+  });
+});
+
+describe("canvas_enter 双形态 marker 往返", () => {
+  let harness: ToolHarness;
+  beforeEach(() => {
+    harness = mountCanvas();
+  });
+
+  it("创建形态：payload={action:'create', params:{statement,criterias,scopeExclusions}}（scope→scopeExclusions 映射），结果文本带工具检索引导", async () => {
+    await withExtLogEnv("1", async () => {
+      harness.selectMock.mockResolvedValue(
+        JSON.stringify({ ok: true, eventId: "e1", evType: "CanvasCreated", summary: "created" }),
+      );
+      const enter = toolOf(harness, "canvas_enter");
+      const result = (await enter.execute(
+        "t1",
+        { statement: "多引擎支持怎么落地", criterias: ["c1"], scope: ["不做 UI"] },
+        undefined,
+        undefined,
+        harness.ctx,
+      )) as { content: Array<{ type: string; text: string }> };
+      const call = lastMarkerCall(harness.selectMock);
+      expect(call.marker).toBe(CANVAS_MARKER);
+      expect(call.payload).toEqual({
+        action: "create",
+        params: { statement: "多引擎支持怎么落地", criterias: ["c1"], scopeExclusions: ["不做 UI"] },
+      });
+      expect(result.content[0].text).toContain("tool_search");
+      expect(result.content[0].text).toContain("canvas_edit / canvas_read / canvas_review / canvas_export");
+    });
+  });
+
+  it("创建形态 name 可选透传；打开形态 payload={action:'enter', params:{canvasId}}", async () => {
+    await withExtLogEnv("1", async () => {
+      harness.selectMock.mockResolvedValue(JSON.stringify({ canvasId: "c9", name: "n", nodes: [] }));
+      const enter = toolOf(harness, "canvas_enter");
+      await enter.execute("t1", { canvasId: "c9" }, undefined, undefined, harness.ctx);
+      expect(lastMarkerCall(harness.selectMock).payload).toEqual({ action: "enter", params: { canvasId: "c9" } });
+    });
+  });
+
+  it("两形态互斥：canvasId 与 statement 同传 → 结构化错误，不进入 select", async () => {
+    await withExtLogEnv("1", async () => {
+      const enter = toolOf(harness, "canvas_enter");
+      await expect(
+        enter.execute(
+          "t1",
+          { canvasId: "c1", statement: "s", criterias: ["c"], scope: [] },
+          undefined,
+          undefined,
+          harness.ctx,
+        ),
+      ).rejects.toThrow("invalid_params");
+      expect(harness.selectMock).not.toHaveBeenCalled();
+    });
+  });
+
+  it("缺创建三要素 → 结构化错误（invalid_params + 恢复动作）", async () => {
+    await withExtLogEnv("1", async () => {
+      const enter = toolOf(harness, "canvas_enter");
+      await expect(
+        enter.execute("t1", {}, undefined, undefined, harness.ctx),
+      ).rejects.toThrow("恢复动作");
+      await expect(
+        enter.execute("t1", { statement: "s" }, undefined, undefined, harness.ctx),
+      ).rejects.toThrow("invalid_params");
+      expect(harness.selectMock).not.toHaveBeenCalled();
+    });
+  });
+});
+
+describe("canvas_edit 五 action 分派", () => {
+  let harness: ToolHarness;
+  beforeEach(() => {
+    harness = mountCanvas();
+  });
+
+  it("grow：payload 按契约组装（batch/reason 透传）", async () => {
+    await withExtLogEnv("1", async () => {
+      harness.selectMock.mockResolvedValue(JSON.stringify({ ok: true, eventId: "e2", evType: "NodeCreated", summary: "grown" }));
+      const edit = toolOf(harness, "canvas_edit");
+      const batch = [{ id: "n1", type: "question", content: "q", attachTo: "root", edge: "decompose" }];
+      await edit.execute(
+        "t1",
+        { action: "grow", growParams: { canvasId: "c1", batch, reason: "MECE 分解" } },
+        undefined,
+        undefined,
+        harness.ctx,
+      );
+      expect(lastMarkerCall(harness.selectMock).payload).toEqual({
+        action: "grow",
+        params: { canvasId: "c1", batch, reason: "MECE 分解" },
+      });
+    });
+  });
+
+  it("grow：argument 条目携带 materiality='fact' → payload 透传且过契约守卫（素材性声明通道）", async () => {
+    await withExtLogEnv("1", async () => {
+      harness.selectMock.mockResolvedValue(JSON.stringify({ ok: true, eventId: "e2b", evType: "NodeCreated", summary: "grown" }));
+      const edit = toolOf(harness, "canvas_edit");
+      const batch = [
+        {
+          id: "arg-1",
+          type: "argument",
+          content: "实测数据支撑",
+          attachTo: "opt-1",
+          edge: "argue",
+          edgePolarity: "support",
+          materiality: "fact",
+        },
+      ];
+      await edit.execute(
+        "t1",
+        { action: "grow", growParams: { canvasId: "c1", batch, reason: "补充证据" } },
+        undefined,
+        undefined,
+        harness.ctx,
+      );
+      expect(lastMarkerCall(harness.selectMock).payload).toEqual({
+        action: "grow",
+        params: { canvasId: "c1", batch, reason: "补充证据" },
+      });
+    });
+  });
+
+  it("action 与参数块缺失 → 结构化错误（五 action 各自报块名）", async () => {
+    await withExtLogEnv("1", async () => {
+      const edit = toolOf(harness, "canvas_edit");
+      for (const [action, block] of [
+        ["grow", "growParams"],
+        ["patch", "patchParams"],
+        ["select", "selectParams"],
+        ["transition", "transitionParams"],
+        ["comment-respond", "commentRespondParams"],
+      ] as const) {
+        await expect(
+          edit.execute("t1", { action }, undefined, undefined, harness.ctx),
+        ).rejects.toThrow(block);
+      }
+      expect(harness.selectMock).not.toHaveBeenCalled();
+    });
+  });
+});
+
+describe("canvas_review / canvas_export / canvas_list 转译", () => {
+  let harness: ToolHarness;
+  beforeEach(() => {
+    harness = mountCanvas();
+  });
+
+  it("review resolve：payload={action:'review-resolve', params 透传}", async () => {
+    await withExtLogEnv("1", async () => {
+      harness.selectMock.mockResolvedValue(JSON.stringify({ ok: true, eventId: "e3", evType: "ReviewEntryResolved", summary: "r" }));
+      const review = toolOf(harness, "canvas_review");
+      await review.execute(
+        "t1",
+        { action: "resolve", resolveParams: { canvasId: "c1", entryId: "rv-1", disposition: "accepted", note: "已修" } },
+        undefined,
+        undefined,
+        harness.ctx,
+      );
+      expect(lastMarkerCall(harness.selectMock).payload).toEqual({
+        action: "review-resolve",
+        params: { canvasId: "c1", entryId: "rv-1", disposition: "accepted", note: "已修" },
+      });
+    });
+  });
+
+  it("review append：payload={action:'review-append', params 透传}", async () => {
+    await withExtLogEnv("1", async () => {
+      harness.selectMock.mockResolvedValue(JSON.stringify({ ok: true, eventId: "e4", evType: "ReviewEntryAppended", summary: "a" }));
+      const review = toolOf(harness, "canvas_review");
+      await review.execute(
+        "t1",
+        {
+          action: "append",
+          appendParams: {
+            canvasId: "c1",
+            round: 1,
+            entries: [{ id: "rv-1", dimension: "support", severity: "must-fix", targetId: "n1", note: "悬空" }],
+          },
+        },
+        undefined,
+        undefined,
+        harness.ctx,
+      );
+      expect(lastMarkerCall(harness.selectMock).payload).toEqual({
+        action: "review-append",
+        params: {
+          canvasId: "c1",
+          round: 1,
+          // 契约收口：逐条注入 round（CanvasReviewEntryInput 幂等锚点）
+          entries: [{ id: "rv-1", dimension: "support", severity: "must-fix", targetId: "n1", note: "悬空", round: 1 }],
+        },
+      });
+    });
+  });
+
+  it("review run：达上限停回（read 后 review.status=max-rounds）→ 短路返回停回说明，不派 reviewer", async () => {
+    await withExtLogEnv("1", async () => {
+      // marker 两跳：review-request（达上限 = 合法终态转移，mutate 成功）→ read（max-rounds 态）
+      harness.selectMock
+        .mockResolvedValueOnce(JSON.stringify({ ok: true, eventId: "e6", evType: "ReviewRequested", summary: "已达轮次上限（5 轮）：已置终态 max-rounds 停回用户" }))
+        .mockResolvedValueOnce(
+          JSON.stringify({
+            canvasId: "c1",
+            name: "多引擎支持",
+            root: { nodeId: "root", statement: "s", criterias: ["c"], scopeExclusions: [] },
+            direction: null,
+            nodes: [],
+            edges: [],
+            comments: [],
+            dirtyPaths: [],
+            review: {
+              status: "max-rounds",
+              round: 5,
+              maxRounds: 5,
+              entries: [],
+              stopNote: "审查已达轮次上限（5 轮）未收敛，停回用户裁决",
+              recoverHint: "升级裁决（扩大审查范围或修改完成判据）后重新发起审查（画布「发起审查」入口，用户操作）",
+            },
+            converged: false,
+            createdAt: "2026-10-15T00:00:00Z",
+            updatedAt: "2026-10-15T00:00:00Z",
+          }),
+        );
+      // service 槽 = 陷阱：停回态下 reviewer 不得被派发（本轮没有开始）
+      const SLOT_KEY = Symbol.for("@zhushanwen/subagent-core.service");
+      const dispatch = vi.fn();
+      (globalThis as Record<symbol, unknown>)[SLOT_KEY] = { executeAndAwait: dispatch };
+      try {
+        const review = toolOf(harness, "canvas_review");
+        const result = (await review.execute("t1", { action: "run", runParams: { canvasId: "c1" } }, undefined, undefined, harness.ctx)) as {
+          content: Array<{ type: string; text: string }>;
+        };
+        const payload = JSON.parse(result.content[0]!.text) as Record<string, unknown>;
+        expect(payload.stopped).toBe(true);
+        expect(payload.status).toBe("max-rounds");
+        expect(String(payload.stopNote)).toContain("轮次上限");
+        expect(String(payload.recoverHint)).toContain("升级裁决");
+        expect(dispatch).not.toHaveBeenCalled();
+      } finally {
+        delete (globalThis as Record<symbol, unknown>)[SLOT_KEY];
+      }
+    });
+  });
+
+  it("export 需求卡缺 leafId → 结构化错误；planning-doc 正常映射", async () => {
+    await withExtLogEnv("1", async () => {
+      harness.selectMock.mockResolvedValue(JSON.stringify({ ok: true, eventId: "e5", evType: "CanvasExported", summary: "x" }));
+      const exp = toolOf(harness, "canvas_export");
+      await expect(
+        exp.execute("t1", { canvasId: "c1", target: "requirement-card" }, undefined, undefined, harness.ctx),
+      ).rejects.toThrow("invalid_params");
+      await exp.execute("t1", { canvasId: "c1", target: "planning-doc" }, undefined, undefined, harness.ctx);
+      expect(lastMarkerCall(harness.selectMock).payload).toEqual({
+        action: "export",
+        params: { canvasId: "c1", target: { target: "planning-doc" } },
+      });
+    });
+  });
+
+  it("list：空参数 payload，marker 一致", async () => {
+    await withExtLogEnv("1", async () => {
+      harness.selectMock.mockResolvedValue(JSON.stringify({ canvases: [] }));
+      const list = toolOf(harness, "canvas_list");
+      await list.execute("t1", {}, undefined, undefined, harness.ctx);
+      const call = lastMarkerCall(harness.selectMock);
+      expect(call.marker).toBe(CANVAS_MARKER);
+      expect(call.payload).toEqual({ action: "list", params: {} });
+    });
+  });
+});
+
+describe("错误闭环（禁止错误成功模式）", () => {
+  let harness: ToolHarness;
+  beforeEach(() => {
+    harness = mountCanvas();
+  });
+
+  it("mutate 领域拒绝（ok:false）：throw 且消息含错误码与恢复动作", async () => {
+    await withExtLogEnv("1", async () => {
+      harness.selectMock.mockResolvedValue(
+        JSON.stringify({
+          ok: false,
+          error: { code: "selection_conflict", message: "该问题已有选定方案", recover: "换选走 replace 参数" },
+        }),
+      );
+      const edit = toolOf(harness, "canvas_edit");
+      await expect(
+        edit.execute(
+          "t1",
+          {
+            action: "select",
+            selectParams: { canvasId: "c1", questionId: "q1", optionId: "o2", reason: "r" },
+          },
+          undefined,
+          undefined,
+          harness.ctx,
+        ),
+      ).rejects.toThrow(/\[selection_conflict\].*恢复动作/s);
+    });
+  });
+
+  it("runtime 结构化错误回包（{error,hint}）：throw formatChannelErrorText 形态", async () => {
+    await withExtLogEnv("1", async () => {
+      harness.selectMock.mockResolvedValue(JSON.stringify({ error: "boom", hint: "check runtime" }));
+      const list = toolOf(harness, "canvas_list");
+      await expect(list.execute("t1", {}, undefined, undefined, harness.ctx)).rejects.toThrow("boom");
+    });
+  });
+
+  it("select resolve undefined（取消/超时折叠）：throw，不静默成功", async () => {
+    await withExtLogEnv("1", async () => {
+      harness.selectMock.mockResolvedValue(undefined);
+      const list = toolOf(harness, "canvas_list");
+      await expect(list.execute("t1", {}, undefined, undefined, harness.ctx)).rejects.toThrow(/cancelled or channel error/);
+    });
+  });
+
+  it("非 JSON 回包：throw 协议漂移提示", async () => {
+    await withExtLogEnv("1", async () => {
+      harness.selectMock.mockResolvedValue("<html>gateway</html>");
+      const list = toolOf(harness, "canvas_list");
+      await expect(list.execute("t1", {}, undefined, undefined, harness.ctx)).rejects.toThrow(/non-JSON/);
+    });
+  });
+
+  it("无墙钟超时：select 选项不携带 timeout（任务级正常路径不设时限）", async () => {
+    await withExtLogEnv("1", async () => {
+      harness.selectMock.mockResolvedValue(JSON.stringify({ canvases: [] }));
+      const list = toolOf(harness, "canvas_list");
+      await list.execute("t1", {}, undefined, undefined, harness.ctx);
+      const opts = harness.selectMock.mock.calls[0][2] as { timeout?: number } | undefined;
+      expect(opts?.timeout).toBeUndefined();
+    });
+  });
+});

package/src/__tests__/tool-registration.test.ts

@@ -0,0 +1,59 @@
+// tool-registration.test.ts —— 六工具注册面（设计 §3.1(2)：动词族 6 工具，全 deferred）。
+
+import { describe, expect, it } from "vitest";
+
+import { CANVAS_TOOL_NAMES } from "@zhushanwen/extension-protocol";
+
+import { mountCanvas, toolOf } from "./helpers/canvas-harness.js";
+
+describe("六工具注册面", () => {
+  it("注册 6 个工具，名集与 U1 契约 CANVAS_TOOL_NAMES 一致", () => {
+    const { registered } = mountCanvas();
+    expect(registered).toHaveLength(6);
+    expect([...registered].map((t) => t.name).sort()).toEqual([...CANVAS_TOOL_NAMES].sort());
+  });
+
+  it("全部 exposure=deferred（画布低频入口，不设常驻 direct）", () => {
+    const { registered } = mountCanvas();
+    for (const tool of registered) {
+      expect(tool.exposure, `${tool.name} must be deferred`).toBe("deferred");
+    }
+  });
+
+  it("每工具带非空 promptSnippet（deferred 形态下激活后工具索引的精简条目）", () => {
+    // 入口可见性（未激活时的存在信号）由 <available_tools> 常驻段承载
+    // （available-tools.test.ts）；snippet 是激活后工具索引的精简条目
+    const { registered } = mountCanvas();
+    for (const tool of registered) {
+      expect(tool.promptSnippet, `${tool.name} must carry a promptSnippet`).toMatch(/\S/);
+    }
+  });
+
+  it("每工具持有独立 typebox schema（object 形态，非共享引用）", () => {
+    const { registered } = mountCanvas();
+    const schemas = registered.map((t) => t.parameters) as Array<Record<string, unknown>>;
+    for (const schema of schemas) {
+      expect(schema.type).toBe("object");
+      expect(schema.properties).toBeTypeOf("object");
+    }
+    // 独立 schema：两两不同引用
+    for (let i = 0; i < schemas.length; i++) {
+      for (let j = i + 1; j < schemas.length; j++) {
+        expect(schemas[i]).not.toBe(schemas[j]);
+      }
+    }
+  });
+
+  it("canvas_edit grow 条目 schema 与契约 CanvasGrowItem 对齐：含 materiality（claim/fact 词表）、不含 factVerified（agent 不自证核实，fact 创建即未核实）", () => {
+    const harness = mountCanvas();
+    const params = toolOf(harness, "canvas_edit").parameters as Record<string, unknown>;
+    const growProps = ((params.properties as Record<string, unknown>).growParams as Record<string, unknown>)
+      .properties as Record<string, unknown>;
+    const batchItems = (growProps.batch as Record<string, unknown>).items as Record<string, unknown>;
+    const itemProps = batchItems.properties as Record<string, unknown>;
+    expect(Object.keys(itemProps)).toContain("materiality");
+    const materialityEnum = (itemProps.materiality as Record<string, unknown>).enum as string[];
+    expect([...materialityEnum].sort()).toEqual(["claim", "fact"]);
+    expect(Object.keys(itemProps)).not.toContain("factVerified");
+  });
+});

package/src/host.ts

@@ -0,0 +1,25 @@
+/**
+ * taiji GUI 宿主判定与画布工具的前置门（设计 §3.1(2) 宿主检测）。
+ *
+ * 谓词单点在 @zhushanwen/pi-ext-guards（isTaijiGuiHost：env 信号 + ctx.mode === "rpc"
+ * ——env 只证明 taiji runtime 在上游，TUI / json / print 形态宿主没有 marker 路由、
+ * select 会落终端 UI，单查 env 会在 env 泄漏到独立 pi 时误入 select 挂起；禁超时
+ * 探测，对齐时间平抑红线：不做「挂起后超时回退」类时间窗兜底，门必须在 select 之前）。
+ * 本模块 re-export 供六工具与组合根共门 import；env 的双语义耦合登记 SSOT 与拆分
+ * 迁移约束见 ext-guards 谓词分节注释（dmg-r1-7：自本文件与 plan state.ts 双实现收敛，
+ * 一致性由构造保证，不再靠注释互指）。
+ */
+
+export { isTaijiGuiHost } from "@zhushanwen/pi-ext-guards";
+
+/** 非 taiji GUI 宿主的结构化错误（设计：返回「画布需要 taiji 宿主」，不进入 select）。 */
+export function hostGateError(): Error {
+  return new Error(
+    [
+      "canvas_unavailable_host: 画布需要 taiji 宿主。",
+      "当前运行环境不是 taiji GUI 托管的 pi（缺 TAIJI_AGENT_EXT_LOG=1 或 ctx.mode 非 rpc），",
+      "画布工具依赖 taiji runtime 的 marker 路由与 CanvasService，独立 pi CLI 下不可用。",
+      "恢复动作：在 taiji 桌面应用的会话中使用画布工具；纯 pi 环境请直接以对话方式规划。",
+    ].join(""),
+  );
+}

package/src/index.ts

@@ -0,0 +1,174 @@
+/**
+ * @zhushanwen/pi-canvas —— 问题解决画布工具面（设计 §3.1(2) / §5-U4）。
+ *
+ * 六工具动词族，全部 exposure:"deferred"（画布是低频入口，不设常驻 direct——
+ * tool_search 检索激活，一次检索同族 action 全解锁）。每工具 execute 将调用
+ * 转译为 CANVAS_MARKER 的 {action, params} 嵌套载荷（契约 SSOT 在
+ * @zhushanwen/extension-protocol 的 src/extensions/canvas/ 契约模块，U1），经 ctx.ui.select
+ * 挂起由 taiji runtime 的 marker 显式分支路由到 CanvasService。
+ *
+ * 宿主检测：工具调用前检查 TAIJI_AGENT_EXT_LOG === "1" 且 ctx.mode === "rpc"
+ * （谓词单点 @zhushanwen/pi-ext-guards isTaijiGuiHost，经 src/host.ts re-export）
+ * ——非 taiji GUI 宿主返回结构化错误、不进入 select（禁超时探测）。
+ *
+ * 该扩展不收窄宿主工具集（与 plan 的根本差异：agent 要边查代码边论证边生长），
+ * 也无 per-session 状态——画布状态唯一权威在 runtime CanvasService。
+ *
+ * <available_tools> 常驻存在性段（before_agent_start 注入）：pi 1.0.0 下 deferred
+ * 工具的 description 只进 tool_search 检索文档、promptSnippet 不进 system prompt
+ * （D3-A1 真机验收实证：模型对画布工具零感知，自然语言驱动不会发起检索）——
+ * 本段把六工具 name + description 常驻进 system prompt 并写明「需先 tool_search
+ * 激活」，subagent-workflow <available_subagents> 注入段同族形态。
+ */
+
+import type {
+  ExtensionAPI,
+  ExtensionContext,
+  BeforeAgentStartEvent,
+} from "@earendil-works/pi-coding-agent";
+
+import { setPiHandle } from "@zhushanwen/pi-extension-logger";
+
+import { isTaijiGuiHost } from "./host.js";
+import { CanvasEnterParams, registerCanvasEnterTool } from "./tool-enter.js";
+import { CanvasEditParams, registerCanvasEditTool } from "./tool-edit.js";
+import { CanvasReadParams, registerCanvasReadTool } from "./tool-read.js";
+import { CanvasReviewParams, registerCanvasReviewTool } from "./tool-review.js";
+import { CanvasExportParams, registerCanvasExportTool } from "./tool-export.js";
+import { CanvasListParams, registerCanvasListTool } from "./tool-list.js";
+
+/**
+ * 六工具对外描述单源（SSOT）：registerTool 的 description 与 <available_tools>
+ * 常驻段共用同一份数据，双处文本零漂移。
+ */
+export const CANVAS_AVAILABLE_TOOLS: ReadonlyArray<{ name: string; description: string }> = [
+  {
+    name: "canvas_enter",
+    description:
+      "Enter problem-solving-canvas mode: CREATE a canvas (pass statement + criterias + scope — the root problem triple) or OPEN an existing one (pass canvasId from canvas_list). " +
+      "Use when the user asks to plan / think through / break down a problem before execution: the canvas is a human-agent co-edited argument map the user watches and rules on in the taiji GUI. " +
+      "After entering, the user's GUI decisions (selections / vetoes / comments) arrive as canvas event notifications — always canvas_read the current state before responding. " +
+      "Requires the taiji desktop runtime (errors out in standalone pi).",
+  },
+  {
+    name: "canvas_edit",
+    description:
+      "Grow and edit the problem-solving canvas: grow (append a batch of nodes — decomposition, options, arguments), patch (edit one node), select (mark the chosen option; replace to re-select with a comparison reason), transition (lifecycle moves like reject-with-record), comment-respond (answer a user comment — adopted or rebutted, never ignored). " +
+      "Reason fields are mandatory (audit trail); always canvas_read first and edit the CURRENT state. " +
+      "Structural guarantee: user-side rulings arrive as notifications, agent-side edits never self-notify. " +
+      "Requires the taiji desktop runtime (errors out in standalone pi).",
+  },
+  {
+    name: "canvas_read",
+    description:
+      "Read the problem-solving canvas: full state or one subtree (nodes / edges / comments / review report / convergence flags). " +
+      "The read-before-act discipline entry: respond to canvas event notifications and edit the canvas only after reading the current state. " +
+      "Agent-side canvas query entry: the reviewer subagent runs with zero tools (canvas data is inlined into the reviewer prompt by this parent extension). " +
+      "Requires the taiji desktop runtime (errors out in standalone pi).",
+  },
+  {
+    name: "canvas_review",
+    description:
+      "Run the canvas adversarial review loop: run (dispatch one reviewer subagent over the six-dimension checklist — completeness / necessity / support / authenticity / conflict / depth — and write the report back; R2+ pass scope to re-review only the resolution table), append (reviewer report write path), resolve (register one entry's disposition: accepted / deferred / rejected-with-reason — the fix side's duty after repairing). " +
+      "must-fix entries block convergence until cleared. " +
+      "Requires the taiji desktop runtime (errors out in standalone pi).",
+  },
+  {
+    name: "canvas_export",
+    description:
+      "Export a converged canvas: 'planning-doc' (full direction-planning document) or 'requirement-card' (one execution leaf, pass leafId). " +
+      "Rejected with not_converged until the canvas has converged (must-fix cleared, no dirty paths, root criterias confirmed). " +
+      "Requires the taiji desktop runtime (errors out in standalone pi).",
+  },
+  {
+    name: "canvas_list",
+    description:
+      "List all problem-solving canvases (id, name, statement, converged flag, open must-fix count, review status). " +
+      "The canvasId source for canvas_enter's open form. " +
+      "Requires the taiji desktop runtime (errors out in standalone pi).",
+  },
+];
+
+/**
+ * 构造 <available_tools> 段文本：工具清单 + 检索激活指引（纯函数，导出供单测）。
+ * description 单行化（注册侧 description 均为单行拼接串；列表项内换行会破坏
+ * 列表形态，防御外部将来传入多行文本）。
+ */
+export function buildAvailableToolsSection(tools: ReadonlyArray<{ name: string; description: string }>): string {
+  const lines = tools.map((t) => `- ${t.name}: ${t.description.replace(/\s+/g, " ").trim()}`);
+  return [
+    "<available_tools>",
+    "The tools below are registered but NOT loaded into your toolset — calling one directly fails.",
+    "To use one, first call `tool_search` with a query matching its name or purpose (e.g. \"canvas enter problem solving\");",
+    "the match is activated and callable from your next turn.",
+    "",
+    ...lines,
+    "</available_tools>",
+  ].join("\n");
+}
+
+export default function canvasExtension(pi: ExtensionAPI): void {
+  // logger 持久化通道接入（appendEntry custom entry，不进 LLM 上下文）
+  setPiHandle(pi);
+
+  // 注册配置：description 从 CANVAS_AVAILABLE_TOOLS 单源引用（逐工具索引；两处
+  // 文本零漂移）；promptSnippet = 工具激活后 system prompt 工具索引里的精简条目
+  // （未激活时不进上下文，入口可见性由 <available_tools> 常驻段承载）。
+  registerCanvasEnterTool(pi, {
+    name: "canvas_enter",
+    label: "Canvas Enter",
+    description: CANVAS_AVAILABLE_TOOLS[0].description,
+    promptSnippet:
+      "Enter canvas mode: create a problem-solving canvas (statement + criterias + scope) or open an existing one",
+    parameters: CanvasEnterParams,
+  });
+
+  registerCanvasEditTool(pi, {
+    name: "canvas_edit",
+    label: "Canvas Edit",
+    description: CANVAS_AVAILABLE_TOOLS[1].description,
+    promptSnippet: "Grow / patch / select / transition / comment-respond on a canvas (one tool, five actions)",
+    parameters: CanvasEditParams,
+  });
+
+  registerCanvasReadTool(pi, {
+    name: "canvas_read",
+    label: "Canvas Read",
+    description: CANVAS_AVAILABLE_TOOLS[2].description,
+    promptSnippet: "Read the current canvas state (full or one subtree) before acting on canvas events",
+    parameters: CanvasReadParams,
+  });
+
+  registerCanvasReviewTool(pi, {
+    name: "canvas_review",
+    label: "Canvas Review",
+    description: CANVAS_AVAILABLE_TOOLS[3].description,
+    promptSnippet: "Run the adversarial review loop, append a reviewer report, or resolve one review entry",
+    parameters: CanvasReviewParams,
+  });
+
+  registerCanvasExportTool(pi, {
+    name: "canvas_export",
+    label: "Canvas Export",
+    description: CANVAS_AVAILABLE_TOOLS[4].description,
+    promptSnippet: "Export a converged canvas as a planning doc or a requirement card",
+    parameters: CanvasExportParams,
+  });
+
+  registerCanvasListTool(pi, {
+    name: "canvas_list",
+    label: "Canvas List",
+    description: CANVAS_AVAILABLE_TOOLS[5].description,
+    promptSnippet: "List all canvases (id, name, converged flag, open must-fix count)",
+    parameters: CanvasListParams,
+  });
+
+  // <available_tools> 常驻段（注入内容注册期构造一次——每轮 system prompt 追加
+  // 相同文本，KV-cache 前缀稳定）。宿主守卫与工具 execute 同谓词：非 taiji GUI
+  // 宿主下画布工具调用必被 hostGateError 拒绝，不应引导模型检索。
+  const availableToolsSection = buildAvailableToolsSection(CANVAS_AVAILABLE_TOOLS);
+  pi.on("before_agent_start", (event: BeforeAgentStartEvent, ctx: ExtensionContext) => {
+    if (!isTaijiGuiHost(ctx)) return undefined;
+    return { systemPrompt: `${event.systemPrompt}\n\n${availableToolsSection}` };
+  });
+}