MuMu 模拟器控制 WinTerminal/dsh-mumuemulator-use

dsh-mumuemulator-use

一个 DSH 插件，把本地的 MuMu Player 12 模拟器交给模型控制。
它直接调用 MuMu 自带的 MuMuManager.exe 和 adb——不用 Python，不用 MCP 服务器，也不多加一层序列化。仅支持 Windows。

七个工具，全部以 mumu_ 开头：

| 工具 | 作用 |
| mumu_env | 显示找到的是哪个安装、从哪里找到、缓存放哪里 |
| mumu_list_instances | 列出每个实例的索引、名称、Android 版本、运行状态、adb 端点、pid |
| mumu_instance | 启动 / 关闭 / 重启 / 创建 / 删除 / 重命名 / show_window / hide_window |
| mumu_app | 列出 / 查看信息 / 安装 / 卸载 / 启动 / 关闭应用 |
| mumu_ui | 点击 / 滑动 / 长按 / 输入文本 / 按键（帧缓冲像素坐标） |
| mumu_shell | 在 Android 客户机内执行 shell 命令 |
| mumu_screenshot | 截屏；返回一张模型能看的图片 |

安装

从 npm 安装

dsh plugin --profile <your-profile> add dsh-mumuemulator-use

就这样——dsh plugin add 会解析依赖，把它链接进配置档，并把 dsh-mumuemulator-use 追加到 dsh.profile.bundles。重启应用或切换 bundle 即可加载。

Desktop DSH 用户可能会看到 pnpm 警告 missing peer @deepseek-ai/dsh。
这是预期内的，无害：Desktop DSH 以 Electron 应用形式发布，不会把宿主暴露给插件的 node_modules。插件通过 Electron 运行时解析宿主，功能不受影响。

从源码安装

只在针对 $PROFILE\plugins\ 下的检出目录开发插件时才需要。设 $PROFILE = C:\Users\HP\.dsh\profiles\desktop：

1. put the files under $PROFILE\plugins\dsh-mumuemulator-use\

2. declare it as a dependency through the official channel
dsh plugin --profile desktop add file:plugins/dsh-mumuemulator-use

the code imports @deepseek-ai/schemastery; a fresh profile sets
autoInstallPeers: false, so make sure it is actually there
dsh plugin --profile desktop add @deepseek-ai/schemastery

3. link it as a junction (see "First: ..." below) — needed ONCE cmd /c rmdir $PROFILE\node_modules\dsh-mumuemulator-use # link only — NEVER /s New-Item -ItemType Junction -Path $PROFILE\node_modules\dsh-mumuemulator-use -Target $PROFILE\plugins\dsh-mumuemulator-use

4. reload the profile

别的都不用做：插件首次使用时会自己找到 MuMu。

路径从哪里来

mumu_env 会打印完整的查找轨迹。解析顺序：

1. 配置覆盖——在 mumu 这一行上设置 mumuRoot / mumuManagerPath / adbPath。
2. 缓存文件，<profile>\dsh-mumu-paths.json——记录的所有路径都还存在时复用。
3. 注册表——在 HKLM\SOFTWARE\Microsoft\Windows\CurrentVersion\Uninstall\、 HKLM\SOFTWARE\WOW6432Node\...\Uninstall\、HKCU\...\Uninstall\ 中匹配 DisplayName 含 /MuMu/i 的项。每命中一项，依次尝试三个字段： InstallLocation → DisplayIcon（"C:\path\app.exe",0，去掉引号和 ,0）→ UninstallString（去掉引号，取目录部分）。只有 <root>\MuMuManager.exe 或 <root>\nx_main\MuMuManager.exe 存在时，候选路径才会被接受。
4. sweep —— 扫描常见安装根目录，仅作最后手段。

adb 优先选最新的 nx_device\<version>\shell\adb.exe，其次 nx_main\adb.exe，最后用 PATH 上的 adb。
reg query 按 OEM 代码页写出，所以输出依次按 UTF-16LE（BOM）、严格 UTF-8、严格 GBK、latin1 解码——这就是 MuMu模拟器 不会变成乱码的原因。

在这台机器上，解析结果是：

MuMu root : D:\Program Files\Netease\MuMu
MuMuManager.exe : D:\Program Files\Netease\MuMu\nx_main\MuMuManager.exe
adb : D:\Program Files\Netease\MuMu\nx_device\15.0\shell\adb.exe
cache file : %PROFILE%\dsh-mumu-paths.json
version : {"version":"6.8.2.0"}

配置

在 %PROFILE%\cordis.patch.yml 里插件对应的行上设置：

- id: mumu # rowId is always "mumu"
config:
adbPath: 'D:\Program Files\Netease\MuMu\nx_device\15.0\shell\adb.exe'
screenshotIncludeImage: false

