@zhushanwen/pi-subagent-workflow 8.5.0 → 8.7.0

package/src/shared/resource-meta.ts

@@ -1,65 +0,0 @@
-/**
- * ResourceMeta — 资源元数据统一类型族（v5 §4.1 / DM1）
- *
- * workflow 与 agent 两类资源共用同一数据格式（YAML），仅 kind 判别 + 专属字段不同。
- * skills 显式 out-of-scope（归 pi core）。
- *
- * 设计：
- * - 整对象透传——config-loader.toCachedMeta / registry-impl.toScript 改为 meta: parsedMeta
- *   不再 {name,description,phases} 解构重建（消灭 3 重映射丢字段 bug）。
- * - workflow 的 parameters（JSON Schema）由 args-validator（m3）按 schema 校验 args；
- *   usage（markdown）覆盖 schema 表达不了的语义约束 + 真实合法示例命令。
- * - agent 的 tools/model 供 AgentRegistry 执行侧 spawn 子进程用，不进 system prompt 注入段。
- *
- * 层归属：shared（L1 统一资源模型）。
- */
-
-/** 资源种类。skills 归 pi core，本 extension 仅 workflow + agent。 */
-export type ResourceKind = "workflow" | "agent";
-
-/** 两类资源共有的路由字段。 */
-export interface ResourceMetaBase {
-  kind: ResourceKind;
-  /** 路由用一句话（受 SSOT lint W1/W2 约束：≤200 字符、不含参数引用语法）。 */
-  name: string;
-  description: string;
-  /** "Use when ..." 正向路由提示（PromptBudget 最后保）。 */
-  when?: string;
-  /** "Not for ..." 负向路由提示。 */
-  notFor?: string;
-}
-
-/** workflow 专属：phases + 参数契约 + 语义说明。 */
-export interface WorkflowMeta extends ResourceMetaBase {
-  kind: "workflow";
-  phases: (string | { title: string; detail?: string })[];
-  /** 参数契约（JSON Schema draft-07）。未声明则 $ARGS 透传不校验（向后兼容）。 */
-  parameters?: Record<string, unknown>;
-  /** markdown，覆盖 schema 表达不了的语义约束 + 真实合法示例命令。 */
-  usage?: string;
-}
-
-/** agent 路由样本（结构化，非嵌入 description 字符串）。 */
-export interface RoutingExample {
-  match: string;
-  action: string;
-  /** true=应触发，false=不应触发（正反各一）。 */
-  positive: boolean;
-}
-
-/** agent 专属：路由样本 + 执行配置。 */
-export interface AgentMeta extends ResourceMetaBase {
-  kind: "agent";
-  examples?: RoutingExample[];
-  /** 供 AgentRegistry 执行侧 spawn 时注入，不进 system prompt 注入段。 */
-  tools?: string[];
-  model?: string;
-  /**
-   * 执行引擎 id（D9 per-agent 主通道：调用参数 engine > 本字段 > 全局默认）。
-   * 与 model 字段同风格——路由字段（不进 system prompt），执行侧（P4 路由层）消费。
-   */
-  engine?: string;
-}
-
-/** 判别联合（kind 判别）。 */
-export type ResourceMeta = WorkflowMeta | AgentMeta;

package/src/shared/schema-jsonify.ts

