前言¶
在 DeepSeek Harness（dsh）里做手机相关任务时，模型需要能「看见当前界面」并执行点击、输入、返回等操作。常见做法是用 ADB 脚本或单独写一套 RPC，再把能力封装成工具注册进智能体；维护成本高，且和 Harness 的插件模型不一定对齐。
下面介绍社区插件 dsh-plugin-android-tools（维护者 asdukw，SkillHub 分类：工作流）。它把设备侧的 UI 自动化桥接成一组 dsh 工具：读屏、截图、点按、长按、输入、系统键、启动应用、滑动，必要时还可经 Termux 桥执行 shell。插件本身是跨平台的 HTTP 客户端，真正读 UI 树和注入手势由 bridge host 实现；仓库只提供客户端，不包含已发布的 Android host，需自行指向已有 host 或按契约自写。
这是什么¶
dsh-plugin-android-tools 是 DeepSeek Harness 插件：注册原子 UI 工具，每次调用转发到配置了 ANDROID_BRIDGE_URL 的 bridge host。host 可参考 Android AccessibilityService 实现，任何能按同一 HTTP 契约响应的系统均可对接。
- 目录页：https://www.skillhub.cn/plugins/asdukw/dsh-plugin-android-tools
- 源码：https://github.com/asdukw/dsh-plugin-android-tools
- 许可证：MIT（见仓库
package.json） - 运行要求：Node.js >= 20；
dsh需配合@deepseek-ai/dsh-tools>=0.1.0-rc.6（peer dependency）
未配置 bridge 或 token 时，工具调用会明确失败，而不是静默空操作。
核心功能¶
插件向模型暴露的工具如下（能力以 host 实现为准；插件只转发 HTTP）：
| 工具 | 作用 |
|---|---|
read_ui_tree |
导出当前界面节点树，行格式如 [12] TextView "Send" clickable @(900,2200) |
tap_node(ref) |
点击上一次 read_ui_tree 中的节点 ref |
capture_screenshot() |
抓取一帧：图像及尺寸、screenshot_id 等 frame 信息 |
tap_target(screenshot_id,x1,y1,x2,y2) |
在截图像素 bbox 上点击（host 负责坐标换算） |
long_press_target(...) |
对截图目标长按（默认 700 ms，可选 300–2000 ms） |
long_press(ref,...) |
对 UI 树节点长按 |
type_text(text) |
向当前焦点输入框写入文本（不自动发送） |
press(key) |
back / home / recents / enter |
launch_app(query) |
按模糊名称或包名启动应用 |
swipe(direction) |
约半屏滑动：up / down / left / right |
run_command(cmd,timeout_ms?) |
在手机 Linux 环境（Termux + proot Debian）执行 shell，返回 stdout / stderr / 退出码 |
说明：
- UI 类工具（除
run_command外）是可逆、可见的界面操作；run_command改文件系统、无撤销，且每次调用独立会话（cd、环境变量、后台进程不保留），也没有 docker / systemd / iptables 等真实内核能力。 run_command仅在 host 注入TAPPET_TERMUX_URL与TAPPET_TERMUX_TOKEN时注册；未配置 Termux 桥的 host 不会出现该工具。capture_screenshot的图像经ctx.attachments附件服务交给模型；未挂载附件服务时调用仍成功，但图像以文本降级、模型收不到图。bridge 返回的 actionpayload形态为{ mediaType, width, height, base64 }等。
Bridge 侧统一契约：POST {ANDROID_BRIDGE_URL}/action，请求头 x-android-bridge-token: <ANDROID_BRIDGE_TOKEN>，body 含 action 与参数；成功 { "ok": true, "payload": "…" }，失败 { "ok": false, "summary": "…" }。建议 bridge 监听本机并校验 token：屏内容可能含个人数据，且 bridge 可直接驱动设备。
安装与启用¶
安装命令以仓库 README 为准（安装后需重启 dsh；包内 dsh.bundle / cordis.patch.yml 会在安装时写入插件行）：
# from git, pinned to a release tag:
dsh plugin add github:asdukw/dsh-plugin-android-tools#v0.3.0
# or from the tarball attached to any GitHub Release:
dsh plugin add ./dsh-plugin-android-tools-0.3.0.tgz
# once npm publishing is enabled:
dsh plugin add dsh-plugin-android-tools
配置¶
在启动 dsh 的环境中设置（host 启动器通常也会注入）：
| 变量 | 含义 |
|---|---|
ANDROID_BRIDGE_URL |
Bridge 基址，例如 http://127.0.0.1:37812 |
ANDROID_BRIDGE_TOKEN |
每次请求校验的共享 token |
TAPPET_TERMUX_URL |
手机 Linux 桥 URL，例如 http://127.0.0.1:8899（可选） |
TAPPET_TERMUX_TOKEN |
上述桥的 token（与上一项成对出现） |
缺少 ANDROID_BRIDGE_URL 或 ANDROID_BRIDGE_TOKEN 时，各工具调用会报未配置错误。
典型用法¶
推荐循环：先读屏，再操作，再读屏确认。
User: open the clock app and set a 5 minute timer
Agent: launch_app("Clock") → read_ui_tree → tap_node(12) → type_text("5") → …
无真机时可先用仓库自带的 mock host 验证插件与 token 链路：
node examples/mock-host.mjs # mock host on http://127.0.0.1:37812 (token: dev-token)
export ANDROID_BRIDGE_URL=http://127.0.0.1:37812
export ANDROID_BRIDGE_TOKEN=dev-token
mock 会确认各 action 并返回 canned 的 read_ui_tree。
若要自写 host，README 给出 checklist：校验 token、将 action 映射到平台无障碍/自动化 API、read_ui_tree 保持 [ref] 在两次读取间稳定以便 tap_node 等。参考实现见 examples/mock-host.mjs（约 60 行，展示解析/鉴权/回复形状）。
适用场景与注意¶
适合谁
- 已在
dsh中编排智能体，需要把 Android（或其它实现了同一契约的平台）UI 操作收成标准工具的人。 - 愿意维护或部署 bridge host，并接受 loopback + token 的安全模型的人。
- 需要在手机 Termux/proot 环境跑命令、且 host 已配置 Termux 桥的场景（慎用
run_command）。
注意
- 插件以当前运行
dsh的进程权限与环境工作；安装前请阅读源码与 MIT 许可证，确认 bridge URL、token 与日志策略符合你的安全要求。 - 仓库不发布 Android host 成品；只有 HTTP 客户端与 mock。生产环境需自备 host 或第三方实现。
- 插件无 OS 特定代码，换平台只需写 bridge host，不必改插件。
- SkillHub 为社区插件目录，与 DeepSeek / 幻方无官方从属关系；星标与版本以 GitHub 与目录页为准（安装示例中 git tag 为
v0.3.0，仓库package.json当前版本为0.6.0，按你的发布物选择对应安装方式）。
结尾¶
dsh-plugin-android-tools 把「读 UI、点按、输入、系统导航、截图定位、可选 shell」收敛成 Harness 可调用的工具面，通过本地 HTTP bridge 与 host 解耦。要上手：安装插件并配置 bridge 环境变量，host 就绪后按「读—做—再读」让模型组合原子操作即可。
