记录时间：2026-10-08 目标设备：vivo V2458A（adb serial 10AF5J16*******），Android 16 / SDK 36 记录范围：从「手机已通过 adb 连接电脑」开始，到 mobilerun 用 DeepSeek 跑通真机任务为止的完整过程 最终结论：✅ 安装完成、配置完成、真机链路跑通（含 1 个已知准确性问题，见 7.3）

mobilerun 是个用 LLM Agent 控制 Android / iOS 设备的工具。过程本身不算难，但坑很集中： 国外源下载、厂商 ROM 的安装拦截、以及一个官方向导配不了的模型供应商。

这篇把每一步的真实命令输出和排查过程都记下来了，照着走可以省掉重复试错。

1. 任务与约束#

1.1 用户诉求（按时间顺序）#

手机已经通过 adb 连接至电脑
阅读 https://github.com/droidrun/mobilerun，帮忙安装该软件
追加要求：uv 安装时使用清华的源
最后：把本次对话所有内容整理成一个 md 文件（即本文）

1.2 项目官方要求（摘自 README）#

要求	说明
Python 版本	`>=3.11,<3.14`，README 明确写了 3.14 不支持
安装方式	推荐 `uv tool install mobilerun`
前置条件	安装 ADB；Android 需开启开发者选项 + USB 调试
标准流程	`mobilerun setup` → `mobilerun ping` → `mobilerun configure` → `mobilerun run`
Anthropic 支持	需额外安装 `mobilerun[anthropic]`

mobilerun 的定位：用 LLM Agent 控制 Android / iOS 设备，通过 Portal App（设备端）暴露无障碍树、截图、点击、滑动、输入等能力，CLI 或 Python API 调用。

2. 初始环境侦察#

2.1 系统与工具链#

项目	侦察结果
操作系统	Windows `10.0.26300.0`（NT 10.0.26300）
Python	仅 3.14.8（`C:\Python314\python.exe`）→ 版本不满足要求
uv	不在 PATH，但实际已安装（`%USERPROFILE%\.local\bin\uv.exe`，v0.9.22）
pipx	未安装
adb	不在 PATH，`where adb` 无结果，无 `ANDROID_HOME` 等环境变量
可用的包管理器	winget、choco、git、node、npm（无 scoop）
工作目录	博客仓库目录（Astro 项目，git 仓库）

2.2 adb 位置搜索#

在用户目录与常见根目录递归搜索 adb.exe，命中：

1
%USERPROFILE%\Downloads\platform-tools-latest-windows\platform-tools\adb.exe

版本：Android Debug Bridge version 1.0.41（37.0.1-15733141）

2.3 设备连接确认#

1
$ adb devices -l
2
List of devices attached
3
10AF5J16*******   device product:PD2415M model:V2458A device:PD2415M transport_id:1
4

5
$ adb shell getprop ro.build.version.release
6
16
7
$ adb shell getprop ro.product.model
8
V2458A

✅ 设备在线：vivo V2458A，Android 16。注意此时 adb server（端口 5037）原本未运行，是首次调用时自动拉起的。

2.4 uv 现状（重要）#

虽然 Get-Command uv 失败，但 uv 实际已存在，且已经装好了 mobilerun：

1
$ uv --version
2
uv 0.9.22 (82a6a66b8 2026-01-06)
3

4
$ uv tool list
5
mobilerun v0.6.22
6
- mobilerun
7
windows-mcp v0.8.7
8
- windows-mcp
9

10
$ uv python list --only-installed
11
cpython-3.14.8-windows-x86_64-none     C:\Python314\python.exe
12
cpython-3.14.8-windows-x86_64-none     C:\ProgramData\chocolatey\bin\python3.14.exe
13
cpython-3.13.11-windows-x86_64-none    %APPDATA%\uv\python\cpython-3.13.11-windows-x86_64-none\python.exe

关键点：系统里只有 Python 3.14，但 mobilerun 要求 <3.14。uv 自动下载并使用了 3.13.11 来搭建 mobilerun 的隔离环境 —— 这说明不需要手动降级系统 Python。

2.5 清华源配置（用户追加要求）—— 已存在#

