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
412 lines
45 KiB
Markdown
412 lines
45 KiB
Markdown
# 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 客户端]
|
||
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。没有任何执行身份可以把运行置为成功、失败或回退阶段;成功只来自控制面对集成证据(无交付配置时)或部署验收的裁决。
|
||
|
||
```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 从已有分支开始的愿望
|
||
|
||
愿望可以指定起点分支(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](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。
|
||
|
||
**生产**(详见 [operations.md](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` |
|