---
name: req-commands
description: 需求命令详细参考。当需要查看 /req 命令的详细用法、参数、示例时使用。
---

# req 命令参考

## 基础命令

### `/req` 或 `/req list`
列出所有需求，按状态分组显示。

### `/req new [标题]`
创建新需求。
- 参数：`--priority=high|medium|low`，`--project=<name>`，`--category=feature|bug|improvement`
- 创建后提示使用 `req-prd` 技能编写 PRD

### `/req status [REQ-ID]`
查看需求详情、进度、关联任务。

## 阶段管理命令

### `/req phase [REQ-ID]`
查看需求当前开发阶段和任务状态。

**执行逻辑**：
1. `get_requirement(id)` → 获取 `delivery_stage`
2. `get_requirement_tasks(id)` → 获取所有关联任务
3. 按 linkRole 分组展示，标注当前阶段任务完成度

**输出示例**：
```
REQ-20260218-0013 | 阶段: dev (开发)
────────────────────────────────────
✅ analysis (评审)
   ✅ #6035 【评审】PRD: 需求全生命周期阶段化管理
   ✅ #6040 【评审】技术设计: 数据模型
▶ dev (开发) ← 当前阶段
   🔄 #6042 【开发-后端】实现阶段管理 API [in_progress]
   ⬜ #6043 【开发-前端】阶段可视化组件 [todo]
⬜ review (代码评审)
   (无任务)
⬜ testing (测试)
   (无任务)
```

### `/req next [REQ-ID]`
检测当前阶段完成度，推进到下一阶段。

**执行逻辑**：
1. 获取当前 `delivery_stage` 和该阶段所有任务
2. 检查任务完成度：
   - 全部完成 → 提示「当前阶段已完成，是否推进到 {下一阶段}？」
   - **部分未完成 → 显示未完成任务列表 + AskUserQuestion**：
     - 选项 A: "强制推进（需说明原因）"
     - 选项 B: "返回完成任务"
     - 用户选 A → 输入跳过原因 → `advance_delivery_stage(force=true)`
     - 记录到需求历史: `POST /requirements/{id}/history`，comment 包含跳过原因
   - **⚠️ 禁止 AI 自动使用 force=true，必须经过 AskUserQuestion 确认**
3. **智能跳阶段检测**（推进前）：
   - `get_requirement_tasks(id)` → 收集所有 linkRole
   - 如果目标阶段与当前 linkRole 不匹配，主动建议跳过：
     - 无 `implementation` → 推进到 review/testing 时提示「该需求无代码任务，建议跳过此阶段」
     - 无 `code_review` → 推进到 review 时提示跳过
     - 无 `test` → 推进到 testing 时提示跳过
   - 通过 AskUserQuestion 确认：「跳过」或「仍然创建任务」
4. 用户确认推进后：
   - 更新 `delivery_stage` 到下一阶段
   - **自动创建**目标阶段的建议任务（`create_stage_task` 批量创建，无需询问）
   - 展示已创建任务列表：「✅ 已创建: #XXXX 【代码评审】CR: {需求标题}。如需撤销请说明」
   - ⚠️ 仅当用户主动要求撤销时才删除已创建任务

**阶段顺序**：
```
analysis → design → dev → review → testing → [待部署池] → released
                                                ↑ /req deploy 批量推进
```

**linkRole 到阶段的映射**：
| linkRole | 所属阶段 |
|----------|----------|
| prd | analysis |
| design | design |
| implementation | dev |
| code_review | review |
| test | testing |
| deploy (staging) | staging |
| deploy (prod) | released |

## 会话恢复命令

### `/req resume [REQ-ID]`
从上次中断的位置恢复工作。**会话被截断后的首选命令**。

**执行逻辑**：
1. 若无 REQ-ID → `list_requirements(status=approved)` 找到最近活跃的需求
2. `get_requirement(id)` → 获取需求基本信息和 `delivery_stage`
3. `get_requirement_tasks(id)` → 获取所有关联任务及状态
4. 汇总展示恢复上下文

