@zhouhao4221/devflow-skills 0.2.0 → 0.3.1

package/plugins/req/skills/test_regression/SKILL.md

@@ -0,0 +1,298 @@
+---
+name: test_regression
+description: |
+  回归测试 - 运行已有自动化测试用例
+---
+
+> **重要**：本命令的测试文件位置、运行命令、代码示例均从项目 CLAUDE.md 的「测试规范」章节读取，不内置任何项目细节。
+
+# 回归测试
+
+运行项目中已存在的自动化测试用例，验证功能正确性。
+
+> 存储路径和缓存同步规则见 [_storage.md](./_storage.md)
+
+## 命令格式
+
+```
+/req:test_regression [选项]
+```
+
+### 选项
+
+| 选项 | 说明 | 示例 |
+|-----|------|------|
+| `--all` | 全量回归（默认） | `/req:test_regression --all` |
+| `--changed` | 仅测试变更相关 | `/req:test_regression --changed` |
+| `--module=<name>` | 指定模块 | `/req:test_regression --module=user` |
+| `--failed` | 仅运行上次失败的 | `/req:test_regression --failed` |
+| `--type=<ut\|api\|e2e>` | 指定测试类型 | `/req:test_regression --type=ut` |
+| `--verbose` | 显示详细输出 | `/req:test_regression --verbose` |
+| `--coverage` | 生成覆盖率报告 | `/req:test_regression --coverage` |
+| `--skip-env` | 跳过环境检查（仅 UT） | `/req:test_regression --type=ut --skip-env` |
+
+---
+
+## 测试环境要求
+
+不同类型的测试需要不同的环境（具体服务和启动命令参考 CLAUDE.md）：
+
+| 测试类型 | 依赖服务 | 后端服务 | 前端服务 |
+|---------|---------|---------|---------|
+| UT | 否 | 否 | 否 |
+| API | 是 | 是 | 否 |
+| E2E | 是 | 是 | 是 |
+
+---
+
+## 执行流程
+
+### 0. 环境准备（API/E2E 需要）
+
+如果测试类型包含 API 或 E2E，先检查并启动测试环境：
+
+```
+检查测试环境...
+
+依赖服务状态：
+<依赖服务 1>    ❌ 未启动
+<依赖服务 2>    ❌ 未启动
+
+按 CLAUDE.md 测试环境配置启动服务...
+<CLAUDE.md中定义的测试环境启动命令>
+
+等待服务就绪...
+<依赖服务 1>  ✅ 就绪
+<依赖服务 2>  ✅ 就绪
+
+启动后端服务...
+<CLAUDE.md中定义的后端启动命令>
+
+等待后端服务...
+<后端服务>  ✅ 就绪
+
+启动前端服务（E2E 需要）...
+<CLAUDE.md中定义的前端启动命令>
+
+等待前端服务...
+<前端服务>  ✅ 就绪
+
+✅ 测试环境准备完成
+```
+
+### 1. 检测项目类型
+
+从 CLAUDE.md 读取项目技术栈和测试框架配置：
+
+```
+检测项目类型...
+
+项目类型：<CLAUDE.md中定义的技术栈>
+测试框架：
+单元测试：<CLAUDE.md中定义的UT框架>
+API 测试：<CLAUDE.md中定义的API测试框架>
+E2E 测试：<CLAUDE.md中定义的E2E框架>
+
+测试目录：
+<CLAUDE.md中定义的UT目录> (N 个文件)
+<CLAUDE.md中定义的API测试目录> (N 个文件)
+<CLAUDE.md中定义的E2E测试目录> (N 个文件)
+```
+
+### 2. 确定测试范围
+
+根据选项确定要执行的测试：
+
+#### 全量模式 (--all)
+执行所有测试文件
+
+#### 变更模式 (--changed)
+```
+检测变更文件...
+
+变更文件：
+<source-file-1>
+<source-file-2>
+<source-file-3>
+
+关联测试：
+<test-file-1>
+<test-file-2>
+<test-file-3>
+```
+
+#### 失败重试模式 (--failed)
+从上次测试结果中读取失败用例
+
+### 3. 执行测试
+
+按类型依次执行：
+
+```
+执行回归测试...
+
+
+单元测试 (<CLAUDE.md中的UT运行命令>)
+
+
+<test-file-1>
+<TestCase_1>           ✅ PASS
+<TestCase_2>           ✅ PASS
+<TestCase_3>           ✅ PASS
+<TestCase_4>           ✅ PASS
+
+<test-file-2>
+<TestCase_5>           ✅ PASS
+<TestCase_6>           ❌ FAIL
+  Expected: <预期值>
+  Actual:   <实际值>
+<TestCase_7>           ✅ PASS
+
+单元测试结果：N/N 通过
+
+
+API 测试 (<CLAUDE.md中的API测试运行命令>)
+
+
+<api-test-file-1>
+<HTTP_METHOD> <endpoint-1>    ✅ PASS
+<HTTP_METHOD> <endpoint-2>    ✅ PASS
+<HTTP_METHOD> <endpoint-3>    ❌ FAIL
+    Expected: 200
+    Actual:   500 (Internal Server Error)
+
+API 测试结果：N/N 通过
+```
+
+### 4. 生成测试报告
+
+```
+
+回归测试报告
+
+
+测试时间：<timestamp>
+测试范围：<全量回归 | 变更相关 | 失败重试>
+总耗时：<duration>
+
+
+类型     总数   通过   失败   通过率  
+
+单元测试 N      N      N      XX.X%   
+API 测试 N      N      N      XX.X%   
+E2E 测试 N      N      N      XX.X%   
+
+合计     N      N      N      XX.X%   
+
+
+❌ 失败用例（N 个）：
+
+1. <失败用例名>
+   文件：<test-file>:<line>
+   原因：<失败原因描述>
+
+2. <失败用例名>
+   文件：<test-file>:<line>
+   原因：<失败原因描述>
+
+下一步操作：
+- 修复后重新测试：/req:test_regression --failed
+- 查看失败详情：/req:test_regression --verbose
+- 忽略失败继续：/req:test --force
+```
+
+### 5. 覆盖率报告（--coverage）
+
+```
+代码覆盖率报告
+
+
+模块/目录                    覆盖率   状态     
+
+<module-1>                  XX.X%    ✅ 达标   
+<module-2>                  XX.X%    ⚠️ 接近   
+<module-3>                  XX.X%    ❌ 不足   
+<module-4>                  XX.X%    ✅ 达标   
+
+总计                        XX.X%    <状态>    
+
+
+目标覆盖率：<CLAUDE.md中定义的覆盖率目标>
+建议补充测试：<覆盖率不足的模块>
+```
+
+---
+
+## 测试框架配置
+
+所有测试运行命令、目录结构、框架配置均从项目 CLAUDE.md 的「测试规范」章节读取，包括：
+
+### 单元测试 (UT)
+
+```bash
+# 运行所有单元测试
+<CLAUDE.md中的UT运行命令>
+
+# 带覆盖率
+<CLAUDE.md中的UT覆盖率命令>
+
+# 指定模块
+<CLAUDE.md中的UT运行命令> <module-path>
+
+# 仅失败重试
+<CLAUDE.md中的UT运行命令> <failed-test-filter>
+```
+
+### API 测试
+
+```bash
+# 前提：确保测试环境已启动（参考 CLAUDE.md 测试环境配置）
+
+# 运行 API 测试
+<CLAUDE.md中的API测试运行命令>
+
+# 带详细输出
+<CLAUDE.md中的API测试运行命令> --verbose
+
+# 指定接口
+<CLAUDE.md中的API测试运行命令> <test-filter>
+```
+
+### E2E 测试
+
+```bash
+# 前提：确保测试环境已启动（参考 CLAUDE.md 测试环境配置，包括前端服务）
+
+# 运行所有 E2E 测试
+<CLAUDE.md中的E2E运行命令>
+
+# 带 UI 调试
+<CLAUDE.md中的E2E运行命令> --ui
+
+# 仅失败重试
+<CLAUDE.md中的E2E运行命令> --last-failed
+
+# 指定测试文件
+<CLAUDE.md中的E2E运行命令> <test-file>
+```
+
+---
+
+## 与 CI/CD 集成
+
+回归测试结果可输出为 CI 友好格式：
+
+```bash
+/req:test_regression --ci --output=junit.xml
+```
+
+生成的报告可用于：
+- GitHub Actions
+- GitLab CI
+- Jenkins
+
+---
+
+## 用户输入
+
+$ARGUMENTS

