@routerhub/agent-rules 1.5.146 → 1.5.148

package/AGENTS.base.md

@@ -131,9 +131,9 @@
 
 - ⚠️ PR Title / Description / Test Plan 全部中文。
 - ⚠️ **PR 必须附效果截图作为可视化证据，且逐条满足以下硬性要求（缺一不可，禁止跳过）**：
-  - **4K 全页**：截图视口统一 3840px 宽、`fullPage` 截完整页面，禁止用 1920px、禁止只截视口一屏。
+  - **全页图**：用浏览器真实视口（`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，确保证据可追溯。
   - **前后对比**：必须同时展示修复前与修复后。
 - ⚠️ **截图必须直接内嵌在 PR Description 中，让 reviewer 打开 PR 就能看到效果图（`![](CDN_URL)` 方式渲染为可见图片），禁止只在文字里描述"改动了什么"而不放图，也禁止把截图只作为文件附件/提交到分支目录而不在 PR 正文中引用。** 原因：reviewer 看 PR 的第一眼就是看描述，如果看不到图、只能读文字，完全无法直观感知改动效果；截图不内嵌 = 等于没附。
@@ -147,9 +147,9 @@
   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 链接给用户 → 发新版本，六步缺一不可，全程自动执行：
-  1. **自动走循环 review**：创建完 PR 后自动触发 `/loop-review` skill，反复「拉取 AI review（Claude Opus + GPT 交叉验证）→ 逐条读真实代码判断哪些值得修 → 值得修的改、不值得修/误报的 Won't fix 切断 → push 触发新一轮 review」，直到某一轮不再冒出值得修的新问题才结束，禁止只跑一轮就收工。
-  2. **重新部署到测试环境**：循环 review 走完后，自动触发 `/deploy-test` skill，把最新代码重新部署到测试环境，确保测试的是循环 review 之后的最终代码。
-  3. **测试环境验证 + 全程截图标注**：在测试环境用真实数据、真实页面交互测试本次改动（遵循「⚠️ 页面功能验证铁律」「⚠️ 用户视角测试铁律」）。测试过程中每一步都截图保留（遵循「⚠️ 截图规范」：视口 3840px 宽、`fullPage` 全页、URL 可见、存盘到 `docs/` 对应子目录），并在每张截图上用**箭头标注**关键改动区域/验证点，让看的人一眼看懂这张图证明了什么。
+  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 可见、存盘到 `docs/` 对应子目录），并在每张截图上用**坐标换算后的箭头标注**（走 `/screenshot-annotate` skill）关键改动区域/验证点，让看的人一眼看懂这张图证明了什么。
   4. **确认没问题才算完成**：测试通过、截图与箭头标注齐全、功能符合预期，才算真正完成。禁止测试没跑、截图没标注就宣称完成。
   5. **把 PR 链接发给用户**：确认没问题后，先把 PR 链接发送给用户（`gh pr view <PR> --json url -q .url`），让用户能直接打开查看，再执行发版。
   6. **发新版本**：确认没问题、PR 链接已发送后，按上面三步收尾完成冲突检查与静态编译检查，PR 合并后执行根目录 `./release.sh` 发新版本。
@@ -199,9 +199,10 @@
 
 ## ⚠️ 截图规范
 
-- ⚠️ **截图视口宽度统一按 4K（3840px 宽）设置，禁止用 1920px**。1920 宽对复杂内容看不全、看不清。用 agent-browser 时先 `agent-browser --cdp 9223 viewport 3840 <height>`（高度按内容给足，如 2400+），或全页截图并保证宽度 3840。
-- ⚠️ **截图必须 `fullPage: true` 截完整页面**，不要只截视口的一部分。
+- ⚠️ **截图用浏览器真实视口宽度（`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 标注），确保证据可追溯。
+- ⚠️ **标注必须准确，坐标必须有浏览器测量来源**：箭头/框要指哪儿，用 `getBoundingClientRect()` + `scrollX/scrollY` 取元素在整页中的 CSS 坐标，再按截图实际宽度换算成截图像素，统一用 `/screenshot-annotate` skill（含 `annotate.js` 脚本）标注。禁止用肉眼看图估坐标，禁止在强制缩放造成坐标错位的前提下标注。
 - **保存到磁盘文件**（`page.screenshot({ path, fullPage: true })`），禁止只用内联展示的截图工具——内联的不落盘，用户无法在 Markdown / HTML 文档里查看。路径统一放 `docs/` 对应功能子目录，文件名用「编号 + 英文描述」（如 `01-login-page.png`）。
 
 ### 非 UI / 后端 / 基础设施改动的效果截图获取方法
@@ -329,6 +330,24 @@
 - ⚠️ **日常对话中，只要聊到写代码/改代码/排查问题/验证功能/实现需求等任何越过「闲聊」的实质内容，就自动触发 `/visual-report` skill，用它管理「验证证据」的产出**，无需用户额外吩咐。触发不依赖于用户正式说「提需求」「做功能」——用户在平常对话里随口提到的开发任务（如「这个页面的按钮没反应」「Redis 里这个 key 好像不对」「帮我把这个查询优化一下」）同样自动触发。该 skill 的职责是：真实数据 + 真实交互 + 可视化证据（页面截图 / Redis 截图 / 数据库截图），把「功能对不对」用用户能一眼看懂的截图和报告证明给用户看。
 - ⚠️ **只有用户显式提到「测试 / TDD / 测试用例」时，才调用 `/tdd-workflow` skill**（写测试用例、跑回归）。没有明确指令时，禁止把 TDD 当作默认开发流程；默认开发流程是上面的 `/visual-report`。
 
+## 🚨 agent-browser 标签页防串扰（所有项目通用）
+
+**根因**：agent-browser 的「当前活动标签页」由共享守护进程维护。多个 Claude 会话
+共用同一个 CDP Chrome（如端口 9226）时，任一会话执行 `tab new` / `tab <n>` /
+`screenshot` 都会把 Chrome 全局活动页切走，导致本会话的 `eval` / `snapshot` /
+`click` / `fill` 落到**别人正在操作的标签页**上（已实测复现：eval 返回了另一个
+任务的页面）。
+
+**必须遵守**：
+1. 每次浏览器操作都固定带专属 `--namespace <会话唯一标识>`，同一会话全程不变。
+2. 不信任「当前活动页是哪一页」。任何操作前先 `agent-browser tab` 列出标签页，
+   按 URL 特征找到自己的页，再执行操作；**把「切到自己的 tab + 全部操作」合并进
+   同一次 Bash 调用**（`tab 15 && ...`），中间不等待、不留空隙，不给其他会话插队。
+3. `tab new` 打开页面后**立即记录返回的 tab id**（如 `t15`），后续每条操作先
+   `tab 15` 再操作，不要靠默认活动页猜测。
+4. 一旦 `eval` / `snapshot` 返回的内容不是自己操作的页面（URL/内容不符），
+   **第一反应是标签页被抢占**：切回自己的 tab id 后重试，禁止盲目重试同一条命令。
+
 ## 优先级
 
 1. 项目私有规则（AGENTS.private.md）

package/package.json

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

package/rules/global.md

