@routerhub/agent-rules 1.5.202 → 1.5.204

package/AGENTS.base.md

@@ -133,8 +133,26 @@ 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 全部白费。
+- ⚠️ **复现要用真实触发场景的数据和路径，禁止自己造一个顺手能触发的输入。** 造出来的输入只能复现你想象的那个问题，不是用户真实碰到的那个——真实数据的边界形态（空值、超长文本、特殊字符、异常关联、旧状态记录）恰恰是问题的来源（呼应「⚠️ 验证功能是否修复时，要用真实存在的数据/路径去测试」）。
+- ⚠️ **复现证据必须写进 PR 描述（PR 模板已内置「缺陷复现」栏目），不写等于没复现。** 这一栏是给 reviewer 看的：他据此判断「这个改动确实是对着这个现象去的」，也能自己照着重跑一遍确认修好了。只有作者本机跑过一次、PR 里一个字没有 = 这一环做了也没人知道。
+- **类比：看病。医生不会听你说一句「我头疼」就直接开止痛药——先做检查（复现）确认到底是什么病、是不是这个病，拿到检查报告（证据），再开药（改代码）。检查下来一切正常，那说明你说的「头疼」可能不是你以为的那个原因，得回去问清楚，而不是照着头疼开药；照着症状开药，病没治好，还耽误了真病因。**
+- ⚠️ **与相邻铁律的分工**：本铁律管「改之前证明问题存在」；「⚠️ 修复验证铁律」管「改之后证明问题消失」；「⚠️ 跨系统真实链路验收铁律」管「整条链路成不成立」。三者是**同一条路径**在时间轴上不同位置各跑一次：复现（改前）→ 复验（改后）→ 链路验收（上线前整条链路）。
+- ⚠️ **例外（可以不先复现的只有这几类，除此之外一律先复现）**：① 本次不是修 bug 的改动（新增功能、重构、文案、依赖升级）；② 问题现象本身已带完整证据（用户给的截图里有报错原文 + 时间戳 + 账号，等同于已复现——此时仍需按上面三要素把它整理成「可重演步骤」写进 PR）；③ 用户明确说「不用复现，直接改」——按用户指令执行，但交付时必须说明本次跳过了复现。
+
 ## ⚠️ 修复验证铁律
 
+- ⚠️ **本铁律管「改之后」，「改之前」见「⚠️ 缺陷复现铁律」——先复现拿到改动前的坏现象证据，改完用同一条路径复验，A/B 对照才成立。**
 - ⚠️ **验证方法必须"可确定性复现"，优先选最直白的路径。** 不要依赖真实流量、后台任务或时序巧合去凑出被验证的状态（反直觉、难复现、别人无法照做）。判断顺序：先问「本次修复的唯一改动是什么」，把它精确映射成一个可手动触发的原子操作，再做 A/B 对照。例：验证"余额变更后网关缓存立即失效"，不要靠真实计费请求养缓存，而是直接 `SET` 种一个已知值 → `GET`（有值 = 修复前）→ `DEL`（= 失效动作）→ `GET`（nil = 修复后）。
 - ⚠️ **报告开头必带一张「为什么这样验证成立」的原理说明卡。** 先讲清楚 bug 前后差异的本质是哪一个动作，再论证"手动模拟该动作 = 真实场景"，让不了解背景的人也能信服。配一张修复前 vs 修复后的 A/B 对照表（代码行为 / 等价操作 / 观测结果三列并排）。
 - ⚠️ **每个验证步骤必须三要素齐全**：① 怎么做的（可复制粘贴的完整命令）② 结果（含可复查标识：执行 ID、时间戳、返回码）③ 这一步证明了什么（一句话点明证据含义，如"DEL 返回 1 = 删除前 key 确实存在"）。
@@ -217,8 +235,14 @@ agent-rules 生成的规则文件分两层，行为与归属不同，评审/发
   - ❌ **把「门户页面全绿」当「链路跑通」**——页面是本系统的回显，跑通是下游真的接住了。
   - ❌ **把「循环 review 全过」当「功能成立」**——review 审的是代码有没有缺陷，管不了「这套组合在真实系统里行不行」。
   - ❌ **把「部署成功 + 截图」当「验收完成」**——部署证明代码上线了，不证明功能用得了。
-- ⚠️ **与循环 review 的分工（两者不可互相替代）**：**循环 review 保证「代码没有明显缺陷」（静态、看 diff）；本流程保证「功能在真实系统里真的成立」（动态、看运行）。** 循环 review 走完只说明「代码层面没问题了」，此时**必须**继续走跨系统真实链路验收，禁止在 review 收敛后直接发链接 / 发版。
-- ⚠️ **具体操作流程见 `/real-chain-verify` skill**（怎么画链路、每类系统怎么取证、证据怎么组织成报告）。
+- ⚠️ **与循环 review 的分工（两者不可互相替代）**：**循环 review 保证「代码没有明显缺陷」（静态、看 diff）；本流程保证「功能在真实系统里真的成立」（动态、看运行）。**
+- ⚠️ **执行时机：拆成两段，禁止合并成一次（顺序错了会白跑 review）。**
+  - **阶段 1「链路预演」——创建 PR 后、循环 review 之前，轻量。** 只回答两件事：**这条链路成不成立、需求口径对不对**。产出只要「链路图 + 每个环节能不能通」的判断，**不写 6 段报告、不做截图箭头标注、不出交付文档**（约为阶段 2 的 20~30% 工作量）。
+  - **阶段 2「链路验收」——循环 review 收敛、重新部署之后，完整。** 走完整取证、6 段报告与截图标注，作为交付证据。
+  - ⚠️ **为什么必须两段而不是一次**：本流程要暴露的四类问题（跨仓库语义 / 需求口径 / 默认值×存量 / 精度临界）**修复代价都是「大改」**（改需求、改默认值、改 schema、改交互），而 review 修的是「代码写得对不对」（小改）。**把大改的发现压到最后，等于先用 N 轮把一个可能要推翻重做的东西打磨到没有代码缺陷，再发现它根本不该这么做**——review 成果直接作废，改完还得重跑 review。真实案例：PR #158 的问题 B 是需求口径反转（09-04 要求拦截 → 09-08 改成顺带清绑定）、问题 C 要改默认值并和存量数据对齐，两者都会让前面已 review 通过的代码整体作废。
+  - ⚠️ **为什么阶段 2 不能提前到 review 之前**：验的必须是「最终要发布的那个版本」。review 会 push 新 commit，提前验完的代码后面会被改，那次证据直接作废、还得再验一遍。阶段 2 的位置是硬的，只能压在最后。
+  - ⚠️ **不命中触发条件的改动，两段都不走**（纯文案、纯展示类改动不受影响）。
+- ⚠️ **具体操作流程见 `/real-chain-verify` skill**（怎么画链路、每类系统怎么取证、两段各自做到什么程度、证据怎么组织成报告）。
 
 ## Git 规范
 
