@routerhub/agent-rules 1.5.204 → 1.5.205

package/AGENTS.base.md

@@ -142,10 +142,15 @@ agent-rules 生成的规则文件分两层，行为与归属不同，评审/发
   1. **环境与版本**：哪个环境（生产 / 测试 / 本地）、哪个 commit 或 revision、用哪个账号 / 哪条数据（具体到 ID）；
   2. **可被别人照着做的操作步骤**：点哪个按钮、发哪条请求（参数写全，禁止用 `...` 省略）、按什么顺序——**标准是别人拿到这几行就能一步步重演**，而不是只有你自己看得懂；
   3. **观测到的坏现象**：报错原文、HTTP 状态码、日志片段、页面截图，带时间戳或 request id 之类可复查的标识。**「有时候会出问题」「偶尔失败」不合格——必须能指出出问题的是哪一次。**
+  - ⚠️ **这三要素的载体是下面那条「逐步截图 + 箭头标注」的可视化文档，不是三段纯文字**——文字是索引，截图才是能让别人跟着走一遍的东西。
 - ⚠️ **复现步骤与修复后的验证步骤必须是同一套——这是 A/B 对照能成立的唯一前提。** 同一条路径跑两遍：第一遍看到坏现象（A = 改动前），第二遍看到好现象（B = 改动后），两者之间只差你这次改动，这才证明了「是这个改动修好的」。两次走的路径不一样 = 没对照（详见「⚠️ 修复验证铁律」）。
 - ⚠️ **复现不出来 → 停下来回到描述方对口径，禁止「复现不出来那我按理解先改」。** 按描述的步骤复现不出来，说明「问题到底是什么」这件事本身还没对齐：可能理解错了现象、可能真正的触发入口是另一个、可能已经被别的改动修掉、可能环境或数据形态不同。此时正确动作是带着证据回去对齐——**「我按你说的步骤做了，看到的是 X 而不是 Y，能不能确认下当时的环境 / 账号 / 时间点」**——而不是照着自己想象改一遍交差。按想象改的后果：改动与真问题无关，PR 里却写着「已修复」，等用户再碰到时，这一轮排查和后面所有 review 全部白费。
 - ⚠️ **复现要用真实触发场景的数据和路径，禁止自己造一个顺手能触发的输入。** 造出来的输入只能复现你想象的那个问题，不是用户真实碰到的那个——真实数据的边界形态（空值、超长文本、特殊字符、异常关联、旧状态记录）恰恰是问题的来源（呼应「⚠️ 验证功能是否修复时，要用真实存在的数据/路径去测试」）。
