@deveco-test/hmos-deveco-cli 0.1.0-TD.4 → 0.1.0-TD.4.1

package/README.md

@@ -2,31 +2,35 @@
   <h1>DevEco CLI</h1>
   <p>一个面向 HarmonyOS 应用开发的统一命令行入口。</p>
   <p>
-    <a href="https://www.npmjs.com/package/@deveco/deveco-cli"><img src="https://img.shields.io/npm/v/@deveco/deveco-cli.svg" alt="NPM Version" /></a>
-    <a href="https://www.npmjs.com/package/@deveco/deveco-cli"><img src="https://img.shields.io/npm/dm/@deveco/deveco-cli.svg" alt="NPM Downloads" /></a>
+    <a href="https://www.npmjs.com/package/@deveco-test/hmos-deveco-cli"><img src="https://img.shields.io/npm/v/@deveco/deveco-cli.svg" alt="NPM Version" /></a>
+    <a href="https://www.npmjs.com/package/@deveco-test/hmos-deveco-cli"><img src="https://img.shields.io/npm/dm/@deveco-test/hmos-deveco-cli.svg" alt="NPM Downloads" /></a>
     <a href="https://nodejs.org/"><img src="https://img.shields.io/badge/Node.js-%3E%3D18-green.svg" alt="Node.js" /></a>
-    <img src="https://img.shields.io/badge/platform-macOS%20%7C%20Windows-blue.svg" alt="Platform" />
-    <a href="https://developer.huawei.com/consumer/cn/download/"><img src="https://img.shields.io/badge/DevEco%20Studio-%3E%3D6.1.0-orange.svg" alt="DevEco Studio" /></a>
+    <img src="https://img.shields.io/badge/platform-HarmonyOS-blue.svg" alt="Platform" />
+    </a>
     <a href="./LICENSE"><img src="https://img.shields.io/badge/license-MIT-green.svg" alt="License" /></a>
   </p>
 </div>
 
-`DevEco CLI` 将 `DevEco Studio` 工具链统一封装为一个 `CLI`，内置 `ohpm`、`hvigor`、`hdc`、`emulator`、`hilog`，同时集成 HarmonyOS 技能安装、项目脚手架、本地  HarmonyOS 文档检索和 `MCP` 服务。
+`DevEco CLI` 将 `DevEco Studio` 工具链统一封装为一个 `CLI`，内置 `ohpm`、`hvigor`、`hdc`、`hilog`，同时集成 HarmonyOS 技能安装、项目脚手架、本地  HarmonyOS 文档检索和 `MCP` 服务。
 
 
 ## 快速开始
 
 ### 前置要求
 
