📝 Add Git Wiki baseline: features, modules and droboticflow domain glossary

This commit is contained in:
wishforge 2026-11-08 06:11:57 -08:00
parent ee340d6a8b
commit d991e0b8e3
13 changed files with 1029 additions and 0 deletions

View File

@ -0,0 +1,76 @@
# 入口与权限:Web / MCP / IDE / 连接器
## 四类入口,同一套事实
| 入口 | 使用者 | 实现 | 能做什么 |
|---|---|---|---|
| Web 工作台 | 人 | `apps/web`(Next.js + BFF) | 全部操作,包括发布审批与 Diff 审核 |
| MCP | Codex / WorkBuddy 等 Agent 客户端 | `apps/api/src/mcp.ts`(Streamable HTTP) | 列项目、提交愿望、跟进、回答、控制、查询交付、请求发布 |
| 云 IDE | 开发者 | `apps/ide`(Theia)+ `apps/web/src/app/ide` | 编辑代码、推送 `ide/` 前缀分支 |
| 连接器配置 | 部署侧 | `connectors/`(Codex、WorkBuddy) | 把 MCP 服务接入第三方 Agent 客户端 |
四类入口共享同一控制面与同一权限模型,不存在「MCP 快捷通道」。MCP 工具说明明确写出:发布审批只在 Web 控制台进行(`apps/api/src/mcp.ts:43`)。
## MCP 工具清单(以代码为准)
`apps/api/src/mcp.ts` 注册了 8 个工具:
| 工具 | 作用 | 关键约束 |
|---|---|---|
| `list_projects` | 列出可提交愿望的项目 | 返回项目 ID、仓库、目标分支、是否配置验证 |
| `submit_wish` | 提交愿望,快速返回 `run_id` 与控制台链接 | 必须带 ≥8 字符的幂等键 |
| `get_run` | 读取阶段、状态、等待原因说明 | — |
| `get_run_events` | 按游标读取进度事件 | 游标是最后看到的 `seq` |
| `answer_question` | 补充信息 | 会创建新的需求版本并重新验证 |
| `control_run` | 暂停 / 继续 / 取消 | 取消不会回滚已上线的发布 |
| `get_delivery` | 读取验证证据、合入 commit、应用地址 | 只有被接受的回执才有地址 |
| `request_release` | 请求部署已验证并构建的 commit | 高风险发布仍需人工在控制台批准 |
「提交返回」不等于完成:工具说明要求客户端继续用 `get_run` / `get_run_events` 跟进,并用 `get_delivery` 报告结果。
## 权限模型:四种能力,六种账户类型
代码定义在 `packages/contracts/src/permissions.ts`。权限不是角色名,而是四个布尔/枚举能力:
- `wish`:`none | frontend | review | full`,决定能许愿改什么。
- `reviewCode`:能否批准/驳回别人的后端改动。
- `releases`:能否发起、批准、拒绝、回滚发布。
- `manage`:成员与权限、项目设置、环境、执行器与预算;包含其他全部能力(`normalizePermissions`,`packages/contracts/src/permissions.ts:41`)。
预置账户类型(`accountTypes`,`:25`):`admin`、`fullstack`、`reviewed`、`frontend`、`releaser`、`viewer`。项目级还可以用 `codeReview.paths` 定义「什么算后端代码」,并把某些路径放进 `exceptPaths` 放行。
> 文档差异:`docs/wishforge-summary.md:84-88` 用「全栈开发 / 后端需审核开发 / 前端开发」描述角色,源码里的对应物是 `fullstack` / `reviewed` / `frontend` 三种账户类型,加上 `reviewCode` 这一独立能力。以 `permissions.ts` 为准。
## 身份类型决定能做什么
`packages/contracts/src/index.ts:85` 定义了 actor 类型:`human | connector | worker | verifier | deployer`。校验不是只按角色,还按身份类型:
- 连接器(`connector`)不能完成人工审批、修改凭据或环境配置(`docs/requirements.md` FR-A6)。
- 执行器(`worker`)与验证器(`verifier`)只能写自己租约范围内的阶段与证据。
- 发布者(`deployer`)只能提交发布回执,不能伪造通用部署证据绕过签名回执(`tests/local-poc-delivery.test.ts:475`)。
## 幂等
所有创建与控制类写操作都要求幂等键:同一键重复请求返回同一结果,同一键不同内容返回冲突(`docs/requirements.md` FR-A4)。MCP 的 `submit_wish`、`answer_question`、`control_run`、`request_release` 都强制要求 `idempotency_key`,这就是为什么 Agent 客户端可以安全重试网络错误。
## 云 IDE 的边界
- 工作区打开时克隆项目仓库;有编辑会话时得到 15 分钟仓库令牌,令牌只允许更新 `refs/heads/ide/`。
- 平台 Git 的 pre-receive 钩子拒绝越界引用;所有推送只接受快进,不能删除分支。
- IDE 分支通过「从该分支开始的愿望」进入目标分支,与 Agent 改动走同一条验证与合入路径。
- 扩展必须来自平台预置白名单并校验摘要。
## 代码入口与测试集
| 关注点 | 入口 | 测试 |
|---|---|---|
| MCP 工具 | `apps/api/src/mcp.ts` | `tests/mcp.test.ts` |
| 权限与账户类型 | `packages/contracts/src/permissions.ts` | `tests/permissions.test.ts`、`tests/application-access.test.ts` |
| 身份与租约 | `apps/api/src/auth.ts`、`apps/api/src/domain/control-plane.ts:931` | `tests/internal-auth.test.ts`、`tests/auth-expiry.test.ts` |
| IDE 网关 | `apps/ide/gateway/`、`apps/web/src/app/ide/[id]` | `apps/ide/gateway/test/*.test.mjs` |
| 连接器 | `connectors/codex`、`connectors/workbuddy` | `tests/mcp.test.ts` |
## 已知边界
- 平台不提供应用访问网关;应用地址由目标环境负责访问控制。
- 访客(viewer)不能进入编辑会话;撤销成员资格后现有 IDE 连接会被关闭(`docs/requirements.md` FR-H1)。

View File

@ -0,0 +1,60 @@
# 控制台:进度、证据、报告与用量
## 控制台负责什么
`apps/web` 是 Next.js 工作台,职责是交互与 BFF 转换,**不直接触碰业务数据库**。所有业务事实来自 `apps/api`,前端只做展示与转发。这条边界可以在 `apps/web/src/app/api/[...path]/route.ts` 这类代理路由中看到,也由 `tests/console-bundle.test.ts` 保护:控制台可以打包 `packages/contracts` 的纯函数(例如 `permissions.ts`),但不能把服务端实现拉进浏览器包。
## 页面与能力
| 页面 | 前端入口 | 主要能力 |
|---|---|---|
| 概览 | `apps/web/src/features/dashboard.tsx` | 待确认、运行中、失败等聚合指标 |
| 运行列表 | `apps/web/src/features/runs.tsx:69` `RunsView` | 按阶段/状态筛选,进入详情 |
| 新建愿望 | `apps/web/src/features/runs.tsx:422` `NewWishView` | 目标、验收标准、模型选择、AI 优化 |
| 运行详情 | `apps/web/src/features/runs.tsx:789` `RunDetailView` | 阶段、事件、Diff、等待卡片、继续/取消/补充需求、代码审核、撤销改动 |
| 发布与审批 | `apps/web/src/features/releases.tsx` | 批准/拒绝、一键回滚、环境状态 |
| 项目设置 | `apps/web/src/features/project-settings.tsx` | 目标分支、验证命令、验证配置、可用模型、后端路径规则 |
| 成员与权限 | `apps/web/src/features/members.tsx` | 成员、账户类型与项目级权限 |
| 环境 | `apps/web/src/features/environments.tsx` | 环境与应用地址 |
| 执行器 | `apps/web/src/features/providers.tsx` | 模型/执行器连接与凭据 |
| 用量 | `apps/web/src/features/usage.tsx` | 月度 token、按运行明细、CSV 导出 |
| Agent 与技能 | `apps/web/src/features/agent.tsx`、`skills.tsx`、`lessons.tsx` | 提示词/模型版本、项目技能与经验 |
| 运行报告 | `apps/web/src/app/reports/wishes/[id]`、`apps/web/src/features/wish-report.tsx` | 单次愿望的交付报告 |
## 事件流与断线续读
- 查询历史事件:`GET /v1/runs/:id/events?after=<cursor>`(`apps/api/src/http.ts:444`)。
- 实时订阅:`GET /v1/runs/:id/events/stream`(`apps/api/src/http.ts:447`)。
- 事件类型的中文标签集中在 `apps/web/src/lib/events.ts:58` 的 `eventLabel`;新增事件类型而忘记补标签,会让详情页出现原始英文类型名,这是可观察的缺陷。
SSE 的设计要求是「断线重连后不丢失、不重复事件」(`docs/requirements.md` FR-C2),因此游标是接口契约的一部分,而不是前端缓存技巧。
## Diff 与代码审核
运行详情页展示生成的文件 Diff,后端审核卡片复用同一渲染。审核动作通过 `POST /v1/runs/:id/code-review`(`apps/api/src/http.ts:492`)提交,批准绑定被审核的 commit 与需求版本;批准后运行自动继续合入,不再重复检查。
## 证据展示
- 证据隔离标签:`apps/web/src/lib/evidence-isolation.ts`,用于让用户区分「沙箱内验证」与「本机 host 模式」的结果。
- 产物:`GET /v1/runs/:id/artifacts`(`apps/api/src/http.ts:502`),存储契约见 `docs/reference/artifact-storage.md` 与 `apps/api/src/domain/artifacts.ts`。
- 交付:`GET /v1/runs/:id/delivery`(`apps/api/src/http.ts:506`)。
## 报告与用量
- 运行报告:`apps/api/src/domain/wish-report.ts`,把一次运行的目标、验证证据、合入 commit 与交付结果整理成可读报告;测试 `tests/wish-report.test.ts`。
- 用量与配额:`apps/api/src/domain/usage.ts`、`entitlements.ts`;测试 `tests/entitlements-usage.test.ts`。关键语义是「暂停、等待中或已结束的运行不长期占用预留额度」,因此暂停后应能提交新愿望。
- 通知:`apps/api/src/domain/notifications.ts`;测试 `tests/notifications.test.ts`。
## 已知边界
- 控制台不做业务判定:所有状态与阶段以 API 返回为准,前端不做乐观状态机。
- 「待确认」指标同时聚合 `waiting` 运行、`awaiting_approval` 发布与 `pending` 审批;取消运行时应级联失效,否则会出现「运行已取消但待确认仍大于 0」的历史问题(`docs/wishforge-summary.md:217-221`)。
## 代码入口与测试集
| 关注点 | 入口 | 测试 |
|---|---|---|
| 页面组件 | `apps/web/src/features/*.tsx` | `tests/console-bundle.test.ts` |
| 前端纯逻辑 | `apps/web/src/lib/*.ts` | `apps/web/src/lib/*.test.ts` |
| BFF 代理 | `apps/web/src/app/api/[...path]/route.ts` | `tests/application-access.test.ts` |
| 事件与报告 API | `apps/api/src/http.ts:444-512` | `tests/local-loop.test.ts`、`tests/wish-report.test.ts` |

