@routerhub/agent-rules 1.5.209 → 1.5.211

package/AGENTS.base.md

@@ -336,6 +336,10 @@ agent-rules 生成的规则文件分两层，行为与归属不同，评审/发
 
 ## PR 核心要求
 
+- ⚠️ **建 PR 前先自检「规则是否在场」——规则写得再全，不在你手里就等于不存在**：动手前先在自己的规则文件里搜一次 `详细实现文档`（`grep -l '详细实现文档' CLAUDE.md AGENTS.md .github/copilot-instructions.md`）。**搜不到就说明当前分支的规则集是旧的**（本条置顶链接规则自 `@routerhub/agent-rules` **v1.5.183** 起生效），**必须先升级规则再建 PR**（合并/变基主分支后重装依赖，postinstall 会重新生成 `CLAUDE.md` / `AGENTS.md`），禁止拿着旧流程把 PR 建完。落地动作见 `/create-pr` 步骤 0 的机械校验。
+    - **⚠️ 规则陈旧是静默故障，要当成一级怀疑对象**：旧规则集是**自洽的**——它能把 PR 完整建完、全程不报一个错，你只是少了一批铁律而毫无察觉。**判据是「手里少了什么」，不是「有没有报错」。** 一条铁律无法防止「这条铁律本身没被加载」，所以只能靠这一步主动去搜。
+    - **由来（PR #181 真实事故）**：该 PR 漏掉 Description 置顶文档链接，根因**不是规则没写**——规则当时已经在 `AGENTS.base.md` 与 `/create-pr` 步骤 5 里，而是该 PR 所在分支**落后主分支 65 个提交、依赖锁在 v1.5.170**，这条规则（v1.5.183）**比手里的规则集晚出生**，读到的 `CLAUDE.md` 里没有它、调用的也是旧版 skill，于是按一份完整的旧流程走完了全程。**规则陈旧时你手里少的不止这一条**，所以发现落后要整批升级，不要只补这一条。
+- ⚠️ **PR 建完后的第一个动作是自问「Description 第一行是不是那条 📄 链接」，不是就当场补**：⚠️ **缺这条链接的 PR 一律不算建完**，禁止交付 review、禁止进入发版流程——「正文已经写得很详细」不构成豁免，链接是**必备件**而非可选优化。
 - ⚠️ **每个 PR 的 Description 最顶部必须放一条醒目的「详细实现文档」链接（截图版 HTML→PDF），把 PR 分成「快速浏览」与「详细展开」两层看**：
     - **两层分工**：PR 正文只承载「快速浏览」——What / Why / Test Plan 精华 + 关键效果截图，让人几十秒内看懂这次改了什么；链接指向的 PDF 承载「详细展开」——本次做了什么 + 为什么这样做 + 每一步怎么做的完整实现过程，并配上带箭头标注的真实截图（遵循「⚠️ 截图规范」与「⚠️ 页面功能验证铁律」）。想深入细节的 reviewer 点开链接即看，不用在正文里翻流水账；也禁止只有正文、缺详细文档链接。
     - **位置与醒目度**：链接必须是 Description 第一条、独占一行、加粗高亮，放在任何正文段落之前，让 reviewer 打开 PR 第一眼就能看到。示意格式：`📄 详细实现文档（含箭头标注截图与逐步说明）：[点击查看](https://github.com/<ORG>/<项目>-docs/blob/docs/<文件名>.pdf)`。reviewer 建议在新标签页打开，看完细节再回正文。
@@ -347,7 +351,7 @@ agent-rules 生成的规则文件分两层，行为与归属不同，评审/发
     - **全页图**：用浏览器真实视口（`window.innerWidth` 即截图宽度，4K 屏自然宽 3840）`fullPage` 截完整页面，禁止只截视口一屏。⚠️ **禁止强制把视口硬拉成 3840 宽**——浏览器视口宽由屏幕实际分辨率决定，硬拉宽会让内容按比例缩小（看不清），且与截图像素发生缩放错位，是标注不准的根因之一。若要更高清晰度，用 `set viewport <W> <H> 2`（DPR 倍率）提高渲染精度（CSS 宽不变、像素更密），而不是拉宽 CSS 视口。
     - **全面多角度**：一张全页图 + 每个关键改动区域的局部放大图，多个改动点要逐个覆盖，确保 reviewer 不看代码就能看全本次全部改动。
     - **箭头标注（必须标注准）**：每张截图必须用醒目箭头 + 简短文字标签标注关键改动区域/验证点（修复前红框/红箭头、修复后绿框/绿箭头），标注放在不遮挡原内容的位置，禁止只贴裸图不标注。⚠️ **标注坐标必须来自浏览器 DOM 测量（`getBoundingClientRect()` + `scrollX/scrollY`）精确换算成截图像素，禁止肉眼看图估坐标**——全页拼接/缩放截图里 CSS 坐标 ≠ 截图像素，肉眼估位是标注不准的直接原因。标注统一走 `/screenshot-annotate` skill（坐标换算方法 + `annotate.js` 统一脚本）。
