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>
37 KiB
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
设计原则:
- 控制面是唯一事实来源。运行状态、证据、审批都由 API 在数据库中裁决;worker 只提交事实与请求,不能自行宣布成功。
- 执行与验证隔离。执行器(写代码的 Agent)与验证器使用不同身份、不同工作区;验证器只信任从检查点恢复的精确 commit。
- 外部副作用幂等、可对账。模型调用、Git 推送、构建、部署都带幂等键或 CAS;结果未知时进入可解除的等待,而不是盲目重试。
- 任何等待都有出口。等待原因是枚举值,每种原因都对应用户或运维的解除操作。
- 开发与生产走同一条链路。本地开发使用
localprovisioner 与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 集成与交付
- verifier 取得项目集成租约(控制面 fence,同一项目同时只有一个运行在集成)。
- 在独立的裸仓库(远端的缓存)中准备候选 commit:目标分支未移动时,候选就是已验证的 commit(快进);否则把已验证的 commit 合并到目标分支的最新提交上。
- 候选与已验证 commit 不同时,对候选重新执行完整验证。合并冲突时提交失败的集成证据(冲突文件与目标 commit),按一轮修复处理:修复轮先把最新目标分支合并进工作区,冲突标记交给执行器解决,检查点以该目标 commit 为基线。
- 非 GitHub 仓库:以
--force-with-lease+ 祖先检查推送到目标分支;推送时目标分支又前进了,就基于新的提交重新准备候选(最多三次)。推送成功后提交集成证据。GitHub 仓库:推送wishforge/<run>/<sha>分支并创建 PR,等待合并(github_review),合并后在合并 commit 上重新验证,再提交集成证据。 - 项目未配置交付:控制面在收到集成证据后把运行置为
succeeded。 - 配置了交付:构建镜像(构建 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
- 用户在项目页请求工作区:API 写入 workspace 记录与 outbox(
workspace.provision)。 - 派发器调用 provisioner
POST /workspaces,平台托管仓库的项目同时带上仓库地址:kubernetes后端创建 Kata Deployment、PVC、Service 与 NetworkPolicy(入站只允许网关;出站只有 DNS,有仓库时再放行平台 Git);local后端返回本机 Theia 地址。 - 用户点击「打开 IDE」:Web 调用 API
/v1/workspaces/:id/launch,API 向网关申请一次性启动码,浏览器跳转网关/session?code=。 - 网关为每个 HTTP 请求与 WebSocket 连接向 API 校验成员资格与角色,并定期复核已打开的连接;撤销后立即断开。
- 会话建立后,网关以该用户的身份向 API 申请 15 分钟的仓库写令牌(
/internal/workspaces/:id/git-credential,每次都复核成员资格与角色),交给工作区后端(Theia 策略扩展的/wishforge-internal/git-credential,需要只有网关持有的 Theia 连接令牌,浏览器无法经网关访问该路径)。后端把令牌写进仓库之外的 Git 配置片段(Kubernetes 中是内存卷),由克隆通过include.path引用;首次收到时把目标分支克隆到以项目命名的文件夹。会话期间网关在令牌到期前 5 分钟续期,没有人打开 IDE 时令牌自然过期。 - IDE 与 Agent 之间只通过 Git commit 交接,人的改动也要经过验证才进入目标分支:
- 推送范围:IDE 的令牌只能推送
ide/开头的分支。平台 Git 用 pre-receive 钩子执行这条限制,克隆默认在ide/work分支上工作。 - 合入:愿望可以指定起点分支(
sourceBranch),运行从该分支的最新提交开始,Agent 在这些改动上继续工作。之后的验证、修复与合入照常进行:目标分支是起点的祖先时快进,否则合并后重新验证,冲突按修复轮处理。发布风险按目标分支合入前后的全部差异计算,包括起点分支带来的提交。 - 提交身份:取最近打开会话的用户(OIDC 的 name/email),可以用
git config覆盖。 - 外部仓库:如 GitHub 的仓库不克隆,那里的改动应走 PR。
- 推送范围:IDE 的令牌只能推送
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 |