Task Sandbox v2 — 技术选型与解耦架构

┌──────────────────────────────────────────────────────────────────────────┐
│  web (browser)              主 API (NestJS, Fly)            sandbox     │
│       │                            │                            │       │
│       │  EventSource (SSE)        │                            │       │
│       │  ◄────── 单向 ─────────────│                            │       │
│       │                            │                            │       │
│       │                            │  adapter.streamLogs()      │       │
│       │                            │  ReadableStream<Uint8>     │       │
│       │                            │  ◄──── 单向 ───────────────│       │
│       │                            │   (sandbox stdout JSONL)   │       │
└──────────────────────────────────────────────────────────────────────────┘
• web→主 API:    HTTP POST /tasks/:id/dispatch (一次性,非通道)
• 主 API→sandbox: 仅在 dispatch 时 provider.create(env, …) 注入,之后无通路

┌────────────────────────────────────────────────────────────────────────────┐
│ web (Next.js · browser)                                                 │
│   socket.io-client / native WS                                             │
│   ─ send: 用户追加指令 / 暂停 / 取消 / permission 回应                       │
│   ─ recv: stage_change / log / completed / failed / agent_question         │
│   ─ 浏览器自动重连(WS Last-Event-ID 模拟)                                   │
└──────────────────────────────────┬─────────────────────────────────────────┘
│ WSS (持久连接)
▼
┌────────────────────────────────────────────────────────────────────────────┐
│ 主 API (NestJS · Fly · min=1)                                            │
│                                                                            │
│   @WebSocketGateway(‘/tasks/:id/stream’)  [NEW]                            │
│     ─ on(‘message’) from web → forward 到 Relay ‘task/:id’ channel         │
│     ─ subscribe Relay ‘task/:id’ → forward 到 web client                   │
│                                                                            │
│   TaskRunnerDispatcher  [修订]                                            │
│     ─ provider.create() 启动 sandbox                                       │
│     ─ store sandbox_id 进 Task 表                                          │
│     ─ subscribe Relay ‘task/:id’                                           │
│     ─ 不再 维护 in-process streamLogs loop                                │
│                                                                            │
│   ResubscribeBootstrap  [NEW · 30 lines]                                  │
│     ─ OnModuleInit: SELECT running tasks → 对每个 subscribe Relay channel   │
│                                                                            │
│   TaskRunnerJanitor  [保留 · 兜底]                                         │
│     ─ 仅当 ResubscribeBootstrap 发现 sandbox 已死时清理                     │
└──────────────────────────────────┬─────────────────────────────────────────┘
│ WSS outbound (主 API → Relay)
▼
┌────────────────────────────────────────────────────────────────────────────┐
│ sandbank Relay (Fly · 独立 app · ~$5-10/mo)  [NEW]                      │
│   @douglas-agent/sandbank-relay (WebSocket + JSON-RPC 2.0)                           │
│   ─ channel = task_id (多 task 天然隔离)                                    │
│   ─ 物理上接受 inbound 但主 API 和 sandbox 都是 outbound 进                 │
│   ─ 可选缓冲最近 N 条消息(供主 API 重连 catch-up)                           │
│   ─ session.context 能力不本期使用(单 task 内 agent 序列, 不需共享 context) │
└──────────────────────────────────┬─────────────────────────────────────────┘
│ WSS outbound (sandbox → Relay)
▼
┌────────────────────────────────────────────────────────────────────────────┐
│ sandbox: task-runner image · run.js  [修订]                          │
│                                                                            │
│   1. 读 /task-spec.json (替代 hardcoded 4 阶段)                            │
│   2. connect() to Relay via @douglas-agent/sandbank-agent                            │
│   3. session.on(‘message’) push to userQueue                               │
│   4. query({ prompt: AsyncIterable(initial + userQueue) }) [streamInput]   │
│   5. for await event of query() → session.broadcast(event)                 │
│   6. 不再写 stdout JSONL (除非 dual-protocol 迁移期)                        │
└────────────────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────────────┐
│ task-runner image 入口 (/app/entry.js)                                  │
│                                                                         │
│  1. parse /task-spec.json                                               │
│  2. resolve runner module: require(‘@douglas-agent/task-runner-’ +      │
│                                    spec.type)                           │
│  3. const runner = module.create()    // implements TaskRunner      │
│  4. const host = await initHostContext(spec)                            │
│       │                                                                 │
│       ├─ Claude SDK client (subapi / direct base url 已配)              │
│       ├─ Sandbox session via @douglas-agent/sandbank-agent.connect()              │
│       ├─ Git workspace (clone + credential helper)                      │
│       ├─ Token store (auto-refresh via Relay 主推)                      │
│       └─ Stage state writer                                             │
│  5. await runner.run(host, spec)                                        │
│  6. host.complete(result) 或 host.fail(reason)                          │
└─────────────────────────────────────────────────────────────────────────┘