uv 的全局配置 %APPDATA%\uv\uv.toml 已经指向清华源：

1
python-install-mirror = "https://ghfast.top/https://github.com/astral-sh/python-build-standalone/releases/download"
2

3
[[index]]
4
url = "https://pypi.tuna.tsinghua.edu.cn/simple"
5
default = true

即 PyPI 包走清华源，python-build-standalone 走 ghfast.top 代理。因此「uv 使用清华源」这一要求开箱即满足，无需改动。

2.6 清华镜像可用性实测#

目标	结果
`https://pypi.tuna.tsinghua.edu.cn/simple/mobilerun/`	✅ 200
`https://mirrors.tuna.tsinghua.edu.cn/github-release/astral-sh/uv/`	❌ 404
`https://mirrors.tuna.tsinghua.edu.cn/github-release/astral-sh/python-build-standalone/`	❌ 404

结论：清华仓的 github-release 镜像不覆盖 astral-sh，所以 GitHub 二进制（uv 本体、Python 运行时、Portal APK）必须另想办法 —— 见 5.1 与 5.2。

3. 关键发现#

#	发现	影响
1	系统只有 Python 3.14，而 mobilerun 要求 `<3.14`	uv 已自动用 3.13.11 解决，无需人工干预
2	uv 与 mobilerun 早已安装，只是 `~/.local/bin` 不在 PATH	不需要重新安装，只需补 PATH
3	`uv.toml` 已配清华 PyPI 源	用户的追加要求已满足
4	adb 不在 PATH，但存在于 Downloads 目录	需迁移到稳定位置并加入 PATH，否则 `mobilerun setup/ping` 无法工作
5	清华未镜像 astral-sh 的 GitHub Release	GitHub 大文件下载需走 `ghfast.top`
6	mobilerun 的 provider 列表里没有 DeepSeek 的 env-key slot	`mobilerun configure` 向导无法配置 DeepSeek，需手写配置

4. 执行过程#

步骤 1：安装 platform-tools 并修复 PATH#

把 adb 从临时下载目录复制到标准 Android SDK 位置（保留 Downloads 原目录不动，非破坏性）：

1
$src = "$env:USERPROFILE\Downloads\platform-tools-latest-windows\platform-tools"
2
$dst = "$env:LOCALAPPDATA\Android\Sdk\platform-tools"
3
New-Item -ItemType Directory -Force -Path (Split-Path $dst) | Out-Null
4
Copy-Item -Path $src -Destination $dst -Recurse -Force

写入用户级 PATH（用 SetEnvironmentVariable 而非 setx，避免 1024 字符截断），并把 ~/.local/bin 一并确保在内：

1
$userPath = [Environment]::GetEnvironmentVariable("Path","User")
2
$entries = @($userPath -split ';' | Where-Object { $_ -ne '' })
3
foreach ($d in @($dst, "$env:USERPROFILE\.local\bin")) {
4
  if ($entries -notcontains $d) { $entries += $d }
5
}
6
[Environment]::SetEnvironmentVariable("Path", ($entries -join ';'), "User")

复制内容（14 个文件，含 adb 依赖的两个 DLL）：

1
adb.exe (8273560)  AdbWinApi.dll  AdbWinUsbApi.dll
2
fastboot.exe  etc1tool.exe  hprof-conv.exe  sqlite3.exe
3
make_f2fs.exe  make_f2fs_casefold.exe  mke2fs.exe  mke2fs.conf
4
libwinpthread-1.dll  NOTICE.txt  source.properties

步骤 2：验证 mobilerun 与首次诊断#

1
$ mobilerun --version
2
v0.6.22
3

4
$ mobilerun devices
5
Found 1 local device(s):
6
  • 10AF5J16*******

首次 mobilerun doctor 结果 —— ADB 是唯一红灯：

1
Mobilerun Doctor
2
  SDK Version   0.6.22 (up to date)                        ✓
3
  Config        ...\droidrun\config.yaml                   ✓
4
  ADB           adb not found in PATH                      ✗
5
  1 issue(s):
6
    ✗ ADB: adb not found in PATH

修复 PATH 后重新诊断，ADB 转为通过，但暴露出下一个问题（Portal 未安装）：

