@zhouhao4221/devflow-skills 0.2.0 → 0.3.1

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

@@ -0,0 +1,131 @@
+---
+name: new
+description: |
+  创建测试流程文档 - 多轮对话引导生成
+---
+
+# 创建测试流程文档
+
+> **Audience:** QA
+
+通过多轮对话收集测试场景，生成结构化的 flow 文档。
+
+## 命令格式
+
+```
+/uat:new [module]
+```
+
+---
+
+## 执行流程
+
+### 1. 确定模块名
+
+- 若参数已传入模块名，直接使用
+- 否则询问：`请输入测试模块名称（如：用户登录、商品搜索）`
+
+检查 `docs/uat/flows/<module>.md` 是否已存在：
+- 已存在 → 提示 `该模块已有测试文档，是否覆盖？(y/n)`
+- 不存在 → 继续
+
+### 2. 读取模板
+
+读取 `plugins/uat/templates/flow-template.md`，了解 flow 文档结构。
+
+### 3. 选择创建方式
+
+询问：
+
+```
+如何创建测试流程文档？
+  [1] 代码分析（扫描路由/表单/接口，自动推导场景）
+  [2] 手动描述（逐场景对话录入）
+```
+
+**选 [1] 代码分析**：
+
+扫描以下来源（自动检测，无需用户指定）：
+- 前端路由：`src/router/`, `src/routes/`, `router.ts`, `router.js`
+- 表单组件：`src/` 下含 `<form`/`<el-form`/`<a-form`/`<van-form` 的 `.vue`/`.tsx`/`.jsx`，提取字段名、类型、校验规则（required/maxlength/pattern）
+- API 接口文档：`openapi.yaml`, `swagger.json`, `docs/openapi.*`
+- 后端路由：FastAPI `@router.*`、Express `router.*`、Spring `@*Mapping`、Go Gin `r.GET/POST`
+
+根据扫描结果推导场景（列表页→浏览、含 POST 的表单→新增、含 PUT 的表单→编辑、含 DELETE→删除），展示候选列表后由用户确认或调整，再进入阶段一补充基本信息（平台/入口/测试数据）。
+
+生成的文档元信息 `生成方式` 填写 `代码分析（/uat:new）`，步骤中标注字段来源（如 `来源：CustomerForm.vue:38`）。
+
+**选 [2] 手动描述**：直接进入阶段一。
+
+---
+
+### 4. 多轮对话收集信息
+
+**阶段一：收集基本信息**
+
+依次询问：
+1. 平台：`web / desktop / mobile-web`（默认 web）
+2. 入口 URL 或路径
+
+**阶段二：收集全局信息**
+
+询问：
+1. 是否有全局测试数据？（账号、密码、通用字段值等）整理为 `测试数据` 表格。
+2. 是否有已知不通过 / 可跳过的路径？（如"接口已知返回 500 跳过"）整理为 `已知结论` 列表。
+
+**阶段三：逐轮收集测试场景**
+
+每轮询问：
+```
+请描述一个测试场景（输入"完成"结束）：
+- 场景名称？
+- 前置条件？（用户状态、页面状态等）
+- 场景类型？（新增 / 编辑 / 查询 / 删除 / 其他）
+- 是否需要数据准备？（手动提前创建 / 已有数据 / 不需要）
+- 若为「新增」场景：如何清理测试数据？（描述操作意图，如"找到该记录，点击删除"）
+- 操作步骤？（用自然语言描述做什么，不需要写选择器）
+  - 例：「在客户名称输入框输入「张三」」「点击保存按钮」「确认列表出现张三」
+  - 如果知道 data-testid 可以补充在括号里，如「点击保存按钮（testid: submit-btn）」
+- 预期结果？（用自然语言描述可观察到的状态）
+```
+
+AI 将用户描述整理为自然语言步骤，不强制写选择器。每收集完一个场景展示整理结果，询问 `是否继续添加场景？`。
+
+**用户说"完成"后**进入阶段四。
+
+**阶段四：表单边界 & 字符类型检测（自动触发）**
+
+分析已收集的场景，判断是否包含「输入框 / 表单提交」步骤：
+
+- **有表单输入** → 主动询问：
+  ```
+  检测到场景中有表单操作，建议补充「表单边界 & 字符类型」测试场景（覆盖空值、超长、特殊字符、XSS 等）。
+  是否添加？(y/n)
+  ```
+  - `y` → 逐字段引导：
+    1. 哪些字段需要测试？（逐一列出）
+    2. 每个字段的：最大/最小长度限制是多少？是否有字符类型约束（仅数字/仅中文等）？
+    3. 对空值/超长/特殊字符的预期行为是什么？（内联提示文字 / 截断 / 其他）
+    4. 按模板 `SXX 表单边界 & 字符类型` 生成对应场景，自动填充字段清单和字段约束
+  - `n` → 跳过，提示 `后续可手动编辑 flow 文档添加边界测试场景`
+
+- **无表单输入** → 跳过此阶段
+
+### 5. 生成文档
+
+严格按模板格式生成 `docs/uat/flows/<module>.md`：
+- 创建 `docs/uat/flows/` 目录（如不存在）
+- 场景 ID 按 S01、S02... 顺序编号
+- `测试数据` 和 `已知结论` 区块必须写入（无内容时保留空占位符）
+
+### 6. 输出
+
+```
+✅ 测试流程文档已创建
+
+docs/uat/flows/<module>.md
+场景数：3
+
+/uat:run <module>   立即执行测试
+直接编辑：docs/uat/flows/<module>.md
+```

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

