@zhushanwen/pi-subagents 0.0.1

package/src/tools/subagent-tool.ts

@@ -0,0 +1,286 @@
+// src/tools/subagent-tool.ts
+//
+// `subagent` LLM 工具。薄壳——参数解析 + 调 runtime.execute。
+// 不创建 state、不节流 onUpdate、不写 history（全部在 runtime 层统一）。
+//
+// 设计说明：renderCall/renderResult/execute 三个回调均抽成模块级 const +
+// 顶层 type alias。原因：stub 的 registerTool(tool: unknown) 参数是 unknown，
+// 在其对象字面量内直接标注从 pi-coding-agent 导入的泛型（AgentToolResult<X>、
+// Theme、ExtensionContext）会触发 TS2307 误报（probe5d/5f 验证）。
+// 抽到顶层后参数类型由 alias 提供，绕过该 quirk。
+
+import type { Component } from "@earendil-works/pi-tui";
+import { StringEnum } from "@mariozechner/pi-ai";
+import type { AgentToolResult, ExtensionAPI, ExtensionContext, Theme } from "@mariozechner/pi-coding-agent";
+import { Type } from "@sinclair/typebox";
+
+import { getSubagentService } from "../runtime/subagent-service.ts";
+import { extractAgentName } from "../tui/format.ts";
+import { type RenderContext,renderSubagentCall, renderSubagentResult } from "../tui/tool-render.ts";
+import type { SubagentToolDetails } from "../types.ts";
+
+// ============================================================
+// 回调类型（抽 alias 绕 registerTool(unknown) 的 TS2307 误报）
+// ============================================================
+
+/**
+ * execute 回调的 params 类型（手写副本，因为 stub registerTool 是 unknown，
+ * 无法从 SubagentParams schema 反向推断参数类型。与 old 实现一致）。
+ */
+interface SubagentExecuteParams {
+  task?: string;
+  agent?: string;
+  wait?: boolean;
+  backgroundId?: string;
+  model?: string;
+  thinkingLevel?: string;
+  skillPath?: string;
+  appendSystemPrompt?: string[];
+  schema?: Record<string, unknown>;
+  maxTurns?: number;
+  graceTurns?: number;
+}
+
+type SubagentExecuteCb = (
+  toolCallId: string,
+  params: SubagentExecuteParams,
+  signal: AbortSignal | undefined,
+  onUpdate?: (partialResult: AgentToolResult<SubagentToolDetails>) => void,
+  ctx?: ExtensionContext,
+) => Promise<AgentToolResult<SubagentToolDetails>>;
+
+type SubagentRenderCallCb = (args: unknown, theme: Theme, ctx: RenderContext) => Component;
+
+type SubagentRenderResultCb = (
+  result: AgentToolResult<SubagentToolDetails>,
+  options: { expanded: boolean; isPartial: boolean },
+  theme: Theme,
+  ctx: RenderContext,
+) => Component;
+
+// ============================================================
+// Params schema
+// ============================================================
+
+export const SubagentParams = Type.Object({
+  task: Type.Optional(Type.String({
+    description: "The task for the subagent to execute. Required to start a new subagent. Omit only when polling an existing background subagent (use backgroundId instead).",
+  })),
+  agent: Type.Optional(Type.String({
+    description: 'Agent name (defines system prompt + tools). Defaults to "worker". Available agents: worker (general), researcher (read-only exploration), scout, planner, reviewer, oracle, context-builder. Custom agents can be defined in config.',
+  })),
+  wait: Type.Optional(Type.Boolean({
+    description: "Execution mode. true (default) = sync: blocks until the subagent finishes, returns its result directly. false = background: returns a backgroundId immediately while the subagent runs detached; on completion a message is auto-injected that triggers a new turn so you can process the result — no need to sleep/poll. Use false for parallel fan-out (multiple wait:false calls in one message run concurrently in the pool, default maxConcurrent=4) or for long tasks you don't want to block on.",
+  })),
+  backgroundId: Type.Optional(Type.String({
+    description: "Poll an existing background subagent by its id. The id is returned when you start a subagent with wait:false. Returns current status (running/done/failed) and result if finished. Do NOT pass this when starting a new task — it is for checking progress of a previously started background subagent only.",
+  })),
+  model: Type.Optional(Type.String({
+    description: 'Model override in "provider/modelId" format (e.g. "anthropic/claude-sonnet-4.5"). If omitted, uses the agent\'s configured default model.',
+  })),
+  thinkingLevel: Type.Optional(StringEnum(["off", "minimal", "low", "medium", "high", "xhigh"] as const)),
+  skillPath: Type.Optional(Type.String()),
+  appendSystemPrompt: Type.Optional(Type.Array(Type.String())),
+  schema: Type.Optional(Type.Record(Type.String(), Type.Unknown())),
+  maxTurns: Type.Optional(Type.Number()),
+  graceTurns: Type.Optional(Type.Number()),
+});
+
+// ============================================================
+// renderCall 预解析 helper
+// ============================================================
+
+// extractAgentName 已上移到 ../tui/format.ts 共享（tool-render / subagent-tool 复用）。
+
+/** 从 unknown args 安全提取 model/thinkingLevel override（传给 resolveModel）。 */
+function extractModelOverride(args: unknown): { model?: string; thinkingLevel?: string } | undefined {
+  if (typeof args !== "object" || args === null) return undefined;
+  const a = args as { model?: unknown; thinkingLevel?: unknown };
+  const override: { model?: string; thinkingLevel?: string } = {};
+  if (typeof a.model === "string" && a.model.length > 0) override.model = a.model;
+  if (typeof a.thinkingLevel === "string" && a.thinkingLevel.length > 0) override.thinkingLevel = a.thinkingLevel;
+  return Object.keys(override).length > 0 ? override : undefined;
+}
+
+// ============================================================
+// 注册
+// ============================================================
+
+/** 注册 `subagent` 工具。由工厂调用。 */
+export function registerSubagentTool(pi: ExtensionAPI): void {
+  pi.registerTool({
+    name: "subagent",
+    label: "Subagent",
+    description: `Delegate a task to a specialized subagent.
+
+CRITICAL — this tool is registered with executionMode "sequential": multiple \`subagent\` calls in the SAME message run one-after-another, NOT in parallel. The first must finish before the next starts. To get real concurrency, use background mode (wait:false) — background calls return immediately and the underlying tasks run concurrently in the pool (default maxConcurrent=4; extras queue).
+
+## Modes
+
+- sync (wait:true, default): blocks until the subagent finishes, returns its result. Use when the next step needs the result.
+- background (wait:false): returns a backgroundId immediately; the subagent runs detached and keeps running even if you stop. On completion a message is auto-injected into the conversation that triggers a new turn so you can process the result.
+
+## Calling patterns
+
+- single — one sync subagent for one task (the common case).
+- chain — dependent steps where B needs A's output: sync calls across turns (A's result informs B's prompt). Sequential by nature.
+- parallel / fan-out — N independent tasks running concurrently: send N \`subagent\` calls with wait:false in the SAME message. Each returns a backgroundId at once; tasks run concurrently. Then do other work, or just stop.
+- background — one long-running task you don't want to block on: wait:false, then move on.
+
+## After launching background — do NOT wait
+
+Completion auto-notifies you (a message is injected that wakes your next turn). So:
+- DO NOT sleep, busy-wait, or poll in a loop after launching.
+- DO useful non-overlapping work if you have any.
+- Otherwise STOP. Stopping is correct — the completion notification will wake you. It is not giving up.
+
+## Polling (backgroundId)
+
+Poll only for a concrete reason (e.g. user asks "is it done yet?"). Reflexive polling right after launch is an anti-pattern — the completion notification already covers it.
+
+## Anti-patterns
+
+- Multiple sync (wait:true) calls in one message expecting parallelism → they serialize; a slow first call delays the rest and long chains may get interrupted.
+- Launching background, then sleeping/polling instead of working or stopping.
+- Using background for a result you need right now → use sync.`,
+    executionMode: "sequential",
+    parameters: SubagentParams,
+    renderCall: subagentRenderCall,
+    renderResult: subagentRenderResult,
+    execute: executeSubagent,
+  });
+}
+
+// ============================================================
+// 回调实现（模块级 const）
+// ============================================================
+
+const subagentRenderCall: SubagentRenderCallCb = (args, theme, ctx) => {
+  // 预解析 model（同步）：renderCall 在 execute 前调用，但 model 解析是同步的
+  // （只读配置 + sessionState）。让标题行能显示 model/thinking，不必等 execute。
+  // service 未就绪（session 未 init）或解析失败时降级——只显示 agent 名。
+  const agent = extractAgentName(args);
+  const override = extractModelOverride(args);
+  let resolved: { model: string; thinkingLevel?: string } | undefined;
+  try {
+    const service = getSubagentService();
+    const r = service?.resolveModel(agent, override);
+    if (r) resolved = { model: `${r.model.provider}/${r.model.id}`, thinkingLevel: r.thinkingLevel };
+  } catch {
+    // service 未注册或 modelRegistry 未注入，降级
+  }
+  return renderSubagentCall(args, theme, ctx, resolved);
+};
+
+const subagentRenderResult: SubagentRenderResultCb = (result, options, theme, ctx) =>
+  renderSubagentResult(result, options, theme, ctx);
+
+/**
+ * execute 实现。
+ *
+ *   ╔══════════════════════════════════════════════════════════════════╗
+ *   ║  rt = getRuntime() —— 未初始化 throw                             ║
+ *   ║                                                                    ║
+ *   ║  ── Mode 3: poll ──────────────────────────────────────────────  ║
+ *   ║  if (params.backgroundId):                                       ║
+ *   ║    query = rt.query(backgroundId)   ◄── store.snapshot + project ║
+ *   ║    不存在 throw；running → 返回 running details                  ║
+ *   ║    settled → 返回 project（顶层 turns/tokens，不钻 result）      ║
+ *   ║    return { content, details }                                    ║
+ *   ║                                                                    ║
+ *   ║  ── task 必填校验 ───────────────────────────────────────────  ║
+ *   ║  rt.assertAgentExists(params.agent)   ◄── fail-fast 未知 agent  ║
+ *   ║                                                                    ║
+ *   ║  ── mode 判定 ─────────────────────────────────────────────  ║
+ *   ║  params.wait > agent.defaultBackground > "sync"                   ║
+ *   ║                                                                    ║
+ *   ║  ── 预解析 model（仅显式 override 失败时 throw）───────────  ║
+ *   ║  resolved = rt.resolveModelForAgent(agent, override)             ║
+ *   ║  hasExplicitOverride && !resolved → throw                        ║
+ *   ║                                                                    ║
+ *   ║  ── 调 runtime.execute（统一入口）────────────────────────  ║
+ *   ║  handle = await rt.execute({                                      ║
+ *   ║    task, agent, mode, model, thinkingLevel,                       ║
+ *   ║    skillPath, appendSystemPrompt, schema, maxTurns, graceTurns,   ║
+ *   ║    signal,                                                        ║
+ *   ║    onUpdate: (details) => onUpdate?.({ content, details }),       ║
+ *   ║  })                                                                ║
+ *   ║                                                                    ║
+ *   ║  ── 返回 ─────────────────────────────────────────────────  ║
+ *   ║  handle.mode==="background":                                      ║
+ *   ║    返回 backgroundId（LLM 后续 poll）                             ║
+ *   ║  handle.mode==="sync":                                            ║
+ *   ║    details = project(handle.record)                               ║
+ *   ║    return { content: resultText, details }                        ║
+ *   ╚══════════════════════════════════════════════════════════════════╝
+ */
+const executeSubagent: SubagentExecuteCb = async (
+  _toolCallId,
+  params,
+  signal,
+  onUpdate,
+  _ctx,
+) => {
+  const service = getSubagentService();
+  if (!service) throw new Error("subagents runtime not initialized");
+
+  // ── poll 路径 ──
+  if (params.backgroundId) {
+    const result = service.query(params.backgroundId);
+    if (!result) throw new Error(`No subagent record with id "${params.backgroundId}"`);
+    // 按 status 分支：done→result；failed/cancelled→暴露 error（不掩盖失败，M5 修复）
+    const text = result.status === "running"
+      ? `Subagent ${result.id} is still running (${result.turns} turns).`
+      : result.status === "done"
+        ? (result.result ?? `Subagent ${result.id} finished.`)
+        : `Subagent ${result.id} ${result.status}${result.error ? `: ${result.error}` : ""}.`;
+    const content = [{ type: "text" as const, text }];
+    return { content, details: result };
+  }
+
+  // ── task 必填 ──
+  if (!params.task) throw new Error("task is required");
+
+  // ── 调 service.execute（mode 判定 + agent 校验 + 执行全在 service 内部）──
+  // D-1：取消首次确认拦截——不再注入 onConfirmCategory。
+  const handle = await service.execute({
+    task: params.task,
+    agent: params.agent,
+    wait: params.wait,
+    model: params.model,
+    thinkingLevel: params.thinkingLevel,
+    skillPath: params.skillPath,
+    appendSystemPrompt: params.appendSystemPrompt,
+    schema: params.schema,
+    maxTurns: params.maxTurns,
+    graceTurns: params.graceTurns,
+    signal,
+    onUpdate: onUpdate
+      ? (details) => {
+          onUpdate({ content: [{ type: "text", text: details.result ?? "" }], details });
+        }
+      : undefined,
+  });
+
+  // ── 返回 ──
+  if (handle.mode === "background") {
+    // background：立即返回 backgroundId + 完整 details（status=running），
+    // 让 tool block 能正常渲染 running 态（而非 "did not produce details"）。
+    // 后台进度靠 progress widget（execute return 后 tool block 无法继续更新）。
+    return { content: [{ type: "text", text: `Background subagent started: ${handle.backgroundId}` }],
+      details: handle.details };
+  }
+
+  // sync: details 用 project 投影的 SubagentToolDetails（含 elapsedSeconds/currentActivity），
+  //       而非 record snapshot（后者缺 TUI 渲染字段）。
+  // schema 模式：优先输出 parsedOutput 的 JSON（调用方期望结构化数据，非 agent 文本）。
+  // 失败/取消时 record.result 为空字符串，但 error 只进 details.error ——
+  // 父 agent 只读 content 会误判「成功但无返回值」。这里与 poll 路径对齐：
+  // 把 error 拼进 content，保证失败「出声」（项目「错误要出声」约定）。
+  const syncText = handle.details.parsedOutput !== undefined
+    ? JSON.stringify(handle.details.parsedOutput)
+    : (handle.record.result
+      || (handle.details.error ? `Subagent failed: ${handle.details.error}` : "Subagent failed."));
+  return { content: [{ type: "text", text: syncText }],
+    details: handle.details };
+};

