# @deveco/deveco-cli-common 中文文档

规范地址：https://npmcn.com/package/%40deveco/deveco-cli-common/

版本：1\.3\.12
npm 元数据更新时间：2026-11-11T07:50:35.655Z
中文译文更新时间：2026-11-12T02:38:44.087Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40deveco/deveco-cli-common
原文对照：https://npmcn.com/package/%40deveco/deveco-cli-common/?lang=original

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：6.6 MB，254 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- Node.js 要求：\>=22
- 运行依赖：22 个
- 首次发布：2026-09-22T11:30:47.947Z
- 最新版本发布：2026-11-10T09:56:54.992Z
- 近 30 天下载量：10831（2026-10-12 至 2026-11-10，npm 官方下载统计）
- 已发布版本数：9（近 12 个月 9 个）

## 中文简介

HarmonyOS 应用程序开发命令行工具

## 安装

```sh
npm install @deveco/deveco-cli-common
```

也可以使用：`pnpm add @deveco/deveco-cli-common`、`yarn add @deveco/deveco-cli-common`、`bun add @deveco/deveco-cli-common`

## README

# DevEco CLI

一个面向 HarmonyOS 应用开发的统一命令行入口。

[![NPM Version](https://img.shields.io/npm/v/@deveco/deveco-cli.svg)](https://www.npmjs.com/package/@deveco/deveco-cli) [![NPM Downloads](https://img.shields.io/npm/dm/@deveco/deveco-cli.svg)](https://www.npmjs.com/package/@deveco/deveco-cli) [![Node.js](https://img.shields.io/badge/Node.js-%3E%3D22-green.svg)](https://nodejs.org/) ![Platform](https://img.shields.io/badge/platform-macOS%20%7C%20Windows%20%7C%20Linux-blue.svg) [![DevEco Studio](https://img.shields.io/badge/DevEco%20Studio-%3E%3D6.0.0-orange.svg)](https://developer.huawei.com/consumer/cn/download/) ![Command Line Tools](https://img.shields.io/badge/Command%20Line%20Tools-%3E%3D26.0.0-orange.svg) [![License](https://img.shields.io/badge/license-MIT-green.svg)](https://npmcn.com/package/%40deveco/deveco-cli-common/LICENSE)

`DevEco CLI` 将 `DevEco Studio` 工具链统一封装为一个 `CLI`，内置 `ohpm`、`hvigor`、`hdc`、`emulator`、`hilog`，同时集成 HarmonyOS 技能安装、项目脚手架、本地 HarmonyOS 文档检索和 `MCP` 服务。

> 关于数据采集与隐私（遥测打点内容、存储加密、上报及关闭方式），请参阅 [PRIVACY.md](https://npmcn.com/package/%40deveco/deveco-cli-common/PRIVACY.md)。

## 快速开始

### 前置要求

-   操作系统为 `macOS` 、 `Windows` 或 `Linux`（需配置对应环境变量）
-   安装`Node.js`，推荐使用22及以上版本
-   [DevEco Studio](https://developer.huawei.com/consumer/cn/download/) >= 6.0.0 或 [Command Line Tools](https://developer.huawei.com/consumer/cn/download/) >= 26.0.0
    -   **macOS**：必须安装在 `~/Applications` 或 `/Applications` 目录下。

### 安装

```bash
npm install -g @deveco/deveco-cli@latest
```

安装后可以通过以下命令更新到最新版本：

```bash
devecocli update
```

### 最短工作流

```bash
devecocli create --app-name MyApp
cd MyApp
devecocli run
devecocli log --level E
```

### 文档检索

```bash
devecocli docs search List
devecocli docs read guides/harmonyos-guides/指南/系统/网络/网络
```

更多命令和参数可通过 `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.0.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
```

## 区域与海外支持

`devecocli` 支持中国大陆（CN）、香港（HK）和澳门（MO）三个区域。其他地区的在线能力（登录、签名、协议查询、镜像下载、知识库下载等）不可用，纯本地命令（`create`/`build`/`device` 等）不受影响。

港澳地区（HK/MO）下，Skills 市场云端命令（`skills list`/`find`/`add`）不可用；已安装 skills 为本地文件，不受影响。

## AI Agent 集成

### Agent 插件

支持插件的 Agent 可加载 DevEco CLI 插件，获得内置 Skill 和 CLI 检查、安装及调用能力。

插件使用方法见 [插件说明](https://npmcn.com/package/%40deveco/deveco-cli-common/.plugin/README.md)，支持的 Agent 及其差异由 [平台配置](https://npmcn.com/package/%40deveco/deveco-cli-common/.plugin/platforms.json) 定义。

### 命令行安装 Skill / MCP

`DevEco CLI` 支持通过命令行将自身技能添加到 `Agent` 中。下面以 `opencode` 为例展示最短流程：

```bash
# 1. 给 opencode 安装 deveco-cli 技能
devecocli init --agent opencode

# 2. 给 opencode 在当前 HarmonyOS 项目配置 MCP
devecocli init --mcp --agent opencode --project ./MyApp

# 3. 进入项目并启动 opencode
cd MyApp
opencode
```

也支持 `atomcode`等 Agent，使用方式相同：

```bash
# 给 atomcode 安装技能
devecocli init --agent atomcode
```

如果 `Agent` 不在 `--agent` 参数取值范围内，可使用 `--path` 参数进行添加，参考如下命令：

```bash
devecocli init --path D:\work\ARKTS\NewData
```

进入 `Agent` 后可以直接描述任务，例如：

-   `Build this project in release mode and run it on my emulator`
-   `Tail the last error logs from this app`
-   `Check for syntax errors in src/main/ets/pages/Index.ets`

**说明：**

-   在`Windows`上搭配`devecocli`使用`opencode`时，推荐将[powershell 7](https://learn.microsoft.com/en-us/powershell/scripting/install/install-powershell-on-windows?view=powershell-7.6) 作为默认执行终端。
-   在`Windows`上用`opencode`执行devecocli build/emulator start等指令时，若命令结束后终端无法正常退出，建议将默认终端切换为[powershell 7](https://learn.microsoft.com/en-us/powershell/scripting/install/install-powershell-on-windows?view=powershell-7.6)

## 常用命令

| 命令 | 用途 |
| --- | --- |
| `devecocli create` | 创建新的 HarmonyOS 项目 |
| `devecocli build` | 构建项目并产出 `.hap` / `.hsp` / `.har` / `.app` |
| `devecocli check lint` | 检查代码规范并输出实践建议与报告 |
| `devecocli check arkts` | 对 `.ets` 源文件执行 ArkTS 静态检查 |
| `devecocli run` | 安装并运行应用 |
| `devecocli device list` | 查看当前连接设备 |
| `devecocli emulator list` | 查看本地模拟器实例 |
| `devecocli ui layout` | 导出设备屏幕上的 UI 节点树（布局、坐标、节点 ID） |
| `devecocli ui window list` | 查看设备窗口列表（为 `ui layout` / `ui click` 等提供窗口 ID） |
| `devecocli ui screenshot` | 对真机或模拟器执行 UI 截图 |
| `devecocli ui click` | 点击指定坐标、节点 ID 或 Selector 定位的元素 |
| `devecocli ui swipe` | 自定义滑动（坐标模式或 `--start`/`--end` 元素模式） |
| `devecocli ui text` | 输入文本到焦点或指定位置，支持 `--selector` 指定控件 |
| `devecocli log` | 查看 `hilog` 或崩溃日志 |
| `devecocli verify` | 根据自然语言测试计划执行 UI 意图校验 |
| `devecocli verify appanalyzer` | 对应用和元服务执行本地测试体检 |
| `devecocli testing` | 透传 DevEco Testing 检测服务（内存泄漏、稳定性、性能、UX、上架预检） |
| `devecocli docs search` | 搜索本地 HarmonyOS 文档 |
| `devecocli docs update` | 更新 HarmonyOS 文档到最新兼容版本 |
| `devecocli init` | 安装内置技能或配置 `MCP` |
| `devecocli skills` | 管理内置与技能市场中的 HarmonyOS 技能 |
| `devecocli plugin` | 管理白名单内的 AI 智能体插件（npm 包形式，装/卸/更新行为由插件定义） |
| `devecocli signature generate` | 自动生成调试签名材料并配置到项目 |
| `devecocli check compat` | 扫描源代码在两个 `SDK` 版本之间的 `API` 变更 |

## 命令集

### `help`

查看版本、帮助信息以及所有子命令

**命令格式：**

```bash
devecocli help
```

```text
# 返回结果
Usage: devecocli [options] [command]

HarmonyOS application development command line tool

Options:
  -V, -v, --version      output the version number
  -h, --help             display help for command

Commands:
  build [options]        Build the HarmonyOS project
  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
  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
  verify [options]       Run UI verification on a connected device
  create [options]       Scaffold a new HarmonyOS application project
  init [options]         Install bundled skills or configure the deveco-mcp server into AI agents
  serve                  Host bundled auxiliary protocol servers
  docs [options]         Search and read HarmonyOS documentation from local docs directory
  check                  Run DevEco project checks
  signature              Generate application signature
  help [command]         display help for command
```

### `design2arkts`（别名 `d2a`）

从 Pixso/Figma 设计稿开发 ArkUI 页面：CLI 提供输入快照、导出、资源准备与受保护导入工具，Agent 按内置 Skill 指引完成分析与生成；完整流程、独立能力（视觉校准、HDS 迁移、React 转换、方案设计）、参数与导入保护见 [D2A 使用指南](https://npmcn.com/package/%40deveco/deveco-cli-common/docs/design2arkts.md)。

方案设计聚焦 UI 页面，仓库分析限于目标页面及关联代码；Pixso 流程由工程理解进入方案设计，组件选型在方案设计中完成。

### `init`

将内置 `Skill`（`deveco-cli`、`hmos-arkui-develop-skill`、`hmos-dfx-analyzer`）或者 `MCP` 服务配置到智能体中。内置 `Skill` 以软链接方式直连 CLI 包内目录，已安装的链接随 `npm update` 自动更新内容。

**已有 Skill 和 MCP 配置默认跳过。更新已有内容或将复制安装的 Skill 改为软链接，需执行 `devecocli init -f`（或 `--force`），旧内容及本地修改会被删除。** 可用 `--agent`、`--project` 或 `--path` 选择位置；`-f` 也允许创建不存在的目标目录。正确安装的软链接随 CLI 更新生效，不需要重复 `init`；建链失败时回退为复制。CLI 升级新增的内置技能需重新执行 `devecocli init` 安装。

**命令格式：**

```bash
devecocli init --agent <agents> --project <path> --path <path> --skill --mcp --with-homegraph --force
```

**参数：**

| 参数名 | 说明 |
| --- | --- |
| \--agent | 可选，智能体名称，多个智能体名称以英文逗号分隔。缺省时配置到所有已检测到的智能体中 |
| \--project | 可选，指定工程路径，将内置 `Skill` 或 `MCP` 服务安装到该工程项目中 |
| \--path | 可选，指定内置 `Skill` 的配置路径。不可与 `--project` 、`--agent` 、 `--mcp` 同时使用 |
| \--skill | 可选，安装全部内置 `Skill`。不可与 `--mcp` 同时使用。`--mcp` 与 `--skill` 都缺省时，执行 `--skill` |
| \--mcp | 可选，配置 `MCP` 服务，与 `--project` 一起使用表示配置工程级 `MCP` 服务，独立使用表示配置用户级 `MCP` 服务。不可与 `--skill` 同时使用 |
| \--with-homegraph | 可选，仅可与 `--mcp` 同用：额外安装 `homegraph` CLI，并在同一 Agent MCP 配置中写入并列的 `homegraph` 条目；会记录 opt-in，供后续 `devecocli update` 升级 |
| \-f, --force | 可选，直接替换已有 Skill 或 MCP 配置，并允许创建不存在的目标目录 |

**示例：**

```bash
# 配置Skill
devecocli init -f   # 安装或更新全部内置 Skill
devecocli init --skill
devecocli init --agent agentname    # agentname需替换为实际的智能体名称
devecocli init --path D:\work\ARKTS\NewData -f

# 配置MCP
devecocli init --mcp
devecocli init --mcp --agent agentname    # agentname需替换为实际的智能体名称   
devecocli init --mcp --project D:\work\ARKTS\NewData -f
devecocli init --mcp --with-homegraph
```

> MCP 配置支持 `opencode`、`pi`、`trae-cn`、`cursor`、`codebuddy`、`claude-code` 和 `codex`。

### Skill 支持的智能体

支持以下 52 个智能体。使用 `--agent` 指定名称，多个名称用英文逗号分隔。

`amp`、`antigravity`、`antigravity-cli`、`astrbot`、`atomcode`、`augment`、`bob`、`claude-code`、`cline`、`codearts-agent`、 `codebuddy`、`codex`、`continue`、`crush`、`cursor`、`deepagents`、`deveco`、`devin`、`droid`、`dsh`、 `gemini-cli`、`github-copilot`、`goose`、`grok`、`hermes-agent`、`iflow-cli`、`junie`、`kilo`、`kimi-code-cli`、`kiro-cli`、 `kode`、`lingma`、`minimax-code`、`mistral-vibe`、`neovate`、`ona`、`openclaw`、`opencode`、`openhands`、`pi`、 `qoder`、`qoder-cn`、`qwen-code`、`reasonix`、`replit`、`trae`、`trae-cn`、`universal`、`warp`、`windsurf`、 `zcode`、`zed`。

未检测到智能体时，可显式指定 `--agent` 安装。

### `docs search`

将关键词搜索版本说明、指南、API参考、最佳实践、`FAQ` 、变更预告等中的内容

**命令格式：**

```bash
devecocli docs search <keywords...> --catalog <name> --format <fmt> --limit <n>
```

**参数：**

| 参数名 | 说明 |
| --- | --- |
| keywords... | 必选，搜索关键词，多个关键词用空格隔开 |
| \--catalog | 可选，文档类别，取值包含`harmonyos-releases`（版本说明）、 `harmonyos-guides`（指南）、`harmonyos-references`（API参考）、`best-practices`（最佳实践）、`harmonyos-faqs`（FAQ）、`harmonyos-roadmap`（变更预告）、`all`（所有分类，默认） |
| \--format | 可选，控制输出格式，取值包括 `default` 、`json` ，默认为`default` ，输出结果包括文档ID、标题、文档的概括内容 |
| \--limit | 可选，设置搜索结果返回条数，默认为10 |

**示例：**

```bash
devecocli docs search 沉浸光感
devecocli docs search '@State' '@Prop' --catalog best-practices --limit 10
devecocli docs search Row Column --format json
```

### `docs read`

按文档ID查询文档的完整内容

**命令格式：**

```bash
devecocli docs read <documentId> 
```

**参数：**

| 参数名 | 说明 |
| --- | --- |
| documentId | 必选，文档ID |

**示例：**

```bash
devecocli docs read guides/harmonyos-guides/指南/系统/网络/网络
```

### `docs catalog`

查询文档分类和分类名称

**命令格式：**

```bash
devecocli docs catalog --format <fmt> 
```

**参数：**

| 参数名 | 说明 |
| --- | --- |
| \--format | 可选，输出格式，`default` 或 `json` ，默认为 `default` |

**示例：**

```bash
devecocli docs catalog 
devecocli docs catalog --format json
```

### `create`

创建 HarmonyOS 应用工程，仅支持创建工程模板中的 `Empty Ability` 模板

**命令格式：**

```bash
devecocli create --app-name <name> --project-path <path> --bundle-name <bundle> --api-level <level> --device-types <types...>
```

**参数：**

| 参数名 | 说明 |
| --- | --- |
| \--app-name | 必选，应用名称 |
| \--project-path | 可选，工程路径，默认为：`./<appname>` |
| \--bundle-name | 可选，包名，默认为：`com.example.<appname>` ，`appname` 自动转为小写 |
| \--api-level | 可选，API级别，最小值为17，最大值从安装的 `Deveco Studio` 的 `HarmonyOS` `SDK` 中自动获取 |
| \--device-types | 可选，设备类型，可指定多个，写入 `module.json5` 的 `deviceTypes`，默认为 `phone`。支持 `phone`、`tablet`、`2in1`、`car`、`wearable`、`tv`；取值不在列表内时报错并列出全部合法值 |

**示例：**

```bash
devecocli create --project-path ./MyApp --app-name MyApp
devecocli create --project-path ./MyApp --app-name MyApp --bundle-name com.acme.myapp --api-level 23
devecocli create --app-name MyApp
devecocli create --app-name MyApp --device-types tablet
devecocli create --app-name MyApp --device-types phone wearable
```

### `auth login`

登录华为开发者账号，打开浏览器完成授权。交互式终端会先等待按 Enter 再拉起浏览器；传入 `--no-prompt` 可跳过确认直接拉起浏览器（供 Agent / 非交互终端使用；stdin 不是 TTY 时自动跳过）。Agent 执行登录或安装时，沿用会话中已有的相应授权，仅在缺少授权时询问。登录已获授权时直接运行 `devecocli auth login --no-prompt`，不再要求用户手动执行命令；用户仍需在浏览器完成认证。

**命令格式：**

```bash
devecocli auth login --no-prompt
```

**说明：**

-   海外账户暂不支持

### `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 工程或工程中的模块

**命令格式：**

```bash
devecocli build --product <product> --modules <modules> --build-mode <mode> --signing-config <name> [--debug-line]
```

**参数：**

| 参数名 | 说明 |
| --- | --- |
| \--product | 可选，产品的名称，默认为 `default` |
| \--modules | 可选，模块的名称。如需指定模块的 `target` 信息，使用 `module@target` 形式。当工程中只有一个模块时，可缺省；当工程中存在多个模块，且仅存在一个 `entry` 类型的模块时，可缺省 |
| \--build-mode | 可选，构建模式，默认为 `debug` |
| \--signing-config | 可选，指定 `build-profile.json5` 中定义的签名配置名称，覆盖 product 默认关联的签名配置 |
| \--debug-line | 可选，向 hvigor 传入 `-p debugLine=true`；默认不传 |

**示例：**

```bash
devecocli build --build-mode release
devecocli build --modules entry library
devecocli build --modules library@phone
devecocli build --product oversea --modules entry --build-mode release
devecocli build --product oversea --modules entry --build-mode release --signing-config default_release
```

**说明：**

-   选定模块的依赖会被自动解析和构建
-   执行`devecocli build --product <name>`命令后，产物为 `.app`
-   执行`devecocli build --product <name> --modules <m1>`命令后，产物为 `.hap` / `.hsp` / `.har`
-   构建成功后，控制台会打印所有产物的绝对路径（`.hap` / `.hsp` / `.har` / `.app`），可直接复制使用

### `build clean`

清理 HarmonyOS 项目的构建产物。默认模块模式（`--mode module`）按模块逐个清理；可指定 `--mode` 和 `--modules` 限定作用域。构建选项（analyze/parallel/incremental/daemon 等）由 `hvigor-config.json5` 的 `execution` 字段控制，与 DevEco Studio 一致。

**命令格式：**

```bash
devecocli build clean [--mode <mode>] [--modules <m1> <m2>]
```

**参数：**

| 参数名 | 说明 |
| --- | --- |
| `--mode <mode>` | 可选，hvigor `--mode` 值（默认 `module`） |
| `--modules <modules>` | 可选，限定清理的模块（多个以空格分隔） |

### `check compat`

基于 `DevEco Studio` 自带的 `apkanalyzer-apiscan` 插件（≥ 26.0.0.810）或 Command Line Tools 内置的 `apicompat` 组件（≥ 26.0.1），扫描源代码在两个 `SDK` 版本之间的 `API` 变更情况。Linux 下需使用 Command Line Tools。

**子命令：**

| 子命令 | 说明 |
| --- | --- |
| `devecocli check compat` | 默认执行工程级扫描 |
| `devecocli check compat --modules <m1> [m2...]` | 按模块扫描 |
| `devecocli check compat <file1> [file2...]` | 按文件扫描（仅支持 `.ets`/`.c`/`.cpp`） |
| `devecocli check compat versions` | 列出可用的目标 `SDK` 版本 |

**命令格式：**

```bash
devecocli check compat [files...] --source-version <ver> --target-version <ver> [--modules <m...>] [--format <default|csv|json>] [--output-path <path>] [--limit <n>]
```

**参数：**

| 参数名 | 说明 |
| --- | --- |
| `--source-version` | 必填，当前工程 `SDK` 版本 |
| `--target-version` | 必填，目标 `SDK` 版本 |
| `--modules` | 可选，指定扫描的模块（多个以空格分隔）。与文件参数互斥 |
| `--format` | 可选，输出格式。`default`/`csv`/`json`。默认 `default`（控制台输出文本，文件输出 `csv`） |
| `--output-path` | 可选，报告输出路径。目录或文件（扩展名必须与 `--format` 匹配） |
| `--limit` | 可选，控制台显示的最大记录数，默认 `100` |

**版本号说明：**

-   可用版本可通过 `devecocli check compat versions` 查看
-   `zsh` 环境下版本号需用引号包裹（包含括号），例如 `"<source_version>"`、`"<target_version>"`

**`compat versions` 参数：**

| 参数名 | 说明 |
| --- | --- |
| `--format` | 可选，输出格式。`default` 或 `json`。默认 `default`（文本输出，每行一个版本号） |

**格式与输出组合：**

| 场景 | 允许的 `--format` | 行为 |
| --- | --- | --- |
| 控制台输出（无 `--output-path`） | `default` / `json` | `default` 输出文本表格，`json` 输出 `JSON` |
| 文件输出（`--output-path <file>`，扩展名必须匹配 `--format`） | `default` / `csv` / `json` | `default`/`csv` 写 `.csv` 文件；`json` 写 `.json` 文件 |
| 目录输出（`--output-path <dir>`，无扩展名） | `default` / `csv` / `json` | `default`/`csv` 生成 `apiChange-res{N}.csv`；`json` 生成 `apiChange-res{N}.json` |

**示例：**

```bash
# 工程级扫描，输出到控制台
devecocli check compat --source-version "<source_version>" --target-version "<target_version>"

# 输出 JSON 到控制台
devecocli check compat --format json --source-version "<source_version>" --target-version "<target_version>"

# 输出报告到目录（默认 csv）
devecocli check compat --output-path ./report --source-version "<source_version>" --target-version "<target_version>"

# 输出 JSON 报告到目录（生成 apiChange-res{N}.json）
devecocli check compat --output-path ./report --format json --source-version "<source_version>" --target-version "<target_version>"

# 输出报告到指定文件
devecocli check compat --output-path ./report.json --format json --source-version "<source_version>" --target-version "<target_version>"

# 文件级扫描
devecocli check compat ./entry/src/main/ets/pages/Index.ets --source-version "<source_version>" --target-version "<target_version>"

# 模块级扫描
devecocli check compat --modules entry har1 --source-version "<source_version>" --target-version "<target_version>"
```

### `check lint`

检查代码规范并输出实践建议与报告。

**命令格式：**

```bash
devecocli check lint [path]
```

**参数：**

| 参数名 | 说明 |
| --- | --- |
| `[path]` | 可选，待检查的文件或目录；默认使用 `build-profile.json5` 所在的项目根目录，否则使用当前目录 |
| `--config-path <path>` | Code Linter 配置文件路径，仅支持 `.json` 或 `.json5`；默认使用待检查项目根目录下的 `code-linter.json5`，显式指定时必须与待检查路径属于同一项目 |
| `--fix` | 自动修复可修复的问题 |
| `--incremental` | 仅检查 Git 未提交文件 |
| `--product <name>` | `build-profile.json5` 中定义的 product，默认为 `default` |
| `--format <default|json>` | 完整报告格式；`default` 输出 Markdown，`json` 输出 JSON；要求 DevEco Studio ≥ 6.1.0 |
| `--output-path <path>` | 完整报告文件或目录,目录形式会自动生成带时间戳的报告文件；要求 DevEco Studio ≥ 6.1.0 |
| `--limit <number>` | 未指定 `--output-path` 时，限制终端显示的问题数量 |

`emulator` 版本要求： DevEco Studio ≥ 6.1.0

### `check arkts`

对 `.ets` 源文件执行 ArkTS 静态检查，基于 DevEco Studio 的 `etsStandaloneChecker`。

**命令格式：**

```bash
devecocli check arkts [files...] [--fix] [--project <path>]
```

**参数：**

| 参数名 | 说明 |
| --- | --- |
| `[files...]` | 可选，待检查的 `.ets` 文件列表；默认检查项目内所有 `.ets` 文件 |
| `--fix` | 自动修复高置信度错误（如缺失的 `export` 关键字） |
| `--project <path>` | 项目根目录；默认从当前目录自动检测 `build-profile.json5` |

**示例：**

```bash
# 检查整个项目
devecocli check arkts

# 检查指定文件并自动修复
devecocli check arkts --fix entry/src/main/ets/pages/Index.ets

# 指定项目路径
devecocli check arkts --project /path/to/project
```

### `emulator list`

查看模拟器实例

**命令格式：**

```bash
devecocli emulator list [--format <table|json>]
devecocli emulator list --details
```

**参数：**

| 参数名 | 说明 |
| --- | --- |
| `--format` | 可选，控制终端输出格式，取值为 `table` 或 `json`，默认为 `table`；`json` 返回固定的五字段精简结构 |
| `--details` | 可选，直接输出底层 `Emulator -list -details` 的完整 JSON，不做任何字段裁剪、重命名或补充；与 `--format` 互斥 |

**示例：**

```bash
devecocli emulator list
devecocli emulator list --format json
devecocli emulator list --details
```

### `emulator start`

启动模拟器。首次使用时，需要签署 HarmonyOS 软件许可与服务协议，具体请参考 `emulator license`

**命令格式：**

```bash
devecocli emulator start [names...]
```

**参数：**

| 参数名 | 说明 |
| --- | --- |
| \[names...\] | 必选，模拟器实例名称，多个名称用空格隔开。若名称中带有空格，则名称需要添加英文引号 |
| \--hdcport <port> | 可选，指定模拟器的 hdc 端口号，取值范围 10000-16555，对应 Emulator 的 `-hdcport` 参数。 |
| \--boot-mode <mode> | 可选，指定模拟器启动方式，对应 Emulator 的 `-bootMode` 参数，可选值：`coldboot`（冷启动，保留上次使用的应用、文件等数据）、`snapshot`（热启动，加载上次关闭时保存的快照，需创建模拟器时启用 Quick Boot）、`reset`（清除数据后冷启动）。不指定时按创建模拟器时选择的方式启动（无法识别创建方式时默认 snapshot）。 |
| \--no-window | 可选，以无界面方式启动模拟器，对应 Emulator 的 `-noWindow` 参数；无图形界面的 Linux 环境必选。 |

**示例：**

```bash
devecocli emulator start Phone
devecocli emulator start Phone1 Phone2
devecocli emulator start Phone --hdcport 12345
devecocli emulator start Phone --boot-mode coldboot --no-window
```

**说明：**

-   `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` 场景操作

控制运行中的模拟器实例，直接映射 DevEco Studio 内置 Emulator 公开命令行参数。新增场景控制命令要求 Emulator 7.0 或更高版本；低版本会直接提示升级。截图不属于模拟器场景操作，统一通过 `devecocli ui screenshot` 执行。

**示例：**

```bash
devecocli emulator shake --target Phone
devecocli emulator power --target Phone
devecocli emulator rotate left --target Phone
devecocli emulator volume up --target Phone
devecocli emulator fold half-open --target Phone
devecocli emulator battery --target Phone --level 90
devecocli emulator battery --target Phone --status charging
devecocli emulator battery --target Phone --level 80 --status charging
devecocli emulator geolocation --target Phone --longitude 116.40024 --latitude 39.908
devecocli emulator scene outdoorRunning --target Phone
devecocli emulator sensor --target Phone --heartrate 80
```

**说明：**

-   `--target` 支持模拟器名称或 `127.0.0.1:<port>` 序列号。
    
-   `battery --level` 与 `battery --status` 可同时传入（一次调用同时设置电量与充电状态）。
    
-   `battery --level` 会自动查询模拟器当前充电状态：充电时取值范围为整数 `[0, 100]`，未充电时为 `[1, 100]`。
    
-   `battery --status` 取值为 `charging` 或 `discharging`。
    
-   `--level 0` 与 `--status discharging` 组合非法（电量 0 仅在充电时允许），会被拒绝。
    
-   `geolocation` 支持 `--longitude`、`--latitude`、`--altitude`、`--direction`。
    
-   `scene` 取值为 `outdoorRunning`、`outdoorCycling`、`drivingNavigation`。
    
-   `sensor` 支持 `--light-intensity`、`--humidity`、`--temperature`、`--steps`、`--heartrate`，可同时传入多个。
    
-   `geolocation`/`battery`/`sensor` 多参数为逐项串行下发、非原子：第 N 项失败时前 N−1 项已生效且不回滚，建议失败后整体重跑。
    
-   `fold <state>` 会根据目标模拟器的设备类型校验状态，设备与参数必须匹配：
    
    | 设备类型 | 支持的 `state` |
    | --- | --- |
    | `foldable` | `open`、`half-open`、`close` |
    | `2in1_foldable` | `open`、`vertical-open`、`half-open`、`close` |
    | `triplefold` | `single`、`double`、`triple`、`left-folded-right-half-folded`、`left-half-folded-right-expanded`、`left-expanded-right-folded`、`left-half-folded-right-folded`、`left-expanded-right-half-folded`、`left-half-folded-right-half-folded` |
    
    校验以目标模拟器实际返回的 `deviceType` 为准。非上述三种设备类型以及不属于目标设备类型的状态会在命令下发前被拒绝。校验通过后，底层映射为 `Emulator -instance <name> -foldedState <state>`。
    
-   设置 `DEVECO_CLI_DEBUG=1` 可查看底层命令映射，例如 `Emulator -instance <name> -shake`。
    

### `emulator create`

创建模拟器

**命令格式：**

```bash
devecocli emulator create <name> \
  --device-type <type> \
  --os-version <version> \
  [--instance-path <path>] \
  [--image-root <path>] \
  [--screen-profile <model>] \
  [--screen <config...>] \
  [--storage <size>] \
  [--memory <size>] \
  [--hot-boot <true|false>] \
  [--force]
```

**参数：**

| 参数名 | 说明 |
| --- | --- |
| `name` | 必选，模拟器名称 |
| `--device-type` | 必选，指定模拟器产品类型，支持的产品类型以官方设备支持类型为准，不区分大小写 |
| `--os-version` | 必选，模拟器镜像版本 |
| `--instance-path` / `--path` | 可选，模拟器实例路径 |
| `--image-root` | 可选，模拟器镜像路径 |
| `--screen-profile` | 可选，模拟器设备型号，例如 `Mate 70 Pro` |
| `--screen` | 可选，屏幕配置，格式为 `宽度(px) 高度(px) DPI 屏幕对角线长度(inch)`；宽度和高度范围为 720～3500 px，DPI 范围为 240～640，屏幕对角线长度范围为 3.5～9 inch；折叠屏模拟器传入两组配置 |
| `--storage` | 可选，存储空间，范围 `2–1023`，单位 G |
| `--memory` | 可选，运行内存，范围 `2–32`，单位 G |
| `--hot-boot` | 可选，取值为 `true` 或 `false`，从 26.0.0 Beta1 开始支持；API 26 及以上未指定时默认为 `true` |
| `--force` | 可选，覆盖已有同名的模拟器 |

`--screen-profile` 和 `--screen` 可同时指定，此时使用 `--screen`。

**示例：**

```bash
devecocli emulator create MyPhone --device-type phone --os-version "HarmonyOS 6.0.1(21)"

devecocli emulator create MyPhone \
  --device-type phone \
  --os-version "HarmonyOS 6.0.1(21)" \
  --screen-profile "Mate 70 Pro" \
  --storage 8 \
  --memory 8

devecocli emulator create Foldable \
  --device-type foldable \
  --os-version "HarmonyOS 6.0.1(21)" \
  --screen "2200 2480 480 7.8" "1080 2480 480 6.4"
```

### `emulator delete`

删除模拟器

**命令格式：**

```bash
devecocli emulator delete <name> [--instance-path <path>]
```

**参数：**

| 参数名 | 说明 |
| --- | --- |
| `name` | 必选，模拟器实例名称或序列号 |
| `--instance-path` / `--path` | 可选，模拟器实例路径；删除通过自定义路径创建的模拟器时，需传入创建时使用的同一路径 |

**示例：**

```bash
devecocli emulator delete MyPhone

devecocli emulator delete MyPhone --instance-path /custom/instance/path
```

### `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`

**命令格式：**

```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`

交互式查看并接受协议。打印完整协议文本后提示 y/N 确认。使用模拟器需要同意 HarmonyOS 软件许可与服务协议，下载镜像需要同意 HarmonyOS `SDK` 许可协议。若已同意则直接提示已接受。非交互终端下会报错，请改用 `emulator license accept`

**命令格式：**

```bash
devecocli emulator license
```

### `emulator license accept`

非交互式同意模拟器所有协议，直接写入同意记录，跳过协议展示和确认提示。适用于 Agent、自动化脚本、CI 或非交互终端环境。若已同意则直接提示已接受。Agent 遇到协议阻塞时，沿用用户已有的协议接受授权，直接执行此命令，成功后继续原操作；仅在缺少授权时询问。需要查看协议内容时使用只读的 `devecocli emulator license view`。

**命令格式：**

```bash
devecocli emulator license accept
```

### `device list`

查询所有已连接的设备，包括真机设备和运行中的模拟器

**命令格式：**

```bash
devecocli device list [--format <table|json>]
```

**参数：**

| 参数名 | 说明 |
| --- | --- |
| \--format | 可选，输出格式。可选值：`table`、`json`，默认 `table` |

### `device view`

查询已连接的设备的详细信息，包括设备序列号、设备名称、设备类型、 `OS` 版本等

**命令格式：**

```bash
devecocli device view [--target <serialOrName>] [--format <table|json>]
```

**参数：**

| 参数名 | 说明 |
| --- | --- |
| \-t，--target | 可选，目标设备名称或序列号。多设备缺省时，会列出所有已连接设备序列号和名称 |
| \--format | 可选，输出格式。可选值：`table`、`json`，默认 `table` |

**示例：**

```bash
devecocli device view
devecocli device view --target 127.0.0.1:5555
devecocli device view -t "My Device Name"
devecocli device view -t 127.0.0.1:5555 --format json
```

### `device file`

在主机与设备（真机或模拟器）之间传输文件，以及检查、删除设备端文件。

**命令格式：**

```bash
devecocli device file [--device <name|serial>] send <src> <dst>
devecocli device file [--device <name|serial>] recv <src> <dst>
devecocli device file [--device <name|serial>] exist <path>
devecocli device file [--device <name|serial>] delete <path>
```

**参数：**

| 参数名 | 说明 |
| --- | --- |
| \--device | 可选，目标设备名称或序列号。单设备可省略，多设备时必填 |
| send <src> <dst> | 子命令，上传本地文件到设备 `<src>`(本地) → `<dst>`(设备端) |
| recv <src> <dst> | 子命令，下载设备文件到主机 `<src>`(设备端) → `<dst>`(本地) |
| exist <path> | 子命令，检查设备端文件是否存在 |
| delete <path> | 子命令，删除设备端文件 |

**示例：**

```bash
devecocli device file send ./local.txt /data/local/tmp/remote.txt
devecocli device file recv /data/local/tmp/remote.txt ./local.txt --device 127.0.0.1:5555
devecocli device file exist /data/local/tmp/testfile.txt
devecocli device file delete /data/local/tmp/testfile.txt
```

### `device sqlite3`

在设备上执行 `sqlite3`，底层映射为 `hdc -t <serial> shell sqlite3 <db-path> [args...]`，后续参数原样透传给设备的 `sqlite3`。

**命令格式：**

```bash
devecocli device sqlite3 [--device <name|serial>] <db-path> [args...]
```

**参数：**

| 参数名 | 说明 |
| --- | --- |
| \--device | 可选，目标设备名称或序列号。单设备可省略，多设备时必填 |
| db-path | 设备端 SQLite 数据库文件路径 |
| args | 可选，透传给设备 `sqlite3` 的参数，如 `-json`、`-header`、`-readonly`、SQL 语句、点命令等 |

**示例：**

```bash
devecocli device sqlite3 /data/app/el2/100/database/com.example.app/foo.db "select * from user limit 5" -json
```

### `device app`

管理设备上的应用，包括安装、卸载、查询、启动、停止和数据清理。

**子命令：**

| 子命令 | 说明 |
| --- | --- |
| `install [files...]` | 安装 hap/hsp 包，可指定多个 |
| `uninstall --bundle <name>` | 按 bundle 名称卸载应用 |
| `list` | 列出已安装应用 |
| `info <bundleName>` | 查看应用详情 |
| `foreground` | 查看当前前台应用 |
| `start` | 启动应用 Ability |
| `stop --bundle <name>` | 强制停止应用 |
| `cleardata --bundle <name>` | 清除应用数据 |
| `clearcache --bundle <name>` | 清除应用缓存 |

**命令格式：**

```bash
devecocli device app install [files...] [--replace] [--shared <path>] [--wait <seconds>] [--user <userId>] [--device <name|serial>]
devecocli device app uninstall --bundle <name> [--device <name|serial>]
devecocli device app list [--format <default|json>] [--device <name|serial>]
devecocli device app info <bundleName> [--format <default|json>] [--device <name|serial>]
devecocli device app foreground [--format <default|json>] [--device <name|serial>]
devecocli device app start [--bundle <name>] [--ability <name>] [--action <action>] [--uri <uri>] [--device <name|serial>]
devecocli device app stop --bundle <name> [--device <name|serial>]
devecocli device app cleardata --bundle <name> [--device <name|serial>]
devecocli device app clearcache --bundle <name> [--device <name|serial>]
```

**参数：**

| 参数名 | 说明 |
| --- | --- |
| \--device | 可选，目标设备名称或序列号。单设备可省略，多设备时必填 |
| \--bundle <name> | 应用 bundle 名称（uninstall/stop/cleardata/clearcache 必填） |
| \--ability <name> | 可选，指定启动的 Ability 名称；指定 `--bundle` 时必须同时指定 |
| \--action <action> | 可选，指定 action 启动 |
| \--uri <uri> | 可选，指定 URI 启动 |
| \--replace | 可选，覆盖安装（install） |
| \--shared <path> | 可选，应用间 HSP 共享库路径，可重复指定多个（install） |
| \--wait <seconds> | 可选，安装等待时长（秒），取值 180–600（install） |
| \--user <userId> | 可选，指定安装用户 ID（install） |
| \--format | 可选，输出格式 `default` 或 `json`（list/info/foreground） |

**示例：**

```bash
devecocli device app install /path/to/app.hap
devecocli device app install /path/to/app.hap --replace --device Phone
devecocli device app uninstall --bundle com.example.app
devecocli device app list --format json
devecocli device app info com.example.app
devecocli device app foreground
devecocli device app start --bundle com.example.app --ability EntryAbility
devecocli device app stop --bundle com.example.app
devecocli device app cleardata --bundle com.example.app
devecocli device app clearcache --bundle com.example.app
```

### `device wake` / `device sleep` / `device status`

控制设备屏幕唤醒、休眠及查询屏幕状态。

**命令格式：**

```bash
devecocli device wake [--device <name|serial>]
devecocli device sleep [--device <name|serial>]
devecocli device status [--device <name|serial>]
```

**示例：**

```bash
devecocli device wake --device Phone
devecocli device sleep --device Phone
devecocli device status --device Phone
```

### `device unlock`

唤醒设备并上滑解锁。仅支持 phone 和 tablet，不支持 2in1 设备。

**命令格式：**

```bash
devecocli device unlock [--device <name|serial>]
```

**示例：**

```bash
devecocli device unlock --device Phone
```

### `device open-control-center` / `device open-notification-center`

通过滑动手势打开控制中心或通知中心。仅支持 phone 和 tablet，不支持 2in1 设备。

**命令格式：**

```bash
devecocli device open-control-center [--device <name|serial>]
devecocli device open-notification-center [--device <name|serial>]
```

**示例：**

```bash
devecocli device open-control-center --device Phone
devecocli device open-notification-center --device Phone
```

### `device time` / `device timezone`

获取或设置设备系统时间和时区。省略参数时为获取，提供参数时为设置。

**命令格式：**

```bash
devecocli device time [datetime] [--device <name|serial>]
devecocli device timezone [timezone] [--device <name|serial>]
```

**参数：**

| 参数名 | 说明 |
| --- | --- |
| `[datetime]` | 可选，省略则获取当前时间，提供则设置 |
| `[timezone]` | 可选，省略则获取当前时区，提供则设置 |
| \--device | 可选，目标设备名称或序列号。单设备可省略，多设备时必填 |

**示例：**

```bash
devecocli device time
devecocli device time "2026-01-01 12:00:00"
devecocli device timezone
devecocli device timezone "Asia/Shanghai"
```

### `device screen`

控制设备屏幕，包括尺寸查询、旋转控制和熄屏超时。

**子命令：**

| 子命令 | 说明 |
| --- | --- |
| `size` | 获取屏幕分辨率 |
| `rotation` | 获取当前屏幕旋转角度 |
| `rotate <0|90|180|270>` | 设置屏幕旋转角度 |
| `rotation-lock <on|off>` | 锁定/解锁自动旋转 |
| `sleeptime <ms>` | 设置熄屏超时（毫秒），`-1` 表示永不熄屏 |

**命令格式：**

```bash
devecocli device screen size [--format <default|json>] [--device <name|serial>]
devecocli device screen rotation [--device <name|serial>]
devecocli device screen rotate <0|90|180|270> [--device <name|serial>]
devecocli device screen rotation-lock <on|off> [--device <name|serial>]
devecocli device screen sleeptime <ms> [--device <name|serial>]
```

**参数：**

| 参数名 | 说明 |
| --- | --- |
| \--device | 可选，目标设备名称或序列号。单设备可省略，多设备时必填 |
| \--format | 可选，`size` 命令输出格式；`default` 输出 `宽度x高度`，`json` 输出 `{width, height}` |
| <rotation> | `rotate` 必填，旋转角度，仅接受 `0`、`90`、`180`、`270` |
| <state> | `rotation-lock` 必填，`on`\=锁定旋转（禁用自动旋转），`off`\=解锁旋转 |
| <ms> | `sleeptime` 必填，熄屏超时毫秒数；`-1` 表示永不熄屏 |

**示例：**

```bash
devecocli device screen size
devecocli device screen size --format json --device Phone
devecocli device screen rotation
devecocli device screen rotate 90
devecocli device screen rotation-lock on
devecocli device screen rotation-lock off
devecocli device screen sleeptime -1
devecocli device screen sleeptime 30000
```

### `device clipboard`

读写或清空设备剪贴板。

**命令格式：**

```bash
devecocli device clipboard read [--device <name|serial>]
devecocli device clipboard write <text> [--device <name|serial>]
devecocli device clipboard clear [--device <name|serial>]
```

**示例：**

```bash
devecocli device clipboard read
devecocli device clipboard write "Hello World" --device Phone
devecocli device clipboard clear
```

### `device font`

管理设备字体，包括查询、安装和卸载。

**命令格式：**

```bash
devecocli device font info <fontpath> [--device <name|serial>]
devecocli device font install <fontpath> [--device <name|serial>]
devecocli device font uninstall <name> [--device <name|serial>]
```

**参数：**

| 参数名 | 说明 |
| --- | --- |
| <fontpath> | `info`/`install` 必填，本地字体文件路径 |
| <name> | `uninstall` 必填，已安装的字体名称 |
| \--device | 可选，目标设备名称或序列号。单设备可省略，多设备时必填 |

**示例：**

```bash
devecocli device font info /path/to/font.ttf
devecocli device font install /path/to/font.ttf --device Phone
devecocli device font uninstall "MyCustomFont"
```

### `device viewmode`

获取或设置设备视图模式（深色/浅色）。省略参数时为获取，提供参数时为设置。

**命令格式：**

```bash
devecocli device viewmode [dark|light] [--device <name|serial>]
```

**参数：**

| 参数名 | 说明 |
| --- | --- |
| `[dark|light]` | 可选，省略则获取当前模式，提供则设置；仅接受 `dark`/`light` |
| \--device | 可选，目标设备名称或序列号。单设备可省略，多设备时必填 |

**示例：**

```bash
devecocli device viewmode
devecocli device viewmode dark --device Phone
devecocli device viewmode light
```

### `device location`

模拟设备位置或关闭位置模拟，基于 `testhelper`（系统版本 7.0+）。支持经纬度模式和 GPX 文件模式（互斥）。

**命令格式：**

```bash
devecocli device location set --latitude <degrees> --longitude <degrees> [--altitude <m>] [--speed <m/s>] [--direction <degrees>] [--interval <s>] [--device <name|serial>]
devecocli device location set --gpx-file <path> [--interval <s>] [--device <name|serial>]
devecocli device location enable [--device <name|serial>]
devecocli device location disable [--device <name|serial>]
```

**示例：**

```bash
devecocli device location set --latitude 39.908 --longitude 116.40024
devecocli device location set --gpx-file ./route.gpx --interval 2
devecocli device location disable
```

**说明：**

-   `--latitude`/`--longitude` 与 `--gpx-file` 互斥。`--altitude`/`--speed`/`--direction` 仅经纬度模式有效。
-   `--interval`（1-3600 秒，默认 1）两种模式均支持，作为 testhelper 命令参数传递，不修改 GPX 文件内容。
-   `set` 会自动启用位置模拟，无需单独 `enable`。
-   GPX 文件支持标准 GPX 1.1 格式，详见 [testhelper 官方文档](https://gitcode.com/openharmony/docs/blob/master/zh-cn/application-dev/application-test/testhelper-guidelines.md#testhelper-set-mocked-locations)。
-   只有 debug 签名的应用才能获取到模拟位置信息，开启模拟后非 debug 应用将获取位置失败。

### `device network-sim`

基于 `netcopilot`（API 20+）模拟设备网络状况，用于弱网/断网/切换等测试场景。

**命令格式：**

```bash
devecocli device network-sim start --id <id> [--device <name|serial>]
devecocli device network-sim start --name <name> --up-bandwidth <bps> --down-bandwidth <bps> --up-latency <ms> --down-latency <ms> --up-drop <rate> --down-drop <rate> [--device <name|serial>]
devecocli device network-sim stop [--device <name|serial>]
devecocli device network-sim list [--device <name|serial>]
devecocli device network-sim status [--device <name|serial>]
```

**示例：**

```bash
devecocli device network-sim start --id 5
devecocli device network-sim start --name weak-net --up-bandwidth 100000 --down-bandwidth 500000 --up-latency 200 --down-latency 200 --up-drop 0.05 --down-drop 0.01
devecocli device network-sim stop
devecocli device network-sim list
```

**说明：**

-   `--id`（预置场景 1-8）与 `--name`+自定义网络参数互斥。
-   预置场景 1-3 需同时连接 WLAN 和蜂窝网络；4-8 需 WLAN 或蜂窝网络之一。
-   `stop` 停止模拟、删除自定义场景、自动关闭 netcopilot，无参数、幂等。

### `device playback`

基于 `ohos-avsession-manager`（系统版本 6.1+）控制设备媒体播放中心。

**命令格式：**

```bash
devecocli device playback list [--device <name|serial>]
devecocli device playback play [--id <id>] [--bundle <name>] [--device <name|serial>]
devecocli device playback pause [--id <id>] [--bundle <name>] [--device <name|serial>]
devecocli device playback next [--id <id>] [--bundle <name>] [--device <name|serial>]
devecocli device playback previous [--id <id>] [--bundle <name>] [--device <name|serial>]
devecocli device playback forward [--id <id>] [--bundle <name>] [--device <name|serial>]
devecocli device playback rewind [--id <id>] [--bundle <name>] [--device <name|serial>]
devecocli device playback seek --position <seconds> [--id <id>] [--bundle <name>] [--device <name|serial>]
```

**示例：**

```bash
devecocli device playback list
devecocli device playback play --bundle com.example.music
devecocli device playback seek --position 120 --bundle com.example.music
```

**说明：**

-   控制命令需要 `--id` 或 `--bundle`（至少提供一个）。`--bundle` 会自动解析会话 ID。
-   `forward`/`rewind` 步长由应用决定，不支持设置时间。
-   `seek --position` 跳转到指定位置（秒），非负数（支持整数和浮点数，如 `0`、`120`、`1.5`）。

### `ui screenshot`

对真机或模拟器执行 UI 截图。

**命令格式：**

```bash
devecocli ui screenshot --device <name|serial> --display <displayId> --path <path>
```

**参数：**

| 参数 | 说明 | 默认值 |
| --- | --- | --- |
| \--device <name|serial> | 真机或模拟器名称/序列号；多设备时必填 | 单设备自动选择 |
| \--display <displayId> | 目标屏幕 ID，可选 | 默认屏幕 |
| \--path <path> | 必填，文件夹路径或 PNG 文件路径；支持相对于当前目录的路径，目录必须存在且可写，目标文件不能已存在 | 无 |

**示例：**

```bash
mkdir -p screenshots
devecocli ui screenshot --device Phone --path ./screenshots
devecocli ui screenshot --device Phone --display 0 --path ./screenshots/phone.png
```

**说明：**

-   `ui screenshot` 支持真机和模拟器。
-   仅有一个可用设备时可省略 `--device`，多个设备同时连接时必须指定。
-   `--path` 可以使用相对于当前目录的路径。可以指定已存在的文件夹并自动生成 PNG 文件名，也可以指定完整的 PNG 文件路径；不会自动创建目录或覆盖已有文件。
-   截图能力统一通过 `ui screenshot` 提供，不放在模拟器场景操作命令中。
-   截图统一使用 `hdc shell snapshot_display` 和 `hdc file recv` 实现；设置 `DEVECO_CLI_DEBUG=1` 可查看实际执行命令。

### `ui screenrecord`

录制真机屏幕并保存为 MP4。仅支持提供系统录屏服务和 `mediatool` 的真机，不支持模拟器。

**命令格式：**

```bash
devecocli ui screenrecord [start] --device <name|serial> --path <dir|file.mp4>
devecocli ui screenrecord stop --device <name|serial> [--force]
devecocli ui screenrecord status --device <name|serial> [--format table|json]
```

**参数：**

| 参数 | 说明 | 默认值 |
| --- | --- | --- |
| \--device <name|serial> | 设备名称或序列号；多设备时必填 | 单设备自动选择 |
| \--path <dir|file.mp4> | 直接录制或 `start` 时必填；已有可写目录或新 MP4 文件路径，父目录必须存在 | 无 |
| \--force | 仅用于 `stop`，允许停止非本 CLI 登记的录屏；此类视频不下载，到设备图库查看 | 不启用 |
| \--format <table|json> | 仅用于 `status`，指定输出格式 | table |

**示例：**

```bash
mkdir -p recordings
# 直接录制，按 Ctrl+C 停止并保存
devecocli ui screenrecord --device Phone --path ./recordings/demo.mp4

# 分步控制
devecocli ui screenrecord start --device Phone --path ./recordings
devecocli ui screenrecord status --device Phone --format json
devecocli ui screenrecord stop --device Phone
```

**说明：**

-   不带子命令时进入交互录制；`start` 确认启动后立即返回，之后用 `stop` 停止并保存到启动时指定的位置。
-   `--path` 支持相对路径；输入目录则自动生成文件名，不创建目录、不覆盖已有文件。录制期间目标被占用时，使用带 `-recovered` 后缀的文件名。
-   `status` 返回 `recording`（本 CLI 录屏）、`busy`（非本 CLI 登记的录屏）或 `idle`（未录屏）；查询不会改变设备状态。
-   设备端已停止或视频保存失败时，可重试 `stop` 取回；再次启动会删除中断会话登记，不取回旧视频，原件保留在设备图库。跨终端操作需使用同一个 `DEVECO_CLI_DATA_DIR`。
-   设备图库保留视频原件。进程被强制结束且登记尚未完成时，需检查设备状态和图库。

### `ui click`

点击指定坐标、节点 ID 或 Selector 定位的元素中心位置。

**命令格式：**

```bash
devecocli ui click [x] [y] --device <name|serial> --id <id> --selector <expr> --window <windowId>
```

**参数：**

| 参数 | 说明 |
| --- | --- |
| `[x] [y]` | 可选，目标坐标。缺省时需配合 `--id` 或 `--selector` 使用 |
| \--device <name|serial> | 目标设备，多设备时必填 |
| \--id <id> | 节点 ID，自动解析为中心坐标。不可与 `[x] [y]` 或 `--selector` 同时使用 |
| \--selector <expr> | Selector DSL 表达式定位元素。不可与 `[x] [y]` 或 `--id` 同时使用 |
| \--window <windowId> | 目标窗口 ID，需与 `--id` 或 `--selector` 配合使用 |

**示例：**

```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
devecocli ui click --selector "text=登录,type=Button"
devecocli ui click --selector "xpath=//Button[@key='login_btn']"
```

### `ui doubleclick`

双击指定坐标、节点 ID 或 Selector 定位的元素中心位置。

**命令格式：**

```bash
devecocli ui doubleclick [x] [y] --device <name|serial> --id <id> --selector <expr> --window <windowId>
```

**参数：**

| 参数 | 说明 |
| --- | --- |
| `[x] [y]` | 可选，目标坐标。缺省时需配合 `--id` 或 `--selector` 使用 |
| \--device <name|serial> | 目标设备，多设备时必填 |
| \--id <id> | 节点 ID，自动解析为中心坐标。不可与 `[x] [y]` 或 `--selector` 同时使用 |
| \--selector <expr> | Selector DSL 表达式定位元素。不可与 `[x] [y]` 或 `--id` 同时使用 |
| \--window <windowId> | 目标窗口 ID，需与 `--id` 或 `--selector` 配合使用 |

**示例：**

```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
devecocli ui doubleclick --selector "key=photo_item"
```

### `ui longclick`

长按指定坐标或节点 ID 的中心位置。

**命令格式：**

```bash
devecocli ui longclick [x] [y] --device <name|serial> --id <id> --selector <expr> --duration <ms> --window <windowId>
```

**参数：**

| 参数 | 说明 |
| --- | --- |
| `[x] [y]` | 可选，目标坐标。缺省时需配合 `--id` 或 `--selector` 使用 |
| \--device <name|serial> | 目标设备，多设备时必填 |
| \--id <id> | 节点 ID，自动解析为中心坐标。不可与 `[x] [y]` 或 `--selector` 同时使用 |
| \--selector <expr> | Selector DSL 表达式定位元素。不可与 `[x] [y]` 或 `--id` 同时使用 |
| \--duration <ms> | 长按时长（毫秒），范围 500–60000，默认 1000 |
| \--window <windowId> | 目标窗口 ID，需与 `--id` 或 `--selector` 配合使用 |

**示例：**

```bash
devecocli ui longclick 100 200
devecocli ui longclick 100 200 --device Phone
devecocli ui longclick 100 200 --duration 3000
devecocli ui longclick --id menu_item
devecocli ui longclick --id menu_item --window main_window
devecocli ui longclick --selector "id=btn_longclick" --duration 1500
```

### `ui swipe`

自定义滑动，支持坐标模式和元素模式（通过 `--start`/`--end` Selector 定位起终点）。

**命令格式：**

```bash
# 坐标模式
devecocli ui swipe <x1> <y1> <x2> <y2> --device <name|serial> --speed <n>

# 元素模式
devecocli ui swipe --start <expr> --end <expr> --device <name|serial> --speed <n> --window <windowId>
```

**参数：**

| 参数 | 说明 |
| --- | --- |
| `<x1> <y1> <x2> <y2>` | 坐标模式必选，起点和终点坐标。与 `--start`/`--end` 互斥 |
| \--start <expr> | 元素模式起点 Selector DSL。必须与 `--end` 同时提供 |
| \--end <expr> | 元素模式终点 Selector DSL。必须与 `--start` 同时提供 |
| \--device <name|serial> | 目标设备，多设备时必填 |
| \--speed <n> | 可选，滑动速度（像素/秒），范围 `200` ~ `40000` |
| \--window <windowId> | 目标窗口 ID（元素模式） |

**示例：**

```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

# 元素模式
devecocli ui swipe --start "key=header_text" --end "key=footer_button"
devecocli ui swipe --start "text=顶部" --end "text=底部" --speed 500
```

### `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`

拖拽操作，支持坐标模式和元素模式（通过 `--start`/`--end` Selector 定位起终点）。

**命令格式：**

```bash
# 坐标模式
devecocli ui drag <x1> <y1> <x2> <y2> --device <name|serial> --speed <n>

# 元素模式
devecocli ui drag --start <expr> --end <expr> --device <name|serial> --speed <n> --window <windowId>
```

**参数：**

| 参数 | 说明 |
| --- | --- |
| `<x1> <y1> <x2> <y2>` | 坐标模式必选，起点和终点坐标。与 `--start`/`--end` 互斥 |
| \--start <expr> | 元素模式起点 Selector DSL。必须与 `--end` 同时提供 |
| \--end <expr> | 元素模式终点 Selector DSL。必须与 `--start` 同时提供 |
| \--device <name|serial> | 目标设备，多设备时必填 |
| \--speed <n> | 可选，滑动速度（像素/秒），范围 `200` ~ `40000` |
| \--window <windowId> | 目标窗口 ID（元素模式） |

**示例：**

```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

# 元素模式
devecocli ui drag --start "key=item_1" --end "key=drop_zone"
devecocli ui drag --start "text=卡片" --end "text=回收站" --speed 800
```

### `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> --selector <expr> --window <windowId>
```

**参数：**

| 参数 | 说明 |
| --- | --- |
| `<text>` | 必选，待输入的文本 |
| `[x] [y]` | 可选，目标坐标 |
| \--device <name|serial> | 目标设备，多设备时必填 |
| \--id <id> | 节点 ID，自动解析为中心坐标。不可与 `[x] [y]` 或 `--selector` 同时使用 |
| \--selector <expr> | Selector DSL 表达式定位输入元素。不可与 `[x] [y]` 或 `--id` 同时使用 |
| \--window <windowId> | 目标窗口 ID，需与 `--id` 或 `--selector` 配合使用 |

**示例：**

```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
devecocli ui text "hello" --selector "key=search_box"
```

### `ui cleartext`

清空文本内容（通过 Ctrl+A + Del），可选先点击目标元素再清空。

**命令格式：**

```bash
devecocli ui cleartext --device <name|serial> --selector <expr> --window <windowId>
```

**参数：**

| 参数 | 说明 |
| --- | --- |
| \--device <name|serial> | 目标设备，多设备时必填 |
| \--selector <expr> | 可选，Selector DSL 表达式定位输入元素（点击后再清空；缺省时清空当前焦点字段） |
| \--window <windowId> | 目标窗口 ID |

**示例：**

```bash
devecocli ui cleartext
devecocli ui cleartext --device Phone
devecocli ui cleartext --selector "id=search_box"
```

### `ui scrolltostart`

将可滚动容器滚动到起始位置（顶部）。

**命令格式：**

```bash
devecocli ui scrolltostart --device <name|serial> --selector <expr> --speed <n> --timeout <ms>
```

**参数：**

| 参数 | 说明 |
| --- | --- |
| \--device <name|serial> | 目标设备，多设备时必填 |
| \--selector <expr> | 可选，滚动容器 Selector DSL（缺省时取第一个可滚动元素） |
| \--speed <n> | 滚动速度（200–40000，默认 1500） |
| \--timeout <ms> | RPC 超时（1–3600000，默认 60000） |

**示例：**

```bash
devecocli ui scrolltostart
devecocli ui scrolltostart --selector "id=scroll_list" --device Phone
devecocli ui scrolltostart --selector "id=scroll_list" --speed 2000
```

### `ui scrolltoend`

将可滚动容器滚动到结束位置（底部）。

**命令格式：**

```bash
devecocli ui scrolltoend --device <name|serial> --selector <expr> --speed <n> --timeout <ms>
```

**参数：**

| 参数 | 说明 |
| --- | --- |
| \--device <name|serial> | 目标设备，多设备时必填 |
| \--selector <expr> | 可选，滚动容器 Selector DSL（缺省时取第一个可滚动元素） |
| \--speed <n> | 滚动速度（200–40000，默认 1500） |
| \--timeout <ms> | RPC 超时（1–3600000，默认 60000） |

**示例：**

```bash
devecocli ui scrolltoend
devecocli ui scrolltoend --selector "id=scroll_list" --device Phone
```

### `ui scrollsearch`

在可滚动容器内滚动并查找目标元素。

**命令格式：**

```bash
devecocli ui scrollsearch <selector> --device <name|serial> --scroll-selector <expr> --vertical <true|false> --offset <n> --timeout <ms>
```

**参数：**

| 参数 | 说明 |
| --- | --- |
| <selector> | 必选，要查找的目标元素 Selector DSL（不支持索引 `[n]`，传索引会报错） |
| \--device <name|serial> | 目标设备，多设备时必填 |
| \--scroll-selector <expr> | 可选，滚动容器 Selector DSL（缺省时取第一个可滚动元素） |
| \--vertical <true|false> | 滚动方向，true=垂直（默认），false=水平 |
| \--offset <n> | 滚动起止与容器边缘的像素偏移（≥0，默认 80） |
| \--timeout <ms> | RPC 超时（1–3600000，默认 60000） |

**示例：**

```bash
devecocli ui scrollsearch "id=target_item"
devecocli ui scrollsearch "id=target_item" --scroll-selector "id=scroll_list" --device Phone
devecocli ui scrollsearch "id=swiper_page_3" --scroll-selector "id=swiper" --vertical false
```

### `ui pinch`

在指定坐标、元素或屏幕中心执行捏合（缩放）手势。

**命令格式：**

```bash
devecocli ui pinch <scale> [x] [y] --device <name|serial> --selector <expr> --area-radius <n> --speed <n> --window <windowId>
```

**参数：**

| 参数 | 说明 |
| --- | --- |
| <scale> | 必选，缩放比例（0.1–10.0，排除 1；>1 放大，<1 缩小） |
| \[x\] \[y\] | 可选，捏合中心坐标。缺省时配合 `--selector` 或取屏幕中心 |
| \--device <name|serial> | 目标设备，多设备时必填 |
| \--selector <expr> | Selector DSL 表达式定位捏合元素。不可与 `[x] [y]` 同时使用 |
| \--area-radius <n> | 捏合区域半径（整数 ≥50；缺省：坐标模式默认 300，元素/屏幕模式默认取区域 90%） |
| \--speed <n> | 捏合速度（600–3000 px/s，默认 600） |
| \--window <windowId> | 目标窗口 ID |

**示例：**

```bash
devecocli ui pinch 2.0
devecocli ui pinch 2.0 500 500 --device Phone
devecocli ui pinch 0.5 --selector "id=gesture_area_pinch"
devecocli ui pinch 2.0 --selector "id=gesture_area_pinch" --area-radius 300
devecocli ui pinch 2.0 500 500 --speed 1200
```

### `ui rotate`

在指定坐标、元素或屏幕中心执行双指旋转手势。

**命令格式：**

```bash
devecocli ui rotate <angle> [x] [y] --device <name|serial> --direction <cw|ccw> --selector <expr> --radius <n> --speed <n> --window <windowId>
```

**参数：**

| 参数 | 说明 |
| --- | --- |
| <angle> | 必选，旋转角度（1–360 度，正整数） |
| \[x\] \[y\] | 可选，旋转中心坐标。缺省时配合 `--selector` 或取屏幕中心 |
| \--device <name|serial> | 目标设备，多设备时必填 |
| \--direction <cw|ccw> | 旋转方向，cw=顺时针（默认），ccw=逆时针 |
| \--selector <expr> | Selector DSL 表达式定位旋转中心元素。不可与 `[x] [y]` 同时使用 |
| \--radius <n> | 手指距中心半径（50–500，默认 300；元素模式缺省时按 bounds 自动） |
| \--speed <n> | 旋转速度（200–40000 px/s，默认 1500） |
| \--window <windowId> | 目标窗口 ID，需与 `--selector` 配合使用 |

**示例：**

```bash
devecocli ui rotate 90
devecocli ui rotate 90 --direction ccw --device Phone
devecocli ui rotate 180 500 500
devecocli ui rotate 90 --selector "id=gesture_area_rotate"
devecocli ui rotate 90 --selector "id=gesture_area_rotate" --radius 200 --speed 1000
```

### `ui press_key`

按压硬件/系统按键，最多支持 3 个按键组合（组合键）。

**命令格式：**

```bash
devecocli ui press_key <key1> [key2] [key3] --device <name|serial>
```

**参数：**

| 参数 | 说明 |
| --- | --- |
| <key1> | 必选，第一个按键（字符串名称或数字 keycode） |
| \[key2\] \[key3\] | 可选，第二、第三个按键（用于组合键） |
| \--device <name|serial> | 目标设备，多设备时必填 |

按键名称（不区分大小写）：`back`、`enter`、`escape`、`tab`、`ctrl_left`、`shift_left` 等；也可直接传数字 keycode（如 `2048`）。

**示例：**

```bash
devecocli ui press_key back
devecocli ui press_key enter --device Phone
devecocli ui press_key ctrl_left c
devecocli ui press_key ctrl_left shift_left escape
devecocli ui press_key 2048
```

### `ui find`

通过 Selector DSL、XPath 或 base64 编码查找 UI 控件。在 `--timeout` 时间内每 300ms 轮询控件树，直至匹配成功或超时。

**命令格式：**

```bash
devecocli ui find [selector] --device <name|serial> --window <windowId> --all --timeout <ms> --format <default|json>
```

**参数：**

| 参数 | 说明 |
| --- | --- |
| `[selector]` | 必选，Selector DSL 表达式、`xpath=` 前缀表达式或 `base64=` 前缀（base64 编码 selector，用于特殊字符逃生） |
| \--device <name|serial> | 目标设备，多设备时必填 |
| \--window <windowId> | 目标窗口 ID，不指定时默认使用聚焦窗口 |
| \--all | 返回所有匹配元素；默认 false |
| \--timeout <ms> | 查找最多等待的毫秒数（轮询），默认 3000，最大值 360000 |
| \--format | 输出格式，`default`（简洁行式）或 `json`（格式化 JSON），默认 `default` |

**Selector DSL 语法：**

`key op value` 子句，支持 `,` 分隔多条件 AND、`[n]` 索引。操作符：`=`（精确）、`*=`（包含）、`^=`（前缀）、`$=`（后缀）、`/=`（正则）。支持 `xpath=` 前缀（XPath 1.0 表达式）和 `base64=` 前缀（base64 编码 selector）。同一属性不可重复指定（`desc` 与 `description` 视为同一属性），重复会报错。

**示例：**

```bash
devecocli ui find "text=登录"
devecocli ui find "type=Button" --all --format json
devecocli ui find "id=login_btn" --device Phone
devecocli ui find "xpath=//Button[@text='登录']"
devecocli ui find "base64=dHlwZT1UZXh0"  # base64 解码后为 type=Text
devecocli ui find "text=不存在的文本" --timeout 1000  # 超时后报错退出
```

### `ui wait`

等待元素出现、消失，或纯等待（sleep）。无 selector 时为纯等待，有 selector 时轮询控件树直至元素出现（默认）或消失（`--disappear`）。

**命令格式：**

```bash
# 纯等待（sleep）
devecocli ui wait [timeoutMs] --device <name|serial>

# 等待元素出现/消失
devecocli ui wait <selector> [timeoutMs] [--disappear] --device <name|serial> --window <windowId>
```

**参数：**

| 参数 | 说明 |
| --- | --- |
| `[selector]` | 可选，Selector DSL/xpath=/base64= 表达式；不指定时为纯等待（sleep） |
| `[timeoutMs]` | 可选，等待毫秒数（正数），默认 3000，最大值 360000 |
| \--disappear | 等待元素**消失**（requires selector） |
| \--device <name|serial> | 目标设备，多设备时必填 |
| \--window <windowId> | 目标窗口 ID，不指定时默认使用聚焦窗口 |

**示例：**

```bash
# 等待元素出现
devecocli ui wait "text=登录" 10000
devecocli ui wait "text=照片" 10000 --device Phone

# 等待元素消失
devecocli ui wait "text=加载中" 5000 --disappear

# 纯等待（sleep）
devecocli ui wait 2000
```

### `ui layout`

导出设备屏幕上的 UI 节点树，输出每个节点的类型、节点 ID、坐标边界 `[left,top,right,bottom]`、文本及可交互标志（`clickable` / `longClickable` / `scrollable` / `checkable`）。

> **设备要求**：需设备 API 20 及以上。

**命令格式：**

```bash
devecocli ui layout --device <name|serial> --id <id> --window <windowId> --all-windows --depth <n> --format <fmt> --mode <full|simplified>
```

**参数：**

| 参数名 | 说明 |
| --- | --- |
| \--device <name|serial> | 目标设备，多设备时必填 |
| \--id <id> | 节点 ID，筛选树中匹配节点（仅输出匹配节点，不带子节点，强制 JSON）。不可与未筛选的全树输出同时视为列表查询 |
| \--window <windowId> | 目标窗口 ID，与 `--all-windows` 互斥 |
| \--all-windows | 包含所有窗口，与 `--window` 互斥 |
| \--depth <n> | 树深度限制，`0`\=不限制（默认），`1`\=仅根，`2`\=根+子节点 |
| \--format | 输出格式，`default` 或 `json`，默认 `default` |
| \--mode | 输出模式：`full`\=完整原始树；`simplified`（默认）=折叠无 ID、无文本、无可交互标志的包装节点 |

**示例：**

```bash
devecocli ui layout
devecocli ui layout --device Phone
devecocli ui layout --device Phone --format json
devecocli ui layout --mode full --depth 2
devecocli ui layout --id submit_button
devecocli ui layout --window 15 --format json
```

**说明：**

-   `--mode simplified`（默认）会折叠无 `id`、无 `text`、无任何可交互标志的包装节点，使输出聚焦于有意义的可操作节点；根节点始终保留。`--depth` 在折叠后截断。
-   `--id` 用于按节点 ID 查询，返回所有匹配节点（`children` 置空），常配合 `ui click --id` / `ui text --id` 定位坐标。
-   节点 `bounds` 为 `[left, top, right, bottom]`，`ui click --id` 等交互命令据此取中心坐标点击。
-   `--window` 的窗口 ID 可通过 `devecocli ui window list` 获取。

### `ui window list`

查看设备上的窗口列表，输出窗口 ID、名称、PID、所属屏幕 ID 及是否聚焦。为 `ui layout --window`、`ui click --window` 等命令提供窗口 ID。

**命令格式：**

```bash
devecocli ui window list --device <name|serial> --format <fmt> --all
```

**参数：**

| 参数名 | 说明 |
| --- | --- |
| \--device <name|serial> | 目标设备，多设备时必填 |
| \--format | 输出格式，`default` 或 `json`，默认 `default` |
| \--all | 显示包含系统窗口在内的所有窗口；缺省时仅显示应用窗口（`type === 1`） |

**示例：**

```bash
devecocli ui window list
devecocli ui window list --device Phone
devecocli ui window list --format json
devecocli ui window list --all
```

**说明：**

-   聚焦窗口在 `default` 格式下高亮显示。
-   缺省时仅列出应用窗口；加 `--all` 可查看系统窗口，用于排查多窗口场景。

### `run`

构建应用后，将应用安装到真机设备或模拟器上，并启动执行

**命令格式：**

```bash
devecocli run --module <m1> [m2...] --device <device> --product <product> --build-mode <mode> --ability <ability> --uninstall --skip-build --apply <fileName> --hotreload [action] --hotreload-apply <fileName> [--debug-line]
```

**参数：**

| 参数名 | 说明 |
| --- | --- |
| \--module | 可选，模块名称，支持多个以空格分隔。如需指定模块的 `target` 信息，使用 `module@target` 形式。当工程中只有一个可运行模块（ `entry` / `feature` / `shared` ）时，可缺省 |
| \--device | 设备名称或设备序列号，单设备时可选，多设备时必选 |
| \--product | 可选，产品的名称，默认为 `default` |
| \--build-mode | 可选，构建模式名称，默认为 `debug` |

## 常见问题

### @deveco/deveco-cli-common 是什么？

HarmonyOS 应用程序开发命令行工具

### 如何安装 @deveco/deveco-cli-common？

在项目目录运行 npm install @deveco/deveco-cli-common，或使用 pnpm add / yarn add / bun add。

### @deveco/deveco-cli-common 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/deveco\_\_deveco-cli-common 是否存在。

### @deveco/deveco-cli-common 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @deveco/deveco-cli-common 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=22。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @deveco/deveco-cli-common 可以商用吗？

@deveco/deveco-cli-common 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @deveco/deveco-cli-common 的下载量有多少？

根据 npm 官方下载统计，@deveco/deveco-cli-common 在 2026/10/12 – 2026/11/10 这 30 天内被下载 10,831 次，日均约 361 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @deveco/deveco-cli-common 还在维护吗？

最新版本 1\.3\.12 发布于 2026/11/10（1 天前）；至今共发布 9 个版本，其中过去 12 个月发布了 9 个；首次发布于 2026/09/22。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。