@deveco-test/deveco-cli 0.8.0 → 1.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (6) hide show
  1. package/README.md +506 -247
  2. package/SKILL.md +2 -2
  3. package/THIRD-PARTY-LICENSES +1 -1
  4. package/dist/cli.js +62 -62
  5. package/docs.zip +0 -0
  6. package/package.json +1 -1
package/README.md CHANGED
@@ -2,8 +2,8 @@
2
2
  <h1>DevEco CLI</h1>
3
3
  <p>一个面向 HarmonyOS 应用开发的统一命令行入口。</p>
4
4
  <p>
5
- <a href="https://www.npmjs.com/package/@deveco-test/deveco-cli"><img src="https://img.shields.io/npm/v/@deveco-test/deveco-cli.svg" alt="NPM Version" /></a>
6
- <a href="https://www.npmjs.com/package/@deveco-test/deveco-cli"><img src="https://img.shields.io/npm/dm/@deveco-test/deveco-cli.svg" alt="NPM Downloads" /></a>
5
+ <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>
6
+ <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>
7
7
  <a href="https://nodejs.org/"><img src="https://img.shields.io/badge/Node.js-%3E%3D18-green.svg" alt="Node.js" /></a>
8
8
  <img src="https://img.shields.io/badge/platform-macOS%20%7C%20Windows-blue.svg" alt="Platform" />
9
9
  <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>
@@ -11,30 +11,22 @@
11
11
  </p>
12
12
  </div>
13
13
 
14
- `devecocli` 将 DevEco Studio 工具链统一封装为一个 CLI，内置 `ohpm`、`hvigor`、`hdc`、`emulator`、`hilog`，同时集成 HarmonyOS 技能安装、项目脚手架、本地 HarmonyOS 文档检索和 MCP 服务。
14
+ `DevEco CLI` 将 `DevEco Studio` 工具链统一封装为一个 `CLI`，内置 `ohpm`、`hvigor`、`hdc`、`emulator`、`hilog`，同时集成 HarmonyOS 技能安装、项目脚手架、本地 HarmonyOS 文档检索和 `MCP` 服务。
15
15
 
16
- 通过单一命令行工具即可完成创建、构建、安装、运行、日志查看、文档检索与 AI Agent 集成等开发流程，无需手动配置 `PATH`、`DEVECO_SDK_HOME` 或 `JAVA_HOME`。
17
-
18
- ## 为什么用它
19
-
20
- - 一条命令完成 `create`、`build`、`run`、`log` 等常见开发流程
21
- - 自动复用 DevEco Studio 自带工具链，减少本地环境配置成本
22
- - 同时支持真机、模拟器、日志诊断和本地文档检索
23
- - 支持给 `opencode`、`cursor`、`trae-cn` 等 AI Agent 注入技能和 MCP 配置
24
- - 面向 CLI 工作流，也适合作为自动化脚本和 Agent 的底层能力
25
16
 
26
17
  ## 快速开始
27
18
 
28
19
  ### 前置要求
29
20
 
