@routerhub/agent-rules 1.5.206 → 1.5.208

package/AGENTS.base.md

@@ -176,6 +176,15 @@ agent-rules 生成的规则文件分两层，行为与归属不同，评审/发
 - ⚠️ **编写 HTML 页面或前端功能后，必须用测试环境的真实数据验证，禁止用虚构/mock 数据自测。** 虚构数据只能验证「代码不报错」，无法验证「功能在真实场景下正常工作」——真实数据会暴露边界情况（空值、超长文本、特殊字符、异常关联关系等），虚构数据碰不到这些。测试环境有真实数据时优先用测试环境；测试环境数据不足时，从生产环境脱敏导出。
 - ⚠️ **页面功能验证必须通过实际的页面交互操作来完成**（打开浏览器、点击按钮、填写表单、观察渲染结果），模拟真实用户操作路径。禁止只靠代码审查、单元测试断言或静态分析代替实际页面操作验证——用户最终是通过页面交互使用功能的，不是通过测试断言。能用浏览器手动操作的，就用浏览器手动操作一遍。
 
+## ⚠️ 验收环境铁律（先部署到测试环境再取证，禁止拿本地环境交差）
+
+- ⚠️ **功能验收 / 取证（给人看的截图、报告、PR 效果图）必须在「别人能直接打开的环境」（测试环境域名）上做，禁止用本地环境的结果交差。** 本地环境（`localhost` / `127.0.0.1` / `vite dev` / 各类「一键启动」脚本 / `file:///` 本机文档）的证据只有你自己看得到：它依赖你本机的数据库、配置中心取值、未提交的代码、正在跑的进程与端口——别人照同样的命令跑，得到的是另一套环境，复现不出你截图里的样子。**证据的价值在于别人能独立打开、独立复核；打不开的证据等于没有证据。**
+- ⚠️ **正确顺序：改完代码 → 部署到测试环境（走 `/deploy-test`）→ 在测试环境域名上操作取证。** 禁止在本地截完图再补一句「测试环境效果相同」——那是推断，不是证据（呼应「⚠️ 环境配置禁止推断」）。
+- ⚠️ **本地环境允许用于开发中的即时联调与排错，但产出的截图/结果一律不得作为交付证据。** 一句话自查：**这张图 / 这个 URL 发给别人，他在自己电脑上能直接打开看到同一个页面吗？** 不能 → 它不是证据，先部署到测试环境再重新取证。
+- ⚠️ **依赖中间件的证据（Redis / 数据库 / 日志）同样连测试环境实例取证**，禁止截本机 Docker 里的 Redis / 本地库——本机实例的值与测试环境无关，证明不了任何事。
+- ⚠️ **例外（仅此两种，且必须在报告里写明「本地环境」及原因）**：① 功能尚未部署到测试环境、且用户明确要求「先看本地效果」；② 该环境客观无法部署（如纯本地离线工具）。除此以外一律先部署再取证。
+- **类比**：请朋友来家里看新装修，却只发一张你自己手机里的照片——他既进不来、也没法确认这照片是不是你家。把地址给他（测试环境域名），他推门进来自己看，这才叫证据。
+
 ## ⚠️ 可视化验证铁律（默认不写测试用例，用证据说话）
 
 - ⚠️ **AI 默认禁止主动写「测试用例」**（单元测试、Playwright E2E、API 冒烟脚本等）。写不写测试、写哪些，完全由用户显式提出（如「加测试」「写测试用例」「补一条回归用例」）才执行。AI 不得在未获明确指令时自行创建测试用例、主动建议补测试、或把「测试先行 / TDD」当作默认开发姿势。
@@ -337,7 +346,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 可见且能打开**：截图中必须能看到当前页面 URL，且该 URL 必须是别人能直接打开的地址（测试环境 / 线上域名），**禁止 `localhost` / `127.0.0.1` / `file:///` 等本机地址**——reviewer 在自己机器上打不开，等于没给。同时在截图旁以文字写出这条 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 阅读，且多了一步手动搬运、容易出错。
@@ -589,7 +598,7 @@ 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 必须是别人能直接打开访问的地址（测试环境 / 线上域名）**：交付时把这条 URL 连同截图一起给出（正文里以文字再写一遍，方便一眼复制打开），别人点开就能看到同一个页面、亲眼复核。**禁止用本机地址充当 URL**——`localhost`、`127.0.0.1`、内网 IP、`file:///...` 本机路径在别人机器上要么打不开、要么指向他自己的机器，等于没给 URL（呼应「⚠️ 验收环境铁律」）。页面本身没有地址栏时，在页面顶部叠加一条 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

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