-- ⚠️ **复现证据必须写进 PR 描述（PR 模板已内置「缺陷复现」栏目），不写等于没复现。** 这一栏是给 reviewer 看的：他据此判断「这个改动确实是对着这个现象去的」，也能自己照着重跑一遍确认修好了。只有作者本机跑过一次、PR 里一个字没有 = 这一环做了也没人知道。
+- ⚠️ **复现的交付物必须是「逐步截图 + 箭头标注」的可视化文档，不能只是一串文字步骤。** 文字步骤只说得清「点了什么」，说不清「点在哪、界面长什么样、坏现象出现在屏幕哪个位置」——看的人得自己在心里拼图，拼错了就以为复现不出来，或者以为自己复现的是另一回事。正确做法：**每一步一张截图，图上用箭头 + 短标签标出「这一步点哪里 / 填什么 / 坏现象出现在哪」**，让人照着走一遍就等于把 bug 亲手复现了一次。
+  - ⚠️ **落点：PR 顶部那份「详细实现文档」（截图版 HTML→PDF，见 `/create-pr` 步骤 5）里必须有「复现步骤」一节**，按步骤编号排开截图；PR 描述里的「缺陷复现」栏目放三要素摘要 + 指向该节的链接。**禁止只在 PR 里贴一段文字步骤就算交差。**
+  - ⚠️ **纯后端 / 无界面的 bug（接口、定时任务、数据链路等）同样要可视化**：把每一步的 curl 请求与响应渲染成暗色终端风格截图（带上请求 ID、时间戳），坏现象那一步单独放大标注——而不是贴一段文字日志。（取证方式见「非 UI / 后端 / 基础设施改动的效果截图获取方法」）
+  - ⚠️ **复现截图必须在「改代码之前」当场拍下并存盘**（遵循「⚠️ 截图规范」：浏览器真实视口、`fullPage` 全页、URL 可见、存到临时目录），不能等改完再写文档时回头补——那时代码已经变了，补出来的不是复现。箭头标注统一走 `/screenshot-annotate` skill（坐标由 `getBoundingClientRect()` 换算，禁止肉眼看图估位）。
+- ⚠️ **复现证据必须写进 PR（PR 模板已内置「缺陷复现」栏目），不写等于没复现。** 这一栏是给 reviewer 看的：他据此判断「这个改动确实是对着这个现象去的」，也能照着那份可视化文档自己重跑一遍确认修好了。只有作者本机跑过一次、PR 里一个字没有 = 这一环做了也没人知道。
 - **类比：看病。医生不会听你说一句「我头疼」就直接开止痛药——先做检查（复现）确认到底是什么病、是不是这个病，拿到检查报告（证据），再开药（改代码）。检查下来一切正常，那说明你说的「头疼」可能不是你以为的那个原因，得回去问清楚，而不是照着头疼开药；照着症状开药，病没治好，还耽误了真病因。**
 - ⚠️ **与相邻铁律的分工**：本铁律管「改之前证明问题存在」；「⚠️ 修复验证铁律」管「改之后证明问题消失」；「⚠️ 跨系统真实链路验收铁律」管「整条链路成不成立」。三者是**同一条路径**在时间轴上不同位置各跑一次：复现（改前）→ 复验（改后）→ 链路验收（上线前整条链路）。
 - ⚠️ **例外（可以不先复现的只有这几类，除此之外一律先复现）**：① 本次不是修 bug 的改动（新增功能、重构、文案、依赖升级）；② 问题现象本身已带完整证据（用户给的截图里有报错原文 + 时间戳 + 账号，等同于已复现——此时仍需按上面三要素把它整理成「可重演步骤」写进 PR）；③ 用户明确说「不用复现，直接改」——按用户指令执行，但交付时必须说明本次跳过了复现。

package/CHANGELOG.md

@@ -2,6 +2,20 @@
 
 所有对 @routerhub/agent-rules 的重大更改都会记录在这个文件中。
 
+## [1.5.205] - 2026-09-10
+
+### Changed
+
+- **「缺陷复现铁律」补齐可视化交付要求（原文只要求文字步骤，落地成了「一串文字 + 自己脑补界面」）**：发版后发现 1.5.204 的规则只说「把复现过程详写进 PR 描述」，没规定交付形态，结果是一段文字步骤——而**文字只说得清「点了什么」，说不清「点在哪、界面长什么样、坏现象出现在屏幕哪个位置」**，看的人得自己在心里拼图，拼错了就会以为「复现不出来」或以为自己复现的是另一回事。现在明确：**复现的交付物必须是「逐步截图 + 箭头标注」的可视化走查**——每一步一张截图，图上用箭头 + 短标签标出「这一步点哪里 / 填什么 / 坏现象出现在哪」，让人照着走一遍就等于把 bug 亲手复现了一次。
+  - **落点**：PR 顶部那份「详细实现文档」（截图版 HTML→PDF）里新增「复现步骤」一节承载完整走查；PR 描述里的「缺陷复现」栏目改为「三要素摘要 + 指向该节的链接」。**禁止只在 PR 里贴一段文字步骤就算交差。**
+  - **纯后端 / 无界面的 bug 同样要可视化**：每一步的 curl 请求与响应渲染成暗色终端风格截图（带请求 ID、时间戳），坏现象那一步单独放大标注，而不是贴一段文字日志。
+  - **复现截图必须在「改代码之前」当场拍下并存盘**：改完代码已经变了，回头补出来的不是复现；箭头标注统一走 `screenshot-annotate` skill（坐标由 `getBoundingClientRect()` 换算，禁止肉眼看图估位）。
+
+### Added
+
+- **PR 模板「缺陷复现」栏目的「① 复现证据」新增「逐步截图走查（必填，附链接）」项**，置于环境版本之前——先给可视化走查的入口，再给文字摘要。
+- **`create-pr` skill**：详细实现文档的适用范围从「至少覆盖三部分」扩为「**修 bug / 修故障的 PR 还必须多一部分『复现步骤』**」（逐步截图 + 箭头标注，后端 bug 用终端风格截图），并明确这些截图必须来自改代码之前的复现、不是改完回头补的。
+
 ## [1.5.204] - 2026-09-10
 
 ### Added

