Skip to main content
A

dsh-mobile-android-test

ayaojies/dsh-mobile-android-test

Run an APK in a managed Android emulator inside DeepSeek Harness: upload it, mirror the screen, drive it with mouse and keyboard, and inspect decrypted HTTPS requests like DevTools. Needs Windows with hardware virtualization, JDK 17+, Python 3.10+, and about 5 GB for the first Android SDK install. Its HTTP routes have no DSH access check, so a web page open in your browser could call them.

Install

dsh plugin --profile web add github:ayaojies/dsh-mobile-android-test

README

移动 App 测试(Mobile app testing)

在 DSH Web GUI 里直接运行手机 App:上传 APK → 自动装进本机托管的安卓模拟器 → 页面内实时投屏并可触控操作 → 像 Chrome DevTools 一样查看 App 发出的 HTTPS 请求(完整解密)。

安装

# 从 npm 安装(发布后可用)
dsh plugin --profile web add @ayaojies/dsh-mobile-android-test

# 或者直接从 GitHub 安装
dsh plugin --profile web add github:@ayaojies/dsh-mobile-android-test

也可以在 DSH 的 Plugins → Add plugin 里选择本地目录安装。安装/升级后重启 DSH。

系统要求

项要求
系统Windows 10/11(主要目标;macOS/Linux 未验证,路径与进程管理按 Windows 编写)
硬件支持 VT-x/AMD-V 的 CPU,并启用 Windows Hypervisor Platform 或 Hyper-V(否则模拟器无硬件加速)
依赖Node 22+(DSH 自带)、JDK 17+(安装 Android SDK 用)、Python 3.10+(抓包引擎 venv)
磁盘首次安装 SDK + 系统镜像约 5GB;同时装两套运行时(64 位主运行时 + 32 位 AOSP 兼容运行时)约 20GB
网络首次安装需能访问 dl.google.com(约 3–4GB 下载)与 PyPI(安装 mitmproxy)
权限无需管理员;只操作本机模拟器与 %LOCALAPPDATA%\dsh-mobile-test

隐私与安全边界

  • 插件会启动 Android 模拟器进程、调用 adb,并在 127.0.0.1 上运行 mitmproxy 代理;所有数据只留在本机,不上传任何服务器。
  • 解密 HTTPS 需要把 plugin 生成的 CA 装进模拟器证书区:主运行时 / AOSP 兼容运行时写系统证书区(模拟器内),Google APIs 32 位镜像退化为用户证书区(仅 debuggable App 生效)。
  • CA 私钥保存在 %LOCALAPPDATA%\dsh-mobile-test\mitm,请勿分发;不要用登录真实敏感账号的账号在模拟器里测试。
  • 证书固定(certificate pinning)的 App 无法解密,这是 TLS 机制决定的,不是插件缺陷。
  • 插件的所有 HTTP 路由都做了同源校验,APK 上传接口限制 1GB。

它在页面里的位置

  • 左侧栏多一个「移动 App 测试」图标,点开是一个全屏面板。
  • 面板分三段,随运行时状态自动切换:检测中 → 未安装(一键下载)→ 就绪(设备 + 网络 + 日志)。

首次使用

  1. 点开侧栏「移动 App 测试」。页面立即显示「正在检测本机安卓运行时…」。
  2. 如果本机没有 Android SDK/模拟器,会列出缺什么,并给一个**「一键下载并安装」**按钮:
    • 自动下载 commandline-tools(约 146MB)→ sdkmanager 安装 platform-tools / emulator / system-images;android-33;google_apis;x86_64(约 1GB)→ 自动创建并配置 AVD(720×1280 / 320dpi)。
    • 全程有总进度条、实时下载速度、已下载量、剩余时间、步骤条与日志,可随时取消。
    • 实测:约 8 分钟(视网络;支持断点续传、失败重试)。
  3. 就绪后点「启动模拟器」(首次冷启动约 2–3 分钟)。
  4. 在设备区点「上传 APK」,选一个 .apk → 自动安装 → 应用列表里点「启动」。
  5. 点「开始抓包」:插件启动内置 MITM 代理、把设备代理指向本机,并自动 adb root + remount 把自签 CA 装进设备系统信任区(现代 Android 会自动 disable-verity 并重启一次)。之后 App 的 HTTPS 请求就以明文出现在右侧网络面板。

顶栏「停止模拟器」右侧的 ⚙ 按钮随时打开「运行环境管理」:可以查看两套运行时的安装状态、单独下载/重装任意一套、或一键「启动并切换」到另一套。

两套运行时(为什么需要)

运行时镜像适用 App
主运行时system-images;android-33;google_apis;x86_64(Android 13 / 64 位)绝大多数 App;HTTPS 解密可用
兼容运行时system-images;android-30;google_apis;x86(Android 11 / 32 位)只打包了 32 位 native 库(x86 / armeabi-v7a)的老 App 或混合打包的 App;HTTPS 解密同样可用