View File

@ -0,0 +1,57 @@
# 独立验证与自修复
## 客户看到的承诺
「Agent 说做完了」不构成交付。WishForge 采信的是验证器在**独立环境**里跑出的命令退出码与输出。客户能看到的证据包括:每条命令的退出码、耗时、输出摘要与输出尾部;失败信息会回灌给执行器触发自修复。
## 验证器为什么无法被被测代码欺骗
`packages/runtime/src/verify.ts:110` 的 `verifyWorkspace` 是这一机制的核心实现:
1. 先核对工作区 `HEAD` 等于检查点 commit,不等就报 `CHECKPOINT_CHANGED`(`:151-152`)。
2. 把该 commit 的树**导出到兄弟目录** `${workspace}-tree`(`:153-156`),被测代码不能修改验证器继续使用的仓库。
3. 在导出目录里 `git init` 并只 fetch 这个 commit 的对象(`:159-172`),因此仓库里的 Git 配置、hooks、历史都带不进来。验证器自身调用 Git 时还使用 `core.hooksPath=/dev/null`、`GIT_CONFIG_NOSYSTEM=1`、`GIT_CONFIG_GLOBAL=/dev/null`(`:144-146`)。
4. 安装依赖允许联网(`:193-202`),**检查命令默认不获得网络**;沙箱执行器由 `packages/runtime/src/sandbox.ts:34` 的 `isolatedVerifierExecutor` 提供。
这解释了文档里反复强调的「物理隔离」:不是靠提示词要求模型诚实,而是让作弊在文件系统与进程层面做不到。
## 受保护的验收配置(verification profile)
项目验证命令保存在平台上,但测试代码在仓库里,Agent 可以改写。因此生产交付还要求一份**运维独立安装**的验收配置:脚本构建进 verifier 镜像的 `/usr/local/lib/wishforge-verification/`,verifier 镜像根文件系统只读,配置按文件路径 + SHA-256 固定,随证据与发布绑定。
- 契约与安装说明:`docs/reference/verification-profiles.md`。
- 选择接口:`POST /v1/projects/:id/verification-profile`(`apps/api/src/http.ts:252`),只允许 owner/admin 人类操作,连接器不行。
- 生产模式下没有验收配置时进入 `verification_unconfigured` 等待,**不会**退回只跑仓库测试。
## 证据的内容与上限
- 输出尾部保留 `OUTPUT_TAIL_CHARS = 4000` 字符(`packages/runtime/src/verify.ts:36`),避免把巨量日志写进数据库。
- 超时退出码固定为 `124`(`packages/runtime/src/verify.ts:38`),与真实命令退出码区分。
- 证据类型 `CommandEvidence` 在 `packages/runtime/src/verify.ts:19` 定义;写入控制面走 `ControlPlane.evidence`(`apps/api/src/domain/control-plane.ts:1213`),必须带租约令牌。
## 自修复如何工作
验证失败时,失败命令与输出尾部被回灌给 executor,最多 `maxRepairRounds` 轮。边界要分清:
| 情况 | 处理 | 是否消耗修复轮 |
|---|---|---|
| 测试断言失败 | 回灌 executor 修复 | 是 |
| 沙箱启动失败、依赖安装失败、Git 访问失败 | 进入 `infrastructure` 等待 | 否 |
| 目标分支自身检查失败 | 进入 `target_broken` 等待 | 否 |
| 修复轮用尽 | 进入 `repair_exhausted` 等待,等人补充需求或再修复一轮 | — |
## 代码入口与测试集
| 关注点 | 入口 | 测试 |
|---|---|---|
| 精确 commit 验证 | `packages/runtime/src/verify.ts:110` | `packages/runtime/test/verify.test.ts` |
| 沙箱执行器 | `packages/runtime/src/sandbox.ts:34` | `packages/runtime/test/host-check-sandbox.test.ts` |
| 验收配置绑定 | `apps/api/src/domain/verification-policy.ts`、`apps/api/src/http.ts:252` | `tests/verification-profile.test.ts` |
| 自修复与轮次 | `apps/worker/src/verifier.ts`、`apps/worker/src/executor.ts` | `tests/run-lifecycle.test.ts`、`tests/control-hardening.test.ts` |
| 隔离证据 | `apps/web/src/lib/evidence-isolation.ts` | `apps/web/src/lib/evidence-isolation.test.ts` |
## 已知边界
- 验证配置变更会使此前的验证、构建与审批失效;这是有意的,避免用旧证据发布新代码。
- 开发模式可以没有验收配置,但其结果**不代表**受保护的生产验收。
- 空脚本或只做表面检查的验收配置不构成业务验收;平台只保证「配置被固定摘要执行」,不保证配置本身写得对。

View File

@ -0,0 +1,59 @@
# 合入、构建、发布与回滚
这是流水线的后半段:`integrate → build → release → accept`。客户需要理解一个核心事实:**运行成功(Run succeeded)与交付成功(delivered)不是同一件事**。配置了交付的项目,必须走完发布并由目标环境回报证据才算闭环。
## 合入(integrate)
- 合入权由租约串行化:`apps/api/src/domain/integration-lease.ts:24` 的 `IntegrationLeases`,每个项目同一时间只允许一个运行集成。
- 推送策略是「祖先检查 + `--force-with-lease`」,目标分支前进了就基于最新提交重新准备候选,最多三次;规则写在 `docs/reference/repository-contract.md`。
- 后端路径门禁:改动命中 `codeReview.paths` 且提交人权限不足时,验证通过后仍要停在 `code_review`,由有「审核代码」权限的人批准。批准绑定被审核的 commit 与需求版本。
- 声明「只改前端」的愿望若改到后端文件,平台在修复轮开始前把这些文件恢复到运行开始时的内容,失败类型为 `scope`。
## 构建(build)
`packages/runtime/src/build.ts:29` 的 `buildDockerImage` 负责镜像构建,产出不可变 digest。关键不变式:**构建所用 commit 必须等于已验证 commit**,不一致时拒绝构建证据(`docs/requirements.md` FR-F3)。
## 发布(release)
| 概念 | 实现位置 | 说明 |
|---|---|---|
| 发布绑定 | `apps/api/src/domain/releases.ts:42` `releaseBinding` | 把 commit、镜像 digest、架构、环境、配置版本、验证策略与证据绑定成一个摘要 |
| 发起发布 | `apps/api/src/domain/releases.ts:280` `request` | 需要验证证据与构建证据 |
| 审批 | `apps/api/src/domain/releases.ts:435` `decide` | 必须提交 `bindingDigest`;摘要不匹配即拒绝 |
| 交付查询 | `apps/api/src/domain/releases.ts:257` `delivery` | 只有被接受的回执才带应用地址 |
| 回滚 | `apps/api/src/domain/releases.ts:662` `rollback` | 生成新的回滚日志并签名下发 |
任何一项绑定内容变化(包括运维改了 POC profile)都会让审批失效,报 `POC_POLICY_CHANGED` 或等价的绑定校验错误。`tests/local-poc-delivery.test.ts:376-386` 专门覆盖「构建后改 profile → 审批被拒」。
风险计算在 `packages/contracts/src/release-risk.ts`:受保护路径、数据迁移、权限扩大、生产环境会提高风险,高风险发布必须人工审批,且**请求人不能批准自己的发布**,连接器也不能批准。
## 驻地交付(accept)与 POC 的真实约束
目标环境运行 `apps/runner`,以出站轮询拉取 Ed25519 签名任务,不需要公网入站端口。`docs/reference/poc-delivery-profile.md` 定义了对既有 `droboticflow` 命名空间的采用方式:
- 固定 Gitea 仓库、`poc` 分支、API server、namespace UID、三个 Deployment UID、容器名、镜像仓库、公网地址与固定摘要的 Kaniko 执行器。
- 只更新命名镜像与 `wishforge.d-robotics.cc/*` 审计注解;不重建 Service/Secret/RBAC/PVC/应用配置。
- 更新顺序固定为 Coordinator → Worker → API。多个 Deployment 不是事务,因此**跨服务协议不兼容的改动必须在发布前被策略拒绝**。
- 完成条件包括三个 rollout、精确就绪副本数、Pod 实际镜像 digest、配置指纹不变、公网健康/就绪/入口响应,以及签名发布里的业务冒烟检查。API 变更时 `/api/health.buildCommit` 必须等于交付的源码 SHA。
- 日志状态只有三种终态:`succeeded`、`rolled_back`、`needs_reconciliation`。
这些不是文档愿景,而是被测试固化的行为:`tests/local-poc-delivery.test.ts` 覆盖伪造回执不置为成功(`:446`)、缺少匹配的组件与 HTTP 证据前运行不成功(`:461`)、普通 deployer 不能用通用部署证据绕过签名回执(`:475`)、首次交付前不能凭空回滚(`:498`)、回滚日志携带前一版镜像与完整基线(`:506`)、不兼容回滚在取锁前拒绝(`:572`)。
## 回滚的边界
回滚只改回仍由本次发布拥有的镜像,不会覆盖更新的外部镜像;它**不回滚** Gitea 提交与数据库变更。配置漂移会停止自动补偿并进入对账。这与「撤销这次改动(Revert Run)」是两件不同的事:后者基于最新主干生成反向 Diff,重新走完整验证。
## 代码入口与测试集
| 关注点 | 入口 | 测试 |
|---|---|---|
| 发布绑定与审批 | `apps/api/src/domain/releases.ts` | `tests/local-poc-delivery.test.ts`、`tests/release-risk.test.ts` |
| Runner 队列 | `apps/api/src/domain/runner-broker.ts` | `tests/local-poc-delivery.test.ts`、`tests/control-hardening.test.ts` |
| 签名任务 | `packages/runtime/src/runner.ts`、`packages/runtime/src/poc-runner.ts` | `packages/runtime/test/poc-release.test.ts` |
| POC 构建与发布 | `packages/runtime/src/poc-build.ts`、`poc-release.ts` | `packages/runtime/test/poc-release.test.ts`、`tests/local-poc-delivery.test.ts` |
| 交付适配 | `apps/runner/src/adapters.ts` | `apps/runner/test/local-entry.test.ts` |
## 已知边界
- 发布审批只在 Web 控制台进行;MCP 可以发起请求,但不能代替人批准。
- 回执里的应用地址由目标环境提供,平台不提供应用访问网关;唯一的 HTTP 例外是本地 POC 绑定的开发项目,且在生产模式被拒绝(`tests/local-poc-delivery.test.ts:401-419`)。

