前言¶
在 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 就緒後按「讀—做—再讀」讓模型組合原子操作即可。