-    - **URL 可见且能打开**：截图中必须能看到当前页面 URL，且该 URL 必须是别人能直接打开的地址（测试环境 / 线上域名），**禁止 `localhost` / `127.0.0.1` / `file:///` 等本机地址**——reviewer 在自己机器上打不开，等于没给。同时在截图旁以文字写出这条 URL，方便 reviewer 一眼复制、亲自打开复核（呼应「⚠️ 验收环境铁律」）。
+    - **URL 可见且能打开**：按「⚠️ 截图规范」把完整 URL 以文字叠进截图本身（`/screenshot-annotate --url`），且该 URL 必须是别人能直接打开的地址（测试环境 / 线上域名），**禁止 `localhost` / `127.0.0.1` / `file:///` 等本机地址**——reviewer 在自己机器上打不开，等于没给。截图旁再给出可点击的链接（PR 正文写成 `[打开页面](URL)`），reviewer 一眼复制、或直接点开亲自复核（呼应「⚠️ 验收环境铁律」）。
     - **前后对比**：必须同时展示修复前与修复后。
 - ⚠️ **截图必须直接内嵌在 PR Description 中，让 reviewer 打开 PR 就能看到效果图（`![](CDN_URL)` 方式渲染为可见图片），禁止只在文字里描述"改动了什么"而不放图，也禁止把截图只作为文件附件/提交到分支目录而不在 PR 正文中引用。** 原因：reviewer 看 PR 的第一眼就是看描述，如果看不到图、只能读文字，完全无法直观感知改动效果；截图不内嵌 = 等于没附。
 - ⚠️ **截图必须通过 PR Description 编辑区直接上传（拖拽/粘贴/文件选择按钮），禁止走评论区 `input[type=file]` 上传后再搬运 CDN URL。** 原因：PR Description 编辑区本身支持图片拖拽上传、自动转为 `![](CDN_URL)` 内嵌，一步到位；走评论区上传需要多一步「提交评论 → 复制 URL → 粘贴到 Description」，产生的临时图片评论会留在 PR 对话里干扰 reviewer 阅读，且多了一步手动搬运、容易出错。
@@ -599,7 +603,8 @@ agent-rules 生成的规则文件分两层，行为与归属不同，评审/发
 
 - ⚠️ **截图用浏览器真实视口宽度（`window.innerWidth` 即截图宽，4K 屏自然宽 3840），禁止强制把视口硬拉成 3840px**。浏览器视口宽度由屏幕实际分辨率决定，强行 `set viewport 3840 <h>` 把 CSS 视口拉宽到比屏幕还宽，会让页面按比例缩小、内容看不清，且 CSS 像素与截图设备像素发生缩放错位——这正是「强制 4K 时标注不准」的根因。需要更高清晰度时用 `set viewport <W> <H> <DPR>`（如 `2` 倍 DPR，CSS 宽不变、像素更密），而不是拉宽 CSS 视口。
 - ⚠️ **全页截图**：用 `screenshot --full`（agent-browser）或 `page.screenshot({ fullPage: true })`（Playwright）截完整页面，不要只截视口的一部分；用 agent-browser 截全页前先 `set viewport <视口宽> <合适高度>` 固定视口，确保截图宽度 = 视口宽度。
