@zhouhao4221/devflow-skills 0.2.0 → 0.3.1

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

@@ -0,0 +1,173 @@
+---
+name: req
+description: |
+  需求工作流管理 - 列出所有需求及其状态
+---
+
+# 需求工作流管理
+
+需求全流程管理主入口，列出所有需求及其状态。
+
+## 命令格式
+
+```
+/req [子命令] [参数] [--module=模块名] [--type=类型]
+```
+
+## 子命令
+
+| 子命令 | 说明 | 示例 |
+|-------|------|------|
+| (空) | 列出所有需求 | `/req` |
+| `new` | 创建新需求 | `/req:new 用户积分系统` |
+| `edit` | 编辑需求 | `/req:edit REQ-001` |
+| `review` | 评审需求 | `/req:review REQ-001` |
+| `dev` | 开发需求 | `/req:dev REQ-001` |
+| `test` | 测试需求 | `/req:test REQ-001` |
+| `done` | 完成需求 | `/req:done REQ-001` |
+| `status` | 查看状态 | `/req:status REQ-001` |
+| `init` | 初始化项目 | `/req:init my-project` |
+| `use` | 切换项目 | `/req:use my-project` |
+| `projects` | 列出所有项目 | `/req:projects` |
+| `migrate` | 迁移本地需求到全局缓存 | `/req:migrate my-project` |
+| `cache` | 缓存管理 | `/req:cache clear my-project` |
+| `modules` | 列出所有模块 | `/req:modules` |
+| `branch` | 分支管理 | `/req:branch init` |
+| `commit` | 规范提交 | `/req:commit` |
+| `changelog` | 生成版本说明 | `/req:changelog v1.0.0` |
+
+---
+
+## 需求存储路径解析
+
+### 路径优先级
+
+1. **全局缓存**（推荐）：`~/.claude-requirements/projects/<project-name>/`
+2. **本地目录**（回退）：`docs/requirements/`
+
+### 解析流程
+
+```
+1. 检查 .claude/settings.local.json 中的 requirementProject
+2. 如果设置了 requirementProject:
+   → 使用 ~/.claude-requirements/projects/<requirementProject>/
+3. 如果未设置:
+   → 回退到本地 docs/requirements/
+```
+
+### 目录结构
+
+```
+<需求根目录>/
+modules/       # 模块文档
+  user.md   # 用户模块
+  order.md  # 订单模块
+active/        # 进行中的需求
+completed/     # 已完成的需求
+INDEX.md       # 需求索引（自动生成）
+template.md    # 需求模板
+```
+
+---
+
+## 执行流程（列表模式）
+
+### 0. 解析需求路径
+
+读取 `.claude/settings.local.json` 的 `requirementProject`：有绑定时使用 `~/.claude-requirements/projects/<project>/active/`，否则使用 `docs/requirements/active/`。
+
+### 1. 扫描需求目录
+
+列出需求路径下的所有文件。
+
+### 2. 解析每个需求文档
+
+提取元信息：
+- 编号（REQ-XXX）
+- 标题
+- 类型（后端/前端/全栈）
+- 模块
+- 状态
+- 功能点完成进度
+- 更新时间
+- 关联需求
+
+### 2.5 筛选（可选）
+
+支持按模块和类型筛选：
+
+```bash
+/req --module=用户模块           # 只看用户模块的需求
+/req --type=后端                 # 只看后端需求
+/req --type=前端 --module=用户模块  # 组合筛选
+```
+
+### 3. 展示需求列表
+
+头部显示插件版本和项目配置状态，然后按状态分组输出需求。
+
+**头部信息**（每次 `/req` 都展示）：
+
+从 `<plugin-path>/.claude-plugin/plugin.json` 读取版本号，从 `settings.local.json` 读取 `requirementProject`、`requirementRole`、`branchStrategy`，检查 CLAUDE.md 是否含架构描述关键词。
+
+```
+需求工作流 v<version> | 项目：<project> (<role>)
+   分支策略：<strategy.model 或 "未配置"> | CLAUDE.md 架构：✅ 或 ⚠️ 未配置
+
+
+
+活跃需求列表
+
+开发中
+| 编号 | 标题 | 类型 | 模块 | 进度 | 关联 |
+|------|------|------|------|------|------|
+| REQ-001 | 用户积分-后端 | 后端 | 用户模块 | 4/6 | REQ-002 |
+| REQ-002 | 用户积分-前端 | 前端 | 用户模块 | 2/4 | REQ-001 |
+
+待评审
+| 编号 | 标题 | 类型 | 模块 | 功能点 |
+|------|------|------|------|--------|
+| REQ-003 | 订单导出 | 后端 | 订单模块 | 3 |
+
+草稿
+| 编号 | 标题 | 类型 | 模块 | 创建时间 |
+|------|------|------|------|----------|
+| REQ-004 | 支付对账 | 全栈 | 支付模块 | 2026-01-08 |
+```
+
+### 4. 提示可用操作
+
+```
+可用命令：
+- /req:new <标题> - 创建新需求
+- /req:dev REQ-001 - 进入开发
+- /req:status REQ-001 - 查看详情
+```
+
+---
+
+## 子命令路由
+
+根据参数路由到对应子命令：
+
+```
+参数解析：
+- 无参数 → 列表模式
+- new → /req:new
+- edit REQ-XXX → /req:edit REQ-XXX
+- review REQ-XXX → /req:review REQ-XXX
+- dev REQ-XXX → /req:dev REQ-XXX
+- test REQ-XXX → /req:test REQ-XXX
+- done REQ-XXX → /req:done REQ-XXX
+- status REQ-XXX → /req:status REQ-XXX
+- init <project-name> → /req:init <project-name>
+- use <project-name> → /req:use <project-name>
+- projects → /req:projects
+- migrate <project-name> → /req:migrate <project-name>
+- cache <action> → /req:cache <action>
+- modules → /req:modules
+```
+
+## 用户输入
+
+$ARGUMENTS

