# WishForge 架构设计 版本:2026-10-19 · 对应需求:[requirements.md](requirements.md) 本文描述系统的组件划分、运行状态机、关键流程、数据模型、接口、身份与信任模型以及部署拓扑。专题契约(仓库与 `wishforge.yaml`、受保护验收配置、模型代理、部署密钥、产物存储、管理台规范)见 [reference/](reference/)。 ## 1. 总览 ```mermaid flowchart LR subgraph Clients[入口] Web[Web 工作台
apps/web] MCPC[WorkBuddy / Codex
MCP 客户端] IDE[云 IDE 浏览器] end subgraph Control[控制面] API[控制面 API
apps/api] PG[(PostgreSQL
RLS)] TMP[(Temporal)] S3[(对象存储)] GIT[平台 Git
apps/git-service] end subgraph Exec[执行面(每个运行代次独立)] COORD[coordinator worker] EXE[executor worker] VER[verifier worker] DEP[deployer worker] PROV[provisioner
local / kubernetes] end subgraph Target[目标环境] RUN[Runner
apps/runner] APP[应用] end GW[IDE 网关
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。没有任何执行身份可以把运行置为成功、失败或回退阶段;成功只来自控制面对集成证据(无交付配置时)或部署验收的裁决。 ```mermaid 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` | 已验证的代码与目标分支冲突,且修复轮数已用完(轮数未用完时冲突自动作为一轮修复处理) | 继续(基于最新目标分支再修复一轮)或取消 | | `target_broken` | 目标分支在运行期间前进了,合并结果未通过检查;不带本次改动的目标分支同样未通过,而运行的起点能通过,说明是之后推送的提交弄坏了分支。不消耗修复轮数 | 修好目标分支后继续(合并到最新代码并重新检查)或取消 | | `code_review` | 改动通过了受保护检查,但涉及项目设置里需要审核的路径(或运行从其他分支开始),在合入前等人审核 | 所有者或管理员批准(运行自动继续,复用这次验证直接合入)或驳回(审核意见作为补充需求交给执行器);继续不能绕过审核 | | `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 提交与派发 ```mermaid 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`):旧条目直接确认丢弃,不为它申请沙箱,也不把运行置为等待。 - 租户的执行名额占满时,运行保持排队(不是等待),派发器每 10 秒看一次名额,名额空出后几秒内开始。 - provisioner 返回失败或超时时,运行进入 `sandbox_provisioner` 等待,派发器指数退避重试;资源预留记为 `unknown`,由资源回收循环在收到释放回执后归还。 ### 4.2 执行、验证与修复 ```mermaid 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 永远没有机会改。 - 执行器失败或被暂停时,已完成的工作仍会导出为检查点,继续时从该检查点恢复,而不是从头开始。 - **代码范围**:愿望可以声明只改前端(`frontendOnly`)。执行器把项目的后端路径规则(`codeReview.paths` 减去 `exceptPaths`)写进提示词;verifier 在运行任何检查之前比较检查点的改动,改到后端路径时记一条失败的验证证据(`backendPaths`,不含命令),失败类型为 `scope`,按一轮修复处理。修复轮开始前执行器用 `git checkout -- :(literal)` 恢复这些文件、删掉新建的(Agent 默认只有读写文件的工具,取不回原内容也删不了文件),提示词告诉 Agent 只改前端重做。控制面另有一道防线:只改前端的运行请求代码审核时若带后端路径,直接拒绝(`FRONTEND_ONLY`),绝不集成。等待中的只改前端运行可以由人放开:补充需求时带 `allowBackend: true`,控制面清除 `frontendOnly`、把「代码范围改为前端和后端」写进新的需求版本,并记 `run.scope` 事件(含操作人);只有回答只改前端的运行时才接受这个参数(否则 `SCOPE_UNCHANGED`)。改动路径用 `git diff --no-renames` 计算,挪动的文件在新旧两个位置都算改到,代码审核和代码范围都不会被「挪到前端目录」绕过。 ### 4.3 集成与交付 1. **代码审核**:验证通过后、取得集成租约之前,verifier 把本次改动的路径交给控制面(`/internal/runs/:id/code-review`)。项目划出的后端代码(`codeReview.paths`,减去放行的 `exceptPaths`;glob,`dir/` 表示整个目录)被改到,或运行从其他分支开始时,控制面按**现在**的权限检查提出需求的每个人:提交人(`requestedBy`)和补充过需求、放开过代码范围或驳回过审核的人(`contributors`)。都能直接合入(许愿范围 `full`)时跳过审核,时间线记 `code_review.skipped`;否则记一条绑定需求版本与 commit 的待审核记录(`code_review`),运行停在 integrate 阶段的 `code_review` 等待。有 `reviewCode` 权限的人批准后运行自动继续,复用这次验证证据直接集成;驳回时审核意见作为补充需求,生成新的需求版本交给执行器。审核由控制面裁决:verifier 每次集成前都重新询问,继续运行绕不过去。请求人只有自己能直接合入时才可以批准自己的改动,生产模式下一律不能。 2. verifier 取得**项目集成租约**(控制面 fence,同一项目同时只有一个运行在集成)。 3. 在独立的裸仓库(远端的缓存)中准备候选 commit:目标分支未移动时,候选就是已验证的 commit(快进);否则把已验证的 commit 合并到目标分支的最新提交上。 4. 候选与已验证 commit 不同时,对候选重新执行完整验证。候选未通过某项检查时,verifier 先在不带本次改动的目标分支上单独跑到这项检查:目标分支能通过,说明问题出在两者合在一起,按一轮修复处理;目标分支同样失败,再检查运行的起点,起点能通过才说明是之后推送的提交弄坏了分支,运行进入 `target_broken` 等待,检查点换回已验证的 commit,不让执行器去改别人的代码;起点也失败时,这个运行可能正是来修它的,仍按一轮修复处理。这些对照检查不记录证据。合并冲突时提交失败的集成证据(冲突文件与目标 commit),按一轮修复处理:修复轮先把最新目标分支合并进工作区,冲突标记交给执行器解决,检查点以该目标 commit 为基线。 5. 非 GitHub 仓库:以 `--force-with-lease` + 祖先检查推送到目标分支;推送时目标分支又前进了,就基于新的提交重新准备候选(最多三次)。推送成功后提交**集成证据**。GitHub 仓库:推送 `wishforge//` 分支并创建 PR,等待合并(`github_review`),合并后在合并 commit 上重新验证,再提交集成证据。 6. 项目未配置交付:控制面在收到集成证据后把运行置为 `succeeded`。 7. 配置了交付:构建镜像(构建 commit 必须等于已验证 commit),提交构建证据,deployer 创建发布。集成或构建停下后继续时,如果检查点就是已验证的 commit(构建时还要求它就是合入的 commit),并且受保护验证策略没有变,verifier 复用那次验证证据,不再重跑安装与检查;集成时合并出的新候选仍会重新验证。发布同样只接受本需求版本、本 commit、当前策略下的证据。策略变了,控制面不再提供旧证据,运行重新验证。 **撤销运行**:`POST /v1/runs/:id/revert` 为一个已合入的运行创建撤销运行(`revertOf` 记下它合入的 commit 和合入前目标分支所在的 commit,取自集成证据)。撤销运行的第一轮不调用 Agent:executor 在目标分支最新代码上三方反向应用这两个 commit 之间的改动(`git apply --3way -R` 的效果),之后其他提交的改动保留;只有和之后的提交改到同一处、留下冲突标记时,才把冲突文件交给执行器解决。之后照常验证、审核、集成、构建与发布。同一运行已有进行中的撤销运行时返回那一个。 ### 4.4 发布、审批与部署 ```mermaid 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;任一项变化都会使审批失效。 - 风险由后端根据验证器上报的可信变更事实计算:受保护路径(鉴权、安全、计费、迁移、基础设施与 CI 的目录,任何名字的 Dockerfile 与 Containerfile、`.dockerignore`、Compose 文件,以及各语言的依赖清单与锁文件)、数据迁移、权限扩大、生产环境。变更范围是「环境当前运行的提交」到这次发布之间的全部差异(本机 POC 按这次要替换的组件计算,沿用原镜像的组件不计入),加上目标分支在本次合入中得到的改动,因此有人直接推到目标分支、或合入后从未部署过的提交,也会计入。环境运行的代码来源不明(提交不在仓库中,或本机 POC 的组件不是由发布部署的)时,分类标记为不完整,发布必须人工审批。 - 部署失败保留旧版本,环境锁随失败回执释放,运行回到等待,继续即可重新请求发布;结果未知时 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 操作。运行在提交时固定版本,之后不再改变。 ### 4.7 通知 配置了飞书自定义机器人(`WF_FEISHU_WEBHOOK_URL`,可选签名密钥 `WF_FEISHU_WEBHOOK_SECRET`)后,API 进程每 10 秒比对运行、代码审核与发布的当前状态,为新出现的状态发一条卡片消息:发布待审批与代码待审核(@ `WF_FEISHU_MENTIONS` 里的决策人,附「去审批」「去审核」链接,链接前缀取 `WF_NOTIFY_WEB_URL`),需要人处理的等待、运行完成、发布失败或回滚。每条消息有固定的键,飞书接受后记入 `notification`,服务重启不会重发也不会漏发;发送失败下次重试,并按次数退避。只通知 30 分钟内变化的状态,开启通知时不会补发历史。消息里来自运行的文字(愿望的第一行、等待说明)去掉了卡片标记,执行器写的改动说明不进入消息。 ### 4.8 优化愿望 `POST /v1/projects/:id/wish-refinements` 用本机 Claude 账号(与执行器相同的 `WF_CLAUDE_BIN`、`WF_CLAUDE_LOCAL_AUTH_HOME`)改写草稿:`claude -p` 不开任何工具(`--tools ""`)、不读设置与 MCP、不保存会话,在空目录中按内置规则加项目的 `wishRules` 生成最多三行的愿望(目标、范围、不改)、验收标准、只有用户能拍板的选择题(`questions`,最多 3 个,每个选项带一句选中后加进愿望的话)和提醒(`focus` 指明这次优化愿望、验收标准还是两者,优化验收标准时愿望原样返回、不出选择题),经 `--json-schema` 和 zod 校验后返回;个别格式不对的问题或选项被丢掉,不影响整个结果。结果不保存、不提交,由用户确认后自己提交。同时最多两个请求;用量不计入运行预算。 ## 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 配置版本;项目经验 | | `code_review` | 运行、需求版本、被审核的 commit 与基线、命中的路径、状态(pending / approved / rejected / invalidated)、决定人与意见 | | `local_account` | 本机部署的个人账号:登录名、显示名、scrypt 密码哈希、密码版本(重置后旧会话失效)、权限(`permissions`);角色由权限推出,存在 `memberships` | | `notification` | 已发送的飞书通知(以通知键为 ID,避免重复发送) | | `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`、`wish-refinements`、`lessons`、`github`、`verification-profile`)、`runs`(含 `events`、`events/stream`、`commands`、`delivery`、`provider-requests`、`code-review`、`revert`)、`lessons`、`releases`(含 `review`、`rollback`)、`approvals`、`environments`(含 `runners`、`application-url`、`deployment-secrets`、`release-policy`、`unlock`)、`local-accounts`(本机部署)、`capabilities`、`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;本机部署中为控制台以本机凭据转发、并附上个人账号与密码版本的请求(`X-WishForge-Local-User`,只在开发令牌下生效,控制台代理从不转发浏览器自带的这个头) | 权限范围内的全部 `/v1` 操作(见下文「权限」),包括审批与配置 | | connector | 其他 OIDC 客户端(MCP) | 提交与控制愿望、查询、请求发布;不能审批、不能管理凭据与环境 | | executor | 运行级 JWT(`kind=worker`,绑定租户/运行/代次,4 小时) | 本运行的租约、心跳、事件、检查点、阶段推进(不能宣布成功) | | verifier | 运行级 JWT(`kind=verifier`) | 本运行的验证、集成、构建证据与变更分类 | | coordinator | 静态服务令牌(限定租户与路由) | 只能查询运行状态、记录等待、请求修复;不能取得执行租约 | | deployer | 静态服务令牌(限定租户与路由) | 只能为已构建的运行取得租约、请求发布并推进到 release | | runner | 每个环境一个令牌(数据库只存哈希,可轮换) | 拉取本环境的签名任务、回报结果 | | IDE 网关 | 每租户网关令牌 | 签发工作区启动码、查询授权(首次凭用户的 access token,之后按已授权的用户复核)、为有编辑会话的用户申请工作区的仓库写令牌 | 权限:每个人有四项权限(`packages/contracts/src/permissions.ts`):许愿范围 `wish`(`none`、`frontend` 只改前端、`review` 前后端但后端改动要审核、`full` 前后端直接合入)、`reviewCode` 审核代码、`releases` 请求/审批/回滚发布(含 GitHub 合并授权)、`manage` 管理(包含其余全部)。本机部署的个人账号把权限存在 `local_account` 上,创建和修改时按六种账户类型(`admin`、`fullstack`、`reviewed`、`frontend`、`releaser`、`viewer`)或自定义组合给出,角色由权限推出(`manage`→admin,能许愿→developer,能审批发布→deployer,否则 viewer),其余按角色的检查不变;认证时权限随 Actor 带上,修改立即生效。没有个人权限的人(本机管理员、OIDC 用户、早于权限的旧账号)按角色取默认权限:owner/admin 全部,developer 为 `review`(项目的 `codeReview.trustedMembers` 可在该项目把它提到 `full`),deployer 只有 `releases`,viewer 什么都没有。 控制面在以下位置强制执行,不依赖控制台隐藏按钮:提交愿望(`none` 拒绝;项目划出后端代码时,`frontend` 的愿望一律 `frontendOnly`,显式要求改后端则拒绝);补充需求(`frontend` 不能补充可以改后端的运行,也不能用 `allowBackend` 放开代码范围);撤销(`frontend` 只能撤销只改前端的运行);代码审核决定(`reviewCode`);发布请求、审批与回滚(`releases`);集成前是否跳过审核(见 4.3)。 信任边界: - **执行器不可信**: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](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](development.md)):Compose 提供 PostgreSQL、Temporal、Keycloak、MinIO、镜像仓库;`npm run dev:all` 在宿主机启动 API、Web、平台 Git、coordinator/deployer worker 与 `local` provisioner;IDE 与网关按需启动。 **生产**(详见 [operations.md](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` |