1
  ADB            found, 1 device(s)                        ✓
2
  Device         10AF5J16******* (online)                  ✓
3
  Portal         not installed                             ✗
4
Downloading Portal APK 0.7.25

步骤 3：确认 Portal 版本与资产#

通过 ungh.cc（GitHub API 代理，比 api.github.com 快）查询最新 Release：

项目	值
Release tag	`v0.7.25`（发布于 2026-08-18）
资产文件	`com.mobilerun.portal-0.7.25.apk`
大小	`53,610,015` 字节（约 51.12 MB）

同时查版本映射表（version_map_android.json），确认 SDK 与 Portal 的对应关系：

1
{
2
  "mappings": {
3
    "0.1.0-0.2.0":    "0.7.16",
4
    "0.4.1-0.4.15":   "v0.4.6",
5
    "0.6.0rc2":       "v0.7.9",
6
    "0.6.0rc3":       "v0.7.11",
7
    "0.6.2-0.6.7":    "0.7.16",
8
    "0.6.8-0.6.18":   "0.7.22",
9
    "0.6.19-0.6.22":  "0.7.25"
10
  },
11
  "download_base": "https://github.com/droidrun/mobilerun-portal/releases/download"
12
}

✅ mobilerun 0.6.22 对应 Portal 0.7.25 —— 与我们要装的版本完全一致。

步骤 4：经镜像下载 Portal APK#

GitHub 直连下载卡死（详见 5.1），改用 ghfast.top 镜像：

1
$cache = "$env:USERPROFILE\.local\share\mobilerun\portal"
2
$url = "https://ghfast.top/https://github.com/droidrun/mobilerun-portal/releases/download/v0.7.25/com.mobilerun.portal-0.7.25.apk"
3
curl.exe -L --retry 3 --retry-delay 2 --connect-timeout 20 -o "$cache\com.mobilerun.portal-0.7.25.apk" $url

结果：22.2 秒完成，51.12 MB，平均 2.31 MB/s，字节数精确匹配 53610015。

APK 校验：文件头 magic = PK（合法 zip/APK）；mobilerun 安装时自报 md5 为 2bbd2416bc7270dc698b9d0ed81e914c。

APK 缓存位置（保留，供以后重装复用）：

1
%USERPROFILE%\.local\share\mobilerun\portal\com.mobilerun.portal-0.7.25.apk

步骤 5：安装 Portal（绕开 vivo 限制）#

mobilerun setup --path 失败（详见 5.2），改用不带 -g 的原生 adb 安装：

1
adb install -r -t "$env:USERPROFILE\.local\share\mobilerun\portal\com.mobilerun.portal-0.7.25.apk"
2
# Performing Streamed Install
3
# Success

验证：

1
$ adb shell pm list packages | Select-String "mobilerun"
2
package:com.mobilerun.portal
3

4
$ adb shell dumpsys package com.mobilerun.portal | Select-String versionName
5
    versionName=0.7.25

步骤 6：启用无障碍服务#

mobilerun setup 无法完成这一步（因为它会先重装并再次失败），所以直接执行 mobilerun 内部 enable_portal_accessibility() 的等价命令：

1
$svc = "com.mobilerun.portal/com.mobilerun.portal.service.MobilerunAccessibilityService"
2
adb shell settings put secure enabled_accessibility_services $svc
3
adb shell settings put secure accessibility_enabled 1

⚠️ 这两条命令是覆盖写。执行前已确认目标为空（enabled_accessibility_services 无值、accessibility_enabled=0），因此没有破坏其它无障碍服务。若设备上已启用其它无障碍服务，切勿直接照抄，应先读取原值再拼接。

验证绑定成功：

1
$ adb shell dumpsys accessibility | Select-String "mobilerun"
2
Bound services:{Service[label=Mobilerun Portal, feedbackType[FEEDBACK_GENERIC],
3
  capabilities=161, eventTypes=TYPES_ALL_MASK, ...]}
4
Enabled services:{{com.mobilerun.portal/com.mobilerun.portal.service.MobilerunAccessibilityService}}

步骤 7：ping 与 doctor 全绿#

