@routerhub/agent-rules 1.5.203 → 1.5.205

package/AGENTS.base.md

@@ -133,8 +133,31 @@ agent-rules 生成的规则文件分两层，行为与归属不同，评审/发
 - ⚠️ **停用/归档任何仍可能被其他配置引用的共享资源（数据库、开关、服务实例、旧接口等）前，必须先确认所有引用方已经完成切换**，禁止先下线资源、后补救引用；正确顺序是「新资源就位 → 所有引用方切到新资源并验证 → 确认无引用后才下线旧资源」。
 - ⚠️ **对「只增不改」的追加型数据表（日志表、流水表）做分批消费时，禁止用「每次从头查 + LIMIT 截断 + 幂等去重」的无状态写法**。无断点的全量查询每次都会返回最早的一批行（早已消费、被幂等跳过、不产生任何效果），而新行永远排在 LIMIT 之外——扣款/同步在数据量超过单批上限后静默停滞，不报错、不崩溃，余额/进度「悄悄不涨不降」，是最阴险的静默 bug（offset-pagination 饥荒）。正确写法是带「进度断点」的增量查询：**按业务排序键（如时间+ID）记录上次消费位置（游标），下轮用 `WHERE 排序键 > 断点` 的严格排他下界续拉，消费成功后游标单调推进到批次末尾**，保证不重也不漏。判断标准：只要处理逻辑会「跳过已处理的记录」且「数据量可能超过单批上限」，就必须用游标/断点，而非从头扫。
 
+## ⚠️ 缺陷复现铁律（先复现，再动手改）
+
+- ⚠️ **核心认知：不复现就改 = 你不知道原来到底有没有这个问题、是不是这个原因。** 照着描述直接改代码，改完无法区分三种情况：① 真修好了；② 问题根本不在这、改动与真问题无关；③ 问题本来就不复现（描述有误 / 已被别的改动顺手修掉 / 环境或数据不同）。这三种情况从「改完看起来没事」里分辨不出来——**没有复现，「修好了」这句话就没有依据**。判断标准：**凡本次改动是为了修一个 bug / 故障 / 线上异常（而不是新增功能、重构、文案、依赖升级），动手改代码之前必须先复现；复现不出来不许改。**
+- ⚠️ **顺序是硬的，禁止颠倒：① 复现 → ② 留证并写下来 → ③ 改代码 → ④ 用同一条路径复验。** 跳过 ①② 直接 ③，就是拿「想象中的问题」当修复目标。
+- ⚠️ **复现必须在「改动前的代码」上做**（线上 / 测试环境当前版本，或打补丁前的那个 commit）。改完之后跑出来的现象证明不了改动前有同样的问题——**改完再回来说「我复现过了」不算数**。
+- ⚠️ **复现三要素缺一不可，这就是要「非常详细地写上去」的内容：**
+  1. **环境与版本**：哪个环境（生产 / 测试 / 本地）、哪个 commit 或 revision、用哪个账号 / 哪条数据（具体到 ID）；
+  2. **可被别人照着做的操作步骤**：点哪个按钮、发哪条请求（参数写全，禁止用 `...` 省略）、按什么顺序——**标准是别人拿到这几行就能一步步重演**，而不是只有你自己看得懂；
+  3. **观测到的坏现象**：报错原文、HTTP 状态码、日志片段、页面截图，带时间戳或 request id 之类可复查的标识。**「有时候会出问题」「偶尔失败」不合格——必须能指出出问题的是哪一次。**
+  - ⚠️ **这三要素的载体是下面那条「逐步截图 + 箭头标注」的可视化文档，不是三段纯文字**——文字是索引，截图才是能让别人跟着走一遍的东西。
+- ⚠️ **复现步骤与修复后的验证步骤必须是同一套——这是 A/B 对照能成立的唯一前提。** 同一条路径跑两遍：第一遍看到坏现象（A = 改动前），第二遍看到好现象（B = 改动后），两者之间只差你这次改动，这才证明了「是这个改动修好的」。两次走的路径不一样 = 没对照（详见「⚠️ 修复验证铁律」）。
+- ⚠️ **复现不出来 → 停下来回到描述方对口径，禁止「复现不出来那我按理解先改」。** 按描述的步骤复现不出来，说明「问题到底是什么」这件事本身还没对齐：可能理解错了现象、可能真正的触发入口是另一个、可能已经被别的改动修掉、可能环境或数据形态不同。此时正确动作是带着证据回去对齐——**「我按你说的步骤做了，看到的是 X 而不是 Y，能不能确认下当时的环境 / 账号 / 时间点」**——而不是照着自己想象改一遍交差。按想象改的后果：改动与真问题无关，PR 里却写着「已修复」，等用户再碰到时，这一轮排查和后面所有 review 全部白费。
+- ⚠️ **复现要用真实触发场景的数据和路径，禁止自己造一个顺手能触发的输入。** 造出来的输入只能复现你想象的那个问题，不是用户真实碰到的那个——真实数据的边界形态（空值、超长文本、特殊字符、异常关联、旧状态记录）恰恰是问题的来源（呼应「⚠️ 验证功能是否修复时，要用真实存在的数据/路径去测试」）。
+- ⚠️ **复现的交付物必须是「逐步截图 + 箭头标注」的可视化文档，不能只是一串文字步骤。** 文字步骤只说得清「点了什么」，说不清「点在哪、界面长什么样、坏现象出现在屏幕哪个位置」——看的人得自己在心里拼图，拼错了就以为复现不出来，或者以为自己复现的是另一回事。正确做法：**每一步一张截图，图上用箭头 + 短标签标出「这一步点哪里 / 填什么 / 坏现象出现在哪」**，让人照着走一遍就等于把 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）；③ 用户明确说「不用复现，直接改」——按用户指令执行，但交付时必须说明本次跳过了复现。
+
 ## ⚠️ 修复验证铁律
 
