@zhushanwen/pi-canvas 0.0.0-stage → 0.2.0

package/README.md

@@ -1,3 +1,12 @@
-# Temporary Holding Version
+# @zhushanwen/pi-canvas
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+问题解决画布的 pi extension 工具面（taiji 组，role=taiji，tier=feature）。
+
+六个 `canvas_*` 工具（全部 `exposure: "deferred"`，tool_search 检索激活）：`canvas_enter`（创建/打开）、`canvas_edit`（grow/patch/select/transition/comment-respond 五 action）、`canvas_read`、`canvas_review`（run/append/resolve）、`canvas_export`、`canvas_list`。
+
+架构（设计 `.tmp/tech-design/problem-solve-canvas.md` §3.1(2)）：
+
+- 画布状态唯一权威在 taiji runtime 的 CanvasService；本扩展是薄工具面——每工具 execute 把调用转译为 `CANVAS_MARKER` 的 `{action, params}` 嵌套载荷，经 `ctx.ui.select` 挂起，由 runtime marker 显式分支路由（session-manager 同款通道；契约 SSOT 在 `@zhushanwen/extension-protocol` 的 `src/extensions/canvas/` 契约模块）。
+- 宿主检测：`TAIJI_AGENT_EXT_LOG === "1"` 且 `ctx.mode === "rpc"`（对齐 plan 的 `isTaijiGuiHost` 完整谓词）——非 taiji GUI 宿主返回结构化错误，不进入 select，禁超时探测。
+- 审查编排：`canvas_review(run)` 经 subagent-workflow 的 `SubagentService`（globalThis service 槽）派单个 reviewer（六维度模板 + 画布全量内联，reviewer 零工具——无改图通道），报告条目经 marker `review-append` 写回（runtime 按 U1 权限矩阵映射 actor=review）。
+- 无墙钟超时：marker select 与 reviewer 派发均不设时限（任务级正常路径不设限；session-manager watch 先例）。

package/index.ts

@@ -0,0 +1 @@
+export { default } from "./src/index.js";

package/package.json

@@ -1,6 +1,63 @@
 {
   "name": "@zhushanwen/pi-canvas",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.2.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",
+  "keywords": [
+    "pi-package",
+    "pi",
+    "pi-coding-agent",
+    "extension",
+    "canvas"
+  ],
+  "license": "MIT",
+  "files": [
+    "index.ts",
+    "src/**/*.ts",
+    "README.md",
+    "skills/"
+  ],
+  "taiji": {
+    "role": "taiji"
+  },
+  "pi": {
+    "extensions": [
+      "./index.ts"
+    ],
+    "skills": [
+      "./skills"
+    ]
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-ai": "^1.0.0",
+    "@earendil-works/pi-coding-agent": "^1.0.0",
+    "typebox": "1.3.27"
+  },
+  "peerDependenciesMeta": {
+    "@earendil-works/pi-ai": {
+      "optional": true
+    },
+    "@earendil-works/pi-coding-agent": {
+      "optional": true
+    },
+    "typebox": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "@vitest/coverage-v8": "^4.1.9",
+    "vitest": "^4.1.8"
+  },
+  "dependencies": {
+    "@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"
+  },
+  "scripts": {
+    "typecheck": "npx tsc --noEmit",
+    "test": "vitest run"
+  }
 }

package/skills/canvas-ext-config/SKILL.md