**输出格式**：
```
📋 恢复工作上下文
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
需求: REQ-20260218-0016 | 需求全生命周期 AI 开发管理优化
状态: approved | 阶段: dev (开发)

📊 任务进度: 2/4 完成
  ✅ #6051 【开发-后端】实现 advance_delivery_stage MCP 工具
  ✅ #6052 【开发-后端】实现 create_stage_task 组合 MCP 工具
  🔄 #6053 【开发-Skill】req-commands 阶段 checklist 模板化 [in_progress]
  ⬜ #6054 【开发-Skill】会话断点恢复机制 [todo]

▶ 建议操作:
  1. 继续任务 #6053（当前 in_progress）
  2. 执行 /req next 推进阶段
  3. 执行 /req phase 查看完整阶段视图
```

**自动行为**：
- 如果有 `in_progress` 任务，提示继续该任务
- 如果当前阶段所有任务已完成，提示执行 `/req next`
- 如果需求已 `archived`，告知用户无需操作

## 评审命令

### `/req review [REQ-ID]`
提交评审。**前置条件**：必须有 PRD 文档。

**评审等待机制（强制）**：
1. `submit_requirement(id)` → status 变为 pending
2. 展示 PRD 要点摘要：
   ```
   PRD 评审摘要
   ─────────────────────
   标题: {需求标题}
   核心方案: {1-2句总结}
   验收标准: {N}项
   改动范围: {文件列表}
   ```
3. **AskUserQuestion**: "请确认 PRD 是否通过评审"
   - "通过评审" → `approve_requirement(id)`
   - "需要修改" → 回到编辑流程
4. **⚠️ 禁止 AI 自动审批**，必须等待用户明确选择

### `/req review pass [REQ-ID]`
评审通过。支持多人审批。参数：`--comment="审批意见"`

### `/req review reject [REQ-ID] [原因]`
评审驳回。必须提供驳回原因。

### `/req review status [REQ-ID]`
查看审批进度（多人审批时）。

## 开发命令

### `/req dev [REQ-ID]`
启动开发，自动选择优先级最高的 todo 任务并开始计时。
- 参数：`--task=<task-id>` 指定任务
- 优先启动 `implementation` 角色任务
- **自动设置** `delivery_stage = dev`（如尚未设置）

### `/req cr [REQ-ID]`
代码评审。**前置条件**：开发任务完成。
- 显示 Git diff 摘要
- 生成代码评审检查清单
- **自动设置** `delivery_stage = review`

### `/req test [REQ-ID]`
启动测试。**前置条件**：代码评审通过。
- 参数：`--skip-cr --reason="原因"` 跳过代码评审
- **自动设置** `delivery_stage = testing`
- **⭐ 遵循 `req-test-gate` v2 技能的 5 道门禁**

**执行逻辑（5-Gate 流程，详见 `req-test-gate` 技能）**：
1. **Gate 1 前置条件**：CR 已通过 + 开发任务全部完成（不可跳过）
2. **Gate 2 测试执行**：推断需求类型（code/skill/ops），分阶段验证
   - **code 类型四阶段**：
     - **2A 静态验证**：编译 + 单元测试 + 条件前端/iOS 测试
     - **2B 集成验证**：API 端点 + DB 约束 + 错误处理
     - **2C 冒烟测试**：Staging 环境健康检查 + 核心流程（已部署时）
     - **2D 原型符合性**：对比原型 HTML 的结构/字段/交互/状态（有原型时）
   - **skill**: 关键词一致性 + 规则无歧义 + 边界情况（至少 3 项）
   - **ops**: 部署命令可执行 + 健康检查
3. **Gate 3 质量验证**：派遣 test-validator 子代理审查测试质量
   - code 类型：总是触发 | skill 类型：≥5 测试项时触发 | ops 类型：不触发
   - Critical 缺陷必须修复，Important 缺陷需 AskUserQuestion 确认
4. **Gate 4 文档持久化（不可跳过）**：`create-and-attach` 将完整测试报告写入测试任务文档
   - 文档模板见 `req-test-gate` 技能的「最小必填模板」（含 2A-2D 阶段标记）
   - 必须包含：前置条件结果 + 测试执行表格 + 质量验证摘要 + 通过/失败结论
   - 无此文档 → `/req deploy` 前置检查会警告