@@ -0,0 +1,48 @@
+---
+name: report
+description: |
+  查看测试报告 - 展示最近一次执行结果
+---
+
+# 查看测试报告
+
+> **Audience:** QA
+
+读取并展示最近一次 `/uat:run` 生成的测试报告。
+
+## 命令格式
+
+```
+/uat:report [module]
+```
+
+- 省略模块名：列出所有模块的最新报告供选择
+- 指定模块名：直接展示该模块最新报告
+
+---
+
+## 执行流程
+
+### 1. 找到报告文件
+
+扫描 `docs/uat/reports/` 目录：
+- 找到匹配模块名的所有报告文件（格式：`YYYY-MM-DD-<module>.md`）
+- 取日期最新的一份
+
+若无报告文件：
+```
+❌ 暂无测试报告
+
+先执行 /uat:run <module> 生成报告
+```
+
+### 2. 展示报告
+
+直接展示报告文件内容（Markdown 格式，含汇总表和失败详情）。
+
+报告末尾追加操作提示：
+
+```
+/uat:bug   将失败项上报为 Gitea issue
+/uat:run   重新执行测试
+```

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

@@ -0,0 +1,78 @@
+---
+name: run
+description: |
+  执行 UAT 测试 - 按流程文档逐场景验收
+---
+
+# 执行 UAT 测试
+
+> **Audience:** QA
+
+读取测试流程文档，调用 uat-executor skill 逐场景执行，输出报告。
+
+> **运行环境要求**：操作方式为 `browser` 时，必须在 **Codex Chrome** 或 **Claude 桌面客户端** 中运行，否则无法调用浏览器工具。
+
+## 命令格式
+
+```
+/uat:run [module]
+```
+
+- 省略模块名：列出所有 flow 文档，提示用户选择
+- 指定模块名：直接执行对应 flow 文档
+
+---
+
+## 执行流程
+
+### 0. 前置检查：skill 是否已安装
+
+检查 `.claude/skills/uat-executor/SKILL.md` 是否存在：
+
+- 存在 → 继续
+- 不存在 → 终止并提示：
+
+```
+❌ uat-executor skill 未安装
+
+当前环境（Codex / Claude 桌面端）需要 skill 文件才能执行测试。
+请先在 Claude Code 中运行：/uat:init
+```
+
+### 1. 确定执行范围
+
+- 有参数 → 查找 `docs/uat/flows/<module>.md`
+- 无参数 → 列出所有 flow 文档，用户选择（支持"全部"）
+
+若 flow 文件不存在：
+```
+❌ 未找到测试流程文档：docs/uat/flows/<module>.md
+使用 /uat:new <module> 创建
+```
+
+### 2. 激活 uat-executor skill
+
+读取 flow 文档后，按 `.claude/skills/uat-executor/SKILL.md` 的指导执行：
+
+- 检查运行环境（browser 模式下确认浏览器工具可用）
+- 逐场景执行并记录结果
+
+### 3. 写入报告
+
+执行完毕后：
+1. 创建 `docs/uat/screenshots/` 目录（如不存在）
+2. 将报告写入 `docs/uat/reports/YYYY-MM-DD-<module>.md`（含「发现记录」节，若有发现项）
+3. 更新 flow 文档元信息的 `最后执行` 字段
+
+### 4. 输出汇总
+
+在终端展示执行汇总（格式见 uat-executor skill），并提示：
+
+```
+报告已保存：docs/uat/reports/YYYY-MM-DD-<module>.md
+
+/uat:report          查看完整报告
+/uat:bug             将失败项（代码 bug）上报为 issue
+```
+
+**注**：执行中发现流程文档描述有误时直接更新 `docs/uat/flows/<module>.md`，无需额外操作。

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

