frontend-visual-qa

前端视觉 QA

审核用户实际能看到的界面。将构建成功、DOM 中存在相关内容以及未经检查的截图文件视为辅助信号，而非视觉证据。

默认仅执行审核。除非用户明确要求修复或更改 UI，否则不要编辑实现、添加测试、安装依赖或更新快照。获准修复源代码，不代表获准重建、重启或部署任何目标。

范围与路由

仅在已有渲染产物后使用此技能。选择能够覆盖请求的最小审核配置：

• 核心视觉 — 构图、排版、间距、换行、裁切、图片；
• 响应式 — 断点、重排、移动端替代方案、滚动归属；
• 状态与流程 — 条件分支、状态转换、恢复、路由；
• 浏览器输出 — 下载、分享、剪贴板、弹窗、文件对话框、打印、PDF；
• 原生外壳 — Electron 或混合应用的界面、权限、拖拽区域、IPC UI；
• 页面契约 — 仪表板/管理后台、落地页/演示文稿、设计系统产物、浏览器工具/游戏、地图/GIS 或审核工具；
• 参考一致性 — 与指定截图、产品或级别进行比较；
• 数据可视化 — 图表层级、设计令牌、语义和无障碍性。

针对特定任务/对象链接交接，选择目标对应的状态与流程配置；标题重复时，也要确认权威机器及运行/作业身份。将审核范围限制在承诺的目标内。

对于转换为 Markdown 的网站/文档，或在 Obsidian 或其他指定阅读器中查看的图文转录/笔记，在评判图示可读性之前，先加载 references/markdown-reader-handoff.md。 将完整源图与其实际文档阅读画布进行比较，包括 HTML 说明文字和 SVG/CSS 依赖。对于过大的嵌入图片，使用其中的显示尺寸方案，并先结合相邻文本测试一张有代表性的长图，再将相同布局应用到文档。

仅当改动涉及的界面范围较广或用户要求进行全面发布审核时，才组合多个配置。不要为了局部换行审核而强行检查无关的身份验证、地图、导出和原生外壳。

按阶段使用相邻技能：

• 使用 ui-designer、frontend-design 或其他设计技能来确定或创建视觉方向，或从参考截图中提取设计系统 — 此技能审核已有渲染产物，不负责推导设计方向。
• 使用此技能测试已渲染的结果，不要用来调试未产生可见缺陷的非视觉代码（逻辑、数据或后端正确性）。
• 使用 qa-expert 制定完整测试策略、缺陷计划和发布指标。
• 仅当渲染后的视觉证据是更广泛 QA 门禁的一部分时，才同时使用此技能和 qa-expert。
• 此技能负责审核渲染后信息层级及几何布局：持久标签、说明和重复上下文是否有助于执行者完成任务，还是挤占了任务空间。不要将此类问题简单归为文案润色。领域事实的准确性、术语和说服力仍需相应的内容或领域专家审核；渲染审核无法认证这些主张。

必需结果

接管目标前的准备

执行审计的人员应先确定最新的用户约定和特定阶段所需的 Skills，然后再操作共享浏览器或设备。请从实际条目中加载此任务明确要求的 Skills。对于数值分析或图表，还应使用 data-visualization-discipline；对于 Android 控制，应在此视觉审计之外同时使用 android-automation。只有在用户提出要求或任务涉及设计变更时，才添加设计 Skill。仅控制设备并不能提供视觉或业务验收标准。

阅读所选当前 Skill 的文本及受影响的参考资料，然后明确参与者的问题、规范目标、受影响的状态以及可观测的答案。目录条目、记住的章节标签或上下文压缩摘要只能用作定位信息，不能代替已加载的指令。仍保留在上下文中的未更改文本可以重复使用；上下文压缩后，只需重新加载所需指令，无需重新执行已完成的测试。

在现有范围约定中记录此准备工作：所需能力、已确定的负责人／条目，以及该能力提供的验收证据。缺少指令时，依赖该指令的判断应标记为未验证；继续执行已获授权的独立只读工作。应在短暂的共享资源使用窗口开始前完成工具／依赖准备，并在窗口结束时遵循目标控制负责人的恢复约定。这些都是审计人员的操作，并不表示存在自动加载 Skill 的防护机制。