@@ -131,9 +131,9 @@ name: "通用规则"
 
 - ⚠️ PR Title / Description / Test Plan 全部中文。
 - ⚠️ **PR 必须附效果截图作为可视化证据，且逐条满足以下硬性要求（缺一不可，禁止跳过）**：
-  - **4K 全页**：截图视口统一 3840px 宽、`fullPage` 截完整页面，禁止用 1920px、禁止只截视口一屏。
+  - **全页图**：用浏览器真实视口（`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，确保证据可追溯。
   - **前后对比**：必须同时展示修复前与修复后。
 - ⚠️ **截图必须直接内嵌在 PR Description 中，让 reviewer 打开 PR 就能看到效果图（`![](CDN_URL)` 方式渲染为可见图片），禁止只在文字里描述"改动了什么"而不放图，也禁止把截图只作为文件附件/提交到分支目录而不在 PR 正文中引用。** 原因：reviewer 看 PR 的第一眼就是看描述，如果看不到图、只能读文字，完全无法直观感知改动效果；截图不内嵌 = 等于没附。
@@ -147,9 +147,9 @@ name: "通用规则"
   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 链接给用户 → 发新版本，六步缺一不可，全程自动执行：
-  1. **自动走循环 review**：创建完 PR 后自动触发 `/loop-review` skill，反复「拉取 AI review（Claude Opus + GPT 交叉验证）→ 逐条读真实代码判断哪些值得修 → 值得修的改、不值得修/误报的 Won't fix 切断 → push 触发新一轮 review」，直到某一轮不再冒出值得修的新问题才结束，禁止只跑一轮就收工。
-  2. **重新部署到测试环境**：循环 review 走完后，自动触发 `/deploy-test` skill，把最新代码重新部署到测试环境，确保测试的是循环 review 之后的最终代码。
-  3. **测试环境验证 + 全程截图标注**：在测试环境用真实数据、真实页面交互测试本次改动（遵循「⚠️ 页面功能验证铁律」「⚠️ 用户视角测试铁律」）。测试过程中每一步都截图保留（遵循「⚠️ 截图规范」：视口 3840px 宽、`fullPage` 全页、URL 可见、存盘到 `docs/` 对应子目录），并在每张截图上用**箭头标注**关键改动区域/验证点，让看的人一眼看懂这张图证明了什么。
+  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 可见、存盘到 `docs/` 对应子目录），并在每张截图上用**坐标换算后的箭头标注**（走 `/screenshot-annotate` skill）关键改动区域/验证点，让看的人一眼看懂这张图证明了什么。
   4. **确认没问题才算完成**：测试通过、截图与箭头标注齐全、功能符合预期，才算真正完成。禁止测试没跑、截图没标注就宣称完成。
   5. **把 PR 链接发给用户**：确认没问题后，先把 PR 链接发送给用户（`gh pr view <PR> --json url -q .url`），让用户能直接打开查看，再执行发版。
   6. **发新版本**：确认没问题、PR 链接已发送后，按上面三步收尾完成冲突检查与静态编译检查，PR 合并后执行根目录 `./release.sh` 发新版本。
@@ -199,9 +199,10 @@ name: "通用规则"
 
 ## ⚠️ 截图规范
 
-- ⚠️ **截图视口宽度统一按 4K（3840px 宽）设置，禁止用 1920px**。1920 宽对复杂内容看不全、看不清。用 agent-browser 时先 `agent-browser --cdp 9223 viewport 3840 <height>`（高度按内容给足，如 2400+），或全页截图并保证宽度 3840。
-- ⚠️ **截图必须 `fullPage: true` 截完整页面**，不要只截视口的一部分。
+- ⚠️ **截图用浏览器真实视口宽度（`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 标注），确保证据可追溯。
+- ⚠️ **标注必须准确，坐标必须有浏览器测量来源**：箭头/框要指哪儿，用 `getBoundingClientRect()` + `scrollX/scrollY` 取元素在整页中的 CSS 坐标，再按截图实际宽度换算成截图像素，统一用 `/screenshot-annotate` skill（含 `annotate.js` 脚本）标注。禁止用肉眼看图估坐标，禁止在强制缩放造成坐标错位的前提下标注。
 - **保存到磁盘文件**（`page.screenshot({ path, fullPage: true })`），禁止只用内联展示的截图工具——内联的不落盘，用户无法在 Markdown / HTML 文档里查看。路径统一放 `docs/` 对应功能子目录，文件名用「编号 + 英文描述」（如 `01-login-page.png`）。
 
 ### 非 UI / 后端 / 基础设施改动的效果截图获取方法
@@ -329,6 +330,24 @@ name: "通用规则"
 - ⚠️ **日常对话中，只要聊到写代码/改代码/排查问题/验证功能/实现需求等任何越过「闲聊」的实质内容，就自动触发 `/visual-report` skill，用它管理「验证证据」的产出**，无需用户额外吩咐。触发不依赖于用户正式说「提需求」「做功能」——用户在平常对话里随口提到的开发任务（如「这个页面的按钮没反应」「Redis 里这个 key 好像不对」「帮我把这个查询优化一下」）同样自动触发。该 skill 的职责是：真实数据 + 真实交互 + 可视化证据（页面截图 / Redis 截图 / 数据库截图），把「功能对不对」用用户能一眼看懂的截图和报告证明给用户看。
 - ⚠️ **只有用户显式提到「测试 / TDD / 测试用例」时，才调用 `/tdd-workflow` skill**（写测试用例、跑回归）。没有明确指令时，禁止把 TDD 当作默认开发流程；默认开发流程是上面的 `/visual-report`。
 
+## 🚨 agent-browser 标签页防串扰（所有项目通用）
+
+**根因**：agent-browser 的「当前活动标签页」由共享守护进程维护。多个 Claude 会话
+共用同一个 CDP Chrome（如端口 9226）时，任一会话执行 `tab new` / `tab <n>` /
+`screenshot` 都会把 Chrome 全局活动页切走，导致本会话的 `eval` / `snapshot` /
+`click` / `fill` 落到**别人正在操作的标签页**上（已实测复现：eval 返回了另一个
+任务的页面）。
+
+**必须遵守**：
+1. 每次浏览器操作都固定带专属 `--namespace <会话唯一标识>`，同一会话全程不变。
+2. 不信任「当前活动页是哪一页」。任何操作前先 `agent-browser tab` 列出标签页，
+   按 URL 特征找到自己的页，再执行操作；**把「切到自己的 tab + 全部操作」合并进
+   同一次 Bash 调用**（`tab 15 && ...`），中间不等待、不留空隙，不给其他会话插队。
+3. `tab new` 打开页面后**立即记录返回的 tab id**（如 `t15`），后续每条操作先
+   `tab 15` 再操作，不要靠默认活动页猜测。
+4. 一旦 `eval` / `snapshot` 返回的内容不是自己操作的页面（URL/内容不符），
+   **第一反应是标签页被抢占**：切回自己的 tab id 后重试，禁止盲目重试同一条命令。
+
 ## 优先级
 
 1. 项目私有规则（AGENTS.private.md）

package/skills/create-doc/SKILL.md

@@ -67,9 +67,9 @@ description: >-
 
 ### 截图规范
 
-- 截取整页（full page），不是可视区域
+- 截取整页（full page），不是可视区域；用真实视口宽度（4K 屏自然宽 3840），禁止强制把视口拉宽
 - 截图结果必须包含当前页面 URL