// 由 task-runner image 提供, runner 模块通过依赖注入接收
interface HostContext {
// Claude Agent SDK 已就绪的 client (env、auth 已注入)
ai: {
query(opts: QueryOptions): AsyncIterable<SDKMessage>
streamInput(messages: AsyncIterable<SDKUserMessage>): void
interrupt(): Promise<void>
}

// 双向通道 (D3: 替代 stdout JSONL)
session: {
broadcast(event: TaskEvent): void              // agent → web
on(type: ‘user_message’, handler: (msg) => void): Unsubscribe
on(type: ‘interrupt’, handler: () => void): Unsubscribe
on(type: ‘token_renewed’, handler: (token) => void): Unsubscribe
}

// Git 操作 (token 由 host 透明管理)
git: {
clone(repo: string, branch: string): Promise<Workspace>
commit(ws: Workspace, message: string): Promise<void>
push(ws: Workspace, branch: string): Promise<void>
openPr(opts: PrOptions): Promise<{ url: string }>
}

// stage 状态 (持久化到 task 行)
stage: {
transition(to: string, status?: ‘running’ | ‘awaiting_review’): void
increment_cycle(): void                        // cyclic 用
current(): string
}

// 日志 (会被 broadcast 出去, 不要 console.log)
log(level: ‘info’ | ‘warn’ | ‘error’, msg: string, data?: object): void

// 退出
complete(result: { prUrl?: string; metrics?: object }): never
fail(reason: string, stage?: string): never
}

// 每个 task type = 一个 npm 包, 默认 export 一个 factory
export interface TaskRunner {
readonly type: string                          // ‘openspec-4stage’
readonly stateModel: ‘dag’ | ‘cyclic’
describe(): RunnerManifest                     // 给主 API 探测用
run(host: HostContext, spec: TaskSpec): Promise<void>
}

interface RunnerManifest {
type: string
version: string                                // semver, 跟 npm 包版对齐
required_skills: string[]                      // 默认 skill 列表
required_capabilities: string[]                // 如 ‘git’, ‘pr’
state_model: ‘dag’ | ‘cyclic’
stages: string[]                               // DAG: 全部 stage; Cyclic: 单轮内的 stage
param_schema: JsonSchema                       // spec.params 校验
default_limits: TaskLimits
}

{
“version”: 1,                                  // schema 版本, 不是 task spec 版本
“type”: “openspec-4stage”,                     // runner module type
“runner_pkg”: “@douglas-agent/task-runner-openspec”,
“runner_version”: “^1.0.0”,                    // semver range
“params”: { … },                             // runner 特定参数, 由 param_schema 校验
“limits”: {
“max_turns”: 100,                            // 单 query() 最大 turn
“max_minutes”: 60,                           // 总时长, 触发 hard timeout
“max_input_tokens”: 200000,
“max_cycles”: 10                             // 仅 cyclic
},
“skills”: […],                               // 覆盖 manifest.required_skills
“stage_detection”: {                           // 声明式 stage 切换
“rules”: [ Rule, Rule, … ]
},
“completion”: {
“git_push”: true,
“open_pr”: true,
“verifier”: { “type”: “typecheck” }          // 可选, completion 前跑
},
“user_controls”: {                             // 允许用户从 web 发的指令
“interrupt”: true,
“append_message”: true,
“stop_loop”: false                           // 仅 cyclic 有意义
}
}

