Preface¶

When developing for HarmonyOS in DSH, common practices involve connecting an MCP server to expose hdc capabilities or having the model answer API questions based on memory. The former can connect to devices but lacks DSH’s native tool cards, screenshot closed-loop, and session-level sandbox policies; the latter is prone to errors due to version differences and offline scenarios.

dsh-hdc-bridge takes a different approach: instead of rewriting the hdc protocol, it directly reuses the local hdc binary (3.x), encapsulating device debugging, official knowledge layers, and optional DevEco CLI build channels into a DSH client plugin. Below, we introduce its positioning, capabilities, and installation and usage.

What Is This¶

dsh-hdc-bridge is published by maintainer 1na-ko, classified as a client plugin, currently at version 0.7.3 under the MIT license. The GitHub repository has 14 stars.

In one sentence: DSH’s native HarmonyOS development assistant — hdc device closed-loop debugging, official-first versioned knowledge layer (offline Tier-1 bundled with package + SDK machine-readable + official documentation retrieval), optional official DevEco CLI build/signature/emulator control.

The division of labor with MCP servers like hdc_mcp is: the latter covers the hdc capability layer; the value of this plugin lies in the DSH native layer — tool cards within the session and read_image closed-loop, sandbox policy parsed per calling session, structured failure reporting, and starting from v0.7, device panel integrated in the form of an official client plugin.

Core Features¶

Device Closed-Loop Debugging¶

The plugin provides 20 tools, covering the complete chain from device discovery to UI verification. By convention, all tools do not throw exceptions on failure; they uniformly return { ok: false, error, hint }. On success, they return a result object with ok: true.

Device-related tools include:

Screenshots are written by default to <workspace>/.dsh-hdc/screenshots/. Tools use the device from the current session by default; on disconnection, they automatically fall back to the first connected device.

Device Panel¶

Starting from v0.7, the panel is integrated as an official client plugin: the left sidebar has a “HarmonyOS” entry, which opens a floating panel (draggable, resizable, collapsible) in the top right corner when clicked. The panel displays device list (model/API/battery), one-click screenshot, hilog tail, system area, and toolchain badges; the theme uses official --dsw-alias-* tokens and adapts to light/dark modes. When the panel is open, it polls every 8s/20s; when closed, it reduces to a 60s slow poll.

Official Knowledge Layer¶

The knowledge capabilities are divided into three layers:

1. Tier-1 Offline Bundled (hms_knowledge): 28 excerpts from OpenHarmony official documentation (CC-BY-4.0), approximately 1.7MB, no SDK/CLI/network required, supporting catalog / read / search.
2. SDK Machine-Readable (hms_api): Reads local SDK .d.ts files, precisely classified by API version based on @since/@deprecated/@syscap.
3. Tier-2 Full Documentation (hms_docs): Requires local installation of @deveco/deveco-cli, searchable via devecocli docs.

Additionally, there are hms_api_change (cross-version breaking change scanning) and hms_lint (official codelinter rule indexing and checking).

Build, Signature, and Emulator¶

hms_build provides official build/signature/run channels: status / build / run / sign / clean. @deveco/deveco-cli is not bundled with the plugin; when not installed, it automatically falls back to local hvigorw + hdc_install + hdc_app closed-loop.

hms_emulator controls the emulator via devecocli: list / start / stop / create / delete, as well as state injection like shake / power / rotate / volume / fold / battery / geolocation / sensor / scene.

hms_setup performs environment checks: hdc / DevEco Studio / SDK / devecocli / device, and parses target API version three sources (project→device→SDK) for inconsistency warnings.

For installation, application, and build failures, the plugin provides Chinese repair suggestions for 11 known error codes (e.g., 9568332 signature not bound to UDID, 1300002 insufficient space).

Runtime Skills¶

The plugin comes with three runtime skills, loaded by the model on demand:

• hdc-bridge: Device closed-loop usage
• deveco-cli: Rewritten official SKILL.md (MIT declaration retained)
• harmonyos-knowledge: Knowledge layer discipline (official-first, versioned, license compliant)

Installation and Enablement¶

This package has zero npm dependencies, is pure JS, and has no build steps. Installation commands are as follows:

# npm installation
dsh plugin --profile <name> add dsh-hdc-bridge

# Or install directly from GitHub
dsh plugin --profile <name> add github:1na-ko/dsh-hdc-bridge

Verify the combined layer and start:

dsh --profile <name> --dump-config   # Confirm the dsh-hdc-bridge layer appears
dsh --profile <name>

Environment Requirements¶

• HarmonyOS device or emulator; for real devices, developer mode + USB debugging is required.
• hdc binary auto-detection: Common SDK paths in DevEco Studio → PATH.
• Screenshot viewing requires an image input model; pure text models can use hdc_ui_dump for text-based UI checks.
• Optional backend @deveco/deveco-cli requires manual installation via npm i -g @deveco/deveco-cli (DevEco Studio ≥ 6.1.0, macOS/Windows, Node ≥ 18); before signing, a one-time devecocli auth login is needed.
• hms_knowledge Tier-1 knowledge is bundled offline and available without network.

Typical Usage¶

Device Debugging Closed-Loop¶

1. Use hdc_list_targets to confirm the device is online.
2. Use hdc_screenshot to take a screenshot and view the interface with read_image.
3. Use hdc_ui_dump to get layout text, or hdc_ui_find to locate control coordinates.
4. Use hdc_ui to perform tap / input operations, then dump to verify.
5. Use hdc_install to install packages, hdc_app to launch applications, and hdc_hilog to view logs.

Querying APIs and Documentation¶

Without network or without DevEco CLI installed, first use hms_knowledge catalog to list directories, then read by section. After installing Studio, use hms_api to read local SDK declarations; after installing devecocli, use hms_docs to search the full official documentation.

Build and Run¶

# Model-side call to hms_build
# status → build → run
# Automatically falls back to hvigorw path when devecocli is missing

Use Cases and Notes¶

Who It’s For:

• Intelligent agent users developing HarmonyOS / OpenHarmony applications in DSH.
• Those needing device screenshots, UI operations, installation verification closed-loop, but don’t want to build their own MCP bridge.
• Developers who want to consult official API excerpts offline or read local SDK declarations as needed.

Notes:

• The plugin runs with the current dsh process permissions; check the source code and MIT license before installation.
• snapshot_display only supports .jpeg (API 10+).
• Real device installation requires a signature profile bound to the device UDID, otherwise error 9568332 occurs.
• The hdc client may still return exit code 0 for remote failures; the plugin uses output marking + disk verification as a safeguard.
• Practical experience with UI input: IME mode switching may swallow characters during mixed string injection; it’s recommended to input in segments + dump verification; soft keyboards change layout, so use the latest coordinates before each operation.
• devecocli’s build/run/sign may report EPERM in restricted sandboxes; follow instructions to execute outside the sandbox.
• macOS real device verification is still on the roadmap and not yet completed.

Optional knowledge pairing: The community package harmony-next.skills is not bundled; users can install it themselves via npx skills add linhay/harmony-next.skills.

Links¶

• Community Directory: https://www.skillhub.cn/plugins/1na-ko/dsh-hdc-bridge
• GitHub Repository: https://github.com/1na-ko/dsh-hdc-bridge

The community directory is an independent site with no official affiliation with DeepSeek / High-Flyer. The DSH ecosystem philosophy is “everything is a plugin,” and dsh-hdc-bridge integrates the device layer, knowledge layer, and build layer of HarmonyOS development into a single client plugin, suitable for running the closed-loop “view device → modify code → install package → verify” directly within DSH sessions.