@zhushanwen/subagent-core 0.2.0

package/src/shared/resource-meta.ts

@@ -0,0 +1,65 @@
+/**
+ * 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-env.ts

@@ -0,0 +1,44 @@
+/**
+ * schema env 跨包契约常量（零依赖叶子模块）。
+ *
+ * 抽取自 session-runner.ts（S5 记账项）：session-runner 依赖树沉重（pi SDK /
+ * spawn 链），跨包契约测试若从它 import 常量会把整条依赖树拖进测试进程。
+ * 本模块只含常量与纯函数、零 import，为 structured-output 侧（及任何消费者）
+ * 的跨包契约测试提供稳定 import 点。
+ *
+ * 层归属：Shared（orchestration 与 execution 共用，先例 timer-delay.ts）。
+ */
+
+/**
+ * 跨包契约 env 名：workflow 子进程把权威 JSON Schema 通过此 env 传给 structured-output 扩展。
+ *
+ * [跨包契约 SSOT] 此字面量是两个独立 npm 包（@zhushanwen/pi-subagent-workflow 与
+ * @zhushanwen/pi-structured-output）之间的隐式 env 契约。structured-output 包内同名常量为
+ * `ENV_SCHEMA = "PI_WORKFLOW_SCHEMA"`（见 extensions/universal/structured-output/src/index.ts）。
+ * 两包是独立 npm 包不能直接 import，故各自保留常量但显式标注此契约关系——
+ * 任一端改名必须同步另一端，否则权威 schema 注入会静默断桥（子进程不注册 tool/hook）。
+ */
+export const SCHEMA_ENV_VAR = "PI_WORKFLOW_SCHEMA";
+
+/**
+ * schema env 值的字节上限（256 KiB）：超过则注入前 fail-fast 拒绝。
+ *
+ * 背景（SO-DATA-4）：schema 经 childEnv 注入子进程，env 值随 spawn argv/env 块走
+ * execve 语义——单条 env 值过大叠加全量继承的 process.env 时可能触发 E2BIG
+ *（ARG_MAX 约束，Linux 通常 ~2MB 总上限，macOS 更紧），spawn 直接失败且错误难归因
+ *（E2BIG 报在 spawn 调用点，与 schema 内容无关的表象）。256KB 对 JSON Schema 是
+ * 宽裕上限（正常 schema 数 KB），提前拒绝把「难归因的 spawn 失败」变成
+ * 「注入点处含实际大小的明确报错」。
+ */
+/** 1 KiB 字节数（换算基数，SCHEMA_ENV_MAX_BYTES 组合用）。 */
+const BYTES_PER_KIB = 1024;
+/** 上限的 KiB 形态（256 KiB = 262144 bytes，注释与文档引用值）。 */
+const SCHEMA_ENV_MAX_KIB = 256;
+export const SCHEMA_ENV_MAX_BYTES = SCHEMA_ENV_MAX_KIB * BYTES_PER_KIB;
+
+/**
+ * 计算 schema env 值的 UTF-8 字节长度（注入大小 = 该值，用于超限判定与错误消息）。
+ */
+export function schemaEnvByteLength(schemaEnv: string): number {
+  return Buffer.byteLength(schemaEnv, "utf8");
+}

package/src/shared/schema-jsonify.ts

@@ -0,0 +1,58 @@
+/**
+ * Schema JSON 序列化缓存（IF7/#13，TC6/DM4）。
+ *
+ * 同一 schema 对象引用的重复 JSON.stringify 消除：resolver（compact，instruction
+ * 与 schemaEnv 复用同串，formatSchemaInstruction 现居 resolver）在单次 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)。
+ *   pretty 为预留模式，当前生产仅 compact 消费（resolver instruction 与 schemaEnv
+ *   复用同串；pretty 暂无生产调用方，仅供测试/未来调试通道）。
+ */
+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/timer-delay.ts