package/PULL_REQUEST_TEMPLATE.md

@@ -11,12 +11,15 @@ Closes #
 
 <!-- 仅「修 bug / 修故障 / 修线上异常」的 PR 需要填（新增功能、重构、文案、依赖升级直接勾豁免项）。
      依据 AGENTS.base.md「⚠️ 缺陷复现铁律」：必须先复现、留证、写下来，再动手改。
-     ⚠️ 复现必须在【改动前的代码】上做（线上/测试环境当前版本，或打补丁前的 commit），改完再补的「复现」不算。 -->
+     ⚠️ 复现必须在【改动前的代码】上做（线上/测试环境当前版本，或打补丁前的 commit），改完再补的「复现」不算。
+     ⚠️ 本栏目是「摘要 + 链接」：完整的逐步截图走查放在 PR 顶部那份「详细实现文档」的「复现步骤」一节里。 -->
 
 - [ ] 本次 PR **不是**修 bug（新增功能 / 重构 / 文案 / 依赖升级），无需缺陷复现
 
 **① 复现证据（改动前的代码上跑出来的）**
 
+- **逐步截图走查（必填）**：详细实现文档「复现步骤」一节 → `<链接>`
+  - ⚠️ 必须**每一步一张截图 + 箭头标注**（标出「点哪里 / 填什么 / 坏现象在哪」），不是一串文字步骤；纯后端 bug 用暗色终端风格的请求响应截图。
 - **环境与版本**：<环境（生产/测试/本地） + commit 或 revision + 账号 / 数据 ID>
 - **操作步骤**（别人照着能一步步重演，禁止省略参数）：
   1.

package/package.json

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

package/rules/global.md

@@ -142,10 +142,15 @@ agent-rules 生成的规则文件分两层，行为与归属不同，评审/发
   1. **环境与版本**：哪个环境（生产 / 测试 / 本地）、哪个 commit 或 revision、用哪个账号 / 哪条数据（具体到 ID）；
   2. **可被别人照着做的操作步骤**：点哪个按钮、发哪条请求（参数写全，禁止用 `...` 省略）、按什么顺序——**标准是别人拿到这几行就能一步步重演**，而不是只有你自己看得懂；
   3. **观测到的坏现象**：报错原文、HTTP 状态码、日志片段、页面截图，带时间戳或 request id 之类可复查的标识。**「有时候会出问题」「偶尔失败」不合格——必须能指出出问题的是哪一次。**
