ux-audit

UX Audit

像真实用户一样亲自走查在线 Web 应用。本审计流程以交互为先——包括打字、点击、发送、观察和截图。仅凭静态 DOM 扫描绝不可能得出判定。

判定状态（Verdict states）

审计结果最终必须且只能落在以下状态之一：

• Pass（通过） — Critical = 0，High = 0，所有硬性门槛均达标，交互清单（Interaction Manifest）填写完整。
• Conditional Pass（有条件通过） — Critical = 0，High = 0，所有硬性门槛均达标，但存在 Medium/Low 级别的缺陷。
• Fail（未通过） — 存在至少 1 个 Critical 或 High 级别的缺陷，或任意硬性门槛未达标。
• Incomplete（未完成） — 交互清单缺失必要记录、某个阶段未执行，或触发了审计元校验（audit-the-audit meta-check）告警（例如：清单时间戳间隔过于集中 < 0.5s、截图数量少于 2 × 路由数、控制台读取次数少于 1 × 路由数、详尽审计的 Phase 3 耗时 < 1 分钟）。即使眼看一切正常，也决不允许合规升级为 Pass。

若工作成果中未包含完整的交互清单，唯一合规的判定就是 Incomplete。“看着还行”绝不能算 Pass。时间戳异常的盲目 Pass 会被直接驳回——Agent 必须用真实的交互重新执行审计。

硬性门槛（Hard gates）

以下条件将直接导致审计判定为 Fail，且无法人工降级。

门槛指标	判定阈值	违规严重程度
走查期间的控制台错误（Console errors）	> 0	Critical
走查期间的控制台警告（Console warnings）	> 0	High
网络 5xx 响应	> 0	Critical
鉴权页面上的网络 403 / 404 响应	> 0	High
在任何测试视口/面板组合下发生布局崩溃	> 0	High
任意被审计页面上存在 axe-core Critical 违规	> 0	Critical
任意被审计页面上存在 axe-core Serious 违规	> 0	High
代表性路由上的 LCP（实用性能预算）	> 4.0s	High
代表性路由上的 CLS	> 0.25	High
代表性路由上的 INP	> 500ms	High
缺失必要的交互清单记录	不适用	Incomplete
清单各记录之间的时间间隔中位数 < 0.5s	不适用	Incomplete（未进行实际交互）

控制台警告至少属于 High 级别。5xx 错误自动归为 Critical 级别。不存在所谓的“Medium 级别控制台错误”——本 Skill 中根本没有这一分类。

axe-core 阈值按单页计算（任意单页违规 >1 即判定失败）。性能阈值在代表性路由上运行一次（按页测试属于过度测试）；实用性能预算标准设在远远优于系统崩溃、但比 CWV 严格标准稍宽松的合理区间。完整阈值与设计初衷详见 references/performance-budget.md。完整无障碍集成与严重程度映射见 references/a11y-automation.md。

已知噪点白名单（Allowlist for known noise）

部分应用存在一些已知但并非 Bug 的控制台/网络噪点（如 Sentry 日志、浏览器插件干扰、鉴权预检产生的预期 401 响应）。在 Phase 3 开始前请先读取审计配置文件并应用白名单。路径回退顺序：.jez/audit-config.yml → audit-config.yml → .audit/config.yml。命中白名单的记录仍会保留在交互清单中，但不会计入问题缺陷。判定区块会同时展示原始数量与白名单过滤后的数量：Console warnings: 3 (1 allowlisted, 2 reportable)。

未提供配置文件时的默认规则：每个控制台错误/警告均记为缺陷。格式、语义与页面覆盖配置详见 references/audit-config.md。

执行阶段（按顺序）

1. Pre-flight（准备阶段） — 锁定画像、浏览器工具配置、URL 确定、视口设置、能力测试
2. Discovery（探索阶段） — 站点地图梳理、任务流程清单、元素清单
3. Walkthrough（走查阶段） — 交互清单记录、流程深度体验、元素全覆盖测试、多面板压测、新用户视角观察、实时交互冒烟测试
4. Polish（打磨阶段） — 视觉细节排查、组件完美度核对表
5. Stress（压测阶段） — 11 大场景测试阵列 + 扩展压测方案
6. Verdict（判定阶段） — 判定状态输出、硬性门槛记分卡、完美度改进路线图、带复现步骤的发现清单
7. Fix-and-verify（修复与验证阶段） — 修复缺陷、重新走查受影响模块、更新审计报告

