@zhushanwen/pi-canvas 0.2.0 → 0.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhushanwen/pi-canvas",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Problem-solving canvas toolface for pi: six deferred canvas_* tools bridging the agent to the taiji runtime CanvasService via the CANVAS_MARKER select channel (problem-solve-canvas)",
   "type": "module",
   "main": "index.ts",
@@ -32,6 +32,7 @@
   "peerDependencies": {
     "@earendil-works/pi-ai": "^1.0.0",
     "@earendil-works/pi-coding-agent": "^1.0.0",
+    "@earendil-works/pi-tui": "^1.0.0",
     "typebox": "1.3.27"
   },
   "peerDependenciesMeta": {
@@ -41,6 +42,9 @@
     "@earendil-works/pi-coding-agent": {
       "optional": true
     },
+    "@earendil-works/pi-tui": {
+      "optional": true
+    },
     "typebox": {
       "optional": true
     }
@@ -54,7 +58,7 @@
     "@zhushanwen/extension-protocol": "0.21.0",
     "@zhushanwen/pi-ext-guards": "0.5.0",
     "@zhushanwen/pi-extension-logger": "0.6.2",
-    "@zhushanwen/subagent-core": "1.5.2"
+    "@zhushanwen/subagent-core": "1.5.3"
   },
   "scripts": {
     "typecheck": "npx tsc --noEmit",

package/src/__tests__/helpers/canvas-harness.ts

@@ -11,6 +11,8 @@ export interface RegisteredTool { // oe-exempt:20261015:framework:画布域类
   exposure?: string;
   parameters: unknown;
   execute: (...args: unknown[]) => Promise<unknown>;
+  /** TUI 结果渲染 handler（renderCanvasToolResult，六工具同函数引用）。 */
+  renderResult?: (result: unknown, options: { expanded: boolean }, theme: unknown) => unknown;
 }
 
 /** before_agent_start handler 的事件/ctx 最小形态（index.ts 只消费 systemPrompt 与 ctx.mode）。 */

package/src/__tests__/render.test.ts

@@ -0,0 +1,68 @@
+// render.test.ts —— canvas 六工具共用 renderResult（pi TUI 侧）：折叠态一行摘要
+// （details.summary，dim 染色）、展开态回原始 content 文本、无摘要异常形态回退。
+
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import { describe, expect, it } from "vitest";
+
+import { renderCanvasToolResult } from "../render.js";
+
+// mock theme（fg 直通，便于断言纯文本；todo render.test.ts 同款）
+const mockTheme = {
+  fg: (_color: string, text: string) => text,
+  bg: (_color: string, text: string) => text,
+  bold: (text: string) => text,
+} as unknown as Theme;
+
+function renderedText(result: unknown, expanded: boolean): string {
+  return renderCanvasToolResult(result, { expanded }, mockTheme).render(400).join("\n");
+}
+
+describe("renderCanvasToolResult", () => {
+  it("折叠态（expanded=false）：渲染 details.summary 一行摘要，不含原始 JSON", () => {
+    const result = {
+      content: [{ type: "text", text: '{"canvases":[{"canvasId":"c1"}]}' }],
+      details: { summary: "Listed 1 canvases" },
+    };
+    const out = renderedText(result, false);
+    expect(out).toContain("Listed 1 canvases");
+    expect(out).not.toContain("canvasId");
+  });
+
+  it("展开态（expanded=true）：渲染 content[0] 原始文本，不含摘要", () => {
+    const result = {
+      content: [{ type: "text", text: '{"canvases":[{"canvasId":"c1"}]}' }],
+      details: { summary: "Listed 1 canvases" },
+    };
+    const out = renderedText(result, true);
+    expect(out).toContain('{"canvases":[{"canvasId":"c1"}]}');
+    expect(out).not.toContain("Listed 1 canvases");
+  });
+
+  it("折叠态但 details 缺失（异常形态）→ 回退 content 文本", () => {
+    const result = { content: [{ type: "text", text: "raw payload" }] };
+    expect(renderedText(result, false)).toContain("raw payload");
+  });
+
+  it("折叠态但 summary 非字符串 / 空串 → 回退 content 文本", () => {
+    const base = { content: [{ type: "text", text: "raw payload" }] };
+    expect(renderedText({ ...base, details: { summary: 42 } }, false)).toContain("raw payload");
+    expect(renderedText({ ...base, details: { summary: "" } }, false)).toContain("raw payload");
+  });
+
+  it("六工具注册的 renderResult 行为一致（共用 renderCanvasToolResult，经 harness 抽查两个工具）", async () => {
+    const { mountCanvas, toolOf } = await import("./helpers/canvas-harness.js");
+    const harness = mountCanvas();
+    const enter = toolOf(harness, "canvas_enter");
+    const list = toolOf(harness, "canvas_list");
+    expect(typeof enter.renderResult).toBe("function");
+    expect(typeof list.renderResult).toBe("function");
+    // 抽查经工具 handler 的折叠态渲染（handler 是各 registerTool 的方法包装，
+    // 共用同一渲染内核；类型桩：theme 直通）
+    type RenderFn = (r: unknown, o: { expanded: boolean }, t: unknown) => { render: (w: number) => string[] };
+    const render = (fn: unknown, result: unknown) =>
+      (fn as RenderFn)(result, { expanded: false }, mockTheme).render(400).join("\n");
+    const sample = { content: [{ type: "text", text: "raw" }], details: { summary: 'Entered canvas "n"' } };
+    expect(render(enter.renderResult, sample)).toContain('Entered canvas "n"');
+    expect(render(list.renderResult, sample)).toContain('Entered canvas "n"');
+  });
+});

package/src/__tests__/summary.test.ts

@@ -0,0 +1,321 @@
+// summary.test.ts —— 六工具 details.summary 产出与 summary 纯函数文案（GUI 对话流
+// 收起态摘要的产出侧契约）：execute 组装断言走 harness（marker 往返），数据缺失
+// 分支直接测纯函数（形状漂移退化为无后缀短文案，不抛错）。
+
+import { beforeEach, describe, expect, it } from "vitest";
+
+import {
+  canvasEditSummary,
+  canvasEnterSummary,
+  canvasExportSummary,
+  canvasListSummary,
+  canvasReadSummary,
+  canvasReviewSummary,
+} from "../summary.js";
+
+import {
+  mountCanvas,
+  toolOf,
+  withExtLogEnv,
+  type ToolHarness,
+} from "./helpers/canvas-harness.js";
+
+describe("execute 组装 details.summary（六工具全路径）", () => {
+  let harness: ToolHarness;
+  beforeEach(() => {
+    harness = mountCanvas();
+  });
+
+  it("canvas_enter 创建形态（params.name 可得）", 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",
+        { name: "多引擎支持", statement: "s", criterias: ["c"], scope: [] },
+        undefined,
+        undefined,
+        harness.ctx,
+      )) as { details: { summary: string } };
+      expect(result.details.summary).toBe('Entered canvas "多引擎支持"');
+    });
+  });
+
+  it("canvas_enter 打开形态（reply=CanvasState.name 优先于 params）", async () => {
+    await withExtLogEnv("1", async () => {
+      harness.selectMock.mockResolvedValue(
+        JSON.stringify({ canvasId: "c9", name: "已有画布", nodes: [] }),
+      );
+      const enter = toolOf(harness, "canvas_enter");
+      const result = (await enter.execute("t1", { canvasId: "c9" }, undefined, undefined, harness.ctx)) as {
+        details: { summary: string };
+      };
+      expect(result.details.summary).toBe('Entered canvas "已有画布"');
+    });
+  });
+
+  it("canvas_edit grow 带 batch 数量；patch 无数量语义", 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" },
+        { id: "n2", type: "option", content: "o", attachTo: "root", edge: "resolve" },
+      ];
+      const growResult = (await edit.execute(
+        "t1",
+        { action: "grow", growParams: { canvasId: "c1", batch, reason: "r" } },
+        undefined,
+        undefined,
+        harness.ctx,
+      )) as { details: { summary: string } };
+      expect(growResult.details.summary).toBe("Canvas edited · +2 nodes");
+
+      const patchResult = (await edit.execute(
+        "t1",
+        { action: "patch", patchParams: { canvasId: "c1", nodeId: "n1", reason: "r" } },
+        undefined,
+        undefined,
+        harness.ctx,
+      )) as { details: { summary: string } };
+      expect(patchResult.details.summary).toBe("Canvas edited");
+    });
+  });
+
+  it("canvas_read 带 name 与节点数", async () => {
+    await withExtLogEnv("1", async () => {
+      harness.selectMock.mockResolvedValue(
+        JSON.stringify({ canvasId: "c1", name: "多引擎支持", nodes: [{ id: "root" }, { id: "n1" }] }),
+      );
+      const read = toolOf(harness, "canvas_read");
+      const result = (await read.execute("t1", { canvasId: "c1" }, undefined, undefined, harness.ctx)) as {
+        details: { summary: string };
+      };
+      expect(result.details.summary).toBe('Read canvas "多引擎支持" · 2 nodes');
+    });
+  });
+
+  it("canvas_review resolve：条目 id + 处置结论", async () => {
+    await withExtLogEnv("1", async () => {
+      harness.selectMock.mockResolvedValue(
+        JSON.stringify({ ok: true, eventId: "e3", evType: "ReviewEntryResolved", summary: "r" }),
+      );
+      const review = toolOf(harness, "canvas_review");
+      const result = (await review.execute(
+        "t1",
+        { action: "resolve", resolveParams: { canvasId: "c1", entryId: "rv-1", disposition: "accepted", note: "已修" } },
+        undefined,
+        undefined,
+        harness.ctx,
+      )) as { details: { summary: string } };
+      expect(result.details.summary).toBe("Review resolved rv-1 (accepted)");
+    });
+  });
+
+  it("canvas_review append：条目数 + must-fix 计数（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");
+      const result = (await review.execute(
+        "t1",
+        {
+          action: "append",
+          appendParams: {
+            canvasId: "c1",
+            round: 1,
+            entries: [
+              { id: "rv-1", dimension: "support", severity: "must-fix", targetId: "e1", note: "n" },
+              { id: "rv-2", dimension: "depth", severity: "suggestion", targetId: "n1", note: "n" },
+              { id: "rv-3", dimension: "conflict", severity: "must-fix", targetId: "n2", note: "n" },
+            ],
+          },
+        },
+        undefined,
+        undefined,
+        harness.ctx,
+      )) as { details: { summary: string } };
+      expect(result.details.summary).toBe("Review appended 3 entries · 2 must-fix");
+    });
+  });
+
+  it("canvas_review run：编排产物带轮次与写回条目数", async () => {
+    await withExtLogEnv("1", async () => {
+      // marker 三跳：review-request（留痕 mutate）→ read（全量，R1）→ review-append（写回 mutate）
+      harness.selectMock
+        .mockResolvedValueOnce(JSON.stringify({ ok: true, eventId: "e6", evType: "ReviewRequested", summary: "req" }))
+        .mockResolvedValueOnce(
+          JSON.stringify({
+            canvasId: "c1",
+            name: "多引擎支持",
+            root: { nodeId: "root", statement: "s", criterias: ["c"], scopeExclusions: [] },
+            direction: null,
+            nodes: [],
+            edges: [],
+            comments: [],
+            dirtyPaths: [],
+            review: null,
+            converged: false,
+            createdAt: "2026-10-17T00:00:00Z",
+            updatedAt: "2026-10-17T00:00:00Z",
+          }),
+        )
+        .mockResolvedValueOnce(JSON.stringify({ ok: true, eventId: "e7", evType: "ReviewEntryAppended", summary: "app" }));
+      const SLOT_KEY = Symbol.for("@zhushanwen/subagent-core.service");
+      // 槽值形状 = { current: service } 持有者（service-bootstrap getServiceSlot），
+      // getSubagentService() 解 .current——直接放 service 本体会取不到
+      (globalThis as Record<symbol, unknown>)[SLOT_KEY] = {
+        current: {
+          executeAndAwait: async () => ({
+            parsedOutput: {
+              entries: [{ id: "rv-1", dimension: "support", severity: "must-fix", targetId: "e1", note: "n" }],
+              summary: "总体判断",
+            },
+          }),
+        },
+      };
+      try {
+        const review = toolOf(harness, "canvas_review");
+        const result = (await review.execute(
+          "t1",
+          { action: "run", runParams: { canvasId: "c1" } },
+          undefined,
+          undefined,
+          harness.ctx,
+        )) as { details: { summary: string } };
+        expect(result.details.summary).toBe("Review round 1 · +1 entries");
+      } finally {
+        delete (globalThis as Record<symbol, unknown>)[SLOT_KEY];
+      }
+    });
+  });
+
+  it("canvas_review run：达轮次上限停回短路带状态词", async () => {
+    await withExtLogEnv("1", async () => {
+      harness.selectMock
+        .mockResolvedValueOnce(JSON.stringify({ ok: true, eventId: "e6", evType: "ReviewRequested", summary: "已达上限" }))
+        .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: "停回用户裁决",
+              recoverHint: "升级裁决后重发",
+            },
+            converged: false,
+            createdAt: "2026-10-17T00:00:00Z",
+            updatedAt: "2026-10-17T00:00:00Z",
+          }),
+        );
+      const review = toolOf(harness, "canvas_review");
+      const result = (await review.execute(
+        "t1",
+        { action: "run", runParams: { canvasId: "c1" } },
+        undefined,
+        undefined,
+        harness.ctx,
+      )) as { details: { summary: string } };
+      expect(result.details.summary).toBe("Review stopped: max-rounds");
+    });
+  });
+
+  it("canvas_export 按目标形态呈现（导出文件路径不在 mutate 回包内，不虚构）", async () => {
+    await withExtLogEnv("1", async () => {
+      harness.selectMock.mockResolvedValue(
+        JSON.stringify({ ok: true, eventId: "e5", evType: "CanvasExported", summary: "x" }),
+      );
+      const exp = toolOf(harness, "canvas_export");
+      const docResult = (await exp.execute(
+        "t1",
+        { canvasId: "c1", target: "planning-doc" },
+        undefined,
+        undefined,
+        harness.ctx,
+      )) as { details: { summary: string } };
+      expect(docResult.details.summary).toBe("Exported planning-doc");
+
+      const cardResult = (await exp.execute(
+        "t1",
+        { canvasId: "c1", target: "requirement-card", leafId: "leaf-9" },
+        undefined,
+        undefined,
+        harness.ctx,
+      )) as { details: { summary: string } };
+      expect(cardResult.details.summary).toBe("Exported requirement-card (leaf leaf-9)");
+    });
+  });
+
+  it("canvas_list 带清单计数", async () => {
+    await withExtLogEnv("1", async () => {
+      harness.selectMock.mockResolvedValue(
+        JSON.stringify({ canvases: [{ canvasId: "c1" }, { canvasId: "c2" }, { canvasId: "c3" }] }),
+      );
+      const list = toolOf(harness, "canvas_list");
+      const result = (await list.execute("t1", {}, undefined, undefined, harness.ctx)) as {
+        details: { summary: string };
+      };
+      expect(result.details.summary).toBe("Listed 3 canvases");
+    });
+  });
+});
+
+describe("summary 纯函数数据缺失分支（形状漂移退化为短文案，不抛错）", () => {
+  it("canvasEnterSummary：reply 与 params 均无名 → 裸文案", () => {
+    expect(canvasEnterSummary({ statement: "s", criterias: ["c"], scope: [] }, { ok: true })).toBe("Entered canvas");
+    expect(canvasEnterSummary({ statement: "s", criterias: ["c"], scope: [] }, "not-an-object")).toBe("Entered canvas");
+  });
+
+  it("canvasEditSummary：grow 缺参数块 / batch 非数组 → 无数量后缀", () => {
+    expect(canvasEditSummary({ action: "grow" })).toBe("Canvas edited");
+    expect(canvasEditSummary({ action: "select" })).toBe("Canvas edited");
+  });
+
+  it("canvasReadSummary：name 缺失 / nodes 非数组 → 逐级省略", () => {
+    expect(canvasReadSummary({ name: "n", nodes: "bad" })).toBe('Read canvas "n"');
+    expect(canvasReadSummary({})).toBe("Read canvas");
+    expect(canvasReadSummary(undefined)).toBe("Read canvas");
+  });
+
+  it("canvasReviewSummary run：编排产物缺 round/appended → Review ran；append 缺 entries → Review appended；resolve 缺参数块 → Review resolved", () => {
+    expect(canvasReviewSummary({ action: "run" }, { ok: true })).toBe("Review ran");
+    expect(canvasReviewSummary({ action: "append" }, { ok: true })).toBe("Review appended");
+    expect(canvasReviewSummary({ action: "resolve" }, { ok: true })).toBe("Review resolved");
+  });
+
+  it("canvasReviewSummary run 停回：status 缺失 → 无状态词", () => {
+    expect(canvasReviewSummary({ action: "run" }, { stopped: true })).toBe("Review stopped");
+  });
+
+  it("canvasReviewSummary append：全 suggestion（must-fix 零计数不显示零后缀）", () => {
+    expect(
+      canvasReviewSummary(
+        { action: "append", appendParams: { canvasId: "c", round: 1, entries: [{ id: "a", severity: "suggestion" }] } },
+        { ok: true },
+      ),
+    ).toBe("Review appended 1 entries");
+  });
+
+  it("canvasExportSummary：requirement-card 缺 leafId → 通用文案", () => {
+    expect(canvasExportSummary({ canvasId: "c", target: "requirement-card" })).toBe("Exported canvas");
+  });
+
+  it("canvasListSummary：canvases 缺失/非数组 → 无计数", () => {
+    expect(canvasListSummary({})).toBe("Listed canvases");
+    expect(canvasListSummary({ canvases: 3 })).toBe("Listed canvases");
+  });
+});

