wishforge-ide/docs/architecture.md
eust-w df87c5dca6 🐛 Drop a run start that a newer one replaced before it takes the run back
The dispatcher read the run, checked that the start it was delivering
was still the pending one, and reserved the execution grant in a later
transaction. A pause and a continue in between enqueued a newer start,
and the older one went ahead anyway: it took the run's execution
generation back and asked the provisioner for a sandbox for a
generation that had already been replaced.

Reserving the grant now checks the pending start again, in the
transaction that takes the generation, and refuses a replaced one with
START_SUPERSEDED. The dispatcher acknowledges such a start without
marking the run as waiting; the newer start proceeds as usual.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-26 15:56:14 +08:00

37 KiB
Raw Blame History

WishForge 架构设计

版本:2026-10-19 · 对应需求:requirements.md

本文描述系统的组件划分、运行状态机、关键流程、数据模型、接口、身份与信任模型以及部署拓扑。专题契约(仓库与 wishforge.yaml、受保护验收配置、模型代理、部署密钥、产物存储、管理台规范)见 reference/。

1. 总览

flowchart LR
  subgraph Clients[入口]
    Web[Web 工作台<br/>apps/web]
    MCPC[WorkBuddy / Codex<br/>MCP 客户端]
    IDE[云 IDE 浏览器]
  end
  subgraph Control[控制面]
    API[控制面 API<br/>apps/api]
    PG[(PostgreSQL<br/>RLS)]
    TMP[(Temporal)]
    S3[(对象存储)]
    GIT[平台 Git<br/>apps/git-service]
  end
  subgraph Exec[执行面(每个运行代次独立)]
    COORD[coordinator worker]
    EXE[executor worker]
    VER[verifier worker]
    DEP[deployer worker]
    PROV[provisioner<br/>local / kubernetes]
  end
  subgraph Target[目标环境]
    RUN[Runner<br/>apps/runner]
    APP[应用]
  end
  GW[IDE 网关<br/>apps/ide/gateway]
  THEIA[Theia 工作区]
  LLM[模型服务商]

  Web -->|BFF /api → /v1| API
  MCPC -->|/mcp OAuth| API
  IDE --> GW --> THEIA
  GW -->|授权| API
  API --- PG
  API -->|outbox 派发| PROV
  API -->|signalWithStart| TMP
  PROV -->|启动| EXE & VER
  TMP --- COORD & EXE & VER & DEP
  EXE & VER -->|/internal| API
  EXE -->|模型代理| API -->|转发| LLM
  EXE & VER --- GIT
  API --- S3
  RUN -->|拉取签名任务| API
  RUN --> APP

设计原则:

  1. 控制面是唯一事实来源。运行状态、证据、审批都由 API 在数据库中裁决;worker 只提交事实与请求,不能自行宣布成功。
  2. 执行与验证隔离。执行器(写代码的 Agent)与验证器使用不同身份、不同工作区;验证器只信任从检查点恢复的精确 commit。
  3. 外部副作用幂等、可对账。模型调用、Git 推送、构建、部署都带幂等键或 CAS;结果未知时进入可解除的等待,而不是盲目重试。
  4. 任何等待都有出口。等待原因是枚举值,每种原因都对应用户或运维的解除操作。
  5. 开发与生产走同一条链路。本地开发使用 local provisioner 与 host 沙箱模式,除隔离强度外,派发、租约、证据、集成流程与生产一致。

2. 组件与目录

