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
72 KiB
WishForge 使用手册
这份手册写给两类人:
- 使用者:提愿望、看进度、处理等待、审批发布的人。读第 1~11 章就够了。
- 本机服务的维护者:负责这台 Mac 上 WishForge 服务的人。另外读第 12、13 章。
想快速试一次,直接看第 3 章。运行停住了,看第 7 章。界面上每个按钮和字段的说明在第 4 章。
1. WishForge 是什么
一句话:你用自然语言提一个「愿望」,WishForge 让编码 Agent 去实现,再由一个独立的验证器按事先定好的检查来判定,通过了就合入代码,需要的话构建并部署上线。
整个过程像一条流水线:
提愿望 → Agent 写代码 → 独立验证 → 合入目标分支 → 构建镜像 →(必要时人工审批)→ 部署 → 验收
↑ │
└── 没通过时带着报错自动修复(修复轮)
几个关键特点:
- Agent 说了不算:代码合不合格,由与 Agent 完全隔离的验证器在干净的目录里运行「受保护检查」来判定。Agent 不能跳过、修改或伪造这些检查。
- 全程有证据:每次验证、合入、构建、部署都有记录,绑定精确的代码提交(commit)和镜像摘要(digest),随时可查。
- 会自己修:检查没通过时,Agent 拿着失败的命令和输出继续修,最多修到你设定的轮数。
- 有人把关:每个人的账户类型决定能许愿改什么。项目可以划出「后端代码」:只能改前端的人提的愿望碰不到后端,不能直接合入后端的人改到后端时,验证通过后先等人审核再合入;改动涉及迁移、鉴权、构建配方、依赖等敏感内容时,发布会停下来等人审批;环境也可以设置为每次发布都要人确认。
- 能撤回:线上版本可以一键回滚;已经合入的改动可以一键撤销,撤销同样走验证和发布。
- 越用越好:运行中积累的「项目技能」(做法、踩坑记录、项目约定)会自动带进同一项目后续的任务里,在「知识库」统一管理。
1.1 两个入口
| 入口 | 适合做什么 |
|---|---|
| 网页工作台 | 全部功能:提愿望、看进度和代码改动、处理等待、审批发布、管理项目与配置 |
| Agent 客户端(MCP) | 在 Codex、WorkBuddy 的对话里直接许愿和跟进(见第 10 章) |
1.2 本机 POC 是什么
目前这台 Mac 上运行的是一套「本机 POC」部署:
- 网页、控制面、执行器(Claude Code 命令行)和部署 Runner 都跑在这台 Mac 上;
- 只服务一个项目:Gitea 上的
longtao.wu/droboticflow仓库,目标分支固定为poc; - 合入
poc后会构建镜像,部署到既有的 POC 集群,公网入口是 http://120.48.164.19 。
手册里凡是写「POC」的地方,说的都是这套部署。
2. 核心概念
| 概念 | 是什么 | 你需要知道的 |
|---|---|---|
| 项目 | 一个代码仓库加上它的配置 | 配置包括目标分支、受保护检查命令、依赖安装命令、交付配置 |
| 目标分支 | 合入代码的分支 | POC 项目固定为 poc |
| 愿望 | 一条需求:描述 + 至少一条验收标准 | 写法见第 5 章 |
| 需求版本(修订) | 愿望的版本号 | 你「补充需求」后版本加一,旧版本的验证结果和审批全部作废 |
| 运行 | 为一个愿望进行的一次完整交付 | 有自己的阶段、状态、时间线和证据 |
| 执行器 | 实际写代码的编码 Agent | POC 只用 Claude Code;平台还支持 Codex、CodeBuddy |
| 检查点 | 执行器产出的精确代码状态(一个 commit) | 暂停、中断后从检查点接着做,不会从头再来 |
| 验证器 | 独立运行受保护检查的组件 | 与执行器的身份、目录完全隔离,只有它能出具验证证据 |
| 受保护检查 | 项目设置里的验证命令 | Agent 改不了;POC 是 TypeScript 检查、前端测试、前端构建、Go 测试 |
| 证据 | 验证、合入、构建、部署各步的结果记录 | 在运行详情的「验证证据」里看每条命令的退出码、耗时和输出 |
| 修复轮 | 检查失败后 Agent 的一次修复 | 次数受「最多修复轮次」限制 |
| 代码权限 | 哪些代码算后端 | 项目设置里划出哪些路径算后端代码;每个人能不能改后端、改了要不要审核,看各自的账户类型(见 4.12) |
| 代码范围 | 这个愿望能不能改后端 | 提交愿望时选:「只改前端」的愿望改到后端代码时,平台把这些改动恢复原样,让 Agent 只改前端重做;「前端和后端」的愿望可以改后端,按提交人的代码权限决定要不要审核 |
| 合入 | 把验证通过的代码推到目标分支 | 目标分支被别人改过时,会先合并、重新验证再推 |
| 发布 | 把构建好的镜像部署到目标环境 | 风险高时等人审批;POC 环境平时自动发布 |
| 目标环境 | 部署去处 | POC 的目标环境就是既有的 POC 集群 |
| 验收 | 部署后的健康与业务检查 | 不通过时,允许的话自动切回旧版本 |
| 等待处理 | 运行停下来等条件或等人处理 | 每种原因都有中文说明和处理办法,见第 7 章 |
| 预算 | 一个运行能用的 token、时长和修复轮数 | 用完后运行停下,可以调整预算后继续 |
| 项目技能 | 项目可复用的知识:做法、踩坑记录(原「项目经验」)、项目约定 | 启用中的技能自动带进同一项目后续运行的提示词;在「知识库」里编辑、停用、复制、导入导出 |
| Agent 配置 | 执行器用的提示词模板与模型,有版本 | 管理员可新建、激活、回滚;每个运行固定使用提交时的版本 |
| 代次 | 运行的一次执行尝试 | 每次「继续」都会产生新代次,旧代次的执行进程立即失效 |
| 账户类型 | 每个人账号的权限 | 管理员在「成员与权限」页创建账号时选:管理员、全栈开发、开发(后端需审核)、前端开发、发布负责人、只读访客(见 4.12) |
| 撤销运行 | 把某个运行合入的改动从目标分支上撤掉的新运行 | 在运行详情点「撤销这次改动」生成,照常验证和发布 |
2.1 阶段
运行按顺序经过 8 个阶段,运行详情页顶部的阶段条会标出进行到哪一步:
| 阶段 | 谁在做 | 做什么 | POC 上的大致耗时 |
|---|---|---|---|
| 澄清 | 执行器 | 记录验收标准 | 几秒 |
| 规划 | 执行器 | 准备工作区 | 几秒 |
| 实现 | 执行器 | Agent 写代码,产出检查点 | 小改动约 1 分钟 |
| 验证 | 验证器 | 在干净目录里安装依赖、跑受保护检查 | 约 2.5 分钟 |
| 合入 | 验证器 | 改到后端代码、而提出需求的人不能直接合入时先等代码审核;推送到目标分支(必要时先合并、再验证) | 约 20 秒;需要合并时再加约 2.5 分钟;审核等待的时间另计 |
| 构建 | 验证器 | 构建镜像(仅配置了交付的项目) | 只构建 api 约 3 分钟;三个组件全重建约 7 分钟 |
| 发布 | Runner | 部署到目标环境(可能先等审批) | 约 1.5 分钟 |
| 验收 | 控制面 | 部署检查通过,运行完成 | — |
一个只改测试或页面的小愿望,在 POC 上从提交到上线大约 8~9 分钟,消耗约 3.5 万~6 万 token。
2.2 状态
| 页面显示 | 含义 |
|---|---|
| 排队中 | 刚提交、刚继续,或在等执行名额 |
| 运行中 | 有执行进程在工作 |
| 暂停中 | 已请求暂停,正在保存工作 |
| 等待处理 | 停下来等条件满足或等人处理,附带原因 |
| 已暂停 | 被人暂停,已完成的工作已保存 |
| 已完成 | 合入完成(未配置交付的项目)或部署验收通过 |
| 已取消 | 被人取消 |
| 失败 | 只出现在历史数据里;现在所有失败都会变成带出口的「等待处理」 |
3. 五分钟上手
以下以本机 POC 为例。
- 打开网页:在这台 Mac 上打开 http://localhost:3000 ;同一局域网的其他电脑打开
http://<这台 Mac 的局域网 IP>:3000(这个地址须已被维护者放行,见 12.4)。 - 登录:在登录页填自己的账号和密码(由管理员在「成员与权限」页创建后交给你;维护者也可以用本机管理员账号),点「进入工作空间」。会话从登录起 1 小时后失效,期间操作不会延长。
- 提交愿望:点「工作概览」或「运行记录」右上角的「+ 提交愿望」。项目空间选 POC 项目,在「你的愿望」里写要什么,在「验收标准」里每行写一条;拿不准怎么写时,点愿望下面的「AI 优化愿望」或验收标准下面的「AI 生成验收标准」,确认改写结果后再提交。执行器保持 Claude Code,点「提交愿望」。
- 看进度:页面会跳到运行详情。「阶段事件」标签页实时显示 Agent 的回复、改了哪些文件、验证结果和部署进度。
- 看结果:运行完成后,「交付结果」里有「访问应用 ↗」,「代码变更」里是这次改动的 diff,「验证证据」里是每条检查的结果。
运行停在「等待处理」时,页面会用中文说明原因和该做什么,对照第 7 章处理。
4. 网页工作台逐页说明
4.1 界面布局与通用操作
左侧导航从上到下是:
| 导航 | 地址 | 用途 |
|---|---|---|
| 工作概览 | / |
首页:进行中和待确认的数量、最近运行 |
| 项目空间 | /projects |
项目列表、创建项目、项目详情与设置 |
| 运行记录 | /runs |
全部运行、提交愿望、运行详情 |
| 知识库 | /skills |
所有项目的项目技能:确认、编辑、停用、删除、导入导出、复制到其他项目 |
| 部署与审批 | /releases |
发布记录、审批;右上角「目标环境 →」进入环境管理 |
| 执行器 | /providers |
执行器状态与凭据 |
| Agent 配置 | /agent |
提示词与模型的版本 |
| 用量 | /usage |
配额、用量明细、导出 |
| 成员与权限 | /members |
账号与账户类型(管理员可管理;其他人看自己的权限) |
- 右上角:当前登录人的名字和「退出登录」(点了直接退出,没有确认);刷新图标「刷新数据」会重新读取当前页面。
- 自动刷新:页面每隔几秒自动更新(运行列表约 5 秒),运行中的详情页通过实时推送更新,不需要手动刷新。
- 出错时:页面上的提示框有中文标题(例如「当前状态不允许这个操作」「已达到配额或并发上限」「没有执行此操作的权限」),下面是后端的原始说明,多为英文;可以点「重新连接」重试。
- 时间显示为「月/日 时:分」;较长的 ID 只显示开头 8 位和末尾 4 位。
- 窄屏(手机)下导航收进左上角的菜单按钮。
4.2 工作概览
- 「+ 提交愿望」按钮。
- 三个数字:进行中的运行(运行中加排队中)、待确认(等待处理的运行加待审批的发布,也就是「需要你判断」的事)、配置可用的执行器。
- 「最近运行」列出最近 5 个运行,「全部运行 →」进入运行记录。
- 右侧是连接状态(POC 上显示「local · local-development」)和三个准备入口:连接代码仓库、配置执行器、提交第一个愿望。
4.3 项目空间与项目详情
项目列表:可以按项目名或仓库地址搜索,点一行进入项目详情。
创建项目(「+ 创建项目」):
| 字段 | 说明 |
|---|---|
| 项目名称 | 必填,最多 120 字 |
| 代码仓库地址 | 可留空:留空时由平台自建仓库;填写时只支持 HTTPS,不支持 SSH |
| 目标分支 | 默认 main |
项目详情页右上角有「⚙ 项目设置」和「+ 提交愿望」,页面包含三块:
- 代码仓库:仓库地址、目标分支、仓库状态(可用 / 不可用 / 未创建)、代码权限(哪些算后端代码,谁能改它见「成员与权限」)。项目设置按钮只有管理员看得到。平台仓库没建好时有「重试创建仓库」。
- 项目运行:这个项目的运行,「查看全部 →」跳到筛选好的运行记录。
- 项目技能:这个项目启用中的技能数量(按做法、踩坑记录、项目约定分)和待确认的数量;「在知识库中管理 →」打开筛选好的知识库(见 4.13)。
项目设置(「⚙ 项目设置」)分两部分:
- 独立验收配置:生产交付必须绑定平台管理员安装的验收配置,仅 Owner 或 Admin 可改,选好后点「保存独立验收配置」。本机 POC 不需要。
- 主要设置,点「保存设置」生效:
| 字段 | 说明 |
|---|---|
| 目标分支 | 验证通过的代码合入这个分支;新愿望也从它的最新提交开始 |
| 验证命令 | 受保护检查。每行一个 JSON 参数数组,例如 ["npm","test"];按顺序执行、不经过 shell,全部通过才算验证通过。命令保存在平台上,Agent 改不了 |
| 依赖安装命令 | 同样每行一个 JSON 数组,例如 ["npm","ci"];在执行器开始前和每次验证前各运行一次,可以联网;留空时使用仓库里 wishforge.yaml 的 dev.install;安装失败不消耗修复轮数 |
| 代码权限 · 后端代码路径 | 每行一个,相对仓库根目录:目录以 / 结尾(如 backend/),* 匹配一层,** 匹配任意层(如 **/*.go)。写 ** 表示除了下一栏放行的路径,其余都算后端。留空表示不区分前后端 |
| 代码权限 · 前端与其他放行的路径 | 同样每行一个;同时命中两边时算放行,例如 src/、tests/frontend/、**/*.md |
| 代码权限 · 谁能改什么 | 列出项目里每个人的账户类型和许愿范围,在「成员与权限」页修改(见 4.12)。划出后端代码后,提交愿望时会出现「代码范围」(见 4.4)。用组织身份登录、没有本地账号的部署里,这里是「可以直接改后端代码的人」勾选框 |
| 愿望优化规则 | AI 优化愿望和验收标准时额外遵守的规则,最多 4000 字,例如「验收标准必须包含新增的单元测试」 |
| 自动启用可信的项目技能 | 默认勾选:修复过的失败记成的踩坑记录、被两次成功运行提炼出的技能直接启用,并由平台持续更新和自动停用;取消后平台学到的技能都先「待确认」 |
| 配置容器构建与发布目标 | 勾选后填写交付配置:镜像仓库、目标环境、架构(Linux / AMD64 或 ARM64)、容器端口(默认 3000)、Dockerfile 路径、健康检查路径(默认 /health)、构建源码目录、冒烟检查(JSON 数组,如 [{"path":"/","expectedStatus":200}])。交付一旦配置就不能再关掉 |
修改验证命令后,已有的验证结果不能再用于发布,需要重新验证。
4.4 运行记录与提交愿望
运行记录列出所有运行,可以按愿望内容或运行 ID 搜索,按项目和状态筛选。每行显示愿望的第一行(目标)、状态、项目、阶段、执行器和更新时间,点愿望进入详情。(筛选后没有结果时,页面也会显示「暂无运行记录」。)
提交愿望(任一页面的「+ 提交愿望」):
| 字段 | 说明 |
|---|---|
| 项目空间 | 选择项目 |
| 你的愿望 | 必填,8~20000 字。第一行写目标,可以再写「范围:」「不改:」各一行;细节写进验收标准,不需要预先拆分技术步骤 |
| 代码范围 | 项目划出了后端代码时才显示,默认「只改前端」。只改前端:只能改项目放行的路径(POC 是 src/、tests/frontend/、**/*.md),Agent 一开始就被告知,做不到时会停下来提问(之后可以在运行详情放开,见 4.5);改到后端代码时不运行检查,平台在下一轮开始前把这些文件恢复原样(新建的删掉),让 Agent 只改前端重做,算一轮修复。前端和后端:可以改后端;你的账户能直接合入时验证通过就合入,否则先等代码审核,选项下面会写明。账户类型是「前端开发」时只有「只改前端」,没得选 |
| 验收标准 | 必填,每行一条,最多 30 条 |
| 执行器 | 只列出这台部署能用的执行器;POC 只有 Claude Code |
| Token 上限 | 1000~2,000,000。默认 30 万;POC 用 Claude Code 时默认 100 万(Claude CLI 的计量包含缓存读取) |
| 最长运行(分钟) | 1~180,默认 30 |
| 最多修复轮次 | 0~3,默认 3 |
「你的愿望」下面有「AI 优化愿望」,「验收标准」下面有「AI 生成验收标准」(已经写了时叫「AI 优化验收标准」)。两个按钮都要先在「你的愿望」里写至少 8 个字,按钮旁边会提示还差几个字;只有这台部署配置了本机 Claude 账号时才显示。点了以后,左右对照显示原来和建议:优化愿望时,下面还有「需要你选」的选择题和建议的验收标准(每条可以单独勾选);优化验收标准时,建议的每条都可以单独勾选。点「采用建议」把结果填进表单,你还可以继续修改。它怎么工作见 5.5。
点「提交愿望」后跳转到运行详情。
4.5 运行详情
页面从上到下:
- 标题区:愿望的第一行(目标),以及状态、运行 ID、「修订 n」(需求版本)、执行器。
- 阶段条:澄清 → 规划 → 实现 → 验证 → 合入 → 构建 → 发布 → 验收,已完成的打勾,当前阶段高亮。
- 操作按钮,随状态变化:
| 运行状态 | 可用按钮 |
|---|---|
| 排队中、运行中 | 暂停、取消运行 |
| 暂停中 | 取消运行 |
| 等待处理(大多数原因) | 继续、取消运行 |
| 等待处理(等待澄清、等待代码审核、等待审批、部署进行中) | 暂停、取消运行 |
| 已暂停 | 继续、取消运行 |
| 已完成、已取消 | 无 |
已经合入过代码的运行(不论状态)还有「撤销这次改动」,见 8.3。
- 「暂停」「继续」点了立即生效,没有确认。
- 「取消运行」会弹出确认框「取消本次运行」,选「确认取消」才执行,选「保留运行」放弃。
- 预算已经用完时,「继续」是灰的,需要先调整预算。
- 等待说明(仅等待处理时):原因的中文标题、后端给出的具体说明(多为英文)、该怎么做,有时附带链接(如「管理执行器」「去审批」)。下面可以展开「补充或修改需求」,写补充说明或回答问题后点「发送补充」:这会产生新的需求版本,运行从规划阶段重新开始。这个表单只在等待处理时出现,只能写文字说明,不能在这里改验收标准。只改前端的愿望停在「执行器需要你的补充」、或者因为一直改到后端而用完了修复轮时,这里还有「改为前端和后端并继续」:确认后这个愿望可以改后端代码,运行带着这个决定从规划阶段重新开始(需求版本加一),确认框里可以顺便回答 Agent 的其他问题;时间线记一条「代码范围改为前端和后端」。之后改到后端时,只有提交人和所有补充过需求的人都能直接合入才不用审核。只有能许愿改后端的人看得到这个按钮;只能改前端的人看到的是「请可以许愿改后端的人放开」。同样,只能改前端的人不能给可以改后端的运行补充需求,补充表单会换成一句说明。
- 代码审核(仅等待代码审核时):列出改到的后端代码和提交人,「代码变更」链接跳到完整改动。有「审核代码」权限的人勾选「我已查看「代码变更」里的全部改动」后可以「批准合入」;或写下审核意见后「驳回并说明」。批准后运行自动继续合入,不再重复检查;驳回后意见作为补充需求交给执行器再改一轮,改完会再次等待审核。不能批准自己提的改动,除非自己本来就能直接合入。没有这项权限的人只能看到「等待有「审核代码」权限的人审核」。
- 运行预算(仅管理员,且运行处于等待处理或已暂停时):显示已用 Token 和已执行时间,展开「调整预算」可以改 Token 上限(最多 200 万)、时间上限(最多 180 分钟)、修复轮次上限(最多 3),点「保存预算」。保存不会自动继续,还要再点「继续」。
- 交付结果:部署验收通过后显示「访问应用 ↗」;未配置交付的项目显示合入的提交。
- 四个标签页:
| 标签页 | 内容 |
|---|---|
| 概览 | 最近一次失败(验证失败、依赖安装失败、合并冲突,或只改前端的愿望改到了后端代码)及输出,这就是修复轮交给 Agent 的内容;具体要求(愿望第一行之后的各行,一行一条;补充需求也接在这里);改动说明(执行器完成实现时写的总结,以代码变更和验证结果为准);验收标准;执行上下文(项目、提交人、代码范围、撤销的是哪个运行、起点分支、创建与更新时间、修复轮次、已合入提交、Token 与时间的上限和用量) |
| 代码变更 | 这次改动的逐文件 diff,相对任务开始时的目标分支(或起点分支);很大的改动只显示前 4000 行 |
| 阶段事件 | 执行时间线:每条事件显示序号、类别、时间和说明。能看到 Agent 的回复、执行的命令、改动的文件、模型用量、阶段推进、证据、发布进度。说明来自后端,多为英文 |
| 验证证据 | 每次验证、合入、构建、部署的结果卡片:需求版本、时间、隔离方式(沙箱隔离 / 本机执行)、通过或未通过;每条命令的退出码、耗时和输出(失败的默认展开);依赖安装失败时会注明「验证命令没有运行(不消耗修复轮数)」 |
4.6 部署与审批
- 顶部「目标环境 →」进入环境管理(4.7)。
- 发布记录:每条发布显示所属运行、目标环境、时间、状态,状态健康时有「访问应用 ↗」;环境当前线上的发布还有「回滚」(见 8.3)。点右侧箭头展开绑定详情:源代码提交、镜像摘要、绑定摘要、架构、应用地址、配置与策略版本、证据记录,以及审批原因(中文)。
- 发布状态:
| 状态 | 含义 |
|---|---|
| 待审批 | 等人审批 |
| 就绪 | 已批准或无需审批,等待 Runner 部署 |
| 部署中 | Runner 正在部署 |
| 健康 | 部署并验收通过,是当前线上版本 |
| 失败 | 部署失败、验收失败、被拒绝或审批过期 |
| 已回滚 | 被回滚,旧版本恢复了服务 |
| 待确认 | 部署结果未知,需要核对 |
- 审批:待审批的发布有「🛡 审阅发布」按钮,打开「审阅这次发布」对话框,内容有目标环境(生产环境会醒目提示)、项目、需求与验收标准、提交人、改动说明、独立验证(每条命令的退出码,以及是否在 Seatbelt 沙箱中运行)、审批期限和请求人、绑定详情。勾选「我已核对以上源代码、制品、目标环境和验证证据。」后「✓ 批准此版本」才能点;「✕ 拒绝」随时可点,点了直接拒绝,没有二次确认。
- 回滚与撤销改动见 8.3。
4.7 目标环境
从「部署与审批」页右上角进入。每个环境卡片显示类型与架构、是否生产环境、Runner、应用地址、部署密钥引用数量;有发布正在部署或结果待确认时会锁定,期间不能再次发布。卡片按钮:
| 按钮 | 用途 |
|---|---|
| 配置应用地址 | 部署完成后用户访问应用的地址(生产须 HTTPS)。修改后,尚未部署的发布和已有审批需要重新发起 |
| 配置密钥引用 | 登记运维提供的密钥版本引用和策略摘要(不是密钥值) |
| 注册 Runner / 重新注册 Runner | 生成 Runner 令牌(只显示一次,重新注册会撤销旧令牌),并下载验签公钥 |
| 核对后解锁 | 只在 Runner 无法确认部署结果时使用:先在目标环境确认这个版本没有在提供服务,勾选确认后「解锁环境」,该发布会被标为失败 |
卡片上的「每次发布都需人工确认」决定这个环境的发布方式:勾选后,每个发布构建完成都停在「待审批」,有权限的人批准后才部署;不勾选时,只有命中风险规则的发布需要审批(见 8.1)。仅所有者和管理员可以修改;已经创建的发布保持原来的决定。
「+ 添加环境」可以登记新环境:名称、所属项目、类型(平台托管 Kubernetes / 自带 Kubernetes / 自带 Docker Compose)、CPU 架构、应用地址,以及「这是生产环境」「允许策略门禁通过后自动部署」两个选项。登记环境不会自动购买或创建资源。
4.8 执行器
每个执行器(Codex、CodeBuddy、Claude Code)一张卡片:状态(配置可用 / 不可用 / 未配置)、能力(代码导出、恢复执行、取消运行、事件重放、用量计量)、凭据来源。
- Claude Code 在 POC 上用的是这台 Mac 上的本机账号,卡片上没有 API Key 按钮,账号和模型权限在任务启动时检查。
- 其他执行器用「配置 API Key」/「更新 API Key」保存自己的模型服务凭据;保存后不再回显。
- 所有者和管理员在每张卡片上还有「执行器设置」(本机账号模式下也有),只影响本工作空间之后发起的运行,留空的项沿用运行环境的配置。各执行器只显示它支持的项:
- 模型网关地址:只随本工作空间自己的 API Key 使用,需为 HTTPS;本机账号模式和生产环境下由运行环境管理,不能修改。
- 默认模型:许愿和 Agent 配置都没有指定模型时使用(顺序:愿望选的模型 > Agent 配置的模型 > 默认模型 > 运行环境的默认)。
- 快速模型(Claude Code 后台小任务用)、备用模型(主模型过载或不可用时切换)。
- 单次执行时限:5 到 150 分钟,默认 30 分钟。
- AI 优化模型、AI 优化备用模型:许愿时「AI 优化」所用的模型。
- 模型名可以写网关的名字,例如
deepseek-pro@latest[1m]。
- 「已保存凭据」里可以「撤销」凭据(有确认框)。
- 「配置可用」不代表账号已经验证,实际检查在任务启动时进行。
4.9 Agent 配置
管理执行器使用的提示词模板和模型。每个版本不可修改,内容相同的只保存一份。
- 「+ 新建配置」:名称、说明、规划提示词、实现提示词、修复提示词、模型(留空使用执行器默认模型)。新配置要「激活」后才生效。
- 列表里每个版本显示状态:当前激活 / 上一个版本 / 未激活。未激活的可以「激活」;有上一个版本时可以「回滚到上一个版本」。这两个操作都没有确认。
- 运行在提交时固定所用的版本,激活或回滚不影响进行中的运行。
4.10 用量
- 套餐权益与当前占用:成员、项目、执行名额的「占用 / 上限」,以及月 Token 配额。
- 执行资源上限与当前预算:单次运行的 CPU、内存、存储上限,已记 Token、已预留 Token、当前活跃运行。
- 按月查看:选择月份(按 UTC 自然月)后「查看月份」,看模型 Token、执行时长、新增产物和逐条明细;「导出 CSV」下载当月明细。
- 平台只记录用量、不计价,模型费用由模型服务商直接结算。
4.11 界面上值得注意的几点
- 没有二次确认的操作:暂停、继续、审批对话框里的「拒绝」、激活和回滚 Agent 配置、停用项目技能、重试创建仓库、修改成员的账户类型和权限(编辑后点「保存」)、停用或启用成员、退出登录。点之前想清楚。
- 有确认的操作:取消运行、回滚发布、撤销这次改动、批准代码审核(须先勾选)、批准发布(须先勾选)、重置成员密码、撤销凭据、解锁环境、注册 Runner。
- 英文内容:等待说明的具体内容、时间线说明、发布失败原因、表单里的错误信息来自后端,多为英文。
- 等待说明里的「打开项目设置」只会打开项目页,还要再点「⚙ 项目设置」。
4.12 成员与权限
每个人用自己的账号登录,系统才知道愿望是谁提的、改动由谁审核、发布由谁批准。每个账号有一个账户类型,决定这个人能做什么:
| 账户类型 | 适合谁 | 许愿 | 审核代码 | 审批发布 | 管理 |
|---|---|---|---|---|---|
| 管理员 | 负责整个工作空间 | 前端和后端,直接合入 | ✓ | ✓ | ✓ |
| 全栈开发 | 可信的开发者 | 前端和后端,直接合入 | — | — | — |
| 开发(后端需审核) | 新同事或外部协作者 | 前端和后端,后端改动要审核 | — | — | — |
| 前端开发 | 只做页面和样式的人 | 只改前端 | — | — | — |
| 发布负责人 | 负责上线的人 | 不能许愿 | — | ✓ | — |
| 只读访客 | 只看进度的人 | 不能许愿 | — | — | — |
四项权限的含义:
- 许愿:能不能提愿望,愿望能不能改后端。哪些代码算后端,在各项目的「项目设置 · 代码权限」里定义;项目没有定义时,所有代码都算前端。
- 只改前端:提的愿望一律「只改前端」,提交表单里没有「前端和后端」可选;Agent 改到后端时,平台恢复原样让它只改前端重做。也不能给可以改后端的运行补充需求、放开它的代码范围,或撤销它。
- 前端和后端,后端改动要审核:可以选「前端和后端」;改到后端的改动验证通过后,等有「审核代码」权限的人批准才合入。
- 前端和后端,直接合入:改到后端的改动验证通过就合入。但只要有不能直接合入的人给这个运行补充过需求(或放开过代码范围),改到后端时仍要审核(见 6.3)。
- 审核代码:在运行详情的「代码审核」里批准或驳回改到后端的改动。不能批准自己提的改动,除非自己本来就能直接合入。
- 审批发布:在「部署与审批」页批准、拒绝和回滚发布。
- 管理:成员与权限、项目设置、环境与 Runner、执行器、Agent 配置、预算、用量导出;包含以上全部权限。
管理员在「成员与权限」页:
- 「+ 添加成员」:填登录名(2~32 位小写字母、数字、点、横线或下划线)、显示名,选账户类型;需要时在「具体权限」里单独调整某项(调整后显示为「自定义」,例如「前端开发」加上「审批发布」),再勾选可以进入的项目(默认全部)。创建后弹出初始密码,只显示这一次,复制后通过可信的渠道交给对方。
- 「编辑」:改显示名、账户类型或具体权限、可以进入的项目。保存后对方的下一个操作就按新权限执行,不用重新登录。
- 「重置密码」:生成新密码(同样只显示一次),对方已登录的会话立即失效。
- 「停用」/「启用」:停用后对方立即无法再操作。
- 不能修改自己的权限和项目,也不能停用自己,要请另一位管理员操作。
列表第一行是本机管理员(凭据文件里的账号):账户类型是管理员,拥有全部权限,不能在这里修改。不是管理员的人打开这一页,看到的是自己的账户类型和权限。
界面会按权限隐藏做不了的操作:例如不能许愿的人看不到「+ 提交愿望」;没有「审批发布」权限的人能打开「审阅发布」看内容,但没有批准和拒绝按钮。
4.13 知识库(项目技能)
左侧导航「知识库」列出你能进入的所有项目的项目技能,可以按项目、状态(待确认 / 启用 / 已停用)、类型筛选和搜索。技能有三类:
- 做法:某类改动在这个项目里怎么做。运行成功后平台会自动提炼(也可以在运行页点「提炼技能」),已有技能覆盖的会补充进去而不是重复新建。
- 踩坑记录:经过修复轮才成功的运行,会把「哪条命令怎么失败的、最后怎么修好的」记下来;同一条命令(或同一组冲突文件)再失败,只更新同一条记录。原来的「项目经验」都已转成踩坑记录或项目约定。
- 项目约定:自己写的、执行器必须遵守的规则,例如「运行测试前先执行 npm run build」。
启用中的技能(每个项目最近修改的 12 条)会进入这个项目之后每个愿望的提示词。项目设置里的「自动启用可信的项目技能」默认打开:踩坑记录、被两次成功运行提炼出的做法自动启用,其他的「待确认」,点「确认启用」生效。每条技能显示用过几次、对应运行成功和失败几次;平台学到、没人编辑过的技能,连续 3 次用到它的运行失败,或者项目一直在运行而它 90 天没进过提示词,会被自动停用并注明原因,确认仍有用可以重新启用。编辑过的技能平台不再改写或自动停用。
- 「+ 新建技能」:选项目和类型,写名称(小写英文和连字符)、什么时候用、做法(Markdown)。
- 「导入」:选一个或多个 SKILL.md,或一个 zip(例如从这里导出的,每个技能一个目录);zip 最大 512 KiB,每个 SKILL.md 最大 64 KiB,一次最多 50 条。可以直接启用或先放进待确认。
- 勾选技能后「复制到其他项目」:复制内容、类型和状态,不复制使用统计和来源运行。
- 导入和复制时,目标项目里已有描述和内容完全相同的技能会跳过;名字被别的技能占用时自动加序号(如
add-page-2)。 - 选定项目后「导出项目技能」得到 zip,可以直接放进
.claude/skills/;每条技能也可以单独导出 SKILL.md。 - 能为这个项目许愿的人可以新建、编辑、停用、删除、导入和复制技能(删除有确认,删了不能恢复)。
5. 怎样写好一个愿望
验证器只认受保护检查,而 Agent 是照着你的文字去做的,所以写清楚要什么、怎样算完成,直接决定结果好不好。
5.1 「你的愿望」:说清要什么、改哪里、不改哪里
- 愿望写短,细节进验收标准:第一行用一句话写目标;需要时再写一行「范围:」(要做到什么、改哪些页面或文件)和一行「不改:」(不能动的范围)。怎样算做完,一条条写进验收标准,不要在愿望里再写一遍。运行记录、运行详情的标题和飞书通知只显示第一行,其余各行在运行详情「概览」的「具体要求」里。
- 写具体的结果,不写模糊的方向。✗「优化一下下载功能」;✓「下载文件名要包含数据集类型,例如
xxx-episode.zip」。 - 点明位置:知道在哪个文件、哪个函数时直接写上,Agent 会少走弯路。
- 写清边界:「只加测试,不修改
src/下的代码」「不要改接口返回格式」这类限制非常有用。 - 选对代码范围:只动页面、样式、前端测试和文档的愿望选「只改前端」,平台会保证它碰不到后端;需要改接口、数据库、服务端逻辑时选「前端和后端」(账户类型是「前端开发」时只能只改前端)。拿不准时先选只改前端:Agent 发现必须改后端时会停下来提问,你确认需要的话在运行详情点「改为前端和后端并继续」。
- 一个愿望只做一件事:大需求拆成几个小愿望,每个都能独立验证、独立上线,出问题也容易定位。
5.2 验收标准:写成能检查的句子
每条标准都应该能回答「做到了没有」:
- ✓「
artifactExtension没有扩展名时返回空字符串」 - ✓「现有前端测试、TypeScript 检查和构建全部通过」
- ✗「代码质量要好」「体验更流畅」
验收标准会原样交给 Agent,审批时也会展示给审批人。注意:自动判定只看受保护检查,验收标准本身不会被机器执行;希望被自动检查的标准,最好让 Agent 落实成测试。
5.3 预算
| 预算项 | 含义 | 建议 |
|---|---|---|
| Token 上限 | 这次运行最多消耗的模型 token | POC 默认 100 万;小改动实际约 3.5 万~6 万 |
| 最长运行(分钟) | 运行的最长执行时间,包含验证、构建和修复 | 默认 30 分钟。POC 上一次完整运行约 9 分钟,可能需要修复或全量重建时给 60~90 分钟 |
| 最多修复轮次 | 检查失败后最多自动修几次 | 默认 3(也是上限) |
预算用完运行会停在「预算已用完」,已完成的工作不会丢;管理员调整预算后点「继续」。
5.4 示例
你的愿望(目标、范围、不改各一行):
为 buildStorageHistoryScopeKey 补充单元测试。
范围:src/lib/storage-path-history.js 里的这个函数,测试放在 tests/frontend/ 下的新文件中。
不改:src/ 下的任何代码。
验收标准(每行一条):
测试覆盖有 connectionId 时得到 connection:<id>,并且优先于 sourcePath;两者都会去掉首尾空白。
测试覆盖只有 sourcePath 时得到 source:<路径>,两者都为空、只有空白或不传参数时得到空字符串。
不修改 src/ 下的任何文件;现有前端测试、TypeScript 检查和构建全部通过。
5.5 用 AI 优化
写完草稿后点「AI 优化愿望」或「AI 生成验收标准」。它的工作方式:
- 把你写的愿望和验收标准草稿发给控制面;
- 控制面用这台部署的本机 Claude 账号改写,不开任何工具:不读代码仓库、不执行命令、不联网查资料,只根据你写的文字;
- 按内置规则改写,再加上项目设置里的「愿望优化规则」:
- 保留原意,不增加你没要求的功能,也不替你做草稿里没有的决定;
- 愿望最多三行:目标、「范围:」、「不改:」;
- 细节只写在验收标准里,3~6 条,每条都能回答「做到了没有」,不重复愿望里的话,最后一条是「现有测试、类型检查和构建全部通过」;
- Agent 读代码就能定的事(存在哪里、放在哪个模块、接口怎么写)不问你,愿望里写「沿用项目现有做法」;
- 只有你能拍板的问题(做什么、给谁用、做到什么程度)列成「需要你选」,最多 3 个,每个 2~4 个选项,第一个是推荐的;你没提到的扩展(保留多久、权限、导出等)不问;
- 弹窗里,推荐选项默认选中,选中的那句话会加进愿望(在建议里高亮显示,放在「不改:」那行前面);再点一次就不写,也可以点「自己写」。建议的验收标准每条前面有勾选框:表单里还没写验收标准时默认全选;已经写了时默认不勾,勾了才替换你写的。其他提醒(例如建议拆成几个愿望)列在「提醒」里;
- 优化验收标准时愿望保持原样,也不出选择题;
- 结果只给你看,不保存、不提交,也不计入运行的 Token 预算,通常 10~20 秒。
因为它不读仓库,文件名、函数名要你自己在愿望里写出来,它才会写进标准;它也可能理解偏,采用前请逐条核对。
5.6 Agent 有问题时
第一轮实现时,Agent 如果认为缺少关键信息,会一个文件都不改,而是列出最多 5 个问题,运行进入「执行器需要你的补充」。在运行详情展开「补充或修改需求」写下回答、点「发送补充」,运行从规划阶段重新开始(需求版本加一)。
6. 一个运行的完整过程
6.1 实现
执行器在独立的工作目录里克隆项目,从目标分支(或指定的起点分支)的最新提交开始,安装依赖后启动 Agent。POC 上的 Claude Code 默认只有读写文件的能力,不能执行命令;安装依赖、跑测试都交给验证器。Agent 结束后,改动被保存为检查点,进入验证。
6.2 验证与自动修复
验证器在另一个独立目录里从检查点精确还原代码,导出一份不含 .git 的干净副本,安装依赖后按顺序运行受保护检查:
- 只改前端的愿望改到了后端代码:先于检查判定,不运行检查;改到的后端文件交还给 Agent,平台在下一轮开始前把它们恢复原样(新建的删掉),Agent 只改前端重做,算一轮修复。挪动文件时新旧两个位置都算改到。
- 全部通过:进入合入。
- 某条检查失败:失败的命令、退出码和输出末尾交还给 Agent,开始一轮修复;修复轮用完仍未通过,停在「修复轮数已用完,验证仍未通过」。
- 依赖安装失败:通常是网络或镜像源问题,停在「基础设施故障」,不消耗修复轮数。例外:如果这次改动本身改了依赖清单(
package.json、go.mod等)导致安装失败,会作为一轮修复交给 Agent。
POC 打开了 Seatbelt 沙箱,受保护检查在 macOS 沙箱里运行:读不到主目录里的文件,检查时不能联网。不过 POC 是 host 模式,证据卡片上的隔离方式仍显示「本机执行(无隔离)」;用了 Seatbelt 记录在证据的原始数据里(checkSandbox: seatbelt)。
6.3 合入
项目划出了后端代码、这次改动改到了它时,先看提出需求的人:提交人和所有补充过需求(或放开过代码范围)的人都能「直接合入」,就直接合入,时间线记一条「可以直接合入,免审核」;只要有一个人不能,验证通过后先停在「等待代码审核」:有「审核代码」权限的人在运行详情查看改动后批准,运行才继续合入(不再重复检查);驳回时审核意见作为补充需求交给 Agent 再改一轮。继续运行绕不过审核。能不能直接合入按现在的账户类型算:审核前调低了谁的权限,就按调低后的算。
| 情况 | WishForge 怎么做 |
|---|---|
| 运行期间目标分支没动 | 直接推送已验证的提交(快进),不重复验证 |
| 运行期间有人推了目标分支 | 把改动合并到最新的目标分支上,对合并结果重新跑一遍受保护检查,通过才推送 |
| 合并有冲突 | 作为一轮修复:Agent 在最新代码上解决冲突,然后重新验证 |
| 合并结果检查失败 | 先单独检查不带本次改动的目标分支:它自己能通过,说明是两者合在一起出的问题,作为一轮修复;它自己也失败、而运行的起点能通过,说明是别人推的提交弄坏了分支,运行停在「目标分支自身未通过检查」,不让 Agent 去改别人的代码,也不消耗修复轮数 |
| 推送时目标分支又被人改了 | 基于新的提交重新合并、重新验证,最多重试 3 次 |
推送使用「比较并交换」方式,任何人的提交都不会被覆盖。
6.4 构建
配置了交付的项目(POC 就是)在合入后构建镜像。POC 有三个组件:
- api:每次都重建;
- worker、coordinator:只有它们实际运行的代码与这次的代码之间,除了网页文件还有别的不同时,才重新构建,否则沿用原来的镜像。
每次发布都会在集群上记下每个组件的镜像构建自哪个提交。没有记录、被回滚覆盖、或者有人用 kubectl set image 手动改过镜像的组件,会被当作「来源不明」:重新构建,并且这次发布必须人工审批。有人在 WishForge 之外用 tag(例如 droboticflow-api:0c776c04-poc-…,而不是 @sha256: 摘要)部署的镜像同样当作来源不明,时间线里会写明是哪个组件、哪个 tag;这次发布部署的仍是摘要固定的镜像,并且失败时不会自动回滚到那个 tag(tag 指向的内容可能已经变了)。
6.5 发布与验收
构建完成后自动请求发布。是否需要审批见第 8 章。
部署后,Runner 会检查健康接口、就绪接口和首页,确认线上 API 报告的构建提交就是这次的提交,并运行业务检查。滚动更新刚结束时入口可能还连着旧实例,所以这些检查会在约 1 分钟内重试几次。全部通过后运行完成;不通过时,如果这次发布允许自动回滚,会切回旧版本。
6.6 暂停、继续、取消、补充需求、调整预算
| 操作 | 什么时候能用 | 效果 |
|---|---|---|
| 暂停 | 排队中、运行中,以及等待澄清/审批/部署时 | 执行停下,Agent 已做的改动保存为检查点 |
| 继续 | 已暂停,或大多数等待处理 | 重新开始执行(产生新代次),从最近的检查点接着做。对于「修复轮数已用完」「与目标分支的最新代码冲突」,继续表示授权再修一轮 |
| 取消运行 | 未结束的运行 | 结束运行,不可恢复。已经合入目标分支的代码不会被撤回 |
| 补充需求 | 等待处理时 | 追加说明或回答问题,需求版本加一,运行从规划阶段重新开始;旧版本的验证结果和审批全部作废,修复轮次重新计算 |
| 调整预算 | 等待处理或已暂停时,仅管理员 | 修改 Token、时间、修复轮次上限,已用量保留;保存后仍需点「继续」 |
7. 运行停下来了怎么办
运行停在「等待处理」时,详情页顶部会显示中文标题、说明和可做的操作。全部原因如下:
| 页面上的标题 | 什么意思 | 你该做什么 |
|---|---|---|
| 执行器未连接或不可用 | 执行器凭据缺失或无效 | 在「执行器」页连接或更新凭据,然后点「继续」 |
| 项目仓库未就绪 | 仓库不可用、起点分支不存在,或 POC 的 poc 分支被强推后已不包含这次合入的提交 |
在项目页重试仓库创建或推送起点分支,然后点「继续」;说明里出现 POC_SOURCE_REWRITTEN 时取消运行,需要的话重新提交愿望 |
| 执行环境未就绪 | 没能启动执行进程 | 系统会自动重试;维护者恢复服务后也可以点「继续」 |
| 没有可用的执行进程 | 执行进程没有按时接手 | 点「继续」,系统以新代次重新派发 |
| 预算已用完 | token 或时长用完 | 管理员在「运行预算」里调整后点「继续」 |
| 执行器需要你的补充 | Agent 动手前提了问题 | 展开「补充或修改需求」回答,运行从规划阶段继续(这时没有「继续」按钮)。只改前端的愿望问能不能改后端时,点「改为前端和后端并继续」 |
| 缺少验证配置 | 项目没配受保护检查 | 在项目设置里配置验证命令后点「继续」 |
| 修复轮数已用完,验证仍未通过 | 修了几轮还是没过;或者只改前端的愿望几轮下来还是要改后端(说明里列出后端文件) | 看「验证证据」里的失败输出;点「继续」再修一轮,或补充需求,或取消。确实需要改后端时点「改为前端和后端并继续」 |
| 基础设施故障 | 依赖安装、网络、集群连接、Git 访问等出错,不消耗修复轮数 | 排除问题(可以先让维护者跑 doctor)后点「继续」 |
| 执行器调用失败 | 调用模型失败,已完成的工作已保存 | 确认执行器可用后点「继续」 |
| 需要人工确认 | 某个外部操作结果未知 | 查看「阶段事件」确认实际情况,再「继续」或取消 |
| 与目标分支的最新代码冲突 | 合入冲突,且修复轮已用完 | 点「继续」,Agent 基于最新代码再修一轮;或取消 |
| 目标分支自身未通过检查 | 别人推到目标分支的提交让检查失败了,不是本次改动造成的 | 修好目标分支后点「继续」,运行合并到最新代码并重新检查;或取消 |
| 等待代码审核 | 改动已通过检查,但改到了后端代码,而提交人或补充过需求的人不能直接合入 | 有「审核代码」权限的人在运行详情的「代码审核」里批准或驳回(这时没有「继续」按钮) |
| 等待 GitHub 合并 | (GitHub 项目)等 PR 审核合并 | 在 GitHub 上审核合并后点「继续」 |
| GitHub 应用未配置 | (GitHub 项目)缺少 GitHub App 授权 | 请运维安装授权后点「继续」 |
| 发布等待审批 | 发布需要人工审批 | 有权限的人到「部署与审批」页审阅(这时没有「继续」按钮) |
| 部署进行中 | Runner 正在部署 | 等待结果;长时间没有结果请维护者核对(这时没有「继续」按钮) |
几点经验:
- 先读等待说明,再看「验证证据」和「阶段事件」。失败命令的输出末尾通常已经说明问题。
- 基础设施故障不消耗修复轮数,排除问题后直接继续。POC 到集群的网络偶尔不稳定,构建和发布会自动重试,断开超过约 1 分钟才会停下。
- 继续会从最近的检查点接着做;已经通过验证的改动,继续合入时不会重复检查它本身,只检查合并结果。
8. 发布、审批与回滚
8.1 什么时候需要审批
控制面根据这次发布实际改变的内容计算风险。命中任意一条,发布就停下等人审批,「部署与审批」页的绑定详情里会列出中文原因:
| 审批原因 | 触发条件 |
|---|---|
改动了受保护的文件:<路径> |
改到鉴权、安全、计费、迁移、基础设施、CI 相关的目录(auth/、security/、billing/、migrations/、infra/、.github/、.gitea/ 等)或 .gitlab-ci.yml;任何名字的 Dockerfile 或 Containerfile、.dockerignore、Compose 文件;任何依赖清单与锁文件(package.json、package-lock.json、go.mod、go.sum、Cargo.toml 等) |
| 包含数据库迁移 | 改动涉及迁移 |
| 改动了鉴权、安全或基础设施相关的代码,可能扩大权限 | 改动位于这些目录下 |
| 环境中有来源不明的代码,这次发布带来的变化无法全部判断 | 环境里有组件运行着无法确认来源的镜像 |
| 这个环境设置为每次发布都需人工确认 | 环境勾选了「每次发布都需人工确认」(见 4.7) |
| 缺少验证器给出的变更分类,无法判断这次发布改了什么 | 缺少可信的变更记录 |
「实际改变的内容」不只是 Agent 写的代码,而是环境当前运行的代码到这次发布之间的全部差异:有人直接推到目标分支、还没部署过的提交也会计入。POC 只计入这次会被替换的组件,沿用原镜像的组件不计入。
POC 环境默认没有勾选「每次发布都需人工确认」,所以只改普通代码和测试的愿望会直接上线;勾选后每次发布都要人批准。
8.2 怎么审批
有「审批发布」权限的人(管理员、发布负责人,或单独给了这项权限的人)可以审批;其他人能打开「审阅发布」看内容,但没有批准和拒绝按钮。配置了飞书通知时,待审批的发布会推送到飞书群并 @ 决策人,点消息里的「去审批」直达这一页。
- 打开「部署与审批」,找到状态为「待审批」的发布,点「🛡 审阅发布」。
- 核对目标环境、需求与验收标准、独立验证结果、提交与镜像、审批原因。
- 勾选「我已核对以上源代码、制品、目标环境和验证证据。」,点「✓ 批准此版本」;或点「✕ 拒绝」(直接生效,没有二次确认)。
注意:
- 审批 24 小时内有效,过期后发布失败,回到运行详情点「继续」可以重新请求发布。
- 补充需求、修改验证配置、环境配置变化等,都会让已有审批失效。
- Codex、WorkBuddy 等 Agent 客户端不能代替人审批。
- 生产部署模式下,请求人不能批准自己的发布。本机 POC 是开发模式,不受这条限制。
8.3 回滚与撤销
- 自动回滚:部署后的验收检查不通过时,如果这次发布允许自动回滚(不含迁移等不可逆改动,组件来源都已知),会自动切回上一个版本。
- 回滚线上版本:在「部署与审批」页,环境当前线上的发布有「回滚」按钮(有「审批发布」权限的人才看得到),确认后由 Runner 把环境换回这次发布之前的版本并检查。只能退回紧挨着的上一个版本,而且要求两次发布的配置兼容;不满足时会提示原因。回滚只换线上运行的版本,目标分支上的代码不变:下一次发布会把这些代码重新部署上去。
- 撤销这次改动:运行详情页上,已经合入过代码的运行有「撤销这次改动」(能许愿的人可用;只能改前端的人只能撤销「只改前端」的运行)。确认后生成一个新的「撤销运行」:先由 Git 在目标分支最新代码上把这次合入的改动反向应用,之后别人提交的改动保留;只有和之后的提交改到同一处时,才交给执行器处理冲突。然后照常验证、审核、合入、构建和发布。线上出问题时,通常先「回滚」止损,再「撤销这次改动」把代码也退掉。
9. 多人一起使用
9.1 本机 POC 的现状
- 每人一个账号:管理员在「成员与权限」页为每个人创建账号并选好账户类型,系统会记下愿望是谁提的、代码由谁审核、发布由谁批准。账户类型决定能做什么(见 4.12);能许愿的人仍然可以暂停、继续或取消彼此的运行,团队内部要约定好,不要动别人的运行。
- 一次只执行一个运行:POC 只有 1 个执行名额。后提交的愿望显示「排队中」;前一个运行完成,或停下来等审批、等部署时,下一个会在几秒内开始。
- 愿望只能从
poc分支开始。 - 飞书通知:维护者配置好飞书机器人后,待审批的发布、待审核的代码、需要人处理的运行、上线结果都会推送到飞书群(见 12.9)。
9.2 有人直接改 poc 分支时
| 情况 | 结果 |
|---|---|
运行实现期间有人推了 poc |
合入时合并到最新的 poc 上,重新验证合并结果后才推送;冲突按修复轮处理 |
| 推上去的提交让检查失败 | 运行停在「目标分支自身未通过检查」,不消耗修复轮数;修好 poc 后点「继续」 |
运行合入后、构建前有人推了 poc |
照常构建这次合入的提交,时间线会说明 poc 已经前进;更新的提交由之后的运行部署 |
直接推到 poc、还没部署的提交 |
随下一个运行一起部署,并计入那次发布的风险判断(该审批的照样审批) |
几条规矩:
- 不要强推(force push)
poc。进行中的运行合入时会把你删掉的提交重新带回来;已经合入的运行会停在「项目仓库未就绪」,只能取消。 - 推
poc之前自己先跑一遍检查,保持分支是好的,否则别人的运行会停在「目标分支自身未通过检查」。 - 不要手动改 POC 集群里的镜像。改过的组件(包括用 tag 部署的)会被当作来源不明,下次发布要重建并人工审批,而且那次发布不能自动回滚。确实需要手动部署时,事后让 WishForge 再发布一次,组件就会回到有记录的状态。
- 想知道线上运行的是不是
poc的最新提交,让维护者跑一次doctor,看application.runsBranchHead。
10. 在 Codex / WorkBuddy 里许愿(MCP)
WishForge 提供 MCP 服务,Agent 客户端可以用你的身份远程许愿,权限不超过你本人,也不能代替你审批。
- 地址:本地为
http://127.0.0.1:4000/mcp;生产为 API 的 HTTPS 地址加/mcp。 - 认证:OAuth(授权码 + PKCE),本地授权服务器是 Keycloak。
- 工具:
| 工具 | 用途 |
|---|---|
list_projects |
列出你能访问的项目 |
submit_wish |
提交愿望(可带 sourceBranch 指定起点分支) |
get_run / get_run_events |
查询运行状态和事件 |
answer_question |
回答 Agent 的澄清问题 |
control_run |
暂停、继续、取消 |
get_delivery |
查看交付结果:代码变更、验证结果、应用地址 |
request_release |
请求发布 |
客户端配置方法见 connectors/README.md。本机 POC 的网页用本地账号登录,Codex/WorkBuddy 的 OAuth 接入需要另外在 Keycloak 中配置客户端。
11. 从自己推送的分支许愿
云 IDE 已经移除。想让自己写的改动经过验证再合入目标分支,可以:
- 把改动推送到项目仓库的一个分支(不能是目标分支,也不能以
wishforge/开头)。 - 通过 API 或 MCP 提交愿望时带上
sourceBranch(见第 10 章)。网页的提交表单不提供这个选项。 - 运行从这个分支的最新提交开始,Agent 可以在你的改动上继续,验证通过后连同你的改动一起合入目标分支;运行详情的「起点分支」显示它。
POC 项目固定从 poc 开始,不接受 sourceBranch。
12. 本机服务维护指南
本章写给维护这台 Mac 上 WishForge 服务的人。
12.1 服务组成
| 服务 | 地址 | 作用 |
|---|---|---|
| 网页工作台 | http://localhost:3000 | 用户入口;可开放给局域网 |
| 控制面 API | http://127.0.0.1:4000 | 核心逻辑;/health 存活检查,MCP 在 /mcp |
| 平台 Git | http://127.0.0.1:4504 | 平台托管仓库(POC 不用) |
| 本地 provisioner | http://127.0.0.1:4450 | 为每个运行代次启动执行器和验证器进程 |
| coordinator / deployer worker | — | 运行 Temporal 工作流 |
| Runner | — | 从控制面拉取签名的部署任务,部署到 POC 集群 |
| Temporal 控制台 | http://127.0.0.1:8233 | 查看工作流(排障用) |
依赖服务(PostgreSQL、Temporal、Keycloak、MinIO 等)由 Docker Compose 运行,不归本服务的启停脚本管。
服务以 macOS LaunchAgent 方式在后台运行,随当前用户登录运行;退出登录、关机或系统睡眠时不可用。需要持续接收愿望时,保持电脑通电并设置合适的睡眠策略。
12.2 日常命令
在仓库根目录执行,不需要 sudo:
node scripts/local-poc-service.mjs status
node scripts/local-poc-service.mjs doctor
node scripts/local-poc-service.mjs stop
node scripts/local-poc-service.mjs start
| 命令 | 作用 |
|---|---|
status |
只看 launchd 进程状态和日志位置 |
doctor |
全面体检,见 12.3 |
stop |
停止服务;等进程真正退出才返回成功,最多约 45 秒 |
start |
启动服务,并等待各服务就绪,最多约 90 秒 |
install |
首次安装,或启动脚本、LaunchAgent 配置变化后使用(先 stop 再 install) |
操作前先确认没有执行中的愿望或发布,避免打断正在进行的集群更新。不要用 pkill node、按端口批量杀进程或停止 Colima 来代替 stop。
更新代码后:
- 只改了服务端代码:
stop后start。 - 改了网页代码:
stop→ 重新构建网页 →start:
node scripts/build-local-web.mjs
构建前会把当前网页保存为备份(.wishforge/local-poc/web-builds/previous-<id>),编译失败自动还原;成功后只保留上一版和一份更早的版本。新版本上线后有问题,停服务后按构建回执 .wishforge/local-poc/last-web-build.json 里的路径还原。
注意:每个运行的执行器和验证器进程是直接用工作区里的代码启动的,改了仓库里的代码,下一个运行马上就会用上(哪怕服务没重启)。所以有运行在执行时,不要改仓库里的代码。
12.3 看懂 doctor
doctor 输出一份 JSON,status 为 ready(一切正常)、degraded(能用但有问题)或 not-ready(不能用)。
| 部分 | 含义 |
|---|---|
services |
网页、API、数据库、provisioner、Git 服务是否就绪 |
runner |
Runner 是否在正常轮询(ready;执行部署时为 busy) |
build |
网页构建产物是否存在 |
lan |
局域网入口配置;mismatch 表示本机当前的局域网地址还没被放行 |
dependencies.cluster |
POC 集群 API 是否可达 |
dependencies.repository |
poc 分支能否读取:read 是构建读分支的方式,push 是合入推送用的 SSH 登录;head 是分支最新提交 |
dependencies.application |
公网应用报告的构建提交;runsBranchHead 为 false 表示有人推了还没部署的提交 |
dependencies.executor |
Claude CLI 能否启动及其版本 |
dependencies.disk |
运行目录所在磁盘剩余空间(低于 5 GB 为 low) |
doctor 只读,不调用模型、不部署、不领取任务,随时可以运行。提交重要的愿望前先跑一次,能提前发现集群、Gitea 或磁盘的问题。
12.4 局域网访问与登录
- 本机管理员的登录凭据保存在
.wishforge/local-access.json(权限 0600),含账号、密码和会话签名材料。不要上传、贴到聊天或日志里。其他人用管理员在「成员与权限」页创建的个人账号登录(见 4.12),不要把本机管理员的密码分给大家。 - 本机 IP 变化后,新地址需要放行才能访问,否则返回 403「请求来源不被允许」。查看和应用新地址:
npm run local:network
npm run local:network -- --address <新的局域网 IP>
npm run local:network -- --address <新的局域网 IP> --apply
应用后 stop 再 start,并从另一台设备实际登录验证。
- 有人离开团队:在「成员与权限」页停用这个人的账号即可。更换本机管理员密码:删除
.wishforge/local-access.json,运行node scripts/setup-local-access.mjs重新生成;所有人的登录会话(包括成员账号)都会失效,需要重新登录。 - 局域网 HTTP 会明文传输登录信息,只在可信网络中使用;需要公网访问时使用经批准的 HTTPS 入口。
- 15 分钟内密码输错超过 8 次后,校验会限速(每 2 秒最多一次),不会把人锁在外面。
12.5 日志与数据位置
| 内容 | 位置 |
|---|---|
| 服务日志 | .wishforge/local-poc/logs/:platform.log、runner.log、supervisor.log(每个 5 MB 轮转,保留 3 份) |
| 本机配置 | .env.local(0600)、.wishforge/local-poc/runner.env(0600) |
| POC 绑定与配置 | .wishforge/local-poc/project.json、~/.config/wishforge/poc-profile.json |
| 运行目录 | ~/.local/share/wishforge/runs/:每个运行代次一个目录,释放后保留 7 天再自动清理 |
| POC 构建记录 | ~/.local/share/wishforge/poc/builds/<发布>/:清单和日志长期保留;上传用的源码包只保留最近的 |
| 受保护检查缓存 | .wishforge/poc-check-cache/ |
排障时先看 supervisor.log 的启动和退出记录,再看对应服务的日志。不要整个删除 .wishforge/ 目录:里面有 POC 绑定、登录凭据、Runner 密钥和部署回执。
12.6 可选的沙箱设置
POC 以 host 模式运行:执行器和验证器直接以当前用户身份运行。有两项可选加固,步骤见 local-poc-operations.md:
- 受保护检查在 Seatbelt 沙箱中运行(当前已开启):检查读不到主目录、不能联网、连不上平台自己的端口。
- 让 Claude 在命令沙箱中执行命令:开启后 Claude 能自己构建和测试;默认关闭,Claude 只有文件工具。
开启前都要先运行文档中的检查脚本,全部通过才开启。
12.7 配额
本机套餐用命令行设置,例如每月 2000 万 token、单并发:
node --import tsx scripts/configure-local-poc-plan.ts 20000000
这只是计量上限,不购买模型额度。用量在「用量」页查看和导出。
12.8 安全须知
host模式没有完整隔离:Agent 写的代码和项目测试在这台 Mac 上运行,只用于可信的项目和模型。- 镜像构建凭据:集群里的镜像构建能读到推送镜像仓库的凭据,而 Dockerfile 可以被 Agent 修改,构建又发生在审批之前。建议运维把这份凭据收窄到只能推送这几个镜像仓库,并限制构建 Pod 的出网。
- 账号与权限:本机管理员拥有全部权限,不要把它的密码分给大家;其他人用自己的账号,按需给最小的账户类型(例如只做页面的人给「前端开发」)。开发模式下请求人可以批准自己的发布和审核自己的改动,要求「别人来批」需靠团队约定。
12.9 飞书通知
配置后,下面这些事会推送到一个飞书群:
| 消息 | 什么时候 | 会 @ 决策人 |
|---|---|---|
| 【待审批】 | 有发布等待确认 | 是 |
| 【待审核】 | 有改动等待代码审核 | 是 |
| 【需要处理】 | 运行停下来等人处理(基础设施故障、修复轮用完、需要补充等) | 否 |
| 【已完成】 | 运行完成,附应用地址或合入的提交 | 否 |
| 【发布失败】/【已回滚】 | 发布没能上线或被回滚 | 否 |
配置步骤:
- 在要接收通知的飞书群里添加「自定义机器人」,复制它的 webhook 地址;建议同时开启「签名校验」并复制密钥。
- 在仓库根目录的
.env.local里加上这几行(WF_FEISHU_WEBHOOK_URL必填,其余可选):
WF_FEISHU_WEBHOOK_URL=https://open.feishu.cn/open-apis/bot/v2/hook/<机器人的 ID>
WF_FEISHU_WEBHOOK_SECRET=<签名校验的密钥>
WF_FEISHU_MENTIONS=<要 @ 的决策人的 open_id,以 ou_ 开头,多个用英文逗号分隔>
WF_NOTIFY_WEB_URL=<大家打开网页用的地址,例如 http://10.112.12.22:3000>
stop再start服务。
几点说明:
- webhook 地址和密钥等同于往群里发消息的凭据,不要贴到聊天或文档里。
- 消息只带愿望的第一行(目标)、提交人、等待原因和审批原因,不带代码和执行器写的说明;消息里来自运行的文字不会变成链接或 @。
- 每条消息只发一次,服务重启不会重发。发送失败会自动重试;只补发 30 分钟内的变化,服务停机超过 30 分钟期间的变化不再补发。
- 群消息里的按钮只是跳到网页,审批和审核仍在网页上完成。
13. 常见问题
提交后一直「排队中」?
POC 一次只执行一个运行,前面的运行还在执行时新愿望会排队,前一个完成或停下等待后几秒内开始。如果没有别的运行也一直排队,让维护者跑 doctor 检查服务。
运行停在「基础设施故障」?
看等待说明里的报错。常见原因是到 POC 集群的网络断了一阵、依赖下载失败。用 doctor 确认集群和 Gitea 可达后点「继续」,不消耗修复轮数。
Agent 修了几轮还是不过?
打开「验证证据」看失败命令的输出。需求没说清楚,就在「补充或修改需求」里说明;需要更多尝试,点「继续」再修一轮;方向错了,取消后写一个更具体的愿望。
为什么这次发布要审批?
在「部署与审批」展开这条发布,看「审批原因」。最常见的是改到了受保护文件(Dockerfile、依赖清单、迁移、鉴权等),或 poc 上有别人直接推的、还没部署的敏感改动。
审批过期了怎么办?
审批 24 小时内有效。过期后发布失败,回到运行详情点「继续」重新请求发布。
运行完成了,线上怎么没变?
未配置交付的项目,完成只代表已合入目标分支;POC 项目会部署。让维护者跑 doctor 看 application.buildCommit 是否等于这次合入的提交;也可能是浏览器缓存,强制刷新试试。
可以一次提很多个愿望吗?
可以,它们会排队依次执行,每个都独立验证、独立上线。相互有依赖的改动,建议等前一个上线后再提下一个。
取消运行会撤回已经合入的代码吗?
不会。取消只停止后续步骤;已经推到目标分支的提交,需要另提一个撤销的愿望。
想把线上版本退回去?
在「部署与审批」点线上发布的「回滚」;要连代码一起退掉,在运行详情点「撤销这次改动」。见 8.3。
怎么在飞书里收到审批提醒?
请维护者按 12.9 配置飞书机器人。配置后,待审批的发布和待审核的代码会推送到群里并 @ 决策人。
电脑睡眠或重启后怎么办?
唤醒或重新登录后,跑 status 和 doctor 确认服务正常;中断的运行以控制面记录为准,需要时点「继续」。
页面提示「请登录工作空间」?
登录会话 1 小时后失效,重新登录即可。
怎么把整个本地环境重置?
见 development.md 第 7 节。不要整个删除 .wishforge/ 目录。
14. 附录
14.1 账户类型与权限
账户类型和四项权限见 4.12。各项权限包含的操作:
| 权限 | 包含的操作 |
|---|---|
| 查看(所有人) | 查看自己能进入的项目、运行、代码变更、证据和发布 |
| 许愿 | 提交愿望、AI 优化、继续/暂停/取消运行、补充需求、撤销改动、创建项目;能不能改后端见 4.12 |
| 审核代码 | 批准或驳回代码审核 |
| 审批发布 | 批准、拒绝、回滚发布(含 GitHub 合并授权) |
| 管理 | 成员与权限、项目设置(含代码权限)、调整预算、执行器凭据、环境与 Runner(含「每次发布都需人工确认」)、Agent 配置、用量明细与导出;包含以上全部 |
本机管理员是管理员。用组织身份(OIDC)登录的部署没有「成员与权限」页,按角色决定:管理员(含所有者)拥有全部权限;开发者能许愿,改到后端要审核,除非项目设置把这个人列为「可以直接改后端代码的人」;部署者审批和回滚发布;只读只能查看。
14.2 相关文档
| 文档 | 内容 |
|---|---|
| requirements.md | 产品需求 |
| architecture.md | 架构、状态机、信任模型 |
| development.md | 从零搭建本地开发环境、测试 |
| local-poc-operations.md | 本机 POC 运维细节 |
| local-browser-access.md | 局域网访问与登录 |
| operations.md | 生产部署与运维 |
| reference/repository-contract.md | 仓库、分支、合入约定 |
14.3 术语中英对照
| 中文 | 英文 / 代码 |
|---|---|
| 愿望 | wish |
| 运行 | run |
| 需求版本(修订) | revision |
| 执行器 | provider / executor |
| 验证器 | verifier |
| 受保护检查 | protected verification commands |
| 检查点 | checkpoint |
| 证据 | evidence |
| 修复轮 | repair round |
| 代码审核 | code review |
| 撤销运行 | revert |
| 合入 | integrate |
| 发布 | release |
| 目标环境 | environment |
| 审批 | approval |
| 验收 | accept |
| 代次 | generation |
| 项目技能 | skill |
| 踩坑记录 | pitfall |
| 知识库 | knowledge base |
| Agent 配置 | agent bundle |
| 等待原因 | waiting reason |