@routerhub/agent-rules 1.5.150 → 1.5.152

package/AGENTS.base.md

@@ -269,7 +269,7 @@
 ## 禁止项
 
 - ⚠️ AI 禁止自动执行格式化命令（`npm run format`、`prettier` 等）。
-- ⚠️ 禁止修改 GCLB 配置（原因和替代方案见下方「共享基础设施变更铁律」）。
+- ⚠️ 禁止修改 GCLB 配置，除用户明确确认外（原因和替代方案见下方「共享基础设施变更铁律」；获得确认后的修改操作须遵循「网关/负载均衡 404 排查规范」的 additive-only 原则）。
 - 禁止修改核心业务文件和 API 相关代码。
 - `.env` 仅允许配端口号，密钥/Token 等敏感信息必须配到 Nacos 配置中心。
 
@@ -361,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` 能复用时必须优先复用。
 
 <!-- 前端特有规则在此添加 -->
 
@@ -391,6 +396,7 @@
 - 🔴 **会导致实际 bug / 数据丢失 / 数据错误 / 安全漏洞**：有明确触发路径（真实输入、真实调用链能复现），读 diff 能确认后果。
 - 🟡 **真实风险**：有明确触发条件，且触发后后果严重（如并发竞态、错误被静默吞掉、未处理空值导致崩溃）。
 - **违反本项目已固化规则**：AGENTS.base.md / AGENTS.private.md 里的 ⚠️ 铁律（DELETE 铁律、部署自包含、数据链路核对、环境配置禁止推断、测试环境验证前置等），diff 中明确违反 → 必须报。
+- **外部事实核查确认的配置错误**：按「审查方法 → ④ 外部事实核查」查出的事实性错误（死域名、环境归属不一致、对外死值等），即使 diff 内部自洽也必须报——这正是「指向错误环境」类问题的唯一暴露途径（呼应「环境配置禁止推断」）。
 
 ### 禁止报（不是问题，报了只会拉长循环）
 
@@ -399,6 +405,7 @@
 - ❓ **无法确认真假的问题**：读 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 发版统一管理，属正常流程。
 
 ### 判断标准
 
@@ -435,6 +442,16 @@
 ⚠️ PR 描述有「行为变更表 / 改前改后对比表」时，审查以它为靶心，逐行问「这条真的成立吗」，用 diff 逐行验证；PR 没列表的，review 意见至少覆盖「改了什么行为 / 不变的行为有没有被误伤」两个面。
 ⚠️ 对作者标注「不在本 PR 范围」的内容（如相关子系统计费、其它仓库同步）：不要求作者修，但必须判断是否构成「已知缺口被静默放过」——已暴露的边界缺口，作者必须在 PR 里显式记录后续动作、或至少点明仍待处理，禁止「提了不等于了」。
 
+**④ 外部事实核查（diff 之外的真实性验证）**
+
+⚠️ diff 内逻辑审完了，对**部署脚本 / 配置 / 品牌 / 环境归属类改动**，还必须做一轮 diff 之外的「外部事实核查」——这类改动最常见的坑是「看着都对，其实指向了错误的环境」。核查不查 DNS / 不核对归属，纯看 diff 是发现不了的（PR #135 教训：AI review 漏掉的 namespace 归属、死域名、死邮箱，人工 reviewer 靠 `dig` + 读关联 PR 才发现）。按下面的清单逐项验证：
+
+- **域名 / 子域名真实存在**：脚本或配置里出现的每个域名、派生子域名，逐个 `dig +short <域名>` 验证有解析记录；约定派生的（如 `doc.<domain>` / `api.<domain>`）不能只看主域成立就推断子域成立——不同子域可能有的解析有的无解析。无解析的死域名必须报（哪怕它只在注释里，也会误导后来者）。
+- **环境归属一致（品牌 ↔ namespace ↔ 项目 ↔ 数据库 ↔ 域名）**：部署脚本里 `PROJECT` / `NACOS_NAMESPACE_ID` / Artifact Registry 仓库 / VPC / 数据库，和脚本服务的品牌、域名是否指向**同一个环境**。最危险的形态：脚本带了正确的域名和品牌，却指向**另一个品牌的库/namespace**——「看着是条正经路径」，实则从没跑过或指向错误环境。发现归属不一致，必须报并给出一致的目标配置。
+- **跨 PR / 跨系统的共享与边界**：改动涉及「多系统共享」的配置（共用项目、共用 namespace、共用仓库）时，读关联 PR 描述、查配置中心真实归属，确认「刻意共用」还是「漏改」——禁止凭 diff 内自洽就默认成立。判定为刻意共用的，必须在脚本/注释里显式写明依据，否则视为漏配。
+- **对外可见的真实值**：写进发布内容 / 对外页面 / 邮件 / 招聘启事等的邮箱、URL、联系方式，必须验证真实存在（邮箱查 MX 记录 `dig MX`、收件箱是否在域名邮件体系内；URL 查 DNS + HTTP 可达）。这类值一旦是死的，比控制台死链更难被发现（用户点了没反应，测试验收也难察觉）。
+- **能查就查，禁止「推断即认可」**：能用一个命令查证的事实（`dig` / `gh pr view` / `curl` / 配置中心），必须查证后再下结论；查不到或需要人工确认的，明确写「待确认」并说明在哪查，禁止凭 diff 内自洽或惯性推断当结论。
+
 **与审稿边界的配合**：本章找出的问题，是否上报仍按「必须报 / 禁止报」判断（真问题、真实风险、违反铁律 → 报；口味、防御、无法确认真假 → 不报）。每条意见必须带「新增量全局跟进」的链路证据（具体 diff 行 + 谁赋值谁读谁落库），禁止只给结论不给路径。
 
 ---

package/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 所有对 @routerhub/agent-rules 的重大更改都会记录在这个文件中。
 
+## [1.5.152] - 2026-08-26
+
+### Added
+
+- 新增「审查方法 → ④ 外部事实核查」规则（审稿方必做）：审查部署脚本 / 配置 / 品牌 / 环境归属类改动时，除 diff 内逻辑审查外，还必须做一轮 diff 之外的真实性核查——域名子域逐个 `dig` 验证（禁止主域成立就推断子域成立）、环境归属一致性（品牌 ↔ namespace ↔ 项目 ↔ 数据库 ↔ 域名是否指向同一环境）、跨 PR / 跨系统共享与边界（读关联 PR 描述、查配置中心真实归属，区分「刻意共用」与「漏改」）、对外可见真实值（邮箱查 MX 记录、URL 查 DNS + HTTP 可达）。原因：这类改动最常见的坑是「看着都对、其实指向了错误的环境」，纯看 diff 无法发现，只有人工靠 `dig` + 读关联 PR 才能暴露（PR #135 教训：AI review 漏掉的 namespace 归属、死域名、死邮箱，人工 reviewer 通过外部核查才发现）。
+- 「审稿边界 → 必须报」清单新增一条：「外部事实核查确认的配置错误」，即使 diff 内部自洽也必须报——这是「指向错误环境」类问题的唯一暴露途径（呼应「环境配置禁止推断」铁律）。
+
 ## [1.5.124] - 2026-08-12
 
 ### Added

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@routerhub/agent-rules",
-  "version": "1.5.150",
+  "version": "1.5.152",
   "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

@@ -269,7 +269,7 @@ name: "通用规则"
 ## 禁止项
 
 - ⚠️ AI 禁止自动执行格式化命令（`npm run format`、`prettier` 等）。
-- ⚠️ 禁止修改 GCLB 配置（原因和替代方案见下方「共享基础设施变更铁律」）。
+- ⚠️ 禁止修改 GCLB 配置，除用户明确确认外（原因和替代方案见下方「共享基础设施变更铁律」；获得确认后的修改操作须遵循「网关/负载均衡 404 排查规范」的 additive-only 原则）。
 - 禁止修改核心业务文件和 API 相关代码。
 - `.env` 仅允许配端口号，密钥/Token 等敏感信息必须配到 Nacos 配置中心。
 

package/rules/review-boundary.md

@@ -13,6 +13,7 @@ outputName: "review-boundary"
 - 🔴 **会导致实际 bug / 数据丢失 / 数据错误 / 安全漏洞**：有明确触发路径（真实输入、真实调用链能复现），读 diff 能确认后果。
 - 🟡 **真实风险**：有明确触发条件，且触发后后果严重（如并发竞态、错误被静默吞掉、未处理空值导致崩溃）。
 - **违反本项目已固化规则**：AGENTS.base.md / AGENTS.private.md 里的 ⚠️ 铁律（DELETE 铁律、部署自包含、数据链路核对、环境配置禁止推断、测试环境验证前置等），diff 中明确违反 → 必须报。
+- **外部事实核查确认的配置错误**：按「审查方法 → ④ 外部事实核查」查出的事实性错误（死域名、环境归属不一致、对外死值等），即使 diff 内部自洽也必须报——这正是「指向错误环境」类问题的唯一暴露途径（呼应「环境配置禁止推断」）。
 
 ### 禁止报（不是问题，报了只会拉长循环）
 
@@ -21,6 +22,7 @@ outputName: "review-boundary"
 - ❓ **无法确认真假的问题**：读 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 发版统一管理，属正常流程。
 
 ### 判断标准
 
@@ -57,6 +59,16 @@ outputName: "review-boundary"
 ⚠️ PR 描述有「行为变更表 / 改前改后对比表」时，审查以它为靶心，逐行问「这条真的成立吗」，用 diff 逐行验证；PR 没列表的，review 意见至少覆盖「改了什么行为 / 不变的行为有没有被误伤」两个面。
 ⚠️ 对作者标注「不在本 PR 范围」的内容（如相关子系统计费、其它仓库同步）：不要求作者修，但必须判断是否构成「已知缺口被静默放过」——已暴露的边界缺口，作者必须在 PR 里显式记录后续动作、或至少点明仍待处理，禁止「提了不等于了」。
 
+**④ 外部事实核查（diff 之外的真实性验证）**
+
+⚠️ diff 内逻辑审完了，对**部署脚本 / 配置 / 品牌 / 环境归属类改动**，还必须做一轮 diff 之外的「外部事实核查」——这类改动最常见的坑是「看着都对，其实指向了错误的环境」。核查不查 DNS / 不核对归属，纯看 diff 是发现不了的（PR #135 教训：AI review 漏掉的 namespace 归属、死域名、死邮箱，人工 reviewer 靠 `dig` + 读关联 PR 才发现）。按下面的清单逐项验证：
+
+- **域名 / 子域名真实存在**：脚本或配置里出现的每个域名、派生子域名，逐个 `dig +short <域名>` 验证有解析记录；约定派生的（如 `doc.<domain>` / `api.<domain>`）不能只看主域成立就推断子域成立——不同子域可能有的解析有的无解析。无解析的死域名必须报（哪怕它只在注释里，也会误导后来者）。
+- **环境归属一致（品牌 ↔ namespace ↔ 项目 ↔ 数据库 ↔ 域名）**：部署脚本里 `PROJECT` / `NACOS_NAMESPACE_ID` / Artifact Registry 仓库 / VPC / 数据库，和脚本服务的品牌、域名是否指向**同一个环境**。最危险的形态：脚本带了正确的域名和品牌，却指向**另一个品牌的库/namespace**——「看着是条正经路径」，实则从没跑过或指向错误环境。发现归属不一致，必须报并给出一致的目标配置。
+- **跨 PR / 跨系统的共享与边界**：改动涉及「多系统共享」的配置（共用项目、共用 namespace、共用仓库）时，读关联 PR 描述、查配置中心真实归属，确认「刻意共用」还是「漏改」——禁止凭 diff 内自洽就默认成立。判定为刻意共用的，必须在脚本/注释里显式写明依据，否则视为漏配。
+- **对外可见的真实值**：写进发布内容 / 对外页面 / 邮件 / 招聘启事等的邮箱、URL、联系方式，必须验证真实存在（邮箱查 MX 记录 `dig MX`、收件箱是否在域名邮件体系内；URL 查 DNS + HTTP 可达）。这类值一旦是死的，比控制台死链更难被发现（用户点了没反应，测试验收也难察觉）。
+- **能查就查，禁止「推断即认可」**：能用一个命令查证的事实（`dig` / `gh pr view` / `curl` / 配置中心），必须查证后再下结论；查不到或需要人工确认的，明确写「待确认」并说明在哪查，禁止凭 diff 内自洽或惯性推断当结论。
+
 **与审稿边界的配合**：本章找出的问题，是否上报仍按「必须报 / 禁止报」判断（真问题、真实风险、违反铁律 → 报；口味、防御、无法确认真假 → 不报）。每条意见必须带「新增量全局跟进」的链路证据（具体 diff 行 + 谁赋值谁读谁落库），禁止只给结论不给路径。
 
 ---

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,60 @@ git push origin "$ORIGINAL_BRANCH"
 
 ```bash
 # 确认本地功能分支与远程已同步（本地无未推送提交）
