投屏控制核心 ns-zzj/dsh-scrcpy-core

dsh-scrcpy-core

DSH 的 scrcpy 共用核心 —— 对用户、对 AI 都只有这一个门面。

它自己不认识任何平台：鸿蒙、安卓各由一个 provider 包提供“这类设备怎么说话”。

| 包 | 作用 |
| @nszzj/dsh-scrcpy-core（本包） | 投屏面板 UI、每设备一个标签页、jmuxer 解码、AI 工具、提示词、权限门禁、设备与聚焦状态、命令路由 |
| dsh-hos-scrcpy | 鸿蒙 provider：hdc 传输 + Java sidecar（HOScrcpy SDK） |
| dsh-android-scrcpy | 安卓 provider：adb 传输 + 官方 scrcpy-server |

provider 不注册 UI、不注册 AI 工具、不写 AI 提示词、不关心“当前聚焦哪台” —— 那些全在 core。

安装

桌面端（0.1.7，当前主力）

dsh plugin --profile desktop … 会被 CLI 拒绝：

error: profile "desktop" is managed exclusively by the Electron application

必须走应用内的插件面板。面板接受三种形式：

- npm 包名（core 是 @nszzj/dsh-scrcpy-core；鸿蒙是 @nszzj/dsh-hos-scrcpy；安卓是 @nszzj/dsh-android-scrcpy）
- 本地 tgz 路径（例如 nszzj-dsh-scrcpy-core-1.0.0.tgz）
- github: 规格（例如 github:ns-zzj/dsh-scrcpy-core）

要装两个包：core + 你要的平台 provider。

命令行（web 等 profile）

dsh plugin --profile add dsh-scrcpy-core dsh-hos-scrcpy # 或 dsh-android-scrcpy

然后重启 dsh web，会话右上角出现「scrcpy 菜单」即成功。

三件必须知道的事

1. core 必须装成 profile 的直接依赖（就是上面那样把它单独列出来）。
只装 provider 时 core 只是传递依赖，不会被登记成 bundle 层 —— 层不挂载、那一行没人插，而且不会有任何警告（2026-09-25 两组对照实测）。
2. 装 provider 不会自动带 core（“自由装”）。没装 core 时 provider 的状态是
pending (waiting for service: scrcpyProviders) —— 不报错，但也用不了，这是设计如此，不是 bug。
3. 桌面端：禁用 / 启用后想立刻看到效果要重启。
实测：启用是热的（立刻生效、不用重启）；禁用只写文件 ——它会把这个包从 profile 的 dsh.profile.bundles 里摘掉（依赖保留，所以恢复时不用重装），但已经装载的插件实例不会在运行中卸载，所以要重启才真正消失。

支持范围

主力是桌面端（Electron）。dsh web（在浏览器里打开 GUI）大体也能用 ——客户端半区本来就是浏览器代码，RPC 也走宿主 HTTP —— 但未做完整验证，出问题请以桌面端为准。

WS 握手的 Origin 校验同时放行 dsh-app://（桌面端渲染进程的真实 Origin，2026-09-26 实测；
不是 http://127.0.0.1:19387）与本机 http 回环（127.0.0.1 / localhost / [::1]，端口不限），
所以 web 版不会因为这条被挡；只有外部网页（以及 DNS rebinding）会拿到 403。

怎么用

1. 会话右上角点「scrcpy 菜单」→ 按平台分组的设备列表（鸿蒙设备 / 安卓设备），每组还带自己的环境检测（鸿蒙组显示 Java + hdc，安卓组显示 adb）。
2. 设备那行点「启动」→ 起服务、打开这台设备的投屏标签页（每台设备一张，互不干扰）。
3. 投屏面板上可以：鼠标点/拖 = 触摸、返回/主页/音量 按键、「输入」按钮（向当前聚焦的输入框注入文本）、「添加截图至聊天框」、以及该平台支持时的「日志」。
4. 切走别的标签页不断流：画面只是暂停广播（省解码与内存），回来接着放。

设置

- AI 控制设置（每台设备的投屏面板 →「设置」）：四项权限 + 识别模型。
- 连接设置（菜单里各平台组右上角）：由该 provider 自己提供字段与检测，core 不认识 “Java 路径 / hdc / adb”这些概念，只负责把它渲染成表单。
- 识别模型下拉列出所有 provider 的所有模型（不按“是否支持图片”筛 —— 非官方 API 大多不报这个字段，会误伤）。选了不支持图片的模型，就由上游 API 自己报错。

