@zhushanwen/pi-subagent-workflow 0.1.0 → 0.2.0

package/src/orchestration/models/run-spec.ts

@@ -40,6 +40,12 @@ export interface RunSpec {
   readonly budgetRef?: Budget;
  /** 脚本名（meta.name 或文件名 stem）。 */
   readonly scriptName: string;
+ /**
+ * Run 级简短标签（≤20 字符），区别于 scriptName（脚本身份名）。
+ * 区分同脚本的不同 run 实例（如 'migrate-users-batch1' vs 'migrate-users-batch2'）。
+ * 旧持久化 run 缺失时为 undefined，渲染时回落 scriptName。
+ */
+  readonly slug?: string;
  /** 脚本文件绝对路径（用于诊断/日志）。 */
   readonly scriptPath: string;
  /** 人类可读描述（meta.description）。 */

package/src/orchestration/models/trace.ts

@@ -61,6 +61,7 @@ export class Trace {
     if (patch.error !== undefined) node.error = patch.error;
     if (patch.completedAt !== undefined) node.completedAt = patch.completedAt;
     if (patch.sessionId !== undefined) node.sessionId = patch.sessionId;
+    if (patch.sessionFile !== undefined) node.sessionFile = patch.sessionFile;
   }
 
  /** 查找指定 stepIndex 的节点（首个匹配，trace 中 stepIndex 应唯一）。 */

package/src/orchestration/models/types.ts

@@ -84,6 +84,12 @@ export interface AgentCallOpts {
  * When omitted, pi's default model is used.
  */
   model?: string;
+ /**
+ * Thinking level override (e.g. "high", "medium", "low").
+ * M2: Added to align with subagent path's ExecuteOptions.thinkingLevel.
+ * When omitted, agent .md frontmatter thinkingLevel is used (via resolveAgentOpts).
+ */
+  thinkingLevel?: string;
  /** Scene name for model-switch advisor recommendation. */
   scene?: string;
  /**
@@ -181,6 +187,13 @@ export interface AgentResult {
  * Can be used to locate the session JSONL file for post-run inspection (G-017)。
  */
   sessionId?: string;
+ /**
+ * Session JSONL 绝对路径（不含目录的文件名在 subagents 侧 AgentResult.sessionFile）。
+ * 由 mapToWorkflowAgentResult 从 subagents AgentResult 透传——让 workflow 编排层
+ * 继承 subagent 执行管道产出的 session 文件路径，overlay/GUI 可直接定位。
+ * 窗口期内可能 undefined（session 尚未创建成功）。
+ */
+  sessionFile?: string;
  /** All tool calls collected from JSONL stream (FR-7). */
   toolCalls?: ToolCallEntry[];
 }
@@ -208,6 +221,11 @@ export interface ExecutionTraceNode {
  */
   sessionId?: string;
  /**
+ * Session JSONL 绝对路径。finalizeCall 从 result.sessionFile 透传。
+ * 持久化到快照（serializeRun），pause/resume + 跨 session 重水合后保留。
+ */
+  sessionFile?: string;
+ /**
  * Live 执行进度对象（running 时存在，done 时由 dispatchAgentCall 清除）。
  *
  * 挂在 node 上（D-10 单源延伸：AgentCall.traceNode 与 Trace.nodes 共享同一引用）。
@@ -229,6 +247,7 @@ export interface TracePatch {
   error?: string;
   completedAt?: string;
   sessionId?: string;
+  sessionFile?: string;
 }
 
 // ── Worker 诊断 ───────────────────────────────────────────────

package/src/orchestration/node-ops.ts

@@ -96,6 +96,7 @@ export async function retryNode(
   call.attempts = 0;
   call.result = undefined;
   call.sessionId = undefined;
+  call.sessionFile = undefined;
 
  // 同步 trace 节点：回退到 pending
   run.state.trace.update(callId, {
@@ -104,6 +105,7 @@ export async function retryNode(
     error: undefined,
     completedAt: undefined,
     sessionId: undefined,
+    sessionFile: undefined,
   });
 
  // 主线程重跑（不重启 worker）——executeAgentCall 内部 markRunning + runner.run

package/src/orchestration/worker-script-builder.ts

@@ -170,6 +170,7 @@ export function buildWorkerScript(userScript: string): string {
     '          schema: firstArg.schema,',
     '          model: firstArg.model,',
     '          scene: firstArg.scene,',
+    '          skill: firstArg.skill,',
     '          timeoutMs: firstArg.timeoutMs,',
     '          cwd: firstArg.cwd,',
     '        };',

package/workflows/README.md

@@ -0,0 +1,58 @@
+# 内置通用编排 Workflow
+
+4 个开箱即用的通用 subagent 编排 workflow，覆盖日常常见的多 agent 协作模式。每个脚本用 `agent()`/`parallel()` 自包含实现，`workflow run <name>` 直接执行，无需额外定义子 workflow。
+
+## 文件清单
+
+| workflow | 模式 | 必需参数 | 适用场景 |
+|----------|------|----------|----------|
+| `chain.js` | analyze → transform → synthesize 顺序链 | `task` | 多阶段处理：先分析、再变换、最后综合 |
+| `parallel.js` | 多视角并行分析 → 聚合汇总 | `target`（可选 `perspectives`） | 多维度评估同一目标（安全/性能/可维护性等） |
+| `scatter-gather.js` | scatter 拆分 → parallel 处理 → gather 合并 | `task` | 大任务先拆成子任务再并行处理 |
+| `map-reduce.js` | parallel map → reduce 归约 | `items`/`itemsJson` + `operation` | 对已知数组批量变换后归约成单一结果 |
+
+## 用法
+
+### chain — 顺序多步处理
+
+```
+workflow run chain --args task="把这段需求文档拆成技术任务：..."
+```
+
+三段 agent 调用：分析任务 → 基于分析产出方案 → 综合方案输出结论。每步用 `schema` 拿结构化输出，上一步输出拼进下一步 prompt。
+
+### parallel — 并行多视角分析
+
+```
+workflow run parallel --args target="src/auth/login.ts"
+workflow run parallel --args target="..." --args 'perspectives=["security","readability"]'
+```
+
+`perspectives` 默认 `["security","performance","maintainability"]`。每个视角一个并行 agent，各自返回评分+发现的问题；最后再一个 agent 汇总成总体评分+top 问题+共识。
+
+### scatter-gather — 分发-收集
+
+```
+workflow run scatter-gather --args task="重构认证模块，涉及 session/jwt/oauth 三块"
+```
+
+三段：第一个 agent 把大任务拆成 2-4 个可并行子任务 → `parallel()` 并行处理每个子任务 → 最后一个 agent 合并所有结果。
+
+### map-reduce — 映射-归约
+
+```
+workflow run map-reduce --args 'items=["file1.ts","file2.ts","file3.ts"]' --args operation="审查代码风格"
+workflow run map-reduce --args itemsJson=/path/to/items.json --args operation="..."
+```
+
+`items` 直接传 JSON 数组，或 `itemsJson` 传 JSON 文件路径（二选一）。`parallel()` 对每个 item 并行执行 `operation` → 一个 agent 把所有结果归约成单一结论。
+
+## 编排 API
+
+这些 workflow 内部使用的编排函数（`agent()` / `parallel()` / `pipeline()` / `workflow()`）由 worker 线程注入，完整 API 参考见 `skills/workflow-script-format/SKILL.md`。
+
+## 相关文档
+
+- `skills/workflow-script-format/SKILL.md` — workflow script 完整 API（agent/parallel/pipeline/workflow 签名、$ARGS/$BUDGET、lint 规则）
+- `docs/adr/030-subagents-workflow-merge.md` — 合并决策（决策 3 分层配额 + workflow 嵌套）
+- `docs/adr/032-builtin-orchestration-workflows.md` — 从"参考模板"改为"内置通用编排 workflow"的决策

package/workflows/chain.js

@@ -0,0 +1,107 @@
+// chain.js — 顺序多步处理（通用 subagent 编排）
+//
+// 模式：analyze → transform → synthesize，每步 agent() 输出作下步输入。
+// 适用于需要"先分析、再变换、最后综合"的多阶段任务。
+//
+// 用法：
+//   workflow run chain --args task="把这段需求文档拆成技术任务：..."
+//
+// ⚠️ lintScript 约束（本脚本已遵守）：
+//   - 含 agent() 入口
+//   - 禁止 bare IIFE（用 top-level await）
+//   - 禁止用 result 作变量名
+
+const meta = {
+  name: "chain",
+  description: "通用编排：analyze → transform → synthesize 顺序三步链",
+  phases: ["analyze", "transform", "synthesize"],
+};
+
+// ── 入参（$ARGS）──────────────────────────────────────────────────
+const task = $ARGS.task;
+if (!task) {
+  throw new Error("chain 缺少必需参数 task。用法：workflow run chain --args task=\"<任务描述>\"");
+}
+
+log("chain 开始，task=" + task);
+
+let currentPhase = "init";
+let outcome;
+
+try {
+  // ── 段 1：analyze（分析任务，提取关键点）─────────────────────────
+  phase("analyze");
+  currentPhase = "analyze";
+  const analysis = await agent({
+    prompt: "分析以下任务，提取核心洞察和关键点：\n\n" + task,
+    schema: {
+      type: "object",
+      properties: {
+        insights: { type: "string", description: "对任务的核心洞察" },
+        keyPoints: {
+          type: "array",
+          items: { type: "string" },
+          description: "关键点列表",
+        },
+      },
+      required: ["insights", "keyPoints"],
+    },
+    description: "chain-analyze",
+  });
+
+  // ── 段 2：transform（基于分析产出方案）───────────────────────────
+  phase("transform");
+  currentPhase = "transform";
+  const plan = await agent({
+    prompt:
+      "基于以下分析结果，产出可执行方案：\n\n洞察：" + (analysis?.insights ?? "(分析无结果)") +
+      "\n关键点：" + JSON.stringify(analysis?.keyPoints ?? []),
+    schema: {
+      type: "object",
+      properties: {
+        plan: { type: "string", description: "执行方案" },
+        actions: {
+          type: "array",
+          items: { type: "string" },
+          description: "具体行动步骤",
+        },
+      },
+      required: ["plan", "actions"],
+    },
+    description: "chain-transform",
+  });
+
+  // ── 段 3：synthesize（综合方案输出最终结论）─────────────────────
+  phase("synthesize");
+  currentPhase = "synthesize";
+  const final = await agent({
+    prompt:
+      "综合以下方案，输出最终结论和建议：\n\n方案：" + (plan?.plan ?? "(方案无结果)") +
+      "\n行动步骤：" + JSON.stringify(plan?.actions ?? []),
+    schema: {
+      type: "object",
+      properties: {
+        summary: { type: "string", description: "最终总结" },
+        recommendation: { type: "string", description: "核心建议" },
+      },
+      required: ["summary", "recommendation"],
+    },
+    description: "chain-synthesize",
+  });
+
+  outcome = {
+    status: "ok",
+    phases_run: ["analyze", "transform", "synthesize"],
+    final: { summary: (final?.summary ?? "(综合无结果)"), recommendation: (final?.recommendation ?? "(综合无结果)") },
+    message: "chain 完成：analyze → transform → synthesize 全绿",
+  };
+} catch (err) {
+  outcome = {
+    status: "error",
+    phase: currentPhase,
+    error: err && err.message ? err.message : String(err),
+    message: "chain 在 " + currentPhase + " 段失败",
+  };
+}
+
+return outcome;

package/workflows/map-reduce.js

@@ -0,0 +1,142 @@
+// map-reduce.js — 映射-归约（通用 subagent 编排）
+//
+// 模式（两段）：
+//   段 1 map:    parallel() 对每个 item 并行执行 operation
+//   段 2 reduce: agent() 把所有 map 结果归约成单一结果
+//
+// 与 scatter-gather 的区别：scatter-gather 强调"拆分"（scatter 决定子任务数）；
+// map-reduce 强调对"已知 items 数组"的变换+聚合（items 已有，map 变换、reduce 归约）。
+//
+// 用法：
+//   workflow run map-reduce --args 'items=["file1.ts","file2.ts","file3.ts"]' --args operation="审查代码风格"
+//   workflow run map-reduce --args itemsJson=/path/to/items.json --args operation="..."
+//
+// ⚠️ lintScript 约束（本脚本已遵守）：含 parallel() 入口（兼 agent 嵌套），禁止 bare IIFE
+
+const meta = {
+  name: "map-reduce",
+  description: "通用编排：parallel map → reduce 两段，处理已知 items 数组",
+  phases: ["map", "reduce"],
+};
+
+const fs = require("fs");
+
+// ── 入参（$ARGS）──────────────────────────────────────────────────
+const operation = $ARGS.operation;
+if (!operation) {
+  throw new Error(
+    'map-reduce 缺少必需参数 operation。用法：workflow run map-reduce --args operation="<对每个 item 做什么>"',
+  );
+}
+
+// items 来源：直接数组 或 itemsJson 文件路径（二选一）
+let items = $ARGS.items;
+if (!items) {
+  const itemsPath = $ARGS.itemsJson;
+  if (!itemsPath) {
+    throw new Error(
+      'map-reduce 需要 items（直接数组）或 itemsJson（JSON 文件路径）参数',
+    );
+  }
+  if (!fs.existsSync(itemsPath)) {
+    throw new Error("itemsJson 文件不存在: " + itemsPath);
+  }
+  items = JSON.parse(fs.readFileSync(itemsPath, "utf-8"));
+}
+
+if (!Array.isArray(items) || items.length === 0) {
+  throw new Error("items 不是数组或为空");
+}
+
+log("map-reduce 开始，items=" + items.length + " 个，operation=" + operation);
+
+let currentPhase = "init";
+let outcome;
+
+try {
+  // ── 段 1：map（parallel 对每个 item 并行变换）────────────────────
+  phase("map");
+  currentPhase = "map";
+
+  // 每个 item 字符串化，便于拼进 prompt
+  const mappedRaw = await parallel(
+    items.map((item, idx) =>
+      agent({
+        prompt:
+          "对以下 item 执行操作：\n\noperation：" + operation +
+          "\nitem：" + (typeof item === "string" ? item : JSON.stringify(item)),
+        schema: {
+          type: "object",
+          properties: {
+            itemIndex: { type: "number", description: "item 序号" },
+            mapped: { type: "string", description: "map 后的结果" },
+          },
+          required: ["itemIndex", "mapped"],
+        },
+        description: "map-reduce-map-" + idx,
+      })
+    ),
+  );
+
+  const mapped = [];
+  let mapFailed = 0;
+  for (let i = 0; i < mappedRaw.length; i++) {
+    const r = mappedRaw[i];
+    if (!r || r.error) {
+      mapped.push({
+        itemIndex: i,
+        item: items[i],
+        status: "failed",
+        error: r ? r.error : "agent 无返回",
+      });
+      mapFailed++;
+    } else {
+      mapped.push({
+        itemIndex: i,
+        item: items[i],
+        status: "ok",
+        mapped: r.mapped,
+      });
+    }
+  }
+  if (mapFailed === items.length) {
+    throw new Error("全部 map 失败（" + mapFailed + "/" + items.length + "）");
+  }
+  log("map 完成：ok=" + (items.length - mapFailed) + " failed=" + mapFailed);
+
+  // ── 段 2：reduce（agent 聚合所有 map 结果）──────────────────────
+  phase("reduce");
+  currentPhase = "reduce";
+  const reduced = await agent({
+    prompt:
+      "以下是对 " + items.length + " 个 item 执行「" + operation + "」的结果，请归约成单一结论：\n\n" +
+      JSON.stringify(mapped, null, 2),
+    schema: {
+      type: "object",
+      properties: {
+        reduced: { type: "string", description: "归约后的最终结果" },
+        stats: { type: "string", description: "统计摘要（成功率/共性发现等）" },
+      },
+      required: ["reduced", "stats"],
+    },
+    description: "map-reduce-reduce",
+  });
+
+  outcome = {
+    status: mapFailed > 0 ? "partial" : "ok",
+    phases_run: ["map", "reduce"],
+    items_total: items.length,
+    items_mapped: items.length - mapFailed,
+    reduced: { reduced: (reduced?.reduced ?? "(归约无结果)"), stats: (reduced?.stats ?? "(归约无结果)") },
+    message: "map-reduce 完成：map " + items.length + " 项（失败 " + mapFailed + "）→ reduce",
+  };
+} catch (err) {
+  outcome = {
+    status: "error",
+    phase: currentPhase,
+    error: err && err.message ? err.message : String(err),
+    message: "map-reduce 在 " + currentPhase + " 段失败",
+  };
+}
+
+return outcome;

package/workflows/parallel.js

@@ -0,0 +1,131 @@
+// parallel.js — 并行多视角分析（通用 subagent 编排）
+//
+// 模式：N 个 agent 从不同角度并行分析同一目标 → 汇总聚合。
+// 适用于需要多维度评估（安全/性能/可维护性等）的场景。
+//
+// 用法：
+//   workflow run parallel --args target="src/auth/login.ts"
+//   workflow run parallel --args target="..." --args 'perspectives=["security","readability"]'
+//
+// ⚠️ 分层配额规则（来源：ADR-030 决策 3）：
+//   - 全局并发上限 maxConcurrent = 6
+//   - parallel() 内的 agent() 调用共享配额池，超出自动排队（不报错）
+//   - 本脚本默认 3 视角并行，配额充足
+//
+// ⚠️ lintScript 约束（本脚本已遵守）：含 parallel() 入口，禁止 bare IIFE
+
+const meta = {
+  name: "parallel",
+  description: "通用编排：多视角并行分析同一目标，再聚合汇总",
+  phases: ["parallel-analyze", "aggregate"],
+};
+
+// ── 入参（$ARGS）──────────────────────────────────────────────────
+const target = $ARGS.target;
+if (!target) {
+  throw new Error("parallel 缺少必需参数 target。用法：workflow run parallel --args target=\"<分析目标>\"");
+}
+const perspectives = Array.isArray($ARGS.perspectives) && $ARGS.perspectives.length > 0
+  ? $ARGS.perspectives
+  : ["security", "performance", "maintainability"];
+
+log("parallel 开始，target=" + target + " perspectives=" + JSON.stringify(perspectives));
+
+let currentPhase = "init";
+let outcome;
+
+try {
+  // ── 段 1：parallel-analyze（多视角并行分析）──────────────────────
+  phase("parallel-analyze");
+  currentPhase = "parallel-analyze";
+
+  // parallel() 接受 Promise 数组；agent() 返回 Promise。allSettled 语义。
+  const perPerspectiveRaw = await parallel(
+    perspectives.map((p) =>
+      agent({
+        prompt:
+          "从「" + p + "」角度分析以下目标，给出评分和发现的问题：\n\n" + target,
+        schema: {
+          type: "object",
+          properties: {
+            perspective: { type: "string", description: "视角名称" },
+            score: { type: "number", description: "0-10 评分" },
+            findings: {
+              type: "array",
+              items: { type: "string" },
+              description: "发现的问题",
+            },
+          },
+          required: ["perspective", "score", "findings"],
+        },
+        description: "parallel-" + p,
+      })
+    ),
+  );
+
+  // 收集结果，标记成功/失败
+  const perPerspective = [];
+  let failedCount = 0;
+  for (let i = 0; i < perPerspectiveRaw.length; i++) {
+    const r = perPerspectiveRaw[i];
+    if (!r || r.error) {
+      perPerspective.push({
+        perspective: perspectives[i],
+        status: "failed",
+        error: r ? r.error : "agent 无返回",
+      });
+      failedCount++;
+    } else {
+      perPerspective.push({ perspective: perspectives[i], status: "ok", ...r });
+    }
+  }
+  if (failedCount === perspectives.length) {
+    throw new Error("全部视角分析失败（" + failedCount + "/" + perspectives.length + "）");
+  }
+  log("parallel-analyze 完成：ok=" + (perspectives.length - failedCount) + " failed=" + failedCount);
+
+  // ── 段 2：aggregate（汇总多视角结果）────────────────────────────
+  phase("aggregate");
+  currentPhase = "aggregate";
+  const aggregate = await agent({
+    prompt:
+      "以下是多视角分析结果，请综合出总体评分、top 问题和共识：\n\n" +
+      JSON.stringify(perPerspective, null, 2),
+    schema: {
+      type: "object",
+      properties: {
+        overallScore: { type: "number", description: "综合评分 0-10" },
+        topIssues: {
+          type: "array",
+          items: { type: "string" },
+          description: "最关键的问题（按严重度排序）",
+        },
+        consensus: { type: "string", description: "多视角共识总结" },
+      },
+      required: ["overallScore", "topIssues", "consensus"],
+    },
+    description: "parallel-aggregate",
+  });
+
+  outcome = {
+    status: failedCount > 0 ? "partial" : "ok",
+    phases_run: ["parallel-analyze", "aggregate"],
+    perspectives_analyzed: perspectives.length,
+    per_perspective: perPerspective,
+    aggregate: {
+      overallScore: (aggregate?.overallScore ?? "(聚合无结果)"),
+      topIssues: (aggregate?.topIssues ?? []),
+      consensus: (aggregate?.consensus ?? "(聚合无结果)"),
+    },
+    message: "parallel 完成：" + perspectives.length + " 视角（失败 " + failedCount + "）→ 聚合",
+  };
+} catch (err) {
+  outcome = {
+    status: "error",
+    phase: currentPhase,
+    error: err && err.message ? err.message : String(err),
+    message: "parallel 在 " + currentPhase + " 段失败",
+  };
+}
+
+return outcome;

package/workflows/scatter-gather.js

@@ -0,0 +1,146 @@
+// scatter-gather.js — 分发-收集（通用 subagent 编排）
+//
+// 模式（三段）：
+//   段 1 scatter: agent() 把大任务拆成 2-4 个可并行的子任务
+//   段 2 process: parallel() 并行处理每个子任务
+//   段 3 gather:  agent() 合并所有子任务结果
+//
+// 适用于"任务太大需要先拆分再并行处理"的场景。
+//
+// 用法：
+//   workflow run scatter-gather --args task="重构认证模块，涉及 session/jwt/oauth 三块"
+//
+// ⚠️ lintScript 约束（本脚本已遵守）：含 parallel() 入口（兼 agent 嵌套），禁止 bare IIFE
+
+const meta = {
+  name: "scatter-gather",
+  description: "通用编排：scatter 拆分 → parallel 处理 → gather 合并 三段",
+  phases: ["scatter", "process", "gather"],
+};
+
+// ── 入参（$ARGS）──────────────────────────────────────────────────
+const task = $ARGS.task;
+if (!task) {
+  throw new Error("scatter-gather 缺少必需参数 task。用法：workflow run scatter-gather --args task=\"<大任务描述>\"");
+}
+
+log("scatter-gather 开始，task=" + task);
+
+let currentPhase = "init";
+let outcome;
+
+try {
+  // ── 段 1：scatter（拆分任务）─────────────────────────────────────
+  phase("scatter");
+  currentPhase = "scatter";
+  const split = await agent({
+    prompt:
+      "把以下任务拆成 2-4 个可独立并行处理的子任务。每个子任务应有明确边界，不互相依赖：\n\n" +
+      task,
+    schema: {
+      type: "object",
+      properties: {
+        subtasks: {
+          type: "array",
+          items: {
+            type: "object",
+            properties: {
+              name: { type: "string", description: "子任务名称" },
+              description: { type: "string", description: "子任务详细描述" },
+            },
+            required: ["name", "description"],
+          },
+          description: "2-4 个可并行的子任务",
+        },
+      },
+      required: ["subtasks"],
+    },
+    description: "scatter-split",
+  });
+
+  const subtasks = Array.isArray(split?.subtasks) ? split.subtasks : [];
+  if (subtasks.length === 0) {
+    throw new Error("scatter 返回的 subtasks 为空");
+  }
+  log("scatter 出 " + subtasks.length + " 个子任务");
+
+  // ── 段 2：process（parallel 并行处理每个子任务）──────────────────
+  phase("process");
+  currentPhase = "process";
+  const processedRaw = await parallel(
+    subtasks.map((s) =>
+      agent({
+        prompt:
+          "处理以下子任务，输出处理结果：\n\n子任务：" + s.name + "\n描述：" + s.description,
+        schema: {
+          type: "object",
+          properties: {
+            subtask: { type: "string", description: "子任务名称" },
+            result: { type: "string", description: "处理结果" },
+          },
+          required: ["subtask", "result"],
+        },
+        description: "scatter-process-" + s.name,
+      })
+    ),
+  );
+
+  const processed = [];
+  let failedCount = 0;
+  for (let i = 0; i < processedRaw.length; i++) {
+    const r = processedRaw[i];
+    if (!r || r.error) {
+      processed.push({
+        subtask: subtasks[i].name,
+        status: "failed",
+        error: r ? r.error : "agent 无返回",
+      });
+      failedCount++;
+    } else {
+      processed.push({ subtask: subtasks[i].name, status: "ok", result: r.result });
+    }
+  }
+  if (failedCount === subtasks.length) {
+    throw new Error("全部子任务处理失败（" + failedCount + "/" + subtasks.length + "）");
+  }
+  log("process 完成：ok=" + (subtasks.length - failedCount) + " failed=" + failedCount);
+
+  // ── 段 3：gather（合并所有子任务结果）───────────────────────────
+  phase("gather");
+  currentPhase = "gather";
+  const gathered = await agent({
+    prompt:
+      "以下是各子任务的处理结果，请合并成一个完整、一致的最终结果：\n\n" +
+      JSON.stringify(processed, null, 2),
+    schema: {
+      type: "object",
+      properties: {
+        mergedResult: { type: "string", description: "合并后的最终结果" },
+        completeness: { type: "string", description: "完整性评估" },
+      },
+      required: ["mergedResult", "completeness"],
+    },
+    description: "scatter-gather-merge",
+  });
+
+  outcome = {
+    status: failedCount > 0 ? "partial" : "ok",
+    phases_run: ["scatter", "process", "gather"],
+    subtasks_total: subtasks.length,
+    subtasks_processed: subtasks.length - failedCount,
+    gathered: {
+      mergedResult: (gathered?.mergedResult ?? "(合并无结果)"),
+      completeness: (gathered?.completeness ?? "(合并无结果)"),
+    },
+    message: "scatter-gather 完成：split " + subtasks.length + " → process（失败 " + failedCount + "）→ merge",
+  };
+} catch (err) {
+  outcome = {
+    status: "error",
+    phase: currentPhase,
+    error: err && err.message ? err.message : String(err),
+    message: "scatter-gather 在 " + currentPhase + " 段失败",
+  };
+}
+
+return outcome;