bb 环境供给机制解析：从 Git Worktree 到 Modal 沙箱，环境如何自动创建与清理
【免费下载链接】bbThe agent IDE that builds itself项目地址: https://gitcode.com/gh_mirrors/bb14/bb
bb是一个"会自我构建"的 Agent IDE：当你给 AI 线程（Thread）发出第一条消息时，它会自动创建并清理一套隔离的运行环境——本地用 Git worktree 开一个独立工作区，云端用 Modal 沙箱拉起一台完整的机器。本文带你快速看懂 bb 环境供给机制的完整链路：环境如何自动创建、状态如何流转、又如何优雅地自动清理。
一、什么是环境供给：Agent 的"出生地"
在 bb 中，每个线程运行前都需要一个环境（Environment）。环境在数据库里先占位，状态机从creating开始，经过provisioning（守护进程挂载与初始化），最终到达ready或error。
整个"出生"过程由服务端的环境引擎统一掌管，负责推进、取消、清理与退役：
- 环境引擎源码：environment-engine.ts
- 官方设计文档：docs/environment-provisioning.md
关键设计：核心（Core）负责持久化启动、重试、取消、退役与拆除；插件只负责资源的创建与删除。职责分离让环境生命周期在服务重启后也能安全恢复。
二、4 个内置环境提供者：按需选择工作区形态
bb 内置了 4 个环境提供者插件，覆盖"本地轻隔离"到"云端重资源"的全部场景：
1️⃣ 项目检出（Project Checkout）
让线程直接跑在已检出的项目目录里。它支持当前分支 / 已有分支 / 新建分支三种模式；如果工作区有未提交改动、或有其他活跃线程占用，会拒绝切换分支，避免互相踩踏。移除时保留检出目录不动。
- 插件源码：plugins/environment-project-checkout/
2️⃣ Git Worktree 隔离工作区
每个子线程默认获得一个全新的 Git worktree：从项目检出中隔离出一个独立目录，互不干扰，天然支持多任务并行。核心引擎退役环境后，插件会删除自己拥有的 worktree；复用的已有 worktree 则保持所有权不变、退役后保留在磁盘上。
- 插件源码：plugins/environment-git-worktree/
- 工作区输入与主机端 Git 原语：packages/environment-provider-host/（Git 执行、工作区锁、进度信号、provisioning 转录等）
3️⃣ 个人工作区（Personal Workspace）
面向无项目的轻量工作：在已注册机器上为每个线程创建独立目录；无项目的子线程共享父环境，最后一个线程归档后由核心退役该目录。
- 插件源码：plugins/environment-personal-workspace/
4️⃣ Modal 云端沙箱（Modal Sandbox）
最"重"也最强大的一种：在 Modal 上自动拉起一台可复用的云端机器。
它的亮点包括：
- 标准镜像：插件自带 Dockerfile，内含 Debian、Node、Git/GitHub CLI、构建工具、Python、bubblewrap、ripgrep、jq、pnpm、Pi、Codex 与 Claude Code。镜像按 Dockerfile 的 SHA-256 命名并在 Modal 账户内复用，首次启动自动构建发布，之后直接复用缓存。
- 幂等初始化钩子：核心会自动克隆选定项目并执行项目里的
.bb-env-setup.sh（装依赖、起服务），失败会显示在启动日志中；由于文件系统恢复后会重跑，该钩子必须幂等。拆除时执行核心的.bb-env-teardown.sh钩子。 - 暂停与快照：空闲默认 15 分钟自动暂停（先快照文件系统再终止算力），恢复时复用已注册的守护进程，不重跑 setup；算力寿命封顶 Modal 的 24 小时，超时前记得暂停以保存工作。
- 安全设计：引导凭据通过 stdin 传入，绝不落盘到机器资源中。
- 详细文档：plugins/environment-modal-sandbox/README.md
三、环境如何自动创建：一条消息触发的完整链路
整个流程无需人工干预，典型链路如下：
- 线程发出首条消息→ 服务端的线程放置逻辑（thread-environment-placement.ts）验证选定提供者并预留环境（
claimPath先占位，防止并发线程抢占同一路径）； - 引擎推进状态→ 提供者插件在注册机器上执行资源创建（建 worktree / 克隆项目 / 分配沙箱），进度与日志通过
pendingLog缓冲后并入线程转录； - 守护进程挂载→ 核心按需安装 BB daemon、注册机器并等待连接（Modal 场景下会先等待持久化资源检查点，确保取消时不必重新分配）；
- 状态到达
ready→ 首条消息被消费，环境正式交付线程使用。
创建失败是终态（记录错误并完成拆除，不会把路径交给删除流程）；但 setup 失败可以在同一环境上重试，无需重建工作区。周期性清扫（periodic sweep）还能在服务重启后恢复未完成的创建流程——详见 docs/environment-provisioning.md。
四、环境如何自动清理：从退役到拆除
bb 的清理策略简单而安全：
| 场景 | 清理行为 |
|---|---|
| 线程归档 / 取消 | 取消会等待进行中的创建落定后再移除资源 |
| 共享环境 | 保留到最后一个活跃线程离开，按提供者宽限期退役 |
| 个人工作区 | 最后一个线程归档后退役目录 |
| Worktree | 核心退役环境后删除自己拥有的 worktree |
| Modal 沙箱 | 手动 / 空闲暂停时先快照再停机；bb machine remove MACHINE --yes显式删除（保留共享标准镜像） |
| 清理失败 | 沿用既有拆除状态与重试截止时间；待清理状态可跨越提供者不可用或服务重启存活 |
此外，提供者卸载前，引擎会先取消该插件名下所有未完成的创建任务（thread-environment-providers.ts），保证卸载不留"孤儿环境"。
五、上手速查：常用命令与关键文件
bb environment providers --json # 查看所有环境提供者的输入与可用性 bb thread spawn --environment-provider git-worktree # 用 worktree 隔离工作区启动线程 bb machine create --provider modal-sandbox --json # 创建 Modal 云端沙箱 bb modal account inspect --json # 校验 Modal 凭据（不分配资源） bb modal image show / set --file ./Dockerfile / reset # 查看、覆盖、重置标准镜像 bb machine list --json # 查看核心侧机器状态📁 相关模块速览：
- 环境供给设计文档：docs/environment-provisioning.md
- 主机端共享原语（Git、锁、进度、转录）：packages/environment-provider-host/src/
- Worktree 提供者：plugins/environment-git-worktree/
- Modal 沙箱提供者：plugins/environment-modal-sandbox/
- 环境引擎：apps/server/src/services/environments/
写在最后
bb 的环境供给机制体现了一个清晰的工程思想："核心管生命周期，插件管资源本身"。无论你是想在本地用 Git worktree 并行跑多个任务，还是想在 Modal 云端拉起一台带完整工具链的沙箱机器，只需发出第一条消息，环境就会自动创建、自动就绪、并在任务结束后被自动清理——把运维工作留给系统，把创造力留给你的 Agent。
【免费下载链接】bbThe agent IDE that builds itself项目地址: https://gitcode.com/gh_mirrors/bb14/bb
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
