PangYiMing/dsh-mobile-control

dsh-mobile-control

DeepSeek Harness 插件 · 操控手机 / DSH plugin for controlling mobile devices

通过 WebDriverAgent（WDA） 驱动 iOS 模拟器：截图、点击、找元素、打开 URL、抓可访问性树。
WDA 是跑在模拟器内部的 XCUITest 运行器，暴露 localhost:8100 HTTP 服务——零 macOS 辅助功能授权、不依赖 idb、能点任意 app（含系统弹窗）。

Drives the iOS simulator through WebDriverAgent (WDA): screenshots, taps, element lookup, URL opening, accessibility-tree dumps. WDA is an in-simulator XCUITest runner exposing an HTTP API on localhost:8100 — no macOS accessibility permission, no idb, and it can tap any app, including system dialogs.

为什么用 WDA（而不是别的）

| 方案 | 问题 |
|---|---|
| idb (Meta) | homebrew-core 的 idb-companion formula 已下架，装不上 |
| cliclick / AppleScript | 走 macOS CGEvent，需要给终端授「辅助功能」权限，否则点了没反应 |
| WDA ✅ | 模拟器内部 XCTest 自动化特权点击，不走 CGEvent，任何 app 都能点 |

快速开始 Quick start

前置：完整版 Xcode（XCUITest 靠 testmanagerd 拉起，纯 simctl launch 起不来 HTTP 服务）。

bash scripts/wda-up.sh [UDID]            # 不传 UDID 用当前 Booted 的模拟器
curl -s localhost:8100/status | head -c 200   # 返回 build/os/device 即 OK

幂等设计：已在跑 → 秒返回；有缓存 → 免编译 ~30s；没缓存 → 首次 clone+编译一次（之后一直免编译）。端口自适应：WDA 构建产物的监听端口是编译时写死的（可能是 8100 或 8101 等），脚本从运行日志发现真实端口并写入 ~/.cache/webdriveragent/wda.port，插件和脚本都读它。模拟器包未签名、arch=arm64+x86_64，可跨 Mac 复用：把 Build/Products + .xctestrun 拷给别人，直接 test-without-building，谁都不用再编。真机不能这么白嫖（真机 WDA 必须用含设备 UDID 的描述文件重新签名）。

操控 API

见 docs/wda-drive.md：建会话、找元素、点击、坐标点击、可访问性树、截图、隐私预授权、scheme 打开 URL——全部 curl 可调。

DSH 工具 Tools

安装插件后，以下 mobile_ 工具自动注册进 agent 的工具集：

| 工具 | 说明 |
|---|---|
| mobile_status | 检查 WDA 是否在服务（端口自适应，默认 8100） |
| mobile_wda_up | 幂等启动 WDA（首次 clone+编译，之后免编译 ~30s） |
| mobile_screenshot | simctl 截图到 PNG |
| mobile_find_element | 按 accessibility label / class 找 UI 元素（返回元素 id） |
| mobile_tap | 点元素（elementId）或按逻辑点坐标（x/y）点击 |
| mobile_accessibility_tree | 导出当前前台 app 的可访问性树 XML |
| mobile_open_url | simctl openurl 打开 URL 或自定义 scheme 深链 |
| mobile_grant_privacy | simctl privacy grant 预授权，避免系统弹窗挡自动化 |

安装后直接在 agent 会话里用自然语言触发：
"用 mobile_wda_up 启动 WDA，然后 mobile_tap 点 (268, 492)"
dsh plugin --profile demo add dsh-mobile-control

路线图 Roadmap

- [x] WDA 幂等启动（scripts/wda-up.sh）
- [x] 建会话 / 找元素 / 点击 / 坐标点击 / 可访问性树
- [x] simctl 截图 + privacy 预授权
- [x] 自定义 scheme 打开 URL（deeplink）
- [x] 封装为 DSH 工具（8 个 mobile_ tools）
- [ ] Android（ADB）支持
- [ ] 元素级滑动 / 长按 / 输入文本

安装 Install

发布到 npm 后
dsh plugin --profile demo add dsh-mobile-control

或从 GitHub 安装（源码安装需要 prepare 构建）
dsh plugin --profile demo add github:PangYiMing/dsh-mobile-control

许可证 License

MIT