-- ⚠️ **截图中必须能看到当前页面的地址栏，且该 URL 必须是别人能直接打开访问的地址（测试环境 / 线上域名）**：交付时把这条 URL 连同截图一起给出（正文里以文字再写一遍，方便一眼复制打开），别人点开就能看到同一个页面、亲眼复核。**禁止用本机地址充当 URL**——`localhost`、`127.0.0.1`、内网 IP、`file:///...` 本机路径在别人机器上要么打不开、要么指向他自己的机器，等于没给 URL（呼应「⚠️ 验收环境铁律」）。页面本身没有地址栏时，在页面顶部叠加一条 URL 标注，标注的仍然必须是可以直接访问的地址。
+- ⚠️ **每张截图都必须在图上写出「文字版」完整 URL——统一写，不得只靠地址栏**：用 `/screenshot-annotate` 的 `--url` 把 URL 叠进截图顶部标题条，让它成为截图自身的一部分，别人一眼能读到、能照着地址跳转。**禁止只依赖浏览器地址栏**：交付形态是 HTML / PDF 时，地址栏是静态像素——别人既点不了、也复制不走；裁切图 / 局部放大图（从大图里裁一块出来）压根没有地址栏；图缩放到文档版心宽度后，条带里的字往往已糊到认不出。**类比：把门牌号直接印在地图上，而不是让人对着地图回忆自己是从哪个路口拐进来的。**
+- ⚠️ **交付载体里必须附「可点击的跳转入口」，且该 URL 必须是别人能直接打开访问的地址（测试环境 / 线上域名）**：HTML 文档 / 报告把地址渲染成按钮或链接，写成 `<a target="_blank" rel="noopener" href="...">`（按「HTML 页面/文档中的外部链接默认用新标签页打开」实现）——点击即在新标签页打开，不打断当前文档；Markdown / PR 正文写成 `[打开页面](URL)`。**禁止用本机地址充当 URL**——`localhost`、`127.0.0.1`、内网 IP、`file:///...` 本机路径在别人机器上要么打不开、要么指向他自己的机器，等于没给 URL，做成按钮也只会点开一个打不开的页面（呼应「⚠️ 验收环境铁律」）。
 - ⚠️ **标注必须准确，坐标必须有浏览器测量来源**：箭头/框要指哪儿，用 `getBoundingClientRect()` + `scrollX/scrollY` 取元素在整页中的 CSS 坐标，再按截图实际宽度换算成截图像素，统一用 `/screenshot-annotate` skill（含 `annotate.js` 脚本）标注。禁止用肉眼看图估坐标，禁止在强制缩放造成坐标错位的前提下标注。
 - **保存到磁盘文件**（`page.screenshot({ path, fullPage: true })`），禁止只用内联展示的截图工具——内联的不落盘，用户无法在 Markdown / HTML 文档里查看。路径统一放 `screenshots/` 临时目录，文件名用「编号 + 英文描述」（如 `01-login-page.png`）。
 

package/PULL_REQUEST_TEMPLATE.md

@@ -88,7 +88,7 @@ Closes #
 ## Screenshots
 
 <!-- UI / 前端改动必须贴截图（整页、含 URL）；行为有变化时贴「改动前 / 改动后」对比。把图片直接拖拽到此处。 -->
-<!-- ⚠️ 图中的 URL 必须是别人能直接打开的地址（测试环境 / 线上域名），禁止 localhost / 127.0.0.1 / file:///；并在图旁以文字写出该 URL。截图一律在测试环境取证，本地效果不作为交付证据。 -->
+<!-- ⚠️ 每张图都要在图上写出文字版完整 URL（`/screenshot-annotate --url` 叠进截图标题条，不得只靠地址栏），且必须是别人能直接打开的地址（测试环境 / 线上域名），禁止 localhost / 127.0.0.1 / file:///；图旁再给一个可点击的链接（`[打开页面](URL)`），别人一点就在新标签页打开复核。截图一律在测试环境取证，本地效果不作为交付证据。 -->
 <!-- 纯后端 / 无界面改动写「N/A（无界面变化）」。 -->
 
 ## Checklist
@@ -100,6 +100,6 @@ Closes #
 - [ ] 跨系统链路验收已按上方栏目填完（未命中触发条件则勾选豁免项）
 - [ ] 已按「取证报告」栏目给出取证数据（或勾选一层豁免项）
 - [ ] UI 改动已贴截图（或注明无界面变化）
-- [ ] 截图与证据取自测试环境（无截图 / 本地例外已注明原因），图中的 URL 是别人能直接打开的地址（非 localhost）
+- [ ] 截图与证据取自测试环境（无截图 / 本地例外已注明原因），且每张图里都写了文字版完整 URL（不是只靠地址栏），该 URL 是别人能直接打开的地址（非 localhost）
 - [ ] 本地编译 / lint / 测试通过，CI 全绿
 - [ ] 已关联 issue、指定 reviewer

package/package.json

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

package/rules/global.md

@@ -336,6 +336,10 @@ agent-rules 生成的规则文件分两层，行为与归属不同，评审/发
 
 ## PR 核心要求
 