组件 目录 职责
Web 工作台 apps/web Next.js App Router。BFF:OIDC 会话(加密 Cookie)、/api/* 代理到 API 的 /v1/*、IDE 启动跳转。页面:概览、项目、运行、发布与审批、环境、执行器、用量。
控制面 API apps/api NestJS(Express)。/v1(人与连接器)、/internal(执行身份)、/mcp、/provider-proxy、/health /readyz /metrics。领域逻辑在 src/domain,后台循环:派发器、资源回收、工作区生命周期。
契约 packages/contracts 领域类型、zod 输入校验、错误类型、等待原因枚举、规范化 JSON(签名与摘要的唯一实现)。
Agent 配置 packages/agent Agent 配置(Bundle)的 schema 与内容摘要、提示词组装(目标、验收标准、修复反馈、项目经验)。
Worker apps/worker Temporal worker,按角色运行:coordinator(工作流与状态同步)、executor(调用执行器)、verifier(验证、集成、构建)、deployer(创建发布)。
Runtime packages/runtime 执行器适配器(Codex SDK;CodeBuddy 与 Claude Code 共用一个输出 stream-json 的命令行适配器)、Git 工作区(检查点、恢复、集成、推送)、验证执行、镜像构建、部署适配器(Compose/Kubernetes 蓝绿)、Runner 任务签名、部署密钥 broker、wishforge.yaml 解析。
平台 Git apps/git-service Smart HTTP Git 服务;仓库范围、读写分离的短期令牌。
GitHub packages/github GitHub App 客户端:安装令牌、PR、合并。
产物存储 packages/artifacts S3 兼容的内容寻址存储,用于检查点 bundle。
Provisioner apps/provisioner 为运行代次创建 executor/verifier,为 IDE 创建工作区。两个后端:local(开发,宿主机进程)与 kubernetes(生产,Kata Job + PVC)。
Runner apps/runner 部署在目标环境侧,主动拉取 Ed25519 签名的部署任务并回报结果。
IDE apps/ide Theia 1.76 应用、策略扩展(扩展白名单)、鉴权网关(gateway/)、按工作区隔离的 OCT 协作(collaboration/)。

3. 运行状态机

运行有阶段(stage,进展到哪一步)与状态(status,当前是否在执行)两个维度。

阶段按顺序推进,不能跳过:

clarify → plan → implement → verify → integrate → build → release → accept
阶段 执行者 产出
clarify executor 记录验收标准后直接进入 plan;澄清问题在第一轮实现中提出(见下方「等待原因」中的 clarification)
plan executor 规划说明(作为进度事件)
implement executor 检查点(commit + 增量 bundle + 补丁)
verify verifier 验证证据(每条命令的结果与输出尾部)
integrate verifier 集成证据(推送到目标分支的 commit),或 GitHub PR 合并结果
build verifier 构建证据(镜像 digest),仅配置了交付时
release deployer / Runner 发布记录、审批、部署证据
accept 控制面 部署验收通过后运行成功

修复(repair)是唯一允许的回退:verify 或 integrate 阶段验证失败或合并冲突时回到 implement,修复计数加一。回退只能由工作流协调器通过 /internal/runs/:id/repair 发起,控制面依据验证器提交的失败证据和修复预算裁决。

每种执行身份只能把运行推进到自己负责的阶段,状态只能是 running 或 waiting:executor 负责 clarify~verify,verifier 负责 verify~build,deployer 负责 release。没有任何执行身份可以把运行置为成功、失败或回退阶段;成功只来自控制面对集成证据(无交付配置时)或部署验收的裁决。

stateDiagram-v2
  [*] --> queued: 提交愿望
  [*] --> waiting: 前置条件缺失
  queued --> running: worker 取得租约
  running --> waiting: 需要外部条件
  waiting --> queued: 用户继续 / 条件满足
  running --> paused: 用户暂停
  waiting --> paused: 用户暂停
  paused --> queued: 用户继续
  running --> succeeded: 合入完成(无交付)或部署验收通过
  queued --> canceled: 用户取消
  running --> canceled
  waiting --> canceled
  paused --> canceled
  succeeded --> [*]
  canceled --> [*]

所有失败都进入带出口的等待,由用户决定继续还是取消;failed 只保留给历史数据。

3.1 等待原因

waiting 状态必须带一个枚举的等待原因(waitingReason)和一段可读说明(waitingDetail):

等待原因 含义 解除方式
credentials 执行器未连接或不可用 连接执行器凭据后继续
git_storage 项目仓库未就绪 重试仓库创建或配置仓库后继续
sandbox_provisioner 没有可用的 provisioner 或创建执行环境失败 运维恢复 provisioner;系统自动重试
worker_unavailable executor/verifier 未在时限内接手 系统按代次重新派发;或用户继续
budget token 或时长预算耗尽 补充需求或提交新愿望
clarification 第一轮实现时,执行器认为缺少关键决定,没有改动任何文件,而是在回复末尾的 QUESTIONS: 后列出最多 5 个问题;问题显示在等待说明里。修复轮不能提问。 回答问题:补充内容并入需求,产生新的需求版本,从 plan 重新开始
verification_unconfigured 没有可运行的验证命令或缺少必需的验收配置 配置验证命令后继续
repair_exhausted 修复轮数用尽仍未通过验证 继续(授权再修复一轮)、补充需求(新需求版本重新计算修复轮数)或取消
infrastructure 依赖安装、沙箱启动、Git 网络等基础设施故障 修复环境后继续(不消耗修复轮数)
provider_error 执行器调用失败(可重试的错误) 继续
ambiguous_execution 外部操作结果未知,需要人工判断 检查事件后继续或取消
integration_conflict 已验证的代码与目标分支冲突,且修复轮数已用完(轮数未用完时冲突自动作为一轮修复处理) 继续(基于最新目标分支再修复一轮)或取消
github_review 等待 GitHub PR 审核或合并 在 GitHub 或工作台完成合并
github_unconfigured GitHub 仓库未配置 GitHub App 运维配置后继续
approval 发布等待人工审批 审批或拒绝
deployment 部署进行中或等待对账 Runner 回报;或运维对账

暂停是独立的 paused 状态,不使用等待原因。

暂停正在执行的运行时,executor 先停止 Agent,把已完成的工作保存为检查点,再确认暂停(/internal/runs/:id/pause);在此之前状态仍是 running,记有 pauseRequestedAt,工作台显示「暂停中」,这期间不再发放模型凭据,也不接受新的模型请求,工作流在暂停完成后才停止。executor 两分钟内没有确认、或者已经停止时,暂停照样生效:心跳、新的租约请求、协调器记录等待与后台维护循环都会完成它。继续运行时从保存的检查点恢复。没有 executor 在执行时(排队、等待,或验证器、发布者持有租约),暂停立即生效。暂停中不能继续,取消立即生效。

4. 关键流程

4.1 提交与派发

sequenceDiagram
  participant U as 用户 / MCP
  participant A as API
  participant D as 派发器
  participant P as Provisioner
  participant T as Temporal
  U->>A: POST /v1/projects/:id/wishes(幂等键)
  A->>A: 校验配额、选择执行器与 Agent 配置版本
  A->>A: 写入 wish、run(queued)与 outbox(run.start)
  D->>A: 认领 outbox(SKIP LOCKED)
  D->>A: 预留执行资源,签发运行级令牌
  D->>P: POST /runs {tenant, run, generation, 令牌, 资源授权}
  P-->>D: provisioned(启动 executor/verifier)
  D->>T: signalWithStart runWorkflow
  • outbox 条目的 ID 即运行的执行代次(generation)。每次继续、补充都会产生新代次;旧代次的 worker 令牌立即失效。
  • 派发器只启动运行最近一次排入的代次。读取运行之后,如果暂停与继续又排入了更新的代次,预留资源的事务会再核对一次并拒绝旧代次(START_SUPERSEDED):旧条目直接确认丢弃,不为它申请沙箱,也不把运行置为等待。
  • provisioner 返回失败或超时时,运行进入 sandbox_provisioner 等待,派发器指数退避重试;资源预留记为 unknown,由资源回收循环在收到释放回执后归还。

4.2 执行、验证与修复

sequenceDiagram
  participant W as runWorkflow
  participant E as executor
  participant V as verifier
  participant A as API
  W->>E: executeRun
  E->>A: 取得租约(fencing token)
  E->>E: 准备工作区,安装依赖
  E->>E: 执行器实现(事件持续上报)
  E->>A: 上传检查点,进入 verify
  W->>V: verifyRun
  V->>A: 取得租约
  V->>V: 从检查点恢复 → 导出无 .git 的目录 → 安装依赖 → 运行受保护命令
  V->>A: 提交验证证据(含输出尾部),控制面据此记录失败摘要
  alt 验证失败
    W->>A: repair(有修复轮数则回到 implement,否则进入 repair_exhausted 等待)
    W->>E: executeRun(提示词包含失败命令与输出)
  else 验证通过
    V->>V: 集成到目标分支(见 4.3)
  end
  • 租约 60 秒,每 10 秒心跳;心跳失败按退避重试,直到租约可能已经过期才放弃。租约丢失后不能再上传检查点,工作区连同 .recovery.json 留在本地供恢复。
  • 执行器的进度(消息、命令、文件变更、用量)规范化为事件,经 /internal/runs/:id/events 写入并通过 SSE 推送。Claude Code 与 CodeBuddy 只在会话正常结束时报告总用量;会话被暂停、取消或超时打断时,按会话流中每次模型响应自带的用量估算(同一响应只计一次),在时间线上标为估算,照常计入预算。最后一次响应的输出 token 可能少计。
  • 基础设施类失败(依赖安装失败、沙箱无法启动、Git 网络错误)记为 infrastructure 等待,不触发修复。验证命令自身超时(退出码 124)视为测试失败,进入修复。例外:检查点改动了依赖清单(package.json、go.mod、锁文件等)之后安装失败、且输出不像网络或仓库故障时,按一轮修复处理,失败类型为 install;修复轮中安装仍失败也照常启动执行器,并把安装输出交给它,否则执行器每次都会先装同样的坏清单,Agent 永远没有机会改。
  • 执行器失败或被暂停时,已完成的工作仍会导出为检查点,继续时从该检查点恢复,而不是从头开始。

4.3 集成与交付

  1. verifier 取得项目集成租约(控制面 fence,同一项目同时只有一个运行在集成)。
  2. 在独立的裸仓库(远端的缓存)中准备候选 commit:目标分支未移动时,候选就是已验证的 commit(快进);否则把已验证的 commit 合并到目标分支的最新提交上。
  3. 候选与已验证 commit 不同时,对候选重新执行完整验证。合并冲突时提交失败的集成证据(冲突文件与目标 commit),按一轮修复处理:修复轮先把最新目标分支合并进工作区,冲突标记交给执行器解决,检查点以该目标 commit 为基线。
  4. 非 GitHub 仓库:以 --force-with-lease + 祖先检查推送到目标分支;推送时目标分支又前进了,就基于新的提交重新准备候选(最多三次)。推送成功后提交集成证据。GitHub 仓库:推送 wishforge/<run>/<sha> 分支并创建 PR,等待合并(github_review),合并后在合并 commit 上重新验证,再提交集成证据。
  5. 项目未配置交付:控制面在收到集成证据后把运行置为 succeeded。
  6. 配置了交付:构建镜像(构建 commit 必须等于已验证 commit),提交构建证据,deployer 创建发布。构建因基础设施故障停下、继续时,如果合入的就是已验证的检查点 commit,并且受保护验证策略没有变,verifier 复用那次验证证据,只还原工作区来构建,不再重跑安装与检查;发布同样只接受本需求版本、本 commit、当前策略下的证据。策略变了,控制面不再提供旧证据,运行重新验证。

4.4 发布、审批与部署

sequenceDiagram
  participant Dp as deployer
  participant A as API
  participant H as 审批人
  participant R as Runner
  Dp->>A: POST /internal/releases(绑定证据)
  A->>A: 计算绑定摘要与风险
  alt 高风险或生产环境
    A-->>H: 等待审批(approval)
    H->>A: 批准(绑定摘要必须一致;生产环境中不能是请求人)
  end
  R->>A: 拉取任务(签名信封)
  A-->>R: deploy 任务
  R->>R: 蓝绿部署、健康与业务检查、切流
  R->>A: 回报结果(签名回执)
  A->>A: 部署证据 → 发布 healthy → 运行 succeeded
  • 发布绑定 commit、镜像 digest、架构、环境、配置版本、密钥版本引用、验证策略摘要与证据 ID;任一项变化都会使审批失效。
  • 风险由后端根据验证器上报的可信变更事实计算:受保护路径、数据迁移、权限扩大、生产环境。
  • 部署失败保留旧版本,环境锁随失败回执释放,运行回到等待,继续即可重新请求发布;结果未知时 Runner 先读回目标状态再回报(reconcile),仍无法确定时 owner/admin 在核对目标后解锁环境。回滚同样处理:Runner 回报回滚失败(当前版本继续服务)时释放环境;结果未知的回滚可以由 owner/admin 核对后解锁,回滚操作随之作废。
  • Runner 拉取任务时,跳过已经失效的就绪发布(运行取消、需求或代码变化、配置或审批失效),把它标记为失败并让对应运行回到等待,后面的发布照常部署;运行暂停中的就绪发布保留,继续运行后可能重新有效。
  • 审批 24 小时内有效;过期后发布失败,运行可以继续并重新请求发布。

4.5 云 IDE

  1. 用户在项目页请求工作区:API 写入 workspace 记录与 outbox(workspace.provision)。
  2. 派发器调用 provisioner POST /workspaces,平台托管仓库的项目同时带上仓库地址:kubernetes 后端创建 Kata Deployment、PVC、Service 与 NetworkPolicy(入站只允许网关;出站只有 DNS,有仓库时再放行平台 Git);local 后端返回本机 Theia 地址。
  3. 用户点击「打开 IDE」:Web 调用 API /v1/workspaces/:id/launch,API 向网关申请一次性启动码,浏览器跳转网关 /session?code=。
  4. 网关为每个 HTTP 请求与 WebSocket 连接向 API 校验成员资格与角色,并定期复核已打开的连接;撤销后立即断开。
  5. 会话建立后,网关以该用户的身份向 API 申请 15 分钟的仓库写令牌(/internal/workspaces/:id/git-credential,每次都复核成员资格与角色),交给工作区后端(Theia 策略扩展的 /wishforge-internal/git-credential,需要只有网关持有的 Theia 连接令牌,浏览器无法经网关访问该路径)。后端把令牌写进仓库之外的 Git 配置片段(Kubernetes 中是内存卷),由克隆通过 include.path 引用;首次收到时把目标分支克隆到以项目命名的文件夹。会话期间网关在令牌到期前 5 分钟续期,没有人打开 IDE 时令牌自然过期。
  6. IDE 与 Agent 之间只通过 Git commit 交接,人的改动也要经过验证才进入目标分支:
    • 推送范围:IDE 的令牌只能推送 ide/ 开头的分支。平台 Git 用 pre-receive 钩子执行这条限制,克隆默认在 ide/work 分支上工作。
    • 合入:愿望可以指定起点分支(sourceBranch),运行从该分支的最新提交开始,Agent 在这些改动上继续工作。之后的验证、修复与合入照常进行:目标分支是起点的祖先时快进,否则合并后重新验证,冲突按修复轮处理。发布风险按目标分支合入前后的全部差异计算,包括起点分支带来的提交。
    • 提交身份:取最近打开会话的用户(OIDC 的 name/email),可以用 git config 覆盖。
    • 外部仓库:如 GitHub 的仓库不克隆,那里的改动应走 PR。

4.6 经验沉淀与 Agent 配置

  • 修复反馈:验证失败时,控制面在运行上记录 lastFailure(失败命令、退出码、脱敏后的输出尾部,单条不超过 4 KiB)。修复轮的提示词包含它。
  • 项目经验(lesson):运行成功且经历过修复时,控制面生成一条经验:触发条件(失败命令与输出摘要)+ 解决方式(执行器在成功修复轮的最后总结)。同项目新运行的提示词注入最近 5 条启用中的经验,总长度不超过 4 KiB。管理员也可以手动添加项目约定类经验。
  • Agent 配置(bundle):内容寻址的不可变配置(规划/实现/修复提示词与模型)。租户策略记录当前激活版本与上一个版本;激活与回滚由 owner/admin 操作。运行在提交时固定版本,之后不再改变。

5. 数据模型

PostgreSQL,所有租户数据表都启用强制行级安全(app.tenant_id 会话变量),应用使用非超级用户、NOBYPASSRLS 角色。

表 用途
tenants 租户、配额与套餐快照
memberships 租户成员与角色
entities 领域实体(JSONB 文档,按 kind 区分),带版本号
run_events 运行事件,按运行递增序号,只追加
outbox 待派发任务,带认领期限
idempotency 幂等键与首次响应
usage_ledger 用量账本,只追加
audit_events 实体变更审计(触发器写入),应用只读
schema_migrations 已应用的迁移版本

主要实体(entities.kind):

kind 关键字段
project 名称、仓库地址与状态、目标分支、成员、验证命令、安装命令、验收配置、交付配置
wish 目标、验收标准、需求版本
run 阶段、状态、等待原因、执行器、预算与用量、执行代次、租约、检查点、已验证 commit、修复计数、最近失败、Agent 配置版本
checkpoint 运行、需求版本、源 commit、基线 commit、补丁、bundle(或产物引用)、可信变更分类
evidence 类型(verification / integration / build / deployment)、commit、命令结果、镜像 digest、隔离级别、签发者
environment 类型、架构、是否生产、配置版本、密钥引用、应用地址、当前与活跃发布
release / approval 发布绑定与状态;审批绑定摘要、过期时间、决定人
runner / runner_task Runner 注册(令牌哈希)、签名任务与回执
workspace IDE 工作区状态、上游地址、生命周期
provider_connection 加密的 BYOK 凭据
provider_proxy_request 模型代理请求的预留、结算与结果
github_operation PR 与合并操作
bundle / lesson Agent 配置版本;项目经验
policy 租户级策略(如当前激活的 Agent 配置)

实体以 JSONB 存储是有意的取舍(见第 10 节 ADR-3):所有字段在 packages/contracts 中显式声明类型,写入前用 zod 校验输入;按 projectId、runId、status 建表达式索引,列表查询通过索引过滤并分页。

6. 接口

前缀 调用方 认证
/v1/* Web BFF、脚本 OIDC access token(azp 等于 Web 客户端时为 human,否则为 connector);开发模式可用开发令牌
/mcp WorkBuddy、Codex 等 OIDC access token,身份固定为 connector
/internal/* worker、verifier、deployer、Runner、IDE 网关 运行级 JWT、静态服务令牌(限定租户与路由)、Runner 令牌、网关令牌
/provider-proxy/v1/* 执行器中的 Codex 运行级模型代理令牌
/health、/readyz、/metrics 探针、Prometheus /metrics 需要监控令牌

/v1 主要资源:projects(含 repository、workspaces、wishes、lessons、github、verification-profile)、runs(含 events、events/stream、commands、delivery、provider-requests)、lessons、releases(含 review、rollback)、approvals、environments(含 runners、application-url、deployment-secrets、unlock)、workspaces(launch、lifecycle)、provider-connections、providers、agent-bundles、verification-profiles、entitlements、plans、usage(含 lines、export)、admin。运行列表支持 project、limit(默认 100,最多 500)与游标 before(上一页最后一条的 createdAt);其他列表按项目权限过滤后返回。

MCP 工具:list_projects、submit_wish、get_run、get_run_events、answer_question、control_run、get_delivery、request_release。工具与 /v1 共用同一套领域逻辑与授权;连接器不能执行人工审批、凭据与环境管理。

错误统一为 { error: { code, message, details? } },HTTP 状态码与语义一致(400 校验失败、401 未认证、403 无权限、404 不存在或不可见、409 状态冲突、429 配额、503 未配置)。

7. 身份与信任模型

身份 来源 能做什么
human Web 客户端签发的 OIDC token 角色范围内的全部 /v1 操作,包括审批与配置
connector 其他 OIDC 客户端(MCP) 提交与控制愿望、查询、请求发布;不能审批、不能管理凭据与环境
executor 运行级 JWT(kind=worker,绑定租户/运行/代次,4 小时) 本运行的租约、心跳、事件、检查点、阶段推进(不能宣布成功)
verifier 运行级 JWT(kind=verifier) 本运行的验证、集成、构建证据与变更分类
coordinator 静态服务令牌(限定租户与路由) 只能查询运行状态、记录等待、请求修复;不能取得执行租约
deployer 静态服务令牌(限定租户与路由) 只能为已构建的运行取得租约、请求发布并推进到 release
runner 每个环境一个令牌(数据库只存哈希,可轮换) 拉取本环境的签名任务、回报结果
IDE 网关 每租户网关令牌 签发工作区启动码、查询授权(首次凭用户的 access token,之后按已授权的用户复核)、为有编辑会话的用户申请工作区的仓库写令牌

信任边界:

  • 执行器不可信:Agent 生成的代码、仓库中的脚本和测试都可能是恶意的。执行器拿不到原始模型密钥(生产经模型代理)、拿不到其他运行的令牌,也不能推进到 succeeded。Agent 的文件工具限定在工作区内,可以写入工作区里的 .git/config、.gitattributes,而 Git 对每条命令都读取仓库本地配置、没有环境变量能禁用它;因此在生成检查点和修复轮合并前,平台先把工作区的 .git/config 收敛到安全白名单(只保留 core 基础项、remote、branch、extensions),丢弃会执行命令的 filter/diff/merge 驱动、core.fsmonitor/sshCommand、[include] 和 url.*.insteadOf 传输改写。驱动名由 Agent 任选,-c 覆盖不了,配置本身才是着力点。
  • 验证器部分可信:它是平台代码,但运行不可信的测试。测试在不含 .git 的导出目录中执行,生产中再由 bubblewrap 隔离网络与文件系统;验证器的令牌和 Git 凭据不对测试进程可见。
  • 证据绑定:每条证据绑定需求版本、精确 commit 与执行代次;后续发布、审批都校验这些绑定,任何不一致都会拒绝。
  • 生产模式:WF_DEPLOYMENT_MODE=production 时拒绝开发令牌、拒绝 host 沙箱证据、要求模型代理与受保护验收配置、要求 HTTPS,发布审批需要请求人以外的第二个人。服务进程启动时必须显式设置部署模式。

8. 执行隔离

模式 使用场景 行为
host 本地开发(WF_DEPLOYMENT_MODE=development) local provisioner 在宿主机为每个代次启动 executor 与 verifier 进程,各自使用独立目录与独立令牌;命令直接以当前用户执行,macOS 上运维可以让受保护检查与依赖安装在 Seatbelt 中运行(见第 11 节)。本地 k3s(local-k3s.md)也使用这个模式,executor 与 verifier 运行在普通 runc Pod 中。证据标记 isolation: host。
kata 生产 kubernetes provisioner 为每个代次创建两个 Kata Job 与独立 PVC,无 Kubernetes API 令牌、无宿主机挂载;网络策略只放行 DNS、API(模型代理与检查点存储都经 API)、Temporal 与平台 Git;验证命令再经 bubblewrap 隔离。依赖安装经运维提供的出站代理访问包仓库(验证命令没有网络),镜像在运维提供的远程构建器上构建,只有 verifier 能连到它。

依赖安装(项目的安装命令或 wishforge.yaml 的 install)在执行器开始前与验证命令执行前各运行一次,允许访问网络(生产经出口代理);Agent 本身默认不开放外网。

Codex 在自己的命令沙箱中执行 Agent 的命令(Linux 上是 bubblewrap,macOS 上是 Seatbelt):只能写工作区,不能联网。executor 启动 Codex 前先探测这个沙箱能否启动。kata 模式下不能启动就以 PROVIDER_SANDBOX_UNAVAILABLE 停在基础设施等待,而不是让 Agent 的每条命令都失败、反复重试直到耗尽预算。host 模式只在开发部署中允许,此时改为不带命令沙箱运行,并在时间线上注明:本地 k3s 的 runc Pod 不允许 bubblewrap 创建用户命名空间,运行的 Pod 就是唯一的边界。

Claude Code 以受限模式运行(--restricted,权限模式 dontAsk):文件工具 Read、Edit、Write、Glob、Grep 只能访问工作区,也不加载仓库与用户的设置、钩子和 MCP 服务器。默认没有执行命令的工具,安装、测试、提交与发布都由独立的 verifier 完成。运维可以用 WF_CLAUDE_COMMAND_SANDBOX=true 让它在 Claude Code 自带的命令沙箱中使用 Bash:沙箱必须能启动(failIfUnavailable),命令不能在沙箱外运行;命令没有网络(本机端口也不行),只能写工作区、沙箱的临时目录和运行目录下的 command-scratch,不能读用户主目录与 worker 自己的目录(工作区、command-scratch 与 WF_CLAUDE_COMMAND_READ_PATHS 列出的路径除外),也看不到模型凭据。WF_CLAUDE_COMMAND_ENV 为命令提供工具链变量(如 GOMODCACHE)。executor 启动前先探测这个沙箱(macOS 上是 Seatbelt;Linux 上是 bubblewrap 与 socat),不能启动时只保留文件工具,并在时间线上注明;提示词按实际可用的工具写明约束。上线前在目标机器上运行 scripts/check-claude-command-sandbox.ts 验收。CodeBuddy 的 Agent 执行命令时没有自己的沙箱,所以只在 host 模式(开发部署)中运行,并在时间线上注明;kata 模式下以 PROVIDER_SANDBOX_UNAVAILABLE 停在基础设施等待。生产中这两个执行器都不可用,因为模型代理还不支持它们。

9. 部署拓扑

本地开发(详见 development.md):Compose 提供 PostgreSQL、Temporal、Keycloak、MinIO、镜像仓库;npm run dev:all 在宿主机启动 API、Web、平台 Git、coordinator/deployer worker 与 local provisioner;IDE 与网关按需启动。

生产(详见 operations.md):控制面(API、Web、Git、coordinator/deployer worker、provisioner、IDE 网关)运行在受信命名空间;运行沙箱与 IDE 工作区运行在独立命名空间的 Kata 节点池;PostgreSQL、Temporal、对象存储与密钥系统使用托管或高可用部署;Runner 部署在各目标环境。

10. 关键决策

编号 决策 理由与代价
ADR-1 用 Temporal 编排运行 长时间运行、等待人工、跨进程重试需要持久化编排;代价是多一个基础设施依赖。工作流只做编排,所有外部副作用在 activity 中执行并带幂等键。
ADR-2 每个运行代次独立的 executor/verifier 进程 令牌、工作区与故障域按代次隔离;代价是启动开销。本地用宿主机进程,生产用 Kata。
ADR-3 实体以 JSONB 文档存储 领域模型仍在快速演化,文档存储降低迁移成本;通过 TypeScript 类型、zod 校验、表达式索引与分页弥补。当运行与事件量需要时,再把 run、evidence 拆成独立表。
ADR-4 部署通过出站 Runner 拉取签名任务 客户环境不需要开放入站端口,平台不持有客户集群凭据;代价是部署延迟取决于 Runner 轮询间隔。
ADR-5 Agent 客户端通过 MCP 接入 WorkBuddy、Codex 等原生支持 MCP 与 OAuth,权限沿用用户身份,无需为每个客户端写适配。
ADR-6 RSI 限定在任务、项目与租户范围,晋升由人决定 自动的平台级元进化需要基准集、评估器与大量真实运行才有统计意义,在当前阶段不可验证,且有跨租户数据风险。
ADR-7 IDE 与 Agent 只通过 Git commit 交接 Git 已经提供精确、可审计的版本身份;IDE 快照、保存屏障等机制复杂且依赖 Theia 内部实现。
ADR-8 IDE 只推送 ide/ 分支,由从该分支开始的愿望验证并合入;令牌由网关按会话投递 目标分支只经由验证器的合入改变,人工改动与 Agent 改动走同一条验证与发布风险评估路径,也能借助修复轮修好。代价是人工改动要多提交一次愿望才能进入目标分支。工作区自己不能签发凭据,令牌只在有人打开 IDE 时存在,最长 15 分钟。

11. 已知限制

  • Temporal 连接使用客户端证书(生产必需),每个租户可以使用自己的命名空间(生产中多租户必需)。命名空间之间的授权依赖 Temporal 服务端按证书配置(见 operations.md 第 13 节)。同一租户的沙箱之间没有按任务队列的授权。
  • OCT 协作房间保存在内存中,服务重启后需要重新创建房间;已保存的文件不受影响。
  • Theia 后端与终端共用同一个 UID,同一工作区内的协作者之间没有强隔离;工作区只应授予可信成员编辑权限。
  • host 沙箱模式没有任何隔离,只能用于本机开发,并且只能运行你信任的代码与模型。macOS 上运维可以用 WF_HOST_CHECK_SANDBOX=true 让受保护检查与依赖安装在 Seatbelt 中运行(主目录内容不可读、只能写工作区与放行的缓存、检查没有网络、平台服务端口始终封锁),证据标记 checkSandbox: seatbelt;它不隔离执行器与验证器进程本身,证据仍是 isolation: host,生产不接受。上线前在目标机器上运行 scripts/check-host-check-sandbox.ts 验收。
  • macOS 上,Claude Code 命令沙箱的 Seatbelt 配置固定允许访问系统安全服务(com.apple.SecurityServer),所以沙箱中的命令可以查询登录钥匙串:信任 security 工具的条目可以被读取,其他条目会弹出授权提示。需要更强的隔离时,用单独的 macOS 用户运行本机服务,或者不打开 WF_CLAUDE_COMMAND_SANDBOX。

12. 需求验证矩阵

需求与自动化测试的对应关系(测试均在 CI 中运行;带「集成」标记的需要相应服务并通过环境变量显式启用)。P1 需求中涉及真实集群、真实 OAuth 客户端或浏览器界面的部分仍需按 M2 手动验收。

需求 测试
FR-A1 apps/web/src/lib/auth.test.ts
FR-A2、FR-A4、FR-C3 tests/control-plane.test.ts、tests/control-hardening.test.ts;集成:tests/integration/postgres.test.ts
FR-A3、FR-A6 tests/mcp.test.ts
FR-B1、FR-B2 tests/repository-input.test.ts、apps/git-service/test/service.test.ts
FR-B3 tests/verification-profile.test.ts、tests/control-hardening.test.ts(验证策略变化后旧发布失效)
FR-C1、FR-D6 tests/control-plane.test.ts(未配置的执行器不执行)、tests/control-hardening.test.ts(token 与时长预算)
FR-C2 tests/mcp.test.ts(事件游标)
FR-D1 packages/runtime/test/runtime.test.ts(Codex、CodeBuddy、Claude Code 适配器)、tests/providers.test.ts(目录与 worker 注册表一致、按可执行文件与生产代理判断可用性)
FR-D3 packages/runtime/test/verify.test.ts、packages/runtime/test/git-contract.test.ts(安装产物不进入检查点)
FR-G6 tests/application-access.test.ts、tests/mcp.test.ts
FR-C5、FR-C6 tests/run-lifecycle.test.ts;模型请求对账见 tests/provider-proxy.test.ts,部署失败与环境解锁见 tests/control-hardening.test.ts,执行异常的恢复见 apps/worker/test/recovery.test.ts
FR-D2、FR-D4、FR-E1–E5、FR-F1、FR-F2、FR-I2 tests/local-loop.test.ts、tests/verification-profile.test.ts(生产拒绝 host 证据)(真实 Git,进程内控制面,脚本化执行器)、packages/runtime/test/git-contract.test.ts、packages/runtime/test/verify.test.ts
FR-D5 tests/provider-proxy.test.ts
FR-J1、FR-J2 tests/entitlements-usage.test.ts、tests/control-plane.test.ts(暂停释放预留)
FR-K2 tests/migrations.test.ts;CI 的 PostgreSQL 任务连续执行两次迁移
FR-H1 apps/ide/gateway/test/gateway.test.mjs、apps/ide/gateway/test/gateway-handler.test.mjs、tests/internal-auth.test.ts
FR-C4 tests/local-loop.test.ts(提问 → 等待澄清 → 回答 → 完成)、packages/agent/test/prompt.test.ts
FR-H2 apps/ide/policy/test/git-workspace.test.cjs(克隆、令牌、ide/work)、apps/ide/gateway/test/gateway-handler.test.mjs(凭据投递)、tests/workspace-git.test.ts、apps/git-service/test/hooks.test.ts(ide/ 推送范围)、tests/local-loop.test.ts(IDE 分支经愿望验证合入,发布风险覆盖分支带来的改动)
FR-K5 tests/service-build.test.ts(构建全部服务并确认每个产物都能加载)
FR-D7 packages/runtime/test/runtime.test.ts(执行器事件)、tests/local-loop.test.ts(事件记录)
FR-K1 apps/provisioner/test/local.test.mjs(本地执行环境);完整的本地启动按 development.md 手动验证
FR-K6 .github/workflows/ci.yml