Task Runner POC — 技术选型与架构

把单条 Task 在容器里完整跑完 explore → propose → apply → archive 四阶段，输出真实 GitHub PR，并把 status / stage / diff stats 实时回传到主 API。本期 POC 同时验证两条部署路径：公有云（Fly Machines）+ 私有化（VPS + Docker），通过 Sandbank 沙箱中间层抽象切换。

公有云栈

Fly Machines

私有化栈

VPS + Docker + Sandbank

Agent SDK

Claude Agent SDK

工期估算

~13 工作日

§1 背景

现状缺口与本期目标。

openspec/specs/tasks/spec.md 已经定义了 Task 数据模型、4 个 REST API 和 3 张设计稿（04 / 04a / 04b）。缺失的是执行引擎—— status: proposing → running → awaiting_review → done 和 stage: explore → propose → apply → archive 这些字段被前端 MiniStages 拿来画动画，但没有任何后端代码会真正推进它们。

§2 影响选型的硬约束

下表所列的每条约束都会拍掉一批候选——选型不应以”功能丰富”为先，而应以”红线不踩”为先。

§3 云端容器：7 选 1

速览矩阵 + 每个候选的展开。✩ = 5 分制契合度。

3.1 Fly Machines（POC 首选）

3 个决定性因素让 Fly 跑赢其他候选：

API 调用形态

# 主 API 调 Fly Machines REST 创建一台短命机器
POST https://api.machines.dev/v1/apps/openspec-task-runner/machines
{
  "config": {
    "image": "ghcr.io/openspec/task-runner:latest",
    "env": {
      "TASK_ID": "<uuid>",
      "INSTALLATION_TOKEN": "<short-lived>",
      "ANTHROPIC_API_KEY": "<key>",
      "CALLBACK_URL": "https://api.douglasdong.com/internal/tasks/<id>/events"
    },
    "auto_destroy": true,
    "guest": { "cpu_kind": "shared", "cpus": 4, "memory_mb": 4096 }
  }
}

劣势

• 没有现成 SDK，要包装 Fly Machines REST API（增量 ~150 行 NestJS service）
• 没有原生 sandbox 抽象（但 microVM 隔离已足够）
• 状态回传要自己实现 HMAC 验签 + callback URL pattern

3.2 备选与排除理由

§4 Agent SDK：Claude vs Codex

头部 2 个候选并排对照。OpenAI Agents SDK / Vercel ToolLoopAgent / LangGraph 三者契合度 ≤ ★★，本节略去。

4.1 并排对照

4.2 决定性差异速读

4.3 Skill 加载机制再评估（承认上一版表述偏激）

修正后的判定：差异从”原生支持 vs 完全不识别”降级为”自动按需加载 vs 手工引导 + 全量常驻”。Claude 仍占优，但优势主要在 token 效率和实施代码量，不在”能不能跑通”。

4.4 鉴权复杂度并排

4.5 速率限制与并行能力

POC 阶段单任务串行可忽略，但只要规划 ≥ 5 并发就要正视。下表汇总 API 层（不算容器层）的速率限制。

**关键洞察：**对 POC 来说，API tier 限制远远高于业务实际需要的并发——5 task 并发 × 平均 30s 一次 API 调用 ≈ 10 RPM，连 Tier 1 都不会触顶。瓶颈不在 SDK / 模型一侧，而在主 API 怎么管”同用户/同仓库的 task 并发”。

4.6 推荐用法示意

import { query } from "@anthropic-ai/claude-agent-sdk";
 
// 在容器入口 run.js 内执行
for await (const msg of query({
  prompt: "/opsx:propose " + task.prompt,
  options: {
    cwd: "/workspace/repo",
    settingSources: ["project"],            // ← 容器内 user 级通常为空
    skills: "all",
    allowedTools: ["Bash", "Edit", "Write", "Read", "Grep", "Glob"],
    permissionMode: "bypassPermissions",   // ← 容器必须 non-root（S7/S8 实测：claude binary 拒绝 root + bypassPermissions）
    maxTurns: 200,
    hooks: {
      PostToolUse: [{
        matcher: "Write",
        hooks: [async (input) => {
          const fp = input.tool_input?.file_path ?? "";
          if (fp.endsWith("/proposal.md")) {
            await reportStage("propose", "done", fp);
          }
          return {};
        }],
      }],
    },
  },
})) {
  if (msg.type === "result") {
    await reportStage("propose", "done", msg);
  }
}

4.7 何时反悔切回 Codex SDK

1. Anthropic API 严重不可用或配额政策大变
2. 核心任务在 GPT-5 推理模型上效果显著更好
3. 业务需要”双 Agent 互评”（Claude 提案 + Codex review）

前两个是完全切换场景，到那时做一次完整迁移评估更划算；只有第 3 个会让两者并存。POC 阶段不必为这种弹性做投资。

§5 容器机器成本估算（联网校准）

所有数字均为 2026-05 联网拉到的官方公开价。只算基础设施成本，Token 成本是 Agent SDK / 模型选型的独立维度，不在本节范围。

5.1 真实月度账单（按规模档 · 已扣 free tier）

5.2 规模化（5K task/月）月度账单可视化

5K task/月真实月度账单 · 已扣 free tier
$0 ──────────► $1,064