5. **Gate 5 回归贡献（code 类型）**：检查是否有 linkRole=regression 任务和用例文档
   - v2.0 过渡期为警告级别，不阻塞
   - 提醒补充回归测试用例到回归池

### `/req deploy [--project <name>] [--env <environment>]`
**项目级批量部署**。收集所有待部署需求，一次构建部署。

- **这是项目级动作**，不是单需求操作
- `--project` 默认为当前项目，`--env` 默认为 `staging`
- 参数：`--platform=web|ios|android`
- **⭐ 遵循 `req-test-gate` v2 的 Deploy Gates (DG1-DG6)**

**执行逻辑**：
1. **前置检查（强制）**：
   - 对每个待部署需求，检查 testing 阶段任务是否有文档附件（`has_task_document`）
   - ✅ 有文档 → 继续
   - ⚠️ 无文档 → AskUserQuestion「测试任务 #XXXX 无测试记录文档，确认继续部署？」
2. **收集待部署需求**：
   - `delivery_stage = testing` 且所有 test 任务 completed
   - 有 implementation 任务（排除纯运维/文档需求）
3. **展示待部署列表** → `AskUserQuestion` 确认部署范围
4. **创建部署批次任务**：
   - 标题：`【部署】{project} {date} ({N} requirements)`
   - 对每个选中需求：`link_tasks_to_requirement(role=deploy)`
5. **Deploy Gates (DG1-DG6)**（详见 `req-test-gate/deploy-gates.md`）：
   - **DG1 迁移检查（不可跳过）**：对比 migrations/ vs 数据库，有新 migration 先备份再执行
   - **DG2 Staging 部署**：构建镜像 + 部署到 singapore
   - **DG3 冒烟测试**：健康检查 + 登录 + 新 API 验证
   - **DG4 影响域回归**：根据 module-deps.json 运行对应回归套件（无套件时跳过）
   - **DG5 性能基线（推荐）**：关键 API 响应时间检查
   - **DG6 生产部署（不可跳过）**：部署 + 健康检查，失败立即回滚
6. **部署后强制检查点**：
   - ✅ **部署文档创建**（必须）：`create-and-attach` 到部署任务，包含 Deploy Gates 结果表格
   - ☑️ **截图验证**（可选）：有 chrome-dev MCP → 执行截图；无 → 记录跳过
7. **部署成功后**：
   - 所有关联需求 `advance_delivery_stage → released`
   - `complete_task(部署任务)`

**单需求兼容**：当仅 1 个需求待部署时，流程自动退化为单需求部署。

### `/req done [REQ-ID]`
完成归档。参数：`--force` 强制归档。

**类型化归档门禁（强制）**：

1. `get_requirement_tasks(id)` → 获取所有关联任务
2. **推断需求类型**（从 linkRole 集合判断）：
   - **code**: 有 `implementation` 角色任务 → 代码需求
   - **skill**: 无 `implementation`，有 `prd`/`code_review`/`test` → Skill/文档需求
   - **ops**: 仅 `deploy` 角色任务 → 运维需求
3. **按类型执行检查清单**：

| 检查项 | code | skill | ops |
|--------|------|-------|-----|
| delivery_stage = released | ✅ | - | - |
| delivery_stage >= testing | - | ✅ | - |
| deploy 任务已完成 | ✅ | - | ✅ |
| 部署文档存在 | ✅ | - | - |
| 所有关联任务已完成 | ✅ | ✅ | ✅ |

4. **检查结果处理**：
   - 全部通过 → 展示检查清单 + AskUserQuestion "确认归档？"
   - 有缺失 → 显示缺失项 + AskUserQuestion "是否强制归档？"
   - 用户确认 → 进入步骤 5
5. **Git 提交（强制）**：
   - `git add` 本需求相关变更文件
   - `git commit -m "feat(skill): REQ-XXXX 需求标题"`（或 `fix`/`refactor` 等合适的 type）
   - `git push origin <current-branch>`
   - ⚠️ 提交前确认无敏感文件（.env、credentials 等）
6. `archive_requirement(id)`
7. 归档后生成生命周期总结，触发同步

### `/req regression [--module <name>] [--mode <mode>]`
**运行回归测试**。系统级持续质量活动。