+- ⚠️ **本铁律管「改之后」，「改之前」见「⚠️ 缺陷复现铁律」——先复现拿到改动前的坏现象证据，改完用同一条路径复验，A/B 对照才成立。**
 - ⚠️ **验证方法必须"可确定性复现"，优先选最直白的路径。** 不要依赖真实流量、后台任务或时序巧合去凑出被验证的状态（反直觉、难复现、别人无法照做）。判断顺序：先问「本次修复的唯一改动是什么」，把它精确映射成一个可手动触发的原子操作，再做 A/B 对照。例：验证"余额变更后网关缓存立即失效"，不要靠真实计费请求养缓存，而是直接 `SET` 种一个已知值 → `GET`（有值 = 修复前）→ `DEL`（= 失效动作）→ `GET`（nil = 修复后）。
 - ⚠️ **报告开头必带一张「为什么这样验证成立」的原理说明卡。** 先讲清楚 bug 前后差异的本质是哪一个动作，再论证"手动模拟该动作 = 真实场景"，让不了解背景的人也能信服。配一张修复前 vs 修复后的 A/B 对照表（代码行为 / 等价操作 / 观测结果三列并排）。
 - ⚠️ **每个验证步骤必须三要素齐全**：① 怎么做的（可复制粘贴的完整命令）② 结果（含可复查标识：执行 ID、时间戳、返回码）③ 这一步证明了什么（一句话点明证据含义，如"DEL 返回 1 = 删除前 key 确实存在"）。

package/CHANGELOG.md

@@ -2,6 +2,32 @@
 
 所有对 @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