package/package.json

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

package/rules/global.md

@@ -176,6 +176,15 @@ agent-rules 生成的规则文件分两层，行为与归属不同，评审/发
 - ⚠️ **编写 HTML 页面或前端功能后，必须用测试环境的真实数据验证，禁止用虚构/mock 数据自测。** 虚构数据只能验证「代码不报错」，无法验证「功能在真实场景下正常工作」——真实数据会暴露边界情况（空值、超长文本、特殊字符、异常关联关系等），虚构数据碰不到这些。测试环境有真实数据时优先用测试环境；测试环境数据不足时，从生产环境脱敏导出。
 - ⚠️ **页面功能验证必须通过实际的页面交互操作来完成**（打开浏览器、点击按钮、填写表单、观察渲染结果），模拟真实用户操作路径。禁止只靠代码审查、单元测试断言或静态分析代替实际页面操作验证——用户最终是通过页面交互使用功能的，不是通过测试断言。能用浏览器手动操作的，就用浏览器手动操作一遍。
 
+## ⚠️ 验收环境铁律（先部署到测试环境再取证，禁止拿本地环境交差）
+
+- ⚠️ **功能验收 / 取证（给人看的截图、报告、PR 效果图）必须在「别人能直接打开的环境」（测试环境域名）上做，禁止用本地环境的结果交差。** 本地环境（`localhost` / `127.0.0.1` / `vite dev` / 各类「一键启动」脚本 / `file:///` 本机文档）的证据只有你自己看得到：它依赖你本机的数据库、配置中心取值、未提交的代码、正在跑的进程与端口——别人照同样的命令跑，得到的是另一套环境，复现不出你截图里的样子。**证据的价值在于别人能独立打开、独立复核；打不开的证据等于没有证据。**
+- ⚠️ **正确顺序：改完代码 → 部署到测试环境（走 `/deploy-test`）→ 在测试环境域名上操作取证。** 禁止在本地截完图再补一句「测试环境效果相同」——那是推断，不是证据（呼应「⚠️ 环境配置禁止推断」）。
+- ⚠️ **本地环境允许用于开发中的即时联调与排错，但产出的截图/结果一律不得作为交付证据。** 一句话自查：**这张图 / 这个 URL 发给别人，他在自己电脑上能直接打开看到同一个页面吗？** 不能 → 它不是证据，先部署到测试环境再重新取证。
+- ⚠️ **依赖中间件的证据（Redis / 数据库 / 日志）同样连测试环境实例取证**，禁止截本机 Docker 里的 Redis / 本地库——本机实例的值与测试环境无关，证明不了任何事。
+- ⚠️ **例外（仅此两种，且必须在报告里写明「本地环境」及原因）**：① 功能尚未部署到测试环境、且用户明确要求「先看本地效果」；② 该环境客观无法部署（如纯本地离线工具）。除此以外一律先部署再取证。
+- **类比**：请朋友来家里看新装修，却只发一张你自己手机里的照片——他既进不来、也没法确认这照片是不是你家。把地址给他（测试环境域名），他推门进来自己看，这才叫证据。
+
 ## ⚠️ 可视化验证铁律（默认不写测试用例，用证据说话）
 
 - ⚠️ **AI 默认禁止主动写「测试用例」**（单元测试、Playwright E2E、API 冒烟脚本等）。写不写测试、写哪些，完全由用户显式提出（如「加测试」「写测试用例」「补一条回归用例」）才执行。AI 不得在未获明确指令时自行创建测试用例、主动建议补测试、或把「测试先行 / TDD」当作默认开发姿势。
