Pi-Anvil（pi-sandbox）

一个任务委派型 MCP 服务器：把编码任务派给跑在加固沙箱里的 coding agent，产出以 diff 形式回来，人审后 apply 或 discard。

状态：M0–M9 服务端里程碑 + Web M0–M4 已实现，v0.2.0。这是个人项目，代码与文档都在持续演进。

它解决什么问题

让 AI 写代码的常见困境是：要么让它直接在你的工作区里乱改，要么把它关在门外什么都干不了。Pi-Anvil 走中间那条路——

agent 在沙箱里干活，宿主文件系统只接受经过审查的变更集。

具体是四件事：

1. 委派：通过 MCP 工具下发任务，agent（Pi）在一次性容器里执行，宿主与它之间只走协议

2. 隔离：Docker + gVisor/Kata 可选，附 seccomp 策略；模型 API 走一条独立的 TCP 桥，用一次性 token 认证，agent 拿不到真凭据

3. 可审：所有变更以 baseline diff 回来，带风险评估（risk assessment），你可以 apply 或 discard

4. 可查：HMAC 链式审计日志、指标、会话子系统、备份/恢复

Related MCP server: agent-bridge-mcp

架构

MCP client (Claude / Pi / 任意 MCP 宿主)
        │  stdio
        ▼
  src/mcp/        工具面：任务下发、状态查询、diff 取回、apply/discard
        │
        ▼
  src/engine/     scheduler → pipeline → reconcile
                  ├─ runners/docker    容器内跑 agent（gVisor/Kata + seccomp）
                  ├─ runners/fake      无 Docker 时的测试替身
                  ├─ baseline-diff     变更集计算
                  ├─ risk              风险评估与分级
                  ├─ apply             落盘（状态机驱动，discard 后不可绕过）
                  ├─ verification      干净性校验（PRD 13.5）
                  ├─ cache             含密钥中毒检测（AKIA/私钥/ghp_ 等模式）
                  └─ sessions          会话生命周期
  src/core/       config · crypto（provider key 加密存储）· secrets · audit(HMAC)
                  fsx(原子写) · backup · events · db · ids · errors
  src/http/       daemon + REST/SSE API（一次性 token 认证）
  runtime/        沙箱镜像构建、pi-adapter、model-bridge、worker
  web/            SPA 控制台：聊天页 / 模型配置页 / 控制台，SSE 实时事件

快速开始

要求：Node ≥ 22.19，TypeScript 5.9，Docker（可选，无 Docker 时用 fake runner 跑测试）。

npm install
npm run build          # tsc
npm test               # vitest
npm run check          # biome + tsc --noEmit（含 web 的 tsconfig）

npm run build:web      # 前端产物
node dist/cli.js       # 起 MCP 服务器

沙箱镜像：

node runtime/build-image.mjs

安全设计上的几个取舍

• agent 永远拿不到 provider 凭据：模型请求经 runtime 里的 model-bridge 转发到宿主，宿主侧用一次性 token 认证后再打给真端点；配置文件里的 API key 是加密存放的

• apply 不可绕过状态机：discard 之后不能直接落盘（这条有专门的回归测试，见 13914e6）

• 缓存写入前做密钥中毒检测：外部内容里出现 AWS AKIA / 私钥块 / GitHub token 形态的字符串会被拦下，避免被投毒的上下文把凭据带进缓存

• 审计是 HMAC 链式的：事后篡改单条记录会被发现

• 文件系统写入全走原子写（fsx），避免半写状态

测试

• test/unit/ 38 个单元测试文件，覆盖 engine / core / http / policy

• test/e2e/ + e2e-state/ 端到端与压力脚本：会话生命周期、协议边界、并发、终态顺序

• 里程碑是按 TDD 推的，提交信息里保留了 red-green 轮次记录

与上游 Pi 的关系

本项目的 agent 侧适配的是 earendil-works/pi（runtime/src/pi-adapter.ts）。Pi 是别人的开源项目，本仓库不包含它的源码，只包含对接它的适配层。

文档

docs/ 下是两份设计文档（PRD），记录了里程碑定义、协议细节和验收条件：

• docs/Pi_Sandbox_MCP_Server_PRD_v1.10.md — 服务端

• docs/Pi_Sandbox_Web_Frontend_PRD_v1.0.md — Web 前端

License

MIT — 见 LICENSE。