| key | default | meaning |
| mumuRoot | '' | 强制指定安装根目录；跳过检测 |
| mumuManagerPath | '' | 强制指定 MuMuManager.exe；跳过检测 |
| adbPath | '' | 强制指定 adb.exe；留空 = 自动，回退到 PATH 上的 adb |
| cacheFile | <profile>\dsh-mumu-paths.json | 缓存解析出的路径 |
| commandTimeoutMs | 120000 | 每条命令的时间预算；超时即杀掉子进程 |
| bootTimeoutMs | 300000 | mumu_instance launch 等待 Android 启动的时长 |
| adbConnectTimeoutMs | 60000 | adb connect 的时间预算 |
| screenshotIncludeImage | true | mumu_screenshot 的 includeImage 参数默认值 |

只有 mumuRoot/mumuManagerPath 会短路检测；单独设 adbPath 只覆盖 adb 这一侧。

已知限制

- MuMuManager sh 无法报告失败。 不管 guest 命令成功与否，它都退出 0 且不打印任何内容，而且 MuMu 拒绝执行 adb 子命令的 getprop 形式。因此 mumu_shell 会自己另起一行追加 echo "MUMU_SH_EXIT:$?"，再把标记解析回来。如果命令行无法被 guest shell 解析（引号不配对），标记会被吞掉，退出码读出来就是 unavailable。裸键名（go_home、go_back 等）原样透传——那些是 MuMu 快捷键，不是 shell。
- control tool cmd 是发后不管。 MuMuManager control -v 1 tool cmd -c "..." 对任何输入都回 {"errcode":0,"errmsg":""}，包括胡写的输入，而且从不返回 guest stdout。需要输出时请用 mumu_shell。
- show_window / hide_window / layout_window / tool func / tool cmd 不校验实例索引——对不存在的索引也回 errcode 0。插件会调用 info -v <index> 先（assertInstance），这样这些路径会直接报错，而不是悄悄成功。
- 实例已停止时，触摸、shell 和 app 工具会返回 errcode -201（player not running / vm not running, can not connect NemuShell !!）；mumu_screenshot 则报告 MuMu instance "1" is not running Android yet (player_state=stopped).
- adb 必须可用。 adbPath 写错会得到 spawn <path> ENOENT；mumu_shell 仍然能用，因为它从不碰 adb。
- lib\index.js 的来源。 原文件被误删后，这个文件是从会话的工具调用日志重建的。
已验证完整——逐行对照每个 read 快照，字节数逐字节一致——所有行为探测均通过。核对记录见 NOTES-dsh-mumuemulator-use.md。
- 帧缓冲是横屏。 wm size 报告 900x1600，但截图返回 1600x900，mumu_ui 坐标是帧缓冲像素，也就是你在 mumu_screenshot 图像里看到的样子。
- 截图约 1.15 MB / 1600x900。轮询时传 includeImage: false（或设置 screenshotIncludeImage: false），这样图像不会在每次调用时进入对话。

修改代码

这个配置档里 HMR 是开着的，所以编辑 %PROFILE% 下的文件会在约 1–2 秒内重载插件——不用重启。 用行为探测实测：单向切换 1100 ms，切回 2051 ms。

首先：node_modules\dsh-mumuemulator-use 必须是 junction

这是整套设置的关键部分，所以先检查它。

1. 要求。 它必须是 junction，不能是真实目录，也不能是硬链接：

New-Item -ItemType Junction -Path $PROFILE\node_modules\dsh-mumuemulator-use -Target $PROFILE\plugins\dsh-mumuemulator-use

2. 怎么检查。

Get-Item $PROFILE\node_modules\dsh-mumuemulator-use | Select-Object LinkType, Target
LinkType Target
Junction C:\Users\HP\.dsh\profiles\desktop\plugins\dsh-mumuemulator-use

3. 怎么修复。 如果 LinkType 返回空，说明它是真实目录（同步工具、手动 Copy-Item 或 pnpm 路径造成的）。删掉它，按第 1 步重新创建 junction。

这里绝不要用递归删除——不要对 junction 用，也不要对仅仅包含它的目录用。
下面两种做法都已经毁掉过一次源文件：

- Remove-Item $PROFILE\node_modules\dsh-mumuemulator-use -Recurse -Force —— PowerShell 会跟随重解析点，于是删掉目标的内容；plugins\dsh-mumuemulator-use 也被清空，最后你剩下两个空目录。
- cmd /c rmdir /s /q $PROFILE\node_modules —— 用 /s 删除父目录时，会以完全相同的方式穿过 junction。问题全在 /s，不在 junction。

唯一安全的删除方式是对链接本身执行非递归的 rmdir：