Fly shared-8x  (4GB)         ▮▮▮▮▮▮▮▮                                   $92    (1x)
Fly perf-2x    (4GB)         ▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮                       $223   (2.4x)
E2B Hobby      (4 vCPU·4GB)  ▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮ $666   (7.2x)
E2B Pro        (+$150/月)    ▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮ $816 (8.9x)
Cloudflare     (4 vCPU·8GB)  ▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮ $905 (9.8x)
Vercel Pro     (4 vCPU·8GB)  ▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮ $1,064 (11.6x)

5.4 数据精度说明

① 单价来自 2026-05 官方公开 pricing 页面（见 §12 参考资料）。 ② I/O wait 50% 假设是中等估算——Claude task 实际 I/O 占比 30-60%，意味着 Vercel 数字波动范围 $0.6x-$1.4x。 ③ Egress 流量在月度量级下可忽略（150 MB × 5K = 750 GB，Fly NA/EU 区 $0.02/GB ≈ $15 在 $92 容器费上 +16%）。如果跨区域流量大需单独算。 ④ 不含模型推理 token 成本（独立维度，由你评估）。 ⑤ 实际生产成本还有冷启动重试、监控、Postgres、Egress 跨区域等——这些是各家通用的，不影响选型决策。

5.5 死循环 / 账单失控防护（重要）

用户反馈：“避免 Cloudflare 这种由于死循环直接刷 10000 刀以上的案例”——这是基于真实社区报告的合理担忧。下表对各候选的自带防护与必须自建的防护做并列。

POC 必须落地的防护清单（多层）

§6 POC 推荐架构

三层拓扑 + 状态机推进 + 关键接口契约。

6.1 拓扑图 · 可插拔双轨

关键设计：Sandbank 沙箱中间层 隔离”主 API 的派发逻辑”与”具体后端”。POC 同时启用 FlyAdapter 和 BoxLiteAdapter 两个 adapter，容器入口 run.js 完全相同。

┌─────────────────────────────────────────────────────────────────────────┐
│  WEB · VERCEL                                                            │
│  ┌───────────────────────────────────────┐                               │
│  │ apps/web · Next.js                    │                               │
│  │   POST /tasks                         │                               │
│  │   GET /tasks/:id/events (SSE)         │                               │
│  └───────────────────────────────────────┘                               │
│              │ HTTPS · session                                            │
│              ▼                                                            │
│  API · FLY.IO                                                            │
│  ┌──────────────────────────────────────────────────────────────┐        │
│  │ apps/api · NestJS                                            │        │
│  │  ┌──────────────────────────┐  ┌─────────────────────────┐   │        │
│  │  │ TasksController          │→ │ TaskEventsController     │   │        │
│  │  │  + POST /tasks/:id/      │  │  POST /internal/tasks/  │   │        │
│  │  │    dispatch              │  │    :id/events           │   │        │
│  │  │  + GET /tasks/:id/events │  │  HMAC 验签 + SSE 广播   │   │        │
│  │  └──────────────────────────┘  └─────────────────────────┘   │        │
│  │  ┌─────────────────────────────────────────────────────────┐ │        │
│  │  │ Sandbank · 沙箱中间层（多 backend 抽象）            │ │        │
│  │  │   provider.create / exec / destroy                       │ │        │
│  │  │   按 env 切换 adapter — 业务代码 99% 共用                 │ │        │
│  │  │   — 公有云 / 私有化双轨切换的核心抽象 —                    │ │        │
│  │  │   ↓ 两个 adapter                                          │ │        │
│  │  │   FlyAdapter（内置）                                │ │        │
│  │  │   BoxLiteAdapter（内置）                            │ │        │
│  │  │   （详见 §6.1.2 - §6.1.4）                                 │ │        │
│  │  └─────────────────────────────────────────────────────────┘ │        │
│  └──────────────────────────────────────────────────────────────┘        │
│      │ FlyAdapter                          │ BoxLiteAdapter               │
│      ▼                                     ▼                              │
│  ⬢ 公有云 · FLY MACHINE            ▣ 私有化 · VPS DOCKER      │
│  ┌──────────────────────────────┐    ┌────────────────────────────────┐  │
│  │ 短命 Machine (auto_destroy)  │    │ BoxLite microVM (via Sandbank) │  │
│  │  guest: 4 vCPU / 4 GB        │    │  host: 普通 Linux VPS (KVM)    │  │
│  │  spec: shared-cpu-8x         │    │  isolation: microVM (每 task)  │  │
│  │  ┌────────────────────────┐  │    │  ┌──────────────────────────┐  │  │
│  │  │ run.js (容器入口)       │  │    │  │ run.js (同一份代码)        │  │  │
│  │  ├────────────────────────┤  │    │  ├──────────────────────────┤  │  │
│  │  │ 1. git clone + checkout│  │    │  │ 1. git clone + checkout  │  │  │
│  │  │ 2. /opsx:explore →     │  │    │  │ 2-4. 同公有云路径         │  │  │
│  │  │      propose           │  │    │  │ 5. 同公有云路径           │  │  │
│  │  │ 3. /opsx:apply         │  │    │  └──────────────────────────┘  │  │
│  │  │    (typecheck+lint)    │  │    │                                │  │
│  │  │ 4. /opsx:archive +     │  │    │  callback: Tailscale tailnet   │  │
│  │  │      git push          │  │    │   (私有，26ms) 或公网 HTTPS    │  │
│  │  │ 5. curl POST /pulls +  │  │    │   (239ms · HMAC)              │  │
│  │  │      report 完成        │  │    │                                │  │
│  │  └────────────────────────┘  │    │ 同一镜像 ghcr.io/openspec/     │  │
│  │ 同一镜像 ghcr.io/openspec/   │    │  task-runner                   │  │
│  │  task-runner                 │    │                                │  │
│  └──────────────────────────────┘    └────────────────────────────────┘  │
│              ╲                              ╱                             │
│               ╲   两条路径的 callback 都打回同一个 events controller   ╱  │
│                ╲                          ╱                              │
│                 ◀──── (异步回调 dashed) ◀──                              │
└─────────────────────────────────────────────────────────────────────────┘