- `--module` 指定模块（okr/task/auth/...），不指定则按影响域推断
- `--mode` 执行模式：`impact`（影响域）| `critical`（关键路径）| `full`（全量）
- 默认模式：`impact`（根据最近变更推断影响域）

**执行逻辑**（详见 `req-test-gate/regression.md`）：
1. **确定范围**：
   - 指定 module → 直接运行该模块回归套件
   - 未指定 → `git diff --name-only` 获取变更 → 查 `module-deps.json` → 推断影响域
2. **运行回归套件**：
   - 执行 `regression-suite/suites/` 下对应脚本
   - 记录每个用例的 PASS/FAIL 状态
3. **回归判定**：
   - 对比上次运行结果
   - 上次 PASS + 本次 FAIL → 标记为「回归」
4. **结果处理**：
   - 全部通过 → 展示通过率
   - 有回归 → AskUserQuestion「是否为回归项创建 bug 需求？」
   - 有新失败 → 展示失败列表，建议排查
5. **报告输出**：
   ```
   回归测试结果 - {module/all}
   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━
   模式: {impact/critical/full}
   套件: {N} 个 | 用例: {M} 个
   ✅ 通过: {P} | ❌ 失败: {F} | 🔴 回归: {R}
   ```

**当前状态**：回归套件待初始化，首次运行会提示建立基线。

## 辅助命令

### `/req link [REQ-ID] --task-id [TASK-ID]`
关联任务到需求。

### `/req decompose [REQ-ID]`
分解需求为任务。**创建时自动加阶段前缀**。

### `/req generate-tasks [REQ-ID]`
根据 PRD 自动生成开发任务。**所有任务带【开发】前缀**。

### `/req priority [REQ-ID] [low|medium|high]`
设置需求优先级。

### `/req stats [REQ-ID|--all]`
查看需求统计信息。

## 阶段任务 Checklist 模板

当 `/req next` 推进到新阶段时，根据目标阶段自动建议创建的任务。使用 `create_stage_task` 组合工具一步完成（创建+关联+可选启动）。

### analysis（评审）
```
☐ 【评审】PRD: {需求标题}          (linkRole: prd)
☐ 【评审】技术设计: {需求标题}      (linkRole: design) [可选]
```

### design（设计）
```
☐ 【设计】技术方案: {需求标题}      (linkRole: design)
☐ 【设计】数据模型设计              (linkRole: design) [可选]
```

### dev（开发）
```
☐ 【开发-后端】{需求标题}           (linkRole: implementation)
☐ 【开发-前端】{需求标题}           (linkRole: implementation) [可选]
☐ 【开发-MCP】{需求标题}            (linkRole: implementation) [可选]
```

### review（代码评审）
```
☐ 【代码评审】{需求标题}            (linkRole: code_review)
```

### testing（测试）
```
☐ 【测试】单元测试: {需求标题}       (linkRole: test)
☐ 【测试】集成测试: {需求标题}       (linkRole: test) [可选]
```

**按需求类型的最低测试标准**：

| 需求类型 | 最低测试要求 |
|----------|-------------|
| **code** | `go test` 或前端测试通过 + API 验证 + 截图验证 |
| **skill** | 关键词跨文件一致性 + 规则无歧义验证 + 边界情况检查（至少 3 项） |
| **ops** | 部署命令可执行 + 健康检查通过 |

**skill 类型测试 checklist**（最低 3 项）：
```
☐ 关键词一致性：grep 验证核心概念在所有相关 skill 文件中对齐
☐ 规则无歧义：每条规则的触发条件和执行动作明确，无二义性
☐ 边界情况：至少验证 1 个边界场景（如混合类型需求的分类）
☐ 交叉引用：文件间的引用（如"见 xxx 技能"）指向正确 [可选]
```

### 部署（项目级，由 `/req deploy` 触发）

部署不再按单需求创建任务，而是通过 `/req deploy` 批量收集待部署需求：
```
testing 完成的需求 → 进入「待部署池」
/req deploy → 创建批次任务：【部署】{project} {date} ({N} requirements)
              关联到所有选中需求 (linkRole: deploy)
              部署成功后批量推进 → released
```