+# 先 fetch 让 origin/* 引用全部最新，再用「分支的 upstream..HEAD」精确列举未推送提交
+# ⚠️ 用全量 "git fetch origin" 而不是 "fetch origin <X>"：单分支 fetch 只写 FETCH_HEAD/只更新该分支引用，
+#    ① 分支已 push 过但本地无远程跟踪引用（如 clone 后手动 push）时，后面 rev-parse --verify "origin/X" 会误判
+#       「远程分支不存在」、把已推送提交误报为未推送；
+#    ② upstream 非同名分支（如 push -u origin other/branch）时，@{u} 指向的引用没被单分支 fetch 更新，
+#        git log @{u}..HEAD 基于过期引用计算，同样误判。
+#    全量 fetch 一次更新 origin 下所有远程跟踪引用，以上两种场景都消除。
+# ⚠️ 分支可能从未推送过（远程不存在该 ref），git fetch origin 对不存在的引用不会报错中断，
+#    因此无需 || true 兜底；git status 在 fetch 后确认工作区状态
+git fetch origin
 git status
-git log origin/"$ORIGINAL_BRANCH".."$ORIGINAL_BRANCH" --oneline   # 应无输出 = 无未推送提交
+# 先选定「比对基准引用」，再分别取两个方向的差集：
+#   UNPUSHED = 本地有、基准没有（本地领先，未推送）
+#   UNPULLED = 基准有、本地没有（本地落后，未拉取）
+# ⚠️ 基准优先级：origin/功能分支 > @{u} > origin/默认分支。
+#    功能分支通常由 `git checkout -b feature/X origin/main` 创建（upstream=origin/main）、
+#    再用 `git push origin feature/X` 推送（不设 upstream），此时 @{u}=origin/main，
+#    用它做基准会把「功能分支相对 main 的全部新增提交」误报为未推送（前 26 轮就是这么误报的）。
+#    全量 git fetch origin 之后 origin/功能分支 一定是最新，且它就是部署目标（PR 对应分支），
+#    语义最准；@{u} 只在「功能分支从未以自己名字推送过」时作降级。
+DEFAULT_BRANCH=$(git remote show origin | grep 'HEAD branch' | cut -d: -f2 | tr -d ' ')
+if git rev-parse --verify "origin/$ORIGINAL_BRANCH" >/dev/null 2>&1; then
+  BASE_REF="origin/$ORIGINAL_BRANCH"
+elif git rev-parse --abbrev-ref '@{u}' >/dev/null 2>&1; then
+  BASE_REF="@{u}"
+elif git rev-parse --verify "origin/$DEFAULT_BRANCH" >/dev/null 2>&1; then
+  BASE_REF="origin/$DEFAULT_BRANCH"
+else
+  # 远程连功能分支与默认分支引用都没有（全新仓库/远程为空）→ 当前分支必然从未推送。
+  # ⚠️ 不能用 git log HEAD 兜底：会把 main 全部历史也算进来，输出上千行淹没真正关心的提交；直接阻断并提示。
+  echo "❌ 远程找不到 ${ORIGINAL_BRANCH} 与 ${DEFAULT_BRANCH} 分支引用，无法比对推送状态；请先 git push origin ${ORIGINAL_BRANCH} 再部署"
+  exit 1
+fi
+UNPUSHED=$(git log "$BASE_REF"..HEAD --oneline)
+UNPULLED=$(git log HEAD.."$BASE_REF" --oneline)
+# ⚠️ 存在未推送提交时必须 exit 1 阻断，不能只打警告继续走部署流程——否则未推送到 PR 分支的代码会被合入/部署到 test，
+#    导致 PR 分支与测试环境代码不一致（违背上文「必须确认所有 review 修复已推送再进行 test 合并」的硬性要求）。
+[ -z "$UNPUSHED" ] && echo "✅ 无未推送提交" || {
+  echo "❌ 存在未推送提交："
+  echo "$UNPUSHED"
+  exit 1
+}
+# ⚠️ 反向检查本地是否落后于远程：只查 UNPUSHED 会漏掉「本地落后」——远程 PR 分支已有别人/其他环境推的新提交、
+#    而本地还是旧 HEAD 时，git log @{u}..HEAD 为空 → 误报「✅ 无未推送提交」→ 把本地旧代码合进 test 部署，
+#    测试环境跑的不是 PR 最新代码。必须同样阻断，先 git pull 再部署。
+[ -z "$UNPULLED" ] && echo "✅ 本地不落后于远程" || {
+  echo "❌ 本地分支落后于远程（远程有本地没有的提交），请先 git pull 再部署："
+  echo "$UNPULLED"
+  exit 1
+}
 ```
 
+⚠️ 比对基准用 `origin/$ORIGINAL_BRANCH`（PR 对应分支的远程引用）而不是 `@{u}` 优先：功能分支通常由 `git checkout -b feature/X origin/main` 创建、再 `git push origin feature/X` 推送（无 `-u`），此时 `@{u}` 仍指向 origin/main，用它做基准会把「功能分支相对 main 的全部新增提交」误报为未推送；而全量 `git fetch origin` 之后 `origin/$ORIGINAL_BRANCH` 就是 PR 分支最新状态，用它对比双向差集（`origin/$ORIGINAL_BRANCH..HEAD` 未推送、`HEAD..origin/$ORIGINAL_BRANCH` 未拉取）语义最准。`@{u}` 仅在功能分支从未以自己名字推送过（origin/$ORIGINAL_BRANCH 引用不存在）时作降级。⚠️ `git log origin/X..HEAD` 对**不存在的引用会直接 fatal**（而不是返回空），因此先用 `git rev-parse --verify "origin/X"` 探测；功能分支、`@{u}` 与默认分支引用都不存在（全新仓库）时无法比对，直接阻断要求先推送。
+
 - ⚠️ 若 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,35 @@ 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` 返回的 LATEST 只回答「最新一轮 AI review **审查了哪个 commit**」，它只证明「bot 已到达当前 HEAD」，**不**证明「该轮 review 里没有值得修的问题」。因此「LATEST = CUR」只是**必要条件**，不能单独作为「循环 review 已收敛」的判据。