+
+- **新增「缺陷复现铁律（先复现，再动手改）」**：补上原有验证体系缺的一半——「⚠️ 修复验证铁律」管的是「改之后证明问题消失」，但没有任何规则要求「改之前先证明问题存在」。后果是照着描述直接改代码，改完分不清三种情况：① 真修好了；② 问题根本不在这、改动与真问题无关；③ 问题本来就不复现（描述有误 / 已被别的改动顺手修掉 / 环境数据不同）——**这三种从「改完看起来没事」里分辨不出来，没有复现，「修好了」就没有依据**。规则给出硬顺序（① 复现 → ② 留证并写下来 → ③ 改代码 → ④ 用同一条路径复验）、复现三要素（环境与版本 / 可被别人照着重演的操作步骤 / 带时间戳或 request id 的坏现象）、三条关键约束：**必须在改动前的代码上复现**（改完再补的不算）、**复现步骤与修复后验证步骤必须同一套**（否则 A/B 对照不成立）、**复现不出来必须回去对口径，禁止「按理解先改」**（按想象改 = 改动与真问题无关、PR 里却写着已修复）。另附与相邻两条铁律的分工（复现管改前 / 修复验证管改后 / 链路验收管整条链路，同一条路径在时间轴不同位置各跑一次）。
+- **PR 模板新增「缺陷复现」栏目**（置于 Description 之后）：修 bug / 修故障的 PR 必须填 ① 复现证据（改动前的代码上跑出来的：环境与版本、可重演步骤、带可复查标识的坏现象）② 用同一套步骤复验后坏现象消失；非修 bug 的（新增功能 / 重构 / 文案 / 依赖升级）勾选豁免项。Checklist 同步新增一项。**作用与「跨系统链路验收」栏目一致：把复现从「作者本机跑过一次」变成 PR 里留痕、reviewer 能看见并自己重跑一遍确认。**
+- `create-pr` skill 的 Description 模板新增「缺陷复现」段；`pr-release-loop` skill 完成定义清单新增一项（修 bug 的 PR 必须已填「缺陷复现」栏目）。
+
+### Changed
+
+- **`create-pr` skill 步骤 4 收紧「截修复前」的做法**：原文允许「临时回退代码 → 截图」得到修复前效果，但**修 bug 的 PR 这样做只是摆拍**——它证明的是「代码改回去长这样」，不是「用户当时遇到的就是这个」。现在明确：修 bug 的「修复前」截图必须来自在未改动代码上的真实复现（同时就是「缺陷复现」栏目的证据），回退代码截图仅用于把界面位置截对齐，不能替代复现。
+
 ## [1.5.203] - 2026-09-10
 
 ### Changed

package/PULL_REQUEST_TEMPLATE.md

@@ -7,6 +7,32 @@
 
 Closes #
 
+## 缺陷复现
+
+<!-- 仅「修 bug / 修故障 / 修线上异常」的 PR 需要填（新增功能、重构、文案、依赖升级直接勾豁免项）。
+     依据 AGENTS.base.md「⚠️ 缺陷复现铁律」：必须先复现、留证、写下来，再动手改。
+     ⚠️ 复现必须在【改动前的代码】上做（线上/测试环境当前版本，或打补丁前的 commit），改完再补的「复现」不算。
+     ⚠️ 本栏目是「摘要 + 链接」：完整的逐步截图走查放在 PR 顶部那份「详细实现文档」的「复现步骤」一节里。 -->
+
+- [ ] 本次 PR **不是**修 bug（新增功能 / 重构 / 文案 / 依赖升级），无需缺陷复现
+
+**① 复现证据（改动前的代码上跑出来的）**
+
+- **逐步截图走查（必填）**：详细实现文档「复现步骤」一节 → `<链接>`
+  - ⚠️ 必须**每一步一张截图 + 箭头标注**（标出「点哪里 / 填什么 / 坏现象在哪」），不是一串文字步骤；纯后端 bug 用暗色终端风格的请求响应截图。
+- **环境与版本**：<环境（生产/测试/本地） + commit 或 revision + 账号 / 数据 ID>
+- **操作步骤**（别人照着能一步步重演，禁止省略参数）：
+  1.
+  2.
+  3.
+- **观测到的坏现象**：<报错原文 / HTTP 状态码 / 日志片段 / 截图，带时间戳或 request id>
+  - ⚠️「偶尔会出问题」不合格——必须能指出出问题的是哪一次。
+
+**② 修复后用同一条路径复验**
+
+- [ ] 已用 ① 的**同一套步骤**重跑一遍，坏现象消失（两次路径不一致 = A/B 对照不成立）
+- **复验结果**：<改后观测到什么，同样带可复查标识>
+
 ## 跨系统链路验收
 
 <!-- 先判断是否命中 AGENTS.base.md「⚠️ 跨系统真实链路验收铁律」的 4 条触发条件（改动跨系统/跨仓库、新增默认值类字段、涉及金额/路由/权限/限流、新增表字段参与对外可见判定）。 -->
@@ -46,6 +72,7 @@ Closes #
 - [ ] 一个 PR 只做一件事，无夹带无关改动
 - [ ] Description 已说明 What / Why / How
 - [ ] Test Plan 完整且带证据
+- [ ] 修 bug 的 PR 已按「缺陷复现」栏目写下改动前的复现证据（非修 bug 的已勾选豁免项）
 - [ ] 跨系统链路验收已按上方栏目填完（未命中触发条件则勾选豁免项）
 - [ ] UI 改动已贴截图（或注明无界面变化）
 - [ ] 本地编译 / lint / 测试通过，CI 全绿

package/package.json

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

package/rules/global.md

