visual-debug

视觉调试

通过结构、AE、DSSIM、运行时和过渡检查，对照捕获的参考证据诊断现有实现。

边界与返回约定

• 仅当参考和实现证据已存在时使用此技能。缺少基线证据时，转交给 ui-capture；实现、重新生成和完整克隆编排则交给 ui-reverse-engineering 或当前调用方。
• 诊断并返回失败的产物、选择器或区域、可能的根因、建议的修复方案，以及确切的验证命令。除非明确委托了修复，否则源代码修改由调用方负责。
• 如果存在 brief/WORKER_BRIEF.md 或 evidence-pack.json，请先阅读，然后只查看诊断失败热点所需的摘要和指定的深入分析产物。
• 如果修复工作已委托给你，请在修复循环前阅读 ../ui-reverse-engineering/iteration-discipline.md。委托和上下文压缩后，尝试历史与停止条件仍然有效。除非已获准修复共享工具，否则请提供复现步骤来报告检查器缺陷；切勿编辑已安装的缓存。
• 文本、尺寸、触发的事件或成功的构建相匹配，并不能证明外观或运动轨迹一致。请比较背景与前景、媒体适配方式，以及中间运动状态。

必须遵守的不变量

日常比较时不要读取 ref/impl 图像。 从摘要和 AE/SSIM 工具开始。对于失败的位置，运行 auto-diagnose.sh；仅当自动诊断未找到问题时，才读取差异图像。阶段 E 是必须遵守的例外，且必须在委托的上下文中运行。

迭代期间固定参考。动态网站的对照目标会不断变化：首次完成参考捕获后，使用冻结的参考裁剪（RECATCH_REF=0），直到证据确实过时。每次修改实现后，都要先生成新的实现证据，再判断修复是否有效。

当证据中包含 window.scrollTo、scrollYProgress、setTimeout、velocity、滚动停止逻辑周围的 guard ref，或 ScrollTrigger pin/scrub 时，必须提供滚动状态机的证明，展示 initial → active/expanded → settled/returned；仅凭单个终点帧并不足够。

不要通过降低阈值或遮罩未解释的区域来消除失败。编辑前，先将每个失败归类为实现、参考/捕获、检查器或未知问题。

成功、失败或中断时，都要关闭你打开的每个浏览器会话：

agent-browser --session <session-name> close

切勿使用 close --all；其他 Agent 可能拥有这些会话。

每个会话仅执行一次的启动步骤

检查所需工具。如果缺少任何工具，请停止并提供引导命令；不要自动执行远程安装程序。

miss=""
for c in agent-browser ffmpeg dssim; do command -v "$c" >/dev/null 2>&1 || miss+=" $c"; done
{ command -v magick >/dev/null 2>&1 || command -v convert >/dev/null 2>&1; } || miss+=" imagemagick"
if [ -n "$miss" ]; then
  printf 'Missing system deps:%s\nBootstrap:\n  tmp=$(mktemp) && curl -LsSf -o "$tmp" https://raw.githubusercontent.com/voidmatcha/ui-clone-skills/main/install.sh && bash "$tmp" && rm -f "$tmp"\n' "$miss"
  exit 1
fi

从当前激活的插件或检出目录解析脚本：

SCRIPTS_DIR="${VISUAL_DEBUG_SCRIPTS_DIR:-}"
if [ -z "$SCRIPTS_DIR" ]; then
  for root in "${PLUGIN_ROOT:-}" "${CODEX_PLUGIN_ROOT:-}" "${CLAUDE_PLUGIN_ROOT:-}" "${UI_CLONE_ROOT:-}" "$PWD" "$PWD/.." "$PWD/../.." "${INSTALL_DIR:-$HOME/.local/share/ui-clone-skills}"; do
    [ -n "$root" ] && [ -f "$root/skills/visual-debug/scripts/ae-compare.sh" ] && SCRIPTS_DIR=$(cd "$root/skills/visual-debug/scripts" && pwd) && break
  done
fi
[ -n "$SCRIPTS_DIR" ] || { echo "Set VISUAL_DEBUG_SCRIPTS_DIR or PLUGIN_ROOT" >&2; exit 1; }

以 bash "$SCRIPTS_DIR/<script>.sh" ... 的形式运行脚本。在没有 Skill 事件的主机（Codex）上，首次调用此类脚本会通知插件钩子：当前会话负责诊断。

将较大的浏览器 JSON 输出到文件；不要将其打印到模型上下文中。每条 agent-browser 命令都必须包含 --session <name>，每次 JS eval 都必须是 IIFE。

选择路径

1. 首先读取最小的现有摘要：sections/result.txt、pipeline-state.json、_summary.json、pixel-perfect-diff.json，或失败的门禁产物。
2. 在检查像素前，先运行成本较低的结构检查：实现界面扫描、stray-absolute-check.sh、相关的过渡/规范覆盖检查、显示/断点检查，然后运行范围较窄的 computed-diff.sh。
3. 使用 section-compare.sh 进行路由生成后的验证；使用 batch-scroll.sh 加 batch-compare.sh 进行独立的全面扫描。section 命令要求提供第四个 ref-dir 参数，因为门禁会读取其中的 sections/result.txt。
4. 仅使用 auto-diagnose.sh 诊断失败的行。根据症状，依次使用 tree-diff.sh、layout-tree-diff.sh、hover-tree-diff.sh 或 keyframes-diff.sh 深入检查未解决的失败。
5. 重新运行受影响的检查及其依赖闭包。迭代期间使用范围受限的验证或标准验证；规范收尾仍要求调用方执行完整的全面验证。

只有在需要确切命令、ONLY_IF_CHANGED、屏蔽规则或工具选择时，才阅读 tool-routing.md。只有需要领域选择器集合时，才阅读 common-selectors.md。只有需要独立的完整捕获/验证机制时，才阅读 verification.md。只有进入修复循环或分派 Phase E 时，才阅读 comparison-fix.md。不要一开始就加载所有参考资料。

三轴完成标准

每个位置都必须满足以下三个轴：

轴	工具	通过条件
像素	AE	每张图像的 AE ≤ 500
感知	DSSIM / 帧 SSIM	每帧 SSIM ≥ 0.995
语义	委派的 Phase E 审查	PASS，或明确批准已知差异

计算样式比较的结果必须为 0 个不匹配。AE=500 允许抗锯齿差异；动态内容仅可通过文档说明的动态路径使用 AE=2000。这些阈值属于约定，只有在用户明确批准并记录理由后才能更改。

完整验证必须执行 Phase E，并在 AE 和 DSSIM 检查后审查每个 ref/impl 位置。将其委派给宿主原生的 visual-debug-reviewer（如可用，则使用 Codex 原生子 Agent）；否则，使用遵循相同约定的通用委派工作线程。不要重试已被拒绝的角色名称。只有判定表会返回协调器。范围受限的诊断 Phase E 可以提前检查具有代表性的现有对，但其非规范产物不能替代最终的全位置审查。请参阅 comparison-fix.md。

只有在三个轴的结果一致且所有必需行都已测量时，才能返回 PASS。FAIL、INCOMPLETE、UNMEASURED、过期证据或缺失产物均表示尚未完成。随后继续调用方的流水线，完成实现和规范收尾。