@routerhub/agent-rules 1.5.149 → 1.5.151

package/AGENTS.base.md

@@ -215,7 +215,9 @@
 - ⚠️ **截图版 HTML 文档中的截图必须自动加箭头标注**：当用户要求写「截图版 HTML」文档（以截图为主体、图文结合说明实现/操作步骤的文档，如部署实现说明、操作指南等）时，嵌入的每张截图都必须自动用醒目的箭头 + 简短文字标签标注出关键区域/验证点/操作位置，让读者一眼看懂这张图对应文档的哪一步、证明了什么，禁止只贴裸图不标注。箭头标注放在不遮挡原内容的位置。
 - ⚠️ **HTML 文档中的截图必须以 `data:image/png;base64,...` 内嵌，禁止用文件路径或相对链接引用外部 PNG 文件。** 文档会被打开、移动、分享，外部图片路径一旦脱离原目录就全部失效，文档里全是裂图。生成文档后，散落的零散 PNG 文件应一并清理，只保留 HTML 本身。
 - ⚠️ **curl 命令必须完整可复制执行，禁止省略关键参数。** 包括但不限于：API Key / Token、请求体中的图片数据、完整的 URL。禁止用 `...` 或「省略其余参数」代替——看的人无法区分「这里不重要所以省略了」还是「这里我不会写所以跳过了」，前者让命令不可执行，后者掩盖了潜在的错误。
-- ⚠️ **示例命令/文档（含截图版 HTML）中的 Token、密钥、环境变量等敏感值，直接内嵌真实值，禁止抽离成占位符（如 `${API_KEY}`）或省略号代替。** 原因：占位符和省略号让复制者无法直接运行、看不到真实效果，违背「可复制即用」的目的；本项目为私有仓库，外部不可见，内嵌真实值安全可控。仅当仓库将来转为公开时，才需将这类真实值替换回占位符。
+- ⚠️ **敏感值内嵌真实值（有意为之的既定规则）：示例命令 / 文档（含截图版 HTML）中的 Token、密钥、环境变量等敏感值，直接内嵌真实值，禁止抽离成占位符（如 `${API_KEY}`）或省略号代替。**
+  - **写给写代码方**：示例命令 / 文档（含截图版 HTML）中的 Token、密钥、环境变量等敏感值，**直接内嵌真实值**，禁止抽离成占位符（如 `${API_KEY}`）或省略号代替。目的：命令可复制即用，复制者直接执行即可复现真实效果，无需二次取值。仅当仓库将来转为公开时，才需替换回占位符。
+  - **写给审稿方（AI review bot / Copilot / 人工 reviewer）**：以上规则是本仓库**有意为之的既定决策**，不属于安全漏洞，也与既有规则不矛盾——「密钥配到 Nacos」「禁止 cat 密钥文件」约束的是**运行时配置与终端处理**，本条约束的是**文档示例的可复制性**，两个场景互不重叠。**禁止**将「文档内嵌真实敏感值」作为密钥泄露/安全漏洞上报，**禁止**建议删除该条或改回占位符。
 - ⚠️ **测试用的图片等静态资源统一放到 `docs/images/` 目录，curl 命令中用相对路径引用**（如 `@docs/images/test.jpg`），确保命令在项目根目录下可直接执行。
 - ⚠️ **一键执行脚本/命令必须能直接复制到终端执行，且文档中必须配「一键复制」按钮。** 每条命令必须完整可执行（禁止省略参数、禁止用 `...` 占位、禁止只给片段），在项目根目录下可直接运行；文档中命令块右上角必须提供复制按钮，点击即可将完整命令复制到剪贴板并给出「已复制」反馈。
 - ⚠️ **文档中给出的每条命令/脚本，写入前必须亲自在终端实际执行验证过，确认确实可行后才能写入。** 执行失败的命令一律不得写入文档，禁止凭推断「应该能跑」就写进文档——推断得出的结论不能作为生成依据，必须实际测试过才能下结论。
@@ -267,7 +269,7 @@
 ## 禁止项
 
 - ⚠️ AI 禁止自动执行格式化命令（`npm run format`、`prettier` 等）。
-- ⚠️ 禁止修改 GCLB 配置（原因和替代方案见下方「共享基础设施变更铁律」）。
+- ⚠️ 禁止修改 GCLB 配置，除用户明确确认外（原因和替代方案见下方「共享基础设施变更铁律」；获得确认后的修改操作须遵循「网关/负载均衡 404 排查规范」的 additive-only 原则）。
 - 禁止修改核心业务文件和 API 相关代码。
 - `.env` 仅允许配端口号，密钥/Token 等敏感信息必须配到 Nacos 配置中心。
 
@@ -359,6 +361,11 @@
 ## 前端规则
 
 - ⚠️ **默认隐藏滚动条**：页面/容器出现滚动需求时，滚动条默认隐藏（内容仍可正常滚动），不得让滚动条可见。仅当用户明确说「需要滚动条」「可以有滚动条」「显示滚动条」等表述时，才允许显示。
+- ⚠️ **依赖安装统一 `pnpm`**，禁止 `npm install` / `yarn install`（pnpm workspace 混合安装会破坏依赖结构）。
+- ⚠️ **API 请求严格使用 OpenAPI 生成的方法，禁止手写请求或直接拼接路径**；接口变更后先更新 OpenAPI 定义并重新生成 API 代码，再进行业务开发。
+- ⚠️ **用 `console.error` 记录错误**（含函数名/模块名上下文），禁止用 `console.log` 输出错误；提交前移除调试日志和临时代码。
+- ⚠️ **调试过程中产生的中间产物（临时文件、测试脚本、调试截图、dump 文件、临时注释、`console.log` 等）禁止加入 Git 提交**，`.gitignore` 中应配置忽略常见中间产物。
+- TypeScript 类型优先复用 `api` 文件夹下 `typings.d.ts`，不存在时再自定义；组件 `props` 能复用时必须优先复用。
 
 <!-- 前端特有规则在此添加 -->
 
@@ -396,6 +403,8 @@
 - 🛡️ **纯防御性建议**：以「如果未来 / 万一 / 边界情况下」开头、当前代码没有实际触发路径的「潜在风险」（如「序号 99999 溢出」「未来可能有人改这里」），一律不报。
 - ❓ **无法确认真假的问题**：读 diff 不能确认会导致 bug 的，默认按「不是问题」处理，禁止报「建议确认一下」这类空泛意见。
 - 🔁 **重复已处理的问题**：已在评论 / 历史中标记 Won't fix 或「已修复于 &lt;hash&gt;」的问题，不再重提。