@@ -0,0 +1,75 @@
+---
+name: canvas-ext-config
+description: "使用或排查 @zhushanwen/pi-canvas（问题解决画布：六个 canvas_* deferred 工具，人机共编论证图）时加载。含 select 通道挂起等待 GUI 裁决的语义（无墙钟超时，裁决经事件通知回推）、宿主检测（canvas_unavailable_host 的两种成因）、events.jsonl/canvas.json 存储概览、排障入口（TAIJI_AGENT_EXT_LOG 日志位置与宿主要求）。触发词：画布、canvas、canvas_enter、canvas_edit、canvas_review、canvas_export、select 挂起、等待裁决、canvas_unavailable_host、画布日志、画布排障、events.jsonl、canvas.json。"
+---
+
+# canvas 画布使用与排障指南
+
+> @zhushanwen/pi-canvas：问题解决画布的工具面。六个 `canvas_*` 工具（全部 deferred，需先 `tool_search` 检索激活）：`canvas_enter`（创建/打开）、`canvas_edit`（grow/patch/select/transition/comment-respond）、`canvas_read`、`canvas_review`（run/append/resolve）、`canvas_export`、`canvas_list`。画布是用户在 taiji GUI 里实时观看并裁决的人机共编论证图。
+
+**本扩展无磁盘配置文件**——没有 `<agentDir>/config/canvas-ext-config.json`，行为不可经文件配置。它的「配置面」就是宿主注入的环境变量（见下文排障节）；不要去找或创建配置 JSON。
+
+## 通道语义：select 挂起等待 GUI 裁决
+
+每个 `canvas_*` 调用的路径：工具 execute 把调用转译为 `CANVAS_MARKER` 的 `{action, params}` 嵌套载荷，经 `ctx.ui.select` **挂起**，由 taiji runtime 的 marker 显式分支路由到 CanvasService；应答回来后经 `extension_ui_response` 按 id 精确解挂。
+
+关键行为（agent 必须知道的三点）：
+
+1. **调用会挂起等待，不是即时返回**：用户正在 GUI 画布上看图、圈选、写批注，应答要等 runtime 侧处理完才回来。这是设计内形态，不是卡死。
+2. **无墙钟超时**：挂起不设时限（任务级正常路径不设限），任意晚的应答都会按 id 解挂。等待期间不要重试同一调用——重试会产生第二个挂起请求。
+3. **用户的 GUI 裁决（圈选 / 否决 / 批注）以画布事件通知回推**：收到通知后**必须先 `canvas_read` 读当前状态再行动**（read-before-act 纪律），不要凭记忆编辑。
+
+## 宿主检测：canvas_unavailable_host
+
+画布工具只在 taiji GUI 托管的 pi 里可用。前置门在 select 之前（`isTaijiGuiHost` 谓词：`TAIJI_AGENT_EXT_LOG === "1"` 且 `ctx.mode === "rpc"`），不满足时直接返回结构化错误、不进入 select：
+
+```
+canvas_unavailable_host: 画布需要 taiji 宿主。…
+恢复动作：在 taiji 桌面应用的会话中使用画布工具；纯 pi 环境请直接以对话方式规划。
+```
+
+成因两种：① 本来就在独立 pi CLI / TUI 里跑（画布不可用，属正常拒绝）；② env 泄漏或 mode 异常（在 taiji 里却报此错——检查 pi 进程 env 是否带 `TAIJI_AGENT_EXT_LOG=1`）。
+
+## 错误闭环（失败可区分，按恢复动作重试）
+
+工具报错分三类，全部 throw（isError 消息可见），agent 可据此决定重试或放弃：
+
+| 错误形态 | 含义 | 处置 |
+|---|---|---|
+| `canvas <action>: cancelled or channel error` | 通道失败（取消/断连） | 重试一次；连续失败转排障节查日志 |
+| `non-JSON response from runtime` / 「应答不是合法 JSON（runtime 契约漂移）」 | runtime 与 extension 版本错配 | 核对两侧同版本后重试 |
+| `canvas <action> 被拒绝 [<错误码>] … 恢复动作：…` | 领域拒绝（不变量拦截，如 not_converged） | 按消息里的恢复动作修正后重试，不要原样重发 |
+
+## 存储概览（只读理解用，agent 不直改文件）
+
+画布数据在 taiji runtime 数据目录 `<dataDir>/canvases/<canvasId>/` 下：
+
+| 文件 | 角色 |
+|---|---|
+| `events.jsonl` | **唯一持久权威**：append-only 领域事件流，每行一个 JSON 事件（seq 从 1 起 per-canvas 单调）。状态疑义以此文件为准 |
+| `canvas.json` | 加速快照 + 锚点（锚点 eventId ≤ 事件流末条，永不超前）。损坏时从 events.jsonl 全量重放重建 |
+| `exports/` | 导出产物（planning-doc / requirement-card） |
+
+`<dataDir>` 按环境：taiji dev = `~/.taiji-dev`，taiji prod = `~/.taiji`（`TAIJI_AGENT_DATA_DIR` 可隔离）。修改画布只经 `canvas_edit` / `canvas_review` 工具走领域校验，**禁止手改这两个文件**。
+
+## 排障入口：扩展日志
+
+文件日志由 pi-extension-logger 双开关分级写 `<agentDir>/logs/pi-canvas-YYYY-MM-DD.log`：
+
+| 开关 | 行为 |
+|---|---|
+| `TAIJI_AGENT_EXT_LOG=1` | INFO 档落盘（taiji 托管环境 runtime spawn pi 时恒注入）+ 7 天保留期清理 |
+| `TAIJI_AGENT_DEBUG=1` | DEBUG 全量（两变量同时注入按更详细的生效） |
+| 均未注入 | no-op——零磁盘、无日志文件（裸 pi 默认即此） |
+
+**宿主要求**：`TAIJI_AGENT_EXT_LOG=1` 在 taiji 里由 runtime 统一注入，无需手配；裸 pi 独立用户要文件日志须自己 export（但画布工具本身在裸 pi 下不可用，日志只有通道报错可看）。
+
+`<agentDir>` 按环境（`PI_CODING_AGENT_DIR` 决定，taiji 隔离到 `<dataDir>/agent/`）：
+
+| 环境 | 日志路径 | 画布数据 |
+|---|---|---|
+| 独立 pi CLI | `~/.pi/agent/logs/` | 不可用（canvas_unavailable_host） |
+| taiji dev | `~/.taiji-dev/agent/logs/` | `~/.taiji-dev/canvases/` |
+| taiji prod | `~/.taiji/agent/logs/` | `~/.taiji/canvases/` |
+
+排障顺序：先看工具 isError 消息里的错误码与恢复动作（多数问题到此为止）→ 需要通道级细节再读当日 `pi-canvas-*.log`（marker 调用失败会带 action 名落日志）→ 数据疑义以 `events.jsonl` 为准核对。