### `/req next` 执行流程（更新版）

1. `get_requirement(id)` → 获取 `delivery_stage`
2. `get_requirement_tasks(id)` → 获取关联任务，收集 linkRole 集合
3. **智能跳阶段检测**：检查目标阶段是否与 linkRole 匹配
   - 不匹配 → AskUserQuestion「建议跳过 {阶段}，是否同意？」
   - 用户同意跳过 → 递归检测下一阶段
   - 用户拒绝 → 继续推进到该阶段
4. **门禁检查**：`advance_delivery_stage(id, nextStage)` 自动检查
   - 通过 → 进入步骤 4.5
   - 未通过 → 显示阻塞任务，AskUserQuestion 确认 force（禁止自动 force）
4.5. **⭐ 内容门禁检查（防空转）**：对关键阶段的已完成任务验证文档附件
   - **适用阶段**: review（CR 报告）、testing（测试结果）、staging（部署文档）
   - **检查逻辑**：
     ```
     对当前阶段的每个 completed 任务:
       has_task_document(taskId) → 有文档？
         ✅ 有 → get_task_document(taskId) → 检查质量:
           - review: ≥500字符 + 含 file:line 代码引用 + 含结论章节
           - testing: 含测试项表格 + 含通过/失败结论 + ≥200字符
                      （详见 req-test-gate 技能 Gate 4 文档质量门禁）
           - staging: 含健康检查结果 + 含镜像/commit 信息
         ❌ 无 → 阻止推进，提示「任务 #XXXX 缺少 {类型} 文档」
     ```
   - **未通过处理**：AskUserQuestion「内容门禁未通过，选择操作」
     - 选项 A: "补充文档后重试"
     - 选项 B: "强制跳过（记录原因）" → 记录跳过原因到需求历史
   - **⚠️ 禁止 AI 自动跳过**，必须经过 AskUserQuestion
5. **自动创建阶段任务**：`create_stage_task` 批量创建目标阶段建议任务
   - 展示已创建列表：「✅ 已创建: #XXXX {任务名}。如需撤销请说明」
   - 用户主动要求撤销时才删除

## MCP 工具映射

| 命令 | MCP 工具 |
|------|----------|
| `/req` | `list_requirements` |
| `/req new` | `create_requirement` |
| `/req phase` | `get_requirement` + `get_requirement_tasks` |
| `/req next` | `advance_delivery_stage` (门禁检查+推进) + `create_stage_task` (创建任务) |
| `/req resume` | `get_requirement` + `get_requirement_tasks` (断点恢复) |
| `/req dev` | `get_requirement` + `get_requirement_tasks` + `start_task_with_timer` |
| `/req cr` | `get_requirement_tasks` + Git diff |
| `/req test` | `req-test-gate` v2 5-Gate 流程: 前置检查 → 类型化测试(2A-2D) → test-validator 子代理 → `create-and-attach` 持久化 → 回归贡献检查 |
| `/req deploy` | 前置检查 + Deploy Gates(DG1-DG6): 迁移→staging→冒烟→回归→性能→生产 + 部署文档 |
| `/req regression` | `git diff` 影响域推断 + 运行回归套件 + 回归判定 + 可选创建 bug 需求 |
| `/req done` | 类型推断 + 检查清单 + `AskUserQuestion` + `archive_requirement`（⚠️ 禁止直接调用 archive） |
| `/req review` | `submit_requirement` |
| `/req review pass` | `approve_requirement` |
| `/req review reject` | `reject_requirement` |
| `/req link` | `link_tasks_to_requirement` |

## 任务关联类型

| link_role | 说明 | 阶段前缀 | 进度权重 |
|-----------|------|----------|----------|
| prd | PRD 文档 | 【评审】 | 0.1 |
| design | 技术设计 | 【评审】 | 0.05 |
| implementation | 开发实现 | 【开发】 | 0.5 |
| code_review | 代码评审 | 【代码评审】 | 0.05 |
| test | 测试验证 | 【测试】 | 0.15 |
| deploy | 部署发布 | 【部署】 | 0.1 |
| regression | 回归用例 | 【回归】 | 0.0 |
| documentation | 文档编写 | 【文档】 | 0.05 |