1
$ mobilerun ping
2
Portal is installed and accessible. You're good to go!

步骤 8：附带加固与清理#

1
# vivo 后台管控较强，把 Portal 加入电池优化白名单
2
adb shell dumpsys deviceidle whitelist +com.mobilerun.portal   # -> Added: com.mobilerun.portal
3

4
# 清理设备上 51MB 的临时推送包
5
adb shell rm -f /data/local/tmp/com.mobilerun.portal-539.apk
6

7
# 清理 Windows 端 4 个下载中断残留的临时 apk（共约 39MB）
8
Get-ChildItem $env:TEMP -Filter "*.apk" | Remove-Item -Force

5. 问题与解决方案#

#	问题	根因	解决方案
1	GitHub 下载 Portal APK 卡死	国内直连 GitHub Release 不稳定	改用 `ghfast.top` 镜像
2	`mobilerun setup` 安装失败 `INSTALL_FAILED_ABORTED`	vivo 拒绝 `-g`（安装时授予全部权限）	去掉 `-g`，用 `adb install -r -t`
3	uv 官方安装脚本被拒	PowerShell 执行策略限制	无需处理（uv 已存在）
4	清华未镜像 astral-sh	清华 `github-release` 仓不含 astral-sh	改用 `ghfast.top`

5.1 问题 1 详情：GitHub 下载中断#

mobilerun doctor 为检查 Portal 版本会下载 51MB APK，但进度停在 7,200,768 字节不动（%TEMP% 下还堆积了 4 个历史残留的 .apk：11.6MB / 8.5MB / 6.7MB / 12.9MB，都是历次中断产物）。

定位手段：对比临时 APK 文件在 12 秒间隔内的体积增长，确认停滞。

解决：改用 ghfast.top 前缀代理 —— 这个代理在用户的 uv.toml 里本就已用于 python-build-standalone，属于已验证可用的通道。22 秒下完，速度提升约 4 倍且不再中断。

5.2 问题 2 详情：vivo 拒绝 `-g` 标志（最重要）#

1
$ mobilerun setup --path <apk>
2
Step 1/2: Installing APK: ...
3
62.2%  31.8 MB/s [31.8 MB/51.1 MB]
4
100.0%  32.0 MB/s [51.1 MB/51.1 MB]
5
verify pushed apk, md5: 2bbd2416bc7270dc698b9d0ed81e914c, size: 51.1 MB
6
Failure INSTALL_FAILED_ABORTED
7
Remote apk is not removed. Manually install command:
8
    adb shell pm install -r -t /data/local/tmp/com.mobilerun.portal-539.apk
9
Installation failed: Failure [INSTALL_FAILED_ABORTED: User rejected permissions]

排查过程：

先怀疑「屏幕熄灭导致确认框无法弹出」—— 当时 mScreenOn=false，于是唤醒设备
唤醒后仍失败，且 mCurrentFocus 显示是 vivo 的安装器在拦截
读取 mobilerun 源码确认 setup_portal() 固定传 flags=["-g"] if uninstall else ["-r","-g"]（见 mobilerun_core_local/driver/android/portal.py:657）
判定 -g（INSTALL_GRANT_ALL_RUNTIME_PERMISSIONS）正是被 vivo 拦截的原因

解决：去掉 -g 重新安装 → Success。

影响与后续：Portal 在没有 -g 的情况下安装，运行时权限未被自动授予。实测不影响功能 —— doctor 的截图、无障碍树、content provider、TCP 四种检查全部通过，因为 Portal 依赖的是无障碍服务与 IME（无需运行时权限）。

⚠️ 重要副作用：mobilerun setup 这个命令在本机会永久失败（它写死用 -g）。Portal 已装好，日常无需再跑；若要重装，请用第 10 节的手动命令。

5.3 问题 3 详情：执行策略（已规避）#

最初尝试官方安装脚本：

1
$ irm https://astral.sh/uv/install.ps1 | iex
2
Error: PowerShell requires an execution policy in [Unrestricted, RemoteSigned, Bypass] to run uv.