+- 🔒 **「文档内嵌真实敏感值」**：AGENTS.base.md 明文规定「示例命令 / 文档内嵌真实 Token/密钥」为**有意为之的既定规则**，不属于安全漏洞，**禁止**作为密钥泄露 / 安全漏洞上报，也**禁止**建议删除该条或改回占位符。与「密钥配到 Nacos」「禁止 cat 密钥文件」互不冲突：后者约束运行时配置与终端处理，本条约束文档示例的可复制性，两个场景互不重叠。
+- 🔧 **「AGENTS.base.md 未同步」**：下游业务仓库的 AGENTS.md / CLAUDE.md / .github/copilot-instructions.md 由 **@routerhub/agent-rules 发版同步**（npm 包 postinstall 自动生成），业务仓库内**不存在** `AGENTS.base.md` 源文件，`node merge.js sync` 只在 agent-rules 仓库执行。审稿方**禁止**因「diff 修改了 AGENTS.md / CLAUDE.md 但未出现 AGENTS.base.md 改动」而报错——业务仓库本就没有此文件，规则改动由 agent-rules 发版统一管理，属正常流程。
 
 ### 判断标准
 

package/package.json

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

package/rules/frontend.md

@@ -7,5 +7,10 @@ outputName: "frontend"
 ## 前端规则
 
 - ⚠️ **默认隐藏滚动条**：页面/容器出现滚动需求时，滚动条默认隐藏（内容仍可正常滚动），不得让滚动条可见。仅当用户明确说「需要滚动条」「可以有滚动条」「显示滚动条」等表述时，才允许显示。
+- ⚠️ **依赖安装统一 `pnpm`**，禁止 `npm install` / `yarn install`（pnpm workspace 混合安装会破坏依赖结构）。
+- ⚠️ **API 请求严格使用 OpenAPI 生成的方法，禁止手写请求或直接拼接路径**；接口变更后先更新 OpenAPI 定义并重新生成 API 代码，再进行业务开发。
+- ⚠️ **用 `console.error` 记录错误**（含函数名/模块名上下文），禁止用 `console.log` 输出错误；提交前移除调试日志和临时代码。
+- ⚠️ **调试过程中产生的中间产物（临时文件、测试脚本、调试截图、dump 文件、临时注释、`console.log` 等）禁止加入 Git 提交**，`.gitignore` 中应配置忽略常见中间产物。
+- TypeScript 类型优先复用 `api` 文件夹下 `typings.d.ts`，不存在时再自定义；组件 `props` 能复用时必须优先复用。
 
 <!-- 前端特有规则在此添加 -->

package/rules/global.md

@@ -215,7 +215,9 @@ name: "通用规则"
 - ⚠️ **截图版 HTML 文档中的截图必须自动加箭头标注**：当用户要求写「截图版 HTML」文档（以截图为主体、图文结合说明实现/操作步骤的文档，如部署实现说明、操作指南等）时，嵌入的每张截图都必须自动用醒目的箭头 + 简短文字标签标注出关键区域/验证点/操作位置，让读者一眼看懂这张图对应文档的哪一步、证明了什么，禁止只贴裸图不标注。箭头标注放在不遮挡原内容的位置。
 - ⚠️ **HTML 文档中的截图必须以 `data:image/png;base64,...` 内嵌，禁止用文件路径或相对链接引用外部 PNG 文件。** 文档会被打开、移动、分享，外部图片路径一旦脱离原目录就全部失效，文档里全是裂图。生成文档后，散落的零散 PNG 文件应一并清理，只保留 HTML 本身。
 - ⚠️ **curl 命令必须完整可复制执行，禁止省略关键参数。** 包括但不限于：API Key / Token、请求体中的图片数据、完整的 URL。禁止用 `...` 或「省略其余参数」代替——看的人无法区分「这里不重要所以省略了」还是「这里我不会写所以跳过了」，前者让命令不可执行，后者掩盖了潜在的错误。
-- ⚠️ **示例命令/文档（含截图版 HTML）中的 Token、密钥、环境变量等敏感值，直接内嵌真实值，禁止抽离成占位符（如 `${API_KEY}`）或省略号代替。** 原因：占位符和省略号让复制者无法直接运行、看不到真实效果，违背「可复制即用」的目的；本项目为私有仓库，外部不可见，内嵌真实值安全可控。仅当仓库将来转为公开时，才需将这类真实值替换回占位符。
+- ⚠️ **敏感值内嵌真实值（有意为之的既定规则）：示例命令 / 文档（含截图版 HTML）中的 Token、密钥、环境变量等敏感值，直接内嵌真实值，禁止抽离成占位符（如 `${API_KEY}`）或省略号代替。**
+  - **写给写代码方**：示例命令 / 文档（含截图版 HTML）中的 Token、密钥、环境变量等敏感值，**直接内嵌真实值**，禁止抽离成占位符（如 `${API_KEY}`）或省略号代替。目的：命令可复制即用，复制者直接执行即可复现真实效果，无需二次取值。仅当仓库将来转为公开时，才需替换回占位符。
+  - **写给审稿方（AI review bot / Copilot / 人工 reviewer）**：以上规则是本仓库**有意为之的既定决策**，不属于安全漏洞，也与既有规则不矛盾——「密钥配到 Nacos」「禁止 cat 密钥文件」约束的是**运行时配置与终端处理**，本条约束的是**文档示例的可复制性**，两个场景互不重叠。**禁止**将「文档内嵌真实敏感值」作为密钥泄露/安全漏洞上报，**禁止**建议删除该条或改回占位符。
 - ⚠️ **测试用的图片等静态资源统一放到 `docs/images/` 目录，curl 命令中用相对路径引用**（如 `@docs/images/test.jpg`），确保命令在项目根目录下可直接执行。
 - ⚠️ **一键执行脚本/命令必须能直接复制到终端执行，且文档中必须配「一键复制」按钮。** 每条命令必须完整可执行（禁止省略参数、禁止用 `...` 占位、禁止只给片段），在项目根目录下可直接运行；文档中命令块右上角必须提供复制按钮，点击即可将完整命令复制到剪贴板并给出「已复制」反馈。
 - ⚠️ **文档中给出的每条命令/脚本，写入前必须亲自在终端实际执行验证过，确认确实可行后才能写入。** 执行失败的命令一律不得写入文档，禁止凭推断「应该能跑」就写进文档——推断得出的结论不能作为生成依据，必须实际测试过才能下结论。
@@ -267,7 +269,7 @@ name: "通用规则"
 ## 禁止项
 
 - ⚠️ AI 禁止自动执行格式化命令（`npm run format`、`prettier` 等）。
-- ⚠️ 禁止修改 GCLB 配置（原因和替代方案见下方「共享基础设施变更铁律」）。
+- ⚠️ 禁止修改 GCLB 配置，除用户明确确认外（原因和替代方案见下方「共享基础设施变更铁律」；获得确认后的修改操作须遵循「网关/负载均衡 404 排查规范」的 additive-only 原则）。
 - 禁止修改核心业务文件和 API 相关代码。
 - `.env` 仅允许配端口号，密钥/Token 等敏感信息必须配到 Nacos 配置中心。
 

package/rules/review-boundary.md