View File

@ -0,0 +1,60 @@
# 运行生命周期与等待出口
## 八阶段流水线
阶段定义在 `packages/contracts/src/index.ts:20`:
```
clarify → plan → implement → verify → integrate → build → release → accept
```
运行状态定义在同一文件的 `:22`:`queued / running / waiting / paused / succeeded / failed / canceled`。阶段与状态是两个正交概念:阶段说「做到哪一步」,状态说「现在是否在推进」。
## 谁在推进状态
- 工作流编排:`apps/worker/src/workflows.ts:16` 的 `runWorkflow`。executor、verifier、release 各是一个 activity;模型、构建、部署类 activity 的 `retry.maximumAttempts` 都是 1(例如 `apps/worker/src/workflows.ts:63-76`),因为**未知结果的外部副作用不允许自动重放**。
- 状态写入:`apps/api/src/domain/control-plane.ts`。提交 `:358`、领取租约 `:931`、阶段迁移 `:1076`、证据 `:1213`。所有迁移都要求租约令牌(lease token),过期执行者无法写入。
- 执行代次(generation):`apps/worker/src/workflows.ts:41-53` 用 `Set` 记录已见代次,延迟到达的旧信号不能把运行拉回旧身份;`tests/execution-generation.test.ts` 覆盖这一行为。
## 18 种等待原因,每一种都有出口
`packages/contracts/src/index.ts:25-44` 定义了 18 个等待原因:
`credentials`、`git_storage`、`sandbox_provisioner`、`worker_unavailable`、`budget`、`clarification`、`verification_unconfigured`、`repair_exhausted`、`infrastructure`、`provider_error`、`ambiguous_execution`、`integration_conflict`、`target_broken`、`code_review`、`github_review`、`github_unconfigured`、`approval`、`deployment`。
每个原因在 `apps/web/src/lib/waiting.ts:15` 都有中文标题、可执行动作、可选链接,以及「继续」是否有效的 `resumable` 标记。这不是装饰:`waitingGuides` 的类型是 `Record<WaitingReason, WaitingGuide>`,**新增等待原因而不同时补齐前端指引会直接类型检查失败**,这是把「不允许死锁」写进类型系统的做法。
> 文档差异:`docs/wishforge-summary.md:166` 写「16 种结构化等待原因」,源码是 18 种(多了 `github_unconfigured` 与 `worker_unavailable` 等)。以源码为准。
## 三类出口的实际语义
| 出口 | 语义 | 代码路径 |
|---|---|---|
| 继续 / resume | 用信号唤醒工作流;同一代次内不重放未知副作用 | `apps/worker/src/workflows.ts:45-53`、`apps/api/src/http.ts:499` 之后的命令接口 |
| 补充需求 / answer | 生成新的需求版本;旧版本的验证证据与审批失效 | `docs/requirements.md` FR-C3;`apps/api/src/domain/control-plane.ts` 的 `submit` 与命令处理 |
| 取消 / cancel | 终止运行,并级联失效关联的发布单与审批单 | `docs/wishforge-summary.md:217-221` |
`ambiguous_execution` 特别值得客户理解:它表示「一次外部操作结果未知」,系统**故意**不自动重试,而是要求人查看阶段事件后决定。自动重试在这里会造成重复部署或重复写库。
## 修复轮与等待的边界
- 测试失败会回灌 executor 自修复,最多 `maxRepairRounds` 轮,用尽后进入 `repair_exhausted`。
- 基础设施类失败(沙箱启动失败、依赖安装失败、Git 访问失败)进入 `infrastructure`,**不消耗修复轮数**。
- 目标分支自身被别人的提交弄坏时进入 `target_broken`,同样不消耗修复轮数,也不归因于本次愿望。
这三条区分的验收标准写在 `docs/requirements.md` FR-E5 与 FR-C6。
## 代码入口与测试集
| 关注点 | 入口 | 测试 |
|---|---|---|
| 阶段/状态/等待原因契约 | `packages/contracts/src/index.ts:20-47` | `tests/control-plane.test.ts` |
| 工作流推进与信号 | `apps/worker/src/workflows.ts` | `tests/run-lifecycle.test.ts`、`tests/execution-generation.test.ts` |
| 状态迁移与租约 | `apps/api/src/domain/control-plane.ts` | `tests/control-hardening.test.ts`、`tests/integration-lease.test.ts` |
| 等待提示 | `apps/web/src/lib/waiting.ts` | 类型检查(`npm run typecheck`) |
| 派发与恢复 | `apps/worker/src/activities.ts`、`apps/api/src/dispatcher.ts` | `tests/dispatcher.test.ts` |
## 已知边界
- 暂停不是「释放资源」:暂停的运行仍占并发名额的实现细节见 `docs/requirements.md` FR-J2 与 `apps/api/src/domain/entitlements.ts`。
- 运行成功不等于交付成功:配置了交付的项目还要经过 build/release/accept,见 [integration-build-release-rollback](integration-build-release-rollback.md)。

View File

@ -0,0 +1,54 @@
# 提交愿望与需求优化
## 客户看到的是什么
一个「愿望」由**目标**和**至少一条验收标准**组成,提交后在隔离环境中由编码 Agent 实现。页面上的表单是最小契约:缺验收标准不能提交;不可用的执行器在表单里不可选,并显示原因。
提交入口:
- 工作台「+ 提交愿望」:`apps/web/src/features/runs.tsx:422`(`NewWishView`)。
- 控制面接口:`POST /v1/projects/:id/wishes`,定义在 `apps/api/src/http.ts:416`,返回 `202`,因为运行是异步推进的。
- MCP 连接器:`submit_wish`(`apps/api/src/mcp.ts:87`),供 Codex/WorkBuddy 使用。
## 愿望文本的固定格式
`packages/contracts/src/wish.ts` 定义了愿望标题与详情的解析规则:
- `wishTitle(goal)` 只取第一行作为列表、标题和消息里显示的目标(`packages/contracts/src/wish.ts:5`)。
- `wishDetails(goal)` 取第一行之后的全部内容,作为需求与限制(`packages/contracts/src/wish.ts:11`)。
- `withAnswers(goal, answers)` 把用户在澄清卡片里选择的答案插入到「不改:」之前;没有「不改:」时追加到末尾(`packages/contracts/src/wish.ts:18`)。这条规则保证补充答案不会覆盖用户明确写下的不可破坏约束。
因此工作台与文档推荐的三段式(目标 / `范围:` / `不改:`)不是提示词风格建议,而是**被解析代码固化的结构**:第一行一定会被单独抽取展示,`不改:` 行一定会被保留在答案之后。
## AI 优化愿望
`POST /v1/projects/:id/wish-refinements`(`apps/api/src/http.ts:409`)调用 `WishRefiner`(`apps/api/src/domain/wish-refiner.ts:113`)。行为要点:
- 使用项目规则与内置 `WISH_RULES` 一起改写草稿(`apps/api/src/domain/wish-refiner.ts:10`)。
- 首选模型是 `deepseek-flash@latest[1m]`,失败后回退到 `deepseek-pro@latest[1m]`;两个模型都可由环境变量覆盖(`apps/api/src/domain/wish-refiner.ts:98-104`)。
- 返回不可用时明确报错,而不是伪造一份「优化后的愿望」(`tests/wish-refiner.test.ts:131`)。
## 模型白名单
项目设置里只允许使用管理员勾选的模型;`GET /v1/models`(`apps/api/src/http.ts:218`)通过受保护通道从模型网关拉取清单,`PATCH /v1/projects/:id` 写入 `models`(`apps/api/src/http.ts:302-344`)。这解决两个现实问题:手输模型名容易漏掉 `[1m]` 这类上下文后缀;企业需要可控的模型范围。
## 边界与常见误解
- **验收标准必须是可自动判定的断言。** 平台只采信命令退出码与输出,不采信 Agent 的文字陈述;主观标准(「体验更流畅」)无法形成证据。
- **优化愿望不会替用户做业务决策。** 它只整理表达,不访问仓库,因此不会补出代码事实。
- **提交是异步的。** `202` 只表示运行已建立,后续必须在运行详情或 MCP 的 `get_run` 跟进。MCP 工具说明里明确写了「A finished agent turn is not a verified delivery」(`apps/api/src/mcp.ts:43`)。
## 代码入口与测试集
| 关注点 | 入口 | 测试 |
|---|---|---|
| 愿望解析与标题 | `packages/contracts/src/wish.ts` | `tests/wish-refiner.test.ts:147`(wish format) |
| 需求优化 | `apps/api/src/domain/wish-refiner.ts` | `tests/wish-refiner.test.ts:35` |
| 提交路由 | `apps/api/src/http.ts:416` | `tests/control-plane.test.ts`、`tests/local-loop.test.ts` |
| 工作台表单 | `apps/web/src/features/runs.tsx:422` | `tests/console-bundle.test.ts`、`apps/web/src/lib/*.test.ts` |
| MCP 提交 | `apps/api/src/mcp.ts:87` | `tests/mcp.test.ts` |
## 已知边界(首版核对)
- 愿望一旦提交,目标文本本身不可原地编辑;补充需求会生成新的需求版本,并使旧版本的验证与审批失效(`docs/requirements.md` FR-C3)。
- 表单中的「不可用执行器」判定来自项目连接与凭据状态,不由前端猜测。

