dsh-vision-android

Readme

# dsh-vision-android

DeepSeek Harness 插件：**多模态视觉 + Android UI 自动化**。

解决两个问题：
1. **主模型没有多模态输入**：把任意截图/图片发给 OpenAI 兼容的视觉模型提问（默认 `gpt-5.6-luna`，可配任意 OpenAI 兼容端点）。
2. **agent 测试手机软件**：通过 adb 在模拟器/真机上做**真实点击、滑动、输入、按键**，形成"截图 → 视觉理解 → 真实点击 → 再截图验证"的闭环。

## 工具清单（注册到 `ctx.tools`，模型可见）

| 工具 | 作用 |
|---|---|
| `vision_ask` | 把本地图片文件发给视觉模型提问（通用多模态） |
| `mobile_look` | 截屏 + 视觉理解：返回屏幕描述 + 可交互元素 `[{label, role, x, y}]`（像素中心坐标） |
| `mobile_dump` | uiautomator 抓取 UI 层级：精确坐标兜底（不花视觉 token） |
| `mobile_screenshot` | 只截屏存 PNG，返回路径 |
| `mobile_tap` | **真实点击** `(x, y)` |
| `mobile_swipe` | 真实滑动手势 |
| `mobile_text` | 输入文本（adb 限制：仅 ASCII，空格自动转义） |
| `mobile_keyevent` | 按键：back/home/enter/tab/esc/dpad_* 等 |
| `mobile_install` | `adb install -r` 安装 APK（保留数据） |
| `mobile_launch` | `am start` 启动组件 / monkey 启动包 |
| `mobile_screen_size` | 屏幕物理分辨率（校验视觉坐标用） |

## 配置

插件 Config（Schemastery 校验，环境变量兜底）：

| 字段 | 默认 | 说明 |
|---|---|---|
| `visionBaseUrl` | `https://api.openai.com/v1` | OpenAI 兼容地址（env `DSH_VISION_BASE_URL`） |
| `visionApiKey` | 空 | API Key（env `DSH_VISION_API_KEY`；**推荐用环境变量，不要写进配置**） |
| `visionModel` | `gpt-5.6-luna` | 视觉模型 ID（env `DSH_VISION_MODEL`） |
| `visionDetail` | `high` | 图片 detail 档位 |
| `visionMaxTokens` / `visionTimeoutMs` | 2000 / 120000 | 生成上限与超时 |
| `adbPath` | `adb` | adb 路径（env `ADB` 兜底，可写绝对路径） |
| `adbTimeoutMs` | 30000 | 单条 adb 命令超时 |
| `screenshotDir` | `.dsh-mobile-shots` | 截图落盘目录 |

## 安装

### A. overlay（开发/本机快速生效）

复制 `cordis.example.yml` 为 `cordis.yml`（已被 gitignore），把插件路径改成你的绝对路径，然后：

```sh
dsh web --patch /path/to/dsh-vision-android/cordis.yml
```

### B. 安装进 profile（bundle 形态，推荐）

```sh
dsh plugin --profile web add ./dsh-vision-android     # 本地目录（link）
# 或从 GitHub 安装：dsh plugin --profile web add github:you/dsh-vision-android
dsh --profile web --dump-config   # 应看到 # == dsh-vision-android 层
```

机器私密配置（API Key / adb 绝对路径）建议放在 `$DSH_HOME/cordis.patch.yml` 或 profile 自己的 patch 里按行 id 覆盖，不要把 Key 写进仓库。

## 构建与演示

```sh
node scripts/build.mjs    # esbuild 打包 src/ → 自包含 lib/index.js（已提交构建产物）
node scripts/smoke.mjs    # 加载冒烟：Config 校验 + 11 个工具注册（无需 Key/设备）
node scripts/demo.mjs     # 端到端：截图→视觉→真实点击→验证（需 DSH_VISION_API_KEY + 设备在线）
```

## 模型对话中的用法示例

```
请打开诡秘之主这本书：先 mobile_look 看当前界面，找到这本书的坐标，
用 mobile_tap 点击，再 mobile_look 确认进入了目录页。
```

## 注意事项

- 视觉坐标为像素值；`mobile_dump` 的坐标永远精确，视觉坐标偶有偏差，重要点击前可先用 dump 校验。
- `mobile_text` 仅 ASCII（adb `input text` 限制），中文输入需设备 IME；空格已自动转义为 `%s`。
- 视觉模型可能把系统软键盘等非应用 UI 误读为应用元素；关键操作前用 `mobile_dump` 交叉验证。