@zseven-w/dsh-android

dsh plugin --profile web add @zseven-w/dsh-android

<p align="center">

<img src="./docs/images/dsh-android-logo.png" alt="DSH Android" width="120" />

</p>

<h1 align="center">DSH Android</h1>

<p align="center">

<strong>把一台真实运行的 Android 设备放进 <a href="https://github.com/deepseek-ai/deepseek-harness">DeepSeek Harness</a> 对话里 —— 模拟器或 USB 手机，全部由 adb 驱动。</strong><br />

_{20 个 agent 工具 &bull; 进程内直播流，无外部依赖 &bull; 三键导航面板 &bull; Gradle 构建运行 &bull; Vision OCR}

</p>

<p align="center">

_{npm: <code>@zseven-w/dsh-android</code> &middot; 当前插件版本: <code>0.1.0-rc.12</code> &middot; 已在 DSH <code>0.1.5-rc.1</code> 上验证}

</p>

<p align="center">

<a href="./README.md">English</a> &middot; <b>简体中文</b> &middot; <a href="./README.zh-TW.md">繁體中文</a> &middot; <a href="./README.ja.md">日本語</a> &middot; <a href="./README.ko.md">한국어</a> &middot; <a href="./README.fr.md">Français</a> &middot; <a href="./README.es.md">Español</a> &middot; <a href="./README.de.md">Deutsch</a> &middot; <a href="./README.pt.md">Português</a> &middot; <a href="./README.ru.md">Русский</a> &middot; <a href="./README.hi.md">हिन्दी</a> &middot; <a href="./README.tr.md">Türkçe</a> &middot; <a href="./README.th.md">ไทย</a> &middot; <a href="./README.vi.md">Tiếng Việt</a> &middot; <a href="./README.id.md">Bahasa Indonesia</a>

</p>

<br />

<p align="center">

<img src="./docs/images/dsh-android-overview.png" alt="DSH Android — 对话里的实时 Android 设备" width="100%" />

</p>

<p align="center">_{在 DSH 对话中直接启动、投流并操作 Android 设备 —— 中间是 Agent 的工具调用，右侧是实时设备面板}</p>

为什么用 DSH Android

DSH Android 把一台真实的 Android 设备交给 agent，同时把画面交给你。agent 可以在模拟器或 USB 手机上开流、构建并安装 Gradle 工程、按 resource-id/文本或 OCR 驱动界面、读取 logcat、检查进程与内存；与此同时设备画面实时渲染在侧边栏面板里，你可以直接在视频上点击、拖拽、旋转，并按下 返回 / 主页 / 多任务。没有 image block，也没有录屏文件：可视字节只通过 DSH webserver 提供的签名短时 URL 抵达界面。

整个插件只有一条代码路径。adb devices -l 报出的 serial 就是设备的唯一身份 —— emulator-5554、USB serial、ip:port 目标行为完全一致。插件不绑定任何模拟器产品（AVD / Genymotion / WSA / 云真机），也不存在"模拟器 vs 真机"两套栈要分别推理。

