wishforge-ide/docs/architecture.md
eust-w addf330b10 ✨ Add account types and enforce per-user wish permissions
- Provide six account types and custom combinations of wish, code review,
  release and management permissions, applied on each authenticated request.
- Enforce frontend-only accounts when submitting, answering, widening and
  reverting wishes; require every contributor to have full access before
  skipping backend code review.
- Gate code review and release decisions by their specific permissions.
- Rework member management to create and edit account types, permissions and
  project access, and reflect those permissions throughout the console.
- Update the manual and architecture docs with permission tests and
  end-to-end coverage.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
2026-10-28 12:07:08 +08:00

426 lines
46 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# WishForge 架构设计
版本:2026-10-19 · 对应需求:[requirements.md](requirements.md)
本文描述系统的组件划分、运行状态机、关键流程、数据模型、接口、身份与信任模型以及部署拓扑。专题契约(仓库与 `wishforge.yaml`、受保护验收配置、模型代理、部署密钥、产物存储、管理台规范)见 [reference/](reference/)。
## 1. 总览
```mermaid
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。没有任何执行身份可以把运行置为成功、失败或回退阶段;成功只来自控制面对集成证据(无交付配置时)或部署验收的裁决。
```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 <base> -- :(literal)<path>` 恢复这些文件、删掉新建的(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/<run>/<sha>` 分支并创建 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` |