@@ -290,10 +314,11 @@ agent-rules 生成的规则文件分两层，行为与归属不同，评审/发
 1. **与主分支冲突检查**：按上一条规则执行（`gh pr view <PR> --json mergeable -q .mergeable`），有冲突必须先解决。
 2. **GitHub 静态编译检查**：用 `gh pr checks <PR>` 查看 CI 检查状态（`success`=通过，`failure`=失败，`pending`=进行中）。存在失败项时，必须定位失败根因、修改代码并重新推送，直到全部通过，禁止把静态编译未通过的 PR 抛给 reviewer。
 3. **发新版本**：PR 合并后按项目发布流程发布新版本（本项目统一执行根目录 `./release.sh`，自动完成 patch 版本号 +1、更新 package.json、`git commit`/`push`、打 tag、`npm publish`）。
-- ⚠️ **创建完 PR 后自动走完整闭环流程，未走完不算完成**：创建 PR → 循环 review → 重新部署测试环境验证 → 确认没问题 → 发 PR 链接给用户 → 发新版本，六步缺一不可，全程自动执行：
+- ⚠️ **创建完 PR 后自动走完整闭环流程，未走完不算完成**：创建 PR → **链路预演** → 循环 review → 重新部署测试环境验证 → 确认没问题 → 发 PR 链接给用户 → 发新版本，七步缺一不可，全程自动执行：
+0. **先走「链路预演」（在循环 review 之前，轻量）**：PR 创建后**立刻**判断是否命中「⚠️ 跨系统真实链路验收铁律」的 4 条触发条件。命中 → 触发 `/real-chain-verify` 的**阶段 1**：只画链路、逐环节快速过一遍，回答「**这条链路成不成立、需求口径对不对**」，**不写 6 段报告、不做截图标注**（约阶段 2 的 20~30% 工作量）。⚠️ **这一步的目的是尽早暴露「需要大改」的问题**（需求口径反转、默认值不对、跨仓库语义不成立、schema 要改）——**大改放在 review 之后发现，等于前面 N 轮 review 全白跑**。发现需大改 → 先改完再进循环 review，禁止带着「可能推翻重做」的设计去跑 review。未命中 → 本步跳过，直接进第 1 步，并在 PR 描述里勾选豁免项。
 1. **自动走循环 review**：创建完 PR 后自动触发 `/loop-review` skill，反复「拉取 AI review（Claude Opus + GPT 交叉验证）→ 逐条读真实代码判断哪些值得修 → 值得修的改、不值得修/误报的 Won't fix 切断 → push 触发新一轮 review」，直到某一轮不再冒出值得修的新问题才结束，禁止只跑一轮就收工。**循环 review 走完后，必须显式输出「✅ 循环 review 完成，进入发布收尾闭环」，并调用 `/pr-release-loop` skill 走完后续步骤。**
 2. **重新部署到测试环境（循环 review 后最容易漏掉的一步）**：循环 review 走完后，自动触发 `/deploy-test` skill，把最新代码重新部署到测试环境，确保测试的是循环 review 之后的最终代码。⚠️ **循环 review 期间每次修复都会 push 新 commit；不重新部署 = 测试环境跑的还是 review 之前的旧代码 = 用旧代码验证新改动 = 结论无效。因此循环 review 结束后禁止直接发 PR 链接 / 发版，必须先 `/deploy-test` 重部署。**
-3. **测试环境验证 + 全程截图标注**：在测试环境用真实数据、真实页面交互测试本次改动（遵循「⚠️ 页面功能验证铁律」「⚠️ 用户视角测试铁律」）。测试过程中每一步都截图保留（遵循「⚠️ 截图规范」：真实视口 + `fullPage` 全页、URL 可见、存盘到 `screenshots/` 临时目录），并在每张截图上用**坐标换算后的箭头标注**（走 `/screenshot-annotate` skill）关键改动区域/验证点，让看的人一眼看懂这张图证明了什么。
+3. **测试环境验证 + 全程截图标注**：在测试环境用真实数据、真实页面交互测试本次改动（遵循「⚠️ 页面功能验证铁律」「⚠️ 用户视角测试铁律」）。测试过程中每一步都截图保留（遵循「⚠️ 截图规范」：真实视口 + `fullPage` 全页、URL 可见、存盘到 `screenshots/` 临时目录），并在每张截图上用**坐标换算后的箭头标注**（走 `/screenshot-annotate` skill）关键改动区域/验证点，让看的人一眼看懂这张图证明了什么。⚠️ **命中「⚠️ 跨系统真实链路验收铁律」触发条件的，本步即该铁律的「阶段 2 链路验收」**：按 `/real-chain-verify` 走完整取证与 6 段报告，把阶段 1 画出的链路逐环节补上下游可观测事实与下游真实生效证据（阶段 1 只判「通不通」，本步必须交出「下游留下了什么痕迹」）。
 4. **确认没问题才算完成**：测试通过、截图与箭头标注齐全、功能符合预期，才算真正完成。禁止测试没跑、截图没标注就宣称完成。
 5. **把 PR 链接发给用户**：确认没问题后，先把 PR 链接发送给用户（`gh pr view <PR> --json url -q .url`），让用户能直接打开查看，再执行发版。
 6. **发新版本**：确认没问题、PR 链接已发送后，按上面三步收尾完成冲突检查与静态编译检查，PR 合并后执行根目录 `./release.sh` 发新版本。

