跳到主要内容

作用域与可见性

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 -> C {
  let x = a        // ✓ a 已经完成
  let y = b        // ✓ b 已经完成
  return x
}

后续 stage 尚未进入作用域，读取后续或不存在的名字会报 unknown-variable。

pipeline 层:源序渐进可见​

pipeline 层语句(普通 let/require/emit/if) 可以访问源序在前的任何 stage 结果:

stage summary -> 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 读取了后续或不存在的结果unknown-variable
对象简写字段 { 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 -> ChartSpec[] {                     // 此前的 profile 可见
  let specs = agent(analyst) {
    input { table: input, profile: profile } // input 与此前 stage 结果都可用
    expect ChartSpec[]
  }
  return specs
}

stage report -> text {                            // 此前的 profile、charts 可见
  let narrative = agent(analyst) {
    input { profile: profile, charts: charts }
    expect text
  }
  return narrative
}

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

下一步​