switch-use：让 AI agent 操作真实的任天堂 Switch

我让 Claude Code 帮我查《集合啦！动物森友会》为什么打不开。它自己回到 HOME，翻完"所有软件"，进系统设置的"软件的详细管理"，最后告诉我：主机上只剩 508 MB 的更新数据，本体没了，所以系统要我插卡。

全程我没碰手柄。干这件事的是 switch-use，一个约 1 MB 的 Rust 命令行工具，开源。

动森的数据管理页：只有主机内存 66.6 MB 和 SD 卡 441 MB 两份更新数据，合计 508 MB

它怎么连上 Switch

主机要跑大气层（Atmosphère），装上 sys-botbase 这个系统模块。sys-botbase 在主机上开一个 TCP 6000 端口，收一行一行的文本命令：按键、摇杆、触摸、截图。switch-use 就是这个协议的客户端，电脑和主机在同一个 Wi-Fi 下就行，不用数据线，也不用常驻进程。

curl -fsSL https://raw.githubusercontent.com/leeguooooo/switch-use/main/install.sh | sh
switch-use discover    # 扫局域网，找到主机后记住地址
switch-use status      # 电量、sys-botbase 版本、正在运行的游戏

Switch 没有无障碍树，就用 OCR 补

我之前做过 iphone-use。iPhone 有无障碍树，每个按钮的文字和坐标都能直接读出来，agent 读文字就能操作。Switch 系统不对外提供这一层，sys-botbase 能给的只有截图。

所以 switch-use 在 Mac 上用 Apple 的 Vision 框架识别截图，把每一行字和它的中心点列出来。坐标就是触摸坐标，可以直接点：

text

$ switch-use elements
[1] 集合啦！动物森友会  (425,64)
[4] 软件信息  (240,192)
[9] 数据管理  (240,351)
[18] 确定  (1085,685)

在这之上有三个命令，都是照着 iphone-use 的用法做的：

tap 数据管理：找到这段文字就点。屏幕上有几处同名的，会列出来让你挑；找不到就给出最接近的几个。
wait 继续 和 press A see:继续：等某段文字出现再往下走，不用写死 sleep 1.5。
--observe：加在任何操作后面，操作完等画面稳定，直接返回新画面的文字。agent 少一次单独读屏。

中文、日文、英文都能认。游戏里的像素字体和封面图认得很差，这些结果会标一个问号。

真机上踩到的坑

HOME 键是个开关。 主机已经在 HOME 时再按一次，会切回正在运行的游戏。我第一版的 home 就是直接按，测试时把《魂斗罗》切了出来。现在 home 会先用 OCR 看右上角有没有时钟（只有 HOME 菜单显示时钟），已经在 HOME 就什么都不按。

画面切换时按键会被吞。 我用 DRIGHT*12 想把光标移到"所有软件"，结果几下右键丢了，A 按在了《坦克大战》上。另一个游戏还开着，系统弹出"将关闭正在运行的软件"，焦点还正好停在"关闭"上。

按 B 取消了，没出事。之后 skill 里多了一条规则：在 HOME 上按 A 之前，先读出光标所在那一项的名字（只有选中项上方会显示名字），对了再按。

加载中的转圈不是文字。 第一次进"所有软件"，页面在转圈，前后两次 OCR 都只读到标题栏，--observe 以为画面稳定了，提前返回。后来加了像素对比：把截图缩成 160×90 的灰度格子，数前后两帧变化超过 60 的格子。在主机上量过，HOME 选中框的呼吸光效最多变 5 格，页面加载时一帧变 1700 格以上，阈值定在 8 格。现在文字和像素都不动了才算稳定；一直在动的画面（动画、超长加载）等 4 秒后返回，输出里注明"画面仍在变化"。

HOME 上第一下触摸只是选中。 我一度以为底座模式下触摸无效，因为点了设置图标没进去。其实第一下只把光标移到了图标上，再点一次才打开。底座模式下 sys-botbase 的虚拟触摸一样能用。现在 touch 和 tap 点完会对比前后画面，什么都没变就报错，agent 不会以为点成功了。

给 agent 用

仓库里带一份 SKILL.md，写了操作流程和上面这些坑。Claude Code 可以装插件：

text

/plugin marketplace add leeguooooo/plugins
/plugin install switch-use@leeguooooo-plugins

它也在 use 家族里，装 use-family 会一起带上。skill 里写死了几条：打断正在运行的游戏前先问；不改系统设置、不删数据、不买东西，除非用户明确要求；不让主机连任天堂的服务。主机最好在虚拟系统（emuMMC）里，用大气层的 hosts 屏蔽任天堂服务器。

想自己玩：随身手柄

sys-botbase 这个端口不光能给 agent 用。我还做了一个 Mac 应用叫随身手柄（Pocket Gamepad），走的是同一条路：连上主机的 sys-botbase，把 Mac 键盘或者闲置手机变成 Switch 的一个手柄。手机不用装东西，扫 Mac 上的二维码就能横屏玩。

朋友来了只有一对 Joy-Con 的时候，第三个人就用它。免费试用 7 天，之后 US$1.99 买断。怎么配、按键怎么映射，写在Switch 手柄不够用？用 Mac 键盘和手机多开一个手柄里。

两个工具可以一起开：sys-botbase 同时接受多个连接，你用随身手柄玩，agent 照样能截图读屏。

还做不到的

OCR 只在 macOS 上有。Linux 上按键、触摸、截图都能用，读屏要自己看图。
OCR 看不出光标在哪。Switch 大部分菜单靠方向键走，选中项是一圈高亮框，不是文字。移动光标后还得看截图确认。
截图慢。sys-botbase 用十六进制传 JPEG，HOME 这种画面约 0.45 秒，"所有软件"那种满屏封面的要 1.4 秒左右。

代码和安装说明在 GitHub，MIT 或 Apache-2.0 双协议。