package/CHANGELOG.md

@@ -2,6 +2,29 @@
 
 所有对 @routerhub/agent-rules 的重大更改都会记录在这个文件中。
 
+## [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
+
+- **「跨系统真实链路验收」改为两段式执行（阶段 1 在循环 review 之前，阶段 2 在之后）**：原先只在循环 review 收敛、重新部署之后做一次完整验收。改为**阶段 1「链路预演」提前到创建 PR 后、循环 review 之前**（轻量：只画链路 + 逐环节判通不通，不写 6 段报告、不做截图标注，约阶段 2 的 20~30% 工作量），目的只有一个——**尽早暴露需要「大改」的问题**（需求口径反转、默认值不对、跨仓库语义不成立、schema 要改）。**阶段 2「链路验收」位置不变**（必须验最终要发布的那个版本，review 会 push 新 commit，提前验的证据会作废）。理由：本流程要暴露的四类问题修复代价都是大改，而 review 修的是小改；把大改压到最后 = 先用 N 轮把一个可能要推翻重做的东西打磨到没有代码缺陷，再发现它根本不该这么做（PR #158 问题 B/C 即此）。闭环流程由六步扩为七步（新增步骤 0「链路预演」）。
+
+### Added
+
+- **PR 模板新增「跨系统链路验收」栏目**：命中 4 条触发条件的，须填 ① 链路预演（链路图 + 各环节归属系统 + 能否走通）② 链路验收（下游真实生效证据 + 默认值类字段与存量数据对照）；未命中的勾选豁免项。Checklist 同步新增一项。**作用是把链路验收从「AI 自查完就没了」变成 PR 里留痕、reviewer 能看见，不填等于这一环做了也没人知道。**
+- `real-chain-verify` skill 新增「两段式」章节（两段各自时机/回答什么/做到什么程度/工作量对照表，以及为什么两段、为什么阶段 2 不能提前）；`create-pr`、`pr-release-loop` skill 同步挂钩（阶段 1 挂到创建 PR 后的闭环步骤 2，阶段 2 挂到复测步骤并回填 PR 栏目）。
+
 ## [1.5.202] - 2026-09-10
 
 ### Added

package/PULL_REQUEST_TEMPLATE.md

@@ -7,6 +7,53 @@
 
 Closes #
 
+## 缺陷复现
+
+<!-- 仅「修 bug / 修故障 / 修线上异常」的 PR 需要填（新增功能、重构、文案、依赖升级直接勾豁免项）。
+     依据 AGENTS.base.md「⚠️ 缺陷复现铁律」：必须先复现、留证、写下来，再动手改。
+     ⚠️ 复现必须在【改动前的代码】上做（线上/测试环境当前版本，或打补丁前的 commit），改完再补的「复现」不算。 -->
+
+- [ ] 本次 PR **不是**修 bug（新增功能 / 重构 / 文案 / 依赖升级），无需缺陷复现
+
+**① 复现证据（改动前的代码上跑出来的）**
+
+- **环境与版本**：<环境（生产/测试/本地） + commit 或 revision + 账号 / 数据 ID>
+- **操作步骤**（别人照着能一步步重演，禁止省略参数）：
+  1.
+  2.
+  3.
+- **观测到的坏现象**：<报错原文 / HTTP 状态码 / 日志片段 / 截图，带时间戳或 request id>
+  - ⚠️「偶尔会出问题」不合格——必须能指出出问题的是哪一次。
+
+**② 修复后用同一条路径复验**
+
+- [ ] 已用 ① 的**同一套步骤**重跑一遍，坏现象消失（两次路径不一致 = A/B 对照不成立）
+- **复验结果**：<改后观测到什么，同样带可复查标识>
+
+## 跨系统链路验收
+
+<!-- 先判断是否命中 AGENTS.base.md「⚠️ 跨系统真实链路验收铁律」的 4 条触发条件（改动跨系统/跨仓库、新增默认值类字段、涉及金额/路由/权限/限流、新增表字段参与对外可见判定）。 -->
+<!-- 未命中：把下面那个勾选框打上，本栏目到此为止。 -->
+<!-- 命中：链路预演（循环 review 之前）与链路验收（review 收敛后）两段的证据都要在此留痕。 -->
+
+- [ ] 本次改动**未命中**上述 4 条触发条件，无需跨系统链路验收
+
+**① 链路预演**（创建 PR 后、循环 review 之前，轻量：只回答「链路成不成立、需求口径对不对」）
+
+```
+链路：<用户动作起点> → <本系统> → <下游环节> → <最终生效处>
+```
+
+| 环节 | 归属系统/仓库 | 能否走通 | 观察到的事实 |
+|---|---|---|---|
+| | | | |
+
+**② 链路验收**（循环 review 收敛、重新部署之后，完整：作为交付证据）
+
+- **下游真实生效证据**（必须来自下游系统，不是本系统回显）：
+  - ❌「门户页面显示 Active」 ✅「网关 `/v1/models` 里精确出现了这个模型」
+- **默认值类字段与存量数据对照**（命中触发条件 2 时必填）：默认值 → 下游消费规则 → 线上存量数据 → 叠加效果
+
 ## Test Plan
 
 <!-- 硬性必填：如何验证改动正确，附可复现步骤或证据（命令 + 结果、手动操作步骤、日志、请求响应、修复前后对比）。 -->
@@ -22,6 +69,8 @@ Closes #
 - [ ] 一个 PR 只做一件事，无夹带无关改动
 - [ ] Description 已说明 What / Why / How
 - [ ] Test Plan 完整且带证据