+- ⚠️ **建 PR 前先自检「规则是否在场」——规则写得再全，不在你手里就等于不存在**：动手前先在自己的规则文件里搜一次 `详细实现文档`（`grep -l '详细实现文档' CLAUDE.md AGENTS.md .github/copilot-instructions.md`）。**搜不到就说明当前分支的规则集是旧的**（本条置顶链接规则自 `@routerhub/agent-rules` **v1.5.183** 起生效），**必须先升级规则再建 PR**（合并/变基主分支后重装依赖，postinstall 会重新生成 `CLAUDE.md` / `AGENTS.md`），禁止拿着旧流程把 PR 建完。落地动作见 `/create-pr` 步骤 0 的机械校验。
+    - **⚠️ 规则陈旧是静默故障，要当成一级怀疑对象**：旧规则集是**自洽的**——它能把 PR 完整建完、全程不报一个错，你只是少了一批铁律而毫无察觉。**判据是「手里少了什么」，不是「有没有报错」。** 一条铁律无法防止「这条铁律本身没被加载」，所以只能靠这一步主动去搜。
+    - **由来（PR #181 真实事故）**：该 PR 漏掉 Description 置顶文档链接，根因**不是规则没写**——规则当时已经在 `AGENTS.base.md` 与 `/create-pr` 步骤 5 里，而是该 PR 所在分支**落后主分支 65 个提交、依赖锁在 v1.5.170**，这条规则（v1.5.183）**比手里的规则集晚出生**，读到的 `CLAUDE.md` 里没有它、调用的也是旧版 skill，于是按一份完整的旧流程走完了全程。**规则陈旧时你手里少的不止这一条**，所以发现落后要整批升级，不要只补这一条。
+- ⚠️ **PR 建完后的第一个动作是自问「Description 第一行是不是那条 📄 链接」，不是就当场补**：⚠️ **缺这条链接的 PR 一律不算建完**，禁止交付 review、禁止进入发版流程——「正文已经写得很详细」不构成豁免，链接是**必备件**而非可选优化。
 - ⚠️ **每个 PR 的 Description 最顶部必须放一条醒目的「详细实现文档」链接（截图版 HTML→PDF），把 PR 分成「快速浏览」与「详细展开」两层看**：
     - **两层分工**：PR 正文只承载「快速浏览」——What / Why / Test Plan 精华 + 关键效果截图，让人几十秒内看懂这次改了什么；链接指向的 PDF 承载「详细展开」——本次做了什么 + 为什么这样做 + 每一步怎么做的完整实现过程，并配上带箭头标注的真实截图（遵循「⚠️ 截图规范」与「⚠️ 页面功能验证铁律」）。想深入细节的 reviewer 点开链接即看，不用在正文里翻流水账；也禁止只有正文、缺详细文档链接。
     - **位置与醒目度**：链接必须是 Description 第一条、独占一行、加粗高亮，放在任何正文段落之前，让 reviewer 打开 PR 第一眼就能看到。示意格式：`📄 详细实现文档（含箭头标注截图与逐步说明）：[点击查看](https://github.com/<ORG>/<项目>-docs/blob/docs/<文件名>.pdf)`。reviewer 建议在新标签页打开，看完细节再回正文。
@@ -347,7 +351,7 @@ agent-rules 生成的规则文件分两层，行为与归属不同，评审/发
     - **全页图**：用浏览器真实视口（`window.innerWidth` 即截图宽度，4K 屏自然宽 3840）`fullPage` 截完整页面，禁止只截视口一屏。⚠️ **禁止强制把视口硬拉成 3840 宽**——浏览器视口宽由屏幕实际分辨率决定，硬拉宽会让内容按比例缩小（看不清），且与截图像素发生缩放错位，是标注不准的根因之一。若要更高清晰度，用 `set viewport <W> <H> 2`（DPR 倍率）提高渲染精度（CSS 宽不变、像素更密），而不是拉宽 CSS 视口。
     - **全面多角度**：一张全页图 + 每个关键改动区域的局部放大图，多个改动点要逐个覆盖，确保 reviewer 不看代码就能看全本次全部改动。
     - **箭头标注（必须标注准）**：每张截图必须用醒目箭头 + 简短文字标签标注关键改动区域/验证点（修复前红框/红箭头、修复后绿框/绿箭头），标注放在不遮挡原内容的位置，禁止只贴裸图不标注。⚠️ **标注坐标必须来自浏览器 DOM 测量（`getBoundingClientRect()` + `scrollX/scrollY`）精确换算成截图像素，禁止肉眼看图估坐标**——全页拼接/缩放截图里 CSS 坐标 ≠ 截图像素，肉眼估位是标注不准的直接原因。标注统一走 `/screenshot-annotate` skill（坐标换算方法 + `annotate.js` 统一脚本）。
