企业官网建设流程全解析

Metabase 自动化 UX 评审指南：UXBot 与 QABot 的界面体验评估清单与证据收集规范

【免费下载链接】metabaseThe easy-to-use open source Business Intelligence and Embedded Analytics tool that lets everyone work with data :bar_chart:项目地址: https://gitcode.com/GitHub_Trending/me/metabase

Metabase 开源仓库的dev/bot/目录下内置了一套由 AI 代理（Agent）驱动的自动化质量保障体系，其中dev/bot/common/ux-evaluation-criteria.md是这套体系中唯一被多个 Agent 共享的 UX 评估标准——它同时被 UXBot Agent（专职模拟真实用户做界面体验测试）和 QABot Agent（合入前的代码评审与 QA 机器人）通过{{FILE:dev/bot/common/ux-evaluation-criteria.md}}模板指令引用。本文以这份清单为骨架，逐条拆解其背后的评估维度与落地方法，并结合仓库源码、测试体系与机器人工作流，说明如何在 Metabase 前端（React + TypeScript，位于 frontend/src/metabase）上执行一套可复现、有证据、结论平衡的 UX 评审。

一、这份清单在仓库机器人体系中的定位

Metabase 的开发机器人体系（dev/bot）由多个分工明确的 Agent 组成：UXBot 只通过浏览器模拟普通用户操作产品、体验真实使用路径；QABot 在功能合入主分支前执行"静态审查 → 动态复现 → UX 评审 → 最终报告"的多阶段检查。两份 Agent 的提示词（prompt）中都显式嵌入了同一份 ux-evaluation-criteria.md：

• UXBot在"Per-Task Report"的 UX evaluation 小节要求逐项对照清单中的评估维度（uxbot-agent.md）；
• QABot在 Phase 4 "UX/Usability Review"阶段要求"Navigate to the affected areas and evaluate using the shared UX checklist"（qabot-agent.md）。

这意味着清单设计上就强调"共享"与"一致性"：无论执行评审的是专职 UX 机器人还是合入前 QA 机器人，衡量界面好坏的标准必须完全相同，这样聚合出来的问题才具有横向可比性。清单全文虽短，但覆盖了从视觉到交互、从正常态到异常态、从桌面到移动、从浅色到深色的完整体验面。

二、UX 评估清单：八个核心评估维度

清单开宗明义："For each affected area, evaluate"（对每个受影响的区域进行评估）。"受影响的区域"这一措辞要求评审者以变更影响面而非整个产品为对象——与 qabot-agent.md 中"基于 diff 识别受影响的 UI 页面/组件，包括后端改动经 API 响应传导到前端的间接影响"的策略完全对应。八个维度逐一展开如下。

2.1 视觉质量（Visual quality）

Layout correctness, spacing, alignment, typography

评估布局是否正确、间距与对齐是否一致、排版（字重、字号、行高）是否符合设计规范。Metabase 前端基于 Mantine 组件库与自研设计体系，视觉质量的退化通常表现为：卡片错位、图表溢出容器、按钮间距不统一、标题层级混乱。评审时应在关键页面停留观察，并对照同一功能在不同入口（首页、集合页、仪表盘）的表现是否一致。

2.2 交互行为（Interactive behavior）

Buttons, dropdowns, modals work smoothly; no jank

按钮、下拉框、弹窗必须流畅工作，不能出现卡顿（jank）。Metabase 的典型交互面包括：Question Builder 的笔记本编辑器（Notebook Editor）步骤增删、仪表盘筛选器的联动、图表的钻取（drill-down）点击、可视化类型切换等。UXBot 在评估此项时遵循"真实用户"原则——只能通过点击、输入、键盘操作完成流程，一旦某交互无法完成，"卡住的用户本身就是发现"（uxbot-agent.md）。

2.3 加载状态（Loading states）

Spinner/skeleton while data loads, no flash of empty content

数据加载期间必须显示 spinner 或骨架屏（skeleton），且不能出现"空内容闪烁"（flash of empty content）。这一条对 Metabase 这类数据密集型 BI 产品尤为关键：SQL 查询、大表渲染、仪表盘多卡片并发加载都需要明确的加载反馈。QABot 在动态复现阶段还会通过服务端日志检查是否有 N+1 查询、被吞掉的异常导致 UI 静默卡死（qabot-agent.md），从后端性能角度佐证前端加载体验。

2.4 错误状态（Error states）

