@zhushanwen/pi-subagent-workflow 7.3.4 → 8.0.0

package/src/execution/model-resolver.ts

@@ -82,11 +82,13 @@ const MODEL_LIST_LIMIT = 20;
 //   ║    3. ctxModel                 （主 agent 当前模型，直接透传）   ║
 //   ║                                                                ║
 //   ║  1/2 级查 registry + auth 校验；3 级无需 lookup（主 agent 在用  ║
-//   ║  说明 auth OK）。thinkingLevel 无指定时 undefined（model 默认） ║
+//   ║  说明 auth OK）。thinkingLevel 无显式指定时兜底「模型最高可用档」║
+//   ║  （maxThinkingForModel，含 "max" 时用 max）——不落回 pi 默认      ║
+//   ║  medium，subagent 任务需要最大推理深度。                          ║
 //   ║                                                                ║
 //   ║  显式指定但 lookup/auth 失败 → 抛错（不静默降级到主 agent，     ║
 //   ║  因为用户明确要求了某个 model，降级会造成「以为用了 X 实际用 Y」║
-//   ╚═══════════════════════════════════════════════════════════════╝
+//   ╚════════════════════════════════════════════════════════════════╝
  *
  * @param agentConfig     agent .md 解析结果（查 model override + thinkingLevel）
  * @param modelRegistry   registry（仅 override 路径用）
@@ -120,11 +122,12 @@ export function resolveModel(
     );
   }
 
-  // 3. 主 agent model（直接透传，thinkingLevel 用 override 或 undefined）
+  // 3. 主 agent model（直接透传）。无显式 thinking → 兜底最高可用档。
   if (ctxModel) {
     return {
       model: ctxModel,
-      thinkingLevel: paramOverride?.thinkingLevel ?? agentConfig?.thinkingLevel,
+      thinkingLevel: paramOverride?.thinkingLevel ?? agentConfig?.thinkingLevel
+        ?? maxThinkingForModel(ctxModel),
     };
   }
 
@@ -166,10 +169,28 @@ function lookupAndResolve(
   }
   return {
     model,
-    thinkingLevel: resolveThinkingLevel(model, requestedThinking),
+    // 无显式请求时兜底「模型最高可用档」（不落 pi 默认 medium）。
+    thinkingLevel: resolveThinkingLevel(model, requestedThinking ?? maxThinkingForModel(model)),
   };
 }
 
