Floom

Floom

循环工程工具架。循环运行的 AI 工作者。

为它们安排计划、触发它们、要求审批，并记录每次运行。
工作者就是一个文件夹：worker.yml + SKILL.md 或 run.py。通过 Claude Code、Codex 或 CLI 部署。通过 UI、REST 或 MCP 运行。

开始使用 · 构建工作者 · 试用托管版本 · 阅读文档

---

大多数“AI 自动化”要么是需要你盯着的聊天窗口，要么是按任务收费且无法审计的无代码流程图。Floom 是一套循环工程工具架：它提供真实的运行时，工作者是可读的软件包，无需你看管也能循环运行，而且每次执行都会留下日志、输出、工具调用、审批，以及可供信赖的回放记录。可通过 MCP 或 CLI 原生搭配 Claude Code 和 Codex 使用。

将 Python 脚本部署为应用、REST API 和 MCP 工具

Floom 能让 Agent 或开发者将 Python 脚本变成工作者，非开发者可以通过 UI 运行，其他系统可以通过 REST 调用，AI Agent 则可以通过 MCP 操作。

从三个文件开始：

workers/my-worker/
  worker.yml
  run.py
  requirements.txt

然后验证、部署并运行：

floom workers validate ./workers/my-worker
floom workers push ./workers/my-worker
floom run my-worker --input key=value

完整的可直接复制粘贴的工作者规范请参阅 BUILDING.md。

Floom 是什么：后台 AI 工作者的运行时

Floom 可将可重复的知识工作自动化任务转变为后台 AI 工作者。工作者可以手动运行、按计划运行、由 webhook 触发，或由应用事件触发。运行时会保留工作者定义、输入架构、输出架构、日志、工具调用、审批和运行历史，供检查。

如果你希望 AI Agent 定期执行任务，又不想让任务变成不透明的聊天记录、难以比较差异的自动化流程图，或缺少监督的一次性脚本，就可以使用 Floom。

从文件夹构建并部署 AI 工作者

AI Agent 和开发者可以从文件夹构建 Floom 工作者：

workers/<worker-id>/
  worker.yml        # manifest: inputs, outputs, trigger, runtime, secrets
  run.py            # script entrypoint, or SKILL.md for agent mode
  requirements.txt  # optional Python dependencies

使用以下命令部署工作者：

floom workers validate ./workers/<worker-id>
floom workers push ./workers/<worker-id>
floom run <worker-id> --input key=value

部署后，Floom 会通过 UI、REST 端点以及面向 AI 客户端的 Floom MCP 服务提供工作者。完整的可直接复制粘贴的构建规范请参阅 BUILDING.md。

工作者的样子

工作者是一种以文件夹为基础的任务定义。用通俗易懂的语言描述工作（SKILL.md），或提供脚本（run.py），在 worker.yml 中声明其工具、触发方式、记忆和密钥，然后由 Floom 运行。

# workers/github-digest/worker.yml  (abbreviated)
name: github-digest
description: "Every morning at 9am, send a digest of unread GitHub PRs and open issues."
exec:
  entry: SKILL.md          # plain-English agent; or run.py for a script
trigger:
  type: schedule
  cron: "0 9 * * *"        # also: manual, webhook, Composio event
connections:
  - app: github            # the only tools this agent is allowed to call
    allowed_tools: [GITHUB_FIND_PULL_REQUESTS, GITHUB_LIST_ASSIGNED_ISSUES]

You are a GitHub assistant generating a daily PR + issues digest.
Fetch the user's open PRs and assigned issues, compile a markdown digest
with Action items, and finish_with_outputs({ "digest": "<markdown>" }).

它会在上午 9 点运行，只调用声明的两个 GitHub 工具，并将 digest.md 写入一次运行记录，你可以打开、回放或回滚该记录：

run 7f3a · github-digest · finished 09:00:04 · 2 tool calls · output: digest.md
  ✓ GITHUB_FIND_PULL_REQUESTS    q="is:open is:pr author:@me"   → 4 PRs
  ✓ GITHUB_LIST_ASSIGNED_ISSUES  state=open                     → 2 issues
  → out/digest.md (text/markdown)   [open · replay · rollback]

完整清单还会添加 schema_version、title、version 和声明的 outputs。可运行示例请参阅 workers/，最精简的可部署工作者请参阅 BUILDING.md，并可查看 Agent 指南。

两种 Agent

	运行位置	主机隔离	工具	副作用
脚本（run.py / .sh / .js / .ts）	E2B 沙盒微型虚拟机	文件系统、环境和进程彼此隔离；平台密钥不会提供给脚本	沙盒 + 已声明的连接	声明后需经过审批关卡
Agent（SKILL.md）	API 进程中的 AgentDriver（仅限受信任的程序包）	按策略不采用微型虚拟机隔离	已声明且列入允许名单的连接	声明后需经过审批关卡

默认情况下，沙盒允许访问公共网络，并阻止访问私有/内部网段；也可选择使用更严格的允许名单。完整的信任模型请参阅：ARCHITECTURE.md。

