跳到主要内容

作用域与可见性

Agent Flow 的作用域是词法的、可静态判定的。一条链,从外到内:

workflow  ：input、context、use 别名(agent/team)
pipeline  ：(继承 workflow)+ 已完成 stage 的结果(按源序渐进可见)
stage     ：(继承 pipeline)+ 显式声明的依赖 stage 结果
block     ：if 的 then / else 体
map       ：parallel map 的循环变量
verify    ：check 名(仅 pass when 可见)

内层可见外层;同级互相不可见。

关键规则​

stage 体内:依赖是白名单​

stage 只能读取头部括号里声明过的 stage 结果:

stage a -> A { ... }
stage b -> B { ... }
stage c after a -> C {
  let x = a        // ✓ 声明了 a
  let y = b        // ✗ undeclared-dependency,即使 b 源序更早、已完成
  return x
}

这条规则让每个 stage 的输入集合写在签名里——review 一个 stage, 不用读完全文就知道它会碰哪些前置结果。

pipeline 层:源序渐进可见​

pipeline 层语句(含后续 stage 的依赖声明之外的普通 let/require/emit/if) 可以访问源序在前的任何 stage 结果:

stage summary after classify, drafts -> TriageSummary { ... }

if summary.urgent_count > 0 {          // pipeline 层直接用 stage 结果
  emit progress { attention: true }
}

let 绑定于当前作用域​

let 在当前作用域生效;在同一作用域内重名报 duplicate-variable。内层(if 块、map 体)里可以引用外层变量; 不同作用域(如 then / else 两个块)可以各自有同名 let。

input 与 context​

  • input:workflow 声明的入参,类型即 input 类型(可为外部类型); 运行时先按 Schema 校验,失败抛 WorkflowInputValidationError
  • context:宿主注入的只读 JSON。声明 context: ContextType 时， 成员访问和运行时输入都按 Schema 校验；省略声明时为 any

常见坑与对应诊断​

坑诊断码
stage 读了没声明的依赖undeclared-dependency
依赖了源序更晚的 stageforward-dependency
依赖的名字不存在unknown-stage
对象简写字段 { plan } 但没有叫 plan 的变量unknown-variable
同作用域 let 重名duplicate-variable
map 循环变量用了保留字(如 as task)直接语法错误

对象简写字段​

input {
  request: input
  plan                    // 等价于 plan: plan —— plan 必须是可见变量
}

简写是糖,前提是变量可见,否则 unknown-variable。

例子:一次作用域的完整旅行​

节选自 examples/data-report.flow:

stage profile -> DataProfile {
  require unique(input.columns[*].name)     // workflow 作用域的 input
    else fail "column names must be unique"
  let result = agent(analyst) { /*...*/ expect DataProfile }
  return result                              // stage 作用域的 let
}

stage charts after profile -> ChartSpec[] {       // 依赖 profile → 体内可见
  let specs = agent(analyst) {
    input { table: input, profile: profile } // input 与依赖都可用
    expect ChartSpec[]
  }
  return specs
}

stage report after profile, charts -> text {      // 多依赖
  let narrative = agent(analyst) {
    input { profile: profile, charts: charts }
    expect text
  }
  return narrative
}

return { profile: profile, charts: charts, summary: report }  // pipeline 层全可见

下一步​