流程定义

流程定义是一个 JSON 对象，声明一个多阶段工作流：它的名字、它接受的参数、它该多激进地并行、它被允许花多少钱，以及构成其 DAG 的有序阶段数组。每个 taskflow —— 无论保存到磁盘还是作为一行内联传入 —— 都会先被反糖化为同一形状，再由运行时校验和执行。

你可能在想：这些字段我都得用吗？ 不用。结构上只有 phases 是必需的（保存的 flow 还要 name）。其余字段都是行为调参 —— 并发、成本上限、缓存默认值、严格度。本页按你实际会需要它们的顺序逐一介绍，详尽的参考材料放在最后。

快速心智模型

一个 flow 只是个容器。它装着元数据、几个执行调参，以及一个阶段列表。阶段干真正的活；容器决定它们怎么跑。

{
  "name": "my-flow",
  "phases": [
    { "id": "do", "type": "agent", "task": "...", "final": true }
  ]
}

下面的一切都是在这个形状上做加法。运行时在生成任何子代理之前先校验整个对象 —— 非法 flow 永远不会花你一个 token。

一个贯穿始终的示例

我们会逐步构建一个真实的 flow —— 审计一个目录的路由是否缺认证检查 —— 一块一块来。每一节加一个顶层字段并解释你为什么会需要它。完整的 flow 出现在本页末尾。

名字与描述

每个保存的 flow 都需要一个 name。它会成为 /tf:<name> 命令别名和运行状态目录名。description 是可选的，但值得加 —— 它会出现在 /tf list 和运行记录里。

{
  "name": "audit-auth",
  "description": "Audit routes for missing auth checks",
  "phases": [/* ... */]
}

声明你的参数：args

大多数可复用的 flow 都接受参数 —— 一个目录、一个严重程度阈值、一个 feature flag。在 args 里声明它们，运行时就能应用默认值并给它们做文档。每个 arg 是一个对象，带可选的 default、description 和建议性的 required 标志。

{
  "name": "audit",
  "args": {
    "dir": { "default": "src/routes", "description": "Directory to audit" },
    "force": { "default": false },
    "severity": { "default": "high", "required": true }
  },
  "phases": [/* ... */]
}

在调用时传参：

/tf run audit dir=src/api force=true

然后在任意阶段里用 {args.<name>} 插值：

{
  "id": "scan",
  "type": "agent",
  "task": "Scan {args.dir} for missing auth checks."
}

你可能在想：如果一个阶段引用了 {args.X}，但调用方没传 X 也没有默认值，会怎样？默认情况下占位符保持字面值，运行时发一条警告。在 strictInterpolation: true 下（见安全网），那条警告会变成硬错误 —— 对生产 flow 很有用，因为字面的 {args.X} 漏进 prompt 是个 bug，不是个意外。

控制并行度：concurrency

concurrency 是整个 flow 中同时跑多少个子代理的默认上限。默认值 8。map 和 parallel 阶段会继承它，除非它们设了自己的阶段级 concurrency。

{
  "name": "fanout",
  "concurrency": 16,
  "phases": [
    {
      "id": "scan",
      "type": "map",
      "over": "{steps.discover.json}",
      "task": "...",
      "concurrency": 4
    }
  ]
}

上面阶段级的 concurrency: 4 只对该阶段覆盖 flow 级的 16。

给成本封顶：budget

有些 flow 是开放式的 —— 一个深度调研 loop、一个有很多变体的 tournament。budget 让你设一个运行级的 USD 成本和/或 token 用量上限。任一超出时，剩余阶段被跳过，运行以 blocked 状态结束。

{
  "name": "capped-run",
  "budget": {
    "maxUSD": 2.0,
    "maxTokens": 2000000
  },
  "phases": [/* ... */]
}

agent 从哪来？agentScope

阶段按名字引用 agent（"agent": "security-reviewer"）。运行时在三种作用域之一里发现 agent 定义（带 YAML frontmatter 的 .md 文件）：

{
  "name": "team-flow",
  "agentScope": "both",
  "phases": [/* ... */]
}

当你有共享的用户级 agent、但想让某个项目覆盖其中几个时，用 "both"。

安全网：strictInterpolation

默认情况下，taskflow 对非致命问题是宽松的 —— 它警告并继续。打开 strictInterpolation 把这些警告提升为硬错误。对保存的、生产用的 flow 这是对的取舍：它能在一次运行浪费 token 之前抓住静默的占位符泄漏和过时字段引用。

{
  "name": "production-flow",
  "strictInterpolation": true,
  "phases": [/* ... */]
}

始终是硬错误的部分（与该标志无关）：

• {steps.X.*} 中 X 无法经 dependsOn/from 到达（阶段会和它的生产者并行跑，看到字面占位符）。
• 阶段引用自身输出（loop 阶段除外，它在 until 里合法地这样做）。
• 未知的 dependsOn / from 目标、依赖环、重复的阶段 id、多于一个 final: true。

仅在 strictInterpolation: true 下才变成硬错误的部分：

跨运行复用工作：incremental

默认情况下，每次运行都从零开始 —— 每个阶段都重新执行，哪怕什么都没变。设 incremental: true 把每个阶段默认为跨运行缓存（cache.scope: "cross-run"），这样重新跑 flow 时会跨运行和跨会话复用未变阶段的结果。

{
  "name": "ci-audit",
  "incremental": true,
  "phases": [
    { "id": "lint", "type": "script", "run": "npm run lint" },
    { "id": "review", "type": "agent", "task": "Review recent changes." }
  ]
}