Worker Runtime 一览

简介	可自托管的运行时，用于创建、运行和管理后台 AI Agent
适用场景	定期执行的 Agent 任务：收件箱分类、摘要、外联内容草拟、信息补充、监控
Agent 类型	脚本（run.py/.sh/.js/.ts）和纯英文 Agent（SKILL.md）
隔离	脚本 worker 在 E2B 沙盒微型虚拟机中运行——主机文件系统、环境和进程彼此隔离；平台密钥不会提供给脚本
触发方式	手动、定时（cron）、webhook、Composio 事件
安全性	对会产生副作用的 Agent 采用人在回路中的审批机制；每个 Agent 的工具均列入允许名单
全程留痕	每次运行都会记录日志、输出、工具调用、审批状态、重放和回滚
费用模式	Floom 不收取单任务费用——你只需支付 E2B 沙盒运行时费用（按秒计费）以及模型/API 提供商的使用费用
技术栈	Next.js + Tailwind UI · FastAPI + SQLite API · MCP 服务 + CLI
运行平台	Linux、macOS、Windows（Python 3.11+、Node 20+）
许可证	MIT · 托管版本

Floom 适合哪些人

• 创始人和运营人员：将定期工作（摘要、分类、外联）转化为可自动运行的 Agent。
• 工程师：需要真正的运行时——清单、沙盒、限制和审批，而不是一个提示词文件加一项 cron 任务。
• 团队：需要将每项操作列入允许名单、经过审批，并可为审计进行重放。
• 任何曾受 Agent 所害的人：Agent 执行了破坏性命令、泄露了密钥，或声称任务成功却没有任何记录。

Floom 对比：原始脚本、Zapier 与手工构建的 MCP

	原始脚本	Zapier / Make	手工构建的 MCP 服务	Floom
Worker 定义	临时提示词或代码	可视化流程图，难以比较差异	自定义工具服务代码	一个文件夹：worker.yml + SKILL.md 或 run.py
运行时	cron、shell 或本地进程	供应商的自动化运行时	由开发者自行构建	Agent 运行时，支持触发器、运行、日志、输出、审批、重放和回滚
隔离	在你的主机上运行	供应商云端，运行过程不透明	取决于实现方式	脚本 worker 使用 E2B 沙盒微型虚拟机
工具访问	脚本能够访问的任何内容	按连接器划分	仅限 MCP 工具	按 worker 声明并列入允许名单
副作用	立即执行	取决于工作流	自定义审批逻辑	声明后需经过人工审批关卡
可观测性	滚动输出（如有）	按步骤记录日志	自定义日志	日志、工具调用、输出、构件、审批状态、重放和回滚
Agent 访问	需要自定义封装器	并非面向 Agent 原生构建	Agent 可以调用工具，但应用运行时彼此独立	MCP 工具让 Agent 可以创建、运行、监控和检查 worker
费用模式	模型 token 和基础设施费用	按任务或执行次数收费	模型 token 和基础设施费用	不收取单任务费用；你只需支付运行时和服务提供商的使用费用
托管方式	你的主机	仅限供应商托管	你的主机	可自托管，或使用托管服务

快速开始：在本地运行 Floom

Linux / macOS

git clone https://github.com/floomhq/floom.git
cd floom
./scripts/setup.sh
# edit apps/api/.env: add a model provider key and E2B_API_KEY
./scripts/dev.sh

Windows PowerShell

git clone https://github.com/floomhq/floom.git; cd floom
.\scripts\setup.ps1
# edit apps\api\.env: add a model provider key and E2B_API_KEY
.\scripts\dev.ps1

需要 Python 3.11+、Node.js 20+、Git、模型提供商密钥，以及从 e2b.dev 获取的 E2B 密钥。打开 http://localhost:3000 并登录——本地开发无需身份验证密钥，示例 Agent 会在首次启动时预置。

完整的设置说明、模型提供商、可选集成和安全自托管检查清单，请参阅：docs/GETTING-STARTED.md。常见问题请参阅：docs/TROUBLESHOOTING.md。

还没准备好自托管？floom.dev 是托管版本——无需设置即可聘用 AI Agent。托管用户可以从 MCP 客户端开始使用：

npx -y @floomhq/floom mcp install --target claude

上述 .env、模型提供商和 E2B 密钥用于运行你自己的本地或 自托管运行时，而不是用于使用 Floom Cloud。

一次运行如何工作

核心概念

• Agent - workers/<name>/ 下的文件夹，包含 worker.yml 和脚本入口点（run.py）或 Agent 提示词（SKILL.md）。
• 运行 - 每次执行都会记录日志、输出、工具调用、审批状态以及重放/回滚上下文。
• 上下文 - 可附加到 Agent 作为参考资料的可复用文件包；默认情况下为敏感内容。
• 审批 - 会产生副作用的 Agent 会暂停运行，等待人工决策，之后才会有任何内容离开系统。
• 工作区历史 - 在由 git 支持的工作区中对 Agent、上下文和设置进行版本控制，以便回滚。

