Flue：当 Astro 团队决定做 Agent 框架

2026 年 2 月，Astro 团队在 GitHub 上建了一个新仓库。名字叫 Flue，描述写的是"The sandbox agent framework。"。当时没人太在意——毕竟每个前端团队都在做 AI 框架，多一个不多。

Astro 是谁？这家公司靠同名框架（astroutils.sh）起家，主打"用更少的 JavaScript"做静态网站。他们的 Astro 框架 GitHub 上 50k+ star，在博客、文档站、营销页面这些场景里用得很多，靠一套"文件约定"的路由机制做出了差异化。后来做了 Astro Studio 和托管服务。不是大厂，但在前端圈子里口碑很好。

Flue 就是这帮人做的——不是大厂 AI Lab 出品，是一个懂 Web 框架、懂工程化的团队，觉得现在 agent 框架普遍太重的反应。

两个月后，2127 个 star，99 个 fork，FredKSchott 一个人推了 163 次 commit，v0.3.10 在 package.json 里躺着但一个正式 release 都没发。我翻了一遍代码，觉得这东西跟市面上所有 agent 框架都不太一样。

先搞清楚它是什么

Flue 的 README 第一句话就说得很直白："If you know how to use Claude Code... then you already know the basics of how to build agents with Flue."

翻译一下：你知道 Claude Code 怎么用对吧？那你就知道怎么用 Flue 写 agent 了。区别只是——Claude Code 需要一个人坐在终端前面敲键盘，Flue 不需要。它就是个 headless Claude Code，没有 TUI，没有 GUI，纯 TypeScript。

这个定位其实很鸡贼。市面上大多数 agent 框架（LangChain、Mastra、Pi）都是"给你一套工具让你搭 agent"。Flue 反着来——它说"这就是个 Claude Code，只不过你可以编程控制它"。

你再想想它的出身就理解了。Astro 团队最擅长什么？把复杂的东西包装成文件约定。Astro 的 src/pages 目录映射路由，src/layouts 映射布局，src/content 映射内容集合。Flue 完全是同一个套路：

• flue.config.ts 定义全局配置
• agents/ 目录下每个 .ts 文件就是一个 agent
• 每个 agent 对应的 .agent.md 文件写行为定义
• tools/agent-name/ 目录放工具实现

配置靠约定，逻辑靠 Markdown，只有编排才是代码。这套哲学在 Astro 身上被验证过——它很对。

代码里藏着什么

我直接扒了 session.ts 和 agent.ts 来看。核心架构比我想象的简洁。

一个 agent 的生命周期是：创建一个 agent runtime（带 sandbox、tools、model），然后开一个对话，之后 .step()、.resume()、.fork() 三个方法走天下。

最有意思的是 session.ts 里的 session 实现。它不是简单的消息数组——每条消息都有一个 parentId，形成链表结构。有个 leafId 指向当前分支。这意味着你可以在任意历史点 fork 出新 session。这个设计在 agent 框架里很少见，但实用场景很明显：调试 agent 的时候你可以"回溯到第 N 轮对话重新开始"。

compaction 那套实现也挺扎实（compaction.ts，335 行纯逻辑）。默认配置是 enable=true、reserveTokens=16384、keepRecentTokens=20000。触发有两种模式：threshold（超过上下文窗口 - reserve 阈值就压缩）和 overflow（LLM 返回 overflow 错误时自动压缩重试）。压缩不是简单丢弃旧消息——它会调 LLM 把旧消息总结成结构化 Markdown，格式固定：## Goal、## Progress、## Key Decisions、## Next Steps。

这里有个设计取舍：压缩用的是 agent 自己的模型。这意味着如果你的 agent 用 Claude Opus 跑主任务，压缩也是 Opus 来做。成本高但质量有保障。

三个沙箱模式的思考

Flue 定义了三种沙箱模式：

• Virtual Sandbox（默认）：基于 just-bash 的 bash 模拟器，不支持真正的进程执行
• Local Sandbox：直接把宿主机的文件系统暴露给 agent
• Remote Sandbox：通过 connector 连接到远程运行环境（Daytona / Vercel）

我一开始觉得 virtual sandbox 不够用——毕竟 just-bash 只是一个 bash 模拟器，不能真的跑 Node.js。但仔细想想，大部分 agent 任务其实不需要容器。翻译一段文字、搜索知识库、写一封邮件——这些操作只需要文件读写和 grep/glob，just-bash 完全够。默认用 virtual 意味着 cold start 可以做到亚秒级，这对 HTTP 触发的 agent 场景至关重要。

