Baton

Baton

从任意编码 Agent 启动、热重载、检查和截图你的应用。
Flutter、Next.js、Vite、React Native / Expo，以及原生 iOS 和 Android 应用，均可通过终端、Baton 应用或任意 MCP 客户端操作。

网站 · 设置你的 Agent · Agent 说明 · PDF 指南 · Token 研究 · 更新日志

Baton 是一个本地守护进程，用于管理正在运行的应用，并提供 MCP 服务和 CLI。你的 Agent 可以在模拟器或浏览器中启动应用，每次编辑后调用一次 check_change，只获取新增内容：重载结果、错误行、失败请求和截图，并给出 OK / NOT OK 判定。你可以在终端、Baton 应用以及 Claude Code 提示词上方的横幅中查看相同的运行记录，并使用相同的按钮。Baton 会读取你已有的 .vscode/launch.json、package.json、pubspec.yaml、Xcode 和 Gradle 项目。

0.2.10 是面向开发者的公开预览版。 如果遇到问题或有想要的功能，请提交问题。

快速开始

运行应用的机器需要安装 Node.js 24+。支持 macOS、Linux 和 Windows。

npm install -g baton-run
baton setup          # adds Baton to every coding agent installed on this machine

重启你的 Agent（或开启新聊天），并让它“运行应用并给我看一张截图”。

其他接入方式：

方式	命令
Claude Code 插件	/plugin marketplace add kanumuri9593/Baton 然后 /plugin install baton@baton
Codex 插件	codex plugin marketplace add kanumuri9593/Baton 然后 codex plugin add baton@baton
VS Code 或 Cursor，一键安装	本页面顶部的安装按钮
VS Code MCP 扩展库	在扩展视图中搜索 @mcp baton（GitHub MCP Registry 条目）
MCP 服务，无需安装	将 npx -y baton-run 用作服务命令（固定版本可用 [email protected]）
固定版本的 GitHub 安装	npm install -g github:kanumuri9593/Baton#v0.2.10
从源代码安装	git clone https://github.com/kanumuri9593/Baton.git && cd Baton && npm install && npm run build

baton setup 只会编辑各工具配置中的 baton 条目，为它更改的每个文件保留 .baton-backup 备份，并且可以安全地重复运行。baton setup cursor codex 只会对这些工具进行设置，--dry-run 可预览更改，--remove 可撤销设置。

适用于任何使用 mcpServers 配置块的 MCP 客户端：

{
  "mcpServers": {
    "baton": { "command": "npx", "args": ["-y", "[email protected]"] }
  }
}

Agent 工作循环

inspect_project → boot_device → run_target → wait_for → edit → check_change → fix → check_change

1. 使用 inspect_project（和 list_targets），并将 cwd 设为项目的绝对路径。
2. 如果没有模拟器或仿真器在运行，则使用 boot_device。如果未指定名称，它会列出可以启动的设备。
3. 运行 run_target；如果是 API 和前端组合，则运行 run_workflow，然后调用 wait_for。wait_for 最长可等待 15 分钟，足以完成首次原生构建。
4. 每次编辑后，都调用 check_change。它会应用编辑内容（Flutter 使用热重载，Web 和 React Native 使用 HMR，原生应用和普通进程则会重启），并且只返回发生变化的内容。

NOT OK  console/storefront  action=none  status=running  2280ms
new errors (1):
  [vite] Internal server error: Unexpected token (14:2)

Flutter 重载失败时会返回编译器错误，而不只是 DevFS synchronization failed：

lib/main.dart:419:19: Error: Expected ';' after this.

截图支持 iOS 模拟器、Android 设备和 Web 应用。对于 Web，Baton 会在一次性无头 Chrome、Edge 或 Brave（或 BATON_CHROME）中打开会话 URL，视口可设为 phone（真实的 390×844 移动端布局）、tablet、desktop 或 WIDTHxHEIGHT。Web 截图默认使用 1× 缩放，因此手机截图为 390×844（对模型来说约为 430 个图像令牌）；需要查看细节时可传入 scale: 2（--scale 2）。使用 screenshot: false 调用 check_change 时只返回文本，但仍会加载 Web 页面，因此页面控制台错误仍会被统计。模拟器和设备的截图会按设备自身分辨率返回。

