SimUtil自定义插件指南：一份YAML接入scrcpy、Maestro与任意外部工具-平芜编程栈

【免费下载链接】simutil

It's not just a cross-platform TUI app that quickly opens Android & iOS emulators/simulators

项目地址：https://gitcode.com/gh_mirrors/sim/simutil

SimUtil 是一款跨平台的终端 UI 工具，用于快速启动和管理 Android 模拟器与 iOS 模拟器。它最被低估的能力是自定义插件：只需在一个 YAML 文件里加几行配置，就能把 scrcpy 投屏、Maestro UI 测试、adb 快捷命令乃至你自己的脚本，全部接入 SimUtil 的快捷键体系，实现一键运行。

本指南面向新手，不写一行 Dart 代码，跟着做 10 分钟即可上手。完整字段说明见官方文档 docs/plugins.md。

为什么用 SimUtil 插件而不是自己敲命令

日常开发中，我们常常要在这些工具之间来回切换：

投屏工具（scrcpy）需要手动拼-s <设备ID>参数
UI 自动化（Maestro）要先确认模拟器已启动再执行 flow
adb 常用命令（截图、打开设置）每次都要查一遍

SimUtil 插件把这些操作变成：选中设备 → 按一个字母 → 工具直接运行。而且插件会自动按当前选中的设备过滤，只在你选了 Android 模拟器时才显示 Android 相关命令。

第一步：找到插件配置文件

插件统一写在 SimUtil 的配置文件里，路径为：

~/.simutil/settings.yaml

三步搞定：

启动一次 SimUtil（首次运行会自动生成该文件，并内置一段带 scrcpy 示例的plugins:模板）
在应用里按e键，默认编辑器会自动打开这个文件
编辑完成后重启 SimUtil使配置生效

💡 如果之后想彻底关闭插件，保留plugins: []即可，不要删除plugins:这一行，否则默认模板会被重新写回。文件写入逻辑见 settings_file.dart。

5 分钟接入第一个插件：scrcpy 投屏

在~/.simutil/settings.yaml的plugins:下添加如下内容：

plugins: - id: scrcpy label: scrcpy description: Android 屏幕镜像与控制 availability: command: scrcpy # 运行前自动探测是否已安装 args: [--version] commands: - id: mirror label: 屏幕镜像 description: 镜像当前设备屏幕 command: scrcpy args: [-s, "{device.id}"] platforms: [android] requires_running: true mode: detached shortcut: s

保存、重启 SimUtil。此时在应用内选中一台 Android 设备：

按p→ 选择scrcpy→ 选择屏幕镜像，即可投屏
或者干脆直接按s（我们设置的快捷键），跳过所有菜单一步运行

YAML 插件结构速览

理解两个概念即可读懂整份配置：

层级	作用	必填字段
插件`plugins`	一组共享身份和探测命令的入口	`id`、`label`、`commands`
命令`commands`	一条真正执行的外部命令	`id`、`label`、`command`

命令级常用可选项：

args：参数列表，支持模板变量（见下节）
platforms：[android]、[ios]或两者，留空表示任意平台
requires_running：为true时仅当设备处于运行状态才显示
mode：detached（GUI 工具，独立开窗，默认）或inherit（命令行工具，共享终端输出）
shortcut：单键快捷键，按它直接运行该命令

模板变量：让命令自动绑定当前设备

在args中可使用以下占位符，运行时自动替换为当前选中设备的真实值：

变量	示例值
`{device.id}`	`emulator-5554`
`{device.name}`	`Pixel 7`
`{device.platform}`	`Android`
`{device.os}`	`android`/`ios`
`{device.state}`	`Booted`/`Shutdown`

⚠️ 含占位符的参数记得加引号，例如"--name={device.name}"。

实战二：接入 Maestro UI 测试

Maestro 是移动 UI 测试框架，接入方式与 scrcpy 类似，只是流测试这类阻塞型命令要用inherit模式：

- id: maestro label: Maestro description: 移动端 UI 测试框架 availability: command: maestro args: [--version] commands: - id: studio label: Maestro Studio command: maestro args: [studio, --device, "{device.id}"] platforms: [android] requires_running: true mode: detached - id: test label: 运行测试流程 command: maestro args: [test, flow.yaml, --device, "{device.id}"] platforms: [android] requires_running: true mode: inherit

接入任意外部工具：脚本与 adb 快捷命令

插件机制本质是"带模板变量的 shell 命令包装器"，所以任何已安装、在PATH中可找到的工具都能接入，包括自定义脚本：

- id: my-scripts label: 我的脚本 commands: - id: deploy label: 部署构建 command: /Users/me/scripts/deploy.sh args: ["{device.id}"] platforms: [android, ios] mode: inherit

mode的选择口诀：会开窗口选detached，要往终端打输出选inherit。这也是新手最常踩的坑——用detached跑纯命令行工具会导致"点了没反应"。

不打开 TUI 也能管理插件，命令行同样支持：

simutil plugin list # 查看已配置插件（-d 可按设备过滤） simutil plugin run scrcpy mirror -d emulator-5554

命令实现见 plugin_command.dart。

运行前可用性探测：工具没装也不会报错卡死

执行前 SimUtil 会按以下顺序确认工具已安装，探测命令以退出码 0 为通过：

命令自身的availability（如果配置了）
插件级的availability
兜底：<command> --version

探测失败时，状态栏会显示"未找到"提示，而不是盲目启动失败进程。

常见问题排查清单

现象	最可能的原因
菜单里看不到插件	设备平台不在`platforms`中；或`requires_running: true`但设备未启动；或`enabled: false`
状态栏提示"not found"	可执行文件不在`PATH`中，或`availability`探测退出码非 0
命令执行后没有任何可见效果	纯 CLI 工具误用了`mode: detached`，改为`inherit`
整个插件配置不生效	YAML 语法错误（单个坏条目只跳过并警告，整段格式错误则全部不加载）
改完配置没变化	忘记重启 SimUtil