@zhushanwen/pi-subagent-workflow 7.4.0 → 8.1.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] };
   }
 

package/src/execution/record-entry.ts

@@ -0,0 +1,118 @@
+// src/execution/record-entry.ts
+//
+// W16 [D4]：subagent record 自描述持久化 entry 的形态权威。
+//
+// pi 文件（session JSONL）是扩展数据持久化权威：record 状态每次迁移都经
+// pi.appendEntry 落一条自描述完整快照（字段即 SubagentRecord），读取方无需
+// 逆向解析 toolCall/toolResult。内存 record-store 保持运行时权威，entry 是
+// 重建源（两者不冲突）。
+//
+// customType 与既有 `subagent-identity`（session 文件首行身份 entry）同族命名
+//（连字符风格）；写点见 record-store.ts 的状态迁移点（register/archive/
+// reportRecordTransition），custom entry 由 pi 写进 session JSONL，不进 LLM context。
+
+import type {
+  AgentEventLogEntry,
+  ClosedReason,
+  DisplayItem,
+  ExecutionMode,
+  ExecutionStatus,
+  SubagentRecord,
+} from "./types.ts";
+
+/** 自描述 record entry 的 customType。写点字面量与本常量的等值由
+ *  __tests__/record-store.test.ts 断言钉住（消费方引用本常量，勿用裸字符串）。 */
+export const SUBAGENT_RECORD_CUSTOM_TYPE = "subagent-record";
+
+/**
+ * `subagent-record` entry 的 data schema（v1）。
+ *
+ * = 完整 SubagentRecord 快照（GUI 侧列表/详情需要的全部持久化字段）+ 版本号。
+ * 显式排除三个非持久化字段（与 SubagentRecord 的差集）：
+ *   - currentActivity：running 时的瞬时流态，重开 session 无重建价值；
+ *   - externalInstance：跨重启探活态（pid/startedAt），由 .alive sidecar 重建；
+ *   - worktreeHandle：不可 JSON 序列化的运行时句柄（布尔投影 worktree 保留）。
+ *
+ * undefined 字段经 JSON.stringify 自然缺省（与 SubagentRecord 重建侧语义一致）。
+ */
+export interface SubagentRecordEntryData {
+  /** schema 版本（W16 起 v1）。消费方按 v 判别解析，不认识的版本跳过而非猜测。 */
+  v: 1;
+  id: string;
+  agent: string;
+  /** 任务提示词（详情面板置顶展示）。 */
+  task: string;
+  /** 短标签（≤35 字符）。 */
+  slug: string;
+  status: ExecutionStatus;
+  /** L2 关闭原因（仅 status="closed" 时有意义）。 */
+  closedReason?: ClosedReason;
+  mode: ExecutionMode;
+  startedAt: number;
+  /** 根 Pi session ID（session 隔离过滤用）。 */
+  rootSessionId: string | undefined;
+  /** 直接父 subagent record ID（层级树构建用）。顶层为 undefined。 */
+  parentRecordId: string | undefined;
+  /** subagent 递归深度。顶层 = 0。 */
+  depth: number;
+  endedAt: number | undefined;
+  /** turn 计数。 */
+  turns: number;
+  totalTokens: number;
+  model: string;
+  thinkingLevel: string | undefined;
+  /** 详情事件日志（/subagents 详情面板）。 */
+  eventLog: AgentEventLogEntry[];
+  /** 从 turns[] 派生的展示项。 */
+  displayItems: DisplayItem[];
+  result?: string;
+  error?: string;
+  sessionFile?: string;
+  /** [MF#3] worktree 模式改动 patch 文件路径。 */
+  patchFile?: string;
+  /** 创建时是否启用 worktree 隔离。 */
+  worktree?: boolean;
+  /** 对话轮次计数（仅 chatMode 有意义；round+1 由轮终迁移写点携带）。 */
+  round?: number;
+  /**
+   * 对话模式标志（residual-fixes）：chat 与否——GUI 侧 done/waiting 细分判据
+   * （one-shot 轮终 chatMode=false + result 有值 → 完成态）。register 起写入显式值
+   * （one-shot 为显式 false）；v1 前存量 entry 缺省，消费端按保守方向处理。
+   */
+  chatMode?: boolean;
+  /** 执行态信号（residual-fixes）：true = 无活进程驱动的 running（轮终/孤儿兜底）。 */
+  resumable?: boolean;
+}
+
+/** SubagentRecord → 自描述 entry data（快照投影，不 mutate 源）。 */
+export function toSubagentRecordEntry(record: SubagentRecord): SubagentRecordEntryData {
+  return {
+    v: 1,
+    id: record.id,
+    agent: record.agent,
+    task: record.task,
+    slug: record.slug,
+    status: record.status,
+    closedReason: record.closedReason,
+    mode: record.mode,
+    startedAt: record.startedAt,
+    rootSessionId: record.rootSessionId,
+    parentRecordId: record.parentRecordId,
+    depth: record.depth,
+    endedAt: record.endedAt,
+    turns: record.turns,
+    totalTokens: record.totalTokens,
+    model: record.model,
+    thinkingLevel: record.thinkingLevel,
+    eventLog: record.eventLog,
+    displayItems: record.displayItems,
+    result: record.result,
+    error: record.error,
+    sessionFile: record.sessionFile,
+    patchFile: record.patchFile,
+    worktree: record.worktree,
+    round: record.round,
+    chatMode: record.chatMode,
+    resumable: record.resumable,
+  };
+}