wishforge-ide/docs/architecture.md
eust-w 3217982f32 🔀 Merge project knowledge
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

# Conflicts:
#	apps/web/src/features/projects.tsx
#	apps/web/src/lib/types.ts
#	docs/architecture.md
#	docs/reference/ui.md
#	docs/requirements.md
#	docs/user-manual.md
#	tests/local-loop.test.ts
2026-11-04 12:45:22 +08:00

45 KiB
Raw Permalink 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 客户端]
  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
  LLM[模型服务商]

  Web -->|BFF /api → /v1| API
  MCPC -->|/mcp OAuth| 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/*。页面:概览、项目、运行、发布与审批、环境、执行器、用量。
控制面 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。两个后端:local(开发,宿主机进程)与 kubernetes(生产,Kata Job + PVC)。
Runner apps/runner 部署在目标环境侧,主动拉取 Ed25519 签名的部署任务并回报结果。

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 已验证的代码与目标分支冲突,且修复轮数已用完(轮数未用完时冲突自动作为一轮修复处理) 继续(基于最新目标分支再修复一轮)或取消
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 提交与派发

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 执行、验证与修复

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 发布、审批与部署

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 从已有分支开始的愿望

愿望可以指定起点分支(API 与 MCP 的 sourceBranch,例如自己推送到项目仓库的分支),运行从该分支的最新提交开始,Agent 在这些改动上继续工作。之后的验证、修复与合入照常进行:目标分支是起点的祖先时快进,否则合并后重新验证,冲突按修复轮处理。发布风险按目标分支合入前后的全部差异计算,包括起点分支带来的提交。人的改动因此也要经过验证才进入目标分支。工作台不提供选择起点的入口。

4.6 经验沉淀与 Agent 配置

  • 修复反馈:验证失败时,控制面在运行上记录 lastFailure(失败命令、退出码、脱敏后的输出尾部,单条不超过 4 KiB)。修复轮的提示词包含它。
  • 项目技能(skill):项目知识的唯一形式,分做法(workflow)、踩坑记录(pitfall)、项目约定(convention)三类(原 lesson 由迁移 004_lessons_to_skills 转为 pitfall / convention 技能)。
    • 踩坑记录:运行成功且经历过修复时,控制面把「触发条件(失败命令与输出摘要)+ 解决方式(成功修复轮的总结)」记成一条踩坑记录;按失败签名(验证/安装失败的命令,或冲突/越界的文件集合)去重,同一失败只在同一条技能前面追加记录(最多 8 条)并追加来源运行。
    • 做法:后台每 60 秒取一个尚未看过的成功运行,交给模型提炼;模型能看到项目全部技能(含踩坑记录与已停用的),可以通过 updates 补充已有技能。平台维护的技能(createdBy: wishforge 且没被人编辑过)可被改写;人写过的只记录来源运行。
    • 自动启用:项目设置 skillAutoActivation(缺省为开)。开启时踩坑记录直接启用,被两次成功运行提炼的提议自动启用,并发出 skill.activated 事件;其余提议保持「待确认」。关闭时一律待确认。
    • 效果跟踪:执行器进入实现阶段时,控制面把这一轮提示词里的技能记入 skill_usage(每个运行每条技能只计一次,累加 useCount、lastUsedAt)。运行成功时立即结算;失败、修复后取消由后台每 10 分钟结算(未失败就取消的不计)。平台维护的技能连续 3 次所在运行失败即停用(skill.retired),项目仍在运行但 90 天没被注入(被更新的技能挤掉)也停用;人写过的技能只显示失败次数。重新启用会清零连续失败。
    • 注入:同项目新运行的提示词注入最近修改的启用中技能,最多 12 条、总长度 2 万字。
    • 迁移:导出单条 SKILL.md 或项目 zip(每条一个目录,非 workflow 类型写在 metadata.wishforge-category);导入接受 SKILL.md 文件或 zip(存储或 deflate,zip 不超过 512 KiB、每个 SKILL.md 不超过 64 KiB、一次最多 50 条;非 SKILL.md 文件忽略),复制到其他项目保留内容、类型和状态,不带统计与来源运行。描述和内容完全相同的技能跳过,名字被不同技能占用时加序号。
  • 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 注册(令牌哈希)、签名任务与回执
provider_connection 加密的 BYOK 凭据
provider_proxy_request 模型代理请求的预留、结算与结果
github_operation PR 与合并操作
bundle / skill / skill_harvest / skill_usage 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 运行级 JWT、静态服务令牌(限定租户与路由)、Runner 令牌
/provider-proxy/v1/* 执行器中的 Codex 运行级模型代理令牌
/health、/readyz、/metrics 探针、Prometheus /metrics 需要监控令牌

/v1 主要资源:projects(含 repository、wishes、wish-refinements、skills(含 import、export)、github、verification-profile)、runs(含 events、events/stream、commands、delivery、provider-requests、code-review、revert)、skills(知识库;含 copy、:id/export)、releases(含 review、rollback)、approvals、environments(含 runners、application-url、deployment-secrets、release-policy、unlock)、local-accounts(本机部署)、capabilities、provider-connections、executor-settings、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 每个环境一个令牌(数据库只存哈希,可轮换) 拉取本环境的签名任务、回报结果

权限:每个人有四项权限(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)也使用这个模式,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。

生产(详见 operations.md):控制面(API、Web、Git、coordinator/deployer worker、provisioner)运行在受信命名空间;运行沙箱运行在独立命名空间的 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 交接(已随云 IDE 移除) 云 IDE(Theia 工作区、IDE 网关、OCT 协作)已从 WishForge 中移除。
ADR-8 人工改动经由从其分支开始的愿望验证并合入 目标分支只经由验证器的合入改变,人工改动与 Agent 改动走同一条验证与发布风险评估路径,也能借助修复轮修好。代价是人工改动要多提交一次愿望才能进入目标分支。原先 IDE 只能推送 ide/ 分支、令牌由网关按会话投递的部分随云 IDE 移除。

11. 已知限制

  • Temporal 连接使用客户端证书(生产必需),每个租户可以使用自己的命名空间(生产中多租户必需)。命名空间之间的授权依赖 Temporal 服务端按证书配置(见 operations.md 第 12 节)。同一租户的沙箱之间没有按任务队列的授权。
  • 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-C4 tests/local-loop.test.ts(提问 → 等待澄清 → 回答 → 完成)、packages/agent/test/prompt.test.ts
FR-H2(仅起点分支) tests/local-loop.test.ts(从已推送分支开始的愿望验证并合入,发布风险覆盖分支带来的改动)
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