@@ -133,8 +133,31 @@ agent-rules 生成的规则文件分两层，行为与归属不同，评审/发
 - ⚠️ **停用/归档任何仍可能被其他配置引用的共享资源（数据库、开关、服务实例、旧接口等）前，必须先确认所有引用方已经完成切换**，禁止先下线资源、后补救引用；正确顺序是「新资源就位 → 所有引用方切到新资源并验证 → 确认无引用后才下线旧资源」。
 - ⚠️ **对「只增不改」的追加型数据表（日志表、流水表）做分批消费时，禁止用「每次从头查 + LIMIT 截断 + 幂等去重」的无状态写法**。无断点的全量查询每次都会返回最早的一批行（早已消费、被幂等跳过、不产生任何效果），而新行永远排在 LIMIT 之外——扣款/同步在数据量超过单批上限后静默停滞，不报错、不崩溃，余额/进度「悄悄不涨不降」，是最阴险的静默 bug（offset-pagination 饥荒）。正确写法是带「进度断点」的增量查询：**按业务排序键（如时间+ID）记录上次消费位置（游标），下轮用 `WHERE 排序键 > 断点` 的严格排他下界续拉，消费成功后游标单调推进到批次末尾**，保证不重也不漏。判断标准：只要处理逻辑会「跳过已处理的记录」且「数据量可能超过单批上限」，就必须用游标/断点，而非从头扫。
 
+## ⚠️ 缺陷复现铁律（先复现，再动手改）
+
+- ⚠️ **核心认知：不复现就改 = 你不知道原来到底有没有这个问题、是不是这个原因。** 照着描述直接改代码，改完无法区分三种情况：① 真修好了；② 问题根本不在这、改动与真问题无关；③ 问题本来就不复现（描述有误 / 已被别的改动顺手修掉 / 环境或数据不同）。这三种情况从「改完看起来没事」里分辨不出来——**没有复现，「修好了」这句话就没有依据**。判断标准：**凡本次改动是为了修一个 bug / 故障 / 线上异常（而不是新增功能、重构、文案、依赖升级），动手改代码之前必须先复现；复现不出来不许改。**
+- ⚠️ **顺序是硬的，禁止颠倒：① 复现 → ② 留证并写下来 → ③ 改代码 → ④ 用同一条路径复验。** 跳过 ①② 直接 ③，就是拿「想象中的问题」当修复目标。
+- ⚠️ **复现必须在「改动前的代码」上做**（线上 / 测试环境当前版本，或打补丁前的那个 commit）。改完之后跑出来的现象证明不了改动前有同样的问题——**改完再回来说「我复现过了」不算数**。
+- ⚠️ **复现三要素缺一不可，这就是要「非常详细地写上去」的内容：**
+  1. **环境与版本**：哪个环境（生产 / 测试 / 本地）、哪个 commit 或 revision、用哪个账号 / 哪条数据（具体到 ID）；
+  2. **可被别人照着做的操作步骤**：点哪个按钮、发哪条请求（参数写全，禁止用 `...` 省略）、按什么顺序——**标准是别人拿到这几行就能一步步重演**，而不是只有你自己看得懂；
+  3. **观测到的坏现象**：报错原文、HTTP 状态码、日志片段、页面截图，带时间戳或 request id 之类可复查的标识。**「有时候会出问题」「偶尔失败」不合格——必须能指出出问题的是哪一次。**
+  - ⚠️ **这三要素的载体是下面那条「逐步截图 + 箭头标注」的可视化文档，不是三段纯文字**——文字是索引，截图才是能让别人跟着走一遍的东西。
+- ⚠️ **复现步骤与修复后的验证步骤必须是同一套——这是 A/B 对照能成立的唯一前提。** 同一条路径跑两遍：第一遍看到坏现象（A = 改动前），第二遍看到好现象（B = 改动后），两者之间只差你这次改动，这才证明了「是这个改动修好的」。两次走的路径不一样 = 没对照（详见「⚠️ 修复验证铁律」）。
+- ⚠️ **复现不出来 → 停下来回到描述方对口径，禁止「复现不出来那我按理解先改」。** 按描述的步骤复现不出来，说明「问题到底是什么」这件事本身还没对齐：可能理解错了现象、可能真正的触发入口是另一个、可能已经被别的改动修掉、可能环境或数据形态不同。此时正确动作是带着证据回去对齐——**「我按你说的步骤做了，看到的是 X 而不是 Y，能不能确认下当时的环境 / 账号 / 时间点」**——而不是照着自己想象改一遍交差。按想象改的后果：改动与真问题无关，PR 里却写着「已修复」，等用户再碰到时，这一轮排查和后面所有 review 全部白费。
+- ⚠️ **复现要用真实触发场景的数据和路径，禁止自己造一个顺手能触发的输入。** 造出来的输入只能复现你想象的那个问题，不是用户真实碰到的那个——真实数据的边界形态（空值、超长文本、特殊字符、异常关联、旧状态记录）恰恰是问题的来源（呼应「⚠️ 验证功能是否修复时，要用真实存在的数据/路径去测试」）。
+- ⚠️ **复现的交付物必须是「逐步截图 + 箭头标注」的可视化文档，不能只是一串文字步骤。** 文字步骤只说得清「点了什么」，说不清「点在哪、界面长什么样、坏现象出现在屏幕哪个位置」——看的人得自己在心里拼图，拼错了就以为复现不出来，或者以为自己复现的是另一回事。正确做法：**每一步一张截图，图上用箭头 + 短标签标出「这一步点哪里 / 填什么 / 坏现象出现在哪」**，让人照着走一遍就等于把 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）；③ 用户明确说「不用复现，直接改」——按用户指令执行，但交付时必须说明本次跳过了复现。
+
 ## ⚠️ 修复验证铁律
 