+  - ⚠️ **这三要素的载体是下面那条「逐步截图 + 箭头标注」的可视化文档，不是三段纯文字**——文字是索引，截图才是能让别人跟着走一遍的东西。
 - ⚠️ **复现步骤与修复后的验证步骤必须是同一套——这是 A/B 对照能成立的唯一前提。** 同一条路径跑两遍：第一遍看到坏现象（A = 改动前），第二遍看到好现象（B = 改动后），两者之间只差你这次改动，这才证明了「是这个改动修好的」。两次走的路径不一样 = 没对照（详见「⚠️ 修复验证铁律」）。
 - ⚠️ **复现不出来 → 停下来回到描述方对口径，禁止「复现不出来那我按理解先改」。** 按描述的步骤复现不出来，说明「问题到底是什么」这件事本身还没对齐：可能理解错了现象、可能真正的触发入口是另一个、可能已经被别的改动修掉、可能环境或数据形态不同。此时正确动作是带着证据回去对齐——**「我按你说的步骤做了，看到的是 X 而不是 Y，能不能确认下当时的环境 / 账号 / 时间点」**——而不是照着自己想象改一遍交差。按想象改的后果：改动与真问题无关，PR 里却写着「已修复」，等用户再碰到时，这一轮排查和后面所有 review 全部白费。
 - ⚠️ **复现要用真实触发场景的数据和路径，禁止自己造一个顺手能触发的输入。** 造出来的输入只能复现你想象的那个问题，不是用户真实碰到的那个——真实数据的边界形态（空值、超长文本、特殊字符、异常关联、旧状态记录）恰恰是问题的来源（呼应「⚠️ 验证功能是否修复时，要用真实存在的数据/路径去测试」）。
-- ⚠️ **复现证据必须写进 PR 描述（PR 模板已内置「缺陷复现」栏目），不写等于没复现。** 这一栏是给 reviewer 看的：他据此判断「这个改动确实是对着这个现象去的」，也能自己照着重跑一遍确认修好了。只有作者本机跑过一次、PR 里一个字没有 = 这一环做了也没人知道。
+- ⚠️ **复现的交付物必须是「逐步截图 + 箭头标注」的可视化文档，不能只是一串文字步骤。** 文字步骤只说得清「点了什么」，说不清「点在哪、界面长什么样、坏现象出现在屏幕哪个位置」——看的人得自己在心里拼图，拼错了就以为复现不出来，或者以为自己复现的是另一回事。正确做法：**每一步一张截图，图上用箭头 + 短标签标出「这一步点哪里 / 填什么 / 坏现象出现在哪」**，让人照着走一遍就等于把 bug 亲手复现了一次。
+  - ⚠️ **落点：PR 顶部那份「详细实现文档」（截图版 HTML→PDF，见 `/create-pr` 步骤 5）里必须有「复现步骤」一节**，按步骤编号排开截图；PR 描述里的「缺陷复现」栏目放三要素摘要 + 指向该节的链接。**禁止只在 PR 里贴一段文字步骤就算交差。**
+  - ⚠️ **纯后端 / 无界面的 bug（接口、定时任务、数据链路等）同样要可视化**：把每一步的 curl 请求与响应渲染成暗色终端风格截图（带上请求 ID、时间戳），坏现象那一步单独放大标注——而不是贴一段文字日志。（取证方式见「非 UI / 后端 / 基础设施改动的效果截图获取方法」）
+  - ⚠️ **复现截图必须在「改代码之前」当场拍下并存盘**（遵循「⚠️ 截图规范」：浏览器真实视口、`fullPage` 全页、URL 可见、存到临时目录），不能等改完再写文档时回头补——那时代码已经变了，补出来的不是复现。箭头标注统一走 `/screenshot-annotate` skill（坐标由 `getBoundingClientRect()` 换算，禁止肉眼看图估位）。
+- ⚠️ **复现证据必须写进 PR（PR 模板已内置「缺陷复现」栏目），不写等于没复现。** 这一栏是给 reviewer 看的：他据此判断「这个改动确实是对着这个现象去的」，也能照着那份可视化文档自己重跑一遍确认修好了。只有作者本机跑过一次、PR 里一个字没有 = 这一环做了也没人知道。
 - **类比：看病。医生不会听你说一句「我头疼」就直接开止痛药——先做检查（复现）确认到底是什么病、是不是这个病，拿到检查报告（证据），再开药（改代码）。检查下来一切正常，那说明你说的「头疼」可能不是你以为的那个原因，得回去问清楚，而不是照着头疼开药；照着症状开药，病没治好，还耽误了真病因。**
 - ⚠️ **与相邻铁律的分工**：本铁律管「改之前证明问题存在」；「⚠️ 修复验证铁律」管「改之后证明问题消失」；「⚠️ 跨系统真实链路验收铁律」管「整条链路成不成立」。三者是**同一条路径**在时间轴上不同位置各跑一次：复现（改前）→ 复验（改后）→ 链路验收（上线前整条链路）。
 - ⚠️ **例外（可以不先复现的只有这几类，除此之外一律先复现）**：① 本次不是修 bug 的改动（新增功能、重构、文案、依赖升级）；② 问题现象本身已带完整证据（用户给的截图里有报错原文 + 时间戳 + 账号，等同于已复现——此时仍需按上面三要素把它整理成「可重演步骤」写进 PR）；③ 用户明确说「不用复现，直接改」——按用户指令执行，但交付时必须说明本次跳过了复现。