-    - **URL 可见且能打开**：截图中必须能看到当前页面 URL，且该 URL 必须是别人能直接打开的地址（测试环境 / 线上域名），**禁止 `localhost` / `127.0.0.1` / `file:///` 等本机地址**——reviewer 在自己机器上打不开，等于没给。同时在截图旁以文字写出这条 URL，方便 reviewer 一眼复制、亲自打开复核（呼应「⚠️ 验收环境铁律」）。
+    - **URL 可见且能打开**：按「⚠️ 截图规范」把完整 URL 以文字叠进截图本身（`/screenshot-annotate --url`），且该 URL 必须是别人能直接打开的地址（测试环境 / 线上域名），**禁止 `localhost` / `127.0.0.1` / `file:///` 等本机地址**——reviewer 在自己机器上打不开，等于没给。截图旁再给出可点击的链接（PR 正文写成 `[打开页面](URL)`），reviewer 一眼复制、或直接点开亲自复核（呼应「⚠️ 验收环境铁律」）。
     - **前后对比**：必须同时展示修复前与修复后。
 - ⚠️ **截图必须直接内嵌在 PR Description 中，让 reviewer 打开 PR 就能看到效果图（`![](CDN_URL)` 方式渲染为可见图片），禁止只在文字里描述"改动了什么"而不放图，也禁止把截图只作为文件附件/提交到分支目录而不在 PR 正文中引用。** 原因：reviewer 看 PR 的第一眼就是看描述，如果看不到图、只能读文字，完全无法直观感知改动效果；截图不内嵌 = 等于没附。
 - ⚠️ **截图必须通过 PR Description 编辑区直接上传（拖拽/粘贴/文件选择按钮），禁止走评论区 `input[type=file]` 上传后再搬运 CDN URL。** 原因：PR Description 编辑区本身支持图片拖拽上传、自动转为 `![](CDN_URL)` 内嵌，一步到位；走评论区上传需要多一步「提交评论 → 复制 URL → 粘贴到 Description」，产生的临时图片评论会留在 PR 对话里干扰 reviewer 阅读，且多了一步手动搬运、容易出错。
@@ -599,7 +603,8 @@ agent-rules 生成的规则文件分两层，行为与归属不同，评审/发
 
 - ⚠️ **截图用浏览器真实视口宽度（`window.innerWidth` 即截图宽，4K 屏自然宽 3840），禁止强制把视口硬拉成 3840px**。浏览器视口宽度由屏幕实际分辨率决定，强行 `set viewport 3840 <h>` 把 CSS 视口拉宽到比屏幕还宽，会让页面按比例缩小、内容看不清，且 CSS 像素与截图设备像素发生缩放错位——这正是「强制 4K 时标注不准」的根因。需要更高清晰度时用 `set viewport <W> <H> <DPR>`（如 `2` 倍 DPR，CSS 宽不变、像素更密），而不是拉宽 CSS 视口。
 - ⚠️ **全页截图**：用 `screenshot --full`（agent-browser）或 `page.screenshot({ fullPage: true })`（Playwright）截完整页面，不要只截视口的一部分；用 agent-browser 截全页前先 `set viewport <视口宽> <合适高度>` 固定视口，确保截图宽度 = 视口宽度。
