前言¶
在 DSH 里做 HarmonyOS 开发，常见做法是接 MCP 服务器暴露 hdc 能力，或让模型凭记忆回答 API 问题。前者能连设备，但缺少 DSH 原生的工具卡片、截图闭环和会话级沙箱策略；后者在版本差异和离线场景下容易出错。
dsh-hdc-bridge 走另一条路：不重写 hdc 协议，直接复用本机 hdc 二进制（3.x），把设备调试、官方知识层和可选 DevEco CLI 构建通道封装成 DSH 客户端插件。下面介绍它的定位、能力与安装用法。
这是什么¶
dsh-hdc-bridge 由维护者 1na-ko 发布，分类为客户端插件，当前版本 0.7.3，MIT 许可。GitHub 仓库 14 stars。
一句话定位：DSH 原生鸿蒙开发助手——hdc 设备闭环调试、官方优先版本化知识层（离线 Tier-1 随包 + SDK 机读 + 官方文档检索）、可选官方 DevEco CLI 构建/签名/模拟器控制。
与 hdc_mcp 等 MCP 服务器的分工是：后者覆盖 hdc 能力层；本插件的价值在 DSH 原生层——会话内工具卡片与 read_image 闭环、按调用会话解析沙箱策略、结构化失败上报，以及 v0.7 起按官方 client 插件形态集成的设备面板。
核心功能¶
设备闭环调试¶
插件提供 20 个工具，覆盖从发现设备到验证 UI 的完整链路。约定上，所有工具失败不抛异常，统一返回 { ok: false, error, hint }；成功返回带 ok: true 的结果对象。
设备相关工具包括：
| 工具 | 说明 |
|---|---|
hdc_list_targets |
列出已连接设备/模拟器 |
hdc_connect |
hdc tconn（严格 host:port 校验） |
hdc_shell |
设备 shell |
hdc_screenshot |
截图 → 拉取 JPEG → 落盘校验 |
hdc_install |
安装 .hap |
hdc_hilog |
hilog 尾部 N 行 |
hdc_ui_dump |
文本化 UI 快照 |
hdc_ui_find |
按文本/hint 找控件 |
hdc_ui |
tap / swipe / input / key 等 UI 操作 |
hdc_app |
应用 query / start / stop / clear-data / uninstall |
hdc_crash |
崩溃抓取与结构化摘要 |
hdc_diag |
hdc 路径、策略解析等诊断 |
截图默认写入 <workspace>/.dsh-hdc/screenshots/。工具默认使用本会话上次使用的设备；掉线时自动回退首台连接设备。
设备面板¶
v0.7 起，面板按官方 client 插件形态集成：左侧边栏「鸿蒙」入口，点击后在右上角打开浮动面板（可拖拽、缩放、收起）。面板展示设备列表（型号/API/电池）、一键截图、hilog 尾部、系统区、工具链徽章；主题走官方 --dsw-alias-* token，随深浅色自适应。面板打开时 8s/20s 轮询，关闭后降为 60s 慢轮询。
官方知识层¶
知识能力分三层：
- Tier-1 离线随包（
hms_knowledge）：28 篇 OpenHarmony 官方文档节选（CC-BY-4.0），约 1.7MB，无需 SDK/CLI/网络，支持 catalog / read / search。 - SDK 机读（
hms_api）：读本机 SDK.d.ts，按@since/@deprecated/@syscap精确到 API 版本分类。 - Tier-2 全量文档（
hms_docs）：需本机安装@deveco/deveco-cli，通过devecocli docs检索。
此外还有 hms_api_change（跨版本破坏性变更扫描）、hms_lint（官方 codelinter 规则索引与检查）。
构建、签名与模拟器¶
hms_build 提供官方构建/签名/运行通道：status / build / run / sign / clean。@deveco/deveco-cli 不随插件安装；未装时自动回退本机 hvigorw + hdc_install + hdc_app 闭环。
hms_emulator 通过 devecocli 控制模拟器：list / start / stop / create / delete，以及 shake / power / rotate / volume / fold / battery / geolocation / sensor / scene 等状态注入。
hms_setup 做环境体检：hdc / DevEco Studio / SDK / devecocli / 设备五项，并解析目标 API 版本三源（项目→设备→SDK）不一致告警。
安装、应用、构建失败时，插件对 11 条已知错误码附中文修复建议（如 9568332 签名未绑 UDID、1300002 空间不足）。
运行时技能¶
插件附带三个运行时技能，模型按需加载：
hdc-bridge：设备闭环用法deveco-cli：官方 SKILL.md 改写（MIT 声明保留）harmonyos-knowledge：知识层纪律（官方优先、版本化、许可合规）
安装与启用¶
本包零 npm 依赖，纯 JS、无构建步骤。安装命令如下：
# npm 安装
dsh plugin --profile <name> add dsh-hdc-bridge
# 或直接从 GitHub 安装
dsh plugin --profile <name> add github:1na-ko/dsh-hdc-bridge
验证组合层并启动：
dsh --profile <name> --dump-config # 确认出现 dsh-hdc-bridge 层
dsh --profile <name>
环境要求¶
- HarmonyOS 设备或模拟器；真机需开发者模式 + USB 调试。
hdc二进制自动探测：DevEco Studio 常见 SDK 路径 → PATH。- 截图查看需图像输入模型；纯文本模型可用
hdc_ui_dump做文本化 UI 检查。 - 可选后端
@deveco/deveco-cli需自行npm i -g @deveco/deveco-cli（DevEco Studio ≥ 6.1.0，macOS/Windows，Node ≥ 18）；签名前需一次devecocli auth login。 hms_knowledge的 Tier-1 知识随包内置，离线可用。
典型用法¶
设备调试闭环¶
- 用
hdc_list_targets确认设备在线。 - 用
hdc_screenshot截图，配合read_image查看界面。 - 用
hdc_ui_dump获取布局文本，或hdc_ui_find定位控件坐标。 - 用
hdc_ui执行 tap / input 等操作，再 dump 验证。 - 用
hdc_install装包，hdc_app启动应用，hdc_hilog看日志。
查 API 与文档¶
无网络或未装 DevEco CLI 时，先用 hms_knowledge 的 catalog 列目录，再 read 按小节读取。装了 Studio 后，用 hms_api 读本机 SDK 声明；装了 devecocli 后，用 hms_docs 检索全量官方文档。
构建与运行¶
# 模型侧调用 hms_build
# status → build → run
# devecocli 缺失时自动走 hvigorw 降级路径
适用场景与注意¶
适合谁：
- 在 DSH 里做 HarmonyOS / OpenHarmony 应用开发的智能体用户。
- 需要设备截图、UI 操作、装包验证闭环，又不想自建 MCP 桥接的人。
- 希望离线查阅官方 API 节选，或按需读本机 SDK 声明的开发者。
注意事项：
- 插件以当前
dsh进程权限运行，安装前应检查源码与 MIT 许可证。 snapshot_display仅支持.jpeg（API 10+）。- 真机安装需签名 profile 绑定设备 UDID，否则报
9568332。 hdc客户端对远端失败可能仍返回退出码 0，插件以输出标记 + 落盘校验兜底。- UI 输入实战经验：混合字符串注入时 IME 模式切换可能吞字符，建议分段输入 + dump 校验；软键盘会改变布局，每次操作前用最新坐标。
- devecocli 的 build/run/sign 在受限沙箱中可能报 EPERM，需按指引在沙箱外执行。
- macOS 实机验证尚在路线图中，尚未完成。
可选知识搭配：社区包 harmony-next.skills 不随包，用户自行 npx skills add linhay/harmony-next.skills。
链接¶
- 社区目录：https://www.skillhub.cn/plugins/1na-ko/dsh-hdc-bridge
- GitHub 仓库：https://github.com/1na-ko/dsh-hdc-bridge
社区目录是独立站点，与 DeepSeek / 幻方无官方从属关系。DSH 生态理念是「一切皆插件」，dsh-hdc-bridge 把鸿蒙开发的设备层、知识层和构建层收进一个客户端插件，适合在 DSH 会话里直接跑通「看设备 → 改码 → 装包 → 验证」的闭环。
