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-agentWindows 用户可一键安装（自动构建 + 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 配置」的设备，不会臆造地址。