给 AI 的工具（一套中性名，只注册一次）

| 工具 | 作用 | 需要权限 |
| scrcpy_devices | 入口：列出已连接设备、当前聚焦哪台、它四项权限状态 | 不需要 |
| scrcpy_screenshot | 截屏 + 内置视觉模型识别（描述画面、找控件） | 允许截图 |
| scrcpy_locate | 读控件清单（type/text/id/key/clickable/fx/fy/w/h，比例坐标 0..1） | 允许控制 |
| scrcpy_tap / scrcpy_longpress | 按比例坐标点击 / 长按，执行前弹确认并在画面上闪绿点显示落点 | 允许控制 |
| scrcpy_key | 按 provider 声明的可用键（安卓 provider 目前是 back 返回 / home 回桌面；声明变了界面标题也跟着变） | 允许按键 |
| scrcpy_input | 向当前聚焦的输入框注入文本（支持中文） | 允许输入 |

所有操作类工具只作用于“当前聚焦”的那台设备（= 用户在投屏面板里正看着的那台）。
没有聚焦设备时工具会明确报错，绝不替你猜一台。

权限：四项 × 三态

每台设备独立四组开关，每组三态：禁止使用 / 需要确认 / 无需确认。

- 「允许控制」「允许按键」「允许输入」都依赖「允许截图」 —— 关掉截图会连带关掉它们。
- 需要确认：每次调用弹二次确认（用户可能拒绝，拒绝后 AI 不应重试）；无需确认：直接执行。

版本与兼容

- 三个包各自独立发版、各自独立安装。
- provider 在登记自己时声明 coreCompat（一段“匹配我需要的 core”的文字）：支持 "1.0.0"（精确）/ "^1.0.0"（同 major）/ ">=1.0.0"（下限）。
- 判定权在 core：core 拿自己的版本比对，不通过就把该 provider 标成停用 ——它的设备不进列表、动作不路由（= 不让用），菜单那一组显示「已停用」+ 一句原因。
provider 自己不报错，坏的那个不会拖垮别的；core 里也不维护“支持哪些 provider 版本”的表。
- 装了 provider 没装 core：只是 pending（等 scrcpyProviders 服务），不报错、用不了。

已知限制

- 安卓 provider 目前没有日志流（鸿蒙那边是 hilog）；没有该能力的 provider，投屏面板不显示「日志」按钮。
- “暂无画面”的含义按平台不同：鸿蒙 SDK 只在画面变化时推帧，所以“没帧”时提示用户滑一下手机；安卓不需要这个提示（没帧只是画面没变化）。文案由 provider 能力决定。
- 投屏本身是变化驱动的：画面静止时不推帧，帧计数/字节数不会增长 —— 这是正常现象。
- 键盘：安卓侧已实现真外接键盘（UHID）—— 鼠标点一下画面，PC 按键就直输给设备，平板自己的输入法会接管（拼音组词 + 候选词，2026-09-26 真机实测通过：打 ce'shi 出「1测试 2侧石 3侧视 …」）。另外「输入」按钮是“直接塞字”（走 INJECT_TEXT，任意中文都行、但不出候选词）。鸿蒙侧目前是 uinput，能否喂给输入法未实测。
- 菜单观感仍在调整。

开发者

契约（provider 怎么登记、动作接口、投屏流协议、版本判定）：见 CONTRACT.md。

dsh-scrcpy-core/
├── package.json # dsh.bundle（本包是 bundle 层）+ dsh.client ├── cordis.patch.yml # 【只插 core 自己那一行】—— 两个 provider 各插自己的行，谁都不许碰 core 行 ├── lib/ # Host 半区：注册表 / 设备与聚焦状态 / 命令路由 / 工具 / 提示词 / RPC ├── client/ # 浏览器半区：全部 UI ├── resources/ # jmuxer.min.js（解码库，随包发） ├── CONTRACT.md # core ↔ provider 契约 └── README.md

为什么每一行只有一个 owner：applyEntryPatches 不按 id 去重 —— 两个 bundle 层各插一条同 id 条目，组合结果里就会留下两条，挂载时被 EntryGroup.update 以 duplicate loader entry id 拒绝、启动直接失败。