kunjinkao-os/dsh-mobile-gui-agent

English | 中文

dsh-mobile-gui-agent 是一个可安装的 DeepSeek Harness Android 移动端 GUI Agent 插件。它通过 ADB 控制真机或模拟器，在 Harness Web UI 中增加 Mobile 标签页，并让每个任务严格执行“观察 → 决策 → 动作 → 验证”的循环。

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

快速开始

连接并授权 Android 设备，然后把固定版本安装到 Harness Web profile：

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

设备行必须显示 device。配置输出中必须出现 # == dsh-mobile-gui-agent 层和一个 dsh-mobile-gui-agent 插件行。打开 Web UI 中的非空会话，选择 移动端。操作包含账号或个人数据的设备前，请先阅读前置条件和使用。

兼容性

• DeepSeek Harness：^0.1.0-rc.5
• 已对上游提交 47f943859bef60e4160492346772ded9b24f765a 验证
• 同时使用 npm 已发布的 0.1.0-rc.6 Harness 包完成构建和测试
• Node.js：^22.19.0 || >=24.0.0
• Android：能被 adb devices 发现的真机或模拟器

插件遵循上游的 dsh.bundle.patch 与 dsh.client manifest，不修改 Harness Agent loop，也不依赖未发布的 Phone 包。

能力

• ADB 设备发现、无线连接、截图、UIAutomator hierarchy、点击、长按、滑动、文本输入、按键、返回、主页和启动应用
• 截图与裁剪压缩后的语义 UI 共同构成观察，每轮元素使用短 ID
• 严格的 phone_observe 与 phone_act Harness 工具
• 每个模型回合只执行一个有意义动作，随后重新观察并确定性验证
• 过期元素保护、自适应稳定等待、卡住检测、步骤与时间限制、可恢复 ADB 错误
• 对发送、发布、删除、购买、支付、转账、拨号、安装和账号安全修改等语义控件复用 Harness 审批
• Web Mobile 标签页：设备选择、无线连接、截图刷新、开始/暂停/继续/停止、动作覆盖框和验证步骤
• 用于无密钥 CI 的 FakePhoneDevice 与脚本化页面状态

本插件不安装 Android 无障碍服务。它组合 ADB 截图与 Android UIAutomator hierarchy。Canvas、WebView、游戏和纯图片控件可能能在截图中看到，却不存在于 hierarchy；此时 Agent 可使用支持视觉输入的模型，或由其他插件提供可选的 PhoneVisionProvider。

前置条件

1. 安装 Android Platform Tools，确认 adb version 可执行。

2. 在 Android 中开启开发者选项和 USB 调试。

3. 手机弹出 RSA 调试授权时允许此电脑。

4. 执行：

   adb devices -l
   

   目标行必须是 device，不能是 offline 或 unauthorized。

5. 使用 DeepSeek Harness Web profile。Phone 是浏览器客户端贡献，纯 headless profile 不会显示该标签页。

不需要 root，也不需要向手机安装 APK。

安装方式

把本地 checkout 安装到标准 Web profile：

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

如果从 Harness 源码仓库运行，请把 dsh 替换为 pnpm dsh：

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

配置输出中应出现 # == dsh-mobile-gui-agent 层和一个名为 dsh-mobile-gui-agent 的插件行。打开 Web UI，进入一个非空会话，再选择 移动端 会话视图。Harness 在新会话仍显示空白 Hero 时会隐藏会话视图标签，因此从新会话测试时应先发送一条普通提示词。

仓库提交了预构建 lib/，因此固定 Git 提交安装时无需允许依赖构建脚本：

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

如需不可变的审查目标，可把发布标签替换为对应提交 SHA。也可以直接安装 Release tarball，不需要 Git 构建步骤：

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

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

无线 ADB

如果 Android 版本要求配对，先使用 Platform Tools 完成配对。可以在启动 Harness 前连接：

adb connect DEVICE_IP:PORT
adb devices -l

也可以在 Mobile 标签页输入 DEVICE_IP:PORT 后点击 Connect。电脑和 Android 设备必须网络互通；Android 重启无线调试后端口可能变化。

使用

1. 打开一个非空 Harness 会话；新会话应先发送一条普通提示词，让 Harness 显示会话视图标签。

2. 选择 移动端 视图。

3. 选择已连接设备并刷新截图。

4. 输入任务，例如：

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

5. 点击 Start；需要时使用 Pause、Resume 或 Stop。

6. 在 Harness 原生审批 UI 中处理确认。需要审批的动作在获得一次性许可前不会执行。

更多任务示例：

打开 Android 设置
打开浏览器并点击地址栏
在当前文本框输入 hello world
打开微信，找到文件传输助手，准备发送“测试123”

最后一个示例在点击语义明确的“发送”控件前会请求审批。

配置

cordis.patch.yml 提供默认值。Harness patch 会整体替换插件行的 config，不会深度合并；因此在 profile 的 cordis.patch.yml 覆盖时应写出完整配置。完整示例见英文 README 的配置章节。