Legend:
主进程/服务 ▢  抽象接口（虚线）▭  公有云容器  私有化容器
── 实时数据流   ┄┄ 异步回调

6.1.1 沙箱中间层 · 用 Sandbank（不自定义 Provider）

Sandbank Provider 接口形态

import { createProvider, FlyAdapter, BoxLiteAdapter } from "sandbank";
 
// 按 env 切换 — 业务代码 99% 共用
const provider = process.env.TASK_RUNNER_MODE === "private"
  ? createProvider(new BoxLiteAdapter({ /* ... */ }))
  : createProvider(new FlyAdapter({ apiKey: process.env.FLY_API_TOKEN }));
 
// 派发一个 task — 容器入口由 image 决定
const sandbox = await provider.create({
  image: "ghcr.io/openspec/task-runner",
  env: {
    TASK_ID: task.id,
    INSTALLATION_TOKEN: installationToken,
    ANTHROPIC_API_KEY: process.env.ANTHROPIC_API_KEY,
    CALLBACK_URL: `https://api.douglasdong.com/internal/tasks/${task.id}/events`,
    HMAC_SECRET: process.env.TASK_HMAC_SECRET,
    REPO_FULL_NAME: branch.repoFullName,
    AGENT_BRANCH: agentBranch,
    PROMPT: task.prompt,
  },
});
 
// 容器内 run.js 串行跑 4 阶段，结束后 sandbox.destroy()

6.1.2 三个中间层候选对比

Sandbank 详解

import { createProvider, FlyAdapter, BoxLiteAdapter } from "sandbank";
 
// 按 env 切换 — 业务代码 99% 共用
const provider = process.env.TASK_RUNNER_MODE === "private"
  ? createProvider(new BoxLiteAdapter({ dockerHost: '...' }))
  : createProvider(new FlyAdapter({ apiKey: process.env.FLY_API_TOKEN }));
 
const sandbox = await provider.create({ image: "ghcr.io/openspec/task-runner" });
const result = await sandbox.exec("/app/run.js");
await provider.destroy(sandbox.id);

修订后的设计决策

6.1.3 Sandbank 私有化接入完整度 + Fork 策略

用户提出的关键问题：Sandbank 对私有化的接入全吗？能不能 fork 改？深入核实后的事实：

BoxLite Adapter 能力完整度

来自上游 issue #2 的能力补充（2026-05-16 维护者回复）

调研中发现 chekusu/sandbank #2 维护者 @guo-yu 详述了各 adapter 的 persistence 能力——补充以下事实：

• BoxLite 是为”长期保留沙箱”设计的——配合 auto_remove: false + snapshot + sleep，维护者原话：“适合本机/自托管的长期保留沙箱”。本场景虽然是”每 task 一次性容器”，但未来如果想做 agent 状态延续（如人工 review 中途暂停 task），能力已现成。
• Fly.io adapter 也支持 volumes——已有集成测试覆盖 volume mount 写入读回。这意味着公有云路径也有持久化能力可选（POC 不用，但未来扩展不需切 backend）。
• Cloudflare adapter 支持 snapshot + volumes（配置 storage 时）。
• E2B adapter 上游仍在 TODO——我们已 fork 自实现：@douglas-agent/sandbank-e2b 提供 E2BAdapter + CubeSandboxAdapter（共享 E2BProtocolAdapter 基类）。详见 change add-sandbank-fork-aio-e2b。

BoxLite 适用范围

BoxLite adapter 背后用的是 BoxLite 的嵌入式 microVM 库。可跑的硬件覆盖了所有目标场景：

• Apple Silicon Mac（Hypervisor.framework）： S3 实测 M4 Mac mini 等效 KVM，PoC demo 推荐硬件
• 裸金属 / 主流云 VM： AWS / GCP / Hetzner / DigitalOcean 等开 nested virt 的环境

极少数仅 OpenVZ 类无虚拟化能力的 VPS 不在 POC 支持范围——这类客户应改选有 nested virt 的 VPS 或自带 Apple Silicon 硬件，不再保留”自写纯 Docker adapter”作为退路（容器内 Docker 没有 microVM 隔离边界，与本项目”每 task 一个独立沙箱”的安全前提冲突）。

Fork 可行性评估

两个 fork 改造方案

修订后的 POC 决策

6.1.4 其他私有化 Runtime 的 Sandbank 接入评估

除了 BoxLite，§10 列出的其他私有化 sandbox runtime（AIO Sandbox / Daytona OSS / Microsandbox / CubeSandbox / OpenSandbox / OpenHands / Docker sbx）——Sandbank 能不能接？逐个核实它们的接口形态后，结论是大多数都能在 1 天内接入。

接入难度矩阵（联网核实每个 runtime 的官方接口）

关键洞察

对原来”Sandbank 私有化支持”的修正

POC 阶段的最优组合（修订）

6.2 状态机推进

proposing ─ dispatch ▶ running / explore ▶ running / propose ▶ running / apply ▶ running / archive ─ PR 创建 ▶ awaiting_review ─ 合并 ▶ done