package/plugins/req/skills/update/SKILL.md

@@ -0,0 +1,131 @@
+---
+name: update
+description: |
+  热更新插件 - 拉取最新命令文件和技能，所有项目立即生效
+---
+
+# 热更新 req 插件
+
+拉取最新版本，所有使用该插件的项目立即生效（无需重装）。
+
+`--check`：只检查是否有更新，不执行拉取。
+
+## 执行流程
+
+### 1. 定位插件目录
+
+**优先级**：本地目录源 > Claude 缓存克隆目录
+
+```bash
+# 1a. 查找 directory 类型源（本地开发安装）
+SOURCE_PATH=$(jq -r '
+  .extraKnownMarketplaces | to_entries[] |
+  select(.value.source.source == "directory") |
+  .value.source.path
+' ~/.claude/settings.json .claude/settings.local.json 2>/dev/null | head -1)
+
+# 1b. 查找 Claude 缓存的克隆目录（GitHub/远程源安装）
+if [ -z "$SOURCE_PATH" ]; then
+    # Claude Code 将远程 marketplace 克隆到 ~/.claude/plugins/marketplaces/<name>/
+    # 从 settings 取 marketplace 名称，映射到缓存目录
+    MARKETPLACE_NAME=$(jq -r '
+      .extraKnownMarketplaces | to_entries[] |
+      select(.value.source.source != "directory") |
+      .key
+    ' ~/.claude/settings.json .claude/settings.local.json 2>/dev/null | head -1)
+
+    if [ -n "$MARKETPLACE_NAME" ]; then
+        CACHE_PATH="$HOME/.claude/plugins/marketplaces/$MARKETPLACE_NAME"
+        if [ -d "$CACHE_PATH/.git" ]; then
+            SOURCE_PATH="$CACHE_PATH"
+        fi
+    fi
+fi
+```
+
+找不到时输出：
+```
+❌ 无法定位插件目录。
+   请检查 ~/.claude/settings.json 中的 extraKnownMarketplaces 配置。
+```
+
+退出。
+
+### 2. 检查远程更新
+
+```bash
+git -C "$SOURCE_PATH" fetch origin --quiet
+
+LOCAL=$(git -C "$SOURCE_PATH" rev-parse HEAD)
+REMOTE=$(git -C "$SOURCE_PATH" rev-parse "@{u}" 2>/dev/null)
+CURRENT_VER=$(jq -r '.version // "unknown"' "$SOURCE_PATH/plugins/req/.claude-plugin/plugin.json" 2>/dev/null)
+```
+
+已是最新时：
+```
+✅ 已是最新版本（v<CURRENT_VER>）
+   源目录：<SOURCE_PATH>
+```
+
+有更新时打印待拉取的提交列表：
+```
+发现更新（当前 v<CURRENT_VER>）：
+  <git log HEAD..@{u} --oneline --no-merges 的输出>
+```
+
+**`--check` 模式**：到此退出，不执行拉取。
+
+### 3. 执行拉取
+
+```bash
+git -C "$SOURCE_PATH" pull --ff-only origin
+NEW_VER=$(jq -r '.version // "unknown"' "$SOURCE_PATH/plugins/req/.claude-plugin/plugin.json" 2>/dev/null)
+```
+
+成功：
+```
+✅ 插件已更新至 v<NEW_VER>
+   源目录：<SOURCE_PATH>
+   所有使用此插件的项目立即生效，无需重启。
+```
+
+失败（本地有分歧提交）：
+```
+❌ 拉取失败：源目录存在本地修改或分歧提交。
+   请手动处理：cd <SOURCE_PATH> && git status
+```
+
+### 4. 检查项目 prompt 文件
+
+**触发条件**：当前目录存在 `docs/prompt/`（说明项目已创建架构文档）。`--check` 模式同样执行此步骤。
+
+读取 `$SOURCE_PATH/plugins/req/schemas/prompt-schema.md`，对 schema 中每个文件逐项检查：
+
+1. 文件是否存在
+2. 文件存在时，必需关键词是否在标题或正文中出现
+
+按结果分级输出：
+
+```
+Prompt 文件检查（schema v<VERSION>）：
+
+  docs/prompt/architecture.md
+    ✅ 技术栈      ✅ 分层      ✅ 目录      ❌ 命名规范（必需，/req:dev 依赖）
+    ⚠️  错误处理（推荐，/req:dev 可能生成不一致的错误返回）
+
+  docs/prompt/testing.md
+    ⚠️  文件不存在（可选，/req:test 将使用内置默认值）
+
+建议：补充 1 个必需章节，详见 plugins/req/schemas/prompt-schema.md
+```
+
+全部覆盖时：
+```
+✅ Prompt 文件结构完整
+```
+
+`docs/prompt/` 不存在时跳过，不输出任何内容（项目尚未初始化架构文档，属正常状态）。
+
+## 用户输入
+
+$ARGUMENTS