@@ -1,56 +0,0 @@
-/**
- * Schema JSON 序列化缓存（IF7/#13，TC6/DM4）。
- *
- * 同一 schema 对象引用的重复 JSON.stringify 消除：resolver（compact，instruction
- * 与 schemaEnv 复用同串）与 session-runner formatSchemaInstruction（pretty）在
- * 单次 agent call 内对同一 schema 对象各 stringify 一次；error-recovery 重试路径
- * 再加一次。本 helper 用 WeakMap 按对象引用缓存两种格式，命中返回缓存串。
- *
- * 返回值与直接 JSON.stringify 逐字节一致（compact = JSON.stringify(x)、
- * pretty = JSON.stringify(x, null, 2)）。
- *
- * 失效语义：无。WeakMap 键随 schema/opts 对象 GC 自动回收；单 call 生命周期内
- * schema 对象引用稳定（resolver/runner 均只读），引用稳定即值稳定；postMessage
- * 克隆使跨 call 恒为新对象，天然隔离（DM4）。
- *
- * 层归属：Shared（resolver 与 session-runner 共用，无 Pi 依赖）。
- */
-
-const cache = new WeakMap<object, { compact?: string; pretty?: string }>();
-
-/** pretty 格式（JSON.stringify(x, null, N)）的缩进空格数。 */
-const PRETTY_PRINT_INDENT_SPACES = 2;
-
-/**
- * JSON.stringify(schema) 的引用级缓存版。
- *
- * @param schema schema 对象（调用方 if 守卫保证非 undefined，helper 不判空）
- * @param mode "compact" = JSON.stringify(x)；"pretty" = JSON.stringify(x, null, 2)
- */
-export function stringifySchemaCached(schema: object, mode: "compact" | "pretty"): string {
-  let entry = cache.get(schema);
-  if (!entry) {
-    entry = {};
-    cache.set(schema, entry);
-  }
-  const hit = entry[mode];
-  if (hit !== undefined) return hit;
-  // [review 修复] TS lib 盲区：lib 对 object 参数声明 JSON.stringify 返回 string，但
-  // schema 含 `toJSON: () => undefined` 钩子时运行时返回 undefined——直接违反本函数
-  // 声明的 string 返回类型，且 `entry[mode] = undefined` 赋值不生效（缓存永不命中，
-  // 重复 stringify 仅是性能损耗）。显式标注 string | undefined 捕获该窗口，fail-loud
-  // 抛含恢复指引的错误——不回退 String(value)（"[object Object]" 会静默拼进 LLM
-  // 指令，比崩溃更难排查）。抛错时 entry[mode] 未被赋值，缓存无毒化。
-  const serialized: string | undefined =
-    mode === "compact" ? JSON.stringify(schema) : JSON.stringify(schema, null, PRETTY_PRINT_INDENT_SPACES);
-  if (serialized === undefined) {
-    throw new Error(
-      `[subagent-workflow] stringifySchemaCached: JSON.stringify returned undefined (mode=${mode}) — ` +
-        `the schema object defines a toJSON hook returning undefined. ` +
-        `Recovery: check the schema source (agent definition / workflow script), remove that toJSON ` +
-        `or make it return a JSON-serializable value.`,
-    );
-  }
-  entry[mode] = serialized;
-  return serialized;
-}

package/src/shared/xml-injection.ts