如果仅需 30 秒的上线前快测，请使用文件末尾的吃狗粮演练（Dogfood drill）——这是项目级规则，而非 Skill 触发。

Phase 1 — Pre-flight（准备阶段）

包含 5 道关卡，任意一道失败即刻终止。

1. Persona Lock（锁定用户画像）

在开展任何审计之前，必须先锁定用户画像。缺乏明确画像时，审计很容易沦为泛泛而谈的“看起来还行”。

请按以下优先级确定用户画像：

1. 命令行参数 — 用户显式提供（如 "ux audit as a busy insurance broker"）
2. 项目内置画像 — 读取已有的画像文件（回退链：.jez/audit-personas/<slug>.md → docs/personas/<slug>.md → personas/<slug>.md → .audit/personas/<slug>.md），以首次匹配到的为准。
3. 主动询问一次 — "这个应用的使用人群是谁？他们主要想完成什么任务？"

画像需包含：角色身份、技术熟练度、时间紧迫感、情绪状态、设备使用场景。优秀的画像能精准预测用户会忽略什么（如：“忙着接电话的前台接待员绝不会滚动到首屏下方”）。

在审计报告顶部写入所选画像即完成锁定。报告中的每个问题都必须站得住脚，符合该画像的视角。如果你发现自己产生了 “开发者应该知道这个…” 的念头——请立刻打住，你的目标用户不知道。

务必同时引入新用户视角（first-time-user lens）（强制要求，参见 Phase 3），即使显式指定的画像是其他角色，也要在所有多页功能上应用此视角。这是 AI / 内部工具最大的盲区。

详见 references/persona-lock.md 查看画像库与编写规范。

2. Browser tool（浏览器工具）

目标场景	使用工具	原因
需鉴权的应用	Chrome MCP	直接复用你真实登录的 Chrome 会话 — OAuth、Cookies、RBAC 权控开箱即用
公开网站	Playwright MCP	无需登录
两者皆不可用	终止	提示用户连接 Chrome MCP 或安装 Playwright

切勿在需鉴权应用中悄悄回退到全新的 Playwright 会话 — 进不去系统，审计就毫无意义。如果 Chrome MCP 未连接，请终止并提示："请打开 Chrome，在 Claude 扩展中点击 Connect，然后重试。"

工具命令详见 references/browser-tools.md。

3. URL（目标地址）

优先使用已部署/在线版本 — 拥有真实的鉴权、真实的时延、真实的 CDN 及 CORS 环境。探测顺序：读取项目 CLAUDE.md / README.md 中的 "URL" → 检查技术栈配置（wrangler.jsonc, vite.config.ts, next.config.js, config/database.yml, manage.py, .env APP_URL, wp-config.php）→ 检查端口 lsof -i :PORT（常见：5173 Vite, 3000 Next/Rails, 8000 Django/Laravel, 8787 Wrangler, 4321 Astro）→ 询问用户。各技术栈适配指南见 references/project-adaptation.md。仅在用户明确要求或功能未部署时使用本地环境。

4. Viewport（视口设置）

初始锁定窗口大小为 1440×900。Phase 3 的多面板压测会测试 375 / 768 / 1024 / 1280 / 1440 / 1920。切勿超过 2000px — 这会导致测试环境崩溃。

5. Capability tests（能力测试）

在开始任何走查前，先通过以下各一次调用验证工具链正常工作：

• 一次截图操作
• 一次控制台读取
• 一次网络请求盘点
• 一次元素选择器查询

若有任意一项失败，请在开启审计前先止血修复连接。对控制台输出视而不见的审计毫无价值。

Phase 2 — Discovery（探索阶段）

Sitemap crawl（站点地图爬取）

在审计任何页面前，先建立完整的页面清单。

1. 路由配置 — 读取应用的路由定义（React Router, TanStack Router, Next.js app dir）
2. 导航爬取 — 依次点击侧边栏/菜单的每个一级与二级板块
3. 深层链接 — 收集 CLAUDE.md、文档或往期审计报告中的 URL