@@ -0,0 +1,54 @@
+/**
+ * setTimeout delay 安全域校验（Shared 层，无 Pi 依赖）。
+ *
+ * Node 的 setTimeout 对超出 32 位有符号整数上限（2^31-1 = 2147483647）的 delay
+ * 会把定时器置为 **1ms**（TimerOverflowWarning 路径，实测 setTimeout(fn, 3e9) 约
+ * 3ms 触发）——语义完全反转：调用方想表达的「近乎不限时」变成立即触发。对 watchdog
+ * / 预算计时器而言即「刚启动就误杀」。
+ *
+ * 本包三个 timer 挂载/解析入口（budgetTimeMs → lifecycle.scheduleTimeBudget、
+ * XYZ_SUBAGENT_SPAWN_WATCHDOG_MS → session-runner.resolveSpawnWatchdogMs、
+ * idleTimeoutMs → lifecycle-manager.armIdleTimer）统一在值流入 setTimeout 前调
+ * assertSafeTimerDelay fail-fast——不静默 clamp（clamp 把配置错误变成静默语义漂移，
+ * 比崩溃更难排查；用户应显式决定 clamp 到多少）。
+ *
+ * 层归属：Shared（orchestration 与 execution 共用，先例 schema-jsonify.ts）。
+ */
+
+/** Node setTimeout delay 的安全上限（2^31 - 1，超出的 delay 被置 1ms 立即触发）。 */
+export const MAX_TIMER_DELAY_MS = 2_147_483_647;
+
+/**
+ * 校验即将流入 setTimeout 的 delay 值在安全域内，越界 fail-fast。
+ *
+ * 错误信息含上限值与恢复指引（建议 clamp 后重试）——不静默 clamp：调用方须显式
+ * 决定 clamp 目标值（语义归属调用方，helper 不替用户做语义决定）。
+ *
+ * [F-3 NaN 穿透修复] 非有限数（Number.isFinite 为 false：NaN / ±Infinity）同样
+ * fail-fast——旧实现只挡 `> MAX`，NaN 的 `NaN > MAX` 为 false 静默放行，
+ * setTimeout(fn, NaN) 被 Node 塌缩为 1ms 立即触发（语义反转：watchdog 刚启动就误杀）。
+ * 错误消息区分「非有限值」与「超出上限」两种指引，恢复动作各自可达。
+ *
+ * @param ms 即将作为 setTimeout delay 的毫秒值（调用方保证已过 undefined/<=0 分流；
+ *   本函数只防溢出域与非有限值，0/负值的「禁用/不限」语义由各入口自行处理）
+ * @param source 值的来源标识（进错误信息，定位用，如 "budgetTimeMs" / env 名）
+ * @throws Error 当 ms 非有限（NaN/±Infinity）或超出 MAX_TIMER_DELAY_MS
+ */
+export function assertSafeTimerDelay(ms: number, source: string): void {
+  if (!Number.isFinite(ms)) {
+    throw new Error(
+      `[subagent-workflow] ${source} = ${ms} is not a finite number (NaN/±Infinity). ` +
+        "Non-finite delays collapse to 1ms in Node setTimeout and fire immediately. " +
+        "Recovery: fix the upstream computation that produced this value " +
+        "(e.g. guard division/parse results before passing them in) and retry.",
+    );
+  }
+  if (ms > MAX_TIMER_DELAY_MS) {
+    throw new Error(
+      `[subagent-workflow] ${source} = ${ms} exceeds the Node setTimeout limit ` +
+        `(${MAX_TIMER_DELAY_MS} ms = 2^31-1); larger delays silently collapse to 1ms and fire immediately. ` +
+        `Recovery: clamp the value to <= ${MAX_TIMER_DELAY_MS} (e.g. omit the option for "unlimited" ` +
+        `semantics, or clamp explicitly) and retry.`,
+    );
+  }
+}

package/src/shared/xml-injection.ts

@@ -0,0 +1,35 @@
+// 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

@@ -0,0 +1,81 @@
+# 内置通用编排 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

@@ -0,0 +1,40 @@
+// 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

@@ -0,0 +1,137 @@
+// 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 同模式）；
+// scriptPath 注入是 worker 契约的显式前提（D1 加固），缺席即 fail-fast，
+// 不回退 cwd——消除从用户目录误加载/被植入同名 _shared/agent-refs.cjs 的代码加载面。
+if (typeof workerData === "undefined" || !workerData || typeof workerData.scriptPath !== "string") {
+  throw new Error("chain: core_module_load_failed: workerData.scriptPath 缺失，无法定位 workflows/_shared/agent-refs.cjs。" +
+    "恢复动作：worker 宿主（WorkerHost）启动 worker 时必须经 workerData 注入 scriptPath" +
+    "（指向本脚本真实路径，注入点见 src/orchestration/worker-host.ts 的 workerData 组装处），" +
+    "禁止依赖 process.cwd() 巧合。");
+}
+const SCRIPT_DIR = require("path").dirname(workerData.scriptPath);
+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;