必须提供以下所有内容：

1. 一份范围约定，注明制品、参与者、工作、目标类型和规范目标身份、条件状态、视口、受影响的用户旅程、参考资料／SSOT 以及授权情况。
2. 一项验证状态：已验证、部分验证或受阻。
3. 与可见证据、影响、状态、视口和复现步骤相关联的发现。
4. 实际执行过的事项及仍未验证事项的清单。
5. 当声明了时效性或部署情况时，单独提供交付状态及其身份依据；当明确授权修改目标时，提供修改前后的身份、针对同一目标／状态／视口的复测，以及回归防护。

切勿将用户的真实目标降级为最容易收集证据的内容。

工作流

对于非简单审计，请跟踪此检查清单：

- [ ] 1. 确定审计约定和授权
- [ ] 2. 选择所需证据级别和规范测试框架
- [ ] 3. 验证目标、状态、数据、视口以及所声明的时效性
- [ ] 4. 捕获并检查宏观、局部和响应式证据
- [ ] 5. 执行受影响的用户旅程并检查接收方输出
- [ ] 6. 报告发现；仅在获授权时修复并重新运行

1. 确立审计约定

阅读项目说明、设计系统 SSOT、令牌、已批准的资源、启动器/测试 SOP，以及变更的代码。然后写下一份可证伪的约定：

产物/页面类型：
角色及任务：
目标类型 + 规范身份：
  Web = 精确的浏览器内 URL（包括查询参数/片段）+ 指定环境
  单个文件/图像 = 规范路径 + 内容哈希 + 渲染方案
  多资源产物 = 规范入口 + 依赖项/清单摘要 + 渲染器
  原生应用 = 已安装产物指纹 + 构建版本/版本号 + 进程/窗口 + 渲染路由
条件状态：
交付身份/状态，仅在声称内容新鲜/已部署时填写：
参考或设计系统 SSOT：
相关视口/设备矩阵：
预期投影/画布尺寸（如有）：
受影响的交互和输出：
审计配置：
源码授权：仅审计 | 修复并验证
交互/操作权限：只读导航 | 对夹具安全的状态进行更改 | <指定操作>
目标修改权限：无 | 隔离诊断 | 本地目标 | 部署 <指定环境>
反目标 / 绝不能变成：
通过条件：

先明确正确的状态，再判断像素。未登录、引导流程、空状态、权限拒绝、已播种数据、已填充数据、加载中和功能标志分支，可能看起来像不同的产品。错误分支的干净截图无效。在授权范围内时，已登录但无角色是一个独立分支；未登录或权限完备状态的证据不能替代它。

以角色的任务作为成功目标。当用户需要判断严重程度、完成审核或从错误中恢复时，“图表存在”或“标签页可以切换”并不足够。

将用户需求与实现分开固定下来。对杂乱、重复说明或空间浪费的抱怨，指出的是一类失败，而不只是圈出的元素。应在声明的完整范围内检查这一类问题。候选方案失败后，不要悄悄将审查范围缩小到最后一张截图的矩形区域，也不要把需求改写成“任务仍然可以完成”。

当通过条件指定了视觉参考——截图、另一款产品的页面，或“让我们的页面看起来和他们的一样”——请在判断实现之前，以及在“修复并验证”模式下编写下一轮修复之前，先加载 references/reference-parity-decomposition.md。这不会扩大本技能在实现后的范围：拆解是审计的第一步，应用于始终已存在的参考产物；每一轮一致性修复都是在本技能“修复并验证”权限范围内进行的实现。如果同一请求还需要从零创建视觉方向，这部分仍属于设计技能——将已完成的清单移交过去，而不是在那里重新推导。约定的第一项交付物是参考内容经过测量的结构清单，一致性判定则是针对该清单逐项关系的差异。每一轮只修复用户最新截图中抱怨的差异，只会通过耗尽用户耐心来收敛——该文件拆解了一个真实的五轮案例。它还涵盖了在清单之外持续存在的两个陷阱：你自己的几何断言对于一致性审查属于 D 级（它们编码了你对参考的解读，误读时仍会通过）；用户否决某种效果（例如“绝不裁剪图像”），追责的应是迫使该效果出现的结构前提，而不是决定其具体表现形式的参数。将报告级数据页面与分级参考进行比较时，该文件与 references/data_viz_tier_and_token_audit.md 共同划分工作：拆解规范页面结构，层级基准规范数据呈现参数——两者都要加载。