package/src/render.ts

@@ -0,0 +1,23 @@
+/**
+ * canvas 六工具共用 renderResult（pi TUI 侧；taiji GUI 对话流不走本文件——GUI 直读
+ * details.summary）。形态对齐 todo 扩展 render.ts 先例：折叠态一行摘要（dim 染色），
+ * 展开态 / 无摘要（异常形态）回退原始 content 文本。
+ */
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import { Text } from "@earendil-works/pi-tui";
+import { firstContentText } from "@zhushanwen/extension-protocol";
+
+/** pi toolResult 通用形状（AgentToolResult 的结构最小面，renderResult 入参收窄用）。 */
+interface ToolResultShape { // oe-exempt:20261017:framework:details 数据形状窄 view（单实现消费，非抽象接口）
+  content: Array<{ type: string; text?: string }>;
+  details?: { summary?: unknown };
+}
+
+export function renderCanvasToolResult(result: unknown, options: { expanded: boolean }, theme: Theme): Text {
+  const r = result as ToolResultShape;
+  const summary = r.details?.summary;
+  if (options.expanded === false && typeof summary === "string" && summary !== "") {
+    return new Text(theme.fg("dim", summary), 0, 0);
+  }
+  return new Text(firstContentText(r), 0, 0);
+}

package/src/summary.ts

