flue 是什么?

Flue 是 Astro 团队维护的 TypeScript Agent 框架:用带 'use agent' 指令的函数和 hooks 组合模型、工具、技能与沙箱,再通过 CLI 单次运行,或作为 Hono/Vite 服务部署到 Node.js、Cloudflare 和 CI。

⭐ 6,823 Stars 🍴 382 Forks TypeScript Apache-2.0 作者: withastro
来源:github.com/withastro/flue;https://flueframework.com/docs/guide/gettin… 查看 GitHub 仓库 → 📘 使用教程 →

为什么值得关注

这些值只用于判断持续性。当前官方仓库已从早期 0.x 演进到 runtime 2.1.0,并把沙箱、持久运行、渠道和部署文档补成较完整的 Agent 运行时。

来源:github.com/withastro/flue;https://github.com/withastro/flue/releases

核心功能

函数式 Agent 与 hooks

Agent 是带 'use agent' 指令的 TypeScript 函数,通过 useModel、useSandbox、useSkill 和 useTool 声明完整 harness。

来源:github.com/withastro/flue;https://flueframework.com/docs/guide/gettin…
多级沙箱

框架支持虚拟、本地和远程容器类沙箱;Node 的 local() 直接绑定宿主文件系统与 shell,因此必须按任务选择隔离级别。

来源:flueframework.com/docs/guide/node-target/;https://github.com/withastr…
持久任务与服务路由

Flue 提供会话、durability、Agent 路由和 SDK;使用 Vite/Hono 可生成 Node 服务或 Cloudflare Worker,CLI 也可直接运行一次性 CI 任务。

来源:github.com/withastro/flue;https://flueframework.com/docs/guide/deploy…
渠道、MCP 与可观测性

官方包和文档覆盖 Slack、Teams、Discord、GitHub 等事件渠道、MCP 工具,以及 OpenTelemetry、Braintrust 和 Sentry 观测出口。

来源:github.com/withastro/flue;https://github.com/withastro/flue/releases

技术架构

Agent 函数声明模型、工具、技能和沙箱;runtime 负责会话、工具循环和持续执行。单次任务由 @flue/cli 直接调用,长期服务则用 @flue/vite 扫描 Agent 模块,通过 Hono 的 createAgentRouter 挂载 HTTP 路由。Node 目标输出 dist/server.mjs,Cloudflare 目标接入 Workers/Durable Objects;持久化需显式配置数据库适配器。

来源:github.com/withastro/flue;https://flueframework.com/docs/guide/gettin…

项目知识图谱

知识图谱:项目核心节点(中心)+ 核心功能(内环六边形)+ 关键技术依赖(外环 chip) @flue/runtime @flue/cli @flue/vite @earendil-works/pi-agent-core / pi-ai@earendil-work… @modelcontextprotocol/client@modelcontextp… 函数式 Agent 与 hooks 多级沙箱 持久任务与服务路由 渠道、MCP 与可观测性 flue 项目本体 核心功能 关键依赖

技术栈

语言TypeScript / ESM框架Flue runtime 2.1.0、Hono、Vite
@flue/runtime@flue/cli@flue/vite@earendil-works/pi-agent-core / pi-ai@modelcontextprotocol/clientvalibot
Node.js 22.19.0+;可部署到 Node、Cloudflare、GitHub Actions 或 GitLab CI;模型 provider key 与可选持久化数据库
来源:github.com/withastro/flue/blob/main/package.json;https://github.com/w…

快速上手

准备 Node.js 22.19.0+ 和模型 provider key,在新项目执行 npm install @flue/runtime @flue/cli;创建带 'use agent' 的 src/agents/assistant.ts,用 useModel() 选模型,再运行 npx flue run src/agents/assistant.ts --id hello-1 --message '测试消息'。需要 HTTP 服务时再安装 @flue/vite、hono 和 vite,配置 app.ts 与 vite.config.ts,依次运行 vite dev、vite build;不要在未限制权限前给 Agent 直接使用 local() 宿主 shell。
来源:flueframework.com/docs/guide/getting-started/;https://flueframework.c…

使用场景