📱 对话里的实时设备 · 进程内生成的 multipart/x-mixed-replace PNG 流，直接从最新帧缓冲经签名路由 /_dsh/dsh-android/* 送出。

🔌 无外部流服务、无内部端口 · 一个常驻 adb exec-out 子进程跑 while :; do screencap -p; done，宿主自己把连续 PNG 切成帧。没有 loopback 流服务器要代理，没有端口区间要管理，也没有异常退出后的孤儿进程要收养。

🧩 单一 adb 代码路径 · 对 adb 而言模拟器与手机是同一种东西，对本插件同样如此。没有 simctl/WebDriverAgent 双栈，真机也不需要先构建签名再信任。

🛠️ 20 个 agent 工具 · 设备枚举、开流/关机、截图、交互、Gradle 构建运行、应用列举与启动、uiautomator 控件树 + 按元素点击、列表行操作、Vision OCR 查找/点击/等待、logcat、进程、ANR/崩溃栈、meminfo、应用信息。

👆 三键导航面板 · 在直播画面上点击与拖拽；工具栏含 ◁ 返回 · ○ 主页 · □ 多任务，外加旋转、截图、刷新；设备菜单提供通知栏、快捷设置、锁屏、唤醒、语音助手五个动作。

🖼️ 原生多模态 · 在支持图像输入的模型上，所有截图类工具（screenshot、interact、tap_element、tap_text、tap_row）会把截图本身作为 image block 一并返回——模型直接"看到"屏幕。OCR 保留用于像素级精确的文字点按与纯文本模型；纯文本路由维持原有 JSON 摘要不变。

🔐 签名的 loopback 专属路由 · 每条路由在读取任何 capability 之前先要求：loopback 对端、loopback Host（拒绝 DNS 重绑定）、Fetch-Metadata/Origin 校验。HMAC-SHA256 capability 10 分钟内过期。

🔍 语义 + 视觉双路自动化 · android_ui_tree 导出 uiautomator 层级，android_tap_element 按 resource-id、文本或 content-description 点击；当控件树为空或文字被烧进图片时，android_find_text / android_tap_text 直接 OCR 屏幕，而不是猜坐标。

工具

20 个工具在任何宿主上都会注册，返回纯 JSON —— 可视字节只经由 presentationMeta + 签名路由抵达界面，绝不作为 image block。adb 解析不到时工具照常注册，每次调用返回带修复指引的可解释错误。

所有坐标一律是流画面的归一化 0..1。帧跟随显示旋转（横屏 app 在 1080×2400 设备上就是 2400×1080），而 input tap 用的是同一个坐标空间，所以本插件的客户端里没有任何旋转换算。

核心工具

工具 · 作用 · 关键参数

android_devices · 列出 adb devices -l 报出的每台设备（serial、状态、模拟器/实体、型号、Android 版本、API level、AVD 名），以及本机的 AVD 名列在 avds 字段。用它拿到其余工具需要的 serial。枚举失败会抛错，而不是返回空列表。 · —

android_boot · 开启直播流。传入在线 serial 立即开流；传入 AVD 名则先启动该模拟器，等它启动完成后再开流（冷启动需数分钟）。流在整个对话期间保持，面板因此能持续显示设备。 · device（必填 —— serial 或 AVD 名）

android_shutdown · 关闭模拟器（adb emu kill）并在流指向它时停流。实体机会被拒绝并说明原因：adb 没有关闭手机电源的动词。 · device

android_screenshot · 抓一张 PNG 并返回精简 JSON 摘要（路径、字节数、尺寸、设备）；图片渲染在卡片与面板里，绝不作为 image block。 · device（可选 —— 默认流中设备，其次唯一在线设备）

android_interact · 与流中设备交互：按归一化 0..1 坐标点击、输入文本、按导航或硬件键（back、home、recents、power、volume_up、volume_down、menu、enter、delete）、发送滑动手势或滚动。动作沉降约 300 ms 后自动截图展示效果。 · action（必填 —— tap/type/button/gesture/scroll）、x/y、text、name、json、device

android_list_apps · 列出设备上已安装的包（pm list packages），附带 dumpsys package 里的版本名，以及能取到时的人类可读标签 —— 第三方包名猜不出来，所以要么先列举，要么给 android_launch_app 传 name。 · device、query（大小写不敏感子串，含中文）、include_system（默认 false）

android_launch_app · 按 packageName 启动已安装应用，或按 name（经同一列举解析的标签子串，大小写不敏感）启动。二者必须且只能给一个。relaunch 会先 force-stop。 · packageName 或 name（二选一）、device、relaunch

android_build_run · 构建 Gradle 工程（./gradlew assembleDebug）、安装产出的 debug APK（adb install -r）并启动。完整构建耗时数分钟；失败时结果里带 Gradle 错误输出的尾部。 · projectPath（必填）、device

控件树与列表行工具（uiautomator）

工具 · 作用 · 关键参数

android_ui_tree · 导出前台应用的 uiautomator 层级为节点 —— type（类名尾段）、text、contentDesc、resourceId、像素 bounds、enabled、focused —— 上限约 40 KB（先剪最深层并置 truncated）。 · device、max_depth、filter（对 text/content-description/resource-id 的大小写不敏感子串）

android_tap_element · 按身份点击元素 —— resource_id 匹配节点的 resource-id，text 匹配其文本或 content-description。先精确匹配，再大小写不敏感包含；嵌套重复项折叠为一个目标，歧义时列出最多 8 个候选而不是替你挑一个。disabled 元素会被拒绝。点击落在元素中心，约 300 ms 后截图展示效果；传 expect_text / expect_gone 则点击与验证合成一个回合。 · device、resource_id、text、expect_text、expect_gone

android_ui_rows · 把列表/信息流界面（RecyclerView 之类）读成行而不是原始树：重复的同构子项变成行，各带索引、像素 frame、聚合标签，以及从该标签里解析出的计数器（数字 + 量词，中英文皆可 —— 不硬编码任何 app 词汇）。计数器 key 可原样回传：把列出的 key 一字不差地交给 android_tap_row.expect_count。 · device、max_depth

android_tap_row · 在某个可见行内按相对位置点击（index 来自 android_ui_rows；x/y 是该行 frame 的分数，默认 0.5 = 中心）。行 frame 来自一次全新的树读取，因此不猜任何绝对坐标；越界 index 直接 FAIL，绝不 clamp。带 expect_count={key, delta} 时，工具在约 800 ms 后重读该行并验证计数器恰好变化 ±1；key 不在该行已解析的计数器里则点击前就拒绝执行。 · device、index（必填）、x、y、expect_count（{key, delta}）

OCR、日志与调试工具

工具 · 作用 · 关键参数

`android_find

…(truncated)