@@ -337,7 +346,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 可见且能打开**：截图中必须能看到当前页面 URL，且该 URL 必须是别人能直接打开的地址（测试环境 / 线上域名），**禁止 `localhost` / `127.0.0.1` / `file:///` 等本机地址**——reviewer 在自己机器上打不开，等于没给。同时在截图旁以文字写出这条 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 阅读，且多了一步手动搬运、容易出错。
@@ -589,7 +598,7 @@ 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 必须是别人能直接打开访问的地址（测试环境 / 线上域名）**：交付时把这条 URL 连同截图一起给出（正文里以文字再写一遍，方便一眼复制打开），别人点开就能看到同一个页面、亲眼复核。**禁止用本机地址充当 URL**——`localhost`、`127.0.0.1`、内网 IP、`file:///...` 本机路径在别人机器上要么打不开、要么指向他自己的机器，等于没给 URL（呼应「⚠️ 验收环境铁律」）。页面本身没有地址栏时，在页面顶部叠加一条 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,7 @@ description: >-
 ### 截图规范
 
 - 截取整页（full page），不是可视区域；用真实视口宽度（4K 屏自然宽 3840），禁止强制把视口拉宽
-- 截图结果必须包含当前页面 URL
+- 截图结果必须包含当前页面 URL，且该 URL 必须是别人能直接打开的地址（测试环境 / 线上域名），禁止 `localhost` / `127.0.0.1` / `file:///` 等本机地址；截图一律在测试环境取证，本地效果不作交付证据
 - ⚠️ **截图版 HTML 的每张截图都必须加箭头（或红框）标注**，指向该图要说明的关键操作点或关键数据，禁止放无标注的「裸截图」；标注放在页面空白区域，不遮挡关键内容。⚠️ **标注坐标必须精确**：用 `/screenshot-annotate` skill（浏览器 DOM 测得的坐标 → `annotate.js` 换算到截图像素），禁止肉眼估位
 - 制作过程中产生的中间截图文件统一放到 `screenshots/` 目录
 

package/skills/create-pr/SKILL.md

@@ -77,7 +77,8 @@ Closes #issue编号
 - ⚠️ **必须 `fullPage: true` 截完整页面**，不要只截视口的一部分。每个改动点都要覆盖到，禁止只截视口内一屏。
 - ⚠️ **截图必须全面（多图覆盖多个角度）**：一张全页图 + 每个关键改动区域的局部放大图。只截一处、截局部、漏掉改动点都不算全。整份 PR Description 的效果截图要使 reviewer 不看代码就能看全本次改动。
 - ⚠️ **每张截图必须用醒目箭头 + 简短文字标签标注关键改动区域/验证点**，让看的人一眼看懂这张图证明了什么；修复前用红框/红箭头，修复后用绿框/绿箭头，标注放在不遮挡原内容的位置。禁止只贴裸图不标注。⚠️ **标注坐标必须精确**：统一用 `/screenshot-annotate` skill（`getBoundingClientRect()` + `scrollX/scrollY` 换算到截图像素，用 `annotate.js` 脚本画箭头），禁止肉眼看图估坐标。
-- ⚠️ **截图中必须能看到当前页面 URL**（浏览器地址栏，或页面顶部叠加 URL 标注），确保证据可追溯。
+- ⚠️ **截图中必须能看到当前页面 URL，且该 URL 必须是别人能直接打开的地址（测试环境 / 线上域名）**——`localhost` / `127.0.0.1` / `file:///` 等本机地址在 reviewer 机器上打不开，等于没给。同时在截图旁以文字写出这条 URL，方便一眼复制复核。
+- ⚠️ **所有截图一律在测试环境取证**：先部署到测试环境（`/deploy-test`）再操作截图，禁止拿本地运行的效果当交付证据——本地依赖你本机的库/配置/未提交代码，别人照同样命令跑不出来（本地仅可用于开发中即时联调，不作证据）。
 - ⚠️ 截图保存到本地磁盘 `docs/` 对应子目录（文件名「编号 + 英文描述」，如 `01-before.png` / `02-after.png`），上传 CDN 后按规则清理临时文件，禁止提交到 Git 仓库。
 - ⚠️ 必须展示前后对比（修复前红框，修复后绿框），标注不遮挡页面内容。
 

package/skills/forensic-report/SKILL.md

@@ -80,7 +80,10 @@ def brief(values, keep=12):
     return values[:keep] + ["… 共 %d 个" % len(values)]
 
 before, after = "before.png", "after.png"
