flue run

概要

flue run <path> --message <text> [--name <agent>] [--id <id>] [--data <json>] [--uid <uid> | --new] [--env <path>] [--json]

描述

flue run 在本地 Node.js 进程中执行一个智能体模块：提交一条消息，将智能体的活动流式传输到 stderr，将最终的助手回复打印到 stdout，然后退出。不会创建服务器，也不会写入构建产物 — 只加载智能体模块（及其导入的内容），永远不会加载 app.ts。导入了 cloudflare:* API 的模块会失败，并提示使用 vite dev，因为平台绑定在那里可用。

对话在多次调用之间保持持久化，因此 --id 可以继续之前运行开始的对话。当项目存在 db 入口 时使用该存储，否则使用项目本地缓存文件（node_modules/.cache/flue/run.db）。flue.config.* 从当前工作目录中发现，项目的 .env 会自动加载（shell 中已设置的值优先）。

选项

选项	描述
<path>	要运行的智能体模块，作为从当前工作目录解析的文件路径。
-m, --message <text>	提交给智能体的用户消息。必填。
--name <agent>	当模块定义了多个智能体时，指定运行哪一个。匹配智能体的名称 — 设置了 agentName 时使用它，否则使用导出的函数名。当模块导出多个智能体时为必填；没有静默默认值。
--id <id>	要创建或继续的对话 ID。默认为新生成的 ULID，打印到 stderr。
--data <json>	实例创建数据，在智能体内部通过 useInitialData() 读取。仅在本次运行创建对话时生效；继续对话时静默忽略。不能与 --uid 组合使用。
--uid <uid>	仅继续此 uid 的对话实例。不能与 --new 或 --data 组合使用。
--new	仅创建：当对话 ID 已存在时拒绝运行。
--json	向 stdout 打印 JSON 结果信封，而不是回复文本。
--env <path>	在运行前加载一个替代的 .env 格式文件，而不是默认的 .env。

输出

最终的助手回复打印到 stdout；其他所有内容（流式文本、工具活动、状态行）输出到 stderr，因此 stdout 保持可管道传输。使用 --json 时，stdout 输出一个 JSON 信封：

{
  "id": "support-4821",
  "agent": "hello",
  "submissionId": "…",
  "outcome": "completed",
  "message": "The final assistant reply.",
  "uid": "inst_…"
}

--json 始终为每个终端结果打印恰好一个信封，通过 outcome 区分：

• "outcome": "completed" 包含 message（助手回复）。
• "outcome": "failed" 和 "outcome": "aborted" 包含 error 对象而不是回复 — { message, type?, details?, dev? }，当底层错误是 Flue 错误时会包含类型化字段。
• 运行开始前的设置或准入失败（模块解析、配置、创建数据验证）会打印 { "outcome": "error", "error": { … } }。

信封是对退出码的补充而非替代：0 表示完成，1 表示失败和设置错误，130 表示中止。

示例

# 运行智能体一次并打印回复
flue run src/agents/hello.ts -m "Hi there"

# 在多次调用之间继续同一对话
flue run src/agents/support.ts -m "It fails on startup." --id support-4821
flue run src/agents/support.ts -m "Node 22, macOS."      --id support-4821

# 从多智能体模块中选择一个智能体
flue run src/agents/team.ts --name second-shift -m "Take over."

# CI：只创建一次，设置创建数据，捕获信封
flue run src/agents/triage.ts -m "Triage this." --id "issue-$N" --data '{"issue": 17307}' --new --json

# 从信封中提取回复文本
flue run src/agents/hello.ts -m "Run the demo." --json | jq -r .message

# 为一次运行加载预发布环境凭证
flue run src/agents/hello.ts -m "Hi" --env .env.staging