Files

guoym 43585b8504 move claude-marketplace to ai-proj-helper

2026-03-12 21:42:30 +08:00

19 KiB

Raw Blame History

name, description

name	description
req-commands	需求命令详细参考。当需要查看 /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]`

查看需求当前开发阶段和任务状态。

执行逻辑：

get_requirement(id) → 获取 delivery_stage
get_requirement_tasks(id) → 获取所有关联任务
按 linkRole 分组展示，标注当前阶段任务完成度

输出示例：

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

`/req next [REQ-ID]`

检测当前阶段完成度，推进到下一阶段。

执行逻辑：

获取当前 delivery_stage 和该阶段所有任务
检查任务完成度：
- 全部完成 → 提示「当前阶段已完成，是否推进到 {下一阶段}？」
- 部分未完成 → 显示未完成任务列表 + AskUserQuestion：
  - 选项 A: "强制推进（需说明原因）"
  - 选项 B: "返回完成任务"
  - 用户选 A → 输入跳过原因 → advance_delivery_stage(force=true)
  - 记录到需求历史: POST /requirements/{id}/history，comment 包含跳过原因
- ⚠️ 禁止 AI 自动使用 force=true，必须经过 AskUserQuestion 确认
智能跳阶段检测（推进前）：
- get_requirement_tasks(id) → 收集所有 linkRole
- 如果目标阶段与当前 linkRole 不匹配，主动建议跳过：
  - 无 implementation → 推进到 review/testing 时提示「该需求无代码任务，建议跳过此阶段」
  - 无 code_review → 推进到 review 时提示跳过
  - 无 test → 推进到 testing 时提示跳过
- 通过 AskUserQuestion 确认：「跳过」或「仍然创建任务」
用户确认推进后：
- 更新 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]`

从上次中断的位置恢复工作。会话被截断后的首选命令。

执行逻辑：

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

输出格式：

📋 恢复工作上下文
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
需求: 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 文档。

评审等待机制（强制）：

submit_requirement(id) → status 变为 pending

展示 PRD 要点摘要：

PRD 评审摘要
─────────────────────
标题: {需求标题}
核心方案: {1-2句总结}
验收标准: {N}项
改动范围: {文件列表}

AskUserQuestion: "请确认 PRD 是否通过评审"
- "通过评审" → approve_requirement(id)
- "需要修改" → 回到编辑流程
⚠️ 禁止 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 技能）：

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

执行逻辑：

前置检查（强制）：
- 对每个待部署需求，检查 testing 阶段任务是否有文档附件（has_task_document）
- ✅ 有文档 → 继续
- ⚠️ 无文档 → AskUserQuestion「测试任务 #XXXX 无测试记录文档，确认继续部署？」
收集待部署需求：
- delivery_stage = testing 且所有 test 任务 completed
- 有 implementation 任务（排除纯运维/文档需求）
展示待部署列表 → AskUserQuestion 确认部署范围
创建部署批次任务：
- 标题：【部署】{project} {date} ({N} requirements)
- 对每个选中需求：link_tasks_to_requirement(role=deploy)
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 生产部署（不可跳过）：部署 + 健康检查，失败立即回滚
部署后强制检查点：
- ✅ 部署文档创建（必须）：create-and-attach 到部署任务，包含 Deploy Gates 结果表格
- ☑️ 截图验证（可选）：有 chrome-dev MCP → 执行截图；无 → 记录跳过
部署成功后：
- 所有关联需求 advance_delivery_stage → released
- complete_task(部署任务)

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

`/req done [REQ-ID]`

完成归档。参数：--force 强制归档。

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

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

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

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

`/req regression [--module <name>] [--mode <mode>]`

运行回归测试。系统级持续质量活动。

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

执行逻辑（详见 req-test-gate/regression.md）：

确定范围：
- 指定 module → 直接运行该模块回归套件
- 未指定 → git diff --name-only 获取变更 → 查 module-deps.json → 推断影响域
运行回归套件：
- 执行 regression-suite/suites/ 下对应脚本
- 记录每个用例的 PASS/FAIL 状态
回归判定：
- 对比上次运行结果
- 上次 PASS + 本次 FAIL → 标记为「回归」
结果处理：
- 全部通过 → 展示通过率
- 有回归 → AskUserQuestion「是否为回归项创建 bug 需求？」
- 有新失败 → 展示失败列表，建议排查

报告输出：

回归测试结果 - {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` 执行流程（更新版）

get_requirement(id) → 获取 delivery_stage
get_requirement_tasks(id) → 获取关联任务，收集 linkRole 集合
智能跳阶段检测：检查目标阶段是否与 linkRole 匹配
- 不匹配 → AskUserQuestion「建议跳过 {阶段}，是否同意？」
- 用户同意跳过 → 递归检测下一阶段
- 用户拒绝 → 继续推进到该阶段
门禁检查：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
自动创建阶段任务：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

19 KiB Raw Blame History Unescape Escape

req 命令参考

基础命令

/req 或 /req list

/req new [标题]

/req status [REQ-ID]

阶段管理命令

/req phase [REQ-ID]

/req next [REQ-ID]

会话恢复命令

/req resume [REQ-ID]

评审命令

/req review [REQ-ID]

/req review pass [REQ-ID]

/req review reject [REQ-ID] [原因]

/req review status [REQ-ID]

开发命令

/req dev [REQ-ID]

/req cr [REQ-ID]

/req test [REQ-ID]

/req deploy [--project <name>] [--env <environment>]

/req done [REQ-ID]

/req regression [--module <name>] [--mode <mode>]

辅助命令

/req link [REQ-ID] --task-id [TASK-ID]

/req decompose [REQ-ID]

/req generate-tasks [REQ-ID]

/req priority [REQ-ID] [low|medium|high]

/req stats [REQ-ID|--all]

阶段任务 Checklist 模板

analysis（评审）

design（设计）

dev（开发）

review（代码评审）

testing（测试）

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

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

MCP 工具映射

任务关联类型

19 KiB

Raw Blame History

`/req` 或 `/req list`

`/req new [标题]`

`/req status [REQ-ID]`

`/req phase [REQ-ID]`

`/req next [REQ-ID]`

`/req resume [REQ-ID]`

`/req review [REQ-ID]`

`/req review pass [REQ-ID]`

`/req review reject [REQ-ID] [原因]`

`/req review status [REQ-ID]`

`/req dev [REQ-ID]`

`/req cr [REQ-ID]`

`/req test [REQ-ID]`

`/req deploy [--project <name>] [--env <environment>]`

`/req done [REQ-ID]`

`/req regression [--module <name>] [--mode <mode>]`

`/req link [REQ-ID] --task-id [TASK-ID]`

`/req decompose [REQ-ID]`

`/req generate-tasks [REQ-ID]`

`/req priority [REQ-ID] [low|medium|high]`

`/req stats [REQ-ID|--all]`

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

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