Clear, helpful error messages when things go wrong

出错时必须给出清晰、有帮助的错误信息。Metabase 中常见错误场景包括：SQL 语法错误、数据库连接失败、权限不足、查询超时。评估要点是错误信息是否能让用户明白"发生了什么、如何解决"，而非抛出堆栈或空洞的"操作失败"。QABot 的 API 可用性评审还要求错误响应包含有用细节，并与同类端点保持一致（qabot-agent.md）。

2.5 空状态（Empty states）

Reasonable display when there's no data

无数据时应合理展示空状态。例如：新集合为空时给出引导性文案与"创建第一个问题"的入口；筛选条件过滤出零条记录时，图表区应显示友好提示而非空白。空状态是 BI 产品中极易被忽视、但用户高频遇到的界面。

2.6 键盘导航（Keyboard navigation）

Tab through interactive elements, correct focus management

必须能通过 Tab 键遍历全部交互元素，且焦点管理（focus management）正确：焦点顺序符合视觉顺序、弹窗打开后焦点移入、关闭后焦点归还。QABot 在静态审查阶段会专门检查无障碍问题（missing aria labels、broken keyboard nav，qabot-agent.md），清单则在动态评审阶段从真实键盘操作角度验证这一点——两者互为印证。

2.7 响应式行为（Responsive behavior）

Works at different viewport sizes

界面必须在不同视口尺寸下正常工作。评估方法是在浏览器中缩放窗口或模拟移动端视口，观察导航栏折叠、卡片重排、表格横向滚动是否合理。UXBot 通过 Playwright MCP 的浏览器工具即可动态调整视口验证。

2.8 明暗主题（Light vs. dark mode）

Verify usability in both themes — contrast, legibility, icon/border visibility, no hard-coded colors that break in one mode

必须在浅色与深色两种主题下验证可用性，重点检查：对比度是否达标、文字是否清晰、图标与边框是否可见、是否存在硬编码颜色导致在某一主题下失效。Metabase 支持主题外观配置（见 配置外观 与 Appearance 文档 相关说明），因此"暗色模式下某按钮不可见"是典型的回归问题，通常源于组件中写死#fff之类的前景色。评估时应逐一在两种主题下过一遍同一流程，并截图对比。

三、证据收集规范（Evidence gathering）

清单的第二部分规定了评审的证据纪律，共四条，每一条都直接对接仓库中机器人工作流的落地机制：

3.1 为什么文件名必须"描述性"

03-dropdown-wont-open.png这样的命名比screenshot-3.png的实战价值高得多：聚合报告（/uxbot-aggregate）会跨会话扫描task-report*.md，描述性文件名让读者无需打开图片即可理解问题点，也便于在 PDF 与 Markdown 之间保持证据可追溯。命名中带序号（03-）还能保留操作时序。

3.2 URL 记录的意义

BI 产品的大量状态编码在 URL 中（/question/42?filter=status、仪表盘参数等）。截图前记录 URL 使问题可复现——评审者或开发者在浏览器中粘贴该 URL 即可回到出问题的界面状态。这也是 UXBot "No Cheating" 原则的一部分：URL 必须通过点击界面自然到达，评审者本人也必须遵守"只能用 UI 到达页面"的约束，才能保证报告的每个截图都代表真实用户路径（uxbot-agent.md）。

3.3 证据产出后的报告机制

收集到的截图最终要进入报告。仓库中的报告链路为：报告生成规范 规定使用相对路径嵌入图片（desc），再通过./bin/mage -bot-md-to-pdf <report-directory>/report.md生成 PDF；UXBot 要求截图以 Markdown 图片语法内联嵌入（而非纯链接），每条配一行说明文字，并最终产出 Markdown 与 PDF 双份交付物（uxbot-agent.md）。

四、在 UXBot 中执行评审的完整流程

将清单落到一次真实的 UX 评审，需要走通 uxbot-agent.md 定义的完整流程，清单在其中扮演"评估标尺"角色：

