安卓手机操控 kunjinkao-os/dsh-mobile-gui-agent

DeepSeek Harness 移动端 GUI 智能体

移动端 GUI 智能体封面

awesome · DSH plugin

dsh-mobile-gui-agent 是可安装的 DeepSeek Harness 插件，通过 ADB 控制 Android 设备。它给 Harness Web UI 加了一个 mobile_gui_agent 入口，每项任务都走「观察 → 决策 → 执行 → 验证」循环。

仓库就是一个可发布的 npm 包。bundle 补丁插入一行 Cordis 插件；这个插件把 ADB Provider、Phone Agent Consumer、Phone 工具、Typert Remote 适配器和浏览器客户端组合在同一个生命周期下。

快速开始

连接并授权一台 Android 设备，然后把固定版本的 release 安装到 Harness Web 配置档：

adb devices -l
dsh plugin --profile web add github:kunjinkao-os/dsh-mobile-gui-agent#v0.2.1
dsh --profile web --dump-config
dsh --profile web

设备那一行必须显示 device。配置 dump 里必须包含 # == dsh-mobile-gui-agent 层和一行 dsh-mobile-gui-agent。想要最清晰的工作流，先在 Harness 会话里发一条简短的普通消息，再选中 mobile_gui_agent，在它的 Task 字段里输入真正的手机指令。不要在 Harness 的普通会话输入框里输入手机指令。操作账号或存有个人数据的设备之前，先看环境要求和使用。

推荐工作流

1. 选一个工作区，在 Harness 普通会话里发一条简短的初始化消息，比如 Prepare a mobile task。
2. 选中 mobile_gui_agent 会话标签页。
3. 选中已连接的设备，只在 mobile_gui_agent 里的 Task 字段输入真正的手机指令。
4. 点 Start，按验证过的步骤走。不要通过普通会话输入框发送手机指令。

空白会话工具栏启动器也能用，但上面的流程把 Harness 会话消息和手机任务分得更清楚。

mobile_gui_agent 设置并启用 12:00 闹钟

演示

打开 Android 设置并进入 Wi-Fi 页面：

mobile_gui_agent 打开设置并进入 Wi-Fi 用 deepseek_mobile 打开淘宝：

deepseek_mobile 打开淘宝

兼容性

- DeepSeek Harness：^0.1.0-rc.5
- 已对照上游 commit 47f943859bef60e4160492346772ded9b24f765a 验证
- 也已针对已发布的 0.1.0-rc.6 Harness 包完成构建与测试
- Node.js：^22.19.0 || >=24.0.0
- Android：一台真机或模拟器，能被 adb devices 识别

本包遵循上游的 dsh.bundle.patch 与 dsh.client 清单。它不会改动 Harness Agent 循环，也不依赖未发布的 Phone 包。

提供的能力

- ADB 设备发现、无线连接、截图、UIAutomator 层级抓取、点击、长按、滑动、可校验的文本输入与替换、按键、返回、主页，以及启动应用
- 截图与裁剪后的语义 UI 观察结果，元素 ID 只在本次观察内有效
- 严格的 phone_observe 与 phone_act Harness 工具
- 模型每轮只执行一个有意义的动作，随后重新观察并做确定性校验
- 过期元素保护、自适应屏幕稳定、卡死检测、步数与时间上限，以及可恢复的 ADB 错误
- 对可能发送、发布、删除、购买、支付、转账、拨号、安装或修改账号安全的语义控件，走 Harness 审批
- 空白会话的 mobile_gui_agent 启动器，以及 Web 会话标签页，支持选择设备、无线连接、刷新截图、任务控制、动作浮层和已校验步骤
- 用于无密钥 Agent 循环测试的假设备与脚本化状态迁移

本插件不安装 Android 无障碍服务。它把 ADB 截图与 Android UIAutomator 生成的层级结合起来。自定义 Canvas、WebView、游戏和纯图片控件可能出现在截图里，却不在层级中；这类界面可以让 Agent 使用支持视觉的模型输入，或选用 PhoneVisionProvider。

环境要求

1. 安装 Android Platform Tools，确认 adb version 能正常运行。
2. 在 Android 设备上开启开发者选项和 USB 调试。
3. Android 弹出 RSA 调试授权提示时，授权这台电脑。
4. 确认设备可用：