+/**
+ * subagent 默认 thinking：模型最高可用档。
+ *
+ *   - thinkingLevelMap 配置了级别 → map 中最高档（模型显式配置 "max" 时即 max）
+ *   - reasoning 但无 map → "xhigh"（pi 合法最高档；"max" 非 pi 合法值——
+ *     spawn 侧 model:"max" 后缀会被 pi 判为非法 thinking 后缀导致 model 解析失败，
+ *     故无 map 时不能直接用 "max"）
+ *   - 非 reasoning 模型 → undefined（不支持 thinking）
+ */
+function maxThinkingForModel(
+  model: { reasoning: boolean; thinkingLevelMap?: Record<string, unknown> },
+): string | undefined {
+  const levels = availableThinkingLevels(model);
+  if (levels.length > 0) return levels[levels.length - 1];
+  return model.reasoning ? "xhigh" : undefined;
+}
+
 /**
  * 解析 "provider/modelId" 并查 registry。
  *

package/src/execution/notifier.ts

@@ -8,10 +8,20 @@
 //   - 通过 pi.sendMessage({ deliverAs:"followUp", triggerTurn:true }) 注入——
 //     当前 turn 结束后唤醒父 agent 处理结果（followUp 不打断 streaming、不锁滚动）
 
-/** 一条待发送的完成通知记录。 */
+/**
+ * 一条待发送的完成通知记录。
+ * SP-1: done/failed/crashed 合并为 closed + closedReason L2 子枚举。
+ */
 export interface BgNotifyRecord {
   id: string;
-  status: "done" | "failed" | "cancelled";
+  /**
+   * 完成状态。v4 B-1 两态收敛：closed（终态，含 cancelled，closedReason 表达 L2 原因）
+   * 或 running（对话模式轮次完成，旧 idle 折入 running，携带本轮结果送回主 agent）。
+   * toNotifyRecord 守卫放行后经此联合穷尽。
+   */
+  status: "running" | "closed";
+  /** L2 关闭原因子枚举（仅 status="closed" 时有意义）。供通知文案按需展示。 */
+  closedReason?: import("./types.ts").ClosedReason;
   agent: string;
   /** 执行所用 model（RecordSnapshot.model），用于完成通知显示。 */
   model?: string;
@@ -19,10 +29,25 @@ export interface BgNotifyRecord {
   error?: string;
   startedAt: number;
   endedAt: number | undefined;
+  /**
+   * 对话轮次计数（仅 idle 有意义）。dedup key 按 `id:round` 去重——对话模式每轮 round
+   * 不同，60s 内多轮不被吞；非 chatMode round 恒定（0/undefined），key 同旧 id 行为不变。
+   */
+  round?: number;
   /** [MF#1] worktree 模式下子 agent 改动的 patch 路径（worktree 外，cleanup 后留存）。
    *  done 时通知文本显式提示 `git apply`，否则 background 子 agent 在隔离 worktree 的改动
    *  会静默丢失——父 LLM 不知 patch 路径，无法应用。 */
   patchFile?: string;
+  /** [wave2] 子 agent session 文件路径（增量语义的全文恢复通道）。
+   *  仅 chatMode 透传（toNotifyRecord 条件透传）——轮次/完成通知末尾追加
+   *  "Full transcript: <path>" 指针行，父 LLM 可按需读全文；one-shot 不透传，
+   *  通知输出逐字节不变。缺失时 buildLlmContent 省略整行。 */
+  sessionFile?: string;
+  /** [C-2] close 终态通知的轮次统计（文案 "completed after N rounds." 用）。
+   *  仅 chatMode close 语义（notifyClosed）构造时携带——此时 dedup 身份 round 已被
+   *  置 undefined（与轮次通知的 id:round key 区分，终态不被吞），轮数改由本字段进
+   *  文案。one-shot 完成通知不设置，文案保持 "completed. Result:" 逐字节（G4）。 */
+  totalRounds?: number;
 }
 
 /** notifier 依赖的 pi 最小接口（解耦，便于测试）。 */
@@ -108,9 +133,12 @@ export class BgNotifier {
         if (now - ts >= DEDUP_TTL_MS) this.dedup.delete(id);
       }
     }
-    const lastSeen = this.dedup.get(record.id);
+    // dedup key：idle（对话模式每轮完成）按 id:round 去重——不同轮次不互相掩蔽；
+    // 非 idle（closed/cancelled）round 恒定 undefined，key 同旧行为不变。
+    const dedupKey = record.round != null ? `${record.id}:${record.round}` : record.id;
+    const lastSeen = this.dedup.get(dedupKey);
     if (lastSeen !== undefined && now - lastSeen < DEDUP_TTL_MS) return;
-    this.dedup.set(record.id, now);
+    this.dedup.set(dedupKey, now);
 
     this.pending.push(record);
 