+- ⚠️ **本铁律管「改之后」，「改之前」见「⚠️ 缺陷复现铁律」——先复现拿到改动前的坏现象证据，改完用同一条路径复验，A/B 对照才成立。**
 - ⚠️ **验证方法必须"可确定性复现"，优先选最直白的路径。** 不要依赖真实流量、后台任务或时序巧合去凑出被验证的状态（反直觉、难复现、别人无法照做）。判断顺序：先问「本次修复的唯一改动是什么」，把它精确映射成一个可手动触发的原子操作，再做 A/B 对照。例：验证"余额变更后网关缓存立即失效"，不要靠真实计费请求养缓存，而是直接 `SET` 种一个已知值 → `GET`（有值 = 修复前）→ `DEL`（= 失效动作）→ `GET`（nil = 修复后）。
 - ⚠️ **报告开头必带一张「为什么这样验证成立」的原理说明卡。** 先讲清楚 bug 前后差异的本质是哪一个动作，再论证"手动模拟该动作 = 真实场景"，让不了解背景的人也能信服。配一张修复前 vs 修复后的 A/B 对照表（代码行为 / 等价操作 / 观测结果三列并排）。
 - ⚠️ **每个验证步骤必须三要素齐全**：① 怎么做的（可复制粘贴的完整命令）② 结果（含可复查标识：执行 ID、时间戳、返回码）③ 这一步证明了什么（一句话点明证据含义，如"DEL 返回 1 = 删除前 key 确实存在"）。

package/skills/create-pr/SKILL.md

@@ -40,6 +40,12 @@ git diff origin/main...HEAD --stat
 ## 改动
 （改了什么，采用什么方案）
 
+## 缺陷复现
+（⚠️ 仅修 bug / 修故障的 PR 必填，其余 PR 写「N/A（非修 bug）」。
+ 依据「⚠️ 缺陷复现铁律」：填的是【改动前的代码】上跑出来的复现证据——
+ 环境与版本 → 可被别人照着重演的操作步骤 → 观测到的坏现象（报错原文/状态码/日志/截图 + 时间戳或 request id），
+ 再附「用同一套步骤复验后坏现象消失」。这一步不做 = 不知道原来到底是不是这个问题。）
+
 ## 方案取舍
 （为什么选这个方案，考虑过什么替代方案）
 
@@ -58,6 +64,7 @@ Closes #issue编号
 1. **截修复后**：浏览器打开改动页面 → 滚动到改动区域 → 全页截图
 2. **截修复前**：临时注释/回退改动代码 → 等 hot reload → 同位置截图 → 恢复代码
    - ⚠️ **若线上数据已变化，导致无法在真实页面复现"修复前"效果**：允许改用等价的纯逻辑对比代替（用新旧两版逻辑代码跑同样的输入数据，把输出结果差异渲染成对比图），但必须在 Description 里明确写清楚"为什么无法复现 + 用了什么替代方案"，禁止因此省略截图或假装能复现。
