让模型写脚本 编排一支 Agent 舰队

第一层是 meta 契约：脚本第一条语句必须是 export const meta = {...}，且 meta 的值由 evaluateLiteral 用纯 AST 求值——不是 eval。它只接受 ObjectExpression / ArrayExpression / Literal / 无插值 TemplateLiteral / 负数 UnaryExpression 五种节点，spread、computed key、方法、稀疏数组全部抛错；连 __proto__ / constructor / prototype 三个保留键名都显式封死，防原型污染。求值完成后，meta export 被从源码里切掉（script.slice(0, first.start) + script.slice(first.end)），剩下的才是要执行的脚本体。

case "ObjectExpression": {
  for (const prop of node.properties) {
    if (prop.type === "SpreadElement") throw new Error(`spread not allowed in ${path}`);
    if (prop.computed) throw new Error(`computed keys not allowed in ${path}`);
    const key = propertyKey(prop.key, path);
    if (key === "__proto__" || key === "constructor" || key === "prototype") {
      throw new Error(`reserved key name not allowed in ${path}: ${key}`);  // 防原型污染
    }
    out[key] = evaluateLiteral(prop.value, `${path}.${key}`);
  }
}
// staticStringOf 折叠 'no'+'w'，让 Date['no'+'w']() 也逃不掉确定性检查

第二层是确定性检查：assertDeterministicAst 递归遍历整棵 AST，命中 Date.now() / Math.random() / new Date() 即拒绝。有意思的是它对抗绕过的细节——staticStringOf（workflow.ts:357）会做静态字符串折叠，处理 BinaryExpression 的 +：左右操作数都能静态求出字符串时就拼接，所以 Date['no'+'w']()、Math[`random`]() 这类 computed member 写法同样被抓（git log 里专门有一个 "Fix determinism checks for prompt mentions" 的 PR #23 修过这块边界）。

const context = vm.createContext({
  agent, parallel, pipeline, log, phase,          // 编排原语
  args: options.args, budget,                      // 注入数据
  cwd: options.cwd ?? process.cwd(),
  process: Object.freeze({ cwd: () => options.cwd ?? process.cwd() }),  // 阉割版 process
  console: { log, info: log, warn, error },        // console → 工作流日志
  JSON, Math, Array, Object, String, Number, Boolean, Set, Map, Promise,
});
const wrapped = `(async () => {\n${body}\n})()`;
const result = await new vm.Script(wrapped, { filename: `${meta.name}.js` }).runInContext(context);
await Promise.allSettled([...pendingAgentRuns]);   // 不留孤儿 agent
assertStructuredCloneable(result, "workflow result"); // 抓"忘了 await"

process 被替换成 Object.freeze({ cwd: () => ... })——脚本能问"在哪个目录"，但拿不到 env、拿不到 exit。console.log 被重定向到 workflow 的 log()，模型习惯写的 console.log 也会变成进度条上的日志行而不是黑洞。

并发控制是一个 17 行的手写信号量 createLimiter：并发上限 min(max(1, hardwareConcurrency - 2), 16)，超出的 agent() 调用排队等 slot。token budget 则是个冻结对象 { total, spent(), remaining() }——每个 agent 跑完用 JSON.stringify(result).length / 4 粗估消耗记账，预算耗尽后下一次 agent() 直接 throw。这给 while (budget.remaining() > 50_000) {...} 这类 loop-until-budget 模式提供了硬护栏。

收尾有两个容易被忽略但很关键的动作：① await Promise.allSettled([...pendingAgentRuns])——脚本主体 return 了，但若有忘记 await 的 agent 还在跑，runtime 会等它们全部落地，不留孤儿 agent；② assertStructuredCloneable(result)——结果必须能 structuredClone，clone 失败时抛出的错误直接点名最常见病因："did you forget to await agent(), parallel(), or pipeline()?"。

agent() 内部 catch 到错误时写一行 agent <label> failed: ... 日志、回调 onAgentEnd(result: null)、返回 null——display 层据此把该 agent 标成 ✗。parallel() 对每个 thunk 单独 try/catch，pipeline() 对每个 item 的每个 stage 单独 try/catch，某个 item 在 stage 2 挂了只让这一条流水线变 null，其他 item 照常流过全部 stage。promptGuidelines 相应地教模型："Check for nulls before synthesizing conclusions."

const run = limiter(async () => {
  state.agentCount++;
  options.onAgentStart?.({ label, phase: assignedPhase, prompt: taskPrompt });
  try {
    const result = await agentRunner.run(taskPrompt, { label, schema, signal, instructions });
    state.spent += estimateTokens(result);          // JSON 长度 / 4 粗估记账
    return result;
  } catch (error) {
    if (options.signal?.aborted) throw error;       // abort → fail-hard，向上传播
    log(`agent ${label} failed: ${error.message}`); // 其他错误 → fail-soft
    options.onAgentEnd?.({ label, phase, result: null });
    return null;                                    // 失败 = null，不连坐
  }
});
pendingAgentRuns.add(run);  // 登记在册，收尾时 allSettled 兜底

