跳到主要内容

包与架构

Agent Flow 是 pnpm monorepo,五个包各司其职,沿编译链排布:

.flow 源码
  │
  ▼
@dynamic-workflow/lang     Langium 文法 + 解析(词法/语法 → AST)
  │
  ▼
@dynamic-workflow/compiler     语义检查 + 类型检查 → Flow IR → 代码生成(受限 JS)
  │
  ▼
@dynamic-workflow/sandbox      子进程 + isolated-vm,装载并执行编译产物
  │
  ▼
@dynamic-workflow/runtime      Runtime 语义:事件、AgentRuntime 适配、FakeAgentRuntime
  │
  ▼
@dynamic-workflow/cli          flow check / compile / run 命令行

包清单​

包职责关键文件
@dynamic-workflow/lang文法定义与解析器(Langium)src/language/agent-flow.langium
@dynamic-workflow/compilercheckFlow(诊断)与 compileFlow(IR + JS 代码生成)src/checker.ts、src/codegen.ts
@dynamic-workflow/runtime运行时语义:FlowEventSink、AgentRuntime 接口与 FakeAgentRuntime、类型化错误src/fake-agent.ts 等
@dynamic-workflow/sandbox沙箱执行:子进程 → isolated-vm → 可信 bootstrap($runtime ABI)e2e 测试
@dynamic-workflow/cli命令行:check / compile / runsrc/main.ts

执行链的每一跳​

  1. 解析(language):.flow → 词法/语法分析(Langium)→ 语法 AST
  2. 检查(compiler.checker):语义诊断(作用域/资源/依赖)+ 类型诊断(推断/可赋值性/期望类型),合并输出
  3. 编译(compiler.codegen):语法 AST → Flow IR(含 StageIR.dependencies 等元数据)→ ESTree → 受限 JavaScript
  4. 沙箱(sandbox):子进程内 isolated-vm 装载 bootstrap,工作流胶水代码 只能通过 $host.invoke(op, payload) 与宿主通信
  5. 运行时(runtime):确定性结构在 bootstrap 内执行;agent 调用转发到 宿主侧 HostOps(预算/并发/解析/收窄/校验/修复/重试管线), 事件流经 FlowEventSink

接入你自己的 Agent 系统​

语言与模型之间只有一个接口:AgentRuntime。宿主要做的:

  1. resolveAgent(resourceId) —— 把 use agent "my-assistant" 的逻辑 id 解析到具体实现
  2. resolveTeam(teamId) —— 返回团队(main 与成员列表), 供 team.main / team.member(...) 路由与成员资格校验
  3. 执行调用 —— 接收任务描述符(target、task、input、tools 交集后的 工具集、write 策略、OutputContract),返回结构化输出; 契约校验与修复回路由 Runtime 完成

CLI 中的用法示例(packages/cli/src/main.ts):

const agents = new FakeAgentRuntime({
  teams: {
    'engineering-team': {
      main: 'lead',
      members: ['lead', 'implementer', 'test-engineer', 'reviewer'],
    },
  },
});

const result = await runFlowSandboxed(compiled, input, {
  host: { agents, events, context: { project: 'cli-demo' } },
});

把 FakeAgentRuntime 换成你的实现(OpenAI、Anthropic、内部网关……), 工作流一行不改——这就是"无厂商绑定"的落点。

构建与测试​

pnpm build          # tsc -b:构建全部包
pnpm test           # vitest 单测
pnpm e2e            # sandbox 端到端测试
pnpm typecheck      # 类型检查
pnpm lint           # biome