package/plugins/req/skills/requirement-analyzer/SKILL.md

@@ -0,0 +1,274 @@
+---
+name: requirement-analyzer
+description: |
+  需求分析助手。仅在执行 /req:new 或 /req:edit 命令时触发。帮助完善需求文档。
+---
+
+# 需求分析助手
+
+仅在创建（`/req:new`）或编辑（`/req:edit`）需求时激活，引导完善需求文档各章节。
+
+---
+
+## 前置准备
+
+在开始分析前，**必须完成以下准备**：
+
+### 1. 读取模块上下文
+
+如果需求已指定模块（`--module` 参数或元信息中的模块字段），先读取模块文档：
+
+```
+docs/requirements/modules/<模块名>.md
+```
+
+从中提取：
+- 模块职责和边界（避免需求越界）
+- 已有业务规则（避免冲突或重复）
+- 核心 API 和数据模型（保持一致性）
+- 相关需求列表（识别依赖和关联）
+
+### 2. 识别需求类型
+
+根据元信息中的「类型」字段，调整分析侧重点：
+
+| 类型 | 分析侧重 |
+|------|---------|
+| 后端 | 接口需求、数据校验、业务规则、权限控制 |
+| 前端 | 页面交互、组件结构、状态管理、异常提示 |
+| 全栈 | 前后端接口契约、数据流转、联调要点 |
+
+---
+
+## 创建模式（`/req:new`）
+
+填充需求定义章节（一~六、九），**不填实现方案（十）**。
+
+分两阶段进行：阶段一通过 AI 提问收集信息，阶段二一次性生成完整文档。
+
+### 阶段一：AI 提问收集
+
+通过逐轮提问收集需求信息，**每轮只问一个主题**，降低用户认知负担。用户用自然语言回答即可，AI 负责结构化。
+
+#### 提问流程
+
+**第 1 轮：问题与现状**（→ 背景 + 客户场景 + 干系人）
+> 现在遇到了什么问题？谁反馈的？能描述一下具体的场景吗？
+
+- 收集目标：痛点是什么、谁受影响、当前怎么处理的、除提出方外还有哪些干系人
+- 质量门槛：有明确的痛点或业务驱动，至少一个具体场景，识别出提出方以外至少一类受影响角色（或明确回答"只有提出方"）
+- 追问触发：
+  - **5 Why 深挖**：用户描述的是**解决方案**而非**问题**时（如"想要一个导出按钮"），追问「为什么需要这个？如果没有会怎样？」直到挖到真正的业务问题
+  - **干系人识别**：用户仅提到提出方时，追问「除了提出方，还有谁会因此变化受影响？（运营 / 客服 / 财务 / 合规 / 运维 / 其他终端用户）」
+  - **范围边界**：用户描述的场景比较发散时，追问「本期必须做的是哪些？哪些相关场景可以放到后面？」
+
+**第 2 轮：期望结果**（→ 目标 + 价值）
+> 你希望做完后达到什么效果？怎么算成功？
+
+- 收集目标：功能上要实现什么能力、上线后的预期效果
+- 质量门槛：功能目标明确，效果目标尽量量化（如提效 XX%、减少 XX 次操作）
+- 追问触发：回答过于模糊时追问「能举个例子说明"好用"具体是什么样吗？」
+
+**第 3 轮：操作流程**（→ 使用场景）
+> 用户具体怎么用这个功能？从哪个入口进去，一步步怎么操作？
+
+- 收集目标：角色、前置条件、操作步骤、系统响应
+- 多场景识别：涉及不同角色或不同路径时，逐个确认
+- 追问触发：只描述了正常流程时追问「如果操作失败 / 数据不合法，系统怎么处理？」
+
+**第 4 轮：约束与风险**（→ 非功能约束 + 外部依赖 + 风险项）
+> 有性能、安全、兼容性方面的要求吗？依赖其他团队或第三方吗？有什么担心的风险点？
+
+- 收集目标：NFR 约束（性能/安全/兼容性）、外部依赖、技术或数据风险
+- 无则跳过：用户回答"没有"时不强求，标记为"暂无"
+
+#### 提问规则
+
+1. **每轮一个主题**：不要一次抛出所有问题
+2. **先听后问**：基于用户上一轮的回答决定追问方向，不要机械按顺序走
+3. **追问而非重复**：回答模糊时针对性追问，不重复问同一个问题
+4. **允许跳过**：用户主动说"先跳过"或"后面再说"时尊重，标记为待补充
+5. **不限轮数**：四个主题是框架而非硬性流程，可以反复深入、补充、修正，直到双方对需求理解一致
+6. **信息足够的判断标准**：至少有明确的痛点/背景 + 可验证的目标 + 一个完整的使用场景
+
+#### 等待用户确认
+
+当 AI 认为信息已充足时，**总结已收集的关键信息**，询问用户是否还有补充或修改，例如：
+
+```
+📋 目前收集到的需求要点：
+- 背景：...
+- 目标：...
+- 核心场景：...
+- 约束：...
+
+还有需要补充或修改的吗？确认无误我就开始生成需求文档。
+```
+
+**必须等用户明确确认**（如"可以了"、"没问题"、"开始生成"、"确认"）后才进入阶段二。用户提出补充或修改时，继续讨论。
+
+### 阶段二：AI 一次性生成文档
+
+基于阶段一收集的信息，AI 推导生成以下章节：
+
+#### 一、需求描述
+
+将收集到的信息结构化填入：
+- 1.1 背景：从第 1 轮提取痛点和现状
+- 1.2 目标：从第 2 轮提取，区分功能目标和效果目标
+- 1.3 客户场景：从第 1 轮提取原始诉求，保留用户原话
+- 1.4 价值：从第 2 轮提取业务收益
+- 1.5 范围与边界：从讨论中提取「本期包含」和「本期不做」；若未明确讨论，默认「本期包含 = 使用场景描述的能力」、「本期不做」留待用户补充并标注"待确认"
+- 1.6 干系人：从第 1 轮提取（提出方 + 5 Why / 干系人追问出的受影响方），填入表格并标注各自关注点
+
+#### 四、使用场景
+
+从第 3 轮提取，结构化为模板格式：
+- 角色、前置条件、基本流程（用户操作 → 系统响应）、异常流程
+
+#### 十、关联信息
+
+从第 4 轮提取：
+- **外部依赖**：依赖的第三方接口 / 其他团队交付 / 基础设施
+- **风险项**：技术 / 数据 / 时间风险
+- **假设**：讨论中出现的"相信为真但未验证的前提"（例：用户规模上限、第三方 SLA、数据量级），一旦不成立需重新评估方案；与"依赖"的区别——依赖是"我们必须拿到 Y"，假设是"我们相信 X 是真的"
+
+关联需求从模块上下文中识别。
+
+#### 二、功能清单
+
+从使用场景中提取原子功能点：
+
+- 每个功能点可独立开发和测试
+- 标注功能点之间的依赖关系
+- 按操作类型组织（如：创建类、查询类、更新类、删除类）
+- **前端需求**：按页面/组件维度组织功能点
+- **后端需求**：按接口/业务操作维度组织功能点
+
+#### 三、业务规则
+
+从使用场景的基本流程和异常流程中提炼：
+
+| 规则类型 | 提取来源 |
+|---------|---------|
+| 数据校验 | 使用场景中的输入描述 → 必填、格式、长度、范围 |
+| 状态转换 | 使用场景中的流程步骤 → 状态流转条件和约束 |
+| 权限控制 | 使用场景中的角色 → 谁可以做什么操作 |
+| 非功能约束 | 从背景和目标中提取 → 性能要求（响应时间、数据量级、并发量）、安全要求（鉴权、脱敏、审计）、兼容性（老接口、多端适配） |
+
+#### 五、数据与交互
+
+根据需求类型生成不同内容：
+
+**后端 / 全栈 → 接口需求**：
+- 只描述**业务语义**：需要什么能力、输入什么、输出什么
+- **不定义技术细节**：不指定 HTTP 方法、URL 路径、字段类型（这些在 `/req:dev` 阶段由 AI 分析代码后生成）
+- 仅填写「后端/全栈：接口需求」子章节，「前端：交互逻辑」子章节保留占位文本
+
+**前端 → 交互逻辑**：
+- 从使用场景中提取每个页面/模块的交互逻辑
+- 按「操作/区域 → 用户行为 → 数据需求 → 交互反馈」四列描述
+- **数据需求只写业务字段**（如"订单编号、状态、金额"），不写接口路径
+- 覆盖：列表展示、搜索筛选、表单提交、操作按钮、状态反馈（加载/空/错误）
+- 仅填写「前端：交互逻辑」子章节，「后端/全栈：接口需求」子章节保留占位文本
+- `/req:dev` 阶段 AI 自动匹配后端接口到每个操作
+
+#### 六、测试要点
+
+分两部分生成：
+
+**6.1 技术测试**（从功能清单和业务规则推导）：
+- 正常流程：每个功能点的 Happy Path
+- 边界条件：业务规则中的极值和临界条件
+- 异常场景：使用场景中的异常流程
+- 权限测试：不同角色的访问控制验证
+- 非功能测试：性能压测场景、安全校验（如有非功能约束）
+
+**6.2 验收标准**（从需求描述和使用场景推导）：
+- 以产品/业务方视角描述，非技术语言
+- 每条格式：在什么页面/入口 → 执行什么操作 → 能看到什么结果
+- 覆盖核心场景的业务可观测结果
+- 效果目标的验证方式（如有量化目标，说明如何确认达成）
+
+### 不在创建阶段填写
+
+- **十一、实现方案**（含数据模型、文件改动清单、实现步骤）→ 在 `/req:dev` 阶段由 AI 分析代码后自动生成
+
+### 粒度检查（创建时必须执行）
+
+在开始分析前，快速判断需求粒度是否合适：
+
+| 信号 | 判断 |
+|------|------|
+| 标题含「系统」「模块」「平台」 | 可能太大 |
+| 标题含「接口」「字段」「按钮」 | 可能太小 |
+| 涉及多个独立的业务功能 | 太大 |
+| CRUD 属于同一业务实体 | 合适 |
+
+**判断标准**：这个需求完成后，用户能感知到一个完整的功能变化吗？能 → 粒度合适；不能 → 拆得太细或太大。
+
+**粒度不合适时**：提示用户先执行 `/req:split` 进行拆分分析，不在创建流程中展开详细拆分讨论。
+
+### 功能扩展判断（编辑时必须执行）
+
+当用户通过 `/req:edit` 要求新增功能点时，先判断是否应该新建 REQ：
+
+| 场景 | 建议 |
+|------|------|
+| 新功能是原需求的自然延伸，缺少则不完整 | 在原 REQ 中补充 |
+| 新功能可独立上线，不依赖原 REQ | 建议 `/req:new` 新建 |
+| 原 REQ 已 `已完成` | 必须 `/req:new` 新建 |
+| 原 REQ 在 `开发中`/`测试中`，新功能影响已写代码 | 建议 `/req:new` 新建，避免范围蔓延 |
+
+**核心问题**：去掉这个功能点，原需求还能独立交付吗？能 → 新建；不能 → 在原 REQ 补充。
+
+---
+
+## 编辑模式（`/req:edit`）
+
+编辑已有需求，仅修改用户指定的章节。
+
+### 编辑原则
+
+1. **只改指定章节**：严禁擅自修改用户未要求编辑的章节
+2. **多轮讨论**：与用户充分讨论修改方向和细节，不限轮数，用户明确确认后再写入文档
+3. **意图澄清**：用户描述的修改意图可能不精确，需分析真实意图：
+   - 用户说改 A 但实际应该改 B → 指出并确认：「您提到修改 XX，但从需求上下文看，实际需要调整的是 YY，是这样吗？」
+   - 修改 A 会导致 B、C 不一致 → 主动提示关联影响：「修改了使用场景后，功能清单和测试要点也需要同步更新，要一起改吗？」
+4. **保留已有内容**：在已有内容基础上修改，不清空重写（除非用户明确要求）
+
+### 变更感知
+
+如果需求已在「开发中」或更后的状态，编辑时主动提示：
+
+```
+⚠️ 需求当前状态为「开发中」，修改可能影响已完成的开发工作。
+建议关注以下变更影响：
+- 功能清单变更 → 开发范围变化
+- 业务规则变更 → 已有实现可能需要调整
+- 接口需求变更 → 前后端接口契约变化
+```
+
+---
+
+## 输出要求
+
+### 格式约束（强制）
+
+生成或补充内容时，**必须严格遵循模板格式**：
+
+1. **先读取模板**：根据需求类型读取对应模板文件
+   - 正式需求：优先 `docs/requirements/templates/requirement-template.md`，其次 `<plugin-path>/templates/requirement-template.md`
+   - 快速修复：优先 `docs/requirements/templates/quick-template.md`，其次 `<plugin-path>/templates/quick-template.md`
+   - **两个路径都不存在时，终止操作**，提示用户执行 `/req:update-template` 恢复模板
+2. **章节结构不可变**：不得新增、删除、合并或重命名模板中的章节
+3. **层级标题不可变**：章节标题、编号必须与模板完全一致
+4. **表格格式不可变**：表格的列名、列数必须与模板一致
+5. **保留空章节**：未涉及的章节保留模板占位文本，不得删除
+6. **仅填充内容**：在模板对应章节的占位文本处填充实际内容
+
+### 内容质量标准
+
+- 功能描述可执行：开发者读完能直接开始编码
+- 业务规则无歧义：不存在"视情况而定"等模糊描述
+- 测试要点可验证：每条有明确的预期结果

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

