dsh-sidebar-mobile
把手机装进 DSH 的右侧边栏 —— 实时画面 + 直接点击，一套 API 同时覆盖 iOS 与 Android
mobilecli 是一条覆盖 iOS 与 Android 的设备控制 CLI，但它的 screencapture 只能写到 stdout、没有面板。本插件把它封进 DSH 的右侧边栏，并把能力同时开放给人和模型。
- 📺 实时画面：Android 走 AVC/H.264（实测 104fps），iOS 模拟器走 MJPEG（实测 131fps）
- 👆 直接在画面上操作：点击即点击、拖拽即滑动，等比例换算回设备坐标
- 🧰 11 个模型工具：读 UI 树、按标识点元素、读日志、等文本出现、把面板打开给你看
- 📱 一套 API 两端通用：真机、模拟器、模拟机走同一条路径，没有平台分支
- 🎓 自带 mobilecli 的 skill：把上游 playbook 打包注册给模型，不用自己往
.agents/ 抄
- 🔐 浏览器从不接触设备端口：只经 DSH 自己的 web 源，签名令牌 + loopback 围栏
- 📦 零运行时依赖：
react 用宿主那份；客户端源码是 JSX，但产物已提交，安装方无需工具链（见开发与自测）
目录：它解决什么问题 · 安装 · 配置 · 使用 · 安全模型 · 已知边界 · 更多文档 · License
它解决什么问题
DSH 社区已有一个 Android 插件和一个 iOS 插件，但各自踩了一个性能坑：
| 方案 | 取帧方式 | 实测帧率 |
|---|
dsh-android | adb exec-out screencap 循环（PNG） | ~1.8fps |
dsh-ios | serve-sim MJPEG | 与下同量级 |
| 本插件（Android） | mobilecli AVC / H.264（MediaCodec 硬编） | 104fps |
| 本插件（iOS 模拟器） | mobilecli MJPEG | 131fps |
瓶颈不在 adb，而在每帧搬一张完整 PNG：1080p PNG 每帧几百 KB，H.264 每帧几 KB，差两个数量级。mobilecli 在设备端用 MediaCodec 编码，只把压缩后的码流传回来。
⚠️ Flutter 应用读元素会读不到，这是预期的
Flutter 把整个 UI 画进一块不透明的原生 view，无障碍树只能看到应用主动投影出去的那部分。实测一个真实的 Flutter 应用（debug 构建）：
mobilecli dump ui --format json → 69 个节点，全部是 android.*
其中 32 个是 systemui 状态栏（时间/网速/wifi/电池），与你的应用无关
应用窗口下全是匿名 View / ImageView —— 只有 rect，没有 text、没有 identifier
更深一层：Flutter 的语义树默认根本不生成（框架出于性能考虑，只在检测到读屏类辅助技术时才生成）。所以这不是 mobilecli 的缺陷，是 Flutter 的渲染模型决定的 —— 关掉读屏时 ext.flutter.debugDumpSemanticsTreeInTraversalOrder 会明确回你：
Semantics not generated … the framework only generates semantics when asked to do so by the platform.
要读真正的 widget 树必须走 Dart VM Service，或在 Flutter 工程里跑 integration_test / Patrol。两条路线的完整实测（协议细节、踩坑、阻塞项）见 docs/FLUTTER-TREE-RESEARCH.md。
本插件不提供这个能力 —— 早先的 mobile_flutter_tree 只是个空承诺（它与 mobile_ui_tree 调同一个函数，却声称直连 VM Service），已删除。
安装
前置：mobilecli
npm install -g mobilecli@latest
mobilecli devices # 确认能看到设备
前置：adb（Android 必需）
Android 设备必须装 adb —— mobilecli 不自己实现 adb 协议，它调用外部 adb。
而 adb 缺失时 mobilecli 不报错：
{"status":"ok","data":{"devices":[]}} // exit code 0，完全看不出问题
真相只在 daemon 日志里：Failed running 'adb devices', is ANDROID_HOME set correctly?。
所以手机明明插着、驱动也正常，设备列表却是空的 —— 大概率就是缺 adb。
# 1) 下载 platform-tools
# https://developer.android.com/tools/releases/platform-tools
# 2) 让 adb 可被找到：加进 PATH，或设 ANDROID_HOME 指向 platform-tools 的**上一级**
# 3) 重启 DSH，然后让 daemon 重新读取环境
mobilecli daemon stop
⚠️ 两个都会踩的坑
① 环境变量是"启动时快照"。 装完 adb 后必须重启 DSH —— 已运行的进程
看不到新写的 PATH / ANDROID_HOME。插件会区分这两种情况：确认 adb 装了但当前
进程看不到时，提示的是"重启 DSH"而不是"去装 adb"。
② daemon 也会缓存环境。 mobilecli 的 daemon 是常驻进程，继承启动那一刻
的环境。所以即使 DSH 的环境对了，旧的 daemon 仍会报"没有设备" —— 必须
mobilecli daemon stop（或等它空闲 30 分钟自动退出）。
面板在"一台设备都没有"时会显示一条可照做的诊断（含 adb 路径与下一条动作），
而不是只显示"未发现设备"。
iOS 真机还需要在设备上装 agent（本插件不会自动装）：
mobilecli agent status --device <udid>
mobilecli agent install --device <udid> # 真机需要 provisioning profile
iOS 模拟器同样需要装一次 agent，否则取流会报 agent is not installed。
装插件
dsh plugin --profile web add @j62268781-alt/dsh-sidebar-mobile@latest
dsh web
或作为已有 profile 包的依赖：
pnpm add @j62268781-alt/dsh-sidebar-mobile
装完刷新页面，右侧边栏的「开始」页出现「移动设备」入口，点它打开面板。
也可以直接按快捷键（胶囊右侧会显示对应徽标）：
| 环境 | 键位 |
|---|
| 桌面应用 | ⌘⇧M（Windows/Linux 为 Ctrl+Shift+M） |
| 浏览器 | ⌘⌥M（Windows 为 Ctrl+Alt+M） |
桌面端没有用 ⌘M：macOS 把 ⌘M 绑给了系统「最小化」，原生菜单会先吃掉这个键。
键位可在 设置 → 快捷键 里改；与 DSH 自带的 8 条绑定均无冲突（已按宿主自身的
绑定规则校验过保留键与重叠）。
它是「开始」页的第 5 个胶囊（官方 3 个 + dsh-context 1 个）。DSH 的「开始」页有条硬规则：
胶囊超过 4 个，就关掉所有胶囊的副标题（MAX_DESCRIBED_ENTRIES = 4，不是只关第 5 个）。
所以装上本插件后，「工作区文件 / 上下文 / 新建终端 / 浏览器」的副标题会一起消失——
这是上游的取舍，插件侧无法只为自己豁免。要恢复副标题，只能把入口挪到会话标题栏
（conversation.session.header.utilities），而不是改本插件的 description。
桌面版：desktop profile 由桌面应用独占，宿主 CLI 的 dsh plugin --profile desktop 会被拒绝。桌面端请走 设置 → 插件市场。
配置
全部配置在 profile 的 cordis.patch.yml 里，挂在 dsh-sidebar-mobile 这一行下：
| 键 | 默认 | 说明 |
|---|
enabled | true | 总开关。关掉后插件仍加载，但不挂路由、不注册工具与技能 |
binaryPath | null | mobilecli 路径。null 走四级自动解析（见下） |
homeDir | null | MOBILECLI_HOME。null 用 mobilecli 默认的 ~/.mobilecli |
routePrefix | /_dsh/dsh-sidebar-mobile | 路由前缀 |
registerSkills | true | 是否把 mobilecli 的 skill 注册给模型 |
stream.idleStopSeconds | 300 | 无消费者后多久停流 |
stream.restartDelayMs | 5000 | 流崩溃后的重启延迟 |
stream.defaultScale | 1.0 | 缩放。0.5 在 iOS 上实测 104fps/6.6Mbps（全分辨率 131fps/20.6Mbps） |
useDaemonRpc | true | 交互指令优先走 mobilecli daemon 的 unix socket（实测 io tap 7.3ms，CLI 是 104.2ms）。排查时设 false 强制走 CLI |
trustedAuthorities | [] | 经反向代理访问时显式列出对外 authority |
binaryPath 为 null 时的四级解析顺序：
MOBILECLI_PATH 环境变量PATH 上的 mobilecli（npm -g 装的 shim）- 本包
node_modules 里的平台包（@mobilenext/mobilecli-<os>-<arch>）
- 全落空 → 工具仍注册，调用时给出安装提示（而不是插件加载失败）
使用
面板
右侧边栏 →「移动设备」：
- 设备下拉：按类型分组（真机 / 模拟器），每项形如
一加 12 · 真机；离线再加「（离线）」。类型来自 mobilecli 的 type 字段（real / simulator / emulator），认不出的值原样显示而不猜 —— 实测同时插着真机和模拟器时，只显示名字完全分不出哪个是模拟器
- 点一个离线模拟器会先把它启动起来（冷启动可达数分钟，期间显示启动提示，别以为卡死了）。离线真机只选中、不启动 —— 真机不归 adb 启动。启动失败不影响选中，但会如实报错，不会让你对着黑屏猜
- ⌂ / ◁ / ⟳：主屏幕 / 返回（仅 Android）/ 旋转
- ⟲：重新申请令牌并重连（画面卡住时用）
- ▢ / ▣ / ▤：切换外观（边框 / 真机 / 无框）
- 在画面上点击 → 点设备的对应位置；拖拽 → 滑动
- 模型也能替你打开这个面板（
mobile_open_panel）。⚠️ 它不是给模型读界面用的 —— 面板在浏览器里、不在模型上下文里。用途是需要你亲眼看屏幕时把它推到你面前
状态栏显示 实时/未串流、平台、以及实际拿到的流格式（H.264 或 MJPEG）。
模型工具
只注册 11 个「工具能做得比 CLI 更好」的工具：
| 工具 | 用途 |
|---|
mobile_devices | 列出所有设备（先跑这个拿到 device id） |
mobile_boot | 启动设备并开始串流（画面出现在面板） |
mobile_ui_tree | 读界面首选：类型、文本、identifier、坐标 |
mobile_screenshot | 截图（给人或多模态模型看，不是读界面的首选） |
mobile_tap_element | 按标识/文本点元素（比坐标稳，可带 expect_text 一并验证） |
mobile_list_apps | 列已安装应用（启动前先列，别猜包名） |
mobile_find_text / mobile_tap_text | OCR 找文字 / 点文字（树读不到时的兜底） |
mobile_wait_for | 等文本出现或消失 |
mobile_logs | 读设备日志（logcat / unified log） |
mobile_open_panel | 把侧边栏的移动设备面板打开给用户看（跨进程，需要客户端在跑） |
为什么不给 tap / swipe / 输入 / 按键 / 启动应用注册工具
这 5 个曾是工具，但只是 mobilecli 的薄包装（一次 runJson 加一句 return），
没有任何加工 —— 而 agent 本来就有 shell，直接跑等价命令即可：
mobilecli io tap --device <id> 540,1200
mobilecli io swipe --device <id> --duration 250 540,1800,540,700
mobilecli io text --device <id> "hello"
mobilecli io button --device <id> BACK
mobilecli apps launch --device <id> com.example.app
这 5 个的 schema 每次请求都要发 —— 删掉它们实测省 453 tokens/轮
（16 个 = 1487 → 11 个 = 1034）。
此后又删了 mobile_flutter_tree（与 mobile_ui_tree 重复），
并加了 mobile_open_panel。当前是 11 个 = 964 tokens/轮 ——
数的个数一样，但不是同一批工具，别把这个差值和上面的 453 混起来。
⚠️ 关键细节没跟着删，都在 skill 的「Driving the device from the shell」一节：
坐标是物理像素、io swipe 必须传 --duration（否则默认 1000ms 慢动作）、
输入前必须先聚焦、io button 的键名、启动前先列应用。
被删的名字留在 REMOVED_TOOL_NAMES 里，便于分辨「插件删了它」和「名字打错了」。
工具描述里写明了"先用哪个、什么时候升级到下一个"，因为三种观察方式的代价差一个数量级：
mobile_ui_tree ~100–300ms 结构化，首选
mobile_screenshot ~200–400ms 给人看
mobile_find_text ~1s OCR，兜底
自带 skill
mobilecli 仓库里的 playbook（SKILL.md + reference.md）被原样打包并注册，模型可以直接读到命令的完整用法、平台差异、以及一批踩坑记录。不需要你往 .agents/ 里抄一份。
安全模型
浏览器从不接触 mobilecli 的端口（它监听 localhost 且没有鉴权）。所有字节只经 DSH 自己的 web 源：
<img src="/_dsh/dsh-sidebar-mobile/stream/<token>">
→ 围栏校验 → Host 转发到 mobilecli → 回传
两道闸门，顺序不可颠倒：
- 传输层围栏（先）：对端必须是 loopback（TCP 层事实，客户端伪造不了）；
Host 头必须是 loopback 或显式配置的 trustedAuthorities。Host 与 Origin 是客户端可控数据，这里只用它们否决，从不用来授权。
- capability（后）：HMAC-SHA256 签名，10 分钟过期。
deviceId 参与签名，所以给 A 设备签的令牌拿到 B 上用不了。
为什么不只用 token：它会进浏览器历史、日志、Referer。围栏先挡住"根本不是本机来的"请求，token 才有意义。
自测覆盖了 DNS rebinding、令牌篡改、过期、跨 DSH_HOME 复用、跨站 POST。
已知边界
- ⚠️ mobilecli 会独占设备的 UiAutomation。上游源码注释原文："While it runs it holds the device's only UiAutomation, which kills every other UiAutomator client (
uiautomator dump, Appium)." 实测确认：daemon 运行时 adb shell uiautomator dump 静默失败（文件根本不生成），mobilecli daemon stop 后立刻恢复。受影响的是 Appium、UiAutomator、以及任何依赖 uiautomator dump 的工具；不受影响的是 adb shell input、screencap、以及进程内的 Flutter 测试（integration_test / patrol 的 Dart 部分不碰 UiAutomation）。
- ⚠️ Android 必须有 adb，且 mobilecli 不会为此报错。缺 adb 时
devices 返回空列表 + exit code 0，看起来跟"没插手机"一模一样。插件会主动体检并区分这两种情况（见前置：adb）。
- ⚠️
--fps 参数不生效。复测（Xiaomi 15 Pro / 1080×2400 / mobilecli 1.0.19）：不传 → 120.6fps，--fps 30 → 105.5fps，--fps 15 → 100.7fps，传什么都是 ~120fps。所以限流只能在客户端渲染侧做：插件每帧都解码（保住 H.264 参考链 —— 丢 P 帧会花屏），但只按 30fps 绘制。想降带宽只能用 --scale 或 --bitrate。
- ⚠️ swipe 不传
--duration 时会跑满 1000ms。实测 io swipe 不带该参数耗时 1074ms，带 --duration 300 只需 374ms。插件按手指按住时长自动计算并透传。
- ⚠️
--bitrate 默认值偏低。实测 1080×2400 静止仅 0.98 Mbps、滑动 2.15 Mbps（大范围运动时明显发糊）。插件默认传 8 Mbps，同场景实测可达 6.6 Mbps。
- ⚠️ iOS 的
--format avc 会被静默降级成 MJPEG。这也是本插件从首块字节嗅探格式、而不相信请求参数的原因。
- 多个 DSH 进程不能共用同一个 daemon。需要并行时给每个 profile 配不同的
homeDir。
- ⚠️ 从源码装时不能用软链。本插件的 Host 半 import 宿主包（
@deepseek-ai/dsh-tools），而 Node 的 ESM 解析会以软链的真实路径为基准去找 node_modules——源码目录下没有那些包，于是启动日志报 failed to import（伴随 1 entry did not activate）。实测对照：同一个插件软链失败、真实目录成功。用 dsh plugin add "link:$PWD" 或 cp -R 成真实目录，见 docs/DEPLOY-DSH.md。发到 npm 后不受影响。
开发与自测
客户端半边有源码与产物之分，改客户端代码前先看这一节：
src/client/index.jsx ← 手写源码（JSX）
src/client/styles.css ← 手写源码（样式）
lib/client.js ← 构建产物，已提交进仓库；安装方加载的就是它
scripts/build-client.mjs
npm run build # 由 src/client/ 生成 lib/client.js —— 改完客户端必须跑
npm test # 147 项，无设备也能跑完（有设备时额外验证真实调用）
npm run check # Host 半边语法检查
npm run build:check # 校验 lib/client.js 与 src/client/ 是否同步
npm run verify # build:check + check + test（提交前跑这个）
⚠️ 改了 src/client/ 一定要 npm run build 并一起提交。
产物进仓库是为了让安装方（git 依赖）完全不需要工具链，代价是它会漂移 ——
build:check 就是拦这个的：它重新构建一遍并与提交的产物逐字节比对，
不一致就失败。忘了构建而只提交源码，安装方拿到的仍是旧面板。
lib/ 按职责分目录（device/ 怎么跟设备说话、stream/ 视频流链路、
agent/ 给模型的那一面），唯一放在根下的 client.js 就是上面那个构建产物。
自测覆盖：二进制四级解析（含 Windows shim 回归）、adb 体检与六类失败诊断、错误归一化、令牌签名与篡改检测、loopback 围栏（含 DNS rebinding）、流格式嗅探、交互输入校验（含 swipe duration 透传）、路由匹配、skill frontmatter 剥离、客户端构建产物是否过期。
更多文档
License
MIT。依赖的 mobilecli 采用 FSL-1.1-ALv2（源码公开，非 OSI 开源；内部使用属 Permitted Purpose，且每个版本满两年后自动转为 Apache-2.0）。
