dsh-android-agent — DSH 手机测试插件（Android Agent App 控制器）

English | 中文

为 DeepSeek Harness（DSH）定制的手机 App 测试插件：通过 WebSocket 连接同一局域网内、已安装 dsh-android-agent 的安卓手机，在 dsh-web 侧边栏「手机」面板里完成打开 App、坐标点击、输入文本、滑动、按键、截图、UI 树读取，并给 Agent 提供同等的 phone_* 工具，主要用于手机 App 的自动化测试。全部通过官方 NPM SDK 实现，不修改 DSH 源码。

能力

| 能力 | 说明 | | --- | --- | | 设备管理 | 增删改查手机设备（别名 / WebSocket 地址 / Token / 备注）；配置存 ~/.dsh/dsh-phone.json（0600） | | 连接管理 | 每设备一条 WebSocket 长连接（ws://手机IP:8080/ws?token=...），断线自动重连（最多 3 次），面板每 5s 刷新状态 | | 打开 App | openApp 按包名启动应用（如 com.android.settings） | | 点击 / 滑动 | tap / swipe，屏幕像素坐标，滑动可设时长 | | 输入文本 | inputText 先点坐标聚焦再输入（无障碍 ACTION_SET_TEXT / 粘贴实现） | | 按键 | keyevent（back=4 / home=3 / recents=187 / enter=66 / delete=67 ...） | | 截图 | 面板内预览 + 保存下载；Agent 工具另存到 ~/.dsh/phone-screenshots | | UI 树 | getUI 转储无障碍节点（文本 / class / bounds / 可执行动作），配合 tap 定位元素 | | UI 树驱动操作 | phone_ui_find（按文本 / resourceId 查找）返回节点 bounds 与点击中心；phone_ui_tap 直接点击最匹配节点；phone_ui_input 按标签聚焦输入框并键入；phone_ui_back 发送返回键或边缘滑动返回手势。面板把 UI 树渲染成可点击的行列表（每行带 tap / input 按钮），无需手输坐标 | | Agent 工具 | phone_list / phone_rpc / phone_open_app / phone_tap / phone_input / phone_swipe / phone_keyevent / phone_screenshot / phone_get_ui / phone_ui_find / phone_ui_tap / phone_ui_input / phone_ui_back，与 GUI 共享同一份设备配置 |

安全模型

• 所有 /api/dsh-phone/* 路由仅限 loopback 访问（含同源校验）——驱动真实手机的执行接口不会暴露给局域网。
• Token 以明文保存在 ~/.dsh/dsh-phone.json（目录 0700、文件 0600，原子写入），与 dsh-ssh 同一信任模型。
• Agent 使用工具前，设备需先在 GUI「手机」面板中配置。
• 截图 / 操作消耗手机真实资源与电量；先确认再操作。

前置条件（手机端）

1. 安装并启动 Agent App 的前台服务（手机应用需开启无障碍 / 屏幕录制权限、同局域网）。
2. 记住 Agent 显示的本机 WebSocket 地址：ws://手机IP:8080/ws 与 Token。
3. 在 dsh-web「手机」面板添加设备：别名、WebSocket 地址、Token。

安装

本插件是独立包（不并入全家桶聚合包 @linxin666/dsh-web-ui-all），通过本地 link 单独安装：

### 从 npm 安装（尚未发布，待发布后可用）
dsh plugin --profile web add dsh-android-agent

### 本地独立包安装（开发调试，包位于 D:\code\dsh\dsh-android-agent）
cd D:\code\dsh\dsh-android-agent
pnpm install && pnpm build
dsh plugin --profile web add link:D:\code\dsh\dsh-android-agent

Windows 用户可一键安装（自动构建 + link 安装，PowerShell）：

powershell -ExecutionPolicy Bypass -File D:\code\dsh\dsh-android-agent\scripts\install.ps1

完整的安装与验证清单（构建 → 单测 → 安装 → GUI/真机验证）见 docs/VERIFY.md。

安装后重启 dsh web：侧边栏出现「手机」入口；Agent 提示词中自动出现插件说明。

数据

• 设备配置：~/.dsh/dsh-phone.json（版本化 JSON，原子写入）
• Agent 截图（工具保存）：~/.dsh/phone-screenshots/

开发

pnpm install
pnpm typecheck
pnpm build   # tsc 类型 + tsdown 双半区产物（lib/ + lib/client.js）

已知限制

• 手机端 inputText 依赖无障碍注入（ACTION_SET_TEXT / 剪贴板粘贴），个别输入框可能无法输入；root/Shizuku 下可用 shell 走 adb 式输入。
• 截图通过 JSON-RPC base64 传输，面板预览为 JPEG 默认（可切 PNG）。
• 断线自动重连可能重放未完成的操作（非幂等），长流程注意。
• 本插件只操作「用户已在 GUI 配置」的设备，不会臆造地址。