-- ⚠️ **截图版 HTML 的每张截图都必须加箭头（或红框）标注**，指向该图要说明的关键操作点或关键数据，禁止放无标注的「裸截图」；标注放在页面空白区域，不遮挡关键内容
+- ⚠️ **截图版 HTML 的每张截图都必须加箭头（或红框）标注**，指向该图要说明的关键操作点或关键数据，禁止放无标注的「裸截图」；标注放在页面空白区域，不遮挡关键内容。⚠️ **标注坐标必须精确**：用 `/screenshot-annotate` skill（浏览器 DOM 测得的坐标 → `annotate.js` 换算到截图像素），禁止肉眼估位
 - 制作过程中产生的中间截图文件统一放到 `screenshots/` 目录
 
 ### 分步操作记录（每步必录）

package/skills/create-pr/SKILL.md

@@ -58,7 +58,7 @@ Closes #issue编号
 1. **截修复后**：浏览器打开改动页面 → 滚动到改动区域 → 全页截图
 2. **截修复前**：临时注释/回退改动代码 → 等 hot reload → 同位置截图 → 恢复代码
    - ⚠️ **若线上数据已变化，导致无法在真实页面复现"修复前"效果**：允许改用等价的纯逻辑对比代替（用新旧两版逻辑代码跑同样的输入数据，把输出结果差异渲染成对比图），但必须在 Description 里明确写清楚"为什么无法复现 + 用了什么替代方案"，禁止因此省略截图或假装能复现。
