wishforge-ide/docs/requirements.md
eust-w da1cfcea13 🔥 Remove the cloud IDE
The cluster never ran Theia or the IDE gateway, so every workspace stayed
"未配置" forever. The feature is gone instead of half-present:

- API: workspace, launch and lifecycle endpoints, the gateway identity and
  its internal routes, the dispatcher's workspace provisioning and the
  lifecycle worker. Migration 003 deletes stored workspaces and settles
  their pending outbox items.
- Provisioner: workspace provisioning and lifecycle for both backends.
- Web: the 云 IDE panel, the launch route, the start-branch picker that
  listed IDE branches, and the workspace count on usage.
- apps/ide, infra/oct, dev:ide and the CI job; IDE parts of local k3s,
  network policies, RBAC, docs and the architecture diagram.

A wish can still start from a pushed branch through the API (sourceBranch).
Plan files and stored entitlements may still carry maxWorkspaces; it is
accepted and ignored.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
2026-11-04 12:43:02 +08:00

21 KiB
Raw Blame History

WishForge 需求说明(PRD)

版本:2026-10-19 · 状态:生效 · 适用范围:本仓库全部组件

本文是 WishForge 的唯一需求来源。架构与实现方案见 architecture.md,本地开发见 development.md,生产运维见 operations.md。

1. 产品定位

WishForge 是一个远程、意图驱动的软件交付平台:

用户用自然语言提出「愿望」(目标 + 可验收标准),后端 Agent 在隔离环境中实现;独立验证器按受保护的验收命令判定结果,失败时把失败信息交还 Agent 自修复;通过后合入代码,按需构建并部署。全过程留有证据,高风险发布需要人工审批。

用户可以从两个入口发起和跟踪愿望:

  • Web 工作台:完整的项目、运行、证据、审批与配置界面。
  • Agent 客户端:WorkBuddy、Codex 等通过 MCP(OAuth 授权)调用 WishForge,在对话中远程许愿。

产品价值:把「一句需求」变成「有证据的交付」,并让交付质量随使用次数提升(见第 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 部署在目标环境侧、主动向平台拉取签名部署任务的代理进程。
Agent 配置(Bundle) 执行器使用的提示词模板与模型选择,以不可变版本保存。
项目经验(Lesson) 从历史运行中沉淀的、对后续任务有用的知识条目。

3. RSI 的定义

RSI(Recursive Self-Improvement,递归自我改进)在 WishForge 中指交付能力随运行次数改进,分三层,全部限定在租户(及项目)范围内,客户数据默认不跨租户使用:

  1. 任务内自修复:验证失败时,失败的命令、退出码和脱敏截断后的输出交还执行器,执行器据此修复并重新提交,直到通过或用尽修复轮数。
  2. 项目经验沉淀:运行结束后自动沉淀经验条目(例如「本项目测试前必须先构建」「某类失败的有效修复方式」),同一项目的后续任务自动在提示词中带上最近的有效经验;管理员可以查看、停用和删除经验。
  3. Agent 配置演进:提示词模板与模型以不可变版本管理,管理员可以发布新版本、激活或回滚;每个运行固定使用启动时的版本,进行中的运行不受影响。

明确不做:无人监督的平台级自动晋升(统计门禁、自动灰度、外部发布回执等)。版本晋升始终由人决定。

4. 用户与角色

角色 权限要点
owner / admin(租户管理员) 管理项目、成员、执行器凭据(BYOK)、环境与 Runner、验证配置、Agent 配置与项目经验;审批发布。
developer(开发者) 提交和控制愿望、回答澄清、请求发布。
deployer(发布者) 审批与回滚发布。
viewer(观察者) 只读查看项目、运行、证据和发布。
平台运维 部署和运维 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 中协作(已移除)

云 IDE 已从 WishForge 中移除。自己写的改动可以推送到项目仓库的一个分支,再通过 API/MCP 提交一个从该分支开始的愿望(sourceBranch),验证通过后合入目标分支。

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(已移除)

云 IDE(Theia 工作区、IDE 网关、OCT 协作、按工作区的创建与生命周期)已从 WishForge 中移除,下列需求不再实现,只保留编号与原文供追溯。FR-H2 中「愿望可以指定起点分支」的部分保留:API 与 MCP 的 sourceBranch 仍然有效,工作台不再提供入口。

ID 优先级 需求 验收标准
FR-H1 已移除 从工作台打开项目的 Theia 工作区;网关对每个 HTTP/WebSocket 请求校验租户、项目与角色;viewer 不能进入编辑会话。 撤销成员资格后,现有连接会被关闭。
FR-H2 已移除(起点分支保留) 工作区首次打开时克隆项目仓库(平台托管仓库),有人使用期间持续注入仓库范围的短期凭据;IDE 只能推送 ide/ 开头的分支,愿望可以指定从这样的分支开始,验证通过后连同 Agent 的改动一起合入目标分支。外部仓库的改动走 PR,不克隆。 新工作区打开后即有项目代码;IDE 直接推送目标分支被拒绝;从 IDE 分支开始的愿望验证并合入这些改动。
FR-H3 已移除 多人实时协作(OCT),房间按工作区隔离,仅有编辑权限的成员可以加入。 其他工作区的邀请无法加入。
FR-H4 已移除 工作区手动暂停/恢复与空闲自动暂停。 暂停后不占用计算资源,恢复后数据仍在。
FR-H5 已移除 扩展白名单:只能使用平台预置并校验过摘要的扩展。 安装未经审核扩展的请求被拒绝。
FR-H6 已移除 活跃使用中的 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(Theia 工作区、IDE 网关、OCT 协作),以及 IDE 保存屏障、草稿恢复、调试控制租约、以 IDE 快照作为集成输入的机制。
  • WorkBuddy Cloud 作为执行器(WorkBuddy 仍可作为 MCP 客户端发起愿望)。
  • SSH/SCP 仓库地址、Git LFS、子模块。
  • 多区域部署;使用客户数据训练模型或跨租户共享经验。

9. 里程碑

里程碑 范围 完成标志
M1 本地主线 全部 P0 本地一键启动后,一个愿望可以完成「实现 → 验证(含自修复)→ 合入」;经验会被沉淀并在下一次运行中使用;文档与代码一致;CI 通过。
M2 生产就绪 全部 P1 在测试集群上完成 Kata 执行、构建、Runner 部署与回滚,并通过真实账号的 MCP OAuth 验收。
M3 持续改进 P2 离线评测、项目归档等。

10. 验证方式

每条 P0 需求都至少由一个自动化测试覆盖,测试必须进入 CI;需要外部服务的集成测试通过环境变量开关显式启用,跳过不能算作通过。需求与测试的对应关系见 architecture.md 的验证矩阵。