-- 操作系统为 `macOS` 或 `Windows`
-- Node.js >= 18，推荐使用22及以上版本
-- [DevEco Studio](https://developer.huawei.com/consumer/cn/download/) >= 6.1.0
-  - **macOS**：必须安装在 `~/Applications` 或 `/Applications` 目录下。
+- 操作系统为 `HarmonyOS`
+- 安装 Command Line Tool 工具
+- 配置环境变量：
+  ```bash
+  export COMMAND_LINE_TOOL_PATH=path/to/deveco_tools
+  export PATH=$PATH:path/to/deveco_tools/node/bin
+  ```
+
 
 ### 安装
 
 ```bash
-npm install -g @deveco/deveco-cli@latest
+npm install -g @deveco-test/hmos-deveco-cli
 ```
 
 安装后可以通过以下命令更新到最新版本：
@@ -72,12 +76,12 @@ opencode
 如果 `Agent` 不在 `--agent` 参数取值范围内，可使用 `--path` 参数进行添加，参考如下命令：
 
 ```bash
-devecocli init --path D:\work\ARKTS\NewData
+devecocli init --path .\work\ARKTS\NewData
 ```
 
 进入 `Agent` 后可以直接描述任务，例如：
 
-- `Build this project in release mode and run it on my emulator`
+- `Build this project in release mode and run it on my device`
 - `Tail the last error logs from this app`
 - `Check for syntax errors in src/main/ets/pages/Index.ets`
 
@@ -89,7 +93,6 @@ devecocli init --path D:\work\ARKTS\NewData
 | `devecocli build`         | 构建项目并产出 `.hap` / `.hsp` / `.har` / `.app` |
 | `devecocli run`           | 安装并运行应用                                   |
 | `devecocli device list`   | 查看当前连接设备                                  |
-| `devecocli emulator list` | 查看本地模拟器实例                                 |
 | `devecocli log`           | 查看 `hilog` 或崩溃日志                          |
 | `devecocli docs search`   | 搜索本地 HarmonyOS 文档                         |
 | `devecocli init`          | 安装内置技能或配置 `MCP`                           |
@@ -122,7 +125,6 @@ Commands:
   run [options]          Build and run the project on a connected device
   update                 Update deveco-cli to the latest version
   device                 Manage connected devices
-  emulator               Manage emulator instances
   skills                 Manage HarmonyOS skills
   log [options]          Obtain device application logs
   create [options]       Scaffold a new HarmonyOS application project
@@ -160,12 +162,12 @@ devecocli init --agent <agents> --project <path> --path <path> --skill --mcp --f
 devecocli init -f   # 安装或更新deveco-cli Skill
 devecocli init --skill
 devecocli init --agent agentname    # agentname需替换为实际的智能体名称
-devecocli init --path D:\work\ARKTS\NewData -f
+devecocli init --path /path/to/project -f
 
 # 配置MCP
 devecocli init --mcp
 devecocli init --mcp --agent agentname    # agentname需替换为实际的智能体名称   
-devecocli init --mcp --project D:\work\ARKTS\NewData -f
+devecocli init --mcp --project /path/to/project -f
 ```
 
 ### `docs search`
@@ -310,214 +312,9 @@ devecocli build --product oversea --modules entry --build-mode release
 devecocli build clean
 ```
 
-### `emulator list`
-
-查看模拟器实例
-
-**命令格式：**
-
-```bash
-devecocli emulator list
-```
-
-### `emulator start`
-
-启动模拟器。首次使用时，需要签署 HarmonyOS 软件许可与服务协议，具体请参考 `emulator license accept`
-
-**命令格式：**
-
-```bash
-devecocli emulator start [names...]
-```
-
-**参数：**
-
-| 参数名         | 说明                                        |
-| ----------- | ----------------------------------------- |
-| \[names...] | 必选，模拟器实例名称，多个名称用空格隔开。若名称中带有空格，则名称需要添加英文引号 |
-
-**示例：**
-
-```bash
-devecocli emulator start Phone
-devecocli emulator start Phone1 Phone2
-```
-
-**说明：**
-
-- `emulator start` 命令仅支持启动 `release` 版本的模拟器
-
-### `emulator stop`
-
-关闭模拟器
-
-**命令格式：**
-
-```bash
-devecocli emulator stop [names...]
-```
-
-**参数：**
-
-| 参数名         | 说明                                        |
-| ----------- | ----------------------------------------- |
-| \[names...] | 必选，模拟器实例名称，多个名称用空格隔开。若名称中带有空格，则名称需要添加英文引号 |
-
-**示例：**
-
-```bash
-devecocli emulator stop Phone
-devecocli emulator stop 127.0.0.1:5555
-```
-
-### `emulator create`
-
-创建模拟器
-
-**命令格式：**
-
-```bash
-devecocli emulator create <name> --device-type <type> --os-version <version> --force
-```
-
-**参数：**
-
-| 参数名           | 说明                                                                                                                              |
-| ------------- | ------------------------------------------------------------------------------------------------------------------------------- |
-| name          | 必选，模拟器名称                                                                                                                        |
-| --device-type | 必选，模拟器设备类型，支持 `phone` ， `foldable` ， `widefold` ， `triplefold` ， `tablet` ， `2in1` ， `2in1 foldable` ， `tv` ， `wearable` ，全小写 |
-| --os-version  | 必选，模拟器镜像版本                                                                                                                      |
-| --force       | 可选，覆盖已有同名的模拟器                                                                                                                   |
-
-**示例：**
-
-```bash
-devecocli emulator create MyPhone --device-type phone --os-version "HarmonyOS 6.0.1(21)"
-```
-
-### `emulator delete`
-
-创建模拟器
-
-**命令格式：**
-
-```bash
-devecocli emulator delete <name>
-```
-
-**参数：**
-
-| 参数名  | 说明             |
-| ---- | -------------- |
-| name | 必选，模拟器实例名称或序列号 |
-
-**示例：**
-
-```bash
-devecocli emulator delete MyPhone
-```
-
-### `emulator image list`
-
-查询模拟器镜像列表
-
-**命令格式：**
-
-```bash
-devecocli emulator image list --device-type <type> --all --format <format>
-```
-
-**参数：**
-
-| 参数名           | 说明                                                                                                                         |
-| ------------- | -------------------------------------------------------------------------------------------------------------------------- |
-| --device-type | 可选，模拟器设备类型，支持 `phone` ， `foldable` ， `widefold` ， `triplefold` ， `tablet` ， `2in1` ， `2in1 foldable` ， `tv` ， `wearable` |
-| --all         | 可选，查询已下载和未下载的所有镜像                                                                                                          |
-| --format      | 可选，控制输出格式，取值为 `table` 或 `json` ，默认为 `table`                                                                                |
-
-**示例：**
-
-```bash
-devecocli emulator image list
-devecocli emulator image list --all
-devecocli emulator image list --device-type phone
-devecocli emulator image list --format json
-```
-
-### `emulator image download`
-
-下载模拟器镜像。首次使用时，需要签署 HarmonyOS `SDK` 许可协议，具体请参考 `emulator license accept`
-
-**命令格式：**
-
-```bash
-devecocli emulator image download --device-type <type> --os-version <version> --force
-```
-
-**参数：**
-
-| 参数名           | 说明                                                                                                                              |
-| ------------- | ------------------------------------------------------------------------------------------------------------------------------- |
-| --device-type | 必选，模拟器设备类型，支持 `phone` ， `foldable` ， `widefold` ， `triplefold` ， `tablet` ， `2in1` ， `2in1 foldable` ， `tv` ， `wearable` ，全小写 |
-| --os-version  | 必选，模拟器镜像版本                                                                                                                      |
-| --force       | 可选，覆盖已有的模拟器镜像                                                                                                                   |
-
-**示例：**
-
-```bash
-devecocli emulator image download --device-type phone --os-version "HarmonyOS 6.0.1(21)" --force
-```
-
-**说明：**
-
-- `emulator image download` 命令仅支持下载 `release` 版本的模拟器镜像
-
-### `emulator image remove`
-
-删除模拟器镜像
-
-**命令格式：**
-
-```bash
-devecocli emulator image remove --device-type <type> --os-version <version>
-```
-
-**参数：**
-
-| 参数名           | 说明                             |
-| ------------- | ------------------------------ |
-| --device-type | 必选，模拟器设备类型，与下载镜像的device-type一致 |
-| --os-version  | 必选，模拟器镜像版本，与下载镜像的os-version一致  |
-
-**示例：**
-
-```bash
-devecocli emulator image remove --device-type phone --os-version "HarmonyOS 6.0.1(21)"
-```
-
-### `emulator license view`
-
-查看协议文本（只读）
-
-**命令格式：**
-
-```bash
-devecocli emulator license view
-```
-
-### `emulator license accept`
-
-查看并接受协议。使用模拟器需要同意 HarmonyOS 软件许可与服务协议，下载镜像需要同意 HarmonyOS `SDK` 许可协议
-
-**命令格式：**
-
-```bash
-devecocli emulator license accept
-```
-
 ### `device list`
 
-查询所有已连接的设备，包括真机设备和运行中的模拟器
+查询所有已连接的设备
 
 **命令格式：**
 
@@ -551,7 +348,7 @@ devecocli device view -t "My Device Name"
 
 ### `run`
 
-构建应用后，将应用安装到真机设备或模拟器上，并启动执行
+构建应用后，将应用安装到设备上，并启动执行
 
 **命令格式：**
 
@@ -733,9 +530,8 @@ devecocli skills remove --skill skillname --agent agentname  # skillname需替
         "mcp"
       ],
       "environment":{
-        "PROJECT_PATH": "D:\\code\\sample_project", // 工程路径
+        "PROJECT_PATH": "/path/to/project", // 工程路径
         "NODE_MAX_OLD_SPACE_SIZE": "8192", // 可选，设置内部node进程最大的老生代内存大小，默认为8192
-        "DEVECO_PATH": "D:\\Application\\DevEco Studio" // 可选，Deveco Studio的路径
       },
       "enbale": true
     }