+- [ ] 修 bug 的 PR 已按「缺陷复现」栏目写下改动前的复现证据（非修 bug 的已勾选豁免项）
+- [ ] 跨系统链路验收已按上方栏目填完（未命中触发条件则勾选豁免项）
 - [ ] UI 改动已贴截图（或注明无界面变化）
 - [ ] 本地编译 / lint / 测试通过，CI 全绿
 - [ ] 已关联 issue、指定 reviewer

package/package.json

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

package/rules/global.md

@@ -133,8 +133,26 @@ 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 全部白费。
+- ⚠️ **复现要用真实触发场景的数据和路径，禁止自己造一个顺手能触发的输入。** 造出来的输入只能复现你想象的那个问题，不是用户真实碰到的那个——真实数据的边界形态（空值、超长文本、特殊字符、异常关联、旧状态记录）恰恰是问题的来源（呼应「⚠️ 验证功能是否修复时，要用真实存在的数据/路径去测试」）。
+- ⚠️ **复现证据必须写进 PR 描述（PR 模板已内置「缺陷复现」栏目），不写等于没复现。** 这一栏是给 reviewer 看的：他据此判断「这个改动确实是对着这个现象去的」，也能自己照着重跑一遍确认修好了。只有作者本机跑过一次、PR 里一个字没有 = 这一环做了也没人知道。
+- **类比：看病。医生不会听你说一句「我头疼」就直接开止痛药——先做检查（复现）确认到底是什么病、是不是这个病，拿到检查报告（证据），再开药（改代码）。检查下来一切正常，那说明你说的「头疼」可能不是你以为的那个原因，得回去问清楚，而不是照着头疼开药；照着症状开药，病没治好，还耽误了真病因。**
+- ⚠️ **与相邻铁律的分工**：本铁律管「改之前证明问题存在」；「⚠️ 修复验证铁律」管「改之后证明问题消失」；「⚠️ 跨系统真实链路验收铁律」管「整条链路成不成立」。三者是**同一条路径**在时间轴上不同位置各跑一次：复现（改前）→ 复验（改后）→ 链路验收（上线前整条链路）。
+- ⚠️ **例外（可以不先复现的只有这几类，除此之外一律先复现）**：① 本次不是修 bug 的改动（新增功能、重构、文案、依赖升级）；② 问题现象本身已带完整证据（用户给的截图里有报错原文 + 时间戳 + 账号，等同于已复现——此时仍需按上面三要素把它整理成「可重演步骤」写进 PR）；③ 用户明确说「不用复现，直接改」——按用户指令执行，但交付时必须说明本次跳过了复现。
+
 ## ⚠️ 修复验证铁律
 
+- ⚠️ **本铁律管「改之后」，「改之前」见「⚠️ 缺陷复现铁律」——先复现拿到改动前的坏现象证据，改完用同一条路径复验，A/B 对照才成立。**
 - ⚠️ **验证方法必须"可确定性复现"，优先选最直白的路径。** 不要依赖真实流量、后台任务或时序巧合去凑出被验证的状态（反直觉、难复现、别人无法照做）。判断顺序：先问「本次修复的唯一改动是什么」，把它精确映射成一个可手动触发的原子操作，再做 A/B 对照。例：验证"余额变更后网关缓存立即失效"，不要靠真实计费请求养缓存，而是直接 `SET` 种一个已知值 → `GET`（有值 = 修复前）→ `DEL`（= 失效动作）→ `GET`（nil = 修复后）。
 - ⚠️ **报告开头必带一张「为什么这样验证成立」的原理说明卡。** 先讲清楚 bug 前后差异的本质是哪一个动作，再论证"手动模拟该动作 = 真实场景"，让不了解背景的人也能信服。配一张修复前 vs 修复后的 A/B 对照表（代码行为 / 等价操作 / 观测结果三列并排）。
 - ⚠️ **每个验证步骤必须三要素齐全**：① 怎么做的（可复制粘贴的完整命令）② 结果（含可复查标识：执行 ID、时间戳、返回码）③ 这一步证明了什么（一句话点明证据含义，如"DEL 返回 1 = 删除前 key 确实存在"）。
@@ -217,8 +235,14 @@ agent-rules 生成的规则文件分两层，行为与归属不同，评审/发
   - ❌ **把「门户页面全绿」当「链路跑通」**——页面是本系统的回显，跑通是下游真的接住了。
   - ❌ **把「循环 review 全过」当「功能成立」**——review 审的是代码有没有缺陷，管不了「这套组合在真实系统里行不行」。
   - ❌ **把「部署成功 + 截图」当「验收完成」**——部署证明代码上线了，不证明功能用得了。