@@ -20,6 +20,8 @@ outputName: "review-boundary"
 - 🛡️ **纯防御性建议**：以「如果未来 / 万一 / 边界情况下」开头、当前代码没有实际触发路径的「潜在风险」（如「序号 99999 溢出」「未来可能有人改这里」），一律不报。
 - ❓ **无法确认真假的问题**：读 diff 不能确认会导致 bug 的，默认按「不是问题」处理，禁止报「建议确认一下」这类空泛意见。
 - 🔁 **重复已处理的问题**：已在评论 / 历史中标记 Won't fix 或「已修复于 <hash>」的问题，不再重提。
+- 🔒 **「文档内嵌真实敏感值」**：AGENTS.base.md 明文规定「示例命令 / 文档内嵌真实 Token/密钥」为**有意为之的既定规则**，不属于安全漏洞，**禁止**作为密钥泄露 / 安全漏洞上报，也**禁止**建议删除该条或改回占位符。与「密钥配到 Nacos」「禁止 cat 密钥文件」互不冲突：后者约束运行时配置与终端处理，本条约束文档示例的可复制性，两个场景互不重叠。
+- 🔧 **「AGENTS.base.md 未同步」**：下游业务仓库的 AGENTS.md / CLAUDE.md / .github/copilot-instructions.md 由 **@routerhub/agent-rules 发版同步**（npm 包 postinstall 自动生成），业务仓库内**不存在** `AGENTS.base.md` 源文件，`node merge.js sync` 只在 agent-rules 仓库执行。审稿方**禁止**因「diff 修改了 AGENTS.md / CLAUDE.md 但未出现 AGENTS.base.md 改动」而报错——业务仓库本就没有此文件，规则改动由 agent-rules 发版统一管理，属正常流程。
 
 ### 判断标准
 

package/skills/create-pr/SKILL.md

@@ -91,7 +91,8 @@ gh pr create \
 ### 6. 补充元数据
 
 - Assignees：填自己
-- Labels：按类型/模块添加- 关联 issue：如有
+- Labels：按类型/模块添加
+- 关联 issue：如有
 - Milestone：如有
 
 ### 6.5 创建完 PR 后自动走完整闭环流程（未走完不算完成）

package/skills/deploy-test/SKILL.md

@@ -44,10 +44,30 @@ git push origin "$ORIGINAL_BRANCH"
 
 ```bash
 # 确认本地功能分支与远程已同步（本地无未推送提交）
+# 先 fetch 让 origin/<分支> 引用最新，再用「分支的 upstream..HEAD」精确列举未推送提交
+# ⚠️ 分支可能从未推送过（远程不存在该 ref），git fetch origin "$X" 会报 "couldn't find remote ref"；
+#    用 2>/dev/null || true 容忍该失败，否则在 set -e 环境下会直接中断、后面的「远程分支不存在」兜底逻辑根本执行不到
+git fetch origin "$ORIGINAL_BRANCH" 2>/dev/null || true
 git status
-git log origin/"$ORIGINAL_BRANCH".."$ORIGINAL_BRANCH" --oneline   # 应无输出 = 无未推送提交
+# 无 upstream 时 @{u} 会报错，先检测：有 upstream 用 @{u} 精确差集；
+# 无 upstream 时先确认远程分支是否存在（git log origin/X..HEAD 对不存在的引用会直接 fatal），
+# 不存在 = 新分支从未推送。⚠️ 此时不能用 git log HEAD（会把 main 全部历史也算进来，输出上千行淹没真正关心的提交），
+#    要相对默认分支（origin/main）取差集，只列出本分支相对默认分支的新增提交
+DEFAULT_BRANCH=$(git remote show origin | grep 'HEAD branch' | cut -d: -f2 | tr -d ' ')
+if git rev-parse --abbrev-ref '@{u}' >/dev/null 2>&1; then
+  UNPUSHED=$(git log "@{u}"..HEAD --oneline)
+elif git rev-parse --verify "origin/$ORIGINAL_BRANCH" >/dev/null 2>&1; then
+  UNPUSHED=$(git log "origin/$ORIGINAL_BRANCH"..HEAD --oneline)
+elif git rev-parse --verify "origin/$DEFAULT_BRANCH" >/dev/null 2>&1; then
+  UNPUSHED=$(git log "origin/$DEFAULT_BRANCH"..HEAD --oneline)
+else
+  UNPUSHED=$(git log HEAD --oneline)
+fi
+[ -z "$UNPUSHED" ] && echo "✅ 无未推送提交" || { echo "⚠️ 存在未推送提交："; echo "$UNPUSHED"; }
 ```
 
+⚠️ 用 `git log @{u}..HEAD`（当前分支与其 upstream 的差集）而不是 `git log origin/"$ORIGINAL_BRANCH".."$ORIGINAL_BRANCH"`：后者在本地分支尚未 fetch 到最新 origin 时会把已推送过的提交误报为「未推送」，导致误判；且若分支创建时 track 的不是同名远程分支，`origin/X` 引用可能缺失。`@{u}` 始终指向当前分支真正跟踪的远程引用，语义更准确。⚠️ 但 `@{u}` 仅在分支设置了 upstream（`git push -u`）时可用；功能分支若用 `git push origin <branch>` 推送则无 upstream，`@{u}` 会直接报错，因此上面先用 `git rev-parse --abbrev-ref "@{u}"` 检测。无 upstream 时还要先确认远程分支存在——`git log origin/X..HEAD` 对**不存在的引用会直接 fatal**（而不是返回空），因此用 `git rev-parse --verify "origin/X"` 探测；远程分支不存在即新分支从未推送，此时全部本地提交都算「未推送」。
+
 - ⚠️ 若 review 修复还没合进当前功能分支 → 先把修复 commit 到功能分支再推送，禁止带着"修复只在 test 分支"的状态去部署。
 - ⚠️ feature 分支与 test 分支两条线必须保持同步：**所有 review 修复代码必须先落 feature 分支（PR 分支），再合并到 test**，缺一不可。
 

package/skills/loop-review/SKILL.md

@@ -47,7 +47,7 @@ AI review bot 在**每次 push 到 PR 时自动触发新一轮 review**。因此
 ```bash
 REPO=$(gh repo view --json nameWithOwner -q '.nameWithOwner')
 PR=$(gh pr view --json number -q '.number')
-HEAD=$(git rev-parse --short HEAD)
+HEAD=$(git rev-parse HEAD)
 ```
 
 记录本轮起始 `HEAD`，用于判断「新 review 是否已针对最新 push」。
@@ -68,19 +68,16 @@ review body 结构（已实测确认）：
 - `## 🤖 GPT-5.5 Code Review（交叉验证）`：GPT-5.5 的交叉验证结论
 - 每个模型内部按严重度分节：`## 🔴 Critical` / `## 🟡 Warning` / `## 🔵 Suggestion`
 