当时的计划是「下载 uv 二进制 zip 并解压」以避免修改用户的系统执行策略；但在执行前发现 uv 其实早已安装（~/.local/bin/uv.exe），于是没有必要改动执行策略，也没有下载任何东西。

6. DeepSeek 配置#

6.1 为什么不能用 `mobilerun configure` 向导#

查阅源码后发现两个硬约束：

位置	内容	结论
`mobilerun/config_manager/env_keys.py:11`	`API_KEY_ENV_VARS` 只有 `google / gemini / openai / xai / anthropic / zai / minimax`	没有 deepseek slot
`mobilerun/agent/providers/registry.py:35`	`VARIANT_ENV_KEY_SLOT` 无 `DeepSeek` 条目	向导的 provider 家族列表里没有 DeepSeek

但 mobilerun/agent/utils/llm_picker.py:834 保留了 DeepSeek 的 legacy 分支：

1
if provider_name == "DeepSeek":
2
    provider_name = "OpenAILike"
3
    kwargs.setdefault("api_key", os.environ.get("DEEPSEEK_API_KEY"))
4
    kwargs.setdefault("model", DEEPSEEK_DEFAULT_MODEL)   # = "deepseek-flash"
5
    kwargs.setdefault("api_base", "https://api.deepseek.com")

结论：DeepSeek 只能通过 provider: DeepSeek + 环境变量 DEEPSEEK_API_KEY 使用；configure 向导做不到（向导里可选的是 OpenAI / Gemini / Anthropic / XAI / Ollama / OpenAI Compatible / MiniMax / ZAI）。

6.2 先验证 Key 与真实模型列表#

不猜模型名，直接问 API：

1
$ GET https://api.deepseek.com/models  (Authorization: Bearer <key>)
2
SUCCESS - available models:
3
  - deepseek-flash
4
  - deepseek-v4-pro

✅ 官网 API 返回的模型正是 deepseek-flash 与 deepseek-v4-pro，与 mobilerun 内置的 DEEPSEEK_DEFAULT_MODEL = "deepseek-flash" 及 DEEPSEEK_FUNCTION_CALLING_MODELS = {"deepseek-flash", "deepseek-v4-pro"} 完全吻合。因此无需修改模型名。

（这一步是必要的：deepseek-flash 这个名字与公开 pricing 数据里的 deepseek-v4-flash 不一致，若不实测就有配错的风险。）

6.3 功能测试（含 Agent 依赖的 tool calling）#

测试 1 — 普通补全

1
content: (空)
2
tokens: in=35 out=20

内容为空是因为 deepseek-flash 默认开启 thinking 模式，token 先消耗在 reasoning 上，被 max_tokens=20 截断。这是预期行为，不是故障。

测试 2 — tool calling（关键，Agent 全靠它）

1
TOOL CALL OK -> name=get_weather args={"city": "Beijing"}

✅ 工具调用正确返回函数名与参数。

6.4 写入配置#

配置文件：%LOCALAPPDATA%\droidrun\droidrun\config.yaml

改动前先备份为 config.yaml.bak-20261008-185427，然后做两处精确文本替换（各命中 5 处，对应 5 个 LLM profile）：

原值	新值
`provider: GoogleGenAI`	`provider: DeepSeek`
`model: gemini-3.8-flash`	`model: deepseek-flash`

改动后的 profile 结构（manager / executor / fast_agent / app_opener / structured_output 五者一致）：

1
llm_profiles:
2
  manager:
3
    provider: DeepSeek
4
    model: deepseek-flash
5
    temperature: 0.2
6
    api_key_source: auto
7
    base_url: null
8
    api_base: null
9
    provider_family: null
10
    ...

6.5 持久化 API Key#

因为 llm_picker 是从 os.environ 读取，所以写入用户级环境变量（不是 api_key_source: file，DeepSeek 走不到那条路径）：

1
[Environment]::SetEnvironmentVariable("DEEPSEEK_API_KEY", "<KEY>", "User")

验证：长度 35 字符，可在用户作用域读取到。

Key 的明文不在本文档中（本仓库是 git 仓库，见第 11 节）。

7. 验证与实测#

7.1 冒烟测试（读路径 —— LLM + 设备状态）#