View File

@ -0,0 +1,194 @@
# 受控 Domain Glossary:droboticflow 业务规则与算子约束
## 这份文档是什么
这是从 `droboticflow` 仓库迁移过来的**受控业务词汇表**。它只回答一个问题:**哪些业务规则是硬约束,执行点在哪一行代码,违反时系统会怎样。**
- 来源仓库:Gitea `longtao.wu/droboticflow`;本地核对副本 `/Users/d-robotics/Desktop/fanyu/droboticflow`。
- 核对版本:`877307cb`(`877307cbe2616a00aee1086221d5aa1a1119a10e`,2026-10-27 16:28 +0800)。
- 收录标准:必须能在代码中找到执行点(handler、校验函数、唯一索引、运行时注入),并至少有一个测试文件覆盖。**纯愿景、计划稿、会议结论不收录**,见文末「未收录」。
- 引用格式:`仓库相对路径:行号`。`internal/`、`custom-operators/`、`tests/` 均指 droboticflow 仓库。
- 与 WishForge Wiki 的关系:WishForge 的 Wish 会修改这个仓库。编码 Agent 在动手前应读本页,避免「测试通过但业务规则被破坏」。
## 规则索引
| 编号 | 规则 | 领域 |
|---|---|---|
| BR-01 | 三类人工角色领取后不能主动释放任务 | 标注协作 |
| BR-02 | 切片名称必须来自项目启用字典,名称按组织+用途防重 | 标注规范 |
| BR-03 | 舍弃必须选择项目字典原因,原因以服务端快照为准 | 标注规范 |
| BR-04 | 切片必须完整分区共同时间范围,空区域不自动赋义 | 标注规范 |
| BR-05 | 无效动作属于外层切片内部,整理必须显式选择并重新验证 | 标注规范 |
| BR-06 | 随机领取只返回数量,不泄露候选 | 标注协作 |
| BR-07 | 人工编辑以版本号乐观锁,冲突返回 409 | 标注协作 |
| OPR-01 | 算子必须遵循统一运行时环境契约 | 算子约束 |
| OPR-02 | 大对象不得内联,必须走受控引用 | 算子约束 |
---
## BR-01 三类人工角色领取后不能主动释放任务
**规则**:标注员、质检员、最终验收员领取 `annotation-qa` 人工任务后,不能主动释放回公共池;接口返回 403。管理员改派与管理操作仍然保留;标注员仍可在本人任务中重新切片,不退回公共池。
**执行点**:
- `internal/api/human_loop.go:1286-1290`:`handleHumanItemRelease` 先判断 `annotationWorkerCannotRelease(principal) && item.PluginID == "annotation-qa"`,命中即写 `human_task_release_forbidden`(标注员为 `annotator_release_forbidden`)并返回 403。
- `internal/api/human_loop.go:1299-1303`:通过角色检查后,仍只允许「领取人本人或管理员」释放,且状态必须是 claimed/in_progress。
**测试依据**:`internal/api/annotation_random_claim_test.go:185`(标注员不能释放或选择未领取任务,管理员仍可释放)、`:206`(质检员不能释放)。
**违反后果**:403 + 明确错误码;任务归属不变,不会造成任务在池中重复被领取。
**WishForge 关联**:任何修改人工任务释放、改派、重新切片权限的 Wish,必须同时更新 `docs/annotation-five-rules.md` 与上述测试。
---
## BR-02 切片名称必须来自项目启用字典,名称按组织+用途防重
**规则**:新确认的切片名称必须来自本项目启用的切片字典,界面名称只读、用选择器;多个实际切片可同名,拆分沿用名称,不追加 A/B。字典名称按「组织 + 字典用途」分别防重,比较时忽略首尾/连续空白与大小写。历史已保存名称原样保留,不自动改写历史产物。
**执行点**:
- `internal/domain/annotation_labels.go:22`:`NameKey` 字段(`json:"-"`,仅用于唯一性)。
- `internal/api/annotation_labels.go:337-360`:`DictionaryNameKey(kind, name)` 生成规范化键,并在批量写入前用 `seenNames` 拒绝同组重复。
- `internal/api/unified_dictionary_mongo_test.go:40`:Mongo 对 `{organizationId, nameKey}` 建唯一索引 `organizationId_nameKey_unique`(partial filter 只作用于字符串 nameKey),并发写入只有一条成功。
**测试依据**:`internal/api/unified_dictionary_mongo_test.go`(唯一索引与并发)、`internal/store/dictionary_names_test.go`(历史名称与规范化)、`internal/api/annotation_five_rules_test.go`(非法/跨项目/停用词条不能确认)。
**违反后果**:新增/改名/项目配置被拒绝;历史重复不删除、不合并,需管理员显式处理。
**WishForge 关联**:改字典写入路径时,**不能**绕过 `DictionaryNameKey` 直接写 `name`,否则唯一索引失效且历史兼容规则被破坏。
---
## BR-03 舍弃必须选择项目字典原因,原因以服务端快照为准
**规则**:项目已配置字典时,舍弃片段必须单选项目已有原因;「其他」及要求说明的词条必须填写说明,最多 1000 字。项目未配置字典时允许手填非空原因。恢复(保留)不依赖字典可用性。词条名称、版本、ID 由服务端确认,客户端提交的值不能篡改。
**执行点**:
- `internal/api/slice_disposition.go:533-546`:服务端先清空 `DiscardReasonLabelID/Version/Name`,只有在 `reasonLabel != nil` 时才用**服务端查到的** `reasonLabel.ID/Version/Name` 覆盖;客户端字段不直接落库。
- `internal/api/slice_disposition.go:164-190`:合并/拆分时继承已保存的原因与版本,并校验候选一致性。
**测试依据**:`internal/api/slice_disposition_test.go:20`(接口校验与版本冲突)、`internal/api/discard_reason_manual_test.go:33`(未配置字典时手填原因的字段形态)、`tests/backend/test_slice_discard_package.py`(真实双目/PTS/IMU 审核文件与交付过滤)。
**违反后果**:请求被拒绝(400/409);历史记录不被追写,字典改名/停用不影响已保存快照。
---
## BR-04 切片必须完整分区共同时间范围,空区域不自动赋义
**规则**:切片分区共同有效范围;描述分区每个切片;相邻描述共享边界,编辑边界同时更新两侧;空区域不自动赋义,最终提交拒绝未覆盖区域与重叠。`hardware-frame-v1` 边界网格把整数硬件时间戳映射到双目帧索引与 CFR 左视频媒体时间;内部边界必须同时推进两个相机索引;区间半开。
**执行点**:
- `internal/api/human_slice_materialization.go:959`:同步 JSON 写入 `window.semantics = "half-open"`、`commonRange` 与逐片边界。
- `internal/api/human_slice_materialization.go:994`:`coverage` 声明 `mode = "full_common_range"`、`contiguous = true`、`gapMicroseconds = 0`、`overlapMicroseconds = 0`,并记录双目帧数与 IMU 行数。
**测试依据**:`internal/api/annotation_boundary_grid_test.go`、`internal/api/human_slice_materialization_test.go`、`internal/api/annotation_operations_test.go:78`(完整分区被接受)、`tests/frontend/unified-annotation-boundaries.test.mjs`。
**违反后果**:最终提交被拒绝;导出的媒体与 JSON 覆盖不一致,下游交付不可用。
---
## BR-05 无效动作属于外层切片内部,整理必须显式选择并重新验证
**规则**:把动作标记为无效不新增外层切片边界。送检前可识别「连续三个保留切片同名、首尾精确相接、中间切片被明确无效动作完整覆盖」的候选,由用户逐项选择是否合并;取消选择保留原划分。服务器重新验证选择后才改变送检版本的外层划分;动作数组(ID、描述、无效判断、起止、硬件时间戳)不因合并改变。
**执行点**:
- `internal/api/annotation_invalid_slice_consolidation.go:13`:`consolidateInvalidActionSlices(input, actions, selected)` 只处理被显式选中的候选;`:76` 记录 `consolidate_invalid_actions` 操作与原切片快照。
**测试依据**:`internal/api/annotation_invalid_slice_consolidation_test.go:16`(选中合并)、`:34`(未选择保留原划分)、`:49`(非法选择被拒绝)、`:66`(重叠候选合成连续区间)。
**违反后果**:非法选择被拒绝且不占用任务;已送检/已审核任务不被自动修改。
---
## BR-06 随机领取只返回数量,不泄露候选
**规则**:`claim-count` 只返回选定项目内、当前标注员具有有效供应商权限、处于可领取阶段的数量;不返回候选 ID、视频或排序。数量是读取瞬间快照;领取仍以服务端原子竞争结果为准。跨项目、非标注员、无有效供应商权限一律 403。
**执行点**:
- `internal/api/annotation_random_claim.go:84-163`:`handleAnnotationClaimCount` 校验角色、项目归属/状态、供应商有效性,只累加 `count`,最终返回 `{projectId, count}`。
- `internal/api/human_loop.go:1193`:领取接口拒绝「指定任务领取」(`random_claim_required`)。
**测试依据**:`internal/api/annotation_five_rules_test.go:53`(数量与私有池一致,领取后数量变化,跨项目/无权限 403)。
**违反后果**:泄露候选列表会让「随机」变成「挑选」,破坏质检公平性;因此任何返回候选 ID 的改动都是规则违反。
---
## BR-07 人工编辑以版本号乐观锁,冲突返回 409
**规则**:所有人工任务写操作必须提交 `version`;服务端版本不匹配返回 409 `version_conflict`,不覆盖他人编辑。
**执行点**:
- `internal/api/human_loop.go:1171`、`:1232`:两处统一返回 `Human item version conflict` + `code: version_conflict`。
**测试依据**:`internal/api/slice_disposition_test.go:44`(过期版本 409)、`internal/api/human_loop.go:1171` 与 `:1232` 两处统一冲突响应、`docs/review-draft-conflict-recovery.md`(草稿冲突恢复流程)。
**违反后果**:并发编辑不会静默丢失;客户端必须刷新后重试。
---
## OPR-01 算子必须遵循统一运行时环境契约
**规则**:算子不是「函数调用」,而是受平台约束的一次节点执行。worker 先把上游 artifact 汇总到 `INPUT_ARTIFACTS_PATH`,节点配置通过 `NODE_DATA_JSON` 注入,算子在 `OUTPUT_DIR` 产出业务文件,worker 再收集 `RESULT_OUTPUT_PATH` 与 `STAGE_MANIFEST_PATH`。
**执行点**:
- `internal/worker/executor.go:792`:注入 `INPUT_ARTIFACTS_PATH` 等环境变量。
- `internal/worker/executor_test.go:74`:断言 `INPUT_ARTIFACTS_PATH` 被填充。
- `custom-operators/h2r-rgbd-pipeline/operator.py:64`:自定义算子读取 `INPUT_ARTIFACTS_PATH`。
- `lightweight-operators/ubt-mcap-pipeline/ubt_pipeline/common.py:116`:轻量算子同样读取该变量。
**违反后果**:算子拿不到输入或产出不被收集,节点显示成功但下游无数据。
**设计含义**:新增算子时先回答五个问题——输入是结构化 JSON、远程引用还是本地路径;输出是否被下游消费;是否有真实外部副作用;失败是否幂等可重试;验收看平台记录还是外部系统。
---
## OPR-02 大对象不得内联,必须走受控引用
**规则**:大视频、大包体结果不得写进日志或 Mongo;必须使用 `artifact.path`、`dataRef.payloadPath`、共享 PVC 或对象存储引用。仅当结构化 JSON 不需要引用时才允许 `payload.inline`。
**执行点**:
- `internal/worker/artifact_storage.go:373-377`:只有在 `structuredJSONRequiresReference` 为假时才写 `ArtifactTransferModeInline`。
- `internal/worker/artifact_storage.go:413`:否则必须提供 worker 可访问的路径或持久引用,否则报 `artifact_externalization_failed`。
- `internal/worker/executor_test.go:211`:小输入清单保持 inline 的便利性;`:405` 覆盖 `payloadPath` 形态。
**测试依据**:`internal/worker/executor_test.go`、`internal/worker/runtime_test.go:161`(读取 `payloadPath`)。
**违反后果**:大对象内联会撑爆 API/数据库;外置失败则节点直接报错,而不是「看起来成功」。
---
## 未收录(有意)
以下内容没有进入本 Glossary,因为无法在代码中找到可指认的执行点,或有更权威的代码覆盖:
- `docs/fanyu-vnext-workflow-draft.md` 等草稿/未来工作流:属于计划,不是现状。
- `docs/annotation-keyboard-guide.zh-CN.md` 的快捷键:属于交互偏好,不是业务不变量。
- 会议结论、性能优化记录(如 `docs/annotation-operation-latency.md`):属于工程改进记录,规则会随实现变化。
## 变更流程
1. **改规则**:先改代码与测试,再改本页;不允许先改 Wiki 让实现去追。
2. **改编号**:只增不改;废弃规则保留编号并标注「已废止 + 替代编号」。
3. **迁移新规则**:补充「执行点」「测试依据」「违反后果」三项,缺一项不得提交。
4. **最后核对**:每次修改记录 droboticflow 的 commit(当前 `877307cb`),便于回溯。
## 自检命令
```bash
# 规则条数与编号
grep -c '^## BR-' wiki/glossary/business-rules.md
grep -c '^## OPR-' wiki/glossary/business-rules.md
# 每条规则至少有一个代码/测试引用
grep -c '^- `internal/\|^ - `internal/\|^- `custom-operators/' wiki/glossary/business-rules.md
```

83
wiki/index.md Normal file
View File

@ -0,0 +1,83 @@
# WishForge Wiki
这是 WishForge 仓库内的受控知识库(Git Wiki)。它面向三类读者,并且只服务于一个目的:让人和 Agent 在**不重新扫描整个代码库**的前提下,找到可信的现状描述、代码入口和业务约束。
| 读者 | 从这里开始 | 需要的回答 |
|---|---|---|
| 客户 / 使用者 | [`features/`](features/) | 这个功能现在到底怎么用、边界在哪里、失败时怎么办 |
| 编码 Agent | [`modules/`](modules/) | 改这个功能要动哪些文件、测试在哪里、哪些契约不能破 |
| 业务与维护者 | [`glossary/business-rules.md`](glossary/business-rules.md) | 哪些业务规则是硬约束、依据在哪个代码/测试文件 |
## 项目速览
WishForge 是「远程、意图驱动的软件交付平台」:用户用一句话提出愿望(目标 + 验收标准),编码 Agent 在隔离环境中实现,独立验证器按受保护命令判定,失败回灌自修复,通过后合入、按需构建与部署(`README.md:3`)。
仓库分层与 Wiki 的对应关系:
| 仓库目录 | 内容(`README.md:65-79`) | 对应 Wiki 页面 |
|---|---|---|
| `apps/api` | 控制面 API(REST、内部接口、MCP、模型代理) | [modules/api-control-plane](modules/api-control-plane.md) |
| `apps/web` | Web 工作台(Next.js,OIDC BFF) | [modules/web-console](modules/web-console.md) |
| `apps/worker` | Temporal worker:coordinator / executor / verifier / deployer | [modules/worker-pipeline](modules/worker-pipeline.md) |
| `apps/provisioner`、`apps/runner`、`apps/git-service` | 执行环境、驻地部署、平台 Git | [modules/provisioner-runner-git-service](modules/provisioner-runner-git-service.md) |
| `packages/contracts`、`packages/runtime` | 领域契约与执行适配 | [modules/runtime-and-contracts](modules/runtime-and-contracts.md) |
运行前置与检查命令见 `README.md:33-59` 与 `:83-93`(`npm ci`、`npm run setup:local`、`docker compose`、`npm run db:migrate`、`npm run dev:all`;`format:check`、`typecheck`、`test`)。
## 目录
### features/ — 面向客户的现状说明书
| 页面 | 说明 |
|---|---|
| [wish-submission-and-refinement](features/wish-submission-and-refinement.md) | 提交愿望、验收标准、AI 优化、模型白名单 |
| [run-lifecycle-and-waiting](features/run-lifecycle-and-waiting.md) | 八阶段流水线、运行状态、18 种等待原因与解除路径 |
| [independent-verification-and-self-repair](features/independent-verification-and-self-repair.md) | 验证器独立裁决、受保护验收配置、自修复轮次 |
| [integration-build-release-rollback](features/integration-build-release-rollback.md) | 合入、构建、发布审批、回滚与 POC 驻地交付 |
| [agent-entrypoints-and-permissions](features/agent-entrypoints-and-permissions.md) | Web / MCP / IDE / 连接器四类入口与角色权限 |
| [console-observability-and-usage](features/console-observability-and-usage.md) | 控制台、事件流、Diff、报告、用量与配额 |
### modules/ — 面向 Agent 的代码地图
| 页面 | 覆盖范围 | 关键入口 |
|---|---|---|
| [api-control-plane](modules/api-control-plane.md) | 控制面 API、领域状态机、数据库与 Outbox | `apps/api/src/main.ts`、`apps/api/src/domain/control-plane.ts` |
| [worker-pipeline](modules/worker-pipeline.md) | Temporal 工作流、executor、verifier、发布请求 | `apps/worker/src/workflows.ts`、`apps/worker/src/verifier.ts` |
| [runtime-and-contracts](modules/runtime-and-contracts.md) | Git/验证/构建/部署适配、领域契约 | `packages/runtime/src/`、`packages/contracts/src/index.ts` |
| [web-console](modules/web-console.md) | Next.js 工作台、BFF、事件与等待提示 | `apps/web/src/features/`、`apps/web/src/lib/waiting.ts` |
| [provisioner-runner-git-service](modules/provisioner-runner-git-service.md) | 执行环境、驻地 Runner、平台 Git 服务 | `apps/provisioner/main.mjs`、`apps/runner/src/main.ts`、`apps/git-service/src/service.ts` |
### glossary/ — 受控领域词汇与业务规则
| 页面 | 说明 |
|---|---|
| [business-rules](glossary/business-rules.md) | 从 `droboticflow` 迁移的标注规范、算子约束与业务规则,每条带代码/测试引用 |
## 内容规则(新增页面前必须遵守)
1. **一条事实必须有一个可追溯依据。** 使用相对仓库根的路径加行号或函数名,例如 `packages/contracts/src/index.ts:20`;测试依据写成 `tests/xxx.test.ts`。没有依据的内容不进入 Wiki。
2. **代码优先于文档。** 当 `docs/` 与源码不一致时,以源码为准,并在页面里显式记录差异。本 Wiki 首版已经记录了至少一处:`docs/wishforge-summary.md` 称 16 种等待原因,而 `packages/contracts/src/index.ts:25-44` 定义了 18 种。
3. **不写空模板。** 每个页面至少包含:现状描述、代码入口、测试集位置、已知边界。占位符页面视为缺陷。
4. **业务规则只用受控表述。** 规则编号(`BR-xx`、`OPR-xx`)只增不改;修改规则需要同步更新引用与“最后核对”版本。
5. **不把推测写成结论。** 无法从代码或测试确认的行为,写进“未确认/待验证”。
## 自检
```bash
# 文件数量
find wiki -name '*.md' | wc -l
# 每个文件的正文字数(去掉 Markdown 语法符号后)
for f in $(find wiki -name '*.md'); do printf '%s %s\n' "$(tr -d '[:space:]#*`|->[]()' < "$f" | wc -m)" "$f"; done
# 业务规则必须带代码引用
grep -c '^### BR-' wiki/glossary/business-rules.md
```
当前基线:13 个 Markdown 文件,6 个 features 页面,5 个 modules 页面,1 个 glossary 页面;全部页面正文超过 200 字,`glossary/business-rules.md` 含 9 条带代码引用的规则。
## 维护方式
- 人工 Review 为主:任何页面改动都必须能指出对应的代码或测试变化。
- 本目录是后续「Run 成功后增量修订 Wiki」流程的**基线结构**:`features/` 对应用户可见行为,`modules/` 对应代码地图,`glossary/` 对应不可违反的业务约束。三者分开,是为了让增量修订时能明确该改哪一类页面。
- 迁移来源:`droboticflow` 仓库(Gitea `longtao.wu/droboticflow`,本地核对版本 `877307cb`,2026-10-27)。迁移只收录能在代码中找到执行点的规则,不搬运纯愿景描述。

View File

@ -0,0 +1,62 @@
# 模块:控制面 API(apps/api)
## 职责
`apps/api` 是平台的**唯一事实来源**:项目与成员、愿望与运行、租约与证据、发布与审批、额度与用量、连接器与模型代理。它自己不跑模型、不跑测试,而是把长时间工作交给 Temporal(`apps/worker`)和目标环境的 Runner。
## 启动与组装顺序
入口 `apps/api/src/main.ts:24` 的 `bootstrap()`:
1. `requireDeploymentMode(process.env)`(`main.ts:25`):部署模式必须显式声明,默认拒绝(fail closed),不靠 `NODE_ENV` 推断。
2. 删除迁移用管理员凭据(`main.ts:27-28`),并对数据库角色做安全检查 `store.assertSafeRole()`(`apps/api/src/db/store.ts:108-110`):超级用户或 `BYPASSRLS` 角色会让租户隔离失效,因此拒绝启动。
3. 若派发开启,强制要求 Temporal TLS 文件与租户命名空间(`main.ts:30-34`),避免通过未认证或共享命名空间派发。
4. 组装 `Services(new ControlPlane(store))`,启动后台技能沉淀与资源对账 worker。
## 代码地图
| 文件 | 职责 | 关键点 |
|---|---|---|
| `apps/api/src/main.ts` | 启动、依赖组装、后台循环 | 206 行;fail-closed 配置校验 |
| `apps/api/src/http.ts` | REST 路由与 DTO 校验 | 933 行;NestJS 控制器;`/v1` 与 `/internal` |
| `apps/api/src/domain/control-plane.ts` | 运行状态机 | 1564 行;`submit:358`、`lease:931`、`transition:1076`、`evidence:1213` |
| `apps/api/src/domain/releases.ts` | 发布绑定、审批、回滚 | 724 行;`releaseBinding:42`、`request:280`、`decide:435`、`rollback:662` |
| `apps/api/src/domain/runner-broker.ts` | Runner 注册、任务队列、回执 | 508 行;`register:54`、`poll:127`、`result:290` |
| `apps/api/src/domain/provider-proxy.ts` | 模型网关代理与短期令牌 | 933 行;原始密钥不进入执行环境 |
| `apps/api/src/domain/local-poc.ts` | POC 绑定与构建证据校验 | `assertPocBuild`;`POC_BINDING_REQUIRED` 等错误码 |
| `apps/api/src/domain/integration-lease.ts` | 每项目单一集成者 | 与 fencing token 配合 |
| `apps/api/src/domain/entitlements.ts` | 套餐限额与并发预留 | 与 `usage.ts` 配合 |
| `apps/api/src/domain/skills.ts` | 项目技能沉淀 | 423 行;后台 harvest |
| `apps/api/src/domain/lessons.ts` | 运行经验注入 | 90 行 |
| `apps/api/src/mcp.ts` | MCP Streamable HTTP 服务 | 8 个工具;OAuth 资源元数据 |
| `apps/api/src/auth.ts`、`internal-auth.ts` | 人类会话与内部身份 | 身份类型见 `packages/contracts/src/index.ts:85` |
| `apps/api/src/dispatcher.ts` | Outbox → Temporal 派发 | 多副本安全 |
| `apps/api/src/db/store.ts` | PostgreSQL 事务与 RLS 上下文 | 每个事务 `set_config('app.tenant_id', …)`(`:116`) |
| `apps/api/src/db/migrate.ts`、`migrations/` | 版本化迁移 | `npm run db:migrate` |
| `apps/api/src/telemetry.ts` | OpenTelemetry 与指标 | Prometheus |
## 数据层约束
- 每个租户事务在进入时设置 `app.tenant_id` 与 `app.actor_id`(`apps/api/src/db/store.ts:116-119`),RLS 策略据此过滤;应用层另有检查,两者都不能省。
- Outbox 表把「状态已提交」与「工作流已派发」解耦:`outbox()` 只取未投递且到期的记录,按 `run.signal` → `workspace.reconcile` → 其他排序(`apps/api/src/db/store.ts:264`),投递成功写 `delivered_at`,失败累加 `attempts` 并退避。
- 清理策略:已投递 outbox 保留 7 天,幂等记录 30 天(`apps/api/src/db/store.ts:84`)。
## 测试集
| 测试 | 覆盖 |
|---|---|
| `tests/control-plane.test.ts` | 提交、租约、阶段迁移、证据 |
| `tests/control-hardening.test.ts` | 取消/补充/暂停的级联失效、越权、租约边界 |
| `tests/local-loop.test.ts` | 本地端到端主链路 |
| `tests/local-poc-delivery.test.ts` | POC 发布绑定、签名回执、回滚 |
| `tests/entitlements-usage.test.ts` | 配额与计量 |
| `tests/internal-auth.test.ts`、`tests/auth-expiry.test.ts` | 身份与过期 |
| `tests/path-rules.test.ts` | 后端路径规则 |
| `tests/mcp.test.ts` | MCP 工具契约 |
## 修改时的检查清单
1. 改状态迁移:必须同时更新 `packages/contracts` 的 schema、`tests/control-plane.test.ts` 与前端等待指引。
2. 改证据结构:确认历史证据仍能反序列化;证据是审计资产。
3. 改发布绑定字段:会让既有审批失效,需要在 PR 中说明。
4. 新增路由:`/v1` 面向人类与连接器,`/internal` 面向 worker/verifier,权限模型不同,不能混用。

View File

@ -0,0 +1,75 @@
# 模块:执行环境、驻地 Runner 与平台 Git
这三个应用分别位于「执行面的两端」和「代码交接点」,共同决定愿望能否在真实环境里落地。
## apps/provisioner — 执行环境
**入口**:`apps/provisioner/main.mjs`;后端实现 `local.mjs` 与 `kubernetes.mjs`;工作区 `workspaces.mjs`、`workspace-lifecycle.mjs`;发布/运行资源 `run-release.mjs`、`run-operations.mjs`、`resource-grants.mjs`。
| 后端 | 适用 | 行为 |
|---|---|---|
| `local` | 本地开发 | 为每个代次在本机启动两个 worker 进程(`WF_SANDBOX_MODE=host`),**没有隔离**;只在 `WF_DEPLOYMENT_MODE=development` 下启动 |
| `kubernetes` | 生产 | 用 `kubectl` 创建 Kata Job、PVC、Secret、ServiceAccount、NetworkPolicy;IDE 工作区为独立 Deployment |
接口(全部要求 `Authorization: Bearer <WF_PROVISIONER_TOKEN>`,除 `/healthz`):
| 方法与路径 | 作用 |
|---|---|
| `POST /runs` | 为该代次启动 executor 与 verifier;同一代次重复请求不重复启动 |
| `POST /runs/release` | 停止计算资源;控制面收到后才归还并发名额 |
| `POST /runs/purge` | 删除该运行所有代次保留的卷;仍有活动进程时返回 `busy` |
| `POST /workspaces` | 创建/返回 IDE 工作区 |
| `GET/PUT /workspaces/:id/lifecycle` | 仅 kubernetes 后端:暂停/恢复 |
| `GET /healthz` | 健康检查 |
**资源授权**:API 用 `WF_RESOURCE_GRANT_SECRET` 做 HMAC 签名,绑定租户、运行、代次、套餐、CPU/内存/存储与运行镜像,有效期 5 分钟。两个后端都校验签名与有效期;kubernetes 后端还要求镜像在允许列表内。这是「执行资源不能被随便要」的机制。
**测试**:`apps/provisioner/test/local.test.mjs`、`kubernetes.test.mjs`、`workspaces.test.mjs`、`workspace-lifecycle.test.mjs`;`npm test` 会跑 `node --test apps/provisioner/test/*.test.mjs`。
## apps/runner — 驻地交付代理
**入口**:`apps/runner/src/main.ts:15` 的 `main()`。
- 必需配置:`WF_CONTROL_PLANE_URL`、`WF_RUNNER_TOKEN`、`WF_TENANT_ID`、`WF_ENVIRONMENT_ID`、`WF_RUNNER_PUBLIC_KEYS`、`WF_RUNNER_STATE_DIR`;缺一项直接启动失败(`main.ts:17-25`)。
- 出站拉取:`apps/runner/src/runner.ts` 的 `OutboundRunner` 轮询控制面的签名任务,目标环境**不需要**公网入站端口。
- 签名校验:公钥来自控制面注册;任务内容是 Ed25519 签名报文。
- `WF_RUNNER_EXECUTE=true` 才真正执行部署,默认只渲染(`render()` 只读)。
- POC 采用:设置 `WF_POC_PROFILE_FILE` 时,**必须**是本地开发模式(`main.ts:28-32`),否则拒绝启动;同时把 profile 摘要与公网地址作为 `trustedPocDelivery` 传入验签,防止换个 profile 冒充。
- 健康与日志:`apps/runner/src/health.ts`、`log.ts`。
**测试**:`apps/runner/test/local-entry.test.ts`;POC 语义由 `packages/runtime/test/poc-release.test.ts` 与 `tests/local-poc-delivery.test.ts` 覆盖。
## apps/git-service — 平台 Git
**入口**:`apps/git-service/src/main.ts`;实现 `service.ts`。
- 平台 Git 是裸仓库服务,按仓库范围签发短期令牌:`issueGitToken` / `verifyGitToken`(`service.ts:99`、`:103`)。
- 推送边界由 `PRE_RECEIVE_HOOK`(`service.ts:44`)执行:令牌里写明允许的引用前缀(例如 `refs/heads/ide/`),越界引用被拒绝;平台自己的合入不受该前缀限制。
- 分支列举:`branchesIn(repository, prefix)`(`service.ts:70`),供工作台列出 IDE 分支。
- 所有推送只接受快进,不能删除分支。
**测试**:`apps/git-service/test/hooks.test.ts`(例如 `:17` 验证 `ide/` 作用域令牌只能推 `ide/` 分支)、`service.test.ts`。
## 三者如何串起来
```
控制面 --(HTTP + 资源授权)--> provisioner --(Kata Job)--> executor / verifier
| |
|<---------------- 证据 / 阶段迁移(内部接口)------------------+
|
+--(签名任务, 出站轮询)--> runner --(kubectl patch)--> 目标集群
|
+--(Git 令牌, 引用前缀)--> git-service <--- IDE / verifier 推送
```
关键不变式:
1. provisioner 不访问数据库、不持有签名密钥;它只执行资源创建。
2. runner 不接收入站连接;目标环境无需暴露端口。
3. git-service 的令牌按引用前缀限权,IDE 令牌无法直接推目标分支。
## 已知边界
- 本地 `host` 模式没有隔离,只能显式开启;生产部署模式下无法启动,其证据也会被拒绝(`docs/requirements.md` FR-D2)。
- provisioner 的 local 后端不支持工作区暂停/恢复,返回 `lifecycle: "unmanaged"`。
- 平台 Git 不是通用 Git 托管:不支持 LFS、子模块、SSH/SCP 地址。

View File

@ -0,0 +1,83 @@
# 模块:运行时适配与领域契约(packages/)
## 为什么把这一层单独成页
`packages/` 是**不依赖具体进程**的可复用内核:契约定义「什么算合法状态」,runtime 定义「怎么在物理世界里执行」。控制面、worker、Runner 都引用它们,因此这里的改动影响面最大。
## packages/contracts — 领域契约
| 文件 | 行数 | 职责 |
|---|---:|---|
| `index.ts` | 868 | 角色、阶段、状态、等待原因、实体、Zod 输入、规范化 JSON |
| `entities.ts` | 117 | 领域实体字段(含集成租约) |
| `permissions.ts` | 88 | 四种能力与六种账户类型,可被控制台直接打包 |
| `path-rules.ts` | 61 | 后端路径 glob 规则与限制 |
| `poc-delivery.ts` | 56 | POC 发布组件集合的 schema 与目标镜像 |
| `deployment-mode.ts` | 47 | 显式部署模式,fail closed |
| `release-risk.ts` | 33 | 发布风险原因与标签 |
| `wish.ts` | 22 | 愿望标题/详情/答案插入 |
| `application-access.ts` | 66 | 应用地址证据匹配 |
| `canonical.ts` | 25 | 规范化 JSON(摘要稳定性的基础) |
| `redaction.ts` | 13 | 日志/证据脱敏 |
关键事实:
- 阶段 `clarify…accept` 与 18 种等待原因都在 `index.ts:20-44`,是全平台唯一来源。
- `canonical.ts` 存在的意义是:同样的语义必须得到同样的摘要,否则发布绑定会被无意义地判为变化。
- `permissions.ts` 显式「不 import 任何东西」,因此控制台可以打包它而不引入服务端代码(`tests/console-bundle.test.ts` 保护这条边界)。
## packages/runtime — 物理执行适配
| 文件 | 行数 | 职责 |
|---|---:|---|
| `git.ts` | 795 | `GitWorkspace`:克隆、基线、检查点 bundle/补丁(各 4 MiB 上限)、推送、合并 |
| `bluegreen.ts` | 762 | 蓝绿部署与流量切换 |
| `poc-release.ts` | 643 | POC 发布:指纹、JSON Patch 前置条件、回滚、对账 |
| `check-pods.ts` | 547 | 瞬态检查 Pod 的创建、等待、清理 |
| `poc-build.ts` | 492 | Kaniko 构建、源码归档、Pod 生命周期 |
| `deployment-secrets.ts` | 439 | 部署密钥按固定版本注入 |
| `sandbox.ts` | 273 | 隔离执行器(bubblewrap / seatbelt)与 host 检查 |
| `project-manifest.ts` | 264 | `wishforge.yaml` 严格解析 |
| `verify.ts` | 232 | `verifyWorkspace`:精确 commit、导出树、证据与输出尾部 |
| `deploy.ts` | 226 | Compose/Kubernetes 部署适配 |
| `poc-runner.ts` | 165 | POC Runner 适配与签名任务校验 |
| `poc-profile.ts` | 133 | 运维 profile schema 与摘要 |
| `build.ts` | 127 | Docker 镜像构建 |
| `runner.ts` | 108 | Ed25519 任务签名/验签 |
| `process.ts` | 129 | 子进程执行、超时、输出上限 |
| `patience.ts` | 46 | 不可靠链路的读重试节奏 |
三个最容易被误改的地方:
1. **`verify.ts` 的导出树。** 被测代码必须与验证器仓库分离,否则 Git filter/hook 可以逃逸。
2. **`git.ts` 的检查点上限。** bundle 与补丁各 4 MiB(`CHECKPOINT_BUNDLE_LIMIT`、`CHECKPOINT_PATCH_LIMIT`),这是为了避免把整个仓库塞进数据库。
3. **`poc-release.ts` 的前置条件。** 每个 JSON Patch 都带 UID、resourceVersion、容器名与旧镜像的 `test` 操作;去掉任何一个都会让并发/漂移场景下的误覆盖成为可能。
## 其他包
| 包 | 入口 | 职责 |
|---|---|---|
| `packages/agent` | `prompt.ts`(209 行)、`bundle.ts` | Agent 提示词组装与配置打包 |
| `packages/github` | `src/index.ts`(479 行) | GitHub App 客户端、分支/PR 操作 |
| `packages/artifacts` | `src/index.ts`(236 行) | 对象存储与产物引用 |
## 测试集
| 测试 | 覆盖 |
|---|---|
| `packages/runtime/test/git-contract.test.ts` | 仓库 URL、分支、检查点 |
| `packages/runtime/test/verify.test.ts` | 精确 commit 验证与失败证据 |
| `packages/runtime/test/sandbox` 相关(`host-check-sandbox.test.ts`) | 隔离执行器 |
| `packages/runtime/test/poc-release.test.ts` | 漂移、不可变镜像、回滚、丢失应答 |
| `packages/runtime/test/poc-fanyu.test.ts` | Fanyu 命名空间采用 |
| `packages/runtime/test/project-manifest.test.ts` | `wishforge.yaml` 拒绝规则 |
| `packages/contracts/test/models.test.ts` | 模型清单 |
| `tests/path-rules.test.ts` | 后端路径规则 |
| `tests/console-bundle.test.ts` | 前端打包边界 |
## 修改时的检查清单
1. 改契约字段:跑 `npm run typecheck`(含 tests 的 tsconfig),并检查所有 consumer。
2. 改 runtime 的 Git/验证逻辑:至少跑对应 `packages/runtime/test/*.test.ts` 与 `tests/local-poc-delivery.test.ts`。
3. 新增摘要字段:确认 `canonical.ts` 的序列化稳定,否则审批会随机失效。
4. 改沙箱:生产模式必须保持 fail closed,host 模式只能显式开启。

View File

@ -0,0 +1,75 @@
# 模块:Web 控制台(apps/web)
## 职责与边界
`apps/web` 是 Next.js 工作台与 BFF。它负责会话、CSRF、页面渲染、SSE 消费与 Diff 展示;**不直接访问业务数据库**,所有请求经 `apps/web/src/app/api/[...path]/route.ts` 转发到 `apps/api`。这条边界让 API 可以独立部署、独立限流,也让前端无法绕过权限检查。
## 目录地图
| 路径 | 内容 |
|---|---|
| `apps/web/src/app/(console)/` | 工作台路由组:dashboard 隐含在根页、`runs`、`runs/[id]`、`runs/new`、`releases`、`projects`、`projects/[id]`、`projects/new`、`environments`、`members`、`providers`、`usage`、`agent` |
| `apps/web/src/app/ide/[id]` | 云 IDE 入口与 launch 路由 |
| `apps/web/src/app/login`、`login/callback`、`logout` | OIDC 授权码 + PKCE 与本地开发登录 |
| `apps/web/src/app/reports/wishes/[id]` | 单次愿望报告页 |
| `apps/web/src/app/api/[...path]` | BFF 代理 |
| `apps/web/src/features/` | 业务页面组件(见下表) |
| `apps/web/src/components/` | `console-shell.tsx`、`run-table.tsx`、`diff-view.tsx`、`ui.tsx` |
| `apps/web/src/lib/` | 纯前端逻辑与会话(含配套 `*.test.ts`) |
## features/ 组件
| 文件 | 页面 |
|---|---|
| `dashboard.tsx` | 概览指标 |
| `runs.tsx` | 运行列表、新建愿望(`:422`)、运行详情(`:789`) |
| `releases.tsx` | 发布、审批、回滚 |
| `projects.tsx`、`project-settings.tsx` | 项目列表与设置(目标分支、验证命令、模型、后端路径) |
| `environments.tsx` | 环境与应用地址 |
| `members.tsx` | 成员与账户类型 |
| `providers.tsx` | 执行器/模型连接 |
| `usage.tsx` | 用量与配额 |
| `agent.tsx`、`skills.tsx`、`lessons.tsx` | Agent 配置、项目技能、经验 |
| `wish-report.tsx` | 愿望报告 |
| `runner-registration.tsx` | Runner 注册与公钥 |
## lib/ 纯逻辑(每个都有测试)
| 文件 | 职责 | 测试 |
|---|---|---|
| `auth.ts` | OIDC、会话加密 Cookie、本地访问凭据 | `auth.test.ts` |
| `api.ts` | SWR 客户端与 `ApiError` | 由组件测试间接覆盖 |
| `events.ts` | 事件类型中文标签(`:58` `eventLabel`) | `events.test.ts` |
| `patch.ts` | unified diff 解析为可渲染行 | `patch.test.ts` |
| `waiting.ts` | 18 种等待原因的中文指引与 `resumable` | 类型检查覆盖完整性 |
| `readiness.ts` | 数据态 `ready/refreshing/stale/unavailable` | `readiness.test.ts` |
| `risk.ts` | 复用 `@wishforge/contracts/release-risk` | `risk.test.ts` |
| `evidence-isolation.ts` | 「沙箱验证 / 本机 host」标签 | `evidence-isolation.test.ts` |
| `people.ts` | 本地账号、操作员与服务的显示名 | — |
| `markdown.tsx` | 受限 Markdown 渲染 | `markdown.test.ts` |
| `browser-id.ts` | 浏览器标识 | `browser-id.test.ts` |
| `local-access.ts` | 本机访问开关 | `local-access.test.ts` |
| `types.ts` | API 响应类型 | 类型检查 |
> `readiness.ts` 的 `resourceState` 值得注意:它把「有旧数据但请求失败」标为 `stale` 而不是清空,避免网络抖动时页面显示成「没有项目」。
## 两个前端陷阱
1. **不要在组件里重新推导状态。** 阶段、等待原因、风险都来自 API;前端只做映射。`waiting.ts` 已经承担了「原因 → 指引」的唯一映射,新增原因必须在此补齐。
2. **不要引入服务端依赖到客户端 bundle。** `packages/contracts/src/permissions.ts` 刻意零 import,正是为了让 `apps/web` 打包它而不把 `pg`、NestJS 等拉进浏览器。`tests/console-bundle.test.ts` 会检查这一点。
## 测试集
| 测试 | 覆盖 |
|---|---|
| `tests/console-bundle.test.ts` | 控制台打包边界与禁止依赖 |
| `apps/web/src/lib/*.test.ts` | 会话、事件标签、Diff 解析、就绪态、证据隔离、本地访问 |
| `tests/application-access.test.ts` | 应用地址与访问证据 |
| `tests/local-loop.test.ts` | 通过 BFF 的端到端链路 |
## 修改时的检查清单
1. 新增页面:同时补 `console-shell` 导航与权限判断。
2. 新增等待原因:改 `packages/contracts` → `apps/web/src/lib/waiting.ts` → 运行详情卡片,三处缺一不可。
3. 改 Diff 渲染:先确认 `patch.ts` 的解析测试,再改组件。
4. 改登录:生产模式必须拒绝开发令牌,回调重放必须被拒绝(`docs/requirements.md` FR-A1)。

View File

@ -0,0 +1,91 @@
# 模块:Temporal 执行流水线(apps/worker)
## 职责
`apps/worker` 承载长时间运行的分布式状态机:把一次愿望拆成 executor → verifier → (可选)release 的 activity 序列,并在外部故障、进程重启、人工等待后从精确断点继续。它不拥有业务数据库,所有状态写入都通过 `/internal` 接口回到控制面。
## 代码地图
| 文件 | 行数 | 职责 |
|---|---:|---|
| `apps/worker/src/workflows.ts` | 141 | 工作流主体、resume 信号、执行代次(generation) |
| `apps/worker/src/activities.ts` | 97 | activity 注册:inspect、execute、verify、requestRelease、prepareRepair、recordWaiting |
| `apps/worker/src/executor.ts` | 486 | 拉取工作区、准备依赖、调用编码 Agent、产出检查点 |
| `apps/worker/src/verifier.ts` | 903 | 独立验证、验收配置、失败分类、修复证据 |
| `apps/worker/src/common.ts` | 237 | `RunInput`、`WorkerConfig`、内部 API 客户端 |
| `apps/worker/src/lease.ts` | 99 | activity 上下文与租约令牌传递 |
| `apps/worker/src/github-delivery.ts` | 123 | GitHub 分支/PR 交付路径 |
| `apps/worker/src/host-checks.ts` | 121 | 本机 host 模式的安全检查 |
| `apps/worker/src/providers.ts` | 134 | 执行器适配选择 |
| `apps/worker/src/main.ts` | 130 | worker 进程启动、任务队列 |
| `apps/worker/src/workflow-failures.ts` | 19 | 失败到等待原因的分类 |
## 工作流的关键设计
### 1. 每次尝试都有独立任务队列
`apps/worker/src/workflows.ts:63-76`:
```ts
taskQueue: `wishforge-executor-${tenantId}-${runId}-${generation}`
taskQueue: `wishforge-verifier-${tenantId}-${runId}-${generation}`
```
按代次隔离队列,意味着一次卡死的执行不会阻塞其他运行;进程重启后,只有同一代次的 worker 会接单。
### 2. 外部副作用不自动重试
模型调用、构建、部署类 activity 的 `retry: { maximumAttempts: 1 }`(`workflows.ts:66-76`)。失败后由 `waitingForFailure(error, phase)` 转成结构化等待原因,而不是盲目重放。这是「未知结果必须由人确认」的代码表达。
### 3. resume 信号与代次防回退
`workflows.ts:45-53`:
- 收到新代次信号时取消当前 `CancellationScope`。
- `seenGenerations` 记录已见代次,晚到的重复信号不能恢复旧身份。
- 循环顶部先 `inspectRunState`,若运行已结束则直接返回,避免对已完成运行继续调用模型。
### 4. 等待记录的一条硬约束
`apps/worker/src/activities.ts` 的 `recordWaiting`:
- 先读状态;代次不匹配返回 `superseded`,不写。
- 已有租约未过期时抛 `EXECUTION_LEASE_HELD`,要求等待租约过期,**不允许**两个执行者同时写等待原因。
- 只有确认后才 `POST /internal/runs/:id/wait`,detail 截断到 2000 字符。
### 5. 发布请求的幂等键
`requestRelease` 用 `release:${runId}:${generation}:${buildEvidenceId}:${environmentId}` 作为幂等键(`apps/worker/src/activities.ts`)。重试不会产生两个发布单;继续一个失败的发布则会因为代次变化产生新键。
## 验证器的失败分类
`verifier.ts` 负责把失败分成「测试失败 / 基础设施失败 / 范围失败」,决定是否消耗修复轮:
- 测试失败:回灌 executor。
- 安装失败、沙箱启动失败:`infrastructure`,不消耗轮次。
- 前端专用愿望改到后端文件:`scope`,先恢复文件再重做。
- 合并冲突:`integration_conflict`。
这些分类与 `docs/requirements.md` FR-E5、`packages/contracts/src/index.ts:256` 的证据类型一致。
## 启动与配置
`apps/worker/src/main.ts:10` 读取 `WorkerConfig`,连接 Temporal 与内部 API。开发时由 `apps/provisioner` 的 local 后端按代次启动 worker 进程;生产由 Kubernetes Job 启动。
## 测试集
| 测试 | 覆盖 |
|---|---|
| `tests/run-lifecycle.test.ts` | 阶段推进、失败分类、修复 |
| `tests/execution-generation.test.ts` | 代次与旧信号 |
| `tests/dispatcher.test.ts` | Outbox 派发与多副本 |
| `tests/verification-profile.test.ts` | 验收配置执行与失效 |
| `tests/local-loop.test.ts` | 本地端到端 |
| `packages/runtime/test/verify.test.ts` | 验证器行为 |
## 修改时的检查清单
1. 新增 activity:必须考虑「结果未知」的恢复路径,不能不设上限重试。
2. 改任务队列命名:provisioner 与 worker 必须同步,否则运行会停在 `worker_unavailable`。
3. 改等待原因:同步 `packages/contracts` 与 `apps/web/src/lib/waiting.ts`。
4. 改修复轮语义:同步 `docs/requirements.md` FR-E4/E5 与 `tests/run-lifecycle.test.ts`。