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