@zhouhao4221/devflow-skills 0.2.0 → 0.3.1

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

@@ -0,0 +1,178 @@
+---
+name: upgrade
+description: |
+  升级需求 - 将快速修复升级为正式需求
+---
+
+# 升级快速修复为正式需求
+
+将 QUICK 快速修复升级为 REQ 正式需求，适用于范围扩大或需要完整评审的场景。
+
+## 命令格式
+
+```
+/req:upgrade <QUICK-XXX>
+```
+
+---
+
+## 执行流程
+
+### 0. 解析存储路径
+
+从 `settings.local.json` 读取 `requirementProject`，确定本地路径（`docs/requirements/active|completed`）和全局缓存路径。
+
+### 1. 定位源文件
+
+优先在本地 active/ 查找 `QUICK-XXX-*.md`，不存在时查缓存；两处都找不到则报错退出。
+
+**状态检查**：
+- 已完成的 QUICK 不允许升级（已归档）
+- 仅允许升级 active/ 目录中的需求
+
+### 2. 读取源文件内容
+
+解析 QUICK 需求的关键信息：
+
+读取并解析 QUICK 需求文档，提取：
+- 编号、标题
+- 改动类型、端类型
+- 当前状态
+- 问题描述（现象、期望）
+- 实现方案（涉及文件）
+- 验证方式
+
+### 3. 生成新编号
+
+格式：`REQ-XXX`（三位数字）。扫描本地和缓存中已有的最大 REQ 编号，取两者较大值 +1。
+
+### 4. 内容转换
+
+#### 4.1 元信息转换
+
+| QUICK 字段 | REQ 字段 | 转换规则 |
+|-----------|---------|---------|
+| 编号 QUICK-XXX | 编号 REQ-XXX | 新生成的编号 |
+| 改动类型 | 类型 | bug修复→后端, 小功能→后端 |
+| 端类型 | 类型 | 后端/前端/全栈 直接映射 |
+| 状态 | 状态 | 见状态映射表 |
+| 模块 | 模块 | 直接复制 |
+| 关联需求 | 关联需求 | 直接复制，新增「升级自 QUICK-XXX」 |
+
+**状态映射**：
+
+| QUICK 状态 | REQ 状态 |
+|-----------|---------|
+| 草稿 | 草稿 |
+| 方案确认 | 评审通过 |
+| 开发中 | 开发中 |
+| 已完成 | ❌ 不允许升级 |
+
+#### 4.2 生命周期转换
+
+从 4 阶段扩展为 6 阶段：
+
+```markdown
+## 生命周期
+
+- [x] 草稿（编写中）      ← 根据状态勾选
+- [ ] 待评审
+- [ ] ✅ 评审通过
+- [ ] 开发中
+- [ ] 测试中
+- [ ] 已完成
+```
+
+#### 4.3 内容章节转换
+
+| QUICK 章节 | REQ 章节 | 转换方式 |
+|-----------|---------|---------|
+| 问题描述.现象 | 需求描述.背景 | 直接复制 |
+| 问题描述.期望 | 需求描述.目标 | 直接复制 |
+| - | 需求描述.价值 | **待补充** |
+| 实现方案.涉及文件 | 文件改动清单 | 按分层重组 |
+| 验证方式 | 测试要点 | 直接复制 |
+| - | 功能清单 | **待补充** |
+| - | 业务规则 | **待补充** |
+| - | 接口需求 | **待补充**（如涉及） |
+| - | 数据模型 | **待补充**（如涉及） |
+| - | 实现步骤 | **待补充** |
+
+### 5. 显示转换预览
+
+```
+升级预览：QUICK-001 → REQ-007
+
+原快速修复：
+  编号：QUICK-001
+  标题：修复用户登录失败问题
+  状态：开发中
+  改动：3 个文件
+
+新正式需求：
+  编号：REQ-007
+  标题：修复用户登录失败问题
+  类型：后端
+  状态：开发中（保持）
+
+需补充的章节：
+  - 需求描述.价值
+  - 功能清单
+  - 业务规则
+  - 实现步骤
+
+原文件处理：
+  [ ] 归档到 completed/（保留历史）
+  [ ] 直接删除（减少冗余）
+
+```
+
+### 6. 用户确认后执行
+
+#### 6.1 创建新 REQ 文件
+
+使用 requirement-template.md 模板，填充转换后的内容，写入 `docs/requirements/active/<NEW_REQ_ID>-<title>.md`。
+
+#### 6.2 处理原 QUICK 文件
+
+**归档**：在原文件末尾追加升级标记（含日期和新编号），移动到 completed/。
+**删除**：直接删除源文件。
+
+#### 6.3 同步缓存
+
+将新 REQ 文件复制到缓存 active/，按用户选择同步处理缓存中的 QUICK 文件（归档或删除）。
+
+### 7. 触发需求完善
+
+升级完成后，触发 requirement-analyzer 技能补充待填章节：
+
+```
+✅ 升级成功！
+
+新需求：REQ-007 修复用户登录失败问题
+文件：docs/requirements/active/REQ-007-修复用户登录失败问题.md
+状态：开发中
+
+需要补充以下章节：
+1. 需求描述.价值
+2. 功能清单
+3. 业务规则
+4. 实现步骤
+
+```
+
+调用 requirement-analyzer 技能引导完善各章节。
+
+---
+
+## 限制条件
+
+1. **仅限 active/ 目录**：已完成（completed/）的 QUICK 不能升级
+2. **状态限制**：「已完成」状态的 QUICK 不允许升级
+3. **编号唯一性**：生成的 REQ 编号必须唯一
+
+---
+
+## 用户输入
+
+$ARGUMENTS

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