失败分支：running/* 任何阶段（含 proposing 阶段下游）若抛 SDK ERR / hard kill / API_retry 耗尽，→立刻转 failed，写 tasks.failedReason（max 1KB），SSE 推 type=failed 事件后退出。failed 终态，由 web 端给”重试”按钮（创建新 task）。proposal.md 中标记为 BREAKING change（status enum 加 failed）—— D7 已固化。

6.3 容器 → 主 API 的事件 callback

POST /internal/tasks/{taskId}/events
Content-Type: application/json
X-Task-Hmac: <hex of hmac-sha256(secret, body)>

{
  "type": "stage_change",            // | "log" | "completed" | "failed"
  "stage": "propose",
  "status": "running",
  "data": {
    "additions": 0,
    "deletions": 0,
    "filesChanged": 0,
    "logTail": "..."                 // 最近几行 stdout，用于 SSE 转发
  }
}

6.4 前端 SSE 事件流

GET /projects/:r/branches/:b/tasks/:t/events
→ SSE stream

event: stage_change
data: {"stage":"propose","status":"running"}

event: log
data: {"tail":"npm install completed in 47s"}

event: completed
data: {"prUrl":"https://github.com/owner/repo/pull/123"}

§7 POC 任务拆解（双轨）

粗粒度时间线 · 单人 ~13 工作日。双轨架构在 day 1 落地，不是远期改造。

公共部分（两条路径共用，9 项）

1. 设计 task_events 表 + Prisma schema — 0.5d
2. 接入 Sandbank · 配置工厂方法（按 env 切 FlyAdapter / BoxLiteAdapter，见 §6.1.1）— 0.5d
3. 主 API 加 POST /tasks/:id/dispatch（调 sandbank provider.create）— 0.5d
4. 主 API 加 POST /internal/tasks/:id/events（HMAC 验签）— 0.5d
5. 主 API 加 GET /tasks/:id/events（SSE）— 0.5d
6. 写 task-runner Docker 镜像（node:22-slim + bash + non-root + git + @fission-ai/openspec + Claude Agent SDK，平台无关）— 1d
7. 写 run.js 容器入口（git clone 用 x-access-token URL + 单 query() 调用 + PostToolUse hook 触发 stage_change，不依赖任何平台 API）— 2d
8. installation token 短命发放（复用现有 GitHub App 路径）— 0.5d
9. 前端 task 详情页接 SSE，MiniStages 实时更新 — 1d

公共小计 — 7d

⬢ 公有云路径（Fly Machines，3 项）

10. 配置 Sandbank FlyAdapter + Fly token 注入（§6.1.2）— 0.5d
11. 设置 Fly secrets · 部署到 staging — 0.5d
12. 真跑一遍 · 公有云路径：真实仓库 + 真 PR — 1d

公有云小计 — 2d

▣ 私有化路径（VPS + Docker，4 项）

13. 配置 Sandbank BoxLiteAdapter（详见 §6.1.3）— 1d
14. 准备一台 4 vCPU 8 GB 演示 VPS（Hetzner / DigitalOcean），装 Docker — 0.5d
15. 容器 → 主 API 的 callback 走公网 + HMAC（验证防火墙穿透）— 0.5d
16. 真跑一遍 · 私有化路径：从 VPS 跑通同一个 task — 1d

私有化小计 — 3d

联调与验收（2 项）

17. E2E：MSW 模拟两种 provider 的 dispatch + callback 链路 — 0.5d
18. 双轨切换演示：同一个 task，切换 env 后两条路径都能跑通 — 0.5d

POC 合计 — ~13d

§8 POC 验证清单

把前面 §1-§7 的调研结论凝结成可执行的验证矩阵。每条都对应一个具体决策点的不确定性——验证不过就要切换方案。

8.1 高优 spike（POC 启动前完成）· 状态总览

这些验证如果失败，整个 POC 设计要重做。2026-05-18 全部 8 个 spike 通过，详见 docs/spikes/。

spike 期间识别的额外架构发现

• ESM/CJS blocker · sandbank ESM-only，apps/api 原 CJS。已切 NodeNext ESM（实际 3 小时工作量，比预估 1-2 天快）。详见 docs/task-runner-sandbank-integration.md
• D11 双轨鉴权（design.md 新增决策）· 容器内 API key + 本地 dev SDK 自动 OAuth fallback
• Tailscale = 天然 callback 通道 · 跨网段不需要 cloudflared / ngrok
• 非 admin 用户也能私有化 · 用 uv 替代 brew 装 Python，全程不需要 sudo
• Cache hit rate 98%（S5 实测）· OpenSpec skill 是 stable system prompt，重复 turn 几乎零增量。S5 简单 prompt $1.15、S7 BST 复杂 prompt $3.03——cache 命中让重复 turn 几乎零增量，远低于”每 turn full input 重传”的一般 multi-turn 估算
• Agent 自主修复工程问题（S5 + S7 实测）· S5 typecheck 失败时主动 git stash 验证预存在问题；S7 OpenSpec CLI 缺失时手动 mkdir+mv 模拟 archive、自我反思修测试期望——LLM-as-engineer 真实表现稳定
• subapi 中转作为第三条鉴权路径（S7 实测）· 把 ANTHROPIC_BASE_URL 指向用户自管 subapi 实例，ANTHROPIC_API_KEY 用 subapi 内部 key——彻底绕开”OAuth 给容器外用”合规风险，但用户得自己运维 subapi。补强 D11 双轨 → 三轨
• 容器必须 non-root（S7 实测）· Claude Code binary 拒绝 root 用 --dangerously-skip-permissions。alpine 默认 root，要用 node:22-alpine 内置 node user（uid 1000）或 Dockerfile USER 切换
• BoxLite 实施细节（S7 实测）· 默认 disk 太小要 disk_size_gb=10；copy_in() 不可靠改用 base64 注入或 box 内 git clone；alpine 默认缺 ca-certificates + bash + ripgrep
• openspec 包名是 scoped（S8 实测）· 正确装法 npm install -g @fission-ai/openspec v1.3.1。npm 上的 openspec 是空占位包 v0.0.0 不要用
• git push 用 x-access-token URL 注入（S8 实测）· https://x-access-token:$TOKEN@github.com/owner/repo.git — 0 配置 credential helper，token 由 D11 容器内续期机制提供（GitHub App installation token）
• Fly base image 必须含 bash（S8 实测）· sandbank flyio adapter 内部 bash -c "<cmd>" 包装 exec。推荐 node:22-slim（Debian 自带 bash），不要用 alpine 默认
• 公有云 vs 私有路径实测对比（S8 实测）· Fly 启动 7.7s vs BoxLite macmini 1.5s（5x，cloud overhead 合理）；callback RTT Fly→subapi 239ms vs LAN 35ms（7x，跨 ocean）。印证 D2 双轨设计：私有低延迟，公有云弹性

8.2 实施期边做边验（POC 13 天中嵌入）

这些不需要前置 spike，但在对应任务完成时必须验证。

8.3 真跑验收（POC 完成时一次性 demo · §7 任务 12 + 16）

这是 POC 的”end-to-end 合格判定”——只有这一关过了，才能给团队/客户演示。

8.4 验证清单可视化（spike 优先级图）

spike 优先级（从上到下：阻塞性高 → 边做边验）        工期 0h ───► 0.5d

S1 Claude SDK + skills   (关键支点)        ▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮                     1-2h
S2 Sandbank 长任务       (新库稳定性)      ▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮  0.5d
S3 BoxLite + KVM         (私有化前置)      ▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮▮                            2h
S4 防火墙穿透            (私有化前置)      ▮▮▮▮▮▮▮▮                                    1h

§9 风险与未决问题

POC 落地前需要解的硬骨头。每个风险都对应 §8 验证清单里的一项。

1. Claude Agent SDK 在容器里加载本仓库 .claude/skills/ 的实际行为

   官方文档说 settingSources + skills:“all” 能加载，但本仓库 .claude/skills/openspec-* 是否 100% 兼容 SDK 期望的 SKILL.md 格式需要 spike 验证。 → 验证项 S1（POC 启动前 1-2h 完成）

2. 网络出口与 callback 路径

   容器要访问 api.github.com / api.anthropic.com；callback 回主 API 走公网或 Fly 内网。POC 阶段建议公网 + HMAC 验签更省事。 → 验证项 S4（私有化路径下额外要测防火墙穿透）+ I4（HMAC 验签）

3. Spec 缺一个 failed 状态值

   现有 status enum 只有 proposing/running/awaiting_review/done，跑失败没地方放。POC 实施前要先扩 spec。 → 验证项 E4（真跑阶段的故障容错演示需要这个状态值存在）

4. installation token 1h 过期

   GitHub App installation token 默认 1h，容器寿命 > 1h 会失效。需要在主 API 加 /internal/tasks/:id/token 端点用于续期。 → 验证项 I5（实施期边做边验，跑超 50 min 时测续期）

5. 并发与排队

   并发上限由 §5.5 列的 4 层防护管（同用户 24h ≤ 20 task / 同 repo ≤ 3 并发 / 全局排队），不另起队列服务——计数走 Postgres tasks 表 + 主 API dispatch 前查询。规模化阶段如出现高并发可换专用队列。 → POC 不验证（推迟到规模化阶段）

6. 取消 / 强制停止

   设计稿 04 task-menu-stop-{id} 已设 disabled。未来支持时调 Sandbank provider.destroy(id)（不直接绑 Fly REST）。 → POC 不验证（前端按钮保持 disabled）

7. apply 阶段跑多少测试

   POC 阶段只跑 typecheck + lint，避免 30 min 上限。完整 jest/playwright 留给 GitHub Actions CI（PR 创建后自动触发）。 → 验证项 E1/E2（30 min 端到端时间预算的约束）

8. 账单失控（死循环 / 恶意调用 / 容器卡死）

   Fly Machines 没有原生 spend cap；Cloudflare Containers 有用户实测比 GCP 贵 2.5x 且无月度 hard cap 的反馈。POC 阶段必须同时落 §5.5 列出的 4 层防护：主 API 并发上限 + 容器内 hard timeout + 平台账单告警 + 主 API 巡检 cron。（模型 token 侧的账单防护属于另一条线，由你在 Anthropic / OpenAI console 独立配置。） → 验证项 E5（真跑阶段用恶意 prompt 演示 4 层防护都生效）

§10 私有化部署路径

私有化路径的完整调研（深度大于 §6.1.2-§6.1.4 的 POC 集成讨论）。本期 POC 已经包含私有化栈（Sandbank + BoxLiteAdapter），本节展开未来阶段可能要的扩展方案与 Runtime 矩阵。

10.1 私有化的精确口径

触发私有化需求的真实场景：

• 合规要求代码 / 凭据不出企业网络边界
• 开源 task-runner 平台让客户自己 docker 跑
• 对推理质量有定制需求，要接入自己微调的模型
• 规模化后单月 task 量 ≥ 5000，托管 SaaS 成本超过自托管运维成本

10.2 开源沙箱运行时速览（按 docker-only 可行性分组）

A · 真正 docker-friendly（符合用户口径）

B · 云依赖型自托管（不符合”docker-only”口径，仅供对比记录）

10.3 docker-friendly 候选展开

docker run --security-opt seccomp=unconfined --rm -it \
  -p 8080:8080 ghcr.io/agent-infra/sandbox:latest

git clone github.com/daytonaio/daytona
cd daytona
docker compose -f docker/docker-compose.yaml up -d
# 访问 http://localhost:3000 — 无需公网域名

# macOS
brew install docker/tap/sbx
# Linux
sudo apt-get install docker-sbx
# 运行
sbx run claude

10.4 单机自托管 vs 托管 SaaS 成本

以 Fly Machines（托管中最便宜）为基准 vs 单台 Linux VPS 跑 AIO Sandbox 做盈亏分析。只算容器成本，token 不算（与 §5 边界一致）。

VPS 价按 Hetzner / OVH 一台 4 vCPU 8GB ≈ $40/月、8 vCPU 16GB ≈ $80/月（2026-05 公开价）估。**注意：**① SRE 人月成本未计入——按 0.2 FTE × $8K/月 ≈ $1600/月，真实盈亏点右移到 ≥ 30K task/月；② 上表只看容器成本，token 不算；③ 单台 VPS 无 auto-scaling，并发取决于机器规格。

10.5 私有化路径的渐进升级图

阶段 1 POC 双轨 ─ 13 天 ▶ 阶段 2 单机扩容 ─ ≥ 5K task/月 ▶ 阶段 3 多机集群 ─ ≥ 100K task/月 ▶ 阶段 4 K8s

POC 阶段已经做对的设计（让未来阶段切换成本最小）：

• 引入 Sandbank 沙箱中间层——未来切换 backend 只需新加或换 adapter，业务代码不动（详见 §6.1.2）。
• 容器入口 run.js 只依赖 stdin/stdout 与 HTTPS callback——不绑任何平台 API，所有 sandbox runtime 都能跑同一个镜像。
• 所有 Fly Machines / VPS Docker 调用走 Sandbank Provider 抽象，主 API 不直接接触平台 REST。

10.6 避坑清单（按 docker-only 口径修订）

• **E2B Infra：**需 GCP/AWS + Terraform，不符合 docker-only 口径。除非已经决定上云做 Nomad 集群，规模化后也不应作为迁移目标。
• **Daytona AGPL：**部署方式（docker-compose）符合口径，但 license 是地雷——商业产品避开，开源社区项目可以用。
• **AIO Sandbox 隔离强度：**容器级（共享 host kernel）。POC 内场景由 GitHub App 信任边界保护够用，但跑不可信代码需要叠 Microsandbox / BoxLite 做 microVM 二次隔离。
• **OpenHands：**是 agent + sandbox 一体方案。已选 Claude Agent SDK 作为 agent，OpenHands 的 agent 部分冗余；要只取 sandbox 需逆向拆解。本期不推荐。
• **Docker Sandboxes (sbx)：**2026-03 新出，license 未公开披露，self-host 行为未文档化。观察 3-6 个月。
• **BoxLite vs Microsandbox 二选一：**API 形态几乎一致。看成熟度选 BoxLite（v0.9.5）；看明确底层引擎与精确性能选 Microsandbox。
• Cloudflare Sandbox SDK：“开源”≠“可自托管”——必须跑在 CF 平台。
• **Firecracker 直接自建：**不要做。Microsandbox / BoxLite 已经把”嵌入式 microVM”做完且开源。
• **K8s 引入：**除非已经有 K8s 平台，否则不要为 task-runner 单独引入——基础设施投资远超收益。

10.7 Agent 业务编排层（澄清版）

先画清楚三层架构

┌───────────────────────────────────────────────────────────────────────┐
│ LAYER 3  Agent 业务编排层                                          │
│   在 sandbox 之上做业务封装：git worktree、agent 多 session、agent 协议适配 │
│   Sandcastle（git worktree 隔离） · rivet-dev/sandbox-agent              │
│   本场景结论：不需要（详见下方分析）                                │
├───────────────────────────────────────────────────────────────────────┤
│ LAYER 2  中间层 / 多 backend 抽象                                  │
│   统一 API 包装多种 Runtime — “写一次，切换 backend 不改业务代码”          │
│   Sandbank（推荐） · cased/sandboxes · sandboxer                        │
│   本场景结论：用 Sandbank（见 §6.1.2 / §6.1.3 / §6.1.4）            │
├───────────────────────────────────────────────────────────────────────┤
│ LAYER 1  Runtime（实际跑容器的运行时）                                    │
│   真正提供隔离 + 执行的实体                                                │
│   公有云：Fly Machines · Vercel Sandbox · E2B · Cloudflare Containers   │
│   私有化：BoxLite · AIO Sandbox · Microsandbox · CubeSandbox · OpenSandbox │
│   本场景结论：POC 用 Fly Machines（公有云）+ BoxLite（私有化）      │
└───────────────────────────────────────────────────────────────────────┘

本场景为什么不需要 Layer 3？

引入 Sandbank（Layer 2）+ “每 task 一个干净容器”的设计之后，Layer 3 提供的两大功能在本场景里都用不上：

Layer 3 什么场景下才需要

本节保留是因为…

虽然本场景不用 Layer 3，但这一节保留作为决策记录有两个价值：

• 明确”为什么不用 Sandcastle”——避免后续团队成员重新考虑这件事
• 未来如果业务变化（如要支持多 agent、单容器多任务复用），知道去哪里找方案

联网调研发现的 Layer 3 候选（仅供未来参考）：

10.8 大厂开源方案专项

把全球主要科技公司开源的 sandbox 方案系统化对比。对国产化 / 合规部署场景尤其重要。

9.8.1 腾讯 CubeSandbox（重点关注）

# 普通云 VM（PVM 启用 KVM）/ WSL 2 / 物理机均可
curl -sL https://github.com/tencentcloud/CubeSandbox/raw/master/deploy/one-click/online-install.sh | bash

# 改一个环境变量即可，业务代码零修改
export E2B_API_URL=http://localhost:<port>
# 然后用任何 E2B SDK，背后跑的就是 CubeSandbox

9.8.2 字节生态澄清

之前 §10.2A 列的 AIO Sandbox (agent-infra/sandbox) 实际上是字节生态的一部分——字节的 bytedance/UI-TARS-desktop 项目已经从内部 omni-tars core 迁移到 agent-infra sandbox。字节系完整图谱：

9.8.3 微软方案

AutoGen 已进入 maintenance mode（2026-Q1 起不再添加新特性，社区维护）。新项目 Microsoft Agent Framework (MAF) 是企业级继任者。AutoGen 内置 DockerCommandLineCodeExecutor——但这是 agent 框架自带的代码执行能力，不是独立的 sandbox runtime/SDK 产品，与本场景的”task-runner 跑 Claude Agent SDK”定位错位。

判定： 微软方案与本场景不直接对接。

9.8.4 更新后的推荐栈（含国产备选）

§11 下一步

双轨 POC 的 3 条可选路径。

§12 POC 实施进度 2026-05-19 · E1+E2 真跑通过

本节是 v1（2026-05-17 explore 阶段）后的实施期记录。原 §7 任务清单 ~13 工作日实际工期内完成，含 8 个 spike（S1-S8 + 私有化 S9）+ 双轨真跑生成真实 GitHub PR。

11.1 § 9.4 集成路径解锁 — BoxLite serve = BoxRun

v1 (2026-05-17) Open Questions 中标 “BoxRun daemon 来源未知”，实施期解决：boxlite-ai/boxlite 单 binary 含 boxlite serve REST mode = BoxRun。

# macmini 装单 binary（不需要 Python venv）
curl -fsSL https://github.com/boxlite-ai/boxlite/releases/latest/download/install.sh | sh
# 启 daemon
nohup ~/.local/bin/boxlite serve --host 0.0.0.0 --port 8100 > /tmp/boxlite.log 2>&1 &
 
# 主 API 集成（Sandbank BoxLiteAdapter remote 模式）
const adapter = new BoxLiteAdapter({
  mode: 'remote',
  apiUrl: 'http://100.101.167.99:8100',  // Tailscale tailnet
  prefix: 'default',  // ⚠ 必传 - boxlite serve 默认 prefix='default'，sandbank 默认 prefix='' 会 404
});
await adapter.listSandboxes();  // 实测返历史 box 列表

capability 集 ['exec.stream', 'port.expose', 'sleep', 'snapshot', 'terminal'] 与 S2.c spike 一致。实施期 follow-up：task-runner-provider.factory.ts 在 private 模式下使用此配置（spike 已通，主 API 集成路径已打通 · 见 tasks.md §12.4）。

11.2 实测成本验证（vs §5 估算）

11.3 8 个 spike 全部通过

11.4 实施期遗留 follow-up

• §12.3 提主 PR add-task-runner-poc（v2 报告 + 实施代码一并）
• §12.4 task-runner-provider.factory.ts 在 private 模式下用 BoxLiteAdapter({ mode: 'remote', apiUrl, prefix: 'default' })
• §12.5 run.js callback completed 一致性 bug（PR #12 真创建但 task 表没切 awaiting_review）
• §12.6 DB ↔ GitHub App install repo 范围 sync gap（connect repo 前主动 reconcile）
• §12.7 spec.md 加 BOXLITE_PREFIX（默认 'default'）必填 env
• §11.1-11.4 E3 双轨切换 demo 脚本 / E4 故障容错 / E5 账单防护 / demo 视频

11.5 后续 change · add-sandbank-fork-aio-e2b 2026-05-20 完成

POC 完成当日，立即启动并完成 sandbank fork + 新增 AIO/E2B adapter 工作：

• Fork repo：Xeonice/sandbank-douglas-agent（MIT 衍生，weekly auto-merge 上游 main）
• npm scope：@douglas-agent — 13 个包发布（10 个上游 mirror + AIO + E2B + CLI）
• 新 adapter：@douglas-agent/sandbank-aio（AIOSandboxAdapter，dockerode + 可选 readinessProbe）+ @douglas-agent/sandbank-e2b（E2BAdapter + CubeSandboxAdapter，共享 E2BProtocolAdapter 基类）
• TASK_RUNNER_MODE 扩展：5 项 public | private | e2b | cube | aio

E1/E2 等价真跑验证（B-full hard）

Cube upstream 阻塞分析

CubeSandbox 是 Tencent 2026-04-20 开源的早期项目（30 天 4 个 release），v0.2.0 / v0.2.1 / v0.2.2 都存在 cubelet.services.images.v1.Images gRPC service 未注册的系统性 bug：

• 跨 AWS / Tencent CVM / 物理 PVM / WSL2 多个环境复现
• maintainer 5/11 给的 workaround（down/up + cubecli unsafe init）多 reporter 实测仍 fail
• PR #282（在 v0.2.2 中）只修了”v0.2.1 .vm not exist” 另一个 regression，没修 images.v1
• 官方 troubleshooting docs 不覆盖（只列 XFS + 磁盘空间 2 条）

我们 fork 的 CubeSandboxAdapter 协议层已 ground-truth 校准 — 上游修复 #159 出 v0.2.3+ 后，adapter 不需任何改动即可用。

详见 openspec/changes/archive/2026-05-20-add-sandbank-fork-aio-e2b/。

§13 参考资料

本报告所引用方案的官方资源。所有数据点均基于这些来源在 2026-05 的内容。

§3 · 云端容器（托管 SaaS）

• Fly Machines 首选 — 官网  · Docs  · Pricing  · Machines API 
• Vercel Sandbox 备选 1 — 官网  · Docs  · Pricing  · npm 
• E2B 备选 2 — 官网  · Docs  · Pricing  · GitHub 
• Cloudflare Sandbox SDK 排除 — 官网  · Docs  · Pricing  · GitHub 
• Daytona Sandboxes 排除 — 官网  · Docs  · GitHub 
• Modal 排除 — 官网  · Docs  · Pricing 
• Anthropic Code Execution Tool 排除 — Docs 

§4 · Agent SDK

• Claude Agent SDK 推荐 — Docs  · Skills  · npm  · GitHub TS  · GitHub Py 
• Codex SDK 对比 — Docs  · npm  · GitHub  · TS README 
• Anthropic API · Pricing & Limits — Pricing  · Rate Limits 
• OpenAI API · Pricing & Limits — Pricing  · Rate Limits  · Codex Pricing 

§10.A · docker-friendly 候选（符合用户口径）

• AIO Sandbox 单 docker run · 推荐 — GitHub 
• Daytona OSS docker-compose · AGPL 警告 — OSS Deploy  · GitHub 
• BoxLite 嵌入式 microVM · v0.9.5 — 官网  · Docs  · GitHub  · MCP Server 
• Microsandbox 嵌入式 microVM · libkrun — 官网  · GitHub 
• OpenHands agent + sandbox 一体 · ★ 68.6k — GitHub  · Docker Sandbox Docs 
• Docker Sandboxes (sbx) Docker 官方 · 2026-03 新出 — Docs 

§6.1.2 · 沙箱中间层（multi-backend 抽象，磨平公有云/私有化差异）

• Sandbank MIT · ★ 163 · 推荐 · 中间层最佳匹配 — GitHub  · Releases (v0.6.2)  · npm  · Issue #2（维护者持久化能力详述） 
• cased/sandboxes MIT · ★ 97 · 偏 CLI — GitHub 
• hyperterse/sandboxer Apache 2.0 · ★ 6 · 较早期 — GitHub 
• spring-ai-community/agent-sandbox Java/Spring 生态 — GitHub 
• @gitwit/sandbox npm 包形态 — npm 

§10.7 · Sandbox SDK / 编排层（重要补充）

• Sandcastle MIT · git worktree 隔离 · 本场景不需要（详见 §10.7） — GitHub  · README 
• rivet-dev/sandbox-agent Apache 2.0 · ★ 1.4k · Universal Agent API — 官网  · GitHub  · npm 
• alibaba/OpenSandbox Apache 2.0 · ★ 10.7k · CNCF — 官网  · GitHub 
• Beam Cloud / Beta9 AGPL 警告 — 官网  · GitHub (Beta9) 
• awesome-sandbox 列表 社区维护的索引 — GitHub  · 2026-05 list (gist) 

§10.8 · 大厂开源方案专项

• 腾讯 CubeSandbox Apache 2.0 · ★ 5.7k · E2B 兼容 · 60ms 冷启动 — GitHub  · Releases 
• 阿里 OpenSandbox Apache 2.0 · ★ 10.7k · CNCF — 官网  · GitHub 
• 字节 AIO Sandbox Apache 2.0 · ★ 4.7k · UI-TARS 生态 — GitHub  · UI-TARS Desktop（生态背景） 
• 字节 SandboxFusion Apache 2.0 · 评估导向 — 官网  · GitHub 
• 字节 DeerFlow 2.0 Apache 2.0 · ★ 35.3k · SuperAgent harness — GitHub 
• 微软 AutoGen MIT · maintenance mode — GitHub  · Docs 
• 微软 Agent Framework (MAF) AutoGen 继任者 — 介绍文章 

§10.B · 云依赖型自托管（仅供对比记录，不符合 docker-only 口径）

• E2B Infra 需 GCP/AWS + Terraform + Nomad — GitHub  · Self-host Guide 
• Google Agent Sandbox 需 Kubernetes — 官网  · GitHub  · 发布文章 
• Firecracker 底层引擎 — 官网  · GitHub 

隔离技术 / 通用对比

• gVisor userspace kernel — 官网  · GitHub 
• Kata Containers VM + OCI — 官网  · GitHub 
• libkrun Microsandbox 底层 — GitHub 

openspec-agent-platform · docs/task-runner-poc.html · v1 · 2026-05-17 · explore 阶段产物