package/src/tui/bg-notify-render.ts

@@ -0,0 +1,139 @@
+// src/tui/bg-notify-render.ts
+//
+// background 完成通知的对话流渲染器。
+// pi.registerMessageRenderer("subagent-bg-notify", ...) 注册。
+//
+// notifier.ts 设 display:true + triggerTurn:true：
+//   - display:true → Pi 创建 CustomMessageComponent（customMessageBg 背景色块，
+//     与 tool block 的 toolSuccessBg 视觉区分），调本 renderer 渲染内容
+//   - triggerTurn:true → 唤醒父 agent 下一 turn，让 LLM 看到「X 完成」
+//
+// 渲染内容（紧凑单行/双行）：
+//   ✓ agent — 摘要首行 (id)
+//   ✗ agent — Error: 错误首行 (id)
+//   ■ agent — cancelled (id)
+//
+// 注意：不调 theme.bg()——背景色由 Pi 的 CustomMessageComponent 容器施加
+// （customMessageBg）。组件只负责前景内容。
+
+import type { Component } from "@earendil-works/pi-tui";
+import { Text } from "@earendil-works/pi-tui";
+import type { Theme } from "@mariozechner/pi-coding-agent";
+
+import { firstLine, statusGlyph, type ThemeLike,truncLine } from "./format.ts";
+
+/** agent 名最大显示宽度。 */
+const AGENT_MAX_WIDTH = 40;
+/** 完成块正文最大显示宽度。 */
+const BODY_MAX_WIDTH = 80;
+
+/**
+ * 渲染 background 完成通知。
+ *
+ * 契约（Pi MessageRenderer，core/extensions/types.ts:1060）：
+ *   (message: CustomMessage, options: { expanded }, theme: Theme) => Component | undefined
+ *
+ *   display:true 时 Pi 调本方法，返回 Component 渲染到 customMessageBg 块。
+ *   details 异常 → 返回 undefined 走 Pi 默认渲染（兜底）。
+ *
+ *   details 两种形态：
+ *     - 单条：BgNotifyRecord（status/agent/id/result/error）
+ *     - 批量：{ batch: true, items: BgNotifyRecord[] }（notifier 合并窗口内多条完成）
+ */
+export function renderBgNotifyMessage(
+  message: { details?: unknown },
+  _options: { expanded: boolean },
+  theme: Theme,
+): Component | undefined {
+  const t = theme as ThemeLike;
+
+  // 批量分支：多条合并，各自渲染一行
+  const batch = extractBatch(message.details);
+  if (batch) {
+    const lines = batch.map((r) => renderRecordLine(r, t));
+    return new Text(lines.join("\n"), 0, 0);
+  }
+
+  // 单条分支
+  const record = extractBgNotifyRecord(message.details);
+  if (!record) return undefined;
+  return new Text(renderRecordLine(record, t), 0, 0);
+}
+
+/** 渲染单条 record 为一行文本（头 + 首行预览 + id）。 */
+function renderRecordLine(
+  record: { id: string; status: "done" | "failed" | "cancelled"; agent: string; result?: string; error?: string },
+  t: ThemeLike,
+): string {
+  const glyph = statusGlyph(record.status);
+  const icon = glyph.icon ?? "•";
+  const agent = truncLine(record.agent, AGENT_MAX_WIDTH);
+  const head = `${t.fg(glyph.color, icon)} ${t.bold(agent)}`;
+
+  let body: string;
+  switch (record.status) {
+    case "done":
+      body = record.result ? firstLineSanitized(record.result) : "(completed)";
+      break;
+    case "failed":
+      body = `Error: ${record.error ? firstLineSanitized(record.error) : "(unknown)"}`;
+      break;
+    case "cancelled":
+      body = "cancelled";
+      break;
+    default:
+      body = "";
+  }
+
+  const idStr = t.fg("dim", ` (${record.id})`);
+  return `${head} — ${t.fg("dim", truncLine(body, BODY_MAX_WIDTH))}${idStr}`;
+}
+
+/**
+ * 从 message.details 防御性提取批量 record。
+ * 形态：{ batch: true, items: BgNotifyRecord[] }。结构不全返回 undefined。
+ */
+function extractBatch(
+  details: unknown,
+): { id: string; status: "done" | "failed" | "cancelled"; agent: string; result?: string; error?: string }[] | undefined {
+  if (typeof details !== "object" || details === null) return undefined;
+  const d = details as Record<string, unknown>;
+  if (d.batch !== true || !Array.isArray(d.items)) return undefined;
+  const records: { id: string; status: "done" | "failed" | "cancelled"; agent: string; result?: string; error?: string }[] = [];
+  for (const item of d.items) {
+    const r = extractBgNotifyRecord(item);
+    if (r) records.push(r);
+  }
+  return records.length > 0 ? records : undefined;
+}
+
+/**
+ * 从 message.details 防御性提取 BgNotifyRecord。
+ * 结构不全（缺 status / agent）返回 undefined。
+ */
+function extractBgNotifyRecord(
+  details: unknown,
+): { id: string; status: "done" | "failed" | "cancelled"; agent: string; result?: string; error?: string } | undefined {
+  if (typeof details !== "object" || details === null) return undefined;
+  const d = details as Record<string, unknown>;
+  const status = d.status;
+  const agent = d.agent;
+  if (
+    (status !== "done" && status !== "failed" && status !== "cancelled") ||
+    typeof agent !== "string"
+  ) {
+    return undefined;
+  }
+  return {
+    id: typeof d.id === "string" ? d.id : "",
+    status,
+    agent,
+    result: typeof d.result === "string" ? d.result : undefined,
+    error: typeof d.error === "string" ? d.error : undefined,
+  };
+}
+
+// firstLine 取首非空行（共享自 ./format.ts）；本文件额外压 \r\t 防多行展开。
+function firstLineSanitized(text: string): string {
+  return firstLine(text).replace(/[\r\t]+/g, " ");
+}

