@zhouhao4221/devflow-skills 0.2.0 → 0.3.1

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

@@ -0,0 +1,191 @@
+---
+name: do
+description: |
+  智能开发 - AI 分析意图，自动选择流程，生成方案并执行
+---
+
+# 智能开发
+
+描述你要做的事，AI 自动分析意图、选择合适的流程、生成方案并执行。无需关心该用哪个命令。
+
+> **Audience:** Engineer
+> 此命令**不受仓库角色限制**，readonly 仓库也可执行。
+> 不触发缓存同步（无需求文档）。
+>
+> **CLI 优先级**：GitHub 用 `gh`；Gitea 按 [`_gitea_cli.md`](./_gitea_cli.md) 检测 `tea`，可用即走 `tea`，否则回退本文 curl 示例。
+
+## 命令格式
+
+```
+/req:do <描述> [--from-issue=#编号]
+```
+
+示例：
+- `/req:do 优化订单查询性能，加索引和分页缓存`
+- `/req:do 重构用户服务层，拆分过大的方法`
+- `/req:do 升级 Go 到 1.23`
+- `/req:do 统一错误码格式`
+- `/req:do 给商品列表加个搜索功能`
+- `/req:do --from-issue=#42` - 从 issue 读取描述后分析
+
+---
+
+## 执行流程
+
+### 0. （可选）从 issue 读取描述
+
+若命令带 `--from-issue=#N`，按 [_issue.md 的 Issue 拉取规范](./_issue.md#issue-拉取规范) 拉取 issue，把 issue 标题 + 正文拼成用户描述传入步骤 1。
+
+本命令不创建需求文档，issue 编号通过**分支名 `-iN` 后缀**持久化（步骤 3 创建分支时追加），供 `/req:commit`、步骤 5 关闭 issue 等后续操作识别。参见 [_issue.md 的 Issue 与分支关联](./_issue.md#issue-与分支提交的关联)。
+
+### 1. AI 分析意图
+
+根据用户描述，AI 判断任务类型和规模：
+
+```
+分析：<用户描述>
+
+  类型：<优化 | 重构 | 升级 | 规范 | 小功能 | 修复>
+  规模：<轻量（无需文档）| 中等（建议创建 QUICK）| 正式（建议创建 REQ）>
+  影响范围：<涉及的模块/文件数估算>
+```
+
+**类型判断依据：**
+
+| 类型 | 关键词/特征 | 分支前缀 | 提交前缀 |
+|------|-----------|---------|---------|
+| 优化 | 性能、缓存、索引、查询慢、加速 | `improve/` | `优化` |
+| 重构 | 重构、拆分、抽取、整理、解耦 | `improve/` | `重构` |
+| 升级 | 升级、更新、迁移、版本 | `improve/` | `构建` |
+| 规范 | 统一、规范、格式、命名、lint | `improve/` | `样式` |
+| 小功能 | 增加、新增、添加、支持 | `feat/` | `新功能` |
+| 修复 | 修复、bug、报错、异常、失败 | `fix/` | `修复` |
+
+**规模判断依据：**
+
+| 规模 | 条件 | 建议流程 |
+|------|------|---------|
+| 轻量 | 改动 < 5 个文件，无新 API/表结构 | 直接执行（本命令） |
+| 中等 | 改动 5~15 个文件，或有新 API | 建议 `/req:new-quick` |
+| 正式 | 改动 > 15 个文件，涉及多模块/新业务 | 建议 `/req:new` |
+
+**规模为中等或正式时**：
+```
+此任务规模较大，建议使用正式流程以便追踪：
+
+  /req:new-quick <标题>    有文档记录的轻量任务
+  /req:new <标题>          正式需求（含评审、测试）
+
+继续用轻量模式执行，还是切换到上述命令？
+```
+
+等待用户选择。用户选择继续 → 进入步骤 2。
+
+### 2. 分析代码，生成方案
+
+> 读取项目 CLAUDE.md 的「项目架构」章节，了解分层结构和目录布局。
+
+AI 搜索代码库，定位相关文件：
+
+```
+代码分析：
+
+涉及文件：
+
+| 文件 | 改动类型 | 说明 |
+|------|---------|------|
+| internal/order/store/order_store.go | 修改 | 添加查询索引 |
+| internal/order/biz/order_list.go | 修改 | 增加分页缓存逻辑 |
+| internal/order/model/order_model.go | 修改 | 补充索引注解 |
+
+修改方案：
+
+1. order_model.go
+   - Order 表 `status` + `created_at` 添加复合索引
+
+2. order_store.go
+   - ListOrders 查询增加 hint 走索引
+   - 添加 count cache（5 分钟 TTL）
+
+3. order_list.go
+   - 首页查询结果缓存（Redis，按筛选条件 key）
+
+是否按以上方案执行？（可以补充说明或调整方向）
+```
+
+**等待用户确认**。用户可以：
+- 确认方案 → 进入步骤 3
+- 补充/调整 → AI 重新分析
+- 放弃 → 结束
+
+### 3. 执行方案
+
+**无 `--from-issue`**：直接在当前分支上开发，不创建新分支。
+
+**有 `--from-issue=#N`**：在步骤 2 方案确认后、开始编码前，根据分支策略创建分支：
+1. 读取 `branchStrategy`（未配置则使用默认前缀）
+2. 分支前缀由步骤 1 的类型判断决定（见类型判断依据表的「分支前缀」列）
+3. AI 根据 issue 标题生成英文 slug
+4. 分支名末尾追加 `-i<N>`（参见 [_issue.md 的 Issue 与分支关联](./_issue.md#issue-与分支提交的关联)）
+5. 示例：`fix/optimize-order-query-i42`、`feat/add-search-feature-i12`
+
+AI 按确认的方案修改代码。
+
+### 4. 完成提示
+
+```
+✅ 完成！
+
+修改文件：
+- internal/order/store/order_store.go（+25 -3）
+- internal/order/biz/order_list.go（+40 -5）
+- internal/order/model/order_model.go（+2 -0）
+
+后续操作：
+- /req:commit       提交代码
+- /req:pr           创建 PR
+```
+
+若来自 `--from-issue=#N`，在后续操作提示中追加：
+```
+提交时建议在 commit message 末尾添加 closes #N 以自动关联 issue
+```
+
+### 5. （可选）关闭 issue
+
+仅当命令带 `--from-issue=#N` 时执行本步骤。
+
+在步骤 4 展示完成提示后，询问用户：
+
+```
+本次任务来自 issue #N
+   是否关闭该 issue？(y/n)
+```
+
+**用户确认（y）** → 按 `repoType` 关闭 issue，逻辑同 [issue.md §5](./issue.md)。
+
+**用户拒绝（n）**：跳过。
+
+---
+
+## 与其他命令的区别
+
+| 命令 | 文档 | 分支 | AI 分析 | 适用场景 |
+|------|------|------|--------|---------|
+| `/req:do` | 无 | 自动选前缀 | 分析意图+方案 | 优化、重构、升级、小调整 |
+| `/req:fix` | 无 | `fix/` | 定位 bug | 明确的 bug 修复 |
+| `/req:new-quick` | QUICK 文档 | `fix/` | 无 | 需要记录的小任务 |
+| `/req:new` | REQ 文档 | `feat/` | 需求分析 | 正式业务需求 |
+
+**选择依据：**
+- 知道是 bug → `/req:fix`
+- 优化/重构/升级/规范化 → `/req:do`
+- 需要文档记录 → `/req:new-quick`
+- 正式业务功能 → `/req:new`
+- 不确定用哪个 → `/req:do`（AI 帮你判断）
+
+---
+
+## 用户输入
+
+$ARGUMENTS

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

@@ -0,0 +1,95 @@
+---
+name: done
+description: |
+  完成需求 - 标记完成并归档
+---
+
+# 完成需求
+
+标记需求为已完成，归档文档。
+
+> 存储路径和缓存同步规则见 [_storage.md](./_storage.md)
+>
+> **CLI 优先级**：GitHub 走 `gh`；Gitea 按 [`_gitea_cli.md`](./_gitea_cli.md) 检测 `tea`，可用即走 `tea pulls create` / `tea issues close`，否则回退本文 curl 示例。
+
+## 命令格式
+
+```
+/req:done [REQ-XXX]
+```
+
+- 省略编号时自动选择「测试中」的需求
+- 多个候选时交互式选择
+
+---
+
+## 执行流程
+
+### 1. 选择需求
+
+- 指定编号 → 使用该需求
+- 未指定 → 扫描 `active/` 中状态为「测试中」的需求，唯一则直接使用，多个则列出让用户选
+
+### 2. 前置检查
+
+- 读取需求文档 YAML 元信息 + 「测试要点」章节
+- 状态必须为「测试中」，否则报错退出
+- 若测试要点中存在未勾选项（`- [ ]`），展示警告并要求用户确认继续
+
+### 3. 更新需求文档
+
+修改 YAML 元信息：
+- `status: 已完成`
+- `completedAt: YYYY-MM-DD`（今日）
+
+勾选生命周期「已完成」对应的复选框。
+
+### 4. 更新 PRD 索引
+
+定位 `docs/requirements/PRD.md` 的「需求追踪」章节（`grep -n "需求追踪"`），更新对应需求所在行的「状态」和「完成日期」两列。PRD 不存在或无该章节时跳过。
+
+### 5. 归档文档 + 同步缓存
+
+将需求文档从 `active/` 移动到 `completed/`（使用 `git mv` 保留历史）。缓存同步由 PostToolUse Hook 自动处理，无需命令内显式调用。
+
+### 6. 输出确认
+
+```
+REQ-XXX <标题> 已完成
+   归档至 docs/requirements/completed/REQ-XXX-<slug>.md
+```
+
+### 7. 分支合并提醒
+
+读取 `.claude/settings.local.json.branchStrategy` 和需求文档的 `branch` 字段。无 `branchStrategy` 或 `branch` 为空 → 跳过本步。
+
+按 `repoType` 创建 PR，逻辑同 [pr.md](./pr.md)（push + 创建 PR + 提示 review-pr）。
+
+**特殊情况**：
+- `giteaToken` 缺失 → 提示手工 compare 链接
+- Git Flow + hotfix 分支 → 需合并到 `main` 和 `develop` 两处，创建两个 PR
+
+### 8. 关联 issue 关闭提醒
+
+按 [_issue.md 的 Issue 读取优先级](./_issue.md#issue-编号的读取优先级) 获取 issue 编号：先查需求文档元信息 `issue` 字段，若为 `-` 或为空则查分支名 `-iN` 后缀。均未找到 → 跳过本步。
+
+否则询问用户：
+
+```
+检测到关联 issue: #123
+   是否关闭该 issue？(y/n)
+```
+
+**用户确认（y）** → 按 `repoType` 关闭 issue，逻辑同 [issue.md §5](./issue.md)。
+
+**用户拒绝（n）**：跳过。
+
+---
+
+## 与 `/req:release` 的区别
+
+`/req:done` 只做归档，不发版。发版用 `/req:release`（合并 SQL / 生成 changelog / 打 tag / 创建 Release）。
+
+## 用户输入
+
+$ARGUMENTS

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

@@ -0,0 +1,187 @@
+---
+name: edit
+description: |
+  编辑需求 - 修改已有需求文档
+---
+
+# 编辑需求
+
+编辑已有需求文档，仅修改内容，不触发开发流程。
+
+> 存储路径和缓存同步规则见 [_storage.md](./_storage.md)
+
+## 命令格式
+
+```
+/req:edit [REQ-XXX]
+```
+
+- 省略编号时自动选择最近活跃的需求
+- 多个候选时让用户选择
+
+---
+
+## 执行流程
+
+### 1. 选择需求
+
+- 指定编号 → 使用该需求
+- 未指定 → 查找活跃需求（按修改时间排序）
+- 本地不存在时从缓存读取
+
+### 2. 读取模板
+
+**必须先读取对应类型的模板文件**，作为格式基准：
+
+```
+正式需求（REQ-XXX）：
+  1. 本地模板：docs/requirements/templates/requirement-template.md
+  2. 插件模板：<plugin-path>/templates/requirement-template.md
+
+快速修复（QUICK-XXX）：
+  1. 本地模板：docs/requirements/templates/quick-template.md
+  2. 插件模板：<plugin-path>/templates/quick-template.md
+```
+
+**两个路径都不存在时，终止操作**：
+```
+❌ 未找到对应类型的模板文件
+
+请执行 /req:update-template <requirement|quick> 恢复模板
+```
+
+读取后解析模板的完整章节结构，编辑时**必须严格保持模板中的所有章节、层级和格式**。
+
+### 3. 功能扩展判断
+
+如果用户意图是**新增功能点**（而非修改已有内容），先判断是否应新建 REQ：
+
+```
+检测到您要新增功能点
+
+核心问题：去掉这个功能点，原需求还能独立交付吗？
+
+- 能独立交付 → 建议执行 /req:new 创建新需求，在关联信息中引用当前 REQ
+- 不能独立交付 → 继续在当前 REQ 中补充
+```
+
+**自动判断规则：**
+- 原 REQ 已 `已完成` → 必须新建，提示用户执行 `/req:new`
+- 原 REQ 在 `开发中`/`测试中` 且新功能影响已写代码 → 建议新建，避免范围蔓延
+- 新功能是原需求的自然延伸 → 继续编辑
+
+> 详细规则见 [_granularity.md](./_granularity.md) 「已有需求的功能扩展」
+
+### 4. 状态提示
+
+如果需求已在开发中或测试中：
+
+```
+⚠️ 警告：需求 REQ-XXX 当前状态为「开发中」
+修改需求可能影响已完成的开发工作。
+```
+
+### 5. 选择编辑章节
+
+询问用户要编辑的内容：
+
+```
+请选择要编辑的章节：
+1. 需求描述
+2. 功能清单
+3. 业务规则
+4. 使用场景
+5. 数据模型
+6. 接口需求
+7. 文件改动清单
+8. 实现步骤
+9. 测试要点
+10. 全部重新分析
+
+请输入编号（可多选，如 1,2,4）：
+```
+
+> 编辑 1（需求描述）或 4（使用场景）后，AI 会自动重新生成功能清单和业务规则。
+
+### 6. 交互式编辑
+
+根据选择进入对应章节的编辑模式：
+- 展示当前内容
+- 与用户多轮讨论修改方向和细节，**不限讨论轮数**
+- **意图澄清**：分析用户真实意图，用户说改 A 但实际应改 B 时主动指出并确认
+- **关联分析**：修改某章节可能导致其他章节不一致时，主动提示是否一并修改
+- 用户明确确认修改内容后（如"可以了"、"就这样改"），再进入变更预览
+
+**格式约束（强制）：**
+- 仅修改用户选择的章节内容，不得改变章节结构
+- 章节标题、编号、层级必须与模板完全一致
+- 不得新增、删除、合并或重命名模板中的章节
+- 表格结构（列名、列数）必须与模板一致
+- 即使某章节内容为空或占位文本，也不得删除该章节
+
+### 7. 变更预览
+
+修改内容写入文档前，向用户展示变更摘要：
+
+```
+变更预览
+
+【将修改的章节】：
+- 使用场景：新增"批量导入"场景
+
+【未修改的章节】：
+- 需求描述、功能清单、业务规则...（保持不变）
+```
+
+> 只修改用户明确要求的章节，严禁擅自修改其他章节内容。
+
+### 8. 变更影响分析
+
+如果需求已在开发中，分析变更影响：
+
+```
+变更影响分析
+
+修改内容：
+- 接口需求：新增渠道关联能力
+
+影响评估：
+- 直接影响：Controller、API 层需要修改
+- 间接影响：前端需配合调整
+
+受影响文件：
+- internal/sys/controller/v1/sys_dept.go
+- pkg/api/core/v1/sys_dept.go
+
+建议：完成当前开发后再进行变更
+```
+
+### 9. 保存并同步缓存
+
+- 更新「变更记录」章节
+- 写入本地文件
+- **同步到全局缓存**
+
+### 10. 输出结果
+
+```
+✅ 需求已更新：REQ-XXX
+路径：docs/requirements/active/REQ-XXX-标题.md
+缓存：已同步
+
+下一步：
+- /req:edit REQ-XXX - 继续编辑
+- /req:review - 提交评审
+```
+
+---
+
+## 注意事项
+
+- 编辑不会改变需求状态
+- 已开发的需求变更需谨慎
+- 所有变更都会记录到变更历史
+
+## 用户输入
+
+$ARGUMENTS