前言¶

在 DSH 里做自动化，经常需要「看一眼手机屏幕」。scrcpy 本身能把安卓画面投到电脑，但它是命令行工具：要记参数、要判断当前是 USB 还是无线、要查手机的 IP、手机重启之后还要重新 adb tcpip。每一步都能做，每一步都要人手动判断。

gem-gti/dsh-scrcpy-mirror 做的事情就是把这些判断封装成一个 DSH 插件，让模型可以通过 phone_mirror 工具直接启动投屏、查状态、截图。下面介绍它提供了哪些能力、怎么装、怎么用。

这是什么¶

由 gem-gti 维护的客户端类插件，基于 scrcpy 把安卓手机画面投到 Windows 电脑。它本身不含客户端部分，只提供工具与命令：

• 给模型用的 phone_mirror 工具，支持 status / start / stop / connect / screenshot
• 给使用者用会话命令 /mirror，不经过模型，直接在输入框执行

平台与宿主要求¶

• 仅 Windows（依赖 scrcpy.exe / adb.exe）
• 宿主：DeepSeek Harness >=0.2.0-rc.1 <0.3.0-0
• 本机需已安装 scrcpy，package.json 里 engines.node 要求 >=20

核心功能¶

phone_mirror 工具的各 action：

除了给模型用的工具，插件还注册了一个会话命令，在输入框直接敲即可：

/mirror              启动投屏（等同 start）
/mirror stop         停止投屏
/mirror status       查看设备与连接状态
/mirror connect      手机重启后重连无线
/mirror screenshot   截一张手机屏幕

命令走 Host 侧的 ctx.commands.register，结果以纯文本显示在会话里。

安装与启用¶

以下命令来自插件 README，均为 PowerShell。先选其中一种安装方式，再重启 DSH 或在插件页启用 phone-mirror。

本地目录（开发调试）：

dsh plugin --profile desktop add "D:\path\to\dsh-scrcpy-mirror"

本地 tarball：

npm pack
dsh plugin --profile desktop add ".\mu-dsh-scrcpy-mirror-0.2.0.tgz"

从 npm 安装（发布后）：

dsh plugin --profile desktop add dsh-scrcpy-mirror

社区市场：发布到 npm 并被目录源（如 DSH 1024Store）收录后，在 DSH 的「社区市场 → 可安装」里搜索 Phone Mirror 点击安装即可。

典型用法¶

安装后在对话里直接说「帮我看看手机投屏状态」「开一下手机投屏」「手机重启了，无线连不上了」「截一张手机屏幕给我」，模型会依次调用：

{ "action": "status" }
{ "action": "start" }
{ "action": "connect" }
{ "action": "screenshot" }

status 的返回示例（节选自 README）：

scrcpy: C:\Users\...\scrcpy.exe
adb: C:\Users\...\adb.exe
网关（连着手机热点时即手机 IP）: 10.99.177.119
网关 5555 端口: 开放
设备:
  - VCJFK7WSLNS8TOEQ（USB）
  - 10.99.177.119:5555（无线）
投屏进程: 127224

这个例子本身说明了它将手机 IP 推断成网关：连着手机热点时，网关即手机地址。

配置¶

cordis.patch.yml 里该行的 config 可以覆盖默认值：

- insert:
    - id: phone-mirror
      name: dsh-scrcpy-mirror
      config:
        maxSize: "1280"        # 画面最长边，越大越清晰
        bitRate: "6M"          # 视频码率；USB 可 8M，无线建议 4M~6M
        audioSource: output    # output=抓全系统声音且手机静音 / playback / mic
        turnScreenOff: true    # 手机熄屏但投屏继续
        alwaysOnTop: true      # 投屏窗口置顶
        shortcutMod: lctrl     # 快捷键修饰键：lctrl（推荐）/ lalt
        adbPort: 5555
        scrcpyPath: ""         # 留空则自动在 winget 目录与 PATH 中查找
        adbPath: ""

前置条件¶

1、电脑装好 scrcpy：

winget install --id Genymobile.scrcpy

2、手机开启「开发者选项 → USB 调试」。
3、首次插线时在手机上点「允许 USB 调试」。
4、想无线投屏：电脑连手机热点（或同一 WiFi），跑一次 connect。

实现说明¶

插件调用外部命令（adb / ipconfig / tasklist / taskkill / scrcpy）时不使用管道，而是用 spawn + 文件句柄直写临时文件再读取。原因是 DSH 宿主可能在受限沙箱里运行插件工具，管道式 stdio 会被直接拒绝（spawn EPERM），表现为「命令静默失败、设备永远查不到」。

手机 IP 的推断也不是只靠 IPv4 默认网关——README 提到小米/澎湃热点常常只下发 IPv6 网关，所以回退顺序是：IPv4 网关 → DHCP 服务器（就是手机）→ 同网段 .1。

适用场景与注意¶

适合在 Windows 上用 DSH 做 Android 相关自动化的开发者：需要让模型能主动查看手机画面、截图，或让使用者不经过模型也能一键投屏。

几点需要注意：

• 仅 Windows 可用，taskkill / ipconfig / winget 路径都按 Windows 实现。
• 插件以当前 dsh 进程权限运行，安装前应检查源码与许可证（本项目为 MIT，投屏能力来自 Apache-2.0 的 scrcpy，本项目不打包其二进制，仅调用本机已安装版本）。
• 手机重启后无线必然失效，这是 adb 的限制，需要插一次线跑 connect。
• 小米/澎湃机型上，scrcpy 自带的「点亮屏幕」快捷键常被系统拦掉，插件不提供唤醒，需要按手机电源键。
• 投屏窗口是 scrcpy 自己的窗口，不在 DSH 界面内。
• README 还说明了一点：该插件不含客户端部分，原因是 DSH 的自定义 Host 服务需要 Typert 编译器生成的 ./typert 入口才能被 remote.xxx 访问，手写 bundle 没有该产物，客户端注入会一直等待并拖垮整个前端启动。所以本插件只提供工具与命令。

结尾¶

这个插件把 scrcpy 的命令行操作收敛成一个工具和一个命令，适合 Windows 上需要让模型直接查看/操作 Android 画面的场景。目录页见 https://www.skillhub.cn/plugins/gem-gti/dsh-scrcpy-mirror，源码见 https://github.com/gem-gti/dsh-scrcpy-mirror。