Metabase 缺陷复现策略全指南：为每个 Issue 类型选择最快的验证路径

Metabase 缺陷复现策略全指南：为每个 Issue 类型选择最快的验证路径

【免费下载链接】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

本文基于仓库中 ReproBot 复现机器人的核心规范文档 reproduction-strategies.md 展开。该文档定义了一套按 Issue 类型选择最快验证路径的策略矩阵、效率预算与特殊场景处理规则，是 Metabase 自动化缺陷复现流水线（ReproBot → FixBot → QA Bot）的关键一环。读完本文，你将掌握：如何区分八类常见缺陷并匹配 REPL / API / Playwright / 代码分析四条验证路径；如何在时间预算内收敛复现尝试并产出可判定的分类结论（REPRODUCED / SEEN FIXED / NOT REPRODUCED / INCONCLUSIVE）；以及如何结合 Metabase 源码（查询处理器、Toucan2 数据层、mage bot 命令族）把每条策略落到可执行的命令与代码片段上。

一、策略文档在哪个体系里：ReproBot 的职责边界

先明确背景：这份策略文档不是孤立的最佳实践，而是 ReproBot Agent 执行流程的一部分。在 reprobot-agent.md 中，ReproBot 的使命被定义为：

You are a bug reproduction specialist. Your job is to take a reported issue, try to reproduce it, classify the result, and optionally write a failing test. You do NOT fix bugs — you confirm them and provide evidence.

也就是说，ReproBot只负责确认缺陷并产出证据，不负责修复。它按照四个阶段执行：Issue 解析（Phase 1）→ 复现（Phase 2，最多 3 次尝试）→ 写失败测试（Phase 3，仅当 REPRODUCED）→ 报告（Phase 4）。本文聚焦的 reproduction-strategies.md 正是被嵌入 Phase 2 的核心规范（见 reprobot-agent.md 中的{{FILE:dev/bot/common/reproduction-strategies.md}}引用）。

在进入策略矩阵之前，必须先理解复现结果的分类体系（reprobot-agent.md），因为所有策略的最终目的都是给出一个可判定的分类：

关键约束：一旦拿到决定性分类就立即 STOP（reprobot-agent.md），不要继续无效尝试；整体预算不超过 30 分钟（reprobot-agent.md）。

二、核心策略矩阵：按 Issue 类型选择主/次验证路径

策略文档的核心是一张Issue 类型 → 验证路径的决策矩阵。它是全文的灵魂，完整继承如下（reproduction-strategies.md）：

2.1 为什么是这个组合：三条验证路径的能力边界

矩阵背后隐含了一个朴素的工程判断：先选最快的验证路径，而不是先选最像的。

• REPL 路径：面向后端状态与逻辑。它不需要启动浏览器、不需要构造完整 HTTP 上下文，直接对运行中的 JVM 求值 Clojure 表达式，是验证查询结果、数据状态、权限与纯逻辑最快的方式。
• API 路径：面向端点契约。通过./bin/mage -bot-api-call走真实 HTTP 层，能验证鉴权、请求/响应结构、错误码等 REPL 直接调 handler 会绕过的环节。
• Playwright 路径：面向用户可见行为。只有 UI 渲染、交互、可视化这类"用户看到什么"的问题才值得付出浏览器开销。
• 代码分析路径：永远作为兜底（Secondary 或代码对比），用于无法在单实例环境复现的场景（见第七章特殊场景）。

2.2 一个判定要点："检查是否已修复"

矩阵最后一行专门为SEEN FIXED分类提供了路径：对比当前分支源码与 Issue 报告版本，再用 REPL 对两个版本分别验证。这与分类体系的定义一一对应——即 reprobot-agent.md 要求的"要么读源码确认修复，要么运行时验证旧代码路径已正确"。

三、效率预算：在时间盒内收敛复现

策略文档为三类操作设置了明确的效率预算（reproduction-strategies.md）：