@@ -1,35 +0,0 @@
-// src/shared/xml-injection.ts
-//
-// XML 注入段渲染共享原语——subagent / workflow / model 三个 injector 的 format
-// 函数曾是三份手写同构（escapeXml 逐字重复 + 同一段落骨架），提取此模块消除重复。
-// 调用方保留各自的排序契约与条目渲染（字段差异大，不强行归一）。
-
-/**
- * 转义 XML 特殊字符（注入段进每 turn system prompt，内容含 < > & 等会破坏
- * XML 结构——全部字段过一遍转义防注入段破碎）。
- */
-export function escapeXml(str: string): string {
-	return str
-		.replace(/&/g, "&amp;")
-		.replace(/</g, "&lt;")
-		.replace(/>/g, "&gt;")
-		.replace(/"/g, "&quot;")
-		.replace(/'/g, "&apos;");
-}
-
-/**
- * XML 注入段渲染骨架：`"\n\n<tag>"` 前导（衔接宿主 prompt 末尾）+ 引导语 +
- * 条目行 + 闭合标签，以 "\n" join。空条目返回空串（不注入）。
- *
- * 三个 injector 共用此骨架保证段落结构逐字节同构；KV-cache 契约（顺序稳定 =
- * 注入段字节稳定）由调用方排序保证，本函数不重排。
- */
-export function renderXmlSection(section: {
-	tag: string;
-	guide: string;
-	items: string[];
-}): string {
-	if (section.items.length === 0) return "";
-	const lines = [`\n\n<${section.tag}>`, section.guide, ...section.items, `</${section.tag}>`];
-	return lines.join("\n");
-}

package/workflows/README.md

@@ -1,81 +0,0 @@
-# 内置通用编排 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` | 对已知数组批量变换后归约成单一结果 |
-| `review-fix-loop.js` | 多批串行（批内并行 review → aggregate → fix → 重审） | `targetType` + `target`（可选 `batch1..batchN`） | 代码/文档审查并修复直到 clean；前置检查先行（fallow 等） |
-
-> ⚠️ **review-fix-loop 是唯一带写操作的内置 workflow**（fix 阶段修改文件，`autoCommit=true` 才 commit）。其他 4 个均为只读分析。
-
-## 用法
-
-### 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，各自返回评分+发现的问题，最后纯代码拼接各视角的 findings。
-
-> **Note (breaking)**: `outcome.aggregate` is now a concatenated string of each perspective's findings (format: `[perspective] finding1; finding2`, joined by newlines). Previously it was an LLM-produced object `{overallScore, topIssues, consensus}`. If you have generated workflows or downstream tools parsing the old object shape, update them to read `outcome.per_perspective` for structured per-perspective scores/findings, or treat `outcome.aggregate` as plain text.
-
-### scatter-gather — 分发-收集
-
-```
-workflow run scatter-gather --args task="重构认证模块，涉及 session/jwt/oauth 三块"
-```
-
-三段：第一个 agent 把大任务拆成 2-4 个可并行子任务 → `parallel()` 并行处理每个子任务 → gather 阶段用 `agent()` 把各子任务结果合并成最终结论（LLM 合并，非纯代码拼接）。
-
-### 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` → reduce 阶段用 `agent()` 把各 item 的 map 结果归约成单一结论（LLM 归约，非纯代码拼接）。
-
-### review-fix-loop — 多批审查-修复循环
-
-```
-workflow run review-fix-loop --args targetType=git-diff target=main \
-  --args batch1=fallow-scan --args batch2=reviewer --args autoCommit=true
-workflow run review-fix-loop --args targetType=file target=/path/to/doc.md \
-  --args batch1=doc-reviewer
-```
-
-- `targetType` 枚举：`git-diff`（target=base ref）/ `file`（target=路径）/ `dir`（target=目录）/ `text`（target=自由描述）
-- `batch1..batchN`：批串行，批内并行 review → aggregate → fix → 重审直到 clean；批次用于前置依赖（如 `fallow-scan` 静态分析先行，后续审查才有意义）
-- 批内某 agent 无 must-fix 后后续轮跳过（`skipCleanAgents` 默认 true + `recheckAfterFix` 默认 false）：clean agent 下轮跳过不重派；显式传 `recheckAfterFix=true` 启用强回归模式——fix 后重派全批，clean agent 走限定 prompt（只审 modifiedFiles ∪ 自检关联点，不诱导全量重扫）
-- agent 项支持：AgentRegistry 名（如 `reviewer`）/ 自定义 .md 文件路径（如 `batch1=/path/to/reviewer.md`）/ 内置 `fallow-scan` / **内置 `doc-reviewer`**（文档场景推荐：`targetType=file/dir` + `batch1=doc-reviewer`，四遍审查方法论：事实锚点核实/逻辑断言验证/落地清单完备性/边界与迁移；无 write 工具，报告经 schema 返回由 workflow 落盘）
-- `fixAgent`（可选）：fix 阶段加载指定 agent（内置名或 .md 路径）；代码场景可在该 agent.md 内写 verify 命令（typecheck/test 实测）当轮拦截编译类回归。⚠️ agent.md 内写的 verify 命令**必须确认能在目标项目可运行**（target 的包管理器/目录结构未知），否则命令失败会误报 fix 状态
-- `maxFixAttempts`（可选，默认 2）：needs-redesign 阈值。问题经 maxFixAttempts 次修复仍未收敛（regressed）→ 终止该批，terminated="needs-redesign"（结构性问题需人工介入，非继续补丁能解决）
-- `convergeNewIssues`（可选，默认 1）+ `convergeRounds`（可选，默认 2）：新发现率收敛阈值。连续 convergeRounds 轮新发现问题 ≤ convergeNewIssues **且**无 open/regressed 活跃条目 → terminated="converged"（推进下一批）。收敛不等于问题全清——需同时满足无活跃条目才终止
-- ⚠️ **fix 阶段会修改文件；`autoCommit` 默认 false（不 commit）**，需要提交时显式 `autoCommit=true`
-
-## 编排 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/extensions/adr/pi-ext-030-subagents-workflow-merge.md` — 合并决策（决策 3 分层配额 + workflow 嵌套）
-- `docs/extensions/adr/pi-ext-032-builtin-orchestration-workflows.md` — 从"参考模板"改为"内置通用编排 workflow"的决策

package/workflows/_shared/agent-refs.cjs

@@ -1,40 +0,0 @@
-// workflows/_shared/agent-refs.cjs
-//
-// 编排 workflow 共用的 agentRef 参数解析（S4 路径统一）。
-//
-// agentRef = .md 绝对路径（注入段 <available_subagents> 的 <location>）。
-// agents 参数 = 逗号分隔的 agentRef 列表，按阶段顺序一一映射。
-// 缺省（未传/空）= 不指定 agent（默认执行者）——编排骨架不强制指定执行者。
-//
-// 注意：本模块只做「字符串 → 路径数组」的纯解析，不读文件。agent 内容的加载
-// 由主线程 resolveAgentOpts（agent-call 时按路径读 + systemPrompt 注入）统一完成。
-"use strict";
-
-/**
- * 解析 agents 参数为 agentRef 路径数组。
- *
- * @param raw 逗号分隔字符串（如 "/a/x.md,/b/y.md"）；undefined/null/空 → []
- * @returns 路径数组（trim + 去空项）
- */
-function parseAgentRefs(raw) {
-  if (raw === undefined || raw === null) return [];
-  if (typeof raw !== "string") return [];
-  const refs = raw
-    .split(",")
-    .map((s) => s.trim())
-    .filter(Boolean);
-  return refs;
-}
-
-/**
- * 按阶段索引取 agentRef（缺省 undefined = 不指定 agent）。
- *
- * @param refs   parseAgentRefs 结果
- * @param index  阶段索引（0-based）
- * @returns agentRef 或 undefined
- */
-function agentRefAt(refs, index) {
-  return refs.length > index ? refs[index] : undefined;
-}
-
-module.exports = { parseAgentRefs, agentRefAt };

package/workflows/chain.js

@@ -1,131 +0,0 @@
-// chain.js — 顺序多步处理（通用 subagent 编排）
-//
-// 模式：analyze → transform → synthesize，每步 agent() 输出作下步输入。
-// 适用于需要"先分析、再变换、最后综合"的多阶段任务。
-//
-// 用法：
-//   workflow run chain --args task="把这段需求文档拆成技术任务：..."
-//
-// ⚠️ lintScript 约束（本脚本已遵守）：
-//   - 含 agent() 入口
-//   - 禁止 bare IIFE（用 top-level await）
-//   - 禁止用 result 作变量名
-
-/* @pi-meta
-name: chain
-description: 通用编排：analyze → transform → synthesize 顺序三步链
-phases: [analyze, transform, synthesize]
-parameters:
-  type: object
-  properties:
-    task: { type: string, minLength: 1 }
-    agents: { type: string }
-  required: [task]
-usage: |
-  ## 使用说明
-  - 顺序三步链：analyze（提取要点）→ transform（产出方案）→ synthesize（合成结论）
-  - agents：逗号分隔的 agent .md 绝对路径，按顺序对应三步（少于 3 个尾部用默认执行者）
-  - 示例：workflow run chain --args task="<任务描述>" agents="/path/analyzer.md,/path/planner.md"
-*/
-
-// ── 入参（$ARGS）──────────────────────────────────────────────────
-const task = $ARGS.task;
-if (typeof task !== "string" || task.trim() === "") {
-  throw new Error("chain 缺少必需参数 task（非空字符串）。用法：workflow run chain --args task=\"<描述>\"");
-}
-
-// S4：agents 参数 = 逗号分隔的 agentRef 路径数组，按阶段顺序对应三步
-// worker 沙箱为 eval 模式：require 相对路径以 cwd 为基准（非脚本目录），
-// 必须用 workerData.scriptPath 锚定脚本目录（review-fix-loop 同模式）。
-const SCRIPT_DIR = workerData && workerData.scriptPath
-  ? require("path").dirname(workerData.scriptPath)
-  : process.cwd();
-const { parseAgentRefs, agentRefAt } = require(SCRIPT_DIR + "/_shared/agent-refs.cjs");
-const agentRefs = parseAgentRefs($ARGS.agents);
-const stepAgent = (i) => { const ref = agentRefAt(agentRefs, i); return ref ? { agent: ref } : {}; };
-
-log("chain 开始，task=" + task + (agentRefs.length ? "，agents=" + agentRefs.join(",") : ""));
-
-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",
-    ...stepAgent(0),
-  });
-
-  // ── 段 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",
-    ...stepAgent(1),
-  });
-
-  // ── 段 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",
-    ...stepAgent(2),
-  });
-
-  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

