@deveco-test/hmos-deveco-cli 0.1.0-TD.5.2 → 0.2.0

package/SKILL.md

@@ -9,7 +9,7 @@ description: >-
 `devecocli` wraps DevEco Studio's `hvigor`, `ohpm`, `hdc`, emulator toolchain, and HarmonyOS-skills installer. **Prefer `devecocli` over invoking underlying tools directly.**
 
 **Do NOT use these legacy commands** — use the `devecocli` equivalent instead:
-- ❌ `deveco preview` / `hvigorw preview` → ✅ `devecocli run --preview` (launches DevEco Studio previewer)
+- ❌ `deveco preview` / `hvigorw preview` → ✅ `devecocli run --device <product-name>` (launches DevEco Studio previewer; product name in `--device` triggers previewer mode)
 - ❌ `hvigorw` directly → ✅ `devecocli build`
 - ❌ `hdc` directly (when a `devecocli` wrapper exists) → ✅ `devecocli device` / `devecocli log` / `devecocli run`
 
@@ -65,12 +65,10 @@ Build, install, and launch.
 - `--ability <ability>`: Default from `module.json5`.
 - `--uninstall`: Uninstall existing app first (Fixes signing key issues).
 - `--skip-build`: Deploy existing artifacts.
-- `--preview`: Launch the DevEco Studio **previewer** instead of installing/running the app. Ensures the DevEco Studio desktop process is running first (throws immediately if not — does NOT auto-start Studio on any platform), then `hdc shell aa start -a DevEcoViewerAbility -b com.huawei.devecostudio -m DevEcoViewer --pi instanceId <pid> --ps paramJson <JSON with double-quotes escaped>` with project info (`bundleName` / `abilityName` / `moduleName` / `productName` / `productType` / `subProductType` / `instanceId` / `launchDeviceIndex` / `launchFlag` / `isCustom` / `nativeDebuggable` / `appDebuggable`). `instanceId` = CLI process.pid (identifies which IDE launched); `launchDeviceIndex` = -1 for single previewer, 0-based for multi. Skips build/install. **Cross-platform**:
-  - **Windows/macOS**: uses DevEco Studio's bundled hdc, auto-detects Studio install path via ToolProvider.
-  - **HarmonyOS native (2in1 PC)**: hdc does NOT auto-discover the local device — self-connect required. Resolution chain for the target port: `--device 127.0.0.1:<port>` (or bare port) → `DEVECO_HDC_PORT` env var → existing `hdc list targets` → interactive prompt → error. DevEco Studio is a system app there (no launcher script, `hap` under `/data/app/el1/bundle/public/com.huawei.devecostudio/`); local `pgrep` cannot see Studio's process due to UID isolation (currentUser 20020102 vs Studio 20020176), so the CLI detects Studio via `hdc shell ps -ef | grep com.huawei.devecostudio` (hdcd runs as root, can see all UIDs) — this requires the hdc self-connect to be established first, so on HarmonyOS the device selection step runs before IDE detection. The CLI does NOT auto-start Studio on any platform — if Studio is not detected, `--preview` throws immediately and the user must start DevEco Studio manually.
-- `--count <n>` (Previewer only, mutually exclusive with `--devices`): Launch N previewer windows by list order (multi-previewer mode). Each device type at most one window.
-- `--devices <names>` (Previewer only, mutually exclusive with `--count`): Launch specified device types, comma-separated (e.g. `"Pura 90 Pro,MatePad 11.5'S"`). Supported: `Pura 90 Pro`, `MatePad 11.5'S`, `Mate X7`, `Pura X`, `Mate XT`. Single name → single previewer of that type. **Smart matching**: case/whitespace/punctuation insensitive; accepts aliases (`phone`, `tablet`/`pad`, `fold`/`foldable`, `widefold`/`wide`, `triplefold`/`triple`) and short forms (`pura90`, `matepad`, `matex7`, `purax`, `matext`); substring match and Levenshtein distance ≤ 2 auto-correction are applied as fallback. Ambiguous matches report candidates.
-- **Agent hint**: After a successful single-preview launch where the user did NOT specify device type or count (i.e. bare `devecocli run --preview`), briefly inform the user in natural language that they can try specifying a device type to preview, and that they can also try launching multiple different device previewers at once. Do NOT mention specific CLI flags (like `--devices` or `--count`) or print command examples — keep it conversational. Do NOT print this hint if the user already specified device type or count.
+- **Previewer mode** (auto-detected from `--device`): When `--device` value matches previewer product names (e.g. `"Pura 90 Pro"`, `"MatePad 11.5'S"`, `phone`, `pad`), the CLI launches the DevEco Studio **previewer** instead of installing/running the app. Comma-separated names → multi-previewer (count = list length). When `--device` is a serial/IP:port/unmatched value, normal run mode is used. Omitting `--device` → normal run. Ensures the DevEco Studio desktop process is running first (throws immediately if not — does NOT auto-start Studio on any platform), then `hdc shell aa start -a DevEcoViewerAbility -b com.huawei.devecostudio -m DevEcoViewer --pi instanceId <pid> --ps paramJson <JSON with double-quotes escaped>` with project info (`bundleName` / `abilityName` / `moduleName` / `productName` / `productType` / `subProductType` / `instanceId` / `launchDeviceIndex` / `launchFlag` / `isCustom` / `nativeDebuggable` / `appDebuggable`). `instanceId` = CLI process.pid; `launchDeviceIndex` = -1 for single previewer, 0-based for multi. Skips build/install (except multi-previewer needs build+install with multiAppMode). **Smart matching**: case/whitespace/punctuation insensitive; accepts aliases (`phone`, `tablet`/`pad`, `fold`/`foldable`, `widefold`/`wide`, `triplefold`/`triple`) and short forms; substring match and Levenshtein ≤ 2 fallback. Ambiguous matches report candidates. Supported products: `Pura 90 Pro`, `MatePad 11.5'S`, `Mate X7`, `Pura X`, `Mate XT`.
+  - **Windows/macOS**: uses DevEco Studio's bundled hdc, auto-detects Studio install path via ToolProvider. hdc target device is auto-selected via `selectDevice` (previewer mode does not use `--device` as hdc target).
+  - **HarmonyOS native (2in1 PC)**: hdc does NOT auto-discover the local device — self-connect required. In previewer mode, `--device` is the product name (not hdc target). The CLI checks `hdc list targets` for a `127.0.0.1:<port>` entry: if found, uses it directly; if not found, warns `hdc 未自联` and fallbacks to `connectLocalDevice` (resolution: `DEVECO_HDC_PORT` env var → existing `hdc list targets` → interactive prompt → error). DevEco Studio is a system app there; local `pgrep` cannot see Studio's process due to UID isolation, so the CLI detects Studio via `hdc shell ps -ef | grep com.huawei.devecostudio` (hdcd runs as root) — requires hdc self-connect first. The CLI does NOT auto-start Studio on any platform.
+- **Agent hint**: After a successful single-preview launch where the user specified only one device type, briefly inform the user in natural language that they can try launching multiple different device previewers at once by comma-separating product names in `--device`. Do NOT print command examples — keep it conversational. Do NOT print this hint if the user already launched multi-preview.
 
 ### `devecocli log`
 Fetch hilog or crash logs. Req `--device <name|serial>` on multi-device hosts.