adb devices -l

选中的那一行必须显示 device，不能是 offline 或 unauthorized。
5. 使用 DeepSeek Harness Web 配置档。mobile_gui_agent 入口属于浏览器客户端贡献，因此纯无头配置档不会显示它。
观察、导航、输入可打印 ASCII 字符都不需要 root 权限，也不用在手机上装 APK。输入 Unicode 字符要靠外部 ADB Keyboard 辅助应用（com.android.adbkeyboard/.AdbIME）。装好这个辅助应用后，即使它处于禁用状态，插件也能发现它；插件只在执行 Unicode 操作时启用并选中它，随后恢复用户原先的输入法和已启用集合。整个过程不需要模型设置操作，也不需要用户交互。如果辅助应用确实不存在，用 adb.unicodeImeApkPath 配置一个绝对主机路径，指向经过审查的 APK；插件绝不会自行下载 APK，安装仍然需要 Harness 明确批准。

安装方式

把本地 checkout 安装到标准 Web 配置档：

dsh plugin --profile web add ./dsh-mobile-gui-agent
dsh --profile web --dump-config
dsh --profile web

从源码 checkout 运行 Harness 时，用 pnpm dsh 代替 dsh：

pnpm dsh plugin --profile web add ../dsh-mobile-gui-agent
pnpm dsh --profile web --dump-config
pnpm dsh --profile web

dump 结果里必须包含 # == dsh-mobile-gui-agent 层，以及一行名为 dsh-mobile-gui-agent 的记录。打开 Web UI，选择一个工作区。空白会话工具栏启动器可以立即打开任务面板。推荐的工作流是：先发一条简短的普通消息，创建非空白对话，然后选中常规的 mobile_gui_agent 标签页，在那里输入手机任务。

构建好的 lib/ 产物已纳入版本管理，因此可以安装固定版本的 Git checkout，而无需允许依赖构建脚本运行：

dsh plugin --profile web add github:kunjinkao-os/dsh-mobile-gui-agent#v0.2.1

想要不可变的审查目标，就把发布标签换成对应的 commit SHA。发布 tarball 也可以安装，无需 Git 构建步骤：

dsh plugin --profile web add ./dsh-mobile-gui-agent-0.2.1.tgz

安装能控制真实设备的插件时，请固定到经过审查的标签或 commit。

无线 ADB

当 Android 版本要求配对时，先用 Android Platform Tools 与手机配对，然后二选一：在启动 Harness 之前连接：

adb connect DEVICE_IP:PORT
adb devices -l

或者在 mobile_gui_agent 面板里输入 DEVICE_IP:PORT，然后选择 Connect。电脑和 Android 设备必须能互相访问，而且 Android 重启无线调试后，无线调试端口可能会变化。

使用

1. 打开 Harness 对话，发一条简短的初始化消息，例如 Prepare a mobile task。
2. 选中 mobile_gui_agent 对话标签页。空白会话工具栏启动器同样可用，作为替代入口。
3. 选择已连接的设备，刷新截图。
4. 在 mobile_gui_agent 内的 Task 字段里输入实际的手机任务，不要写在普通 Harness 对话输入框里。例如：

Open Settings and go to the Wi-Fi page

5. 选择 Start。需要时使用 Pause、Resume 或 Stop。
6. 在标准 Harness 审批 UI 中回应审批提示。在审批通过一次之前，智能体会在关键操作前停下。

其他示例任务：

Open Android Settings
Open the browser and focus the address bar
Type hello world in the focused text field
Open WeChat, find File Transfer, and prepare to send “test123”

最后一个示例需要审批，之后才会激活语义化的 Send 控件。

配置

bundle 在 cordis.patch.yml 中提供安全默认值。请在配置档的 cordis.patch.yml 中覆盖整个插件行，因为 Harness 补丁行会替换其 config 值，而不是深度合并。