package/src/__tests__/available-tools.test.ts

@@ -0,0 +1,84 @@
+// available-tools.test.ts —— <available_tools> 常驻存在性段（D3-A1 验收实证的
+// 入口可见性修复：pi 1.0.0 下 deferred 工具对模型零感知，name + description 须
+// 常驻 system prompt 并写明 tool_search 激活路径）。
+
+import { describe, expect, it } from "vitest";
+
+import { buildAvailableToolsSection, CANVAS_AVAILABLE_TOOLS } from "../index.js";
+import { CANVAS_TOOL_NAMES } from "@zhushanwen/extension-protocol";
+
+import { mountCanvas, withExtLogEnv, type BeforeAgentStartShape } from "./helpers/canvas-harness.js";
+
+describe("CANVAS_AVAILABLE_TOOLS 单源", () => {
+  it("清单 = 六工具全集，与 U1 契约 CANVAS_TOOL_NAMES 一致", () => {
+    expect(CANVAS_AVAILABLE_TOOLS.map((t) => t.name).sort()).toEqual([...CANVAS_TOOL_NAMES].sort());
+  });
+
+  it("每条 description 与注册进 pi 的工具 description 逐字一致（注册配置从本单源引用）", () => {
+    // 一致性由 index.ts 注册配置直接引用本清单保证；此处锁单源形态：
+    // 每条非空、无换行（列表形态依赖）
+    for (const tool of CANVAS_AVAILABLE_TOOLS) {
+      expect(tool.description.trim().length).toBeGreaterThan(40);
+      expect(tool.description).not.toContain("\n");
+    }
+  });
+});
+
+describe("buildAvailableToolsSection（纯函数）", () => {
+  it("段内含每个工具的 name 与完整 description 及 tool_search 激活指引", () => {
+    const section = buildAvailableToolsSection(CANVAS_AVAILABLE_TOOLS);
+    expect(section.startsWith("<available_tools>\n")).toBe(true);
+    expect(section.endsWith("\n</available_tools>")).toBe(true);
+    expect(section).toContain("tool_search");
+    for (const tool of CANVAS_AVAILABLE_TOOLS) {
+      expect(section).toContain(`- ${tool.name}: ${tool.description}`);
+    }
+  });
+
+  it("description 多行文本被单行化（列表项内换行破坏列表形态）", () => {
+    const section = buildAvailableToolsSection([{ name: "t", description: "a\n\nb  c" }]);
+    expect(section).toContain("- t: a b c");
+  });
+});
+
+describe("before_agent_start 注入钩子", () => {
+  it("taiji GUI 宿主下返回追加了 <available_tools> 段的 systemPrompt，段内含六工具与激活指引", async () => {
+    const { beforeAgentStartHandlers } = mountCanvas();
+    expect(beforeAgentStartHandlers).toHaveLength(1);
+    const handler = beforeAgentStartHandlers[0];
+    const result = await withExtLogEnv("1", () =>
+      handler({ systemPrompt: "BASE PROMPT" } as BeforeAgentStartShape, { mode: "rpc" }),
+    );
+    expect(result).toBeDefined();
+    expect(result?.systemPrompt.startsWith("BASE PROMPT\n\n<available_tools>")).toBe(true);
+    expect(result?.systemPrompt).toContain("</available_tools>");
+    expect(result?.systemPrompt).toContain("tool_search");
+    for (const name of CANVAS_TOOL_NAMES) {
+      expect(result?.systemPrompt).toContain(`- ${name}: `);
+    }
+  });
+
+  it("env 信号缺失或非 rpc 模式均不注入（与工具 execute 宿主守卫同谓词）", async () => {
+    const { beforeAgentStartHandlers } = mountCanvas();
+    const handler = beforeAgentStartHandlers[0];
+    const envMissing = await withExtLogEnv(undefined, () =>
+      handler({ systemPrompt: "B" } as BeforeAgentStartShape, { mode: "rpc" }),
+    );
+    expect(envMissing).toBeUndefined();
+    const notRpc = await withExtLogEnv("1", () =>
+      handler({ systemPrompt: "B" } as BeforeAgentStartShape, { mode: "tui" }),
+    );
+    expect(notRpc).toBeUndefined();
+  });
+
+  it("同输入两次调用输出一致（每轮注入相同文本，KV-cache 前缀稳定）", async () => {
+    const { beforeAgentStartHandlers } = mountCanvas();
+    const handler = beforeAgentStartHandlers[0];
+    const [a, b] = await withExtLogEnv("1", () => {
+      const event = { systemPrompt: "BASE" } as BeforeAgentStartShape;
+      const ctx = { mode: "rpc" };
+      return [handler(event, ctx), handler(event, ctx)];
+    });
+    expect(a?.systemPrompt).toBe(b?.systemPrompt);
+  });
+});

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