• 代码搜索：最多 3–5 次 Grep，使用宽泛模式；独立搜索并行化；不要迭代收窄模式，而是放宽。这是典型的"搜索成本递增"陷阱——一次宽泛搜索通常比多轮精确搜索更快定位。
• 代码分析：最多 5–7 次有目标的文件读取；若根因仍不清晰，立刻切换到运行时验证；不要追踪完整 git 历史。
• 后端缺陷：Playwright 只用于 1–2 张证据截图；如果 REPL 已确认缺陷，不要在 UI 复现上继续迭代。

这套预算与 reprobot-agent.md 的"并行化"和"时间感知"规则相互呼应：独立 REPL 调用、Grep 调用、API 调用应在同一轮内批量发出，总耗时不超过 30 分钟，3 次尝试后仍无定论即判 INCONCLUSIVE。

从仓库实现看，mage的 bot 命令族本身就是为这种批量并行设计的——-bot-api-call、-bot-repl-eval、-bot-preflight-health等命令分别实现在 mage/src/mage/bot/api_call.clj、mage/src/mage/bot/repl_eval.clj 与 mage/src/mage/bot/preflight.clj，它们共享 mage/src/mage/bot/server_info.clj 的环境发现结果，可以在同一回合内被反复调用而不产生环境初始化开销。

四、REPL 路径实操：从矩阵到可直接执行的代码

策略矩阵中，REPL 承担了 8 类 Issue 中 6 类的主路径。这些策略不是抽象口号，而是对应着 metabase-patterns.md 中沉淀的可直接复制的 REPL 配方（该文档同样被 ReproBot Phase 2 引用，见 reprobot-agent.md）。下面按矩阵行逐一展开。

4.1 "错误数据 / 数据库状态" →t2/select检查

矩阵第 5 行指向t2/select，这是 Metabase 数据访问层 Toucan2 的核心查询函数。用于检查某张业务表的实际状态：

;; 检查某数据库下的表 (t2/select [:model/Table :id :name :db_id] :db_id 1) ;; 查看某个设置项的实际值（用于确认功能开关状态） (t2/select-one :model/Setting :key "site-name") ;; 查询原始 SQL (t2/query "SELECT id, name FROM report_card LIMIT 5")

在本地开发模式下，通过统一包装命令在运行中的后端上执行（environment-discovery.md）：

./bin/mage -bot-repl-eval '(do (require (quote [toucan2.core :as t2])) (t2/select :model/Card :id 1))'

注意：-bot-repl-eval会自动检测后端（优先 nREPL，其次 socket REPL），在远端 PR 预览环境（pr-env 模式）下会路由到远程 socket REPL；一次调用只发送一个顶层表达式，多表达式需包在(do ...)中（environment-discovery.md）。

4.2 "查询结果 / SQL 生成" →qp/process-query与qp.compile/compile

矩阵第 4 行对应查询处理器链路。这两条配方对应 Metabase 查询处理器的两个层次：执行层与编译层。

执行层（真正跑查询）直接调用查询处理器命名空间：