上传 APK 时插件会读它的 lib/<abi>/ 目录和当前设备 ABI 做对比:

  • 不匹配时不会白等安装失败(秒级返回),而是弹出可操作卡片,一键「安装兼容镜像」(约 1.1GB)→「切换到兼容模拟器」→ 重新上传即可。
  • 典型场景:某 App 里只有 arm64-v8a / armeabi-v7a / armeabi / x86 而没有 x86_64,在 64 位模拟器上会报 INSTALL_FAILED_NO_MATCHING_ABIS,切到 32 位兼容运行时后其 lib/x86 可原生运行。

功能

区块能力
运行时自动检测 SDK/adb/emulator/AVD/设备;一键安装带速度/剩余时间进度;虚拟化不可用时给出可复制的修复命令;支持插真机(开 USB 调试即可自动识别);⚙ 环境管理可随时下载/重装/切换两套运行时
设备实时投屏(PNG 轮询,默认 4fps,可配)、点击、拖拽滑动、返回/主页/任务/旋转、文本输入、上传并安装 APK(含 ABI 预检)、已装应用列表与启停
网络开始/停止抓包、明文 HTTPS 解密、请求表(方法/状态/主机/路径/耗时/大小,分色)、详情(请求/响应 Headers、Body 预览)、过滤、清空、CA 证书下载
日志logcat 增量流,按级别过滤(E/W/I/D),自动滚底

配置

在 cordis.patch.yml 里改这一行的 config(重启 DSH 或重载 profile 后生效):

- insert:
    - id: dsh-mobile-test
      name: '@local/dsh-mobile-test'
      config:
        dataDir: ''                                            # 默认 %LOCALAPPDATA%\dsh-mobile-test
        sdkDir: ''                                             # 默认 <dataDir>\android-sdk
        systemImage: 'system-images;android-33;google_apis;x86_64'
        avdName: 'dsh-mobile-test'
        avdDevice: 'pixel_5'
        proxyPort: 8899
        screenMaxFps: 4                                        # 投屏帧率上限,越高越吃 CPU
        captureMaxRequests: 3000                               # 抓包内存条数上限
        captureMaxBodyBytes: 262144                            # 单条 body 预览上限(256KB)

数据都落在 dataDir:android-sdk/(SDK)、mitm/(CA 与 mitmproxy 配置)、capture/(venv 与 events.jsonl)、apks/(上传的安装包)。

常见问题

模拟器起不来 / 提示没有硬件加速。 需要 Windows「虚拟机监控程序平台」(WHPX)或 Google AEHD 驱动。以管理员运行 DISM /Online /Enable-Feature /FeatureName:HypervisorPlatform /All 后重启;或 sdkmanager "extras;google;Android_Emulator_Hypervisor_Driver" 后在 <sdkDir>\extras\google\Android_Emulator_Hypervisor_Driver 以管理员运行 silent_install.bat。 不想折腾虚拟化就插真机、开 USB 调试,插件会自动识别。

SDK 下载很慢或失败。 国内直连 dl.google.com 可能不稳定;插件已做 3 次重试 + 指数退避 + 断点续传,失败后可在页面重试(已下载部分不会重来)。

抓包看不到某个 App 的请求。 两种常见原因:

  1. CA 没装成功 —— 网络面板顶部会有提示,点它重试;也可下载 ca.pem 手动安装。
  2. App 做了 证书固定(certificate pinning) —— MITM 原理上无法解密,请求会显示为失败。这类 App 需要额外用 Frida/objection 之类的脱壳手段,本插件不提供。 另外 capture/start 首次会创建 Python venv 并 pip install mitmproxy(约 1–2 分钟,自动切换清华/阿里镜像);若三个源都不可用会降级为隧道模式:仍能看到域名、端口、连接时长,但看不到 HTTPS 明文,面板上会明确标注。

32 位兼容运行时上抓不到 HTTPS 明文。 这是有意的安全限制:32 位 API 30 镜像在禁用 dm-verity 后无法可靠重启(实测会让模拟器起不来),所以插件在检测到 32 位兼容镜像时直接跳过写系统 CA,只返回一条中文说明,模拟器保持在线可正常投屏。需要解密抓包时请切回主运行时(Android 13)。

抓到 HTTPS 但状态码是空的 / 10 秒超时。 说明设备侧发不出请求(目标域名不可达或被墙),不是插件问题。

端口占用。 默认代理端口 8899、模拟器 5554/5556/5558;冲突时模拟器会自动换端口,代理端口可在配置里改。

安全与隐私

  • 抓包代理只监听 127.0.0.1,CA 私钥只在本机 dataDir\mitm 下,不要把 mitmproxy-ca.pem 分发给别人。
  • 装进模拟器系统信任区的 CA 只影响这台模拟器;模拟器建议只用于测试,不要登录真实敏感账号。
  • 插件所有 HTTP 路由都做了同源校验(拒绝跨站请求),上传接口限制 1GB。

抓包的两种模式(重要)

网络栏工具栏有个 「解密 HTTPS」开关,它决定抓包是否介入 TLS:

模式开关能看到什么App 联网
解密模式开完整请求/响应:URL、Headers、状态码、Body需要设备信任插件的 CA;做了证书固定的 App 会失败
隧道模式关域名、端口、CONNECT 状态、耗时、字节数(看不到内容)完全不受影响,与自己直连一致

自动行为(不需要你操心):

  • 设备上装不了 CA 时(例如 32 位兼容镜像,或打开抓包后 CA 推送失败),插件会自动降级为隧道模式,而不是把 App 的网络打断;
  • 反过来,在隧道模式下点黄色提示条里的「尝试安装 CA 证书」,装成功会自动切回解密模式。

什么时候必须用隧道模式:

  • 用 32 位兼容运行时(该镜像无法可靠写系统分区,见下方限制);
  • App 做了证书固定(certificate pinning)。典型特征是抓包一开 App 就报网络错误、拿不到返回值 —— 比如自带阿里 SecurityGuard(libsgmain.so)的 App。这类 App 即使 CA 装好了也无法被 MITM 解密,请关掉开关。

操作延迟与键盘输入

点击/滑动不再走 adb shell input(每次要在设备里新起一个 app_process,实测 850–1565ms/次),而是走模拟器自带的 gRPC 输入接口(sendTouch / sendKey,持久 HTTP/2 连接):

操作之前(adb)现在(gRPC)
点击850–1565 ms9–16 ms
按键805 ms4 ms
输入文本1797 ms6 ms

另外页面在按下的瞬间就会画一个涟漪/拖拽轨迹(不等下一帧截图),所以手感是即时的。设备栏会显示「输入 2ms 级」徽标确认当前走的是 gRPC 通道。

电脑键盘输入:点一下投屏画面(出现品牌色描边=键盘已连接),然后直接用电脑键盘打字即可:

  • 普通字符、中文输入法上屏文字 → 直接注入到 App 的输入框;
  • Enter / Backspace / Tab / Esc / Delete / 方向键 / Home / End / PageUp / PageDown → 对应按键;
  • Ctrl+V / Cmd+V → 把电脑剪贴板内容整段注入(长文本、中文最可靠);
  • 页面里的「文本输入框」仍保留作兜底;点输入框打字时不会劫持按键。

真机(无 gRPC 通道)会自动回退到 adb 输入,功能可用但明显慢一些。

投屏性能

投屏走「截图泵」:后台用 4 路并发 adb exec-out screencap 持续抓帧,只保留最新一帧,页面按需取最鲜的一帧(双缓冲,最多 2 个请求在飞),因此帧率不再被单次 adb 调用串行拖慢。页面还会显示实时帧率徽标。

实测(本机 32 位兼容运行时,跑着真实 App 界面):

投屏分辨率帧率每帧大小
720×1280(原生)9.4 fps~60KB
540×9609.4 fps~42KB
480×80010.8 fps~29KB

改造前是 2.1 fps(单发 screencap -p 468ms,其中设备端 PNG 编码占 234ms)。帧率与画面复杂度有关:纯色/文字界面更快,图片密集界面会低一些。

想要更流畅可以调低投屏分辨率,在 cordis.patch.yml 里加:

        mirrorWidth: 480        # 0 = 用设备原生分辨率
        mirrorHeight: 800
        screenPumpConcurrency: 4   # 截图并发数,1-8;1 个 ≈ 2.5fps,4 个 ≈ 9fps

也可以调 screenMaxFps(页面取帧上限,默认 10)。设备栏会显示实时帧率,低于 4fps 时会提示你调 mirrorWidth。

已知限制

  • 页面内嵌的是「截图流 + 触控转发」,不是真正的视频流:默认 4fps,动作类测试够用,不适合验证动画流畅度。
  • 只支持 Android(APK);iOS 需要 macOS。
  • 系统 CA 需要 root + 可写 system;Play Store 版镜像(...;google_apis_playstore;...)不允许 adb root,请用 google_apis 或 AOSP 镜像。
  • 真机装系统 CA 需要 root;未 root 的真机只能看到 HTTP 明文与连接信息。
  • 兼容运行时的 Android 版本固定为 11(API 30):App 的 minSdk 高于 30 时无法安装在该环境,需要改用更高 API 的 32 位镜像(目前 Google 只为 API 30 及以下提供 32 位 x86 镜像)。
  • 模拟器同一时刻只跑一套运行时;「启动并切换」会先停掉当前那套。

开发者说明

  • 结构:index.js(Host 路由 + 生命周期)、lib/runtime.mjs(安卓运行时)、lib/capture.mjs(抓包引擎)、client.js(浏览器半边)、docs/API.md(内部契约)。
  • 零 npm 依赖,只用 Node 内置模块;抓包依赖 Python + mitmproxy(插件自建 venv)。
  • 自测脚本在 tmp/:api-smoke.mjs(接口冒烟)、verify-mitm.py(用 Python ssl 验证 MITM 解密)、client-lint.mjs(前端静态检查)、ui-ssr/render-test.mjs(真实 React SSR 渲染)。

Related plugins