package/skills/create-pr/SKILL.md

@@ -86,6 +86,7 @@ Closes #issue编号
 ⚠️ **每个 PR 的 Description 顶部必须附一条醒目的「详细实现文档」链接（截图版 HTML→PDF），把 PR 分成「快速浏览」与「详细展开」两层看**：PR 正文只承载 What / Why / Test Plan 精华 + 关键效果截图（几十秒看懂这次改了什么）；链接指向的 PDF 承载「做了什么 + 为什么这样做 + 每一步怎么做的」完整过程，并配上带箭头标注的真实截图。想深入细节的 reviewer 点开链接即看；禁止在正文里翻流水账，也禁止只有正文、缺详细文档链接。
 
 1. **汇总素材**：本 PR 的「改了什么 + 为什么改 + 每一步怎么改/怎么验证」，以及步骤 4 产出的全部效果截图（含修复前后对比）。
+   - ⚠️ **修 bug / 修故障的 PR，文档必须额外覆盖第四部分「复现步骤」**（依据「⚠️ 缺陷复现铁律」）：把复现时按步骤拍下的截图按编号排开，**每一步一张图 + 箭头标注出「这一步点哪里 / 填什么 / 坏现象出现在哪」**，让人照着走一遍就等于亲手复现了一次。⚠️ **纯后端 / 无界面的 bug 也要可视化**：每一步的 curl 请求与响应渲染成暗色终端风格截图（带请求 ID、时间戳），坏现象那一步单独放大标注。⚠️ 这些截图必须是**改代码之前**复现时当场存下来的，不是改完之后回头补的（改完代码变了，补出来的不是复现）。禁止只在 PR 描述里贴一段文字步骤就算交差。
    - ⚠️ **素材取材优先级：前端可视化优先，纯逻辑才退而用代码/接口图**：讲「改了什么、效果如何」时，**凡这个功能有真实前端页面承载的（如 routerhub-ui 的 admin / 用户平台等页面），必须用真实页面截图证明**——打开页面、真实数据操作、箭头标注出「这个功能在页面哪儿用、操作前后效果长什么样」，让人不写代码也能看懂；只有页面截不出来、纯后端逻辑（计费、限流、路由、数据链路等）的部分，才允许退而用代码截图 / curl 请求响应图 / 日志图代替。页面能截出来的就不许偷懒贴代码——前端可视化是最有说服力的证据，reviewer 要的是一眼看到改动效果，不是读代码猜。
 2. **生成截图版 HTML → 转 PDF**：走 `/create-doc` skill 输出自包含 HTML——截图一律 `data:image/png;base64` 内嵌并自动加箭头标注（遵循「⚠️ 截图规范」「⚠️ HTML 文档截图与 curl 命令规范」），图文逐步说明每一步怎么做的；再经无头 Chrome 转 PDF。
 3. **托管到私有文档仓库**：push 到该项目的 `<项目>-docs` 私有仓库 `docs` 分支（仓库名从 git remote 推导：`git@github.com:<ORG>/<项目>.git` → 文档仓库 `<ORG>/<项目>-docs`），文件名用与 PR 主题相关的英文短名。
