# @deveco/deveco-cli-openharmony-arm64 中文文档

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

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

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

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

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

- 包体积（解压后）：54.8 MB，43 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- Node.js 要求：\>=18
- 运行依赖：26 个
- 首次发布：2026-09-22T11:27:37.758Z
- 最新版本发布：2026-11-10T02:41:05.894Z
- 近 30 天下载量：2634（2026-10-12 至 2026-11-10，npm 官方下载统计）
- 已发布版本数：7（近 12 个月 7 个）

## 中文简介

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

## 安装

```sh
npm install @deveco/deveco-cli-openharmony-arm64
```

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

## README

# DevEco CLI

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

[![NPM Version](https://img.shields.io/npm/v/@deveco/deveco-cli.svg)](https://www.npmjs.com/package/@deveco-test/hmos-deveco-cli) [![NPM Downloads](https://img.shields.io/npm/dm/@deveco-test/hmos-deveco-cli.svg)](https://www.npmjs.com/package/@deveco-test/hmos-deveco-cli) [![Node.js](https://img.shields.io/badge/Node.js-%3E%3D18-green.svg)](https://nodejs.org/) ![Platform](https://img.shields.io/badge/platform-HarmonyOS-blue.svg) [![License](https://img.shields.io/badge/license-MIT-green.svg)](https://npmcn.com/package/%40deveco/deveco-cli-openharmony-arm64/LICENSE)

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

## 快速开始

### 前置要求

-   操作系统为 `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-test/hmos-deveco-cli
```

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

```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 harmonyos-guides/application-models/arkts-page-start-overview
```

更多命令和参数可通过 `devecocli --help` 或各子命令的 `--help` 查看。

## AI Agent 集成

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

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

```bash
devecocli init --path .\work\ARKTS\NewData
```

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

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

## 常用命令

| 命令 | 用途 |
| --- | --- |
| `devecocli create` | 创建新的 HarmonyOS 项目 |
| `devecocli build` | 构建项目并产出 `.hap` / `.hsp` / `.har` / `.app` |
| `devecocli check lint` | 检查代码规范并输出实践建议与报告 |
| `devecocli run` | 安装并运行应用 |
| `devecocli device list` | 查看当前连接设备 |
| `devecocli log` | 查看 `hilog` 或崩溃日志 |
| `devecocli docs search` | 搜索本地 HarmonyOS 文档 |
| `devecocli init` | 安装内置技能或配置 `MCP` |
| `devecocli skills` | 管理 HarmonyOS 技能市场中的技能 |
| `devecocli signature generate` | 自动生成调试签名材料并配置到项目 |

## 命令集

### `help`

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

**命令格式：**

```bash
devecocli help
```

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

HarmonyOS application development command line tool

Options:
  -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
  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
  create [options]       Scaffold a new HarmonyOS application project
  init [options]         Install the deveco-cli skill 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
```

### `init`

将`deveco-cli` `Skill` 或者 `MCP` 服务配置到智能体中

**命令格式：**

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

**参数：**

| 参数名 | 说明 |
| --- | --- |
| \--agent | 可选，智能体名称，多个智能体名称以英文逗号分隔。缺省时配置到所有已检测到的智能体中 |
| \--project | 可选，指定工程路径，将`deveco-cli` `Skill` 或 `MCP` 服务安装到该工程项目中 |
| \--path | 可选，指定 `deveco-cli` `Skill` 的配置路径。不可与 `--project` 、`--agent` 、 `--mcp` 同时使用 |
| \--skill | 可选，安装 `deveco-cli` `Skill`。不可与 `--mcp` 同时使用。`--mcp` 与 `--skill` 都缺省时，执行 `--skill` |
| \--mcp | 可选，配置 `MCP` 服务，与 `--project` 一起使用表示配置工程级 `MCP` 服务，独立使用表示配置用户级 `MCP` 服务。不可与 `--skill` 同时使用 |
| \-f, --force | 可选，当目标位置已存在 `deveco-cli` `Skill` 或 `MCP` 服务时，覆盖重装 |

**示例：**

```bash
# 配置Skill
devecocli init -f   # 安装或更新deveco-cli Skill
devecocli init --skill
devecocli init --agent agentname    # agentname需替换为实际的智能体名称
devecocli init --path /path/to/project -f

# 配置MCP
devecocli init --mcp
devecocli init --mcp --agent agentname    # agentname需替换为实际的智能体名称   
devecocli init --mcp --project /path/to/project -f
```

### `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 | 可选，设置搜索结果返回条数，默认为20 |

**示例：**

```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 开发指南/应用框架/UI_Design_Kit_UI设计套件/沉浸光感/ui-design-hds-component-material
```

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

**参数：**

| 参数名 | 说明 |
| --- | --- |
| \--app-name | 必选，应用名称 |
| \--project-path | 可选，工程路径，默认为：`./<appname>` |
| \--bundle-name | 可选，包名，默认为：`com.example.<appname>` ，`appname` 自动转为小写 |
| \--api-level | 可选，API级别，最小值为17，最大值从安装的 `Deveco Studio` 的 `HarmonyOS` `SDK` 中自动获取 |

**示例：**

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

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

**命令格式：**

```bash
devecocli build --product <product> --modules <modules> --build-mode <mode>
```

**参数：**

| 参数名 | 说明 |
| --- | --- |
| \--product | 可选，产品的名称，默认为 `default` |
| \--modules | 可选，模块的名称。如需指定模块的 `target` 信息，使用 `module@target` 形式。当工程中只有一个模块时，可缺省；当工程中存在多个模块，且仅存在一个 `entry` 类型的模块时，可缺省 |
| \--build-mode | 可选，构建模式，默认为 `debug` |

**示例：**

```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 <name>`命令后，产物为 `.app`
-   执行`devecocli build --product <name> --modules <m1>`命令后，产物为 `.hap` / `.hsp` / `.har`

### `build clean`

清理 HarmonyOS 项目的构建产物

**命令格式：**

```bash
devecocli build clean
```

### `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 |
| `--output-path <path>` | 完整报告文件或目录；目录形式会自动生成带时间戳的报告文件 |
| `--limit <number>` | 未指定 `--output-path` 时，限制终端显示的问题数量 |

### `device list`

查询所有已连接的设备

**命令格式：**

```bash
devecocli device list
```

### `device view`

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

**命令格式：**

```bash
devecocli device view --target <serialOrName>
```

**参数：**

| 参数名 | 说明 |
| --- | --- |
| \-t，--target | 可选，目标设备名称或序列号。多设备缺省时，会列出所有已连接设备序列号和名称 |

**示例：**

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

### `run`

构建应用后，将应用安装到设备上，并启动执行

**命令格式：**

```bash
devecocli run --module <module> --device <device> --product <product> --build-mode <mode> --ability <ability> --uninstall --skip-build --apply <txtFile>
```

**参数：**

| 参数名 | 说明 |
| --- | --- |
| \--module | 可选，模块名称。如需指定模块的 `target` 信息，使用 `module@target` 形式。当工程中只有一个可运行模块（ `entry` / `feature` / `shared` ）时，可缺省 |
| \--device | 设备名称或设备序列号，单设备时可选，多设备时必选 |
| \--product | 可选，产品的名称，默认为 `default` |
| \--build-mode | 可选，构建模式名称，默认为 `debug` |
| \--ability | 可选，待启动的 `Ability` ，默认：模块 `module.json5` 中的`mainElement` |
| \--uninstall | 可选，安装前先卸载已有应用 |
| \--skip-build | 可选，跳过构建操作，直接安装应用 。\*\*说明：\*\*使用该参数时，需确保对应模块已有构建产物 |
| \--apply <fileName> | 可选，**快速增量部署**：仅重编改动文件 → signed hqf → `bm quickfix -a -f -o` 安装 → 重启，比全量 `run` 快。`<fileName>` 是工程 `.hvigor/` 目录下的**纯文件名**（调用方把清单写到此目录，文件名做安全校验防穿越）；内容为本轮改动的源文件路径清单（每行一个相对工程根路径；`#`/空行忽略；`.ets`/`.ts`/`.cpp`/资源文件；changeFileList 增量累积，只需列本轮改的，历史文件自动保留）。模块从清单路径自动识别（无需 `--module`）。**前提**：先 `devecocli run` 全量构建部署一次（生成 buildConfig.json 缓存）；**没生效排查**：检查 `<module>/build/config/buildConfig.json` 有无内容（空/无 = 没跑过 `devecocli run`）；**失败兜底**：直接 `devecocli run` |

> **说明：** 在 OpenHarmony 平台上，未指定 `--device` 时：无设备连接且 `bm`/`aa` 可用则在本地运行；有设备连接时需用 `--device local` 显式指定本地运行，或 `--device <serial>` 指定设备。

**示例：**

```bash
devecocli run
devecocli run --module entry --device 127.0.0.1:5555
devecocli run --module library@phone --device 127.0.0.1:5555
devecocli run --product oversea --module entry --ability EntryAbility
devecocli run --build-mode release
devecocli run --uninstall
devecocli run --apply changes.txt
```

### `log`

查看`hilog`普通日志或崩溃日志

**命令格式：**

```bash
devecocli log --device <device> --crash --level <level> --bundle-name <bundle-name> --keyword <keyword> --tail <num> --from <start> --to <end> --follow
```

**参数：**

| 参数名 | 说明 |
| --- | --- |
| \--device | 设备名称或设备序列号，单设备时可选，多设备时必选 |
| \--crash | 可选，查看崩溃日志 |
| \--level | 可选，日志级别，取值包括`D`（ `Debug` ）、`I`（ `Info` ）、`W`（ `Warn` ）、`E`（ `Error` ）、`F`（ `Fatal` ） |
| \--bundle-name | 可选，根据包名查看日志 |
| \--keyword | 可选，根据关键词查看日志，关键词区分大小写 |
| \--tail | 可选，显示最新的N行日志，取值为正整数 |
| \--from | 可选，起始时间，单位为`m`和`s`，`m`和`s`为小写，默认为`s`，`start`的取值需要大于等于`end` |
| \--to | 可选，结束时间，单位为`m`和`s`，`m`和`s`为小写，默认为`s` 。不可与--follow同时使用。**说明：** 如当前时间为05：00，`start`设置为30s，`end`设置为10s，则起始时间为04：30，结束时间为04：50 |
| \--follow | 可选，实时输出日志。不可与--to同时使用 |

**示例：**

```bash
devecocli log --level E
devecocli log --crash --bundle-name com.example.app
devecocli log --device 127.0.0.1:5555 --level W --keyword Init
devecocli log --tail 100 --from 5m --to 2m
devecocli log --follow --bundle-name com.example.app
```

### `skills list`

查询可用的 `Skill`

**命令格式：**

```bash
devecocli skills list --long
```

**参数：**

| 参数名 | 说明 |
| --- | --- |
| \-l，--long | 可选，`Skill` 详情，包括描述和已安装的智能体列表。缺省时，仅显示 `Skill` 名称 |

**示例：**

```bash
devecocli skills list
devecocli skills list --long
devecocli skills list -l
```

### `skills find`

按关键词搜索 `Skill`

**命令格式：**

```bash
devecocli skills find <keyword>
```

**参数：**

| 参数名 | 说明 |
| --- | --- |
| keyword | 必选，搜索关键词 |

**示例：**

```bash
devecocli skills find deveco
```

### `skills add`

将 `Skill` 添加到智能体中

**命令格式：**

```bash
devecocli skills add --all --agent <agents> --skill <skill-name> --project <path> --path <path> --force
```

**参数：**

| 参数名 | 说明 |
| --- | --- |
| \--all | 可选，添加所有可用的 `Skill` ，与 `--skill` 二选一 |
| \--agent | 可选，智能体名称，多个智能体时以英文逗号分隔。缺省时，添加到已检测到的智能体中 |
| \--skill | 可选，待添加的 `Skill` 名称，与 `--all` 二选一 |
| \--project | 可选，指定项目路径，将 `Skill` 添加到该工程项目中 |
| \--path | 可选，指定路径，将 `Skill` 添加到该路径，不可与 `--project` 或 `--agent` 同时使用 |
| \-f，--force | 可选，当目标位置已有同名 `Skill` 时，覆盖重添加 |

**示例：**

```bash
devecocli skills add --all
devecocli skills add --skill skillname --agent agentname --force # skillname需替换成实际的Skill名称
devecocli skills add --skill skillname --project ./my-app  # skillname需替换成实际的Skill名称
```

### `skills remove`

从智能体中删除已添加的 `Skill`

**命令格式：**

```bash
devecocli skills remove --skill <skill-name> --agent <agents> --project <path> --path <path>
```

**参数：**

| 参数名 | 说明 |
| --- | --- |
| \--skill | 必选，待删除的 `Skill` 名称 |
| \--agent | 可选，智能体名称，多个智能体时以英文逗号分隔。缺省时，删除到已检测到的智能体中的 `Skill` |
| \--project | 可选，指定项目路径，删除该项目中的 `Skill` |
| \--path | 可选，指定路径，删除该项目中的 `Skill`，不可与 `--project` 或 `--agent` 同时使用 |

**示例：**

```bash
devecocli skills remove --skill skillname  # skillname需替换成实际的Skill名称
devecocli skills remove --skill skillname --agent agentname  # skillname需替换成实际的Skill名称
```

### `serve mcp`

启动本地 `MCP` 服务。智能体配置 `MCP` 服务后，可通过 `MCP` 协议调用下方列出的代码分析与语言特性工具。不同智能体平台配置 `MCP` 服务的界面不一样，一个智能体平台的配置示例如下。 推荐通过 `devecocli init --mcp` 自动配置

```bash
{
  "mcp": {
    "deveco-mcp": {
      "type": "local",
      "command": [
        "devecocli",
        "serve",
        "mcp"
      ],
      "environment":{
        "PROJECT_PATH": "/path/to/project", // 工程路径
        "NODE_MAX_OLD_SPACE_SIZE": "8192", // 可选，设置内部node进程最大的老生代内存大小，默认为8192
      },
      "enbale": true
    }
  }
}
```

#### MCP 工具

`deveco-mcp` 服务遵循 [MCP](https://modelcontextprotocol.io/) 规范，通过 `tools/list` 暴露工具、由模型经 `tools/call` 调用。每个工具由**名称**、**描述**和 **JSON Schema 入参**定义；返回值为 `content` 文本数组，`isError: true` 表示执行错误。

**工具总览：**

| 工具名 | 用途 | 支持语言 |
| --- | --- | --- |
| `check` | 静态语法分析，返回结构化诊断信息 | ArkTS、C/C++ |
| `hover` | 获取指定位置的悬浮信息（类型、文档） | ArkTS、C/C++ |
| `definition` | 查找符号定义位置 | ArkTS、C/C++ |
| `declaration` | 查找符号声明位置（ArkTS 中可能与定义不同） | ArkTS、C/C++ |
| `references` | 查找符号在全工程中的所有引用 | ArkTS、C/C++ |
| `implementation` | 查找符号的实现（如接口实现） | ArkTS、C/C++ |
| `workspaceSymbol` | 按名称在全工程搜索符号 | ArkTS、C/C++ |
| `documentSymbol` | 获取单文件的符号树（函数、类、变量及范围） | ArkTS、C/C++ |
| `callHierarchy` | 查询函数调用关系（incoming=调用方，outgoing=被调用方） | ArkTS 双向、C/C++ 仅 incoming |
| `restart` | 原地重启（重置状态 + 重新 sync/init），不杀进程、客户端不断开；ERROR 态可用 | ArkTS、C/C++（可按 target 单选） |

**可用性说明：**

-   `check` 与 `restart` 始终注册；其余 7 个语言特性工具仅在 DevEco Studio 附带标准 LSP 服务入口（`standardIndex/index.js`）时注册，老版本将不暴露这些工具。
-   所有语言特性工具需项目进入 `READY` 状态（`ohpm install` + `hvigor sync` + LSP 初始化完成）后才可用；未就绪时返回 `please retry in N seconds`，模型可稍后重试。`restart` 例外：它正是用于把 server 从 `ERROR` 态拉回，调用后返回"约 10 秒后重试"，后台异步重置并重新 sync/init。
-   C/C++ 工具需要工程包含 C++ 模块；无 C++ 代码时返回 `No C++ code`。
-   支持的文件扩展名：ArkTS 为 `.ets`；C/C++ 为 `.c` `.cc` `.cpp` `.cxx` `.c++` `.h` `.hh` `.hpp` `.hxx` `.h++` `.ipp` `.ixx` `.inl` `.inc` `.tpp`。
-   不属于当前工程的路径会被拒绝。

**入参定义：**

##### `check`

对传入的源文件进行静态语法分析并返回诊断信息，支持 ArkTS 与 C/C++ 在同一次调用中混合传入。

| 参数 | 类型 | 必选 | 说明 |
| --- | --- | --- | --- |
| `files` | string\[\] | 是 | 待检查的源文件路径列表，相对工程根目录，至少 1 个 |

##### `hover` / `definition` / `declaration` / `references` / `implementation`

位置类语言特性，共享同一入参结构。返回该位置符号的类型/文档信息、定义/声明位置、引用列表或实现列表。

| 参数 | 类型 | 必选 | 说明 |
| --- | --- | --- | --- |
| `file` | string | 是 | 源文件路径，相对工程根目录，支持 `.ets` 与 C/C++ 扩展名 |
| `line` | number | 是 | 行号，0-based |
| `character` | number | 是 | 列号（字符偏移），0-based |

##### `workspaceSymbol`

按名称在全工程搜索符号，无需打开具体文件。

| 参数 | 类型 | 必选 | 说明 |
| --- | --- | --- | --- |
| `query` | string | 是 | 符号名称或片段，非空 |

##### `documentSymbol`

获取单个文件的符号树，适合文件概览、结构化拆解和大文件切片。

| 参数 | 类型 | 必选 | 说明 |
| --- | --- | --- | --- |
| `file` | string | 是 | 源文件路径，相对工程根目录，支持 `.ets` 与 C/C++ 扩展名 |

##### `callHierarchy`

查询某位置函数的调用关系。

| 参数 | 类型 | 必选 | 说明 |
| --- | --- | --- | --- |
| `file` | string | 是 | 源文件路径，相对工程根目录，支持 `.ets` 与 C/C++ 扩展名 |
| `line` | number | 是 | 行号，0-based |
| `character` | number | 是 | 列号（字符偏移），0-based |
| `direction` | enum | 是 | `incoming`\=谁调用了该函数；`outgoing`\=该函数调用了谁。ArkTS 支持双向，C/C++（clangd）仅 `incoming` |

##### `restart`

原地重启 MCP server：重置双侧状态并重新 sync/init（ohpm install + hvigor sync + compileNative + LSP 握手），不杀进程、客户端连接保持。用于 sync/init 失败导致 server 停在 `ERROR` 态时（免去退出并重开 agent）。fire-and-forget：立即返回"约 10 秒后重试"，重置在后台异步进行。**注意：`restart` 仅在修复根因后用于恢复，不能修复错误的工程配置。若重启后再次失败，说明是持久性配置问题（oh-package.json5/build-profile.json5 无效、ohpm install 或 hvigor sync 失败、SDK 版本不符等），不要循环调用 `restart`，应请用户排查并修复工程后再重试。**

| 参数 | 类型 | 必选 | 说明 |
| --- | --- | --- | --- |
| `target` | enum | 否 | 重启哪一侧：`arkts`（ArkTS ace-server）、`cpp`（C++ clangd）、`all`（双侧，默认）。省略等同 `all` |

### `serve lsp`

启动本地 `LSP` 语言服务。智能体配置 `LSP` 服务后，可通过 `LSP` 协议获取代码补全、跳转定义、悬浮提示、引用查找、诊断等语言特性。当前支持 `ArkTS`和 `clangd`。

```bash
{
  "lsp": {
    "ArkTS": {
      "command": [
        "devecocli",
        "serve",
        "lsp",
        "--arkts"
      ],
      "extensions": [
        ".ets"
      ]
    },
    "clangd": {
      "command": [
        "devecocli",
        "serve",
        "lsp",
        "--cpp"
      ],
      "extensions": [
        ".c",
        ".cpp",
        ".cc",
        ".cxx",
        ".h",
        ".hpp",
        ".hxx",
        ".hh"
      ]
    }
  }
}
```

**参数：**

| 参数名 | 说明 |
| --- | --- |
| `--arkts` | 与 `--cpp` 二选一，启动 ArkTS 语言服务（ace-server） |
| `--cpp` | 与 `--arkts` 二选一，启动 C/C++ 语言服务（clangd） |
| `--project-path <path>` | 可选，工程根路径，默认为当前工作目录 |
| `--auto-detect` | 可选，当前目录向下查找工程根（检查当前目录自身及其子目录，最多 3 层子目录）；适用于 `--arkts` 和 `--cpp`；指定了 `--project-path` 则忽略 |

### `signature generate`

自动生成调试签名材料（包括p12密钥库、csr证书请求文件、p7b配置文件、cer证书文件），并将签名配置写入项目的 `build-profile.json5` 中。

**命令格式：**

```bash
devecocli signature generate  --product <product> --team-id <team-id> --udid <udid> --force --help
```

**参数：**

| 参数名 | 说明 |
| --- | --- |
| \--product <product> | 可选，指定product生成签名，默认为 `default` |
| \--team-id <team-id> | 可选，指定生效的team-id,默认使用自身作为团队信息 |
| \--udid <udid...> | 可选，为未连接的设备签名。可重复传入或用逗号分隔多台；追加 `:<type>` 声明设备类型（`phone`|`wearable`|`liteWearable`|`tv`，默认 `phone`）。与 `hdc` 自动探测到的设备合并，同一 UDID 以探测到的类型为准 |
| \--force | 可选，强制覆盖已存在的证书文件 |
| \--help,--h | 可选，查看帮助信息 |

**示例：**

```bash
# 自动生成签名并写入工程配置
devecocli signature generate

# 指定product
devecocli signature generate --product default

# 指定team-id
devecocli signature generate --team-id 1222

# 为未连接的设备签名（UDID 为 64 位十六进制，可通过已连接设备的 `hdc shell bm get -u` 获取）
devecocli signature generate --udid 1A2B3C4D...

# 为未连接的穿戴设备签名，并同时传入多台
devecocli signature generate --udid 1A2B3C4D...:wearable --udid 5E6F7A8B...

# 强制覆盖已存在的证书文件
devecocli signature generate --force

# 查询帮助信息
devecocli signature generate --help
```

## 常见问题

### 如何本地推包运行

当没有真机设备连接时，可以通过无线调试实现自连，在本地推包运行应用：

**步骤 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` 命令推包运行应用。

## 开发

```bash
npm install
npm run dev
npm start -- <command>
npm run lint
npm run format
npm run build
```

-   架构与目录说明见 [`AGENTS.md`](https://npmcn.com/package/%40deveco/deveco-cli-openharmony-arm64/AGENTS.md)
-   如需参与维护，建议先阅读 `AGENTS.md` 中的约定与架构说明

## 许可证

[MIT](https://npmcn.com/package/%40deveco/deveco-cli-openharmony-arm64/LICENSE)

## 常见问题

### @deveco/deveco-cli-openharmony-arm64 是什么？

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

### 如何安装 @deveco/deveco-cli-openharmony-arm64？

在项目目录运行 npm install @deveco/deveco-cli-openharmony-arm64，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 devecocli，可以用 npx devecocli 直接运行。

### @deveco/deveco-cli-openharmony-arm64 支持 TypeScript 吗？

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

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

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

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

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

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

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

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

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

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

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