项目简介
Sandcastle 是一个 TypeScript 库，可在隔离沙箱中运行 AI 编码代理，内置支持 Docker、Podman 和 Vercel。它提供编程 API 处理沙箱、分支和合并提交，支持并行代理执行和审查流水线。
README 预览
\n \n \n \n \n \n\n\n## What Is Sandcastle?\n\nA TypeScript library for orchestrating AI coding agents in isolated sandboxes:\n\n1. You invoke agents with a single `sandcastle.run()`.\n2. Sandcastle handles sandboxing the agent with a configurable branch strategy.\n3. The commits made on the branches get merged back.\n\nSandcastle is provider-agnostic — it ships with built-in providers for Docker, Podman, and Vercel, and you can create your own. Great for parallelizing multiple AFK agents, creating review pipelines, or even just orchestrating your own agents.\n\n## Prerequisites\n\n- [Git](https://git-scm.com/)\n- A sandbox provider — Sandcastle needs an isolated environment to run agents in. Built-in options:\n - [Docker Desktop](https://www.docker.com/) — most common for local development\n - [Podman](https://podman.io/) — rootless alternative to Docker\n - [Vercel](https://vercel.com/) — cloud-based Firecracker microVMs via `@vercel/sandbox`\n - Or [create your own](#custom-sandbox-providers) using `createBindMountSandboxProvider` or `createIsolatedSandboxProvider`\n\n## Quick start\n\n1. Install the package:\n\n```bash\nnpm install --save-dev @ai-hero/sandcastle\n```\n\n2. Run `sandcastle init`. This scaffolds a `.sandcastle` directory with all the files needed.\n\n```bash\nnpx sandcastle init\n```\n\n3. Edit `.sandcastle/.env` and fill in your default values for `ANTHROPIC_API_KEY`. If you want to use your Claude subscription instead of an API key, see [#191](https://github.com/mattpocock/sandcastle/issues/191).\n\n```bash\ncp .sandcastle/.env.example .sandcastle/.env\n```\n\n4. Run the `.sandcastle/main.ts` (or `main.mts`) file with `npx tsx`\n\n```bash\nnpx tsx .sandcastle/main.ts\n```\n\n```typescript\n// 3. Run the agent via the JS API\nimport { run, claudeCode } from "@ai-hero/sandcastle";\nimport { docker } from "@ai-hero/sandcastle/sandboxes/docker";\n\nawait run({\n agent: claudeCode("claude-opus-4-7"),\n sandbox: docker(), // or podman常见问题 (3)
how_to如何在sandcastle中跨多个提示继续代理对话？
how_to
如何在sandcastle中跨多个提示继续代理对话？在由 run() 返回的 RunResult 对象上调用 resume(prompt) 方法。示例：const r = await run({ agent: claudeCode('claude-opus-4-6'), sandbox: docker(), prompt: 'draft a plan' }); await r.resume('now execute the plan');。这样可以延续代理会话并保留完整上下文，无需手动传递 sessionId，同时避免重建沙箱。该方法在 @ai-hero/sandcastle 中可用。
故障排除为什么 createSandbox 在多次运行同一分支时会保留一个过时的分支？
故障排除
为什么 createSandbox 在多次运行同一分支时会保留一个过时的分支？沙盒会复用首次运行时的本地分支克隆，因此后续运行不会拉取最新更改。解决方法：添加一个 onSandboxReady 钩子，在工作空间中执行 git pull origin <branch>。
故障排除当shell扩展超时导致@ai-hero/sandcastle中整个运行崩溃时，如何修复"PromptExpansionTimeoutError"？
故障排除
当shell扩展超时导致@ai-hero/sandcastle中整个运行崩溃时，如何修复"PromptExpansionTimeoutError"？对提示中的shell命令应用重试包装。例如，将!\\gh api graphql ...\\`替换为!\\for i in 1 2 3; do gh api graphql ... && break; sleep 2; done\\`。这可以处理诸如令牌缓存争用或API停滞等短暂故障。在上游库添加原生重试之前（跟踪问题#617），此手动循环可防止单次超时中止AFK运行。如果争用持续存在，减少并行的沙盒代理。