package/plugins/req/skills/update-template/SKILL.md

@@ -0,0 +1,203 @@
+---
+name: update-template
+description: |
+  更新模板 - 将插件最新模板同步到项目本地
+---
+
+# 更新模板文件
+
+将插件 `templates/` 目录下的最新模板同步到项目本地 `docs/requirements/`，覆盖旧版本。
+
+> 存储路径规则见 [_storage.md](./_storage.md)
+
+## 命令格式
+
+```
+/req:update-template [模板名称] [--force]
+```
+
+**示例：**
+- `/req:update-template` - 交互选择要更新的模板
+- `/req:update-template requirement` - 更新需求模板
+- `/req:update-template all` - 更新所有模板
+- `/req:update-template requirement --force` - 强制覆盖，跳过对比确认
+
+---
+
+## 可更新的模板
+
+| 模板名称 | 插件源文件（相对插件根目录） | 项目目标文件 |
+|---------|--------------------------|------------|
+| `requirement` | `templates/requirement-template.md` | `docs/requirements/templates/requirement-template.md` |
+| `quick` | `templates/quick-template.md` | `docs/requirements/templates/quick-template.md` |
+| `module` | `templates/module-template.md` | `docs/requirements/templates/module-template.md` |
+| `prd` | `templates/prd-template.md` | `docs/requirements/templates/prd-template.md` |
+| `release-prompt` | `templates/release-prompt-template.md` | `docs/prompt/release.md` |
+| `all` | 以上全部 | 以上全部 |
+
+---
+
+## 执行流程
+
+### 1. 定位插件根目录
+
+本命令文件位于插件的 `commands/` 目录下。通过本文件自身路径向上一级即可得到插件根目录：
+
+```
+本文件路径: <插件根目录>/commands/update-template.md
+插件根目录: 本文件所在目录的父目录
+模板目录:   <插件根目录>/templates/
+```
+
+**定位方式**：读取 `.claude/settings.local.json` 中的 `extraKnownMarketplaces` 配置，或通过当前项目的 `.claude/settings.local.json` 找到插件注册信息。如果找不到，使用以下回退策略：
+
+```
+1. 读取 ~/.claude/settings.json 的 extraKnownMarketplaces 字段
+2. 找到 name 包含 "req" 的插件条目
+3. 提取 source.path 作为插件根目录
+4. 若以上均失败，提示用户手动指定插件路径
+```
+
+**重要**：必须先确认插件根目录存在 `templates/` 子目录，且目标模板文件存在，再继续后续步骤。
+
+### 2. 前置检查
+
+```bash
+# 检查本地存储目录是否存在
+LOCAL_ROOT=docs/requirements
+if [ ! -d "$LOCAL_ROOT" ]; then
+    echo "本地需求目录不存在，请先执行 /req:init <project-name>"
+    exit 1
+fi
+
+# 检查仓库角色
+ROLE=$(cat .claude/settings.local.json 2>/dev/null | jq -r '.requirementRole // "primary"')
+if [ "$ROLE" = "readonly" ]; then
+    echo "只读仓库不支持更新模板"
+    exit 1
+fi
+```
+
+### 3. 选择模板
+
+如果未指定模板名称，交互选择：
+
+```
+请选择要更新的模板：
+
+1. requirement - 需求模板 (requirement-template.md)
+2. quick       - 快速修复模板 (quick-template.md)
+3. module      - 模块模板 (module-template.md)
+4. prd         - PRD 模板 (prd-template.md)
+a. all         - 更新全部模板
+
+请输入编号或名称:
+```
+
+### 4. 读取插件模板并对比
+
+对每个待更新的模板：
+
+1. **读取插件源模板**：使用 Read 工具读取 `<插件根目录>/templates/<模板文件>`
+2. **读取项目本地模板**：使用 Read 工具读取 `docs/requirements/<目标文件>`（如存在）
+3. **对比内容**
+
+**情况 A：本地文件不存在**
+```
+模板 requirement:
+  插件版本: <插件根目录>/templates/requirement-template.md
+  本地文件: 不存在（将新建）
+```
+
+**情况 B：内容相同**
+```
+模板 requirement: 已是最新，无需更新
+```
+
+**情况 C：内容不同**
+
+展示主要差异摘要（不展示完整 diff，而是结构化对比）：
+
+```
+模板 requirement:
+  插件版本: <插件根目录>/templates/requirement-template.md
+  本地文件: docs/requirements/templates/requirement-template.md
+
+差异摘要:
+  - 插件版本新增章节: "十三、非功能需求"
+  - 插件版本修改章节: "五、接口需求"（表格结构调整）
+  - 本地独有内容: "五、数据模型" 中有自定义字段
+
+更新将覆盖本地文件，本地自定义内容将丢失
+```
+
+**--force 模式**：跳过对比确认，直接覆盖。
+
+### 5. 执行更新
+
+使用 Write 工具将插件模板内容写入项目本地文件：
+
+| 模板名称 | 读取（Read） | 写入（Write） |
+|---------|-------------|-------------|
+| `requirement` | `<插件根目录>/templates/requirement-template.md` | `docs/requirements/templates/requirement-template.md` |
+| `quick` | `<插件根目录>/templates/quick-template.md` | `docs/requirements/templates/quick-template.md` |
+| `module` | `<插件根目录>/templates/module-template.md` | `docs/requirements/templates/module-template.md` |
+| `prd` | `<插件根目录>/templates/prd-template.md` | `docs/requirements/templates/prd-template.md` |
+
+**注意**：PRD 模板更新时保留原始模板变量（`{{PROJECT_NAME}}`、`{{DATE}}`），不做变量替换。已有的 `PRD.md` 是项目文档，不会被覆盖。PRD 模板更新到 `prd-template.md`，仅影响后续新建项目时使用。
+
+### 6. 同步到全局缓存
+
+更新后自动同步模板到全局缓存：
+
+```bash
+PROJECT=$(cat .claude/settings.local.json 2>/dev/null | jq -r '.requirementProject // empty')
+if [ -n "$PROJECT" ]; then
+    CACHE_ROOT=~/.claude-requirements/projects/$PROJECT
+    mkdir -p $CACHE_ROOT/templates
+    cp $LOCAL_ROOT/templates/*.md $CACHE_ROOT/templates/ 2>/dev/null
+fi
+```
+
+### 7. 输出结果
+
+**单个模板更新：**
+```
+已更新模板: requirement
+  源文件: <插件根目录>/templates/requirement-template.md
+  目标: docs/requirements/templates/requirement-template.md
+  缓存同步: 已完成
+
+新创建的需求将使用更新后的模板。已有需求文档不受影响。
+```
+
+**批量更新（all）：**
+```
+模板更新结果:
+
+  requirement  已更新
+  quick        已更新
+  module       已是最新
+  prd          已更新
+
+共更新 3 个模板，1 个无需更新。
+新创建的需求将使用更新后的模板。已有需求文档不受影响。
+```
+
+---
+
+## 错误处理
+
+| 错误场景 | 处理方式 |
+|---------|---------|
+| 插件根目录无法定位 | 提示：无法定位插件目录，请检查 `~/.claude/settings.json` 中的 `extraKnownMarketplaces` 配置 |
+| 插件 templates/ 目录不存在 | 提示：插件模板目录不存在，插件安装可能不完整 |
+| 本地需求目录不存在 | 提示先执行 `/req:init` |
+| 只读仓库 | 提示只读仓库不支持更新模板 |
+| 用户取消 | 提示已取消，不做任何修改 |
+
+---
+
+## 用户输入
+
+$ARGUMENTS