// Rule 由 PostToolUse hook 在 sandbox 内本地评估
interface Rule {
match: ToolPattern        // 匹配条件
action: Action            // 触发动作
priority?: number         // 默认 0, 高优先级先匹配
}

interface ToolPattern {
tool: ‘Write’ | ‘Bash’ | ‘Read’ | ‘Edit’ | ’*’
path?: string             // glob: ‘src/**/*.ts’
command_prefix?: string   // Bash: ‘npm test’ 等
result?: ‘success’ | ‘failure’  // Bash 退出码
}

type Action =
| { kind: ‘transition’; to: string }              // DAG: 切到新 stage
| { kind: ‘increment_cycle’ }                     // Cyclic: cycle++
| { kind: ‘evaluate’; check: ‘tests_pass’ | ‘verifier’ }
| { kind: ‘complete’; data?: object }
| { kind: ‘fail’; reason: string }

{
“version”: 1,
“type”: “openspec-4stage”,
“runner_pkg”: “@douglas-agent/task-runner-openspec”,
“runner_version”: “^1.0.0”,
“params”: {
“prompt”: “Add dark mode toggle”,
“change_id”: “add-dark-mode”,
“openspec_change_path”: “openspec/changes/add-dark-mode”
},
“limits”: { “max_turns”: 100, “max_minutes”: 60 },
“skills”: [
“.claude/skills/openspec-explore/SKILL.md”,
“.claude/skills/openspec-propose/SKILL.md”,
“.claude/skills/openspec-apply/SKILL.md”,
“.claude/skills/openspec-archive/SKILL.md”
],
“stage_detection”: {
“rules”: [
{ “match”: { “tool”: “Write”, “path”: “openspec/changes/*/proposal.md” },
“action”: { “kind”: “transition”, “to”: “propose” } },
{ “match”: { “tool”: “Write”, “path”: “src/**/*” },
“action”: { “kind”: “transition”, “to”: “apply” } },
{ “match”: { “tool”: “Bash”, “command_prefix”: “openspec archive” },
“action”: { “kind”: “transition”, “to”: “archive” } }
]
},
“completion”: {
“git_push”: true, “open_pr”: true,
“verifier”: { “type”: “typecheck” }
},
“user_controls”: { “interrupt”: true, “append_message”: true }
}