2. 选择证据级别

根据主张选择所需的最高证据级别：

级别	证据	可支持的主张
A	通过用户操作流程驱动的真实可见 Chrome／浏览器窗口或规范的原生应用窗口	浏览器／操作系统界面、下载、剪贴板、弹出窗口拦截、文件选择器／对话框、打印预览、权限、原生外壳、实际可见窗口相关问题
B	同一状态下的浏览器开发者工具，或使用代表性数据运行的项目 E2E／Playwright 测试	DOM 几何尺寸、路由、焦点、覆盖层、交互状态、可重复的响应式行为
C	通过捆绑脚本进行的新鲜无头机械检查	溢出、换行、图像、基本布局启发式检查、候选截图
D	源码、lint、构建、单元测试或静态 DOM 推理	仅用于假设和回归支持

不得将较低级别的证据提升为更强的结论：

• 从未打开过的截图路径不具备视觉证据价值。
• 新鲜的无头空状态无法验证用户填充数据后的状态。
• 渲染器 URL 无法验证 Electron／原生外壳。
• 处理程序调用无法验证 Chrome 打印预览、弹出窗口或下载界面。
• 指针光标、悬停样式或“点击以执行 X”徽标无法证明点击会产生任何效果：没有可用处理程序的提示标识属于无效点击，只有触发该操作（步骤 5）才能确认。
• 设备模拟只是近似方案；当设备特定行为至关重要时，应使用真实设备。

如果所需的 A 级界面不可用，或 GUI 正由另一会话占用，则只能继续使用不会假装能够取代它的证据。报告确切缺失的证据，并将受影响的主张标记为部分验证或受阻。

3. 证明目标、状态和视口

启动任何内容之前，先读取项目权威状态。仅当每项副作用均符合其各自权限时，才使用规范启动器：生命周期权限涵盖重建／重启／部署，而种子数据或事务数据变更则需要交互／操作权限。切勿由一项权限推断另一项。经授权的隔离诊断服务必须标记为非目标。

在浏览器内存中保留完整的 Web URL，但只持久化经过删减的结构化 URL，以及稳定摘要／查询键列表。单个文件／图像需记录路径、内容哈希和渲染器；多个资源组成的 HTML／演示文稿则需要权威资源清单或依赖闭包摘要。原生 UI 需要已安装构件的指纹／代码签名，以及构建、进程／窗口和渲染器路由信息。渲染器开发 URL 仅用于诊断。将原始截图视为本地临时敏感证据；仅分享／提交最少量的删减衍生内容。

当主张涉及源码更改、新鲜度或部署时，还需补全从源码到目标的链路：

1. 从目标的发布契约获取预期身份；除非目标本应运行 HEAD，否则不要使用本地 HEAD；
2. 读取项目权威的运行时构建／镜像／发布状态；
3. 将浏览器／数据平面证据映射到预期构件——除非预期清单对其进行了映射，否则仅凭带哈希的文件名无法证明任何内容；
4. 证明目标路由、操作者、数据、条件状态和视口。

