@deveco-test/hmos-deveco-cli 0.3.0-TD.2.3 → 0.3.0-TD.2.4

package/SKILL.md

@@ -69,10 +69,13 @@ Build, install, and launch.
   - **Prereq**: run `devecocli run` once first (full build + deploy + generates the `buildConfig.json` cache that `--apply` reuses).
   - **If changes don't take effect**: check `<module>/build/config/buildConfig.json` has content — empty/missing means `devecocli run` wasn't run; on any apply failure, fall back to a full `devecocli run`.
 *Ex*: `devecocli run` → edit code → write `.hvigor/changes.txt` → `devecocli run --apply changes.txt`
-- **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.
+- **Previewer mode**: Pass a product name to `--device` to launch the DevEco Studio previewer. If `--device` matches a connected real device (name or serial), it takes priority over previewer mode — check device names with `devecocli device list`.
+  - Single Previewer: `devecocli run --device "Pura 90 Pro"`
+  - Multi Previewer: `devecocli run --device "Pura 90 Pro,MatePad 11.5'S"`
+  - Prerequisites:
+    1. Device connected: enable wireless debugging (Settings → System → Developer options → Wireless debugging) and run `hdc tconn 127.0.0.1:<port>` (or set `DEVECO_HDC_PORT=<port>` env var).
+    2. DevEco Studio running (CLI throws if not — does NOT auto-start).
+  - Supported products: `Pura 90 Pro`, `MatePad 11.5'S`, `Mate X7`, `Pura X`, `Mate XT`. Aliases: `phone`, `pad`/`tablet`, `fold`/`foldable`.
 
 ### `devecocli signature generate` `[Outside sandbox]`
 Auto-generate HarmonyOS signing materials (local p12/csr + cloud cert + test profile) and write signing config to `build-profile.json5`.
@@ -161,11 +164,7 @@ Manage HarmonyOS skills in AI agents/projects.
 
 - **Fresh checkout to real device**:
   `devecocli build` -> `devecocli device list` -> `devecocli run --device <serial>`
-- **Launch previewer for current project** (instead of `deveco preview`):
-  - 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
+- **Launch previewer**: `devecocli run --device "Pura 90 Pro"` (single) or `devecocli run --device "Pura 90 Pro,Mate XT"` (multi).
 - **Diagnose crash**:
   `devecocli log --crash --bundle-name <bundle>`
 - **Release build**:
@@ -184,4 +183,4 @@ Manage HarmonyOS skills in AI agents/projects.
 - **`Invalid AccessToken. Sign in and try again`**: Token expired. Run `devecocli auth login` again.
 - **`skills add` agent not found**: Valid: `codebuddy`, `cursor`, `opencode`, `qoder`, `trae-cn`.
 - **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.
+- **Previewer — "DevEco Studio is not running"**: Tell the user to start DevEco Studio manually first, then retry. Do NOT retry automatically.