@@ -0,0 +1,118 @@
+/**
+ * canvas 六工具结果的一行摘要（details.summary 单一产出点）。
+ *
+ * 消费两路：各工具 execute 组装 details.summary（taiji GUI 对话流收起态展示）+
+ * render.ts 的 renderResult 折叠态渲染（pi TUI）。纯函数无 IO：reply 是 marker
+ * 通道回包（runtime 侧 JSON，不信任外部格式——逐字段守卫，形状漂移退化为无后缀
+ * 短文案而非抛错；摘要只是展示辅助，不得反过来影响工具成功路径）。
+ *
+ * 数据可得性按契约（@zhushanwen/extension-protocol canvas 契约模块）核对：
+ * - enter 打开形态 / read 的 reply = CanvasState（name/nodes）；enter 创建形态与
+ *   mutate 族 reply = CanvasMutateReply（ok/eventId/evType/summary，无画布名）。
+ * - review run 的 reply 是本包编排产物（review.ts runReviewRound：round/appended）；
+ *   max-rounds 停回短路是 stopped/status 形状（tool-review.ts）。
+ * - export 的 reply 是 CanvasMutateReply，不携带导出文件路径——target 从 params 取。
+ */
+import type { Static } from "typebox";
+
+import type { CanvasEditParams } from "./tool-edit.js";
+import type { CanvasEnterParams } from "./tool-enter.js";
+import type { CanvasExportParams } from "./tool-export.js";
+import type { CanvasReviewParams } from "./tool-review.js";
+
+/** 不信任来源的对象访问统一入口（review.ts recordOf 同款）。 */
+function recordOf(v: unknown): Record<string, unknown> | undefined {
+  return typeof v === "object" && v !== null && !Array.isArray(v)
+    ? (v as Record<string, unknown>)
+    : undefined;
+}
+
+function stringField(rec: Record<string, unknown> | undefined, key: string): string | undefined {
+  const v = rec?.[key];
+  return typeof v === "string" && v !== "" ? v : undefined;
+}
+
+function arrayField(rec: Record<string, unknown> | undefined, key: string): unknown[] | undefined {
+  const v = rec?.[key];
+  return Array.isArray(v) ? v : undefined;
+}
+
+function numberField(rec: Record<string, unknown> | undefined, key: string): number | undefined {
+  const v = rec?.[key];
+  return typeof v === "number" && Number.isFinite(v) ? v : undefined;
+}
+
+/** canvas_enter：打开形态 reply 带 CanvasState.name；创建形态 reply 无名（mutate
+ * 信封），退 params.name（runtime 可能按 statement 派生名，params 未传则裸文案）。 */
+export function canvasEnterSummary(params: Static<typeof CanvasEnterParams>, reply: unknown): string {
+  const name = stringField(recordOf(reply), "name") ?? (params.name !== undefined && params.name !== "" ? params.name : undefined);
+  return name !== undefined ? `Entered canvas "${name}"` : "Entered canvas";
+}
+
+/** canvas_edit：grow 从 params.batch 带新增节点数；其余 action 无数量语义。 */
+export function canvasEditSummary(params: Static<typeof CanvasEditParams>): string {
+  if (params.action === "grow" && params.growParams && Array.isArray(params.growParams.batch)) {
+    return `Canvas edited · +${params.growParams.batch.length} nodes`;
+  }
+  return "Canvas edited";
+}
+
+/** canvas_read：reply = CanvasState（name + nodes 必备字段，守卫漂移时逐级省略）。 */
+export function canvasReadSummary(reply: unknown): string {
+  const rec = recordOf(reply);
+  const name = stringField(rec, "name");
+  const nodes = arrayField(rec, "nodes");
+  if (name !== undefined && nodes !== undefined) return `Read canvas "${name}" · ${nodes.length} nodes`;
+  if (name !== undefined) return `Read canvas "${name}"`;
+  return "Read canvas";
+}
+
+/**
+ * canvas_review 三 action 各按可得数据呈现：
+ * - run：编排产物带 round/appended（写回条目数）；达轮次上限的停回短路带
+ *   stopped/status。verdict（pass/fail）不在工具结果里（报告聚合在画布状态，
+ *   经 canvas_read 读），文案不虚构该数据。
+ * - append：entries 数与 must-fix 计数从 params 数（报告条目写回量）。
+ * - resolve：处置条目与三选一结论从 params 取。
+ */
+export function canvasReviewSummary(params: Static<typeof CanvasReviewParams>, reply: unknown): string {
+  if (params.action === "run") {
+    const rec = recordOf(reply);
+    if (rec?.stopped === true) {
+      const status = stringField(rec, "status");
+      return status !== undefined ? `Review stopped: ${status}` : "Review stopped";
+    }
+    const round = numberField(rec, "round");
+    const appended = numberField(rec, "appended");
+    if (round !== undefined && appended !== undefined) return `Review round ${round} · +${appended} entries`;
+    return "Review ran";
+  }
+  if (params.action === "append") {
+    const entries = params.appendParams?.entries;
+    if (Array.isArray(entries)) {
+      const mustFix = entries.filter((e) => recordOf(e)?.severity === "must-fix").length;
+      return mustFix > 0
+        ? `Review appended ${entries.length} entries · ${mustFix} must-fix`
+        : `Review appended ${entries.length} entries`;
+    }
+    return "Review appended";
+  }
+  const resolve = params.resolveParams;
+  if (resolve) return `Review resolved ${resolve.entryId} (${resolve.disposition})`;
+  return "Review resolved";
+}
+
+/** canvas_export：reply 是 mutate 信封不携带产物路径——按 target 呈现导出物。 */
+export function canvasExportSummary(params: Static<typeof CanvasExportParams>): string {
+  if (params.target === "planning-doc") return "Exported planning-doc";
+  if (params.target === "requirement-card" && params.leafId !== undefined && params.leafId !== "") {
+    return `Exported requirement-card (leaf ${params.leafId})`;
+  }
+  return "Exported canvas";
+}
+
+/** canvas_list：reply = CanvasListReply { canvases }。 */
+export function canvasListSummary(reply: unknown): string {
+  const canvases = arrayField(recordOf(reply), "canvases");
+  return canvases !== undefined ? `Listed ${canvases.length} canvases` : "Listed canvases";
+}

