@routerhub/agent-rules 1.5.145 → 1.5.147

package/AGENTS.base.md

@@ -116,13 +116,24 @@
 - ⚠️ **已推送到远程的提交需要撤销时，必须用 `git revert`，禁止用 `git push --force` 覆盖远程历史。** `git revert` 会创建一条新的撤销提交，保留完整的操作记录，不影响其他协作者的本地分支；`git push --force` 会破坏远程历史，导致其他人的本地分支与远程脱节，极易引发合并冲突或丢失他人提交。
 - ⚠️ **提交并推送代码后，若发现与主分支存在冲突，必须主动解决**，不能推送完就算完事、把冲突留给别人处理。
 
+## ⚠️ PR 冲突修复统一用临时 worktree
+
+- ⚠️ **修复 PR 与主分支的冲突时，一律使用临时 git worktree，禁止直接在当前工作副本上切换分支（`git checkout`）解题。** 原因：A-/B-/C-/M- 多副本仓库中，同一个克隆往往同时被其他开发任务占用；直接切分支会破坏别人正在进行的代码、或把自己卡在非主分支上。
+- ⚠️ **标准操作流程**：
+  1. 在仓库根目录执行 `git worktree add ../<pr>-fix <PR分支名> --detach`（或 `-b` 新建一个与 PR 分支同名的分支），临时分离出来用独立目录操作，当前工作副本状态完全不动。
+  2. 在 worktree 目录里 `git merge origin/main`（或 `git rebase origin/main`）→ 解决冲突文件 → 本地测试通过。
+  3. `git push` 推送回 PR 分支（须确认 push 目标为 origin 的对应 PR 分支，禁止 `--force`）。
+  4. 操作完成后用 `git worktree remove ../<pr>-fix` 清理临时 worktree，再回到原副本继续。
+- ⚠️ **worktree 与主副本共享同一套本地 `.git`**，但工作目录、索引、当前分支状态完全独立，不会干扰正在 main 或其他分支上改动代码的协作者。
+- ⚠️ **worktree 目录默认在仓库根目录同级（`../`）**，避免被误当成子文件夹进 git；进入前先确认该路径不存在同名文件夹。
+
 ## PR 核心要求
 
 - ⚠️ 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 的第一眼就是看描述，如果看不到图、只能读文字，完全无法直观感知改动效果；截图不内嵌 = 等于没附。