-3. **生成对比图**：用 sharp 拼接 → 上方红/绿色标注条（❌修复前 / ✅修复后）→ 下方左右并排截图 → 关键改动区域用箭头 + 红/绿框圈选
+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)` 内嵌
    - ⚠️ **禁止走评论区上传再搬运 CDN URL**：评论区上传需要多一步「提交评论 → 复制 URL → 粘贴到 Description」，产生的临时图片评论会留在 PR 对话里干扰 reviewer 阅读，且多一步手动搬运容易出错
@@ -66,10 +66,10 @@ Closes #issue编号
 5. **保存 Description**：确认图片已内嵌进 Description 正文后，保存 PR Description 使图片持久化
 
 **截图硬性规范（PR 效果截图必须逐条满足，缺一不可，禁止跳过）**：
-- ⚠️ **视口宽度统一 4K（3840px 宽）**：用 agent-browser 时先 `agent-browser --cdp 9223 viewport 3840 <height>`（高度按内容给足，如 2400+），或全页截图并保证宽度 3840。禁止用 1920px——1920 宽对复杂内容看不全、看不清。
+- ⚠️ **全页图用浏览器真实视口宽度（`window.innerWidth` 即截图宽，4K 屏自然宽 3840）**，用 agent-browser 时先 `set viewport <视口宽> <合适高度>` 固定视口，再 `screenshot --full` 截完整页面。⚠️ **禁止强制 `set viewport 3840 <h>` 把 CSS 视口拉宽到比屏幕还宽**（页面会缩小看不清、且 CSS 像素与截图像素缩放错位导致标注不准）；需要更高清晰度时用 `set viewport <W> <H> 2`（DPR 倍率，CSS 宽不变、像素更密）。
 - ⚠️ **必须 `fullPage: true` 截完整页面**，不要只截视口的一部分。每个改动点都要覆盖到，禁止只截视口内一屏。
 - ⚠️ **截图必须全面（多图覆盖多个角度）**：一张全页图 + 每个关键改动区域的局部放大图。只截一处、截局部、漏掉改动点都不算全。整份 PR Description 的效果截图要使 reviewer 不看代码就能看全本次改动。
-- ⚠️ **每张截图必须用醒目箭头 + 简短文字标签标注关键改动区域/验证点**，让看的人一眼看懂这张图证明了什么；修复前用红框/红箭头，修复后用绿框/绿箭头，标注放在不遮挡原内容的位置。禁止只贴裸图不标注。
+- ⚠️ **每张截图必须用醒目箭头 + 简短文字标签标注关键改动区域/验证点**，让看的人一眼看懂这张图证明了什么；修复前用红框/红箭头，修复后用绿框/绿箭头，标注放在不遮挡原内容的位置。禁止只贴裸图不标注。⚠️ **标注坐标必须精确**：统一用 `/screenshot-annotate` skill（`getBoundingClientRect()` + `scrollX/scrollY` 换算到截图像素，用 `annotate.js` 脚本画箭头），禁止肉眼看图估坐标。
 - ⚠️ **截图中必须能看到当前页面 URL**（浏览器地址栏，或页面顶部叠加 URL 标注），确保证据可追溯。
 - ⚠️ 截图保存到本地磁盘 `docs/` 对应子目录（文件名「编号 + 英文描述」，如 `01-before.png` / `02-after.png`），上传 CDN 后按规则清理临时文件，禁止提交到 Git 仓库。
 - ⚠️ 必须展示前后对比（修复前红框，修复后绿框），标注不遮挡页面内容。
@@ -101,7 +101,7 @@ gh pr create \
 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. **测试环境验证 + 全程截图标注**：在测试环境用真实数据、真实页面交互测试本次改动（遵循「⚠️ 页面功能验证铁律」「⚠️ 用户视角测试铁律」）。测试过程中每一步都截图保留（遵循「⚠️ 截图规范」：视口 3840px 宽、`fullPage` 全页、URL 可见、存盘到 `docs/` 对应子目录），并在每张截图上用**箭头标注**关键改动区域/验证点，让看的人一眼看懂这张图证明了什么。
+4. **测试环境验证 + 全程截图标注**：在测试环境用真实数据、真实页面交互测试本次改动（遵循「⚠️ 页面功能验证铁律」「⚠️ 用户视角测试铁律」）。测试过程中每一步都截图保留（遵循「⚠️ 截图规范」：真实视口 + `fullPage` 全页、URL 可见、存盘到 `docs/` 对应子目录），并在每张截图上用**坐标换算后的箭头标注**（走 `/screenshot-annotate` skill）关键改动区域/验证点，让看的人一眼看懂这张图证明了什么。
 5. **确认没问题才算完成**：测试通过、截图与箭头标注齐全、功能符合预期，才算真正完成。禁止测试没跑、截图没标注就宣称完成。
 6. **发新版本**：确认没问题后，回到下方步骤 7 完成冲突检查与静态编译检查，PR 合并后执行根目录 `./release.sh` 发新版本。
 

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

@@ -0,0 +1,94 @@
+---
+name: pr-release-loop
+description: >-
+  PR 发布完整闭环（循环 review 之后的收尾）——创建 PR 后按 AGENTS.base.md「⚠️ 创建完 PR 后自动走完整闭环流程」自动走完
+  循环 review → 重新部署测试环境 → 测试环境复测 → 确认 → 发 PR 链接 → 发新版本 六步。核心防线：**循环 review 走完后，
+  必须重新部署到测试环境并复测，确认没问题之后才能发链接/发版**——这是最容易漏掉的一环（review 会改代码，跳过复测=拿旧代码下结论）。
+  触发场景包括但不限于：
+  「PR闭环」「闭环走完」「完整闭环」「六步闭环」「走完整流程」「收尾」「发布闭环」「发布收尾」「循环review完再部署测一遍」「测试环境再测一遍」。
+  以及「创建PR后的完整流程」「走完循环review流程」「循环review完之后」。
+  当循环 review 显示「无值得修的新问题」、进入收尾阶段时，**自动触发本 Skill**，无需用户再开口。
+---
+
+# PR 发布完整闭环（循环 review 之后的收尾）
+
+⚠️ **本 Skill 已触发。在用户回复中第一句话必须输出：「🔧 已触发 `pr-release-loop`，进入循环 review 之后的发布收尾闭环…」然后严格按照以下步骤执行，不得跳过。**
+
+创建 PR 之后，自动把完整闭环走完。**重点不是「做六件事」本身，而是第 3、4 步是重活、最容易在「收尾惯性」中被省略**——循环 review 走完时往往急着交付，直接把「重新部署测试环境 + 复测」跳过去了。本 Skill 就是那道闸。
+
+## ⚠️ 核心铁律（违反即错误）
+
+- ⚠️ **循环 review 结束 ≠ 完成。** review 期间会 push 新 commit，**只有把最新代码重新部署到测试环境、在测试环境复测通过，才算真正完成**。跳过复测直接用旧代码下结论 = 白 review。
+- ⚠️ **完成定义清单（终局前必须逐项自查并输出）：**
+  1. ✅ 循环 review 走完（`/loop-review`，直到某一轮不再冒出值得修的新问题）
+  2. ✅ 最新代码已提交并推送到 PR 分支
+  3. ✅ 已通过 `/deploy-test` 重新部署到测试环境（部署的是 review 之后的最终代码）
+  4. ✅ 测试环境用真实数据 + 真实交互复测通过（每张截图真实视口 + `fullPage` 全页、坐标换算箭头标注、URL 可见）
+  5. ✅ 与主分支无冲突（`gh pr view <PR> --json mergeable -q .mergeable` = `MERGEABLE`）
+  6. ✅ GitHub 静态编译通过（`gh pr checks <PR>` 无 `failure`）
+  7. ✅ PR 链接已发送给用户
+  8. ✅ 发新版本（`./release.sh`）
+- ⚠️ **循环 review 走完后，显式输出「✅ 循环 review 完成，进入发布收尾闭环」，然后逐项执行下面第 2～8 步，禁止在循环 review 结束后直接发链接/发版。** 若发现某一步没做（典型：忘了重新部署、复测是旧数据），必须停下来补齐再继续，禁止把「漏掉的第 3/4 步」带进交付。
+
+## 核心流程
+
+### 1. 确认循环 review 已完成
+
+```bash
+gh pr view <PR> --json comments -q '.comments | length'
+```
+
+确认 `/loop-review` 已走到「无值得修的新问题」那一轮（或达到最大轮数由用户决定结束）。若循环 review 还没走完，**先补跑 `/loop-review`，不得跳过**。
+
+### 2. 确保最新代码已推送
+
+循环 review 期间若有改动，确保已提交并推送到 PR 分支。若 review 过程中没有新增 commit，且已满足「无值得修的新问题」，则跳过本步（不必为了触发而空 push）。
+
+```bash
+git status && git push origin "$(git branch --show-current)"
+```
+
+### 3. 重新部署到测试环境（最容易漏的一步）
+
+⚠️ 必须触发 `/deploy-test` skill，**把「当前功能分支的最新代码」合并到 test 并部署**，确保测试的就是 review 之后的最终代码。
+
+> 为什么必须重部署：循环 review 的每次修复都 push 了新 commit。如果不重部署，测试环境跑的还是 review 之前的旧代码，等于用旧代码验证新改动，结论无效。
+
+### 4. 测试环境复测 + 全程截图标注
+
+- 在测试环境用**真实数据 + 真实交互**测试本次改动（遵循「⚠️ 页面功能验证铁律」「⚠️ 用户视角测试铁律」）。
+- 每步截图保留（遵循「⚠️ 截图规范」：真实视口 + `fullPage` 全页、URL 可见、存盘到 `docs/` 对应子目录），并用**坐标换算后的箭头标注**（走 `/screenshot-annotate` skill）关键改动区域/验证点，让看的人一眼看懂这张图证明了什么。
+- 若本次改动是纯后端/基础设施，按「非 UI / 后端 / 基础设施改动的效果截图获取方法」把 curl 响应渲染成暗色终端 HTML 截图。
+
+### 5. 确认没问题才算完成
+
+测试通过、截图与箭头标注齐全、功能符合预期，才算真正完成。**禁止测试没跑、截图没标注就宣称完成。**
+
+### 6. 冲突检查 + 静态编译检查（三步收尾）
+
+用 `gh pr view <PR> --json mergeable -q .mergeable` 检查冲突（`CONFLICTING` 必须先解决），用 `gh pr checks <PR>` 检查 CI（有 `failure` 必须修复重推）。两者都通过后才发链接/发版。
+
+### 7. 发 PR 链接给用户
+
+```bash
+gh pr view <PR> --json url -q .url
+```
+
+一般按下流程：循环 review 全部通过 → 部署测试环境复测 → 确认后**先发 PR 链接，再发版**。
+
+### 8. 发新版本
+
+PR 合并后按项目发布流程执行根目录 `./release.sh` 发新版本（自动完成 patch 号 +1、更新 `package.json`、`git commit`/`push`、打 tag、`npm publish`）。
+
+## 判断边界
+
+- ⚠️ **如果循环 review 走完但没有重新部署测试就发链接/发版 → 直接违背闭环，必须停下并报告缺失项**（你没说过「跳过复测」，这属于该做而没做）。
+- ⚠️ **用户明确说「不用部署测试」「跳过复测，直接发版」等显式指令** → 按用户指令执行，不必拦（但要在交付时说明「本次跳过了测试环境复测」）。
+- ⚠️ **纯文档/无逻辑改动（如只改 README）** → 可以跳过复测，但发链接/发版前仍要完成冲突+编译检查。
+
+## 相关
+
+- 循环 review 细节：`loop-review` skill
+- 部署测试环境：`deploy-test` skill
+- 创建 PR / 截图上传：`create-pr` skill
+- 验证证据产出：`visual-report` skill

package/skills/screenshot-annotate/SKILL.md

@@ -0,0 +1,116 @@
+---
+name: screenshot-annotate
+description: >-
+  截图标注的标准化流程。触发场景包括但不限于：
+  「给截图加标注」「截图标注」「标注截图的箭头」「给截图画箭头」「截图圈出来」「标注哪个区域」「标注关键区域」
+  「加箭头和文字」「给这张截图标注一下」「用箭头标注截图」「截图上的红框指着哪」等任何「对截图做标注/圈选/加箭头文字」的说法。
+  当截图规范要求「箭头标注」但需要保证「标注得准」（坐标换算、不靠肉眼估）时，也自动使用本 Skill。
+  核心：坐标必须来自浏览器 DOM 测量（getBoundingClientRect + 滚动量）精确换算到截图像素，再用统一脚本标注，
+  禁止肉眼看图估坐标。
+---
+
+# 截图标注标准化流程（Screenshot Annotate）
+
+⚠️ **本 Skill 已触发。在用户回复中第一句话必须输出：「🔧 已触发 `screenshot-annotate`，按坐标换算流程标注截图…」然后严格按照以下步骤执行。**
+
+## 核心原则
+
+- **标注必须准时归一到「坐标换算」**：箭头/框/文字放哪，由浏览器告诉我们的元素坐标（`getBoundingClientRect()` + `scrollX/scrollY`）经公式换算成截图里的像素位置；**禁止肉眼看图估坐标**。坐标对不上 = 标注就是歪的，这是以前「强制 4K 时标注不准」的根因。
+- **坐标必须是页面 CSS 坐标或浏览器直接给的缩放信息**，不能是截图里目测出来的点。
+
+## 标注坐标换算方法
+
+### 情形 A：真实视口 + `fullPage` 全页截图（推荐做法）
+
+浏览器 `window.innerWidth` 就是截图宽度（设了截图画布时也一样）。对全页截图：
+
+```
+元素在「整页」中的 CSS 位置 = rect.left + scrollX
+                         rect.top  + scrollY
+截图里对应像素位置 = 该 CSS 位置（fullPage 拼接时 1 CSS px = 1 设备像素） x 截图宽度 / 整页宽
+```
+
+一个 CSS 像素等于一个设备像素的前提下，`fullPage` 拼接图的坐标与 CSS 坐标直接对应，**无需再缩放**：
+标注时给 annotate.js 传 `x = rect.left + scrollX`、`y = rect.top + scrollY`，宽度 `w = rect.width`、高度 `h = rect.height`。
+
+### 情形 B：设置了自定义 viewport 视口的截图（截图宽度 = viewport 宽）
+
+浏览器把 viewport 设成 X×Y，截图宽高 = X×Y（`window.innerWidth` / `innerHeight`）。元素坐标直接用 `rect` 的值即可。
+
+### 情形 C：一个普通（非拼接、无缩放）截图
+
+如果截图就是某视口的渲染结果，且截图宽 ≠ CSS 视口宽，说明有 `devicePixelRatio` 缩放。
+此时标注坐标 = CSS 坐标 × (截图宽 / 视口 CSS 宽)（横向），(截图高 / 视口 CSS 高)（纵向）。
+
+## 坐标捕获命令（在打开的浏览器标签页上执行）
+
+用 `agent-browser --cdp 9226 --namespace <NS> eval` 捕获目标元素的精确坐标：
+
+```js
+(function () {
+  const el = document.querySelector('选择器');   // 替换成真实目标元素的选择器
+  if (!el) return { error: '未找到元素', selector: '选择器' };
+  const r = el.getBoundingClientRect();
+  return {
+    x: Math.round(r.left + window.scrollX),        // 整页内 CSS 像素
+    y: Math.round(r.top + window.scrollY),
+    w: Math.round(r.width),
+    h: Math.round(r.height),
+    url: location.href,
+    viewport: { w: window.innerWidth, h: window.innerHeight },
+    dpr: window.devicePixelRatio,
+  };
+})()
+```
+
+上次截图若用了 `set viewport` 设视口，在 eval 里把 `window.innerWidth/Height` 作为 viewport 一并读出，确认截图宽高与之一致。
+
+## 统一标注脚本 annotate.js
+
+标注由 `annotate.js`（本 skill 目录内的零依赖 Node 脚本）完成。它把截图 + 坐标转成自包含标注 HTML（截图 base64 内嵌、SVG 箭头/框/文字精确放在换算后的坐标上），再用无头浏览器渲染为 PNG。
+
+脚本与 SKILL.md 位于同一 skill 目录（随 agent-rules 同步到各项目 `.claude/skills/screenshot-annotate/`）。调用时定位到该目录：
+
+```bash
+SKILL_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"   # 或显式 .claude/skills/screenshot-annotate 目录
+node "$SKILL_DIR/annotate.js" \
+  shot.png shot-annot.html \
+  --json '[{"x":412,"y":1240,"w":160,"h":48,"text":"新增的保存按钮","color":"#22c55e"}]' \
+  --label "✅ 修复后" --labelColor "#f43f5e" --url "https://api-test.xxx/gateway/dashboard"
+```
+
+- 坐标默认视为**设备像素**（截图内坐标）；`--viewport "cssW,cssH"` 传入时视为 CSS 坐标会自动换算
+- `--label` 顶部标题条（适合「修复前/修复后」对比）、`--url` 在标题条显示 URL 满足「URL 可见」
+- `text` 文本框自动排布在目标旁空闲侧，不遮挡内容；`w/h` 存在时画高亮圆角框指向其中心
+
+## 渲染标注 HTML 为 PNG（固定流程）
+
+用 `SKILL_DIR/annotate.js` 生成标注 HTML 后，用无头浏览器渲染为 PNG。
+
+```bash
+NS="claude-截图标注"
+# 1. 无头打开标注 HTML
+agent-browser --cdp 9226 --namespace "$NS" tab new "file:///<上一步生成的绝对路径>/shot-annot.html"
+# 2. 设视口为标注画布尺寸（annotate.js 会打印「画布尺寸 WxH」）
+agent-browser --cdp 9226 --namespace "$NS" set viewport <W> <H>
+# 3. 全页截图
+agent-browser --cdp 9226 --namespace "$NS" screenshot --full shot-annot.png
+# 4. 关闭标签页
+agent-browser --cdp 9226 --namespace "$NS" tab close <tabId>
+```
+
+确认渲染图尺寸与画布一致、无黑边（`sips -g pixelWidth -g pixelHeight`），标注清晰后交付。
+
+## 校验
+
+- 箭头尖端指向的元素，肉眼应与 eval 捕获到的目标一致（坐标没歪）
+- 文本框不遮挡关键内容
+- 标注入口处能确认 URL（标题条或截图内地址栏）
+- 修改坐标/文字后重新跑脚本 + 渲染，不要在原图上手工补。
+
+## 重要规则
+
+- ⚠️ 坐标必须有浏览器测量来源，禁止目测
+- ⚠️ 每种「关键区域」都要箭头/框标注到位，禁止只标一处；多个改动点逐个覆盖
+- ⚠️ 若截图是真实视口截出的，尽量一图一文；整页图定位大区域，局部区域用放大图单独标注
+- 渲染用无头实例（不抢焦点）；如需给用户看效果用截图

package/skills/screenshot-annotate/annotate.js

@@ -0,0 +1,448 @@
+#!/usr/bin/env node
+/**
+ * annotate.js — 生成「标注 HTML」（零依赖，Node 内置模块实现）
+ *
+ * 作用：把一张截图 + 若干标注坐标，生成一个自包含的 HTML 文件——
+ *       截图 base64 内嵌为底图，SVG 在精确换算后的坐标上画
+ *       「箭头 + 文本框 + 圆角高亮框 + 顶部标题条」。
+ *       标注文字/箭头由浏览器引擎渲染（中文完美、抗锯齿），
+ *       再由 agent-browser 用无头 CDP 把 HTML 截成最终标注图。
+ *
+ * 为什么这样设计：
+ *   标注不准的根因是「坐标单位换算错位 + 人工肉眼看图估位」。
+ *   本脚本强制走「元素 CSS 坐标(getBoundingClientRect) + 滚动量 → 截图设备像素」的换算，
+ *   换算结果直接画在 SVG 上，全程不经过人手目测。
+ *
+ * 坐标换算规则：
+ *   - 默认：--json 里的 x/y/w/h 视为「截图设备像素坐标」（截图像素）。
+ *     画布里实际位置 = margin + 给定值。
+ *   - 传 --viewport "cssW,cssH"：x/y/w/h 视为「CSS 视口坐标」，
+ *     脚本先按 (截图宽/cssW)、(截图高/cssH) 换算成设备像素，再画。
+ *   - 全页拼接截图时，元素相对整页的左/顶 = rect.left + scrollX / rect.top + scrollY，
+ *     把这两个和作为 x/y 传入（这就是整页里的设备像素位置，无需 --viewport）。
+ *
+ * 用法：
+ *   node annotate.js <image> <outHtml> \
+ *     --json '[{"x":412,"y":1240,"w":160,"h":48,"text":"新增的保存按钮","color":"#22c55e"}]' \
+ *     --label "✅ 修复后" [--labelColor "#f43f5e"] [--viewport "1440,900"] [--margin-frac 0.05]
+ *
+ *   <image>    输入截图（PNG/JPG/WebP…，尺寸由 IHDR / JPEG SOF / sips 探测）
+ *   <outHtml>  输出的标注 HTML 路径
+ *   --json     标注数组 JSON，每项：{x,y[,w,h][,text][,color][,stroke-width]}
+ *              - x/y：目标点（默认设备像素坐标；传 --viewport 时为 CSS 坐标）
+ *              - w/h：目标区域宽高（有则画高亮圆角框，箭头指向其中心）
+ *              - text：文本框文字（浏览器渲染中文，自动排布在目标旁空闲侧）
+ *              - color：主色（箭头/框/文本描边），缺省 #f43f5e
+ *   --label    顶部标题条文字（适合「修复前/修复后」对比图），可省略
+ *   --labelColor  标题条主题色，缺省 #f43f5e
+ *   --viewport "cssW,cssH"  指定后坐标视为 CSS 视口坐标，自动换算
+ *   --margin-frac  画布四周留白相对图片长边的比例（给箭头腾空间），缺省 0.05
+ *   --url       可选：在标题条右侧显示页面 URL（用于「URL 可见」证据要求）
+ *
+ * 渲染为 PNG 的固定流程（配合 screenshot-annotate skill）：
+ *   1. 生成标注 HTML：  node annotate.js shot.png shot-annot.html --json '...' --label '...'
+ *   2. 无头打开并设视口为画布尺寸（画布比图片多四周留白）：
+ *        AGENT_BROWSER  --cdp 9226 --namespace <ns> tab new "file://<abs>/shot-annot.html"
+ *        AGENT_BROWSER  --cdp 9226 --namespace <ns> set viewport <W> <H>
+ *   3. 截图：            AGENT_BROWSER --cdp 9226 --namespace <ns> screenshot --full shot-annot.png
+ *   4. 关闭标签页：      AGENT_BROWSER --cdp 9226 --namespace <ns> tab close <tabId>
+ *   （W/H = annotate.js 打印的「画布尺寸」，即图片宽/高 + 2×margin）
+ *   本脚本与 SKILL.md 同目录（随 agent-rules 同步到各项目 .claude/skills/screenshot-annotate/）。
+ */
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+const { execFileSync } = require("child_process");
+
+// ---------------------------------------------------------------- 参数解析
+function parseArgs(argv) {
+  const positionals = [];
+  const keyed = {};
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a.startsWith("--")) {
+      const key = a.slice(2);
+      const next = argv[i + 1];
+      if (next !== undefined && !next.startsWith("--")) {
+        keyed[key] = next;
+        i++;
+      } else {
+        keyed[key] = true;
+      }
+    } else {
+      positionals.push(a);
+    }
+  }
+  return { positionals, keyed };
+}
+
+function num(v, dflt) {
+  if (v === undefined || v === true || v === null || v === "") return dflt;
+  const n = Number(v);
+  return Number.isFinite(n) ? n : dflt;
+}
+
+// ---------------------------------------------------------------- 图片尺寸探测
+function pngSize(buf) {
+  // 8 字节签名 + IHDR chunk（长度4 + 'IHDR' 4 + data 13）
+  if (
+    buf.length >= 24 &&
+    buf.readUInt32BE(0) === 0x89504e47 &&
+    buf.toString("ascii", 12, 16) === "IHDR"
+  ) {
+    return { width: buf.readUInt32BE(16), height: buf.readUInt32BE(20) };
+  }
+  return null;
+}
+
+function jpegSize(buf) {
+  if (buf.length < 4 || buf[0] !== 0xff || buf[1] !== 0xd8) return null;
+  let pos = 2;
+  while (pos + 9 < buf.length) {
+    if (buf[pos] !== 0xff) {
+      pos++;
+      continue;
+    }
+    const marker = buf[pos + 1];
+    // SOF0..15（除 DHT C4、JPG C8、DAC CC、RST0-7 D0-D7、DNL DC、SOS DA、DRI DD、APP0-EF E0-EF、COM FE）
+    if (
+      marker >= 0xc0 &&
+      marker <= 0xcf &&
+      marker !== 0xc4 &&
+      marker !== 0xc8 &&
+      marker !== 0xcc &&
+      (marker < 0xd0 || marker > 0xd7) &&
+      marker !== 0xda &&
+      marker !== 0xdb &&
+      marker !== 0xdc
+    ) {
+      const segLen = buf.readUInt16BE(pos + 2);
+      const height = buf.readUInt16BE(pos + 5);
+      const width = buf.readUInt16BE(pos + 7);
+      return { width, height };
+    }
+    const segLen = buf.readUInt16BE(pos + 2);
+    if (segLen < 2) return null;
+    pos += 2 + segLen;
+  }
+  return null;
+}
+
+function sipsSize(filePath) {
+  try {
+    const out = execFileSync("sips", ["-g", "pixelWidth", "-g", "pixelHeight", filePath], {
+      encoding: "utf-8",
+    });
+    const w = Number((out.match(/pixelWidth:\s*(\d+)/) || [])[1]);
+    const h = Number((out.match(/pixelHeight:\s*(\d+)/) || [])[1]);
+    if (Number.isFinite(w) && Number.isFinite(h) && w > 0 && h > 0) {
+      return { width: w, height: h };
+    }
+  } catch (e) {
+    /* fallthrough */
+  }
+  return null;
+}
+
+function detectSize(filePath, buf) {
+  return pngSize(buf) || jpegSize(buf) || sipsSize(filePath);
+}
+
+// ---------------------------------------------------------------- HTML 安全
+function escapeHtml(s) {
+  return String(s)
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;")
+    .replace(/'/g, "&#39;");
+}
+function extMime(filePath) {
+  const ext = path.extname(filePath).toLowerCase();
+  const map = {
+    ".png": "image/png",
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".gif": "image/gif",
+    ".webp": "image/webp",
+    ".svg": "image/svg+xml",
+    ".bmp": "image/bmp",
+  };
+  return map[ext] || "image/png";
+}
+
+// ---------------------------------------------------------------- 布局工具（生成 SVG 常量）
+// 文字排版：根据中文字符数近似估算宽度（一个汉字≈1.0em，拉丁≈0.55em）
+function estimateTextMetrics(text, fontSize) {
+  const chars = [...text];
+  let w = 0;
+  for (const ch of chars) {
+    const code = ch.codePointAt(0);
+    const width = code > 0x2e80 ? fontSize : fontSize * 0.55;
+    w += width;
+  }
+  return { width: Math.ceil(w) + 2 * fontSize, height: Math.ceil(fontSize * 1.7) };
+}
+
+// ---------------------------------------------------------------- 生成标注 HTML
+function buildHtml({
+  imagePath,
+  imageMime,
+  imageW,
+  imageH,
+  annotations,
+  label,
+  labelColor,
+  url,
+  marginFrac,
+}) {
+  const margin = Math.max(24, Math.round(Math.max(imageW, imageH) * marginFrac));
+  const W = imageW + margin * 2;
+  const H = imageH + margin * 2;
+  const imgData = fs.readFileSync(imagePath).toString("base64");
+  const dataUri = `data:${imageMime};base64,${imgData}`;
+
+  // 预处理标注：换算坐标（CSS→设备像素若给 viewport）、排版文本
+  const placed = [];
+  for (const a of annotations) {
+    const color = a.color || "#f43f5e";
+    const lw = num(a["stroke-width"], Math.max(3, Math.round(W / 900)));
+    // 换算已在 main() 中完成（CSS 坐标 → 设备像素）
+    const x = num(a.x, 0);
+    const y = num(a.y, 0);
+    const w = num(a.w, 0);
+    const h = num(a.h, 0);
+    placed.push({ ...a, x, y, w, h, color, lw });
+  }
+
+  // 文本距离目标框
+  const gap = Math.max(30, Math.round(Math.min(imageW, imageH) * 0.03));
+
+  // 生成每条标注的 SVG 片段
+  const parts = [];
+  for (const a of placed) {
+    // 目标中心
+    const tx = a.x + a.w / 2;
+    const ty = a.y + a.h / 2;
+    const fs = Math.max(16, Math.round(imageW / 90));
+    const metrics = a.text ? estimateTextMetrics(a.text, fs) : { width: 0, height: 0 };
+    const boxW = Math.ceil((metrics.width || 0) + fs * 1.2);
+    const boxH = Math.ceil(metrics.height + fs * 0.6);
+    const pad = 8;
+    const bw = a.text ? boxW : 0;
+    const bh = a.text ? boxH : 0;
+
+    // 文本候选方位（上、下、左、右），取第一个不越界且不遮目标的
+    const cands = [
+      { bx: tx - bw / 2, by: ty - gap - bh, name: "up" },
+      { bx: tx - bw / 2, by: ty + gap, name: "down" },
+      { bx: tx - gap - bw, by: ty - bh / 2, name: "left" },
+      { bx: tx + gap, by: ty - bh / 2, name: "right" },
+    ];
+    let slot = null;
+    for (const c of cands) {
+      const inX = c.bx - pad > margin && c.bx + bw + pad < margin + imageW;
+      const inY = c.by - pad > margin && c.by + bh + pad < margin + imageH;
+      let overlap = false;
+      if (a.w > 0 && a.h > 0) {
+        overlap = rectsOverlap(c.bx, c.by, bw, bh, a.x, a.y, a.w, a.h);
+      }
+      if (inX && inY && !overlap) {
+        slot = c;
+        break;
+      }
+    }
+    if (!slot) slot = cands[0];
+
+    const hasTarget = a.w > 0 && a.h > 0;
+    const hasText = Boolean(a.text);
+
+    // 高亮目标框
+    if (hasTarget) {
+      const rx = Math.max(8, a.lw * 1.8);
+      parts.push(`
+        <rect x="${a.x}" y="${a.y}" width="${a.w}" height="${a.h}" rx="${rx}" ry="${rx}"
+          fill="${a.color}" fill-opacity="0.14" stroke="${a.color}" stroke-width="${a.lw}"
+          vector-effect="non-scaling-stroke" />`);
+    }
+
+    // 文本框
+    if (hasText) {
+      const rx = Math.max(6, a.lw * 1.5);
+      parts.push(`
+        <rect x="${slot.bx}" y="${slot.by}" width="${bw}" height="${bh}" rx="${rx}" ry="${rx}"
+          fill="#ffffff" fill-opacity="0.92" stroke="${a.color}" stroke-width="${Math.max(
+          1,
+          Math.round(a.lw * 0.8),
+        )}"
+          vector-effect="non-scaling-stroke" />`);
+      parts.push(`
+        <text x="${slot.bx + bw / 2}" y="${slot.by + bh / 2}" font-family="system-ui, -apple-system, 'PingFang SC', 'Microsoft YaHei', sans-serif"
+          font-size="${fs}" font-weight="600" text-anchor="middle" dominant-baseline="central"
+          fill="${textContrast(a.color)}">${escapeHtml(a.text)}</text>`);
+    }
+
+    // 箭头：文本框中心 → 目标中心
+    const sx = slot.bx + bw / 2;
+    const sy = slot.by + bh / 2;
+    const dx = tx - sx;
+    const dy = ty - sy;
+    const len = Math.sqrt(dx * dx + dy * dy);
+    if (len > 1) {
+      // 起点避开文本框（沿方向外移半框）
+      const star = Math.min(1, Math.max(0, (bw * 0.5 + a.lw * 2) / len));
+      const ex = (star * dx) / len;
+      const ey = (star * dy) / len;
+      const sx2 = sx + ex * len;
+      const sy2 = sy + ey * len;
+      const arrowLen = Math.max(12, a.lw * 3.2);
+      const ang = Math.atan2(ty - sy, tx - sx);
+      const a1 = ang + Math.PI / 6;
+      const a2 = ang - Math.PI / 6;
+      parts.push(`
+        <line x1="${sx2}" y1="${sy2}" x2="${tx}" y2="${ty}" stroke="${a.color}"
+          stroke-width="${a.lw}" stroke-linecap="round" vector-effect="non-scaling-stroke" />`);
+      parts.push(`
+        <path d="M ${tx} ${ty} L ${tx - arrowLen * Math.cos(a1)} ${ty - arrowLen * Math.sin(a1)} L ${
+          tx - arrowLen * Math.cos(a2)
+        } ${ty - arrowLen * Math.sin(a2)} Z"
+          fill="${a.color}" />`);
+    }
+  }
+
+  // 标题条
+  let bar = "";
+  if (label) {
+    const barH = Math.max(40, Math.round(imageH * 0.05));
+    const fs = Math.max(20, Math.round(imageW / 55));
+    const lc = /^#[0-9a-fA-F]{6}$/.test(labelColor) ? labelColor : "#f43f5e";
+    const urlText = url ? escapeHtml(url) : "";
+    bar = `
+      <rect x="${margin}" y="${margin}" width="${imageW}" height="${barH}" rx="10" ry="10"
+        fill="${lc}" fill-opacity="0.9" />
+      <text x="${margin + imageW / 2}" y="${margin + barH / 2}" font-family="system-ui, sans-serif"
+        font-size="${fs}" font-weight="700" text-anchor="middle" dominant-baseline="central"
+        fill="#ffffff">${escapeHtml(label)}</text>
+      ${
+        urlText
+          ? `<text x="${margin + imageW - 14}" y="${margin + barH / 2}" font-family="ui-monospace, Menlo, monospace"
+              font-size="${Math.round(fs * 0.55)}" text-anchor="end" dominant-baseline="central"
+              fill="#ffffff" fill-opacity="0.92">${urlText}</text>`
+          : ""
+      }`;
+  }
+
+  return `<!doctype html>
+<html>
+<head>
+<meta charset="utf-8" />
+<title>标注</title>
+<style>
+  html, body { margin:0; padding:0; overflow:hidden; background:#000; }
+  .stage { position:relative; width:${W}px; height:${H}px; }
+  .stage img { position:absolute; left:${margin}px; top:${margin}px; width:${imageW}px; height:${imageH}px; }
+  .stage svg { position:absolute; left:0; top:0; width:${W}px; height:${H}px; }
+</style>
+</head>
+<body>
+<div class="stage">
+  <img src="${dataUri}" />
+  <svg xmlns="http://www.w3.org/2000/svg" width="${W}" height="${H}">
+    ${bar}
+    ${parts.join("\n")}
+  </svg>
+</div>
+</body>
+</html>`;
+
+  function rectsOverlap(x1, y1, w1, h1, x2, y2, w2, h2) {
+    return !(x1 + w1 < x2 || x2 + w2 < x1 || y1 + h1 < y2 || y2 + h2 < y1);
+  }
+  function textContrast(colorHex) {
+    const c = colorHex.replace("#", "");
+    const r = parseInt(c.slice(0, 2), 16) || 0;
+    const g = parseInt(c.slice(2, 4), 16) || 0;
+    const b = parseInt(c.slice(4, 6), 16) || 0;
+    return (0.2126 * r + 0.7152 * g + 0.0722 * b) > 140 ? "#1a1a1a" : "#ffffff";
+  }
+}
+
+// ---------------------------------------------------------------- 主流程
+function main() {
+  const { positionals, keyed } = parseArgs(process.argv.slice(2));
+  const [imagePath, outHtml] = positionals;
+  if (!imagePath || !outHtml) {
+    console.error(
+      "用法: node annotate.js <image> <outHtml> [--json \"...\"] [--label \"...\"] [--labelColor \"#fff\"] [--viewport \"cssW,cssH\"] [--margin-frac N] [--url \"...\"]",
+    );
+    process.exit(1);
+  }
+
+  if (!fs.existsSync(imagePath)) {
+    console.error(`❌ 图片不存在: ${imagePath}`);
+    process.exit(1);
+  }
+  const buf = fs.readFileSync(imagePath);
+  const size = detectSize(imagePath, buf);
+  if (!size) {
+    console.error(`❌ 无法探测图片尺寸（需 IHDR / JPEG SOF / sips）: ${imagePath}`);
+    process.exit(1);
+  }
+  const imageW = size.width;
+  const imageH = size.height;
+
+  let annotations = [];
+  if (keyed.json) {
+    try {
+      annotations = JSON.parse(keyed.json);
+    } catch (e) {
+      console.error("❌ --json 解析失败:", e.message);
+      process.exit(1);
+    }
+    if (!Array.isArray(annotations)) {
+      console.error("❌ --json 必须是标注数组");
+      process.exit(1);
+    }
+  }
+
+  // 坐标换算：CSS 坐标 → 设备像素
+  let viewport = null;
+  if (keyed.viewport && keyed.viewport !== true) {
+    const [vw, vh] = String(keyed.viewport).split(",").map(Number);
+    if (Number.isFinite(vw) && Number.isFinite(vh) && vw > 0 && vh > 0) {
+      viewport = { w: vw, h: vh };
+    }
+  }
+  const scaleX = viewport ? imageW / viewport.w : 1;
+  const scaleY = viewport ? imageH / viewport.h : 1;
+  annotations = annotations.map((a) => ({
+    ...a,
+    x: num(a.x, 0) * scaleX,
+    y: num(a.y, 0) * scaleY,
+    w: num(a.w, 0) * scaleX,
+    h: num(a.h, 0) * scaleY,
+  }));
+
+  const marginFrac = num(keyed["margin-frac"], 0.05);
+  const html = buildHtml({
+    imagePath,
+    imageMime: extMime(imagePath),
+    imageW,
+    imageH,
+    annotations,
+    label: keyed.label || "",
+    labelColor: keyed.labelColor || "#f43f5e",
+    url: keyed.url || "",
+    marginFrac,
+  });
+
+  fs.writeFileSync(outHtml, html);
+  const margin = Math.max(24, Math.round(Math.max(imageW, imageH) * marginFrac));
+  console.log(
+    `✅ 已生成标注 HTML → ${outHtml}`,
+  );
+  console.log(`   画布尺寸 ${imageW + margin * 2}×${imageH + margin * 2}（视口截图时用）`);
+}
+
+main();

package/skills/visual-report/SKILL.md

@@ -32,7 +32,7 @@ description: >-
 
 | 改动类型 | 证据来源 | 具体动作 |
 |------|------|------|
-| 页面 / 界面改动 | 真实页面 | 打开真实页面，用真实数据走真实交互（点击、填写、提交、等待渲染），全页截图 + 箭头标注关键改动区域 |
+| 页面 / 界面改动 | 真实页面 | 打开真实页面，用真实数据走真实交互（点击、填写、提交、等待渲染），全页截图 + 坐标换算后的箭头标注关键改动区域（/screenshot-annotate） |
 | Redis 相关 | Redis for VS Code 插件 | 查看运行时 Redis 的 key/value，A/B 对比改动前后的值（SET 已知值 → 触发业务动作 → 截图看值是否如预期） |
 | 数据库相关 | SQLTools 插件 | 查看运行时数据库的 row 数据，A/B 对比改动前后的值（插入/更新 → 触发业务动作 → 截图看落库是否如预期） |
 | 纯后端接口 / 定时任务无页面 | 运行时真实返回 | curl / 日志 / 查库 / 查 Redis，把结果渲染成可视化证据（暗色终端风格的请求/响应对比 HTML 截图，或 Redis/SQLTools 截图） |
@@ -53,7 +53,7 @@ description: >-
   2. **「为什么这样验证成立」原理说明卡**：先讲清楚 bug/功能差异的本质是哪一个动作，再论证「手动模拟该动作 = 真实场景」
   3. **A/B 对照表**：修复前 vs 修复后（或改动前 vs 改动后），代码行为 / 等价操作 / 观测结果三列并排
   4. **每步截图**：必须带箭头标注关键区域/验证点，图注写清「这张图证明了什么」，标注关键行/关键数据
-- 截图本身遵循「⚠️ 截图规范」：视口 3840px 宽、`fullPage` 全页、URL 可见、存到 `docs/` 对应子目录、文件名「编号 + 英文描述」。
+- 截图本身遵循「⚠️ 截图规范」：真实视口 + `fullPage` 全页、URL 可见、存到 `docs/` 对应子目录、文件名「编号 + 英文描述」。截图上的箭头/框标注统一走 `/screenshot-annotate` skill（坐标精确换算，禁止肉眼估位）。
 
 ## 不写测试 ≠ 不查错