package/src/tool-edit.ts

@@ -17,11 +17,13 @@
  * 幂等重试一致性判定也比对它）。
  */
 import { StringEnum } from "@earendil-works/pi-ai";
-import type { ExtensionAPI, ExtensionToolContext } from "@earendil-works/pi-coding-agent";
+import type { ExtensionAPI, ExtensionToolContext, Theme } from "@earendil-works/pi-coding-agent";
 import { Type, type Static } from "typebox";
 import type { CanvasMarkerRequest } from "@zhushanwen/extension-protocol";
 import { isCanvasMarkerRequest } from "@zhushanwen/extension-protocol";
 
+import { renderCanvasToolResult } from "./render.js";
+import { canvasEditSummary } from "./summary.js";
 import { callCanvas } from "./marker-channel.js";
 import { hostGateError, isTaijiGuiHost } from "./host.js";
 
@@ -185,6 +187,9 @@ export function registerCanvasEditTool(
     description: cfg.description,
     promptSnippet: cfg.promptSnippet,
     parameters: cfg.parameters,
+    renderResult(result: unknown, options: { expanded: boolean }, theme: Theme) {
+      return renderCanvasToolResult(result, options, theme);
+    },
     async execute(
       _toolCallId: string,
       params: Static<typeof CanvasEditParams>,
@@ -205,7 +210,10 @@ export function registerCanvasEditTool(
       }
       const markerRequest: CanvasMarkerRequest = request;
       const reply = await callCanvas(ctx, markerRequest.action, markerRequest.params);
-      return { content: [{ type: "text" as const, text: JSON.stringify(reply) }], details: undefined };
+      return {
+        content: [{ type: "text" as const, text: JSON.stringify(reply) }],
+        details: { summary: canvasEditSummary(params) },
+      };
     },
   });
 }