+
+⚠️ 收敛判据必须是两条**同时满足**：
+1. **review 已到达**：`LATEST` 等于 `CUR`（或等于 /loop-review 最后处理过的 commit），否则 bot 还没审到最新 push，循环 review 尚未完成；
+2. **该轮已无值得修的新问题**：打开最新一条 review 的正文（`gh pr view $PR --json reviews -q '.reviews[-1].body'`，或 `/loop-review` 的抓取命令），逐条核对——所有值得修的问题都已修复，剩余问题均已有明确的 Won't fix / 误报 / 已处理回复。只要还有一条值得修而未处理的问题，就必须回到 `/loop-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 +75,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 +109,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,30 @@ 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）
+    // JPEG 规范允许 marker 前缀 0xFF 与 marker 字节之间出现任意多个 0xFF 填充字节。
+    // 遇到 FF FF D8 这类序列时 marker === 0xff，若不跳过会把 marker 当段长读、pos 跳到随机偏移，
+    // 甚至可能在错误偏移上命中 0xC0..0xCF 返回假宽高，导致画布/标注坐标整体错位。这里 pos++ 继续，把第二个 FF 当新前缀。
+    if (marker === 0xff) {
+      pos++;
+      continue;
+    }
+    // 无长度字段的标记段：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 +160,84 @@ 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)
+  );
+}
+
+// 按文件内容（magic bytes）判断 MIME，避免依赖扩展名——扩展名可能与实际内容不符
+// （如 JPEG 内容误命名 .png），此时若按扩展名生成 data:image/png;base64 会渲染异常。
+// 各魔数探测函数已按内容识别格式，直接复用它返回的类型；找不到魔数才回退扩展名（sips 兜底场景）。
+function detectMime(buf, filePath) {
+  if (buf.length >= 8 && buf.readUInt32BE(0) === 0x89504e47) return "image/png";
+  if (buf.length >= 3 && buf[0] === 0xff && buf[1] === 0xd8 && buf[2] === 0xff) return "image/jpeg";
+  if (
+    buf.length >= 12 &&
+    buf.toString("ascii", 0, 4) === "RIFF" &&
+    buf.toString("ascii", 8, 12) === "WEBP"
+  ) {
+    return "image/webp";
+  }
+  if (
+    buf.length >= 6 &&
+    (buf.toString("ascii", 0, 6) === "GIF87a" || buf.toString("ascii", 0, 6) === "GIF89a")
+  ) {
+    return "image/gif";
+  }
+  if (buf.length >= 4 && buf.toString("ascii", 0, 4) === "<svg") return "image/svg+xml";
+  if (buf.length >= 2 && buf[0] === 0x42 && buf[1] === 0x4d) return "image/bmp";
+  return extMime(filePath);
 }
 
 // ---------------------------------------------------------------- HTML 安全
