前言¶
在 DSH 中做智能體任務時，控制 Android 設備往往會遇到幾類具體問題：設備是否已完成調試授權、當前屏幕上有哪些可操作元素、模型發出的動作是否真的生效、哪些動作必須經過人工批准。
dsh-mobile-gui-agent 是一個 DeepSeek Harness 插件。它通過 ADB 控制 Android 設備，把截圖、UIAutomator 層級、動作驗證、審批和 Web 移動端視圖放進同一個插件裏，讓 DSH 可以按“觀察—決策—動作—驗證”的循環處理手機任務。
這是什麼¶
kunjinkao-os/dsh-mobile-gui-agent 是一個用於 DeepSeek Harness 的 Android Mobile GUI Agent 插件。它提供 ADB 控制、驗證過的迭代動作、審批和 Web 移動端視圖。
項目由 kunjinkao-os 維護，採用 MIT 許可證。當前可安裝版本爲 v0.2.1。
核心能力¶
下面介紹插件已覈實的幾類能力。
- ADB 控制：設備發現、無線連接、截圖、UIAutomator 層級抓取、點擊、長按、滑動、文本輸入/替換、按鍵、返回、Home、啓動包。
- 觀察輸入：截圖，以及經過剪枝的語義 UI 觀察；元素 ID 是當前 observation 內局部有效的。
- Harness 工具：提供嚴格的
phone_observe和phone_act工具。 - 動作循環：每個模型回合執行一個有意義動作，隨後取得新觀察，並進行確定性驗證。
- 穩定性保護：stale-element protection、adaptive screen stabilization、stuck detection、step and time limits、recoverable ADB errors。
- 審批：對可能發送、發佈、刪除、購買、支付、轉賬、撥號、安裝、修改賬戶安全等語義控制，觸發 Harness approval。
- Web 視圖：提供 blank-session
mobile_gui_agentlauncher 和 conversation tab，支持設備選擇、無線連接、截圖刷新、任務控制、動作 overlays 和 verified steps。 - 測試能力：提供 fake device 和 scripted state transitions，用於 keyless Agent-loop tests。
環境要求¶
使用這個插件前，需要先確認環境滿足以下條件。
- 需要 DeepSeek Harness Web profile。
mobile_gui_agententry 是 browser client contribution，因此 headless-only profile 不會顯示它。 - 需要一個 Android 物理設備或 emulator，並且能被
adb devices看到。 - Android 設備需要開啓 Developer options 和 USB debugging，並完成 RSA debugging authorization。
- Node.js 要求爲
^22.19.0 || >=24.0.0。 - DeepSeek Harness 兼容性爲
^0.1.0-rc.5；已對照 upstream commit47f943859bef60e4160492346772ded9b24f765a驗證，並在發佈的0.1.0-rc.6Harness packages 上構建和測試過。
安裝與啓用¶
先確認 Android 設備可用。下面命令用於查看設備列表：
adb devices -l
設備需要已經完成授權，後續插件才能通過 ADB 正常工作。
接着，把固定版本安裝到 Harness Web profile：
dsh plugin --profile web add github:kunjinkao-os/dsh-mobile-gui-agent#v0.2.1
這個插件可以控制真實設備，因此安裝時建議固定已審查的 tag 或 commit。
安裝後，檢查配置並啓動 Web profile：
dsh --profile web --dump-config
dsh --profile web
經過上面的步驟，就可以在 Web 端使用 mobile_gui_agent 入口。
典型用法¶
推薦使用下面的流程，把普通 Harness 會話消息和手機任務分開。
- 選擇一個 workspace，並在普通 Harness conversation 中發送一個簡短初始化消息，例如：
Prepare a mobile task
-
選擇
mobile_gui_agentconversation tab。 -
選擇已連接的設備，並把實際手機命令只填入
mobile_gui_agent裏的 Task 字段。 -
選擇 Start，然後跟隨 verified steps 查看執行結果。
也可以使用 blank-session mobile_gui_agent launcher 打開任務面板。上面的流程更適合在普通 Harness 會話和手機任務之間保持明確邊界。
輸入與權限邊界¶
Unicode 輸入會使用外部 ADB Keyboard helper：
com.android.adbkeyboard/.AdbIME
如果該 helper 不存在，可以通過 adb.unicodeImeApkPath 配置一個指向已審查 APK 的 absolute host path。插件本身不會下載 APK；如果涉及 APK 安裝，仍然需要 explicit Harness approval。
這個插件不會安裝 Android accessibility service。
對於 Custom Canvas、WebView、game 和 image-only 控件，它們可能出現在截圖中，但不會出現在 UIAutomator hierarchy 裏。對這類屏幕，可以使用 vision-capable model input 或 optional PhoneVisionProvider。
適用場景與注意¶
這個插件適合想給 DSH 增加 Android 設備控制能力的開發者或使用者，尤其是在 Web 裏查看設備狀態、執行手機任務，並對敏感操作做審批的場景。
使用前需要注意：
- 它會通過當前 Harness /
dsh進程調用 ADB 等本地能力，並對 Android 設備執行操作。 - 安裝前應檢查源碼、許可證和版本固定情況。
- 需要 DeepSeek Harness Web profile；headless-only profile 不會顯示
mobile_gui_agententry。 - 發送、發佈、刪除、購買、支付、轉賬、撥號、安裝、修改賬戶安全等動作需要 Harness approval。
- 控制真實設備時，應安裝固定 tag 或 commit，而不是隨意使用未審查版本。
結尾¶
dsh-mobile-gui-agent 的價值，是把 Android GUI 控制放進 DSH 插件體系：ADB 動作、屏幕觀察、動作驗證、審批和 Web 視圖都在同一流程裏。
項目地址：
https://github.com/kunjinkao-os/dsh-mobile-gui-agent