@@ -209,18 +237,47 @@ export class BgNotifier {
   private buildLlmContent(record: BgNotifyRecord): string {
     const agent = record.agent;
     const id = record.id;
+    // [wave2 指针行] 增量语义下轮次通知只携带本轮增量，异步 flush 窗口丢失时不可重发
+    //（见 subagent-service.ts onRoundSettled 注释），恢复通道是 session 文件全文。
+    // 仅 chatMode 透传 sessionFile，one-shot 通知不含该行；cancelled/gc-failed 不追加
+    //（无成功结果可读，指针无意义）；缺失时省略整行（追加空串 = 输出逐字节不变）。
+    const transcriptPointer = record.sessionFile
+      ? `\n\nFull transcript: ${record.sessionFile}`
+      : "";
     switch (record.status) {
-      case "done": {
-        const base = `Subagent "${agent}" (${id}) completed. Result:\n${record.result ?? "(empty)"}`;
+      case "closed": {
+        // v4 B-1: closed 统一终态（含 cancelled）。按 closedReason 派生通知文案。
+        const reason = record.closedReason ?? "gc";
+        if (reason === "cancelled") {
+          return `Subagent "${agent}" (${id}) cancelled.`;
+        }
+        // 失败场景（gc + 有 error）：展示错误。判定必须先于 patchFile——失败轮也会写
+        // patchFile（doFinalizeRecord Step 0 对 worktreeHandle 无条件 collectPatch），若
+        // patch 分支在前，gc 失败 + worktree 并存时 LLM 被告知 completed。顺序与三处
+        // 同构契约的另外两处一致（shared/subagent.ts deriveClosedDisplay、
+        // bg-notify-render.ts renderRecordLines：cancelled → gc+error → patch/result）。
+        if (record.error && reason === "gc") {
+          return `Subagent "${agent}" (${id}) failed: ${record.error}`;
+        }
+        // 成功完成（user-close）或通用结束（gc/parent-shutdown 等）：展示结果。
+        // [C-2] chatMode close 终态通知附轮次统计（设计 D2 路径①"completed after N rounds"）。
+        // totalRounds 仅 close 语义携带（notifyClosed）；one-shot 完成通知不设置（round 无轮次
+        // 语义），文案保持 "completed. Result:" 逐字节（G4 硬约束，one-shot 字节锁测试锚定）。
+        const roundsSuffix =
+          record.totalRounds != null && record.totalRounds > 0
+            ? ` after ${record.totalRounds} round${record.totalRounds === 1 ? "" : "s"}`
+            : "";
+        const base = `Subagent "${agent}" (${id}) completed${roundsSuffix}. Result:\n${record.result ?? "(empty)"}`;
         if (record.patchFile) {
-          return `${base}\n\nThis subagent ran in an isolated worktree; its file changes were captured as a patch:\n  ${record.patchFile}\nTo bring these changes into the current repo, run: \`git apply ${record.patchFile}\``;
+          // [wave2 review] 长 return 拆行：模板串内不可直接换行（会改变输出内容），提取 patchHint 中转变量
+          const patchHint = `\n\nThis subagent ran in an isolated worktree; its file changes were captured as a patch:\n  ${record.patchFile}\nTo bring these changes into the current repo, run: \`git apply ${record.patchFile}\``;
+          return `${base}${patchHint}${transcriptPointer}`;
         }
-        return base;
+        return `${base}${transcriptPointer}`;
       }
-      case "failed":
-        return `Subagent "${agent}" (${id}) failed: ${record.error ?? "(unknown error)"}`;
-      case "cancelled":
-        return `Subagent "${agent}" (${id}) cancelled.`;
+      case "running":
+        // v4 B-1: 对话模式轮次完成（旧 idle 折入 running）：携带本轮结果送回主 agent，等待下一轮 message。
+        return `Subagent "${agent}" (${id}) finished a round. Reply:\n${record.result ?? "(empty)"}${transcriptPointer}`;
     }
   }
 

package/src/execution/pi-invocation.ts

@@ -51,12 +51,32 @@ function isGenericRuntime(execPath: string): boolean {
  *   2. execPath 非通用运行时（pi standalone binary）→ <execPath> <userArgs>
  *   3. 通用运行时但无可用脚本路径 → "pi" <userArgs>（依赖 PATH 中可找到 pi）
  */
+// [perf] 决策链只依赖 process.argv[1] / process.execPath（进程内恒定），其中唯一的
+// 磁盘探测（existsSync）结果 memo 一次——每次 spawn 免重复 syscall。memo 键含
+// argv[1] 值：测试 mock 切换 argv[1] 模拟不同运行时时自动失效重算。
+let scriptExistsCache: { script: string | undefined; exists: boolean } | undefined;
+
+/** process.argv[1] 是真实磁盘脚本（非 bun 虚拟路径）且存在。 */
+function currentScriptExists(): boolean {
+  const currentScript = process.argv[1];
+  if (scriptExistsCache === undefined || scriptExistsCache.script !== currentScript) {
+    scriptExistsCache = {
+      script: currentScript,
+      exists:
+        currentScript !== undefined &&
+        !currentScript.startsWith(BUN_VIRTUAL_PREFIX) &&
+        fs.existsSync(currentScript),
+    };
+  }
+  return scriptExistsCache.exists;
+}
+
 export function getPiInvocation(userArgs: string[]): PiInvocation {
   const currentScript = process.argv[1];
   const isBunVirtualScript = currentScript?.startsWith(BUN_VIRTUAL_PREFIX);
 
   // 分支 1：有真实脚本路径 → 复现启动方式（node <pi-script> <args>）
-  if (currentScript && !isBunVirtualScript && fs.existsSync(currentScript)) {
+  if (currentScript && !isBunVirtualScript && currentScriptExists()) {
     return { command: process.execPath, args: [currentScript, ...userArgs] };
   }