Metabase QABot 合并前自动 QA 工作流解析：`/qabot` 命令编排、独立运行目录与六阶段缺陷复现体系

Metabase QABot 合并前自动 QA 工作流解析：/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

QABot 是 Metabase 仓库中一套用于合并前（pre-merge）质量把关的自动化 QA 工作流：它以 Claude Code 自定义命令/qabot为入口，让 AI Agent 直接在本仓库、对着本地正在运行的 Metabase 实例分析当前分支，先于合并找出 bug、边界问题、安全缺陷与 UX 问题。读完本文，你将掌握这条工作流从“时间戳运行目录生成”到“分严重度缺陷报告与修复计划产出”的完整编排链路，理解其输出目录隔离、模板化 Prompt 生成、静态审查与动态复现相结合的分级方法，并能在自己项目中复刻这套“AI 合并前审查”的工程模式。

QABot 是什么：合并前的只读守门人

在 Metabase 的日常研发中，一个分支在合并进master之前，QABot 会被触发对分支改动做一轮完整的 QA 分析。其定位明确写在其 Agent 提示词 dev/bot/qabot-agent.md 中：

You are a pre-merge QA bot. Your job is to find bugs, edge cases, security issues, and UX problems in the changes on this branchbefore they are merged. You do NOT fix anything — you find and report.

核心设计原则有三：

• 只读守门而非修复：QABot 只负责发现并报告问题，绝不修改任何源码；修复由后续的 fixbot 工作流承担。
• 直接跑在真实实例上：它直接运行在当前项目里，对着本地已启动的 Metabase 服务（后端 + 前端）做动态验证，而不是纯静态推理。
• 隔离运行：每次/qabot调用都必须落在独立的运行目录.bot/qabot/<TIMESTAMP>/中，同一仓库可同时存在多次互不冲突的调用。

如果想针对某个指定分支在隔离的 worktree + 独立后端/前端中跑同样分析，/qabot文档还提示使用/autobot <branch> /qabot，其调度入口定义在 .claude/commands/autobot.md（见下文“与 autobot / 远程 PR 环境的协同”）。

一次/qabot调用的整体编排

.claude/commands/qabot.md 本身是一个编排器（orchestrator）命令，它把整个流程拆成 4 个显式步骤：

1. 生成每次运行的独立目录—— 用YYYYMMDD-HHMMSS时间戳建出唯一的OUTPUT_DIR；
2. 收集上下文—— 先跑 discover 生成config.env，再读取 Linear issue / PR 描述等背景；
3. 生成 Agent 提示词—— 调用mage -bot-generate-prompt，用模板填充本次运行的变量；
4. 执行—— Agent 读取生成的prompt.md，按其中的 Phases 1–6 顺序执行完所有阶段。

其中第 4 步的“Phases 1–6”实际由模板文件 dev/bot/qabot-agent.md 承载——它是一份 600 多行的“Agent 任务书”，定义了六个阶段的完整方法论。因此整套工作流本质是：薄编排层（命令文件）+ 厚方法论文档（模板） + Clojure 工具支撑（mage bot 系列命令）的三层结构。

第一步：为每次运行生成独立的输出目录

/qabot首先要求生成一个YYYYMMDD-HHMMSS格式的时间戳：

• 如果 Agent 知道当前墙钟时间，直接构造；
• 否则运行./bin/mage -bot-timestamp；
• 明确禁止直接调用date命令（保持所有时间来源统一、可审计）。

随后设置两个环境变量作为本次运行的主干：

TIMESTAMP=<YYYYMMDD-HHMMSS> OUTPUT_DIR=.bot/qabot/<TIMESTAMP>

硬性约束：本次运行写入的所有文件——包括 discover 阶段的产物——都必须位于<OUTPUT_DIR>/之下，且不同运行之间不得共享任何路径（"There must beno shared paths across runs"）。这意味着：

• 多人在同一仓库先后调用/qabot不会互相覆盖证据文件；
• 目录名自带时间戳，天然成为审计/追溯依据；
• 运行结束后的产物（截图、API 响应、报告）可以整体拷贝或归档。

