refactor: 通用技能按类别拆分为独立目录

skills/ → skills-dev(9), skills-req(10), skills-ops(4), skills-integration(8), skills-biz(4), skills-workflow(7) generate-marketplace.py 改为自动扫描所有 skills-* 目录。 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-03-14 11:31:58 +10:30
parent ea266e9cce
commit 712063071c
170 changed files with 341 additions and 346 deletions
--- a/skills-req/req-commands-plugin/skills/SKILL.md
+++ b/skills-req/req-commands-plugin/skills/SKILL.md
@@ -0,0 +1,436 @@
+---
+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 |