@deveco-test/deveco-cli 0.6.1 → 0.8.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 (29) hide show
  1. package/LICENSE +21 -21
  2. package/README.md +507 -507
  3. package/SKILL.md +116 -116
  4. package/THIRD-PARTY-LICENSES +3536 -3503
  5. package/dist/cli.js +60 -60
  6. package/package.json +2 -1
  7. package/templates/application/AppScope/app.json5 +10 -10
  8. package/templates/application/AppScope/resources/base/element/string.json +8 -8
  9. package/templates/application/AppScope/resources/base/media/layered_image.json +6 -6
  10. package/templates/application/build-profile.json5 +41 -41
  11. package/templates/application/code-linter.json5 +31 -31
  12. package/templates/application/entry/build-profile.json5 +32 -32
  13. package/templates/application/entry/hvigorfile.ts +7 -7
  14. package/templates/application/entry/obfuscation-rules.txt +19 -19
  15. package/templates/application/entry/oh-package.json5 +10 -10
  16. package/templates/application/entry/src/main/ets/entryability/EntryAbility.ets +62 -62
  17. package/templates/application/entry/src/main/ets/entrybackupability/EntryBackupAbility.ets +30 -30
  18. package/templates/application/entry/src/main/ets/pages/Index.ets +37 -37
  19. package/templates/application/entry/src/main/module.json5 +49 -49
  20. package/templates/application/entry/src/main/resources/base/element/color.json +7 -7
  21. package/templates/application/entry/src/main/resources/base/element/float.json +8 -8
  22. package/templates/application/entry/src/main/resources/base/element/string.json +15 -15
  23. package/templates/application/entry/src/main/resources/base/media/layered_image.json +6 -6
  24. package/templates/application/entry/src/main/resources/base/profile/backup_config.json +2 -2
  25. package/templates/application/entry/src/main/resources/base/profile/main_pages.json +5 -5
  26. package/templates/application/entry/src/main/resources/dark/element/color.json +7 -7
  27. package/templates/application/hvigor/hvigor-config.json5 +23 -23
  28. package/templates/application/hvigorfile.ts +7 -7
  29. package/templates/application/oh-package.json5 +10 -10