@@ -0,0 +1,158 @@
+---
+name: use
+description: |
+  切换需求项目 - 将当前仓库绑定到不同的项目
+---
+
+# 切换需求项目
+
+将当前仓库绑定到另一个已存在的需求项目。
+
+## 命令格式
+
+```
+/req:use <project-name>
+```
+
+## 参数
+
+- `project-name`: 要切换到的项目名称
+
+---
+
+## 执行流程
+
+### 1. 解析参数
+
+```
+目标项目: $ARGUMENTS
+全局缓存路径: ~/.claude-requirements
+```
+
+### 2. 检查目标项目是否存在
+
+检查 `~/.claude-requirements/projects/<project-name>/` 是否存在。
+
+**如果项目不存在**：
+- 列出所有可用项目
+- 提示使用 `/req:init` 创建新项目
+
+### 3. 读取当前绑定
+
+检查当前仓库的 `.claude/settings.json`：
+
+```json
+{
+  "requirementProject": "old-project"
+}
+```
+
+### 4. 更新仓库绑定
+
+> 写入规范见 [_storage.md](./_storage.md#settings-文件写入规范)。
+
+读取已有 `.claude/settings.json`，合并以下字段后写回（不覆盖已有的 `branchStrategy` 等字段）：
+
+```json
+{
+  "requirementProject": "<project-name>",
+  "requirementRole": "readonly"
+}
+```
+
+> `/req:use` 绑定的仓库默认为 `readonly` 角色，仅从缓存读取需求。如需升级为主仓库，使用 `/req:init <project-name>` 初始化本地存储。
+
+### 5. 更新全局索引
+
+更新 `~/.claude-requirements/index.json`：
+- 从旧项目的 repos 列表移除当前仓库
+- 添加到新项目的 repos 列表
+
+### 6. 项目配置检查
+
+绑定完成后检查当前仓库的配置完整性。
+
+#### 6.1 CLAUDE.md 架构检查
+
+检查 CLAUDE.md 是否包含以下关键词之一：`分层架构`、`目录结构`、`技术栈`、`项目架构`、`Architecture`、`Tech Stack`、`Project Structure`。
+
+**缺失时引导**（与 `/req:init` 步骤 8 相同）：
+
+```
+⚠️ CLAUDE.md 中未检测到项目架构描述
+
+   /req:dev 需要架构信息来生成实现方案
+
+   选择项目类型，生成 CLAUDE.md 建议片段：
+
+   1. Go 后端（Gin + GORM 分层架构）
+   2. Java 后端（Spring Boot 分层架构）
+   3. 前端项目（React/Vue + TypeScript）
+   4. 自定义（生成空白模板，手动填写）
+   5. 跳过（稍后手动添加）
+
+请选择（1-5）：
+```
+
+选择后读取 `<plugin-path>/templates/claude-md-snippets/` 对应模板，追加到 CLAUDE.md。
+
+#### 6.2 分支策略检查
+
+读取 `settings.json` 中的 `branchStrategy` 字段。
+
+**未配置时提示**（不阻断）：
+
+```
+未配置分支策略，/req:dev 将使用默认行为
+   建议执行 /req:branch init 配置分支策略
+```
+
+### 7. 输出结果
+
+```
+✅ 已切换到项目 "<project-name>"
+
+项目状态:
+   - 活跃需求: X 个
+   - 已完成: Y 个
+
+活跃需求列表:
+   | 编号 | 标题 | 状态 |
+   |------|------|------|
+   | REQ-001 | ... | 开发中 |
+   | REQ-002 | ... | 待评审 |
+
+使用 /req 查看完整列表
+```
+
+---
+
+## 无参数模式
+
+当不带参数执行 `/req:use` 时：
+
+### 显示当前绑定
+
+```
+当前项目: <project-name>
+路径: ~/.claude-requirements/projects/<project-name>/
+
+可用命令:
+   - /req:use <project-name>  切换到其他项目
+   - /req:projects            查看所有项目
+```
+
+---
+
+## 错误处理
+
+| 错误场景 | 处理方式 |
+|---------|---------|
+| 项目不存在 | 列出可用项目，提示使用 `/req:init` 创建 |
+| 全局缓存未初始化 | 提示先运行 `/req:init <project-name>` |
+
+---
+
+## 用户输入
+
+$ARGUMENTS

package/plugins/req/skills/version-bumper/SKILL.md

@@ -0,0 +1,113 @@
+---
+name: version-bumper
+description: |
+  版本号管理助手。仅在执行 /req:release 命令时触发。
+  自动检测各插件变更范围，按 semver 规则推导并更新插件版本号和整体版本号。
+---
+
+# 版本号管理助手
+
+仅在 `/req:release` 命令执行时触发，负责在发版前更新 devflow 各插件版本号。
+
+## 触发条件
+
+仅在 `/req:release` 执行时触发，在 release 流程的步骤 2（确定版本号）之后、步骤 9（生成 changelog）之前执行。
+
+## 版本文件
+
+| 文件 | 字段 | 当前含义 |
+|------|------|---------|
+| `.claude-plugin/marketplace.json` | `metadata.version` | 整体发布版本，与 git tag 保持一致 |
+| `plugins/req/.claude-plugin/plugin.json` | `version` | req 插件独立版本 |
+| `plugins/pm/.claude-plugin/plugin.json` | `version` | pm 插件独立版本 |
+| `plugins/api/.claude-plugin/plugin.json` | `version` | api 插件独立版本 |
+| `plugins/diag/.claude-plugin/plugin.json` | `version` | diag 插件独立版本 |
+
+---
+
+## 工作流程
+
+### 1. 读取当前版本
+
+用 Read 工具读取所有版本文件，记录各插件当前版本号。
+
+### 2. 检测各插件变更文件
+
+```bash
+git diff --name-only <FROM_REF>..HEAD
+```
+
+`FROM_REF` 与 release 步骤 2 中一致（平台最新 Release 的 tag，无则最新 git tag，无则仓库首次 commit）。
+
+按文件路径前缀归属插件：
+
+| 路径前缀 | 归属插件 |
+|---------|---------|
+| `plugins/req/` | req |
+| `plugins/pm/` | pm |
+| `plugins/api/` | api |
+| `plugins/diag/` | diag |
+| 其他（根目录、docs/、.claude/ 等） | 仅影响 marketplace 整体版本 |
+
+### 3. 推导各插件 bump 等级
+
+对每个有变更的插件，分析其目录下的 commit 信息：
+
+```bash
+git log <FROM_REF>..HEAD --pretty=format:"%s" -- plugins/<name>/
+```
+
+按最高优先级确定该插件的 bump 等级：
+
+| commit 特征 | bump 等级 |
+|------------|---------|
+| `!:` 或 `BREAKING CHANGE` | major |
+| `feat:` / `新功能:` | minor |
+| `fix:` / `perf:` / `refactor:` / `修复:` / `优化:` / `重构:` | patch |
+| `docs:` / `chore:` / `ci:` / `test:` / `build:` | 不 bump（插件功能无变化） |
+
+无变更或仅 docs/chore 的插件：保持版本号不变。
+
+### 4. 更新 marketplace 整体版本
+
+`marketplace.json` 的 `metadata.version` 直接设为 release 步骤 2 推导出的版本号（去掉 `v` 前缀）。
+
+示例：release tag `v2.27.0` → `metadata.version` = `"2.27.0"`
+
+### 5. 展示版本变更预览
+
+```
+版本更新预览：
+
+  marketplace.json:  2.26.0 → 2.27.0  (与 tag v2.27.0 同步)
+
+  req:   3.18.0 → 3.19.0  (minor - 新增命令)
+  pm:    0.2.0  → 0.2.0   (无变更)
+  api:   0.3.0  → 0.3.1   (patch - 修复解析)
+  diag:  0.1.0  → 0.1.0   (无变更)
+```
+
+### 6. 更新版本文件
+
+用 Edit 工具更新各 JSON 文件中的 `version`（或 `metadata.version`）字段。仅更新有变更的插件和 marketplace.json。
+
+### 7. 暂存版本文件
+
+```bash
+git add .claude-plugin/marketplace.json plugins/req/.claude-plugin/plugin.json \
+        plugins/pm/.claude-plugin/plugin.json plugins/api/.claude-plugin/plugin.json \
+        plugins/diag/.claude-plugin/plugin.json
+```
+
+版本文件的修改会在 release 步骤 10 的统一 commit 中一起提交（`chore(release): prepare <version>`），**不单独提交**。
+
+---
+
+## 边界情况
+
+| 场景 | 处理 |
+|------|------|
+| 版本号已与 tag 一致 | 跳过该文件，不重复写入 |
+| 插件仅有 docs/chore 变更 | 插件版本不 bump，仅更新 marketplace |
+| 无任何 Release 也无 git tag（首次发版） | FROM_REF 取仓库首次 commit，视所有 commit 为新增，各插件 minor bump |
+| 版本号格式不符合 X.Y.Z | 打印警告并跳过该插件的 bump，不阻塞发版 |

package/plugins/uat/skills/bug/SKILL.md

@@ -0,0 +1,153 @@
+---
+name: bug
+description: |
+  上报测试失败项 - 将失败场景创建为 Gitea issue
+---
+
+# 上报测试 Bug
+
+> **Audience:** QA
+
+将最近一次测试的失败场景上报为 Gitea issue。
+
+## 命令格式
+
+```
+/uat:bug [module]
+```
+
+---
+
+## 执行流程
+
+### 1. 读取配置
+
+从 `settings.local.json` 读取：
+- `branchStrategy.repoType`：仓库类型（github / gitea）
+- `branchStrategy.giteaUrl`：Gitea 地址（gitea 时必填）
+- `branchStrategy.giteaToken`：Gitea token（gitea 时必填）
+
+### 2. 找到最新报告
+
+扫描 `docs/uat/reports/` 找最新报告文件，提取所有 `❌ FAIL` 场景。
+
+若无失败项：
+```
+✅ 最近一次测试全部通过，无需上报
+```
+
+若无报告文件：
+```
+❌ 未找到测试报告，请先执行 /uat:run
+```
+
+### 3. 展示候选列表并询问
+
+```
+发现 3 个需上报场景：
+
+❌ 失败（2 个）：
+  1. S02 密码错误提示
+     原因：表单未显示错误信息
+
+  2. S05 退出登录后跳转
+     原因：未跳转到登录页
+
+⚠️  Console Error（1 个，功能表现正常但有 JS 异常）：
+  3. S03 新增客户
+     TypeError: Cannot read properties of undefined (reading 'id')
+
+是否上报？(y/n/选择编号如 1,2,3)
+```
+
+用户可选择全部上报、部分上报或取消。
+
+### 4. 上报 issue
+
+**前置检查**（gitea 仓库）：
+- `giteaUrl` 和 `giteaToken` 非空，否则提示：
+  ```
+  ❌ 未配置 giteaUrl / giteaToken
+  在 settings.local.json 中配置后重试
+  ```
+
+**CLI 优先**（与 req 插件保持一致）：
+- GitHub：`gh issue create`
+- Gitea：优先 `tea issue create`，不可用时回退 `curl + giteaToken`
+
+**上报范围**：`❌ FAIL` 和 `⚠️ PASS（有 console error）` 的场景都纳入上报候选，在步骤 3 展示时分组标注。
+
+**issue 正文**：
+
+```
+## 测试场景
+- 模块：<module>
+- 场景：S0N <场景名称>
+- 测试日期：YYYY-MM-DD
+- 结果：❌ FAIL / ⚠️ PASS（有 console error）
+
+## 失败步骤
+<失败步骤描述，⚠️ PASS 时填「步骤均通过，但有 console error」>
+
+## 预期结果
+<预期断言>
+
+## 实际结果
+<失败原因，⚠️ PASS 时填「功能表现正常，但 console 有以下报错」>
+
+## Console Errors
+<本场景捕获的 console error，无则省略此节>
+
+---
+由 /uat:bug 自动生成
+```
+
+> 截图不写在正文里，创建 issue 后单独上传（见步骤 5）。
+
+### 5. 上传截图附件
+
+issue 创建成功后，检查该场景是否有对应截图（`docs/uat/screenshots/` 下匹配场景 ID 的文件）。有则上传，无则跳过。
+
+**GitHub**（`repoType=github`）：
+
+```bash
+# 获取当前仓库
+REPO=$(gh repo view --json owner,name -q '"\\(.owner.login)/\\(.name)"')
+
+# 上传截图到 GitHub，获取可访问 URL
+UPLOAD_RESPONSE=$(curl -s -X POST \
+  "https://uploads.github.com/repos/$REPO/issues/assets" \
+  -H "Authorization: token $(gh auth token)" \
+  -H "Content-Type: image/png" \
+  --data-binary "@<截图路径>")
+IMG_URL=$(echo $UPLOAD_RESPONSE | jq -r '.url // empty')
+
+# 追加图片评论到 issue
+gh issue comment <issue_number> --body "![截图]($IMG_URL)"
+```
+
+若 upload 失败（非 2xx）：追加一条评论写明截图本地路径，提示手动上传。
+
+**Gitea**（`repoType=gitea`）：
+
+```bash
+# 上传附件到 issue
+curl -s -X POST "$GITEA_URL/api/v1/repos/$OWNER/$REPO/issues/$ISSUE_NUM/assets" \
+  -H "Authorization: token $GITEA_TOKEN" \
+  -F "attachment=@<截图路径>"
+```
+
+附件上传后 Gitea 自动在 issue 页面展示，无需额外操作。
+
+若 `tea` CLI 支持附件上传则优先 `tea`，否则回退 `curl`。
+
+### 6. 输出结果
+
+```
+✅ 已创建 2 个 issue：
+
+  #42 [UAT] 用户登录 - S02 密码错误提示   截图已上传
+  #43 [UAT] 用户登录 - S05 退出登录后跳转  ⚠ 无截图
+
+/uat:run   修复后重新验证
+```

package/plugins/uat/skills/init/SKILL.md

@@ -0,0 +1,88 @@
+---
+name: init
+description: |
+  初始化 UAT 插件 - 创建目录结构并安装 skill 到项目
+---
+
+# 初始化 UAT 插件
+
+> **Audience:** Engineer
+
+将 uat-executor skill 安装到项目的 `.claude/skills/`，使 Codex 和 Claude 桌面端能在执行测试时自动加载。
+
+## 命令格式
+
+```
+/uat:init
+```
+
+---
+
+## 执行流程
+
+### 1. 创建目录结构
+
+```bash
+mkdir -p docs/uat/flows
+mkdir -p docs/uat/reports
+mkdir -p docs/uat/screenshots
+mkdir -p .claude/skills/uat-executor
+```
+
+### 2. 生成 testid 命名约定文档
+
+将约定模板复制到项目：
+
+```bash
+cp plugins/uat/templates/testid-convention.md docs/uat/testid-convention.md
+```
+
+此文件提交到 git，供前端开发参考添加 `data-testid` 属性。
+
+### 3. 安装 uat-executor skill
+
+将插件源文件复制到项目 skills 目录：
+
+```bash
+cp plugins/uat/skills/uat-executor/SKILL.md .claude/skills/uat-executor/SKILL.md
+```
+
+若插件路径不存在（说明插件未通过 Claude Code 安装），输出：
+
+```
+❌ 未找到 uat 插件源文件
+请先通过 devflow 安装 uat 插件后重试
+```
+
+### 4. 更新 .gitignore
+
+检查项目根目录的 `.gitignore`：
+
+- 若已包含 `docs/uat/reports/` → 跳过
+- 否则追加：
+
+```
+# UAT test artifacts
+docs/uat/reports/
+docs/uat/screenshots/
+```
+
+### 5. 输出结果
+
+```
+✅ UAT 插件初始化完成
+
+已创建目录：
+  docs/uat/flows/          测试流程文档
+  docs/uat/reports/        测试报告（已加入 .gitignore）
+  docs/uat/screenshots/    截图存储（已加入 .gitignore）
+
+已安装 skill：
+  .claude/skills/uat-executor/SKILL.md
+
+已生成约定文档：
+  docs/uat/testid-convention.md    data-testid 命名约定（提交 git，供前端参考）
+
+Codex / Claude 桌面端现在可以使用 /uat:run 执行测试
+使用 /uat:new 创建第一个测试流程文档
+```