@@ -136,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` 发新版本。
@@ -188,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 / 后端 / 基础设施改动的效果截图获取方法
@@ -318,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.145",
+  "version": "1.5.147",
   "description": "Shared Copilot agent rules and guidelines for RouterHub projects",
   "main": "AGENTS.base.md",
   "bin": {

package/rules/global.md

@@ -116,13 +116,24 @@ name: "通用规则"
 - ⚠️ **已推送到远程的提交需要撤销时，必须用 `git revert`，禁止用 `git push --force` 覆盖远程历史。** `git revert` 会创建一条新的撤销提交，保留完整的操作记录，不影响其他协作者的本地分支；`git push --force` 会破坏远程历史，导致其他人的本地分支与远程脱节，极易引发合并冲突或丢失他人提交。
 - ⚠️ **提交并推送代码后，若发现与主分支存在冲突，必须主动解决**，不能推送完就算完事、把冲突留给别人处理。
 
+## ⚠️ PR 冲突修复统一用临时 worktree
+
+- ⚠️ **修复 PR 与主分支的冲突时，一律使用临时 git worktree，禁止直接在当前工作副本上切换分支（`git checkout`）解题。** 原因：A-/B-/C-/M- 多副本仓库中，同一个克隆往往同时被其他开发任务占用；直接切分支会破坏别人正在进行的代码、或把自己卡在非主分支上。
+- ⚠️ **标准操作流程**：
+  1. 在仓库根目录执行 `git worktree add ../<pr>-fix <PR分支名> --detach`（或 `-b` 新建一个与 PR 分支同名的分支），临时分离出来用独立目录操作，当前工作副本状态完全不动。
+  2. 在 worktree 目录里 `git merge origin/main`（或 `git rebase origin/main`）→ 解决冲突文件 → 本地测试通过。
+  3. `git push` 推送回 PR 分支（须确认 push 目标为 origin 的对应 PR 分支，禁止 `--force`）。
+  4. 操作完成后用 `git worktree remove ../<pr>-fix` 清理临时 worktree，再回到原副本继续。
+- ⚠️ **worktree 与主副本共享同一套本地 `.git`**，但工作目录、索引、当前分支状态完全独立，不会干扰正在 main 或其他分支上改动代码的协作者。
+- ⚠️ **worktree 目录默认在仓库根目录同级（`../`）**，避免被误当成子文件夹进 git；进入前先确认该路径不存在同名文件夹。
+
 ## PR 核心要求
 
 - ⚠️ 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 的第一眼就是看描述，如果看不到图、只能读文字，完全无法直观感知改动效果；截图不内嵌 = 等于没附。
@@ -136,8 +147,8 @@ 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 之后的最终代码。
+  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. **测试环境验证 + 全程截图标注**：在测试环境用真实数据、真实页面交互测试本次改动（遵循「⚠️ 页面功能验证铁律」「⚠️ 用户视角测试铁律」）。测试过程中每一步都截图保留（遵循「⚠️ 截图规范」：视口 3840px 宽、`fullPage` 全页、URL 可见、存盘到 `docs/` 对应子目录），并在每张截图上用**箭头标注**关键改动区域/验证点，让看的人一眼看懂这张图证明了什么。
   4. **确认没问题才算完成**：测试通过、截图与箭头标注齐全、功能符合预期，才算真正完成。禁止测试没跑、截图没标注就宣称完成。
   5. **把 PR 链接发给用户**：确认没问题后，先把 PR 链接发送给用户（`gh pr view <PR> --json url -q .url`），让用户能直接打开查看，再执行发版。
@@ -188,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 / 后端 / 基础设施改动的效果截图获取方法
@@ -318,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/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. ✅ 测试环境用真实数据 + 真实交互复测通过（每张截图 4K 全页、箭头标注、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. 测试环境复测 + 全程截图标注
+
+- 在测试环境用**真实数据 + 真实交互**测试本次改动（遵循「⚠️ 页面功能验证铁律」「⚠️ 用户视角测试铁律」）。
+- 每步截图保留（遵循「⚠️ 截图规范」：视口 3840px 宽、`fullPage` 全页、URL 可见、存盘到 `docs/` 对应子目录），并用**箭头标注**关键改动区域/验证点，让看的人一眼看懂这张图证明了什么。
+- 若本次改动是纯后端/基础设施，按「非 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,113 @@
+---
+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
+
+标注由 `scripts/annotate.js`（本项目源仓库 scripts/ 下的零依赖 Node 脚本）完成。它把截图 + 坐标转成自包含标注 HTML（截图 base64 内嵌、SVG 箭头/框/文字精确放在换算后的坐标上），再用无头浏览器渲染为 PNG。
+
+将脚本临时落到当前工作区（或直接用绝对路径调用）：
+
+```bash
+node /绝对路径/agent-rules/scripts/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（固定流程）
+
+```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（标题条或截图内地址栏）
+- 修改坐标/文字后重新跑脚本 + 渲染，不要在原图上手工补。
+
+## 重要规则
+
+- ⚠️ 坐标必须有浏览器测量来源，禁止目测
+- ⚠️ 每种「关键区域」都要箭头/框标注到位，禁止只标一处；多个改动点逐个覆盖
+- ⚠️ 若截图是真实视口截出的，尽量一图一文；整页图定位大区域，局部区域用放大图单独标注
+- 渲染用无头实例（不抢焦点）；如需给用户看效果用截图