前言¶
在 DeepSeek Harness（DSH）里做 Android 开发或自动化，常见做法是截图来回传、手动跑 adb，或另起一套 Appium / UIAutomator 脚本。Agent 看得到日志，却难在对话里直接「看见」设备画面，你也很难在同一会话里点按、拖拽、读 logcat。
DSH Android 把这条链路收进一个插件：通过 adb 驱动模拟器或 USB 手机，在对话侧边栏呈现实时画面，并提供 20 个 agent 工具供构建、交互与调试。下面介绍它的定位、能力与安装用法。
这是什么¶
DSH Android（npm 包 @zseven-w/dsh-android）是 DeepSeek Harness 的客户端类插件，由 ZSeven-W 维护。当前插件版本为 0.1.0-rc.4，已在 DSH 0.1.1-rc.1 上验证；GitHub 仓库约 95 stars、6 forks。
一句话定位：在 DSH 对话中构建、运行并与一台在线的 Android 设备（模拟器或 USB 手机）交互，全程由 adb 驱动，不依赖外部流服务或 loopback 端口代理。
核心功能¶
单一 adb 代码路径¶
adb devices -l 报出的 serial 是设备唯一身份——emulator-5554、USB serial、ip:port 目标行为一致。插件不绑定特定模拟器产品（AVD、Genymotion、WSA 等），也不区分「模拟器栈」与「真机栈」。
进程内直播流与侧边栏面板¶
开流后，插件用常驻 adb exec-out 子进程循环执行 screencap -p，宿主自行切帧，生成 multipart/x-mixed-replace PNG 流，经 DSH webserver 的签名路由 /_dsh/dsh-android/* 送到界面。浏览器不与 adb 直接通信，也没有可代理的内部流端口。
侧边栏面板渲染实时画面，支持在视频上点击、拖拽，工具栏提供返回、主页、多任务，以及旋转、截图、刷新；设备菜单可触发通知栏、快捷设置、锁屏、唤醒、语音助手等动作。
20 个 agent 工具¶
工具在任何宿主上都会注册，返回纯 JSON；可视内容经 presentationMeta 与签名路由呈现，不作为 image block 直接塞给模型（支持图像输入的模型上，截图类工具另有原生多模态路径）。
坐标一律是流画面的归一化 0..1，帧跟随显示旋转，input tap 与流共用同一坐标空间。
核心工具包括：
| 工具 | 作用 |
|---|---|
android_devices |
枚举 adb 设备与本机 AVD 列表 |
android_boot |
对在线 serial 开流，或先启动指定 AVD 再开流 |
android_shutdown |
关闭模拟器并停流（实体机 adb 无法关机，会明确拒绝） |
android_screenshot |
抓取 PNG，返回 JSON 摘要 |
android_interact |
点击、输入、按键、手势、滚动 |
android_list_apps / android_launch_app |
列举与启动已安装应用 |
android_build_run |
./gradlew assembleDebug、安装 debug APK 并启动 |
UI 自动化侧提供 android_ui_tree、android_tap_element、android_ui_rows、android_tap_row（基于 uiautomator）。日志与调试侧提供 android_logs、android_processes、android_backtrace、android_meminfo、android_app_info。
OCR 工具 android_find_text、android_tap_text、android_wait_for 依赖 macOS 上的 Apple Vision 框架，仅在 macOS 宿主可用；Linux 与 Windows 上其余 17 个工具不受影响。
安全模型¶
流与截图路由要求 loopback 对端、loopback Host（拒绝 DNS 重绑定）、Fetch-Metadata/Origin 同源校验；HMAC-SHA256 capability 约 10 分钟内过期。截图路径逐级 lstat、拒绝符号链接，并用 realpath 做包含性校验。
安装与启用¶
插件以当前 DSH 进程权限运行，安装前应阅读 GitHub 源码 与 MIT 许可证，确认环境中有可信的 adb 与 Android 设备。
环境要求（摘自官方 README）：
- Node ≥ 24.11.0
- adb（Android SDK platform-tools），解析顺序：
ADB环境变量 →PATH→ SDK 默认路径 - 一台 adb 可见的设备（模拟器或开启 USB 调试的手机）
- 带 web bundle 的 DSH ≥ 0.1.0-rc.6 才有侧边栏面板；headless 配置下 20 个工具仍可用
先安装插件并启动 web 会话：
dsh plugin --profile web add @zseven-w/dsh-android@latest
dsh web
也可把包加入既有 profile 的依赖：
pnpm add @zseven-w/dsh-android
非 ASCII 文本输入（中文、emoji）需可选安装 ADBKeyboard 并设为当前输入法；未安装时相关输入会被拒绝并给出提示。
典型用法¶
官方快速上手流程如下。
- 发现设备——让 agent 调用
android_devices，取得 serial 或 AVD 名。 - 开流——对
emulator-5554等在线 serial 调用android_boot；传 AVD 名会先冷启动模拟器（可能需数分钟），随后面板显示实时画面。 - 交互——在面板上直接点按，或让 agent 用
android_interact；结构化点击可走android_ui_tree+android_tap_element；控件树不可用时在 macOS 上可用 OCR 工具。 - 构建运行——对 Gradle 工程调用
android_build_run，指定projectPath；完整构建耗时数分钟，成功后应用安装并启动。 - 读日志——
android_logs可按包名过滤，例如查看某应用最近两分钟的 logcat。
示例对话意图与工具对应关系：
列出 Android 设备。 → android_devices
把 emulator-5554 投出来。 → android_boot
打开设置，然后点显示。 → android_interact 或 android_ui_tree + android_tap_element
构建并运行 /path/to/MyApp。 → android_build_run
看 com.example.app 最近两分钟的 logcat。 → android_logs
适用场景与注意¶
适合谁
- 在 DSH 对话里做 Android 应用联调、UI 验证、logcat 排查的开发者
- 希望 agent 能驱动真实 adb 设备、而非只靠静态截图的自动化场景
- 已有 Gradle 工程，需要在会话内一键 build / install / launch 的团队
使用注意
- USB 真机帧率通常约 2–5 fps，模拟器约 5–10 fps；插件 README 在 Android 14 模拟器上实测常驻 screencap 循环约 8 fps。
android_shutdown不能关闭实体手机；adb 无此能力，工具会如实说明。- 设备状态为
unauthorized时，需在手机屏幕上确认 USB 调试授权；android_devices会报告状态而非隐藏设备。 - 模拟器画面全白/全黑但控件树正常时，可能是 host-GPU framebuffer 读回问题；可尝试
emulator -avd <名称> -gpu swiftshader_indirect软渲染重启。 - 流在消费者归零约 5 分钟后会因空闲策略停止，下次工具调用或打开面板时会重启。
DSH 生态采用「一切皆插件」思路；SkillHub 是社区插件目录，与 DeepSeek / 幻方无官方从属关系。
链接¶
- 社区目录：https://www.skillhub.cn/plugins/ZSeven-W/dsh-android
- GitHub 仓库：https://github.com/ZSeven-W/dsh-android
- npm 包：
@zseven-w/dsh-android
