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/metabaseMetabase 开源仓库的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.mdUXBot在Per-Task Report的 UX evaluation 小节要求逐项对照清单中的评估维度uxbot-agent.mdQABot在 Phase 4 UX/Usability Review阶段要求Navigate to the affected areas and evaluate using the shared UX checklistqabot-agent.md。这意味着清单设计上就强调共享与一致性无论执行评审的是专职 UX 机器人还是合入前 QA 机器人衡量界面好坏的标准必须完全相同这样聚合出来的问题才具有横向可比性。清单全文虽短但覆盖了从视觉到交互、从正常态到异常态、从桌面到移动、从浅色到深色的完整体验面。二、UX 评估清单八个核心评估维度清单开宗明义For each affected area, evaluate对每个受影响的区域进行评估。受影响的区域这一措辞要求评审者以变更影响面而非整个产品为对象——与 qabot-agent.md 中基于 diff 识别受影响的 UI 页面/组件包括后端改动经 API 响应传导到前端的间接影响的策略完全对应。八个维度逐一展开如下。2.1 视觉质量Visual qualityLayout correctness, spacing, alignment, typography评估布局是否正确、间距与对齐是否一致、排版字重、字号、行高是否符合设计规范。Metabase 前端基于 Mantine 组件库与自研设计体系视觉质量的退化通常表现为卡片错位、图表溢出容器、按钮间距不统一、标题层级混乱。评审时应在关键页面停留观察并对照同一功能在不同入口首页、集合页、仪表盘的表现是否一致。2.2 交互行为Interactive behaviorButtons, dropdowns, modals work smoothly; no jank按钮、下拉框、弹窗必须流畅工作不能出现卡顿jank。Metabase 的典型交互面包括Question Builder 的笔记本编辑器Notebook Editor步骤增删、仪表盘筛选器的联动、图表的钻取drill-down点击、可视化类型切换等。UXBot 在评估此项时遵循真实用户原则——只能通过点击、输入、键盘操作完成流程一旦某交互无法完成卡住的用户本身就是发现uxbot-agent.md。2.3 加载状态Loading statesSpinner/skeleton while data loads, no flash of empty content数据加载期间必须显示 spinner 或骨架屏skeleton且不能出现空内容闪烁flash of empty content。这一条对 Metabase 这类数据密集型 BI 产品尤为关键SQL 查询、大表渲染、仪表盘多卡片并发加载都需要明确的加载反馈。QABot 在动态复现阶段还会通过服务端日志检查是否有 N1 查询、被吞掉的异常导致 UI 静默卡死qabot-agent.md从后端性能角度佐证前端加载体验。2.4 错误状态Error statesClear, helpful error messages when things go wrong出错时必须给出清晰、有帮助的错误信息。Metabase 中常见错误场景包括SQL 语法错误、数据库连接失败、权限不足、查询超时。评估要点是错误信息是否能让用户明白发生了什么、如何解决而非抛出堆栈或空洞的操作失败。QABot 的 API 可用性评审还要求错误响应包含有用细节并与同类端点保持一致qabot-agent.md。2.5 空状态Empty statesReasonable display when theres no data无数据时应合理展示空状态。例如新集合为空时给出引导性文案与创建第一个问题的入口筛选条件过滤出零条记录时图表区应显示友好提示而非空白。空状态是 BI 产品中极易被忽视、但用户高频遇到的界面。2.6 键盘导航Keyboard navigationTab through interactive elements, correct focus management必须能通过 Tab 键遍历全部交互元素且焦点管理focus management正确焦点顺序符合视觉顺序、弹窗打开后焦点移入、关闭后焦点归还。QABot 在静态审查阶段会专门检查无障碍问题missing aria labels、broken keyboard navqabot-agent.md清单则在动态评审阶段从真实键盘操作角度验证这一点——两者互为印证。2.7 响应式行为Responsive behaviorWorks at different viewport sizes界面必须在不同视口尺寸下正常工作。评估方法是在浏览器中缩放窗口或模拟移动端视口观察导航栏折叠、卡片重排、表格横向滚动是否合理。UXBot 通过 Playwright MCP 的浏览器工具即可动态调整视口验证。2.8 明暗主题Light vs. dark modeVerify usability in both themes — contrast, legibility, icon/border visibility, no hard-coded colors that break in one mode必须在浅色与深色两种主题下验证可用性重点检查对比度是否达标、文字是否清晰、图标与边框是否可见、是否存在硬编码颜色导致在某一主题下失效。Metabase 支持主题外观配置见 配置外观 与 Appearance 文档 相关说明因此暗色模式下某按钮不可见是典型的回归问题通常源于组件中写死#fff之类的前景色。评估时应逐一在两种主题下过一遍同一流程并截图对比。三、证据收集规范Evidence gathering清单的第二部分规定了评审的证据纪律共四条每一条都直接对接仓库中机器人工作流的落地机制规范原文要点在仓库中的落地关键节点截图在动作前后、意外状态出现时截图UXBot 要求频繁截图且必须在尝试棘手交互之前、失败之后各截一张uxbot-agent.md描述性文件名如03-dropdown-wont-open.png、issue-01-before.pngQABot 动态复现时保存为issue-01-before.png、issue-01-after.png到{{OUTPUT_DIR}}/output/qabot-agent.md截图前记录 URL始终捕获当前 URL含查询参数QABot 要求用browser_evaluate读取window.location.href并在报告图片说明中带上 URL例如!/question/42?filterstatus平衡的报告记录做得好的地方不只报问题QABot 明确要求 Note what works well, not just whats broken — reports should be balanced并设有专门的 What Works Well 报告章节qabot-agent.md3.1 为什么文件名必须描述性03-dropdown-wont-open.png这样的命名比screenshot-3.png的实战价值高得多聚合报告/uxbot-aggregate会跨会话扫描task-report*.md描述性文件名让读者无需打开图片即可理解问题点也便于在 PDF 与 Markdown 之间保持证据可追溯。命名中带序号03-还能保留操作时序。3.2 URL 记录的意义BI 产品的大量状态编码在 URL 中/question/42?filterstatus、仪表盘参数等。截图前记录 URL 使问题可复现——评审者或开发者在浏览器中粘贴该 URL 即可回到出问题的界面状态。这也是 UXBot No Cheating 原则的一部分URL 必须通过点击界面自然到达评审者本人也必须遵守只能用 UI 到达页面的约束才能保证报告的每个截图都代表真实用户路径uxbot-agent.md。3.3 证据产出后的报告机制收集到的截图最终要进入报告。仓库中的报告链路为报告生成规范 规定使用相对路径嵌入图片desc再通过./bin/mage -bot-md-to-pdf report-directory/report.md生成 PDFUXBot 要求截图以 Markdown 图片语法内联嵌入而非纯链接每条配一行说明文字并最终产出 Markdown 与 PDF 双份交付物uxbot-agent.md。四、在 UXBot 中执行评审的完整流程将清单落到一次真实的 UX 评审需要走通 uxbot-agent.md 定义的完整流程清单在其中扮演评估标尺角色重置浏览器状态评审开始前必须清除全部 cookie、localStorage、sessionStorage防止上次会话的登录态泄漏进本次评审uxbot-agent.md以普通用户身份操作UXBot 被严格限制为regular user禁止读源码、禁止 REPL、禁止 API 调用只能通过 Playwright MCP 点击界面——如果你卡住了那本身就是发现uxbot-agent.md执行任务并截图按清单八维标准在关键节点截图保存到.bot/uxbot/SESSION_TIMESTAMP/screenshots/20 分钟时限单个任务超时即停止并汇报卡点卡住的位置就是最有价值的 UX 数据uxbot-agent.md撰写 per-task 报告在 report-generation.md 的格式约束下报告 Body 必须包含 Task / Approach / Steps taken / Struggles / Resolution / Screenshots / Time spent / UX evaluation 等章节其中UX evaluation 小节即对照本文清单逐项扫描uxbot-agent.md生成 PDF 并交付./bin/mage -bot-md-to-pdf生成 PDF向用户报告两个文件的绝对路径。注意清单要求Skip criteria that didnt come up; call out anything notable that did——未涉及的维度可跳过但出现明显异常的维度必须重点标注这保证了报告既不过度冗长又不遗漏关键问题。五、在 QABot 中执行评审的完整流程Phase 4QABot 的 UX 评审发生在动态复现Phase 3之后、最终报告Phase 5之前且即使 diff 只改后端也必须做完整 UX 评审——因为后端改动可能经 API 响应结构、权限、错误流传导到前端qabot-agent.md。其执行路径为从 diff 中识别受影响的页面/组件以及行为被间接改变调用被改后端代码的 API 端点结合 Phase 1 的测试覆盖分析优先探索弱覆盖或无覆盖的流程qabot-agent.md使用 Playwright 导航到受影响区域对照 ux-evaluation-criteria.md 逐项评估对被改/新增 API 做可用性评审响应结构与同类端点是否一致、字段命名是否符合约定、错误响应是否包含有用细节、是否泄漏内部信息qabot-agent.md评审过程中通过 REPL 的(logger/messages)或./bin/mage -bot-api-call /api/logger/logs检查服务端日志捕捉 N1 查询、被吞异常、慢操作导致的 UI 卡顿qabot-agent.md将发现写入ux-review.md连同截图、API 响应、日志摘录一并作为证据。六、与仓库测试体系的协同清单中的评估维度在 Metabase 的自动化测试体系中都有对应的验证层次评审发现的 UI 问题最终可落到具体测试类型修复见 test-strategy.md评估维度对应测试类型仓库位置交互行为、用户工作流Cypress 端到端测试e2e/test/scenarios 下的*.cy.spec.ts前端渲染、组件行为Jest 单元/组件测试与组件同目录的*.unit.spec.tsxfrontend/src/metabase后端逻辑、查询处理器Clojure 单元测试test/metabase/...混合前后端两者都要后端数据测试 前端/e2e UI 测试测试运行命令在项目根目录 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考