dsh-plugin-devecocli

Readme

# dsh-plugin-devecocli

> HarmonyOS development tools for [DeepSeek Harness](https://github.com/deepseek-ai/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:

```sh
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`](./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](./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 / 开发

```sh
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](./LICENSE).