Metabase 开源仓库 autobot 会话停止操作指南：理解 `./bin/mage -autobot-stop` 的机制与正确用法

Metabase 开源仓库 autobot 会话停止操作指南：理解./bin/mage -autobot-stop的机制与正确用法

【免费下载链接】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 仓库内机器人自动化开发（autobot）工具链中的"会话停止"环节。autobot 会为每个任务创建独立 git worktree、开发环境与 tmux 会话，而本文要讲清楚如何只停止运行环境、保留工作区（kill tmux and dev environment, but keep the worktree），涵盖./bin/mage -autobot-stop的命令用法、两种调用形态、错误分支处理，并结合 autobot.clj 源码剖析其底层执行链。读完你将掌握安全终止 autobot 会话的标准操作，并能区分-autobot-stop与-autobot-kill的边界。

一、autobot 会话的生命周期与 stop 的定位

Metabase 仓库的 autobot（见.claude/commands/autobot.md）是一个为开发机器人（如 qabot、fixbot、reprobot 等）提供"隔离执行环境"的会话管理工具。一次/autobot <branch> /<command>调用会：

1. 基于分支创建（或复用）一个独立 git worktree；
2. 在 worktree 中配置开发环境与正确的应用数据库；
3. 在 tmux 的多个窗格中启动 backend / frontend 开发服务；
4. 将内层命令作为 prompt 启动 Claude 执行任务。

会话生命周期由 mage/src/mage/bot/autobot.clj 统一管理（该命名空间的注释即 "Unified autobot session management — launch, stop, list, kill"），对外暴露四类操作命令：

stop是"暂停/收工"语义而非"销毁"语义：代码与 worktree 原样保留，之后可用/autobot直接重启复用。仓库内的/autobot-stopslash 命令文档即.claude/commands/autobot-stop.md，它定义了一个重要执行约束——stop 必须让底层 mage 命令自行完成一切，不得预判。

二、标准用法：一个命令完成停止

autobot-stop文档定义的核心调用方式非常简单——在你希望停止会话的当前工作目录内直接执行：

./bin/mage -autobot-stop $ARGUMENTS

关键约束有两条：

• 不要cd到别处：./bin/mage从任意 worktree 都能工作；而无参数形式依赖"当前就在待停止的 worktree 内"这一前提。从源码看，-autobot-stop对当前目录的判断是基于git rev-parse的（详见下文第三节），因此必须在目标会话的 worktree 内或提供会话名。
• 不要预先运行-autobot-list再让用户挑选：文档明确要求 "Do NOT preemptively run-autobot-listand ask the user to pick"，直接把用户给的名字（或空参数）传给-autobot-stop并展示输出即可。

$ARGUMENTS是可选的，mage 命令会自行处理两种情形：

对 Agent（Claude Code）而言，文档强调执行后必须向用户展示命令的完整 stdout+stderr，包括成功输出与所有错误信息，不要做任何截断或转述。

三、stop!的底层实现：先停开发环境，再杀 tmux

-autobot-stop的实际逻辑在 autobot.clj 的stop!函数。核心调用链如下：

(defn stop! "Stop a session (kill tmux + dev env, keep worktree). Works with a session name argument, or detects current session if no args." [{:keys [arguments]}] (let [session (resolve-session-name (first arguments)) wt-path (worktree-path session)] ;; 1. 停止开发环境 (when (and wt-path (seq wt-path)) (println (c/yellow "Stopping dev environment in " wt-path "...")) (shell/sh* {:quiet? true :dir wt-path} "./bin/mage" "-bot-dev-env" "--down")) ;; 2. 杀掉 tmux 会话 (println (c/yellow "Stopping tmux session: " session "...")) (shell/sh* {:quiet? true} "tmux" "kill-session" "-t" session) (println) (println (c/bold (c/green "Session stopped: ") (c/cyan session))) (println (c/yellow "Worktree preserved. Use /autobot to restart."))))

整个stop只做两件有序动作：

1. 关闭 dev 环境：先解析出会话对应的 worktree 路径，然后在 worktree 内执行./bin/mage -bot-dev-env --down。该子命令在 dev_env.clj 中负责清理为 worktree 分配的 Docker 服务与占用的开发端口（dev 环境的端口分配机制见port-bases：jetty 3000、frontend-dev 8080、postgres-app 15432、nrepl 50605 等，均基于 worktree 名计算 slot 0-99 后偏移）。若 worktree 路径无法解析，这一步会被安全跳过。
2. 杀掉 tmux 会话：执行tmux kill-session -t <session>，回收承载 backend、frontend 与 Claude 的 tmux 会话。

成功后输出Session stopped: <session>与Worktree preserved. Use /autobot to restart.——后半句正是"环境已停、代码仍在"语义的直接体现：此后用/autobot再次发起同一分支任务时会命中"已有 worktree → relaunch"路径（go!中通过find-session+worktree-path判断后走relaunch-existing-session!），而不会重复新建 worktree。