30
- - Node.js >= 18
21
+ - 操作系统为 `macOS` 或 `Windows`
22
+ - Node.js >= 18，推荐使用22及以上版本
31
23
  - [DevEco Studio](https://developer.huawei.com/consumer/cn/download/) >= 6.1.0
32
- - 操作系统为 macOS 或 Windows
24
+ - **macOS**：必须安装在 `~/Applications` 或 `/Applications` 目录下。
33
25
 
34
26
  ### 安装
35
27
 
36
28
  ```bash
37
- npm install -g @deveco-test/deveco-cli@latest
29
+ npm install -g @deveco/deveco-cli@latest
38
30
  ```
39
31
 
40
32
  安装后可以通过以下命令更新到最新版本：
@@ -63,7 +55,7 @@ devecocli docs read harmonyos-guides/application-models/arkts-page-start-overvie
63
55
 
64
56
  ## AI Agent 集成
65
57
 
66
- `devecocli` 支持接入 `opencode`、`cursor`、`trae-cn` 等 AI Agent。下面以 `opencode` 为例展示最短流程：
58
+ `DevEco CLI` 支持通过命令行将自身技能添加到 `Agent` 中。下面以 `opencode` 为例展示最短流程：
67
59
 
68
60
  ```bash
69
61
  # 1. 给 opencode 安装 deveco-cli 技能
@@ -77,7 +69,13 @@ cd MyApp
77
69
  opencode
78
70
  ```
79
71
 
80
- 进入 Agent 后可以直接描述任务，例如：
72
+ 如果 `Agent` 不在 `--agent` 参数取值范围内，可使用 `--path` 参数进行添加，参考如下命令：
73
+
74
+ ```bash
75
+ devecocli init --path D:\work\ARKTS\NewData
76
+ ```
77
+
78
+ 进入 `Agent` 后可以直接描述任务，例如：
81
79
 
82
80
  - `Build this project in release mode and run it on my emulator`
83
81
  - `Tail the last error logs from this app`
@@ -94,35 +92,23 @@ opencode
94
92
  | `devecocli emulator list` | 查看本地模拟器实例 |
95
93
  | `devecocli log` | 查看 `hilog` 或崩溃日志 |
96
94
  | `devecocli docs search` | 搜索本地 HarmonyOS 文档 |
97
- | `devecocli init` | 安装内置技能或配置 MCP |
98
- | `devecocli skills` | 管理 HarmonyOS 技能市场中的技能 |
95
+ | `devecocli init` | 安装内置技能或配置 `MCP` |
96
+ | `devecocli skills` | 管理 HarmonyOS 技能市场中的技能 |
99
97
 
100
- ## 详细使用指南
98
+ ## 命令集
101
99
 
102
- 下面按使用场景保留完整的折叠式参数说明。
100
+ ### `help`
103
101
 
104
- <details>
105
- <summary><b>安装与要求</b></summary>
102
+ 查看版本、帮助信息以及所有子命令
106
103
 
107
- ### 前置要求
108
-
109
- - **DevEco Studio**：需已安装 DevEco Studio 6.1.0 或更高版本。
110
- - **Windows**：必须是安装版本，不支持便携版或解压版。默认安装路径为 `C:\Program Files\Huawei\DevEco Studio`。
111
- - **macOS**：必须安装在 `~/Applications` 或 `/Applications` 目录下，名称中包含 `deveco` 的 `.app` 即可被识别。
112
- - **Node.js**：运行时要求 Node.js 18 或更高版本。
113
-
114
- ### 安装版本说明
104
+ **命令格式：**
115
105
 
116
106
  ```bash
117
- npm install -g @deveco-test/deveco-cli@latest
107
+ devecocli help
118
108
  ```
119
109
 
120
- </details>
121
-
122
- <details>
123
- <summary><b>命令概览</b></summary>
124
-
125
110
  ```text
111
+ # 返回结果
126
112
  Usage: devecocli [options] [command]
127
113
 
128
114
  HarmonyOS application development command line tool
@@ -146,347 +132,620 @@ Commands:
146
132
  help [command] display help for command
147
133
  ```
148
134
 
149
- | 类别 | 命令 | 主要子命令 | 用途 |
150
- | ----- | ---------- | --------------------------------------------------------------------- | --------------------------------------- |
151
- | 项目脚手架 | `create` | - | 基于内置模板初始化新工程 |
152
- | 构建打包 | `build` | `clean` | 编译并产出 `.hap` / `.hsp` / `.har` / `.app` |
153
- | 部署运行 | `run` | - | 安装并启动应用 |
154
- | 设备管理 | `device` | `list` / `view` | 查看当前连接设备与详情 |
155
- | 模拟器 | `emulator` | `list` / `start` / `stop` / `create` / `delete` / `image` / `license` | 管理本地模拟器实例与系统镜像 |
156
- | 日志诊断 | `log` | - | 获取 `hilog` 与崩溃日志 |
157
- | 文档检索 | `docs` | `search` / `read` / `catalog` | 检索本地 HarmonyOS 文档 |
158
- | 技能初始化 | `init` | - | 安装内置 `deveco-cli` 技能或配置 `deveco-mcp` |
159
- | 技能管理 | `skills` | `list` / `find` / `add` / `remove` | 管理 HarmonyOS 技能市场中的技能 |
160
- | 辅助服务 | `serve` | `mcp` | 启动内置辅助服务 |
161
- | 自更新 | `update` | - | 升级到最新版本 |
135
+ ### `init`
136
+
137
+ 将`deveco-cli` `Skill` 或者 `MCP` 服务配置到智能体中
138
+
139
+ **命令格式：**
140
+
141
+ ```bash
142
+ devecocli init --agent <agents> --project <path> --path <path> --skill --mcp --force
143
+ ```
144
+
145
+ **参数：**
146
+
147
+ | 参数名 | 说明 |
148
+ | ----------- | ----------------------------------------------------------------------------------------- |
149
+ | --agent | 可选，智能体名称，多个智能体名称以英文逗号分隔。缺省时配置到所有已检测到的智能体中 |
150
+ | --project | 可选，指定工程路径，将`deveco-cli` `Skill` 或 `MCP` 服务安装到该工程项目中 |
151
+ | --path | 可选，指定 `deveco-cli` `Skill` 的配置路径。不可与 `--project` 、`--agent` 、 `--mcp` 同时使用 |
152
+ | --skill | 可选，安装 `deveco-cli` `Skill`。不可与 `--mcp` 同时使用。`--mcp` 与 `--skill` 都缺省时，执行 `--skill` |
153
+ | --mcp | 可选，配置 `MCP` 服务，与 `--project` 一起使用表示配置工程级 `MCP` 服务，独立使用表示配置用户级 `MCP` 服务。不可与 `--skill` 同时使用 |
154
+ | -f, --force | 可选，当目标位置已存在 `deveco-cli` `Skill` 或 `MCP` 服务时，覆盖重装 |
155
+
156
+ **示例：**
157
+
158
+ ```bash
159
+ # 配置Skill
160
+ devecocli init -f # 安装或更新deveco-cli Skill
161
+ devecocli init --skill
162
+ devecocli init --agent agentname # agentname需替换为实际的智能体名称
163
+ devecocli init --path D:\work\ARKTS\NewData -f
164
+
165
+ # 配置MCP
166
+ devecocli init --mcp
167
+ devecocli init --mcp --agent agentname # agentname需替换为实际的智能体名称
168
+ devecocli init --mcp --project D:\work\ARKTS\NewData -f
169
+ ```
170
+
171
+ ### `docs search`
172
+
173
+ 将关键词搜索版本说明、指南、API参考、最佳实践、`FAQ` 、变更预告等中的内容
174
+
175
+ **命令格式：**
176
+
177
+ ```bash
178
+ devecocli docs search <keywords...> --catalog <name> --format <fmt> --limit <n>
179
+ ```
180
+
181
+ **参数：**
182
+
183
+ | 参数名 | 说明 |
184
+ | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
185
+ | keywords... | 必选，搜索关键词，多个关键词用空格隔开 |
186
+ | --catalog | 可选，文档类别，取值包含`harmonyos-releases`（版本说明）、 `harmonyos-guides`（指南）、`harmonyos-references`（API参考）、`best-practices`（最佳实践）、`harmonyos-faqs`（FAQ）、`harmonyos-roadmap`（变更预告）、`all`（所有分类，默认） |
187
+ | --format | 可选，控制输出格式，取值包括 `default` 、`json` ，默认为`default` ，输出结果包括文档ID、标题、文档的概括内容 |
188
+ | --limit | 可选，设置搜索结果返回条数，默认为20 |
189
+
190
+ **示例：**
191
+
192
+ ```bash
193
+ devecocli docs search 沉浸光感
194
+ devecocli docs search '@State' '@Prop' --catalog best-practices --limit 10
195
+ devecocli docs search Row Column --format json
196
+ ```
197
+
198
+ ### `docs read`
199
+
200
+ 按文档ID查询文档的完整内容
201
+
202
+ **命令格式：**
203
+
204
+ ```bash
205
+ devecocli docs read <documentId>
206
+ ```
207
+
208
+ **参数：**
209
+
210
+ | 参数名 | 说明 |
211
+ | ---------- | ------- |
212
+ | documentId | 必选，文档ID |
213
+
214
+ **示例：**
215
+
216
+ ```bash
217
+ devecocli docs read 开发指南/应用框架/UI_Design_Kit_UI设计套件/沉浸光感/ui-design-hds-component-material
218
+ ```
219
+
220
+ ### `docs catalog`
221
+
222
+ 查询文档分类和分类名称
223
+
224
+ **命令格式：**
225
+
226
+ ```bash
227
+ devecocli docs catalog --format <fmt>
228
+ ```
229
+
230
+ **参数：**
231
+
232
+ | 参数名 | 说明 |
233
+ | -------- | ----------------------------------------- |
234
+ | --format | 可选，输出格式，`default` 或 `json` ，默认为 `default` |
235
+
236
+ **示例：**
237
+
238
+ ```bash
239
+ devecocli docs catalog
240
+ devecocli docs catalog --format json
241
+ ```
242
+
243
+ ### `create`
244
+
245
+ 创建 HarmonyOS 应用工程，仅支持创建工程模板中的 `Empty Ability` 模板
246
+
247
+ **命令格式：**
248
+
249
+ ```bash
250
+ devecocli create --app-name <name> --project-path <path> --bundle-name <bundle> --api-level <level>
251
+ ```
252
+
253
+ **参数：**
162
254
 
163
- </details>
255
+ | 参数名 | 说明 |
256
+ | -------------- | ----------------------------------------------------------------- |
257
+ | --app-name | 必选，应用名称 |
258
+ | --project-path | 可选，工程路径，默认为：`./<appname>` |
259
+ | --bundle-name | 可选，包名，默认为：`com.example.<appname>` ，`appname` 自动转为小写 |
260
+ | --api-level | 可选，API级别，最小值为17，最大值从安装的 `Deveco Studio` 的 `HarmonyOS` `SDK` 中自动获取 |
164
261
 
165
- <details>
166
- <summary><b>创建项目</b></summary>
262
+ **示例：**
167
263
 
168
264
  ```bash
169
265
  devecocli create --project-path ./MyApp --app-name MyApp
266
+ devecocli create --project-path ./MyApp --app-name MyApp --bundle-name com.acme.myapp --api-level 23
267
+ devecocli create --app-name MyApp
170
268
  ```
171
269
 
172
- | 参数 | 说明 | 默认值 |
173
- | ------------------------ | ------------------------------ | ------------------------ |
174
- | `--project-path <path>` | 项目目录路径 | `./<app-name>` |
175
- | `--app-name <name>` | 应用名称，必填；以字母开头，仅含字母、数字、下划线 | - |
176
- | `--bundle-name <bundle>` | Bundle Name，默认根据 `app-name` 生成 | `com.example.<app-name>` |
177
- | `--api-level <level>` | API 级别（`>=17`），自动探测 SDK 版本 | 无 IDE 时默认 `23` |
270
+ ### `build`
178
271
 
179
- </details>
272
+ 编译并打包 HarmonyOS 工程或工程中的模块
180
273
 
181
- <details>
182
- <summary><b>构建与运行</b></summary>
274
+ **命令格式：**
183
275
 
184
276
  ```bash
185
- # 构建项目
186
- devecocli build
277
+ devecocli build --product <product> --modules <modules> --build-mode <mode>
278
+ ```
187
279
 
188
- # 构建指定模块
189
- devecocli build --modules entry library
280
+ **参数：**
190
281
 
191
- # 构建 release 版本
282
+ | 参数名 | 说明 |
283
+ | ------------ | ------------------------------------------------------------------------------------------------------- |
284
+ | --product | 可选，产品的名称，默认为 `default` |
285
+ | --modules | 可选，模块的名称。如需指定模块的 `target` 信息，使用 `module@target` 形式。当工程中只有一个模块时，可缺省；当工程中存在多个模块，且仅存在一个 `entry` 类型的模块时，可缺省 |
286
+ | --build-mode | 可选，构建模式，默认为 `debug` |
287
+
288
+ **示例：**
289
+
290
+ ```bash
192
291
  devecocli build --build-mode release
292
+ devecocli build --modules entry library
293
+ devecocli build --modules library@phone
294
+ devecocli build --product oversea --modules entry --build-mode release
295
+ ```
193
296
 
194
- # 构建并运行
195
- devecocli run
297
+ **说明：**
196
298
 
197
- # 运行到指定设备
198
- devecocli run --device 127.0.0.1:5555
299
+ - 选定模块的依赖会被自动解析和构建
300
+ - 执行`devecocli build --product <name>`命令后，产物为 `.app`
301
+ - 执行`devecocli build --product <name> --modules <m1>`命令后，产物为 `.hap` / `.hsp` / `.har`
199
302
 
200
- # 清理构建产物并停止 daemon
303
+ ### `build clean`
304
+
305
+ 清理 HarmonyOS 项目的构建产物
306
+
307
+ **命令格式：**
308
+
309
+ ```bash
201
310
  devecocli build clean
202
311
  ```
203
312
 
204
- ### `build` 参数
313
+ ### `emulator list`
205
314
 
206
- | 参数 | 说明 | 默认值 |
207
- | ------------------------ | ----------------------------------- | -------------------- |
208
- | `--product <product>` | Product 名称；仅指定该参数时构建整个 product | `default` |
209
- | `--modules <modules...>` | 指定模块，格式为 `module` 或 `module@target` | 单入口模块时自动检测；多入口时需显式指定 |
210
- | `--build-mode <mode>` | 构建模式（`debug` / `release` 等） | `debug` |
315
+ 查看模拟器实例
211
316
 
212
- ### `run` 参数
317
+ **命令格式：**
213
318
 
214
- | 参数 | 说明 | 默认值 |
215
- | --------------------- | ------------------------------------- | ------------------------------------ |
216
- | `--module <module>` | 要运行的模块，格式为 `module` 或 `module@target` | 单个可运行模块时自动检测 |
217
- | `--device <device>` | 目标设备，支持设备名称或序列号 | 单设备时自动检测 |
218
- | `--product <product>` | Product 名称 | `default` |
219
- | `--build-mode <mode>` | 构建模式 | `debug` |
220
- | `--ability <ability>` | 要启动的 Ability | 优先 `EntryAbility`，否则取模块中的第一个 Ability |
221
- | `--uninstall` | 安装前先卸载已有应用 | - |
222
- | `--skip-build` | 跳过构建步骤，直接部署已有产物 | - |
319
+ ```bash
320
+ devecocli emulator list
321
+ ```
223
322
 
224
- </details>
323
+ ### `emulator start`
225
324
 
226
- <details>
227
- <summary><b>设备与模拟器</b></summary>
325
+ 启动模拟器。首次使用时，需要签署 HarmonyOS 软件许可与服务协议，具体请参考 `emulator license accept`
228
326
 
229
- ### 设备管理
327
+ **命令格式：**
230
328
 
231
329
  ```bash
232
- # 列出已连接设备
233
- devecocli device list
330
+ devecocli emulator start [names...]
331
+ ```
234
332
 
235
- # 查看设备详情
236
- devecocli device view
237
- devecocli device view -t 127.0.0.1:5555
333
+ **参数：**
334
+
335
+ | 参数名 | 说明 |
336
+ | ----------- | ----------------------------------------- |
337
+ | \[names...] | 必选，模拟器实例名称，多个名称用空格隔开。若名称中带有空格，则名称需要添加英文引号 |
338
+
339
+ **示例：**
340
+
341
+ ```bash
342
+ devecocli emulator start Phone
343
+ devecocli emulator start Phone1 Phone2
238
344
  ```
239
345
 
240
- `device view` 参数：
346
+ **说明：**
347
+
348
+ - `emulator start` 命令仅支持启动 `release` 版本的模拟器
241
349
 
242
- - `-t, --target <serialOrName>`：目标设备，多设备时必填。
350
+ ### `emulator stop`
243
351
 
244
- > `run`、`log` 等命令中的 `--device` 同时支持设备名称模糊匹配和序列号精确匹配。
352
+ 关闭模拟器
245
353
 
246
- ### 模拟器管理
354
+ **命令格式：**
247
355
 
248
356
  ```bash
249
- # 列出所有模拟器
250
- devecocli emulator list
357
+ devecocli emulator stop [names...]
358
+ ```
359
+
360
+ **参数：**
361
+
362
+ | 参数名 | 说明 |
363
+ | ----------- | ----------------------------------------- |
364
+ | \[names...] | 必选，模拟器实例名称，多个名称用空格隔开。若名称中带有空格，则名称需要添加英文引号 |
251
365
 
252
- # 启动模拟器
253
- devecocli emulator start HarmonyOS_Phone
366
+ **示例：**
254
367
 
255
- # 停止模拟器
256
- devecocli emulator stop HarmonyOS_Phone
368
+ ```bash
369
+ devecocli emulator stop Phone
370
+ devecocli emulator stop 127.0.0.1:5555
371
+ ```
372
+
373
+ ### `emulator create`
257
374
 
258
- # 创建模拟器
375
+ 创建模拟器
376
+
377
+ **命令格式：**
378
+
379
+ ```bash
380
+ devecocli emulator create <name> --device-type <type> --os-version <version> --force
381
+ ```
382
+
383
+ **参数：**
384
+
385
+ | 参数名 | 说明 |
386
+ | ------------- | ------------------------------------------------------------------------------------------------------------------------------- |
387
+ | name | 必选，模拟器名称 |
388
+ | --device-type | 必选，模拟器设备类型，支持 `phone` ， `foldable` ， `widefold` ， `triplefold` ， `tablet` ， `2in1` ， `2in1 foldable` ， `tv` ， `wearable` ，全小写 |
389
+ | --os-version | 必选，模拟器镜像版本 |
390
+ | --force | 可选，覆盖已有同名的模拟器 |
391
+
392
+ **示例：**
393
+
394
+ ```bash
259
395
  devecocli emulator create MyPhone --device-type phone --os-version "HarmonyOS 6.0.1(21)"
396
+ ```
397
+
398
+ ### `emulator delete`
399
+
400
+ 创建模拟器
401
+
402
+ **命令格式：**
403
+
404
+ ```bash
405
+ devecocli emulator delete <name>
406
+ ```
260
407
 
261
- # 删除模拟器
408
+ **参数：**
409
+
410
+ | 参数名 | 说明 |
411
+ | ---- | -------------- |
412
+ | name | 必选，模拟器实例名称或序列号 |
413
+
414
+ **示例：**
415
+
416
+ ```bash
262
417
  devecocli emulator delete MyPhone
418
+ ```
419
+
420
+ ### `emulator image list`
421
+
422
+ 查询模拟器镜像列表
423
+
424
+ **命令格式：**
425
+
426
+ ```bash
427
+ devecocli emulator image list --device-type <type> --all --format <format>
428
+ ```
429
+
430
+ **参数：**
431
+
432
+ | 参数名 | 说明 |
433
+ | ------------- | -------------------------------------------------------------------------------------------------------------------------- |
434
+ | --device-type | 可选，模拟器设备类型，支持 `phone` ， `foldable` ， `widefold` ， `triplefold` ， `tablet` ， `2in1` ， `2in1 foldable` ， `tv` ， `wearable` |
435
+ | --all | 可选，查询已下载和未下载的所有镜像 |
436
+ | --format | 可选，控制输出格式，取值为 `table` 或 `json` ，默认为 `table` |
263
437
 
264
- # 系统镜像管理
438
+ **示例：**
439
+
440
+ ```bash
265
441
  devecocli emulator image list
266
- devecocli emulator image download --device-type phone --os-version "HarmonyOS 6.0.1(21)"
267
- devecocli emulator image remove --device-type phone --os-version "HarmonyOS 6.0.1(21)"
442
+ devecocli emulator image list --all
443
+ devecocli emulator image list --device-type phone
444
+ devecocli emulator image list --format json
445
+ ```
268
446
 
269
- # 许可协议
270
- devecocli emulator license view
271
- devecocli emulator license accept
447
+ ### `emulator image download`
448
+
449
+ 下载模拟器镜像。首次使用时，需要签署 HarmonyOS `SDK` 许可协议，具体请参考 `emulator license accept`
450
+
451
+ **命令格式：**
452
+
453
+ ```bash
454
+ devecocli emulator image download --device-type <type> --os-version <version> --force
272
455
  ```
273
456
 
274
- > `emulator start` 和 `emulator image download` 执行前会自动检查许可协议状态，未接受时将提示先运行 `emulator license accept`。
457
+ **参数：**
275
458
 
276
- **设备类型：** `phone`、`foldable`、`widefold`、`triplefold`、`tablet`、`2in1`、`2in1 foldable`、`wearable`、`tv`
459
+ | 参数名 | 说明 |
460
+ | ------------- | ------------------------------------------------------------------------------------------------------------------------------- |
461
+ | --device-type | 必选，模拟器设备类型，支持 `phone` ， `foldable` ， `widefold` ， `triplefold` ， `tablet` ， `2in1` ， `2in1 foldable` ， `tv` ， `wearable` ，全小写 |
462
+ | --os-version | 必选，模拟器镜像版本 |
463
+ | --force | 可选，覆盖已有的模拟器镜像 |
277
464
 
278
- ### `emulator create` 参数
465
+ **示例：**
279
466
 
280
- | 参数 | 说明 | 默认值 |
281
- | ------------------------ | ------------------------------------- | --- |
282
- | `<name>` | 模拟器名称，仅含字母、空格、数字、下划线 | - |
283
- | `--device-type <type>` | 设备类型，必填 | - |
284
- | `--os-version <version>` | 已下载的系统镜像版本，必填，须与 `image list` 中的值完全一致 | - |
285
- | `--force` | 覆盖已有实例 | - |
467
+ ```bash
468
+ devecocli emulator image download --device-type phone --os-version "HarmonyOS 6.0.1(21)" --force
469
+ ```
286
470
 
287
- ### `emulator image list` 参数
471
+ **说明：**
288
472
 
289
- | 参数 | 说明 | 默认值 |
290
- | ---------------------- | ---------------------- | ------- |
291
- | `--device-type <type>` | 按设备类型筛选 | 全部 |
292
- | `--all` | 列出所有镜像（已下载 + 未下载） | 仅已下载 |
293
- | `--format <format>` | 输出格式（`table` / `json`） | `table` |
473
+ - `emulator image download` 命令仅支持下载 `release` 版本的模拟器镜像
294
474
 
295
- ### `emulator image download` 参数
475
+ ### `emulator image remove`
296
476
 
297
- | 参数 | 说明 | 默认值 |
298
- | ------------------------ | ------------------------------------ | --- |
299
- | `--device-type <type>` | 设备类型，必填 | - |
300
- | `--os-version <version>` | 系统镜像版本，必填，例如 `"HarmonyOS 6.0.1(21)"` | - |
301
- | `--force` | 覆盖已存在的镜像 | - |
477
+ 删除模拟器镜像
302
478
 
303
- ### `emulator image remove` 参数
479
+ **命令格式：**
304
480
 
305
- | 参数 | 说明 | 默认值 |
306
- | ------------------------ | ----------------------------------- | --- |
307
- | `--device-type <type>` | 设备类型，必填 | - |
308
- | `--os-version <version>` | 系统镜像版本，必填，支持镜像标签和 `softwareVersion` | - |
481
+ ```bash
482
+ devecocli emulator image remove --device-type <type> --os-version <version>
483
+ ```
309
484
 
310
- </details>
485
+ **参数：**
311
486
 
312
- <details>
313
- <summary><b>日志与文档检索</b></summary>
487
+ | 参数名 | 说明 |
488
+ | ------------- | ------------------------------ |
489
+ | --device-type | 必选，模拟器设备类型，与下载镜像的device-type一致 |
490
+ | --os-version | 必选，模拟器镜像版本，与下载镜像的os-version一致 |
314
491
 
315
- ### 日志诊断
492
+ **示例：**
316
493
 
317
494
  ```bash
318
- # 获取日志
319
- devecocli log
495
+ devecocli emulator image remove --device-type phone --os-version "HarmonyOS 6.0.1(21)"
496
+ ```
320
497
 
321
- # 按级别过滤
322
- devecocli log --level E
498
+ ### `emulator license view`
499
+
500
+ 查看协议文本（只读）
501
+
502
+ **命令格式：**
323
503
 
324
- # 按应用过滤
325
- devecocli log --bundle-name com.example.app
504
+ ```bash
505
+ devecocli emulator license view
506
+ ```
326
507
 
327
- # 崩溃日志
328
- devecocli log --crash
508
+ ### `emulator license accept`
329
509
 
330
- # 实时日志
331
- devecocli log --follow
510
+ 查看并接受协议。使用模拟器需要同意 HarmonyOS 软件许可与服务协议，下载镜像需要同意 HarmonyOS `SDK` 许可协议
332
511
 
333
- # 时间窗口
334
- devecocli log --from 5m --tail 100
512
+ **命令格式：**
513
+
514
+ ```bash
515
+ devecocli emulator license accept
335
516
  ```
336
517
 
337
- | 参数 | 说明 | 默认值 |
338
- | ----------------------------- | --------------------------------- | -------- |
339
- | `--device <device>` | 目标设备，支持设备名称或序列号 | 单设备时自动检测 |
340
- | `--crash` | 崩溃日志模式 | - |
341
- | `--level <level>` | 日志级别（`D` / `I` / `W` / `E` / `F`） | - |
342
- | `--bundle-name <bundle-name>` | 按 Bundle Name 过滤 | - |
343
- | `--keyword <keyword>` | 关键词过滤 | - |
344
- | `--tail <num>` | 只显示最新 N 行 | - |
345
- | `--from <start>` | 起始偏移（如 `30s`、`5m`、`2.5m`） | - |
346
- | `--to <end>` | 结束偏移（格式同 `--from`） | - |
347
- | `--follow` | 实时跟随，不可与 `--to` 同时使用 | - |
518
+ ### `device list`
348
519
 
349
- ### 本地文档检索
520
+ 查询所有已连接的设备，包括真机设备和运行中的模拟器
521
+
522
+ **命令格式：**
350
523
 
351
524
  ```bash
352
- # 搜索文档
353
- devecocli docs search ArkTS Row layout
525
+ devecocli device list
526
+ ```
354
527
 
355
- # 指定目录搜索
356
- devecocli docs search @State @Prop --catalog harmonyos-guides --limit 10
528
+ ### `device view`
357
529
 
358
- # 阅读文档
359
- devecocli docs read harmonyos-guides/application-models/arkts-page-start-overview
530
+ 查询已连接的设备的详细信息，包括设备序列号、设备名称、设备类型、 `OS` 版本等
360
531
 
361
- # 列出所有目录
362
- devecocli docs catalog
532
+ **命令格式：**
533
+
534
+ ```bash
535
+ devecocli device view --target <serialOrName>
363
536
  ```
364
537
 
365
- 参数说明：
538
+ **参数：**
366
539
 
367
- - `search <keywords...>`：关键词搜索，支持多个关键词，采用 OR 逻辑，最多 10 个关键词。
368
- - `--catalog <name>`：指定目录，默认 `all`。
369
- - `--format <default|json>`：输出格式，默认 `default`。
370
- - `--limit <n>`：最大结果数，默认 `20`。
371
- - `read <documentId>`：根据文档 ID 阅读完整内容。
372
- - `catalog`：列出所有可用目录。
540
+ | 参数名 | 说明 |
541
+ | ----------- | ------------------------------------- |
542
+ | -t，--target | 可选，目标设备名称或序列号。多设备缺省时，会列出所有已连接设备序列号和名称 |
373
543
 
374
- </details>
544
+ **示例：**
375
545
 
376
- <details>
377
- <summary><b>AI Agent、技能与 MCP</b></summary>
546
+ ```bash
547
+ devecocli device view
548
+ devecocli device view --target 127.0.0.1:5555
549
+ devecocli device view -t "My Device Name"
550
+ ```
378
551
 
379
- ### 什么时候用 `init`、`skills`、`serve`
552
+ ### `run`
380
553
 
381
- - `init`：推荐新用户使用，用于安装内置 `deveco-cli` 技能或配置 `deveco-mcp`
382
- - `skills`：用于管理 HarmonyOS 技能市场中的技能
383
- - `serve`：用于启动内置辅助服务，当前仅有 `serve mcp`
554
+ 构建应用后，将应用安装到真机设备或模拟器上，并启动执行
384
555
 
385
- ### `init`
556
+ **命令格式：**
386
557
 
387
558
  ```bash
388
- # 安装技能到所有检测到的 AI Agent
389
- devecocli init
559
+ devecocli run --module <module> --device <device> --product <product> --build-mode <mode> --ability <ability> --uninstall --skip-build
560
+ ```
390
561
 
391
- # 仅安装技能到指定 Agent
392
- devecocli init --skill --agent opencode
562
+ **参数：**
393
563
 
394
- # 已安装过时强制更新技能
395
- devecocli init -f
564
+ | 参数名 | 说明 |
565
+ | ------------ | ------------------------------------------------------------------------------------------------------ |
566
+ | --module | 可选，模块名称。如需指定模块的 `target` 信息，使用 `module@target` 形式。当工程中只有一个可运行模块（ `entry` / `feature` / `shared` ）时，可缺省 |
567
+ | --device | 设备名称或设备序列号，单设备时可选，多设备时必选 |
568
+ | --product | 可选，产品的名称，默认为 `default` |
569
+ | --build-mode | 可选，构建模式名称，默认为 `debug` |
570
+ | --ability | 可选，待启动的 `Ability` ，默认：模块 `module.json5` 中的`mainElement` |
571
+ | --uninstall | 可选，安装前先卸载已有应用 |
572
+ | --skip-build | 可选，跳过构建操作，直接安装应用 。\*\*说明：\*\*使用该参数时，需确保对应模块已有构建产物 |
396
573
 
397
- # 配置全局 MCP 服务器
398
- devecocli init --mcp
574
+ **示例：**
399
575
 
400
- # 为指定 Agent 配置项目级 MCP 服务器
401
- devecocli init --mcp --agent opencode --project ./my-app
576
+ ```bash
577
+ devecocli run
578
+ devecocli run --module entry --device 127.0.0.1:5555
579
+ devecocli run --module library@phone --device 127.0.0.1:5555
580
+ devecocli run --product oversea --module entry --ability EntryAbility
581
+ devecocli run --build-mode release
582
+ devecocli run --uninstall
402
583
  ```
403
584
 
404
- | 参数 | 说明 | 默认值 |
405
- | ------------------ | ------------------------------ | ------------- |
406
- | `--agent <agents>` | 目标 Agent（逗号分隔） | 所有已检测到的 Agent |
407
- | `--project <path>` | 安装到项目目录 | - |
408
- | `--path <path>` | 直接安装到指定路径 | - |
409
- | `--skill` | 仅安装内置 `deveco-cli` 技能 | 默认行为 |
410
- | `--mcp` | 仅配置 `deveco-mcp` MCP 服务器，不安装技能 | - |
411
- | `-f, --force` | 强制覆盖已有配置 | - |
585
+ ### `log`
586
+
587
+ 查看`hilog`普通日志或崩溃日志
412
588
 
413
- ### `skills`
589
+ **命令格式：**
414
590
 
415
591
  ```bash
416
- # 列出技能列表
417
- devecocli skills list --long
592
+ devecocli log --device <device> --crash --level <level> --bundle-name <bundle-name> --keyword <keyword> --tail <num> --from <start> --to <end> --follow
593
+ ```
418
594
 
419
- # 搜索技能
420
- devecocli skills find harmony
595
+ **参数：**
421
596
 
422
- # 安装所有技能
423
- devecocli skills add --all
597
+ | 参数名 | 说明 |
598
+ | ------------- | -------------------------------------------------------------------------------------------------------------------------- |
599
+ | --device | 设备名称或设备序列号，单设备时可选，多设备时必选 |
600
+ | --crash | 可选，查看崩溃日志 |
601
+ | --level | 可选，日志级别，取值包括`D`（ `Debug` ）、`I`（ `Info` ）、`W`（ `Warn` ）、`E`（ `Error` ）、`F`（ `Fatal` ） |
602
+ | --bundle-name | 可选，根据包名查看日志 |
603
+ | --keyword | 可选，根据关键词查看日志，关键词区分大小写 |
604
+ | --tail | 可选，显示最新的N行日志，取值为正整数 |
605
+ | --from | 可选，起始时间，单位为`m`和`s`，`m`和`s`为小写，默认为`s`，`start`的取值需要大于等于`end` |
606
+ | --to | 可选，结束时间，单位为`m`和`s`，`m`和`s`为小写，默认为`s` 。不可与--follow同时使用。**说明：** 如当前时间为05：00，`start`设置为30s，`end`设置为10s，则起始时间为04：30，结束时间为04：50 |
607
+ | --follow | 可选，实时输出日志。不可与--to同时使用 |
424
608
 
425
- # 安装指定技能
426
- devecocli skills add --skill deveco-cli --agent cursor
609
+ **示例：**
427
610
 
428
- # 移除技能
429
- devecocli skills remove --skill deveco-cli
611
+ ```bash
612
+ devecocli log --level E
613
+ devecocli log --crash --bundle-name com.example.app
614
+ devecocli log --device 127.0.0.1:5555 --level W --keyword Init
615
+ devecocli log --tail 100 --from 5m --to 2m
616
+ devecocli log --follow --bundle-name com.example.app
430
617
  ```
431
618
 
432
- ### `serve mcp`
619
+ ### `skills list`
620
+
621
+ 查询可用的 `Skill`
622
+
623
+ **命令格式：**
624
+
625
+ ```bash
626
+ devecocli skills list --long
627
+ ```
628
+
629
+ **参数：**
630
+
631
+ | 参数名 | 说明 |
632
+ | --------- | ----------------------------------------------- |
633
+ | -l，--long | 可选，`Skill` 详情，包括描述和已安装的智能体列表。缺省时，仅显示 `Skill` 名称 |
634
+
635
+ **示例：**
433
636
 
434
637
  ```bash
435
- devecocli serve mcp
638
+ devecocli skills list
639
+ devecocli skills list --long
640
+ devecocli skills list -l
436
641
  ```
437
642
 
438
- `serve` 当前仅提供 `mcp` 子命令，用于以本地 `stdio` 模式启动 MCP 服务器，为 ArkTS 和 C/C++ 提供语法检查能力。
643
+ ### `skills find`
439
644
 
440
- </details>
645
+ 按关键词搜索 `Skill`
441
646
 
442
- <details>
443
- <summary><b>调试与常见问题</b></summary>
647
+ **命令格式：**
444
648
 
445
- ### 查看底层命令调用
649
+ ```bash
650
+ devecocli skills find <keyword>
651
+ ```
652
+
653
+ **参数：**
446
654
 
447
- 如需打印底层 `ohpm`、`hvigor`、`hdc`、`emulator` 等实际执行命令，可设置：
655
+ | 参数名 | 说明 |
656
+ | ------- | -------- |
657
+ | keyword | 必选，搜索关键词 |
658
+
659
+ **示例：**
448
660
 
449
661
  ```bash
450
- DEVECO_CLI_DEBUG=1 devecocli build
662
+ devecocli skills find deveco
451
663
  ```
452
664
 
453
- ### 常见问题
665
+ ### `skills add`
454
666
 
455
- **Q: CLI 报错找不到 DevEco Studio？**
667
+ 将 `Skill` 添加到智能体中
456
668
 
457
- A: 确保已安装 DevEco Studio 6.1.0 或更高版本。CLI 会按以下顺序探测：
669
+ **命令格式：**
458
670
 
459
- - **Windows**：注册表 -> `C:\Program Files\Huawei\DevEco Studio`
460
- - **macOS**：`~/Applications` -> `/Applications`
671
+ ```bash
672
+ devecocli skills add --all --agent <agents> --skill <skill-name> --project <path> --path <path> --force
673
+ ```
461
674
 
462
- **Q: 多设备环境下如何选择目标设备？**
675
+ **参数：**
463
676
 
464
- A: 使用 `--device` 指定设备名或序列号：
677
+ | 参数名 | 说明 |
678
+ | ---------- | --------------------------------------------------------- |
679
+ | --all | 可选，添加所有可用的 `Skill` ，与 `--skill` 二选一 |
680
+ | --agent | 可选，智能体名称，多个智能体时以英文逗号分隔。缺省时，添加到已检测到的智能体中 |
681
+ | --skill | 可选，待添加的 `Skill` 名称，与 `--all` 二选一 |
682
+ | --project | 可选，指定项目路径，将 `Skill` 添加到该工程项目中 |
683
+ | --path | 可选，指定路径，将 `Skill` 添加到该路径，不可与 `--project` 或 `--agent` 同时使用 |
684
+ | -f，--force | 可选，当目标位置已有同名 `Skill` 时，覆盖重添加 |
685
+
686
+ **示例：**
465
687
 
466
688
  ```bash
467
- devecocli run --device "My Phone"
468
- devecocli run --device 127.0.0.1:5555
689
+ devecocli skills add --all
690
+ devecocli skills add --skill skillname --agent agentname --force # skillname需替换成实际的Skill名称
691
+ devecocli skills add --skill skillname --project ./my-app # skillname需替换成实际的Skill名称
469
692
  ```
470
693
 
471
- **Q: 模拟器启动或下载镜像时被许可协议阻塞？**
694
+ ### `skills remove`
695
+
696
+ 从智能体中删除已添加的 `Skill`
472
697
 
473
- A: 需要在本地交互终端运行：
698
+ **命令格式：**
474
699
 
475
700
  ```bash
476
- devecocli emulator license accept
701
+ devecocli skills remove --skill <skill-name> --agent <agents> --project <path> --path <path>
477
702
  ```
478
703
 
479
- 确认 `y` 或 `yes` 后重试。AI Agent 无法替用户完成该交互步骤。
704
+ **参数：**
480
705
 
481
- **Q: 安装应用时提示** **`install sign info inconsistent`？**
706
+ | 参数名 | 说明 |
707
+ | --------- | -------------------------------------------------------- |
708
+ | --skill | 必选，待删除的 `Skill` 名称 |
709
+ | --agent | 可选，智能体名称，多个智能体时以英文逗号分隔。缺省时，删除到已检测到的智能体中的 `Skill` |
710
+ | --project | 可选，指定项目路径，删除该项目中的 `Skill` |
711
+ | --path | 可选，指定路径，删除该项目中的 `Skill`，不可与 `--project` 或 `--agent` 同时使用 |
482
712
 
483
- A: 使用 `--uninstall` 先卸载旧版本：
713
+ **示例：**
484
714
 
485
715
  ```bash
486
- devecocli run --uninstall
716
+ devecocli skills remove --skill skillname # skillname需替换成实际的Skill名称
717
+ devecocli skills remove --skill skillname --agent agentname # skillname需替换成实际的Skill名称
718
+ ```
719
+
720
+ ### `serve mcp`
721
+
722
+ 启动本地 `MCP` 服务。智能体配置 `MCP` 服务后，可通过 `MCP` 协议调用 `ArkTS` / `C++` 语法检查工具。不同智能体平台配置 `MCP` 服务的界面不一样，一个智能体平台的配置示例如下。
723
+ 推荐通过 `devecocli init --mcp` 自动配置
724
+
725
+ ```bash
726
+ {
727
+ "mcp": {
728
+ "deveco-mcp": {
729
+ "type": "local",
730
+ "command": [
731
+ "devecocli",
732
+ "serve",
733
+ "mcp"
734
+ ],
735
+ "environment":{
736
+ "PROJECT_PATH": "D:\\code\\sample_project", // 工程路径
737
+ "NODE_MAX_OLD_SPACE_SIZE": "8192", // 可选，设置内部node进程最大的老生代内存大小，默认为8192
738
+ "DEVECO_PATH": "D:\\Application\\DevEco Studio" // 可选，Deveco Studio的路径
739
+ },
740
+ "enbale": true
741
+ }
742
+ }
743
+ }
487
744
  ```
488
745
 
489
- </details>
746
+ ## 常见问题
747
+
748
+ [FAQ](https://gitcode.com/openharmony-sig/deveco-cli/wiki/FAQ.md)
490
749
 
491
750
  ## 开发
492
751