1
$ mobilerun run "What app is currently open? Answer in one short sentence."
2
🚀 Starting: What app is currently open? Answer in one short sentence.
3
🤖 Agent mode: direct execution
4
👁️  Vision settings: Manager=False, Executor=False, FastAgent=False
5
🔄 Step 1/15
6
FastAgent response:
7
The device state clearly shows the Settings app is open, displaying the Accessibility (无障碍) settings screen.
8
🎉 Goal achieved: The currently open app is Settings (设置), showing the Accessibility (无障碍) page.

✅ 1 步完成，回答与真机状态一致（此前 mobilerun ping 失败时自动打开了无障碍设置页，所以前台确实是它）。

7.2 动作路径测试（README 官方示例）#

1
$ mobilerun run "Open the settings app and tell me the Android version"

执行轨迹（8 步，全部真实作用于手机）：

步	动作	结果
1	`system_button(back)`	从无障碍页返回
2	`system_button(back)`	⚠️ 输出畸形工具调用标记
3	`system_button(back)`	返回到桌面
4	`open_app("设置")`	启动 `com.android.settings`
5	`click(index=42)`	⚠️ 输出畸形工具调用标记
6	`click(index=42)`	点击「关于手机」→ `(629, 2355)`
7	`click(index=31)`	点击「版本信息」→ `(630, 2731)`
8	`complete`	输出结论

✅ 动作链路完全可用：返回、启动应用、按无障碍树 index 精确点击，坐标都命中了目标。

7.3 ⚠️ 发现的准确性问题（重要）#

第 8 步给出的结论是错的：

1
Android version: 15 (Android 15). Device is a vivo X200s (model V2458A).
2
Confirmed via the kernel version string "6.6.127-android15-8-g8015405e252d-..." in
3
Settings > About phone > Version info.

真机实测（ground truth）：

1
ro.build.version.release = 16     ← 实际是 Android 16
2
ro.build.version.sdk     = 36
3
ro.product.model         = V2458A

问题定性：模型看到内核串里的 android15 字样就断言系统版本是 15，没有完整扫描屏幕上的「Android 版本」字段。这属于模型侧的推理捷径，不是 Portal 或工具链故障 —— 无障碍树是完整可读的。

另一个观察：日志两次出现 Malformed tool-call markup detected (1/3)，模型偶尔吐出畸形工具调用标记（可见 ｜｜DSML｜｜ 之类的干扰 token），靠 mobilerun 的重试机制恢复了。说明该模型在这个提示词格式下的输出稳定性有波动。

实践建议：涉及事实性结论（版本号、金额、日期）时，务必自行复核；或改用 deepseek-v4-pro 试试是否更稳。

7.4 一条 8 步任务的实际 token 消耗提示#

该任务共 8 步、每步都携带完整无障碍树，属于长上下文场景。deepseek-flash 的 context window 为 1,048,576，余量充足，但注意 reasoning 模式的 token 开销（见 6.3 测试 1）。

8. 最终状态#

8.1 `mobilerun doctor` 完整输出（唯一一条警告无害）#

1
Mobilerun Doctor
2

3
  SDK Version            0.6.22 (up to date)                        ✓
4
  Config                 %LOCALAPPDATA%\droidrun\droidrun\config.yaml ✓
5
  ADB                    found, 1 device(s)                         ✓
6
  Device                 10AF5J16******* (online)                   ✓
7
  Portal                 installed                                  ✓
8
  Portal Version         v0.7.25 (pinned for mobilerun 0.6.22)      ✓
9
  Accessibility          enabled                                    ✓
10
  Content Provider       reachable                                  ✓
11
  State (content)        a11y_tree, phone_state, device_context (via content_provider) ✓
12
  Screenshot (content)   ok (194 KB)                                ✓
13
  TCP Mode               localhost:58779                            ✓
14
  State (tcp)            a11y_tree, phone_state, device_context (via tcp) ✓
15
  Screenshot (tcp)       ok (194 KB)                                ✓
16
  Keyboard               not listed                                 ⚠
17

18
  1 warning(s):
19
    ⚠ Keyboard: not listed
20
      Will be set up automatically when needed

