@routerhub/agent-rules 1.5.188 → 1.5.189

package/AGENTS.base.md

@@ -142,6 +142,13 @@
     - 能 → 必须用真实页面交互验证，能模拟用户手动测试就手动，并截图留证；
     - 不能（纯后端接口、定时任务、无页面入口的链路）→ 用运行时真实返回验证（curl/日志/查库/查 Redis），并把结果渲染成可视化证据（暗色终端风格的请求/响应对比 HTML 截图，或 Redis/SQLTools 插件截图）。
 - ⚠️ **验证结论必须基于运行时真实数据，禁止用 mock/虚构数据自测。** 真实数据会暴露边界情况（空值、超长文本、特殊字符、异常关联关系等），虚构数据碰不到这些。测试环境有真实数据时优先用测试环境；测试环境数据不足时，从生产环境脱敏导出。
+- ⚠️ **分步操作教学演示（报告 = 可照做的操作手册，所有验证报告一律适用）**：验证报告正文里出现的每个可操作流程，必须录成「分步操作教学演示」——读者照报告点一遍就能完整复现操作、学会这个功能怎么用，禁止只贴过程/结果图、让读者猜中间步骤。硬性要求：
+  1. **按真实点击顺序逐步截图**：一个可执行步骤 = 一张图，按操作顺序排列，禁止把多个步骤压进一张图后靠文字补述；
+  2. **每张图标出「该点什么 / 看到什么」**：箭头 + 文字标注具体按钮位置与预期反馈，标注坐标必须来自 DOM 测量（`getBoundingClientRect()`），走 `/screenshot-annotate`；绿色 = 正确操作路径、红色 = 会被拒绝的错误姿势，让读者一眼看出「别这么点、该那么点」；
+  3. **图间配过渡说明**：每张 caption 讲清「上一步发生了什么 → 这一步点哪里 → 预期看到什么」，报告内按操作顺序成段排布，读者能跟着连点；
+  4. **逐张自检**：只看这张图 + 说明，能否照着点出下一步？能 = 合格；不能 = 补一张步骤图或补标注，直到整条流程读者不靠你就能走完。
+  - **类比**：交付报告像给菜谱——一道菜（一个功能）从备料到出锅（完整操作流程）必须给出「第 1 步切什么、第 2 步放多少油」的步骤图，读者照做能做出同一道菜；只贴一张成品照让读者猜过程，等于没教。
+  - 反面示例：演示「删不掉挂着映射的账户」，只贴「删除被拒」和「最终删除成功」两张图、不展示中间「打开 Models → Remove(Unbind) → 确认」的顺序，读者仍不知道卡住时该点哪里。
 
 ## Git 规范
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@routerhub/agent-rules",
-  "version": "1.5.188",
+  "version": "1.5.189",
   "description": "Shared Copilot agent rules and guidelines for RouterHub projects",
   "main": "AGENTS.base.md",
   "bin": {

package/rules/global.md

@@ -142,6 +142,13 @@ name: "通用规则"
     - 能 → 必须用真实页面交互验证，能模拟用户手动测试就手动，并截图留证；
     - 不能（纯后端接口、定时任务、无页面入口的链路）→ 用运行时真实返回验证（curl/日志/查库/查 Redis），并把结果渲染成可视化证据（暗色终端风格的请求/响应对比 HTML 截图，或 Redis/SQLTools 插件截图）。
 - ⚠️ **验证结论必须基于运行时真实数据，禁止用 mock/虚构数据自测。** 真实数据会暴露边界情况（空值、超长文本、特殊字符、异常关联关系等），虚构数据碰不到这些。测试环境有真实数据时优先用测试环境；测试环境数据不足时，从生产环境脱敏导出。
+- ⚠️ **分步操作教学演示（报告 = 可照做的操作手册，所有验证报告一律适用）**：验证报告正文里出现的每个可操作流程，必须录成「分步操作教学演示」——读者照报告点一遍就能完整复现操作、学会这个功能怎么用，禁止只贴过程/结果图、让读者猜中间步骤。硬性要求：
+  1. **按真实点击顺序逐步截图**：一个可执行步骤 = 一张图，按操作顺序排列，禁止把多个步骤压进一张图后靠文字补述；
+  2. **每张图标出「该点什么 / 看到什么」**：箭头 + 文字标注具体按钮位置与预期反馈，标注坐标必须来自 DOM 测量（`getBoundingClientRect()`），走 `/screenshot-annotate`；绿色 = 正确操作路径、红色 = 会被拒绝的错误姿势，让读者一眼看出「别这么点、该那么点」；
+  3. **图间配过渡说明**：每张 caption 讲清「上一步发生了什么 → 这一步点哪里 → 预期看到什么」，报告内按操作顺序成段排布，读者能跟着连点；
+  4. **逐张自检**：只看这张图 + 说明，能否照着点出下一步？能 = 合格；不能 = 补一张步骤图或补标注，直到整条流程读者不靠你就能走完。
+  - **类比**：交付报告像给菜谱——一道菜（一个功能）从备料到出锅（完整操作流程）必须给出「第 1 步切什么、第 2 步放多少油」的步骤图，读者照做能做出同一道菜；只贴一张成品照让读者猜过程，等于没教。
+  - 反面示例：演示「删不掉挂着映射的账户」，只贴「删除被拒」和「最终删除成功」两张图、不展示中间「打开 Models → Remove(Unbind) → 确认」的顺序，读者仍不知道卡住时该点哪里。
 
 ## Git 规范