package/src/tool-enter.ts

@@ -10,9 +10,11 @@
  * canvas_read / canvas_review / canvas_export」指引——deferred 工具须检索激活后
  * 下一轮起可调，直接点名工具名让模型检索词精准命中。
  */
-import type { ExtensionAPI, ExtensionToolContext } from "@earendil-works/pi-coding-agent";
+import type { ExtensionAPI, ExtensionToolContext, Theme } from "@earendil-works/pi-coding-agent";
 import { Type, type Static } from "typebox";
 
+import { renderCanvasToolResult } from "./render.js";
+import { canvasEnterSummary } from "./summary.js";
 import { callCanvas } from "./marker-channel.js";
 import { hostGateError, isTaijiGuiHost } from "./host.js";
 
@@ -129,6 +131,9 @@ export function registerCanvasEnterTool(pi: ExtensionAPI, cfg: EnterToolConfig):
     description: cfg.description,
     promptSnippet: cfg.promptSnippet,
     parameters: cfg.parameters,
+    renderResult(result: unknown, options: { expanded: boolean }, theme: Theme) {
+      return renderCanvasToolResult(result, options, theme);
+    },
     async execute(
       _toolCallId: string,
       params: Static<typeof CanvasEnterParams>,
@@ -141,7 +146,7 @@ export function registerCanvasEnterTool(pi: ExtensionAPI, cfg: EnterToolConfig):
       if ("error" in request) throw request.error;
       const reply = await callCanvas(ctx, request.action, request.params);
       const text = `${JSON.stringify(reply)}\n\n${CANVAS_ENTER_GUIDANCE}`;
-      return { content: [{ type: "text" as const, text }], details: undefined };
+      return { content: [{ type: "text" as const, text }], details: { summary: canvasEnterSummary(params, reply) } };
     },
   });
 }