@@ -0,0 +1,75 @@
+// canvas-harness.ts —— pi-canvas 测试共享装配 harness（session-manager 同款样板：
+// registerTool 捕获 + before_agent_start 捕获 + rpc ctx 桩 + select 桩；断言全部留在各测试文件）。
+
+import { expect, vi, type Mock } from "vitest";
+
+import registerExtension from "../../index.js";
+
+/** registerTool 捕获的注册工具形态（execute 以固定五参形态调用）。 */
+export interface RegisteredTool { // oe-exempt:20261015:framework:画布域类型契约（数据形状/端口/测试 harness，非抽象接口单实现）
+  name: string;
+  exposure?: string;
+  parameters: unknown;
+  execute: (...args: unknown[]) => Promise<unknown>;
+}
+
+/** before_agent_start handler 的事件/ctx 最小形态（index.ts 只消费 systemPrompt 与 ctx.mode）。 */
+export interface BeforeAgentStartShape { // oe-exempt:20261015:framework:画布域类型契约（数据形状/端口/测试 harness，非抽象接口单实现）
+  systemPrompt: string;
+}
+
+export type BeforeAgentStartHandler = (
+  event: BeforeAgentStartShape,
+  ctx: { mode: string },
+) => { systemPrompt: string } | undefined;
+
+export interface ToolHarness { // oe-exempt:20261015:framework:画布域类型契约（数据形状/端口/测试 harness，非抽象接口单实现）
+  registered: RegisteredTool[];
+  selectMock: Mock;
+  /** 捕获的 before_agent_start handler（index.ts 只注册一个；空数组 = 未注册）。 */
+  beforeAgentStartHandlers: BeforeAgentStartHandler[];
+  /** rpc 模式 ctx 桩（ui.select → selectMock）。 */
+  ctx: { mode: "rpc"; hasUI: true; ui: { select: Mock } };
+}
+
+/** 挂载被测 extension：捕获六工具 + before_agent_start + select 桩。 */
+export function mountCanvas(): ToolHarness {
+  const registered: RegisteredTool[] = [];
+  const beforeAgentStartHandlers: BeforeAgentStartHandler[] = [];
+  registerExtension({
+    registerTool: (tool: RegisteredTool) => registered.push(tool),
+    on: (event: string, handler: BeforeAgentStartHandler) => {
+      if (event === "before_agent_start") beforeAgentStartHandlers.push(handler);
+    },
+  } as never);
+  const selectMock = vi.fn();
+  const ctx = { mode: "rpc" as const, hasUI: true as const, ui: { select: selectMock } };
+  return { registered, selectMock, beforeAgentStartHandlers, ctx };
+}
+
+/** 按名取已注册工具（缺名 = 注册面回归，直接红）。 */
+export function toolOf(harness: ToolHarness, name: string): RegisteredTool {
+  const tool = harness.registered.find((t) => t.name === name);
+  expect(tool, `tool ${name} must be registered`).toBeDefined();
+  return tool as RegisteredTool;
+}
+
+/** select 桩的一次 marker 调用解包（(marker, [payload], opts) 形态 → {marker, payload, opts}；取最近一次）。 */
+export function lastMarkerCall(selectMock: Mock): { marker: string; payload: Record<string, unknown>; opts: unknown } {
+  const call = selectMock.mock.calls[selectMock.mock.calls.length - 1] as [string, [string], unknown];
+  return { marker: call[0], payload: JSON.parse(call[1][0]) as Record<string, unknown>, opts: call[2] };
+}
+
+/** env 信号保全切换（TAIJI_AGENT_EXT_LOG 非数据目录，无副作用面；用后即还）。
+ * async 等待式：await fn() 完成后才恢复——env 变更覆盖被测代码的全部 await 点。 */
+export async function withExtLogEnv<T>(value: string | undefined, fn: () => Promise<T> | T): Promise<T> {
+  const prev = process.env.TAIJI_AGENT_EXT_LOG;
+  if (value === undefined) delete process.env.TAIJI_AGENT_EXT_LOG;
+  else process.env.TAIJI_AGENT_EXT_LOG = value;
+  try {
+    return await fn();
+  } finally {
+    if (prev === undefined) delete process.env.TAIJI_AGENT_EXT_LOG;
+    else process.env.TAIJI_AGENT_EXT_LOG = prev;
+  }
+}

