@zhouhao4221/devflow-skills 0.2.0 → 0.3.1

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

@@ -0,0 +1,172 @@
+---
+name: new
+description: |
+  创建新需求 - 基于模板创建需求文档
+---
+
+# 创建新需求
+
+基于模板创建新的需求文档，引导用户完成需求分析。
+
+> **Audience:** Product Manager
+> 存储路径规则见 [_storage.md](./_storage.md)
+
+## 命令格式
+
+```
+/req:new [需求标题] [--type=类型] [--module=模块名] [--from-issue=#编号]
+```
+
+**示例：**
+- `/req:new 用户积分系统` - 交互选择类型和模块
+- `/req:new 用户积分-后端 --type=后端 --module=用户模块`
+- `/req:new 订单优惠券 --type=全栈 --module=订单模块,支付模块`
+- `/req:new --from-issue=#123` - 从 GitHub/Gitea issue 创建，标题/正文作为讨论起点
+
+---
+
+## 执行流程
+
+### 0. （可选）从 issue 导入
+
+若命令带 `--from-issue=#N`，按 [_issue.md 的 Issue 拉取规范](./_issue.md#issue-拉取规范) 拉取 issue。
+
+拉取成功后：
+- **默认标题**：issue 标题（用户未传标题时直接采用，传了则以用户标题为准）
+- **issue 字段**：记录 `#N`，稍后写入文档元信息
+- **讨论上下文**：将 issue 正文作为「问题与现状」的初始输入，跳过阶段一的第一个主题追问，直接展示解析结果让用户确认或补充
+
+### 1. 生成编号
+扫描 active/ 和 completed/ 目录，最大编号 +1 → `REQ-XXX`
+
+### 2. 收集信息
+
+交互收集（未通过参数指定时）：
+- **标题**（必填）
+- **类型**：后端 / 前端 / 全栈
+- **模块**（必填）：从已有模块选择或创建新模块
+- **关联需求**：如果是后端，询问是否关联前端需求
+- **优先级**：P1/P2/P3，默认 P2
+
+#### 模块选择流程（强制）
+
+正式需求**必须关联模块**，流程如下：
+
+```
+1. 扫描 docs/requirements/modules/ 获取现有模块列表
+2. 展示选项：
+   
+   请选择所属模块：                      
+                                       
+   1. 用户模块                          
+   2. 订单模块                          
+   3. 支付模块                          
+                
+   n. 创建新模块                        
+   
+3. 用户选择：
+   - 选择现有模块 → 继续下一步
+   - 选择"创建新模块" → 输入模块名 → 创建模块文档 → 继续
+4. 支持多模块：用逗号分隔（如 --module=用户模块,订单模块）
+```
+
+**注意**：不允许跳过模块选择，这确保所有正式需求都能按模块检索。
+
+### 3. 读取模板
+
+**必须先读取模板文件**，确定文档结构：
+
+```
+优先级：
+1. 本地模板：docs/requirements/templates/requirement-template.md
+2. 插件模板：<plugin-path>/templates/requirement-template.md
+```
+
+**两个路径都不存在时，终止操作**：
+```
+❌ 未找到需求模板文件
+
+请执行 /req:update-template requirement 恢复模板
+```
+
+读取后解析模板的完整章节结构，后续创建文档**必须严格保留模板中的所有章节、层级和格式**。
+
+### 4. 创建文档
+
+1. **严格按模板结构**创建文档，保留所有章节标题和占位内容
+2. 填充元信息（编号、类型、模块、状态=草稿、日期）
+3. 若从 issue 导入 → 元信息 `issue` 字段填 `#N`；否则填 `-`
+4. 写入 `docs/requirements/active/REQ-XXX-标题.md`
+5. 同步到全局缓存（如已绑定项目）
+
+**格式约束（强制）：**
+- 章节标题、编号、层级必须与模板完全一致
+- 不得新增、删除、合并或重命名模板中的章节
+- 未填写的章节保留模板中的占位文本，不得删除
+- 表格结构（列名、列数）必须与模板一致
+
+### 5. 引导需求分析
+
+分两阶段完善需求文档的**需求定义章节**（一~六、九）：
+
+**阶段一：AI 多轮讨论收集**
+
+通过多轮对话收集需求信息（详见 requirement-analyzer 技能），围绕以下主题展开：
+
+1. **问题与现状** → 收集背景、客户场景
+2. **期望结果** → 收集目标、价值
+3. **操作流程** → 收集使用场景（角色、步骤、异常）
+4. **约束与风险** → 收集非功能约束、外部依赖、风险项
+
+每轮只问一个主题，用户用自然语言回答，AI 追问模糊点。**不限制讨论轮数**，可以反复深入、补充、修正，直到用户明确确认（如"可以了"、"没问题"、"开始生成"）后才进入阶段二。
+
+**阶段二：AI 一次性生成文档**
+
+基于收集的信息，AI 推导生成所有需求定义章节：
+1. **一、需求描述**（结构化用户回答 → 背景、目标、客户场景、价值、范围与边界、干系人）
+2. **二、功能清单**（从使用场景中提取原子功能点）
+3. **三、业务规则**（从场景提炼规则，含非功能约束）
+4. **四、使用场景**（结构化用户描述的操作流程）
+5. **五、接口需求**（需要什么接口能力，不定义技术细节）
+6. **六、测试要点**（6.1 技术测试 + 6.2 验收标准）
+7. **十、关联信息**（外部依赖、假设、风险项、关联需求）
+
+**不在创建阶段填写的章节：**
+- **七、图示**（可选，有需要时由用户或 AI 补充 Mermaid 图）
+- **十一、实现方案**（含数据模型、文件改动清单、实现步骤）→ 在 `/req:dev` 阶段由 AI 分析代码后自动生成
+
+**AI 生成时必须遵循模板格式**：填充内容到模板对应章节中，不得改变章节结构。
+
+### 6. 更新 PRD 索引
+
+在 `docs/requirements/PRD.md` 的「需求追踪」章节追加新需求记录：
+
+```markdown
+| REQ-XXX | 需求标题 | 模块名 | 草稿 | YYYY-MM-DD | - |
+```
+
+若 PRD.md 不存在或无「需求追踪」章节，跳过此步骤。
+
+### 7. 更新关联
+
+- 更新模块文档的「相关需求」
+- 更新 INDEX.md 索引
+
+### 8. 输出结果
+
+```
+✅ 需求文档已创建
+路径：docs/requirements/active/REQ-XXX-标题.md
+模块：用户模块
+状态：草稿
+
+下一步：
+- /req:edit REQ-XXX - 继续完善
+- /req:review REQ-XXX - 提交评审
+```
+
+---
+
+## 用户输入
+
+$ARGUMENTS

package/plugins/req/skills/new-quick/SKILL.md

@@ -0,0 +1,246 @@
+---
+name: new-quick
+description: |
+  快速修复 - 创建小bug修复或小功能的快速需求
+---
+
+# 快速修复需求
+
+> **Audience:** Engineer
+
+用于小bug修复或小功能开发，简化流程：方案确认即可开发。
+
+## 命令格式
+
+```
+/req:new-quick [标题]
+```
+
+---
+
+## 简化生命周期
+
+```
+草稿 → ✅ 方案确认 → 开发中 → 已完成
+```
+
+（跳过：评审、测试阶段）
+
+---
+
+## 执行流程
+
+### 0. 解析存储路径
+
+本地主存储为 `docs/requirements/active/` 和 `docs/requirements/completed/`，确保目录存在。读取 `settings.local.json` 的 `requirementProject`；有绑定则同时准备缓存路径 `~/.claude-requirements/projects/$PROJECT/`。
+
+### 1. 生成需求编号
+
+格式：`QUICK-XXX`（三位数字，如 QUICK-001）
+
+扫描本地 active/completed 和缓存 active/completed 中所有 QUICK-XXX 文件，取两边最大编号中的较大值，加 1 生成新编号。
+
+### 1.5 （可选）从 issue 导入
+
+若命令带 `--from-issue=#N`，按 [_issue.md 的 Issue 拉取规范](./_issue.md#issue-拉取规范) 拉取 issue：
+- issue 标题作为默认标题
+- issue 正文作为「问题/需求描述」的初始输入
+- 元信息 `issue` 字段填 `#N`（否则填 `-`）
+
+`repoType` 为 `other` 或未配置时提示并退出。
+
+### 2. 收集基本信息
+
+如果未提供标题，询问用户：
+
+**需要收集的信息：**
+- 问题/需求描述（必填）
+- 类型：bug修复 / 小功能 / 优化（默认：bug修复）
+- 优先级（P1/P2/P3，默认 P2）
+- **模块**：自动设为「快速修复」（无需用户选择）
+
+### 3. 读取模板
+
+**必须先读取快速修复模板**，确定文档结构：
+
+```
+优先级：
+1. 本地模板：docs/requirements/templates/quick-template.md
+2. 插件模板：<plugin-path>/templates/quick-template.md
+```
+
+**两个路径都不存在时，终止操作**：
+```
+❌ 未找到快速修复模板文件
+
+请执行 /req:update-template quick 恢复模板
+```
+
+读取后解析模板的完整章节结构，后续创建文档**必须严格保留模板中的所有章节、层级和格式**。
+
+### 4. 创建简化文档
+
+**步骤 4.1：严格按模板结构创建**
+
+使用快速需求模板创建文件：`$LOCAL_ACTIVE/QUICK-XXX-标题.md`
+
+**格式约束（强制）：**
+- 章节标题、层级必须与模板完全一致
+- 不得新增、删除、合并或重命名模板中的章节
+- 未填写的章节保留模板中的占位文本，不得删除
+- 表格结构（列名、列数）必须与模板一致
+
+**初始化内容：**
+- 填充元信息（编号、标题、类型、状态=草稿、日期）
+- **模块字段设为「快速修复」**
+- `issue` 字段：从 issue 导入时填 `#N`，否则填 `-`
+- 生命周期勾选「草稿」
+
+**步骤 4.2：同步到全局缓存**
+
+若已绑定项目，将新建文档同步复制到 `$CACHE_ACTIVE/`。
+
+### 5. 快速分析并生成方案
+
+AI 分析问题/需求，生成实现方案：
+
+#### 4.1 问题分析（如果是bug）
+- 分析错误信息/现象
+- 定位问题根因
+- 确定影响范围
+
+#### 4.2 代码定位
+- 搜索相关代码
+- 确定涉及的文件
+- 理解现有实现
+
+#### 4.3 生成实现方案
+- 具体的改动说明
+- 涉及文件清单
+- 预估改动量（小/中）
+
+### 6. 方案确认
+
+显示方案摘要，等待用户确认：
+
+```
+快速需求：QUICK-001 修复xxx问题
+
+类型：bug修复
+优先级：P2
+
+问题分析：
+  [问题根因分析]
+
+实现方案：
+  [具体实现方案]
+
+涉及文件：
+  - internal/xxx/biz/xxx.go（修改）
+  - internal/xxx/store/xxx.go（修改）
+
+改动量：小（约 20 行）
+
+```
+
+### 7. 方案确认检查
+
+在确认前检查：
+- [ ] 改动范围可控（建议 <5 个文件）
+- [ ] 不涉及数据库结构变更
+- [ ] 不影响其他核心功能
+- [ ] 可快速验证
+
+**如果任一不满足**，建议用户升级为正式需求：
+
+```
+⚠️ 此改动可能超出快速修复范围：
+- 涉及 8 个文件
+- 需要修改数据库表结构
+
+建议使用正式需求流程：/req:new [标题]
+
+```
+
+### 8. 确认后进入开发
+
+用户确认后：
+
+1. 更新状态为「方案确认」→「开发中」
+2. 更新需求文档（先本地，后缓存）
+3. 使用 TodoWrite 生成开发任务
+4. 按照 dev-guide 技能引导开发
+
+```
+✅ 方案已确认，开始开发
+
+开发任务：
+1. [ ] 修改 internal/xxx/biz/xxx.go
+2. [ ] 修改 internal/xxx/store/xxx.go
+3. [ ] 自测验证
+
+开始执行第一个任务...
+```
+
+### 9. 开发完成
+
+完成所有改动后：
+
+1. 更新状态为「已完成」
+2. 移动文档到 completed 目录
+3. 同步缓存
+
+```
+快速修复完成！
+
+QUICK-001 修复xxx问题
+状态：已完成
+改动文件：2 个
+耗时：约 15 分钟
+
+文档归档：docs/requirements/completed/QUICK-001-修复xxx问题.md
+
+下一步（可选）：
+- 代码审查：/code-reviewer
+- 提交代码：git add . && git commit
+```
+
+---
+
+## 适用场景
+
+### 适合快速修复的情况
+
+- 简单的 bug 修复（逻辑错误、空指针等）
+- 小功能增强（新增字段、调整参数等）
+- 代码优化（性能优化、代码整理等）
+- UI 微调（文案修改、样式调整等）
+
+### 不适合快速修复的情况
+
+建议使用 `/req:new` 创建正式需求：
+
+- 涉及数据库表结构变更
+- 涉及多个模块的联动修改
+- 需要新增 API 接口
+- 影响核心业务流程
+- 需要多人协作或评审
+
+---
+
+## 与正式需求的区别
+
+| 对比项 | 快速修复 (QUICK) | 正式需求 (REQ) |
+|-------|-----------------|---------------|
+| 编号格式 | QUICK-XXX | REQ-XXX |
+| 生命周期 | 4 阶段 | 6 阶段 |
+| 评审环节 | 无 | 有 |
+| 测试环节 | 自测 | 完整测试 |
+| 文档详细度 | 简化 | 完整 |
+| 适用场景 | 小改动 | 中大型需求 |
+
+---
+
+## 用户输入
+
+$ARGUMENTS

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

@@ -0,0 +1,157 @@
+---
+name: pr
+description: |
+  创建 PR - 根据仓库类型自动创建 Pull Request
+---
+
+# 创建 Pull Request
+
+根据分支策略中的仓库类型，自动推送分支并创建 PR。
+
+> **Audience:** Engineer
+> 不受仓库角色限制，readonly 也可执行。不触发缓存同步。
+>
+> **CLI 优先级**：GitHub 走 `gh pr create`；Gitea 按 [`_gitea_cli.md`](./_gitea_cli.md) 检测，可用 `tea` 时走 `tea pulls create --base <target> --head <branch> --title ... --description ...`，否则回退本文 curl 示例。
+
+## 命令格式
+
+```
+/req:pr [REQ-XXX] [--title=自定义标题] [--base=目标分支]
+```
+
+- 省略编号时根据当前分支名匹配需求
+- `--title`、`--base` 覆盖自动值
+
+---
+
+## 执行流程
+
+### 1. 识别需求和分支
+
+- 指定编号 → 读取该需求的 `branch` 字段，按逗号拆分得到分支列表
+- 未指定 → `git branch --show-current`，从分支名提取 `REQ-XXX` / `QUICK-XXX`
+- 两者都失败 → 提示 `请指定需求编号：/req:pr REQ-XXX` 退出
+
+**多分支处理**：`branch` 字段含多个分支时，为**每个分支各创建一个 PR**，依次执行步骤 2–8：
+
+```
+此需求有 2 个开发分支，将分别创建 PR：
+  [1/2] feat/REQ-025-backend  → main
+  [2/2] feat/REQ-025-frontend → main
+```
+
+若只需对当前分支创建 PR，直接运行（不传编号），命令自动匹配当前分支。
+
+### 2. 前置检查
+
+`git status --porcelain` 有未提交改动时，自动串联执行 `/req:commit` 流程（分支检查 + 生成提交信息 + 提交），成功后继续。
+
+### 3. 读取策略配置 + 推导合并目标
+
+读取 `.claude/settings.local.json.branchStrategy`：
+- `model`（`git-flow` / `github-flow` / `trunk-based`，缺省 `github-flow`）
+- `mainBranch`（缺省 `main`）
+- `developBranch`（缺省 `develop`，git-flow 专用）
+- `mergeTarget`（兜底值，缺省 `main`）
+- `repoType`（缺省 `other`）
+- `giteaUrl`、`giteaToken`（仅 gitea 需要）
+- `deleteBranchAfterMerge`（缺省 `true`）
+- `reviewers`（数组，缺省 `[]`；非空则自动设置审核人，无需确认）
+
+无 `branchStrategy` → 按 `other` 处理，`reviewers` 视为空。
+
+**合并目标推导**（`--base` 可覆盖最终结果）：
+
+```
+branch = 当前分支名
+
+if model == "git-flow":
+    if branch 以 "hotfix/" 开头:
+        targets = [mainBranch, developBranch]   # 步骤 7 双 PR
+    elif branch 以 "release/" 或 "chore/release-" 开头:
+        targets = [mainBranch]                  # release 合入主线
+    else:                                       # feat/ fix/ 等功能分支
+        targets = [developBranch]               # 功能合入 develop
+elif model in ("github-flow", "trunk-based"):
+    targets = [mainBranch]
+else:
+    targets = [mergeTarget]                     # 兜底
+```
+
+`--base` 存在时直接覆盖 `targets = [args.base]`，跳过上述推导。
+
+### 4. 生成 PR 标题和 Body
+
+**标题**（`--title` 覆盖）：
+- REQ-XXX → `feat(REQ-XXX): <标题>`
+- QUICK-XXX → `fix(QUICK-XXX): <标题>`
+- hotfix 分支 → `hotfix: <描述>`
+
+**Body**（Markdown）：
+```
+## 需求
+- 编号 / 标题 / 状态（从需求文档 YAML 元信息读取）
+
+## 功能清单
+（从需求文档「二、功能清单」提取）
+
+## 变更文件
+（从「十一、实现方案.文件改动清单」提取；无则跳过）
+```
+
+### 5. 推送分支
+
+推送当前分支到 origin 并设置上游追踪。
+
+### 6. 按 repoType 创建 PR
+
+#### gitea
+
+1. 解析 `git remote get-url origin` 得到 `OWNER/REPO`（SSH/HTTPS 均支持）
+2. `giteaToken` 缺失 → 提示配置方式，给出手动 compare 链接退出
+3. 先查 `GET /api/v1/repos/{OWNER}/{REPO}/pulls?state=open&head={OWNER}:{branch}&base={target}` 是否已有 PR；有 → 输出现有 PR 链接，跳到步骤 8
+4. 无 → `POST /api/v1/repos/{OWNER}/{REPO}/pulls`，参数 `title/body/head/base`
+5. **设置审核人**（`reviewers` 非空时，**不询问**直接执行）：
+   - `POST /api/v1/repos/{OWNER}/{REPO}/pulls/{N}/requested_reviewers`，body `{"reviewers": [...]}`
+   - tea CLI 无对应子命令，统一走 curl
+   - 单个失败（用户名不存在 / 权限不足）不阻塞主流程，输出 ⚠️ 提示后继续
+
+成功输出：
+```
+✅ PR 已创建
+   <url>
+已请求审核：@user1, @user2     ← reviewers 非空时输出
+/req:review-pr review / merge，或 /req:done 归档
+```
+
+#### github
+
+检查 `command -v gh`。可用 → `gh pr create --title "..." --body "..." --base <target>`，`reviewers` 非空时追加 `--reviewer <逗号分隔列表>`（**不询问**直接执行）。不可用 → 提示命令 + 浏览器 compare 链接。
+
+#### other
+
+不创建 PR，输出：
+```
+分支已推送：<branch> → <target>
+合并命令：git checkout <target> && git merge <branch>
+```
+
+### 7. 多目标处理
+
+`targets` 包含多个分支时（当前仅 git-flow hotfix 场景），对每个 target 各执行一次步骤 6，输出对应 PR 链接 / 命令。
+
+### 8. 分支清理提示
+
+**auto 模式跳过**：若项目内存在 `.claude/.req-auto` 且 mtime 在 10 分钟内（由 `/req:fix --auto` 等上游命令创建），直接跳过本步骤，不询问也不切分支——PR 刚创建还没合并，此时删本地分支不合理，合并后用 `/req:review-pr merge` 自然处理。
+
+非 auto 模式下，`deleteBranchAfterMerge != false` 时询问：
+```
+是否切回 <target> 并删除本地分支 <branch>？
+```
+确认 → 切回 target 并删除本地分支（用 `-d` 而非 `-D`，未合并时会被 git 拒绝）。当前已在目标分支则跳过切换。远程分支不删。
+
+---
+
+## 用户输入
+
+$ARGUMENTS