{
“version”: 1,
“type”: “spec-kit”,
“runner_pkg”: “@douglas-agent/task-runner-spec-kit”,
“params”: {
“prompt”: ”…”,
“constitution_path”: “.github/spec-kit/constitution.md”
},
“stage_detection”: {
“rules”: [
{ “match”: { “tool”: “Write”, “path”: “specs/*/spec.md” },
“action”: { “kind”: “transition”, “to”: “spec” } },
{ “match”: { “tool”: “Write”, “path”: “plans/*/plan.md” },
“action”: { “kind”: “transition”, “to”: “plan” } },
{ “match”: { “tool”: “Write”, “path”: “plans/*/tasks.md” },
“action”: { “kind”: “transition”, “to”: “tasks” } },
{ “match”: { “tool”: “Bash”, “command_prefix”: “git checkout -b implement/” },
“action”: { “kind”: “transition”, “to”: “implement” } }
]
},
“completion”: {
“verifier”: { “type”: “checklist”, “path”: “plans/*/tasks.md” },
“git_push”: true, “open_pr”: true
}
}

{
“version”: 1,
“type”: “tdd-cycle”,
“runner_pkg”: “@douglas-agent/task-runner-tdd”,
“params”: {
“feature_prompt”: “Add user.email validation”,
“test_command”: “pnpm vitest run —reporter=json”,
“target_module”: “packages/auth/src/user.ts”
},
“limits”: { “max_minutes”: 60, “max_cycles”: 10 },
“stage_detection”: {
“rules”: [
{ “match”: { “tool”: “Write”, “path”: ”**/*.test.ts” },
“action”: { “kind”: “transition”, “to”: “red” } },
{ “match”: { “tool”: “Bash”, “command_prefix”: “pnpm vitest”, “result”: “failure” },
“action”: { “kind”: “transition”, “to”: “green” } },
{ “match”: { “tool”: “Bash”, “command_prefix”: “pnpm vitest”, “result”: “success” },
“action”: { “kind”: “evaluate”, “check”: “tests_pass” } }
]
},
“completion”: {
“verifier”: { “type”: “tests_green_n_cycles”, “min_cycles”: 3 },
“git_push”: true, “open_pr”: true
},
“user_controls”: {
“interrupt”: true,
“append_message”: true,
“stop_loop”: true                        // cyclic 专有
}
}

┌─────────────────────────────────────────────────────────────────────────┐
│ monorepo: packages/task-runners/                                        │
│   ├─ openspec/      package.json: “@douglas-agent/task-runner-openspec” │
│   ├─ spec-kit/      package.json: “@douglas-agent/task-runner-spec-kit” │
│   └─ tdd/           package.json: “@douglas-agent/task-runner-tdd”      │
│                                                                         │
│ 每个 runner 包结构:                                                      │
│   ├─ src/                                                               │
│   │   ├─ index.ts          // export default factory()             │
│   │   ├─ manifest.ts       // RunnerManifest 静态对象              │
│   │   ├─ stages/           // 每 stage 逻辑(可选)                  │
│   │   └─ verifier.ts       // completion verifier                  │
│   ├─ skills/               // 包内 SKILL.md, copied into image     │
│   └─ schema/task-spec.schema.json                                       │
└─────────────────────────────────────────────────────────────────────────┘

主 API dispatcher 派发流程:
1. 客户端 POST /tasks/:id/dispatch  body: { task_type, params }
2. 主 API 查 runner registry (Postgres 表或硬编码)
SELECT image, runner_version FROM runner_registry WHERE type = $1
3. 校验 params 是否符合 manifest.param_schema
4. 生成 task-spec.json 并放进容器 env / volume
5. provider.create({ image, env: { TASK_SPEC_JSON: ’…’ }, … })

model Task {
id                  String     @id @default(uuid())
branchId            String     @map(“branch_id”)
creatorId           String?    @map(“creator_id”)
title               String
prompt              String
changeId            String     @map(“change_id”)
openspecChangePath  String     @map(“openspec_change_path”)
status              TaskStatus @default(proposing)
  stage               TaskStage  @default(explore)               // enum 写死 4 值
  stage               String     @default(“explore”) @db.VarChar(32)
                                  // 不同 task_type 有不同 stage 名,故改 varchar

  sandboxId           String?    @map(“sandbox_id”)     @db.VarChar(128)
                                  // sandbank 返回的 handle id, ResubscribeBootstrap 用
  sandboxProvider     SandboxProvider? @map(“sandbox_provider”)
                                  // ‘microsandbox’ | ‘fly’ | ‘boxlite’ | ‘aio’ | ‘e2b’ | ‘cube’

  taskType            String     @default(“openspec-4stage”) @map(“task_type”) @db.VarChar(64)
  runnerPkg           String     @map(“runner_pkg”)     @db.VarChar(128)
  runnerVersion       String     @map(“runner_version”) @db.VarChar(32)
  taskSpec            Json       @map(“task_spec”)
                                  // 完整 /task-spec.json 副本, 主 API 重启后
                                  // 不调容器即可知道这个 task 是哪种 type / 哪个 stage

  cycleCount          Int        @default(0) @map(“cycle_count”)
                                  // cyclic 类 task 进度持久化 (tdd-cycle 等)

additions, deletions, filesChanged, prUrl, failedReason,
createdAt, updatedAt, deletedAt
…
@@index([branchId, deletedAt])
@@index([creatorId, deletedAt])
@@index([createdAt])
  @@index([status, sandboxId])   // ResubscribeBootstrap WHERE status IN (‘running’…) 用
}

model TaskEvent {
id        String   @id @default(uuid())
taskId    String   @map(“task_id”)
type      String                              // 值域扩 (见下)
stage     String?
status    String?
data      Json

  sequenceNumber  BigInt @map(“sequence_number”)
                                  // per task 单调自增, 行级保序; web 用 last_seq
                                  // 做 catch-up (避免依赖 created_at 精度)

  ingestMethod    String @default(“relay”) @map(“ingest_method”) @db.VarChar(24)
                                  // ‘relay’ | ‘stdout’ | ‘bootstrap_resubscribe’ | ‘janitor’
                                  // 审计 + 调试用

  cycleIndex      Int?   @map(“cycle_index”)
                                  // cyclic 任务专用,标记是第几轮的事件

createdAt DateTime @default(now())
task Task @relation(fields: [taskId], references: [id], onDelete: Cascade)

@@index([taskId, createdAt])
  @@unique([taskId, sequenceNumber])    // 保序 + catch-up 唯一索引
}

// type 字段值域扩
现:  ‘stage_change’ | ‘log’ | ‘completed’ | ‘failed’
加:  ‘user_message_injected’ | ‘token_renewed’ | ‘cycle_evaluated’ | ‘stage_evaluated’

model RunnerRegistry {
  id              String   @id @default(uuid()) @db.Uuid
  type            String   @unique @db.VarChar(64)
                                  // ‘openspec-4stage’ | ‘spec-kit’ | ‘tdd-cycle’ | …
  runnerPkg       String   @map(“runner_pkg”) @db.VarChar(128)
                                  // ‘@douglas-agent/task-runner-openspec’
  runnerVersion   String   @map(“runner_version”) @db.VarChar(32)
                                  // semver range 或锁定版本
  image           String   @db.VarChar(256)
                                  // ‘ghcr.io/openspec/task-runner:v2.1.0’
  imageDigest     String?  @map(“image_digest”) @db.VarChar(80)
                                  // ‘sha256:…’ 用于 supply chain 锁定
  manifest        Json
                                  // RunnerManifest: required_skills, param_schema,
                                  // state_model, stages, default_limits
  active          Boolean  @default(true)
                                  // false = 软停用, 不能新派发但 in-flight 不影响
  createdAt       DateTime @default(now()) @map(“created_at”) @db.Timestamptz(6)
  updatedAt       DateTime @updatedAt @map(“updated_at”) @db.Timestamptz(6)

  @@index([type, active])
  @@map(“runner_registry”)
}

// dispatcher 派发路径:
// 1. POST /tasks/:id/dispatch  body: { task_type, params }
// 2. SELECT * FROM runner_registry WHERE type = $1 AND active = true
// 3. validate(params, registry.manifest.param_schema)
// 4. 写 Task.{taskType, runnerPkg, runnerVersion, taskSpec}
// 5. provider.create({ image: registry.image, env: { TASK_SPEC_JSON: …  })}

┌─────────────────────────────────────────────────────────────────────────────┐
│  身份域 (Identity)                                                         │
│                                                                             │
│   ┌──────────────┐  1 ──── N  ┌───────────────┐                            │
│   │  User        │ ──────────▶│  Session      │                            │
│   │              │            │  (cookie 凭据) │                            │
│   └──────┬───────┘            └───────────────┘                            │
│          │ 1                                                                │
│          │                                                                  │
└──────────┼──────────────────────────────────────────────────────────────────┘
│
│ N (installedBy / creator)
│
┌──────────┴──────────────────────────────────────────────────────────────────┐
│  资源域 (Resources)                                                       │
│                                                                             │
│   ┌──────────────────┐ 1 ── N ┌───────────────┐ 1 ── N ┌──────────────┐    │
│   │ GithubInstall    │ ──────▶│ GithubRepo    │ ──────▶│ GithubBranch │    │
│   │  ation           │        │ (镜像)         │        │ (镜像)        │    │
│   └──────────────────┘        └───────────────┘        └──────┬───────┘    │
│                                                                │ 1          │
└────────────────────────────────────────────────────────────────┼────────────┘
│
│ N
│
┌────────────────────────────────────────────────────────────────┴────────────┐
│  任务域 (Tasks)                                                           │
│                                                                             │
│   ┌─────────────────────────────────────────────┐                          │
│   │ Task                                        │  1 ── N  ┌─────────────┐ │
│   │   ─ branch_id  (FK 硬约束 → GithubBranch)   │ ────────▶│ TaskEvent   │ │
│   │   ─ creator_id (FK 软约束 → User, SetNull)  │          │  ─ task_id  │ │
│   │   ─ sandbox_id  (外部 sandbank id,非 FK)    │          │  ─ seq_no   │ │
│   │   ─ sandbox_provider (enum)                  │          │  ─ cycle_idx│ │
│   │   ─ task_type (软引用 RunnerRegistry.type)   │          │  ─ type     │ │
│   │   ─ runner_pkg / runner_version              │          │  ─ data     │ │
│   │   ─ task_spec (jsonb)                        │          └─────────────┘ │
│   │   ─ cycle_count                              │                          │
│   │   ─ status, stage, prompt, …              │                          │
│   └────────┬────────────────────────────────────┘                          │
│            │ 软引用 (字符串 task_type, 不约束)                                │
└────────────┼────────────────────────────────────────────────────────────────┘
│
▼
┌────────────────────────────────────────────────────────────────────────────┐
│  运行时域 (Runtime)  [v2 NEW]                                          │
│                                                                            │
│   ┌─────────────────────────────────────────┐                              │
│   │ RunnerRegistry                          │                              │
│   │   ─ type  (unique, 软引用目标)            │                              │
│   │   ─ runner_pkg / runner_version         │                              │
│   │   ─ image / image_digest                │                              │
│   │   ─ manifest (jsonb)                    │                              │
│   │   ─ active                              │                              │
│   └─────────────────────────────────────────┘                              │
│         无 FK 引用外部 (独立资源, 主 API 启动时 seed)                          │
└────────────────────────────────────────────────────────────────────────────┘

外键约束策略：
硬约束 (CASCADE): Task.branch_id, TaskEvent.task_id
软约束 (SetNull): Task.creator_id (用户删了 task 留着)
无 FK (软引用):  Task.task_type → RunnerRegistry.type
Task.sandbox_id  → 外部 sandbank handle

+ enum SandboxProvider {
+   microsandbox
+   fly
+   boxlite
+   aio
+   e2b
+   cube
+   @@map(“sandbox_provider”)
+ 

- enum TaskStage {                          // 删除: 不同 task_type 有不同 stage 名
-   explore
-   propose
-   apply
-   archive
- 

model Task {
… (现有字段)
-   stage           TaskStage  @default(explore)
+   stage           String     @default(“explore”) @db.VarChar(32)
+   sandboxId       String?    @map(“sandbox_id”) @db.VarChar(128)
+   sandboxProvider SandboxProvider? @map(“sandbox_provider”)
+   taskType        String     @default(“openspec-4stage”) @map(“task_type”)
+   runnerPkg       String     @map(“runner_pkg”) @db.VarChar(128)
+   runnerVersion   String     @map(“runner_version”) @db.VarChar(32)
+   taskSpec        Json       @map(“task_spec”)
+   cycleCount      Int        @default(0) @map(“cycle_count”)
+   @@index([status, sandboxId])
}

model TaskEvent {
… (现有字段)
+   sequenceNumber  BigInt @map(“sequence_number”)
+   ingestMethod    String @default(“relay”) @map(“ingest_method”) @db.VarChar(24)
+   cycleIndex      Int?   @map(“cycle_index”)
+   @@unique([taskId, sequenceNumber])
}

+ model RunnerRegistry { … }                // 见 10.5