package/src/__tests__/host.test.ts

@@ -0,0 +1,44 @@
+// host.test.ts —— 宿主检测真值表（设计：env 信号 + ctx.mode === "rpc" 完整谓词；
+// 非 taiji GUI 宿主不进入 select）。
+
+import { isTaijiHost } from "@zhushanwen/pi-ext-guards";
+import { describe, expect, it } from "vitest";
+
+// isTaijiGuiHost 经 host.js re-export（canvas 工具门实走同一引用）；isTaijiHost
+// env 腿无 canvas 侧业务消费方，直接从共享谓词单点 import。
+import { hostGateError, isTaijiGuiHost } from "../host.js";
+import { withExtLogEnv } from "./helpers/canvas-harness.js";
+
+describe("isTaijiHost / isTaijiGuiHost", () => {
+  it("env 信号缺失 = 非宿主（mode 无关）", () =>
+    withExtLogEnv(undefined, () => {
+      expect(isTaijiHost()).toBe(false);
+      expect(isTaijiGuiHost({ mode: "rpc" })).toBe(false);
+    }));
+
+  it("env=1 但 mode 非 rpc（TUI / json / print）= 非 GUI 宿主（env 泄漏形态，禁入 select）", () =>
+    withExtLogEnv("1", () => {
+      expect(isTaijiHost()).toBe(true);
+      expect(isTaijiGuiHost({ mode: "tui" })).toBe(false);
+      expect(isTaijiGuiHost({ mode: "json" })).toBe(false);
+      expect(isTaijiGuiHost({ mode: "print" })).toBe(false);
+    }));
+
+  it("env=1 + rpc = taiji GUI 宿主", () =>
+    withExtLogEnv("1", () => {
+      expect(isTaijiGuiHost({ mode: "rpc" })).toBe(true);
+    }));
+
+  it("env 非 '1' 值 = 非宿主（严格等值判定）", () =>
+    withExtLogEnv("0", () => {
+      expect(isTaijiHost()).toBe(false);
+    }));
+});
+
+describe("hostGateError", () => {
+  it("结构化错误含「画布需要 taiji 宿主」与恢复动作", () => {
+    const err = hostGateError();
+    expect(err.message).toContain("画布需要 taiji 宿主");
+    expect(err.message).toContain("恢复动作");
+  });
+});

package/src/__tests__/review.test.ts

