前言¶
在 DeepSeek Harness（DSH）裏做 Android 開發或自動化，常見做法是截圖來回傳、手動跑 adb，或另起一套 Appium / UIAutomator 腳本。Agent 看得到日誌，卻難在對話裏直接「看見」設備畫面，你也很難在同一會話裏點按、拖拽、讀 logcat。
DSH Android 把這條鏈路收進一個插件：通過 adb 驅動模擬器或 USB 手機，在對話側邊欄呈現即時畫面，並提供 20 個 agent 工具供構建、交互與調試。下面介紹它的定位、能力與安裝用法。
這是什麼¶
DSH Android（npm 包 @zseven-w/dsh-android）是 DeepSeek Harness 的客戶端類插件，由 ZSeven-W 維護。當前插件版本爲 0.1.0-rc.4，已在 DSH 0.1.1-rc.1 上驗證；GitHub 倉庫約 95 stars、6 forks。
一句話定位：在 DSH 對話中構建、運行並與一臺在線的 Android 設備（模擬器或 USB 手機）交互，全程由 adb 驅動，不依賴外部流服務或 loopback 端口代理。
核心功能¶
單一 adb 代碼路徑¶
adb devices -l 報出的 serial 是設備唯一身份——emulator-5554、USB serial、ip:port 目標行爲一致。插件不綁定特定模擬器產品（AVD、Genymotion、WSA 等），也不區分「模擬器棧」與「真機棧」。
進程內直播流與側邊欄面板¶
開流後，插件用常駐 adb exec-out 子進程循環執行 screencap -p，宿主自行切幀，生成 multipart/x-mixed-replace PNG 流，經 DSH webserver 的簽名路由 /_dsh/dsh-android/* 送到界面。瀏覽器不與 adb 直接通信，也沒有可代理的內部流端口。
側邊欄面板渲染即時畫面，支持在視頻上點擊、拖拽，工具欄提供返回、主頁、多任務，以及旋轉、截圖、刷新；設備菜單可觸發通知欄、快捷設置、鎖屏、喚醒、語音助手等動作。
20 個 agent 工具¶
工具在任何宿主上都會註冊，返回純 JSON；可視內容經 presentationMeta 與簽名路由呈現，不作爲 image block 直接塞給模型（支持圖像輸入的模型上，截圖類工具另有原生多模態路徑）。
座標一律是流畫面的歸一化 0..1，幀跟隨顯示旋轉，input tap 與流共用同一座標空間。
核心工具包括：
| 工具 | 作用 |
|---|---|
android_devices |
枚舉 adb 設備與本機 AVD 列表 |
android_boot |
對在線 serial 開流，或先啓動指定 AVD 再開流 |
android_shutdown |
關閉模擬器並停流（實體機 adb 無法關機，會明確拒絕） |
android_screenshot |
抓取 PNG，返回 JSON 摘要 |
android_interact |
點擊、輸入、按鍵、手勢、滾動 |
android_list_apps / android_launch_app |
列舉與啓動已安裝應用 |
android_build_run |
./gradlew assembleDebug、安裝 debug APK 並啓動 |
UI 自動化側提供 android_ui_tree、android_tap_element、android_ui_rows、android_tap_row（基於 uiautomator）。日誌與調試側提供 android_logs、android_processes、android_backtrace、android_meminfo、android_app_info。
OCR 工具 android_find_text、android_tap_text、android_wait_for 依賴 macOS 上的 Apple Vision 框架，僅在 macOS 宿主可用；Linux 與 Windows 上其餘 17 個工具不受影響。
安全模型¶
流與截圖路由要求 loopback 對端、loopback Host（拒絕 DNS 重綁定）、Fetch-Metadata/Origin 同源校驗；HMAC-SHA256 capability 約 10 分鐘內過期。截圖路徑逐級 lstat、拒絕符號鏈接，並用 realpath 做包含性校驗。
安裝與啓用¶
插件以當前 DSH 進程權限運行，安裝前應閱讀 GitHub 源碼 與 MIT 許可證，確認環境中有可信的 adb 與 Android 設備。
環境要求（摘自官方 README）：
- Node ≥ 24.11.0
- adb（Android SDK platform-tools），解析順序：
ADB環境變量 →PATH→ SDK 默認路徑 - 一臺 adb 可見的設備（模擬器或開啓 USB 調試的手機）
- 帶 web bundle 的 DSH ≥ 0.1.0-rc.6 纔有側邊欄面板；headless 配置下 20 個工具仍可用
先安裝插件並啓動 web 會話：
dsh plugin --profile web add @zseven-w/dsh-android@latest
dsh web
也可把包加入既有 profile 的依賴：
pnpm add @zseven-w/dsh-android
非 ASCII 文本輸入（中文、emoji）需可選安裝 ADBKeyboard 並設爲當前輸入法；未安裝時相關輸入會被拒絕並給出提示。
典型用法¶
官方快速上手流程如下。
- 發現設備——讓 agent 調用
android_devices，取得 serial 或 AVD 名。 - 開流——對
emulator-5554等在線 serial 調用android_boot；傳 AVD 名會先冷啓動模擬器（可能需數分鐘），隨後面板顯示即時畫面。 - 交互——在面板上直接點按，或讓 agent 用
android_interact；結構化點擊可走android_ui_tree+android_tap_element；控件樹不可用時在 macOS 上可用 OCR 工具。 - 構建運行——對 Gradle 工程調用
android_build_run，指定projectPath；完整構建耗時數分鐘，成功後應用安裝並啓動。 - 讀日誌——
android_logs可按包名過濾，例如查看某應用最近兩分鐘的 logcat。
示例對話意圖與工具對應關係：
列出 Android 設備。 → android_devices
把 emulator-5554 投出來。 → android_boot
打開設置，然後點顯示。 → android_interact 或 android_ui_tree + android_tap_element
構建並運行 /path/to/MyApp。 → android_build_run
看 com.example.app 最近兩分鐘的 logcat。 → android_logs
適用場景與注意¶
適合誰
- 在 DSH 對話裏做 Android 應用聯調、UI 驗證、logcat 排查的開發者
- 希望 agent 能驅動真實 adb 設備、而非只靠靜態截圖的自動化場景
- 已有 Gradle 工程，需要在會話內一鍵 build / install / launch 的團隊
使用注意
- USB 真機幀率通常約 2–5 fps，模擬器約 5–10 fps；插件 README 在 Android 14 模擬器上實測常駐 screencap 循環約 8 fps。
android_shutdown不能關閉實體手機；adb 無此能力，工具會如實說明。- 設備狀態爲
unauthorized時，需在手機屏幕上確認 USB 調試授權；android_devices會報告狀態而非隱藏設備。 - 模擬器畫面全白/全黑但控件樹正常時，可能是 host-GPU framebuffer 讀回問題；可嘗試
emulator -avd <名稱> -gpu swiftshader_indirect軟渲染重啓。 - 流在消費者歸零約 5 分鐘後會因空閒策略停止，下次工具調用或打開面板時會重啓。
DSH 生態採用「一切皆插件」思路；SkillHub 是社區插件目錄，與 DeepSeek / 幻方無官方從屬關係。
鏈接¶
- 社區目錄：https://www.skillhub.cn/plugins/ZSeven-W/dsh-android
- GitHub 倉庫：https://github.com/ZSeven-W/dsh-android
- npm 包：
@zseven-w/dsh-android