- id: mobile-gui-agent
name: dsh-mobile-gui-agent
config:
adb:
adbPath: adb
unicodeImeApkPath: /absolute/path/to/reviewed/ADBKeyboard.apk
commandTimeoutMs: 10000
processGraceMs: 1000
screenshotMaxBytes: 16777216
hierarchyMaxBytes: 4194304
diagnosticMaxBytes: 65536
hierarchyMaxElements: 400
hierarchyMaxSerializedBytes: 65536
hierarchyAttempts: 3
hierarchyRetryDelayMs: 300
stablePollMs: 300
stableSamples: 3
stableTimeoutMs: 5000
stableDifferenceThreshold: 0.01
agent:
maxSteps: 50
taskTimeoutMs: 600000
actionTimeoutMs: 30000
maxConsecutiveFailures: 5
stablePollMs: 300
stableSamples: 3
stableTimeoutMs: 5000
stableDifferenceThreshold: 0.01
approvalEnabled: true
traceScreenshots: true
maxTraceSteps: 100

commandTimeoutMs 限制单个 ADB 子进程。actionTimeoutMs 限制整个操作，包括稳定等待和操作后的观察。请让 actionTimeoutMs 大于 commandTimeoutMs；较慢的无线设备可能需要 30–60 秒。

unicodeImeApkPath 是可选项，必须是 Harness 主机上的绝对路径。它绝不接受来自模型的输入。已安装的辅助程序会通过 Android 的全部输入法列表检测到并透明使用：插件按需临时启用/选中它，广播文本，然后恢复之前的输入法和启用状态。当辅助程序不存在且配置了 APK 路径时，智能体可以调用 setup_unicode_input；Harness 会在安装前显示强制的一次性审批。配置前请审查 APK 源码和许可证；插件不捆绑也不下载 ADBKeyBoard。

maxTraceSteps 限制实时和终端的 GUI 步骤列表。maxSteps 和 taskTimeoutMs 限制一次运行。截图和层级字节限制防止 ADB 输出无界增长。当所选模型接受图像时，模型可见的截图使用 Harness 附件存储。

架构

dsh.bundle patch
└── dsh-mobile-gui-agent (one Cordis Loader row)
├── AdbPhoneDeviceRegistry provides ctx.phone
├── PhoneAgentService 提供 ctx.phoneRuns │ └── 智能体作用域工具 phone_observe + phone_act └── PhoneAgentRemote Typert Host 命名空间

dsh.client 浏览器贡献 ├── 挂载生成的 phoneAgent Typert Remote 描述符 ├── 注册 mobile_gui_agent 会话视图 └── 注册 blank-session mobile_gui_agent 启动器

现有 Harness Agent 负责规划和回合执行。启动 Phone 运行只会安装智能体作用域的 Phone 工具和专用 Phone 系统提示词。每次 phone_act 都会重新做一次动作前捕获，校验严格动作，解析语义元素边界，必要时请求审批，通过 PhoneDevice 执行，等待屏幕稳定，再次捕获，验证结果，并把新的观察结果返回给同一个 Agent 循环。

紧凑层级会移除不可见和无意义的容器，优先保留文本和可交互节点，分配短 ID，并强制元素数量和序列化字节上限。tap_element 动作还会带上观察 ID。执行前，插件会重新校验所选元素的 resource ID、class、content description 和 bounds；无关动画可以继续，但目标若已移动、缺失、改变或存在歧义，就会作为过期目标被拒绝。

模型体验

启动运行会把专用 Phone 提示词和两个智能体作用域工具加入现有 Harness Agent。phone_observe 返回前台应用、activity、紧凑层级、受支持时的截图附件、最近已验证步骤和失败上下文。phone_act 接受一个严格动作，并且总是返回新的动作后观察结果。模型永远不会收到原始 UIAutomator XML 或任意 ADB shell 访问权限。

提示词前缀在一次运行中保持稳定，而每次紧凑观察结果会随手机屏幕变化。元素数量和序列化字节上限会限制层级增长；截图附件只在所选模型接受图像输入时使用。纯文本模型仍可操作由层级支撑的控件，但如果没有 PhoneVisionProvider，就无法可靠推理纯图像 UI。

安全模型

