顶层结构与管道

一个 .flow 文件必须包含至少一个 workflow。本页讲一个 workflow 的骨架: 声明、资源、限制、类型、管道与阶段。

workflow 声明

workflow deliver_change(input: ChangeRequest) -> Delivery {
  // use / limits / type / pipeline,顺序任意
  pipeline delivery {
    return { changes: [], review: { approved: true } }
  }
}

形参必须命名为 input,且只有一个(错误码 workflow-param-name)
输出类型在 -> 之后:编译期检查 pipeline 返回值(workflow-return-mismatch), 运行时再按 Schema 校验一次
limits 与 pipeline 至多各一个;pipeline 必须存在

use:声明资源

use team "engineering-team" as engineering
use agent "secure-code-reviewer" as security

use 只声明逻辑资源——字符串是资源 id,不指向任何具体产品。真正的解析发生在运行时(AgentRuntime.resolveAgent/resolveTeam), 别名在 workflow 作用域内唯一。

limits:预算与上限

limits {
  concurrency: 4     // 并发 agent 调用上限(正整数)
  agent_runs: 12     // 整个 workflow 的 agent 调用总次数上限
  duration: 30m      // 墙钟时长上限(时长字面量)
}

三个字段均可选;最终生效值为 host 策略 ∩ workflow limits 的较小者。 agent_runs 超限抛 LimitExceededError,duration 超限抛 WorkflowTimeoutError。

type:结构化类型

type WorkItem {
  id: text
  owner: member<engineering>
  writes: path[]
  acceptance: text[]
}

type Plan {
  summary: text
  work: WorkItem[1..6]    // 数组,最少 1 个最多 6 个
}

类型声明顺序任意、允许前向引用,但不允许递归。详细规则见类型系统。

pipeline 与 stage

pipeline 是语句的容器;stage 是具名的阶段,名字即结果变量:

pipeline delivery {

  stage plan -> Plan {
    let result = agent(engineering.main) { /* ... */ expect Plan }
    require result.work.count in 1..6 else fail "..."
    return result
  }

  //      ↓ 显式依赖声明
  stage execute after plan -> ChangeResult[] {
    // plan 在这里可见
    return parallel map plan.work as item { /* ... */ }
  }

  stage review after execute -> ReviewResult { /* ... */ }

  return { changes: execute, review: review }   // 最后一句话必须是 return
}

依赖的三条规则

规则	错误码
依赖的 stage 必须已声明	`unknown-stage`
依赖必须源序在前(不能前向依赖)	`forward-dependency`
stage 体内只能读取已声明依赖的结果——即使某个更早的 stage 已经完成	`undeclared-dependency`

依赖是白名单:声明了 stage execute after plan,体内就只能看 plan, 看不见 review。这让每个 stage 的输入集合在源码上完全可审计。

return 的位置规则

pipeline 的最后一个语句必须是 return(missing-return), 且 return 只能出现在末尾(pipeline-return-position)
stage 同理(stage-return-missing)
stage 返回值必须可赋值到声明的 -> TypeRef(stage-return-mismatch)

V1 按源序执行 stage;依赖元数据进入 Flow IR(StageIR.dependencies), 供未来的 DAG 调度器使用——写代码时把依赖声明全,就是在为调度器留信息。

pipeline / stage 内的语句

语句	文法	约束
`let`	`let name = 表达式`	绑定当前作用域变量,同名重复报 `duplicate-variable`
`require`	`require 布尔 else fail "原因"`	条件必须 bool;失败抛 `WorkflowAssertionError`
`emit`	`emit progress { ... }`	只支持 progress 事件,载荷为对象字面量
`if`	`if 布尔 { ... } else { ... }`	条件必须 bool;then/else 各自成块作用域
`return`	`return 表达式`	位置见上

注意 stage 内不能嵌套 stage;pipeline 内不能写 agent 调用以外的裸表达式。

模式:if 分支 + 兜底 return

stage 内需要"条件提前返回"时,用 if 内 return + 末尾兜底:

stage route after audit -> text {
  if audit.needs_manual_review {
    return agent(approver) { task "..." expect text }
  } else {
    emit progress { decision: "direct" }
  }
  return agent(preparer) { task "..." expect text }   // 兜底
}

下一步

类型系统 —— type、数组界、member、可赋值性
agent() 调用 —— 唯一的非确定点

workflow 声明​

use:声明资源​

limits:预算与上限​

type:结构化类型​

pipeline 与 stage​

依赖的三条规则​

return 的位置规则​

pipeline / stage 内的语句​

模式:if 分支 + 兜底 return​

下一步​