1. 重置浏览器状态：评审开始前必须清除全部 cookie、localStorage、sessionStorage，防止上次会话的登录态泄漏进本次评审（uxbot-agent.md）；
2. 以普通用户身份操作：UXBot 被严格限制为"regular user"，禁止读源码、禁止 REPL、禁止 API 调用，只能通过 Playwright MCP 点击界面——"如果你卡住了，那本身就是发现"（uxbot-agent.md）；
3. 执行任务并截图：按清单八维标准在关键节点截图，保存到.bot/uxbot/<SESSION_TIMESTAMP>/screenshots/；
4. 20 分钟时限：单个任务超时即停止并汇报卡点，卡住的位置就是最有价值的 UX 数据（uxbot-agent.md）；
5. 撰写 per-task 报告：在 report-generation.md 的格式约束下，报告 Body 必须包含 Task / Approach / Steps taken / Struggles / Resolution / Screenshots / Time spent / UX evaluation 等章节，其中UX evaluation 小节即对照本文清单逐项扫描（uxbot-agent.md）；
6. 生成 PDF 并交付：./bin/mage -bot-md-to-pdf生成 PDF，向用户报告两个文件的绝对路径。

注意：清单要求"Skip criteria that didn't come up; call out anything notable that did"——未涉及的维度可跳过，但出现明显异常的维度必须重点标注，这保证了报告既不过度冗长又不遗漏关键问题。

五、在 QABot 中执行评审的完整流程（Phase 4）

QABot 的 UX 评审发生在动态复现（Phase 3）之后、最终报告（Phase 5）之前，且即使 diff 只改后端也必须做完整 UX 评审——因为后端改动可能经 API 响应结构、权限、错误流传导到前端（qabot-agent.md）。其执行路径为：

1. 从 diff 中识别受影响的页面/组件，以及行为被间接改变（调用被改后端代码）的 API 端点；
2. 结合 Phase 1 的测试覆盖分析，优先探索弱覆盖或无覆盖的流程（qabot-agent.md）；
3. 使用 Playwright 导航到受影响区域，对照 ux-evaluation-criteria.md 逐项评估；
4. 对被改/新增 API 做可用性评审：响应结构与同类端点是否一致、字段命名是否符合约定、错误响应是否包含有用细节、是否泄漏内部信息（qabot-agent.md）；
5. 评审过程中通过 REPL 的(logger/messages)或./bin/mage -bot-api-call /api/logger/logs检查服务端日志，捕捉 N+1 查询、被吞异常、慢操作导致的 UI 卡顿（qabot-agent.md）；
6. 将发现写入ux-review.md，连同截图、API 响应、日志摘录一并作为证据。

六、与仓库测试体系的协同

清单中的评估维度在 Metabase 的自动化测试体系中都有对应的验证层次，评审发现的 UI 问题最终可落到具体测试类型修复（见 test-strategy.md）：

测试运行命令在项目根目录 CLAUDE.md 中有完整约定（例如后端./bin/test-agent、前端bun run test-unit-keep-cljs、Cypressnpx cypress run --spec ...）。评审者若在动态复现阶段需要快速验证后端逻辑，可参考 reproduction-strategies.md 与 metabase-patterns.md 中的 REPL 配方（如qp/process-query、t2/select、(dev/restart!)等），但要注意：UXBot 场景下这些工具是禁止使用的，以保证评审视角纯粹是真实用户视角。

七、使用清单时的注意事项

• 以受影响区域为对象：不要对整个产品做地毯式评审，聚焦 diff 触及的页面、组件及其间接影响面；
• 平衡记录：做得好的交互（好的错误提示、顺畅的钻取、周到的边界处理）同样要写进报告，避免报告失去公信力；
• 明确结论边界：无法复现的问题标注 SUSPECTED 并说明触发条件，而不是默认代码没问题（qabot-agent.md）；
• 兼容真实环境：在共享的 PR 预览环境中执行破坏性测试前先快照、测试后回滚，无法回滚的破坏性测试直接标注 CONFIRMED_STATIC 并说明原因（environment-discovery.md）。

结语

ux-evaluation-criteria.md 虽然只有短短两节，却是 Metabase 自动化质量保障体系中承上启下的关键节点：它向上被 UXBot 与 QABot 两个 Agent 共同引用，保证了"真实用户视角"与"合入前评审"使用同一把体验标尺；向下与 e2e 测试、Jest 单测、Clojure 后端测试形成互补——清单负责"发现体验问题"，测试体系负责"锁定问题不再回归"。对任何希望在 CI 流程中引入自动化 UX 评审的团队而言，这套"八维标准 + 证据纪律 + 平衡报告"的范式都值得直接借鉴。

【免费下载链接】metabaseThe easy-to-use open source Business Intelligence and Embedded Analytics tool that lets everyone work with data :bar_chart:项目地址: https://gitcode.com/GitHub_Trending/me/metabase