@zhushanwen/pi-subagent-workflow 9.4.0 → 9.5.0

package/src/interface/tool/__tests__/capture-tool.ts

@@ -1,8 +1,8 @@
 /**
- * 注册层黑盒测试共享捕获 helper：fake pi 收集 registerTool 入参，断言恰好注册
- * 一个 tool（可锁定期望名）并返回首个。此前 7 个测试文件各自内联同构拷贝
- * （fake pi + tools 数组 + name 断言 + CapturedTool 类型），收敛至此单点；
- * 差异面（注册函数、pi 之后的实参、deps 形状）留在调用方闭包。
+ * 注册层黑盒测试共享捕获 helper：fake pi 收集 registerTool 入参，支持两种形态——
+ * ①恰好注册一个 tool（可锁定期望名）；②一次注册多个工具（D3 拆分：registerSubagentTool
+ * 注册三工具、registerWorkflowTool 注册两工具）按名捕获。差异面（注册函数、pi 之后
+ * 的实参、deps 形状）留在调用方闭包。
  */
 
 /** 注册层捕获到的 tool 定义最小形态（各文件按需用泛型传窄 view 类型）。 */
@@ -32,25 +32,46 @@ export interface ScriptResultToolView extends CapturedTool { // oe-exempt:202609
   }>;
 }
 