@@ -0,0 +1,64 @@
+---
+name: uat
+description: |
+  UAT 测试工作流 - 列出测试模块和上次执行状态
+---
+
+# UAT 测试工作流
+
+> **Audience:** QA
+
+列出所有测试流程模块及其上次执行状态。
+
+## 命令格式
+
+```
+/uat
+```
+
+## 子命令
+
+| 命令 | 说明 |
+|------|------|
+| `/uat:init` | 初始化 UAT 插件（首次使用必须执行） |
+| `/uat:new [module]` | 创建测试流程文档（对话录入或代码分析） |
+| `/uat:run [module]` | 执行测试（需 Codex Chrome 或 Claude 桌面端） |
+| `/uat:report` | 查看最近一次测试报告 |
+| `/uat:bug` | 将失败场景上报为 issue |
+
+---
+
+## 执行流程
+
+### 1. 扫描测试流程文档
+
+扫描 `docs/uat/flows/` 目录，读取所有 `*.md` 文件的元信息（模块名、操作方式、最后执行日期）。
+
+### 2. 扫描最近报告
+
+扫描 `docs/uat/reports/` 目录，找到每个模块最新的报告文件，提取通过/失败数。
+
+### 3. 输出
+
+```
+UAT 测试模块
+
+  模块              操作方式    最后执行      结果
+  
+  用户登录           browser    2026-05-12   ✅ 2/3
+  商品下单           browser    -            -（未执行）
+  支付接口           api        2026-05-10   ❌ 1/2
+
+共 3 个模块
+
+/uat:run <module>   执行测试
+/uat:new            创建新测试模块
+```
+
+若 `docs/uat/flows/` 不存在或为空：
+
+```
+暂无测试流程文档
+
+使用 /uat:new 创建第一个测试模块
+```

package/plugins/uat/skills/uat-executor/SKILL.md

