前言¶
在 DSH 裏做鴻蒙相關開發或調試時，常見做法是單獨開 HDC 工具鏈、另起投屏窗口，再把截圖或頁面信息手動餵給 Agent。步驟分散，側欄裏也缺少與 NEXT 主題一致的統一入口。dsh-harmony（倉庫 kexijiang/dsh-harmony）把源自 Piora 的鴻蒙設備工作臺接到 DSH NEXT 桌面版：通過 Better Sidebar 註冊「鴻蒙設備」Tab，並提供可置頂、可縮放的獨立懸浮投屏，同時暴露 harmony_control 供 Agent 枚舉設備、觀察頁面與執行觸控類操作。
這是什麼¶
維護者爲 kexijiang，社區分類爲客戶端。插件當前版本 0.4.1（見倉庫 package.json），許可 MIT。它面向 Windows x64 上的 DSH NEXT，不承諾其他桌面分支或操作系統；數據默認落在 %USERPROFILE%\.dsh\harmony，跟隨宿主 DSH_HOME，不改動 Piora 原有數據目錄。
核心功能¶
側欄與懸浮投屏¶
- 側欄投屏與 Windows 懸浮窗可相互切換；懸浮窗支持置頂、縮放和拖動。
- 界面跟隨 NEXT 深淺色與主題；設置走不透明抽屜，連接詳情用獨立對話框。
- 主導航保留投屏、文件、媒體、設備信息；型號、系統與序列號集中在「設備信息」頁。
設備與文件能力¶
- 保留 Piora 側的設備管理、截圖、錄屏、文件與診斷能力，以及 Agent 操作接口。
- 「文件」爲目錄樹表格，按需展開，展示真實權限、修改時間與大小；右鍵或「屬性 / 操作」支持預覽文本、上傳、下載、新建、重命名、複製、移動及刪除。支持普通目錄與可調試應用沙箱；設備授權與原有寫入範圍仍然生效。
Agent：harmony_control¶
- 提供設備枚舉、頁面觀察、點擊、滑動、文字輸入等；截圖以 DSH 圖片附件返回。
- 「更多 → 界面結構」爲 UI 檢查器：獲取截圖與組件樹，點擊畫面定位組件、查看屬性，支持搜索、父組件選擇與重疊組件切換；檢查快照時不會對手機發點擊。
暫未開放的入口¶
應用、數據庫、日誌、終端、自動化和語音驗證頁面暫不開放；相關實現保留，完善後再恢復入口。
安裝與啓用¶
目標環境：Windows x64，DSH NEXT 2.0.21-next（內置 dsh 0.2.1-rc.4），Better Sidebar 0.28.2 或兼容版本。
- 在 NEXT 插件頁面安裝並啓用 Better Sidebar。
- 下載最新 Release 中的
dsh-plugin-harmony.tgz，通過 NEXT 的「添加插件」安裝本地包或 Release 地址，並啓用本插件。 - 升級後，在空閒時通過「應用 → 退出並重啓」重啓 NEXT，確保後端模塊更新。
- 打開右側邊欄，點擊 ＋ → 鴻蒙設備。連接已允許 USB 調試的鴻蒙設備，選擇「面板內投屏」或「懸浮投屏」，點擊「打開投屏」。
預構建包直鏈如下（與 README 一致）：
https://github.com/kexijiang/dsh-harmony/releases/latest/download/dsh-plugin-harmony.tgz
也可在 Releases 頁面下載同名包。插件市場爲 dsh-market，目錄來自 awesome-dsh-plugin；倉庫公開不等於已在市場可搜，收錄前可用 Release 安裝。
懸浮窗優先複用 DSH 已有 Electron；無運行時時首次打開會下載官方 Electron 43.3.0（約 140 MB）。也可在配置中指定 electronPath。手機息屏可能暫停視頻，亮屏後恢復或可點「重新連接」；插件不會繞過鎖屏或調試授權。
典型用法¶
面板側¶
連接 USB 調試已授權的鴻蒙設備後，在側欄 Tab 內選擇投屏模式並打開投屏；需要大屏對照時可切到懸浮窗。文件與 UI 檢查器從主導航或「更多」進入。
Agent 側¶
README 給出的 harmony_control 調用示例：
{"operation":"list_devices"}
{"operation":"help","topic":"observe_screen"}
{"operation":"acquire_control","input":{"serial":"設備序列號"}}
{"operation":"observe_screen","input":{"serial":"設備序列號","includeScreenshot":true}}
{"operation":"release_control","input":{"serial":"設備序列號"}}
其他操作先通過 help 獲取準確參數。任務結束或取消時應 release_control；面板與 Agent 共用設備管理器。模型由 DSH 提供，不讀取 Piora 模型憑據。
observe_page 支持分頁讀取頁面節點與祖先信息。檢查器展示的是設備實際暴露的組件，不能保證自繪畫面的內部元素；截圖與結構按順序獲取，頁面變化後需刷新。
配置¶
可在 Desktop profile 的 cordis.patch.yml 追加：
- id: harmony
config:
cwd: 'C:\HarmonyWorkspace'
dataDir: 'C:\HarmonyData'
hdcPath: 'C:\HarmonySDK\toolchains\hdc.exe'
# electronPath: 'C:\Electron\electron.exe'
省略 hdcPath 時使用內置 Windows HDC，也可在設備設置中更改。cwd 爲允許訪問的本機工作目錄；省略時使用宿主啓動目錄。文件操作會校驗真實路徑與工作目錄邊界。HTTP 接口限制本機來源；懸浮窗使用獨立隨機憑據，僅由其主進程注入請求。
適用場景與注意¶
適合誰： 已在 Windows 上使用 DSH NEXT，需要鴻蒙真機投屏、文件瀏覽、診斷，並希望 Agent 通過統一工具協議操控設備的開發者。
運行與權限： 插件在 DSH NEXT 進程權限下運行，可訪問本機 HDC、工作目錄與已授權設備上的調試能力。安裝前應閱讀倉庫源碼、NOTICE.md 與 MIT 許可；對會改寫手機數據的操作（如刪除文件、安裝應用）應自行評估風險——README 說明應用安裝/卸載、文件刪除等未作爲 UI 冒煙測試執行。
生態說明： DSH 採用「一切皆插件」思路；SkillHub 目錄頁 與 GitHub 爲社區信息來源，與 DeepSeek / 幻方無官方從屬關係。
結尾¶
dsh-harmony 把鴻蒙設備工作臺收進 NEXT 側欄與懸浮窗，並把 Piora 側能力接到 harmony_control，減少工具鏈切換成本。需要安裝包或源碼時，可訪問目錄頁 kexijiang/dsh-harmony 或倉庫 github.com/kexijiang/dsh-harmony。