适合构建需要工具、技能、工作区、持续会话和多部署目标的 TypeScript Agent,也适合用 flue run 在 CI 中执行一次性任务。只需简单的几轮模型工具调用时,较轻的 Agent loop SDK 会更直接;处理不可信代码时不能把 local() 当成隔离容器。

来源:github.com/withastro/flue;https://flueframework.com/docs/ecosystem/de…

优势与局限

优势

  • 把模型、工具、技能、沙箱和会话放进同一个 TypeScript Agent 定义
  • 同时支持一次性 CLI 任务和 Node/Cloudflare 服务部署
  • 提供渠道、MCP、持久化与可观测性扩展点
  • Apache-2.0 许可,当前 runtime 已发布 2.1.0

局限

  • Node.js 最低要求为 22.19.0,旧环境不能直接安装当前 runtime
  • local() 直接使用宿主文件系统和 shell,不提供容器级隔离
  • 构建后的 Node 服务不会自动加载 .env,部署时必须显式注入密钥
  • 未配置数据库适配器时会话只存在内存中,重启后丢失
  • 本轮未安装依赖或运行 Agent
来源:github.com/withastro/flue;https://flueframework.com/docs/guide/gettin…

最新版本

当前官方 @flue/runtime 版本为 2.1.0;2026-09-18 的多包 release 组包含 @flue/sdk、@flue/vite 和多个渠道包 2.1.0,并记录 runtime 2.1.0 依赖更新。升级时应同时核对 runtime、CLI、Vite 插件和实际使用的渠道包。

来源:github.com/withastro/flue/releases;https://github.com/withastro/flue/…

实测与证据

status: official_docs_checked_not_run  |  checked_at: 2026-09-23  |  environment: 核对 withastro/flue 官方仓库、package.json、runtime package、2.1.0 Releases、Getting Started、CLI、Deploy 与 Node.js 文档  |  limitations: 未安装 npm 包、未运行 npx flue、未调用模型、未启动 Vite 服务,也未部署 Node 或 Cloudflare  |  observed_output: 官方包元数据标明 @flue/runtime 2.1.0 和 Node.js >=22.19.0;官方入门命令为 npm install @flue/runtime @flue/cli,部署使用 @flue/vite、Hono 与 Vite

来源:github.com/withastro/flue/releases;https://github.com/withastro/flue/…

同类项目对比

Vercel AI SDK 的 ToolLoopAgent 主要封装模型、工具、上下文和停止条件组成的多步循环;Flue 在类似循环之上进一步整合沙箱、持续会话、Vite/Hono 路由、Node/Cloudflare 目标、渠道和观测。只做几轮工具调用时 ToolLoopAgent 更轻,Agent 需要工作区、恢复和服务化部署时 Flue 的范围更完整。

来源:flueframework.com/docs/guide/getting-started/;https://github.com/with…

总结评价

它的价值在于把 Agent loop、沙箱、会话和部署放到统一 TypeScript 运行时;上线前必须补齐持久化、密钥注入和沙箱权限验证。

来源:github.com/withastro/flue;https://flueframework.com/docs/guide/deploy/

常见问题

Flue 2.1.0 需要哪个 Node.js 版本?

官方 Getting Started 和 runtime 包都要求 Node.js 22.19.0 或更新版本。仓库自身使用 pnpm 11;普通使用者可以按文档用 npm 安装已发布包。

Flue 的 local() 是隔离容器吗?

不是。Node 目标的 local() 直接绑定宿主文件系统与 shell;需要更强隔离时应选择受控的远程或容器沙箱,并限制凭据和网络。

Flue 服务重启后会保留对话吗?

默认不会。官方部署文档说明,没有配置数据库适配器时,会话只在进程内存中,重启即丢失。重要任务应接持久化适配器并测试恢复。

Flue 和 Vercel AI SDK 的 ToolLoopAgent 有什么区别?

ToolLoopAgent 重点是模型、工具和停止条件组成的多步循环;Flue 在此类循环之上整合沙箱、持久会话、部署路由、渠道与可观测性。

资料与核验范围
本文依据项目公开资料整理。版本、安装命令和功能边界可能随上游更新,请以所列来源和项目当前版本为准。 资料核对时间: 2026-09-23 13:55.

参考材料:README、GitHub API、依赖文件