@deveco-test/deveco-code 1.0.2 → 1.0.4

package/resources/deveco/skills/deveco-cli/SKILL.md

@@ -0,0 +1,240 @@
+---
+name: deveco-cli
+description: >-
+  Use 'devecocli' for HarmonyOS apps (scaffold, build, run, debug, devices, emulators, logs, docs, UI inspection, 鸿蒙开发文档, skills). Use it if workspace has build-profile.json5 or oh-package.json5, or user mentions HarmonyOS, 鸿蒙, DevEco, ArkTS, ArkUI, docs, 鸿蒙文档, 知识, 搜索, skills, UI, UI测试, 组件调试. If user explicitly specifies another tool, skill, or workflow, follow that choice; otherwise use 'devecocli'.
+---
+
+# DevEco CLI
+
+`devecocli` wraps DevEco Studio's `hvigor`, `ohpm`, `hdc`, emulator toolchain, and bundled skills installer.
+
+This is DevEco Code's Router-aware skill, synchronized with `@deveco/deveco-cli@1.3.4`. DevEco Code invokes its bundled CLI through a proxy; the create, build, docs, run, and log behavior below includes local adaptations. Maintain this repository copy when upgrading the CLI; do not replace it with the npm package's unmodified skill.
+
+Available commands: `build`, `check`, `run`, `update`, `device`, `emulator`, `ui`, `skills`, `log`, `create`, `init`, `serve`, `docs`, `signature`, `auth`.
+
+**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>`: Final project root. Auto-created if omitted (`./<app-name>`) or missing, and populated if empty. A non-empty target returns `PROJECT_EXISTS` unless `--merge` is supplied.
+- `--bundle-name <bundle>`: Default `com.example.<appname-lowercase>`. 7–128 chars, ≥3 segments.
+- `--api-level <level>`: int ≥17 (default: auto or 23).
+- `--merge` allows a non-empty target while preserving existing content. Generated paths are checked before the target changes, and no existing file is overwritten.
+- `PROJECT_EXISTS` (exit 2): use `--merge` only if the existing directory is intended to become the project root. Otherwise ask whether to overwrite, rename, or cancel. Never clear the reported `details.targetRoot` without explicit confirmation.
+- `PROJECT_FILE_CONFLICT` (exit 2): report `details.conflicts` and ask the user to rename those paths, choose another root, or cancel. No existing files were changed; never overwrite the conflicts automatically.
+- In a DevEco Code session, successful creation reports `Project root:` for the session's workspace switch. In a standalone shell, change directory to that root before building.
+*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` |
+
+If build output is truncated, the complete log is saved at the path shown after `Full output saved to:`.
+
+### `devecocli check lint`
+Run DevEco Code Linter checks for TS/ArkTS code.
+- **Studio requirement**: Default lint checks and `--fix`, `--incremental`, `--product`, `--config-path`, and `--limit` support DevEco Studio `>= 6.0.0`; explicitly using `--format` or `--output-path` requires DevEco Studio `>= 6.1.0`. Command Line Tools mode follows the CLT `>= 26.0.0` baseline.
+- `[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>`.
+- Set `DEVECO_CLI_CLT_PATH` to the Command Line Tools root when DevEco Studio is not installed; CLT is not discovered automatically from PATH or default installation directories.
+
+### `devecocli emulator`
+Manage local emulator instances and system images.
+- **Studio requirement**: DevEco Studio `>= 6.1.0`.
+- `list`: Show instances (status, serial, device type). Opt: `--format <table|json>` (default: `table`).
+- `start <names...>`: Start instances. Quote names with spaces. (See Troubleshooting if blocked).
+- `stop <names...>`: Stop by name or serial (`127.0.0.1:<port>`).
+- Scene control commands require Emulator 7.0 or later. Use `DEVECO_CLI_DEBUG=1` to inspect the underlying `Emulator` command mapping.
+- `shake` / `power` / `rotate <left|right>` / `volume <up|down>` (Req: `--target <nameOrSerial>`): Basic emulator controls.
+- `fold <state>` (Req: `--target <nameOrSerial>`): Set foldable display state, matched against the target emulator's reported `deviceType`. `foldable` uses `open|half-open|close`; `2in1_foldable` uses `open|vertical-open|half-open|close`; `triplefold` uses `single|double|triple` or one of its six left/right folded-state combinations. Other device types and cross-device states are rejected before execution.
+- `battery` (Req: `--target`; one of `--level <0-100>` or `--status <charging|discharging>`): Set battery state. `--level` checks the current emulator charging state automatically (`0-100` while charging, `1-100` otherwise).
+- `geolocation` (Req: `--target`; one of `--longitude`, `--latitude`, `--altitude`, `--direction`): Inject GPS data.
+- `scene <outdoorRunning|outdoorCycling|drivingNavigation>` (Req: `--target`): Start motion simulation.
+- `sensor` (Req: `--target`; one of `--light-intensity`, `--humidity`, `--temperature`, `--steps`, `--heartrate`): Inject sensor data.
+- `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 ui`
+Inspect UI on a connected physical device or running emulator.
+- `screenshot`: Capture a screenshot from a physical device or running emulator. `--device <name|serial>` is optional when exactly one device is connected, and required when multiple devices are connected.
+- Optional: `--display <displayId>`. Required: `--path <path>` (existing directory or PNG file path, including paths relative to the current directory; writable destination; no overwrite).
+- Implementation uses `hdc shell snapshot_display` and `hdc file recv`; set `DEVECO_CLI_DEBUG=1` to inspect the actual `hdc` commands.
+*Ex*: `devecocli ui screenshot --device Phone --path ./screenshots/phone.png`
+
+### `devecocli docs`
+Search/read local HarmonyOS docs.
+- `search <keywords...>`: Match any keyword. Opts: `--catalog <name>`, `--format <default|json>`, `--limit <n>`.
+- `read <documentId>`: Read a document by ID (e.g. `devecocli docs read 开发指南/冷启动_Launch分析/Launch模板基本操作/ide-insight-session-launch`).
+- `catalog`: List available catalogs.
+- `search` and `read` responses default to a 5,000-character preview. When truncated, the complete result is saved at the path shown after `Full output saved to:`.
+- This also applies to `--format json`: a truncated preview is not valid JSON. Read the saved file for the complete result instead of parsing the preview.
+
+### `devecocli device`
+- `list`: Show active real devices and running emulators. Opt: `--format <table|json>` (default: `table`).
+- `view`: Detailed info. Req `-t <name|serial>` on multi-device hosts. Opt: `--format <table|json>` (default: `table`).
+
+### `devecocli run` `[Outside sandbox]`
+Build, install, and launch.
+- `--module <module>`: Target module (auto-selected if only one runnable).
+- `--device <name|serial>`: Target device. For a standard build-and-run deployment, omitting it auto-selects the only available physical device or emulator and starts a stopped emulator before deployment. Multiple targets return `DEVICE_SELECTION_REQUIRED`; no available target returns `NO_DEVICE_AVAILABLE`.
+- On `DEVICE_SELECTION_REQUIRED`, ask the user to choose from the returned targets, then retry with `--device`. An explicitly selected stopped emulator is also started automatically. Special modes (`--apply`, `--hotreload`, `--hotreload-apply`), help, and unknown run options bypass Router device selection/startup; ensure a running device and pass `--device` when needed. Discovery failures fall back to the native CLI.
+- `--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**: DevEco Studio ≥6.1.1 (hvigor `assembleDevHqf` support; below is rejected with an upgrade hint); 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`
+- `--hotreload [action]`: **Hot-reload watch session** — must be started as a **background process** (the process holds a persistent socket to the hvigor daemon). It builds the hap in hot-reload mode (`hotReload=true debuggable=true`), deploys+launches the app, then the process itself connects a socket to the daemon and sends `CommonBuild assembleHap --hot-reload-build --watch`, **staying connected** so the daemon's watch worker (rollup watch) stays alive for `--hotreload-apply` to reuse. The process stays alive (onBuildOutput streams to its stdout). **Must be stopped (kill the background process) when the hot-reload debug session ends** — otherwise the watch worker/daemon leaks. `--hotreload stop` additionally stops the hvigor daemon.
+  - **Usage through DevEco Code**: the proxy buffers child stdout/stderr until the CLI exits, so do not wait for "watch session active" on proxy stdout. Use a managed background job, inspect `<module>/build/<product>/.hotreload-mode` and `.hvigor/hotreload-watch.log` for readiness/errors, then run `devecocli run --module <m> --hotreload-apply <file>`. A marker left by an earlier session alone does not prove readiness. When done, stop the job's CLI child process as well as the proxy, then run `devecocli run --hotreload stop`; killing only the proxy may leave the child alive.
+- `--hotreload-apply <fileName>`: **Hot reload without app restart** — reads the changed-file list from `.hvigor/<fileName>` (same format/merge rules as `--apply`), opens a **short socket** to the daemon (kept alive by the background `--hotreload` process) and sends `CommonBuild assembleDevHqf --hot-compile` → the watch worker incrementally hot-compiles changed `.ets`/`.ts` into abc (HotReloadArkTS; output/errors streamed live via WatchLog), then **manually** packs + signs a hqf from that abc (`app_packing_tool.jar` + `hap-sign-tool.jar`, DevEco material password decrypted via `DecipherUtil`), and installs it via `bm quickfix -a -f -o`. The app is **not restarted** — changes take effect immediately.
+  - **Prereq**: the background `devecocli run --hotreload` process must be running (holds the watch session). If `--hotreload-apply` times out, the watch session isn't alive — (re)start the background `--hotreload`.
+  - **Scope (important)**: hot reload targets a **single module** (`--module` required; the target can be entry/hsp/feature; `har` deps are folded in and fine). **`har` dependency changes are auto-routed** to the dependent main module's (entry/feature/hsp) `hotReload/changedFileList.json` — so editing a har's `.ets` and listing it hot-reloads via the target module. Changes in **`feature`/`hsp` dependency modules** (not the target) are NOT hot-reloadable — they're detected and warned (run a full `devecocli run` to redeploy those). `@State`/state-decorator changes are **not** hot-reloadable (state isn't re-initialized); hot-reloadable changes are non-state code: UI property values (`.fontColor`/`.fontSize`), `Text`/`Button` literal labels, method bodies, expressions. Resources/native changes need a full run.
+  - **Compile errors**: ArkTS compile errors from the hot compile are routed (via WatchLog) to the **background `--hotreload` process**, which writes them to **`.hvigor/hotreload-watch.log`** (and its stdout). On failure, `--hotreload-apply` reads that file and prints the errors inline (fast-fail, ~15s timeout if the watch session is dead).
+  - **Artifacts under `.hvigor/`** (shared with `--apply`): `.hvigor/<fileName>` = the changed-file list you write; `.hvigor/hotreload-watch.log` = the watch session's onBuildOutput/compile-errors (written by the background `--hotreload` process; safe to read/delete). The hot-reload marker is `<module>/build/<product>/.hotreload-mode`.
+*Ex*: background `devecocli run --module entry --hotreload` → (ready) → edit `.fontColor` in `entry/src/main/ets/pages/Index.ets` → write path to `.hvigor/changes.txt` → `devecocli run --module entry --hotreload-apply changes.txt` (UI updates without restart). When done: kill the background process + `devecocli run --hotreload stop`.
+
+### `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`.
+- **Prereq**: `devecocli auth login` first; run from a project directory (with `build-profile.json5`); a connected device or emulator is required for device registration.
+- `--product <name>`: Product name for local p12/csr file naming (default: `default`).
+- `--team-id <id>`: Specify the team-id (default: current user's id).
+- `--force`: Force regenerate even if existing materials are valid.
+- Generates under `~/.ohos/config/`: `.p12` keystore, `.csr`, downloaded `.cer` certificate, `.p7b` profile.
+- Writes `signingConfigs` + `products` entries to `build-profile.json5` with encrypted key/store passwords (AES-128-GCM).
+- Cloud cert name: `auto_debug_<teamId>.cer`. Local files: `<product>_<project>_<hash>=.{p12,csr,cer,p7b}`.
+- Error handling (aligned with DevEco Studio JAR): 401→re-login, 403→no AGC permission, `205389872`→cert limit, `205389904`→not Harmony user, `205389938`→provision limit, invalid `.cer`→retry.
+*Ex*: `devecocli signature generate --product default`
+
+
+### `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>`: Return the latest N matching log lines; must be a positive integer. Defaults to 2000 only when none of `--tail`, `--from`, `--to`, `--follow`, or `--crash` is present.
+- `--follow`: The native CLI follows logs until stopped, but the DevEco Code proxy buffers output until the child exits; it is not a live log stream in the tool response. Prefer bounded `--from` / `--tail` queries for interactive diagnosis. Cannot be combined with `--to`.
+- `clear [--device <name|serial>]`: Clear hilog before reproducing an issue. Without a selector, exactly one connected device is required. Names must resolve uniquely; prefer a serial when names repeat.
+- Invalid clear selectors, device discovery failures, missing HDC, and HDC failure output return an error without reporting successful cleanup.
+*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`.
+
+DevEco Code already ships this Router-aware skill. Do not use `init --skill` to overwrite it with the native CLI skill; use that installer only for separately requested agent/project setup.
+
+### `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.
+
+### `devecocli check compat` `[Outside sandbox]`
+Scan source code for breaking API changes between two SDK versions. Built on top of DevEco Studio's `arkanalyzer-apiscan` plugin.
+- `versions`: List available target SDK versions. Opts: `--format <default|json>` (default: `default`).
+- Default (no args): project-level scan.
+- `--modules <m1> [m2...]`: Module-level scan.
+- `<file1> [file2...]`: File-level scan (`.ets`/`.c`/`.cpp` only).
+- `--source-version <v>` (Req) / `--target-version <v>` (Req): SDK version pair. Run `devecocli check compat versions` first; on zsh, **quote the value** (e.g. `"<source_version>"`, `"<target_version>"`).
+- `--format <default|csv|json>` (default: `default`): Console output accepts `default` (text) or `json`; file output (via `--output-path`) accepts `default` (csv), `csv`, or `json`. `csv` requires `--output-path`.
+- `--output-path <path>`: Directory (writes `apiChange-*.csv`/`apiChange-*.json`) or explicit file (extension must match `--format`).
+- `--limit <n>` (default `100`): Max records shown on console when no `--output-path`.
+
+Validation order: `files` + `--modules` mutually exclusive → `--source-version`/`--target-version` required → `csv` requires `--output-path` → project dir valid → modules exist → files exist + extension valid → versions in catalog + `target > source` → format/extension match → output target writable.
+
+*Ex*: `devecocli check compat --source-version "<source_version>" --target-version "<target_version>" --output-path ./report`
+
+## 3. Maintenance
+
+- **`devecocli update`** `[Outside sandbox]`: Native standalone CLI updater. DevEco Code pins its bundled CLI; do not use this command or a global npm install to upgrade the bundle. Upgrade DevEco Code itself, or update its pinned dependency, lockfile, and this skill together during repository development.
+- **`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 emulator**:
+  `devecocli run` (builds and deploys; Router selects/starts the sole target). If there are multiple targets, choose one and retry with `--device "Name"`. After a separate successful build, use `devecocli run --skip-build`.
+- **Diagnose crash**:
+  `devecocli log --crash --bundle-name <bundle>`
+- **Release build**:
+  `devecocli build --product oversea --build-mode release`
+- **First-time signing setup**:
+  `devecocli auth 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/start emulator. Pass `-t <serial>` (device view) or `--device <name|serial>` (run/log).
+- **`error:install sign info inconsistent`**: Signing key changed. Run `devecocli run --uninstall` or `devecocli signature generate --force`.
+- **`Not logged in. Run devecocli auth login first`**: Run `devecocli auth login` to authenticate.
+- **`Provision number exceeds limit`**: Test provision quota is full. Delete old test provisions in DevEco Studio (Signing Configs) or AGC console, then retry `devecocli signature generate`.
+- **`Invalid AccessToken. Sign in and try again`**: Token expired. Run `devecocli auth login` again.
+- **`skills add` agent not found**: Valid: `atomcode`, `codebuddy`, `cursor`, `opencode`, `qoder`, `trae-cn`.
+- **`emulator start` / `image download` blocked on agreement**: User MUST accept agreements. Interactive: `devecocli emulator license` (requires TTY). Non-interactive (CI/scripts): `devecocli emulator license accept`. Ask the user to review and accept; run the non-interactive acceptance only if explicitly authorized. 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.
+- **`ui layout` missing expected node**: `layout` only returns on-screen nodes. Scroll the target into view with `ui dircfling` / `ui swipe` when appropriate for the requested UI task, or ask the user to scroll, then retry `ui layout`.

package/resources/deveco/skills/hmos-arkui-develop-skill/.deveco-builtin

@@ -0,0 +1 @@
+hmos-arkui-develop-skill

package/resources/deveco/skills/hmos-arkui-develop-skill/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: hmos-arkui-develop-skill
+description: REQUIRED before writing the first .ets file of a session. Fatal gotchas list + API quick-reference for HarmonyOS ArkTS/ArkUI development. Load this skill when writing or modifying .ets files, porting TypeScript to ArkTS, or building any ArkUI page, component, layout, navigation, dialog, state-driven UI, or animation. Covers ArkTS linter rules, forbidden syntax, null safety, struct/@Component constraints, V1/V2 state management, rendering control, API parameter correctness, and UI quality. Triggers — .ets, ArkTS, ArkUI, HarmonyOS, struct, @Component, TS-to-ArkTS migration, ArkUI build error, runtime crash.
+---
+
+# ArkTS/ArkUI 编码约束
+
+为 agent 写 ArkTS/ArkUI 代码提供致命陷阱清单和准确的 API 参考入口。
+
+## API 和约束查表优先
+
+1. **写任何组件前，必须同时查两类文件**：
+   - **API 签名**：在 `references/quick-apis/_index.md` 定位组件所在文件，用 Grep 取卡片（勿整读大文件）。签名必须照搬，不得凭记忆改写、增减参数或改变参数类型
+   - **约束规则**：在 `references/quick-rules/_index.md` 按任务特征查对应规则文件，提前预防错误
+2. **组件→规则文件交叉索引**（写某组件时，必查对应的规则文件）：
+
+| 写这些组件/功能时 | 必查 API 文件 | 必查规则文件 |
+|---|---|---|
+| List / Grid / WaterFlow / Tabs / Scroll | 01-layout | 12-layout（子组件约束）+ 06-rendering（ForEach/LazyForEach/Repeat） |
+| Navigation / NavDestination | 12-navigation | 08-navigation（路由栈、pushPath param） |
+| @State/@Link/@Prop/@Local/@Param 等 | 08-state-decorators | 05-state（V1/V2 混用、@Builder 传参、@ObjectLink 限制） |
+| Button / Text / Image / TextInput | 02-basic-components | 07-attribute-params（臆造 API 清单） |
+| DatePicker / TimePicker / TextPicker | 04-selectors | 07-attribute-params（构造参数字段名高发错） |
+| AlertDialog / ActionSheet / bindSheet | 11-dialog-menu | 09-dialog（堆叠规则） |
+| animateTo / transition | 09-animation | 07-attribute-params（curve 必须枚举等） |
+| 手势 / 拖拽 | 10-gesture | 11-extension（手势绑定、拖拽冲突） |
+| import / router / promptAction | — | 01-import（kit 路径）+ 02-uicontext（全局接口替换） |
+
+## 高频错误及约束
+
+### ArkTS 语法
+
+1. 不使用 any/unknown 类型、以及...解构赋值
+2. 从回调 / Map.get / Array.find / 可选属性取值时做空安全处理（`??` 默认值或判空）
+3. 函数与箭头函数参数必须显式标注类型；泛型函数调用必须显式指定类型参数——`arr.map(x => x.id)` ❌、`arr.map((x: Item): string => x.id)` ✅；`new Map()` ❌、`new Map<string, number>()` ✅；`arr.find(x => x.id === 1)` ❌、`arr.find((x: Item): boolean => x.id === 1)` ✅（依赖推断会报 `arkts-no-any-unknown` 或 `arkts-no-inferred-generic-params`）
+
+### 命名与作用域
+
+4. ArkTS 不支持声明合并（arkts-no-decl-merging），同一项目中不同文件的顶层 interface/class/struct 名不能重复，也不能与系统组件/全局类型重名——自定义名称一律加业务前缀
+    - WRONG: 文件A声明 `interface Item`，文件B也声明 `interface Item`
+    - RIGHT: 文件A用 `interface CartItem`，文件B用 `interface OrderItem`，按业务语义区分命名
+5. 变量名/参数名/方法名避开框架保留字（如 `builder`/`create`/`value`），否则报 `arkts-unique-names` 或 `10505001`——见 `references/quick-rules/03-component.md` 保留字全表
+6. **@State/@Prop/@Local 等成员名禁止与链式方法重名**——`value`/`width`/`height`/`margin`/`padding`/`offset`/`position`/`border`/`backgroundColor`/`opacity`/`visibility`/`scale`/`rotate`/`size`/`direction`/`enabled`/`zIndex`/`layoutWeight`/`alignItems`/`justifyContent`/`alignContent` 等通用属性名均为禁区 → **10505001**。用业务前缀消歧义：`currentValue` 而非 `value`
+
+### build() 与组件结构
+
+7. @Entry 根节点必须是单个容器组件（Column/Row/Stack 等）；@Component 根节点可为非容器，但必须是唯一节点，但 **`ForEach` 仍不可作为根节点**
+
+8. build() 中不声明本地变量、不用 console，详细可以参考`references/quick-rule/build.md`
+
+9. ForEach / LazyForEach / Repeat 必须显式提供 key（用业务 ID 不用索引）；省略时 ForEach 默认 `JSON.stringify`（bigint/循环引用会 jscrash），Repeat 生成随机值（每次更新全量重建）
+
+10. `@Entry` 不能用 `@ObjectLink`，必须抽子组件
+
+11. **Button('label') 与子组件互斥**——`Button('OK') { Text('x') }` ❌ → **10905202**；`Button('OK')` ✅ 或 `Button() { Text('x') }` ✅
+
+12. **@Builder 返回 void，调用处不可链式**——`myBuilder().onClick(...)` ❌
+
+13. **嵌套 ForEach 参数名必须不同**——外层 `row` 内层 `cell`，不用 `item`/`item`
+
+### 状态管理
+
+14. V1/V2 状态管理不混用——@Component 内只能用 @State/@Prop/@Link/@Provide/@Consume/@Watch/@ObjectLink/@Observed；@ComponentV2 内只能用 @Local/@Param/@Provider/@Consumer/@Monitor/@Computed/@ObservedV2/@Trace；AppStorageV2/PersistenceV2 只能在@ComponentV2 内使用；@Link/@ObjectLink 不本地初始化（值从父组件传入）
+15. `@State` 只代理第一层；嵌套属性变化不刷新，需 `@Observed` 类 + 子组件 `@ObjectLink` 逐层代理
+16. `@Builder` 按引用传递：形参用 `$$: InterfaceType` 接收，调用时传单参数对象字面量 `myBuilder({ key: this.val })`；多参数不刷新；@Builder 方法定义在 build() 之前；参数类型必须用显式声明的 interface/class，禁止内联对象字面量类型 → **10605040**
+17. **@Param 只读**——`this.x = ...` 在 @ComponentV2 内报 `Cannot assign to 'x' because it is a read-only property`；@Local 只能内部初始化，调用处传值不生效
+18. **@ObjectLink 禁止整体赋值**——`this.objLink = new Info()` ❌，只能改属性
+
+### 布局与渲染
+
+19. 部分容器组件内部只允许放对应的子组件，如`List与ListItem、Grid与GridItem`等
+20. `ForEach`/`LazyForEach`/`Repeat` **不是真实组件**，返回的 `ForEachAttribute` 等不支持 `.layoutWeight()`/`.width()` 等通用布局属性
+21. Repeat (V2)设置了virtualScroll懒加载情况下仅 `@ComponentV2` 内可用
+22. **Repeat 的 cachedCount 放滚动容器上**——`Repeat(arr).cachedCount(3)` ❌ → **10505001**；`List() { Repeat(arr) }.cachedCount(3)` ✅
+23. **LazyForEach 的 dataSource 不可重新赋值**，修改数据后必须通过 DataChangeListener 通知更新
+
+### API 参数（编译必挂高频）
+
+24. 传给组件构造/API 的对象字面量，字段名与 Options 类型逐字一致
+25. 回调参数类型用编译器声明的联合类型，不自行收窄（如 `onChange(index: number)` → 实际签名是 `onChange(index: number | string)`）
+26. **构造参数字段名不能凭记忆编造**——实测高发：`TimePicker({ useMilitaryTime: true })` ❌（useMilitaryTime 是 TimePickerDialog 的字段）；`Tabs(this.tabsController)` ❌（构造参数是 `{ controller: ... }`）；`MenuItem({ value: '复制', icon: $r(...) })` ❌（正确字段是 content + startIcon）；`Shape({ viewPort: {...} })` ❌（viewPort 是链式方法）；`PersistentStorage.persistProps([{ key: 'k', default: 'v' }])` ❌（正确字段是 defaultValue）
+
+详细规则文件索引见 `references/quick-rules/_index.md`。