控制流

taskflow 的 DAG 是静态拓扑 —— 边在定义时就固定了。但真实的工作流需要动态行为：当严重程度低时跳过某个阶段，当第一次尝试失败时切换到回退，对一个不稳定的模型重试，或对未通过质量门的输出进行返工。本页的字段在拓扑之上添加这一动态层。

场景：带条件深度的 PR 审查

想象你在构建一个代码审查 flow。并非每个 PR 都需要相同的处理。一个小型文档调整只需快速摘要；而一个高严重程度的变更应触发深度审计。下面这个 flow 根据分诊决策分支：

{
  "name": "conditional-review",
  "phases": [
    {
      "id": "triage",
      "type": "agent",
      "output": "json",
      "task": "Classify the PR. Output JSON {severity, reason}."
    },
    {
      "id": "deep-audit",
      "when": "{steps.triage.json.severity} == high",
      "dependsOn": ["triage"],
      "agent": "risk-reviewer",
      "task": "Deep-dive the change. Reason: {steps.triage.json.reason}"
    },
    {
      "id": "quick-summary",
      "when": "{steps.triage.json.severity} != high",
      "dependsOn": ["triage"],
      "task": "Write a one-paragraph summary."
    }
  ]
}

每个分支上的 when 字段就是守卫。当分诊解析为 severity: "high" 时，deep-audit 分支运行而 quick-summary 被跳过 —— 不花费 token、不生成子代理。低严重程度的 PR 则相反。

when 是本指南的第一个工具。本页其余部分 walkthrough 六个字段，它们合起来让你能表达几乎所有运行时决策：

when：有条件地跳过阶段

when 表达式是一种微型、安全的布尔语言，在阶段运行之前求值。若为真，阶段运行；若为假，阶段被跳过：无子代理调用、无 token，运行记录显示 status: "skipped"。

最简单的守卫将一个 JSON 字段与字面量比较：

{
  "id": "deep",
  "when": "{steps.triage.json.severity} == high",
  "dependsOn": ["triage"]
}

可以用 &&、|| 和 ! 组合守卫：

{
  "id": "deep",
  "when": "({steps.triage.json.severity} == high || {steps.triage.json.severity} == critical) && !{steps.triage.json.suppressed}",
  "dependsOn": ["triage"]
}

裸占位符也是守卫

如果上游阶段产出的是一个布尔值，或一个你信任其真值性的 JSON 字段，你可以完全省略运算符：

{
  "id": "b",
  "when": "{steps.triage.json.hasFindings}",
  "task": "..."
}

常见模式

Fail-open：破损的守卫永不丢弃阶段

错误会出现在阶段的 warnings 和运行记录中，便于你发现和修复。空或全空白的 when（视为 true）以及未解析的占位符也是如此 —— 一个未解析的 {steps.missing.json} 解析为 undefined（为假），但表达式仍正常解析和求值。

完整的运算符表、优先级、比较语义和解析错误见本页末尾的条件参考。

join：阶段如何等待其依赖

默认情况下，一个阶段等待每个声明的依赖完成（join: "all"）。这是正确的默认值 —— 大多数阶段确实需要其全部输入。

但回到上面的条件审查 flow。deep-audit / quick-summary 恰好运行一个；另一个被跳过。如果下游阶段依赖两者，它会永远挂起等待被跳过的分支。join: "any" 就是解法：

{
  "id": "merge",
  "type": "reduce",
  "from": ["deep-audit", "quick-summary"],
  "join": "any",
  "dependsOn": ["deep-audit", "quick-summary"],
  "task": "Combine the surviving branch's output into one report."
}

有了 join: "any"，merge 阶段在任一依赖完成后即继续，而不是等待全部。

If / else 路由

将 when 守卫与 merge 阶段上的 join: "any" 组合，是表达 if/else 分支的惯用法：

[
  { "id": "triage", "type": "agent", "output": "json", "task": "Classify severity." },
  { "id": "deep",   "when": "{steps.triage.json.severity} == high", "dependsOn": ["triage"], "task": "Deep analysis." },
  { "id": "quick",  "when": "{steps.triage.json.severity} != high", "dependsOn": ["triage"], "task": "Quick summary." },
  { "id": "merge",  "type": "reduce", "from": ["deep", "quick"], "join": "any", "dependsOn": ["deep", "quick"] }
]

deep / quick 恰好运行一个；merge 在存活分支完成后即继续。

何谓"满足"

一个依赖若以 done 结束，或以 failed 结束且被标记为 optional（见 optional），则视为满足。被跳过或非 optional 失败的依赖不满足。

optional：容忍失败

有些工作是尽力而为的。一个 lint 脚本可能失败；一个第三方丰富化调用可能 503。你并不总是想让那中止整个运行。

{
  "id": "lint",
  "type": "script",
  "run": "npm run lint",
  "optional": true
}

失败的非 optional 阶段将运行状态设为 failed 并级联：dependsOn 含其的下游阶段被跳过（除非它们 join: "any" 或该依赖本身 optional）。失败的 optional 阶段被容忍 —— 运行继续，且该阶段对 join 而言仍算"满足"的依赖（"all" 和 "any" 均如此）。

与回退阶段配对

optional + when 一起构建带回退的尽力阶段：

[
  {
    "id": "enrich",
    "type": "agent",
    "optional": true,
    "task": "Call the external API and enrich the record. May fail."
  },
  {
    "id": "fallback",
    "when": "{steps.enrich.output} == \"[previous phase failed]\"",
    "dependsOn": ["enrich"],
    "task": "Produce a minimal record without enrichment."
  }
]