对于可通过 GET 读取的 Web 资源，请遵循 交付验证，并在声称部署匹配之前运行捆绑的清单比对。还需包含单独提供服务的嵌入组件。其结果仅能证明所提供的身份检查；像素检查和实际用户操作流程仍须作为独立关卡。 没有身份映射，就无法证实新鲜度或部署声明；若两者都未声明，则使用不适用。当前像素仍可独立验证。 如果源端修复与目标端不同，其关闭状态仍为部分完成——源端已修复，验证目标已过时。仅审计工作会继续检查实时目标，不做任何修改。仅有源端修复权限并不允许对目标执行生命周期操作；如果另行获得目标修改授权，则应在操作前记录身份，仅运行指定的规范生命周期，再次验证身份，并重复相同的目标、状态和视口。如果生命周期的归属尚未明确，则该修改路径为受阻。

优先使用禁用缓存的重新加载或新上下文。仅当项目声明查询参数在语义上无影响时，才更改查询参数；保留现有查询参数和片段，并在原始 URL 上运行最终取证。详细的页面状态探测、file:// 边界、缓存规则、重定向和视口比较见 references/browser-driving-and-observation-traps.md §2–§5。在进行 CSS 诊断前，记录最终 URL 和尺寸；完成后恢复用户预期的视口。

对于加载速度声明，测量前先阅读 §2 中的性能比较边界。

对于隐藏页面轮询，测试前先阅读该参考文档中的验证轮询是否会在真正隐藏的页面中停止操作指南；媒体焦点模拟无法证明该策略。

对于脚本化扫描，首先使用以下任一方式证明目标状态可复现：

• 项目的 fixture/storage-state/setup 路径；
• 通过重复使用 --require 标志传入一个或多个必需的已渲染标记；
• 刷新后会恢复相同状态的直接深层链接。

否则，将运行标记为新会话诊断，而非通过。

如果审计必须登录 SPA、脚本化登录失败或跳回身份验证路由，或者目标运行在 shell 代理后的 localhost 上，则在提交任何登录/网络问题前，先阅读 references/auth-session-and-environment-traps.md ——这些故障通常是驱动测试工具或环境伪装成了产品缺陷。

身份验证后，不要根据记忆中的侧边栏标签进行操作，也不要假定目标导航已经挂载。记录最终 URL、简短的可见正文摘录，以及当前可用的链接/按钮；然后遵循已渲染的落地页实际提供的规范入口。如果预期的定位器不存在，在目标路由/状态得到独立验证之前，应优先怀疑导航约定或测试工具发生偏移。

4. 捕获并检查已渲染证据

先捕获整个可见布局，再放大查看缺陷，然后捕获受影响的组件、相关响应式宽度和较低页面区域。使用图像查看器打开每张截图并记录观察结果；未经检查的文件不构成证据。

在信任捕获结果前先校准捕获过程。通过 DOM 几何信息排除看似裁切的情况，在支持时固定设备缩放比例，等待字体、网络和动画稳定，并使用接收方实际查看时所用的引擎。DOM 证据用于解释像素，不能替代像素证据。

完整的捕获校准协议和最低检查集见 references/browser-driving-and-observation-traps.md §12。无头捕获特有的范围和设备模拟陷阱，已在同一参考文档的 §4–§5 中列出。 在使用水平滚轮输入阅读内容溢出的 <pre> 之前，先加载 最新的输入目标检查，并检查受影响的文本位置，而不能仅凭滚动移动就下结论。 在判断滚轮驱动的平移／缩放灵敏度之前，加载同一参考文档中的 滚轮请求不等于浏览器收到的滚轮事件 配方；将移动情况与实际收到的输入进行比较，而不是与测试框架发出的请求进行比较。

加载 references/history-derived-checklist.md，查看核心视觉／响应式缺陷目录和基于标准的检查项。 对于构图或信息密度审查，包括对 AI 生成的 UI 或文案的投诉，请执行其中的 布局前先判断信息是否必要 检查，并在调整换行前选用匹配的 成熟方法。在宣布渲染后的 UI 已可发布之前，请完成该检查中的辅助文案清单及其在声明范围内的处置，包括共享文本和受影响的条件状态。 覆盖不完整或与任务相关的解释尚未解决，都会使发布声明只能算部分完成；几何检查通过或未发现禁用词，都无法消除这些问题。扫描中的 attentionInventory 可检查可见文本总体及完全重复项；请根据任务审查全部文本，而不只是重复候选项。清单覆盖完整，并不能证明内容确有必要。