关键配置：

• adb.commandTimeoutMs：单个 ADB 子进程的超时。
• agent.actionTimeoutMs：动作、页面稳定等待和动作后观察的总超时，应大于 ADB 命令超时；较慢的无线设备可设为 30–60 秒。
• agent.maxSteps、agent.taskTimeoutMs：限制完整任务。
• agent.maxConsecutiveFailures：连续验证失败上限。
• agent.traceScreenshots：视觉模型可用时，把截图存入 Harness attachment store。
• agent.maxTraceSteps：GUI 当前及终态步骤的保留上限。

截图、hierarchy 和诊断输出都有字节上限，避免 ADB 输出或执行轨迹无限增长。

架构

dsh.bundle patch
└── dsh-mobile-gui-agent（一个 Cordis Loader 行）
    ├── AdbPhoneDeviceRegistry       提供 ctx.phone
    ├── PhoneAgentService            提供 ctx.phoneRuns
    │   └── Agent 范围工具           phone_observe + phone_act
    └── PhoneAgentRemote             Typert Host namespace

dsh.client 浏览器贡献
├── 挂载生成的 phoneAgent Typert Remote 描述
└── 注册 Phone 会话视图

规划与回合执行仍由 Harness 现有 Agent 负责。启动 Phone run 后，插件只在该 Agent 范围安装 Phone 工具和专用 system prompt。每次 phone_act 会重新获取动作前状态、验证严格 action、解析元素边界、按需审批、通过 PhoneDevice 执行、等待画面稳定、再次获取状态、验证结果，再把新观察交回同一 Agent loop。

压缩 hierarchy 会过滤不可见和无意义容器，优先保留文本与交互节点，为元素分配短 ID，并限制元素数和序列化字节数。tap_element 同时携带 observation ID；屏幕改变后，旧的语义坐标会被拒绝。

模型体验

启动 run 后，插件会向 Harness 现有 Agent 增加专用 Phone prompt 和两个 Agent 范围工具。phone_observe 返回前台应用、Activity、压缩 hierarchy、模型支持时的截图附件、最近验证步骤和失败上下文。phone_act 只接受一个严格 action，并始终返回新的动作后观察。模型不会看到原始 UIAutomator XML，也不能执行任意 ADB shell。

一次 run 内的 prompt 前缀保持稳定，每轮压缩观察随手机画面变化。元素数和序列化字节上限约束 hierarchy 体积；只有选定模型接受图片输入时才使用截图附件。纯文本模型仍可操作 hierarchy 中的控件，但没有 PhoneVisionProvider 时无法可靠理解纯图片 UI。

安全模型

• 模型不能提交任意 ADB shell 文本；底层诊断命令使用封闭的 PhoneShellRequest 分类。
• approvalEnabled 开启时，具有真实副作用的语义控件复用 Harness 审批服务。
• 审批只允许一次；拒绝、缺少审批 Provider 或取消会成为结构化动作失败。
• 原始坐标动作不一定能识别语义副作用。涉及账号、支付或敏感数据时，应人工核对目标并配置严格的 Harness 权限。
• 所有设备动作都是真实动作。评估时使用测试设备和非生产账号。

安全问题请查看 SECURITY.md。

已知限制

• UIAutomator 可能遗漏 Canvas、游戏、纯图片和部分 WebView 控件。
• ADB 非 ASCII 文本输入行为取决于 Android 构建和当前输入法。
• 无线 ADB 的延迟与可靠性取决于网络和当前 Android 调试端口。
• 原始坐标动作不一定能按语义判断影响；应优先使用语义元素并核对审批提示。
• MVP 在观察和动作后刷新截图，不提供 scrcpy 视频流。

开发与测试

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

普通测试使用 FakePhoneDevice。真实 ADB 集成测试会在未提供设备序列号时自动跳过。只读截图与 hierarchy 检查：

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、tap、swipe 和输入文字，只能对允许这些动作的测试设备运行。

故障排查

看不到 Mobile 标签页

确认插件安装到了当前启动的 Web profile，检查 --dump-config，安装后强制刷新浏览器。headless profile 没有浏览器会话视图。新会话空白 Hero 中看不到标签时，先发送一条普通提示词；上游 Harness 只在会话变为非空后显示会话视图标签。

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。插件会把超时作为可恢复动作结果返回，不会假定点击成功。

hierarchy 为空或不完整

UIAutomator 不会暴露所有 Canvas、WebView、游戏或自定义渲染控件。使用支持视觉输入的模型，刷新截图，尝试滚动或关闭遮罩，也可以提供 PhoneVisionProvider 插件。

文本输入不正确

ADB 文本输入对已聚焦的普通文本框最可靠。非 ASCII 输入取决于设备键盘和 Android 构建。先聚焦文本框，并在继续前验证输入结果。

许可证

MIT

仓库使用 dsh-plugin topic，供 DSH 社区目录发现。