@deveco-test/deveco-cli 1.3.0-Test.8 → 1.3.0-Test.9

package/README.md

@@ -5,8 +5,9 @@
     <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://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" />
+    <img src="https://img.shields.io/badge/platform-macOS%20%7C%20Windows%20%7C%20Linux-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/Command%20Line%20Tools-%3E%3D26.0.0-orange.svg" alt="Command Line Tools" />
     <a href="./LICENSE"><img src="https://img.shields.io/badge/license-MIT-green.svg" alt="License" /></a>
   </p>
 </div>
@@ -18,9 +19,9 @@
 
 ### 前置要求
 
-- 操作系统为 `macOS` 或 `Windows`
+- 操作系统为 `macOS` 、 `Windows` 或 `Linux`（需配置对应环境变量）
 - Node.js >= 18，推荐使用22及以上版本
-- [DevEco Studio](https://developer.huawei.com/consumer/cn/download/) >= 6.1.0
+- [DevEco Studio](https://developer.huawei.com/consumer/cn/download/) >= 6.1.0 或 [Command Line Tools](https://developer.huawei.com/consumer/cn/download/)  >= 26.0.0
   - **macOS**：必须安装在 `~/Applications` 或 `/Applications` 目录下。
 
 ### 安装
@@ -53,6 +54,41 @@ devecocli docs read harmonyos-guides/application-models/arkts-page-start-overvie
 
 更多命令和参数可通过 `devecocli --help` 或各子命令的 `--help` 查看。
 
+## 环境变量
+
+`devecocli` 当需要使用非默认安装路径、多版本并存时固定选型，Command Line Tools或在Linux下运行时，可通过以下环境变量显式指定工具链根：
+
+| 名称                     | 说明                                                   |
+| ------------------------ | ------------------------------------------------------ |
+| `DEVECO_CLI_STUDIO_PATH` | 显式指定 DevEco Studio 安装根，优先级最高              |
+| `DEVECO_CLI_CLT_PATH`    | 显式指定 Command Line Tools 安装根 |
+
+完整优先级链：
+
+```text
+DEVECO_CLI_STUDIO_PATH > DEVECO_CLI_CLT_PATH > Auto_Detect
+```
+
+### 平台与版本约束
+
+| 平台    | DevEco Studio Auto_Detect                     | Command Line Tools | 最低版本                      |
+| ------- | --------------------------------------------- | ------------------ | ----------------------------- |
+| Windows | 支持                                          | 可选               | Studio `6.1.0` / CLT `26.0.0` |
+| macOS   | 支持                                          | 可选               | 同上                          |
+| Linux   | 不支持                                        | 必选               | CLT `26.0.0`                  |
+
+### 使用示例
+
+```bash
+# 设置 DevEco Studio
+export DEVECO_CLI_STUDIO_PATH="/Applications/DevEco-Studio.app" （可带或不带尾部 Contents）
+devecocli device list
+
+# 设置 CLT
+export DEVECO_CLI_CLT_PATH=/opt/command-line-tools
+devecocli device list
+```
+
 ## AI Agent 集成
 
 `DevEco CLI` 支持通过命令行将自身技能添加到 `Agent` 中。下面以 `opencode` 为例展示最短流程：
@@ -92,6 +128,9 @@ devecocli init --path D:\work\ARKTS\NewData
 | `devecocli device list`   | 查看当前连接设备                                  |
 | `devecocli emulator list` | 查看本地模拟器实例                                 |
 | `devecocli ui screenshot` | 对真机或模拟器执行 UI 截图                          |
+| `devecocli ui click`      | 点击指定坐标或节点 ID                             |
+| `devecocli ui swipe`      | 自定义滑动（指定起点、终点和速度）                   |
+| `devecocli ui text`       | 输入文本到焦点或指定位置                            |
 | `devecocli log`           | 查看 `hilog` 或崩溃日志                          |
 | `devecocli docs search`   | 搜索本地 HarmonyOS 文档                         |
 | `devecocli init`          | 安装内置技能或配置 `MCP`                           |
@@ -126,6 +165,7 @@ Commands:
   update                 Update deveco-cli to the latest version
   device                 Manage connected devices
   emulator               Manage emulator instances
+  auth                   Authentication commands (login, logout, status, team)
   ui                     Inspect and interact with UI on a connected device
   skills                 Manage HarmonyOS skills
   log [options]          Obtain device application logs
@@ -272,6 +312,56 @@ devecocli create --project-path ./MyApp --app-name MyApp --bundle-name com.acme.
 devecocli create --app-name MyApp
 ```
 
+### `auth login`
+
+登录华为开发者账号，打开浏览器完成授权。
+
+**命令格式：**
+
+```bash
+devecocli auth login
+```
+
+**说明：**
+
+- 海外账户暂不支持
+
+### `auth logout`
+
+登出并清除本地存储的凭据
+
+**命令格式：**
+
+```bash
+devecocli auth logout
+```
+
+### `auth status`
+
+显示当前登录的用户
+
+**命令格式：**
+
+```bash
+devecocli auth status
+```
+
+### `auth team list`
+
+列出当前用户已加入的团队
+
+**命令格式：**
+
+```bash
+devecocli auth team list
+```
+
+**示例：**
+
+```bash
+devecocli auth team list
+```
+
 ### `build`
 
 编译并打包 HarmonyOS 工程或工程中的模块
@@ -436,40 +526,6 @@ devecocli emulator sensor --target Phone --heartrate 80
   校验以目标模拟器实际返回的 `deviceType` 为准。非上述三种设备类型以及不属于目标设备类型的状态会在命令下发前被拒绝。校验通过后，底层映射为 `Emulator -instance <name> -foldedState <state>`。
 - 设置 `DEVECO_CLI_DEBUG=1` 可查看底层命令映射，例如 `Emulator -instance <name> -shake`。
 
-### `ui screenshot`
-
-对真机或模拟器执行 UI 截图。`devecocli ui` 当前只交付截图能力。
-
-**命令格式：**
-
-```bash
-devecocli ui screenshot [--device <name|serial>] [--path <path>]
-```
-
-**参数：**
-
-| 参数                       | 说明                       | 默认值       |
-| ------------------------ | ------------------------ | ---------- |
-| --device \<name\|serial> | 真机或模拟器名称/序列号；多设备时必填     | 单设备自动选择 |
-| --display \<displayId>   | 目标屏幕 ID，可选                | 默认屏幕     |
-| --path \<path>           | 截图输出路径，可选；目录或父目录必须已存在 | `./screenshot-<timestamp>.png` |
-
-**示例：**
-
-```bash
-devecocli ui screenshot --device Phone
-mkdir -p screenshots
-devecocli ui screenshot --device Phone --path ./screenshots/phone.png
-devecocli ui screenshot --device Phone --display 0 --path ./screenshots/phone.png
-```
-
-**说明：**
-
-- `ui screenshot` 支持真机和模拟器。
-- 仅有一个可用设备时可省略 `--device`，多个设备同时连接时必须指定。
-- 截图能力统一通过 `ui screenshot` 提供，不放在模拟器场景操作命令中。
-- 截图统一使用 `hdc shell snapshot_display` 和 `hdc file recv` 实现；设置 `DEVECO_CLI_DEBUG=1` 可查看实际执行命令。
-
 ### `emulator create`
 
 创建模拟器
@@ -659,6 +715,264 @@ devecocli device view --target 127.0.0.1:5555
 devecocli device view -t "My Device Name"
 ```
 
+### `ui screenshot`
+
+对真机或模拟器执行 UI 截图。
+
+**命令格式：**
+
+```bash
+devecocli ui screenshot --device <name|serial> --display <displayId> --path <path>
+```
+
+**参数：**
+
+| 参数                       | 说明                       | 默认值       |
+| ------------------------ | ------------------------ | ---------- |
+| --device \<name\|serial> | 真机或模拟器名称/序列号；多设备时必填     | 单设备自动选择 |
+| --display \<displayId>   | 目标屏幕 ID，可选                | 默认屏幕     |
+| --path \<path>           | 截图输出路径，可选；目录或父目录必须已存在 | `./screenshot-<timestamp>.png` |
+
+**示例：**
+
+```bash
+devecocli ui screenshot --device Phone
+mkdir -p screenshots
+devecocli ui screenshot --device Phone --path ./screenshots/phone.png
+devecocli ui screenshot --device Phone --display 0 --path ./screenshots/phone.png
+```
+
+**说明：**
+
+- `ui screenshot` 支持真机和模拟器。
+- 仅有一个可用设备时可省略 `--device`，多个设备同时连接时必须指定。
+- 截图能力统一通过 `ui screenshot` 提供，不放在模拟器场景操作命令中。
+- 截图统一使用 `hdc shell snapshot_display` 和 `hdc file recv` 实现；设置 `DEVECO_CLI_DEBUG=1` 可查看实际执行命令。
+
+### `ui click`
+
+点击指定坐标或节点 ID 的中心位置。
+
+**命令格式：**
+
+```bash
+devecocli ui click [x] [y] --device <name|serial> --id <id> --window <windowId>
+```
+
+**参数：**
+
+| 参数 | 说明 |
+| --- | --- |
+| `[x] [y]` | 可选，目标坐标。缺省时需配合 `--id` 使用 |
+| --device \<name\|serial> | 目标设备，多设备时必填 |
+| --id \<id> | 节点 ID，自动解析为中心坐标。不可与 `[x] [y]` 同时使用 |
+| --window \<windowId> | 目标窗口 ID，需与 `--id` 配合使用 |
+
+**示例：**
+
+```bash
+devecocli ui click 100 200
+devecocli ui click 100 200 --device Phone
+devecocli ui click --id submit_button
+devecocli ui click --id submit_button --window main_window
+```
+
+### `ui doubleclick`
+
+双击指定坐标或节点 ID 的中心位置。
+
+**命令格式：**
+
+```bash
+devecocli ui doubleclick [x] [y] --device <name|serial> --id <id> --window <windowId>
+```
+
+**参数：**
+
+| 参数 | 说明 |
+| --- | --- |
+| `[x] [y]` | 可选，目标坐标。缺省时需配合 `--id` 使用 |
+| --device \<name\|serial> | 目标设备，多设备时必填 |
+| --id \<id> | 节点 ID，自动解析为中心坐标。不可与 `[x] [y]` 同时使用 |
+| --window \<windowId> | 目标窗口 ID，需与 `--id` 配合使用 |
+
+**示例：**
+
+```bash
+devecocli ui doubleclick 100 200
+devecocli ui doubleclick 100 200 --device Phone
+devecocli ui doubleclick --id photo_thumb
+devecocli ui doubleclick --id photo_thumb --window main_window
+```
+
+### `ui longclick`
+
+长按指定坐标或节点 ID 的中心位置。
+
+**命令格式：**
+
+```bash
+devecocli ui longclick [x] [y] --device <name|serial> --id <id> --window <windowId>
+```
+
+**参数：**
+
+| 参数 | 说明 |
+| --- | --- |
+| `[x] [y]` | 可选，目标坐标。缺省时需配合 `--id` 使用 |
+| --device \<name\|serial> | 目标设备，多设备时必填 |
+| --id \<id> | 节点 ID，自动解析为中心坐标。不可与 `[x] [y]` 同时使用  |
+| --window \<windowId> | 目标窗口 ID，需与 `--id` 配合使用 |
+
+**示例：**
+
+```bash
+devecocli ui longclick 100 200
+devecocli ui longclick 100 200 --device Phone
+devecocli ui longclick --id menu_item
+devecocli ui longclick --id menu_item --window main_window
+```
+
+### `ui swipe`
+
+自定义滑动（指定起点、终点和速度）。
+
+**命令格式：**
+
+```bash
+devecocli ui swipe <x1> <y1> <x2> <y2> --device <name|serial> --speed <n>
+```
+
+**参数：**
+
+| 参数 | 说明 |
+| --- | --- |
+| `<x1> <y1> <x2> <y2>` | 必选，起点和终点坐标 |
+| --device \<name\|serial> | 目标设备，多设备时必填 |
+| --speed \<n> | 可选，滑动速度（像素/秒），范围 `200` ~ `40000` |
+
+**示例：**
+
+```bash
+devecocli ui swipe 100 500 100 200
+devecocli ui swipe 100 500 100 200 --device Phone
+devecocli ui swipe 100 500 100 200 --speed 1000
+```
+
+### `ui fling`
+
+快速滑动（Fling）。
+
+**命令格式：**
+
+```bash
+devecocli ui fling <x1> <y1> <x2> <y2> --device <name|serial> --speed <n>
+```
+
+**参数：**
+
+| 参数 | 说明 |
+| --- | --- |
+| `<x1> <y1> <x2> <y2>` | 必选，起点和终点坐标 |
+| --device \<name\|serial> | 目标设备，多设备时必填 |
+| --speed \<n> | 可选，滑动速度（像素/秒），范围 `200` ~ `40000` |
+
+**示例：**
+
+```bash
+devecocli ui fling 100 800 100 200
+devecocli ui fling 100 800 100 200 --device Phone
+devecocli ui fling 100 800 100 200 --speed 3000
+```
+
+### `ui drag`
+
+拖拽操作。
+
+**命令格式：**
+
+```bash
+devecocli ui drag <x1> <y1> <x2> <y2> --device <name|serial> --speed <n>
+```
+
+**参数：**
+
+| 参数 | 说明 |
+| --- | --- |
+| `<x1> <y1> <x2> <y2>` | 必选，起点和终点坐标 |
+| --device \<name\|serial> | 目标设备，多设备时必填 |
+| --speed \<n> | 可选，滑动速度（像素/秒），范围 `200` ~ `40000` |
+
+**示例：**
+
+```bash
+# 拖拽操作
+devecocli ui drag 100 500 100 200
+devecocli ui drag 100 500 100 200 --device Phone
+devecocli ui drag 100 500 100 200 --speed 1500
+```
+
+### `ui dircfling`
+
+向指定方向快速滑动。
+
+**命令格式：**
+
+```bash
+devecocli ui dircfling <direction> --device <name|serial>
+```
+
+**参数：**
+
+| 参数 | 说明 |
+| --- | --- |
+| `<direction>` | 必选，方向，取值为 `up`, `down`, `left`, `right` |
+| --device \<name\|serial> | 目标设备，多设备时必填 |
+
+**示例：**
+
+```bash
+devecocli ui dircfling up
+devecocli ui dircfling down --device Phone
+devecocli ui dircfling left
+devecocli ui dircfling right
+```
+
+**与 `ui swipe` 的区别：**
+
+- `ui swipe` 需要指定精确的起点和终点坐标，支持自定义速度，适用于特定区域滑动。
+- `ui dircfling` 仅需指定方向，使用系统默认速度，适用于页面滚动或列表快速滑动。
+
+### `ui text`
+
+输入文本到当前焦点、指定坐标或指定节点位置。
+
+**命令格式：**
+
+```bash
+devecocli ui text <text> [x] [y] --device <name|serial> --id <id> --window <windowId>
+```
+
+**参数：**
+
+| 参数 | 说明 |
+| --- | --- |
+| `<text>` | 必选，待输入的文本 |
+| `[x] [y]` | 可选，目标坐标 |
+| --device \<name\|serial> | 目标设备，多设备时必填 |
+| --id \<id> | 节点 ID，自动解析为中心坐标。不可与 `[x] [y]`同时使用 |
+| --window \<windowId> | 目标窗口 ID，需与 `--id` 配合使用 |
+
+**示例：**
+
+```bash
+devecocli ui text "Hello World"
+devecocli ui text "Hello World" --device Phone
+devecocli ui text "Hello World" 100 200
+devecocli ui text "Hello World" --id search_box
+devecocli ui text "Hello World" --id search_box --window main_window
+```
+
 ### `run`
 
 构建应用后，将应用安装到真机设备或模拟器上，并启动执行

package/SKILL.md

@@ -8,7 +8,7 @@ description: >-
 
 `devecocli` wraps DevEco Studio's `hvigor`, `ohpm`, `hdc`, emulator toolchain, and bundled skills installer. **Prefer `devecocli` over invoking underlying tools directly.**
 
-Available commands: `build`, `check`, `run`, `update`, `device`, `emulator`, `ui`, `skills`, `log`, `create`, `init`, `serve`, `docs`, `signature`, `login`, `logout`, `whoami`.
+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.
 
@@ -88,7 +88,7 @@ Build, install, and launch.
 
 ### `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 login` first; run from a project directory (with `build-profile.json5`); a connected device or emulator is required for device registration.
+- **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.
@@ -119,15 +119,16 @@ Inspect UI on a connected device. All subcommands accept `--device <name|serial>
 | `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 | `--speed <n>` (200–40000, px/s) |
+| `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>` | Fling in a fixed direction | `direction`: `up`, `down`, `left`, `right` |
+| `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 and `--id` are mutually exclusive. Provide either `x y` or `--id <id>`; for `text`, if neither is given the text goes to the currently focused field.
-- `--window <windowId>` may only be used together with `--id`.
-- Default: focused window only. Use `--window <id>` or `--all-windows` to target specific/all windows (mutually exclusive).
+- **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 raw`: 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.
@@ -146,16 +147,19 @@ MUTUALLY EXCLUSIVE modes for setup:
 - `-f, --force`: Overwrite existing config.
 *MCP Rules*: Global MCP (no `--project`) only supports `opencode` and `cursor`. Others require `--project`.
 
-### `devecocli login`
+### `devecocli auth login`
 Sign in to your Huawei Developer account. Opens a browser for OAuth authentication. Required before `signature generate`.
-*Ex*: `devecocli login`
+*Ex*: `devecocli auth login`
 
-### `devecocli logout`
+### `devecocli auth logout`
 Sign out and clear locally stored credentials.
 
-### `devecocli whoami`
+### `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.
@@ -191,7 +195,7 @@ Validation order: `files` + `--modules` mutually exclusive → `--source-version
 - **Release build**:
   `devecocli build --product oversea --build-mode release`
 - **First-time signing setup**:
-  `devecocli login` -> `devecocli signature generate --product default` -> `devecocli build` -> `devecocli run`
+  `devecocli auth login` -> `devecocli signature generate --product default` -> `devecocli build` -> `devecocli run`
 
 ## Troubleshooting
 
@@ -199,9 +203,9 @@ Validation order: `files` + `--modules` mutually exclusive → `--source-version
 - **"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 login first`**: Run `devecocli login` to authenticate.
+- **`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 login` again.
+- **`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`.
 - **`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`. Agents cannot run the interactive form; suggest the user run it, or use `license accept` if a non-TTY flow is acceptable. 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.

package/THIRD-PARTY-LICENSES

@@ -2763,7 +2763,7 @@ OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 
 The following npm packages may be included in this product:
 
- - @node-rs/jieba-darwin-arm64@2.0.1
+ - @node-rs/jieba-linux-x64-gnu@2.0.1
  - agent-base@6.0.2
  - https-proxy-agent@5.0.1
  - isarray@0.0.1
@@ -4000,7 +4000,7 @@ The following npm packages may be included in this product:
  - ini@1.3.8
  - isexe@2.0.0
  - once@1.4.0
- - semver@7.7.4
+ - semver@7.8.5
  - which@2.0.2
  - wrappy@1.0.2