@@ -173,13 +264,21 @@ function extMime(filePath) {
 }
 
 // ---------------------------------------------------------------- 布局工具（生成 SVG 常量）
-// 文字排版：根据中文字符数近似估算宽度（一个汉字≈1.0em，拉丁≈0.55em）
+// 文字排版：按字符近似估算宽度（汉字/全角≈1.0em，拉丁≈0.55em，常用符号/emoji≈全宽）
 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;
+    // 全宽判定：汉字/全角（≥0x2E80）按 1em；
+    // 常用符号/emoji 实际渲染接近全宽，也必须按 1em 估——按半宽会撑破文本框被 overflow:hidden 裁掉
+    // （SKILL.md 示例 --label "✅ 修复后" 就含这类字符）：
+    //   - 箭头/数学/杂项符号等 0x2190-0x2BFF（含 ✅ U+2705、⚠ U+26A0、→ U+2192）
+    //   - 0x1F300+ 各 Emoji 区段
+    // 拉丁/数字/标点（<0x2190）才按半宽 0.55em。
+    const fullWidth =
+      code >= 0x2e80 || (code >= 0x2190 && code <= 0x2bff) || code >= 0x1f300;
+    const width = fullWidth ? fontSize : fontSize * 0.55;
     w += width;
   }
   return { width: Math.ceil(w) + 2 * fontSize, height: Math.ceil(fontSize * 1.7) };
