dsh-phone-butler：通過 ADB 讓智能體管理真實 Android 設備

前言¶

DeepSeek Harness（DSH）的插件化設計讓「把手機交給 agent」成爲可能。dsh-phone-butler 是其中一類客戶端插件：它不依賴虛擬化或 root，而是利用 ADB 把一臺真實 Android 設備變成 agent 可直接查看和打理的設備。它解決的是「手機空間滿了」這類問題——文件管理器說能清，系統設置說騰不出，而真正的元兇往往藏在一個看不見的目錄裏。

插件定位¶

這是一個 DeepSeek Harness 插件，由 Void-LifeStream 維護。它的核心價值是：在無需 root 的情況下，讓智能體通過 ADB 對 Android 手機進行只讀分析（存儲佔用、應用數據大小、緩存情況）和可控清理（清緩存、刪除文件、卸載應用、截圖）。它把「能清理」的 /sdcard 層和「碰不到」的 /data/data 層區分開，同時讓後者至少可以被度量。

核心功能¶

插件提供了若干能力，全部通過 ADB 調用實現：

phone_status：返回設備是否可達及其狀態信息
phone_scan：只讀掃描，包括：清理概覽、每個應用的數據大小、緩存、使用情況和大文件
phone_fs：對 /sdcard 執行 ls 和 du，列出文件和目錄大小
phone_act：寫操作，包括清緩存、刪除文件、卸載應用；每次寫操作必須顯式 confirm: true，否則只返回計劃不執行
phone_shot：截取屏幕並保存到本地文件

插件還內置一個技能 phone-butler，包含能力映射、連接方式和五個容易導致錯誤結論的陷阱說明。

安裝與啓用¶

在 DSH 中，通過官方 bundle 安裝姿勢指向本目錄（或其克隆）：

plugin_manager action: install_bundle target: <本目錄絕對路徑>

安裝後，插件會在 profile 的 cordis.patch.yml 中注入配置項。可選配置包括：

- id: dsh-phone-butler
  config:
    adbPath: 'C:\platform-tools\adb.exe'
    timeoutMs: 240000

adbPath 指向 ADB 可執行文件；如果 ADB 已在系統 PATH 中，則無需配置。插件需要 Android 設備開啓 USB 調試。

典型用法¶

以下步驟展示從連接到使用的基本流程：

確保手機開啓 USB 調試（無線調試或 adb tcpip 5555 後使用）。
在同一 Wi-Fi 下執行一次 adb tcpip 5555，之後手機持續監聽 5555 端口，可通過 adb connect <手機地址>:5555 遠程連接。
在 DSH 中調用 phone_status 檢查設備是否可達：

   phone_status

使用 phone_scan 查看存儲佔用情況：

   phone_scan kind=apps

這會解析 dumpsys diskstats，列出每個 App 的私有數據大小（包含 /data/data 與外部 Android/data）。
5. 如需清理某個應用的緩存（保留數據）：

   phone_act op=clear-cache pkg=<包名>

需要刪除 /sdcard 下的文件時，必須先確認：

   phone_act op=rm path=/sdcard/某路徑 confirm=true

截圖並保存到本地：

   phone_shot target=本地文件路徑

能力邊界¶

插件的能力在不同層級上有所不同：

/sdcard/**：可讀寫，包含每個 App 的 Android/data 和 Android/obb。
/data/data/<pkg>：未 root 時無法觸達（Permission denied）；run-as 對非 debuggable 包也無效。
每個 App 的數據大小：可獲取，通過 dumpsys diskstats。
只清緩存：可以，使用 pm clear --cache-only <pkg>，應用數據保留。
清空 App 數據：技術上可行，但會毀壞用戶數據，插件故意不暴露此能力。

安全立場¶

插件在設計上遵循兩條原則：

讀操作永遠不改動任何東西。
寫操作必須顯式 confirm: true；否則工具只返回計劃，不執行任何實際操作。
rm 只接受 /sdcard 下的路徑，其它路徑一律拒絕。
掃描默認不列文件名，避免泄露隱私；需要文件名時使用 names: true。
Android 沒有回收站，rm 即爲最終結果。

五個容易踩空的地方¶

find /sdcard 默認不跟隨符號鏈接，會返回空列表；必須使用 find -H /sdcard。
在 PowerShell 中傳遞帶雙引號的命令時，引號會被喫掉；建議用 argv 數組傳參。
推送到手機上的腳本必須是 LF 換行，CRLF 會導致 id\r: inaccessible or not found。
截圖出現全黑時，可能是鎖屏而非失敗；可通過文件大小或 dumpsys power 判斷。
不要從截圖裏讀路徑，OCR 容易混淆 l/1、I/1；應通過 pm path <包名> 獲取。

它不是什麼¶

有人會問：爲什麼不做成「手機的感知器官」？比如調相機、讀傳感器、失聯自動求援、代做需要本人承諾的事。經過評估，結論是不做。理由包括：

ADB 沒有 CAMERA 權限，截取的是屏幕而非相機畫面，且無法驗證是否爲相機畫面。
Android 12+ 對 shell 主動遮蔽傳感器數值，只能獲取清單與時間戳。
ADB 是「桌面端主動連手機」，唯一需要它的時刻往往不在線。
操作結束後用戶必須能說「這是我做的、我理解的」，否則不做。

注意事項¶

插件以當前 DSH 進程的權限運行，安裝前應檢查源碼與許可證（MIT）。
同一臺電腦上的多個 agent 共用同一個 ADB server；adb kill-server 會斷開所有人，只斷開某條連接應使用 adb disconnect <地址>。
手機重啓後 adb tcpip 5555 生效的連接會失效，需重新在 Wi-Fi 下執行一次。

小結¶

dsh-phone-butler 讓智能體在無需 root 的情況下，通過 ADB 對真實 Android 設備進行存儲分析、緩存清理、應用管理和截圖。它把可清理層與不可清理層區分開，同時讓後者至少可以被度量，避免了「手機空間滿了」這類問題的模糊性。完整文檔與實現見：

插件目錄：https://www.skillhub.cn/plugins/Void-LifeStream/dsh-phone-butler
GitHub：https://github.com/Void-LifeStream/dsh-phone-butler