package/src/tool-export.ts

@@ -5,9 +5,11 @@
  * runtime 以 not_converged 拒绝（错误码 + 恢复动作文案经 marker-channel throw 透出）。
  */
 import { StringEnum } from "@earendil-works/pi-ai";
-import type { ExtensionAPI, ExtensionToolContext } from "@earendil-works/pi-coding-agent";
+import type { ExtensionAPI, ExtensionToolContext, Theme } from "@earendil-works/pi-coding-agent";
 import { Type, type Static } from "typebox";
 
+import { renderCanvasToolResult } from "./render.js";
+import { canvasExportSummary } from "./summary.js";
 import { callCanvas } from "./marker-channel.js";
 import { hostGateError, isTaijiGuiHost } from "./host.js";
 
@@ -55,6 +57,9 @@ export function registerCanvasExportTool(
     description: cfg.description,
     promptSnippet: cfg.promptSnippet,
     parameters: cfg.parameters,
+    renderResult(result: unknown, options: { expanded: boolean }, theme: Theme) {
+      return renderCanvasToolResult(result, options, theme);
+    },
     async execute(
       _toolCallId: string,
       params: Static<typeof CanvasExportParams>,
@@ -66,7 +71,10 @@ export function registerCanvasExportTool(
       const request = exportRequestOf(params);
       if ("error" in request) throw request.error;
       const reply = await callCanvas(ctx, "export", request.params);
-      return { content: [{ type: "text" as const, text: JSON.stringify(reply) }], details: undefined };
+      return {
+        content: [{ type: "text" as const, text: JSON.stringify(reply) }],
+        details: { summary: canvasExportSummary(params) },
+      };
     },
   });
 }