package/README.md CHANGED
@@ -1,507 +1,507 @@
1
- <div align="center">
2
- <h1>DevEco CLI</h1>
3
- <p>一个面向 HarmonyOS 应用开发的统一命令行入口。</p>
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>
7
- <a href="https://nodejs.org/"><img src="https://img.shields.io/badge/Node.js-%3E%3D18-green.svg" alt="Node.js" /></a>
8
- <img src="https://img.shields.io/badge/platform-macOS%20%7C%20Windows-blue.svg" alt="Platform" />
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>
10
- <a href="./LICENSE"><img src="https://img.shields.io/badge/license-MIT-green.svg" alt="License" /></a>
11
- </p>
12
- </div>
13
-
14
- `devecocli` 将 DevEco Studio 工具链统一封装为一个 CLI，内置 `ohpm`、`hvigor`、`hdc`、`emulator`、`hilog`，同时集成 HMOS 技能安装、项目脚手架、本地 HarmonyOS 文档检索和 MCP 服务。
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
-
26
- ## 快速开始
27
-
28
- ### 前置要求
29
-
30
- - Node.js >= 18
31
- - [DevEco Studio](https://developer.huawei.com/consumer/cn/download/) >= 6.1.0
32
- - 操作系统为 macOS 或 Windows
33
-
34
- ### 安装
35
-
36
- ```bash
37
- npm install -g @deveco-test/deveco-cli@latest
38
- ```
39
-
40
- 安装后可以通过以下命令更新到最新版本：
41
-
42
- ```bash
43
- devecocli update
44
- ```
45
-
46
- ### 最短工作流
47
-
48
- ```bash
49
- devecocli create --app-name MyApp
50
- cd MyApp
51
- devecocli run
52
- devecocli log --level E
53
- ```
54
-
55
- ### 文档检索
56
-
57
- ```bash
58
- devecocli docs search List
59
- devecocli docs read harmonyos-guides/application-models/arkts-page-start-overview
60
- ```
61
-
62
- 更多命令和参数可通过 `devecocli --help` 或各子命令的 `--help` 查看。
63
-
64
- ## AI Agent 集成
65
-
66
- `devecocli` 支持接入 `opencode`、`cursor`、`trae-cn` 等 AI Agent。下面以 `opencode` 为例展示最短流程：
67
-
68
- ```bash
69
- # 1. 给 opencode 安装 deveco-cli 技能
70
- devecocli init --agent opencode
71
-
72
- # 2. 给 opencode 在当前 HarmonyOS 项目配置 MCP
73
- devecocli init --mcp --agent opencode --project ./MyApp
74
-
75
- # 3. 进入项目并启动 opencode
76
- cd MyApp
77
- opencode
78
- ```
79
-
80
- 进入 Agent 后可以直接描述任务，例如：
81
-
82
- - `Build this project in release mode and run it on my emulator`
83
- - `Tail the last error logs from this app`
84
- - `Check for syntax errors in src/main/ets/pages/Index.ets`
85
-
86
- ## 常用命令
87
-
88
- | 命令 | 用途 |
89
- | ------------------------- | ----------------------------------------- |
90
- | `devecocli create` | 创建新的 HarmonyOS 项目 |
91
- | `devecocli build` | 构建项目并产出 `.hap` / `.hsp` / `.har` / `.app` |
92
- | `devecocli run` | 安装并运行应用 |
93
- | `devecocli device list` | 查看当前连接设备 |
94
- | `devecocli emulator list` | 查看本地模拟器实例 |
95
- | `devecocli log` | 查看 `hilog` 或崩溃日志 |
96
- | `devecocli docs search` | 搜索本地 HarmonyOS 文档 |
97
- | `devecocli init` | 安装内置技能或配置 MCP |
98
- | `devecocli skills` | 管理 HMOS 技能市场中的技能 |
99
-
100
- ## 详细使用指南
101
-
102
- 下面按使用场景保留完整的折叠式参数说明。
103
-
104
- <details>
105
- <summary><b>安装与要求</b></summary>
106
-
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
- ### 安装版本说明
115
-
116
- ```bash
117
- npm install -g @deveco-test/deveco-cli@latest
118
- ```
119
-
120
- </details>
121
-
122
- <details>
123
- <summary><b>命令概览</b></summary>
124
-
125
- ```text
126
- Usage: devecocli [options] [command]
127
-
128
- HarmonyOS application development command line tool
129
-
130
- Options:
131
- -V, --version output the version number
132
- -h, --help display help for command
133
-
134
- Commands:
135
- build [options] Build the HarmonyOS project
136
- run [options] Build and run the project on a connected device
137
- update Update deveco-cli to the latest version
138
- device Manage connected devices
139
- emulator Manage emulator instances
140
- skills Manage HMOS skills
141
- log [options] Obtain device application logs
142
- create [options] Scaffold a new HarmonyOS application project
143
- init [options] Install the deveco-cli skill or configure the deveco-mcp server into AI agents
144
- serve Host bundled auxiliary protocol servers
145
- docs [options] Search and read Harmony documentation from local docs directory
146
- help [command] display help for command
147
- ```
148
-
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` | 检索本地 Harmony 文档 |
158
- | 技能初始化 | `init` | - | 安装内置 `deveco-cli` 技能或配置 `deveco-mcp` |
159
- | 技能管理 | `skills` | `list` / `find` / `add` / `remove` | 管理 HMOS 技能市场中的技能 |
160
- | 辅助服务 | `serve` | `mcp` | 启动内置辅助服务 |
161
- | 自更新 | `update` | - | 升级到最新版本 |
162
-
163
- </details>
164
-
165
- <details>
166
- <summary><b>创建项目</b></summary>
167
-
168
- ```bash
169
- devecocli create --project-path ./MyApp --app-name MyApp
170
- ```
171
-
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` |
178
-
179
- </details>
180
-
181
- <details>
182
- <summary><b>构建与运行</b></summary>
183
-
184
- ```bash
185
- # 构建项目
186
- devecocli build
187
-
188
- # 构建指定模块
189
- devecocli build --modules entry library
190
-
191
- # 构建 release 版本
192
- devecocli build --build-mode release
193
-
194
- # 构建并运行
195
- devecocli run
196
-
197
- # 运行到指定设备
198
- devecocli run --device 127.0.0.1:5555
199
-
200
- # 清理构建产物并停止 daemon
201
- devecocli build clean
202
- ```
203
-
204
- ### `build` 参数
205
-
206
- | 参数 | 说明 | 默认值 |
207
- | ------------------------ | ----------------------------------- | -------------------- |
208
- | `--product <product>` | Product 名称；仅指定该参数时构建整个 product | `default` |
209
- | `--modules <modules...>` | 指定模块，格式为 `module` 或 `module@target` | 单入口模块时自动检测；多入口时需显式指定 |
210
- | `--build-mode <mode>` | 构建模式（`debug` / `release` 等） | `debug` |
211
-
212
- ### `run` 参数
213
-
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` | 跳过构建步骤，直接部署已有产物 | - |
223
-
224
- </details>
225
-
226
- <details>
227
- <summary><b>设备与模拟器</b></summary>
228
-
229
- ### 设备管理
230
-
231
- ```bash
232
- # 列出已连接设备
233
- devecocli device list
234
-
235
- # 查看设备详情
236
- devecocli device view
237
- devecocli device view -t 127.0.0.1:5555
238
- ```
239
-
240
- `device view` 参数：
241
-
242
- - `-t, --target <serialOrName>`：目标设备，多设备时必填。
243
-
244
- > `run`、`log` 等命令中的 `--device` 同时支持设备名称模糊匹配和序列号精确匹配。
245
-
246
- ### 模拟器管理
247
-
248
- ```bash
249
- # 列出所有模拟器
250
- devecocli emulator list
251
-
252
- # 启动模拟器
253
- devecocli emulator start HarmonyOS_Phone
254
-
255
- # 停止模拟器
256
- devecocli emulator stop HarmonyOS_Phone
257
-
258
- # 创建模拟器
259
- devecocli emulator create MyPhone --device-type phone --os-version "HarmonyOS 6.0.1(21)"
260
-
261
- # 删除模拟器
262
- devecocli emulator delete MyPhone
263
-
264
- # 系统镜像管理
265
- 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)"
268
-
269
- # 许可协议
270
- devecocli emulator license view
271
- devecocli emulator license accept
272
- ```
273
-
274
- > `emulator start` 和 `emulator image download` 执行前会自动检查许可协议状态，未接受时将提示先运行 `emulator license accept`。
275
-
276
- **设备类型：** `phone`、`foldable`、`widefold`、`triplefold`、`tablet`、`2in1`、`2in1 foldable`、`wearable`、`tv`
277
-
278
- ### `emulator create` 参数
279
-
280
- | 参数 | 说明 | 默认值 |
281
- | ------------------------ | ------------------------------------- | --- |
282
- | `<name>` | 模拟器名称，仅含字母、空格、数字、下划线 | - |
283
- | `--device-type <type>` | 设备类型，必填 | - |
284
- | `--os-version <version>` | 已下载的系统镜像版本，必填，须与 `image list` 中的值完全一致 | - |
285
- | `--force` | 覆盖已有实例 | - |
286
-
287
- ### `emulator image list` 参数
288
-
289
- | 参数 | 说明 | 默认值 |
290
- | ---------------------- | ---------------------- | ------- |
291
- | `--device-type <type>` | 按设备类型筛选 | 全部 |
292
- | `--all` | 列出所有镜像（已下载 + 未下载） | 仅已下载 |
293
- | `--format <format>` | 输出格式（`table` / `json`） | `table` |
294
-
295
- ### `emulator image download` 参数
296
-
297
- | 参数 | 说明 | 默认值 |
298
- | ------------------------ | ------------------------------------ | --- |
299
- | `--device-type <type>` | 设备类型，必填 | - |
300
- | `--os-version <version>` | 系统镜像版本，必填，例如 `"HarmonyOS 6.0.1(21)"` | - |
301
- | `--force` | 覆盖已存在的镜像 | - |
302
-
303
- ### `emulator image remove` 参数
304
-
305
- | 参数 | 说明 | 默认值 |
306
- | ------------------------ | ----------------------------------- | --- |
307
- | `--device-type <type>` | 设备类型，必填 | - |
308
- | `--os-version <version>` | 系统镜像版本，必填，支持镜像标签和 `softwareVersion` | - |
309
-
310
- </details>
311
-
312
- <details>
313
- <summary><b>日志与文档检索</b></summary>
314
-
315
- ### 日志诊断
316
-
317
- ```bash
318
- # 获取日志
319
- devecocli log
320
-
321
- # 按级别过滤
322
- devecocli log --level E
323
-
324
- # 按应用过滤
325
- devecocli log --bundle-name com.example.app
326
-
327
- # 崩溃日志
328
- devecocli log --crash
329
-
330
- # 实时日志
331
- devecocli log --follow
332
-
333
- # 时间窗口
334
- devecocli log --from 5m --tail 100
335
- ```
336
-
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` 同时使用 | - |
348
-
349
- ### 本地文档检索
350
-
351
- ```bash
352
- # 搜索文档
353
- devecocli docs search ArkTS Row layout
354
-
355
- # 指定目录搜索
356
- devecocli docs search @State @Prop --catalog harmonyos-guides --limit 10
357
-
358
- # 阅读文档
359
- devecocli docs read harmonyos-guides/application-models/arkts-page-start-overview
360
-
361
- # 列出所有目录
362
- devecocli docs catalog
363
- ```
364
-
365
- 参数说明：
366
-
367
- - `search <keywords...>`：关键词搜索，支持多个关键词，采用 OR 逻辑，最多 10 个关键词。
368
- - `--catalog <name>`：指定目录，默认 `all`。
369
- - `--format <default|json>`：输出格式，默认 `default`。
370
- - `--limit <n>`：最大结果数，默认 `20`。
371
- - `read <documentId>`：根据文档 ID 阅读完整内容。
372
- - `catalog`：列出所有可用目录。
373
-
374
- </details>
375
-
376
- <details>
377
- <summary><b>AI Agent、技能与 MCP</b></summary>
378
-
379
- ### 什么时候用 `init`、`skills`、`serve`
380
-
381
- - `init`：推荐新用户使用，用于安装内置 `deveco-cli` 技能或配置 `deveco-mcp`
382
- - `skills`：用于管理 HMOS 技能市场中的技能
383
- - `serve`：用于启动内置辅助服务，当前仅有 `serve mcp`
384
-
385
- ### `init`
386
-
387
- ```bash
388
- # 安装技能到所有检测到的 AI Agent
389
- devecocli init
390
-
391
- # 仅安装技能到指定 Agent
392
- devecocli init --skill --agent opencode
393
-
394
- # 已安装过时强制更新技能
395
- devecocli init -f
396
-
397
- # 配置全局 MCP 服务器
398
- devecocli init --mcp
399
-
400
- # 为指定 Agent 配置项目级 MCP 服务器
401
- devecocli init --mcp --agent opencode --project ./my-app
402
- ```
403
-
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` | 强制覆盖已有配置 | - |
412
-
413
- ### `skills`
414
-
415
- ```bash
416
- # 列出技能列表
417
- devecocli skills list --long
418
-
419
- # 搜索技能
420
- devecocli skills find harmony
421
-
422
- # 安装所有技能
423
- devecocli skills add --all
424
-
425
- # 安装指定技能
426
- devecocli skills add --skill deveco-cli --agent cursor
427
-
428
- # 移除技能
429
- devecocli skills remove --skill deveco-cli
430
- ```
431
-
432
- ### `serve mcp`
433
-
434
- ```bash
435
- devecocli serve mcp
436
- ```
437
-
438
- `serve` 当前仅提供 `mcp` 子命令，用于以本地 `stdio` 模式启动 MCP 服务器，为 ArkTS 和 C/C++ 提供语法检查能力。
439
-
440
- </details>
441
-
442
- <details>
443
- <summary><b>调试与常见问题</b></summary>
444
-
445
- ### 查看底层命令调用
446
-
447
- 如需打印底层 `ohpm`、`hvigor`、`hdc`、`emulator` 等实际执行命令，可设置：
448
-
449
- ```bash
450
- DEVECO_CLI_DEBUG=1 devecocli build
451
- ```
452
-
453
- ### 常见问题
454
-
455
- **Q: CLI 报错找不到 DevEco Studio？**
456
-
457
- A: 确保已安装 DevEco Studio 6.1.0 或更高版本。CLI 会按以下顺序探测：
458
-
459
- - **Windows**：注册表 -> `C:\Program Files\Huawei\DevEco Studio`
460
- - **macOS**：`~/Applications` -> `/Applications`
461
-
462
- **Q: 多设备环境下如何选择目标设备？**
463
-
464
- A: 使用 `--device` 指定设备名或序列号：
465
-
466
- ```bash
467
- devecocli run --device "My Phone"
468
- devecocli run --device 127.0.0.1:5555
469
- ```
470
-
471
- **Q: 模拟器启动或下载镜像时被许可协议阻塞？**
472
-
473
- A: 需要在本地交互终端运行：
474
-
475
- ```bash
476
- devecocli emulator license accept
477
- ```
478
-
479
- 确认 `y` 或 `yes` 后重试。AI Agent 无法替用户完成该交互步骤。
480
-
481
- **Q: 安装应用时提示** **`install sign info inconsistent`？**
482
-
483
- A: 使用 `--uninstall` 先卸载旧版本：
484
-
485
- ```bash
486
- devecocli run --uninstall
487
- ```
488
-
489
- </details>
490
-
491
- ## 开发
492
-
493
- ```bash
494
- npm install
495
- npm run dev
496
- npm start -- <command>
497
- npm run lint
498
- npm run format
499
- npm run build
500
- ```
501
-
502
- - 架构与目录说明见 [`AGENTS.md`](./AGENTS.md)
503
- - 如需参与维护，建议先阅读 `AGENTS.md` 中的约定与架构说明
504
-
505
- ## 许可证
506
-
507
- [MIT](./LICENSE)
1
+ <div align="center">
2
+ <h1>DevEco CLI</h1>
3
+ <p>一个面向 HarmonyOS 应用开发的统一命令行入口。</p>
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>
7
+ <a href="https://nodejs.org/"><img src="https://img.shields.io/badge/Node.js-%3E%3D18-green.svg" alt="Node.js" /></a>
8
+ <img src="https://img.shields.io/badge/platform-macOS%20%7C%20Windows-blue.svg" alt="Platform" />
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>
10
+ <a href="./LICENSE"><img src="https://img.shields.io/badge/license-MIT-green.svg" alt="License" /></a>
11
+ </p>
12
+ </div>
13
+
14
+ `devecocli` 将 DevEco Studio 工具链统一封装为一个 CLI，内置 `ohpm`、`hvigor`、`hdc`、`emulator`、`hilog`，同时集成 HarmonyOS 技能安装、项目脚手架、本地 HarmonyOS 文档检索和 MCP 服务。
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
+
26
+ ## 快速开始
27
+
28
+ ### 前置要求
29
+
30
+ - Node.js >= 18
31
+ - [DevEco Studio](https://developer.huawei.com/consumer/cn/download/) >= 6.1.0
32
+ - 操作系统为 macOS 或 Windows
33
+
34
+ ### 安装
35
+
36
+ ```bash
37
+ npm install -g @deveco-test/deveco-cli@latest
38
+ ```
39
+
40
+ 安装后可以通过以下命令更新到最新版本：
41
+
42
+ ```bash
43
+ devecocli update
44
+ ```
45
+
46
+ ### 最短工作流
47
+
48
+ ```bash
49
+ devecocli create --app-name MyApp
50
+ cd MyApp
51
+ devecocli run
52
+ devecocli log --level E
53
+ ```
54
+
55
+ ### 文档检索
56
+
57
+ ```bash
58
+ devecocli docs search List
59
+ devecocli docs read harmonyos-guides/application-models/arkts-page-start-overview
60
+ ```
61
+
62
+ 更多命令和参数可通过 `devecocli --help` 或各子命令的 `--help` 查看。
63
+
64
+ ## AI Agent 集成
65
+
66
+ `devecocli` 支持接入 `opencode`、`cursor`、`trae-cn` 等 AI Agent。下面以 `opencode` 为例展示最短流程：
67
+
68
+ ```bash
69
+ # 1. 给 opencode 安装 deveco-cli 技能
70
+ devecocli init --agent opencode
71
+
72
+ # 2. 给 opencode 在当前 HarmonyOS 项目配置 MCP
73
+ devecocli init --mcp --agent opencode --project ./MyApp
74
+
75
+ # 3. 进入项目并启动 opencode
76
+ cd MyApp
77
+ opencode
78
+ ```
79
+
80
+ 进入 Agent 后可以直接描述任务，例如：
81
+
82
+ - `Build this project in release mode and run it on my emulator`
83
+ - `Tail the last error logs from this app`
84
+ - `Check for syntax errors in src/main/ets/pages/Index.ets`
85
+
86
+ ## 常用命令
87
+
88
+ | 命令 | 用途 |
89
+ | ------------------------- | ----------------------------------------- |
90
+ | `devecocli create` | 创建新的 HarmonyOS 项目 |
91
+ | `devecocli build` | 构建项目并产出 `.hap` / `.hsp` / `.har` / `.app` |
92
+ | `devecocli run` | 安装并运行应用 |
93
+ | `devecocli device list` | 查看当前连接设备 |
94
+ | `devecocli emulator list` | 查看本地模拟器实例 |
95
+ | `devecocli log` | 查看 `hilog` 或崩溃日志 |
96
+ | `devecocli docs search` | 搜索本地 HarmonyOS 文档 |
97
+ | `devecocli init` | 安装内置技能或配置 MCP |
98
+ | `devecocli skills` | 管理 HarmonyOS 技能市场中的技能 |
99
+
100
+ ## 详细使用指南
101
+
102
+ 下面按使用场景保留完整的折叠式参数说明。
103
+
104
+ <details>
105
+ <summary><b>安装与要求</b></summary>
106
+
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
+ ### 安装版本说明
115
+
116
+ ```bash
117
+ npm install -g @deveco-test/deveco-cli@latest
118
+ ```
119
+
120
+ </details>
121
+
122
+ <details>
123
+ <summary><b>命令概览</b></summary>
124
+
125
+ ```text
126
+ Usage: devecocli [options] [command]
127
+
128
+ HarmonyOS application development command line tool
129
+
130
+ Options:
131
+ -V, --version output the version number
132
+ -h, --help display help for command
133
+
134
+ Commands:
135
+ build [options] Build the HarmonyOS project
136
+ run [options] Build and run the project on a connected device
137
+ update Update deveco-cli to the latest version
138
+ device Manage connected devices
139
+ emulator Manage emulator instances
140
+ skills Manage HarmonyOS skills
141
+ log [options] Obtain device application logs
142
+ create [options] Scaffold a new HarmonyOS application project
143
+ init [options] Install the deveco-cli skill or configure the deveco-mcp server into AI agents
144
+ serve Host bundled auxiliary protocol servers
145
+ docs [options] Search and read HarmonyOS documentation from local docs directory
146
+ help [command] display help for command
147
+ ```
148
+
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` | - | 升级到最新版本 |
162
+
163
+ </details>
164
+
165
+ <details>
166
+ <summary><b>创建项目</b></summary>
167
+
168
+ ```bash
169
+ devecocli create --project-path ./MyApp --app-name MyApp
170
+ ```
171
+
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` |
178
+
179
+ </details>
180
+
181
+ <details>
182
+ <summary><b>构建与运行</b></summary>
183
+
184
+ ```bash
185
+ # 构建项目
186
+ devecocli build
187
+
188
+ # 构建指定模块
189
+ devecocli build --modules entry library
190
+
191
+ # 构建 release 版本
192
+ devecocli build --build-mode release
193
+
194
+ # 构建并运行
195
+ devecocli run
196
+
197
+ # 运行到指定设备
198
+ devecocli run --device 127.0.0.1:5555
199
+
200
+ # 清理构建产物并停止 daemon
201
+ devecocli build clean
202
+ ```
203
+
204
+ ### `build` 参数
205
+
206
+ | 参数 | 说明 | 默认值 |
207
+ | ------------------------ | ----------------------------------- | -------------------- |
208
+ | `--product <product>` | Product 名称；仅指定该参数时构建整个 product | `default` |
209
+ | `--modules <modules...>` | 指定模块，格式为 `module` 或 `module@target` | 单入口模块时自动检测；多入口时需显式指定 |
210
+ | `--build-mode <mode>` | 构建模式（`debug` / `release` 等） | `debug` |
211
+
212
+ ### `run` 参数
213
+
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` | 跳过构建步骤，直接部署已有产物 | - |
223
+
224
+ </details>
225
+
226
+ <details>
227
+ <summary><b>设备与模拟器</b></summary>
228
+
229
+ ### 设备管理
230
+
231
+ ```bash
232
+ # 列出已连接设备
233
+ devecocli device list
234
+
235
+ # 查看设备详情
236
+ devecocli device view
237
+ devecocli device view -t 127.0.0.1:5555
238
+ ```
239
+
240
+ `device view` 参数：
241
+
242
+ - `-t, --target <serialOrName>`：目标设备，多设备时必填。
243
+
244
+ > `run`、`log` 等命令中的 `--device` 同时支持设备名称模糊匹配和序列号精确匹配。
245
+
246
+ ### 模拟器管理
247
+
248
+ ```bash
249
+ # 列出所有模拟器
250
+ devecocli emulator list
251
+
252
+ # 启动模拟器
253
+ devecocli emulator start HarmonyOS_Phone
254
+
255
+ # 停止模拟器
256
+ devecocli emulator stop HarmonyOS_Phone
257
+
258
+ # 创建模拟器
259
+ devecocli emulator create MyPhone --device-type phone --os-version "HarmonyOS 6.0.1(21)"
260
+
261
+ # 删除模拟器
262
+ devecocli emulator delete MyPhone
263
+
264
+ # 系统镜像管理
265
+ 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)"
268
+
269
+ # 许可协议
270
+ devecocli emulator license view
271
+ devecocli emulator license accept
272
+ ```
273
+
274
+ > `emulator start` 和 `emulator image download` 执行前会自动检查许可协议状态，未接受时将提示先运行 `emulator license accept`。
275
+
276
+ **设备类型：** `phone`、`foldable`、`widefold`、`triplefold`、`tablet`、`2in1`、`2in1 foldable`、`wearable`、`tv`
277
+
278
+ ### `emulator create` 参数
279
+
280
+ | 参数 | 说明 | 默认值 |
281
+ | ------------------------ | ------------------------------------- | --- |
282
+ | `<name>` | 模拟器名称，仅含字母、空格、数字、下划线 | - |
283
+ | `--device-type <type>` | 设备类型，必填 | - |
284
+ | `--os-version <version>` | 已下载的系统镜像版本，必填，须与 `image list` 中的值完全一致 | - |
285
+ | `--force` | 覆盖已有实例 | - |
286
+
287
+ ### `emulator image list` 参数
288
+
289
+ | 参数 | 说明 | 默认值 |
290
+ | ---------------------- | ---------------------- | ------- |
291
+ | `--device-type <type>` | 按设备类型筛选 | 全部 |
292
+ | `--all` | 列出所有镜像（已下载 + 未下载） | 仅已下载 |
293
+ | `--format <format>` | 输出格式（`table` / `json`） | `table` |
294
+
295
+ ### `emulator image download` 参数
296
+
297
+ | 参数 | 说明 | 默认值 |
298
+ | ------------------------ | ------------------------------------ | --- |
299
+ | `--device-type <type>` | 设备类型，必填 | - |
300
+ | `--os-version <version>` | 系统镜像版本，必填，例如 `"HarmonyOS 6.0.1(21)"` | - |
301
+ | `--force` | 覆盖已存在的镜像 | - |
302
+
303
+ ### `emulator image remove` 参数
304
+
305
+ | 参数 | 说明 | 默认值 |
306
+ | ------------------------ | ----------------------------------- | --- |
307
+ | `--device-type <type>` | 设备类型，必填 | - |
308
+ | `--os-version <version>` | 系统镜像版本，必填，支持镜像标签和 `softwareVersion` | - |
309
+
310
+ </details>
311
+
312
+ <details>
313
+ <summary><b>日志与文档检索</b></summary>
314
+
315
+ ### 日志诊断
316
+
317
+ ```bash
318
+ # 获取日志
319
+ devecocli log
320
+
321
+ # 按级别过滤
322
+ devecocli log --level E
323
+
324
+ # 按应用过滤
325
+ devecocli log --bundle-name com.example.app
326
+
327
+ # 崩溃日志
328
+ devecocli log --crash
329
+
330
+ # 实时日志
331
+ devecocli log --follow
332
+
333
+ # 时间窗口
334
+ devecocli log --from 5m --tail 100
335
+ ```
336
+
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` 同时使用 | - |
348
+
349
+ ### 本地文档检索
350
+
351
+ ```bash
352
+ # 搜索文档
353
+ devecocli docs search ArkTS Row layout
354
+
355
+ # 指定目录搜索
356
+ devecocli docs search @State @Prop --catalog harmonyos-guides --limit 10
357
+
358
+ # 阅读文档
359
+ devecocli docs read harmonyos-guides/application-models/arkts-page-start-overview
360
+
361
+ # 列出所有目录
362
+ devecocli docs catalog
363
+ ```
364
+
365
+ 参数说明：
366
+
367
+ - `search <keywords...>`：关键词搜索，支持多个关键词，采用 OR 逻辑，最多 10 个关键词。
368
+ - `--catalog <name>`：指定目录，默认 `all`。
369
+ - `--format <default|json>`：输出格式，默认 `default`。
370
+ - `--limit <n>`：最大结果数，默认 `20`。
371
+ - `read <documentId>`：根据文档 ID 阅读完整内容。
372
+ - `catalog`：列出所有可用目录。
373
+
374
+ </details>
375
+
376
+ <details>
377
+ <summary><b>AI Agent、技能与 MCP</b></summary>
378
+
379
+ ### 什么时候用 `init`、`skills`、`serve`
380
+
381
+ - `init`：推荐新用户使用，用于安装内置 `deveco-cli` 技能或配置 `deveco-mcp`
382
+ - `skills`：用于管理 HarmonyOS 技能市场中的技能
383
+ - `serve`：用于启动内置辅助服务，当前仅有 `serve mcp`
384
+
385
+ ### `init`
386
+
387
+ ```bash
388
+ # 安装技能到所有检测到的 AI Agent
389
+ devecocli init
390
+
391
+ # 仅安装技能到指定 Agent
392
+ devecocli init --skill --agent opencode
393
+
394
+ # 已安装过时强制更新技能
395
+ devecocli init -f
396
+
397
+ # 配置全局 MCP 服务器
398
+ devecocli init --mcp
399
+
400
+ # 为指定 Agent 配置项目级 MCP 服务器
401
+ devecocli init --mcp --agent opencode --project ./my-app
402
+ ```
403
+
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` | 强制覆盖已有配置 | - |
412
+
413
+ ### `skills`
414
+
415
+ ```bash
416
+ # 列出技能列表
417
+ devecocli skills list --long
418
+
419
+ # 搜索技能
420
+ devecocli skills find harmony
421
+
422
+ # 安装所有技能
423
+ devecocli skills add --all
424
+
425
+ # 安装指定技能
426
+ devecocli skills add --skill deveco-cli --agent cursor
427
+
428
+ # 移除技能
429
+ devecocli skills remove --skill deveco-cli
430
+ ```
431
+
432
+ ### `serve mcp`
433
+
434
+ ```bash
435
+ devecocli serve mcp
436
+ ```
437
+
438
+ `serve` 当前仅提供 `mcp` 子命令，用于以本地 `stdio` 模式启动 MCP 服务器，为 ArkTS 和 C/C++ 提供语法检查能力。
439
+
440
+ </details>
441
+
442
+ <details>
443
+ <summary><b>调试与常见问题</b></summary>
444
+
445
+ ### 查看底层命令调用
446
+
447
+ 如需打印底层 `ohpm`、`hvigor`、`hdc`、`emulator` 等实际执行命令，可设置：
448
+
449
+ ```bash
450
+ DEVECO_CLI_DEBUG=1 devecocli build
451
+ ```
452
+
453
+ ### 常见问题
454
+
455
+ **Q: CLI 报错找不到 DevEco Studio？**
456
+
457
+ A: 确保已安装 DevEco Studio 6.1.0 或更高版本。CLI 会按以下顺序探测：
458
+
459
+ - **Windows**：注册表 -> `C:\Program Files\Huawei\DevEco Studio`
460
+ - **macOS**：`~/Applications` -> `/Applications`
461
+
462
+ **Q: 多设备环境下如何选择目标设备？**
463
+
464
+ A: 使用 `--device` 指定设备名或序列号：
465
+
466
+ ```bash
467
+ devecocli run --device "My Phone"
468
+ devecocli run --device 127.0.0.1:5555
469
+ ```
470
+
471
+ **Q: 模拟器启动或下载镜像时被许可协议阻塞？**
472
+
473
+ A: 需要在本地交互终端运行：
474
+
475
+ ```bash
476
+ devecocli emulator license accept
477
+ ```
478
+
479
+ 确认 `y` 或 `yes` 后重试。AI Agent 无法替用户完成该交互步骤。
480
+
481
+ **Q: 安装应用时提示** **`install sign info inconsistent`？**
482
+
483
+ A: 使用 `--uninstall` 先卸载旧版本：
484
+
485
+ ```bash
486
+ devecocli run --uninstall
487
+ ```
488
+
489
+ </details>
490
+
491
+ ## 开发
492
+
493
+ ```bash
494
+ npm install
495
+ npm run dev
496
+ npm start -- <command>
497
+ npm run lint
498
+ npm run format
499
+ npm run build
500
+ ```
501
+
502
+ - 架构与目录说明见 [`AGENTS.md`](./AGENTS.md)
503
+ - 如需参与维护，建议先阅读 `AGENTS.md` 中的约定与架构说明
504
+
505
+ ## 许可证
506
+
507
+ [MIT](./LICENSE)