关于 incremental 与阶段级设置如何交互，有几条规则：

• 它等价于在每个阶段上设 cache: { scope: "cross-run" }。
• 阶段自己的 cache 设置优先 —— cache.scope: "off" 或 "run-only" 仍被尊重。
• 被跨运行阻止的阶段类型（gate、approval、loop、tournament、script）即使在 incremental 下也永不跨运行缓存 —— 它们每次运行都必须产出新结果。在上面的例子里，lint 尽管 incremental 仍每次调用都重跑；review 会被缓存。
• idempotent: false 的阶段完全排除在缓存之外。在 incremental 下这会产生一条警告，让你知道该阶段不会被复用。

在阶段间共享上下文：contextSharing

当多个阶段读同样的文件时，你可以用一个标志把它们统统纳入共享上下文树。contextSharing: true 是在每个阶段上设 shareContext: true 的简写 —— 每个阶段的子代理会得到 ctx_read/ctx_write（一个与兄弟和祖先共享的 blackboard）以及 ctx_report/ctx_spawn（向上汇报 + 排队子任务）。个别阶段仍可用 shareContext: false 退出。

{
  "name": "collab-flow",
  "contextSharing": true,
  "phases": [
    { "id": "explore", "type": "agent", "task": "..." },
    { "id": "synthesize", "type": "agent", "task": "...", "dependsOn": ["explore"] }
  ]
}

phases 数组

phases 是唯一必需的字段 —— 一个有序的阶段定义数组（minItems: 1）。每个阶段有唯一 id、一个 type（默认 "agent"），并通过 dependsOn 构成 DAG 边。没有依赖的阶段在第一拓扑层运行。

运行时通过 Kahn 算法计算拓扑层：同层阶段并发运行（至多 concurrency 个）。一个阶段在它所有 dependsOn 完成后启动 —— 或在 join: "any" 下任一完成后启动。

每种阶段类型的每个字段，见阶段类型页。

简写：简单工作跳过 DAG

对一次性委派，你不需要写一个完整的 phases DAG。taskflow 接受三种简写形状，运行时的 desugar() 会在校验前把它们展开成完整 flow。当一个 spec 没有 phases 数组、但有 task、tasks 或 chain 之一时，它被识别为简写。

单个任务

{ "task": "Summarize src/", "agent": "explorer" }

反糖化为一个 agent 阶段（id "main"、final: true）。可选的 agent、context、contextLimit 会透传。

并行任务

{
  "tasks": [
    { "task": "Audit auth in src/api", "agent": "analyst" },
    { "task": "Audit validation in src/api", "agent": "analyst" }
  ]
}

反糖化为一个 parallel 阶段（id "parallel"、final: true）。context 在所有分支间共享：spec 级 context 加上各步 context 数组的并集会被合并、只读一次。

顺序链

{
  "chain": [
    { "task": "Find all TODO comments" },
    { "task": "Summarize them: {previous.output}" },
    { "task": "Open issues for: {previous.output}" }
  ]
}

反糖化为顺序的 agent 阶段（step1、step2、……），每个依赖前一个；最后一个是 final: true。每一步用 {previous.output} 引用上一步的输出。

简写透传什么

三种形式都会把这些可选的顶层字段透传到反糖化后的 flow：name（默认为 "task"、"parallel" 或 "chain"）、description、concurrency、agentScope、args、budget、strictInterpolation。

完整示例

这是把我们讨论过的所有内容都用上的 audit-auth flow：

{
  "name": "audit-auth",
  "description": "Audit routes for missing auth checks",
  "version": 2,
  "args": {
    "dir": { "default": "src/routes", "description": "Directory to audit" },
    "severity": { "default": "high", "required": true }
  },
  "concurrency": 8,
  "agentScope": "both",
  "strictInterpolation": true,
  "incremental": false,
  "budget": {
    "maxUSD": 2.0,
    "maxTokens": 2000000
  },
  "phases": [
    {
      "id": "discover",
      "type": "agent",
      "agent": "scout",
      "task": "List every route handler in {args.dir} as JSON.",
      "output": "json"
    },
    {
      "id": "audit-each",
      "type": "map",
      "over": "{steps.discover.json}",
      "as": "route",
      "agent": "security-reviewer",
      "task": "Does {route.path} require auth? Output {\"ok\": true|false}.",
      "output": "json",
      "dependsOn": ["discover"]
    },
    {
      "id": "report",
      "type": "reduce",
      "from": ["audit-each"],
      "agent": "writer",
      "task": "Summarize the audit results: {steps.audit-each.output}",
      "final": true,
      "dependsOn": ["audit-each"]
    }
  ]
}

字段参考

本页剩下的是详尽参考 —— 每个顶层字段、ArgSpec 形状，以及完整的校验表。需要精确答案时来查。

顶层字段

ArgSpec

args 中的每个条目是一个带这些字段的对象：

校验行为

每个 flow 在执行前都会被校验，有两种模式：

1. 静态（/tf verify，无运行时参数）：仅结构检查 —— schema 形状、DAG 完整性、环检测、{steps.X} 引用的可达性。零 token。
2. 运行时（运行启动时，带已解析的参数）：以上全部，外加参数缺失警告和 cwd/codebase 不匹配警告。

硬错误（始终让运行失败）

警告（在 strictInterpolation 下提升为错误）

isShorthand 识别

当一个 spec 没有 phases 数组、且至少满足下列之一时，被当作简写处理：

• chain 是非空数组
• tasks 是非空数组
• task 是字符串

否则它作为完整 flow 按 TaskflowSchema 校验。

下一步

Last updated on