(require '[metabase.query-processor :as qp]) (qp/process-query {:database 1 :type :native :native {:query "SELECT * FROM ORDERS LIMIT 5"}})

编译层（只看 SQL 生成，不执行）则验证 MBQL → SQL 的翻译是否正确——这对"SQL 生成类缺陷"尤其有价值，因为可以快速对比期望 SQL 与实际 SQL：

(require '[metabase.query-processor.compile :as qp.compile]) (qp.compile/compile {:database 1 :type :query :query {:source-table 1 :filter [:= [:field 1 nil] 42]}})

这两个命名空间对应仓库中的 src/metabase/query_processor/ 目录（含process.clj、compile.clj等 95 个文件，是查询执行的完整实现）。此外 metabase-patterns.md 还提供了dev/pprint-sql用于美化打印 SQL，以及dev/explain-query用于查看执行计划——适合在 SQL 生成可疑时快速人工比对。

4.3 "API / 端点行为" → 直接调用 handler 或-bot-api-call

矩阵第 3 行给出两条等价路径：

1. REPL 直接调用 handler：跳过 HTTP 层，直接调用 API 命名空间下的处理函数，速度最快，但会绕过鉴权等中间件。
2. ./bin/mage -bot-api-call：走完整 HTTP 栈，能验证真实请求/响应与错误码。该命令在 mage/src/mage/bot/api_call.clj 中实现，在 pr-env 模式下自动把请求发往BASE_URL并使用缓存的会话令牌，遇到 401 会自动刷新会话（environment-discovery.md）。

# 健康检查（也是复现前置条件） ./bin/mage -bot-api-call /api/health # 带管理员 API Key 读取日志 ./bin/mage -bot-api-call /api/logger/logs --api-key $ADMIN_API_KEY

从源码结构看，Metabase 的 REST API 端点集中定义在 src/metabase/api/、src/metabase/api_routes/ 与各功能的*_rest目录（如 src/metabase/queries_rest/、src/metabase/settings_rest/），REPL 中可直接require对应命名空间调用内部函数。

4.4 "权限 / 认证流程" → REPL + Playwright

权限类缺陷需要两条证据链：后端权限判定（REPL 检查）与用户实际看到的界面表现（Playwright）。REPL 侧检查权限数据：

(t2/select :model/Permissions :group_id 1)

4.5 "代码逻辑 / 边界情况" → 先读源码再调函数

矩阵第 7 行强调"read source then invoke functions"——先用文件读取定位候选实现（遵守 5–7 次文件读取预算），再在 REPL 中直接调用目标函数验证边界输入。这条路径尤其适合纯函数逻辑，Metabase 的核心逻辑大量集中在 src/metabase/lib/（130 个.cljc文件，前后端共享的 MBQL 库）与 src/metabase/util/ 中，可读性高、易于直接调用。

五、Playwright 路径实操：UI 类缺陷的证据采集

对于 UI / 前端行为类 Issue，主策略是Playwright + REPL 准备数据：

• REPL 负责数据准备：用t2/insert-returning-instance!/t2/update!或 mage 命令构造复现所需的数据状态（如先建一张卡、设一个 Feature Flag）。
• Playwright 负责 UI 验证：导航、快照、点击、填充、截图，把"用户看到的行为"固化为证据。

复现开始前，环境发现阶段要求先加载 Playwright MCP 工具集（browser_navigate/browser_snapshot/browser_click/browser_take_screenshot等 12 个工具，environment-discovery.md）。同时策略文档给出严格的截图预算：后端缺陷最多 1–2 张证据截图（reproduction-strategies.md），避免在 REPL 已确认缺陷后仍在 UI 上反复折腾。

在 pr-env 模式（远程预览环境）下，Playwright 必须导航到-bot-server-info报告的BASE_URL（HTTPS 预览站点），而非http://localhost:*；且该网络需要 Tailscale 才能访问（environment-discovery.md）。

六、特殊场景：三条不能走常规路径的规则

策略文档在矩阵之外专门定义了三个特殊场景（reproduction-strategies.md），它们决定了一类缺陷是否值得动态复现：

6.1 时序 / 竞态条件（Timing / Race Conditions）

如果复现需要模拟慢响应或竞态条件、且无法在本地单实例环境触发，则放弃动态复现，直接进入代码分析。此时根因通过 code review 确认，但要明确记录："根因已由代码审查确认，但在单实例环境中无法经验性观测"——这是一条重要的诚实性规则：结论级别（CONFIRMED vs SUSPECTED）必须与证据强度匹配，不能因为没跑出截图就把已确认的代码缺陷降级。

6.2 时序序列缺陷（Time-series Bugs）

这类缺陷有可量化的复现配方：在多种数据密度下测试——约 12 个点（月度/1 年）、约 36 个点（月度/3 年）、约 60 个点（月度/5 年）。缺陷往往在特定密度下才显现，因为该密度触发 ECharts 切换时间间隔（interval）逻辑。这直接关联仓库前端可视化层：Metabase 的图表渲染基于 ECharts（见根目录 patches/echarts+6.1.0.patch），时间轴密度切换正是 ECharts 时间刻度的常见边界问题，前端相关实现位于 frontend/src/metabase/ 的可视化模块中。

6.3 外部依赖缺陷（External Dependency Bugs）

如果缺陷需要远程数据库、LDAP、SMTP、S3 或其他本地不可用的外部服务，直接分类为 INCONCLUSIVE，并在报告中注明所需基础设施。这是对"3 次尝试"规则的例外——缺少基础设施时，尝试次数再多也不会产生有效证据。仓库中的相关集成测试资源（如 test_resources/ldap/、test_resources/smtp/、test_resources/ssh/）可以佐证这些依赖在测试环境中的配置方式，但真实外部服务的缺失仍是判定边界。

七、复现之后：证据归档与"写失败测试"的门槛

策略文档只是 Phase 2 的一部分，但它决定了后续 Phase 3/4 的走向，因此需要把闭环讲清楚。

证据归档：每次尝试的截图、API 响应、REPL 输出都要保存到{{OUTPUT_DIR}}/output/目录（reprobot-agent.md）。环境发现阶段会提前创建该目录（environment-discovery.md 要求mkdir -p .bot/autobot {{OUTPUT_DIR}}/output {{OUTPUT_DIR}}/tmp），因为 Playwright 截图在目录不存在时会直接ENOENT失败。

写失败测试的门槛（reprobot-agent.md）：仅当状态为REPRODUCED 且缺陷在当前分支仍存在时才写测试。此时调用 test-strategy.md 中的测试类型选择表：

测试命名要求引用 Issue ID：Clojure 用(deftest issue-12345-test ...)，Jest 用it("should handle X (issue #12345)")。验证失败的运行命令：

# 后端：仅运行指定测试 ./bin/test-agent :only '[metabase.foo-test/issue-12345-test]' # 前端单元测试 bun run test-unit-keep-cljs path/to/file.unit.spec.ts # Cypress 端到端 npx cypress run --spec e2e/test/scenarios/category/file.cy.spec.ts

测试补丁以git diff > {{OUTPUT_DIR}}/test-diff.patch保存，随后 Phase 4 输出report.md并调用./bin/mage -bot-md-to-pdf生成 PDF 报告（reprobot-agent.md）。这份失败测试随后会被 FixBot 采纳，作为 TDD 的"红灯"起点（fixbot-agent.md）。

八、总结：把策略变成可执行的判定流程

把整份策略文档压缩成一个可操作的决策流程：

1. 解析 Issue→ 判断缺陷类型（Frontend / Backend / Query / Mixed）与数据库类型（H2 默认 / Postgres / MySQL / MariaDB，见 reprobot-agent.md）。
2. 查矩阵选主策略→ 大多数情况优先 REPL（数据/查询/逻辑）或-bot-api-call（端点）；只有 UI 可见行为才动用 Playwright。
3. 守效率预算→ 3–5 次宽模式 Grep、5–7 次文件读取、后端缺陷最多 1–2 张截图；批处理并行调用。
4. 命中特殊场景就降级→ 竞态 → 代码分析；时序 → 三档数据密度测试；外部依赖 → 直接 INCONCLUSIVE 并注明所需基础设施。
5. 拿到决定性分类立即 STOP→ REPRODUCED 则进入失败测试（Phase 3）与报告（Phase 4）；SEEN FIXED / NOT REPRODUCED / INCONCLUSIVE 则如实记录，3 次尝试后仍无定论判 INCONCLUSIVE。

这套策略的价值在于把"复现一个 Metabase 缺陷"从凭感觉的探索，变成有时间预算、有证据标准、有明确出口条件的工程流程——每一类缺陷都有最短验证路径，每一条路径都有仓库内可执行的命令与代码片段支撑，而"无法动态复现"本身也是一种有据可依的结论。

【免费下载链接】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