Files

T

skill-gate / gate (pull_request) Waiting to run

Details

feat(req): REQ 连续推进（continuous）模式 + checkpoint

- 新增 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 同步

2026-11-01 09:56:32 +08:00

6.9 KiB

Raw Blame History

连续推进（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）。

{
  "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 时）：

先读 checkpoint；没有就重建：ai-proj req get --id <id> + ai-proj req tasks --id <id> 得到真实 delivery_stage 与任务状态，再写 checkpoint。
复核 evidence 是否仍成立：命令能否重跑通过、artifact 是否还在、REQ 阶段是否被人改过。失效的证据视为未完成，重做该阶段，不要沿用。
从 next_command 继续；blockers 里还有 type: "hard" 时按 §5 停下。
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 后重跑一遍已通过的阶段	证据仍成立就跳过，只补做失败或缺失的阶段

6.9 KiB Raw Blame History Unescape Escape