+   - ⚠️ **修 bug 的 PR：这张"修复前"截图必须来自真实复现，不是回退代码摆拍出来的。** 正确做法是先按「⚠️ 缺陷复现铁律」在**未改动的代码**上复现出坏现象、截下这一张（它同时就是「缺陷复现」栏目的证据），再去改代码；回退代码截图只是辅助，**唯一目的是把同一处界面截得位置对齐**，不能替代复现——否则截图证明的只是"代码改回去长这样"，不是"用户当时遇到的就是这个"。无法在改动前复现的，按上一条写明原因，禁止默认走回退摆拍。
 3. **生成对比图**：用 `annotate.js`（截图标注统一脚本，见 `/screenshot-annotate` skill）拼接并标注 → 上方红/绿色标注条（❌修复前 / ✅修复后）→ 下方左右并排截图 → 关键改动区域用坐标精确换算后的箭头 + 红/绿框圈选
 4. **上传 GitHub CDN**（在 PR Description 编辑区直接上传）：
    - 打开目标 PR 页面 → 在 **Description 编辑区**直接上传图片（拖拽/粘贴，或定位 Description 编辑区的隐藏 `input[type=file]` 上传），GitHub 会自动把图片转成 `https://github.com/user-attachments/assets/...` 的 CDN 地址并插入 Description 正文，`![](CDN_URL)` 内嵌
@@ -79,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 主题相关的英文短名。
@@ -89,7 +97,7 @@ Closes #issue编号
    ```
    reviewer 建议以新标签页打开，看完细节再回 PR 正文。
 
-**适用范围**：所有 PR 一律附此链接，无例外；内容至少覆盖「改了什么、为什么改、每一步怎么改/怎么验证的」三部分。后续步骤 6 创建 PR 时，此链接已作为 body 第一条。
+**适用范围**：所有 PR 一律附此链接，无例外；内容至少覆盖「改了什么、为什么改、每一步怎么改/怎么验证的」三部分。⚠️ **修 bug / 修故障的 PR 还必须有第四部分「复现步骤」**——逐步截图 + 箭头标注的复现走查（见上方第 1 点）。后续步骤 6 创建 PR 时，此链接已作为 body 第一条。
 
 ### 6. 创建 PR
 
@@ -159,5 +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（非 Draft）**：PR 创建完成即进入可评审状态，可直接交付 review，禁止先开 Draft PR、后续再手动标记 Ready for review
 - 作者不能 Approve 自己的 PR

package/skills/pr-release-loop/SKILL.md

@@ -29,11 +29,12 @@ description: >-
   2. ✅ 最新代码已提交并推送到 PR 分支
   3. ✅ 已通过 `/deploy-test` 重新部署到测试环境（部署的是 review 之后的最终代码）
   4. ✅ 测试环境用真实数据 + 真实交互复测通过，**且命中的跨系统链路环节已按 `/real-chain-verify` 阶段 2 验完下游**（每张截图浏览器真实视口全页、箭头标注、URL 可见）
-  5. ✅ PR 描述里的「跨系统链路验收」栏目已填完（未命中触发条件的已勾选豁免项）
-  6. ✅ 与主分支无冲突（`gh pr view <PR> --json mergeable -q .mergeable` = `MERGEABLE`）
-  7. ✅ GitHub 静态编译通过（`gh pr checks <PR>` 无 `failure`）
-  8. ✅ PR 链接已发送给用户
-  9. ✅ 发新版本（`./release.sh`）
+  5. ✅ 修 bug 的 PR，PR 描述里的「缺陷复现」栏目已填完（改动前的复现证据 + 同一套步骤复验结果；非修 bug 的已勾选豁免项）
+  6. ✅ PR 描述里的「跨系统链路验收」栏目已填完（未命中触发条件的已勾选豁免项）
+  7. ✅ 与主分支无冲突（`gh pr view <PR> --json mergeable -q .mergeable` = `MERGEABLE`）
+  8. ✅ GitHub 静态编译通过（`gh pr checks <PR>` 无 `failure`）
+  9. ✅ PR 链接已发送给用户
+  10. ✅ 发新版本（`./release.sh`）
 - ⚠️ **循环 review 走完后，显式输出「✅ 循环 review 完成，进入发布收尾闭环」，然后逐项执行下面第 2～8 步，禁止在循环 review 结束后直接发链接/发版。** 若发现某一步没做（典型：忘了重新部署、复测是旧数据），必须停下来补齐再继续，禁止把「漏掉的第 3/4 步」带进交付。
 
 ## 核心流程