+/** 注册并捕获全部 tool 定义，按名索引（D3 拆分多工具注册形态）。 */
+export function captureToolsByName(
+  register: (pi: { registerTool: (tool: unknown) => void }) => void,
+): Record<string, CapturedTool> {
+  const tools: unknown[] = [];
+  register({ registerTool: (tool) => tools.push(tool) });
+  const byName: Record<string, CapturedTool> = {};
+  for (const tool of tools) {
+    const named = tool as CapturedTool;
+    byName[named.name] = named;
+  }
+  if (tools.length === 0) {
+    throw new Error("expected at least one registered tool, got 0");
+  }
+  return byName;
+}
+
 /**
  * 注册并捕获 tool 定义。泛型 T 供需要窄 execute 返回类型的调用方传 view
  * 类型（方法参数双变 + 返回协变，窄形态天然 extends CapturedTool，零 cast）。
  *
  * @param register 拿 fake pi 执行注册（调用方闭包内传齐注册函数与其余实参）
- * @param expectedName 期望的 tool 名（缺省不锁定——仅断言恰好注册一个）
+ * @param expectedName 期望的 tool 名——给定：多工具注册中按名取出（D3 拆分形态）；
+ *   缺省：断言恰好注册一个并返回首个（单工具注册形态）
  */
 export function captureTool<T extends CapturedTool = CapturedTool>(
   register: (pi: { registerTool: (tool: unknown) => void }) => void,
   expectedName?: string,
 ): T {
-  const tools: unknown[] = [];
-  register({ registerTool: (tool) => tools.push(tool) });
-  const first = tools[0] as T | undefined;
-  if (first === undefined || tools.length !== 1) {
-    throw new Error(`expected exactly one registered tool, got ${tools.length}`);
+  const byName = captureToolsByName(register);
+  if (expectedName !== undefined) {
+    const named = byName[expectedName] as T | undefined;
+    if (named === undefined) {
+      throw new Error(`expected registered tool '${expectedName}', got names: ${Object.keys(byName).join(", ")}`);
+    }
+    return named;
   }
-  if (expectedName !== undefined && first.name !== expectedName) {
-    throw new Error(`expected registered tool '${expectedName}', got '${String(first.name)}'`);
+  const names = Object.keys(byName);
+  if (names.length !== 1) {
+    throw new Error(`expected exactly one registered tool, got ${names.length}`);
   }
-  return first;
+  return byName[names[0]] as T;
 }

package/src/interface/tool/__tests__/subagent-tool-actions.test.ts

@@ -1,13 +1,15 @@
 /**
- * subagent tool 非 start 通道 + renderCall 预解析测试（与 path-guard 的 start 守卫面
- * 互补，覆盖 executeSubagent 的 action 路由全分支与 renderCall 的 model 预解析降级链）。
+ * subagent 工具组非 start 通道 + renderCall 预解析测试（与 path-guard 的 start 守卫面
+ * 互补，覆盖 subagent_manage / subagent_message 的 action 路由全分支、subagent_start
+ * 的顶层透传与 renderCall 的 model 预解析降级链）。
  *
- * 覆盖面：
- *   - execute：service 缺席 → 带恢复动作的错误；未知 action → immediate throw；
- *     list/cancel/message/close/fork-from 六通道 handler 接线 + adapter 包装
- *     （content JSON 给 LLM / details 领域对象给 renderResult）
- *   - renderCall：model override 三层解析（override 在场 → resolved 注入标题；
- *     resolveModel 抛错 → 降级不崩；override 缺省 → resolved undefined）
+ * 覆盖面（tool-declaration-slimming D3 拆分后）：
+ *   - subagent_start：service 缺席 → 带恢复动作的错误；顶层 params 原样透传
+ *   - subagent_manage：list/cancel/close 三通道 handler 接线 + adapter 包装；
+ *     未知 action → immediate throw
+ *   - subagent_message：message/fork-from 两通道接线；未知 action → immediate throw
+ *   - renderCall（subagent_start）：model override 三层解析（override 在场 → resolved
+ *     注入标题；resolveModel 抛错 → 降级不崩；override 缺省 → resolved undefined）
  *
  * mock 策略：六 handler 深路径 stub（领域内核行为由 core 侧
  * subagent-actions-core.test.ts 锁定，此处只测接线）；pi-ai/typebox 用共享桩
@@ -65,15 +67,18 @@ interface SubagentToolView { // oe-exempt:20260930:test:test double shape for to
   renderCall: (args: unknown, theme: unknown, ctx: unknown) => { render(width: number): string[] };
 }
 
-function captureTool(): SubagentToolView {
+/** 按名捕获注册的 tool（D3 拆分：一次注册三个）。 */
+function captureToolByName(toolName: string): SubagentToolView {
   let captured: SubagentToolView | undefined;
   const pi = mockExtensionApi({
     registerTool: (tool: unknown) => {
-      captured = tool as SubagentToolView;
+      if ((tool as { name?: string }).name === toolName) {
+        captured = tool as SubagentToolView;
+      }
     },
   });
   registerSubagentTool(pi);
-  if (!captured) throw new Error("subagent tool not registered");
+  if (!captured) throw new Error(`${toolName} tool not registered`);
   return captured;
 }
 
@@ -97,29 +102,47 @@ afterEach(() => {
   resetServiceSlot();
 });
 
-describe("subagent tool execute：守卫与缺席面", () => {
+describe("注册面：三工具名（D3 拆分终态）", () => {
+  it("registerSubagentTool 注册 subagent_start / subagent_manage / subagent_message 三工具", () => {
+    const names: string[] = [];
+    const pi = mockExtensionApi({
+      registerTool: (tool: unknown) => names.push((tool as { name: string }).name),
+    });
+    registerSubagentTool(pi);
+    expect(names.sort()).toEqual(["subagent_manage", "subagent_message", "subagent_start"]);
+  });
+});
+
+describe("subagent_start execute：守卫与缺席面", () => {
   it("service 缺席 → immediate throw，错误带恢复动作指引", async () => {
-    const tool = captureTool(); // 槽未注入
+    const tool = captureToolByName("subagent_start"); // 槽未注入
     await expect(
-      tool.execute("c1", { action: "list" }, undefined, undefined, undefined),
+      tool.execute("c1", { task: "t", slug: "s" }, undefined, undefined, undefined),
     ).rejects.toThrow(/subagents runtime not initialized.*Recovery: reload this session/s);
   });
+});
 
-  it("未知 action → immediate throw（Unknown subagent action）", async () => {
+describe("subagent_manage execute：三 action 通道接线", () => {
+  /** 注入最小 fake service 并捕获 manage 工具（三通道共用基座）。 */
+  function withService(): SubagentToolView {
     setSubagentService({ execute: vi.fn() } as never);
-    const tool = captureTool();
+    return captureToolByName("subagent_manage");
+  }
+
+  it("service 缺席 → immediate throw（manage 同文案单源）", async () => {
+    const tool = captureToolByName("subagent_manage");
     await expect(
-      tool.execute("c2", { action: "pause" }, undefined, undefined, undefined),
-    ).rejects.toThrow("Unknown subagent action: pause");
+      tool.execute("c0", { action: "list" }, undefined, undefined, undefined),
+    ).rejects.toThrow(/subagents runtime not initialized/);
   });
-});
 
-describe("subagent tool execute：六 action 通道接线", () => {
-  /** 注入最小 fake service 并捕获 tool（六通道共用基座）。 */
-  function withService(): SubagentToolView {
+  it("未知 action → immediate throw（Unknown subagent_manage action）", async () => {
     setSubagentService({ execute: vi.fn() } as never);
-    return captureTool();
-  }
+    const tool = withService();
+    await expect(
+      tool.execute("c2", { action: "pause" }, undefined, undefined, undefined),
+    ).rejects.toThrow("Unknown subagent_manage action: pause");
+  });
 
   it("list：listParam 解包透传，adapter 包装 listResponse", async () => {
     vi.mocked(listHandler).mockReturnValue({ response: { items: [], total: 0 } } as never);
@@ -140,15 +163,6 @@ describe("subagent tool execute：六 action 通道接线", () => {
     expect(JSON.parse(result.content[0]!.text)).toMatchObject({ action: "cancel", subagentId: "sa-9" });
   });
 
-  it("message：messageParam 解包透传", async () => {
-    vi.mocked(messageHandler).mockResolvedValue({ subagentId: "sa-7", response: { queued: true } } as never);
-    const tool = withService();
-    const params = { action: "message", messageParam: { subagentId: "sa-7", text: "continue" } };
-    const result = await tool.execute("c5", params, undefined, undefined, undefined);
-    expect(vi.mocked(messageHandler)).toHaveBeenCalledWith(expect.anything(), params.messageParam);
-    expect(JSON.parse(result.content[0]!.text)).toMatchObject({ action: "message", subagentId: "sa-7" });
-  });
-
   it("close：closeParam 解包透传", async () => {
     vi.mocked(closeHandler).mockResolvedValue({ subagentId: "sa-6", response: { archived: true } } as never);
     const tool = withService();
@@ -157,6 +171,23 @@ describe("subagent tool execute：六 action 通道接线", () => {
     expect(vi.mocked(closeHandler)).toHaveBeenCalledWith(expect.anything(), { subagentId: "sa-6" });
     expect(JSON.parse(result.content[0]!.text)).toMatchObject({ action: "close", subagentId: "sa-6" });
   });
+});
+
+describe("subagent_message execute：两 action 通道接线", () => {
+  /** 注入最小 fake service 并捕获 message 工具（两通道共用基座）。 */
+  function withService(): SubagentToolView {
+    setSubagentService({ execute: vi.fn() } as never);
+    return captureToolByName("subagent_message");
+  }
+
+  it("message：messageParam 解包透传", async () => {
+    vi.mocked(messageHandler).mockResolvedValue({ subagentId: "sa-7", response: { queued: true } } as never);
+    const tool = withService();
+    const params = { action: "message", messageParam: { subagentId: "sa-7", text: "continue" } };
+    const result = await tool.execute("c5", params, undefined, undefined, undefined);
+    expect(vi.mocked(messageHandler)).toHaveBeenCalledWith(expect.anything(), params.messageParam);
+    expect(JSON.parse(result.content[0]!.text)).toMatchObject({ action: "message", subagentId: "sa-7" });
+  });
 
   it("fork-from：forkFromParam 解包透传", async () => {
     vi.mocked(forkFromHandler).mockResolvedValue({
@@ -170,7 +201,17 @@ describe("subagent tool execute：六 action 通道接线", () => {
     expect(JSON.parse(result.content[0]!.text)).toMatchObject({ action: "fork-from", subagentId: "sa-new" });
   });
 
-  it("start：合法绝对路径放行，顶层 params 原样透传（含 signal/model override）", async () => {
+  it("未知 action → immediate throw（Unknown subagent_message action）", async () => {
+    setSubagentService({ execute: vi.fn() } as never);
+    const tool = withService();
+    await expect(
+      tool.execute("c2m", { action: "pause" }, undefined, undefined, undefined),
+    ).rejects.toThrow("Unknown subagent_message action: pause");
+  });
+});
+
+describe("subagent_start execute：顶层透传", () => {
+  it("start：合法绝对路径放行，顶层 params 原样透传（无 action 字段；signal/model ctx 透传）", async () => {
     vi.mocked(startHandler).mockResolvedValue({
       subagentId: "sa-1",
       slug: "demo",
@@ -178,9 +219,8 @@ describe("subagent tool execute：六 action 通道接线", () => {
       response: { mode: "background" },
     } as never);
     setSubagentService({ execute: vi.fn() } as never);
-    const tool = captureTool();
+    const tool = captureToolByName("subagent_start");
     const params = {
-      action: "start",
       task: "t",
       slug: "demo",
       skillPath: "/abs/skills/x.md",
@@ -193,12 +233,12 @@ describe("subagent tool execute：六 action 通道接线", () => {
   });
 });
 
-describe("subagent tool renderCall：model 预解析", () => {
+describe("subagent_start renderCall：model 预解析", () => {
   it("override 在场 + resolveModel 成功 → resolved 注入标题（provider/model · thinking）", () => {
     setSubagentService({
       resolveModel: () => ({ model: { provider: "p", id: "m1" }, thinkingLevel: "high" }),
     } as never);
-    const tool = captureTool();
+    const tool = captureToolByName("subagent_start");
     const comp = tool.renderCall({ agent: "coder", model: "p/m1", thinkingLevel: "high", slug: "demo" }, markingTheme, {});
     const text = comp.render(200).join("");
     expect(text).toContain("p/m1");
@@ -212,7 +252,7 @@ describe("subagent tool renderCall：model 预解析", () => {
         throw new Error("registry cold");
       },
     } as never);
-    const tool = captureTool();
+    const tool = captureToolByName("subagent_start");
     const comp = tool.renderCall({ agent: "coder", model: "p/m1" }, markingTheme, {});
     const text = comp.render(80).join("");
     expect(text).toContain("subagent");
@@ -220,7 +260,7 @@ describe("subagent tool renderCall：model 预解析", () => {
   });
 
   it("service 缺席 → resolved undefined 降级；无 agent 字段兜底默认名", () => {
-    const tool = captureTool(); // 槽空
+    const tool = captureToolByName("subagent_start"); // 槽空
     const comp = tool.renderCall({ task: "t" }, markingTheme, {});
     const text = comp.render(80).join("");
     expect(text).toContain("subagent");
@@ -231,8 +271,32 @@ describe("subagent tool renderCall：model 预解析", () => {
     setSubagentService({
       resolveModel: () => ({ model: { provider: "p", id: "m1" }, thinkingLevel: "high" }),
     } as never);
-    const tool = captureTool();
+    const tool = captureToolByName("subagent_start");
     const comp = tool.renderCall(null, markingTheme, {});
     expect(comp.render(80).join("")).toContain("subagent");
   });
 });
+
+describe("subagent_manage / subagent_message renderCall：轻量标题行", () => {
+  it("manage：标题含工具名与 action", () => {
+    const tool = captureToolByName("subagent_manage");
+    const comp = tool.renderCall({ action: "list", listParam: {} }, markingTheme, {});
+    const text = comp.render(200).join("");
+    expect(text).toContain("subagent_manage");
+    expect(text).toContain("list");
+  });
+
+  it("message：标题含工具名与 action", () => {
+    const tool = captureToolByName("subagent_message");
+    const comp = tool.renderCall({ action: "fork-from", forkFromParam: {} }, markingTheme, {});
+    const text = comp.render(200).join("");
+    expect(text).toContain("subagent_message");
+    expect(text).toContain("fork-from");
+  });
+
+  it("args 缺 action → 不崩，标题仍渲染工具名", () => {
+    const tool = captureToolByName("subagent_manage");
+    const comp = tool.renderCall(null, markingTheme, {});
+    expect(comp.render(200).join("")).toContain("subagent_manage");
+  });
+});

package/src/interface/tool/__tests__/subagent-tool-path-guard.test.ts

@@ -5,16 +5,18 @@
 // 闸。schema pattern（^/）经 pi agent-loop 运行时强校验已是强制（PS-20：
 // agent-loop.js:403-404 → validation.js:247-273），工具层守卫定位 = defense-in-depth
 // + schema 表达力缺口——`..` 穿越语义超出 pattern 能力（^/ 放行 "/a/../b"），
-// 守卫在 executeSubagent start 分支 immediate throw（与 action 枚举守卫同风格）。
+// 守卫在 executeSubagentStart immediate throw（与 action 枚举守卫同风格）。
 //
 // 本文件锁住：
 //   1. skillPath / cwd 含 `..` 穿越段 → 同步 reject，service.execute 零触达
 //   2. skillPath / cwd 相对路径 → 同步 reject
 //   3. 合法绝对路径放行 → 参数原样透传 service.execute（守卫零误伤对照）
 //
-// harness（[u-5b / A-V3] 改写）：registerSubagentTool 后捕获 execute 回调直接调用。
+// harness（[u-5b / A-V3] 改写）：registerSubagentTool 后按名捕获 subagent_start 的
+// execute 回调直接调用（D3 拆分：registerSubagentTool 注册三工具，start 守卫在
+// subagent_start 的 execute）。
 // SubagentService 经单例访问器槽注入 fake（setSubagentService，globalThis 槽——
-// executeSubagent 内 getSubagentService() 读同一槽，「守卫拒绝时 service.execute
+// executeSubagentStart 内 getSubagentService() 读同一槽，「守卫拒绝时 service.execute
 // 零触达」的承重断言不依赖整类 mock）；pi-ai/typebox 桩改共享桩
 // （src/__tests__/mocks/runtime-stubs.ts，async 工厂 + 动态 import，消费约定见
 // 桩 module 头注）。
@@ -59,22 +61,24 @@ function resetServiceSlot(): void {
 
 type ExecuteCb = (...args: unknown[]) => Promise<unknown>;
 
-/** 注册 tool 并捕获 execute 回调（sdk-contract 同款）。 */
-function captureExecute(): ExecuteCb {
+/** 注册工具组并按名捕获 subagent_start 的 execute 回调。 */
+function captureStartExecute(): ExecuteCb {
   let captured: ExecuteCb | undefined;
   const pi = mockExtensionApi({
     registerTool: (tool: unknown) => {
-      captured = (tool as { execute: ExecuteCb }).execute;
+      if ((tool as { name?: string }).name === "subagent_start") {
+        captured = (tool as { execute: ExecuteCb }).execute;
+      }
     },
   });
   registerSubagentTool(pi);
-  if (!captured) throw new Error("subagent tool not registered");
+  if (!captured) throw new Error("subagent_start tool not registered");
   return captured;
 }
 
-/** 合法 start 入参基线（守卫测试只变动 skillPath/cwd 字段）。 */
+/** 合法 start 入参基线（守卫测试只变动 skillPath/cwd 字段；start 工具无 action 字段）。 */
 function baseParams(over: Record<string, unknown> = {}): Record<string, unknown> {
-  return { action: "start", task: "guard task", slug: "path-guard", ...over };
+  return { task: "guard task", slug: "path-guard", ...over };
 }
 
 /** 合法 execute 返回值 stub（放行路径 adapter 包装用）。 */
@@ -87,15 +91,15 @@ function stubHandle() {
   };
 }
 
-describe("subagent tool 路径守卫（skillPath/cwd：绝对路径 + 禁 .. 穿越）", () => {
+describe("subagent_start 路径守卫（skillPath/cwd：绝对路径 + 禁 .. 穿越）", () => {
   let execute: ExecuteCb;
 
   beforeEach(() => {
     vi.clearAllMocks();
     mockServiceExecute.mockResolvedValue(stubHandle());
-    // 经真实单例访问器注入 fake service（executeSubagent 内 getSubagentService 读同槽）
+    // 经真实单例访问器注入 fake service（executeSubagentStart 内 getSubagentService 读同槽）
     setSubagentService({ execute: mockServiceExecute, getCollectSyncDefault: () => "async" } as never);
-    execute = captureExecute();
+    execute = captureStartExecute();
   });
 
   afterEach(() => {