visual-debug 用于诊断现有实现与已捕获参考证据之间的差异，进行结构、AE、DSSIM、运行时和过渡检查。适用前提是参考与实现证据均已存在；缺少基线证据应转交 ui-capture，实现、重生成与完整克隆编排应转交 ui-reverse-engineering 或当前调用方。
诊断结果返回失败产物、选择器或区域、可能根因、建议修复及精确验证命令。除非明确委托修复，源码编辑由调用方负责。存在 brief/WORKER_BRIEF.md 或 evidence-pack.json 时应先读取，再按失败热点读取所需摘要与下钻产物。
常规比较不直接读取 ref/impl 图像，先看摘要与 AE/SSIM 工具；失败位置运行 auto-diagnose.sh，仅当自动诊断无果时才读差异图。迭代期间固定参考，首次完整捕获后使用冻结参考裁剪（RECATCH_REF=0），实现编辑后须生成新实现证据再判断。
证据含 window.scrollTo、scrollYProgress、setTimeout、velocity、滚动停止守卫或 ScrollTrigger pin/scrub 时，需滚动状态机证明初始→激活/展开→稳定/返回。不得削弱阈值或掩盖区域来通过失败，须先分类为实现、参考/捕获、检查器或未知。
每个浏览器会话结束须关闭：agent-browser --session <session-name> close，禁止 close --all。会话开始检查 agent-browser、ffmpeg、dssim、imagemagick 等依赖，缺失时停止并提示引导命令，不自动执行远程安装器。脚本从活动插件或检出目录解析，可用 VISUAL_DEBUG_SCRIPTS_DIR 或 PLUGIN_ROOT 指定。
完成需三轴一致：像素 AE 每图 ≤500，感知 SSIM 每帧 ≥0.995，语义由委托的 Phase E 审查通过或明确批准已知差异；计算样式比较 0 不匹配。AE=500 允许抗锯齿差异，动态内容仅经文档化动态路径可用 AE=2000。阈值变更须用户明确批准并记录理由。Phase E 为完整验证必需，审查每个 ref/impl 位置，委托给宿主原生 visual-debug-reviewer 或同契约的通用委托工作者，仅裁决表返回协调者。只有三轴一致且所有必需行均已测量才返回 PASS；FAIL、INCOMPLETE、UNMEASURED、过期证据或缺失产物均视为未完成。