这个“per-run 隔离目录”思想在整套 bot 体系里被反复强调：discover 文档 .claude/commands/qabot-discover.md 同样规定“Discover never picks a directory itself, so nothing is ever written to a shared.bot/qabot/...location”——路径永远由调用方（/qabot或/autobot）传入--output-dir。

第二步：discover 收集上下文并落盘config.env

如果<OUTPUT_DIR>/config.env不存在，编排器先调用 discover 阶段：

/qabot-discover $ARGUMENTS --output-dir <OUTPUT_DIR>

discover 会把产物直接写进<OUTPUT_DIR>/，绝不写共享位置。随后读取三个文件：

根据 .claude/commands/qabot-discover.md，discover 内部还完成了几项关键工作：

• 解析/检测 Linear issue：若调用参数带了MB-12345这类 ID，按[A-Z]+-[0-9]+校验；否则从当前分支名按*/<prefix>-NNNNN-*（不区分大小写）提取，前缀是 2–4 字母的团队代号（MB、BOT、UXW、EMB、QB、DEV、GHY、GDGT……），再退而通过gh pr view --json title,url,body从 PR body 里找 Linear 链接；仍找不到则置空——不询问用户，因为这是非交互式发现步骤。
• 拉取上下文：issue 命中后运行./bin/mage -bot-fetch-issue <ISSUE_ID>，PR 存在则gh pr view --json title,body。
• 校验分支是否偏离 master：git log --oneline origin/master..HEAD为空时在config.env追加BRANCH_WARNING=no-local-commits。
• 写结果：QABot 一律固定使用 postgres 应用库（它测试的是分支改动本身，而非数据库专属 bug），最终写出的config.env形如：

APP_DB=postgres LINEAR_ISSUE_ID=<resolved-id-or-empty> TIMESTAMP=<TIMESTAMP> OUTPUT_DIR=<OUTPUT_DIR>

第三步：用 mage 模板引擎生成 Agent Prompt

编排器不把上下文直接粘贴进对话，而是引用 discover 目录里的文件，通过mage的一条命令完成“模板 + 变量 + 文件内联”：

./bin/mage -bot-generate-prompt \ --template dev/bot/qabot-agent.md \ --output <OUTPUT_DIR>/prompt.md \ --set "TIMESTAMP=<TIMESTAMP>" \ --set "OUTPUT_DIR=<OUTPUT_DIR>" \ --set "LINEAR_ISSUE_ID=<resolved-id-or-empty>" \ --set-from-file "LINEAR_CONTEXT=<OUTPUT_DIR>/linear-context.txt" \ --set-from-file "PR_CONTEXT=<OUTPUT_DIR>/pr-context.txt"

关键参数语义

• --template：模板路径，这里是 dev/bot/qabot-agent.md；--output：生成的 prompt 落点。
• --set KEY=VALUE：做纯文本替换。若 VALUE 含 shell 特殊字符，parse-set-args会先检查是否含=，缺=的条目会被警告并忽略（见 mage/src/mage/bot/prompt.clj）。
• --set-from-file KEY=PATH：读取该文件并把全文内联为模板变量值（实现见 prompt.clj）。若文件不存在——比如 discover 没找到 Linear issue 或 PR——变量会退化为空字符串，这正是期望行为，无需报错。这样既避免了把多行文本 shell 转义进命令行，也天然处理了“可选上下文缺失”的情形。

模板的两种占位符

prompt.clj 的实现揭示了模板引擎的两个机制：

1. {{KEY}}值替换：先用--set-from-file/--set构造 replacements 映射，再按 key 逐一替换；
2. {{FILE:path}}文件内联：以仓库根为基准解析路径并 slurp 进模板。模板 agent 文件里就大量使用了这一机制，例如：

{{FILE:dev/bot/common/environment-discovery.md}}