会话名解析：参数优先，路径探测兜底

stop!的第一步是resolve-session-name（autobot.clj），它实现了文档中描述的"带参数/不带参数"双路径：

• 带会话名：调用find-session进行匹配——先对workmux list输出的 worktree 名做大小写不敏感的精确匹配；若无精确命中，再退化为对原始行的子串匹配。两者均失败则打印红色错误No session found matching: ...，随后输出Available sessions:列表（print-available-sessions!），最后以退出码 1 结束。
• 不带参数：调用detect-current-session自动探测。其实现不依赖 workmux（它没有current子命令），而是通过两条 git 命令判断当前位置：
  1. git rev-parse --show-toplevel得到当前 worktree 绝对路径；
  2. git rev-parse --git-common-dir得到主仓库路径（linked worktree 下指向共同仓库）；
  3. 二者相同 → 处于主仓库 → 返回 nil（此处没有活跃会话）；
  4. 二者不同 → 取 worktree 路径的 basename 作为会话名（autobot 始终以会话 slug 命名 worktree）。

若两者都无法确定会话，则打印红色错误No session name provided and not inside a session.，并给出 usage 提示：

Usage: ./bin/mage -autobot-stop <session-name> (or run from inside a session with no arguments)

随后以非零码退出——这解释了为何文档要求"无参数调用必须在待停止的 worktree 内执行"。

四、易错点与边界处理

综合.claude/commands/autobot-stop.md与源码实现，实际使用中需注意以下几点：

• 主仓库内直接-autobot-stop会报 usage 错误：因为detect-current-session判断调用者处于主仓库（非 worktree）时返回 nil，命令无法确认目标会话。此时必须显式传入会话名。
• 传错会话名不会误杀：find-session匹配失败时命令在杀掉任何 tmux 会话之前就以非零码退出，并贴心打印可用会话列表供参考，属于安全失败（fail-safe）设计。
• 会话名来源：会话名并非任意字符串。autobot 启动时由branch-to-session-name（autobot.clj）把分支名小写化、将非字母数字字符替换为-、压缩连续-、截断到 40 字符并去除首尾-得到（如feature/my-branch→feature-my-branch）。想要确认确切名称时，可直接查看workmux list或/autobot-list的输出，而不是猜测。
• stop 不会删除任何代码：它会保留 worktree、.bot/产物（各机器人输出目录、result.md等）与 prompt 内容，以便后续重启或通过/autobot-result检索执行结果。
• 与/autobot-kill的区别：kill!（autobot.clj）执行的是workmux remove -f <session>+tmux kill-session -t <session>，即连 worktree 一并删除。因此：临时收工用-autobot-stop，彻底清理任务现场用-autobot-kill。
• 启动冲突保护：若目标会话仍在运行，go!会拒绝重复启动并提示 "Stop it first with: /autobot-stop "（见 autobot.clj）——可见 stop 也是"重入会话"前的必要前置步骤。

五、与周边命令的协作流程

在 Metabase 仓库的机器人开发工作流中，autobot-stop 通常出现在这样的闭环中（可对照.claude/commands/autobot.md中的 Report 步骤）：

1. /autobot <branch> /<inner-command>启动会话；
2. tmux attach -t <session-name>附着观察执行进度；
3. 任务收尾后用/autobot-stop <session-name>（或在会话 worktree 内直接/autobot-stop）停止 tmux 与 dev 环境；
4. 需要查看产出时用/autobot-result <branch> <bot>读取该会话最末的result.md；
5. 全部完成、确认不需要该工作区后，再用/autobot-kill <session-name>清理 worktree。

对底层 mage 命令而言，对应关系为-autobot-go、-autobot-stop、-autobot-result、-autobot-list、-autobot-kill，全部以./bin/mage为入口，从仓库任意 worktree 目录执行即可（mage 子命令与任务分发的详细机制可从 mage/src/mage 目录继续深入，bot 相关逻辑集中在 mage/src/mage/bot 下）。

小结

Metabase 仓库的 autobot 会话管理把"运行状态"与"工作成果"解耦：-autobot-stop精确地只停止前者——先通过./bin/mage -bot-dev-env --down回收 worktree 内的开发环境，再用tmux kill-session终止运行载体，而 git worktree 与.bot/产物原样保留。理解其"参数精确匹配优先、worktree 路径探测兜底"的会话解析策略与 fail-safe 的错误处理，就能在自动化机器人开发中安全、快速地管理任意数量的并行任务会话。

延伸阅读：可在仓库内继续阅读会话启动文档.claude/commands/autobot.md、列表命令.claude/commands/autobot-list.md、彻底清理命令.claude/commands/autobot-kill.md，以及统一会话管理的核心源码 mage/src/mage/bot/autobot.clj。

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