鸿蒙开发工具集 frankq007/dsh-plugin-devecocli

dsh-plugin-devecocli

面向 DeepSeek Harness 的 HarmonyOS 开发工具，由 devecocli CLI（@deveco/deveco-cli）提供支持。注册 13 个 harmony_ 模型工具：设备/模拟器管理、截图与 UI 自动化、构建与部署、日志、lint、签名与离线 HarmonyOS 文档。

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

Features / 工具清单（13 个）

| 工具 | 用途 | devecocli 命令 |
| harmony_device_list | 列出已连接的设备/模拟器 | device list --format json |
| harmony_emulator_list | 列出模拟器实例及状态 | emulator list --format json |
| harmony_emulator_control | start/stop/shake/power/rotate/volume/battery/geolocation/sensor/scene/fold | emulator ... |
| harmony_screenshot | 截取设备屏幕为 PNG | ui screenshot --path |
| harmony_ui_dump | 导出屏幕上的 UI 节点树 | ui layout --format json |
| harmony_ui_interact | click/doubleclick/longclick/swipe/fling/drag/text | ui ... |
| harmony_log | 设备应用日志（level/bundle/keyword/crash） | log --... |
| harmony_build | 构建项目（可选先 clean） | build [clean] |
| harmony_deploy | 部署到设备（默认 --skip-build 快速安装） | run |
| harmony_signature | 生成签名材料到项目中 | signature generate |
| harmony_check_lint | DevEco Code Linter（可选 --fix） | check lint |
| harmony_docs | 离线 HarmonyOS 文档搜索 | docs search |
| harmony_exec | 任意 devecocli 子命令的逃生通道（白名单） | 任意 |

Requirements / 前置要求

- DeepSeek Harness (dsh) — 任意 profile
- devecocli 在 PATH 中（通过 DevEco Studio 安装，或 npm i -g @deveco/deveco-cli）
- 已连接 HarmonyOS 模拟器/设备（用于设备工具）
- 设备/SDK 命令需要 完全访问会话（见下方 Sandbox）

Install / 安装

方案 A — bundle（推荐，持久化）

作为 Cordis bundle 安装到任意 profile：

dsh plugin --profile add dsh-plugin-devecocli
or from git / tarball / local checkout:
dsh plugin --profile add github:/dsh-plugin-devecocli
dsh plugin --profile add ./dsh-plugin-devecocli-0.1.0.tgz

重启你的 DSH profile。这 13 个 harmony_ 工具将对该 profile 中的每个 agent 可用。
使用 dsh plugin --profile remove dsh-plugin-devecocli 卸载。

对于 git 安装，pnpm ≥10 需要授权 prepare 脚本 — 将 pnpm 打印的确切 package key 复制到该 profile 的 pnpm-workspace.yaml 的 allowBuilds 中，然后重新运行 add。

方案 B — 动态插件（无需安装，会话本地）

在 creator-mode (cordis) 会话中，于运行时注册该插件：

1. cordis_inspect_list → cordis_inspect_query（确认 Host shell 服务和 harness API）
2. 使用 code.host = code.host.js 的内容执行 cordis_define
3. cordis_run（如提示，在 UI 中批准）动态插件是进程本地的：DSH 重启后它们就会消失。code.host.js 是用于重新安装的持久化源文件。参见 code.host.js。

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

在 dsh-web creator-mode 会话（deve-1/pkg-4，13 个工具）上执行。

| # | 检查项 | 结果 |
| T1 | 插件激活 | ✅ 3 次激活成功，deve-1/pkg-4 运行中 |
| T2 | harmony_device_list | ✅ [{"name":"dcode_api24","serial":"127.0.0.1:5555","kind":"emulator","deviceType":"phone"}] |
| T3 | harmony_screenshot | ✅ 生成 132032 字节的 PNG |
| T4 | harmony_ui_dump | ✅ 返回带 bounds 的真实 UI 树 |
| T5 | harmony_exec 回退 | ✅ 输出与 T2 相同 |
| T6 | 错误路径（未登录） | ✅ 结构化错误：Run devecocli auth login to sign in. |
| T7 | 生命周期 stop/run | ✅ 停止时工具消失，运行时恢复 |
| T8 | 源文件已持久化 | ✅ code.host.js + README |
| T9 | harmony_check_lint | ✅ 10 个警告 / 0 个错误 |

额外：harmony_exec ["--version"] → 1.2.2；harmony_docs search arkts → 3 条 JSON 结果。
Bundle 层已在本地验证：dsh --profile --dump-config 显示 dsh-plugin-devecocli 层，其中包含行 devecocli-tools。

Sandbox / 沙箱注意事项

- 受限沙箱（workspace-write）：devecocli 可以启动（--version、auth status、 docs search 可用），但设备/SDK 命令会被拒绝： The executable is not digitally signed: ...\hdc.exe。插件会检测到这一点并返回提示。受限沙箱下仅文档/认证/版本类命令可用。
- 完整访问会话（danger-full-access）：所有设备/SDK 命令均可用（T2–T5、T9）。
需要完整权限会话才能发挥全部能力。
- 未登录华为开发者账号 → harmony_signature 会失败并给出清晰提示；请运行 devecocli auth login（交互式，不适合通过工具执行）。

Development / 开发

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

Known limits / 已知限制

- Bundle 工具注册在 profile 层；creator-mode 动态副本可共存且不会冲突（作用域层不同）。
- ui layout 完整输出可能达数百 KB —— 工具返回截断的尾部（64KB）+ JSON 摘要。
- 构建是长时间运行的（数分钟）—— 单次执行有超时限制，返回尾部输出。
- 交互式命令（auth login、emulator license）不适合通过工具执行。

License

MIT —— 参见 LICENSE。