Keyboard: not listed 是说明 mobilerun 的输入法（MobilerunKeyboardIME）尚未启用，按需自动安装，不影响使用。

8.2 组件版本清单#

组件	版本	位置
uv	0.9.22	`%USERPROFILE%\.local\bin\uv.exe`
mobilerun	v0.6.22	`%USERPROFILE%\.local\bin\mobilerun.exe`
Python（mobilerun 用）	3.13.11	`%APPDATA%\uv\python\cpython-3.13.11-windows-x86_64-none\`
Python（系统）	3.14.8	`C:\Python314\python.exe`（未被 mobilerun 使用）
adb	1.0.41 / 37.0.1	`%LOCALAPPDATA%\Android\Sdk\platform-tools\adb.exe`
Portal（设备端）	0.7.25	vivo V2458A，包名 `com.mobilerun.portal`
LLM	DeepSeek `deepseek-flash`	5 个 profile 全部指向它

8.3 环境变量与 PATH#

用户级 PATH（最终）：

1
%USERPROFILE%\.local\bin
2
%LOCALAPPDATA%\Programs\DeepSeek Harness\resources\runtime\cli\bin
3
%LOCALAPPDATA%\pnpm\bin
4
%LOCALAPPDATA%\Microsoft\WindowsApps
5
%APPDATA%\npm
6
%LOCALAPPDATA%\Programs\Microsoft VS Code\bin
7
%LOCALAPPDATA%\Android\Sdk\platform-tools      ← 本次新增

用户级环境变量新增：DEEPSEEK_API_KEY（已脱敏）

8.4 本次产生 / 修改的文件#

文件	说明
`%LOCALAPPDATA%\droidrun\droidrun\config.yaml`	已修改：5 个 profile → DeepSeek/deepseek-flash
`%LOCALAPPDATA%\droidrun\droidrun\config.yaml.bak-20261008-185427`	改动前备份
`%LOCALAPPDATA%\Android\Sdk\platform-tools\`	新增：14 个文件（adb 全套）
`%USERPROFILE%\.local\share\mobilerun\portal\com.mobilerun.portal-0.7.25.apk`	新增：51MB APK 缓存
`%USERPROFILE%\Downloads\platform-tools-latest-windows\`	未改动（原样保留）

9. 使用指南#

9.1 首次使用前必做#

重开一个终端（PATH 与环境变量的改动只对新进程生效），然后：

1
mobilerun devices
2
mobilerun run "打开设置，开启深色模式"

9.2 常用命令#

1
mobilerun ping                                        # 检查设备就绪
2
mobilerun doctor                                      # 全链路体检
3
mobilerun device ui                                   # 打印当前无障碍树（带 bounds）
4
mobilerun device screenshot                           # 截图
5
mobilerun device tap 500 1200                         # 坐标点击
6
mobilerun device start com.android.settings           # 启动应用
7
mobilerun run "..." --steps 30 --debug                # 加步数 + 调试日志
8
mobilerun run "..." --reasoning                       # manager-executor 规划模式

9.3 ⚠️ 重要注意事项#

不要用 --vision / --vision-only DeepSeek 目前只有 deepseek-flash 和 deepseek-v4-pro 两个纯文本模型，没有视觉模型。开启截图理解会失败。默认配置未开 vision，保持现状即可。
不要跑 mobilerun setup 它固定用 -g，在 vivo 上必然报 INSTALL_FAILED_ABORTED。Portal 已装好，无需再跑。
mobilerun configure 无法配置 DeepSeek 向导里没有这个选项。要改模型只能直接编辑 config.yaml。
换更强模型 把 config.yaml 里 5 处 model: deepseek-flash 改成 model: deepseek-v4-pro（已验证同样支持 function calling）。
重启后无障碍服务掉线 vivo 后台管控较强，已加入电池优化白名单。若仍掉线，去「设置 → 无障碍 → Mobilerun Portal」重新打开。
事实性结论需复核 见 7.3：Agent 曾把 Android 16 误报为 15。

10. 避坑清单与复现命令#

10.1 从零复现的关键命令（Windows）#

1
# 0) 确认 uv 已装 + 清华源
2
uv --version
3
Get-Content "$env:APPDATA\uv\uv.toml"      # 应含 pypi.tuna.tsinghua.edu.cn
4

5
# 1) adb 进 PATH（复制到稳定位置，保留原目录）
6
$dst = "$env:LOCALAPPDATA\Android\Sdk\platform-tools"
7
New-Item -ItemType Directory -Force -Path (Split-Path $dst) | Out-Null
8
Copy-Item "$env:USERPROFILE\Downloads\platform-tools-latest-windows\platform-tools" $dst -Recurse -Force
9
$p = @(([Environment]::GetEnvironmentVariable("Path","User") -split ';' | ? {$_}) + $dst + "$env:USERPROFILE\.local\bin" | Select-Object -Unique)
10
[Environment]::SetEnvironmentVariable("Path", ($p -join ';'), "User")
11

12
# 2) 经镜像下载 Portal APK（GitHub 直连会卡死）
13
$cache = "$env:USERPROFILE\.local\share\mobilerun\portal"
14
New-Item -ItemType Directory -Force -Path $cache | Out-Null
15
curl.exe -L --retry 3 -o "$cache\com.mobilerun.portal-0.7.25.apk" `
16
  "https://ghfast.top/https://github.com/droidrun/mobilerun-portal/releases/download/v0.7.25/com.mobilerun.portal-0.7.25.apk"
