@deveco-test/hmos-deveco-cli 0.3.0-TD.2-alpha2 → 0.3.0-TD.2

package/SKILL.md

@@ -1,172 +1,172 @@
----
-name: deveco-cli
-description: >-
-  **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`, 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`, `check`, `run`, `update`, `device`, `skills`, `log`, `create`, `init`, `serve`, `docs`, `auth`.
-
-**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.
-
-## 1. Code → Build → Deploy → Run → Debug
-
-### `devecocli create`
-Scaffold a new HarmonyOS project.
-- `--app-name <name>` (Req): 1–200 chars, `^[a-zA-Z][a-zA-Z0-9_]*$`
-- `--project-path <path>`: Auto-created if omitted (`./<app-name>`). Must be empty if exists.
-- `--bundle-name <bundle>`: Default `com.example.<appname-lowercase>`. 7–128 chars, ≥3 segments.
-- `--api-level <level>`: int ≥17 (default: auto or 23).
-*Ex*: `devecocli create --app-name MyApp --project-path ./CustomDir --api-level 23`
-
-### `devecocli build` `[Outside sandbox]`
-Compile and package project/modules. (Defaults: `--product default`, `--build-mode debug`)
-| Goal | Command |
-|---|---|
-| Single-module / single-`entry` | `devecocli build` |
-| Specific modules | `devecocli build --modules <m1> <m2>@<target>` |
-| Whole product bundle (.app) | `devecocli build --product <name>` |
-| Clean build outputs | `devecocli build clean` |
-
-### `devecocli check lint`
-Run DevEco Code Linter checks for TS/ArkTS code.
-- `[path]`: File or directory to lint. Defaults to the project root from `build-profile.json5`, otherwise the current directory.
-- Options: `--config-path <file>`, `--fix`, `--incremental`, `--product <name>`, `--format <default|json>`, `--output-path <path>`, `--limit <number>`.
-
-### `devecocli docs`
-Search/read local HarmonyOS docs.
-- `search <keywords...>`: Match any keyword. Opts: `--catalog <name>`, `--format <default|json>`, `--limit <n>`.
-- `read <documentId>`: Read full content by ID (e.g. `devecocli docs read 开发指南/冷启动_Launch分析/Launch模板基本操作/ide-insight-session-launch`).
-- `catalog`: List available catalogs.
-
-### `devecocli device`
-- `list`: Show active real devices.
-- `view`: Detailed info. Req `-t <name|serial>` on multi-device hosts.
-
-### `devecocli run` `[Outside sandbox]`
-Build, install, and launch.
-- `--module <module>`: Target module (auto-selected if only one runnable).
-- `--device <name|serial>`: Target device (Req if multiple connected).
-- `--product <product>` / `--build-mode <mode>`: Defaults: `default` / `debug`.
-- `--ability <ability>`: Default from `module.json5`.
-- `--uninstall`: Uninstall existing app first (Fixes signing key issues).
-- `--skip-build`: Deploy existing artifacts.
-- `--apply <fileName>`: **Fast incremental deploy** — rebuilds only changed files into a signed hqf, installs via `bm quickfix -a -f -o`, then restarts the app. Much faster than a full `devecocli run` for iterating on code changes. Modules are auto-detected from the file paths in `<fileName>` (no `--module` needed).
-  - `<fileName>`: a plain file name (no path separators) under the project's `.hvigor/` directory; the caller writes the changed-file list there. File name is sanitized to prevent path traversal. Content: list of **source file paths changed this round** (one per line, relative to project root or absolute; `#` comments and blank lines ignored; typically `.ets`/`.ts`/`.cpp`/resource files). The changeFileList is **incrementally merged** — only list files changed since the last apply; previously listed files are retained automatically.
-  - **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.
-
-### `devecocli log`
-Fetch hilog or crash logs. Req `--device <name|serial>` on multi-device hosts.
-- `--crash`: Dump crash logs.
-- `--level D|I|W|E|F`: Filter by level.
-- `--bundle-name` / `--keyword`: Filter output.
-- `--from <start>` / `--to <end>`: Relative offsets (`30s`, `5m`).
-- `--tail <num>` / `--follow`: Keep last N lines / stream real-time (no `--to`).
-*Ex*: `devecocli log --crash --bundle-name com.example.app`, `devecocli log --level E --from 5m --tail 200`
-
-### `devecocli ui`
-Inspect UI on a connected device. All subcommands accept `--device <name|serial>` (Req on multi-device hosts).
-
-| Subcommand | Description | Key Options |
-|---|---|---|
-| `layout` | Dump ArkUI accessibility layout tree — **visible area only** (on-screen nodes) | `--id <id>`, `--window <windowId>`, `--all-windows`, `--depth <n>` (0=unlimited, 1=root only, 2=root+children), `--format default\|json`, `--mode full\|simplified` |
-| `window list` | List active windows | `--format default\|json`, `--all` (include system windows) |
-| `screenshot` | Capture a screenshot of the device screen | `--display <displayId>`, required `--path <path>` (existing directory or PNG file path; relative paths supported; writable destination; no overwrite) |
-| `click [x] [y]` | Tap at the specified coordinates or node | `--id <id>` (auto-resolves to center), `--window <windowId>` (used with `--id`) |
-| `doubleclick [x] [y]` | Double-tap at the specified coordinates or node | `--id <id>`, `--window <windowId>` |
-| `longclick [x] [y]` | Long-press at the specified coordinates or node | `--id <id>`, `--window <windowId>` |
-| `swipe <x1> <y1> <x2> <y2>` | Swipe from one point to another (precise coordinates, custom speed) | `--speed <n>` (200–40000, px/s) |
-| `fling <x1> <y1> <x2> <y2>` | Fling from one point to another | `--speed <n>` (200–40000, px/s) |
-| `drag <x1> <y1> <x2> <y2>` | Drag from one point to another | `--speed <n>` (200–40000, px/s) |
-| `dircfling <direction>` | Quick directional fling (system default speed, ideal for scrolling) | `direction`: `up`, `down`, `left`, `right` |
-| `text <text> [x] [y]` | Input text at a target location or the currently focused field | `--id <id>` (auto-resolves to center), `--window <windowId>` (used with `--id`) |
-
-- **Coordinates vs `--id`**: Mutually exclusive. Provide either `x y` or `--id <id>`. For `text`, if neither is given, text goes to the currently focused field.
-- **`--window`**: May only be used together with `--id`. Default is focused window. Secondary display operations via `--id` + `--window` are not supported.
-- **`swipe` vs `dircfling`**: `swipe` requires exact start/end coordinates and supports `--speed`; `dircfling` only needs a direction (`up/down/left/right`) and uses system default speed (ideal for page/list scrolling).
-- **Text encoding**: Special characters in `text` are Base64-encoded internally to safely pass through device shell.
-- `--format json` pairs well with `jq`.
-- `--mode full`: full layout tree, no filtering.
-- `--mode simplified` (default): folds meaningless wrapper containers (non-root, no `id`, no text, not interactive) by lifting their surviving children up. `--depth` truncates after folding.
-
-## 2. Setup
-
-### `devecocli init`
-MUTUALLY EXCLUSIVE modes for setup:
-1. `--skill` (Default): Install `deveco-cli` skill to AI agents.
-2. `--mcp`: Configure `deveco-mcp` server (ArkTS/C++ syntax checking).
-*Options*:
-- `--agent <agents>`: Comma-separated (e.g. `opencode,cursor`). Omitting targets all.
-- `--project <path>`: Project-level config (Abs path for MCP).
-- `--path <path>`: Direct skill install path.
-- `-f, --force`: Overwrite existing config.
-*MCP Rules*: Global MCP (no `--project`) only supports `opencode` and `cursor`. Others require `--project`.
-
-### `devecocli auth login`
-Sign in to your Huawei Developer account. Opens a browser for OAuth authentication. Required before `signature generate`.
-*Ex*: `devecocli auth login`
-
-### `devecocli auth logout`
-Sign out and clear locally stored credentials.
-
-### `devecocli auth status`
-Show the current logged-in user.
-
-### `devecocli auth team list`
-List team accounts the current user has joined.
-
-### `devecocli skills`
-Manage HarmonyOS skills in AI agents/projects.
-- `list [-l|--long]` / `find <keyword>`: List or search skills.
-- `add (--all | --skill <name>) [--agent <a,b…>] [--project <path>] [--path <path>] [-f]`: Install.
-- `remove --skill <name> [...]`: Uninstall.
-
-## 3. Maintenance
-
-- **`devecocli update`** `[Outside sandbox]`: Update CLI to latest version.
-- **`devecocli serve mcp`**: Host stdio MCP server (`check` tool for `.ets`/C/C++). Used via `init --mcp`. (Env: `PROJECT_PATH`, `DEVECO_PATH`, `NODE_MAX_OLD_SPACE_SIZE`, `DEBUG=1`).
-
-## Recipes
-
-- **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
-- **Diagnose crash**:
-  `devecocli log --crash --bundle-name <bundle>`
-- **Release build**:
-  `devecocli build --product oversea --build-mode release`
-- **First-time signing setup**:
-  `devecocli login` -> `devecocli signature generate --product default` -> `devecocli build` -> `devecocli run`
-
-## Troubleshooting
-
-- **"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 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`.
-- **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.
+---
+name: deveco-cli
+description: >-
+  **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`, 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`, `check`, `run`, `update`, `device`, `skills`, `log`, `create`, `init`, `serve`, `docs`, `auth`.
+
+**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.
+
+## 1. Code → Build → Deploy → Run → Debug
+
+### `devecocli create`
+Scaffold a new HarmonyOS project.
+- `--app-name <name>` (Req): 1–200 chars, `^[a-zA-Z][a-zA-Z0-9_]*$`
+- `--project-path <path>`: Auto-created if omitted (`./<app-name>`). Must be empty if exists.
+- `--bundle-name <bundle>`: Default `com.example.<appname-lowercase>`. 7–128 chars, ≥3 segments.
+- `--api-level <level>`: int ≥17 (default: auto or 23).
+*Ex*: `devecocli create --app-name MyApp --project-path ./CustomDir --api-level 23`
+
+### `devecocli build` `[Outside sandbox]`
+Compile and package project/modules. (Defaults: `--product default`, `--build-mode debug`)
+| Goal | Command |
+|---|---|
+| Single-module / single-`entry` | `devecocli build` |
+| Specific modules | `devecocli build --modules <m1> <m2>@<target>` |
+| Whole product bundle (.app) | `devecocli build --product <name>` |
+| Clean build outputs | `devecocli build clean` |
+
+### `devecocli check lint`
+Run DevEco Code Linter checks for TS/ArkTS code.
+- `[path]`: File or directory to lint. Defaults to the project root from `build-profile.json5`, otherwise the current directory.
+- Options: `--config-path <file>`, `--fix`, `--incremental`, `--product <name>`, `--format <default|json>`, `--output-path <path>`, `--limit <number>`.
+
+### `devecocli docs`
+Search/read local HarmonyOS docs.
+- `search <keywords...>`: Match any keyword. Opts: `--catalog <name>`, `--format <default|json>`, `--limit <n>`.
+- `read <documentId>`: Read full content by ID (e.g. `devecocli docs read 开发指南/冷启动_Launch分析/Launch模板基本操作/ide-insight-session-launch`).
+- `catalog`: List available catalogs.
+
+### `devecocli device`
+- `list`: Show active real devices.
+- `view`: Detailed info. Req `-t <name|serial>` on multi-device hosts.
+
+### `devecocli run` `[Outside sandbox]`
+Build, install, and launch.
+- `--module <module>`: Target module (auto-selected if only one runnable).
+- `--device <name|serial>`: Target device (Req if multiple connected).
+- `--product <product>` / `--build-mode <mode>`: Defaults: `default` / `debug`.
+- `--ability <ability>`: Default from `module.json5`.
+- `--uninstall`: Uninstall existing app first (Fixes signing key issues).
+- `--skip-build`: Deploy existing artifacts.
+- `--apply <fileName>`: **Fast incremental deploy** — rebuilds only changed files into a signed hqf, installs via `bm quickfix -a -f -o`, then restarts the app. Much faster than a full `devecocli run` for iterating on code changes. Modules are auto-detected from the file paths in `<fileName>` (no `--module` needed).
+  - `<fileName>`: a plain file name (no path separators) under the project's `.hvigor/` directory; the caller writes the changed-file list there. File name is sanitized to prevent path traversal. Content: list of **source file paths changed this round** (one per line, relative to project root or absolute; `#` comments and blank lines ignored; typically `.ets`/`.ts`/`.cpp`/resource files). The changeFileList is **incrementally merged** — only list files changed since the last apply; previously listed files are retained automatically.
+  - **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.
+
+### `devecocli log`
+Fetch hilog or crash logs. Req `--device <name|serial>` on multi-device hosts.
+- `--crash`: Dump crash logs.
+- `--level D|I|W|E|F`: Filter by level.
+- `--bundle-name` / `--keyword`: Filter output.
+- `--from <start>` / `--to <end>`: Relative offsets (`30s`, `5m`).
+- `--tail <num>` / `--follow`: Keep last N lines / stream real-time (no `--to`).
+*Ex*: `devecocli log --crash --bundle-name com.example.app`, `devecocli log --level E --from 5m --tail 200`
+
+### `devecocli ui`
+Inspect UI on a connected device. All subcommands accept `--device <name|serial>` (Req on multi-device hosts).
+
+| Subcommand | Description | Key Options |
+|---|---|---|
+| `layout` | Dump ArkUI accessibility layout tree — **visible area only** (on-screen nodes) | `--id <id>`, `--window <windowId>`, `--all-windows`, `--depth <n>` (0=unlimited, 1=root only, 2=root+children), `--format default\|json`, `--mode full\|simplified` |
+| `window list` | List active windows | `--format default\|json`, `--all` (include system windows) |
+| `screenshot` | Capture a screenshot of the device screen | `--display <displayId>`, required `--path <path>` (existing directory or PNG file path; relative paths supported; writable destination; no overwrite) |
+| `click [x] [y]` | Tap at the specified coordinates or node | `--id <id>` (auto-resolves to center), `--window <windowId>` (used with `--id`) |
+| `doubleclick [x] [y]` | Double-tap at the specified coordinates or node | `--id <id>`, `--window <windowId>` |
+| `longclick [x] [y]` | Long-press at the specified coordinates or node | `--id <id>`, `--window <windowId>` |
+| `swipe <x1> <y1> <x2> <y2>` | Swipe from one point to another (precise coordinates, custom speed) | `--speed <n>` (200–40000, px/s) |
+| `fling <x1> <y1> <x2> <y2>` | Fling from one point to another | `--speed <n>` (200–40000, px/s) |
+| `drag <x1> <y1> <x2> <y2>` | Drag from one point to another | `--speed <n>` (200–40000, px/s) |
+| `dircfling <direction>` | Quick directional fling (system default speed, ideal for scrolling) | `direction`: `up`, `down`, `left`, `right` |
+| `text <text> [x] [y]` | Input text at a target location or the currently focused field | `--id <id>` (auto-resolves to center), `--window <windowId>` (used with `--id`) |
+
+- **Coordinates vs `--id`**: Mutually exclusive. Provide either `x y` or `--id <id>`. For `text`, if neither is given, text goes to the currently focused field.
+- **`--window`**: May only be used together with `--id`. Default is focused window. Secondary display operations via `--id` + `--window` are not supported.
+- **`swipe` vs `dircfling`**: `swipe` requires exact start/end coordinates and supports `--speed`; `dircfling` only needs a direction (`up/down/left/right`) and uses system default speed (ideal for page/list scrolling).
+- **Text encoding**: Special characters in `text` are Base64-encoded internally to safely pass through device shell.
+- `--format json` pairs well with `jq`.
+- `--mode full`: full layout tree, no filtering.
+- `--mode simplified` (default): folds meaningless wrapper containers (non-root, no `id`, no text, not interactive) by lifting their surviving children up. `--depth` truncates after folding.
+
+## 2. Setup
+
+### `devecocli init`
+MUTUALLY EXCLUSIVE modes for setup:
+1. `--skill` (Default): Install `deveco-cli` skill to AI agents.
+2. `--mcp`: Configure `deveco-mcp` server (ArkTS/C++ syntax checking).
+*Options*:
+- `--agent <agents>`: Comma-separated (e.g. `opencode,cursor`). Omitting targets all.
+- `--project <path>`: Project-level config (Abs path for MCP).
+- `--path <path>`: Direct skill install path.
+- `-f, --force`: Overwrite existing config.
+*MCP Rules*: Global MCP (no `--project`) only supports `opencode` and `cursor`. Others require `--project`.
+
+### `devecocli auth login`
+Sign in to your Huawei Developer account. Opens a browser for OAuth authentication. Required before `signature generate`.
+*Ex*: `devecocli auth login`
+
+### `devecocli auth logout`
+Sign out and clear locally stored credentials.
+
+### `devecocli auth status`
+Show the current logged-in user.
+
+### `devecocli auth team list`
+List team accounts the current user has joined.
+
+### `devecocli skills`
+Manage HarmonyOS skills in AI agents/projects.
+- `list [-l|--long]` / `find <keyword>`: List or search skills.
+- `add (--all | --skill <name>) [--agent <a,b…>] [--project <path>] [--path <path>] [-f]`: Install.
+- `remove --skill <name> [...]`: Uninstall.
+
+## 3. Maintenance
+
+- **`devecocli update`** `[Outside sandbox]`: Update CLI to latest version.
+- **`devecocli serve mcp`**: Host stdio MCP server (`check` tool for `.ets`/C/C++). Used via `init --mcp`. (Env: `PROJECT_PATH`, `DEVECO_PATH`, `NODE_MAX_OLD_SPACE_SIZE`, `DEBUG=1`).
+
+## Recipes
+
+- **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
+- **Diagnose crash**:
+  `devecocli log --crash --bundle-name <bundle>`
+- **Release build**:
+  `devecocli build --product oversea --build-mode release`
+- **First-time signing setup**:
+  `devecocli login` -> `devecocli signature generate --product default` -> `devecocli build` -> `devecocli run`
+
+## Troubleshooting
+
+- **"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 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`.
+- **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.