-**确认「最新一轮 review 是否针对当前 HEAD」**，优先用 review 的 `commit_id` 字段，为空时解析 body 里的「审查 commit」：
+**确认「最新一轮 review 是否针对当前 HEAD」**：调用独立脚本 `check-review.sh` 获取最新 review 的完整 commit_id（脚本处理完整 SHA、按 submitted_at 排序取末条、分页合并），再与当前 HEAD 完整 SHA 比较：
 
 ```bash
 # 取最新一条对应当前 HEAD 的 review（命中则输出 YES，否则为空）
-CUR=$(git rev-parse --short HEAD)
-gh api repos/$REPO/pulls/$PR/reviews?per_page=100 --jq \
-  --arg cur "$CUR" '
-  [.[] | select(.user.login == "github-actions[bot]") |
-   (.commit_id // (try (.body | capture("审查 commit: `(?<h>[0-9a-f]+)`") | .h) catch null))] |
-  if .[0] == $cur then "YES" else "NO" end'
+CUR=$(git rev-parse HEAD)
+LATEST=$(bash "$(git rev-parse --show-toplevel)/.claude/skills/loop-review/scripts/check-review.sh" "$REPO" "$PR")
+if [ -n "$LATEST" ] && [ "$LATEST" = "$CUR" ]; then echo "YES"; else echo "NO"; fi
 ```
 
-若最新 review 对应的还是更早的 commit，说明 push 后 bot 尚未审查完，先进入步骤 5 的等待。
+⚠️ `git rev-parse HEAD` 必须用完整 40 位 SHA：`review.commit_id` 是完整 SHA，短 SHA 比较永远不匹配，会误判「review 未到」而空等。
 
 ### 2. 汇总建议并逐条判断（核心）
 
@@ -150,17 +147,16 @@ git push origin <当前分支>
 - push 后 bot 需要一段时间才出新一轮 review（实测几分钟到几十分钟不等），用轮询等待，不要干等：
 
 ```bash
-CUR=$(git rev-parse --short HEAD)
+CUR=$(git rev-parse HEAD)
 for i in $(seq 1 45); do
-  R=$(gh api repos/$REPO/pulls/$PR/reviews?per_page=100 --jq \
-    --arg cur "$CUR" '
-    [.[] | select(.user.login == "github-actions[bot]") |
-     (.commit_id // (try (.body | capture("审查 commit: `(?<h>[0-9a-f]+)`") | .h) catch null))] | .[0]')
-  [ "$R" = "$CUR" ] && echo "NEW_REVIEW_READY" && break
+  R=$(bash "$(git rev-parse --show-toplevel)/.claude/skills/loop-review/scripts/check-review.sh" "$REPO" "$PR")
+  [ -n "$R" ] && [ "$R" = "$CUR" ] && echo "NEW_REVIEW_READY" && break
   sleep 20
 done
 ```
 
+⚠️ 等待判断也用完整 SHA + `check-review.sh`（步骤 1 的同一套逻辑），避免 `gh api --jq --arg` 写法失败或短 SHA 误判导致空等 15 分钟。
+
 - ⚠️ **遵守心跳约定**：等待期间超过 1 分钟无输出，主动告知「正在等 bot 审查」。
 - 轮询约 15 分钟（45 次 × 20s）仍没出新 review → 停止等待，向用户报告当前状态并询问是否继续等。
 

package/skills/loop-review/scripts/check-review.sh

