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

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

全程我没碰手柄。干这件事的是 [switch-use](https://github.com/leeguooooo/switch-use)，一个约 1 MB 的 Rust 命令行工具，开源。

![动森的数据管理页：只有主机内存 66.6 MB 和 SD 卡 441 MB 两份更新数据，合计 508 MB](https://img.leeguoo.com/media/c90e2594-9d60-49ea-be3b-74b8e99af4a7/switch-acnh-data.jpg)

## 它怎么连上 Switch

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

```sh
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](https://github.com/leeguooooo/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 按在了《坦克大战》上。另一个游戏还开着，系统弹出"将关闭正在运行的软件"，焦点还正好停在"关闭"上。

![误按后弹出的关闭软件对话框，焦点在"关闭"上](https://img.leeguoo.com/media/f55b06f0-7dd9-4779-b7ff-1da3d0fa75a1/switch-close-dialog.jpg)

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

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

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

## 给 agent 用

仓库里带一份 [SKILL.md](https://github.com/leeguooooo/switch-use/blob/main/SKILL.md)，写了操作流程和上面这些坑。Claude Code 可以装插件：

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

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

## 想自己玩：随身手柄

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

朋友来了只有一对 Joy-Con 的时候，第三个人就用它。免费试用 7 天，之后 US$1.99 买断。怎么配、按键怎么映射，写在[Switch 手柄不够用？用 Mac 键盘和手机多开一个手柄](https://blog.leeguoo.com/zh/posts/switch-extra-controller-keyboard-phone-atmosphere/)里。

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

## 还做不到的

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

代码和安装说明在 [GitHub](https://github.com/leeguooooo/switch-use)，MIT 或 Apache-2.0 双协议。