-- ⚠️ **截图中必须能看到当前页面的地址栏，且该 URL 必须是别人能直接打开访问的地址（测试环境 / 线上域名）**：交付时把这条 URL 连同截图一起给出（正文里以文字再写一遍，方便一眼复制打开），别人点开就能看到同一个页面、亲眼复核。**禁止用本机地址充当 URL**——`localhost`、`127.0.0.1`、内网 IP、`file:///...` 本机路径在别人机器上要么打不开、要么指向他自己的机器，等于没给 URL（呼应「⚠️ 验收环境铁律」）。页面本身没有地址栏时，在页面顶部叠加一条 URL 标注，标注的仍然必须是可以直接访问的地址。
+- ⚠️ **每张截图都必须在图上写出「文字版」完整 URL——统一写，不得只靠地址栏**：用 `/screenshot-annotate` 的 `--url` 把 URL 叠进截图顶部标题条，让它成为截图自身的一部分，别人一眼能读到、能照着地址跳转。**禁止只依赖浏览器地址栏**：交付形态是 HTML / PDF 时，地址栏是静态像素——别人既点不了、也复制不走；裁切图 / 局部放大图（从大图里裁一块出来）压根没有地址栏；图缩放到文档版心宽度后，条带里的字往往已糊到认不出。**类比：把门牌号直接印在地图上，而不是让人对着地图回忆自己是从哪个路口拐进来的。**
+- ⚠️ **交付载体里必须附「可点击的跳转入口」，且该 URL 必须是别人能直接打开访问的地址（测试环境 / 线上域名）**：HTML 文档 / 报告把地址渲染成按钮或链接，写成 `<a target="_blank" rel="noopener" href="...">`（按「HTML 页面/文档中的外部链接默认用新标签页打开」实现）——点击即在新标签页打开，不打断当前文档；Markdown / PR 正文写成 `[打开页面](URL)`。**禁止用本机地址充当 URL**——`localhost`、`127.0.0.1`、内网 IP、`file:///...` 本机路径在别人机器上要么打不开、要么指向他自己的机器，等于没给 URL，做成按钮也只会点开一个打不开的页面（呼应「⚠️ 验收环境铁律」）。
 - ⚠️ **标注必须准确，坐标必须有浏览器测量来源**：箭头/框要指哪儿，用 `getBoundingClientRect()` + `scrollX/scrollY` 取元素在整页中的 CSS 坐标，再按截图实际宽度换算成截图像素，统一用 `/screenshot-annotate` skill（含 `annotate.js` 脚本）标注。禁止用肉眼看图估坐标，禁止在强制缩放造成坐标错位的前提下标注。
 - **保存到磁盘文件**（`page.screenshot({ path, fullPage: true })`），禁止只用内联展示的截图工具——内联的不落盘，用户无法在 Markdown / HTML 文档里查看。路径统一放 `screenshots/` 临时目录，文件名用「编号 + 英文描述」（如 `01-login-page.png`）。
 

package/skills/create-doc/SKILL.md

@@ -150,7 +150,8 @@ description: >-
 ### 截图规范
 
 - 截取整页（full page），不是可视区域；用真实视口宽度（4K 屏自然宽 3840），禁止强制把视口拉宽
-- 截图结果必须包含当前页面 URL，且该 URL 必须是别人能直接打开的地址（测试环境 / 线上域名），禁止 `localhost` / `127.0.0.1` / `file:///` 等本机地址；截图一律在测试环境取证，本地效果不作交付证据
+- 截图结果必须在图上写出文字版完整 URL（走 `/screenshot-annotate --url`，叠进截图标题条），不得只靠地址栏；且该 URL 必须是别人能直接打开的地址（测试环境 / 线上域名），禁止 `localhost` / `127.0.0.1` / `file:///` 等本机地址；截图一律在测试环境取证，本地效果不作交付证据
+- 文档里每张截图旁再给一个可点击的跳转入口（`<a target="_blank" rel="noopener" href="...">打开页面</a>` 渲染成按钮），让别人一点就在新标签页打开该页面亲自复核，不用从图里抄地址
 - ⚠️ **截图版 HTML 的每张截图都必须加箭头（或红框）标注**，指向该图要说明的关键操作点或关键数据，禁止放无标注的「裸截图」；标注放在页面空白区域，不遮挡关键内容。⚠️ **标注坐标必须精确**：用 `/screenshot-annotate` skill（浏览器 DOM 测得的坐标 → `annotate.js` 换算到截图像素），禁止肉眼估位
 - 制作过程中产生的中间截图文件统一放到 `screenshots/` 目录
 

package/skills/create-pr/SKILL.md

@@ -16,6 +16,26 @@ description: >-
 
 ## 核心流程
 