@@ -0,0 +1,64 @@
+#!/usr/bin/env bash
+# loop-review：查询 PR 上「最新一轮 AI review 审查的 commit_id」。
+# 供 SKILL.md 轮询/判断流程调用，把易错的 jq 转义逻辑收敛到独立脚本，便于测试与维护。
+#
+# 用法：
+#   bash check-review.sh <REPO> <PR>   # 输出最新 review 审查的 commit_id（完整 SHA），无 review 输出空
+#
+# 依赖：
+#   - gh CLI（已登录且有权限读该仓库）
+#   - jq >= 1.6：capture（1.5+）、try/catch（1.6+）、-s slurp；本地旧版 jq 会语法报错
+#   - 说明：GitHub GET /pulls/{n}/reviews 返回按创建时间升序，但显式 sort_by(.submitted_at) 取最后一条最稳。
+
+set -euo pipefail
+
+REPO="${1:?用法: bash check-review.sh <REPO> <PR>}"
+PR="${2:?用法: bash check-review.sh <REPO> <PR>}"
+
+# $REPO / $PR 直接拼入 URL 路径与 jq filter 字符串，必须先校验格式：
+#   - $REPO 形如 owner/name，仅含字母数字、点、下划线、中划线
+#   - $PR 必须是纯数字
+# 避免传参含特殊字符时破坏 jq 语法或让请求打到意外路径。
+[[ "$REPO" =~ ^[a-zA-Z0-9._-]+/[a-zA-Z0-9._-]+$ ]] || { echo "错误: REPO 格式非法（应为 owner/repo，收到: ${REPO}）" >&2; exit 1; }
+[[ "$PR" =~ ^[0-9]+$ ]] || { echo "错误: PR 必须是纯数字（收到: ${PR}）" >&2; exit 1; }
+
+# jq 版本校验：下方 filter 用了 try/catch（jq 1.6+ 语法），Ubuntu 20.04 默认 jq 1.5 会直接语法报错，
+# 且报错信息晦涩难定位。启动时主动检测版本，给明确提示而不是等 jq 报错。
+if ! command -v jq >/dev/null 2>&1; then
+  echo "错误: 未找到 jq（脚本依赖 jq >= 1.6，请先安装）" >&2
+  exit 1
+fi
+# jq --version 保证单行输出（如 jq-1.6），grep -oE 最多匹配一行，head -1 冗余，直接省略
+JQ_VERSION="$(jq --version 2>/dev/null | grep -oE '[0-9]+(\.[0-9]+)+')"
+if [ -z "$JQ_VERSION" ]; then
+  echo "错误: 无法从 jq --version 解析出版本号（输出: $(jq --version 2>&1)），脚本依赖 jq >= 1.6" >&2
+  exit 1
+fi
+# 版本比较：拆分主/次版本号后直接做整数比较（review 建议，替代反直觉的 awk exit 语义）。
+# 直白逻辑：主版本 >1，或主版本==1 且次版本>=6 → 满足要求，不进入报错分支。
+JQ_MAJOR="${JQ_VERSION%%.*}"
+JQ_MINOR_REMAINDER="${JQ_VERSION#*.}"
+JQ_MINOR="${JQ_MINOR_REMAINDER%%.*}"
+if [ "$JQ_MAJOR" -lt 1 ] || { [ "$JQ_MAJOR" -eq 1 ] && [ "$JQ_MINOR" -lt 6 ]; }; then
+  echo "错误: jq 版本过低（当前 ${JQ_VERSION}，需要 >= 1.6）：try/catch 语法不可用" >&2
+  exit 1
+fi
+
+# ⚠️ 分页处理：gh api --paginate 不带 --jq，把每页原始 JSON 输出（多页 = 多个数组流），
+#    再管道给 jq -s（slurp）合并成单一数组后统一筛选排序。
+#    --paginate --jq 会「每页独立执行 jq」，review 超过一页时输出多行 commit_id，调用方误判。
+# ⚠️ jq filter 用单引号包裹（无 shell 变量插值），内部反引号/双引号无需 shell 转义，避免转义脆弱性。
+# `-r` raw 输出：去掉 JSON 字符串引号，调用方 `[ "$LATEST" = "$CUR" ]` 才能比较成功。
+# `(add // [])`：gh api 完全无输出（如 PR 不存在/无任何 review）时，slurp 的输入为空流，
+#    add 得 null，后续 select 会报「Cannot iterate over null」；// [] 让空输入变空数组。
+# `select($cid | type == "string" and length == 40)`：只保留完整 40 位 SHA 的 review。
+#    优先用 commit_id 字段（GitHub API 保证完整），fallback 解析 body「审查 commit」时可能拿到短 SHA，
+#    短 SHA 与调用方 git rev-parse HEAD（完整 40 位）比较永远不匹配 → 空等；这里过滤掉非 40 位值，
+#    宁可判定「未审查」也不误判「已审查」。
+gh api "repos/$REPO/pulls/$PR/reviews?per_page=100" --paginate | jq -rs '
+  (add // []) | [.[] | select(.user.login == "github-actions[bot]" and .submitted_at != null) |
+   (.commit_id // (try (.body | capture("审查 commit: `(?<h>[0-9a-f]+)`") | .h) catch null)) as $cid |
+   select($cid | type == "string" and length == 40) |
+   {commit_id: $cid, submitted_at}] |
+  sort_by(.submitted_at) | .[-1].commit_id // empty
+'

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

@@ -23,7 +23,7 @@ description: >-
   1. ✅ 循环 review 走完（`/loop-review`，直到某一轮不再冒出值得修的新问题）
   2. ✅ 最新代码已提交并推送到 PR 分支
   3. ✅ 已通过 `/deploy-test` 重新部署到测试环境（部署的是 review 之后的最终代码）
-  4. ✅ 测试环境用真实数据 + 真实交互复测通过（每张截图真实视口 + `fullPage` 全页、坐标换算箭头标注、URL 可见）
+  4. ✅ 测试环境用真实数据 + 真实交互复测通过（每张截图浏览器真实视口全页、箭头标注、URL 可见）
   5. ✅ 与主分支无冲突（`gh pr view <PR> --json mergeable -q .mergeable` = `MERGEABLE`）
   6. ✅ GitHub 静态编译通过（`gh pr checks <PR>` 无 `failure`）
   7. ✅ PR 链接已发送给用户
@@ -35,17 +35,31 @@ description: >-
 ### 1. 确认循环 review 已完成
 
 ```bash
-gh pr view <PR> --json comments -q '.comments | length'
+REPO=$(gh repo view --json nameWithOwner -q '.nameWithOwner')
+PR=$(gh pr view --json number -q '.number')
+CUR=$(git rev-parse HEAD)
+LATEST=$(bash "$(git rev-parse --show-toplevel)/.claude/skills/loop-review/scripts/check-review.sh" "$REPO" "$PR")
+echo "最新 review 审查 commit: $LATEST"
+echo "当前 HEAD: $CUR"
 ```
 
-确认 `/loop-review` 已走到「无值得修的新问题」那一轮（或达到最大轮数由用户决定结束）。若循环 review 还没走完，**先补跑 `/loop-review`，不得跳过**。
+与 `check-review.sh` 返回的最新 review 审查 commit 对比：若等于当前 HEAD，说明 bot 已审查到最新代码（循环 review 已对该 commit 收敛）；若为空或更早，说明 bot 还没审到最新 push，循环 review 尚未完成。
+
+⚠️ 不要用 `gh pr view --json comments -q '.comments | length'`（评论总数）判断闭环——评论数与「循环 review 是否收敛」无对应关系，验证不了。判断依据是「最新 review 是否针对当前 HEAD」，即 `/loop-review` 步骤 1 的同一套逻辑。若循环 review 还没走完，**先补跑 `/loop-review`，不得跳过**。
 
 ### 2. 确保最新代码已推送
 
 循环 review 期间若有改动，确保已提交并推送到 PR 分支。若 review 过程中没有新增 commit，且已满足「无值得修的新问题」，则跳过本步（不必为了触发而空 push）。
 
 ```bash
-git status && git push origin "$(git branch --show-current)"
+# ⚠️ git status 即使存在未提交改动也返回 0，直接 git status && git push 会把「还有未提交改动」误判成「已推送」。
+# 必须用 --porcelain 显式检查工作区/暂存区是否干净，脏则中止推送。
+if [ -n "$(git status --porcelain)" ]; then
+  echo "❌ 工作区存在未提交改动，请先 commit 后再 push"
+  git status
+  exit 1
+fi
+git push origin "$(git branch --show-current)"
 ```
 
 ### 3. 重新部署到测试环境（最容易漏的一步）
@@ -57,7 +71,7 @@ git status && git push origin "$(git branch --show-current)"
 ### 4. 测试环境复测 + 全程截图标注
 
 - 在测试环境用**真实数据 + 真实交互**测试本次改动（遵循「⚠️ 页面功能验证铁律」「⚠️ 用户视角测试铁律」）。
-- 每步截图保留（遵循「⚠️ 截图规范」：真实视口 + `fullPage` 全页、URL 可见、存盘到 `docs/` 对应子目录），并用**坐标换算后的箭头标注**（走 `/screenshot-annotate` skill）关键改动区域/验证点，让看的人一眼看懂这张图证明了什么。
+- 每步截图保留（遵循「⚠️ 截图规范」：浏览器真实视口宽（需要更清晰时提高 DPR）、`fullPage` 全页、URL 可见、存盘到 `docs/` 对应子目录），并用**箭头标注**关键改动区域/验证点，让看的人一眼看懂这张图证明了什么。
 - 若本次改动是纯后端/基础设施，按「非 UI / 后端 / 基础设施改动的效果截图获取方法」把 curl 响应渲染成暗色终端 HTML 截图。
 
 ### 5. 确认没问题才算完成
@@ -91,4 +105,4 @@ PR 合并后按项目发布流程执行根目录 `./release.sh` 发新版本（
 - 循环 review 细节：`loop-review` skill
 - 部署测试环境：`deploy-test` skill
 - 创建 PR / 截图上传：`create-pr` skill
-- 验证证据产出：`visual-report` skill
+- 验证证据产出：`visual-report` skill

package/skills/screenshot-annotate/SKILL.md

@@ -27,20 +27,27 @@ description: >-
 ```
 元素在「整页」中的 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`。
+fullPage 截图宽高 = 整页 CSS 宽高 × `devicePixelRatio`（DPR）。因此：
+
+- **DPR = 1**：整页 CSS 坐标 = 截图像素坐标，直接给 annotate.js 传 `x = rect.left + scrollX`、`y = rect.top + scrollY`，无需任何换算参数。
+- **DPR ≠ 1**（`set viewport <W> <H> 2` 提高了 DPR）：必须传 `--fullpage --dpr N`（N = `window.devicePixelRatio`），annotate.js 按 DPR 等比缩放，`w/h` 一并缩放。
+
+⚠️ **禁止**在 fullPage 场景用 `--viewport "cssW,cssH"` 让 annotate.js 按 `imageH / cssH` 算 Y 轴——`cssH` 是视口高不是整页高，页面越长标注越往下偏。
+
+⚠️ **坐标捕获命令会返回 `dpr`**：截图时记下 `set viewport` 是否用了 DPR>1，若用了必须把捕获到的 `dpr` 一并传给 annotate.js（`--fullpage --dpr <dpr>`），不要依赖记忆。
 
 ### 情形 B：设置了自定义 viewport 视口的截图（截图宽度 = viewport 宽）
 
-浏览器把 viewport 设成 X×Y，截图宽高 = X×Y（`window.innerWidth` / `innerHeight`）。元素坐标直接用 `rect` 的值即可。
+浏览器把 viewport 设成 X×Y，截图宽高 = X×Y × DPR（`window.innerWidth` / `innerHeight` 是 CSS 宽高）。元素坐标直接用 `rect` 的值即可，但传给 annotate.js 时：
+- DPR = 1：直接传，无需参数；
+- DPR > 1：传 `--viewport "cssW,cssH"`（cssW/cssH = `window.innerWidth/Height`），annotate.js 按截图/视口换算。
 
 ### 情形 C：一个普通（非拼接、无缩放）截图
 
 如果截图就是某视口的渲染结果，且截图宽 ≠ CSS 视口宽，说明有 `devicePixelRatio` 缩放。
-此时标注坐标 = CSS 坐标 × (截图宽 / 视口 CSS 宽)（横向），(截图高 / 视口 CSS 高)（纵向）。
+此时标注坐标 = CSS 坐标 × (截图宽 / 视口 CSS 宽)（横向），(截图高 / 视口 CSS 高)（纵向）——等价于传 `--viewport "cssW,cssH"` 给 annotate.js 自动换算。
 
 ## 坐标捕获命令（在打开的浏览器标签页上执行）
 
@@ -69,17 +76,19 @@ description: >-
 
 标注由 `annotate.js`（本 skill 目录内的零依赖 Node 脚本）完成。它把截图 + 坐标转成自包含标注 HTML（截图 base64 内嵌、SVG 箭头/框/文字精确放在换算后的坐标上），再用无头浏览器渲染为 PNG。
 
-脚本与 SKILL.md 位于同一 skill 目录（随 agent-rules 同步到各项目 `.claude/skills/screenshot-annotate/`）。调用时定位到该目录：
+脚本与 SKILL.md 位于同一 skill 目录（随 agent-rules 同步到各项目 `.claude/skills/screenshot-annotate/`）。调用时定位到该目录（在项目根目录下直接粘贴即可执行，禁止用 `BASH_SOURCE[0]`——那只在脚本文件内有效，粘贴到终端时为空）：
 
 ```bash
-SKILL_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"   # 或显式 .claude/skills/screenshot-annotate 目录
+# 从项目根目录定位 skill 目录（git rev-parse --show-toplevel 返回仓库根，与 loop-review 里 check-review.sh 的取法一致）
+ROOT="$(git rev-parse --show-toplevel)"
+SKILL_DIR="$ROOT/.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 坐标会自动换算
+- 坐标默认视为**设备像素**（截图内坐标）；`--viewport "cssW,cssH"` 传入时视为 CSS 视口坐标自动换算（非 fullPage）；`--fullpage --dpr N` 用于 fullPage 全页截图（坐标视为整页 CSS 坐标，按 DPR 缩放）
 - `--label` 顶部标题条（适合「修复前/修复后」对比）、`--url` 在标题条显示 URL 满足「URL 可见」
 - `text` 文本框自动排布在目标旁空闲侧，不遮挡内容；`w/h` 存在时画高亮圆角框指向其中心
 

package/skills/screenshot-annotate/annotate.js

@@ -17,16 +17,19 @@
  *   - 默认：--json 里的 x/y/w/h 视为「截图设备像素坐标」（截图像素）。
  *     画布里实际位置 = margin + 给定值。
  *   - 传 --viewport "cssW,cssH"：x/y/w/h 视为「CSS 视口坐标」，
- *     脚本先按 (截图宽/cssW)、(截图高/cssH) 换算成设备像素，再画。
+ *     脚本按 (截图宽/cssW)、(截图高/cssH) 换算成设备像素。仅适用于非 fullPage 视口截图。
+ *   - 传 --fullpage --dpr N：x/y/w/h 视为「整页 CSS 坐标」，按 DPR 等比缩放
+ *     （fullPage 全页截图宽高 = CSS 宽高 × DPR）。⚠️ 禁止用 imageH/viewport.h 算 Y 轴，
+ *     viewport.h 是视口高不是整页高，会放错。
  *   - 全页拼接截图时，元素相对整页的左/顶 = rect.left + scrollX / rect.top + scrollY，
- *     把这两个和作为 x/y 传入（这就是整页里的设备像素位置，无需 --viewport）。
+ *     把这两个和作为 x/y 传入（这就是整页里的 CSS 位置，配 --fullpage --dpr 使用）。
  *
  * 用法：
  *   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 探测）
+ *   <image>    输入截图（PNG/JPG/WebP/GIF，尺寸由 IHDR / JPEG SOF / WebP RIFF / GIF 头探测，sips 仅作兜底）
  *   <outHtml>  输出的标注 HTML 路径
  *   --json     标注数组 JSON，每项：{x,y[,w,h][,text][,color][,stroke-width]}
  *              - x/y：目标点（默认设备像素坐标；传 --viewport 时为 CSS 坐标）
@@ -35,8 +38,9 @@
  *              - color：主色（箭头/框/文本描边），缺省 #f43f5e
  *   --label    顶部标题条文字（适合「修复前/修复后」对比图），可省略
  *   --labelColor  标题条主题色，缺省 #f43f5e
- *   --viewport "cssW,cssH"  指定后坐标视为 CSS 视口坐标，自动换算
- *   --margin-frac  画布四周留白相对图片长边的比例（给箭头腾空间），缺省 0.05
+ *   --viewport "cssW,cssH"  非 fullPage 视口截图：坐标视为 CSS 视口坐标，按截图/视口换算
+ *   --fullpage --dpr N  fullPage 全页截图：坐标视为整页 CSS 坐标，按 DPR 等比缩放
+ *   --margin-frac  画布四周留白比例（相对图片**短边**，另设绝对上限 200px，防全页长图画布过大），缺省 0.05
  *   --url       可选：在标题条右侧显示页面 URL（用于「URL 可见」证据要求）
  *
  * 渲染为 PNG 的固定流程（配合 screenshot-annotate skill）：
@@ -105,19 +109,23 @@ function jpegSize(buf) {
       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）
+    // 无长度字段的标记段：SOI(FFD8)/EOI(FFD9)/TEM(FF01)/RSTn(FFD0-D7) 等，跳过 2 字节即可。
+    // 若不跳过会把后续两字节误当段长，pos 跳到错误位置，甚至解析出错误的宽高。
+    if (
+      marker === 0x01 ||
+      (marker >= 0xd0 && marker <= 0xd9)
+    ) {
+      pos += 2;
+      continue;
+    }
+    // SOF0..15（除 DHT C4、JPG C8、DAC CC）；其余带长度的 APPn/COM 等靠段长跳过
     if (
       marker >= 0xc0 &&
       marker <= 0xcf &&
       marker !== 0xc4 &&
       marker !== 0xc8 &&
-      marker !== 0xcc &&
-      (marker < 0xd0 || marker > 0xd7) &&
-      marker !== 0xda &&
-      marker !== 0xdb &&
-      marker !== 0xdc
+      marker !== 0xcc
     ) {
-      const segLen = buf.readUInt16BE(pos + 2);
       const height = buf.readUInt16BE(pos + 5);
       const width = buf.readUInt16BE(pos + 7);
       return { width, height };
@@ -145,8 +153,60 @@ function sipsSize(filePath) {
   return null;
 }
 
+function webpSize(buf) {
+  // RIFF....WEBPVP8 / VP8L / VP8X
+  if (
+    buf.length >= 30 &&
+    buf.toString("ascii", 0, 4) === "RIFF" &&
+    buf.toString("ascii", 8, 12) === "WEBP"
+  ) {
+    const fourcc = buf.toString("ascii", 12, 16);
+    if (fourcc === "VP8X") {
+      // VP8X：24-bit 宽/高，各减 1，最小单位 1px
+      const w = 1 + buf.readUIntLE(24, 3);
+      const h = 1 + buf.readUIntLE(27, 3);
+      return { width: w, height: h };
+    }
+    if (fourcc === "VP8L") {
+      // VP8L：14-bit 宽 + 14-bit 高（各减 1）
+      const b = buf;
+      const bits = b.readUInt32LE(21);
+      const w = (bits & 0x3fff) + 1;
+      const h = ((bits >> 14) & 0x3fff) + 1;
+      return { width: w, height: h };
+    }
+    if (fourcc === "VP8 ") {
+      // VP8 lossy：宽高字段低 14 位是实际尺寸，高 2 位是 scale 位（水平和垂直缩放 2-bit），
+      // 直接读 16 位会把 scale 位混入宽高，导致 >16383px 的图尺寸算错。必须 & 0x3fff 屏蔽高 2 位。
+      const w = buf.readUInt16LE(26) & 0x3fff;
+      const h = buf.readUInt16LE(28) & 0x3fff;
+      if (w > 0 && h > 0) return { width: w, height: h };
+    }
+  }
+  return null;
+}
+
+function gifSize(buf) {
+  // GIF8[79]a  + 16-bit LE 宽高
+  const isGif =
+    (buf.length >= 10 && buf.toString("ascii", 0, 6) === "GIF87a") ||
+    (buf.length >= 10 && buf.toString("ascii", 0, 6) === "GIF89a");
+  if (isGif) {
+    const w = buf.readUInt16LE(6);
+    const h = buf.readUInt16LE(8);
+    if (w > 0 && h > 0) return { width: w, height: h };
+  }
+  return null;
+}
+
 function detectSize(filePath, buf) {
-  return pngSize(buf) || jpegSize(buf) || sipsSize(filePath);
+  return (
+    pngSize(buf) ||
+    jpegSize(buf) ||
+    webpSize(buf) ||
+    gifSize(buf) ||
+    sipsSize(filePath)
+  );
 }
 
 // ---------------------------------------------------------------- HTML 安全
@@ -197,20 +257,25 @@ function buildHtml({
   url,
   marginFrac,
 }) {
-  const margin = Math.max(24, Math.round(Math.max(imageW, imageH) * marginFrac));
+  // margin 基于图片短边并设绝对上限：全页长图高度可达上万像素，
+  // 若按长边 5% 会让画布膨胀到两万多高，Chrome 截图直接失败。
+  const margin = Math.max(24, Math.min(200, Math.round(Math.min(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）、排版文本
+  // ⚠️ 底图实际渲染在 (margin, margin)，因此所有标注坐标统一加 margin，
+  //    后续几何计算与边界判断全部在画布坐标系进行，避免整体偏移 margin。
   const placed = [];
   for (const a of annotations) {
-    const color = a.color || "#f43f5e";
+    // a.color 与 labelColor 走同一套 6 位十六进制校验，防止非法值/注入拼进 SVG
+    const color = /^#[0-9a-fA-F]{6}$/.test(a.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 x = margin + num(a.x, 0);
+    const y = margin + 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 });
@@ -222,18 +287,19 @@ function buildHtml({
   // 生成每条标注的 SVG 片段
   const parts = [];
   for (const a of placed) {
-    // 目标中心
+    // 目标中心（已在画布坐标系，含 margin）
     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 fontSize = Math.max(16, Math.round(imageW / 90));
+    const metrics = a.text ? estimateTextMetrics(a.text, fontSize) : { width: 0, height: 0 };
+    const boxW = Math.ceil((metrics.width || 0) + fontSize * 1.2);
+    const boxH = Math.ceil(metrics.height + fontSize * 0.6);
     const pad = 8;
     const bw = a.text ? boxW : 0;
     const bh = a.text ? boxH : 0;
 
     // 文本候选方位（上、下、左、右），取第一个不越界且不遮目标的
+    // 坐标已含 margin，图片区在 [margin, margin+imageW] × [margin, margin+imageH]
     const cands = [
       { bx: tx - bw / 2, by: ty - gap - bh, name: "up" },
       { bx: tx - bw / 2, by: ty + gap, name: "down" },
@@ -258,7 +324,7 @@ function buildHtml({
     const hasTarget = a.w > 0 && a.h > 0;
     const hasText = Boolean(a.text);
 
-    // 高亮目标框
+    // 高亮目标框（坐标已含 margin，无需再加）
     if (hasTarget) {
       const rx = Math.max(8, a.lw * 1.8);
       parts.push(`
@@ -267,7 +333,7 @@ function buildHtml({
           vector-effect="non-scaling-stroke" />`);
     }
 
-    // 文本框
+    // 文本框：白底固定深色文字（避免默认红字 + 白底 = 白字白底不可读）
     if (hasText) {
       const rx = Math.max(6, a.lw * 1.5);
       parts.push(`
@@ -279,8 +345,8 @@ function buildHtml({
           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>`);
+          font-size="${fontSize}" font-weight="600" text-anchor="middle" dominant-baseline="central"
+          fill="#111827">${escapeHtml(a.text)}</text>`);
     }
 
     // 箭头：文本框中心 → 目标中心
@@ -290,8 +356,9 @@ function buildHtml({
     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));
+      // 起点避开文本框：上/下方位沿垂直外移 bh/2，左/右方位沿水平外移 bw/2
+      const halfExtent = slot.name === "up" || slot.name === "down" ? bh * 0.5 : bw * 0.5;
+      const star = Math.min(1, Math.max(0, (halfExtent + a.lw * 2) / len));
       const ex = (star * dx) / len;
       const ey = (star * dy) / len;
       const sx2 = sx + ex * len;
@@ -311,23 +378,27 @@ function buildHtml({
     }
   }
 
-  // 标题条
+  // 标题条：画在图片上方的 margin 留白区（不遮挡截图顶部，保证「URL 可见」）
+  // 传了 --label 或 --url 任一就渲染标题条：单独传 --url（仅需 URL 证据、不要文字标签）也必须生效，避免被静默忽略
   let bar = "";
-  if (label) {
-    const barH = Math.max(40, Math.round(imageH * 0.05));
-    const fs = Math.max(20, Math.round(imageW / 55));
+  if (label || url) {
+    const barH = Math.min(Math.max(40, Math.round(imageH * 0.05)), Math.max(24, margin));
+    // 字号必须由 barH 反推，保证字放得进标题条：宽而矮的横向图（如 3840×400 局部截图）上
+    // barH 可能被 margin 上限压得很小（24px），若仍按 imageW/55 取（≈70px）文字会被 overflow:hidden 裁掉。
+    // 用 Math.min(barH * 0.55, imageW / 55) 让字号受 barH 约束，同时保底 20px。
+    const fontSize = Math.max(20, Math.min(Math.round(barH * 0.55), 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"
+      <rect x="${margin}" y="${margin - barH}" 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>
+      <text x="${margin + imageW / 2}" y="${margin - barH + barH / 2}" font-family="system-ui, sans-serif"
+        font-size="${fontSize}" 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"
+          ? `<text x="${margin + imageW - 14}" y="${margin - barH + barH / 2}" font-family="ui-monospace, Menlo, monospace"
+              font-size="${Math.round(fontSize * 0.55)}" text-anchor="end" dominant-baseline="central"
               fill="#ffffff" fill-opacity="0.92">${urlText}</text>`
           : ""
       }`;
@@ -359,13 +430,6 @@ function buildHtml({
   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";
-  }
 }
 
 // ---------------------------------------------------------------- 主流程
@@ -407,15 +471,44 @@ function main() {
   }
 
   // 坐标换算：CSS 坐标 → 设备像素
-  let viewport = null;
-  if (keyed.viewport && keyed.viewport !== true) {
+  // 三种模式：
+  //  - 默认：--json 的 x/y/w/h 视为「截图设备像素坐标」，×1 直接用；
+  //  - --viewport "cssW,cssH"：非 fullPage 视口截图，坐标是 CSS 视口坐标，按 (截图宽/视口宽) 缩放；
+  //  - --fullpage + --dpr N：fullPage 全页截图，坐标是整页 CSS 坐标，按 DPR 等比缩放。
+  //    ⚠️ fullPage 下绝不能按 imageH/viewport.h 缩放（viewport.h 只是视口高，不是整页高，会把 Y 轴放错）。
+  let scaleX = 1;
+  let scaleY = 1;
+  if (keyed.fullpage) {
+    // fullPage 模式依赖 DPR 把整页 CSS 坐标换算成设备像素。缺 --dpr 时 DPR=1 是合法场景
+    // （fullPage 截图恰好 DPR=1），但显式传了非正数/非数字必须报错，禁止静默降级导致标注整体偏移。
+    // ⚠️ 必须区分「缺省（undefined/true/""）」与「显式传了非法值（如 abc/2x/-1/0）」：
+    //    num() 会把显式非法值也归一化成默认值 1，仅凭 dpr>0 校验判断不出「非法值被静默降级」，
+    //    因此要在 num() 之外单独检查「显式传值但非有限正数」并 exit 1。
+    const dprExplicit = keyed.dpr !== undefined && keyed.dpr !== true && keyed.dpr !== "";
+    if (dprExplicit && !(Number.isFinite(Number(keyed.dpr)) && Number(keyed.dpr) > 0)) {
+      console.error(`❌ --dpr 必须是正数，收到 "${keyed.dpr}"`);
+      process.exit(1);
+    }
+    const dpr = num(keyed.dpr, 1);
+    if (!(dpr > 0)) {
+      console.error("❌ --dpr 必须为正数");
+      process.exit(1);
+    }
+    if (!dprExplicit) {
+      console.warn("⚠️ 未传 --dpr，按 1 处理。若 fullPage 截图时 DPR≠1（如浏览器缩放渲染），坐标会整体偏移，请显式传 --dpr N。");
+    }
+    scaleX = dpr;
+    scaleY = dpr;
+  } else 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 };
+      scaleX = imageW / vw;
+      scaleY = imageH / vh;
+    } else {
+      console.error(`❌ --viewport 格式应为 "cssW,cssH"，收到 "${keyed.viewport}"`);
+      process.exit(1);
     }
   }
-  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,
@@ -438,7 +531,8 @@ function main() {
   });
 
   fs.writeFileSync(outHtml, html);
-  const margin = Math.max(24, Math.round(Math.max(imageW, imageH) * marginFrac));
+  // 与 buildHtml 里同一套公式（短边 + 绝对上限 200px），保证打印的画布尺寸与实际一致
+  const margin = Math.max(24, Math.min(200, Math.round(Math.min(imageW, imageH) * marginFrac)));
   console.log(
     `✅ 已生成标注 HTML → ${outHtml}`,
   );

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. **每步截图**：必须带箭头标注关键区域/验证点，图注写清「这张图证明了什么」，标注关键行/关键数据
-- 截图本身遵循「⚠️ 截图规范」：真实视口 + `fullPage` 全页、URL 可见、存到 `docs/` 对应子目录、文件名「编号 + 英文描述」。截图上的箭头/框标注统一走 `/screenshot-annotate` skill（坐标精确换算，禁止肉眼估位）。
+- 截图本身遵循「⚠️ 截图规范」：浏览器真实视口宽（需要更清晰时提高 DPR）、`fullPage` 全页、URL 可见、存到 `docs/` 对应子目录、文件名「编号 + 英文描述」。
 
 ## 不写测试 ≠ 不查错
 
@@ -70,4 +70,4 @@ description: >-
 
 - ⚠️ 第一反应不是写代码、也不是写测试，而是「想清楚怎么用证据证明功能对了」
 - ⚠️ 验证报告必须先给用户看、用户确认无误才算完成，禁止 AI 自认为「看起来对」就宣称完成
-- ⚠️ 带得动的改动（页面/Redis/数据库）必须走可视化验证；只有带不动又不属于上面两类的，才需要向用户说明并请用户决定
+- ⚠️ 带得动的改动（页面/Redis/数据库）必须走可视化验证；只有带不动又不属于上面两类的，才需要向用户说明并请用户决定