把 environment-discovery.md（环境/实例/REPL/日志访问手册）、reproduction-strategies.md、metabase-patterns.md、ux-evaluation-criteria.md等公共章节按需注入。实现中只做单遍扫描——被 include 的内容不会再递归解析其中的{{FILE:...}}标记，避免了循环引用风险；路径缺失时替换为<!-- FILE NOT FOUND: ... -->注释并告警。

generate-prompt!还会在写盘前自动mkdirs父目录并打印Wrote prompt: <path>（prompt.clj），因此--output指向尚不存在的<OUTPUT_DIR>时也无需手工建目录。

第四步：执行 Phases 1–6 的完整 QA 方法论

生成的prompt.md就是 Agent 本次运行的任务书。六个阶段的方法论全部来自模板 dev/bot/qabot-agent.md，要求 Agent在单次对话内顺序跑完所有阶段，除非命中 STOP 条件。值得一提的是，Agent 被要求用“醒目横幅”与用户交互（获取输入、报告阻塞、呈现最终报告时），横幅如：

╔══════════════════════════════════════════════════════════════╗ ║ 🔍 QABOT — <STATUS> ║ ╠══════════════════════════════════════════════════════════════╣ ║ <your message here> ║ ╚══════════════════════════════════════════════════════════════╝

Phase 1：Git Diff + 上下文

1. 确认分支确实含改动：先git log --oneline origin/master..HEAD；为空则查远端分支git log --oneline HEAD..origin/<branch-name>，必要时git merge --ff-only origin/<branch-name>，本地与远端发散时需在报告中注明“动态测试可能不反映 PR 改动”。
2. 收集全部改动（三条 diff 必须全跑，互相不可替代）：
   • git diff origin/master...HEAD—— 已提交改动；
   • git diff—— 未提交改动（可用git status确认）；
   • git diff --cached—— 已暂存改动；
   • git log --oneline origin/master..HEAD—— 提交历史。
3. 按领域分组文件：Backend（Clojuresrc/、enterprise/backend/）/ Frontend（frontend/src/）/ API routes（defendpoint与api/路径）/ Migrations（resources/migrations/）/ Tests（test/、frontend/test/、e2e/）/ Config 及其他。
4. 结合 Linear/PR 上下文理解“本意”，通常 PR 描述是最佳的行为预期来源。
5. 分析测试覆盖：对每个改动区域记录“测了什么 / 没测什么 / 代码与测试之间的缺口”，驱动后续阶段把精力集中在未覆盖路径上。同时警惕形如(with-redefs [foo (fn [& _] (throw ...))] ...)的“禁令测试”（断言某函数不被调用、某路径不被走通）——它锁定了一条新的“禁止”，要在 Phase 2 一并分析。
6. 从 E2E 测试学习 UI 交互模式：e2e/目录下的*.cy.spec.ts是“如何操作 UI”的现成范例（点击顺序、输入文本、等待条件），但只是出发点，真正的 bug 往往藏在用户偏离 happy path 的地方。
7. 将 diff 摘要写入<OUTPUT_DIR>/diff-summary.md。

Phase 2：静态代码审查（Code Analysis）

Phase 2 的核心方法论可以浓缩为几个“审查透镜”：

