ciky20171114/dsh-plugin-midscene

dsh-plugin-midscene

CI

为 DeepSeek Harness（DSH）提供基于 Midscene 的 AI 驱动 UI 自动化。模型看得到屏幕、用自然语言描述定位元素、对真实目标执行操作——一台真实的 Android 设备或一个真实的 Chrome 浏览器。

一个能力 seam（ctx.midscene）、两个 Provider、两个工具：

| | Provider 入口 | 工具 | 目标 |
|---|---|---|---|
| Android | dsh-plugin-midscene/android | android_ui | 一台 ADB 连接的设备 |
| Web | dsh-plugin-midscene/web | web_ui | 一台已经在运行的 Chrome 的活动页面 |

每个工具都是带 action 参数的单工具（与 str_replace_editor 同风格）：模型选择一个动作（tap / act / input / query / assert / boolean / back），工具在内部自行分发——不撑大工具面。

前置条件

- DSH（dsh CLI）及一个 profile
- Android：adb devices 能看到设备
- Web：Chrome 以 --remote-debugging-port=9222 --user-data-dir= 启动；Provider 只连接、绝不启动浏览器
- 一个 Midscene 兼容的视觉模型，通过环境变量配置（见模型配置）

安装

dsh plugin --profile mysetup add dsh-plugin-midscene

bundle 的默认层注册两个工具。工具以机会主义方式读取 ctx.midscene，所以即使还没配置 provider 工具也已出现——此时调用会以一条指明缺失 provider 行的错误失败。

然后向 profile 的 cordis.patch.yml（~/.dsh/profiles/mysetup/cordis.patch.yml）加恰好一个 provider 行（两个 provider 不能在同一个 context 里同时拥有 ctx.midscene）：

Android

- insert:
- id: midscene-android
name: dsh-plugin-midscene/android
config:
deviceId: ''            # 留空：选择 getConnectedDevices() 的第一台
aiActionContext: ''     # 供 aiAct 规划使用的自由文本上下文，例如应用约定

Web

- insert:
- id: midscene-web
name: dsh-plugin-midscene/web
config:
browserWSEndpoint: 'ws://127.0.0.1:9222/devtools/browser/'
aiActionContext: ''

可直接粘贴的 provider 行见 examples/。

从 http://127.0.0.1:9222/json/version 的 webSocketDebuggerUrl 取端点。注意该 Chrome 每次重启后 id 都会变——更新此行并重启 dsh。

销毁时 provider 会销毁自己的 agent，然后对浏览器执行 disconnect() —— 绝不 close()：Chrome 进程属于你的部署，继续运行。

启动：

dsh --profile mysetup          # 若 3080 被占用，加 --port 3081

安装排错

dsh plugin add 报 ERR_PNPM_IGNORED_BUILDS，点名 sharp / @ffmpeg-installer/linux-x64：pnpm ≥ 10 会拦截这些传递依赖的安装脚本（来自 @midscene/），直到显式声明。处理：打开 ~/.dsh/profiles//pnpm-workspace.yaml，把 pnpm 列在 allowBuilds 下的键设为 false（插件没有它们也能工作——仅当你要 sharp/ffmpeg 二进制做真机截图/录屏时才设 true），然后重新执行 add。每个 profile 只需一次。

工具参考

android_ui 与 web_ui 共享同一形状：

| action | 其余参数 | 结果 |
|---|---|---|
| tap | prompt（元素描述） | ack |
| act | prompt（目标描述） | ack + agent 自身的结果文本（若有） |
| input | prompt（元素）+ value（要输入的文本） | ack |
| query | demand（要提取什么） | 提取出的 JSON |
| assert | prompt（断言）+ 可选 msg | pass/fail + 可选思考过程 |
| boolean | prompt（是/否问题） | true/false |
| back | — | ack（Android：系统返回；Web：历史返回） |

schema 无法表达的跨字段规则（如 input 必须有 value、query 必须有 demand）在 execute 中以指名道姓的错误消息强制执行。断言失败是一次成功的 pass: false 结果——错误路径只留给基础设施故障（设备消失、websocket 拒绝）。

模型配置

Midscene 的视觉模型通过 @midscene/ 自身的约定配置——环境变量，而非 DSH 的 ctx.llm：

export MIDSCENE_MODEL_NAME=glm-4.6v
export MIDSCENE_MODEL_BASE_URL=https://open.bigmodel.cn/api/paas/v4/
export MIDSCENE_MODEL_API_KEY=
export MIDSCENE_MODEL_FAMILY=glm-v

（任何 OpenAI 兼容的多模态端点都可以——设置对应变量即可。）

设计边界：不含策略、不含恢复

Provider 是刻意的薄传输层：无重试、无前置条件检查、无对意外 UI 状态的自动恢复（意外弹窗、非预期跳转、重新登录）。有这类需求的调用方在其上自行构建——例如每次写操作前检查应用状态的约束/harness 层。

已知限制

- 每个 provider 实例一个目标 —— 每个 context 一台设备或一台浏览器；扇出需要隔离的组合。
- 不重连 —— 会话中途断开表现为一次被拒绝的调用。
- 锁定 SDK 版本 —— @midscene/android / @midscene/web 精确锁定在 1.11.0；升级是一次刻意的版本 bump。
- puppeteer 是 peer（web）—— 由部署方的 pnpm 解析；Chrome 本身由部署方提供，本插件绝不下载。

开发

git clone https://github.com/ciky20171114/dsh-plugin-midscene
cd dsh-plugin-midscene
pnpm install   # 原生/浏览器安装脚本默认被拒绝；测试 mock 掉 SDK
pnpm test      # 只测接线：mock 的 @midscene/*、puppeteer，真实工具注册表背后的 stub seam
pnpm build     # tsc 输出到 lib/（git 安装时作为 prepare 运行）

目录结构：

src/service.ts   MidsceneService 定义 —— ctx.midscene seam（7 个操作）
src/android.ts   Android provider（AndroidDevice + AndroidAgent，ADB）
src/web.ts       Web provider（puppeteer.connect + PuppeteerBrowserAgent，只连接）
src/tool.ts      android_ui + web_ui 工具（一份共享定义，action 分支）
tests/           31 个接线测试 —— 绝不碰真机或真浏览器

开发时把本地 checkout 装进 profile：

dsh plugin --profile dev add /path/to/dsh-plugin-midscene

社区与支持

欢迎通过 GitHub Discussions 提交反馈或 bug 报告。本仓库携带 dsh-plugin topic 以便被检索到。

许可证

MIT