dsh-plugin-devecocli

HarmonyOS development tools for DeepSeek Harness,
backed by the devecocli CLI (@deveco/deveco-cli). Registers 13 harmony_* model tools:
device/emulator management, screen capture & UI automation, build & deploy, logs, lint,
signing and offline HarmonyOS docs.

让 DSH 掌握鸿蒙开发能力：设备/模拟器管理、截图与 UI 自动化、构建部署、日志诊断、Lint、签名与本地文档检索。

Features / 工具清单（13 个）

Tool	Purpose	devecocli command
harmony_device_list	List connected devices/emulators	device list --format json
harmony_emulator_list	List emulator instances & status	emulator list --format json
harmony_emulator_control	start/stop/shake/power/rotate/volume/battery/geolocation/sensor/scene/fold	emulator <action> ...
harmony_screenshot	Capture device screen to PNG	ui screenshot --path
harmony_ui_dump	Dump on-screen UI node tree	ui layout --format json
harmony_ui_interact	click/doubleclick/longclick/swipe/fling/drag/text	ui <gesture> ...
harmony_log	Device app logs (level/bundle/keyword/crash)	log --...
harmony_build	Build project (optional clean first)	build [clean]
harmony_deploy	Deploy to device (default --skip-build fast install)	run
harmony_signature	Generate signing materials into project	signature generate
harmony_check_lint	DevEco Code Linter (optional --fix)	check lint
harmony_docs	Offline HarmonyOS doc search	docs search
harmony_exec	Escape hatch for any devecocli subcommand (whitelisted)	any

Requirements / 前置要求

• DeepSeek Harness (dsh) — any profile
• devecocli on PATH (install via DevEco Studio or npm i -g @deveco/deveco-cli)
• HarmonyOS emulator/device connected (for device tools)
• Full-access session for device/SDK commands (see Sandbox below)

Install / 安装

Option A — bundle (recommended, persistent)

Install into any profile as a Cordis bundle:

dsh plugin --profile <name> add dsh-plugin-devecocli
# or from git / tarball / local checkout:
dsh plugin --profile <name> add github:<owner>/dsh-plugin-devecocli
dsh plugin --profile <name> add ./dsh-plugin-devecocli-0.1.0.tgz

Restart your DSH profile. The 13 harmony_* tools become available to every agent
in that profile. Remove with dsh plugin --profile <name> remove dsh-plugin-devecocli.

For git installs, pnpm ≥10 requires authorizing the prepare script — copy the exact
package key pnpm prints into the profile's pnpm-workspace.yaml allowBuilds, then
re-run add.

Option B — dynamic plugin (no install, session-local)

In a creator-mode (cordis) session, register the plugin at runtime:

1. cordis_inspect_list → cordis_inspect_query (confirm Host shell service and harness API)
2. cordis_define with code.host = body of code.host.js
3. cordis_run (approve in UI if prompted)

Dynamic plugins are process-local: they disappear when DSH restarts. code.host.js
is the persisted source for re-install. See code.host.js.

Verification / 实测验证（T1–T9 PASS）

Executed on dsh-web creator-mode session (deve-1/pkg-4, 13 tools).

#	Check	Result
T1	Plugin activation	✅ 3 activations OK, deve-1/pkg-4 running
T2	harmony_device_list	✅ [{"name":"dcode_api24","serial":"127.0.0.1:5555","kind":"emulator","deviceType":"phone"}]
T3	harmony_screenshot	✅ 132032-byte PNG produced
T4	harmony_ui_dump	✅ real UI tree with bounds returned
T5	harmony_exec fallback	✅ same output as T2
T6	Error path (not logged in)	✅ structured error: Run devecocli auth login to sign in.
T7	Lifecycle stop/run	✅ tools disappear on stop, restored on run
T8	Source persisted	✅ code.host.js + README
T9	harmony_check_lint	✅ 10 warnings / 0 errors

Extra: harmony_exec ["--version"] → 1.2.2; harmony_docs search arkts → 3 JSON results.
Bundle layer verified locally: dsh --profile <test> --dump-config shows the
dsh-plugin-devecocli layer with row devecocli-tools.

Sandbox / 沙箱注意事项

• Restricted sandbox (workspace-write): devecocli launches (--version, auth status,
  docs search work) but device/SDK commands are denied:
  The executable is not digitally signed: ...\hdc.exe. The plugin detects this and
  returns a hint. 受限沙箱下仅文档/认证/版本类命令可用。
• Full-access session (danger-full-access): all device/SDK commands work (T2–T5, T9).
  需要完整权限会话才能发挥全部能力。
• Not logged in to Huawei Developer account → harmony_signature fails with a clear
  hint; run devecocli auth login (interactive, not suitable via tools).

Development / 开发

node --check index.js        # syntax check
npm run check

Known limits / 已知限制

• Bundle tools register in the profile layer; a creator-mode dynamic copy coexists
  without conflicts (different scope layers).
• ui layout full output can be hundreds of KB — tools return truncated tail (64KB) + JSON summary.
• Builds are long-running (minutes) — single execution has a timeout, returns tail output.
• Interactive commands (auth login, emulator license) don't fit tool execution.

License

MIT — see LICENSE.