前言¶
在 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 會話裏直接跑通「看設備 → 改碼 → 裝包 → 驗證」的閉環。
