Sandcastle 中文教程：用 Docker 编排编码 Agent 与 Git 分支
Sandcastle 是 TypeScript 编排库，解决的是编码 Agent 怎样进入 sandbox、在哪个 Git 分支工作，以及完成后怎样把提交带回。它不会提升模型本身的代码能力，安全边界也取决于你选的 provider、挂载、凭据和分支策略。
1. 它怎样处理代码改动
run() 把 Agent、提示和 sandbox 连接起来。SandboxProvider 负责环境生命周期，AgentProvider 负责调用编码工具，branchStrategy 决定改动落点。head 直接作用于当前工作区，merge-to-head 先在临时 worktree 工作再合并，branch 把结果留在命名分支。
Docker 和 Podman 属于 bind-mount provider，可以把宿主目录或 worktree 挂到容器中；Vercel 属于隔离 provider，会把仓库同步到云端 microVM，再将结果带回。两类方案的默认 branchStrategy 不同，迁移 provider 时应重新核对行为。
2. 安装和初始化
npm install --save-dev @ai-hero/sandcastle npx @ai-hero/sandcastle init # 检查生成的 .sandcastle/main.ts、prompt、Dockerfile 和 .env # 填入 CLAUDE_CODE_OAUTH_TOKEN 或 ANTHROPIC_API_KEY npx tsx .sandcastle/main.ts
前置条件是 Git、Node/TypeScript 环境和一个 sandbox provider。官方列出 Docker Desktop、Podman、Vercel 与自定义 provider。先在非生产仓库初始化，打开生成文件，确认安装依赖的命令、hook、挂载目录、网络访问和注入的环境变量。
3. 第一次运行怎样收紧范围
使用可丢弃分支，只给一个能快速验收的小任务，例如修改一处文档并运行单个 lint。完成后检查提交落在哪个分支、未提交文件如何处理、失败时 worktree 是否保留，以及日志有没有泄露凭据。Docker 容器不是“看不见宿主”的保证；bind mount 允许访问被挂载路径，应只挂任务所需目录。
noSandbox() 会直接在宿主机运行 Agent。它适合外层已经是受控容器或虚拟机的情况，不适合拿来执行不可信提示或无人看守任务。v0.12.0 新增的 sandbox.exec(command, options?) 可以在同一个暖环境运行测试和 lint；非零退出码放在 ExecResult 中，不会自动抛错，调用方要显式判断。
4. 版本和费用边界
Sandcastle 仍是 0.x。CHANGELOG 已记录 branchStrategy、provider 导入和结果类型等破坏性变化，现有自动化应固定 @ai-hero/sandcastle 版本，并在升级时逐段阅读变更。Vercel sandbox、模型 API 或 Agent 订阅可能产生费用；项目自身是 MIT 开源包，本轮没有发现它经营付费分发或转售漏斗。
5. 与 E2B 对比
E2B 官方项目 提供云端隔离 sandbox 基础设施和 JavaScript/Python SDK，重点是创建环境、执行命令、传文件与暴露端口。Sandcastle 位于上层，负责选择编码 Agent、组织提示、管理 worktree 和回收提交。需要通用云执行环境时看 E2B；需要 TypeScript 中的编码 Agent 与 Git 编排时看 Sandcastle。
这里仅补原教程没有展开的事实和边界。安装命令与操作步骤仍以前文为准。
先判断这个项目是否适合你
适合谁用
适合并行运行多个后台编码任务、建立实现与复核流水线、在 CI 中让 Agent 修改分支，或在一个暖 sandbox 内连续运行 Agent 和验证命令。单次交互任务可以直接使用原 Agent CLI；没有容器或远程隔离边界时，不应把 noSandbox() 当成安全替代。
采用建议
Sandcastle 适合已经把 Git、容器和 Agent 凭据管好的 TypeScript 团队。先锁定版本，选清 provider 与 branchStrategy，再用小任务验证提交回收和失败清理；只要权限、挂载或 noSandbox() 没说明白，就不宜接入自动执行。
原教程未展开的系统信息
核心功能
统一的 Agent 编排入口
run() 负责启动 Agent、传入提示、收集迭代与提交；createSandbox() 可保留一个暖 sandbox，在多次运行之间复用环境。
结构化结果与 sandbox.exec
提示词管线支持参数、动态上下文和结构化输出。v0.12.0 又为 Sandbox handle 增加 exec()，可在同一环境运行测试或 lint，并以 ExecResult 返回非零退出码。
架构与数据流
Sandcastle 把 AgentProvider、SandboxProvider、提示词处理和 Git 同步分开。bind-mount provider 把宿主目录或 worktree 挂进 Docker/Podman；isolated provider 把仓库同步进远端或独立环境，再将提交、diff 和文件带回。branchStrategy 决定结果进入当前 HEAD、合并回 HEAD 或保留在命名分支。Orchestrator 串联提示、Agent 事件、sandbox 生命周期、提交和日志。
常见问题
Sandcastle 的 Docker provider 等于完全隔离吗？
不等于。bind mount 会让容器访问被挂载的宿主目录，仍需限制挂载、凭据和网络，并在可回滚分支里测试。
可以用 noSandbox() 跑不可信任务吗？
不应该。noSandbox() 直接在宿主执行，只适合外层已经有可信隔离的环境。
v0.5.x 的 Sandcastle 示例还能直接用于 v0.12.0 吗？
不能先假定兼容。0.x 期间公开 API、branchStrategy 和 provider 路径已有变化，应按锁定版本的 README、类型和 CHANGELOG 核对。
使用 Sandcastle 一定要购买 Vercel Sandbox 吗？
不一定。官方也支持本地 Docker Desktop、Podman 和自定义 provider；模型凭据与费用仍需另行评估。