前言¶

DSH 的擴展方式是把外部能力做成插件。對需要本地調試 Android 應用的開發者來說，常見痛點是如何把 ADB 能力安全地暴露給模型：既要覆蓋設備發現、應用管理、系統服務、UI 層級、輸入、文件傳輸和日誌，又要避免模型在宿主機 shell 中自由拼接命令，同時需要對設備、超時和輸出大小做限制。

adb-dsh-plugin 把本機已有的 Android Debug Bridge（ADB）註冊爲 DSH 工具。它不啓動額外的代理服務，也不在宿主機 shell 中拼接命令；所有 ADB 進程都通過 Harness 的 ctx.subprocess 服務啓動，並繼承工具調用的取消和超時信號。

這是什麼¶

adb-dsh-plugin 是一個 MIT 許可證的 DSH 插件，用於通過 ADB 控制 Android 設備。package.json 中的插件名是 adb-dsh-plugin，版本爲 0.1.0。倉庫地址爲：

https://github.com/mang0cola/adb_dsh_plugin

它面向本地已有 adb 的 DSH 使用場景，把設備信息、應用包、系統服務、UI 層級、輸入、文件傳輸和日誌等能力註冊爲模型可調用的工具。

核心能力¶

下面列出已覈實的工具能力：

adb_packages、adb_system_services、adb_service_dump 和 adb_app_info 都是隻讀工具，不依賴 enableShell 或 enableAppManagement。adb_app_info 默認返回適合模型直接使用的結構化字段；確實需要 Package Manager 的其他細節時，可傳 includeRawDump: true，原始輸出仍受 maxOutputBytes 限制，並通過 truncated 標記截斷。

環境要求¶

已覈實資料要求：

• Node.js ^22.19.0 || >=24
• pnpm
• PATH 中可用的 adb

README 中提到，要求與當前 DeepSeek Harness 0.1.0-rc.5 相同。

安裝與啓用¶

本地開發、測試與構建¶

在插件目錄安裝依賴、運行測試並構建：

cd ~/Desktop/side_projects/adb_dsh_plugin
pnpm install
pnpm test
pnpm build

如果已連接並授權一臺測試設備，可以運行本地真機功能測試：

pnpm test:device

該測試會覆蓋設備發現、設備信息、UI 層級、截圖、無副作用按鍵碼、結構化應用信息、權限與四大組件、系統服務、日誌，以及一次位於 /data/local/tmp/adb_dsh_plugin_function_test.txt 的文件 push/pull 往返；測試結束會自動清理宿主機和設備上的臨時文件。請只在允許測試的設備上運行。

源碼 overlay¶

複製開發配置模板：

cd ~/Desktop/side_projects/adb_dsh_plugin
cp cordis.dev.example.yml cordis.dev.yml

修改 cordis.dev.yml 中的絕對路徑後，停止已有的 pnpm dsh web，再從 Harness 倉庫啓動：

cd ~/Desktop/playground/deepseek-harness
pnpm dsh web --patch ~/Desktop/side_projects/adb_dsh_plugin/cordis.dev.yml

cordis.dev.yml 是包含本機路徑和個人權限策略的本地文件，不納入 Git。如果移動了插件目錄，需要同步修改其中的絕對路徑。

安裝爲 web profile bundle¶

構建插件後，可以把本地 checkout 安裝到 web profile：

cd ~/Desktop/playground/deepseek-harness
pnpm dsh plugin --profile web add ~/Desktop/side_projects/adb_dsh_plugin
pnpm dsh web

package.json 中的 dsh.bundle 會讓 cordis.patch.yml 自動加入 profile 的 bundle 層。

更新插件代碼後，需要重新構建：

pnpm build

然後重啓 dsh。bundle 列表變化也需要重啓。

卸載¶

cd ~/Desktop/playground/deepseek-harness
pnpm dsh plugin --profile web remove adb-dsh-plugin

典型用法¶