@@ -96,7 +97,7 @@ Closes #issue编号
    ```
    reviewer 建议以新标签页打开，看完细节再回 PR 正文。
 
-**适用范围**：所有 PR 一律附此链接，无例外；内容至少覆盖「改了什么、为什么改、每一步怎么改/怎么验证的」三部分。后续步骤 6 创建 PR 时，此链接已作为 body 第一条。
+**适用范围**：所有 PR 一律附此链接，无例外；内容至少覆盖「改了什么、为什么改、每一步怎么改/怎么验证的」三部分。⚠️ **修 bug / 修故障的 PR 还必须有第四部分「复现步骤」**——逐步截图 + 箭头标注的复现走查（见上方第 1 点）。后续步骤 6 创建 PR 时，此链接已作为 body 第一条。
 
 ### 6. 创建 PR
 
@@ -166,6 +167,6 @@ gh pr checks <PR>
 - ⚠️ 每次修改 PR 后（含创建、push 新提交、响应 review 意见）都必须做三步收尾：冲突检查 → 静态编译检查 → PR 合并后发新版本（见步骤 8）
 - ⚠️ **创建完 PR 后必须自动走完整闭环流程（见步骤 7.5）**：创建 PR → 先做 CI 闸门检查并修复失败项 → **链路预演（命中跨系统链路验收触发条件时，在循环 review 之前先跑，只为尽早暴露需要大改的问题）** → 自动循环 review → 重新部署测试环境验证（全程截图 + 箭头标注，命中触发条件的走 `/real-chain-verify` 阶段 2）→ 确认没问题 → 发新版本，七步缺一不可，未走完不算完成
 - ⚠️ **PR 描述里必须填「跨系统链路验收」栏目**（PR 模板已内置）：命中 4 条触发条件的填链路预演链路图 + 下游真实生效证据 + 默认值对照；未命中的勾选豁免项。**留痕是给 reviewer 看的——不填等于这一环做了也没人知道。**
-- ⚠️ **PR 描述里必须填「缺陷复现」栏目**（PR 模板已内置）：修 bug / 修故障的 PR 必须填**改动前**的复现证据（环境版本 → 可重演步骤 → 坏现象 + 可复查标识）与「同一套步骤复验后坏现象消失」；非修 bug 的勾选豁免项。⚠️ **动手改代码之前就要先复现**——复现不出来先回去对口径，禁止「按理解先改、改完补个复现描述」。见「⚠️ 缺陷复现铁律」。
+- ⚠️ **PR 描述里必须填「缺陷复现」栏目**（PR 模板已内置）：修 bug / 修故障的 PR 必须填**改动前**的复现证据（环境版本 → 可重演步骤 → 坏现象 + 可复查标识）与「同一套步骤复验后坏现象消失」；非修 bug 的勾选豁免项。⚠️ **复现的交付物是「逐步截图 + 箭头标注」的可视化走查（放在详细实现文档的「复现步骤」一节），不是一串文字步骤**——文字说不清「点在哪、界面长什么样、坏现象在屏幕哪个位置」，看的人只能自己拼图。⚠️ **动手改代码之前就要先复现并当场存图**，改完再补的不算复现。见「⚠️ 缺陷复现铁律」。
 - ⚠️ **直接创建正式 PR（非 Draft）**：PR 创建完成即进入可评审状态，可直接交付 review，禁止先开 Draft PR、后续再手动标记 Ready for review
 - 作者不能 Approve 自己的 PR