前言¶
在 DSH 里做安卓或鸿蒙设备的投屏与自动化，如果每个平台各自实现一套菜单、标签页、解码和 AI 工具，会话侧会出现重复注册、权限口径不一致、以及「当前操作哪台设备」难以统一的问题。DeepSeek Harness 的插件模型允许把能力拆成多个包协作；dsh-scrcpy-core 的定位是 scrcpy 投屏对用户和 AI 都只有这一个门面——界面、设备列表、投屏面板与 AI 工具集中在本包，具体平台怎么连设备、怎么推流，交给各自的 provider。
下面介绍该插件是什么、能做什么、如何安装与使用，以及和 provider 配合时的注意点。事实以仓库 README 为准；维护者为 ns-zzj，npm 包名为 @nszzj/dsh-scrcpy-core（资料中版本 1.0.2，MIT 许可证）。
这是什么¶
dsh-scrcpy-core 是 DSH 客户端分类下的 scrcpy 共用核心。它自己不识别鸿蒙或安卓，只负责：
- 投屏面板 UI、每台设备一个标签页
- jmuxer 解码
- AI 工具、提示词、权限门禁
- 设备与聚焦状态、命令路由
各平台由独立 provider 提供「这类设备怎么说话」：
| 包 | 作用 |
|---|---|
@nszzj/dsh-scrcpy-core（本包） |
上述共用能力 |
dsh-hos-scrcpy |
鸿蒙：hdc 传输 + Java sidecar（HOScrcpy SDK） |
dsh-android-scrcpy |
安卓：adb 传输 + 官方 scrcpy-server |
资料明确：provider 不注册 UI、不注册 AI 工具、不写 AI 提示词、不关心当前聚焦哪台设备——这些都在 core。
核心功能¶
会话内的投屏体验¶
- 会话右上角「scrcpy 菜单」展示按平台分组的设备列表（鸿蒙 / 安卓），每组带环境检测（鸿蒙组显示 Java +
hdc，安卓组显示adb）。 - 设备行点「启动」：起服务并打开该设备的投屏标签页（一机一标签，互不干扰）。
- 投屏面板上：鼠标点拖映射触摸、
返回/主页/音量、向聚焦输入框注入文本、「添加截图至聊天框」、以及该平台支持时的「日志」。 - 切到其他标签页不断流：画面暂停广播以省解码与内存，回到标签页继续播放。
给 AI 的工具（中性名，只注册一次）¶
| 工具 | 作用 | 需要权限 |
|---|---|---|
scrcpy_devices |
列出已连接设备、当前聚焦设备、四项权限状态 | 不需要 |
scrcpy_screenshot |
截屏 + 内置视觉模型识别 | 允许截图 |
scrcpy_locate |
读控件清单（比例坐标 0..1 等字段） | 允许控制 |
scrcpy_tap / scrcpy_longpress |
按比例坐标点击 / 长按（执行前确认并在画面闪绿点） | 允许控制 |
scrcpy_key |
按 provider 声明的可用键（如安卓 provider 的 back / home） |
允许按键 |
scrcpy_input |
向当前聚焦输入框注入文本（支持中文） | 允许输入 |
所有操作类工具只作用于用户在投屏面板里正看着的那台设备；无聚焦设备时会明确报错，不会自动选一台。
每台设备独立四组权限开关，每组三态：禁止使用 / 需要确认 / 无需确认。「允许控制」「允许按键」「允许输入」依赖「允许截图」；关掉截图会连带关掉它们。
版本与 provider 兼容¶
三个包各自独立发版、独立安装。provider 登记时声明 coreCompat（如 "1.0.0"、"^1.0.0"、">=1.0.0"）；判定权在 core，不匹配则该 provider 标为停用，设备不进列表、动作不路由，菜单组显示「已停用」及原因，其它 provider 不受影响。
安装与启用¶
要装两个包：core + 你目标平台的 provider。 core 必须装成 profile 的直接依赖；只装 provider 时 core 仅为传递依赖，bundle 层不挂载且不会有警告（README 2026-09-25 对照说明）。只装 provider、未装 core 时状态为 pending (waiting for service: scrcpyProviders)，不报错但不可用，属设计行为。
桌面端（资料称 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 路径
github:规格（例如github:ns-zzj/dsh-scrcpy-core）
禁用 / 启用：README 实测 启用可热生效；禁用会从 profile 的 dsh.profile.bundles 摘掉该包（依赖保留，恢复不必重装），但已装载实例不会在运行中卸载，需重启后才真正消失。
命令行（web 等 profile）¶
dsh plugin --profile <profile> add dsh-scrcpy-core dsh-hos-scrcpy
或把 dsh-hos-scrcpy 换成 dsh-android-scrcpy。然后重启 dsh web；会话右上角出现「scrcpy 菜单」即表示安装成功。
支持范围¶
主力为桌面端（Electron）。dsh web 大体可用（客户端半区为浏览器代码，RPC 走宿主 HTTP），但 README 注明未做完整验证，出问题以桌面端为准。WS 握手的 Origin 校验放行 dsh-app:// 与本机回环，web 版一般不因 Origin 被挡；外部网页会得到 403。
典型用法¶
- 安装 core 与对应 provider 后，打开 DSH 会话，点右上角「scrcpy 菜单」，确认平台组环境检测通过。
- 在目标设备行点「启动」，在投屏标签页内操作设备；需要 AI 介入时，在每台设备的投屏面板「设置」里配置四项权限与识别模型。
- 连接类参数（Java 路径、
hdc、adb等）在菜单里各平台组右上角「连接设置」中填写——字段与检测由 provider 提供，core 只渲染表单。 - 在对话中让 AI 调用
scrcpy_devices了解聚焦设备与权限，再按需使用截图、定位、点击、按键、输入等工具；需要确认模式下用户可拒绝，AI 不应在拒绝后盲目重试。
识别模型下拉列出所有 provider 的所有模型（不按是否支持图片筛选）；若选了不支持图片的模型，由上游 API 报错。
适用场景与注意¶
适合谁： 已在 DSH 桌面端或 web profile 中开发、调试，并需要统一投屏 UI 与 AI 操控入口的团队或个人；实际连设备、推流需另装 dsh-hos-scrcpy 或 dsh-android-scrcpy。
运行与信任： 插件在当前 DSH 进程权限下运行，可访问本机 adb/hdc、设备画面与输入。安装前请阅读 GitHub 源码 与 MIT 许可证，自行评估是否纳入工作流。
已知限制（摘自 README）： 安卓 provider 目前没有日志流；鸿蒙 SDK 在画面静止时可能无帧，界面会提示用户滑动手机，安卓无此提示；投屏为变化驱动，静止时帧计数不增长属正常；安卓侧已实现 UHID 外接键盘（点一下画面后 PC 键入由设备输入法处理），「输入」按钮走直接注入文本；鸿蒙侧 uinput 能否喂给输入法 README 标注未实测。
社区目录 skillhub.cn 插件页 为独立站点，与 DeepSeek / 幻方无官方从属关系；DSH 生态理念是「一切皆插件」，本包是投屏栈的共用层，而非单独完成全平台投屏的单体插件。
结尾¶
dsh-scrcpy-core 把投屏界面、多设备标签、解码、权限与 AI 工具收到一处，平台差异下沉到 provider，避免重复注册与路由混乱。使用上记住 core 与 provider 都要装、core 须为直接依赖，桌面端走应用内插件面板，CLI profile 用官方 add 命令并重启 web。