@@ -110,12 +108,10 @@ Manage HarmonyOS skills in AI agents/projects.
 - **Fresh checkout to emulator**:
   `devecocli build` -> `devecocli emulator list` -> `devecocli emulator start "Name"` -> `devecocli run`
 - **Launch previewer for current project** (instead of `deveco preview`):
-  - Single previewer (default first device in list): `devecocli run --preview`
-  - Single previewer, specific device type: `devecocli run --preview --devices "MatePad 11.5'S"`
-  - Multi-preview by count: `devecocli run --preview --count 2`
-  - Multi-preview by device types: `devecocli run --preview --devices "Pura 90 Pro,Mate XT"`
-  - On HarmonyOS native PC: ensure wireless debugging is on, then `devecocli run --preview` will self-connect (or pass `--device 127.0.0.1:<port>`)
-  - `--count` and `--devices` are mutually exclusive
+  - Single previewer (specific device type): `devecocli run --module entry --device "Pura 90 Pro"`
+  - Multi-preview by device types: `devecocli run --module entry --device "Pura 90 Pro,Mate XT"`
+  - On HarmonyOS native PC: set `DEVECO_HDC_PORT=<port>` env var before running (previewer mode uses `--device` for product name, not hdc target)
+  - Previewer mode is auto-detected: `--device` value matching product names → previewer; serial/IP:port → normal run
 - **Diagnose crash**:
   `devecocli log --crash --bundle-name <bundle>`
 - **Release build**:
@@ -132,5 +128,5 @@ Manage HarmonyOS skills in AI agents/projects.
 - **`image download` failure / timeout**: Do NOT auto-retry. Give the command to the user to run manually in their terminal.
 - **`emulator create` timeout**: Treat as user-action step. Ask user to open DevEco Studio -> Device Manager. Check `emulator list` after user confirms. Do NOT auto-retry or edit SDK files.
 - **`image list` duplicate OS rows**: `phone`/`foldable`/`widefold`/`triplefold` share the same image. Download/remove ONCE per OS version.
-- **HarmonyOS native (2in1 PC) — `hdc list targets` shows `[Empty]`**: hdc on HarmonyOS does NOT auto-discover the local device. Open "Settings → System → Developer options → Wireless debugging", note the port, then `hdc tconn 127.0.0.1:<port>`. Or pass `--device 127.0.0.1:<port>` / set `DEVECO_HDC_PORT` to let `run --preview` self-connect.
-- **`run --preview` — "DevEco Studio is not running"**: The previewer's rendering depends on the DevEco Studio desktop process. If the CLI returns this error, do NOT retry. Use natural language to tell the user: "预览器需要 DevEco Studio 处于运行状态,请先手动启动 DevEco Studio,启动后再重试此命令。" On HarmonyOS PC, also remind the user that process detection may be limited by UID isolation (currentUser cannot see Studio's process), but if the CLI reports this error it means detection genuinely failed.
+- **HarmonyOS native (2in1 PC) — `hdc list targets` shows `[Empty]`**: hdc on HarmonyOS does NOT auto-discover the local device. Open "Settings → System → Developer options → Wireless debugging", note the port, then `hdc tconn 127.0.0.1:<port>`. For normal run: pass `--device 127.0.0.1:<port>`. For previewer mode: set `DEVECO_HDC_PORT=<port>` env var (previewer mode uses `--device` for product name, not hdc target).
+- **Previewer mode — "DevEco Studio is not running"**: The previewer's rendering depends on the DevEco Studio desktop process. If the CLI returns this error, do NOT retry. Use natural language to tell the user: "预览器需要 DevEco Studio 处于运行状态,请先手动启动 DevEco Studio,启动后再重试此命令。" On HarmonyOS PC, also remind the user that process detection may be limited by UID isolation (currentUser cannot see Studio's process), but if the CLI reports this error it means detection genuinely failed.