-- ⚠️ **与循环 review 的分工（两者不可互相替代）**：**循环 review 保证「代码没有明显缺陷」（静态、看 diff）；本流程保证「功能在真实系统里真的成立」（动态、看运行）。** 循环 review 走完只说明「代码层面没问题了」，此时**必须**继续走跨系统真实链路验收，禁止在 review 收敛后直接发链接 / 发版。
-- ⚠️ **具体操作流程见 `/real-chain-verify` skill**（怎么画链路、每类系统怎么取证、证据怎么组织成报告）。
+- ⚠️ **与循环 review 的分工（两者不可互相替代）**：**循环 review 保证「代码没有明显缺陷」（静态、看 diff）；本流程保证「功能在真实系统里真的成立」（动态、看运行）。**
+- ⚠️ **执行时机：拆成两段，禁止合并成一次（顺序错了会白跑 review）。**
+  - **阶段 1「链路预演」——创建 PR 后、循环 review 之前，轻量。** 只回答两件事：**这条链路成不成立、需求口径对不对**。产出只要「链路图 + 每个环节能不能通」的判断，**不写 6 段报告、不做截图箭头标注、不出交付文档**（约为阶段 2 的 20~30% 工作量）。
+  - **阶段 2「链路验收」——循环 review 收敛、重新部署之后，完整。** 走完整取证、6 段报告与截图标注，作为交付证据。
+  - ⚠️ **为什么必须两段而不是一次**：本流程要暴露的四类问题（跨仓库语义 / 需求口径 / 默认值×存量 / 精度临界）**修复代价都是「大改」**（改需求、改默认值、改 schema、改交互），而 review 修的是「代码写得对不对」（小改）。**把大改的发现压到最后，等于先用 N 轮把一个可能要推翻重做的东西打磨到没有代码缺陷，再发现它根本不该这么做**——review 成果直接作废，改完还得重跑 review。真实案例：PR #158 的问题 B 是需求口径反转（09-04 要求拦截 → 09-08 改成顺带清绑定）、问题 C 要改默认值并和存量数据对齐，两者都会让前面已 review 通过的代码整体作废。
+  - ⚠️ **为什么阶段 2 不能提前到 review 之前**：验的必须是「最终要发布的那个版本」。review 会 push 新 commit，提前验完的代码后面会被改，那次证据直接作废、还得再验一遍。阶段 2 的位置是硬的，只能压在最后。
+  - ⚠️ **不命中触发条件的改动，两段都不走**（纯文案、纯展示类改动不受影响）。
+- ⚠️ **具体操作流程见 `/real-chain-verify` skill**（怎么画链路、每类系统怎么取证、两段各自做到什么程度、证据怎么组织成报告）。
 
 ## Git 规范
 
@@ -290,10 +314,11 @@ agent-rules 生成的规则文件分两层，行为与归属不同，评审/发
 1. **与主分支冲突检查**：按上一条规则执行（`gh pr view <PR> --json mergeable -q .mergeable`），有冲突必须先解决。
 2. **GitHub 静态编译检查**：用 `gh pr checks <PR>` 查看 CI 检查状态（`success`=通过，`failure`=失败，`pending`=进行中）。存在失败项时，必须定位失败根因、修改代码并重新推送，直到全部通过，禁止把静态编译未通过的 PR 抛给 reviewer。
 3. **发新版本**：PR 合并后按项目发布流程发布新版本（本项目统一执行根目录 `./release.sh`，自动完成 patch 版本号 +1、更新 package.json、`git commit`/`push`、打 tag、`npm publish`）。
-- ⚠️ **创建完 PR 后自动走完整闭环流程，未走完不算完成**：创建 PR → 循环 review → 重新部署测试环境验证 → 确认没问题 → 发 PR 链接给用户 → 发新版本，六步缺一不可，全程自动执行：
+- ⚠️ **创建完 PR 后自动走完整闭环流程，未走完不算完成**：创建 PR → **链路预演** → 循环 review → 重新部署测试环境验证 → 确认没问题 → 发 PR 链接给用户 → 发新版本，七步缺一不可，全程自动执行：
+0. **先走「链路预演」（在循环 review 之前，轻量）**：PR 创建后**立刻**判断是否命中「⚠️ 跨系统真实链路验收铁律」的 4 条触发条件。命中 → 触发 `/real-chain-verify` 的**阶段 1**：只画链路、逐环节快速过一遍，回答「**这条链路成不成立、需求口径对不对**」，**不写 6 段报告、不做截图标注**（约阶段 2 的 20~30% 工作量）。⚠️ **这一步的目的是尽早暴露「需要大改」的问题**（需求口径反转、默认值不对、跨仓库语义不成立、schema 要改）——**大改放在 review 之后发现，等于前面 N 轮 review 全白跑**。发现需大改 → 先改完再进循环 review，禁止带着「可能推翻重做」的设计去跑 review。未命中 → 本步跳过，直接进第 1 步，并在 PR 描述里勾选豁免项。
 1. **自动走循环 review**：创建完 PR 后自动触发 `/loop-review` skill，反复「拉取 AI review（Claude Opus + GPT 交叉验证）→ 逐条读真实代码判断哪些值得修 → 值得修的改、不值得修/误报的 Won't fix 切断 → push 触发新一轮 review」，直到某一轮不再冒出值得修的新问题才结束，禁止只跑一轮就收工。**循环 review 走完后，必须显式输出「✅ 循环 review 完成，进入发布收尾闭环」，并调用 `/pr-release-loop` skill 走完后续步骤。**
 2. **重新部署到测试环境（循环 review 后最容易漏掉的一步）**：循环 review 走完后，自动触发 `/deploy-test` skill，把最新代码重新部署到测试环境，确保测试的是循环 review 之后的最终代码。⚠️ **循环 review 期间每次修复都会 push 新 commit；不重新部署 = 测试环境跑的还是 review 之前的旧代码 = 用旧代码验证新改动 = 结论无效。因此循环 review 结束后禁止直接发 PR 链接 / 发版，必须先 `/deploy-test` 重部署。**