如果某个出版物通过了本地检查，但发现或阅读体验仍显得杂乱，请使用出版物体验路径案例，通过失败案例和健康对照来校准对整体路径的判断。这些合成案例用于补充现有的必要性检查，而不是提供风格评分。

有些缺陷不会产生任何诊断：全局重置样式优先于组件自身样式；库重命名内部 DOM 类，导致整组规则都无法匹配；声明了字体系列却未随项目提供；将几何属性写入源代码扫描无法识别的主题配置；新设计令牌复用了文件中已占用的名称；属性因规则未设置其所依赖的布局模式而无法生效；以及每个元素都符合规范，整体看起来却仍像是“没有设计系统”。源代码审查、类型检查和几何断言在结构上都无法检测这些问题——产物有效，却不起作用。当页面看起来廉价，但所有关卡都显示通过时，这种组合就是典型信号。加载 references/silent-degradation-and-evidence.md，了解各类问题的检测方法，并以机械方式检查最容易发现的两类问题：

node <skill-root>/scripts/silent_degradation_probe.mjs font \
  --url http://127.0.0.1:5173/ --weight 700 \
  --family "Brand Sans" --family "Fallback Sans"

node <skill-root>/scripts/silent_degradation_probe.mjs class \
  --css path/to/bridge.css --library-css node_modules/<lib>/dist/<lib>.css

传入字体栈中的所有字体系列，以及页面实际使用的字重。请准确解读全部五种判定结果；平台通用字体属于正常情况，只有“仅由宿主提供”和“资源损坏”才是缺陷。参考文档解释了为什么计算所得的字体系列名称、document.fonts.check()、未加载的候选字体以及仅使用 CJK 字符的宽度探测，都会导致错误结论。

请在经过审计的项目中运行捆绑的扫描工具，以便解析项目现有的 Playwright 依赖：

node <skill-root>/scripts/visual_layout_audit.mjs \
  --url 'http://127.0.0.1:5173/?state=fixture#/ready' \
  --page-type app \
  --require "Expected state marker" \
  --screenshot-sections

对于本地 HTML 产物，请使用 --file <artifact.html>。运行 node /scripts/visual_layout_audit.mjs --help 查看所有标志。对于尺寸受限的画布，请传入一个或多个精确视口；自定义视口会替换默认的响应式矩阵： node /scripts/visual_layout_audit.mjs
--file deck.html --page-type deck --viewport 1920x1080
--screenshot-sections

对于证据依赖首屏以下封面或缩略图的长页面，请添加 --scroll-visible-media。该选项会在截图前访问已渲染的媒体行，以便启动延迟加载，同时排除 CSS 隐藏的响应式替代内容。未使用该选项时，屏幕外的延迟加载媒体会报告为覆盖范围尚未确认，而不是损坏的资源。无论哪种模式，都请检查截图：“未请求”“仍在加载”和“请求已完成但无法解码”是不同的状态。

仅当当前产品规范明确禁止项目专属的过时名称或渲染文本时，才重复使用 --forbid 模式。不要将一般审美偏好编码为禁止正则表达式。

脚本的退出状态：

• 无机械错误时为 0；
• 仍有错误，或使用 --fail-on-warning 时仍有警告，为 1；
• 输入无效、缺少先决条件或运行时／设置失败时为 2。

脚本会将截图和 JSON 报告写入唯一的临时运行目录；显式指定的 --out 必须是新目录或空目录。这是 Level C 扫描，并非最终判定。切勿提交／分享原始证据：报告会对渲染标签进行哈希处理并编辑从目标内容派生的值，而衍生截图需要遮盖可识别的像素。其目标字符串指纹和单文件字节哈希无法计算多资源闭包／原生身份；请提供项目规范。

不要仅为运行扫描而修改受审计项目。请沿用项目已有的包管理器和规范的浏览器测试框架。如果没有 Playwright，请继续使用可用的 Level A/B 证据，并报告省略了 Level C 扫描；只有在获准更改依赖时才安装依赖。

