前言¶
在 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。
