插值

阶段的 task、when、until、context 和 script 的 input 都是模板。{花括号} 中的任何内容都会在阶段运行之前于运行时被解析，解析依据是上游阶段产出的数据、调用参数和循环状态。本页展示如何在阶段之间接线数据 —— 以及当占位符无法解析时运行时会怎么做。

场景：把文件列表从一个阶段传给下一个

想象你想让一个 agent 发现变更的文件，让第二个 agent 审查它们。第二个阶段需要第一个阶段产出的列表。下面是最小版本：

{
  "phases": [
    { "id": "discover", "task": "List changed source files. Output a JSON array of {path}." },
    {
      "id": "review",
      "dependsOn": ["discover"],
      "task": "Review these files for risks:\n{steps.discover.output}"
    }
  ]
}

{steps.discover.output} 是一个占位符。在 review 运行之前，运行时用 discover 产出的原始文本替换它。dependsOn 是让这一切安全的原因 —— 它保证 discover 在 review 的 task 被插值之前已完成，也正是它让 /tf verify 能确认该引用是可达的。

这是核心心智模型：占位符从上游阶段拉取数据，dependsOn 保证顺序。 本页其余部分讲其他占位符家族、JSON 提取策略、条件语言以及失败模式。

占位符家族

有六个占位符家族，各自从不同来源拉取。

让我们逐个 walkthrough。

{args.X} —— 调用参数

参数在流程定义中声明并带默认值，用 {args.X} 引用：

{
  "args": {
    "dir": { "default": "src" },
    "force": { "default": false }
  },
  "phases": [
    { "id": "list", "task": "List files under {args.dir}." }
  ]
}

下降是深度的：{args.user.id} 遍历 args.user.id，并在任意环节缺失时优雅地返回 undefined。

{steps.ID.output} —— 先前文本输出

子代理作为最终输出产出的原始字符串。ID 必须是当前阶段经由 dependsOn（或 from）可达的传递祖先；否则验证会以硬错误失败。

{
  "phases": [
    { "id": "name-gen", "task": "Generate a project name." },
    {
      "id": "scaffold",
      "task": "Create a directory named {steps.name-gen.output} and init it.",
      "dependsOn": ["name-gen"]
    }
  ]
}

该值原样插入 —— 不引用、不重新序列化。output 之后的尾随路径段（如 {steps.a.output.foo}）不被允许：output 是字符串，不是对象。如果你要字段，用 .json。

{steps.ID.json} —— 解析 JSON

解析先前阶段的输出并返回结果。如果解析值是对象或数组，插入前用 JSON.stringify(value, null, 2) 美化打印；如果是原始值，直接插入。

{
  "phases": [
    { "id": "triage", "output": "json", "task": "Classify severity. Output only JSON." },
    {
      "id": "deep",
      "when": "{steps.triage.json.severity} == high",
      "task": "Deep-dive. Context: {steps.triage.json}",
      "dependsOn": ["triage"]
    }
  ]
}

{steps.ID.json.field} 下降进入解析后的对象。在浅数据上的深路径解析为 undefined（一个 missing 警告），永不抛错 —— 因此在 {"severity": "high"} 上取 {steps.triage.json.severity.label} 会软失败。

{previous.output} —— 紧接上游

解析为最后完成的依赖的输出，按逆序扫描 dependsOn ∪ from，返回第一个状态为 done 的阶段。

这个占位符正是简写 chain 能工作的原因 —— 每一步得到上一步的输出而无需命名它。

{item} —— 当前 map 元素

在 map 阶段内部，每个分支将当前数组元素作为一个 local 接收。该 local 的名称是 phase.as（默认 "item"）。下降可用，因此 {item.path}、{item.meta.title} 以及裸 {item} 都能用。

{
  "id": "audit",
  "type": "map",
  "over": "{steps.discover.json}",
  "as": "file",
  "task": "Audit {file.path}.",
  "concurrency": 8
}

自定义名称（上面的 as: "file"）完全替换 item —— 在该阶段中 {item} 将无法解析。当数组中的对象在概念上不是"items"（文件、路由、发现）时，使用自定义名称。over 必须是插值引用（如 "{steps.scan.json}"），不能是字面数组 —— 验证会拒绝字面数组，并要求你先从上游阶段产出它。

{loop.X} 与 {reflexion} —— 循环状态

loop 阶段将一个 loop 对象绑定到上下文，在 body 的 task 和 until 条件中可用。

{
  "id": "refine",
  "type": "loop",
  "maxIterations": 4,
  "until": "{loop.iteration} >= 3",
  "task": "Iteration {loop.iteration}/{loop.maxIterations}. Previous draft: {loop.lastOutput}"
}

{reflexion} 是一个裸占位符（无子路径），仅可用于带 reflexion: true 的 loop 阶段。第 1 次迭代时它解析为一个哨兵值；后续迭代中它携带上一次迭代的结构化失败摘要 —— 输出片段、expect 契约诊断、错误文本，或未满足的 until 条件。

{
  "id": "fix",
  "type": "loop",
  "reflexion": true,
  "maxIterations": 3,
  "until": "{steps.fix.json.passed} == true",
  "output": "json",
  "task": "Fix the failing test. {reflexion}"
}

处理 JSON

LLM 很少产出干净的 JSON。它们把它裹在正文里、用代码围栏围起来，偶尔还附加杂散键。taskflow 的 safeParse 是为这种现实设计的多阶段恢复流水线。每个 {steps.ID.json} 占位符、每个 map.over、每个 gate 评分器 target 都流经它。

四个阶段

{"severity": "high", "reason": "missing auth check"}

Here is the analysis:

```typescript
const x = compute();
```

```json
{"severity": "high", "reason": "..."}
```

[
  {"id": "D-001", "status": "open"}
],
"deferred": [
  {"id": "D-002", "status": "deferred"}
]

如果每个阶段都失败，safeParse 返回 undefined —— 于是 {steps.ID.json} 成为 missing 警告，{steps.ID.json.field} 解析为 undefined。

为 map.over 强制数组

map.over 和 gate 评分器 target 需要数组。当解析值不是数组时，coerceArray 查找一个便利的包裹键，顺序固定：

第一个匹配的数组胜出。因此一个产出 {"results": [...]} 的模型无论你要的是数组还是包裹器都能工作 —— 在模型包裹以添加元数据时很有用。

条件

when（在任何阶段上）和 until（在 loop 上）接受一种微型的、安全的布尔表达式语言 —— 无 eval / Function，一个手写的递归下降解析器。Gate 的 eval 前置条件使用相同的语言外加 contains 操作符。

完整的运算符表、优先级、比较语义和真值规则文档在控制流页。这里我们只讲与插值相关的部分：操作数如何被解析。

这种拆分是有意为之：比较需要类型化的值（5 > 3 是数值，"high" == "high" 是字符串），而 task 模板需要可读文本。同一占位符语法服务于两者，但按上下文有不同的解析规则。

Gate contains

Gate 的 eval 前置条件增加了一个 when / until 中没有的操作符：

{
  "id": "lint-gate",
  "type": "gate",
  "eval": ["{steps.lint.output} contains no errors"],
  "task": "..."
}

contains 在分词之前被预处理：左侧被插值为字符串，右侧为字面字符串，然后执行子串检查。这是基于正文输出做门控的惯用法（{steps.lint.output} contains no errors）。在 gate 前置条件之外，contains 不被识别。

Fail-open 与循环例外

when 表达式中的解析错误会设置 error，且表达式求值为 true —— 一个破损的守卫永远不会静默丢弃阶段。错误会在运行记录中呈现。

对于 loop.until，解析错误会停止循环（fail-safe）—— 继续下去会有无限循环的风险。

失败模式

无法解析的占位符绝不是静默丢弃。运行时显式处理每种失败模式。

缺失占位符

当 resolvePath 返回 undefined 时，占位符在输出字符串中保持原样，其路径被推入 missing[]。运行时随后：

阶段仍然运行 —— 模型看到字面的 {steps.x.output} 文本，这通常足以在运行记录中暴露 bug。这就是 fail-open 保证：一个拼写错误永远不会静默丢弃阶段。

转义字面花括号

没有转义序列（\{ 没有特殊含义）。相反，占位符正则的严格字符集提供了隐式转义：任何 {...} 只要内容包含空格、引号、标点或 [a-zA-Z0-9_-] 之外的字符，就根本不是占位符，会原样透传。

验证

静态验证（/tf verify）在任何 agent 运行之前检查每个字符串字段中的占位符引用，并对照 DAG 校验。

硬错误

传递祖先检查使用 对 dependsOn ∪ from 的 BFS：若 C 依赖 B 而 B 依赖 A，C 可以引用 {steps.A.*}。带 join: "any" 的阶段被豁免 —— 它们只需一个依赖完成，可作为信息性上下文引用其他阶段。

警告

严格模式

{
  "name": "ci-gated",
  "strictInterpolation": true,
  "args": { "spec": { "default": "SPEC.md" } },
  "phases": [ /* ... */ ]
}

设 strictInterpolation: true 时，所有警告都成为硬错误 —— 在 CI 中捕获任何漂移很有用。strict 也可按验证调用传入（opts.strict），为一次性检查覆盖 flow 的标志。

解析规则（参考）

所有占位符都流经 resolvePath → _resolvePath → dig。这是详尽参考；日常编写用占位符家族的表就够了。

dig —— 下降原语

dig 按一串属性键遍历对象。它永不抛错。在浅数据末端走偏、下降中途命中原始值、或引用缺失的键，都会返回 undefined。

dig(obj, ["a", "b", "c"]):
  cur = obj
  for each part:
    if cur is null/undefined → return undefined
    if cur is not an object → return undefined
    cur = cur[part]
  return cur

这使得像 {steps.scan.json.results.0.id} 这样深层嵌套的占位符即使在数据比预期浅时也是安全的。

字符串化

当占位符解析为非 undefined 值时，在拼入模板前会被字符串化：

按 head 的解析顺序

占位符语法（正则）

占位符由如下正则匹配：

\{([a-zA-Z0-9_-]+(?:\.[a-zA-Z0-9_-]+)*)\}

一个 {，随后是若干由点号分隔的路径段（每段由字母 / 数字 / 连字符 / 下划线组成），最后是一个 }。第一段是 head（占位符家族）；其余是下降路径。

后果：

• {steps.audit-each.output} ✓ —— id 中允许连字符，与命名约定一致。
• { args.x } ✗ —— 花括号内的前导/尾随空格不会被匹配器剥除；head 会变成 args，解析失败。（条件操作数会 trim；任务占位符不会。）
• {"key": "value"}、{a b}、{$special} ✗ —— 这些包含了 [a-zA-Z0-9_-] 之外的字符，因此它们根本不是占位符，会原样透传。

观察到的 readSet

每个成功解析的占位符都会触发 onRead 钩子（除非未设置）。未解析的引用不会触发它。运行时借此记录一个阶段实际消费了哪些上游阶段 —— 即其观察到的 readSet —— 这与它声明的 dependsOn 不同。一个阶段可能依赖三个阶段却只读取一个，运行记录会反映真相。

下一步

Last updated on