package/src/tool-list.ts

@@ -2,9 +2,11 @@
  * canvas_list —— 列画布清单（设计 §3.1(2) 工具面）：canvas_enter 打开形态的
  * canvasId 来源；无参数（过滤无字段——runtime 按契约 Record 结构性拒绝夹带）。
  */
-import type { ExtensionAPI, ExtensionToolContext } from "@earendil-works/pi-coding-agent";
+import type { ExtensionAPI, ExtensionToolContext, Theme } from "@earendil-works/pi-coding-agent";
 import { Type, type Static } from "typebox";
 
+import { renderCanvasToolResult } from "./render.js";
+import { canvasListSummary } from "./summary.js";
 import { callCanvas } from "./marker-channel.js";
 import { hostGateError, isTaijiGuiHost } from "./host.js";
 
@@ -21,6 +23,9 @@ export function registerCanvasListTool(
     description: cfg.description,
     promptSnippet: cfg.promptSnippet,
     parameters: cfg.parameters,
+    renderResult(result: unknown, options: { expanded: boolean }, theme: Theme) {
+      return renderCanvasToolResult(result, options, theme);
+    },
     async execute(
       _toolCallId: string,
       _params: Static<typeof CanvasListParams>,
@@ -30,7 +35,10 @@ export function registerCanvasListTool(
     ) {
       if (!isTaijiGuiHost(ctx)) throw hostGateError();
       const reply = await callCanvas(ctx, "list", {});
-      return { content: [{ type: "text" as const, text: JSON.stringify(reply) }], details: undefined };
+      return {
+        content: [{ type: "text" as const, text: JSON.stringify(reply) }],
+        details: { summary: canvasListSummary(reply) },
+      };
     },
   });
 }

package/src/tool-read.ts

@@ -5,9 +5,11 @@
  * reviewer prompt；ExecuteOptions 无 tools 通道，结构上无法授工具）；
  * 响应纪律「先 read 再动」的数据入口。
  */
-import type { ExtensionAPI, ExtensionToolContext } from "@earendil-works/pi-coding-agent";
+import type { ExtensionAPI, ExtensionToolContext, Theme } from "@earendil-works/pi-coding-agent";
 import { Type, type Static } from "typebox";
 
+import { renderCanvasToolResult } from "./render.js";
+import { canvasReadSummary } from "./summary.js";
 import { callCanvas } from "./marker-channel.js";
 import { hostGateError, isTaijiGuiHost } from "./host.js";
 