@@ -0,0 +1,201 @@
+---
+name: review
+description: |
+  需求评审 - 提交或记录评审结果
+---
+
+# 需求评审
+
+提交需求评审或记录评审结果。
+
+> **Audience:** Product Manager
+> 存储路径和缓存同步规则见 [_storage.md](./_storage.md)
+
+## 命令格式
+
+```
+/req:review [REQ-XXX] [pass|reject]
+```
+
+- 省略编号时自动选择「草稿」「评审驳回」或「待评审」的需求
+- 多个候选时让用户选择
+
+---
+
+## 执行流程
+
+### 根据当前状态执行不同操作
+
+---
+
+## 场景一：提交评审（草稿/评审驳回 → 待评审）
+
+当需求状态为「草稿」或「评审驳回」时：
+
+### 1. 完整性检查
+
+检查必填章节是否完整：
+
+```
+需求完整性检查
+
+✅ 需求描述 - 已填写
+✅ 功能清单 - 3 个功能点
+✅ 业务规则 - 5 条规则
+✅ 数据模型 - 1 张新表
+✅ 接口需求 - 3 个接口能力
+✅ 文件改动清单 - 8 个文件
+✅ 实现步骤 - 9 个步骤
+✅ 测试要点 - 8 个测试点
+
+检查结果：✅ 通过
+```
+
+如果有缺失：
+```
+❌ 需求完整性检查失败
+
+缺失内容：
+- ❌ 业务规则 - 未填写
+- ❌ 实现步骤 - 未填写
+
+请先完善需求文档：/req:edit REQ-XXX
+```
+
+### 2. 生成评审摘要
+
+```markdown
+## 需求评审摘要
+
+### 基本信息
+- 编号：REQ-001
+- 标题：部门渠道关联
+- 优先级：P1
+- 功能点数：6
+
+### 需求概述
+在组织部门管理中，实现部门和分组与渠道的关联功能...
+
+### 影响范围
+- 模块：sys（系统）、oms（订单）、dashboard（看板）
+- 文件数：12 个
+- 新增表：1 张
+
+### 风险评估
+- 中等风险：涉及权限控制逻辑变更
+
+### 工作量评估
+- 功能点：6 个
+- 预计涉及文件：12 个
+```
+
+### 3. 更新状态并同步缓存
+
+- 修改元信息状态为「待评审」
+- 勾选生命周期「待评审」
+- **同步到全局缓存**
+
+### 4. 提示
+
+```
+✅ 需求已提交评审
+
+REQ-001 部门渠道关联
+状态：待评审
+
+评审通过后执行：/req:review REQ-001 pass
+评审驳回执行：/req:review REQ-001 reject
+```
+
+---
+
+## 场景二：评审通过（待评审 → 评审通过）
+
+当参数包含 `pass` 时：
+
+### 1. 状态检查
+
+```
+if 状态 != "待评审":
+    错误：当前状态不是「待评审」，无法执行评审操作
+    退出
+```
+
+### 2. 收集评审信息
+
+```
+评审人：<git config user.name 的值>（如需修改请输入）
+评审意见：（可选）
+```
+
+- **评审人**（必填）：默认取 `git config user.name`，展示给用户确认，用户可修改
+- **评审意见**：可选
+
+### 3. 记录评审结果并同步缓存
+
+- 更新「评审记录」章节
+- 修改元信息状态为「评审通过」
+- 勾选生命周期「评审通过」
+- **同步到全局缓存**
+
+### 4. 提示
+
+```
+✅ 评审通过
+
+REQ-001 部门渠道关联
+状态：✅ 评审通过
+
+开始开发：/req:dev REQ-001
+```
+
+---
+
+## 场景三：评审驳回（待评审 → 评审驳回）
+
+当参数包含 `reject` 时：
+
+### 1. 收集评审信息
+
+```
+评审人：<git config user.name 的值>（如需修改请输入）
+驳回原因（必填）：
+```
+
+- **评审人**（必填）：默认取 `git config user.name`，展示给用户确认，用户可修改
+- **驳回原因**（必填）：必须填写
+
+### 2. 记录评审结果并同步缓存
+
+- 更新「评审记录」章节（驳回原因必填）
+- 修改元信息状态为「评审驳回」
+- **同步到全局缓存**
+
+### 3. 提示
+
+```
+❌ 评审驳回
+
+REQ-001 部门渠道关联
+状态：❌ 评审驳回
+
+驳回原因：接口需求需要补充异常场景说明
+
+修改需求：/req:edit REQ-001
+重新提审：/req:review REQ-001
+```
+
+---
+
+## 状态流转图
+
+```
+草稿 → 待评审 → 评审通过
+  ↑                                  
+                ↓                    ↓
+  评审驳回              开发中
+```
+
+## 用户输入
+
+$ARGUMENTS