Flue: 沙箱智能体框架

这是什么

Flue 是一个基于 TypeScript 的开源 Agent Harness Framework（智能体运行框架），由 Astro 团队开发。它被定位为“下一代智能体构建框架”，旨在提供类似 Claude Code 或 Codex 的开发体验，但完全去除了对图形用户界面（GUI）或终端用户界面（TUI）的依赖。

Flue 的核心设计理念是 100% Headless（无头）且可编程。它不依赖人类操作员实时交互，而是通过 TypeScript 代码、Markdown 文件（如 AGENTS.md）以及内置的 Agent Harness 来驱动智能体自主完成任务。它并非传统的 AI SDK，而是一个运行时无关（runtime-agnostic）的框架，类似于 Astro 或 Next.js 之于 Web 开发，允许开发者“编写一次，部署到任何地方”（如 Node.js、Cloudflare Workers、GitHub Actions、GitLab CI/CD 等）。

目前项目处于实验性活跃开发阶段（Experimental），API 可能会发生变化。

解决的问题

1. 智能体部署的碎片化与复杂性：传统的 AI 应用开发往往需要处理复杂的容器管理、沙箱隔离和环境配置。Flue 通过抽象出统一的 Harness 层，解决了在不同运行时环境（Serverless、CI/CD、本地 Node）中部署智能体时的环境差异问题。
2. 过度依赖人类交互：许多现有框架（如早期的 Chatbot 框架）假设需要人类在循环中不断输入指令。Flue 解决了需要构建完全自主、无需人工介入即可执行复杂任务序列的智能体的需求。
3. 性能与成本瓶颈：为每个智能体会话启动完整的 Docker 容器不仅速度慢，而且资源消耗巨大。Flue 通过引入“虚拟沙箱”（Virtual Sandbox）机制，解决了高并发、大规模场景下的性能与成本问题。
4. 逻辑与代码的耦合：传统开发中，智能体的行为逻辑硬编码在 TypeScript 中。Flue 将大部分“逻辑”（技能、上下文、指令）下沉到 Markdown 文件（如 AGENTS.md）中，实现了声明式配置与代码逻辑的分离，降低了维护成本。

核心功能

• Agent Harness 运行时： Flue 提供了一个内置的 Harness 机制，负责初始化智能体所需的沙箱、工具、技能和上下文。开发者只需调用 createAgent 和 harness.session() 即可启动智能体会话。

• 多模式沙箱支持：

  • Virtual Sandbox（虚拟沙箱）：默认选项，基于 just-bash 实现。无需启动完整容器，速度极快、成本低、扩展性强，适合高流量场景。
  • Local Sandbox：直接访问宿主机文件系统和 Shell。适用于 CI/CD 环境（如 GitHub Actions），利用现有的 gh、git、npm 等工具链。
  • Container Sandbox（容器沙箱）：通过 Daytona 等连接器集成完整的 Linux 容器环境，适用于需要完整开发环境（如浏览器、Node.js、Git 仓库克隆）的复杂编码智能体。

• 消息驱动架构（Message-Driven）： 智能体可以通过 HTTP 或 WebSocket 端点（/agents/:name/:id）接收直接消息。应用也可以通过 dispatch(...) 方法将异步输入推送到智能体会话中，支持 WebSocket 实时交互。

• 基于 Markdown 的配置驱动： 智能体的行为逻辑大量依赖于 AGENTS.md 和 Skills 定义。开发者可以通过 Frontmatter 定义技能名称，并在代码中通过 session.skill('name', args) 调用，实现逻辑的模块化。

• 类型安全的结果验证： 集成 valibot 等库，支持在 prompt() 或 skill() 调用中定义 result schema。智能体返回的数据会经过严格的类型和结构验证，确保下游编排逻辑的安全性。

• 可观测性集成： 提供官方的 @flue/opentelemetry 适配器，支持外部追踪、指标收集和错误报告（如 Braintrust 追踪、Sentry 错误上报）。

亮点 / 与同类相比

• 与 Claude Code / Codex 对比：

  • 体验相似，架构不同：Flue 的开发体验接近 Claude Code，但它是完全无头（Headless）的。它不需要 TUI/GUI，而是通过代码和 Markdown 进行控制，更适合集成到自动化流水线或后端服务中。
  • 无人类操作员假设：传统工具往往设计为辅助人类编码，而 Flue 设计的智能体是自主运行的实体。

• 与 LangChain / LlamaIndex 对比：

  • 框架 vs SDK：LangChain 等更多被视为 AI SDK 或链式编排库，侧重于 RAG 和 Prompt 工程。Flue 则是一个完整的 Runtime Framework，关注智能体的生命周期管理、环境隔离（沙箱）和部署形态。
  • 运行时无关性：Flue 强调“Write once, deploy anywhere”，原生支持 Cloudflare Workers 等边缘计算环境，而许多传统 SDK 更偏向于 Node.js 服务端。

• 性能优势：虚拟沙箱（Virtual Sandbox）： 这是 Flue 的一大亮点。相比为每个会话启动 Docker 容器，Flue 默认的虚拟沙箱基于 just-bash，启动速度呈数量级提升，资源占用极低。这使得构建每秒处理数千请求的高并发智能体成为可能，而无需承担高昂的容器运维成本。

• 声明式逻辑： 将 Skills 和 Context 放在 Markdown 中，使得非代码层面的业务逻辑（如提示词、规则）更容易被非开发人员（如产品经理、运营）理解和修改，实现了代码与配置的解耦。

适合谁用 / 上手

适合人群：

1. TypeScript 开发者：Flue 是 TypeScript 原生框架，类型系统完善，适合熟悉 TS 生态的工程师。
2. 需要构建自动化智能体的团队：例如需要构建自动代码审查、自动 Issue 分类、自动化客服回复等无需人工实时介入的场景。
3. 边缘计算/Serverless 用户：由于支持 Cloudflare Workers 等轻量级运行时，适合希望降低基础设施成本、利用边缘节点部署 AI 应用的开发者。
4. CI/CD 集成者：适合希望在 GitHub Actions 或 GitLab CI 中嵌入智能体进行自动化测试、部署或代码分析的场景。

上手指南：

1. 安装：通过 npm/yarn/pnpm 安装 @flue/runtime 及相关依赖。
2. 初始化：创建 .flue/workflows 目录，定义工作流文件（如 hello-world.ts）。
3. 定义 Agent：使用 createAgent 创建智能体实例，配置模型（如 anthropic/claude-sonnet-4-6）和沙箱类型。
4. 编写逻辑：在 run 函数中初始化 Harness，创建 Session，并通过 session.prompt 发送指令。利用 valibot 定义返回结果的结构。
5. 配置 Markdown：在项目中添加 AGENTS.md 或 Skills 文件，定义智能体的行为规则和上下文。
6. 部署：根据目标运行时（Node.js, Cloudflare 等）调整配置，利用 Flue 的中间件暴露 HTTP 端点或直接通过 CLI 运行。

注意：由于项目处于 v0.0.x 实验阶段，API 可能频繁变动，建议在正式生产环境使用前密切关注官方更新日志。