+### 0. 规则在场自检（机械校验，禁止跳过）
+
+⚠️ **建 PR 之前先跑一遍，确认手里的规则集不是旧的。** 旧规则集是**自洽的**——它能把 PR 完整建完、全程不报一个错，你只是少了一批铁律而毫无察觉。**判据是「手里少了什么」，不是「有没有报错」。**
+
+```bash
+# ① 铁律是否在场：三个规则文件里任意一个能搜到「详细实现文档」即通过
+grep -l '详细实现文档' CLAUDE.md AGENTS.md .github/copilot-instructions.md 2>/dev/null
+
+# ② 规则版本新鲜度：当前分支 vs 远程默认分支（默认分支名不写死，从 origin/HEAD 取）
+base=$(git symbolic-ref --short refs/remotes/origin/HEAD 2>/dev/null || echo origin/main)
+cur=$(grep -o '"@routerhub/agent-rules": "[^"]*"' package.json 2>/dev/null | grep -o '[0-9][0-9.]*')
+ref=$(git show "$base:package.json" 2>/dev/null | grep -o '"@routerhub/agent-rules": "[^"]*"' | grep -o '[0-9][0-9.]*')
+echo "当前分支: ${cur:-未声明}  /  $base: ${ref:-未声明}"
+```
+
+- ① 无输出（三个文件都搜不到），或 ② 当前分支版本落后于远程默认分支 → **中止，先升级规则再建 PR**：合并/变基远程默认分支后重装依赖（`pnpm install`），postinstall 会重新生成 `CLAUDE.md` / `AGENTS.md`。**发现落后要整批升级，不要只补这一条——陈旧时你手里少的不止这一条。**
+- 两边一致 → 通过，继续步骤 1。
+
+⚠️ **本步骤的由来（PR #181 真实事故）**：该 PR 漏掉 Description 置顶「详细实现文档」链接，根因**不是规则没写**——规则当时已经在 `AGENTS.base.md` 与 `create-pr` 步骤 5 里，而是该 PR 所在分支**落后主分支 65 个提交、依赖锁在 `@routerhub/agent-rules` v1.5.170**，而这条规则自 **v1.5.183** 起才生效，**比手里的规则集晚出生**——读到的 `CLAUDE.md` 里没有它、调用的也是旧版 skill，于是按一份完整的旧流程走完了全程。**一条铁律无法防止「这条铁律本身没被加载」**，所以必须用这一步主动去搜。
+
 ### 1. 收集改动信息
 
 ```bash
@@ -77,7 +97,7 @@ Closes #issue编号
 - ⚠️ **必须 `fullPage: true` 截完整页面**，不要只截视口的一部分。每个改动点都要覆盖到，禁止只截视口内一屏。
 - ⚠️ **截图必须全面（多图覆盖多个角度）**：一张全页图 + 每个关键改动区域的局部放大图。只截一处、截局部、漏掉改动点都不算全。整份 PR Description 的效果截图要使 reviewer 不看代码就能看全本次改动。
 - ⚠️ **每张截图必须用醒目箭头 + 简短文字标签标注关键改动区域/验证点**，让看的人一眼看懂这张图证明了什么；修复前用红框/红箭头，修复后用绿框/绿箭头，标注放在不遮挡原内容的位置。禁止只贴裸图不标注。⚠️ **标注坐标必须精确**：统一用 `/screenshot-annotate` skill（`getBoundingClientRect()` + `scrollX/scrollY` 换算到截图像素，用 `annotate.js` 脚本画箭头），禁止肉眼看图估坐标。
-- ⚠️ **截图中必须能看到当前页面 URL，且该 URL 必须是别人能直接打开的地址（测试环境 / 线上域名）**——`localhost` / `127.0.0.1` / `file:///` 等本机地址在 reviewer 机器上打不开，等于没给。同时在截图旁以文字写出这条 URL，方便一眼复制复核。
+- ⚠️ **每张截图都必须在图上写出文字版完整 URL（走 `/screenshot-annotate --url` 叠进截图标题条），且该 URL 必须是别人能直接打开的地址（测试环境 / 线上域名）**——`localhost` / `127.0.0.1` / `file:///` 等本机地址在 reviewer 机器上打不开，等于没给。截图旁再以可点击链接写出这条 URL（PR 正文写成 `[打开页面](URL)`），方便一眼复制或直接点开复核。
 - ⚠️ **所有截图一律在测试环境取证**：先部署到测试环境（`/deploy-test`）再操作截图，禁止拿本地运行的效果当交付证据——本地依赖你本机的库/配置/未提交代码，别人照同样命令跑不出来（本地仅可用于开发中即时联调，不作证据）。
 - ⚠️ 截图保存到本地磁盘 `docs/` 对应子目录（文件名「编号 + 英文描述」，如 `01-before.png` / `02-after.png`），上传 CDN 后按规则清理临时文件，禁止提交到 Git 仓库。
 - ⚠️ 必须展示前后对比（修复前红框，修复后绿框），标注不遮挡页面内容。
@@ -162,6 +182,8 @@ gh pr checks <PR>
 - ⚠️ 一个 PR 只做一件事
 - ⚠️ PR 所有文字内容必须中文
 - ⚠️ 必须附截图作为可视化证据
