wishforge-ide/docs/requirements.md
eust-w 1d75b03430 feat: register executors in one catalog and add Claude Code (FR-D1)
Adding an executor touched the contracts, the API's availability check, the
worker and the console separately. Now it is an adapter plus one entry in
@wishforge/contracts' providerCatalog (name, executable variable, whether the
model proxy isolates its credentials) and one in the worker's
providerRegistry; the API, the console's options and MCP's submit_wish read
the catalog, and a test checks every entry is registered with the worker.

The CodeBuddy adapter already parsed Claude-Code-style stream-json, so it is
now a StreamJsonCliAdapter with a dialect per CLI. Claude Code runs headless
with --verbose and --permission-mode bypassPermissions inside the per-run
sandbox and receives only ANTHROPIC_* credentials (WF_CLAUDE_BIN). Like
CodeBuddy it is development-only until the model proxy supports it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-19 20:23:05 +08:00

239 lines
21 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

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

# WishForge 需求说明(PRD)
版本:2026-10-19 · 状态:生效 · 适用范围:本仓库全部组件
本文是 WishForge 的唯一需求来源。架构与实现方案见 [architecture.md](architecture.md),本地开发见 [development.md](development.md),生产运维见 [operations.md](operations.md)。
## 1. 产品定位
WishForge 是一个**远程、意图驱动**的软件交付平台:
> 用户用自然语言提出「愿望」(目标 + 可验收标准),后端 Agent 在隔离环境中实现;独立验证器按受保护的验收命令判定结果,失败时把失败信息交还 Agent 自修复;通过后合入代码,按需构建并部署。全过程留有证据,高风险发布需要人工审批,任何时候都可以打开云 IDE 查看和修改代码。
用户可以从三个入口发起和跟踪愿望:
- **Web 工作台**:完整的项目、运行、证据、审批与配置界面。
- **Agent 客户端**:WorkBuddy、Codex 等通过 MCP(OAuth 授权)调用 WishForge,在对话中远程许愿。
- **云 IDE**:基于 Theia 的浏览器 IDE,直接查看和修改项目代码。
产品价值:把「一句需求」变成「有证据的交付」,并让交付质量随使用次数提升(见第 3 节 RSI)。
## 2. 术语
| 术语 | 含义 |
|---|---|
| 愿望(Wish) | 一条需求:目标描述 + 至少一条可验收标准。补充信息会产生新的需求版本(revision)。 |
| 运行(Run) | 为实现一个愿望而进行的一次完整交付过程,包含多个阶段。 |
| 执行器(Provider) | 实际写代码的编码 Agent,例如 Codex、CodeBuddy、Claude Code。 |
| 检查点(Checkpoint) | 执行器产出的精确代码状态(Git commit + 增量 bundle + 补丁),可在另一个工作区精确恢复。 |
| 验证器(Verifier) | 与执行器身份和工作区都隔离的组件,在检查点上运行受保护验证命令并出具证据。 |
| 证据(Evidence) | 验证、构建、部署的结果记录,绑定精确的 commit、镜像 digest 与需求版本。 |
| 发布(Release) | 把某个已验证、已构建的版本部署到某个环境的请求,绑定全部输入的摘要。 |
| 环境(Environment) | 部署目标:平台托管 Kubernetes、客户自有 Kubernetes 或 Docker Compose。 |
| Runner | 部署在目标环境侧、主动向平台拉取签名部署任务的代理进程。 |
| 工作区(Workspace) | 项目的云 IDE 实例。 |
| Agent 配置(Bundle) | 执行器使用的提示词模板与模型选择,以不可变版本保存。 |
| 项目经验(Lesson) | 从历史运行中沉淀的、对后续任务有用的知识条目。 |
## 3. RSI 的定义
RSI(Recursive Self-Improvement,递归自我改进)在 WishForge 中指**交付能力随运行次数改进**,分三层,全部限定在租户(及项目)范围内,客户数据默认不跨租户使用:
1. **任务内自修复**:验证失败时,失败的命令、退出码和脱敏截断后的输出交还执行器,执行器据此修复并重新提交,直到通过或用尽修复轮数。
2. **项目经验沉淀**:运行结束后自动沉淀经验条目(例如「本项目测试前必须先构建」「某类失败的有效修复方式」),同一项目的后续任务自动在提示词中带上最近的有效经验;管理员可以查看、停用和删除经验。
3. **Agent 配置演进**:提示词模板与模型以不可变版本管理,管理员可以发布新版本、激活或回滚;每个运行固定使用启动时的版本,进行中的运行不受影响。
明确不做:无人监督的平台级自动晋升(统计门禁、自动灰度、外部发布回执等)。版本晋升始终由人决定。
## 4. 用户与角色
| 角色 | 权限要点 |
|---|---|
| owner / admin(租户管理员) | 管理项目、成员、执行器凭据(BYOK)、环境与 Runner、验证配置、Agent 配置与项目经验;审批发布。 |
| developer(开发者) | 提交和控制愿望、回答澄清、打开 IDE 编辑、请求发布。 |
| deployer(发布者) | 审批与回滚发布。 |
| viewer(观察者) | 只读查看项目、运行、证据和发布;不能进入 IDE 编辑会话。 |
| 平台运维 | 部署和运维 WishForge 本身,配置执行环境、验收配置、套餐与配额。 |
| Agent 客户端 | WorkBuddy、Codex 等,以用户身份经 OAuth 调用 MCP,权限不超过该用户,且不能代替人完成审批。 |
非 owner/admin 用户只能访问自己是成员的项目。
## 5. 核心用户旅程
**J1 在 Agent 客户端中远程许愿**
1. 用户在 WorkBuddy/Codex 中说出需求,客户端通过 `list_projects` 找到项目,必要时向用户确认。
2. 调用 `submit_wish`,返回运行 ID 与工作台链接。
3. 通过 `get_run` / `get_run_events` 跟踪进度;运行需要澄清时,转述问题并用 `answer_question` 回答。
4. 完成后通过 `get_delivery` 汇报:代码变更、验证结果、部署地址,以及尚未完成的验证。
**J2 在 Web 工作台完成一次交付**
1. 创建项目(自动创建平台 Git 仓库,或导入 HTTPS 仓库),配置受保护验证命令。
2. 连接执行器凭据,提交愿望。
3. 实时查看阶段、事件与 Agent 输出;需要时暂停、补充或取消。
4. 查看可读的代码 diff 与验证证据(每条命令的结果与输出)。
5. 未配置交付的项目,代码合入目标分支后运行即成功;配置了交付的项目继续构建,按风险自动发布或等待审批,部署完成后访问应用。
**J3 在云 IDE 中协作**
1. 从项目页打开工作区,在浏览器中编辑、使用终端和调试器。
2. 改动提交并推送到 `ide/` 开头的分支;从该分支提交一个愿望,验证通过后合入目标分支。
3. 可以邀请有编辑权限的成员实时协作。
**J4 失败与修复**
1. 验证失败时,Agent 带着失败信息自动修复,最多尝试预算规定的轮数。
2. 仍未通过时,运行进入「等待」,并说明原因和可选操作(补充需求、调整验收标准、追加预算或取消)。
**J5 经验与配置演进**
1. 管理员在项目页查看自动沉淀的经验,停用不准确的条目。
2. 发布新的 Agent 配置版本并激活;发现变差时一键回滚。
## 6. 功能需求
优先级:**P0**=里程碑 M1 必须完成且本地可端到端验证;**P1**=生产就绪(M2);**P2**=后续。
### A. 身份与接入
| ID | 优先级 | 需求 | 验收标准 |
|---|---|---|---|
| FR-A1 | P0 | Web 使用 OIDC 授权码 + PKCE 登录;本地开发可使用开发令牌。 | 生产模式拒绝开发令牌;会话 Cookie 加密且为 HttpOnly;回调重放被拒绝。 |
| FR-A2 | P0 | 多租户、成员与五种角色;项目级成员 ACL。 | 跨租户访问在数据库层(RLS)被拒绝;非成员访问项目返回 404。 |
| FR-A3 | P0 | MCP 服务(Streamable HTTP,OAuth 受保护资源元数据),提供工具:`list_projects`、`submit_wish`、`get_run`、`get_run_events`、`answer_question`、`control_run`、`get_delivery`、`request_release`。 | 未认证请求返回带资源元数据地址的 401;客户端无需事先知道项目 ID 即可完成 J1。 |
| FR-A4 | P0 | 所有创建与控制类写操作要求幂等键。 | 同一键重复请求返回同一结果;同一键不同内容返回冲突。 |
| FR-A5 | P1 | Web 会话自动续期,不因 access token 过期而频繁重新登录。 | 持续使用 8 小时内无需重新登录。 |
| FR-A6 | P0 | 连接器身份(MCP)不能完成人工审批、修改凭据或环境配置。 | 连接器调用这些操作返回 403。 |
### B. 项目与仓库
| ID | 优先级 | 需求 | 验收标准 |
|---|---|---|---|
| FR-B1 | P0 | 创建项目时默认在平台 Git 服务上创建仓库(`main` 分支);展示仓库状态与失败原因,失败可重试。 | 平台 Git 不可用时项目显示「仓库不可用」及原因,恢复后可重试成功。 |
| FR-B2 | P0 | 导入已有 HTTPS 仓库;私有 GitHub 仓库通过 GitHub App 授权。 | SSH/SCP 地址、带凭据或查询串的 URL 被拒绝。 |
| FR-B3 | P0 | 项目设置:目标分支、受保护验证命令、依赖安装命令、交付配置(可选)。 | 修改验证命令后,已有的验证结果不能再用于发布。 |
| FR-B4 | P1 | GitHub 仓库通过 PR 交付;控制台展示 PR 状态,支持授权合并、触发合并与失败重试。 | 合并后的 commit 重新经过验证才允许构建。 |
| FR-B5 | P2 | 归档项目并释放配额。 | 归档项目不再接受新愿望。 |
### C. 愿望与运行
| ID | 优先级 | 需求 | 验收标准 |
|---|---|---|---|
| FR-C1 | P0 | 提交愿望:目标、验收标准(至少一条)、执行器、预算(token、时长、修复轮数)。 | 不可用的执行器在表单中不可选,并显示原因。 |
| FR-C2 | P0 | 展示运行的阶段与状态;进度事件实时推送(SSE),并支持按游标补读。 | 断线重连后不丢失、不重复事件。 |
| FR-C3 | P0 | 暂停、继续、取消;补充需求会产生新的需求版本,并使旧版本的验证结果和审批失效。 | 补充后,旧版本的验证证据不能用于发布。 |
| FR-C4 | P1 | 澄清:执行器在实现前可提出问题,运行进入「等待澄清」,用户回答后继续。 | 问题在工作台和 MCP 中可见,回答后运行从规划阶段继续。 |
| FR-C5 | P0 | 等待原因结构化(缺执行器凭据、缺仓库、执行环境未就绪、预算耗尽、等待审批、等待澄清、需要人工处理等),工作台与 MCP 显示对应的可执行操作。 | 每种等待原因都有中文说明和至少一个解除路径。 |
| FR-C6 | P0 | 运行不会永久卡死:异常中断、外部调用结果未知、部署失败等情况都有明确的恢复路径(自动或人工)。 | 暂停、取消或补充后,该运行和该租户的后续运行都能继续使用模型与部署能力。 |
### D. Agent 执行
| ID | 优先级 | 需求 | 验收标准 |
|---|---|---|---|
| FR-D1 | P0 | 执行器适配层:Codex(官方 SDK)为 P0;CodeBuddy CLI 与其他 Agent(如 Claude Code)通过同一适配接口接入为 P1。 | 新增执行器只需实现适配接口并在注册表登记。 |
| FR-D2 | P0 | 每个运行代次使用独立工作目录与独立的短期身份。生产在 Kata 沙箱中运行;本地开发提供 `host` 模式(无隔离,必须显式开启,仅限开发环境)。 | 生产部署模式下 `host` 模式无法启动,其证据也会被拒绝。 |
| FR-D3 | P0 | 执行前按项目配置安装依赖(允许联网);Agent 执行过程默认不开放外网。 | 依赖安装失败时运行等待,并显示安装命令的输出。 |
| FR-D4 | P0 | 执行产出检查点(相对基线的增量 Git bundle),可在独立工作区精确恢复。 | 有长历史的仓库也能产出和恢复检查点。 |
| FR-D5 | P0 | 租户 BYOK 模型凭据加密存储;生产经模型代理为每个运行签发短期令牌,原始密钥不进入执行环境。 | 执行环境中读不到原始密钥。 |
| FR-D6 | P0 | 强制执行 token 与时长预算,超出后运行进入等待。 | 预算耗尽后不再调用模型。 |
| FR-D7 | P0 | Agent 执行过程中的输出(消息、执行的命令、修改的文件)作为进度事件展示。 | 运行中可以在工作台看到 Agent 当前在做什么。 |
### E. 独立验证与自修复
| ID | 优先级 | 需求 | 验收标准 |
|---|---|---|---|
| FR-E1 | P0 | 验证器使用独立身份与独立工作区,从检查点恢复精确 commit,运行受保护验证命令(项目命令 + 平台安装的验收配置)。 | 验证的 commit 与检查点 commit 一致,否则拒绝出具证据。 |
| FR-E2 | P0 | 验证在不含 `.git` 的导出目录中执行,被测代码无法篡改验证器自身或其凭据。 | 仓库中写入 Git filter/hook 的恶意测试无法在验证器中执行。 |
| FR-E3 | P0 | 证据记录每条命令的退出码、耗时、输出摘要,以及脱敏、截断后的输出尾部。 | 工作台可以看到失败命令的输出。 |
| FR-E4 | P0 | 验证失败时,失败信息回灌执行器自动修复,最多修复 `maxRepairRounds` 轮,用尽后进入等待。 | 修复轮的提示词包含失败命令与输出尾部。 |
| FR-E5 | P0 | 基础设施类失败(沙箱启动失败、超时、依赖安装失败)与测试失败区分,前者不消耗修复轮数。 | 验证器无法启动时运行等待,而不是触发修复。 |
### F. 集成与构建
| ID | 优先级 | 需求 | 验收标准 |
|---|---|---|---|
| FR-F1 | P0 | 已验证的 commit 以比较并交换(祖先检查 + `--force-with-lease`)方式推送到目标分支;目标分支已前进时,基于最新代码重新验证。 | 并发运行不会覆盖彼此的提交。 |
| FR-F2 | P0 | 未配置交付的项目,代码合入目标分支后运行即成功。 | 运行状态为成功,并记录合入的 commit。 |
| FR-F3 | P1 | 配置了交付的项目:构建不可变镜像(digest),构建所用 commit 必须等于已验证 commit。 | 不一致时拒绝构建证据。 |
### G. 发布、审批与部署
| ID | 优先级 | 需求 | 验收标准 |
|---|---|---|---|
| FR-G1 | P1 | 发布绑定 commit、镜像 digest、架构、环境、配置版本、密钥版本引用、验证策略与证据;任一项变化都会使审批失效。 | 同一发布 ID 的绑定内容变化时被拒绝。 |
| FR-G2 | P1 | 风险由后端根据可信变更事实计算(受保护路径、数据迁移、权限扩大、生产环境);高风险发布需要人工审批,且审批人不能是请求人。 | 连接器无法批准;请求人无法批准自己的发布。 |
| FR-G3 | P1 | 通过出站 Runner(Ed25519 签名任务)对 Compose 或 Kubernetes 做蓝绿部署,执行健康检查与业务检查;失败时保留旧版本。 | 坏版本不会切流;切流后失败会自动恢复旧版本。 |
| FR-G4 | P1 | 部署失败或结果未知时,可通过目标读回对账或运维操作解除环境锁;支持回滚到上一个稳定版本。 | 部署失败后环境仍可回滚和再次发布。 |
| FR-G5 | P1 | 部署密钥通过密钥 broker 按固定版本注入;证据和日志中不含明文。 | 回执中只出现密钥引用与版本号。 |
| FR-G6 | P0 | 部署完成后在工作台与 MCP 展示应用地址。访问控制由目标环境负责,平台不提供应用访问网关。 | `get_delivery` 返回应用地址。 |
### H. 云 IDE
| ID | 优先级 | 需求 | 验收标准 |
|---|---|---|---|
| FR-H1 | P0 | 从工作台打开项目的 Theia 工作区;网关对每个 HTTP/WebSocket 请求校验租户、项目与角色;viewer 不能进入编辑会话。 | 撤销成员资格后,现有连接会被关闭。 |
| FR-H2 | P1 | 工作区首次打开时克隆项目仓库(平台托管仓库),有人使用期间持续注入仓库范围的短期凭据;IDE 只能推送 `ide/` 开头的分支,愿望可以指定从这样的分支开始,验证通过后连同 Agent 的改动一起合入目标分支。外部仓库的改动走 PR,不克隆。 | 新工作区打开后即有项目代码;IDE 直接推送目标分支被拒绝;从 IDE 分支开始的愿望验证并合入这些改动。 |
| FR-H3 | P1 | 多人实时协作(OCT),房间按工作区隔离,仅有编辑权限的成员可以加入。 | 其他工作区的邀请无法加入。 |
| FR-H4 | P1 | 工作区手动暂停/恢复与空闲自动暂停。 | 暂停后不占用计算资源,恢复后数据仍在。 |
| FR-H5 | P1 | 扩展白名单:只能使用平台预置并校验过摘要的扩展。 | 安装未经审核扩展的请求被拒绝。 |
| FR-H6 | P1 | 活跃使用中的 IDE 会话自动续期,不会被定时强制断开。 | 连续使用 2 小时不需要重新打开。 |
### I. 经验沉淀与 Agent 配置(RSI)
| ID | 优先级 | 需求 | 验收标准 |
|---|---|---|---|
| FR-I1 | P0 | 任务内自修复(同 FR-E4)。 | — |
| FR-I2 | P0 | 运行结束时自动沉淀项目经验(验证失败模式与最终通过的修复要点);同项目后续运行的提示词注入最近的有效经验(有数量与长度上限);管理员可以查看、停用、删除。 | 某项目的第二个运行的提示词中包含第一个运行沉淀的经验;停用后不再注入。 |
| FR-I3 | P1 | Agent 配置版本:提示词模板与模型以内容寻址的不可变版本保存;管理员可激活或回滚;每个运行固定使用启动时的版本。 | 激活新版本不影响进行中的运行。 |
| FR-I4 | P2 | 离线评测:用固定任务集对比不同配置版本的成功率与成本,作为晋升参考。 | 评测结果可在配置版本旁查看,不会自动晋升。 |
### J. 用量与配额
| ID | 优先级 | 需求 | 验收标准 |
|---|---|---|---|
| FR-J1 | P0 | 记录每个运行的 token 用量(优先使用代理计量)与执行时长。 | 用量页显示本月 token 与按运行的明细。 |
| FR-J2 | P0 | 租户配额:并发运行数、月度 token 上限;超额时拒绝提交并说明原因;暂停、等待中或已结束的运行不长期占用预留额度。 | 暂停一个运行后,可以提交新的愿望。 |
| FR-J3 | P1 | 套餐限额(成员数、项目数、工作区数、执行资源规格)由运营配置;用量明细可导出 CSV。 | 超出套餐限额时返回明确错误。 |
### K. 运维与工程
| ID | 优先级 | 需求 | 验收标准 |
|---|---|---|---|
| FR-K1 | P0 | 本地一键启动:依赖服务(Compose)、迁移、种子数据,以及全部进程(API、Web、Git、worker 各角色、本地 provisioner)。 | 按 development.md 操作,提交的愿望能在本地跑到成功(模型调用需要用户自己的 Key)。 |
| FR-K2 | P0 | 版本化数据库迁移,记录已应用的版本。 | 已应用的迁移不会重复执行;新增迁移只执行增量。 |
| FR-K3 | P1 | 健康/就绪检查、Prometheus 指标、审计日志(含操作者)。 | 通过 MCP 发起的写操作在审计中记录真实用户。 |
| FR-K4 | P1 | 数据库备份与恢复演练脚本。 | 恢复到新库后表摘要一致。 |
| FR-K5 | P1 | 生产部署:各服务的镜像构建、Kubernetes 清单与 Kata 运行时要求。 | 镜像中运行的是编译产物,而不是开发脚本。 |
| FR-K6 | P0 | CI:格式检查、类型检查(含测试代码)、单元测试。 | 主分支的每次提交都需要 CI 通过。 |
## 7. 非功能需求
| 类别 | 要求 |
|---|---|
| 安全 | 租户隔离同时由 RLS 和应用层检查保证;执行身份按运行和代次签发并绑定租约,权限最小化;Agent 输出与仓库代码一律视为不可信;密钥不写入日志或证据;生产模式由显式的部署模式开关决定且默认拒绝(fail closed),不依赖 `NODE_ENV` 推断。 |
| 可靠性 | 编排持久化(Temporal);外部副作用幂等;租约 + fencing token 防止过期执行者写入;任何状态都有出口;后台派发在多副本下安全。 |
| 性能 | 本地环境下控制 API 读请求 p95 < 200 ms(不含模型与构建);进度事件端到端延迟 < 3 秒;读请求不被同租户写事务阻塞。 |
| 可观测 | 结构化日志带请求 ID;关键指标(运行数、等待原因、派发延迟、模型调用);后台循环的失败必须记录日志。 |
| 可维护 | 统一 Prettier 格式(行宽 120);领域实体字段全部显式声明类型;包之间通过 workspace 依赖引用;CI 必须通过。 |
| 兼容 | Node.js 22+;开发支持 macOS 与 Linux;生产为 Linux amd64/arm64。 |
## 8. 不做与推迟
以下内容明确不在当前范围内,相关代码已删除或不会实现:
- 发票、计价、结算与作废流程(只保留用量计量、配额与 CSV 导出)。
- 无人监督的平台级自动元进化(统计门禁、自动灰度、签名评估与外部发布回执)。
- 平台提供的私有应用访问网关及签名探测证明链。
- IDE 保存屏障、草稿恢复、调试控制租约,以及以 IDE 快照作为集成输入的机制。IDE 与 Agent 之间只通过 Git commit 交接。
- WorkBuddy Cloud 作为执行器(WorkBuddy 仍可作为 MCP 客户端发起愿望)。
- SSH/SCP 仓库地址、Git LFS、子模块。
- 多区域部署;使用客户数据训练模型或跨租户共享经验。
## 9. 里程碑
| 里程碑 | 范围 | 完成标志 |
|---|---|---|
| M1 本地主线 | 全部 P0 | 本地一键启动后,一个愿望可以完成「实现 → 验证(含自修复)→ 合入」;经验会被沉淀并在下一次运行中使用;文档与代码一致;CI 通过。 |
| M2 生产就绪 | 全部 P1 | 在测试集群上完成 Kata 执行、构建、Runner 部署与回滚、IDE 工作区克隆与协作,并通过真实账号的 MCP OAuth 验收。 |
| M3 持续改进 | P2 | 离线评测、项目归档等。 |
## 10. 验证方式
每条 P0 需求都至少由一个自动化测试覆盖,测试必须进入 CI;需要外部服务的集成测试通过环境变量开关显式启用,跳过不能算作通过。需求与测试的对应关系见 [architecture.md 的验证矩阵](architecture.md#12-需求验证矩阵)。