-print("md5 一致？", md5(before) == md5(after))   # True = 逐字节完全相同，最强证据
+md5_before, md5_after = md5(before), md5(after)
+print("md5 before：%s" % md5_before)   # 打印完整 32 位值：报告里要原样贴出来，供读者自己复算
+print("md5 after ：%s" % md5_after)
+print("md5 一致？", md5_before == md5_after)   # True = 逐字节完全相同，最强证据
 
 a = Image.open(before).convert("RGB")
 b = Image.open(after).convert("RGB")
@@ -109,7 +112,7 @@ else:
 **两个概念要向读者解释清楚（报告里直接写人话）**：
 
 - **「md5 一致」是什么意思**：md5 是把一整个文件算成一段 32 位十六进制指纹，文件里哪怕只改了 1 个 bit，指纹就完全不同。两张 PNG 的 md5 相同 = **逐字节完全相同**，比「像素一样」还强一层（连压缩块、元数据都没变）。
-- **「逐像素相减」是怎么做的**：两张同尺寸的整页图，按坐标一一对应的像素做减法，统计有多少个像素不一样、落在哪一列哪一行。一张 1680 宽的整页截图约 300 万个像素，**只要有一个像素颜色变了就会被抓到**。
+- **「逐像素相减」是怎么做的**：两张同尺寸的整页图，按坐标一一对应的像素做减法，统计有多少个像素不一样、落在哪一列哪一行。一张 1680×2400 的整页截图有 403 万个像素（1680 × 2400 = 4,032,000），**只要有一个像素颜色变了就会被抓到**。
 
 ### 第 3 层 · 数据库逐行（绕过前端，最权威）
 
@@ -150,7 +153,7 @@ SELECT provider_id, count(*) FROM provider_model_pricing
 
 **实例（可直接作为图注模板）**：
 
-> 整页 1680×2400 共约 300 万像素，**只有 17 个不同**，全部落在 `x=383` 这**一列**、`y=150..166` 这 17 **行**。改动前该处纯白 `(255,255,255)`，改动后是一条 1px 深灰竖线 `(55,65,81)`；左右相邻的 `(382)` 与 `(384)` 前后**都是纯白**。单列、1px 宽、竖直、两侧纯白、位于搜索框内部 —— 只可能是输入框的文本光标，不是数据变化。
+> 整页 1680×2400 共 403 万像素（4,032,000），**只有 17 个不同**，全部落在 `x=383` 这**一列**、`y=150..166` 这 17 **行**。改动前该处纯白 `(255,255,255)`，改动后是一条 1px 深灰竖线 `(55,65,81)`；左右相邻的 `(382)` 与 `(384)` 前后**都是纯白**。单列、1px 宽、竖直、两侧纯白、位于搜索框内部 —— 只可能是输入框的文本光标，不是数据变化。
 
 ⚠️ **「左右相邻像素前后都是纯白」这一句是关键**：它排除了「这是一块色斑 / 一个被改动的单元格 / 一段被换掉的文字」。报告里要给出这几个值，让读者能自己下同样的结论。
 

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 可见」
+- `--label` 顶部标题条（适合「修复前/修复后」对比）、`--url` 在标题条显示 URL 满足「URL 可见」。⚠️ **`--url` 传的必须是别人能直接打开的地址（测试环境 / 线上域名）**——传 `localhost` / `127.0.0.1` / `file:///` 只是形式上「有 URL」，看的人打不开，等于没给
 - `text` 文本框自动排布在目标旁空闲侧，不遮挡内容；`w/h` 存在时画高亮圆角框指向其中心
 
 ## 渲染标注 HTML 为 PNG（固定流程）
@@ -114,7 +114,7 @@ agent-browser --cdp 9226 --namespace "$NS" tab close <tabId>
 
 - 箭头尖端指向的元素，肉眼应与 eval 捕获到的目标一致（坐标没歪）
 - 文本框不遮挡关键内容
-- 标注入口处能确认 URL（标题条或截图内地址栏）
+- 标注入口处能确认 URL（标题条或截图内地址栏），且该 URL 是别人能直接打开的地址（非 `localhost` / `127.0.0.1` / `file:///`）
 - 修改坐标/文字后重新跑脚本 + 渲染，不要在原图上手工补。
 
 ## 重要规则