@@ -0,0 +1,299 @@
+---
+name: uat-executor
+description: |
+  UAT 测试执行引导。在 /uat:run 命令时激活。
+  读取自然语言测试流程文档，理解每步操作意图，
+  根据当前环境选择最合适的工具和元素定位方式执行。
+  不依赖选择器前置，testid/aria-label 为可选加速提示。
+---
+
+# UAT 执行引导
+
+仅在 `/uat:run` 命令执行时激活。
+
+**核心原则**：读懂步骤的**意图**，自行决定用什么工具、怎么找到元素，不依赖 flow 文档预先写好的选择器。
+
+---
+
+## 一、执行前准备
+
+### 1. 读取 flow 文档
+
+```
+docs/uat/flows/<module>.md
+```
+
+解析以下字段：
+- `平台`：影响工具选择和元素定位方式
+- `入口`：初始 URL 或路径
+- `测试数据`：全局复用数据，执行时按字段名注入
+- `已知结论`：跳过列表，对应场景标记 SKIP
+- 所有 `S0N` 场景：步骤意图 + 预期结果
+
+### 2. 执行环境感知
+
+启动前检测当前可用工具，**不要求 flow 文档预先指定**：
+
+| 可用工具 | 优先用于 |
+|---------|---------|
+| `browser:browser` skill | web / mobile-web 平台，DOM 操作 |
+| 截图 + 视觉分析 | 任意平台的验证步骤（判断"显示正确"） |
+| Bash | CLI 工具、脚本、文件检查 |
+| 无工具 | 提示用户手动操作，Claude 旁观记录 |
+
+若 `平台=web` 但无 browser 工具：
+```
+⚠️  当前环境无浏览器工具，无法自动执行 web 测试
+💡  请在 Codex Chrome 或 Claude 桌面客户端运行 /uat:run
+    或将平台改为 desktop，手动操作后由 Claude 验证截图
+```
+
+---
+
+## 二、逐场景执行
+
+### 执行前：处理已知结论
+
+读取 `已知结论` 区块，命中场景直接标记 **SKIP**：
+
+```
+⏭ S02 <场景名> — SKIP（已知结论：手工新增接口返回 500）
+```
+
+### 执行前：注入 console error 监听（web 平台）
+
+在打开页面后、执行任何步骤前，通过 browser 工具注入以下脚本，收集整个场景过程中的 console error：
+
+```javascript
+window.__uatConsoleErrors = [];
+const _orig = console.error.bind(console);
+console.error = function(...args) {
+  window.__uatConsoleErrors.push(args.map(String).join(' '));
+  _orig(...args);
+};
+```
+
+每个场景结束后读取并清空 `window.__uatConsoleErrors`，作为该场景的附加信息。
+
+### 对每个场景 `S0N`，按以下流程执行：
+
+```
+1. 输出场景标题：▶ S01 <场景名称>
+2. 注入 console error 监听（web 平台，见上方）
+3. 数据准备：若有说明，提示用户手动准备后确认继续
+4. 检查前置条件
+5. 逐步理解并执行操作步骤（见三、意图驱动执行）
+6. 逐条验证预期结果（见六、断言策略）
+7. 读取 window.__uatConsoleErrors，记录本场景的 console error 列表
+8. 数据清理：若场景类型为「新增」，执行清理（见五）
+9. 记录结果（见下方结果判定规则）
+```
+
+### console error 结果判定
+
+| 步骤结果 | console error | 最终标记 | 说明 |
+|---------|--------------|---------|------|
+| PASS | 无 | ✅ PASS | 正常 |
+| PASS | 有 | ⚠️ PASS | 功能通过但有异常，需关注 |
+| FAIL | 无 | ❌ FAIL | 步骤/断言失败 |
+| FAIL | 有 | ❌ FAIL | 同上，console error 作为附加线索 |
+
+⚠️ PASS 不算失败，不触发截图，但会写入报告和工单。
+
+---
+
+## 三、意图驱动执行
+
+**步骤解析原则**：从自然语言步骤中提取三要素——操作类型、目标元素、目标值，再决定执行方式。
+
+### 操作类型映射
+
+| 步骤关键词 | 操作类型 | 执行方式 |
+|-----------|---------|---------|
+| 输入、填写、写入 | 文字输入 | 找到输入框 → 清空 → 输入 |
+| 点击、按下、选择 | 点击 | 找到目标元素 → 点击 |
+| 选择（下拉/级联） | 下拉选择 | 见下方浮层规则 |
+| 确认、检查、验证 | 断言 | 见六、断言策略 |
+| 等待、直到 | 等待 | 等指定条件成立 |
+
+### 元素定位优先级
+
+从步骤描述中提取定位线索，按优先级依次尝试：
+
+1. **testid 提示**：步骤中若有 `(testid: xxx)` → 直接用 `[data-testid="xxx"]`
+2. **语义角色**：按钮、输入框、表格、弹窗等角色 + 步骤中的文字描述
+   - 「保存按钮」→ 查找包含「保存」文字的 button 元素
+   - 「客户名称输入框」→ 查找 label 含「客户名称」的 input
+3. **aria-label / placeholder**：无障碍属性中含目标文字
+4. **上下文位置**：「列表中第一行的删除按钮」→ 定位到列表容器，取第一行，找删除操作
+5. **视觉截图兜底**：以上都找不到 → 截图发给 Claude 分析，识别目标元素位置
+
+**不要一开始就抓全页 DOM**。先用语义线索缩小范围，再精确定位。
+
+### 下拉 / 级联选择处理
+
+步骤写「在省市区选择框选择「广东省 → 广州市 → 天河区」」时，自动拆解为：
+
+```
+1. 找到省市区选择框（触发器），点击打开
+2. 等待选项列表出现（在 body 全局查找浮层，框架无关）
+3. 点击「广东省」，等待下一级列表加载
+4. 点击「广州市」，等待下一级列表加载
+5. 点击「天河区」，等待选择框显示值更新
+```
+
+**定位起点：先找字段，不找选项文本**
+始终先定位字段对应的输入框/触发器（按字段标签名），再操作。不要从页面全局搜索选项文本（如"专业运动"），因为同名文本可能出现在表格、标题、历史数据中。
+
+**浮层查找原则**：不在当前容器内查找，在 `body` 全局查找新出现的浮层元素（按组件库特征或新增 DOM 节点检测）。打开下拉后**只看新出现的浮层区域**，不再扫全页。
+
+**同名选项消歧**：若页面多处出现同名文字（如"专业运动"），真正要点的是**当前展开下拉菜单内**的那个。用"最近打开的浮层"限定范围，不要从全局 DOM 找第一个匹配。
+
+**优先键盘筛选**：下拉打开后，先尝试**直接输入选项名**等待列表过滤，再按回车或点击首个匹配项——比在长列表中滚动翻找更快。级联也可逐级尝试，但需确认组件支持。
+
+**避免 Esc 关闭下拉**：关闭浮层通过点击下一个字段或点击下拉外侧。Esc 在弹窗中可能关闭整个弹窗，造成意外中断。
+
+**页面记忆：字段顺序固定后不重新探索**
+第一次确认同一表单的字段顺序（如省市区、销售渠道、客户类型）后，后续用"第几个可见下拉"或"字段标签附近的控件"直接操作，不再每次重新扫描全页。
+
+**未命中重试**：点击选项后若选择框值未更新，等 300ms 后重试，最多 2 次，超过记为 ❌ FAIL。
+
+---
+
+## 四、等待策略
+
+不使用固定 sleep。根据步骤意图自动选择等待信号：
+
+| 操作后等什么 | 等待方式 | 超时 |
+|------------|---------|-----|
+| 点击提交后 | 等成功提示文字出现 或 URL 变化 或 弹窗关闭 | 10s |
+| 点击下拉触发器 | 等浮层出现（新 DOM 节点） | 5s |
+| 切换页面/路由 | 等 URL 变化 + 目标元素出现 | 10s |
+| 加载中 | 等 loading 指示消失 | 15s |
+| 无明确信号 | 等网络空闲（200ms 内无新请求） | 5s |
+
+---
+
+## 五、测试数据清理
+
+**判断场景类型**：标题或步骤含「新增 / 创建 / 添加 / 导入」→ 新增场景，需清理；含「编辑 / 修改 / 更新」→ 不清理。
+
+**清理方式**：读取 flow 文档的 `数据清理` 字段，按其描述操作：
+- 若写了 testid 提示 → 按 testid 定位删除按钮
+- 若写的是意图描述（如"找到「测试客户」这条记录，点击删除"）→ 按意图执行
+- 找不到目标 → 记录 `⚠️ 数据未清理，请手动删除`，不阻断报告
+
+---
+
+## 六、断言策略
+
+按预期结果的描述判断类型，自动选择验证方式：
+
+| 预期结果描述 | 验证方式 |
+|------------|---------|
+| 「XX 文字出现」/ 「显示 XX」 | 在页面中搜索目标文字 |
+| 「列表包含 XX 记录」 | 在列表容器中查找含目标文字的行 |
+| 「提示消失」/ 「弹窗关闭」 | 确认对应元素不在 DOM 中 |
+| 「跳转到 XX 页面」/ 「URL 为 XX」 | 检查当前 URL |
+| 「XX 不显示」/ 「不应存在」 | 确认目标元素不存在 |
+| 截图肉眼判断（视觉一致性） | 截图发 Claude 分析 |
+
+**截图策略**：**仅在步骤失败时截图**，通过步骤不截图。路径：`docs/uat/screenshots/YYYY-MM-DD-S0N-<step>.png`
+
+---
+
+## 七、表单边界 & 字符类型测试
+
+场景含「边界」或「字符」关键词，或有 `测试矩阵` 表格时，逐行执行：
+
+```
+对每一行（B1-B3 边界、C1-C7 字符）：
+  1. 找到目标字段（按字段清单中的名称定位）
+  2. 清空字段（全选删除）
+  3. 输入当前行的测试值
+  4. 点击提交，等待页面反馈
+  5. 对比实际结果与预期列：
+     - 边界行（B*）：预期出现内联错误提示，不提交
+     - 字符行（C*）：合法字符保存后展示不乱码、不执行脚本
+  6. 任一行不符合预期 → 记为 ❌ FAIL，截图，附行编号和实际结果
+```
+
+**XSS 补充验证**：C4 保存成功后，重新加载详情/列表页，确认字段展示为纯文本而非执行脚本。
+
+---
+
+## 八、执行中更新流程文档
+
+执行过程中，若发现实际行为与 flow 文档描述不符（步骤顺序、提示文本、字段名等），直接更新 `docs/uat/flows/<module>.md` 对应内容，不需要询问，继续执行后续场景。
+
+---
+
+## 九、结果输出格式
+
+### 终端汇总
+
+```
+═══════════════════════════════════
+  UAT 执行报告：<module>
+  执行时间：YYYY-MM-DD HH:mm
+═══════════════════════════════════
+  ✅ S01 正常登录           PASS
+  ❌ S02 密码错误提示        FAIL  表单未显示错误信息
+  ⚠️ S03 新增客户           PASS  1 个 console error
+  ⏭ S04 手工新增           SKIP  已知结论：接口 500
+───────────────────────────────────
+  通过：2   警告：1   失败：1   跳过：1   共 4
+═══════════════════════════════════
+```
+
+### 报告文件格式
+
+写入 `docs/uat/reports/YYYY-MM-DD-<module>.md`：
+
+```markdown
+# UAT 报告：<module>
+
+执行时间：YYYY-MM-DD HH:mm
+平台：web
+
+## 汇总
+
+| 场景 | 名称 | 结果 | Console Errors | 备注 |
+|------|------|------|---------------|------|
+| S01 | 正常登录 | ✅ PASS | - | - |
+| S02 | 密码错误提示 | ❌ FAIL | - | 表单未显示错误信息 |
+| S03 | 新增客户 | ⚠️ PASS | 1 个 | 见详情 |
+| S04 | 手工新增 | ⏭ SKIP | - | 已知结论：接口 500 |
+
+通过：2 · 警告：1 · 失败：1 · 跳过：1
+
+## 失败详情
+
+### S02 密码错误提示
+- **失败步骤**：步骤 3 - 点击登录后
+- **预期**：页面显示「密码错误」提示
+- **实际**：页面无任何提示，直接刷新
+- **截图**：docs/uat/screenshots/2026-05-12-S02-step3.png
+
+## Console Error 详情
+
+### S03 新增客户
+```
+TypeError: Cannot read properties of undefined (reading 'id')
+    at CustomerForm.vue:142
+```
+```
+
+更新 flow 文档元信息的 `最后执行` 字段为当前日期。
+
+### 有发现项时的「发现记录」节（见八）
+
+若有执行中发现项，在报告末尾写入「发现记录」表格。
+
+### 有 FAIL 时的后续提示
+
+```
+⚠️  发现 <N> 个失败场景
+
+💡 执行 /uat:bug 上报工单（自动创建 issue + 上传截图附件）
+```