17
# 期望大小 53610015
18

19
# 3) 安装 Portal —— 必须去掉 -g（vivo 会拒）
20
adb install -r -t "$cache\com.mobilerun.portal-0.7.25.apk"
21

22
# 4) 启用无障碍服务（先确认没有其它已启用的服务！）
23
$svc = "com.mobilerun.portal/com.mobilerun.portal.service.MobilerunAccessibilityService"
24
adb shell settings put secure enabled_accessibility_services $svc
25
adb shell settings put secure accessibility_enabled 1
26

27
# 5) 电池优化白名单（vivo）
28
adb shell dumpsys deviceidle whitelist +com.mobilerun.portal
29

30
# 6) 验证
31
mobilerun ping
32
mobilerun doctor

10.2 一句话避坑表#

坑	一句话对策
GitHub 大文件下载卡死	URL 前加 `https://ghfast.top/`
vivo 拒绝 `-g`	用 `adb install -r -t`，去掉 `-g`
系统只有 Python 3.14	不用管，uv 会自动用 3.13.11
清华没有 astral-sh 镜像	走 ghfast.top，不要找清华
DeepSeek 配不进向导	手写 `config.yaml` + `DEEPSEEK_API_KEY` 环境变量
`adb`/`mobilerun` 找不到	改完 PATH 要重开终端

11. 安全提示#

API Key 已脱敏 本文档刻意不包含 DeepSeek API Key 明文。原因：本文件位于 git 仓库内，明文密钥会被提交进版本历史，事后即使删除也难以彻底清除。
Key 的实际存放位置
- 用户级环境变量 DEEPSEEK_API_KEY（注册表 HKCU\Environment，明文）
- 相关会话的聊天记录中曾出现明文
建议轮换 如果该 Key 有额度意义，建议在 https://platform.deepseek.com 轮换一次。

本文的脱敏处理 为公开发布，文中替换了以下标识，不影响任何命令的复现：

原内容	替换为	说明
Windows 用户名	`%USERPROFILE%` / `%APPDATA%` / `%LOCALAPPDATA%`	PowerShell 代码块内用 `$env:USERPROFILE`，可直接粘贴运行
设备序列号	`10AF5J16*******`	仅保留前 8 位
本地仓库绝对路径	以「博客仓库目录」代指	——

仍刻意保留的内容及理由：

设备型号 V2458A / PD2415M：公开产品型号，非用户专有；且 7.3 节的问题分析依赖它
APK 的 md5、localhost 随机端口：构建产物校验值与本机端口，不指向个人
各版本号、字节数、包名：公开信息

另需注意：站点作者名本身已是公开的，所以本文脱敏 Windows 用户名只能避免「正文里再出现一份」，无法隐藏作者身份。

本文档由实际命令输出与源码查阅结果整理而成；所有版本号、字节数、路径均来自真实执行结果。

目录#