@@ -745,7 +541,32 @@ devecocli skills remove --skill skillname --agent agentname  # skillname需替
 
 ## 常见问题
 
-[FAQ](https://gitcode.com/openharmony-sig/deveco-cli/wiki/FAQ.md)
+### 如何本地推包运行
+
+当没有真机设备连接时，可以通过无线调试实现自连，在本地推包运行应用：
+
+**步骤 1：开启无线调试**
+
+在设备上进入：系统 → 开发者选项 → 无线调试，开启无线调试功能。
+
+**步骤 2：配置 hdc 命令路径**
+
+将 hdc 工具路径添加到环境变量：
+
+```bash
+export PATH=$PATH:path/to/deveco_tools/sdk/default/openharmony/toolchains
+```
+
+**步骤 3：通过 hdc 命令自连**
+
+使用 hdc 命令连接设备的 IP 和端口：
+
+```bash
+hdc tconn IP:端口
+```
+
+连接成功后，即可使用 `devecocli run` 命令推包运行应用。
+
 
 ## 开发
 

package/SKILL.md

@@ -1,13 +1,18 @@
----
+---
 name: deveco-cli
 description: >-
-  **MUST** use 'devecocli' for HarmonyOS apps (scaffold, build, run, debug, devices, emulators, logs, docs, 鸿蒙开发文档, skills). **REQUIRED** and **MANDATORY** if workspace has build-profile.json5 or oh-package.json5, or user mentions HarmonyOS, 鸿蒙, DevEco, ArkTS, ArkUI, docs, 鸿蒙文档, 知识, 搜索, or skills.
+  **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/预览/预览器/多预览器/多设备预览器.
 ---
 
 # DevEco CLI
 
 `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)
+- ❌ `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`.
 
 **Sandbox Rule**: Commands tagged `[Outside sandbox]` must be run outside the sandbox.
@@ -60,6 +65,12 @@ 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.
 
 ### `devecocli log`
 Fetch hilog or crash logs. Req `--device <name|serial>` on multi-device hosts.
@@ -98,6 +109,13 @@ 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
 - **Diagnose crash**:
   `devecocli log --crash --bundle-name <bundle>`
 - **Release build**:
@@ -114,3 +132,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.