前言¶

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