@@ -0,0 +1,300 @@
+// review.test.ts —— 审查编排单元（review.ts）：派发端口解析 / 轮次推进 / 条目校验
+// 与写回 / 失败显式上报。编排链的 marker 往返（review-request / read / append 的
+// 载荷形状）由 tool-execute.test.ts 通道层覆盖，此处聚焦编排纯逻辑。
+
+import { afterEach, describe, expect, it } from "vitest";
+
+import type { CanvasState } from "@zhushanwen/extension-protocol";
+
+import {
+  REVIEWER_REPORT_SCHEMA,
+  buildReviewerTask,
+  collectValidEntries,
+  currentReviewRound,
+  isCanvasStateReply,
+  renderResolutionTable,
+  resolveReviewerDispatcher,
+  runReviewRound,
+  type ReviewerDispatchPort,
+} from "../review.js";
+import { withExtLogEnv } from "./helpers/canvas-harness.js";
+
+const SLOT_KEY = Symbol.for("@zhushanwen/subagent-core.service");
+
+function makeState(overrides: Partial<CanvasState> = {}): CanvasState {
+  return {
+    canvasId: "c1",
+    name: "多引擎支持",
+    root: { nodeId: "root", statement: "多引擎支持怎么落地", criterias: ["c"], scopeExclusions: [] },
+    direction: null,
+    nodes: [],
+    edges: [],
+    comments: [],
+    dirtyPaths: [],
+    review: null,
+    converged: false,
+    createdAt: "2026-10-14T00:00:00Z",
+    updatedAt: "2026-10-14T00:00:00Z",
+    ...overrides,
+  };
+}
+
+afterEach(() => {
+  delete (globalThis as Record<symbol, unknown>)[SLOT_KEY];
+});
+
+describe("resolveReviewerDispatcher（SubagentService 访问器）", () => {
+  it("槽缺位（current=null）→ 结构化错误（review_dispatch_unavailable + 恢复动作）", () =>
+    withExtLogEnv(undefined, () => {
+      expect(() => resolveReviewerDispatcher()).toThrow(/review_dispatch_unavailable/);
+      expect(() => resolveReviewerDispatcher()).toThrow(/恢复动作/);
+    }));
+
+  it("current 形态漂移（executeAndAwait 非函数）→ 同款结构化错误", () => {
+    (globalThis as Record<symbol, unknown>)[SLOT_KEY] = { current: { nope: true } };
+    expect(() => resolveReviewerDispatcher()).toThrow(/review_dispatch_unavailable/);
+  });
+
+  it("current 形态合法 → 经访问器返回 service 本体（D3-A4：旧 mock 把本体直放槽里，与断链的生产形态不同构）", () => {
+    const port: ReviewerDispatchPort = { executeAndAwait: async () => ({}) };
+    // 生产形状 = {current} 持有者（service-bootstrap.ts setSubagentService 只置 .current）
+    (globalThis as Record<symbol, unknown>)[SLOT_KEY] = { current: port };
+    expect(resolveReviewerDispatcher()).toBe(port);
+  });
+});
+
+describe("轮次与收窄输入", () => {
+  it("currentReviewRound：read 回包的 review.round 即本轮轮次（run 链路 read 发生在 review-request 之后）；从未审查 = R1", () => {
+    // 从未审查（read 无 review 聚合）= R1
+    expect(currentReviewRound(makeState())).toBe(1);
+    // GUI 双跳第二跳：user 发起 R1（尚无报告条目）→ agent run 的 read = round 1（不再 +1）
+    expect(
+      currentReviewRound(
+        makeState({
+          review: { status: "in-progress", round: 1, maxRounds: 5, entries: [] },
+        }),
+      ),
+    ).toBe(1);
+    // runtime 推进到 R2 后的 read = round 2
+    expect(
+      currentReviewRound(
+        makeState({
+          review: { status: "in-progress", round: 2, maxRounds: 5, entries: [] },
+        }),
+      ),
+    ).toBe(2);
+  });
+
+  it("renderResolutionTable：条目 × 处置状态逐条渲染；未处置显式标注", () => {
+    const table = renderResolutionTable(
+      makeState({
+        review: {
+          status: "in-progress",
+          round: 1,
+          maxRounds: 5,
+          entries: [
+            {
+              id: "rv-1",
+              round: 1,
+              dimension: "support",
+              severity: "must-fix",
+              targetId: "n1",
+              note: "悬空断言",
+              resolution: { disposition: "accepted", by: "agent", note: "补了论据" },
+            },
+            { id: "rv-2", round: 1, dimension: "conflict", severity: "suggestion", targetId: "n2", note: "候选矛盾" },
+          ],
+        },
+      }),
+    );
+    expect(table).toContain("[rv-1]");
+    expect(table).toContain("accepted（by agent）：补了论据");
+    expect(table).toContain("[rv-2]");
+    expect(table).toContain("未处置");
+  });
+
+  it("buildReviewerTask：R1 含六维度词表与画布 JSON；R2+ 注入 scope 与处置表", () => {
+    const state = makeState();
+    const r1 = buildReviewerTask(state, 1);
+    expect(r1).toContain("completeness");
+    expect(r1).toContain("depth");
+    expect(r1).toContain('"canvasId":"c1"');
+    expect(r1).not.toContain("本轮审查范围");
+    const r2 = buildReviewerTask(state, 2, "上轮处置表 + 攻击点");
+    expect(r2).toContain("R2 复审");
+    expect(r2).toContain("上轮处置表 + 攻击点");
+  });
+
+  it("reviewer schema：entries 必填、六维度 enum、severity 两值、supportRating 三值", () => {
+    const entries = REVIEWER_REPORT_SCHEMA.properties as { entries: { items: { properties: Record<string, { enum?: string[]; type?: string }> }; type: string } };
+    expect(entries.entries.type).toBe("array");
+    expect(entries.entries.items.properties.dimension.enum).toEqual([
+      "completeness",
+      "necessity",
+      "support",
+      "authenticity",
+      "conflict",
+      "depth",
+    ]);
+    expect(entries.entries.items.properties.severity.enum).toEqual(["must-fix", "suggestion"]);
+    expect(entries.entries.items.properties.supportRating.enum).toEqual(["sufficient", "gap", "invalid"]);
+    expect(entries.entries.items.properties.supportGaps.type).toBe("array");
+  });
+});
+
+describe("collectValidEntries（reviewer 产出不信任校验）", () => {
+  it("合法条目收集（借契约守卫逐条校验），畸形条目丢弃并计数", () => {
+    const valid = { id: "rv-1", dimension: "support", severity: "must-fix", targetId: "n1", note: "x" };
+    const badWord = { id: "rv-2", dimension: "style", severity: "must-fix", targetId: "n1", note: "x" };
+    const badShape = { id: "rv-3", dimension: "support", severity: "must-fix", note: "缺 targetId" };
+    const { entries, dropped } = collectValidEntries("c1", 1, { entries: [valid, badWord, badShape] });
+    expect(entries).toEqual([{ ...valid, round: 1 }]);
+    expect(dropped).toBe(2);
+  });
+
+  it("支撑度评价透传：gap 附清单合法收集；gap 无清单 / 词表外 rating / 孤儿清单丢弃计数", () => {
+    const rated = { id: "rv-1", dimension: "support", severity: "must-fix", targetId: "e-o1", note: "悬空", supportRating: "gap", supportGaps: ["缺性能论据"] };
+    const noGaps = { id: "rv-2", dimension: "support", severity: "must-fix", targetId: "e-o1", note: "x", supportRating: "gap" };
+    const badWord = { id: "rv-3", dimension: "support", severity: "must-fix", targetId: "e-o1", note: "x", supportRating: "strong" };
+    const orphan = { id: "rv-4", dimension: "support", severity: "must-fix", targetId: "e-o1", note: "x", supportGaps: ["孤儿"] };
+    const sufficient = { id: "rv-5", dimension: "support", severity: "suggestion", targetId: "e-o1", note: "支撑成立", supportRating: "sufficient" };
+    const { entries, dropped } = collectValidEntries("c1", 2, { entries: [rated, noGaps, badWord, orphan, sufficient] });
+    expect(entries).toEqual([
+      { ...rated, round: 2 },
+      { ...sufficient, round: 2 },
+    ]);
+    expect(dropped).toBe(3);
+  });
+
+  it("entries 非数组（LLM 畸形输出）→ 全丢弃、dropped=1", () => {
+    const { entries, dropped } = collectValidEntries("c1", 1, { entries: "nope" });
+    expect(entries).toEqual([]);
+    expect(dropped).toBe(1);
+  });
+});
+
+describe("isCanvasStateReply（read 回包收窄）", () => {
+  it("CanvasState 形状放行；缺 nodes / 非对象拒绝", () => {
+    expect(isCanvasStateReply(makeState())).toBe(true);
+    expect(isCanvasStateReply({ canvasId: "c1", name: "n", root: {} })).toBe(false);
+    expect(isCanvasStateReply("text")).toBe(false);
+  });
+});
+
+describe("runReviewRound（编排主体）", () => {
+  // 每用例独立写回收集器（不做跨用例共享状态）
+  const makeAppend = () => {
+    const calls: unknown[] = [];
+    return {
+      calls,
+      append: async (params: unknown): Promise<void> => {
+        calls.push(params);
+      },
+    };
+  };
+
+  it("写回链：reviewer 合法条目经 appendWriteBack 落 round 与 canvasId，结果汇总条数", async () => {
+    const append = makeAppend();
+    const calls: unknown[] = [];
+    const dispatch: ReviewerDispatchPort = {
+      executeAndAwait: async (opts) => {
+        calls.push(opts);
+        return {
+          parsedOutput: {
+            entries: [{ id: "rv-1", dimension: "support", severity: "must-fix", targetId: "n1", note: "悬空" }],
+            summary: "2 处支撑缺口",
+          },
+        };
+      },
+    };
+    const outcome = await runReviewRound({
+      state: makeState(),
+      dispatch,
+      appendWriteBack: append.append,
+    });
+    expect(outcome.round).toBe(1);
+    expect(outcome.appended).toBe(1);
+    expect(outcome.dropped).toBe(0);
+    expect(outcome.summary).toBe("2 处支撑缺口");
+    expect(append.calls).toEqual([
+      {
+        canvasId: "c1",
+        round: 1,
+        entries: [{ id: "rv-1", dimension: "support", severity: "must-fix", targetId: "n1", note: "悬空", round: 1 }],
+      },
+    ]);
+    // 派发参数：task 内联画布 JSON + reviewer schema；slug 固定
+    expect(calls).toHaveLength(1);
+    const opts = calls[0] as { slug: string; task: string; schema: unknown; signal?: undefined };
+    expect(opts.slug).toBe("canvas-review");
+    expect(opts.task).toContain('"canvasId":"c1"');
+    expect(opts.schema).toBe(REVIEWER_REPORT_SCHEMA);
+  });
+
+  it("R1 run（GUI 双跳第二跳：round=1 且尚无报告条目）→ 报告标 R1（不超前一轮），prompt 为全面审", async () => {
+    const append = makeAppend();
+    let capturedTask = "";
+    const dispatch: ReviewerDispatchPort = {
+      executeAndAwait: async (opts) => {
+        capturedTask = opts.task;
+        return { parsedOutput: { entries: [] } };
+      },
+    };
+    const outcome = await runReviewRound({
+      // run 链路时序：read 发生在 review-request 之后——input.state 是发起后形态
+      //（user 发起 R1 → 回推 → agent run；R1 尚无报告条目）
+      state: makeState({
+        review: { status: "in-progress", round: 1, maxRounds: 5, entries: [] },
+      }),
+      dispatch,
+      appendWriteBack: append.append,
+    });
+    expect(outcome.round).toBe(1);
+    expect(capturedTask).toContain("R1 全面审查");
+    // 全 clean 轮：零条目不写回（append 不被调用）
+    expect(append.calls).toHaveLength(0);
+  });
+
+  it("R2 run（runtime 已推进 round=2）→ 报告标 R2，scope 收窄 + 上轮处置表进 task", async () => {
+    const append = makeAppend();
+    let capturedTask = "";
+    const dispatch: ReviewerDispatchPort = {
+      executeAndAwait: async (opts) => {
+        capturedTask = opts.task;
+        return { parsedOutput: { entries: [] } };
+      },
+    };
+    const outcome = await runReviewRound({
+      state: makeState({
+        review: {
+          status: "in-progress",
+          round: 2,
+          maxRounds: 5,
+          entries: [{ id: "rv-1", round: 1, dimension: "support", severity: "must-fix", targetId: "n1", note: "悬空断言" }],
+        },
+      }),
+      scope: "只审处置表",
+      dispatch,
+      appendWriteBack: append.append,
+    });
+    expect(outcome.round).toBe(2);
+    expect(capturedTask).toContain("R2 复审");
+    expect(capturedTask).toContain("只审处置表");
+    expect(capturedTask).toContain("[rv-1]");
+    expect(append.calls).toHaveLength(0);
+  });
+
+  it("reviewer 执行失败（error 信封）→ 显式 throw（review_dispatch_failed + 恢复动作）", async () => {
+    const append = makeAppend();
+    const dispatch: ReviewerDispatchPort = {
+      executeAndAwait: async () => ({ error: "engine spawn failed" }),
+    };
+    await expect(
+      runReviewRound({ state: makeState(), dispatch, appendWriteBack: append.append }),
+    ).rejects.toThrow(/review_dispatch_failed/);
+    await expect(
+      runReviewRound({ state: makeState(), dispatch, appendWriteBack: append.append }),
+    ).rejects.toThrow(/恢复动作/);
+    expect(append.calls).toHaveLength(0);
+  });
+});