+- ⚠️ **建 PR 前先做步骤 0 的规则在场自检**：规则文件里搜不到 `详细实现文档`，或当前分支规则版本落后远程默认分支 → 先升级规则再建 PR。规则陈旧是静默故障，不报错不等于没缺东西。
+- ⚠️ **PR 建完后的第一个动作是自问「Description 第一行是不是那条 📄 链接」，不是就当场补**：⚠️ **缺这条链接的 PR 一律不算建完**，禁止交付 review、禁止进入发版流程——「正文已经写得很详细」不构成豁免，链接是**必备件**而非可选优化。
 - ⚠️ **PR Description 顶部必须附「详细实现文档」链接（截图版 HTML→PDF，见步骤 5）**：PR 正文只承载快速浏览，链接展开「做了什么 + 为什么 + 每一步怎么做的」完整细节
 - ⚠️ 截图禁止提交到 Git 仓库
 - ⚠️ PR 截图直接内嵌在 Description 正文中（Markdown 图片语法）

package/skills/screenshot-annotate/SKILL.md

@@ -89,7 +89,7 @@ node "$SKILL_DIR/annotate.js" \
 ```
 
 - 坐标默认视为**设备像素**（截图内坐标）；`--viewport "cssW,cssH"` 传入时视为 CSS 视口坐标自动换算（非 fullPage）；`--fullpage --dpr N` 用于 fullPage 全页截图（坐标视为整页 CSS 坐标，按 DPR 缩放）
-- `--label` 顶部标题条（适合「修复前/修复后」对比）、`--url` 在标题条显示 URL 满足「URL 可见」。⚠️ **`--url` 传的必须是别人能直接打开的地址（测试环境 / 线上域名）**——传 `localhost` / `127.0.0.1` / `file:///` 只是形式上「有 URL」，看的人打不开，等于没给
+- `--label` 顶部标题条（适合「修复前/修复后」对比）；**`--url` 必填**——它把完整 URL 以文字写进顶部标题条，成为截图自身的一部分，满足「⚠️ 截图规范」的「每张截图都要在图上写出文字版 URL，不得只靠地址栏」。⚠️ **`--url` 传的必须是别人能直接打开的地址（测试环境 / 线上域名）**——传 `localhost` / `127.0.0.1` / `file:///` 只是形式上「有 URL」，看的人打不开，等于没给；交付载体（HTML 文档 / 报告）里还要把这条地址渲染成 `<a target="_blank" rel="noopener">` 按钮或链接，让别人一点就在新标签页打开
 - `text` 文本框自动排布在目标旁空闲侧，不遮挡内容；`w/h` 存在时画高亮圆角框指向其中心
 
 ## 渲染标注 HTML 为 PNG（固定流程）
@@ -114,7 +114,7 @@ agent-browser --cdp 9226 --namespace "$NS" tab close <tabId>
 
 - 箭头尖端指向的元素，肉眼应与 eval 捕获到的目标一致（坐标没歪）
 - 文本框不遮挡关键内容
-- 标注入口处能确认 URL（标题条或截图内地址栏），且该 URL 是别人能直接打开的地址（非 `localhost` / `127.0.0.1` / `file:///`）
+- **标题条里写着文字版完整 URL**（`--url` 已传，不是靠截图内的地址栏），且该 URL 是别人能直接打开的地址（非 `localhost` / `127.0.0.1` / `file:///`）
 - 修改坐标/文字后重新跑脚本 + 渲染，不要在原图上手工补。
 
 ## 重要规则

package/skills/screenshot-annotate/annotate.js

@@ -41,7 +41,8 @@
  *   --viewport "cssW,cssH"  非 fullPage 视口截图：坐标视为 CSS 视口坐标，按截图/视口换算
  *   --fullpage --dpr N  fullPage 全页截图：坐标视为整页 CSS 坐标，按 DPR 等比缩放
  *   --margin-frac  画布四周留白比例（相对图片**短边**，另设绝对上限 200px，防全页长图画布过大），缺省 0.05
- *   --url       可选：在标题条右侧显示页面 URL（用于「URL 可见」证据要求）
+ *   --url       在标题条右侧显示页面 URL。⚠️ 规则必填：「⚠️ 截图规范」要求每张截图都在图上写出
+ *               文字版完整 URL（不得只靠地址栏），所以实际调用时都应传本参数
  *
  * 渲染为 PNG 的固定流程（配合 screenshot-annotate skill）：
  *   1. 生成标注 HTML：  node annotate.js shot.png shot-annot.html --json '...' --label '...'