dsh-android-use

DSH 插件：让 AI 通过 adb 操作安卓手机。提供 10 个工具覆盖设备发现、屏幕感知、输入操作和应用管理，让模型能够自主操控 Android 设备。

安装

# 从本地 checkout 开发安装：
dsh plugin --profile web add link:D:\Projects\deepseek-harness\dsh-plugin-android-use

# 从 npm 安装（发布后）：
dsh plugin --profile web add @huanlin/dsh-plugin-android-use

预构建策略：lib/ 入库，无 prepare 脚本，npm 安装开箱即用，无需 allowBuilds。

前提条件：本机已安装 adb 并在 PATH 上（或通过 adbPath 配置指定路径），已通过 adb connect <ip:port> 或 USB 连接 Android 设备。

配置

在 DSH GUI 设置页或 cordis.patch.yml 中配置：

字段	类型	默认值	说明
adbPath	string	'adb'	adb 可执行路径。默认从 PATH 查找。
defaultSerial	string?	-	默认设备 serial。省略则单设备自动选择；多设备时模型需传 serial 参数。
inputTextMode	'input' | 'adbkeyboard'	'input'	文本输入模式。input 仅支持 ASCII（用 adb shell input text）；adbkeyboard 支持 Unicode（需设备安装 ADBKeyboard IME）。

工具

设备发现

工具	参数	说明
android_list_devices	无	列出所有已连接的安卓设备（serial、state、product、model）。
android_device_info	serial?	获取设备详细信息：型号、品牌、Android 版本、SDK、屏幕分辨率、密度、屏幕状态。

屏幕感知

工具	参数	说明
android_screenshot	serial?	截屏并保存到 attachment store。仅当当前模型路由支持 image 输入时向模型发图；否则仅返回元数据（感知走 android_ui_dump）。
android_ui_dump	serial?	转储 accessibility 树（UI 层级），返回节点列表（文本、bounds、center 坐标、交互标志）。主要屏幕感知方式——DeepSeek 无视觉能力时靠它理解屏幕。

输入操作

工具	参数	说明
android_tap	x, y (必填), duration_ms?, times?	点击屏幕坐标。duration_ms > 0 为长按。
android_swipe	x1, y1, x2, y2 (必填), duration_ms?	从一点滑动到另一点。
android_press_key	key (必填, 命名或整数), times?	按键。命名键：home/back/app_switch/power/enter/volume_up 等，或裸 keycode 整数。
android_input_text	text (必填), submit?	在聚焦输入框中输入文本。submit: true 输入后按回车。

应用管理

工具	参数	说明
android_open_app	package (必填), activity?	打开应用。有 activity 用 am start；无 activity 用 monkey 启动默认 Activity。
android_foreground_app	serial?	获取当前前台应用和 Activity（通过 dumpsys window）。

开发

pnpm install          # 安装开发依赖（schemastery、typescript、vitest、tsdown）
pnpm run typecheck    # tsc --noEmit 类型检查
pnpm test             # vitest run 单元测试（132 用例）
pnpm run build        # tsc + tsdown → lib/（index.js + client.js 双产物）

类型检查需要 junction 到本地 DSH 源码树（私有 peer 依赖不在 npm 上；junction 必须在 pnpm install 之后创建）：

# 在 node_modules/@deepseek-ai/ 下创建 junction（指向本地 DSH 源码 checkout）
$nm = "node_modules/@deepseek-ai"
$src = "C:\Users\Administrator\.dsh\source\current"
@{
  "cordis"                     = "$src\vendor\cordis"
  "dsh-tools"                  = "$src\packages\core\tools"
  "dsh-attachment"             = "$src\packages\attachment\attachment"
  "dsh-llm"                    = "$src\packages\llm\llm"
  "dsh-client-ui-slots"        = "$src\packages\client\ui-slots"
  "dsh-client-ui-tool"         = "$src\packages\client\ui-tool"
  "dsh-client-ui-session"      = "$src\packages\client\ui-session"
  "dsh-client-ui-conversation" = "$src\packages\client\ui-conversation"
  "dsh-client-ui-renderer"     = "$src\packages\client\ui-renderer"
}.GetEnumerator() | ForEach-Object {
  New-Item -ItemType Junction -Path (Join-Path $nm $_.Key) -Target $_.Value | Out-Null
}

检查

合规自检（参见 plugin-development-guide.md §10）：

• 零源码 patch：未修改 DSH checkout 任何文件
• B1: package.json 声明 dsh.bundle.patch
• B2: 插件自带 cordis.patch.yml（insert 行 id/name/config 齐全）
• B3: patch 行 name 用包名（Loader 从 profile node_modules 解析）
• F1: files 含 lib/ + cordis.patch.yml
• F2: peerDependencies 含 @deepseek-ai/cordis + 用到的 @deepseek-ai/*（不用 devDependencies 冒充）
• F3: typecheck/test/build script 齐全
• A6: 不导出 default
• C4: 工具返回规范 JSON 值 + render 投影分离
• C5: adb 缺失/设备离线等基础设施失败 throw；取消不 throw
• C6: 尊重 exec.signal 取消在途 adb 子进程
• G: Unit 测试（tests/*.spec.ts，132 用例，含真实 launcher dump fixture）

目录结构

dsh-plugin-android-use/
├── src/
│   ├── index.ts           # 入口：name、inject、Config（Schemastery）、apply
│   ├── adb.ts             # AdbClient: spawn 封装 + serial 解析 + 设备列表解析
│   ├── xml.ts             # uiautomator XML 解析（零依赖）
│   ├── keys.ts            # 命名按键表（home/back/app_switch/... → keycode）
│   ├── registry.ts        # registerTools(ctx, deps) — 依赖注入入口
│   ├── client/            # 浏览器半：tool.call.toolview 卡片（tap / screenshot）
│   │   ├── index.ts       # client 插件：slots.inject 注册两张卡片
│   │   ├── TapCard.tsx    # android_tap 卡片（前后截图对照）
│   │   └── ScreenshotCard.tsx  # android_screenshot 卡片
│   └── tools/
│       ├── device.ts      # list_devices / device_info
│       ├── screen.ts      # screenshot / ui_dump
│       ├── input.ts       # tap / swipe / press_key / input_text
│       └── apps.ts        # open_app / foreground_app
├── tests/
│   ├── adb.spec.ts        # 设备列表解析、serial 解析序
│   ├── xml.spec.ts        # XML 解析（真实 launcher dump fixture）
│   ├── keys.spec.ts       # 命名按键 → keycode 映射
│   ├── input.spec.ts      # 文本转义、非 ASCII 报错、adbkeyboard 编码
│   ├── tools.spec.ts      # fake AdbClient + 全工具 schema/execute/render 验证
│   └── fixtures/
│       └── launcher_dump.xml  # 真实 PJF110 设备 launcher dump
├── cordis.patch.yml       # bundle 层：插入 dsh-android-use 插件行
├── package.json           # dsh.bundle.patch 声明 + peerDeps
├── tsconfig.json          # NodeNext、ES2022、strict
├── tsdown.config.ts       # 双 entry：index.js（node）+ client.js（DSSH 模块加载器包裹）
└── vitest.config.ts       # vitest forks pool