fluidbox

# 流体盒 🧊 **在受控、可丢弃的沙盒中运行 AI 编程代理，具备策略、人工审批、只追加审计跟踪和成本控制。** [](https://github.com/hrishikeshdkakkad/fluidbox/actions/workflows/ci.yml) [](./LICENSE) [](./crates) [](./CONTRIBUTING.md) 编程代理功能强大，但缺乏 accountability：它们以您的凭证、在您的机器上运行，没有记录它们做了什么或为什么。**流体盒**是一个开源控制平面，解决了 accountability 问题，同时保持了强大的功能。您可以注册一个版本化的**代理定义**（执行环境、模型、系统、策略、预算），然后启动它的**运行**。每次运行： 1. **冻结一个不可变的 `RunSpec`** — 模型、提示、策略快照、能力锁定 — 以便审计跟踪可以被信任，即使在代理和策略更改后。 2. **获取一个全新的、无外部访问的沙盒**，带有绑定挂载的存储库副本。您的 API 密钥、Git 凭证和 OAuth令牌**从未进入沙盒** — 控制平面代理每个凭证操作。 3. **在每个工具调用通过策略门时，流式传输实时事件时间线**：允许、拒绝或**暂停以等待人工审批**（或在自主模式下在更严格的防护措施下自动决策）。 4. **以差异和成本报告结束**，由只追加、强制删除的账本支持 — 提示从不触及数据库，只有摘要、使用情况和决策。 ## 内部 - **策略引擎** — 按工具调用评估的 YAML 规则，策略快照冻结每个运行，并且在自主模式下记录原始和重写的裁决。 - **人工审批** — 幂等、重启安全、带有过期时间；权限回调在每个自主模式下保持连接。 - **两个执行环境** — Claude Agent SDK 和 Codex，背后是一个运行者合约；添加执行环境是一个新的运行者镜像和一个注册表臂。 - **凭证反转** — 沙盒的 `ANTHROPIC_API_KEY` 是一个会话令牌，通过服务器内部的 LLM 外观验证，该外观计量使用情况并强制预算停止；Git 获取和代理的 MCP 工具在控制平面上运行，凭证在静止时密封。 - **触发器和调度** — 订阅范围的 API 令牌、签名 webhook 输入、cron 调度，精确触发一次，以及带有重试的 HMAC 签名结果交付。 - **GitHub 集成** — 无缝 GitHub 应用连接、PR 分发（每个 PR 一个稳定评论，每个 head SHA 一个检查），以及 fork PR 冻结为只读，无审批逃脱。 - **能力目录** — 版本化的 MCP 工具包，在运行创建时锁定：沙盒工具作为包含的 stdio 子进程运行，代理工具在控制平面上执行，凭证沙盒看不到。 - **连接器目录 + OAuth** — 使用 PKCE、资源指示器和动态客户端注册连接外部服务；刷新令牌在静止时密封，原子旋转。 - **仪表板** — 一个 Next.js UI（仅呈现；所有逻辑都位于 Rust API 中）。 ## 快速入门 先决条件：[Rust](https://rustup.rs)（稳定版）、[Docker](https://docs.docker.com/get-docker/)、[just](https://github.com/casey/just)、[pnpm](https://pnpm.io)，以及一个免费的 [Neon](https://neon.tech) Postgres 数据库。 ```bash git clone https://github.com/hrishikeshdkakkad/fluidbox.git cd fluidbox cp .env.example .env # 填写 DATABASE_URL、ANTHROPIC_API_KEY、tokens just neon-setup # 或使用您自己的 Postgres（直接连接字符串） just sandbox-build # 构建沙盒运行器镜像 just dev # LiteLLM 网关 + Rust 服务器 + 仪表板 ``` 然后打开 <http://localhost:3000>，或从 CLI 驱动运行： ```bash cargo run -p fluidbox-cli -- run --repo /path/to/repo --task "修复失败的测试" ``` 每个旋钮都在 [`.env.example`](./.env.example) 中内联记录。 ## 架构 ``` ┌────────────────────────── 控制平面（Rust） ──────────────────────────┐ 仪表板 │ /v1 公共 API 编排器 策略引擎 审批 SSE 流 │ CLI ─────▶ │ /内部网关 ◀── 权限检查、事件、心跳、结果 │ webhooks │ /内部/LLM 外观 ◀── 预算停止、计量、凭证交换 │ └───────────▲──────────────────────────────┬──────────────────────────────┘ │ 运行者合约 │ 代理工具、Git 获取、 ┌───────────┴───────────┐ │ LiteLLM → 模型提供者 │ 可丢弃的沙盒 │ ▼ │ （代理执行环境，无 │ 密封凭证 │ 真实凭证） │ （从不进入沙盒） └───────────────────────┘ ``` - [`docs/ARCHITECTURE.md`](./docs/ARCHITECTURE.md) — 运行流程、安全模型和扩展缝隙。 - [`PLAN.md`](./PLAN.md) — 权威设计文档：北极星、收敛不变量、里程碑。 ### 仓库布局 ``` crates/fluidbox-core 纯领域：策略引擎、事件、状态机、特征 crates/fluidbox-db sqlx 仓库、迁移、监听/通知 crates/fluidbox-provider Docker 提供者（下一个是 Lambda MicroVM 提供者） crates/fluidbox-server axum API + SSE + 编排器 + LLM 会话外观 crates/fluidbox-cli `fluidbox` 命令 apps/web Next.js 仪表板 images/sandbox-runner Claude Agent SDK 运行者镜像 images/codex-runner Codex 运行者镜像（第二个执行环境） images/runner-lib 共享运行者合约客户端 deploy/ docker-compose + LiteLLM 配置 migrations/ SQL 迁移（嵌入式；启动时自动运行） policies/ 种子策略 YAML ``` ## 状态 fluidbox **早期且快速发展**，但上述所有内容都已实现，并由端到端验收套件（`just e2e`）覆盖：受控的实时运行、审批、Git 工作区、API/webhook/调度触发器、GitHub PR 分发、能力目录、连接器 OAuth 和两个执行环境。接下来是 [路线图](./PLAN.md#7-milestones) 上的内容：AWS Lambda MicroVM 执行提供者和自带云。 在标记版本发布之前，请期待破坏性更改；[变更日志](./CHANGELOG.md) 跟踪了已落地的内容。 ## 贡献 欢迎贡献 — 错误报告、文档和代码。从 [CONTRIBUTING.md](./CONTRIBUTING.md) 开始，了解开发设置和质量标准（`just check` 和，对于治理路径更改，`just e2e`）。架构更改必须保留 [`PLAN.md` §2](./PLAN.md) 中的收敛不变量。 发现安全问题？请 **不要公开问题** — 参见 [SECURITY.md](./SECURITY.md)。 ## 许可证 [MIT](./LICENSE) © fluidbox 贡献者。