cmd /c rmdir "$env:USERPROFILE\.dsh\profiles\desktop\node_modules\dsh-mumuemulator-use"

先查 LinkType（Get-Item … | Select-Object LinkType）；只有 Junction 才能用 rmdir 删除。
如果 LinkType 为空，说明它是真实目录，rmdir 会拒绝删除——先把文件复制出来，再删除。
当 pnpm/dsh plugin 安装需要重建 node_modules 时，让它自己删除 junction，不要从下面把目录清空。

4. 出错时的症状： 你改了源码，HMR 没有任何异常报告，但行为没有变化。模块 URL 变成 node_modules\dsh-mumuemulator-use\lib\index.js，于是 watcher 重新加载的是旧副本，而你的修改还留在 plugins\ 里。没有报错，没有日志——重载对着错误的文件照样成功。这比旧的硬链接损坏更安静，后者至少会表现为大小或 File-ID 不匹配。

那么：为什么会重载

两个设置让重载发生：

- %PROFILE%\cordis.patch.yml 启用 watcher：
- id: hmr
disabled: false
config:
root: ['.']

- junction 把模块的真实路径留在 %PROFILE%\plugins\dsh-mumuemulator-use\lib\index.js——在 node_modules 之外，而 dsh-hmr 默认忽略 node_modules。

要确认重载生效，查看工具列表里 mumu_env 的描述，或者调用一个你刚改过行为的工具。

如果 HMR 关着，退路就是重启——只改文件不会被拾取，因为 Node 按 URL 缓存 ES 模块，缓存持续整个进程生命周期。

保存写到一半的代码

每次保存都会触发 HMR，先截断再写入的编辑器可能短暂暴露不完整的文件。为偶尔的开发后修改不值得防这个：一次坏保存只会让工具报错，直到下次保存修好，重启配置档就能清掉。唯一要避免的是：保存进行到一半时，从会话里发起 mumu_ 调用。

重载对进行中调用的影响

重载会销毁旧代，任何运行中调用在宿主侧的 MuMuManager.exe 子进程会在保存后约 1.5 s 消失。这不会打断调用：它仍按自然时长返回，仍报告真实的 guest 退出码，也不留下僵尸进程。

2026-10-01 用 mumu_shell {command: 'sleep 60'} 实测，后台轮询器报告 (Get-Process MuMuManager -EA SilentlyContinue).Count：

| 场景 | 宿主 MuMuManager 数量 | 被包装的调用 |
| 对照组，无重载 | 整个 20 s 调用期间为 1 | 在 20 579 ms 返回 |
| +6 s 时 HMR 重载 | +6 s 为 1 → +7.5 s 为 0 → 之后为 0 | 在 60 588 ms 返回，guest exit code 0 |
| +6 s 时外部 Stop-Process -Name MuMuManager | +6 s 为 1 → +7 s 为 0 → 之后为 0 | 在 25 529 ms 返回，guest exit code 0 |
所以重载不会打断正在进行的工作，也不会泄漏。复现步骤：启动一个长时间运行的 mumu_shell，从后台 pwsh 任务轮询计数，再在 %PROFILE% 下保存文件触发重载。

卸载

从 npm 卸载

dsh plugin --profile <your-profile> remove dsh-mumuemulator-use

这条命令会移除依赖、dsh.profile.bundles 条目和链接的包。如果你还改过配置档补丁（tool-plugin-manager / hmr / tool-cordis），见下文「配置档补丁改动」。

从源码卸载

设 $PROFILE = C:\Users\HP\.dsh\profiles\desktop：

1. remove the bundle through the official channel
dsh plugin --profile desktop remove dsh-mumuemulator-use

2. delete the junction — NON-RECURSIVE only (see "First: ..." above) cmd /c rmdir "$env:USERPROFILE\.dsh\profiles\desktop\node_modules\dsh-mumuemulator-use"

3. delete the source directory — this one is a real directory, so rmdir /s is safe here cmd /c rmdir /s /q "$env:USERPROFILE\.dsh\profiles\desktop\plugins\dsh-mumuemulator-use"

4. if step 1 did not already do it, drop "dsh-mumuemulator-use" from
dsh.profile.bundles in $PROFILE\package.json

5. delete the path cache
Remove-Item $PROFILE\dsh-mumu-paths.json

配置档补丁改动

如果你改过，$PROFILE\cordis.patch.yml 里会多出三行：tool-plugin-manager（已启用）、hmr 和 tool-cordis。

除非你想一次性撤销这三项，否则不要恢复 cordis.patch.yml.bak-before-mumu。 那份备份早于整轮改动，恢复它也会一并禁用 HMR 和 tool-plugin-manager。如果只想删掉 mumu 那一行，删掉 - id: mumu / - id: mumuemulator-use 条目即可，其余保持不动。