请参阅 docs/GETTING-STARTED.md 编写你的第一个 Agent，然后参阅 docs/AUTHORING.md 了解完整的清单和运行时契约。

工作器如何执行

默认情况下，脚本工作器（.py/.sh/.js/.ts）在 E2B 沙箱微型虚拟机中运行：依赖项相互隔离，无法访问主机进程，资源受到限制。TypeScript 工作器使用 Node 运行时和 tsx（npx --yes tsx run.ts），并遵循与 Python 工作器相同的 inputs.json/result.json 契约。在沙箱内转储 os.environ 的程序包只能看到沙箱元数据——FLOOM_SECRET、提供商密钥和 E2B_API_KEY 均不可见。Agent 工作器（SKILL.md）通过由 API 托管的 AgentDriver 工具循环运行，并受其声明的连接和审批关卡约束；当前的单租户策略仅允许此路径使用受信任的 Agent 程序包。不提供进程内本地脚本运行器。完整的信任模型请参阅：ARCHITECTURE.md。

数据处理、已连接账户的保护措施、保留范围以及托管版 Cloud 的法律信息页面均概述于 docs/DATA-RETENTION.md。

架构

apps/web      Next.js + TypeScript + Tailwind + shadcn/ui
apps/api      FastAPI + SQLite + Pydantic
apps/mcp      MCP server + CLI
workers/      Worker folders (worker.yml + run.py or SKILL.md)
data/         SQLite DB + run artifacts

常见问题：AI Agent、MCP 和 Python 脚本部署

用一句话来说，Floom 是什么？

Floom 是一个开源运行时，用于运行后台 AI 工作器。工作器来自经过版本控制的文件夹，并声明输入、输出、触发器、工具、审批、日志、REST API 访问、UI 访问和 MCP 访问。

Floom 是 MCP 服务吗？

Floom 包含 MCP 服务，但它不仅仅是 MCP 服务。MCP 端点允许 Agent 客户端创建、运行、监视、检查和管理 Floom 工作器。Floom 运行时负责执行这些工作器、记录运行、管理审批，并提供 UI 和 REST API。

AI 编码 Agent 能否根据此代码仓库构建 Floom 工作器？

可以。请先阅读 BUILDING.md。构建契约要求使用 workers/<id>/ 文件夹，其中包含 worker.yml、run.py 或 SKILL.md，以及可选的 requirements.txt，然后运行 floom workers validate 和 floom workers push。

我可以将 Python 脚本部署为应用、REST API 和可通过 MCP 访问的工作器吗？

可以。将脚本放入 workers/<id>/run.py，在 worker.yml 中声明其输入和输出，然后使用 floom workers push 部署。Floom 会让它可以通过 UI、REST API 和 MCP 工具运行。

脚本模式和 Agent 模式有什么区别？

脚本模式会在沙箱中运行 Python、shell 或 Node 等确定性代码。Agent 模式会通过 Agent 循环运行 SKILL.md 提示词，并使用已声明的工具和输出写入器。

Floom 会取代 Zapier 或 Make 吗？

Floom 面向需要版本化工作器文件夹、沙箱执行、审批关卡、日志、输出、重放、回滚、REST API 访问和 MCP 访问的团队。Zapier 和 Make 是采用各自供应商运行时的可视化自动化产品。

Floom 会取代手写的 MCP 工具吗？

Floom 可以通过 MCP 提供工作能力，而无需你手动构建整个应用运行时。手写的 MCP 服务会向 Agent 提供工具；Floom 则会为工作器提供运行时、UI、API、触发器、输出、日志、审批和 MCP 工具。

文档

• 快速入门 - 了解 Floom 的用途、首次运行、创建首个 Agent，以及安全的自托管检查清单。
• 构建 Floom 工作器 - 面向 Agent 和开发者的机器可读构建规范。
• 编写 Agent - 完整的 worker.yml 架构、执行模式、密钥、连接、触发器和审批。
• 数据、保留与保障措施 - Floom 会存储哪些内容、已连接账户的数据如何划分范围，以及可以安全承诺哪些删除和保留保障。
• Agent 实用指南 - 借助 Agent 编写内容的操作指南。
• 架构 - 运行时拓扑和沙箱信任模型。提交安全问题前请先阅读。
• API 概览 - 精选端点索引；完整参考文档见 http://localhost:8000/docs。
• 故障排除 · 路线图 · 项目历史 · v1.0.0 发行说明
• 许可 - Floom 的 MIT 许可证及第三方依赖许可证说明。

贡献

欢迎贡献。有关本地设置、首次贡献指南和 PR 准则，请参阅 CONTRIBUTING.md。在仓库根目录运行以下命令，可快速进行本地检查：

npm run test:api
npm run lint:web
npm run test:web
npm run test:mcp

安全

如需报告漏洞，请遵循 SECURITY.md，并私下报告，不要公开提交 issue。

许可证

MIT 许可证 (c) 2026 Floom 贡献者。你可以使用、复制、修改、合并、发布、分发、再许可和销售 Floom 副本，但须遵守 MIT 许可证声明和免责声明。