快速开始

十分钟:装好工具链,校验并运行第一个 workflow,看懂第一个编译产物。

环境要求

Node.js 20 或 22（原生沙箱依赖暂不支持更高主版本）
pnpm ≥ 9(仓库使用 pnpm workspace)

1. 构建工具链

git clone <repo> dynamic-workflow && cd dynamic-workflow
pnpm install
pnpm build          # tsc -b:构建 packages/* 全部五个包

构建完成后,CLI 入口在 packages/cli/dist/main.js。

2. 校验一个 workflow

node packages/cli/dist/main.js check examples/simple.flow
# ✓ examples/delivery.flow checks clean

check 做三层校验:词法/语法(Langium 解析)→ 语义( 作用域、资源、stage 依赖)→ 类型(表达式推断与可赋值性)。存在 error 级诊断时退出码非零,并带行号列号。

试一个会报错的:把 workflow hello(input: Request) 的形参改名成 req, 再 check:

error workflow-param-name 1:15 workflow parameter must be named 'input'

3. 沙箱运行

node packages/cli/dist/main.js run examples/simple.flow \
  --input '{"text": "hello agent flow"}'

run 把编译产物放进沙箱(子进程 + isolate)执行。CLI 内置一个 schema 驱动的 FakeAgentRuntime:它不调用真实模型,而是按 expect 的 JSON Schema 生成占位输出。所以你看到的回答是 "generated" 之类的占位串——这正好证明:即使模型是假的,契约校验、流程推进、事件流转都是真的。

占位值的坑

FakeAgentRuntime 对所有字符串字段生成常量 "generated"。对含跨条目唯一性 require 的示例(如 unique(items[*].id)), 请用单条目输入运行,否则唯一性断言会因占位值重复而失败。

4. 看编译产物

node packages/cli/dist/main.js compile examples/simple.flow --js
node packages/cli/dist/main.js compile examples/simple.flow --ir

--js 输出受限 JavaScript 胶水代码,--ir 输出 Flow IR(JSON)。加 --out <path> 写入文件。生成的 JS 里没有任何直接 I/O, 一切运行时能力都通过 $runtime ABI 调用。

5. 写你自己的第一个 workflow

新建 mine.flow,贴入:

workflow first(input: Ask) -> Answer {
  use agent "my-assistant" as helper

  type Ask { question: text }
  type Answer { reply: text }

  pipeline {
    stage reply -> Answer {
      let result = agent(helper) {
        task """
        Answer the question in one short paragraph.
        """
        input { question: input.question }
        tools none
        expect Answer
        timeout 2m
      }

      require result.reply != ""
        else fail "reply must not be empty"

      return result
    }

    return reply
  }
}

node packages/cli/dist/main.js check mine.flow
node packages/cli/dist/main.js run mine.flow --input '{"question": "why dsl"}'

注意三件事:

require 在 agent 之外——确定性判断由语言结构表达
expect Answer 让 result.reply 在编译期就完成字段检查
tools none 请求空工具集——这是权限声明,不是装饰

命令速查

命令	作用
`flow check <file>`	语法 + 语义 + 类型诊断,输出诊断与退出码
`flow compile <file> [--js\|--ir] [--out p]`	编译为受限 JS 或 Flow IR
`flow run <file> [--input '<json>'\|--input-file p]`	沙箱执行,FakeAgentRuntime 驱动

完整说明见 CLI 参考。

接入真实模型

CLI 的 FakeAgentRuntime 只用于演示。真实运行时实现 AgentRuntime 接口(resolveAgent / resolveTeam / 调用执行),由宿主注入。语言与模型之间的全部耦合就这一个接口——见包与架构。

下一步

顶层结构与管道
示例库:24 个可直接 check/run 的例子

环境要求​

1. 构建工具链​

2. 校验一个 workflow​

3. 沙箱运行​

4. 看编译产物​

5. 写你自己的第一个 workflow​

命令速查​

接入真实模型​

下一步​