通过 --header-env "Name: ENV_NAME" 传递标头；argv 仅包含标头／环境变量名称，绝不包含值。原始 --header 已禁用。值仅用于目标源；除非明确指定为受信任的自签名源，否则始终启用 TLS。

请在已提供 Playwright 的项目中运行探针回归测试：

node --test <skill-root>/tests/test_silent_degradation_probe.mjs

5. 验证用户旅程与输出

对于已更改的数据绑定贡献视图或多项读取，在判定通过之前，先按关联的用户旅程契约检查有界窗口覆盖、可见贡献以及混合结果恢复。这些是审核员通过经授权的项目测试框架执行的操作，并非通用扫描强制执行的判定条件。

对于 UI 重构、类别拆分或导航更改，先应用 references/journey-and-page-contracts.md 中的 重构保真 方案。 从不可变的更改前版本推导受影响的用户旅程，然后在当前目标版本上验证；不能仅凭新的导航来界定哪些内容得以保留。 对于刷新、深层链接和返回检查，使用该参考文档中的 路由与可访问性 方案；如果产品承诺保留重复出现的项目，也要逐一检查。

可见标识不代表行为已得到验证——触发所有副作用符合明确操作授权的相关控件，确认响应，并将其余控件标记为未验证。 指针、悬停或按钮样式可能造成虚假的可操作感：处理程序可能缺失或已过时，但截图和看似合理的源代码仍能通过检查。只有实际执行 Level A/B 触发操作才能验证行为。优先检查后续添加的灯箱、缩略图网格和复制操作。断言最终状态，而非事件派发；在判定点击无效之前，排除事件委托、水合时序或可信手势限制（browser-driving-and-observation-traps.md 陷阱 1）。静默降级参考文档中描述了相反的故障：行为正常，却缺少可见提示。

仅验证相关的状态转换矩阵：

进入 -> 就绪 -> 活跃 -> 处理中 -> 成功/错误 -> 恢复 -> 就绪

在适用时，还要验证：

• 点击 -> URL/状态 -> 刷新 -> 深层链接 -> 前进/后退；
• 抽屉/模态框/弹出层的打开、焦点、背景交互、关闭及移动端行为；
• 触发前已启用观察的临时通知生命周期；
• 高级模式 -> 可见的当前模式和触发操作所属对象 -> 一步恢复默认设置；
• 提供方/模型/运行时状态 -> 所选配置和当前状态证据；
• 下载 -> 文件下载完成 -> 在接收端打开生成的文件；
• 分享 -> URL 已复制/已打开 -> 接收端状态已刷新；
• 文件选择器/对话框 -> 打开/取消/选择路径的可见行为 -> 应用状态已恢复；
• 打印/PDF -> 实际的 Chrome 预览 -> 页面内容非空；
• Electron/原生环境 -> 规范的应用进程/窗口 -> 原生控件和系统外壳。

如果审核包含状态转换、授权、模式、摘要到详情的展开、提供方/模型/运行时真实性、路由、临时状态、覆盖层、浏览器输出、原生外壳、落地页/演示文稿/浏览器工具/游戏产物、仪表板、设计系统产物、GIS/地图或审核工具，请加载 references/journey-and-page-contracts.md。

对于承诺提供原始证据的引用标记，针对实际文本、图像或 PDF 及其返回路径，执行该参考文档中的 引用来源检查。 对于已更改的长文档导航或来源侧边栏，还要使用其中的 长文档阅读位置 方案；首屏正确，并不能证明文档深处的同一控件也正常。

仅当涉及报告级数据页面、命名的层级/参考比较、图表令牌审核或分类调色板时，才加载 references/data_viz_tier_and_token_audit.md。

报告非简单审核结果之前，以疲惫用户的视角、不借助调试器上下文，重新走查主要路径。优先排查触发操作或模式归属不清、隐藏的恢复默认方式、受阻的恢复流程、误导性的运行时标签、原始机器语言、无法触达的控件、可避免的手动操作，以及会导致同类缺陷再次出现的保护措施缺失。这是一次证伪检查，不是将局部的纯视觉审核扩展到每种配置的借口。