- 模型无法发出任意 ADB shell 文本。服务商自有的诊断命令使用封闭的 PhoneShellRequest 分类。
- 当 approvalEnabled 为 true 时，有后果的语义控件需要现有 Harness 审批服务。
- Unicode 辅助程序设置始终需要 Harness 审批服务，即使普通动作审批已禁用。
- 审批是一次性的。被拒绝、不可用或取消的审批会变成结构化动作失败。
- 原始坐标动作不一定能暴露其语义效果。操作账号、支付应用或敏感数据时，请检查可见目标，并使用限制严格的 Harness 权限。
- 设备动作是真实的。评估期间请使用测试设备和非生产账号。

按照 SECURITY.md 报告安全问题。

已知限制

- UIAutomator 可能会漏掉 Canvas、游戏、纯图片控件，以及部分 WebView 控件。
- Unicode 文本输入需要兼容的外部 ADB Keyboard 辅助应用。已安装的辅助应用会自动启用并还原；安装缺失的辅助应用需要在 adb.unicodeImeApkPath 指定经过审查的 APK，并明确批准。
- 无线 ADB 的延迟和可靠性取决于网络，以及当前的 Android 调试端口。
- 原始坐标操作不一定能按语义影响分类；请使用语义元素，并留意审批提示。
- MVP 会在观察和操作后刷新截图；它不串流 scrcpy 视频。

开发

pnpm install
pnpm run typecheck
pnpm run build
pnpm run test
pnpm run verify:package
pnpm pack

常规测试套件使用 FakePhoneDevice。真实 ADB 集成测试套件会自动跳过，除非提供设备序列号。用下面的命令运行它的只读截图与层级检查：

DSH_PHONE_ADB_INTEGRATION_DEVICE=emulator-5554 pnpm run test:adb

变更检查需要单独开启：

DSH_PHONE_ADB_INTEGRATION_DEVICE=emulator-5554 DSH_PHONE_ADB_MUTATION_TESTS=1 pnpm run test:adb

变更检查会在选定的设备上按 Home、按 Back、点击、滑动、输入文本。只在对这些操作安全的设备上使用。

故障排查

mobile_gui_agent 入口不见了

确认插件添加到了你启动时用的同一个 Web 配置档，检查 --dump-config，安装后强制刷新浏览器。无头配置档没有浏览器会话视图。在空的新会话主界面上，Harness 会隐藏常规标签栏，但选中工作区后，插件在编辑器工具栏里应该会出现 mobile_gui_agent 按钮；用它直接打开任务面板。

device unauthorized

解锁手机，接受 RSA 提示，然后运行 adb kill-server、adb start-server 和 adb devices -l。如果提示不再出现，在 Android 上撤销 USB 调试授权。

exec-out screencap -p 超时

无线 ADB 可能很慢或已断开。手动运行 adb -s DEVICE exec-out screencap -p > /tmp/phone.png，重新连接端点，保持屏幕解锁，并调高 adb.commandTimeoutMs 和 agent.actionTimeoutMs。插件会把超时报告为可恢复的操作结果，而不是假定点击成功。

层级为空或不完整

UIAutomator 不会暴露每一个 Canvas、WebView、游戏或自定义渲染控件。使用支持视觉的模型，刷新截图，滚动，关闭浮层，或提供 PhoneVisionProvider 插件。

文本输入不正确

ADB 文本输入在聚焦的普通文本字段上最可靠。可打印 ASCII 使用 Android 原生的 input text。Unicode 通过 ADB Keyboard（com.android.adbkeyboard/.AdbIME）发送 UTF-8 Base64 广播。用下面的命令检查当前状态：

adb shell ime list -s
adb shell settings get secure enabled_input_methods
adb shell settings get secure default_input_method

服务商通过 ime list -a -s 检查安装情况，不会把已禁用的输入法误判成包不存在。如果 ADB Keyboard 已安装，input_text 和 replace_text 会按需临时启用并选中它，广播结束后恢复之前的输入法状态，取消清理时也一样。如果辅助程序不存在，就把 adb.unicodeImeApkPath 设为你审查过的 APK 的绝对路径。智能体随后调用 setup_unicode_input，这个调用无法绕过 Harness 审批，只在必要时才安装。如果没有配置路径，setup 返回 PHONE_UNICODE_INPUT_UNSUPPORTED，智能体随即停止，不会重试。replace_text 一步就能更新聚焦字段并完成校验，不用反复按 Delete。

License

MIT

仓库使用 dsh-plugin 话题，方便 DSH 社区目录发现它。