Baton 会启动应用并报告证据，但不会点击界面或判断截图：捕获成功表示图像已写入，并不代表屏幕显示正确。需要进行交互的流程可搭配 Playwright MCP、Chrome DevTools MCP 或设备控制 MCP 使用。

29 个工具： inspect_project、list_targets、list_sessions、list_checkouts、list_devices、boot_device、run_target、run_workflow、check_change、hot_reload、hot_restart、stop_session、forget_session、wait_for、read_logs、session_summary、screenshot、set_debug_flag、diagnose、list_network_requests、get_network_request、clear_network_requests、read_launch_config、write_launch_config、run_proof、list_proofs、list_run_history、show_dashboard 和 dashboard_action（在支持 MCP Apps 的宿主中，show_dashboard 绘制的实时卡片上的按钮）。每个工具都带有 MCP 提示，因此遵循这些提示的客户端可以跳过对 16 个只读工具的提示词。

支持的 Agent

Agent	baton setup id	指南
Claude Code（终端、桌面应用、VS Code）	claude（安装插件）	docs/clients/claude-code.md
Codex	codex	docs/clients/codex.md
Cursor	cursor	docs/clients/cursor.md
VS Code（GitHub Copilot Agent 模式）	vscode	docs/clients/vscode.md
Antigravity	antigravity	docs/clients/antigravity.md
Gemini CLI	gemini	docs/clients/gemini-cli.md
Windsurf	windsurf	docs/clients/windsurf.md
Claude Desktop（聊天）	仅限手动配置	docs/clients/claude-desktop.md

不支持 MCP 的 Agent 可以调用同一个 CLI。每条命令在失败时都会以非零状态退出，而 baton check <session> --json 会给出与 check_change 相同的判定结果。Agent 完整说明： AGENTS.md。爬虫摘要：llms.txt。

可分享的可打印指南：快速入门、 Agent 设置指南和 常见问题。

在 Claude Code 中：Baton 栏

只要有任务正在运行，插件就会在提示词上方显示 Baton，无论是在终端还是桌面应用中。 每个运行任务占一行，显示其设备或 URL、状态、CPU 和内存，以及图标按钮：

按钮	功能
☰	显示或隐藏该运行任务下的近期日志
🐞	调试：让 Claude 读取运行任务的错误和日志，修复原因并执行 check_change
▶	播放：热重载（或重启）正在运行的应用、恢复已暂停的应用，或在运行结束后重新运行
⏸	暂停应用（macOS）
⏹	停止。运行结束后，此按钮会变为 ✕，用于关闭
⧉	将该运行任务自己的模拟器窗口（或网页）置于前台（macOS）

标题栏中有 ＋（新建运行任务：在提示词中填入 /baton:run ），以及可一次性控制所有运行 任务的 ▶ ⏸ ⏹ ⧉。点击 Bring all 会将所有设备的窗口置于前台。/baton 会在侧边窗格中 打开同一个工作区，并显示更长的日志。栏和窗格读取的是与 MCP 工具相同的守护进程，因此由 Claude、CLI 或 Baton 应用启动的运行任务都会显示在所有位置。详情： docs/clients/claude-code.md。

支持情况

框架	热重载（保留状态）	重启	说明
Flutter / Dart	✅ 真正支持，通过守护进程协议实现	✅ 热重启	设备、DevTools、调试标记、屏幕截图（也支持 Flutter Web）
Next.js、Vite、Nuxt、Astro、Remix、Angular、CRA	保存时自动触发 HMR	✅ 重启开发服务器	检测实际 URL 和就绪状态；支持手机、平板和桌面截图
React Native / Expo	自动触发 Fast Refresh	✅ 向开发客户端广播重新加载	与 Metro 的消息套接字通信
原生 iOS（Xcode）	—	✅ 重新构建、重新安装并重新启动	为所选模拟器构建、安装、启动、跟踪日志并截图
原生 Android（Gradle）	—	✅ 重新构建、重新安装并重新启动	执行 installDebug，启动启动器 Activity，跟踪 logcat 并截图
其他任何项目	—	✅ 终止并重新启动	任意 launch.json 或 package.json 脚本