6. 报告、修复并重新运行

每项外观问题都必须附上能展示该问题的像素证据。 看不到缺陷的读者无法判断它的影响，也无法核实问题是否属实。只截取受影响元素，并保留足以定位它的周边内容——整页截图无法证明一个 14px 的错位，而单靠文字描述（“按钮看起来很廉价”）无论多准确都无法采取行动。scripts/silent_degradation_probe.mjs shot 会为此截取一个元素及其周边留白。

以下规则决定证据能否经得起读者检验： 对比必须缩放匹配（将两个全宽区域并排放置会导致画面缩小，讨论中的 3px 差异也会随之消失——应将两者都裁剪到相同宽度的同一组件）；尺寸必须以 CSS px 为单位报告，绝不可使用设备像素（DPR-2 截图的像素数量是两倍，将其误报为页面高度曾导致“有 20 个屏幕那么长”这一错误结论）；修复前拍摄的截图必须标注其展示的提交版本，不能当作当前状态呈现；基于代码计数而非截图的发现必须明确标注，让读者知道清单中哪些内容的证据力度相同。

将影响与类别分开。项目有严重程度分类体系时，遵循该体系；否则使用：

• 阻断级 — 成功状态有误、操作具有破坏性或误导性，或者无法在没有安全替代方案的情况下完成主要流程；
• 重大 — 核心任务、接收方输出、恢复流程、路由或关键控件无法使用；
• 中等 — 理解或操作受到实质影响，但存在安全替代方案；
• 轻微 — 对任务影响很小的润色问题。

使用布局、响应式、状态、路由、无障碍、浏览器输出、原生外壳、意图或审美等类别。审美和意图不属于严重程度级别。

使用以下精简格式报告：

当前渲染状态：已验证 | 部分验证 | 受阻
交付状态：匹配 | 不匹配 | 无法证明 | 不适用
修复闭环状态：已验证 | 部分验证 | 受阻 | 不适用
目标：<Web：脱敏后的请求目标/最终目标 + 目标字符串指纹/查询键/重定向 | 单文件/图像：脱敏后的规范路径 + 内容哈希 + 渲染器 | 多资源：入口 + 权威清单/依赖闭包摘要 + 渲染器 | 原生：已安装制品指纹/签名 + 构建版本 + 进程/窗口 + 渲染器路由>
环境：<已验证名称或未验证>
交付身份：<预期值；观察到的前后值；证据>
操作者/任务；参考/通过条件；受影响流程：
授权：<来源范围；交互/操作范围；目标变更范围>
范围：<状态、视口、配置>

发现：
- 重大 · 浏览器输出 · PDF 操作 · 桌面端
  影响/状态/视口/复现步骤：
  证据文件/裁剪图：
  证据：点击可见控件后打开了 about:blank；打印预览没有页面。
  修复：使用可在用户手势下安全运行的打印方式，并重新测试接收方预览。

参考对齐清单（仅限对齐审计）：
- <关系 -> 匹配 | 有意偏离（推导依据） | 尚未完成，每项一行>

已验证：
- <流程/状态/视口 + 具体证据>

未验证：
- <缺失的界面/证据及原因>

在仅审计模式下，继续只读收集证据，不得修改源或目标。在修复并验证模式下：

1. 修复根本原因，而不是掩盖溢出、缩小所有文字、通过更改选择器来规避检测，或移除功能。
2. 在提交共享视觉令牌之前，先实时预览各种主观方案。
3. 仅在目标具有单独命名的修改权限时才更新目标；否则，报告“源已修复／目标未经验证”，不要扩大范围。
4. 重新检查同一个规范目标，并再次证明其身份、路由、状态、视口、操作流程和接收方输出。
5. 添加或更新能够捕获已确认故障类别的最小回归防护。

这些做法可避免修复过程自身制造缺陷——每种情况都确实发生过：