• Anti-anchor（反锚定）：动手前先在initial-review.md写下“这个 patch 可能错的三条理由”，而不是“它看起来对的三条理由”。想不出三条合理失败模式 = 还没看懂 patch。小、测试全、风格干净的代码只证明“用心”，不证明“正确”。
• “每条新禁止都是一条新需求”：这是整个审查中最重要的透镜。任何收窄原先允许范围的改动（新 guard、新 early-return、新when、新if条件、新前置校验、cond 新增过滤分支、收紧 spec、禁令测试、移除调用点）都必须回答 5 个问题：旧规则一句话是什么？新规则一句话是什么？逐条列出落入旧且不满足新的具体记录/用户/流程/调用方/部署状态？每个被排除案例是有意为之吗（PR 描述/Linear issue 是否提及）？它是否可被合法用户旅程触达（是 → 即使 diff 很小、测试全绿也要按 SEVERE 报）？
• 输入分支粒度分析，而非只遍历调用方：类似(or discovery-path manual-path)的输入分支可能身处相反的授权上下文（一端是攻击者可控制的远端 OIDC discovery 文档，另一端是管理员在设置页录入的 URL）；对同一函数正确的 guard 对另一端可能是回归。要求把每个输入分支写成字面量 bulleted list 记入initial-review.md；cond/case/解构 shape/变参 arity 一视同仁。
• 寻找可触发的具体 bug：围绕逻辑与正确性（off-by-one、nil 处理、竞态、错误被吞、隐式类型转换）、边界（空集合、缺失/多余字段、Unicode 与超长串、并发重复请求）展开，并建立“困惑用户输入（数字字段填"banana"/"1e999"、全空白串、粘贴隐藏字符如零宽空格/智能引号、Integer.MAX_VALUE/NaN、重复提交、end<start）与恶意输入（SQL 注入、XSS、路径穿越、SSRF 指向169.254.169.254/file://、命令注入、模板注入{{7*7}}、同形字/RTLO、超大输入、CRLF 注入、跨租户 IDOR）两大类词典。规则是：每个用户可达输入至少各挑一类尝试；发现“前端校验了但后端没校验”即使当前无 UI 路径也要按API_ROBUSTNESS上报。
• 针对 Clojure 后端的健壮性清单：并发与线程安全（atom/agent/ref）、资源生命周期、依赖失败时的恢复、无界增长（队列/缓冲/重试）、事务语义（嵌套事务、savepoint、after-commit 回调）、大表上的迁移锁问题。
• 安全观测性：对每个新安全 guard 追问“它触发时在服务器日志里长什么样？”——若被阻断的攻击与普通网络抖动产生同一行日志，按GOOD_TO_FIX上报，并建议区分化的 WARN/ERROR 日志（含被阻断 URL）或独立 metric 计数器。
• 状态机回归的真值表：穷举相关状态组合对比新旧行为，且必须包含迁移行（“记录处于 A → 执行动作 X → 到 B”），不只列状态行。对“首次登录/首次 SSO 握手/首次同步”这类翻转 bit 的事件尤其警惕。
• Flag-writer census：新逻辑若以某字段值作为门控（如sso_source = :ldap），必须用 Grep 枚举该字段的所有写入方（t2/update!、t2/insert!、裸 SQL、resources/migrations/下的迁移）。若唯一写入方正是被门控的流程本身，该门控会制造bootstrap deadlock（存量记录永远无法进入“被放行”桶）——这按 SEVERE 上报。

每个 finding 都要记录：文件与行区间、类别、UI reachable 与否、描述、复现假设、置信度，写入initial-review.md。若没发现任何潜在 bug，则写入一句结论并直接跳到 Phase 4。

缺陷分级体系（贯穿 Phase 2 的关键规则）

Phase 3：动态复现问题

对 Phase 2 中置信度MEDIUM 及以上的每条 finding 做动态验证，同时把精力多花在 Phase 1 标记的未测试路径上。当改动用户可达时，优先通过 UI 复现——因为真实用户流程能告诉你用户会不会撞上、看到什么错误、UI 其他状态是否被破坏；REPL/API 复现最快但只是辅助证据。常用工具链：

• UI 问题：用 Playwright MCP 导航、操作、截图，关键节点分别存 baseline / after / error 三张图到{{OUTPUT_DIR}}/output/，文件名形如issue-01-before.png；每张截图前用browser_evaluate执行window.location.href记录当前 URL（含 query 参数），并写入文件名或作为附图说明。
• 后端/API 问题：一律走./bin/mage -bot-api-call（禁止裸curl，它会触发权限提示且需手工拼 URL），支持--api-key、--method、--body、--raw等参数；响应重定向到 stdout 存证：

  ./bin/mage -bot-api-call /api/user/current --api-key $ADMIN_API_KEY ./bin/mage -bot-api-call /api/<endpoint> --method POST --api-key $ADMIN_API_KEY --body '{"key": "value"}' ./bin/mage -bot-api-call /api/<endpoint> --api-key $ADMIN_API_KEY > {{OUTPUT_DIR}}/output/api-<name>.json

  -bot-api-call把诊断前缀打到stderr（GET /api/... (port 3000)、Status: 200），JSON 主体打到stdout，因此... | jq .email直接可用；不需要任何 stderr 输出时加--raw。

