wishforge-ide/docs/user-manual.md
eust-w 3217982f32 🔀 Merge project knowledge
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
2026-11-04 12:45:22 +08:00

72 KiB
Raw Blame History

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 为例。

  1. 打开网页:在这台 Mac 上打开 http://localhost:3000 ;同一局域网的其他电脑打开 http://<这台 Mac 的局域网 IP>:3000(这个地址须已被维护者放行,见 12.4)。
  2. 登录:在登录页填自己的账号和密码(由管理员在「成员与权限」页创建后交给你;维护者也可以用本机管理员账号),点「进入工作空间」。会话从登录起 1 小时后失效,期间操作不会延长。
  3. 提交愿望:点「工作概览」或「运行记录」右上角的「+ 提交愿望」。项目空间选 POC 项目,在「你的愿望」里写要什么,在「验收标准」里每行写一条;拿不准怎么写时,点愿望下面的「AI 优化愿望」或验收标准下面的「AI 生成验收标准」,确认改写结果后再提交。执行器保持 Claude Code,点「提交愿望」。
  4. 看进度:页面会跳到运行详情。「阶段事件」标签页实时显示 Agent 的回复、改了哪些文件、验证结果和部署进度。
  5. 看结果:运行完成后,「交付结果」里有「访问应用 ↗」,「代码变更」里是这次改动的 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)。

项目设置(「⚙ 项目设置」)分两部分:

  1. 独立验收配置:生产交付必须绑定平台管理员安装的验收配置,仅 Owner 或 Admin 可改,选好后点「保存独立验收配置」。本机 POC 不需要。
  2. 主要设置,点「保存设置」生效:
字段 说明
目标分支 验证通过的代码合入这个分支;新愿望也从它的最新提交开始
验证命令 受保护检查。每行一个 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 运行详情

页面从上到下:

  1. 标题区:愿望的第一行(目标),以及状态、运行 ID、「修订 n」(需求版本)、执行器。
  2. 阶段条:澄清 → 规划 → 实现 → 验证 → 合入 → 构建 → 发布 → 验收,已完成的打勾,当前阶段高亮。
  3. 操作按钮,随状态变化:
运行状态 可用按钮
排队中、运行中 暂停、取消运行
暂停中 取消运行
等待处理(大多数原因) 继续、取消运行
等待处理(等待澄清、等待代码审核、等待审批、部署进行中) 暂停、取消运行
已暂停 继续、取消运行
已完成、已取消 无

已经合入过代码的运行(不论状态)还有「撤销这次改动」,见 8.3。

  • 「暂停」「继续」点了立即生效,没有确认。
  • 「取消运行」会弹出确认框「取消本次运行」,选「确认取消」才执行,选「保留运行」放弃。
  • 预算已经用完时,「继续」是灰的,需要先调整预算。
  1. 等待说明(仅等待处理时):原因的中文标题、后端给出的具体说明(多为英文)、该怎么做,有时附带链接(如「管理执行器」「去审批」)。下面可以展开「补充或修改需求」,写补充说明或回答问题后点「发送补充」:这会产生新的需求版本,运行从规划阶段重新开始。这个表单只在等待处理时出现,只能写文字说明,不能在这里改验收标准。只改前端的愿望停在「执行器需要你的补充」、或者因为一直改到后端而用完了修复轮时,这里还有「改为前端和后端并继续」:确认后这个愿望可以改后端代码,运行带着这个决定从规划阶段重新开始(需求版本加一),确认框里可以顺便回答 Agent 的其他问题;时间线记一条「代码范围改为前端和后端」。之后改到后端时,只有提交人和所有补充过需求的人都能直接合入才不用审核。只有能许愿改后端的人看得到这个按钮;只能改前端的人看到的是「请可以许愿改后端的人放开」。同样,只能改前端的人不能给可以改后端的运行补充需求,补充表单会换成一句说明。
  2. 代码审核(仅等待代码审核时):列出改到的后端代码和提交人,「代码变更」链接跳到完整改动。有「审核代码」权限的人勾选「我已查看「代码变更」里的全部改动」后可以「批准合入」;或写下审核意见后「驳回并说明」。批准后运行自动继续合入,不再重复检查;驳回后意见作为补充需求交给执行器再改一轮,改完会再次等待审核。不能批准自己提的改动,除非自己本来就能直接合入。没有这项权限的人只能看到「等待有「审核代码」权限的人审核」。
  3. 运行预算(仅管理员,且运行处于等待处理或已暂停时):显示已用 Token 和已执行时间,展开「调整预算」可以改 Token 上限(最多 200 万)、时间上限(最多 180 分钟)、修复轮次上限(最多 3),点「保存预算」。保存不会自动继续,还要再点「继续」。
  4. 交付结果:部署验收通过后显示「访问应用 ↗」;未配置交付的项目显示合入的提交。
  5. 四个标签页:
标签页 内容
概览 最近一次失败(验证失败、依赖安装失败、合并冲突,或只改前端的愿望改到了后端代码)及输出,这就是修复轮交给 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 生成验收标准」。它的工作方式:

  1. 把你写的愿望和验收标准草稿发给控制面;
  2. 控制面用这台部署的本机 Claude 账号改写,不开任何工具:不读代码仓库、不执行命令、不联网查资料,只根据你写的文字;
  3. 按内置规则改写,再加上项目设置里的「愿望优化规则」:
    • 保留原意,不增加你没要求的功能,也不替你做草稿里没有的决定;
    • 愿望最多三行:目标、「范围:」、「不改:」;
    • 细节只写在验收标准里,3~6 条,每条都能回答「做到了没有」,不重复愿望里的话,最后一条是「现有测试、类型检查和构建全部通过」;
    • Agent 读代码就能定的事(存在哪里、放在哪个模块、接口怎么写)不问你,愿望里写「沿用项目现有做法」;
    • 只有你能拍板的问题(做什么、给谁用、做到什么程度)列成「需要你选」,最多 3 个,每个 2~4 个选项,第一个是推荐的;你没提到的扩展(保留多久、权限、导出等)不问;
  4. 弹窗里,推荐选项默认选中,选中的那句话会加进愿望(在建议里高亮显示,放在「不改:」那行前面);再点一次就不写,也可以点「自己写」。建议的验收标准每条前面有勾选框:表单里还没写验收标准时默认全选;已经写了时默认不勾,勾了才替换你写的。其他提醒(例如建议拆成几个愿望)列在「提醒」里;
  5. 优化验收标准时愿望保持原样,也不出选择题;
  6. 结果只给你看,不保存、不提交,也不计入运行的 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 怎么审批

有「审批发布」权限的人(管理员、发布负责人,或单独给了这项权限的人)可以审批;其他人能打开「审阅发布」看内容,但没有批准和拒绝按钮。配置了飞书通知时,待审批的发布会推送到飞书群并 @ 决策人,点消息里的「去审批」直达这一页。

  1. 打开「部署与审批」,找到状态为「待审批」的发布,点「🛡 审阅发布」。
  2. 核对目标环境、需求与验收标准、独立验证结果、提交与镜像、审批原因。
  3. 勾选「我已核对以上源代码、制品、目标环境和验证证据。」,点「✓ 批准此版本」;或点「✕ 拒绝」(直接生效,没有二次确认)。

注意:

  • 审批 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、还没部署的提交 随下一个运行一起部署,并计入那次发布的风险判断(该审批的照样审批)

几条规矩:

  1. 不要强推(force push)poc。进行中的运行合入时会把你删掉的提交重新带回来;已经合入的运行会停在「项目仓库未就绪」,只能取消。
  2. 推 poc 之前自己先跑一遍检查,保持分支是好的,否则别人的运行会停在「目标分支自身未通过检查」。
  3. 不要手动改 POC 集群里的镜像。改过的组件(包括用 tag 部署的)会被当作来源不明,下次发布要重建并人工审批,而且那次发布不能自动回滚。确实需要手动部署时,事后让 WishForge 再发布一次,组件就会回到有记录的状态。
  4. 想知道线上运行的是不是 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 已经移除。想让自己写的改动经过验证再合入目标分支,可以:

  1. 把改动推送到项目仓库的一个分支(不能是目标分支,也不能以 wishforge/ 开头)。
  2. 通过 API 或 MCP 提交愿望时带上 sourceBranch(见第 10 章)。网页的提交表单不提供这个选项。
  3. 运行从这个分支的最新提交开始,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 飞书通知

配置后,下面这些事会推送到一个飞书群:

消息 什么时候 会 @ 决策人
【待审批】 有发布等待确认 是
【待审核】 有改动等待代码审核 是
【需要处理】 运行停下来等人处理(基础设施故障、修复轮用完、需要补充等) 否
【已完成】 运行完成,附应用地址或合入的提交 否
【发布失败】/【已回滚】 发布没能上线或被回滚 否

配置步骤:

  1. 在要接收通知的飞书群里添加「自定义机器人」,复制它的 webhook 地址;建议同时开启「签名校验」并复制密钥。
  2. 在仓库根目录的 .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>
  1. 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