如实报告功能。Vite 会话不会声称支持 Flutter 那种有状态的热重载，因此控制面板会将该按钮 置灰，Agent 也会收到明确的拒绝提示，而不是静默无操作。

目标的来源

Baton 会读取你已有的配置，无需新建配置文件。

• .vscode/launch.json：只读取，不做修改，因此你的 IDE 可以照常工作
• .claude/launch.json：格式相同
• package.json：dev、start、serve 和 storybook 脚本，包管理器根据你的锁文件确定
• pubspec.yaml：没有 launch.json 的 Flutter 项目也会获得默认配置
• Xcode：.xcodeproj / .xcworkspace、共享 scheme、Podfile 或 Package.swift
• Gradle：settings.gradle(.kts)、wrapper、应用模块或单独的 AndroidManifest.xml

单独选择嵌套的 ios/ 或 android 文件夹时，它会被视为原生目标。选择 Flutter 或 React Native 根目录时，运行的仍是框架本身，这样才能进行热重载。原生会话会在你 选择的设备上构建、安装并启动应用，然后跟踪应用日志。重启会重新构建并启动应用。

baton init 会根据检测结果写入 .vscode/launch.json（使用 --claude 则写入 .claude/launch.json）。小型启动配置示例请参见 examples/。

CLI

baton list                                  # every target, and where it came from
baton run "iOS Simulator (DEV)"             # names match on any unambiguous substring
baton run "iOS Simulator (DEV)" --branch origin/main
baton ps                                    # what's running
baton logs dev -f                           # follow output
baton check webapp --viewport phone         # did my edit break anything?
baton reload --all
baton stop --all
baton devices --all                         # connected devices, plus every one you could boot
baton boot "iPhone 17 Pro Max"              # start a simulator that isn't running
baton add ~/code/storefront                 # watch another project too
baton doctor                                # sources, blockers, nested projects, guidance
baton app                                   # the control panel

baton help 会列出所有命令。

同时运行多个应用和项目

按依赖顺序启动 API 和控制台，只需一次调用：

baton workflow examples/workflow-lab/workflow.json

结果包含会话 ID、就绪状态、URL 和重点错误。MCP Agent 使用 run_workflow。试试无需依赖的双项目交付实验。

守护进程不绑定到某个目录。baton add <path> 会跟踪另一个项目；控制面板随后会为 每个项目显示一个侧边栏，并提供 All。会话 ID 按项目区分（storefront/npm-dev、 api/npm-dev），因此两个项目都可以有一个 npm dev。会话由守护进程管理，因此关闭 终端不会停止应用。

尚未启动的设备

connected
  ● iPhone 17 Pro                48F0A0D1-…  ios (emulator)
  ● sdk gphone16k arm64          emulator-5556  android (emulator)

bootable
  ○ iPhone 17 Pro Max            3237F94B-…  ios  iOS 26.5
  ○ iPad mini (A17 Pro)          51470177-…  ios  iOS 26.5
  ○ Pixel 10 Pro                 Pixel_10_Pro  android

Flutter 的模拟器列表会将所有 iPhone 和 iPad 合并成一个条目，因此 Baton 会直接询问 simctl。 baton boot "iPad mini" 会启动一台设备，等待 Flutter 能够识别它，然后打印可用于运行的 设备 ID。

无需切换 Git 分支

选择本地或远程分支后，Baton 会在 ~/.baton/worktrees 下创建 Git 工作树，将你文件夹中的 密钥和配置复制过去（不包括 build/ 或 node_modules），并从副本运行。你的分支、暂存 内容和编辑器都不会变动。也可以附加已有的工作树（即 Agent 已在编辑的文件夹），热重载 也会跟随该文件夹。

baton run "iOS Simulator (DEV)" --branch origin/main
baton run "iOS Simulator (DEV)" --checkout ~/wt/agent-a
baton checkouts

启动前检查

配置通常会引用被 Git 忽略的文件。Baton 会先检查，并在启动前拒绝运行：

✗ "iOS Simulator (DEV / dev flavor)" cannot run yet:
  missing config/secrets.local.json — copy config/secrets.local.template.json to config/secrets.local.json

baton list 也会以相同方式标记被阻止的目标。--force 会忽略检查并继续运行。