每个路由记录一行，并注明作用：/app/clients — 客户列表、搜索、新建客户。

Thread inventory（任务流程清单）

梳理出 3–5 个构成用户日常的核心真实任务。这些是整个审计的骨架。

寻找方式：询问用户、阅读 CLAUDE.md / README、从顶层导航推断。例如：保险经纪人 → 续保保单、新建客户、处理今日待办。项目管理 → 晨会分流、更新任务、发送客户总结。空间/聊天应用 → 创建空间、发送消息、发起讨论串。

Element inventory（元素清单）

每到达一个路由，列出其中所有的交互元素。采取按需延迟构建策略 — 遍历到哪个页面就记录哪个页面，而非一次性全部准备好。这用于驱动覆盖率指标："在 /app/clients 页面上测试了 31 个元素中的 29 个"。

Phase 3 — Walkthrough (the audit itself)（走查阶段）

Interaction Manifest (MANDATORY)（交互清单 - 强制要求）

每一次走查都必须产出交互清单。无清单则直接判定Verdict = Incomplete。

交互清单 — /dashboard/spaces/marketing-pod
  用户画像：中小企业老板，时间紧迫，技术熟练度低
  [✓] 14:32:01 在消息输入框输入 "@assistant test" (textarea[placeholder*="message"])
  [✓] 14:32:03 从自动补全列表中选中 @assistant (li[data-mention-id="assistant"])
  [✓] 14:32:05 点击发送按钮 (button[aria-label="Send"])
  [✓] 14:32:06 验证输入框在 1000ms 内已清空 (textarea.value === "")
  [✓] 14:32:08 验证消息已出现在对话记录中 ([data-message-id] 数量 +1)
  [✓] 14:32:12 针对该消息展开讨论串 ([data-thread-trigger])
  [✓] 14:32:13 验证展开讨论串后主列宽度 ≥ 200px (getBoundingClientRect().width)
  [✓] 每步操作后均进行控制台读取 (0 警告, 0 错误)
  [✓] 每次关键操作前后均进行截图保存
  [✓] 网络请求已盘点 (0 个 5xx 错误，鉴权页面 0 个 403/404)

每个复选框都必须对应一次工具调用（点击、截图、控制台读取），并记录对应的时间戳与选择器。没有完整的清单，Agent 绝不能输出“Pass”报告。

每个被审计页面要求的必填项：

• ≥ 1 个已打字输入的输入框（真实文本，而非仅仅点击）
• ≥ 1 个已触发的主操作（发送 / 保存 / 提交 / 创建 / 发布 — 视业务而定）
• ≥ 1 个已打开的弹窗或详情面板
• 主操作触发后进行 ≥ 1 次控制台读取
• 主操作触发前 AND 触发后各进行 ≥ 1 次截图
• 验证预期操作后的状态更新（输入框清空、成功 Toast 提示、路由跳转、列表更新等）

完整模板与重放协议见 references/interaction-manifest.md。

Thread Traversal（流程遍历）

针对每个任务流程：

1. 从应用入口起点开始 — 切勿从流程中途切入。真实用户都是从 / 或 /dashboard 进入的。
2. 完全按画像视角走查 — 如果画像习惯扫读，就扫读；如果画像容易看错标签，就假装看错。记录犹豫点。
3. 截取每个状态变化的图像 — 默认状态 → 悬停/聚焦 → 激活 → 点击后 → 加载完成后 → 确认反馈。图片流就是证据链。
4. 统计使用成本 — 点击次数、决策节点、死胡同、中断恢复能力（在第 3 步关闭标签页再在第 4 步重新打开 — 状态还在吗？）
5. 在每个流程结束时将截图交给子 Agent 复核。

在每个流程结束时，（站在画像视角）回答：流程结束得清晰吗？我还会再来用吗？有什么改进能让使用体验简单一倍？

详见 references/walkthrough-checklist.md 及 references/workflow-comprehension.md。

Element Exhaustion（元素点测）

针对每个路由，逐个清理元素清单。跳过流程遍历中已经测试过的元素。详见 references/walkthrough-checklist.md。

<!-- truncated for translation batch; full body continues in source -->