@@ -1,174 +0,0 @@
-// 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
-
-/* @pi-meta
-name: map-reduce
-description: 通用编排：parallel map → reduce 两段，处理已知 items 数组
-phases: [map, reduce]
-parameters:
-  type: object
-  properties:
-    items: { type: array, items: { type: string } }
-    itemsJson: { type: string }
-    operation: { type: string }
-    agents: { type: string }
-  required: [operation]
-  oneOf:
-    - required: [items]
-    - required: [itemsJson]
-usage: |
-  ## 使用说明
-  - items 与 itemsJson 至少一个：items 直接传字符串数组，itemsJson 传文件路径（内容为 JSON 数组）
-  - agents：逗号分隔的 agent .md 绝对路径，按顺序对应 map/reduce 两段
-  - 示例：workflow run map-reduce --args operation="<对每个 item 做什么>" itemsJson="/path/items.json" agents="/path/mapper.md,/path/reducer.md"
-*/
-
-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);
-
-// S4：agents 参数 = 逗号分隔的 agentRef 路径数组，按顺序对应 map/reduce 两段
-// worker 沙箱为 eval 模式：require 相对路径以 cwd 为基准（非脚本目录），
-// 必须用 workerData.scriptPath 锚定脚本目录（review-fix-loop 同模式）。
-const SCRIPT_DIR = workerData && workerData.scriptPath
-  ? require("path").dirname(workerData.scriptPath)
-  : process.cwd();
-const { parseAgentRefs, agentRefAt } = require(SCRIPT_DIR + "/_shared/agent-refs.cjs");
-const agentRefs = parseAgentRefs($ARGS.agents);
-const stepAgent = (i) => { const ref = agentRefAt(agentRefs, i); return ref ? { agent: ref } : {}; };
-
-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,
-        ...stepAgent(0),
-      })
-    ),
-  );
-
-  const mapped = [];
-  let mapFailed = 0;
-  for (let i = 0; i < mappedRaw.length; i++) {
-    const r = mappedRaw[i];
-    if (!r || r.status === "failed" || r.error) {
-      mapped.push({
-        itemIndex: i,
-        item: items[i],
-        status: "failed",
-        error: r ? (r.error || "agent 返回 failed 状态") : "agent 无返回",
-      });
-      mapFailed++;
-    } else {
-      mapped.push({
-        itemIndex: i,
-        item: items[i],
-        status: "ok",
-        mapped: (typeof r.mapped === "string" ? 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 reducedResult = 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",
-    ...stepAgent(1),
-  });
-
-  outcome = {
-    status: mapFailed > 0 ? "partial" : "ok",
-    phases_run: ["map", "reduce"],
-    items_total: items.length,
-    items_mapped: items.length - mapFailed,
-    reduced: {
-      reduced: (reducedResult?.reduced ?? "(归约无结果)"),
-      stats: (reducedResult?.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;