当 enrich 失败时，其 {steps.enrich.output} 解析为哨兵 "[previous phase failed]"，使下游引用不致中断 —— 而 fallback 阶段的 when 守卫恰好捕获那种情况。

retry：失败时重试

LLM 提供方会打嗝。速率限制、5xx 和超时是家常便饭。taskflow 分两层处理。

第一层：隐式瞬态自动重试

即使没有显式 retry 块，瞬态提供方错误也会被自动重试，这样一次短暂的 429 会在运行内被吸收，而不是冒泡上去、促使调用方 agent 重新调用整个工具（那会堆叠重复的进度块）。

若失败信息匹配 rate limit、too many requests、overloaded、429、502、503、504、service unavailable、temporarily unavailable、timeout、timed out、ECONNRESET、ETIMEDOUT 或 socket hang up（大小写不敏感），则视为瞬态。确定性失败 —— 显式中止、空闲超时、阶段超时、契约违反 —— 不被重试。

第二层：显式逐阶段重试

当你想控制曲线，或也想对硬失败重试时，加一个显式 retry：

{
  "id": "generate",
  "retry": { "max": 5, "backoffMs": 1000, "factor": 2 },
  "task": "..."
}

第 N 次尝试（0 起始）前的延迟：min(60000, round(backoffMs * factor ** attempt))。

两层如何组合

两种策略组合，而非替换：

• 显式策略覆盖所有失败（瞬态和硬）至 retry.max。
• 瞬态回退仅覆盖瞬态错误，至多 3 次尝试，且仅当 idempotent !== false。
• 总尝试预算为 max(explicitMax, 1 + 3)。
• 退避曲线： 若阶段定义了显式 retry.backoffMs，该曲线用于显式和瞬态重试（用 backoffMs: 0 可让测试快速）。否则用瞬态默认（2000 ms，factor 2）。

idempotent：分类副作用

有些阶段绝不能重复。一次部署、一个 webhook POST、一次 DB 迁移 —— 在瞬态 429 上重跑这些正是作者想要防止的危害。设 idempotent: false 声明"此阶段有不可逆副作用"：

{
  "id": "deploy",
  "type": "agent",
  "idempotent": false,
  "task": "Run the production deploy. This must not be repeated on transient errors.",
  "retry": { "max": 0 }
}

idempotent: false 做什么

它不做的事

• 它不抑制显式 retry: {}。显式策略是作者声明重复可接受。要禁止所有重试，还需设 retry: { max: 0 }。
• 它不改变 optional 语义。有副作用的阶段仍可 optional: true。

验证交互

何时设置

对任何重执行不安全的阶段设 idempotent: false —— webhook POST、邮件/通知发送、部署、迁移、DB 写入，任何每次调用都收费或变更外部状态的调用。对只读分析、生成和变换阶段保持 true（默认）—— 它们受益于瞬态重试和缓存。

onBlock：自愈合 gate

一个 gate 阶段可以发出 VERDICT: BLOCK 来中止 flow。但有时你不想中止 —— 你想让 gate 强制返工并再试一次。这正是 onBlock: "retry" 做的：

[
  {
    "id": "implement",
    "type": "agent",
    "task": "Implement the feature."
  },
  {
    "id": "quality",
    "type": "gate",
    "onBlock": "retry",
    "retry": { "max": 3 },
    "dependsOn": ["implement"],
    "task": "Does this satisfy all criteria? Output VERDICT: PASS or VERDICT: BLOCK with reasons."
  }
]

每轮 BLOCK：

防止失控循环的守卫

评分 gate（score）工作方式相同 —— 循环重跑上游依赖并针对新输出重新评分，共享深度上限和预算/中止守卫。

条件参考

when 表达式语言是一种微型、安全的布尔语法 —— 无 eval / Function，一个手写的递归下降解析器。本节是详尽参考；日常使用上面常见模式的表就够了。

运算符与优先级

从最松到最紧绑定：

比较是非结合的：a == b == c 是解析错误（trailing tokens）。用显式 && 链式：(a == b) && (b == c)。

比较语义：数值 vs 字符串

==、!=、<、>、<=、>= 按操作数类型分派：

• 若两个操作数都是数值（JSON number，或可解析为有限数的字符串），比较为数值：1.5 == "1.5" → true；"10" > "9" → true。
• 否则，两个操作数被强制为字符串（null / undefined → ""）并按字典序比较："high" == "high" → true；"9" > "10" → false。

这意味着将一个解析为数字的占位符与 high 这样的裸词比较时，始终是字符串比较 —— 这正是你对枚举类字段的期望。

操作数

真值性

一个裸操作数（无比较运算符）按真值性求值：

字符串转义

单引号和双引号都接受。反斜杠按字面转义下一个字符（\" → "，\\ → \）。所有其他 \X 序列变为字面 X —— \n 变成两个字符 n，不是换行。这不同于 JSON/JS 转义，但对条件字符串是正确的 —— 它们只需引号转义。

{
  "id": "d",
  "when": "{steps.x.json.label} == \"high-priority\"",
  "task": "..."
}

裸词 true / false / null 是关键字，不是字符串。要与字面字符串 "true" 比较，请加引号：{steps.x.json.flag} == "true"。

常见解析错误

下一步

Last updated on