parallel() 还有一个针对模型高频错误的防呆校验：传入数组里只要有一个元素不是函数（典型病例 parallel(items.map(item => agent(...)))，map 时 promise 已经全部起跑，限流器形同虚设），立刻抛带修复示例的 TypeError："parallel() expects an array of functions, not promises. Wrap each call: () => agent(...)"。pipeline 的 stage 回调签名是 (prev, originalItem, index)——后段 stage 不需要让前段刻意透传上下文，原始 item 永远在第二个参数里。

关键参数是 SessionManager.inMemory(cwd)——会话不落盘、不进历史列表、跑完即焚；工具集是 createCodingTools(cwd)，read/write/edit/bash 一应俱全，所以子 Agent 能像正常 Pi 一样读仓库、跑命令。abort 走标准 AbortSignal 链：父信号 addEventListener('abort') → session.abort()，finally 里必 session.dispose()。父子之间的通信带宽被压到最小：进去一段 prompt，出来一段文本或一个 schema 对象，子会话塞满的上下文不会污染父窗口——和 Claude Code subagent 的隔离哲学一致。

结构化输出是这个项目里性价比最高的 47 行（structured-output.ts）：传了 opts.schema 时，子会话被注入一个 structured_output 工具 + 四条"最终输出契约"指令。Pi 框架先按 JSON Schema 验参才会调 execute，所以参数即是已验证的返回值；execute 返回 terminate: true，子 Agent 在这次工具调用上直接终止——省掉一整轮 assistant 收尾回复的 token。如果子 Agent 跑完都没调 structured_output，则抛错（fail-soft 规则接手变 null）。没传 schema 时，返回值是从消息列表从后往前找的第一段非空 assistant 文本。

return defineTool({
  name: "structured_output",
  parameters: schema,                // Pi 先验参，参数即已验证的返回值
  async execute(_toolCallId, params) {
    capture.value = params;
    capture.called = true;
    return {
      content: [{ type: "text", text: "Structured output received." }],
      terminate: true,               // 子 Agent 就此收口，省一轮 assistant 回复
    };
  },
});

phase 在循环里动态创建、在条件分支里跳过，都是合法的——被跳过的分支不会留下一行空进度。agent 归组的优先级是 opts.phase ?? state.currentPhase：并发场景下（pipeline 的后段 stage 跑起来时全局 currentPhase 早就变了）用显式 opts.phase 避免归组错乱。渲染端（display.ts）按 phase 聚合出 done/running/errors/skipped 计数，每组最多显示 maxAgents 个，更早的折叠成 "… N earlier agents"，每行一个状态图标：○ queued ● running ✓ done ✗ error - skipped。

  ◆ Workflow: audit_repo (5/7 done, 2 running)
  ✓ Scan 2/2
    #1 ✓ repo inventory
    #2 ✓ entry points
  ▶ Review 3/5 · 2 running
    #3 ✓ src/workflow.ts review
    #4 ✓ src/agent.ts review
    #5 ✓ display review
    #6 ● tool definition review
    #7 ● tests review
    … 0 earlier agents

  log: 12 findings so far, deduping…

abort 路径在 workflow-tool.ts 里收尾得很整齐：捕获到 abort 后，把快照里所有 running 的 agent 翻成 skipped（error 字段标 "aborted"），重算计数，最后再渲染一次完成态——用户按下 Esc 看到的不是僵死的进度条，而是一棵明确标注了"谁被中断"的树。

它不造 Agent、不管模型、不碰记忆，只回答一个问题——"当模型决定要 fan-out 时，让它用什么语言表达编排逻辑？" 答案是：用真正的编程语言（JavaScript），配真正的解释器约束（AST 校验 + vm 沙箱），而不是又一层 YAML/JSON DSL。控制流是确定性的代码，智能在叶子节点的子 Agent 里——这个分工把"LLM 驱动的编排"（每一步都问模型下一步干嘛）换成了"模型一次性写出编排程序"，可审查、可测试（160 行 parser 单测覆盖接受/拒绝形状）、可复现。

它同时是一个值得注意的生态信号：Claude Code 在 2026 年发布 dynamic workflows 后，13 天内社区就在另一个开源 agent（Pi）上完成了高保真复刻并收获近 900 stars——头部 agent 的交互范式正在以周为单位向开源生态扩散，而 Pi 的扩展机制（registerTool + peerDependencies）让这种移植只需要 1100 行代码。