johnQ
cfb393638c
skill-gate / gate (pull_request) Waiting to run
- 新增 req-workflow/skills/references/continuous-mode.md：阶段自动循环、hard/soft 门禁分级、checkpoint schema、恢复协议、停止格式、staging 终点约定 - req / req-workflow SKILL.md 增加 continuous 小节与门禁分级说明 - 版本号、CHANGELOG、docs/skill-routing.md、catalog.json 同步
118 lines
6.9 KiB
Markdown
118 lines
6.9 KiB
Markdown
# 连续推进（continuous）模式
|
||
|
||
> 目的：让 Codex 等**无人值守 agent** 能从一个需求一路推进到 staging 验证通过，**只在硬门禁停**。
|
||
> 默认即 continuous；只有用户明确要求「一步一步来 / 每步问我」时才退回逐阶段确认。
|
||
|
||
## 1. 目标与边界
|
||
|
||
- **自动终点**：一个 REQ 从 `/req new` 自动推进到「**staging 部署成功 + 冒烟验证通过**」，并把证据写进 checkpoint。
|
||
- **不在自动范围内**：生产发布（`/req deploy prod`）属**硬门禁**，必须人工授权；`force` 放行、需求范围变更同样必须人工拍板。
|
||
- 每个阶段的文档、任务、证据都要真实落盘（REQ 备注 / 任务文档 / checkpoint），**不得凭记忆或口头声称阶段完成**。
|
||
- 无人值守不等于无人负责：soft 门禁产生的「待用户确认」项必须在 checkpoint 与交付汇报里显式列出。
|
||
|
||
## 2. 阶段循环
|
||
|
||
每个阶段固定四步，**一步不缺**：
|
||
|
||
```
|
||
做事 → 留证据 → 写 checkpoint → 自动 /req next → 下一阶段
|
||
```
|
||
|
||
- **做事**：按阶段职责产出交付物（讨论结论 / PRD / 设计 / 代码 + PR / CR 报告 / 测试报告 / 部署记录）。
|
||
- **留证据**：可复核的命令 + 结果（测试输出、CI 链接、健康检查返回、冒烟截图路径），写入 `evidence[]`。
|
||
- **写 checkpoint**：更新 `.ai-proj/req-<id>.state.json` 的 `stage` / `evidence` / `next_command`。
|
||
- **自动下一步**：直接执行 `/req next`（或等价推进命令），进入下一阶段。
|
||
|
||
**禁止在阶段边界停**：不允许以「这一阶段做完了，请确认是否继续」结束回合；`/req next` 的门禁信息门禁走默认补齐流程（补文档后继续）。
|
||
|
||
## 3. 门禁分级
|
||
|
||
| 级别 | 门禁 | 连续模式下的行为 |
|
||
| --- | --- | --- |
|
||
| **hard（停）** | 需求方案确认 | 停下，等用户拍板方案 |
|
||
| **hard（停）** | PRD 评审通过 | 停下；禁止自审批、禁止代替用户放行 |
|
||
| **hard（停）** | 生产发布授权 | 停下，等显式授权才能 `/req deploy prod` |
|
||
| **hard（停）** | `force` 放行 | 停下，等用户确认并记录跳过原因 |
|
||
| **hard（停）** | 密钥 / 权限缺失 | 停下，说明缺什么、谁能给 |
|
||
| **hard（停）** | 需求范围变更 | 停下，范围变更必须重新确认 |
|
||
| **soft（不停）** | 讨论摘要确认 | 写 `## 讨论结论` 并追加到需求 description，标注「待用户确认」后**继续**写 PRD |
|
||
| **soft（不停）** | 部署范围确认 | 按 REQ 关联任务（`linkRole=deploy` / `implementation`）推导默认部署范围，记录推导依据后**继续** |
|
||
|
||
**soft 门禁的落地方式**：不停下发问，但必须把「待用户确认」写进两处——checkpoint 的 `blockers[]`（`type: "soft"`）与 REQ 备注；交付时统一列给用户复核。soft 策略只允许「按已有证据推导默认值」，不允许「替用户改变需求范围或方案」。
|
||
|
||
## 4. checkpoint 约定
|
||
|
||
文件路径：项目根 `.ai-proj/req-<id>.state.json`（一台机器一份，按需求 id 分文件；`<id>` 为数值 id）。
|
||
|
||
```json
|
||
{
|
||
"req_id": 897,
|
||
"stage": "testing",
|
||
"updated_at": "2026-11-01T10:20:00+08:00",
|
||
"evidence": [
|
||
{
|
||
"stage": "dev",
|
||
"command": "go test ./... && /req ci",
|
||
"result": "pass",
|
||
"artifact": "PR #123 / CI run 4567 全绿"
|
||
},
|
||
{
|
||
"stage": "staging",
|
||
"command": "按项目 AGENTS.md 的 staging 部署约定执行",
|
||
"result": "deployed",
|
||
"artifact": "staging 健康检查 200；冒烟记录 reports/smoke/REQ-897.md"
|
||
}
|
||
],
|
||
"next_command": "/req test",
|
||
"blockers": [
|
||
{ "type": "soft", "reason": "讨论摘要待用户确认", "needs": "用户 5 分钟复核" }
|
||
]
|
||
}
|
||
```
|
||
|
||
- `stage`：当前所在 `delivery_stage`（`analysis` / `design` / `dev` / `review` / `integration` / `testing` / `staging` / `released`）。
|
||
- `evidence[]`：每项 `stage / command / result / artifact`，`command` 要能原样重跑。
|
||
- `next_command`：恢复后要执行的第一条命令，写具体命令而不是「继续推进」。
|
||
- `blockers[]`：每项 `type`（`hard` / `soft`）/ `reason` / `needs`；hard 未清空时不得推进。
|
||
|
||
**恢复协议**（新会话 / 上下文丢失 / 换 agent 时）：
|
||
|
||
1. 先读 checkpoint；**没有就重建**：`ai-proj req get --id <id>` + `ai-proj req tasks --id <id>` 得到真实 `delivery_stage` 与任务状态，再写 checkpoint。
|
||
2. **复核 evidence 是否仍成立**：命令能否重跑通过、artifact 是否还在、REQ 阶段是否被人改过。失效的证据视为未完成，重做该阶段，不要沿用。
|
||
3. 从 `next_command` 继续；`blockers` 里还有 `type: "hard"` 时按 §5 停下。
|
||
4. checkpoint 与 REQ 实际状态冲突时，**以 REQ 状态为准**，修正 checkpoint 后再推进。
|
||
|
||
## 5. 停止格式
|
||
|
||
**只有命中 hard 门禁才停**，停下时固定输出五段：
|
||
|
||
```
|
||
卡点：<哪个 hard 门禁>
|
||
原因：<触发它的具体事实：报错 / 缺失 / 待授权的动作>
|
||
已做到哪：<最后一个有证据的阶段 + 证据位置>
|
||
下一步命令：<解除卡点后要执行的第一条命令>
|
||
需要谁确认：<用户 / 复核人 / 运维 / 安全>
|
||
```
|
||
|
||
除 hard 门禁外**不得停下发问**；soft 门禁只记录、不阻塞。
|
||
|
||
## 6. staging 段（自动终点）
|
||
|
||
- 合并与部署到 staging 的**真实路径不在本技能里写死**：先读目标项目根目录的 `AGENTS.md`，按其「staging 部署约定」执行（分支 / 构建 / 部署触发 / 环境地址 / 验证入口）。
|
||
- 项目 `AGENTS.md` 没有 staging 约定，或缺部署权限 → 视为 hard 门禁，按 §5 格式停下。
|
||
- **部署成功 ≠ 完成**：必须做冒烟验证——关键页面可达、核心 API 返回正常、主流程走通、日志无新增报错；把命令与结果写入 `evidence[]`（`stage: "staging"`），这一步通过才算**自动终点**。
|
||
- 冒烟失败：先自行修复重试；同类失败连续两次且判断需要人拍板（环境权限、外部系统、方案本身有问题）→ 按 hard 门禁停。
|
||
- 自动终点之后的一切（生产发布、验收、归档）都需要人工授权，不在 continuous 范围内。
|
||
|
||
## 7. 反例
|
||
|
||
| 反例 | 正确做法 |
|
||
| --- | --- |
|
||
| 每个阶段结束都 AskUserQuestion 等确认 | soft 门禁记入 checkpoint 后继续，只在 hard 门禁停 |
|
||
| 没有 evidence 就写「阶段已完成」 | 先跑命令拿到可复核结果，再写 `evidence[]` |
|
||
| 跳过 `/req ci` 直接推进到 review | `/req ci` 是 dev → review 的必跑门禁 |
|
||
| 把 staging 部署命令写死在技能里 | 读目标项目 `AGENTS.md` 的 staging 部署约定 |
|
||
| 把生产发布当成「下一步自动执行」 | 生产发布是 hard 门禁，必须显式授权 |
|
||
| 新会话凭记忆接着干 | 先读 checkpoint 并复核 evidence，再按 `next_command` 继续 |
|
||
| 换 agent 后重跑一遍已通过的阶段 | 证据仍成立就跳过，只补做失败或缺失的阶段 |
|