• 在缺陷仍存在时截取“修复前”的画面。 重建后，缺陷可能无法复现，此时结项报告就只能声称有所改进。修复后截图应使用完全相同的裁剪窗口，这样前后两张图只相差一个变量。
• 引入新的共享名称前先执行 grep。 如果令牌名称取自文件中已经用过的词（rail、bar、card），它会因定义顺序不同而被静默覆盖或覆盖其他定义，从而同时改变两个子系统（静默降级类别 1f）。
• 证明修复后的断言确实会失败。 重新引入缺陷，观察断言是否按预期幅度变红，然后再移除缺陷。如果断言在整个故障期间始终为绿，改写它也不会让它变成防护措施。

完成门槛

仅当满足以下条件时，才可将当前渲染状态判定为已验证：

• 已证明规范目标的类型／身份、最终目标、数据和操作者状态；
• 若声称内容是最新的，已确认交付内容匹配、不匹配或无法证明；否则标记为不适用；
• 报告中引用的每张截图都已打开并检查；
• 已覆盖相关视口和较下方的页面内容；
• 已按要求的证据级别测试受影响的交互和输出；
• 没有尚未解决且与检查结论相矛盾的阻塞级／重大问题；
• 已满足所有明确的通过条件，包括布局／信息密度或发布准备度相关的信息必要性要求；将违规称为中等、轻微、审美问题或“仍可使用”，都不能凌驾于用户要求之上；
• 已明确说明剩余限制。

只有在授权修复针对同一规范目标／状态／视口完成复查后，才能将修复闭环状态判定为已验证；否则应使用“部分完成”或“受阻”。

否则，报告“部分完成”或“受阻”。如果现有 Agent 工具能够执行检查，绝不要要求用户代为检查。

捆绑资源

• scripts/visual_layout_audit.mjs — 由 Playwright 驱动的机械化视口、布局和媒体状态巡检，并生成截图和 JSON 证据。
• scripts/attention_inventory.mjs — 巡检所用的文本／几何、重复内容和标签回声观测清单；不会认证其必要性。
• scripts/painted_text_probe.mjs — 巡检所用的垂直文本片段裁切检测；会报告已检查的覆盖范围，以及不受支持的裁切／滚动窗口。
• scripts/journey_input.mjs — 为已获授权的浏览器适配器提供非 TTY JSONL 输入；保留完整命令，并在失败时停止依赖该步骤的后续步骤。
• references/history-derived-checklist.md — 核心视觉／响应式缺陷目录，以及基于标准的检查项。
• references/journey-and-page-contracts.md — 状态、路由、叠加层、浏览器输出、原生外壳和页面类型契约。
• references/markdown-reader-handoff.md — 在实际 Markdown 阅读器中进行完整图像对比、诊断依赖项，以及经授权的可读图像修复。
• references/auth-session-and-environment-traps.md — 经身份验证的 SPA 登录与登录后导航的操作陷阱，以及环境劫持诊断（代理、CSP 入口、服务器日志交叉验证）。
• references/data_viz_tier_and_token_audit.md — 条件式数据可视化、参考等级、令牌和调色板审计。
• references/reference-parity-decomposition.md — 参考一致性分析配置的方法：在评判或修复之前，对指定参考进行实测结构清单；根据匹配标准逐项给出关系一致性判定；说明为何自行编写的断言在一致性分析中属于 D 级；分析否决前提；检查资源保真度；进行关系（而非数值）转换；以及报告前的确认清单。
• references/browser-driving-and-observation-traps.md — 审计人员自身的失败模式：误读点击、缓存过期、file:// 限制、视口截图与页面截图、调整宽度与设备模拟的区别、默认截图无法展示的状态、隐藏标签页的媒体延迟与轮询验收、虚拟时间导致的假阴性、--dump-dom 时序（以及正确执行标题编码交互探测的方法），还有 Range 服务器导致的媒体卡顿。在操作真实浏览器前，以及遇到意外观测结果时，请先阅读。
• evals/evals.json 和 evals/trigger-evals.json — 行为与路由回归用例；不包含在打包的运行时内容中。