@zhouhao4221/devflow-skills 0.2.0 → 0.3.0

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

@@ -0,0 +1,237 @@
+---
+name: issue
+description: |
+  Issue 工作流 - 创建/编辑/关闭/列表/查看/评论 issue
+---
+
+# Issue 工作流
+
+统一管理 GitHub / Gitea issue 的全生命周期：创建、编辑、关闭、重开、列表、查看、评论。
+
+> 不受仓库角色限制，readonly 也可执行。不触发缓存同步。
+>
+> **CLI 优先级**：GitHub 走 `gh`；Gitea 按 [`_gitea_cli.md`](./_gitea_cli.md) 检测 `tea`，可用即走 `tea`，否则回退 curl。`tea` 不支持的操作（评论列表、标签增删等）始终走 curl。
+
+---
+
+## 子命令路由
+
+| 参数 | 功能 |
+|------|------|
+| `new` | 创建 issue |
+| `edit` | 修改字段 |
+| `close` | 关闭（可附留言） |
+| `reopen` | 重开 |
+| `list` | 列出 |
+| `show` | 查看详情和评论 |
+| `comment` | 添加或列出评论 |
+| 无 / `help` | 打印摘要并终止 |
+
+issue 编号支持 `#42` 和 `42` 两种写法。所有子命令都先执行前置检查。
+
+---
+
+## §1 前置检查
+
+读取 `.claude/settings.local.json` 的 `branchStrategy`：
+
+| repoType | 要求 | 失败时 |
+|---------|------|-------|
+| `gitea` | `giteaUrl` + `giteaToken` 非空；检测 `tea` 可用性 | 提示执行 `/req:branch init` 后终止 |
+| `github` | `gh` CLI 已安装 | 提示安装 gh 后终止 |
+| `other` / 未配置 | 无 | 写操作输出手动提示；list/show 报错 |
+
+OWNER/REPO 从 `git remote get-url origin` 解析，支持 SSH 和 HTTPS 格式，见 [_issue.md](./_issue.md#ownerrepo-解析)。
+
+---
+
+## §2 共用行为
+
+### 2.1 关联需求
+
+写操作可自动附需求上下文。`--req=REQ-XXX` 显式指定，未指定时从当前分支名提取（匹配 `REQ-\d+` / `QUICK-\d+`）。命中后读需求文档，提取元信息（标题/类型/模块/状态）和功能清单首段作摘要。
+
+### 2.2 标签匹配
+
+**禁止硬编码中英文对照表**，始终从仓库拉取真实 labels 再匹配。
+
+匹配顺序：完全匹配（忽略大小写）→ 去空格/连字符/下划线后匹配 → 子串包含。
+
+无匹配时询问是否在仓库创建该标签；用户拒绝则跳过，不终止。
+
+### 2.3 指派人解析
+
+从仓库协作者列表匹配，匹配策略同 §2.2。`@me` 自动解析为当前登录用户（GitHub 原生支持，Gitea 需先 `GET /user`）。无匹配时跳过，不终止。
+
+### 2.4 JSON 安全
+
+**禁止字符串拼接构造 JSON**，含引号、换行、反斜杠的文本必须用 `python3 -c 'import json,sys; print(json.dumps(sys.stdin.read()))'` 或 `jq -Rs` 转义后再传入请求体。
+
+### 2.5 错误处理
+
+| 错误 | 提示 |
+|------|------|
+| 401 / 403 | 鉴权失败，检查 giteaToken 或 gh auth status |
+| 404 | Issue 不存在或仓库路径错误 |
+| 422 | 回显 API message 字段，标出不合法字段 |
+| 423 locked | Issue 已锁定，无法评论/编辑 |
+| curl 非 0 | 请求失败，检查网络后重试 |
+
+### 2.6 `--auto` 模式
+
+检测 `.claude/.req-auto` 且 mtime < 10 分钟时跳过交互确认。`new` 强制预览，不受影响。
+
+---
+
+## §3 new
+
+```
+/req:issue new <标题> [--body=] [--labels=a,b] [--assignees=u1,u2] [--req=REQ-XXX]
+```
+
+**正文生成**：有 `--body` 直接用；无则 AI 生成含「问题描述/复现步骤/预期行为/实际行为/环境信息」的结构化模板，环境信息从 `git branch --show-current` 和 `git rev-parse --short HEAD` 取值。关联需求时在末尾用 `---` 分隔附加需求上下文。
+
+**防误关闭**：正文含 `closes #N` / `fixes #N` 时警告，确认后再提交。
+
+**强制预览**，不受 `--auto` 影响：
+
+```
+Issue 草稿：
+  仓库：owner/repo (gitea)
+  标题：登录超时后 token 未清除
+  标签：bug, authentication
+  指派：@haiqing
+  关联：REQ-001
+
+  正文（前 10 行）：...
+
+  是否提交？(y/n/e - 编辑某字段)
+```
+
+`e` 可选择修改字段，改完回到预览。
+
+成功输出：
+
+```
+✅ Issue 已创建
+  <url>
+  #170 登录超时后 token 未清除
+
+/req:fix --from-issue=#170   创建修复
+/req:new --from-issue=#170   创建正式需求
+```
+
+---
+
+## §4 edit
+
+```
+/req:issue edit #N [--title=] [--body=] [--add-labels=] [--remove-labels=] [--assignees=]
+```
+
+无字段参数时展示当前状态并提示可用字段，不修改。
+
+**Gitea 限制**：labels 必须走独立端点（`POST /labels` 新增、`DELETE /labels/{id}` 逐个删除），不能通过 PATCH body 修改。title/body/assignees 走 PATCH。
+
+预览变更后提交，`--auto` 跳过预览。
+
+---
+
+## §5 close
+
+```
+/req:issue close #N [--comment=<留言>] [--reason=completed|not_planned]
+```
+
+**Gitea 执行顺序**：先发评论再改状态——评论失败不阻止关闭，关闭失败时评论已留痕。
+
+**Gitea 不支持 `--reason`**，首次遇到时静默忽略并提示一次（GitHub 专属字段）。
+
+---
+
+## §6 reopen
+
+```
+/req:issue reopen #N
+```
+
+无预览，直接执行。
+
+---
+
+## §7 list
+
+```
+/req:issue list [--state=open|closed|all] [--labels=] [--assignee=] [--limit=20] [--page=1]
+```
+
+**Gitea 注意**：`type=issues` 在部分版本未完全过滤 PR，需客户端二次过滤 `pull_request != null` 的条目。limit 上限 50。
+
+输出格式：
+
+```
+Open issues @owner/repo（第 1 页 / 20 条）
+
+  #    状态   标题                          标签       指派      更新
+  
+  170  open   登录超时后 token 未清除        bug        @haiqing  2h
+  165  open   导出 Excel 中文乱码            bug, 紧急  -         1d
+
+/req:issue list --page=2
+```
+
+---
+
+## §8 show
+
+```
+/req:issue show #N
+```
+
+拉取 issue 主体和全部评论，渲染格式：
+
+```
+Issue #170 登录超时后 token 未清除
+  状态：open  作者：@haiqing（2026-04-15 14:32）
+  标签：bug   指派：@haiqing
+
+正文 
+...
+
+评论（共 3 条）
+[1] @alice（15:01）  我能复现。
+[2] @haiqing（16:22）已定位到 src/interceptors/request.ts:45
+
+/req:issue comment 170 <文本>
+```
+
+---
+
+## §9 comment
+
+```
+/req:issue comment #N <评论文本>
+/req:issue comment #N --list
+```
+
+`--list` 仅渲染评论列表，不显示 issue 主体。
+
+add 模式：关联需求时评论末尾附需求摘要（用 `---` 分隔）。预览后提交，`--auto` 跳过预览。
+
+---
+
+## 与其他命令的分工
+
+| 场景 | 命令 |
+|------|------|
+| 从 issue 派生需求 | `/req:new --from-issue=#N` |
+| 从 issue 派生修复 | `/req:fix --from-issue=#N` |
+| 从 issue 派生任务 | `/req:do --from-issue=#N` |
+| 需求完成时关闭 issue | `/req:done` / `/req:fix` 结束时询问 |
+| commit 自动关联 | message 末尾加 `closes #N` |
+
+---
+
+## 用户输入
+
+$ARGUMENTS

package/plugins/req/skills/issue-guide/SKILL.md

@@ -0,0 +1,125 @@
+---
+name: issue-guide
+description: |
+  Issue 操作引导助手。在执行 /req:issue 命令，或需要创建/查看/关闭 GitHub/Gitea
+  issue 时触发。提供平台检测、标签匹配、JSON 安全处理等关键约束。
+---
+
+# Issue 操作引导助手
+
+在执行任何 issue 相关操作时激活，确保平台差异、数据安全和交互一致性。
+
+---
+
+## 一、前置：读取平台配置
+
+所有操作开始前，读取 `.claude/settings.local.json` 的 `branchStrategy`：
+
+| 字段 | 用途 |
+|------|------|
+| `repoType` | `github` / `gitea` / `other` — 决定使用哪套 CLI |
+| `giteaUrl` | Gitea 实例地址（**必须从配置读取，禁止从 git remote 猜测**） |
+| `giteaToken` | Gitea API Token |
+
+**OWNER/REPO 解析**：从 `git remote get-url origin` 提取，去掉 `.git` 后缀取最后两段路径。支持 SSH（`git@host:owner/repo.git`）和 HTTPS（`https://host/owner/repo.git`）。
+
+**未配置时**：提示执行 `/req:branch init`，终止操作。
+
+---
+
+## 二、CLI 优先级
+
+| 平台 | 优先 | 回退 |
+|------|------|------|
+| GitHub | `gh` | — |
+| Gitea | `tea`（先检测可用性） | `curl + giteaToken` |
+
+`tea` 不支持的操作（评论列表、标签增删）始终走 `curl`。
+
+---
+
+## 三、关键约束
+
+### 3.1 JSON 安全（必须遵守）
+
+**禁止字符串拼接构造 JSON**。含引号、换行、反斜杠的文本必须转义后再传入请求体：
+
+```bash
+# 方法 A：python3
+python3 -c 'import json,sys; print(json.dumps(sys.stdin.read()))' <<< "$body"
+
+# 方法 B：jq
+echo "$body" | jq -Rs .
+```
+
+### 3.2 标签匹配
+
+**禁止硬编码中英文对照表**，始终从仓库拉取真实 labels 再匹配：
+
+1. 完全匹配（忽略大小写）
+2. 去空格/连字符/下划线后匹配
+3. 子串包含匹配
+
+无匹配时：询问用户是否在仓库创建该标签；拒绝则跳过（不终止操作）。
+
+### 3.3 Gitea labels 限制
+
+Gitea 的 labels **不能**通过 PATCH body 修改，必须走独立端点：
+- 新增：`POST /repos/{owner}/{repo}/issues/{index}/labels`
+- 删除：`DELETE /repos/{owner}/{repo}/issues/{index}/labels/{id}`（逐个删除）
+- title / body / assignees 走 `PATCH /repos/{owner}/{repo}/issues/{index}`
+
+### 3.4 指派人解析
+
+从仓库协作者列表匹配（策略同 §3.2）。`@me` 自动解析为当前登录用户（GitHub 原生支持，Gitea 需先 `GET /user`）。无匹配时跳过，不终止。
+
+### 3.5 Gitea list 过滤
+
+`GET /issues?type=issues` 在部分 Gitea 版本未完全过滤 PR，需客户端二次过滤掉 `pull_request != null` 的条目。limit 上限 50。
+
+---
+
+## 四、关联需求上下文
+
+写操作（new / edit / comment）可附需求摘要：
+
+- `--req=REQ-XXX` 显式指定
+- 未指定时从当前分支名提取（匹配 `REQ-\d+` / `QUICK-\d+`）
+- 命中后读需求文档，提取标题/类型/模块/状态和功能清单首段
+
+---
+
+## 五、new 操作 — 正文生成
+
+无 `--body` 时 AI 生成结构化模板，包含：
+
+- 问题描述 / 复现步骤 / 预期行为 / 实际行为
+- 环境信息：从 `git branch --show-current` 和 `git rev-parse --short HEAD` 取值
+
+**强制预览**（不受 `--auto` 影响）：展示草稿，等待用户 y/n/e 确认。
+
+成功后输出：
+```
+✅ Issue 已创建
+  🔗 <url>
+
+💡 /req:fix --from-issue=#N   创建修复
+💡 /req:new --from-issue=#N   创建正式需求
+```
+
+---
+
+## 六、close 操作 — Gitea 执行顺序
+
+先发评论 → 再改状态（评论失败不阻止关闭）。`--reason` 是 GitHub 专属字段，Gitea 静默忽略并提示一次。
+
+---
+
+## 七、与其他命令的分工
+
+| 需求 | 命令 |
+|------|------|
+| 从 issue 派生需求 | `/req:new --from-issue=#N` |
+| 从 issue 派生修复 | `/req:fix --from-issue=#N` |
+| 需求完成时关闭 issue | `/req:done` 结束时询问 |
+| commit 自动关联 | message 末尾加 `closes #N` |

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

@@ -0,0 +1,128 @@
+---
+name: migrate
+description: |
+  迁移需求 - 将本地需求迁移到全局缓存
+---
+
+# 迁移需求
+
+将本地 `docs/requirements/` 中的需求迁移到全局缓存。
+
+## 命令格式
+
+```
+/req:migrate <project-name> [--keep]
+```
+
+## 参数
+
+- `project-name`: 目标项目名称（必填）
+- `--keep`: 保留本地文件（可选，默认删除）
+
+---
+
+## 执行流程
+
+### 1. 前置检查
+
+`docs/requirements/active` 和 `completed` 均不存在时报错退出，提示使用 `/req:init`。统计本地活跃/已完成需求数量。
+
+### 2. 检查目标项目
+
+目标路径 `~/.claude-requirements/projects/<project-name>/`。项目不存在时自动创建；已存在且有需求文档时，询问合并策略：合并（编号冲突时重新编号）、覆盖、取消。
+
+### 3. 显示迁移预览
+
+```
+需求迁移预览
+
+源目录: docs/requirements/
+目标项目: <project-name>
+目标路径: ~/.claude-requirements/projects/<project-name>/
+
+迁移内容:
+- 活跃需求: X 个
+- 已完成需求: Y 个
+- 模板文件: 1 个
+
+文件列表:
+活跃需求:
+REQ-001-部门渠道关联.md
+REQ-002-用户积分系统.md
+REQ-003-订单导出优化.md
+
+已完成:
+REQ-000-初始化项目.md
+```
+
+### 4. 执行迁移
+
+将 active/、completed/、templates/（如存在）分别复制到目标项目对应目录。
+
+### 5. 处理编号冲突（合并模式）
+
+如果目标项目已有需求，检查编号冲突：
+
+```
+⚠️ 检测到编号冲突
+
+冲突列表:
+- REQ-001 (本地: 部门渠道关联 vs 远程: 用户管理)
+- REQ-002 (本地: 用户积分系统 vs 远程: 权限配置)
+
+处理方式:
+- REQ-001 → 保留远程，本地重命名为 REQ-004
+- REQ-002 → 保留远程，本地重命名为 REQ-005
+```
+
+### 6. 绑定当前仓库
+
+> 写入规范见 [_storage.md](./_storage.md#settingslocaljson-写入规范)。
+
+读取已有 `.claude/settings.local.json`，合并以下字段后写回（不覆盖已有的 `branchStrategy` 等字段）：
+
+```json
+{
+  "requirementProject": "<project-name>"
+}
+```
+
+### 7. 清理本地文件（默认行为）
+
+无 `--keep` 时删除本地 active/、completed/、templates/ 目录。指定 `--keep` 时保留并提示手动清理命令。
+
+### 8. 输出结果
+
+```
+✅ 迁移完成！
+
+迁移统计:
+- 迁移活跃需求: X 个
+- 迁移已完成需求: Y 个
+- 重新编号: Z 个
+
+新位置: ~/.claude-requirements/projects/<project-name>/
+
+当前仓库已绑定到项目 "<project-name>"
+
+下一步:
+- 查看需求列表: /req
+- 在其他仓库绑定: /req:use <project-name>
+```
+
+---
+
+## 错误处理
+
+| 错误场景 | 处理方式 |
+|---------|---------|
+| 本地无需求 | 提示使用 `/req:init` |
+| 目标项目有冲突 | 提供合并策略选择 |
+| 权限不足 | 提示检查目录权限 |
+| 迁移中断 | 回滚已迁移文件 |
+
+---
+
+## 用户输入
+
+$ARGUMENTS

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

@@ -0,0 +1,195 @@
+---
+name: modules
+description: |
+  模块管理 - 列出所有模块及其需求概览
+---
+
+# 模块管理
+
+列出所有模块及其关联的需求，支持创建和查看模块文档。
+
+## 命令格式
+
+```
+/req:modules [子命令] [模块名]
+```
+
+## 子命令
+
+| 子命令 | 说明 | 示例 |
+|--------|------|------|
+| (空) | 列出所有模块概览 | `/req:modules` |
+| `new` | 创建新模块文档 | `/req:modules new 用户模块` |
+| `show` | 查看模块详情 | `/req:modules show user` |
+
+---
+
+## 存储路径
+
+```
+<需求根目录>/
+modules/           # 模块文档目录
+  user.md       # 用户模块
+  order.md      # 订单模块
+  ...
+active/           # 进行中的需求
+completed/        # 已完成的需求
+INDEX.md          # 需求索引（自动生成）
+```
+
+---
+
+## 执行流程（列表模式）
+
+### 1. 扫描模块目录
+
+优先使用 `docs/requirements/modules/`；若已绑定项目则同时扫描 `~/.claude-requirements/projects/$PROJECT/modules/`。
+
+### 2. 解析模块文档
+
+从每个模块文档提取：
+- 模块名称
+- 核心功能数量
+- 关联需求列表及状态
+
+### 3. 扫描需求文档
+
+从需求元信息中提取模块字段，统计各模块的需求分布。
+
+### 4. 展示模块列表
+
+```
+模块概览
+
+| 模块 | 功能数 | 需求 | 开发中 | 已完成 |
+|------|--------|------|--------|--------|
+| 用户模块 | 8 | 5 | 1 | 4 |
+| 订单模块 | 12 | 8 | 2 | 6 |
+| 支付模块 | 6 | 3 | 0 | 3 |
+
+可用操作：
+- /req:modules show user - 查看用户模块详情
+- /req:modules new 新模块 - 创建新模块
+- /req --module=user - 筛选用户模块的需求
+```
+
+---
+
+## 创建模块（new）
+
+### 流程
+
+1. 检查模块是否已存在
+2. 从模板创建模块文档
+3. 引导填写模块信息
+
+### 示例
+
+```
+/req:modules new 积分模块
+```
+
+输出：
+
+```
+创建模块：积分模块
+
+已创建模块文档：docs/requirements/modules/points.md
+
+请完善以下信息：
+1. 模块概述 - 描述核心职责
+2. 业务规则 - 列出关键约束
+3. 关键文件 - 标注代码位置
+
+创建需求时可关联此模块：/req:new --module=积分模块
+```
+
+---
+
+## 查看模块详情（show）
+
+### 流程
+
+1. 读取模块文档
+2. 扫描关联需求的最新状态
+3. 展示模块完整信息
+
+### 示例
+
+```
+/req:modules show user
+```
+
+输出：
+
+```
+用户模块
+
+## 概述
+管理用户账户、认证、权限
+
+## 核心功能
+| 功能 | 需求 | 状态 |
+|------|------|------|
+| 注册登录 | REQ-001 | ✅ 已完成 |
+| 个人信息 | REQ-003 | ✅ 已完成 |
+| 密码重置 | REQ-007 | 开发中 |
+| 用户积分 | REQ-012 | 草稿 |
+
+## 业务规则
+- 手机号唯一
+- 密码至少 8 位
+- 积分有效期 1 年
+
+## 关键文件
+- internal/user/model/
+- internal/user/biz/
+- internal/user/controller/
+
+可用操作：
+- /req:dev REQ-007 - 继续开发密码重置
+- /req:new --module=用户模块 - 创建新需求
+```
+
+---
+
+## 与其他命令集成
+
+### /req:new
+
+创建需求时选择模块：
+
+```
+/req:new 用户积分系统 --module=用户模块,订单模块
+```
+
+或在创建过程中交互选择。
+
+### /req
+
+列出需求时按模块筛选：
+
+```
+/req --module=用户模块
+```
+
+### /req:done
+
+完成需求时自动更新模块文档的功能状态。
+
+---
+
+## 索引自动更新
+
+当以下操作发生时，自动更新 `INDEX.md`：
+
+- `/req:new` - 新增需求
+- `/req:done` - 完成需求
+- `/req:modules new` - 新增模块
+- 需求状态变更
+
+---
+
+## 用户输入
+
+$ARGUMENTS