@@ -197,20 +296,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 +326,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" },
@@ -253,12 +358,23 @@ function buildHtml({
         break;
       }
     }
-    if (!slot) slot = cands[0];
+    // 目标靠近页面顶部/底部且文本较宽时，四个候选可能全部越界。此时不能直接丢出越界的 cands[0]
+    // （body overflow:hidden + 固定画布会把越界部分裁掉，文本框和箭头一起看不见——目标在首屏是最常见场景）。
+    // 兜底：取 up 候选并把 bx/by clamp 进【画布】（W×H，允许压到 margin 留白区，但绝不越出画布）。
+    // ⚠️ clamp 上界用画布尺寸 W/H 而非图片区（margin+imageW）：文本框比图片还宽时，
+    //    用图片区上界 margin+imageW-bw 会算出负值，clamp 后仍越界；用 W-bw 保证至少放进画布。
+    //    bw 比画布还宽的极端情况（超长文本），上界取 0，框左缘贴画布左缘，文字溢出由画布裁，但框和箭头至少可见。
+    if (!slot) {
+      const bx0 = cands[0].bx, by0 = cands[0].by;
+      const bxMax = Math.max(0, W - bw);
+      const byMax = Math.max(0, H - bh);
+      slot = { ...cands[0], bx: Math.min(Math.max(0, bx0), bxMax), by: Math.min(Math.max(0, by0), byMax) };
+    }
 
     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 +383,7 @@ function buildHtml({
           vector-effect="non-scaling-stroke" />`);
     }
 
-    // 文本框
+    // 文本框：白底固定深色文字（避免默认红字 + 白底 = 白字白底不可读）
     if (hasText) {
       const rx = Math.max(6, a.lw * 1.5);
       parts.push(`
@@ -279,8 +395,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>`);
     }
 
     // 箭头：文本框中心 → 目标中心
@@ -289,9 +405,14 @@ function buildHtml({
     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));
+    // ⚠️ 只在 hasText 时画箭头：text 是可选字段（{x,y,w,h} 只想画高亮框的用法），
+    //    无 text 时 bw=bh=0、slot 落在目标中心，此时画箭头等于从目标中心画一条无来源说明的线，
+    //    且 slot.name 兜底为 "up" 会让箭头起点「避开文本框」的偏移逻辑指向一个不存在的框，
+    //    生成无标签来源的误导性标注。因此无 text 时只画高亮框、不画箭头。
+    if (hasText && len > 1) {
+      // 起点避开文本框：上/下方位沿垂直外移 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 +432,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 +484,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";
-  }
 }
 
 // ---------------------------------------------------------------- 主流程
@@ -404,18 +522,86 @@ function main() {
       console.error("❌ --json 必须是标注数组");
       process.exit(1);
     }
+    // ⚠️ 校验元素类型：--json '[null]' 或含字符串/数字元素时，后面 a.x/a.y 会抛未捕获 TypeError（英文堆栈），
+    //    与其他参数错误的「❌ 中文提示 + exit 1」风格不一致。必须在换算前统一拦截。
+    if (annotations.some((a) => a === null || typeof a !== "object")) {
+      console.error("❌ --json 数组的每个元素都必须是对象（{x,y,...}），不能含 null 或非对象元素");
+      process.exit(1);
+    }
   }
 
   // 坐标换算：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;
+  // ⚠️ --viewport 被 parseArgs 置为 true（后面紧跟另一个 --xxx 或位于末尾 = 没带值）时，
+  //    必须报错而不是静默跳过换算——否则坐标按设备像素走、用户却以为按视口换算了，标注整体错位且无任何提示。
+  if (keyed.viewport === true) {
+    console.error('❌ --viewport 必须显式传值 "cssW,cssH"（如 --viewport "1440,900"），当前为无值参数');
+    process.exit(1);
+  }
+  // ⚠️ --fullpage 与 --viewport 是互斥的两种换算模式（DPR 等比 vs 截图/视口比例），同传时按谁走都会让另一方的坐标全歪且无提示。
+  //    必须在代码里 exit 1，不能靠文档约束（SKILL.md 里虽强调"禁止 fullPage 用 --viewport"，但使用者仍可能同传）。
+  if (keyed.fullpage && keyed.viewport && keyed.viewport !== true) {
+    console.error("❌ --fullpage 与 --viewport 互斥，不能同时使用");
+    process.exit(1);
+  }
+  // ⚠️ --dpr 只对 --fullpage 模式生效（整页 CSS 坐标按 DPR 等比缩放）。默认/--viewport 模式下坐标已按
+  //    设备像素或「截图宽/视口宽」换算，--dpr 不参与计算；此时传 --dpr 会被静默忽略、scale 保持 1，
+  //    标注整体按 1 倍画出来且无任何提示——正是本脚本要根治的「静默错位」。与其他参数校验一致 fail-fast，
+  //    不能靠文档约束（SKILL.md 里 --fullpage --dpr N 连写，使用者漏打 --fullpage 就会命中）。
+  if (keyed.dpr !== undefined && !keyed.fullpage) {
+    console.error("❌ --dpr 只在 --fullpage 模式下生效；非 fullPage 模式坐标已按设备像素/视口换算，无需 --dpr。请移除 --dpr 或补上 --fullpage。");
+    process.exit(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);
+    }
+  }
+  // 必填坐标校验：x/y 是标注定位的必填字段，缺失/非法值时若静默归零会把箭头/框画到左上角且无任何提示
+  // （正是本脚本要根治的「静默错位」）。w/h 是可选（缺省 0 = 只画点不画框），不在此列。
+  for (const a of annotations) {
+    for (const f of ["x", "y"]) {
+      const v = a[f];
+      if (v === undefined || v === null || v === "" || v === true || !Number.isFinite(Number(v))) {
+        console.error(
+          `❌ 标注数组第 ${annotations.indexOf(a) + 1} 项的 "${f}" 缺失或非法（收到: ${JSON.stringify(v)}），x/y 必须是有穷数字`,
+        );
+        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,
@@ -427,7 +613,8 @@ function main() {
   const marginFrac = num(keyed["margin-frac"], 0.05);
   const html = buildHtml({
     imagePath,
-    imageMime: extMime(imagePath),
+    // MIME 由文件内容魔数决定而非扩展名，避免「JPEG 内容误命名 .png」生成 data:image/png;base64 渲染异常
+    imageMime: detectMime(buf, imagePath),
     imageW,
     imageH,
     annotations,
@@ -438,7 +625,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/数据库）必须走可视化验证；只有带不动又不属于上面两类的，才需要向用户说明并请用户决定