@@ -29,6 +31,9 @@ export function registerCanvasReadTool(
     description: cfg.description,
     promptSnippet: cfg.promptSnippet,
     parameters: cfg.parameters,
+    renderResult(result: unknown, options: { expanded: boolean }, theme: Theme) {
+      return renderCanvasToolResult(result, options, theme);
+    },
     async execute(
       _toolCallId: string,
       params: Static<typeof CanvasReadParams>,
@@ -38,7 +43,10 @@ export function registerCanvasReadTool(
     ) {
       if (!isTaijiGuiHost(ctx)) throw hostGateError();
       const reply = await callCanvas(ctx, "read", { canvasId: params.canvasId, subtree: params.subtree });
-      return { content: [{ type: "text" as const, text: JSON.stringify(reply) }], details: undefined };
+      return {
+        content: [{ type: "text" as const, text: JSON.stringify(reply) }],
+        details: { summary: canvasReadSummary(reply) },
+      };
     },
   });
 }

package/src/tool-review.ts

@@ -13,13 +13,15 @@
  * 分离构造保证：reviewer 无改图能力（零工具）；主 agent 修复走 canvas_edit。
  */
 import { StringEnum } from "@earendil-works/pi-ai";
-import type { ExtensionAPI, ExtensionToolContext } from "@earendil-works/pi-coding-agent";
+import type { ExtensionAPI, ExtensionToolContext, Theme } from "@earendil-works/pi-coding-agent";
 import { Type, type Static } from "typebox";
 import {
   isCanvasReviewAppendParams,
   isCanvasReviewResolveParams,
 } from "@zhushanwen/extension-protocol";
 
+import { renderCanvasToolResult } from "./render.js";
+import { canvasReviewSummary } from "./summary.js";
 import { callCanvas } from "./marker-channel.js";
 import { hostGateError, isTaijiGuiHost } from "./host.js";
 import {
@@ -97,6 +99,9 @@ export function registerCanvasReviewTool(
     description: cfg.description,
     promptSnippet: cfg.promptSnippet,
     parameters: cfg.parameters,
+    renderResult(result: unknown, options: { expanded: boolean }, theme: Theme) {
+      return renderCanvasToolResult(result, options, theme);
+    },
     async execute(
       _toolCallId: string,
       params: Static<typeof CanvasReviewParams>,
@@ -121,7 +126,10 @@ export function registerCanvasReviewTool(
           );
         }
         const reply = await callCanvas(ctx, "review-resolve", params.resolveParams);
-        return { content: [{ type: "text" as const, text: JSON.stringify(reply) }], details: undefined };
+        return {
+          content: [{ type: "text" as const, text: JSON.stringify(reply) }],
+          details: { summary: canvasReviewSummary(params, reply) },
+        };
       }
       if (params.action === "append") {
         const appendParams = params.appendParams;
@@ -145,7 +153,10 @@ export function registerCanvasReviewTool(
           );
         }
         const reply = await callCanvas(ctx, "review-append", request);
-        return { content: [{ type: "text" as const, text: JSON.stringify(reply) }], details: undefined };
+        return {
+          content: [{ type: "text" as const, text: JSON.stringify(reply) }],
+          details: { summary: canvasReviewSummary(params, reply) },
+        };
       }
       // action === "run"：编排链（review-request 留痕 → read 全量 → 派 reviewer → append 写回）
       if (!params.runParams) {
@@ -169,15 +180,18 @@ export function registerCanvasReviewTool(
       // 终态 + 停回说明（mutate 本身成功——合法终态转移而非校验失败），本轮没有开始，
       // 不得再派 reviewer。停回说明结构化可读（stopNote/recoverHint），不解析 summary 文本。
       if (readReply.review?.status === "max-rounds") {
-        const text = JSON.stringify({
+        const payload = {
           ok: true,
           canvasId: readReply.canvasId,
           stopped: true,
           status: readReply.review.status,
           stopNote: readReply.review.stopNote,
           recoverHint: readReply.review.recoverHint,
-        });
-        return { content: [{ type: "text" as const, text }], details: undefined };
+        };
+        return {
+          content: [{ type: "text" as const, text: JSON.stringify(payload) }],
+          details: { summary: canvasReviewSummary(params, payload) },
+        };
       }
       const dispatcher = resolveReviewerDispatcher();
       const outcome = await runReviewRound({
@@ -195,7 +209,10 @@ export function registerCanvasReviewTool(
         dropped: outcome.dropped,
         summary: outcome.summary,
       });
-      return { content: [{ type: "text" as const, text }], details: undefined };
+      return {
+        content: [{ type: "text" as const, text }],
+        details: { summary: canvasReviewSummary(params, outcome) },
+      };
     },
   });
 }