-3. **测试环境验证 + 全程截图标注**：在测试环境用真实数据、真实页面交互测试本次改动（遵循「⚠️ 页面功能验证铁律」「⚠️ 用户视角测试铁律」）。测试过程中每一步都截图保留（遵循「⚠️ 截图规范」：真实视口 + `fullPage` 全页、URL 可见、存盘到 `screenshots/` 临时目录），并在每张截图上用**坐标换算后的箭头标注**（走 `/screenshot-annotate` skill）关键改动区域/验证点，让看的人一眼看懂这张图证明了什么。
+3. **测试环境验证 + 全程截图标注**：在测试环境用真实数据、真实页面交互测试本次改动（遵循「⚠️ 页面功能验证铁律」「⚠️ 用户视角测试铁律」）。测试过程中每一步都截图保留（遵循「⚠️ 截图规范」：真实视口 + `fullPage` 全页、URL 可见、存盘到 `screenshots/` 临时目录），并在每张截图上用**坐标换算后的箭头标注**（走 `/screenshot-annotate` skill）关键改动区域/验证点，让看的人一眼看懂这张图证明了什么。⚠️ **命中「⚠️ 跨系统真实链路验收铁律」触发条件的，本步即该铁律的「阶段 2 链路验收」**：按 `/real-chain-verify` 走完整取证与 6 段报告，把阶段 1 画出的链路逐环节补上下游可观测事实与下游真实生效证据（阶段 1 只判「通不通」，本步必须交出「下游留下了什么痕迹」）。
 4. **确认没问题才算完成**：测试通过、截图与箭头标注齐全、功能符合预期，才算真正完成。禁止测试没跑、截图没标注就宣称完成。
 5. **把 PR 链接发给用户**：确认没问题后，先把 PR 链接发送给用户（`gh pr view <PR> --json url -q .url`），让用户能直接打开查看，再执行发版。
 6. **发新版本**：确认没问题、PR 链接已发送后，按上面三步收尾完成冲突检查与静态编译检查，PR 合并后执行根目录 `./release.sh` 发新版本。

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)` 内嵌
@@ -117,11 +124,12 @@ gh pr create \
 ⚠️ 创建完 PR 后，禁止只做完步骤 8 收尾就交付。必须自动依次走完下方闭环，全程自动执行，未走完不算完成：
 
 1. **先做 CI 闸门检查**：创建 PR 后立即执行 `gh pr checks <PR>`（必要时轮询直到非 `pending`）。若存在任一 `failure`，必须先定位失败根因并修复，推送后复查到全部 `success`，再继续后续步骤；禁止带红 CI 进入下一步。
-2. **自动走循环 review**：自动触发 `/loop-review` skill，反复「拉取 AI review（Claude Opus + GPT 交叉验证）→ 逐条读真实代码判断哪些值得修 → 值得修的改、不值得修/误报的 Won't fix 切断 → push 触发新一轮 review」，直到某一轮不再冒出值得修的新问题才结束。
-3. **重新部署到测试环境**：循环 review 走完后，自动触发 `/deploy-test` skill，把最新代码重新部署到测试环境，确保测试的是循环 review 之后的最终代码。
-4. **测试环境验证 + 全程截图标注**：在测试环境用真实数据、真实页面交互测试本次改动（遵循「⚠️ 页面功能验证铁律」「⚠️ 用户视角测试铁律」）。测试过程中每一步都截图保留（遵循「⚠️ 截图规范」：真实视口 + `fullPage` 全页、URL 可见、存盘到 `docs/` 对应子目录），并在每张截图上用**坐标换算后的箭头标注**（走 `/screenshot-annotate` skill）关键改动区域/验证点，让看的人一眼看懂这张图证明了什么。
-5. **确认没问题才算完成**：测试通过、截图与箭头标注齐全、功能符合预期，才算真正完成。禁止测试没跑、截图没标注就宣称完成。
-6. **发新版本**：确认没问题后，回到下方步骤 8 完成冲突检查与静态编译检查，PR 合并后执行根目录 `./release.sh` 发新版本。
+2. **链路预演（在循环 review 之前，轻量）**：判断本次改动是否命中「⚠️ 跨系统真实链路验收铁律」的 4 条触发条件（改动跨系统/跨仓库、新增默认值类字段、涉及金额/路由/权限/限流、新增表字段参与对外可见判定）。命中 → 触发 `/real-chain-verify` 的**阶段 1**：只画链路、逐环节快速过一遍，回答「这条链路成不成立、需求口径对不对」，**不写 6 段报告、不做截图标注**。⚠️ **发现需要大改（需求口径反转、默认值不对、跨仓库语义不成立、schema 要改）时，先改完再进循环 review**——大改放在 review 之后发现 = 前面 N 轮 review 全白跑。未命中 → 跳过本步，在 PR 描述里勾选豁免项。
+3. **自动走循环 review**：自动触发 `/loop-review` skill，反复「拉取 AI review（Claude Opus + GPT 交叉验证）→ 逐条读真实代码判断哪些值得修 → 值得修的改、不值得修/误报的 Won't fix 切断 → push 触发新一轮 review」，直到某一轮不再冒出值得修的新问题才结束。
+4. **重新部署到测试环境**：循环 review 走完后，自动触发 `/deploy-test` skill，把最新代码重新部署到测试环境，确保测试的是循环 review 之后的最终代码。
+5. **测试环境验证 + 全程截图标注**：在测试环境用真实数据、真实页面交互测试本次改动（遵循「⚠️ 页面功能验证铁律」「⚠️ 用户视角测试铁律」）。测试过程中每一步都截图保留（遵循「⚠️ 截图规范」：真实视口 + `fullPage` 全页、URL 可见、存盘到 `docs/` 对应子目录），并在每张截图上用**坐标换算后的箭头标注**（走 `/screenshot-annotate` skill）关键改动区域/验证点，让看的人一眼看懂这张图证明了什么。⚠️ **命中链路验收触发条件的，本步即「阶段 2 链路验收」**：按 `/real-chain-verify` 走完整取证与 6 段报告，并**回填 PR 描述里的「跨系统链路验收」栏目**（阶段 1 的链路图 + 下游真实生效证据 + 默认值对照）。
+6. **确认没问题才算完成**：测试通过、截图与箭头标注齐全、功能符合预期，才算真正完成。禁止测试没跑、截图没标注就宣称完成。
+7. **发新版本**：确认没问题后，回到下方步骤 8 完成冲突检查与静态编译检查，PR 合并后执行根目录 `./release.sh` 发新版本。
 
 ### 8. 每次修改 PR 后收尾检查（冲突 + 静态编译 + 发版本）
 
@@ -156,6 +164,8 @@ gh pr checks <PR>
 - ⚠️ 截图禁止提交到 Git 仓库
 - ⚠️ PR 截图直接内嵌在 Description 正文中（Markdown 图片语法）
 - ⚠️ 每次修改 PR 后（含创建、push 新提交、响应 review 意见）都必须做三步收尾：冲突检查 → 静态编译检查 → PR 合并后发新版本（见步骤 8）
-- ⚠️ **创建完 PR 后必须自动走完整闭环流程（见步骤 7.5）**：创建 PR → 先做 CI 闸门检查并修复失败项 → 自动循环 review → 重新部署测试环境验证（全程截图 + 箭头标注）→ 确认没问题 → 发新版本，六步缺一不可，未走完不算完成
+- ⚠️ **创建完 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

@@ -1,12 +1,15 @@
 ---
 name: pr-release-loop
 description: >-
-  PR 发布完整闭环（循环 review 之后的收尾）——创建 PR 后按 AGENTS.base.md「⚠️ 创建完 PR 后自动走完整闭环流程」自动走完
-  循环 review → 重新部署测试环境 → 测试环境复测 → 确认 → 发 PR 链接 → 发新版本 六步。核心防线：**循环 review 走完后，
-  必须重新部署到测试环境并复测，确认没问题之后才能发链接/发版**——这是最容易漏掉的一环（review 会改代码，跳过复测=拿旧代码下结论）。
-  复测环节命中「跨系统真实链路验收铁律」触发条件时，自动触发 `real-chain-verify` skill 验到下游（页面全绿 ≠ 链路跑通）。
+  PR 发布完整闭环（循环 review 之后的收尾，也是跨系统链路验收的「阶段 2」）——创建 PR 后按 AGENTS.base.md
+  「⚠️ 创建完 PR 后自动走完整闭环流程」自动走完 链路预演 → 循环 review → 重新部署测试环境 → 测试环境复测 →
+  确认 → 发 PR 链接 → 发新版本。核心防线：**循环 review 走完后，必须重新部署到测试环境并复测，确认没问题之后
+  才能发链接/发版**——这是最容易漏掉的一环（review 会改代码，跳过复测=拿旧代码下结论）。
+  复测环节命中「跨系统真实链路验收铁律」触发条件时，自动触发 `real-chain-verify` **阶段 2**（完整验收）验到下游，
+  并回填 PR 描述里的「跨系统链路验收」栏目（页面全绿 ≠ 链路跑通）。阶段 1「链路预演」应在循环 review 之前已完成，
+  没做则先补做。
   触发场景包括但不限于：
-  「PR闭环」「闭环走完」「完整闭环」「六步闭环」「走完整流程」「收尾」「发布闭环」「发布收尾」「循环review完再部署测一遍」「测试环境再测一遍」。
+  「PR闭环」「闭环走完」「完整闭环」「六步闭环」「七步闭环」「走完整流程」「收尾」「发布闭环」「发布收尾」「循环review完再部署测一遍」「测试环境再测一遍」。
   以及「创建PR后的完整流程」「走完循环review流程」「循环review完之后」。
   当循环 review 显示「无值得修的新问题」、进入收尾阶段时，**自动触发本 Skill**，无需用户再开口。
 ---
@@ -20,15 +23,18 @@ description: >-
 ## ⚠️ 核心铁律（违反即错误）
 
 - ⚠️ **循环 review 结束 ≠ 完成。** review 期间会 push 新 commit，**只有把最新代码重新部署到测试环境、在测试环境复测通过，才算真正完成**。跳过复测直接用旧代码下结论 = 白 review。
+- ⚠️ **本 Skill 是「链路验收」的阶段 2。** 跨系统真实链路验收分两段：阶段 1「链路预演」应在**创建 PR 后、循环 review 之前**已完成（轻量：只画链路 + 判通不通）；阶段 2 就是本 Skill 的第 3、4 步（完整取证 + 6 段报告 + 截图标注）。⚠️ **若命中触发条件却没做过阶段 1，必须先补做**——阶段 1 的作用是尽早暴露「需要大改」的问题，漏掉它意味着 review 可能跑在会推翻重做的设计上。
 - ⚠️ **完成定义清单（终局前必须逐项自查并输出）：**
   1. ✅ 循环 review 走完（`/loop-review`，直到某一轮不再冒出值得修的新问题）
   2. ✅ 最新代码已提交并推送到 PR 分支
   3. ✅ 已通过 `/deploy-test` 重新部署到测试环境（部署的是 review 之后的最终代码）
-  4. ✅ 测试环境用真实数据 + 真实交互复测通过，**且命中的跨系统链路环节已按 `/real-chain-verify` 验完下游**（每张截图浏览器真实视口全页、箭头标注、URL 可见）
-  5. ✅ 与主分支无冲突（`gh pr view <PR> --json mergeable -q .mergeable` = `MERGEABLE`）
-  6. ✅ GitHub 静态编译通过（`gh pr checks <PR>` 无 `failure`）
-  7. ✅ PR 链接已发送给用户
-  8. ✅ 发新版本（`./release.sh`）
+  4. ✅ 测试环境用真实数据 + 真实交互复测通过，**且命中的跨系统链路环节已按 `/real-chain-verify` 阶段 2 验完下游**（每张截图浏览器真实视口全页、箭头标注、URL 可见）
+  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 步」带进交付。
 
 ## 核心流程
@@ -76,7 +82,8 @@ git push origin "$(git branch --show-current)"
 ### 4. 测试环境复测 + 全程截图标注
 
 - 在测试环境用**真实数据 + 真实交互**测试本次改动（遵循「⚠️ 页面功能验证铁律」「⚠️ 用户视角测试铁律」）。
-- ⚠️ **先判断是否命中「⚠️ 跨系统真实链路验收铁律」的触发条件**（改动跨系统/跨仓库、新增默认值类字段、涉及金额/路由/权限/限流、新增表字段参与对外可见判定）。**命中则必须触发 `/real-chain-verify`**，从「用户动作起点」一路验到「最终生效的下游系统」，取到下游真实生效证据——**禁止只交本系统页面截图就当作复测完成**。
+- ⚠️ **先判断是否命中「⚠️ 跨系统真实链路验收铁律」的触发条件**（改动跨系统/跨仓库、新增默认值类字段、涉及金额/路由/权限/限流、新增表字段参与对外可见判定）。**命中则必须触发 `/real-chain-verify` 的阶段 2**（完整验收），从「用户动作起点」一路验到「最终生效的下游系统」，取到下游真实生效证据——**禁止只交本系统页面截图就当作复测完成**。阶段 1（链路预演）应在循环 review 之前已完成；若没做，先补做。
+- ⚠️ **本步结束后必须回填 PR 描述里的「跨系统链路验收」栏目**：命中触发条件的填「② 链路验收」的下游真实生效证据与默认值对照；未命中的勾选豁免项。这是留给 reviewer 的痕迹——不填等于这一环做了也没人知道。
 - 每步截图保留（遵循「⚠️ 截图规范」：浏览器真实视口宽（需要更清晰时提高 DPR）、`fullPage` 全页、URL 可见、存盘到 `docs/` 对应子目录），并用**箭头标注**关键改动区域/验证点，让看的人一眼看懂这张图证明了什么。
 - 若本次改动是纯后端/基础设施，按「非 UI / 后端 / 基础设施改动的效果截图获取方法」把 curl 响应渲染成暗色终端 HTML 截图。
 

package/skills/real-chain-verify/SKILL.md

@@ -7,9 +7,12 @@ description: >-
   小数值精度临界，这四类问题只有真跑一遍才会暴露。
   触发场景包括但不限于：
   「整链路验收」「真实链路」「走一遍真实流程」「端到端验收」「跨系统验证」「链路跑通」「真打一次请求」
-  「下游有没有生效」「这套跑起来行不行」「验收一下」「跑一遍完整流程」。
+  「下游有没有生效」「这套跑起来行不行」「验收一下」「跑一遍完整流程」「链路预演」。
   **当改动命中「跨系统/跨仓库、新增默认值类字段、涉及金额/路由/权限/限流、新增表字段参与对外可见判定」
   任一条件时，自动触发本 Skill，无需用户再开口。**
+  **本 Skill 分两段执行**：阶段 1「链路预演」在**创建 PR 后、循环 review 之前**自动触发（轻量：只画链路 +
+  逐环节判通不通，尽早暴露需要大改的问题）；阶段 2「链路验收」在**循环 review 收敛、重新部署之后**自动触发
+  （完整：全部步骤 + 6 段报告 + 截图标注，作为交付证据）。
 ---
 
 # 跨系统真实链路验收
@@ -19,10 +22,29 @@ description: >-
 ## ⚠️ 核心铁律（违反即错误）
 
 - ⚠️ **本系统页面全绿 ≠ 链路跑通。** 门户显示 Active，不等于网关选路里有它；Dashboard 说发了请求，不等于下游真的接住并计费了。**证据必须是「下游系统里能看到的东西」，不是本系统的回显。**
-- ⚠️ **本流程与循环 review 不可互相替代。** 循环 review 保证「代码没有明显缺陷」（静态、看 diff）；本流程保证「功能在真实系统里真的成立」（动态、看运行）。循环 review 收敛后**必须**继续走本流程，禁止直接发链接/发版。
+- ⚠️ **本流程与循环 review 不可互相替代。** 循环 review 保证「代码没有明显缺陷」（静态、看 diff）；本流程保证「功能在真实系统里真的成立」（动态、看运行）。
 - ⚠️ **禁止用「我以为下游会接住」代替「我看到下游接住了」。** 没取到下游痕迹 = 这一步没验完，不是「应该没问题」。
 - ⚠️ **先画链路再验证。** 链路没列出来就开测 = 不知道该验哪些环节 = 必然漏一整个下游。
 
+## ⚠️ 两段式：阶段 1 在 review 前，阶段 2 在 review 后（禁止合并成一次）
+
+本流程**分两段执行**，位置是硬的——顺序错了会白跑 review。
+
+| | 阶段 1「链路预演」 | 阶段 2「链路验收」 |
+|---|---|---|
+| **时机** | 创建 PR 后、**循环 review 之前** | 循环 review 收敛、**重新部署之后** |
+| **回答什么** | 这条链路**成不成立**、需求口径**对不对** | 下游**真的接住了吗** |
+| **做到什么程度（本 skill 的哪些步）** | 只做第 1、2 步 + 第 3 步的**快速版**（每环节判「通/不通」，不追完整证据） | 第 1～7 步**全做**，含 6 段报告 + 截图箭头标注 |
+| **工作量** | 约阶段 2 的 20~30% | 100%（交付证据） |
+| **产出** | 链路图 + 逐环节通/不通判断 | 完整验收报告（交付物） |
+| **不做** | ❌ 不写 6 段报告 ❌ 不做截图箭头标注 ❌ 不出交付文档 | — |
+
+**为什么阶段 1 必须在前面**：本流程要暴露的四类问题（跨仓库语义 / 需求口径 / 默认值×存量 / 精度临界），**修复代价都是「大改」**（改需求、改默认值、改 schema、改交互），而 review 修的是小改（补判空、改错误码）。**把大改的发现压到最后 = 先用 N 轮把一个可能要推翻重做的东西打磨到没有代码缺陷，再发现它根本不该这么做**——review 成果直接作废，改完还得重跑 review。阶段 1 的成本很低（只画链路 + 快速过一遍），换来的是「review 跑在已经确认方向正确的代码上」。
+
+**为什么阶段 2 不能提前**：验的必须是「最终要发布的那个版本」。review 会 push 新 commit，提前验完的代码后面会被改，那次证据直接作废、还得再验一遍。阶段 2 只能压在最后。这也是「阶段 1 轻量、阶段 2 完整」的分工依据——轻的那段先跑，重的那段只跑一次。
+
+⚠️ **阶段 1 发现「需要大改」时，禁止带着它进循环 review**：先改完（改需求口径 / 改默认值 / 补下游能力），再进 review。这正是阶段 1 存在的意义。
+
 ## 核心流程
 
 ### 1. 判定是否触发