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
934 lines
72 KiB
Markdown
934 lines
72 KiB
Markdown
# WishForge 使用手册
|
||
|
||
这份手册写给两类人:
|
||
|
||
- **使用者**:提愿望、看进度、处理等待、审批发布的人。读第 1~11 章就够了。
|
||
- **本机服务的维护者**:负责这台 Mac 上 WishForge 服务的人。另外读第 12、13 章。
|
||
|
||
想快速试一次,直接看[第 3 章](#3-五分钟上手)。运行停住了,看[第 7 章](#7-运行停下来了怎么办)。界面上每个按钮和字段的说明在[第 4 章](#4-网页工作台逐页说明)。
|
||
|
||
---
|
||
|
||
## 1. WishForge 是什么
|
||
|
||
一句话:**你用自然语言提一个「愿望」,WishForge 让编码 Agent 去实现,再由一个独立的验证器按事先定好的检查来判定,通过了就合入代码,需要的话构建并部署上线。**
|
||
|
||
整个过程像一条流水线:
|
||
|
||
```
|
||
提愿望 → Agent 写代码 → 独立验证 → 合入目标分支 → 构建镜像 →(必要时人工审批)→ 部署 → 验收
|
||
↑ │
|
||
└── 没通过时带着报错自动修复(修复轮)
|
||
```
|
||
|
||
几个关键特点:
|
||
|
||
- **Agent 说了不算**:代码合不合格,由与 Agent 完全隔离的验证器在干净的目录里运行「受保护检查」来判定。Agent 不能跳过、修改或伪造这些检查。
|
||
- **全程有证据**:每次验证、合入、构建、部署都有记录,绑定精确的代码提交(commit)和镜像摘要(digest),随时可查。
|
||
- **会自己修**:检查没通过时,Agent 拿着失败的命令和输出继续修,最多修到你设定的轮数。
|
||
- **有人把关**:每个人的账户类型决定能许愿改什么。项目可以划出「后端代码」:只能改前端的人提的愿望碰不到后端,不能直接合入后端的人改到后端时,验证通过后先等人审核再合入;改动涉及迁移、鉴权、构建配方、依赖等敏感内容时,发布会停下来等人审批;环境也可以设置为每次发布都要人确认。
|
||
- **能撤回**:线上版本可以一键回滚;已经合入的改动可以一键撤销,撤销同样走验证和发布。
|
||
- **越用越好**:运行中积累的「项目技能」(做法、踩坑记录、项目约定)会自动带进同一项目后续的任务里,在「知识库」统一管理。
|
||
|
||
### 1.1 两个入口
|
||
|
||
| 入口 | 适合做什么 |
|
||
|---|---|
|
||
| **网页工作台** | 全部功能:提愿望、看进度和代码改动、处理等待、审批发布、管理项目与配置 |
|
||
| **Agent 客户端(MCP)** | 在 Codex、WorkBuddy 的对话里直接许愿和跟进(见[第 10 章](#10-在-codex--workbuddy-里许愿mcp)) |
|
||
|
||
### 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 章](#5-怎样写好一个愿望) |
|
||
| **需求版本**(修订) | 愿望的版本号 | 你「补充需求」后版本加一,旧版本的验证结果和审批全部作废 |
|
||
| **运行** | 为一个愿望进行的一次完整交付 | 有自己的阶段、状态、时间线和证据 |
|
||
| **执行器** | 实际写代码的编码 Agent | POC 只用 Claude Code;平台还支持 Codex、CodeBuddy |
|
||
| **检查点** | 执行器产出的精确代码状态(一个 commit) | 暂停、中断后从检查点接着做,不会从头再来 |
|
||
| **验证器** | 独立运行受保护检查的组件 | 与执行器的身份、目录完全隔离,只有它能出具验证证据 |
|
||
| **受保护检查** | 项目设置里的验证命令 | Agent 改不了;POC 是 TypeScript 检查、前端测试、前端构建、Go 测试 |
|
||
| **证据** | 验证、合入、构建、部署各步的结果记录 | 在运行详情的「验证证据」里看每条命令的退出码、耗时和输出 |
|
||
| **修复轮** | 检查失败后 Agent 的一次修复 | 次数受「最多修复轮次」限制 |
|
||
| **代码权限** | 哪些代码算后端 | 项目设置里划出哪些路径算后端代码;每个人能不能改后端、改了要不要审核,看各自的账户类型(见 4.12) |
|
||
| **代码范围** | 这个愿望能不能改后端 | 提交愿望时选:「只改前端」的愿望改到后端代码时,平台把这些改动恢复原样,让 Agent 只改前端重做;「前端和后端」的愿望可以改后端,按提交人的代码权限决定要不要审核 |
|
||
| **合入** | 把验证通过的代码推到目标分支 | 目标分支被别人改过时,会先合并、**重新验证**再推 |
|
||
| **发布** | 把构建好的镜像部署到目标环境 | 风险高时等人审批;POC 环境平时自动发布 |
|
||
| **目标环境** | 部署去处 | POC 的目标环境就是既有的 POC 集群 |
|
||
| **验收** | 部署后的健康与业务检查 | 不通过时,允许的话自动切回旧版本 |
|
||
| **等待处理** | 运行停下来等条件或等人处理 | 每种原因都有中文说明和处理办法,见[第 7 章](#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](#124-局域网访问与登录))。
|
||
2. **登录**:在登录页填自己的账号和密码(由管理员在「成员与权限」页创建后交给你;维护者也可以用本机管理员账号),点「进入工作空间」。会话从登录起 1 小时后失效,期间操作不会延长。
|
||
3. **提交愿望**:点「工作概览」或「运行记录」右上角的「+ 提交愿望」。项目空间选 POC 项目,在「你的愿望」里写要什么,在「验收标准」里每行写一条;拿不准怎么写时,点愿望下面的「AI 优化愿望」或验收标准下面的「AI 生成验收标准」,确认改写结果后再提交。执行器保持 Claude Code,点「提交愿望」。
|
||
4. **看进度**:页面会跳到运行详情。「阶段事件」标签页实时显示 Agent 的回复、改了哪些文件、验证结果和部署进度。
|
||
5. **看结果**:运行完成后,「交付结果」里有「访问应用 ↗」,「代码变更」里是这次改动的 diff,「验证证据」里是每条检查的结果。
|
||
|
||
运行停在「等待处理」时,页面会用中文说明原因和该做什么,对照[第 7 章](#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。
|
||
|
||
- 「暂停」「继续」点了立即生效,没有确认。
|
||
- 「取消运行」会弹出确认框「取消本次运行」,选「确认取消」才执行,选「保留运行」放弃。
|
||
- 预算已经用完时,「继续」是灰的,需要先调整预算。
|
||
|
||
4. **等待说明**(仅等待处理时):原因的中文标题、后端给出的具体说明(多为英文)、该怎么做,有时附带链接(如「管理执行器」「去审批」)。下面可以展开「**补充或修改需求**」,写补充说明或回答问题后点「发送补充」:这会产生新的需求版本,运行从规划阶段重新开始。这个表单只在等待处理时出现,只能写文字说明,不能在这里改验收标准。只改前端的愿望停在「执行器需要你的补充」、或者因为一直改到后端而用完了修复轮时,这里还有「**改为前端和后端并继续**」:确认后这个愿望可以改后端代码,运行带着这个决定从规划阶段重新开始(需求版本加一),确认框里可以顺便回答 Agent 的其他问题;时间线记一条「代码范围改为前端和后端」。之后改到后端时,只有提交人和所有补充过需求的人都能直接合入才不用审核。只有能许愿改后端的人看得到这个按钮;只能改前端的人看到的是「请可以许愿改后端的人放开」。同样,只能改前端的人不能给可以改后端的运行补充需求,补充表单会换成一句说明。
|
||
5. **代码审核**(仅等待代码审核时):列出改到的后端代码和提交人,「代码变更」链接跳到完整改动。有「审核代码」权限的人勾选「我已查看「代码变更」里的全部改动」后可以「批准合入」;或写下审核意见后「驳回并说明」。批准后运行自动继续合入,不再重复检查;驳回后意见作为补充需求交给执行器再改一轮,改完会再次等待审核。不能批准自己提的改动,除非自己本来就能直接合入。没有这项权限的人只能看到「等待有「审核代码」权限的人审核」。
|
||
6. **运行预算**(仅管理员,且运行处于等待处理或已暂停时):显示已用 Token 和已执行时间,展开「调整预算」可以改 Token 上限(最多 200 万)、时间上限(最多 180 分钟)、修复轮次上限(最多 3),点「保存预算」。保存不会自动继续,还要再点「继续」。
|
||
7. **交付结果**:部署验收通过后显示「访问应用 ↗」;未配置交付的项目显示合入的提交。
|
||
8. **四个标签页**:
|
||
|
||
| 标签页 | 内容 |
|
||
|---|---|
|
||
| 概览 | 最近一次失败(验证失败、依赖安装失败、合并冲突,或只改前端的愿望改到了后端代码)及输出,这就是修复轮交给 Agent 的内容;具体要求(愿望第一行之后的各行,一行一条;补充需求也接在这里);改动说明(执行器完成实现时写的总结,以代码变更和验证结果为准);验收标准;执行上下文(项目、提交人、代码范围、撤销的是哪个运行、起点分支、创建与更新时间、修复轮次、已合入提交、Token 与时间的上限和用量) |
|
||
| 代码变更 | 这次改动的逐文件 diff,相对任务开始时的目标分支(或起点分支);很大的改动只显示前 4000 行 |
|
||
| 阶段事件 | 执行时间线:每条事件显示序号、类别、时间和说明。能看到 Agent 的回复、执行的命令、改动的文件、模型用量、阶段推进、证据、发布进度。说明来自后端,多为英文 |
|
||
| 验证证据 | 每次验证、合入、构建、部署的结果卡片:需求版本、时间、隔离方式(沙箱隔离 / 本机执行)、通过或未通过;每条命令的退出码、耗时和输出(失败的默认展开);依赖安装失败时会注明「验证命令没有运行(不消耗修复轮数)」 |
|
||
|
||
### 4.6 部署与审批
|
||
|
||
- 顶部「目标环境 →」进入环境管理([4.7](#47-目标环境))。
|
||
- **发布记录**:每条发布显示所属运行、目标环境、时间、状态,状态健康时有「访问应用 ↗」;环境当前线上的发布还有「**回滚**」(见 8.3)。点右侧箭头展开绑定详情:源代码提交、镜像摘要、绑定摘要、架构、应用地址、配置与策略版本、证据记录,以及**审批原因**(中文)。
|
||
- 发布状态:
|
||
|
||
| 状态 | 含义 |
|
||
|---|---|
|
||
| 待审批 | 等人审批 |
|
||
| 就绪 | 已批准或无需审批,等待 Runner 部署 |
|
||
| 部署中 | Runner 正在部署 |
|
||
| 健康 | 部署并验收通过,是当前线上版本 |
|
||
| 失败 | 部署失败、验收失败、被拒绝或审批过期 |
|
||
| 已回滚 | 被回滚,旧版本恢复了服务 |
|
||
| 待确认 | 部署结果未知,需要核对 |
|
||
|
||
- **审批**:待审批的发布有「🛡 审阅发布」按钮,打开「审阅这次发布」对话框,内容有目标环境(生产环境会醒目提示)、项目、需求与验收标准、提交人、改动说明、独立验证(每条命令的退出码,以及是否在 Seatbelt 沙箱中运行)、审批期限和请求人、绑定详情。勾选「我已核对以上源代码、制品、目标环境和验证证据。」后「✓ 批准此版本」才能点;「✕ 拒绝」随时可点,**点了直接拒绝,没有二次确认**。
|
||
- 回滚与撤销改动见 [8.3](#83-回滚与撤销)。
|
||
|
||
### 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 示例
|
||
|
||
**你的愿望**(目标、范围、不改各一行):
|
||
|
||
```text
|
||
为 buildStorageHistoryScopeKey 补充单元测试。
|
||
范围:src/lib/storage-path-history.js 里的这个函数,测试放在 tests/frontend/ 下的新文件中。
|
||
不改:src/ 下的任何代码。
|
||
```
|
||
|
||
**验收标准**(每行一条):
|
||
|
||
```text
|
||
测试覆盖有 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 章](#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](../connectors/README.md)。本机 POC 的网页用本地账号登录,Codex/WorkBuddy 的 OAuth 接入需要另外在 Keycloak 中配置客户端。
|
||
|
||
---
|
||
|
||
## 11. 从自己推送的分支许愿
|
||
|
||
云 IDE 已经移除。想让自己写的改动经过验证再合入目标分支,可以:
|
||
|
||
1. 把改动推送到项目仓库的一个分支(不能是目标分支,也不能以 `wishforge/` 开头)。
|
||
2. 通过 API 或 MCP 提交愿望时带上 `sourceBranch`(见[第 10 章](#10-在-codex--workbuddy-里许愿mcp))。网页的提交表单不提供这个选项。
|
||
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:
|
||
|
||
```bash
|
||
node scripts/local-poc-service.mjs status
|
||
```
|
||
|
||
```bash
|
||
node scripts/local-poc-service.mjs doctor
|
||
```
|
||
|
||
```bash
|
||
node scripts/local-poc-service.mjs stop
|
||
```
|
||
|
||
```bash
|
||
node scripts/local-poc-service.mjs start
|
||
```
|
||
|
||
| 命令 | 作用 |
|
||
|---|---|
|
||
| `status` | 只看 launchd 进程状态和日志位置 |
|
||
| `doctor` | 全面体检,见 [12.3](#123-看懂-doctor) |
|
||
| `stop` | 停止服务;等进程真正退出才返回成功,最多约 45 秒 |
|
||
| `start` | 启动服务,并等待各服务就绪,最多约 90 秒 |
|
||
| `install` | 首次安装,或启动脚本、LaunchAgent 配置变化后使用(先 `stop` 再 `install`) |
|
||
|
||
**操作前先确认没有执行中的愿望或发布**,避免打断正在进行的集群更新。不要用 `pkill node`、按端口批量杀进程或停止 Colima 来代替 `stop`。
|
||
|
||
**更新代码后**:
|
||
|
||
- 只改了服务端代码:`stop` 后 `start`。
|
||
- 改了网页代码:`stop` → 重新构建网页 → `start`:
|
||
|
||
```bash
|
||
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「请求来源不被允许」。查看和应用新地址:
|
||
|
||
```bash
|
||
npm run local:network
|
||
```
|
||
|
||
```bash
|
||
npm run local:network -- --address <新的局域网 IP>
|
||
```
|
||
|
||
```bash
|
||
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](local-poc-operations.md):
|
||
|
||
- **受保护检查在 Seatbelt 沙箱中运行**(当前已开启):检查读不到主目录、不能联网、连不上平台自己的端口。
|
||
- **让 Claude 在命令沙箱中执行命令**:开启后 Claude 能自己构建和测试;默认关闭,Claude 只有文件工具。
|
||
|
||
开启前都要先运行文档中的检查脚本,全部通过才开启。
|
||
|
||
### 12.7 配额
|
||
|
||
本机套餐用命令行设置,例如每月 2000 万 token、单并发:
|
||
|
||
```bash
|
||
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` 必填,其余可选):
|
||
|
||
```bash
|
||
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>
|
||
```
|
||
|
||
3. `stop` 再 `start` 服务。
|
||
|
||
几点说明:
|
||
|
||
- webhook 地址和密钥等同于往群里发消息的凭据,不要贴到聊天或文档里。
|
||
- 消息只带愿望的第一行(目标)、提交人、等待原因和审批原因,不带代码和执行器写的说明;消息里来自运行的文字不会变成链接或 @。
|
||
- 每条消息只发一次,服务重启不会重发。发送失败会自动重试;只补发 30 分钟内的变化,服务停机超过 30 分钟期间的变化不再补发。
|
||
- 群消息里的按钮只是跳到网页,审批和审核仍在网页上完成。
|
||
|
||
---
|
||
|
||
## 13. 常见问题
|
||
|
||
**提交后一直「排队中」?**
|
||
|
||
POC 一次只执行一个运行,前面的运行还在执行时新愿望会排队,前一个完成或停下等待后几秒内开始。如果没有别的运行也一直排队,让维护者跑 `doctor` 检查服务。
|
||
|
||
**运行停在「基础设施故障」?**
|
||
|
||
看等待说明里的报错。常见原因是到 POC 集群的网络断了一阵、依赖下载失败。用 `doctor` 确认集群和 Gitea 可达后点「继续」,不消耗修复轮数。
|
||
|
||
**Agent 修了几轮还是不过?**
|
||
|
||
打开「验证证据」看失败命令的输出。需求没说清楚,就在「补充或修改需求」里说明;需要更多尝试,点「继续」再修一轮;方向错了,取消后写一个更具体的愿望。
|
||
|
||
**为什么这次发布要审批?**
|
||
|
||
在「部署与审批」展开这条发布,看「审批原因」。最常见的是改到了受保护文件(Dockerfile、依赖清单、迁移、鉴权等),或 `poc` 上有别人直接推的、还没部署的敏感改动。
|
||
|
||
**审批过期了怎么办?**
|
||
|
||
审批 24 小时内有效。过期后发布失败,回到运行详情点「继续」重新请求发布。
|
||
|
||
**运行完成了,线上怎么没变?**
|
||
|
||
未配置交付的项目,完成只代表已合入目标分支;POC 项目会部署。让维护者跑 `doctor` 看 `application.buildCommit` 是否等于这次合入的提交;也可能是浏览器缓存,强制刷新试试。
|
||
|
||
**可以一次提很多个愿望吗?**
|
||
|
||
可以,它们会排队依次执行,每个都独立验证、独立上线。相互有依赖的改动,建议等前一个上线后再提下一个。
|
||
|
||
**取消运行会撤回已经合入的代码吗?**
|
||
|
||
不会。取消只停止后续步骤;已经推到目标分支的提交,需要另提一个撤销的愿望。
|
||
|
||
**想把线上版本退回去?**
|
||
|
||
在「部署与审批」点线上发布的「回滚」;要连代码一起退掉,在运行详情点「撤销这次改动」。见 [8.3](#83-回滚与撤销)。
|
||
|
||
**怎么在飞书里收到审批提醒?**
|
||
|
||
请维护者按 12.9 配置飞书机器人。配置后,待审批的发布和待审核的代码会推送到群里并 @ 决策人。
|
||
|
||
**电脑睡眠或重启后怎么办?**
|
||
|
||
唤醒或重新登录后,跑 `status` 和 `doctor` 确认服务正常;中断的运行以控制面记录为准,需要时点「继续」。
|
||
|
||
**页面提示「请登录工作空间」?**
|
||
|
||
登录会话 1 小时后失效,重新登录即可。
|
||
|
||
**怎么把整个本地环境重置?**
|
||
|
||
见 [development.md 第 7 节](development.md#7-常见问题)。不要整个删除 `.wishforge/` 目录。
|
||
|
||
---
|
||
|
||
## 14. 附录
|
||
|
||
### 14.1 账户类型与权限
|
||
|
||
账户类型和四项权限见 4.12。各项权限包含的操作:
|
||
|
||
| 权限 | 包含的操作 |
|
||
|---|---|
|
||
| 查看(所有人) | 查看自己能进入的项目、运行、代码变更、证据和发布 |
|
||
| 许愿 | 提交愿望、AI 优化、继续/暂停/取消运行、补充需求、撤销改动、创建项目;能不能改后端见 4.12 |
|
||
| 审核代码 | 批准或驳回代码审核 |
|
||
| 审批发布 | 批准、拒绝、回滚发布(含 GitHub 合并授权) |
|
||
| 管理 | 成员与权限、项目设置(含代码权限)、调整预算、执行器凭据、环境与 Runner(含「每次发布都需人工确认」)、Agent 配置、用量明细与导出;包含以上全部 |
|
||
|
||
本机管理员是管理员。用组织身份(OIDC)登录的部署没有「成员与权限」页,按角色决定:管理员(含所有者)拥有全部权限;开发者能许愿,改到后端要审核,除非项目设置把这个人列为「可以直接改后端代码的人」;部署者审批和回滚发布;只读只能查看。
|
||
|
||
### 14.2 相关文档
|
||
|
||
| 文档 | 内容 |
|
||
|---|---|
|
||
| [requirements.md](requirements.md) | 产品需求 |
|
||
| [architecture.md](architecture.md) | 架构、状态机、信任模型 |
|
||
| [development.md](development.md) | 从零搭建本地开发环境、测试 |
|
||
| [local-poc-operations.md](local-poc-operations.md) | 本机 POC 运维细节 |
|
||
| [local-browser-access.md](local-browser-access.md) | 局域网访问与登录 |
|
||
| [operations.md](operations.md) | 生产部署与运维 |
|
||
| [reference/repository-contract.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 |
|