package/src/tui/config-wizard.ts

@@ -0,0 +1,253 @@
+// src/tui/config-wizard.ts
+//
+// /subagents config 交互式向导。
+// 用 Pi 内置的 ctx.ui.select / input / notify（都是 awaitable Promise）串成多级菜单。
+//
+// 数据闭环：
+//   modelService.getGlobalConfig()（副本）→ mutate → modelService.saveGlobalConfig（内存 + 落盘）
+//   YOLO 是 session 级（sessionState），用 modelService.toggleYolo（不落盘 config.json）。
+//
+// UI 接口（WizardUi）与 Pi ExtensionUIContext 的 select/input/notify 子集 duck-type 对齐（测试可 mock）。
+
+import { availableThinkingLevels, type ModelInfo, type ModelRegistryLike } from "../core/model-resolver.ts";
+import type { ModelConfigService } from "../runtime/model-config-service.ts";
+import type { CategoryDefinition, SubagentsGlobalConfig } from "../types.ts";
+
+/** wizard 依赖的 UI 接口（与 ExtensionUIContext 的 select/input/notify 对齐）。 */
+export interface WizardUi {
+  select(title: string, options: string[], opts?: { signal?: AbortSignal; timeout?: number }): Promise<string | undefined>;
+  input(title: string, placeholder?: string, opts?: { signal?: AbortSignal; timeout?: number }): Promise<string | undefined>;
+  notify(message: string, type?: "info" | "warning" | "error"): void;
+}
+
+/**
+ * 运行配置向导。
+ *
+ *   ╔══════════════════════════════════════════════════════════════╗
+ *   ║  主菜单 select（循环，直到用户选"退出"）：                       ║
+//   ║    - 切换 YOLO 模式（toggleYolo，session 级）                    ║
+//   ║    - 选择 category → 修改 model/thinkingLevel（落盘）           ║
+//   ║    - 修改 maxConcurrent（落盘）                                  ║
+//   ║    - 修改 fallback 模型（落盘）                                  ║
+//   ║    - 退出                                                        ║
+//   ║                                                                    ║
+//   ║  修改 globalConfig 的项 mutate 副本后调 saveGlobalConfig 持久化  ║
+//   ║  modelService 未初始化或 registry 未注入 → notify + return          ║
+//   ╚══════════════════════════════════════════════════════════════╝
+ */
+export async function runConfigWizard(
+  ui: WizardUi,
+  args: string[],
+  modelService: ModelConfigService,
+): Promise<void> {
+  void args; // 预留：未来支持 /subagents config <category> 直跳
+
+  const config = modelService.getGlobalConfig();
+  const registry = safeGetRegistry(modelService);
+  if (!registry) {
+    ui.notify("subagents 模型注册表未就绪（session 未初始化）", "error");
+    return;
+  }
+
+  // 主循环
+  for (;;) {
+    const yoloState = modelService.getSessionState().yoloMode ? "on" : "off";
+    const mainChoice = await ui.select("Subagents config", [
+      `切换 YOLO 模式（当前: ${yoloState}）`,
+      "修改 category 模型",
+      `修改 maxConcurrent（当前: ${config.maxConcurrent}）`,
+      `修改 fallback 模型（当前: ${config.fallback.model}）`,
+      "退出",
+    ]);
+    if (mainChoice === undefined || mainChoice === "退出") return;
+
+    if (mainChoice.startsWith("切换 YOLO")) {
+      const newVal = modelService.toggleYolo();
+      ui.notify(`YOLO 模式: ${newVal ? "on" : "off"}`, "info");
+      continue;
+    }
+    if (mainChoice.startsWith("修改 category")) {
+      await editCategoryModel(ui, config, registry, modelService);
+      continue;
+    }
+    if (mainChoice.startsWith("修改 maxConcurrent")) {
+      await editMaxConcurrent(ui, config, modelService);
+      continue;
+    }
+    if (mainChoice.startsWith("修改 fallback")) {
+      await editFallbackModel(ui, config, registry, modelService);
+      continue;
+    }
+  }
+}
+
+// ============================================================
+// 子流程：修改 category 模型
+// ============================================================
+
+/** 修改某个 category 的 model + thinkingLevel，落盘。 */
+async function editCategoryModel(
+  ui: WizardUi,
+  config: SubagentsGlobalConfig,
+  registry: ModelRegistryLike,
+  modelService: ModelConfigService,
+): Promise<void> {
+  const catNames = Object.keys(config.categories);
+  if (catNames.length === 0) {
+    ui.notify("没有可配置的 category", "warning");
+    return;
+  }
+  const available = registry.getAvailable();
+  const availableIds = new Set(available.map((m) => `${m.provider}/${m.id}`));
+  // label 显示真实模型——若 config 配的 model 在 registry 无效，标降级提示
+  // （resolveModel 会 fallback 到 fallback.model 或 ctx.model，用户应感知）
+  const catLabels = catNames.map((n) => {
+    const def = config.categories[n]!;
+    const valid = availableIds.has(def.model);
+    const suffix = valid ? "" : ` ⚠ 无效（将降级到 ${config.fallback.model}）`;
+    return `${def.label} (${n}) = ${def.model}${suffix}`;
+  });
+  const catChoice = await ui.select("选择 category", catLabels);
+  if (catChoice === undefined) return;
+  const catIdx = catLabels.indexOf(catChoice);
+  if (catIdx < 0) return;
+  const catName = catNames[catIdx]!;
+
+  if (available.length === 0) {
+    ui.notify("没有可用的模型（检查 modelRegistry 鉴权）", "warning");
+    return;
+  }
+  const modelOptions = available.map((m) => modelLabel(m));
+  const modelChoice = await ui.select(`选择 ${catName} 的模型`, modelOptions);
+  if (modelChoice === undefined) return;
+  const modelIdx = modelOptions.indexOf(modelChoice);
+  if (modelIdx < 0) return;
+  const model = available[modelIdx]!;
+  const modelStr = `${model.provider}/${model.id}`;
+
+  // thinkingLevel（按 model.thinkingLevelMap 过滤——不同 model 支持的级别不同）
+  const thinkingLevels = [...availableThinkingLevels(model)];
+  if (thinkingLevels.length === 0) {
+    // 非 reasoning 或无 map 信息：写 undefined，跳过选择
+    config.categories[catName] = { ...config.categories[catName]!, model: modelStr, thinkingLevel: undefined };
+    await saveAndNotify(ui, config, modelService, `${catName} → ${modelStr} · thinking off`);
+    return;
+  }
+  const current = config.categories[catName]!.thinkingLevel ?? "off";
+  const thinkingChoice = await ui.select(
+    `选择 thinking level（当前: ${current}）`,
+    thinkingLevels,
+  );
+  if (thinkingChoice === undefined) return;
+
+  const newDef: CategoryDefinition = {
+    ...config.categories[catName]!,
+    model: modelStr,
+    thinkingLevel: thinkingChoice,
+  };
+  config.categories[catName] = newDef;
+  await saveAndNotify(ui, config, modelService, `${catName} → ${modelStr} · thinking ${thinkingChoice}`);
+}
+
+// ============================================================
+// 子流程：修改 maxConcurrent
+// ============================================================
+
+/** 修改 maxConcurrent（正整数校验），落盘。 */
+async function editMaxConcurrent(
+  ui: WizardUi,
+  config: SubagentsGlobalConfig,
+  modelService: ModelConfigService,
+): Promise<void> {
+  const input = await ui.input(`maxConcurrent（当前 ${config.maxConcurrent}，输入正整数）`);
+  if (input === undefined) return;
+  const n = Number.parseInt(input, 10);
+  if (!Number.isFinite(n) || n < 1 || String(n) !== input.trim()) {
+    ui.notify("无效值（需为正整数），未修改", "warning");
+    return;
+  }
+  config.maxConcurrent = n;
+  await saveAndNotify(ui, config, modelService, `maxConcurrent = ${n}`);
+}
+
+// ============================================================
+// 子流程：修改 fallback 模型
+// ============================================================
+
+/** 修改 fallback 的 model + thinkingLevel，落盘。 */
+async function editFallbackModel(
+  ui: WizardUi,
+  config: SubagentsGlobalConfig,
+  registry: ModelRegistryLike,
+  modelService: ModelConfigService,
+): Promise<void> {
+  const available = registry.getAvailable();
+  if (available.length === 0) {
+    ui.notify("没有可用的模型", "warning");
+    return;
+  }
+  const modelOptions = available.map((m) => modelLabel(m));
+  const modelChoice = await ui.select("选择 fallback 模型", modelOptions);
+  if (modelChoice === undefined) return;
+  const modelIdx = modelOptions.indexOf(modelChoice);
+  if (modelIdx < 0) return;
+  const model = available[modelIdx]!;
+  const modelStr = `${model.provider}/${model.id}`;
+
+  // thinkingLevel（按 model.thinkingLevelMap 过滤）
+  const thinkingLevels = [...availableThinkingLevels(model)];
+  let thinkingLevel: string | undefined;
+  if (thinkingLevels.length > 0) {
+    const choice = await ui.select("选择 fallback thinking level", thinkingLevels);
+    if (choice === undefined) return;
+    thinkingLevel = choice;
+  }
+  // 无可用级别（非 reasoning / 无 map）→ thinkingLevel = undefined
+
+  config.fallback = { model: modelStr, thinkingLevel };
+  await saveAndNotify(ui, config, modelService, `fallback → ${modelStr} · thinking ${thinkingLevel ?? "off"}`);
+}
+
+// ============================================================
+// 辅助
+// ============================================================
+
+/** 模型选项 label（provider/id — name）。 */
+function modelLabel(m: ModelInfo): string {
+  return `${m.provider}/${m.id} — ${m.name}`;
+}
+
+/**
+ * 保存全局配置并通知用户。
+ *
+ * 做两件事（单一职责拆分会割裂调用方 try/catch，合并在此更内聚）：
+ *   1. modelService.saveGlobalConfig —— 更新 Service 内存副本 + 原子写 config.json
+ *   2. ui.notify —— 向用户反馈结果（成功显示摘要，失败显示错误）
+ *
+ * 失败不抛（向导继续可用），由 notify error 兜底。
+ */
+async function saveAndNotify(
+  ui: WizardUi,
+  config: SubagentsGlobalConfig,
+  modelService: ModelConfigService,
+  summary: string,
+): Promise<void> {
+  try {
+    await modelService.saveGlobalConfig(config);
+    ui.notify(`已保存：${summary}`, "info");
+  } catch (err) {
+    ui.notify(`保存失败：${String(err)}`, "error");
+  }
+}
+
+/**
+ * 安全获取 modelRegistry（initModel 未调用时返回 undefined 而非 throw）。
+ * wizard 用它做 guard，避免 hub 未就绪时抛错中断向导。
+ */
+function safeGetRegistry(modelService: ModelConfigService): ModelRegistryLike | undefined {
+  try {
+    return modelService.getModelRegistry();
+  } catch {
+    return undefined;
+  }
+}