Local sandbox 反倒是我觉得最被低估的模式。它把宿主机的文件系统挂载到 /workspace，agent 可以直接读你的仓库、跑 git log、调 npm test。对于 CI 场景来说，这比启动一个容器更直接——你已经在 runner 里了，仓库刚 checkout 完，为什么要多包一层容器？Flue 的 CI agent 例子就是这种模式：issue 来了，agent 用 gh CLI 读 issue，用 npm test 跑测试确认能不能复现，最后自动提 PR。全程不需要容器，不需要 docker-in-docker。这个思路比那些强制用容器的框架务实得多。

Remote sandbox 通过 connector 接入 Daytona。我看了 Daytona connector 的代码（在 agents/ 里，700 多行的 Markdown 模板），它把 Daytona SDK 的 DaytonaRunner 对象包装成 Flue 的 Sandbox 接口，然后 exec() 转成 runCommand()。这个适配器模式很干净——只要实现了 readFile、writeFile、exec、stat 这几个方法，任何容器提供商都能接进来。目前官方给了 Daytona 和 Vercel 两个 connector，E2B 和 Modal 在文档里提了但还没实装。

Connector 系统是个有趣的 trick

Flue 的 connector 不是 npm 包，是 Markdown 安装说明。flue add 会从 GitHub 拉下来一份 Markdown 文档，然后直接 pipe 给 Claude Code（或其他 coding agent），由 coding agent 自己写适配器代码。

这个设计的聪明之处：Flue 不需要维护多平台 SDK，兼容性问题由 coding agent 在安装时动态解决。缺点是安装过程需要一个 coding agent 在场，纯 CI 环境里可能不太方便。

跟竞品比

拿它跟 Mastra 和 Pi 放一起看比较有意思。

Mastra 的核心卖点是 Observational Memory——它把 agent 的运行时状态暴露给开发者调试。Flue 没有这东西，它更关心"你的 agent 能不能部署到 Cloudflare Workers"这种工程问题。

Flue 直接依赖了 @mariozechner/pi-agent-core（agent 运行时 + 工具执行）和 @mariozechner/pi-ai（多模型统一 API）。模型调用和 agent 循环这些层直接复用 pi 的实现，Flue 自己专注在 sandbox 和编译部署上。

LangChain 就不比了，完全不是一个赛道。LangChain 是 LLM 调用组合库，Flue 是 agent 部署框架。

缺点和问题

坦白说，Flue 还有很多 unfinished business。

第一，零官方 release。package.json 版本是 0.3.10，但 npm 上搜不到，GitHub Releases 是空的。这意味着你只能从源码构建。对于一个宣称"build once, deploy anywhere"的框架来说，这有点尴尬。

第二，只支持 Node.js 和 Cloudflare Workers 两个 target。GitHub Actions 和 GitLab CI/CD 作为 deploy target 在文档里提到了，但看 build 系统代码，目前只有 node 和 cloudflare 两个 plugin 实现。

第三，error handling 的体验还比较粗糙。从 session.ts 的 error 逻辑看，很多错误消息直接 console.error 然后 throw，没有统一的错误类型体系。生产环境里 debug 可能比较痛苦。

第四，文档网站 flueframework.com 目前就是一个 Astro app 的根路由加几个代码片段页面。connector 的安装说明页倒是做得很精致（Markdown 模板 + 变量替换），但整体文档还很薄。

第五，build 系统虽然功能上能跑，但代码还比较幼稚。build.ts 里扫描 agents 目录的逻辑是硬编码的，没有插件机制来扩展文件发现规则。Cloudflare plugin 用了一个很 hacky 的方式绕过 esbuild——因为 wrangler 自己会 bundle，double bundle 会炸，所以 Cloudflare 路径直接写了 bundle: 'none'。

我为什么觉得它值得关注

不是因为它有多完善——恰恰相反，它还很粗糙。我关注它是因为它代表了一种不同的思路。

大多数 agent 框架在解决"让 LLM 能调用工具"这个问题上花了很多精力。Flue 默认你已经知道怎么用 Claude Code——它解决的是"如何把 Claude Code 变成编程可控的基础设施"。

这个区别决定了它的设计取舍：编译型部署而非运行时解释、文件约定而非 API 配置、sandbox 分层而非统一容器方案。这些取舍不一定都对，但它们方向一致——让 agent 从"命令行玩具"变成"可部署的服务"。

Astro 团队在这方面的经验是实打实的。他们把 Vite 插件生态带到了静态网站生成领域，把文件路由变成了主流范式。现在他们要做的，是把这个方法复制到 agent 领域。能不能成不一定，但方向值得看。