連接並授權設備後，可在 Web UI 中依次嘗試以下提示詞。

調用 adb_devices 列出設備，然後讀取唯一在線設備的系統、屏幕和電池信息。

這條提示會先列出設備，再讀取設備信息。

調用 adb_packages 列出第三方應用，返回包名、版本碼、安裝來源和 APK 路徑，不修改設備。

調用 adb_app_info 查看 com.example.app：彙總申請的權限及其授權狀態，並分別列出 activity、service、broadcast receiver 和 content provider。

先用 adb_system_services 查找 package 服務，再用 adb_service_dump 查看它的當前狀態，只做讀取。

使用 adb_ui_hierarchy 查看當前界面，找到文本爲“設置”的可點擊節點並告訴我它的 bounds，先不要點擊。

圖片模型還可以使用：

調用 adb_screenshot 查看當前設備屏幕並描述界面，不要執行任何點擊。

截圖只在模型聲明支持圖片輸入且 Harness 已掛載附件服務時執行；否則工具會提示改用 adb_ui_hierarchy。

配置與安全¶

在 overlay 的插件行添加 config，可以覆蓋默認值：

- insert:
    - id: adb-tools
      name: '/absolute/path/to/adb_dsh_plugin/src/index.ts'
      config:
        adbPath: adb
        defaultSerial: emulator-5554
        allowedSerials:
          - emulator-5554
        commandTimeoutMs: 30000
        transferTimeoutMs: 180000
        maxOutputBytes: 1048576
        maxScreenshotBytes: 16777216
        processGraceMs: 1000
        enableShell: false
        enableDeviceControl: true
        enableFileTransfer: true
        enableAppManagement: true
        enableDestructiveActions: false
        enableScreenshots: true
        enableUiHierarchy: true
        restrictHostPathsToWorkspace: true

上面配置用於在 overlay 插件行中設置 ADB 路徑、設備白名單、超時、輸出上限和工具開關。

關鍵限制如下：

• 未傳 serial 時，插件依次使用 defaultSerial 或唯一在線且允許的設備；連接多個在線設備時，模型必須明確傳入 serial。
• allowedSerials: [] 表示允許所有 ADB 可見設備；生產環境建議設置 allowedSerials，並只啓用確實需要的工具。
• adb_shell 默認不註冊，需要顯式啓用；任意 shell 和清理/卸載應用默認關閉。
• adb_app 的 clear_data 和 uninstall 只有在 enableDestructiveActions: true 時才執行。
• restrictHostPathsToWorkspace: true 會解析真實路徑，並拒絕通過絕對路徑、.. 或符號鏈接訪問會話工作區外的宿主機文件。
• 輸出超限時只保留有界結果，並明確標記截斷。
• UI 層級優先使用無障礙樹；當設備的 uiautomator 返回空樹時，會回退到 Android WindowManager 的可見原生 View 層級。該回退路徑無法保證包含 Jetpack Compose/WebView 內部的完整語義，必要時應結合截圖判斷。

適用場景與注意¶

adb-dsh-plugin 適合本地 DSH 調試、Android 設備狀態檢查、應用與組件查詢、UI 層級檢查、日誌抓取、文件 push/pull，以及受控環境下的點擊、滑動、安全 ASCII 文本輸入和 keyevent。

需要注意：

• ADB 授權本身給予主機對設備的高權限控制。
• Harness 的宿主機文件沙箱不會限制設備側的點擊、應用管理或 adb shell 副作用。
• 插件通過 Harness 的 ctx.subprocess 服務啓動 ADB 進程，並繼承工具調用的取消和超時信號；它會以當前 DSH 進程可用的本地權限運行這些子進程。
• 安裝前建議檢查源碼、依賴和 MIT 許可證。
• 已覈實資料未給出星標數或目錄頁 URL；本文給出的安裝方式是本機本地 checkout 添加到 web profile。
• GitHub 倉庫：

https://github.com/mang0cola/adb_dsh_plugin