• 后端逻辑问题：用./bin/mage -bot-repl-eval '<form>'直接调函数、测边界（nil/空集合/类型强转）、验证 DB 状态（如(t2/select-one :model/Setting :key "some-key")）。wrapper 会自动发现后端（本地 nREPL、PR-env 下 socket REPL）并缓存到.bot/repl.env；不要直接调clj-nrepl-eval（它在 PR-env 模式会静默失败）。每条调用发一个顶层 form，多 form 用(do ...)包裹。

复现中建议对相关 namespace 提日志级别（(logger/set-ns-log-level! 'metabase.some-ns :debug)）→ 复现 → 捕获日志 → 复位。需要测启动行为或不同设置时用(dev/restart!)并等待健康检查通过。

每条 finding 最后要落一个动态状态并写入initial-review-results.md：

Phase 4：UX / 可用性评审

纯后端 diff 也必须做完整 UX 评审——后端改动可能透过 API 响应形状、错误流、权限、认证、查询变慢引发前端异常行为。评审路线：

1. 从 diff 定位受影响的 UI 页面/组件（直接前端改动，或经由 API 间接影响的）与行为发生变化的 API endpoint；
2. 复用 Phase 1 的测试覆盖分析，把 UX 实测火力集中在弱覆盖区域；
3. 按共享的 UX 评估清单（见 dev/bot/common/ux-evaluation-criteria.md）在浏览器中逐项核对：加载/错误态、表单校验提示、可访问性（aria、键盘导航）等；
4. 顺带记录做得好的部分——报告应保持平衡；
5. 每轮显著交互后用(logger/messages)或/api/logger/logs检查服务器日志里的意外报错、N+1 查询、被吞异常与可能引起 UI 卡顿的慢操作；
6. 证据（截图/API 响应/日志摘录）统一进{{OUTPUT_DIR}}/output/，评审结论写ux-review.md。

Phase 5：最终报告

写报告前先做一轮自我审计，即使当前 finding 列表为空也不能跳过（空列表恰恰是自我审计价值最高的时候）：

1. Bootstrap check：PR 读的每个状态，是否存在不经过被门控路径的写入方？没有则可能死锁。
2. Transition check：PR 保留不变的“before”状态是否只能作为通往被阻断状态的过渡点被触达？
3. Prohibition test check：对 PR 新增的“X 必须不发生”测试，重新推导它为何正确，是否误伤了合法用户旅程。
4. Rollout check：管理员把这个 PR 部署到有真实用户的存量实例后，会不会有某类用户立刻失去昨天还能做的事？说出具体用户类别。
5. Writer census check：对新代码读取的每个字段列出全部写入方，列表短于预期就重新审视门控。

随后读取initial-review-results.md与ux-review.md，产出report.md（结构模板见 dev/bot/qabot-agent.md 的 Phase 5 章节）：先写 Summary（含分支/commit/Linear issue/PR 信息与 2–3 段分支行为描述；若没有任何 actionable findings，Summary 要真诚地肯定代码质量），再按SECURITY>SEVERE>GOOD TO FIX>API ROBUSTNESS>SUSPECTED BUT UNCONFIRMED>TRIVIAL分组给出每条 finding 的复现步骤、代码引用（file:line）、截图/API 响应与影响评估，最后是 "What Works Well"。某分组无 finding 就整体省略该节，不写 "None found"。超过 100 行的 API 响应不内联，改为引用output/下的文件。

报告生成后转 PDF：

./bin/mage -bot-md-to-pdf {{OUTPUT_DIR}}/report.md

最终向用户展示report.pdf、report.md的绝对路径（若有 Phase 6 产物则还有fix-plan.md），并按“有无 actionable findings”二选一展示完成横幅与按类别的 finding 统计。

Phase 6：修复计划

只有报告存在SECURITY/SEVERE/GOOD_TO_FIX时才生成fix-plan.md（TRIVIAL不值得专项修复，全空则整阶段跳过）。计划按严重度排序，每条必须可执行：点名具体文件与函数、说明建议改什么、给出验证途径，并自包含到“只看本文件加代码库即可实施修复”的程度；报告末尾再引用fix-plan.md后重新生成 PDF。

输出目录与证据规范

整套工作流对“证据”的要求贯穿始终：

• 所有截图、API 响应 JSON、日志摘录、中间产物统一落在{{OUTPUT_DIR}}/output/与{{OUTPUT_DIR}}/tmp/（后者仅放 prompt 片段等中间文件）；
• 无证据不上报——每条 finding 必须有截图、API 响应或具体代码引用；
• 报告内嵌图片一律用相对路径且图注必须带完整 URL（含 query 参数），例如/question/42?filter=status — filter dropdown broken；
• 环境信息不硬编码：端口、凭据、API key 一律从./bin/mage -bot-server-info现场发现，实例首次启动时会经由配置文件自动建用户与 API key，无需手工/api/setup。

与 autobot / 远程 PR 环境的协同

/qabot的另一种形态是把它作为“内部命令”挂进 autobot 会话（.claude/commands/autobot.md）：/autobot <branch> /qabot会为分支创建独立 worktree、起好本地 dev 环境（tmux 面板跑后端 + 前端），再把/qabot当作会话提示词交给 Claude。autobot 会先为分支解析 PR 环境并做基础设施预检，然后同样以时间戳生成.bot/qabot/<TIMESTAMP>运行目录并调用 discover。若目标是PR 预览环境（https://pr<NUMBER>.coredev.metabase.com形态），则进入 remote 模式：没有本地数据库与前端，API 经-bot-api-call透明转发并自动刷新会话，REPL 走远程 socket REPL，重启后端不可能，破坏性测试（改site-url、删连接、清缓存等）需遵守“快照 → 变更 → 还原 → 确认”的模式，无法还原就不做动态复现、改记CONFIRMED_STATIC。这类预览环境仅限 Metabase Tailscale 网络可达，且通常与 PR 作者及其他 bot 会话共享，因此只读验证优先。

可复用的工程模式小结

从整套 QABot 工作流中可以提炼出几条放之四海皆准的“AI 合并前审查”模式：

1. 编排与执行分层：薄薄的 orchestrator 命令只负责建目录、收集上下文、渲染 prompt，厚重的评审方法论放在模板文件中按需{{FILE:}}注入，避免每个命令文件臃肿。
2. 运行隔离是底线：时间戳目录 + “一切产物必须落在本次目录 + 禁止共享路径”，让并发运行、审计归档都变得安全廉价。
3. 静态审查要“攻击优先”：anti-anchor（先写三条它为什么错）、把每条新禁止当作新需求并要求枚举被排除对象、区分输入分支而非只查调用方——这三招把审查重心从“确认作者没写错”扭转到“证明它没错”。
4. 分级避免信号淹没：SEVERE 只留给“升级会破坏真实用户既有流程”的回归，攻击者场景的难看错误归GOOD_TO_FIX，只有 API 可达的归API_ROBUSTNESS——让真正的严重问题不被卫生问题淹没。
5. 动态状态机让证据可比较：CONFIRMED / CONFIRMED_STATIC / SUSPECTED / NOT_REPRODUCED / BLOCKED让“试过、看到什么、差在哪”全程可追溯。
6. 报告与修复分离且各自自包含：只读守门人产出带完整复现步骤的分级报告，再生成另一 Agent 可直接执行的fix-plan.md，恰好呼应本仓库 fixbot/reprobot/uxbot 的分工体系——同一套.claude/commands/与dev/bot/家族还管理着/fixbot（修复已报告问题）、/reprobot（复现 issue）、/uxbot（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