@zhushanwen/pi-subagent-workflow 9.2.1 → 9.4.0

package/src/interface/command/__tests__/subagent-model.test.ts

@@ -0,0 +1,242 @@
+/**
+ * /subagent-model 命令 handler 测试（subagent-model-switch §7.1.1，U6）。
+ *
+ * 覆盖（通道契约：全程不抛 + 一切结果落结果文件）：
+ * - 合法 payload → service.setModel 桩 → 结果文件内容 = 应答（core SetModelReply 原样）；
+ * - service.setModel 抛错 → 错误 envelope 文件且 handler 不抛；
+ * - 非法 JSON（无 requestId）→ 零文件 + handler 不抛（runtime 超时路径承接）；
+ * - 字段校验失败（requestId 在场）→ invalid_payload envelope；
+ * - service 未就绪 → subagent_runtime_not_ready envelope；
+ * - 注册形态：命令名 / TUI 模式指引（内部 RPC 通道，无 TUI 分支）。
+ *
+ * mock 策略：runSubagentModelRpc 依赖注入面直驱（不 mock barrel）；落盘全在 mkdtemp tmp。
+ * 运行：cd extensions/universal/subagent-workflow && npx vitest run src/interface/command/__tests__/subagent-model.test.ts
+ */
+import { existsSync, mkdtempSync, readFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import type { ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+
+import { registerSubagentModelCommand, runSubagentModelRpc } from "../subagent-model.ts";
+import type { SubagentModelCommandDeps } from "../subagent-model.ts";
+
+// ── fixture ──────────────────────────────────────────────────
+
+let root: string;
+
+beforeEach(() => {
+  root = mkdtempSync(join(tmpdir(), "subagent-model-cmd-"));
+});
+
+afterEach(() => {
+  rmSync(root, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 });
+});
+
+interface StubService { // oe-exempt:20261006:test:测试专用服务桩装配单实现为常态
+  setModel: ReturnType<typeof vi.fn>;
+  chatActions: { getRecordForAction: ReturnType<typeof vi.fn> };
+}
+
+function stubService(): StubService {
+  return {
+    setModel: vi.fn(async () => ({
+      scope: "chat",
+      reply: { kind: "recorded", notice: "已记录，下次执行生效。" },
+    })),
+    chatActions: {
+      getRecordForAction: vi.fn(() => ({ id: "sa-1" }) as never),
+    },
+  };
+}
+
+function deps(service: StubService | null): { deps: SubagentModelCommandDeps; resultsDir: string } {
+  const resultsDir = join(root, "results");
+  return {
+    deps: {
+      getService: () => service as never,
+      resolveAgentDir: () => join(root, "agent"),
+      // rootCwd 作为 enc 编码键——结果目录 = <agentDir>/subagents/<enc(cwd)>/model-switch
+      resolveRootCwd: () => join(root, "proj"),
+    },
+    resultsDir,
+  };
+}
+
+function rpcCtx(mode: "rpc" | "tui" = "rpc"): { ctx: ExtensionCommandContext; notifies: Array<{ msg: string; level: string }> } {
+  const notifies: Array<{ msg: string; level: string }> = [];
+  const ctx = {
+    mode,
+    ui: { notify: (msg: string, level: string) => notifies.push({ msg, level }) },
+    cwd: join(root, "proj"),
+  };
+  return { ctx: ctx as never, notifies };
+}
+
+const VALID_ARGS = JSON.stringify({
+  requestId: "req-abc",
+  recordId: "sa-1",
+  provider: "zai-coding-cn",
+  modelId: "glm-5.3-flash",
+  thinkingLevel: "high",
+});
+
+function resultFile(requestId: string): string {
+  // enc 段镜像 core encodeCwd（布局单源在 path-encoding.ts，测试只按同式派生锚）。
+  const enc = "--" + join(root, "proj").replace(/^[/\\]/, "").replace(/[/\\:]/g, "-") + "--";
+  return join(root, "agent", "subagents", enc, "model-switch", `${requestId}.json`);
+}
+
+// ── 成功路 ───────────────────────────────────────────────────
+
+describe("/subagent-model — 成功路（payload → setModel → 结果文件）", () => {
+  it("合法 payload：setModel 桩收到 target/model/thinkingLevel，结果文件 = 应答原样", async () => {
+    const service = stubService();
+    const { deps: d } = deps(service);
+    const { ctx } = rpcCtx();
+
+    await runSubagentModelRpc(d, VALID_ARGS, ctx);
+
+    expect(service.chatActions.getRecordForAction).toHaveBeenCalledWith("sa-1");
+    expect(service.setModel).toHaveBeenCalledWith(
+      { domain: "chat", record: { id: "sa-1" } },
+      { provider: "zai-coding-cn", modelId: "glm-5.3-flash" },
+      "high",
+    );
+    const raw = readFileSync(resultFile("req-abc"), "utf8");
+    expect(JSON.parse(raw)).toEqual({ scope: "chat", reply: { kind: "recorded", notice: "已记录，下次执行生效。" } });
+  });
+
+  it("runId 目标：workflow-run 域分流（不触 getRecordForAction）", async () => {
+    const service = stubService();
+    const { deps: d } = deps(service);
+    const { ctx } = rpcCtx();
+
+    const args = JSON.stringify({ requestId: "req-run", runId: "wf-1", provider: "p", modelId: "m" });
+    await runSubagentModelRpc(d, args, ctx);
+
+    expect(service.chatActions.getRecordForAction).not.toHaveBeenCalled();
+    expect(service.setModel).toHaveBeenCalledWith({ domain: "workflow-run", runId: "wf-1" }, { provider: "p", modelId: "m" }, undefined);
+  });
+
+  it("handler 不抛（即使 setModel 桩 resolve 失败也不向上传播）", async () => {
+    const service = stubService();
+    service.setModel.mockResolvedValue({ scope: "error", message: "目录无此模型（最接近的候选：X）" });
+    const { deps: d } = deps(service);
+    const { ctx } = rpcCtx();
+
+    await expect(runSubagentModelRpc(d, VALID_ARGS, ctx)).resolves.toBeUndefined();
+    const envelope = JSON.parse(readFileSync(resultFile("req-abc"), "utf8")) as { scope: string };
+    expect(envelope.scope).toBe("error");
+  });
+});
+
+// ── 失败路：envelope 且不抛 ──────────────────────────────────
+
+describe("/subagent-model — 失败路（envelope 落盘 + 全程不抛）", () => {
+  it("service.setModel 抛错：错误 envelope 文件 + handler 不抛", async () => {
+    const service = stubService();
+    service.setModel.mockRejectedValue(Object.assign(new Error("thinking 档位 max 在模型 X 上不可用"), { code: "thinking_level_unavailable" }));
+    const { deps: d } = deps(service);
+    const { ctx } = rpcCtx();
+
+    await expect(runSubagentModelRpc(d, VALID_ARGS, ctx)).resolves.toBeUndefined();
+
+    const envelope = JSON.parse(readFileSync(resultFile("req-abc"), "utf8")) as {
+      error: { code: string; message: string; recovery: string };
+    };
+    expect(envelope.error.code).toBe("thinking_level_unavailable");
+    expect(envelope.error.message).toContain("不可用");
+    expect(envelope.error.recovery).toContain("重试切换");
+  });
+
+  it("getRecordForAction 抛错（目标不存在）：envelope + handler 不抛", async () => {
+    const service = stubService();
+    service.chatActions.getRecordForAction.mockImplementation(() => {
+      throw new Error("record sa-ghost not found");
+    });
+    const { deps: d } = deps(service);
+    const { ctx } = rpcCtx();
+
+    await expect(runSubagentModelRpc(d, VALID_ARGS, ctx)).resolves.toBeUndefined();
+
+    const envelope = JSON.parse(readFileSync(resultFile("req-abc"), "utf8")) as { error: { code: string } };
+    expect(envelope.error.code).toBe("subagent_model_switch_failed");
+  });
+
+  it("非法 JSON（无 requestId）：零文件 + handler 不抛 + warning notify", async () => {
+    const { deps: d } = deps(stubService());
+    const { ctx, notifies } = rpcCtx();
+
+    await expect(runSubagentModelRpc(d, "not-json{", ctx)).resolves.toBeUndefined();
+    expect(existsSync(resultFile("req-abc"))).toBe(false);
+    expect(notifies[0]?.level).toBe("warning");
+  });
+
+  it("字段校验失败（缺 provider）：invalid_payload envelope", async () => {
+    const { deps: d } = deps(stubService());
+    const { ctx } = rpcCtx();
+
+    const args = JSON.stringify({ requestId: "req-bad", recordId: "sa-1", modelId: "m" });
+    await runSubagentModelRpc(d, args, ctx);
+
+    const envelope = JSON.parse(readFileSync(resultFile("req-bad"), "utf8")) as {
+      error: { code: string; message: string };
+    };
+    expect(envelope.error.code).toBe("invalid_payload");
+    expect(envelope.error.message).toContain("provider");
+  });
+
+  it("recordId 与 runId 双给：invalid_payload envelope（wire 契约二选一）", async () => {
+    const { deps: d } = deps(stubService());
+    const { ctx } = rpcCtx();
+
+    const args = JSON.stringify({ requestId: "req-both", recordId: "sa-1", runId: "wf-1", provider: "p", modelId: "m" });
+    await runSubagentModelRpc(d, args, ctx);
+
+    const envelope = JSON.parse(readFileSync(resultFile("req-both"), "utf8")) as { error: { code: string } };
+    expect(envelope.error.code).toBe("invalid_payload");
+  });
+
+  it("service 未就绪（session_start 前）：subagent_runtime_not_ready envelope", async () => {
+    const { deps: d } = deps(null);
+    const { ctx } = rpcCtx();
+
+    await runSubagentModelRpc(d, VALID_ARGS, ctx);
+
+    const envelope = JSON.parse(readFileSync(resultFile("req-abc"), "utf8")) as { error: { code: string } };
+    expect(envelope.error.code).toBe("subagent_runtime_not_ready");
+  });
+});
+
+// ── 注册形态 ─────────────────────────────────────────────────
+
+describe("registerSubagentModelCommand — 注册形态", () => {
+  interface CapturedCommand { // oe-exempt:20261006:test:测试专用命令捕获结构单实现为常态（同 commands-resume.test.ts 先例）
+    name: string;
+    description: string;
+    handler: (args: string, ctx: ExtensionCommandContext) => Promise<void>;
+  }
+
+  function captureCommand(): CapturedCommand {
+    const commands: CapturedCommand[] = [];
+    const api = {
+      registerCommand: (name: string, def: Omit<CapturedCommand, "name">) => {
+        commands.push({ name, ...def });
+      },
+    };
+    registerSubagentModelCommand(api as never);
+    expect(commands).toHaveLength(1);
+    return commands[0]!;
+  }
+
+  it("命令名 = subagent-model；TUI 模式 = 指引提示（内部 RPC 通道无 TUI 分支）", async () => {
+    const cmd = captureCommand();
+    expect(cmd.name).toBe("subagent-model");
+    const { ctx, notifies } = rpcCtx("tui");
+    await cmd.handler(VALID_ARGS, ctx);
+    expect(notifies[0]?.level).toBe("warning");
+    expect(notifies[0]?.msg).toContain("internal taiji GUI channel");
+  });
+});

package/src/interface/command/command-actions.ts

@@ -22,7 +22,7 @@ export type SubagentRpcAction =
 /** /workflows RPC action 判别联合。 */
 export type WorkflowRpcAction =
   | { action: "abort"; runId: string }
-  | { action: "resume"; runId: string }
+  | { action: "resume"; runId: string; model?: string }
   | { action: "lifecycle-missing-id"; verb: "abort" | "resume" }
   | { action: "lifecycle-removed"; verb: "pause" }
   | { action: "noop" };
@@ -128,8 +128,9 @@ export function parseSubagentRpcCommand(argsStr: string): SubagentRpcAction {
  * 支持格式：
  * - `abort <runId>` → { action: "abort", runId }
  * - `abort`（无 runId）→ { action: "lifecycle-missing-id", verb: "abort" }
- * - `resume <runId>` → { action: "resume", runId }（断点续跑——与 TUI verb、
- *   workflow tool action:"resume" 三通道同语义）
+ * - `resume <runId> [model]` → { action: "resume", runId, model? }（断点续跑——与
+ *   TUI verb、workflow tool action:"resume" 三通道同语义；model 可选 canonical ref
+ *   'provider/modelId[:thinkingLevel]'，落统一覆盖记账——F1-26 后续项）
  * - `resume`（无 runId）→ { action: "lifecycle-missing-id", verb: "resume" }
  * - `pause ...`（已移除的 lifecycle verb，带或不带 runId 均同）→
  *   { action: "lifecycle-removed", verb: "pause" }——removed verb 优先于 missing-id 判定
@@ -140,7 +141,7 @@ export function parseWorkflowRpcCommand(argsStr: string): WorkflowRpcAction {
   const args = argsStr.trim().split(/\s+/).filter(Boolean);
   if (args.length === 0) return { action: "noop" };
 
-  const [verb, runId] = args;
+  const [verb, runId, model] = args;
   if (isRemovedLifecycleVerb(verb)) {
     return { action: "lifecycle-removed", verb };
   }
@@ -149,7 +150,7 @@ export function parseWorkflowRpcCommand(argsStr: string): WorkflowRpcAction {
     if (!runId) return { action: "lifecycle-missing-id", verb };
     return verb === "abort"
       ? { action: "abort", runId }
-      : { action: "resume", runId };
+      : { action: "resume", runId, ...(model !== undefined ? { model } : {}) };
   }
   return { action: "noop" };
 }

package/src/interface/command/commands.ts

@@ -24,7 +24,13 @@ import type { ExtensionAPI, ExtensionCommandContext, Theme } from "@earendil-wor
 import { getLogger } from "@zhushanwen/pi-extension-logger";
 
 import type { LauncherDeps } from "@zhushanwen/subagent-core";
-import { abortRun, getSubagentService, resumeRun } from "@zhushanwen/subagent-core";
+import {
+  abortRun,
+  assertModelInCatalog,
+  getModelConfigService,
+  getSubagentService,
+  resumeRun,
+} from "@zhushanwen/subagent-core";
 import type { WorkflowRun } from "@zhushanwen/subagent-core";
 import { parseWorkflowRpcCommand, type WorkflowRpcAction } from "./command-actions.ts";
 import { createWorkflowsView, type ViewActions } from "../tui/views/WorkflowsView.ts";
@@ -130,13 +136,17 @@ export function registerWorkflowsCommand(
       if (verb === "resume") {
         const runId = rest[0];
         if (!runId) {
-          ctx.ui.notify("Usage: /workflows resume <runId>", "warning");
+          ctx.ui.notify("Usage: /workflows resume <runId> [model]", "warning");
           return;
         }
+        // 可选第二参数 = 显式模型 canonical ref（'provider/modelId[:thinkingLevel]'）——
+        // 落统一覆盖记账（F1-26 后续项：与 setModel 补切同通道，resume 合一步表达）。
+        const model = rest[1];
         try {
-          await resumeRun(runId, deps);
+          if (model !== undefined) assertResumeModelInCatalog(model);
+          await resumeRun(runId, deps, ...(model !== undefined ? [{ model }] : []));
           ctx.ui.notify(
-            `Workflow ${runId}: resuming — completed calls replay at zero token cost, unfinished calls re-dispatched`,
+            `Workflow ${runId}: resuming${model !== undefined ? ` with model ${model}` : ""} — completed calls replay at zero token cost, unfinished calls re-dispatched`,
             "info",
           );
         } catch (err) {
@@ -192,9 +202,10 @@ async function handleRpcMode(
     }
     case "resume": {
       try {
-        await resumeRun(parsed.runId, deps);
+        if (parsed.model !== undefined) assertResumeModelInCatalog(parsed.model);
+        await resumeRun(parsed.runId, deps, ...(parsed.model !== undefined ? [{ model: parsed.model }] : []));
         ctx.ui.notify(
-          `Workflow ${parsed.runId}: resuming — completed calls replay at zero token cost, unfinished calls re-dispatched`,
+          `Workflow ${parsed.runId}: resuming${parsed.model !== undefined ? ` with model ${parsed.model}` : ""} — completed calls replay at zero token cost, unfinished calls re-dispatched`,
           "info",
         );
       } catch (err) {
@@ -210,7 +221,14 @@ async function handleRpcMode(
       );
       return;
     case "lifecycle-missing-id":
-      ctx.ui.notify(`Usage: /workflows ${parsed.verb} <runId>`, "warning");
+      // Usage 按 verb 区分（与 TUI verb 分支同文案——两模式统一）：resume 的可选
+      // [model] 参数要出现在提示里，GUI 侧缺 runId 时得到的指引不指向旧用法。
+      ctx.ui.notify(
+        parsed.verb === "resume"
+          ? "Usage: /workflows resume <runId> [model]"
+          : `Usage: /workflows ${parsed.verb} <runId>`,
+        "warning",
+      );
       return;
     case "noop":
       ctx.ui.notify("View workflows in the composer task tray", "info");
@@ -223,6 +241,28 @@ async function handleRpcMode(
   }
 }
 
+/**
+ * 命令通道显式 model 的目录预检（D8 拒单语义，与 tool 通道 run/resume action 同款
+ * ——isModelRef 语法闸在 core resumeRun，此处补目录存在性：语法合法但目录查无
+ * （如 provider 段拼写错）在写覆盖记账之前同步拒绝，不延迟到派发期，避免「记账已
+ * 落盘 + 命令已 notify 成功」的假成功形态；三通道（TUI verb / RPC verb / tool）对称）。
+ * throw 落调用方 try/catch，分类化错误文案（含可用模型清单 + 修复指引）经 notify
+ * 直达用户。单例缺席（session_start 前不可达）降级跳过 + warn 留痕——派发期
+ * identity 解析仍是权威裁决（与 tool 通道降级语义一致）。
+ */
+function assertResumeModelInCatalog(model: string): void {
+  const modelService = getModelConfigService();
+  if (modelService === null) {
+    getLogger("subagent-workflow").warn(
+      "[commands] model catalog unavailable (model service not initialized) — resume model catalog check skipped; dispatch-time identity resolution remains authoritative",
+    );
+    return;
+  }
+  assertModelInCatalog(model, modelService.getModelRegistry(), {
+    source: "resume model override",
+  });
+}
+
 /**
  * TUI 模式：按 runId 直接打开对应 run 的 view（精确匹配优先，前缀唯一匹配次之）。
  * 均未命中 → error notify。

package/src/interface/command/subagent-model.ts

@@ -0,0 +1,268 @@
+// src/interface/command/subagent-model.ts
+//
+// /subagent-model 命令——subagent/workflow run 执行模型切换的宿主触达通道消费端
+// （subagent-model-switch §7.1.1 通道，U6）。内部 RPC 命令：runtime 网关适配器经
+// client.prompt("/subagent-model <单行JSON>") 短路本 handler（不经主 agent LLM，
+// pi _tryExecuteExtensionCommand 主路径对 / 前缀先行执行）。
+//
+// 通道契约（§7.1.1 四要素）：
+// - 载荷 = 单行 JSON {requestId, recordId?|runId?, provider, modelId, thinkingLevel?}；
+// - 执行 = 本进程直调宿主 setModel 编排（service.setModel，§7.2 单一三步）；
+// - 回执 = 一切结果（SetModelReply 三 scope / 错误 envelope）写结果文件
+//   `<subagent 数据根>/model-switch/<requestId>.json` 后正常返回——**全程不抛**；
+//   runtime 出站点在 handler 返回后读文件一次（写后读，无轮询无监视）。
+// - 结果文件承载 core SetModelReply 形状（scope 判别）——extension 不依赖
+//   @taiji/shared，wire 三形态映射归 runtime 适配器（依赖方向的唯一合法位置）。
+//
+// TUI 分支不存在：本命令是 GUI 通道专用内部命令，非交互入口（照 /subagents RPC
+// verb 的 GUI 屏蔽先例，TUI 手敲仅得指引提示）。
+
+import * as path from "node:path";
+
+import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+
+import {
+  ENV_ROOT_CWD,
+  getSubagentModelSwitchResultsDir,
+  getSubagentService,
+  writeAtomicFileSync,
+} from "@zhushanwen/subagent-core";
+import type { ModelSwitchTarget, SetModelReply } from "@zhushanwen/subagent-core";
+import { getLogger } from "@zhushanwen/pi-extension-logger";
+import { toErrorMessage } from "@zhushanwen/pi-ext-guards";
+
+const logger = getLogger("subagents");
+
+/**
+ * requestId 文件名白名单：`[\w-]{1,128}`（与 core record id 白名单同式——防路径穿越；
+ * 生产源 = runtime randomUUID，字符集 ⊆ 白名单，本式仅防御畸形通道输入）。
+ */
+const REQUEST_ID_PATTERN = /^[\w-]{1,128}$/;
+
+/** 错误 envelope 形状（结果文件内的失败承载；code 值域 = 本文件错误分型常量族）。
+ *  scope: "error" = 网关 mapResultFileToWireReply 的分派判别键（D3-A4 缺陷修复：
+ *  缺 scope 时域内失败被「scope 未知」通道错误吞掉，真实 code/recovery 丢失）。 */
+interface SubagentModelEnvelope { // oe-exempt:20261006:framework:通道结果信封契约形状（单命令单载体，单实现常态）
+  scope: "error";
+  error: { code: string; message: string; recovery: string };
+}
+
+/** /subagent-model 命令的依赖注入面（注册点装配生产实现，单测注入桩）。 */
+export interface SubagentModelCommandDeps { // oe-exempt:20261006:framework:命令 handler 依赖注入面（注册点装配，单实现常态）
+  /** 宿主 setModel 编排单例（session_start 前 null——envelope 分型承接）。 */
+  getService: () => ReturnType<typeof getSubagentService>;
+  /** agentDir 锚（pi SDK 活源，与 session-lifecycle 装配同源）。 */
+  resolveAgentDir: () => string;
+  /** 树根主 cwd（session-baselines rootCwd 同式推导，见 registerSubagentModelCommand）。 */
+  resolveRootCwd: () => string;
+}
+
+/** 载荷解析三态（显式判别：无 requestId = 无法命名结果文件，与字段校验失败分流）。 */
+type ParsedPayload =
+  | { ok: true; requestId: string; payload: SubagentModelPayload }
+  | { ok: false; requestIdMissing: true }
+  | { ok: false; requestIdMissing: false; requestId: string; validationMessage: string };
+
+/** 载荷结构（wire 契约 §7.1.1：recordId/runId 二选一，provider/modelId 必填）。
+ *  字段经逐项 typeof 抽取组装（JSON 边界不落地 unknown 断言）。 */
+interface SubagentModelPayload { // oe-exempt:20261006:framework:通道载荷契约形状（单命令单载体，单实现常态）
+  requestId: string;
+  recordId?: string;
+  runId?: string;
+  provider?: string;
+  modelId?: string;
+  thinkingLevel?: string;
+}
+
+/** 非空字符串字段抽取（undefined = 缺失或类型不符，二者同判缺失）。 */
+function nonEmptyString(v: unknown): string | undefined {
+  return typeof v === "string" && v !== "" ? v : undefined;
+}
+
+/**
+ * 解析单行 JSON 载荷（§7.1.1 要素 1）。requestId 缺失/非法 → requestIdMissing（无法
+ * 命名结果文件，本侧零回执——runtime 出站点超时路径承接通道失败，仅日志留痕）；
+ * 其余字段校验失败在 requestId 在场时落 envelope（invalid_payload 分型）。
+ */
+function parsePayload(argsStr: string): ParsedPayload {
+  let raw: unknown;
+  try {
+    raw = JSON.parse(argsStr.trim());
+  } catch {
+    return { ok: false, requestIdMissing: true };
+  }
+  if (typeof raw !== "object" || raw === null) return { ok: false, requestIdMissing: true };
+  const obj = raw as Record<string, unknown>;
+  const requestId = nonEmptyString(obj.requestId);
+  if (requestId === undefined || !REQUEST_ID_PATTERN.test(requestId)) {
+    return { ok: false, requestIdMissing: true };
+  }
+  const payload: SubagentModelPayload = {
+    requestId,
+    recordId: nonEmptyString(obj.recordId),
+    runId: nonEmptyString(obj.runId),
+    provider: nonEmptyString(obj.provider),
+    modelId: nonEmptyString(obj.modelId),
+    thinkingLevel: nonEmptyString(obj.thinkingLevel),
+  };
+  const validationMessage = validatePayload(payload);
+  if (validationMessage !== undefined) {
+    return { ok: false, requestIdMissing: false, requestId, validationMessage };
+  }
+  return { ok: true, requestId, payload };
+}
+
+/** 载荷字段校验（requestId 之外的域内畸形 → envelope invalid_payload 的 message 文案）。 */
+function validatePayload(payload: SubagentModelPayload): string | undefined {
+  if ((payload.recordId !== undefined) === (payload.runId !== undefined)) {
+    return "payload 需要 recordId（chat 域）或 runId（workflow run 级）二选一";
+  }
+  if (payload.provider === undefined) {
+    return "payload 缺 provider（canonical ref 的 provider 段）";
+  }
+  if (payload.modelId === undefined) {
+    return "payload 缺 modelId（canonical ref 的 modelId 段）";
+  }
+  return undefined;
+}
+
+/**
+ * 结果文件写入（唯一出站原语，永不抛）：writeAtomicFileSync（tmp+rename，防 runtime
+ * 读到半文件）+ 目录递归建。写失败 = 通道回执丢失（runtime 超时路径承接），日志留痕。
+ */
+function writeResultFile(resultsFile: string, content: string): void {
+  try {
+    writeAtomicFileSync(resultsFile, content);
+  } catch (err) {
+    logger.warn(`[subagent-model] result file write failed (runtime will report channel timeout): ${toErrorMessage(err)}`, {
+      resultsFile,
+    });
+  }
+}
+
+/** 提取引擎分型错误码（EngineError 载荷 .code——分型值域校验交由 runtime 侧）。 */
+function errorCodeOf(err: unknown): string | undefined {
+  // `in` 收窄（TS 4.9+）：Error & Record<"code", unknown>，零断言读载荷。
+  if (!(err instanceof Error) || !("code" in err)) return undefined;
+  const code: unknown = err.code;
+  return typeof code === "string" && code !== "" ? code : undefined;
+}
+
+/**
+ * RPC 执行体（§7.1.1 要素 2）：payload 校验 → 宿主 setModel → 结果文件。
+ * **全程不抛**——一切异常 catch 后落错误 envelope；校验失败同落 envelope。
+ */
+export async function runSubagentModelRpc(
+  deps: SubagentModelCommandDeps,
+  argsStr: string,
+  ctx: ExtensionCommandContext,
+): Promise<void> {
+  const parsed = parsePayload(argsStr);
+  if (!parsed.ok) {
+    if (parsed.requestIdMissing) {
+      // requestId 不可用 = 无关联回执面：日志留痕即可，runtime 超时按通道失败应答
+      //（结果文件名 = requestId，载荷缺失时本侧无从落文件）。
+      logger.warn("[subagent-model] payload unparseable or requestId missing — no result file, runtime timeout path will report");
+      ctx.ui.notify("/subagent-model payload requires requestId — request dropped", "warning");
+      return;
+    }
+    // requestId 在场 + 字段校验失败：envelope 落盘（invalid_payload 分型）。
+    const invalidFile = path.join(
+      getSubagentModelSwitchResultsDir(deps.resolveAgentDir(), deps.resolveRootCwd()),
+      `${parsed.requestId}.json`,
+    );
+    writeResultFile(
+      invalidFile,
+      JSON.stringify({
+        scope: "error",
+        error: {
+          code: "invalid_payload",
+          message: parsed.validationMessage,
+          recovery: "修正 subagent.setModel 载荷后重试（runtime 协议面问题，正常使用不可达）",
+        },
+      } satisfies SubagentModelEnvelope),
+    );
+    return;
+  }
+  const { requestId, payload } = parsed;
+  const resultsFile = path.join(
+    getSubagentModelSwitchResultsDir(deps.resolveAgentDir(), deps.resolveRootCwd()),
+    `${requestId}.json`,
+  );
+
+  try {
+    const service = deps.getService();
+    if (!service) {
+      writeResultFile(
+        resultsFile,
+        JSON.stringify({
+          scope: "error",
+          error: {
+            code: "subagent_runtime_not_ready",
+            message: "subagent 执行运行时未就绪（session 未启动或已 dispose）",
+            recovery: "先在该会话派发一条消息启动 subagent 运行时，再重试切换",
+          },
+        } satisfies SubagentModelEnvelope),
+      );
+      return;
+    }
+
+    // 目标组装（§6.1 作用域分流）：recordId → chat 域（getRecordForAction 同 message/close
+    // 的统一入口——含归属校验与冷查）；runId → run 级（终局/成员清单校验在编排步骤①）。
+    let target: ModelSwitchTarget;
+    if (typeof payload.recordId === "string") {
+      target = { domain: "chat", record: service.chatActions.getRecordForAction(payload.recordId) };
+    } else {
+      target = { domain: "workflow-run", runId: payload.runId as string };
+    }
+
+    const thinkingLevel = payload.thinkingLevel as string | undefined;
+    const reply: SetModelReply = await service.setModel(
+      target,
+      { provider: payload.provider as string, modelId: payload.modelId as string },
+      thinkingLevel,
+    );
+    // 应答三 scope 原样落文件（scope 判别由 runtime 适配器消费——core 形状是唯一权威）。
+    writeResultFile(resultsFile, JSON.stringify(reply));
+  } catch (err) {
+    // §7.5 通道行同族语义：handler 域内失败如实落 envelope（生效状态未知不虚构——
+    // 消息携带宿主编排错误原文，恢复动作照通道行）。
+    writeResultFile(
+      resultsFile,
+      JSON.stringify({
+        scope: "error",
+        error: {
+          code: errorCodeOf(err) ?? "subagent_model_switch_failed",
+          message: toErrorMessage(err),
+          recovery: "重试切换（覆盖替换幂等）；当前生效状态以面板与记录链为准",
+        },
+      } satisfies SubagentModelEnvelope),
+    );
+  }
+}
+
+/** 注册 /subagent-model 命令（内部 RPC 通道，taiji GUI 专用）。 */
+export function registerSubagentModelCommand(pi: ExtensionAPI): void {
+  pi.registerCommand("subagent-model", {
+    description: "Internal RPC: switch subagent/workflow-run model (single-line JSON payload)",
+    handler: async (argsStr: string, ctx: ExtensionCommandContext) => {
+      if (ctx.mode !== "rpc") {
+        ctx.ui.notify("/subagent-model is an internal taiji GUI channel — switch models from the subagent panel", "warning");
+        return;
+      }
+      // rootCwd 与 session-baselines 构造推导同式（env PI_SUBAGENT_ROOT_CWD 贯穿 ||
+      // ctx.cwd）——保证结果目录与 records 落同一 enc 段（enc 段不变量，path-encoding
+      // 头注同族约束）。本命令只在主进程执行（子进程无 / 命令通道），env 恒缺省。
+      await runSubagentModelRpc(
+        {
+          getService: getSubagentService,
+          resolveAgentDir: getAgentDir,
+          resolveRootCwd: () => process.env[ENV_ROOT_CWD] || ctx.cwd,
+        },
+        argsStr,
+        ctx,
+      );
+    },
+  });
+}

package/src/interface/command/subagents.ts

@@ -36,8 +36,8 @@ export interface SubagentDirectiveDetails {
 /**
  * 定向消息留痕：向主 session 落 subagent-directive custom_message entry。
  *
- * 按主 agent streaming 状态分流 sendMessage options。pi 0.84.4 sendCustomMessage
- * 实装（agent-session.js）：isStreaming 且无 deliverAs 时默认 agent.steer()——会把
+ * 按主 agent streaming 状态分流 sendMessage options。pi sendCustomMessage
+ * 实装（agent-session.js，1.0.0 复核同构）：isStreaming 且无 deliverAs 时默认 agent.steer()——会把
  * 定向消息注入正在运行的主 agent LLM turn，违反「不经主 agent LLM 直达 subagent」。
  * 故按调用时刻的权威 streaming 状态（ctx.isIdle()，与 sendCustomMessage 内部
  * isStreaming 判据精确互补，含 agent_end 后 retry/continuation 窗口）分流：