跨设备获取证据

baton proof "Local lab" --branch main --devices "iPhone 17 Pro" --appearance light,dark

证明包包含日志、截图和网络摘要。请参见启动和验证指南，并从 无需凭据的 Flutter 实验开始。

后端跟踪

Node 启动目标可以设置 "batonTrace": true，以获取本地 OpenTelemetry HTTP/HTTPS 和 fetch 元数据。baton diagnose（以及 MCP diagnose）会返回各会话中有限的错误摘要； baton diagnose <trace-id> --all 则会跟踪一个请求在多个 Node 项目间的情况。请参见 本地后端跟踪。

The Baton 应用

baton app

每个会话占一行，紧凑显示状态、重新加载／重启／停止、日志，以及应用 URL 和 DevTools 的链接。按 r 可热重载当前视图中的所有内容，按 R 可热重启。没有 App Store 下载版本。

• macOS：原生浮动启动器和菜单栏项目。它会始终显示在全屏终端上方，不会窃取焦点，菜单栏项目还会显示当前运行的会话数。首次使用时，会从 hud/ 中的源代码编译小型 AppKit 宿主，需要 Xcode 或 Command Line Tools；如果没有这些工具，Baton 会在浏览器中打开。
• Linux 和 Windows（或使用 baton app --browser）：在类似应用的浏览器窗口中打开相同页面，由守护进程通过 loopback 提供服务，不会发出外部请求。

设置：docs/app-settings.md。baton hud 仍是兼容性别名。

工作原理

.vscode/launch.json ─┐
package.json  ───────┤
pubspec.yaml  ───────┼─► detect ─► daemon ─► one session per target
Xcode / Gradle  ─────┘                │       (flutter | web-dev | react-native | ios | android | process)
                                      │
                     WebSocket + POST /rpc on 127.0.0.1
                          ├── Baton app  (native panel on macOS, browser elsewhere)
                          ├── baton      (any terminal)
                          └── baton-mcp  (any agent)

所有会话均由一个守护进程管理，因此在终端中启动的会话也会显示在控制面板和你的 Agent 中。守护进程绑定到 127.0.0.1，并写入 ~/.baton/daemon.json（模式为 0600），其中包含端口和令牌；客户端会读取这些信息并进行身份验证。

对于 Flutter，会话是 flutter run --machine 子进程，每个控制操作都是在其文档化 JSON 协议上发送的一个请求（app.restart、app.stop、app.callServiceExtension）。支持 FVM：如果项目通过 .fvm/flutter_sdk 指定了 SDK，就会使用该 SDK。详见 docs/architecture.md。

状态

截至 0.2.3，已在包含 3,692 个库的大型生产级 Flutter 应用上测试：热重载耗时 87 ms，热重启耗时 359 ms，可同时运行三个模拟器，并可在同一控制面板中并排管理三个项目（Flutter、Vite 和纯 worker）。Flutter 适配器功能最完整。Web 和 React Native 适配器支持运行、重启、查看日志和检测 URL。

故障排除

• ERR_UNSUPPORTED_NODE_MODULES_TYPE_STRIPPING：你使用的是旧版 [email protected]。运行 npm uninstall -g baton-run && npm install -g baton-run。
• Agent 看不到 Baton：运行 baton setup 后重启应用或打开新聊天，然后查看 docs/clients.md 中对应工具的指南。
• Web 截图失败：安装 Chrome、Chromium、Edge 或 Brave，或将 BATON_CHROME 设置为浏览器可执行文件的路径。
• 其他问题：运行 baton doctor，或在 Claude Code 中运行 /baton:doctor。

未固定版本的 github:kanumuri9593/Baton 会跟随 main。建议使用 #v0.2.10，或运行 npm install -g baton-run。

参与贡献

npm install
npm test          # portable tests, no simulator required
npm run typecheck

请参阅 CONTRIBUTING.md。如需报告安全问题，请按照 SECURITY.md 中的说明私下联系。此项目遵循行为准则。

应用图标和矢量标记位于 assets/；运行 npm run icons 可生成各种常见尺寸的 PNG，以及 macOS .icns 文件。

许可证

MIT。由 Yeswanth Varma Kanumuri 编写并维护。