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