@deveco-test/hmos-deveco-cli 0.2.0 → 0.2.2

package/SKILL.md

@@ -1,19 +1,24 @@
 ---
 name: deveco-cli
 description: >-
-  **MUST** use 'devecocli' for HarmonyOS apps (scaffold, build, run, debug, devices, emulators, logs, docs, 鸿蒙开发文档, skills, multi-preview). **REQUIRED** and **MANDATORY** if workspace has build-profile.json5 or oh-package.json5, or user mentions HarmonyOS, 鸿蒙, DevEco, ArkTS, ArkUI, docs, 鸿蒙文档, 知识, 搜索, skills, or preview/预览/预览器/多预览器/多设备预览器.
+  **MUST** use 'devecocli' for HarmonyOS apps (scaffold, build, run, debug, devices, logs, docs, 鸿蒙开发文档, skills, multi-preview). **REQUIRED** and **MANDATORY** if workspace has build-profile.json5 or oh-package.json5, or user mentions HarmonyOS, 鸿蒙, DevEco, ArkTS, ArkUI, docs, 鸿蒙文档, 知识, 搜索, skills, or preview/预览/预览器/多预览器/多设备预览器.
 ---
 
 # DevEco CLI
 
-`devecocli` wraps DevEco Studio's `hvigor`, `ohpm`, `hdc`, emulator toolchain, and HarmonyOS-skills installer. **Prefer `devecocli` over invoking underlying tools directly.**
+`devecocli` wraps DevEco Studio's `hvigor`, `ohpm`, `hdc`, 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 --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`
 
-Available commands: `build`, `run`, `update`, `device`, `emulator`, `skills`, `log`, `create`, `init`, `serve`, `docs`.
+Available commands: `build`, `run`, `update`, `device`, `skills`, `log`, `create`, `init`, `serve`, `docs`.
+
+**Platform awareness**: On HarmonyOS native PC (2in1), **emulator commands are NOT available** and must never be suggested. The `emulator` command does not exist on this platform. When `device list` shows no devices, instead of suggesting emulator startup, tell the user to:
+1. Enable wireless debugging in Settings → System → Developer options → Wireless debugging
+2. Note the port number
+3. Run `hdc tconn 127.0.0.1:<port>`
 
 **Sandbox Rule**: Commands tagged `[Outside sandbox]` must be run outside the sandbox.
 
@@ -36,17 +41,6 @@ Compile and package project/modules. (Defaults: `--product default`, `--build-mo
 | Whole product bundle (.app) | `devecocli build --product <name>` |
 | Clean build outputs | `devecocli build clean` |
 
-### `devecocli emulator`
-Manage local emulator instances and system images.
-- `list`: Show instances (status, serial, device type).
-- `start <names...>`: Start instances. Quote names with spaces. (See Troubleshooting if blocked).
-- `stop <names...>`: Stop by name or serial (`127.0.0.1:<port>`).
-- `create <name>` (Req: `--device-type`, `--os-version`): Create instance. Optional: `--force`.
-- `delete <name>`: Delete instance.
-- `image list`: List downloaded images. Opts: `--device-type <type>`, `--all`, `--format <table|json>`.
-- `image download` / `image remove` (Req: `--device-type`, `--os-version`): Download/remove image. (Takes 30+ min, set long timeout).
-*Device types*: `phone`, `foldable`, `widefold`, `triplefold`, `tablet`, `2in1`, `2in1 foldable`, `wearable`, `tv`.
-
 ### `devecocli docs`
 Search/read local HarmonyOS docs.
 - `search <keywords...>`: Match any keyword. Opts: `--catalog <name>`, `--format <default|json>`, `--limit <n>`.
@@ -54,7 +48,7 @@ Search/read local HarmonyOS docs.
 - `catalog`: List available catalogs.
 
 ### `devecocli device`
-- `list`: Show active real devices and running emulators.
+- `list`: Show active real devices.
 - `view`: Detailed info. Req `-t <name|serial>` on multi-device hosts.
 
 ### `devecocli run` `[Outside sandbox]`
@@ -105,8 +99,8 @@ Manage HarmonyOS skills in AI agents/projects.
 
 ## Recipes
 
-- **Fresh checkout to emulator**:
-  `devecocli build` -> `devecocli emulator list` -> `devecocli emulator start "Name"` -> `devecocli run`
+- **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"`
@@ -121,12 +115,8 @@ Manage HarmonyOS skills in AI agents/projects.
 
 - **"Product / Build mode `<x>` not found"**: Check `build-profile.json5`.
 - **"Multiple entry modules" / "No entry module"**: Pass `--modules` (build) or `--module` (run).
-- **"No active devices" / "Multiple devices connected"**: Connect/start emulator. Pass `-t <serial>` (device view) or `--device <name|serial>` (run/log).
+- **"No active devices" / "Multiple devices connected"**: Connect a real device (or self-connect via wireless debugging on HarmonyOS native PC). Pass `-t <serial>` (device view) or `--device <name|serial>` (run/log).
 - **`error:install sign info inconsistent`**: Signing key changed. Run `devecocli run --uninstall`.
 - **`skills add` agent not found**: Valid: `codebuddy`, `cursor`, `opencode`, `qoder`, `trae-cn`.
-- **`emulator start` / `image download` blocked on agreement**: User MUST run `devecocli emulator license accept` in interactive TTY. Agents cannot do this. Do not retry until accepted.
-- **`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>`. 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.