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>
21 KiB
WishForge 需求说明(PRD)
版本:2026-10-19 · 状态:生效 · 适用范围:本仓库全部组件
本文是 WishForge 的唯一需求来源。架构与实现方案见 architecture.md,本地开发见 development.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 中指交付能力随运行次数改进,分三层,全部限定在租户(及项目)范围内,客户数据默认不跨租户使用:
- 任务内自修复:验证失败时,失败的命令、退出码和脱敏截断后的输出交还执行器,执行器据此修复并重新提交,直到通过或用尽修复轮数。
- 项目经验沉淀:运行结束后自动沉淀经验条目(例如「本项目测试前必须先构建」「某类失败的有效修复方式」),同一项目的后续任务自动在提示词中带上最近的有效经验;管理员可以查看、停用和删除经验。
- Agent 配置演进:提示词模板与模型以不可变版本管理,管理员可以发布新版本、激活或回滚;每个运行固定使用启动时的版本,进行中的运行不受影响。
明确不做:无人监督的平台级自动晋升(统计门禁、自动灰度、外部发布回执等)。版本晋升始终由人决定。
4. 用户与角色
| 角色 | 权限要点 |
|---|---|
| owner / admin(租户管理员) | 管理项目、成员、执行器凭据(BYOK)、环境与 Runner、验证配置、Agent 配置与项目经验;审批发布。 |
| developer(开发者) | 提交和控制愿望、回答澄清、打开 IDE 编辑、请求发布。 |
| deployer(发布者) | 审批与回滚发布。 |
| viewer(观察者) | 只读查看项目、运行、证据和发布;不能进入 IDE 编辑会话。 |
| 平台运维 | 部署和运维 WishForge 本身,配置执行环境、验收配置、套餐与配额。 |
| Agent 客户端 | WorkBuddy、Codex 等,以用户身份经 OAuth 调用 MCP,权限不超过该用户,且不能代替人完成审批。 |
非 owner/admin 用户只能访问自己是成员的项目。
5. 核心用户旅程
J1 在 Agent 客户端中远程许愿
- 用户在 WorkBuddy/Codex 中说出需求,客户端通过
list_projects找到项目,必要时向用户确认。 - 调用
submit_wish,返回运行 ID 与工作台链接。 - 通过
get_run/get_run_events跟踪进度;运行需要澄清时,转述问题并用answer_question回答。 - 完成后通过
get_delivery汇报:代码变更、验证结果、部署地址,以及尚未完成的验证。
J2 在 Web 工作台完成一次交付
- 创建项目(自动创建平台 Git 仓库,或导入 HTTPS 仓库),配置受保护验证命令。
- 连接执行器凭据,提交愿望。
- 实时查看阶段、事件与 Agent 输出;需要时暂停、补充或取消。
- 查看可读的代码 diff 与验证证据(每条命令的结果与输出)。
- 未配置交付的项目,代码合入目标分支后运行即成功;配置了交付的项目继续构建,按风险自动发布或等待审批,部署完成后访问应用。
J3 在云 IDE 中协作
- 从项目页打开工作区,在浏览器中编辑、使用终端和调试器。
- 改动提交并推送到
ide/开头的分支;从该分支提交一个愿望,验证通过后合入目标分支。 - 可以邀请有编辑权限的成员实时协作。
J4 失败与修复
- 验证失败时,Agent 带着失败信息自动修复,最多尝试预算规定的轮数。
- 仍未通过时,运行进入「等待」,并说明原因和可选操作(补充需求、调整验收标准、追加预算或取消)。
J5 经验与配置演进
- 管理员在项目页查看自动沉淀的经验,停用不准确的条目。
- 发布新的 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 的验证矩阵。