Metabase Fixbot 自动化修复工作流解析从 Linear Issue 到代码修复、验证与提 PR 的完整链路【免费下载链接】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/metabaseFixbot 是 Metabase 仓库中为修复 Linear issue而设计的自动化 AI 工作流它以/fixbot斜杠命令为编排入口借助仓库内的 Claude Code 命令、dev/bot下的 Agent 提示模板以及mage的 bot 系列 CLI 命令完成问题上下文采集、Agent Prompt 生成、代码修复与自验、用户验收乃至 PR 提交流程。本文以 .claude/commands/fixbot.md 为主干结合其下游文件与mage源码实现说明这套工作流每一步做什么、为什么这样做以及每个命令与产物的真实形态供需要扩展或维护仓库开发工具链的读者参考。一、工作流定位在哪个环境下、修什么问题先明确 fixbot 的边界。编排命令的开头就定义了它的运行方式与约束You are the orchestrator for the fixbot workflow. Fixbot fixes a Linear issue, running directly in this project against the locally running server.也就是说fixbot 直接在当前仓库中运行针对一台本地已经启动的 Metabase 服务进行排障和修复而不是在隔离的临时环境中。如果希望把整个修复过程放进一个隔离的 git worktree独立的后端 前端则改用复合命令/autobot branch /fixbot args——autobot会先创建/复用 worktree、搭好开发环境再在会话里以/fixbot作为内部命令执行见 .claude/commands/autobot.md。在 Metabase 的机器人家族里fixbot 与 qabotQA 评审 PR、reprobot复现 bug 并产出失败测试、uxbotUX 评审并列分别对应修复、验收、复现与交互体验评估dev/bot/下与之配套的 Agent 模板包括 dev/bot/fixbot-agent.md 等公共操作手册则放在 dev/bot/common/environment-discovery、test-strategy、reproduction-strategies、report-generation 等fixbot 是这条自动化链路的实施者。1. 直接运行与 worktree 运行的选择运行方式触发命令运行环境适用场景直接运行/fixbot [args]当前仓库 本地已运行服务快速修复允许与开发中的工作区共享隔离运行/autobot branch /fixbot args独立 worktree 独立后端/前端需要干净分支、互不干扰的修复autobot 文档还支持 PR 预览环境形如https://prNUMBER.coredev.metabase.com的远程模式此时本机不启动服务bot 直接对接已部署的预览环境。二、Step 1生成每次运行的隔离目录Per-run Directory工作流的第一步是为本次运行分配独立的产物目录这是整套设计的地基生成时间戳格式固定为YYYYMMDD-HHMMSS如20260907-070155若无法确定当前墙钟时间运行./bin/mage -bot-timestamp获取——明确禁止直接用date命令定义两个变量并据此建目录TIMESTAMPYYYYMMDD-HHMMSS OUTPUT_DIR.bot/fixbot/TIMESTAMP紧接着执行mkdir -p OUTPUT_DIR保证后续所有cp/Write写入都能成功。设计要点有三条直接体现了多任务并发的可靠性考量本次运行产生的所有文件包括 discover 阶段工件都只能落在OUTPUT_DIR/下不允许出现跨运行共享的路径因为目录名带秒级时间戳同一仓库内多次/fixbot调用不会互相冲突严禁从上次运行的目录复制旧工件例如linear-context.txt上下文必须让 discover 重新生成避免把过期内容带进本次修复。这样的一运行一目录 全局唯一产物路径约定配合 mage/src/mage/bot/prompt.clj 中写入文件前自动mkdirs父目录的实现让每个阶段的文件操作都无须担心路径竞争。三、Step 2上下文收集——discover 阶段与 config.env当OUTPUT_DIR/config.env不存在时先执行 discover/fixbot-discover $ARGUMENTS --output-dir OUTPUT_DIRDiscover 把工件直接写入OUTPUT_DIR/从不写共享位置。随后编排者读取两份关键输入文件从中提取的内容OUTPUT_DIR/config.envISSUE_ID、BRANCH_NAME、APP_DBOUTPUT_DIR/linear-context.txt完整 Linear issue 内容注入 Agent 模板的LINEAR_CONTEXT3.1 fixbot-discover 的职责拆解.claude/commands/fixbot-discover.md 把上下文发现拆成六个子步骤① 解析 Issue ID。位置参数支持三种输入格式需归一化为 Linear issue IDLinear issue ID如MB-12345、UXW-3155——直接使用GitHub issue 编号如12345——先解析为 LinearGitHub issue URL——先抽取编号再解析为 Linear。GitHub 输入的解析路径是用gh issue view NUMBER --repo metabase/metabase --json body,comments,title拉取 issue在正文与评论里搜索 Linear 链接https://linear.app/metabase/issue/[A-Z]-[0-9]模式并抽取 ID找不到 Linear 链接时改用./bin/mage -bot-fetch-issue以 GitHub issue 标题派生搜索词直接搜索 Linear仍无匹配则明确告知用户并停止。ID 最终必须通过[A-Z]-[0-9]校验。② 解析运行目录。从$ARGUMENTS中提取--output-dir PATH缺失即停止并提示TIMESTAMP取路径尾部的时间戳段。③ 从 Linear 拉取 issue。执行./bin/mage -bot-fetch-issue ISSUE_ID读取输出中的 issue 详情与分支名并把完整输出写入OUTPUT_DIR/linear-context.txt。该命令的底层实现见 mage/src/mage/bot/linear.clj通过 GraphQLendpoint 为https://api.linear.app/graphql按 identifier 查询返回identifier / title / description / url / branchName / state / comments等字段API Key 通过 mage/src/mage/bot/env.clj 的共享解析函数获取。值得注意的是 linear.clj 内部把该命令记为-fixbot-fetch-issueusage 提示即./bin/mage -fixbot-fetch-issue MB-12345说明这套 bot CLI 在迭代中调整过命名新增命令时需以当前mage任务表为准。④ 确定分支名。优先取 Linear issue 输出中声明的分支若未指定则用 issue ID 小写化作为分支名例如MB-12345→mb-12345。⑤ 推断应用数据库。依据 issue 描述/评论内容从三个候选中选择一个提到MySQL问题、MySQL 专有 SQL 语法或错误信息 →mysql明确提到MariaDB→mariadb其他一律 →postgres默认。这一点之所以重要是因为 Metabase 支持 Postgres/MySQL/MariaDB 等不同应用数据库某些 bug 只在特定方言下复现bot 需要按正确数据库启动测试环境。⑥ 写结果。用结构化格式把五元组写入OUTPUT_DIR/config.envAPP_DBpostgres|mysql|mariadb BRANCH_NAMEbranch-name ISSUE_IDISSUE_ID TIMESTAMPTIMESTAMP OUTPUT_DIROUTPUT_DIRautobot 的编排逻辑里还有一层兜底读完 config.env 后若APP_DB缺失默认按postgres处理。这套配置文件即契约的约定让 discover 阶段与后续的 Agent 阶段通过文件解耦任何一方都能独立测试。四、Step 3用 mage 生成 Agent Prompt上下文齐备后编排者用mage的模板引擎从 Agent 提示模板渲染出本次运行专属的 prompt./bin/mage -bot-generate-prompt \ --template dev/bot/fixbot-agent.md \ --output OUTPUT_DIR/prompt.md \ --set ISSUE_IDISSUE_ID \ --set BRANCH_NAMEbranch-name \ --set APP_DBpostgres|mysql|mariadb \ --set OUTPUT_DIROUTPUT_DIR \ --set-from-file LINEAR_CONTEXTOUTPUT_DIR/linear-context.txt参数语义参数作用说明--template指定 Agent 提示模板指向 dev/bot/fixbot-agent.md必填且要求文件存在--output渲染产物路径写入OUTPUT_DIR/prompt.md必填--set KEYVALUE内联变量例如 ISSUE_ID、BRANCH_NAME、APP_DB、OUTPUT_DIR--set-from-file KEYpath从文件读入多行值LINEAR_CONTEXT内容通常很长且含换行直接内联需要繁琐的 shell 转义故用此方式按路径读取4.1 模板引擎源码级原理mage/src/mage/bot/prompt.clj 的generate-prompt!展示了渲染的实际行为必填参数校验--template/--output缺失即报错退出模板文件不存在同样退出先执行resolve-file-includes把{{FILE:path}}占位符替换为仓库根目录下对应文件的内容——只做一遍被包含的内容不会被再次扫描路径相对仓库根目录文件缺失时替换为!-- FILE NOT FOUND: path --并给出警告再用--set与--set-from-file合并出的替换表把{{KEY}}占位符逐一替换源码中是逐 key 执行str/replace因此替换后的值不会参与其他 key 的展开parse-set-args对缺少的--set项给出黄色警告并忽略parse-set-from-file-args对不存在的文件也仅警告并将值置为空串写入前.mkdirs自动创建父目录然后spit输出并打印Wrote prompt:。这样fixbot-agent.md 模板里的两类占位符——{{ISSUE_ID}}、{{BRANCH_NAME}}、{{APP_DB}}、{{LINEAR_CONTEXT}}这类变量占位符以及{{FILE:dev/bot/common/environment-discovery.md}}、{{FILE:dev/bot/common/test-strategy.md}}这类文件包含占位符——会在渲染时被统一替换最终产出一个自包含、可直接作为 Agent 系统提示的 prompt.md。这种模板 文件包含 运行时变量的结构让 agent 手册可以复用公共章节避免在多份模板间复制粘贴漂移。五、Step 4执行阶段——Agent 的任务模型与自主边界编排者随后读取渲染好的OUTPUT_DIR/prompt.md按其中的 Phase 1–4 顺序执行且要求所有阶段在同一个 turn 内完成除非触发 STOP 条件——不能在阶段之间停下来等用户。真正定义 Agent 行为的是提示模板 dev/bot/fixbot-agent.md其任务模型包含约束、阶段与安全边界三层。5.1 两条硬性约束20 分钟时间上限。Agent 若在 20 分钟内未能完成理解—修复—自检Phases 1–3必须立刻停下把已有的诊断、部分修复和阻塞点呈现给用户并请求指引——能说明自己卡在哪里的 fixbot远比一个默默绕圈烧时间的 fixbot 有价值。Know Your Limits。fixbot 只处理能自主完成的简单明确 bug 与功能请求遇到以下情况必须 STOP 并说明原因修复涉及复杂架构决策、存在工程师难以一致认同的取舍改动以难以察觉的方式影响既有功能如其他功能依赖的行为功能请求本身该不该做需要产品讨论issue 存在歧义不同解读会导向差异很大的方案修复横跨多个子系统、爆炸半径过大需要靠猜而不是靠把握来确定预期行为。模板还给出了一个沟通技巧任何需要用户输入、提问、停下决策、或必须让用户注意的节点都要用醒目的横幅框住示例为用╔═╗绘制的 FIXBOT NEEDS YOUR INPUT 风格 banner避免用户错过关键信息。5.2 六个执行阶段阶段目标关键动作Phase 1 Understand理解问题通读已注入的 LINEAR_CONTEXT不再重复 fetch充分搜索代码库理解 bug 周边架构涉及 UI 时用 Playwright MCP 复现产品行为歧义才问用户Phase 2 Fix修复严格 red/green TDD后端先写失败 Clojure 测试./bin/test-agent前端先写 Jest 单测或 Cypress E2E补上 issue 编号命名规范Phase 3 Self-Review自检改过的 Clojure 文件跑/clojure-review、TS/JS 文件跑/typescript-review逐个解决发现的问题有重大改动则复审直到干净Phase 4 Verify验证UI 修复先由 Agent 用 Playwright MCP 自查再把精确的验收步骤交给用户URL 一律用http://localhost:$MB_JETTY_PORT/...后端端口而非前端 dev server并提醒登录凭据来自./bin/mage -bot-server-infoPhase 5 Open PR提交用户确认后提交绝不提交.claude/、.bot/fixbot/、mage/下的改动逐个git add path/to/file.clj禁用git add ./-Acommit 与 PR 中严禁出现 Linear URL 或 issue ID内部信息不外泄PR body 用固定模板Description / How to verify / Checklist且不加 labelPhase 6 Monitor PR跟进提 PR 后用/cibot监控 CI 结果并处理失败直到通过值得注意的是模板环境章节特别说明开发环境始终是 Enterprise EditionEE即使 issue 说的是 OSS 版本也要在 EE 下开发测试若修复确实必须在 OSS 版验证例如 OSS-only 行为差异要停下告知用户而不是强行尝试 OSS-only 修复。同时关于用户画像的设定也约束了交互方式用户不是开发者不要向 TA 要实现建议或技术决策但 TA 是资深的 Metabase 产品用户可用于澄清预期行为与做 UI 验收。5.3 复现机器人(reprobot)协同模板还提供了与 reprobot 的协作路径若 issue 评论里包含 reprobot 的排查结论Linear 评论中的 patch 或测试代码可取来作为 TDD red 步骤的起点但模板同时告诫——reprobot 的分析与根因假设不总是正确必须对照真实代码自行验证。这与dev/bot/中 reprobot/qabot/fixbot 分角色协同的设计互为印证。六、支撑 Agent 运行的公共手册与 mage 基建被{{FILE:...}}注入到提示模板中的公共手册承载了 agent 实际操作的底层能力6.1 environment-discovery环境发现与免硬编码dev/bot/common/environment-discovery.md 规定了一套先发现、后使用的原则核心是./bin/mage -bot-server-info——它会一次性输出 Jetty 后端端口、前端 dev server 端口、nREPL/socket REPL 端口、数据库端口、配置文件路径与内容、环境变量与 edition/token/连接 URI。严禁硬编码端口、凭据与 API key一律从-bot-server-info动态获取。配套的 mage 实现包括-bot-repl-eval clojure-form——统一 REPL 入口自动在 nREPL 与 socket REPL 间回退见 mage/src/mage/bot/repl_eval.clj-bot-api-call /api/path [--method ...] [--api-key ...] [--body ...]——API 调用封装见 mage/src/mage/bot/api_call.clj-bot-preflight-health——轮询健康检查最长 5 分钟的后端就绪探测见 mage/src/mage/bot/preflight.clj环境变量解析优先级mise.local.toml .env .lein-env 系统环境变量见 mage/src/mage/bot/env.clj。该手册同时强调数据库操作应通过 REPL Clojure JDBCToucan2进行如./bin/mage -bot-repl-eval (do (require (quote [toucan2.core :as t2])) (t2/select :model/Card :id 1))而不是在 shell 里直接跑psql/mysql日志访问可通过metabase.logger.core的(logger/messages)最近 250 条与set-ns-log-level!动态调整级别此外还有 Playwright MCP 工具装载、fail-fast 策略、远程 PR 环境模式Tailscale 依赖、通过 API 而非本地库访问数据、破坏性测试先快照再回滚等约束。6.2 test-strategy测试类型选型与命令dev/bot/common/test-strategy.md 提供测试选型矩阵后端逻辑/查询处理器/API 用 Clojure 单测test/metabase/...前端 UI 行为用 Jest 组件测试co-located*.unit.spec.tsx端到端用户流程用 Cypresse2e/test/scenarios/...混合改动则两者都写。文件命名有固定规律src/metabase/foo/bar.clj→test/metabase/foo/bar_test.clj。运行命令示例./bin/test-agent :only [metabase.foo-test/issue-12345-test] bun run test-unit-keep-cljs path/to/file.unit.spec.ts npx cypress run --spec e2e/test/scenarios/category/file.cy.spec.ts测试命名还要求带上 issue 号如(deftest issue-12345-test ...)让自动化修复的测试可以追溯到原始工单。6.3 状态与结果汇报为了让用户在长任务中保持知情agent 要维护两个文件.bot/autobot/llm-status.txt1–3 行的状态栏如 Reproducing issue/Writing tests/Blocked: ...以及OUTPUT_DIR/result.md——后者由/autobot-result branch bot读取展示格式为已完成 / 当前状态两段式摘要加一份不断追加的绝对路径产物清单diff 分析、截图、API 响应、日志抓取等。七、完整命令速查下面是整套 fixbot 工作流涉及的触发命令与 CLI便于对照使用位置命令用途编排入口/fixbot issue直接在当前仓库修复 Linear issue隔离运行/autobot branch [from base] /fixbot issueworktree 内修复上下文发现/fixbot-discover issue --output-dir dir解析 issue、推断 APP_DB、写 config.env时间戳./bin/mage -bot-timestamp生成YYYYMMDD-HHMMSS禁止用date拉取 issue./bin/mage -bot-fetch-issue ISSUE_IDLinear GraphQL 拉取 issue 详情渲染 prompt./bin/mage -bot-generate-prompt --template dev/bot/fixbot-agent.md --output ... --set ... --set-from-file ...生成自包含 Agent 提示环境发现./bin/mage -bot-server-info端口/凭据/API key/环境变量一站式输出REPL./bin/mage -bot-repl-eval formnREPL/socket 自动回退求值API./bin/mage -bot-api-call /api/...免手工鉴权的 HTTP 调用健康检查./bin/mage -bot-preflight-health后端就绪轮询最长 5 分钟测试./bin/test-agent/ Jest / Cypress后端/前端/E2E 测试八、小结这套编排设计的可取之处从仓库实现回看 fixbot 工作流可以提炼出四个值得借鉴的设计点文件即接口、目录即隔离discover 与执行阶段通过config.env和 per-runOUTPUT_DIR解耦秒级时间戳保证并发安全禁止复制旧工件杜绝了上下文过期问题模板 文件包含 变量mage -bot-generate-prompt的{{FILE:path}}机制让 agent 公共手册可以在多份 bot 模板间复用单一事实来源避免各 bot 行为漂移明确的时间预算与决策边界20 分钟硬上限、Know Your Limits 的 STOP 清单把自主执行限定在低风险修复内把架构取舍与产品歧义交还人类安全与卫生红线不提交.claude/、.bot/、mage/等生成/拷贝目录逐文件 stagePR 与 commit 零 Linear 内部信息敏感信息不落公开历史。对希望基于 .claude/commands/fixbot.md 理解或扩展这套机器人修复 issue基础设施的读者建议按 .claude/commands/fixbot-discover.md → dev/bot/fixbot-agent.md → dev/bot/common/environment-discovery.md 的顺序阅读并结合 mage/src/mage/bot/prompt.clj 与 mage/src/mage/bot/linear.clj 等实现逐行对照即可获得从编排命令到底层 CLI的完整视角。【免费下载链接】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），仅供参考