@deveco-test/deveco-cli 1.3.0-Test.9 → 1.3.1-Test.1
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.
- package/README.md +322 -78
- package/SKILL.md +23 -13
- package/THIRD-PARTY-LICENSES +245 -1028
- package/dist/cli.js +134 -122
- package/dist/internal/doc-init-background.js +1 -65
- package/dist/internal/telemetry-upload-background.js +9 -0
- package/docs.zip +0 -0
- package/index.zip +0 -0
- package/package.json +11 -17
- package/scripts/postinstall.mjs +1 -22
- package/scripts/install-better-sqlite3.mjs +0 -51
- package/scripts/install-jieba-wasm.mjs +0 -47
- package/scripts/lib/better-sqlite3-vendor.mjs +0 -129
- package/scripts/lib/cli-data-dir.mjs +0 -44
- package/scripts/lib/doc-init-log-path.mjs +0 -15
- package/scripts/lib/jieba-wasm-vendor.mjs +0 -102
package/README.md
CHANGED
|
@@ -4,15 +4,17 @@
|
|
|
4
4
|
<p>
|
|
5
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
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
|
-
<a href="https://nodejs.org/"><img src="https://img.shields.io/badge/Node.js-%3E%
|
|
7
|
+
<a href="https://nodejs.org/"><img src="https://img.shields.io/badge/Node.js-%3E%3D22-green.svg" alt="Node.js" /></a>
|
|
8
8
|
<img src="https://img.shields.io/badge/platform-macOS%20%7C%20Windows%20%7C%20Linux-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.
|
|
9
|
+
<a href="https://developer.huawei.com/consumer/cn/download/"><img src="https://img.shields.io/badge/DevEco%20Studio-%3E%3D6.0.0-orange.svg" alt="DevEco Studio" /></a>
|
|
10
10
|
<img src="https://img.shields.io/badge/Command%20Line%20Tools-%3E%3D26.0.0-orange.svg" alt="Command Line Tools" />
|
|
11
11
|
<a href="./LICENSE"><img src="https://img.shields.io/badge/license-MIT-green.svg" alt="License" /></a>
|
|
12
12
|
</p>
|
|
13
13
|
</div>
|
|
14
14
|
|
|
15
|
-
`DevEco CLI` 将 `DevEco Studio` 工具链统一封装为一个 `CLI`，内置 `ohpm`、`hvigor`、`hdc`、`emulator`、`hilog`，同时集成 HarmonyOS 技能安装、项目脚手架、本地
|
|
15
|
+
`DevEco CLI` 将 `DevEco Studio` 工具链统一封装为一个 `CLI`，内置 `ohpm`、`hvigor`、`hdc`、`emulator`、`hilog`，同时集成 HarmonyOS 技能安装、项目脚手架、本地 HarmonyOS 文档检索和 `MCP` 服务。
|
|
16
|
+
|
|
17
|
+
> 关于数据采集与隐私（遥测打点内容、存储加密、上报及关闭方式），请参阅 [PRIVACY.md](./PRIVACY.md)。
|
|
16
18
|
|
|
17
19
|
|
|
18
20
|
## 快速开始
|
|
@@ -20,8 +22,8 @@
|
|
|
20
22
|
### 前置要求
|
|
21
23
|
|
|
22
24
|
- 操作系统为 `macOS` 、 `Windows` 或 `Linux`（需配置对应环境变量）
|
|
23
|
-
- Node.js
|
|
24
|
-
- [DevEco Studio](https://developer.huawei.com/consumer/cn/download/) >= 6.
|
|
25
|
+
- 安装`Node.js`，推荐使用22及以上版本
|
|
26
|
+
- [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
|
|
25
27
|
- **macOS**：必须安装在 `~/Applications` 或 `/Applications` 目录下。
|
|
26
28
|
|
|
27
29
|
### 安装
|
|
@@ -73,7 +75,7 @@ DEVECO_CLI_STUDIO_PATH > DEVECO_CLI_CLT_PATH > Auto_Detect
|
|
|
73
75
|
|
|
74
76
|
| 平台 | DevEco Studio Auto_Detect | Command Line Tools | 最低版本 |
|
|
75
77
|
| ------- | --------------------------------------------- | ------------------ | ----------------------------- |
|
|
76
|
-
| Windows | 支持 | 可选 | Studio `6.
|
|
78
|
+
| Windows | 支持 | 可选 | Studio `6.0.0` / CLT `26.0.0` |
|
|
77
79
|
| macOS | 支持 | 可选 | 同上 |
|
|
78
80
|
| Linux | 不支持 | 必选 | CLT `26.0.0` |
|
|
79
81
|
|
|
@@ -105,6 +107,13 @@ cd MyApp
|
|
|
105
107
|
opencode
|
|
106
108
|
```
|
|
107
109
|
|
|
110
|
+
也支持 `atomcode`等 Agent，使用方式相同：
|
|
111
|
+
|
|
112
|
+
```bash
|
|
113
|
+
# 给 atomcode 安装技能
|
|
114
|
+
devecocli init --agent atomcode
|
|
115
|
+
```
|
|
116
|
+
|
|
108
117
|
如果 `Agent` 不在 `--agent` 参数取值范围内，可使用 `--path` 参数进行添加，参考如下命令：
|
|
109
118
|
|
|
110
119
|
```bash
|
|
@@ -117,6 +126,10 @@ devecocli init --path D:\work\ARKTS\NewData
|
|
|
117
126
|
- `Tail the last error logs from this app`
|
|
118
127
|
- `Check for syntax errors in src/main/ets/pages/Index.ets`
|
|
119
128
|
|
|
129
|
+
**说明：**
|
|
130
|
+
- 在`Windows`上搭配`devecocli`使用`opencode`时，推荐将[powershell 7](https://learn.microsoft.com/en-us/powershell/scripting/install/install-powershell-on-windows?view=powershell-7.6) 作为默认执行终端。
|
|
131
|
+
- 在`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)
|
|
132
|
+
|
|
120
133
|
## 常用命令
|
|
121
134
|
|
|
122
135
|
| 命令 | 用途 |
|
|
@@ -127,6 +140,8 @@ devecocli init --path D:\work\ARKTS\NewData
|
|
|
127
140
|
| `devecocli run` | 安装并运行应用 |
|
|
128
141
|
| `devecocli device list` | 查看当前连接设备 |
|
|
129
142
|
| `devecocli emulator list` | 查看本地模拟器实例 |
|
|
143
|
+
| `devecocli ui layout` | 导出设备屏幕上的 UI 节点树（布局、坐标、节点 ID） |
|
|
144
|
+
| `devecocli ui window list` | 查看设备窗口列表（为 `ui layout` / `ui click` 等提供窗口 ID） |
|
|
130
145
|
| `devecocli ui screenshot` | 对真机或模拟器执行 UI 截图 |
|
|
131
146
|
| `devecocli ui click` | 点击指定坐标或节点 ID |
|
|
132
147
|
| `devecocli ui swipe` | 自定义滑动（指定起点、终点和速度） |
|
|
@@ -135,6 +150,7 @@ devecocli init --path D:\work\ARKTS\NewData
|
|
|
135
150
|
| `devecocli docs search` | 搜索本地 HarmonyOS 文档 |
|
|
136
151
|
| `devecocli init` | 安装内置技能或配置 `MCP` |
|
|
137
152
|
| `devecocli skills` | 管理 HarmonyOS 技能市场中的技能 |
|
|
153
|
+
| `devecocli signature generate` | 自动生成调试签名材料并配置到项目 |
|
|
138
154
|
| `devecocli check compat` | 扫描源代码在两个 `SDK` 版本之间的 `API` 变更 |
|
|
139
155
|
|
|
140
156
|
## 命令集
|
|
@@ -174,6 +190,7 @@ Commands:
|
|
|
174
190
|
serve Host bundled auxiliary protocol servers
|
|
175
191
|
docs [options] Search and read HarmonyOS documentation from local docs directory
|
|
176
192
|
check Run DevEco project checks
|
|
193
|
+
signature Generate application signature
|
|
177
194
|
help [command] display help for command
|
|
178
195
|
```
|
|
179
196
|
|
|
@@ -230,7 +247,7 @@ devecocli docs search <keywords...> --catalog <name> --format <fmt> --limit <n>
|
|
|
230
247
|
| keywords... | 必选，搜索关键词，多个关键词用空格隔开 |
|
|
231
248
|
| --catalog | 可选，文档类别，取值包含`harmonyos-releases`（版本说明）、 `harmonyos-guides`（指南）、`harmonyos-references`（API参考）、`best-practices`（最佳实践）、`harmonyos-faqs`（FAQ）、`harmonyos-roadmap`（变更预告）、`all`（所有分类，默认） |
|
|
232
249
|
| --format | 可选，控制输出格式，取值包括 `default` 、`json` ，默认为`default` ，输出结果包括文档ID、标题、文档的概括内容 |
|
|
233
|
-
| --limit | 可选，设置搜索结果返回条数，默认为
|
|
250
|
+
| --limit | 可选，设置搜索结果返回条数，默认为10 |
|
|
234
251
|
|
|
235
252
|
**示例：**
|
|
236
253
|
|
|
@@ -405,6 +422,80 @@ devecocli build --product oversea --modules entry --build-mode release
|
|
|
405
422
|
devecocli build clean
|
|
406
423
|
```
|
|
407
424
|
|
|
425
|
+
### `check compat`
|
|
426
|
+
|
|
427
|
+
基于 `DevEco Studio` 自带的 `apkanalyzer-apiscan` 插件，扫描源代码在两个 `SDK` 版本之间的 `API` 变更情况。
|
|
428
|
+
|
|
429
|
+
**子命令：**
|
|
430
|
+
|
|
431
|
+
| 子命令 | 说明 |
|
|
432
|
+
| --- | --- |
|
|
433
|
+
| `devecocli check compat` | 默认执行工程级扫描 |
|
|
434
|
+
| `devecocli check compat --modules <m1> [m2...]` | 按模块扫描 |
|
|
435
|
+
| `devecocli check compat <file1> [file2...]` | 按文件扫描（仅支持 `.ets`/`.c`/`.cpp`） |
|
|
436
|
+
| `devecocli check compat versions` | 列出可用的目标 `SDK` 版本 |
|
|
437
|
+
|
|
438
|
+
**命令格式：**
|
|
439
|
+
|
|
440
|
+
```bash
|
|
441
|
+
devecocli check compat [files...] --source-version <ver> --target-version <ver> [--modules <m...>] [--format <default|csv|json>] [--output-path <path>] [--limit <n>]
|
|
442
|
+
```
|
|
443
|
+
|
|
444
|
+
**参数：**
|
|
445
|
+
|
|
446
|
+
| 参数名 | 说明 |
|
|
447
|
+
| --- | --- |
|
|
448
|
+
| `--source-version` | 必填，当前工程 `SDK` 版本 |
|
|
449
|
+
| `--target-version` | 必填，目标 `SDK` 版本 |
|
|
450
|
+
| `--modules` | 可选，指定扫描的模块（多个以空格分隔）。与文件参数互斥 |
|
|
451
|
+
| `--format` | 可选，输出格式。`default`/`csv`/`json`。默认 `default`（控制台输出文本，文件输出 `csv`） |
|
|
452
|
+
| `--output-path` | 可选，报告输出路径。目录或文件（扩展名必须与 `--format` 匹配） |
|
|
453
|
+
| `--limit` | 可选，控制台显示的最大记录数，默认 `100` |
|
|
454
|
+
|
|
455
|
+
**版本号说明：**
|
|
456
|
+
|
|
457
|
+
- 可用版本可通过 `devecocli check compat versions` 查看
|
|
458
|
+
- `zsh` 环境下版本号需用引号包裹（包含括号），例如 `"<source_version>"`、`"<target_version>"`
|
|
459
|
+
|
|
460
|
+
**`compat versions` 参数：**
|
|
461
|
+
|
|
462
|
+
| 参数名 | 说明 |
|
|
463
|
+
| --- | --- |
|
|
464
|
+
| `--format` | 可选，输出格式。`default` 或 `json`。默认 `default`（文本输出，每行一个版本号） |
|
|
465
|
+
|
|
466
|
+
**格式与输出组合：**
|
|
467
|
+
|
|
468
|
+
| 场景 | 允许的 `--format` | 行为 |
|
|
469
|
+
| --- | --- | --- |
|
|
470
|
+
| 控制台输出（无 `--output-path`） | `default` / `json` | `default` 输出文本表格，`json` 输出 `JSON` |
|
|
471
|
+
| 文件输出（`--output-path <file>`，扩展名必须匹配 `--format`） | `default` / `csv` / `json` | `default`/`csv` 写 `.csv` 文件；`json` 写 `.json` 文件 |
|
|
472
|
+
| 目录输出（`--output-path <dir>`，无扩展名） | `default` / `csv` / `json` | `default`/`csv` 生成 `apiChange-res{N}.csv`；`json` 生成 `apiChange-res{N}.json` |
|
|
473
|
+
|
|
474
|
+
**示例：**
|
|
475
|
+
|
|
476
|
+
```bash
|
|
477
|
+
# 工程级扫描，输出到控制台
|
|
478
|
+
devecocli check compat --source-version "<source_version>" --target-version "<target_version>"
|
|
479
|
+
|
|
480
|
+
# 输出 JSON 到控制台
|
|
481
|
+
devecocli check compat --format json --source-version "<source_version>" --target-version "<target_version>"
|
|
482
|
+
|
|
483
|
+
# 输出报告到目录（默认 csv）
|
|
484
|
+
devecocli check compat --output-path ./report --source-version "<source_version>" --target-version "<target_version>"
|
|
485
|
+
|
|
486
|
+
# 输出 JSON 报告到目录（生成 apiChange-res{N}.json）
|
|
487
|
+
devecocli check compat --output-path ./report --format json --source-version "<source_version>" --target-version "<target_version>"
|
|
488
|
+
|
|
489
|
+
# 输出报告到指定文件
|
|
490
|
+
devecocli check compat --output-path ./report.json --format json --source-version "<source_version>" --target-version "<target_version>"
|
|
491
|
+
|
|
492
|
+
# 文件级扫描
|
|
493
|
+
devecocli check compat ./entry/src/main/ets/pages/Index.ets --source-version "<source_version>" --target-version "<target_version>"
|
|
494
|
+
|
|
495
|
+
# 模块级扫描
|
|
496
|
+
devecocli check compat --modules entry har1 --source-version "<source_version>" --target-version "<target_version>"
|
|
497
|
+
```
|
|
498
|
+
|
|
408
499
|
### `check lint`
|
|
409
500
|
|
|
410
501
|
检查代码规范并输出实践建议与报告。
|
|
@@ -424,18 +515,33 @@ devecocli check lint [path]
|
|
|
424
515
|
| `--fix` | 自动修复可修复的问题 |
|
|
425
516
|
| `--incremental` | 仅检查 Git 未提交文件 |
|
|
426
517
|
| `--product <name>` | `build-profile.json5` 中定义的 product，默认为 `default` |
|
|
427
|
-
| `--format <default\|json>` | 完整报告格式；`default` 输出 Markdown，`json` 输出 JSON
|
|
428
|
-
| `--output-path <path>` |
|
|
518
|
+
| `--format <default\|json>` | 完整报告格式；`default` 输出 Markdown，`json` 输出 JSON；要求 DevEco Studio ≥ 6.1.0 |
|
|
519
|
+
| `--output-path <path>` | 完整报告文件或目录,目录形式会自动生成带时间戳的报告文件；要求 DevEco Studio ≥ 6.1.0 |
|
|
429
520
|
| `--limit <number>` | 未指定 `--output-path` 时，限制终端显示的问题数量 |
|
|
430
521
|
|
|
522
|
+
`emulator` 版本要求： DevEco Studio ≥ 6.1.0
|
|
523
|
+
|
|
431
524
|
### `emulator list`
|
|
432
525
|
|
|
433
526
|
查看模拟器实例
|
|
434
527
|
|
|
435
528
|
**命令格式：**
|
|
436
529
|
|
|
530
|
+
```bash
|
|
531
|
+
devecocli emulator list [--format <table|json>]
|
|
532
|
+
```
|
|
533
|
+
|
|
534
|
+
**参数：**
|
|
535
|
+
|
|
536
|
+
| 参数名 | 说明 |
|
|
537
|
+
| --- | --- |
|
|
538
|
+
| `--format` | 可选，控制终端输出格式，取值为 `table` 或 `json`，默认为 `table` |
|
|
539
|
+
|
|
540
|
+
**示例：**
|
|
541
|
+
|
|
437
542
|
```bash
|
|
438
543
|
devecocli emulator list
|
|
544
|
+
devecocli emulator list --format json
|
|
439
545
|
```
|
|
440
546
|
|
|
441
547
|
### `emulator start`
|
|
@@ -510,7 +616,7 @@ devecocli emulator sensor --target Phone --heartrate 80
|
|
|
510
616
|
**说明：**
|
|
511
617
|
|
|
512
618
|
- `--target` 支持模拟器名称或 `127.0.0.1:<port>` 序列号。
|
|
513
|
-
- `battery --level`
|
|
619
|
+
- `battery --level` 会自动查询模拟器当前充电状态：充电时取值范围为整数 `[0, 100]`，未充电时为 `[1, 100]`。
|
|
514
620
|
- `battery --status` 取值为 `charging` 或 `discharging`。
|
|
515
621
|
- `geolocation` 支持 `--longitude`、`--latitude`、`--altitude`、`--direction`。
|
|
516
622
|
- `scene` 取值为 `outdoorRunning`、`outdoorCycling`、`drivingNavigation`。
|
|
@@ -688,9 +794,15 @@ devecocli emulator license accept
|
|
|
688
794
|
**命令格式：**
|
|
689
795
|
|
|
690
796
|
```bash
|
|
691
|
-
devecocli device list
|
|
797
|
+
devecocli device list [--format <table|json>]
|
|
692
798
|
```
|
|
693
799
|
|
|
800
|
+
**参数：**
|
|
801
|
+
|
|
802
|
+
| 参数名 | 说明 |
|
|
803
|
+
| --- | --- |
|
|
804
|
+
| --format | 可选，输出格式。可选值：`table`、`json`，默认 `table` |
|
|
805
|
+
|
|
694
806
|
### `device view`
|
|
695
807
|
|
|
696
808
|
查询已连接的设备的详细信息，包括设备序列号、设备名称、设备类型、 `OS` 版本等
|
|
@@ -698,7 +810,7 @@ devecocli device list
|
|
|
698
810
|
**命令格式：**
|
|
699
811
|
|
|
700
812
|
```bash
|
|
701
|
-
devecocli device view --target <serialOrName>
|
|
813
|
+
devecocli device view [--target <serialOrName>] [--format <table|json>]
|
|
702
814
|
```
|
|
703
815
|
|
|
704
816
|
**参数：**
|
|
@@ -706,6 +818,7 @@ devecocli device view --target <serialOrName>
|
|
|
706
818
|
| 参数名 | 说明 |
|
|
707
819
|
| ----------- | ------------------------------------- |
|
|
708
820
|
| -t，--target | 可选，目标设备名称或序列号。多设备缺省时，会列出所有已连接设备序列号和名称 |
|
|
821
|
+
| --format | 可选，输出格式。可选值：`table`、`json`，默认 `table` |
|
|
709
822
|
|
|
710
823
|
**示例：**
|
|
711
824
|
|
|
@@ -713,6 +826,7 @@ devecocli device view --target <serialOrName>
|
|
|
713
826
|
devecocli device view
|
|
714
827
|
devecocli device view --target 127.0.0.1:5555
|
|
715
828
|
devecocli device view -t "My Device Name"
|
|
829
|
+
devecocli device view -t 127.0.0.1:5555 --format json
|
|
716
830
|
```
|
|
717
831
|
|
|
718
832
|
### `ui screenshot`
|
|
@@ -731,14 +845,13 @@ devecocli ui screenshot --device <name|serial> --display <displayId> --path <pat
|
|
|
731
845
|
| ------------------------ | ------------------------ | ---------- |
|
|
732
846
|
| --device \<name\|serial> | 真机或模拟器名称/序列号；多设备时必填 | 单设备自动选择 |
|
|
733
847
|
| --display \<displayId> | 目标屏幕 ID，可选 | 默认屏幕 |
|
|
734
|
-
| --path \<path> |
|
|
848
|
+
| --path \<path> | 必填，文件夹路径或 PNG 文件路径；支持相对于当前目录的路径，目录必须存在且可写，目标文件不能已存在 | 无 |
|
|
735
849
|
|
|
736
850
|
**示例：**
|
|
737
851
|
|
|
738
852
|
```bash
|
|
739
|
-
devecocli ui screenshot --device Phone
|
|
740
853
|
mkdir -p screenshots
|
|
741
|
-
devecocli ui screenshot --device Phone --path ./screenshots
|
|
854
|
+
devecocli ui screenshot --device Phone --path ./screenshots
|
|
742
855
|
devecocli ui screenshot --device Phone --display 0 --path ./screenshots/phone.png
|
|
743
856
|
```
|
|
744
857
|
|
|
@@ -746,6 +859,7 @@ devecocli ui screenshot --device Phone --display 0 --path ./screenshots/phone.pn
|
|
|
746
859
|
|
|
747
860
|
- `ui screenshot` 支持真机和模拟器。
|
|
748
861
|
- 仅有一个可用设备时可省略 `--device`，多个设备同时连接时必须指定。
|
|
862
|
+
- `--path` 可以使用相对于当前目录的路径。可以指定已存在的文件夹并自动生成 PNG 文件名，也可以指定完整的 PNG 文件路径；不会自动创建目录或覆盖已有文件。
|
|
749
863
|
- 截图能力统一通过 `ui screenshot` 提供，不放在模拟器场景操作命令中。
|
|
750
864
|
- 截图统一使用 `hdc shell snapshot_display` 和 `hdc file recv` 实现；设置 `DEVECO_CLI_DEBUG=1` 可查看实际执行命令。
|
|
751
865
|
|
|
@@ -973,6 +1087,78 @@ devecocli ui text "Hello World" --id search_box
|
|
|
973
1087
|
devecocli ui text "Hello World" --id search_box --window main_window
|
|
974
1088
|
```
|
|
975
1089
|
|
|
1090
|
+
### `ui layout`
|
|
1091
|
+
|
|
1092
|
+
导出设备屏幕上的 UI 节点树，输出每个节点的类型、节点 ID、坐标边界 `[left,top,right,bottom]`、文本及可交互标志（`clickable` / `longClickable` / `scrollable` / `checkable`）。
|
|
1093
|
+
|
|
1094
|
+
**命令格式：**
|
|
1095
|
+
|
|
1096
|
+
```bash
|
|
1097
|
+
devecocli ui layout --device <name|serial> --id <id> --window <windowId> --all-windows --depth <n> --format <fmt> --mode <full|simplified>
|
|
1098
|
+
```
|
|
1099
|
+
|
|
1100
|
+
**参数：**
|
|
1101
|
+
|
|
1102
|
+
| 参数名 | 说明 |
|
|
1103
|
+
| --- | --- |
|
|
1104
|
+
| --device \<name\|serial> | 目标设备，多设备时必填 |
|
|
1105
|
+
| --id \<id> | 节点 ID，筛选树中匹配节点（仅输出匹配节点，不带子节点，强制 JSON）。不可与未筛选的全树输出同时视为列表查询 |
|
|
1106
|
+
| --window \<windowId> | 目标窗口 ID，与 `--all-windows` 互斥 |
|
|
1107
|
+
| --all-windows | 包含所有窗口，与 `--window` 互斥 |
|
|
1108
|
+
| --depth \<n> | 树深度限制，`0`=不限制（默认），`1`=仅根，`2`=根+子节点 |
|
|
1109
|
+
| --format | 输出格式，`default` 或 `json`，默认 `default` |
|
|
1110
|
+
| --mode | 输出模式：`full`=完整原始树；`simplified`（默认）=折叠无 ID、无文本、无可交互标志的包装节点 |
|
|
1111
|
+
|
|
1112
|
+
**示例：**
|
|
1113
|
+
|
|
1114
|
+
```bash
|
|
1115
|
+
devecocli ui layout
|
|
1116
|
+
devecocli ui layout --device Phone
|
|
1117
|
+
devecocli ui layout --device Phone --format json
|
|
1118
|
+
devecocli ui layout --mode full --depth 2
|
|
1119
|
+
devecocli ui layout --id submit_button
|
|
1120
|
+
devecocli ui layout --window 15 --format json
|
|
1121
|
+
```
|
|
1122
|
+
|
|
1123
|
+
**说明：**
|
|
1124
|
+
|
|
1125
|
+
- `--mode simplified`（默认）会折叠无 `id`、无 `text`、无任何可交互标志的包装节点，使输出聚焦于有意义的可操作节点；根节点始终保留。`--depth` 在折叠后截断。
|
|
1126
|
+
- `--id` 用于按节点 ID 查询，返回所有匹配节点（`children` 置空），常配合 `ui click --id` / `ui text --id` 定位坐标。
|
|
1127
|
+
- 节点 `bounds` 为 `[left, top, right, bottom]`，`ui click --id` 等交互命令据此取中心坐标点击。
|
|
1128
|
+
- `--window` 的窗口 ID 可通过 `devecocli ui window list` 获取。
|
|
1129
|
+
|
|
1130
|
+
### `ui window list`
|
|
1131
|
+
|
|
1132
|
+
查看设备上的窗口列表，输出窗口 ID、名称、PID、所属屏幕 ID 及是否聚焦。为 `ui layout --window`、`ui click --window` 等命令提供窗口 ID。
|
|
1133
|
+
|
|
1134
|
+
**命令格式：**
|
|
1135
|
+
|
|
1136
|
+
```bash
|
|
1137
|
+
devecocli ui window list --device <name|serial> --format <fmt> --all
|
|
1138
|
+
```
|
|
1139
|
+
|
|
1140
|
+
**参数：**
|
|
1141
|
+
|
|
1142
|
+
| 参数名 | 说明 |
|
|
1143
|
+
| --- | --- |
|
|
1144
|
+
| --device \<name\|serial> | 目标设备，多设备时必填 |
|
|
1145
|
+
| --format | 输出格式，`default` 或 `json`，默认 `default` |
|
|
1146
|
+
| --all | 显示包含系统窗口在内的所有窗口；缺省时仅显示应用窗口（`type === 1`） |
|
|
1147
|
+
|
|
1148
|
+
**示例：**
|
|
1149
|
+
|
|
1150
|
+
```bash
|
|
1151
|
+
devecocli ui window list
|
|
1152
|
+
devecocli ui window list --device Phone
|
|
1153
|
+
devecocli ui window list --format json
|
|
1154
|
+
devecocli ui window list --all
|
|
1155
|
+
```
|
|
1156
|
+
|
|
1157
|
+
**说明：**
|
|
1158
|
+
|
|
1159
|
+
- 聚焦窗口在 `default` 格式下高亮显示。
|
|
1160
|
+
- 缺省时仅列出应用窗口；加 `--all` 可查看系统窗口，用于排查多窗口场景。
|
|
1161
|
+
|
|
976
1162
|
### `run`
|
|
977
1163
|
|
|
978
1164
|
构建应用后，将应用安装到真机设备或模拟器上，并启动执行
|
|
@@ -980,21 +1166,23 @@ devecocli ui text "Hello World" --id search_box --window main_window
|
|
|
980
1166
|
**命令格式：**
|
|
981
1167
|
|
|
982
1168
|
```bash
|
|
983
|
-
devecocli run --module <module> --device <device> --product <product> --build-mode <mode> --ability <ability> --uninstall --skip-build --apply <
|
|
1169
|
+
devecocli run --module <module> --device <device> --product <product> --build-mode <mode> --ability <ability> --uninstall --skip-build --apply <fileName> --hotreload [action] --hotreload-apply <fileName>
|
|
984
1170
|
```
|
|
985
1171
|
|
|
986
1172
|
**参数：**
|
|
987
1173
|
|
|
988
|
-
| 参数名 | 说明
|
|
989
|
-
| ------------
|
|
990
|
-
| --module | 可选，模块名称。如需指定模块的 `target` 信息，使用 `module@target` 形式。当工程中只有一个可运行模块（ `entry` / `feature` / `shared` ）时，可缺省
|
|
991
|
-
| --device | 设备名称或设备序列号，单设备时可选，多设备时必选
|
|
992
|
-
| --product | 可选，产品的名称，默认为 `default`
|
|
993
|
-
| --build-mode | 可选，构建模式名称，默认为 `debug`
|
|
994
|
-
| --ability | 可选，待启动的 `Ability` ，默认：模块 `module.json5` 中的`mainElement`
|
|
995
|
-
| --uninstall | 可选，安装前先卸载已有应用
|
|
996
|
-
| --skip-build | 可选，跳过构建操作，直接安装应用 。\*\*说明：\*\*使用该参数时，需确保对应模块已有构建产物
|
|
997
|
-
| --apply \<fileName\> |
|
|
1174
|
+
| 参数名 | 说明 |
|
|
1175
|
+
| ------------ |------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|
|
1176
|
+
| --module | 可选，模块名称。如需指定模块的 `target` 信息，使用 `module@target` 形式。当工程中只有一个可运行模块（ `entry` / `feature` / `shared` ）时，可缺省 |
|
|
1177
|
+
| --device | 设备名称或设备序列号，单设备时可选，多设备时必选 |
|
|
1178
|
+
| --product | 可选，产品的名称，默认为 `default` |
|
|
1179
|
+
| --build-mode | 可选，构建模式名称，默认为 `debug` |
|
|
1180
|
+
| --ability | 可选，待启动的 `Ability` ，默认：模块 `module.json5` 中的`mainElement` |
|
|
1181
|
+
| --uninstall | 可选，安装前先卸载已有应用 |
|
|
1182
|
+
| --skip-build | 可选，跳过构建操作，直接安装应用 。\*\*说明：\*\*使用该参数时，需确保对应模块已有构建产物 |
|
|
1183
|
+
| --apply \<fileName\> | 可选，快速增量部署。仅重编改动文件并安装，比全量 `run` 快。`<fileName>` 为 `.hvigor/` 下的改动文件清单（每行一个相对工程根路径）。前提：DevEco Studio ≥6.1.1，且先跑过一次 `devecocli run` |
|
|
1184
|
+
| --hotreload [action] | 可选，使用热重载功能。使用热重载时，该命令需持续存活，以使热重载构建可以快速响应。当不需要时，执行 `devecocli run --hotreload stop` 去停止进程，释放资源 |
|
|
1185
|
+
| --hotreload-apply \<fileName\> | 可选，热重载（不重启应用即生效）。读取 `.hvigor/<fileName>` 改动清单，经编译安装使改动生效。前提：后台 `--hotreload` 进程在跑。范围：仅单个模块（`--module` 必填），且只支持 `.ets` 文件 |
|
|
998
1186
|
|
|
999
1187
|
**示例：**
|
|
1000
1188
|
|
|
@@ -1006,6 +1194,9 @@ devecocli run --product oversea --module entry --ability EntryAbility
|
|
|
1006
1194
|
devecocli run --build-mode release
|
|
1007
1195
|
devecocli run --uninstall
|
|
1008
1196
|
devecocli run --apply changes.txt
|
|
1197
|
+
devecocli run --hotreload
|
|
1198
|
+
devecocli run --hotreload stop
|
|
1199
|
+
devecocli run --hotreload-apply changes.txt
|
|
1009
1200
|
```
|
|
1010
1201
|
|
|
1011
1202
|
### `log`
|
|
@@ -1145,7 +1336,7 @@ devecocli skills remove --skill skillname --agent agentname # skillname需替
|
|
|
1145
1336
|
|
|
1146
1337
|
### `serve mcp`
|
|
1147
1338
|
|
|
1148
|
-
启动本地 `MCP` 服务。智能体配置 `MCP` 服务后，可通过 `MCP`
|
|
1339
|
+
启动本地 `MCP` 服务。智能体配置 `MCP` 服务后，可通过 `MCP` 协议调用下方列出的代码分析与语言特性工具。不同智能体平台配置 `MCP` 服务的界面不一样，一个智能体平台的配置示例如下。
|
|
1149
1340
|
推荐通过 `devecocli init --mcp` 自动配置
|
|
1150
1341
|
|
|
1151
1342
|
```bash
|
|
@@ -1161,7 +1352,8 @@ devecocli skills remove --skill skillname --agent agentname # skillname需替
|
|
|
1161
1352
|
"environment":{
|
|
1162
1353
|
"PROJECT_PATH": "D:\\code\\sample_project", // 工程路径
|
|
1163
1354
|
"NODE_MAX_OLD_SPACE_SIZE": "8192", // 可选，设置内部node进程最大的老生代内存大小，默认为8192
|
|
1164
|
-
"DEVECO_PATH": "D:\\Application\\DevEco Studio" // 可选，Deveco Studio的路径
|
|
1355
|
+
"DEVECO_PATH": "D:\\Application\\DevEco Studio", // 可选，Deveco Studio的路径
|
|
1356
|
+
"DEVECO_CLI_CPP_ENABLED": "true" // 可选，是否启用C++ LSP服务，默认为true，设为false可关闭
|
|
1165
1357
|
},
|
|
1166
1358
|
"enbale": true
|
|
1167
1359
|
}
|
|
@@ -1169,6 +1361,88 @@ devecocli skills remove --skill skillname --agent agentname # skillname需替
|
|
|
1169
1361
|
}
|
|
1170
1362
|
```
|
|
1171
1363
|
|
|
1364
|
+
#### MCP 工具
|
|
1365
|
+
|
|
1366
|
+
`deveco-mcp` 服务遵循 [MCP](https://modelcontextprotocol.io) 规范，通过 `tools/list` 暴露工具、由模型经 `tools/call` 调用。每个工具由**名称**、**描述**和 **JSON Schema 入参**定义；返回值为 `content` 文本数组，`isError: true` 表示执行错误。
|
|
1367
|
+
|
|
1368
|
+
**工具总览：**
|
|
1369
|
+
|
|
1370
|
+
| 工具名 | 用途 | 支持语言 |
|
|
1371
|
+
| --- | --- | --- |
|
|
1372
|
+
| `check` | 静态语法分析，返回结构化诊断信息 | ArkTS、C/C++ |
|
|
1373
|
+
| `hover` | 获取指定位置的悬浮信息（类型、文档） | ArkTS、C/C++ |
|
|
1374
|
+
| `definition` | 查找符号定义位置 | ArkTS、C/C++ |
|
|
1375
|
+
| `declaration` | 查找符号声明位置（ArkTS 中可能与定义不同） | ArkTS、C/C++ |
|
|
1376
|
+
| `references` | 查找符号在全工程中的所有引用 | ArkTS、C/C++ |
|
|
1377
|
+
| `implementation` | 查找符号的实现（如接口实现） | ArkTS、C/C++ |
|
|
1378
|
+
| `workspaceSymbol` | 按名称在全工程搜索符号 | ArkTS、C/C++ |
|
|
1379
|
+
| `documentSymbol` | 获取单文件的符号树（函数、类、变量及范围） | ArkTS、C/C++ |
|
|
1380
|
+
| `callHierarchy` | 查询函数调用关系（incoming=调用方，outgoing=被调用方） | ArkTS 双向、C/C++ 仅 incoming |
|
|
1381
|
+
| `restart` | 原地重启（重置状态 + 重新 sync/init），不杀进程、客户端不断开；ERROR 态可用 | ArkTS、C/C++（可按 target 单选） |
|
|
1382
|
+
|
|
1383
|
+
**可用性说明：**
|
|
1384
|
+
|
|
1385
|
+
- `check` 与 `restart` 始终注册；其余 7 个语言特性工具仅在 DevEco Studio 附带标准 LSP 服务入口（`standardIndex/index.js`）时注册，老版本将不暴露这些工具。
|
|
1386
|
+
- 所有语言特性工具需项目进入 `READY` 状态（`ohpm install` + `hvigor sync` + LSP 初始化完成）后才可用；未就绪时返回 `please retry in N seconds`，模型可稍后重试。`restart` 例外：它正是用于把 server 从 `ERROR` 态拉回，调用后返回"约 10 秒后重试"，后台异步重置并重新 sync/init。
|
|
1387
|
+
- C/C++ 工具需要工程包含 C++ 模块；无 C++ 代码时返回 `No C++ code`。
|
|
1388
|
+
- 支持的文件扩展名：ArkTS 为 `.ets`；C/C++ 为 `.c` `.cc` `.cpp` `.cxx` `.c++` `.h` `.hh` `.hpp` `.hxx` `.h++` `.ipp` `.ixx` `.inl` `.inc` `.tpp`。
|
|
1389
|
+
- 不属于当前工程的路径会被拒绝。
|
|
1390
|
+
|
|
1391
|
+
**入参定义：**
|
|
1392
|
+
|
|
1393
|
+
##### `check`
|
|
1394
|
+
|
|
1395
|
+
对传入的源文件进行静态语法分析并返回诊断信息，支持 ArkTS 与 C/C++ 在同一次调用中混合传入。
|
|
1396
|
+
|
|
1397
|
+
| 参数 | 类型 | 必选 | 说明 |
|
|
1398
|
+
| --- | --- | --- | --- |
|
|
1399
|
+
| `files` | string[] | 是 | 待检查的源文件路径列表，相对工程根目录，至少 1 个 |
|
|
1400
|
+
|
|
1401
|
+
##### `hover` / `definition` / `declaration` / `references` / `implementation`
|
|
1402
|
+
|
|
1403
|
+
位置类语言特性，共享同一入参结构。返回该位置符号的类型/文档信息、定义/声明位置、引用列表或实现列表。
|
|
1404
|
+
|
|
1405
|
+
| 参数 | 类型 | 必选 | 说明 |
|
|
1406
|
+
| --- | --- | --- | --- |
|
|
1407
|
+
| `file` | string | 是 | 源文件路径，相对工程根目录，支持 `.ets` 与 C/C++ 扩展名 |
|
|
1408
|
+
| `line` | number | 是 | 行号，0-based |
|
|
1409
|
+
| `character` | number | 是 | 列号（字符偏移），0-based |
|
|
1410
|
+
|
|
1411
|
+
##### `workspaceSymbol`
|
|
1412
|
+
|
|
1413
|
+
按名称在全工程搜索符号，无需打开具体文件。
|
|
1414
|
+
|
|
1415
|
+
| 参数 | 类型 | 必选 | 说明 |
|
|
1416
|
+
| --- | --- | --- | --- |
|
|
1417
|
+
| `query` | string | 是 | 符号名称或片段，非空 |
|
|
1418
|
+
|
|
1419
|
+
##### `documentSymbol`
|
|
1420
|
+
|
|
1421
|
+
获取单个文件的符号树，适合文件概览、结构化拆解和大文件切片。
|
|
1422
|
+
|
|
1423
|
+
| 参数 | 类型 | 必选 | 说明 |
|
|
1424
|
+
| --- | --- | --- | --- |
|
|
1425
|
+
| `file` | string | 是 | 源文件路径，相对工程根目录，支持 `.ets` 与 C/C++ 扩展名 |
|
|
1426
|
+
|
|
1427
|
+
##### `callHierarchy`
|
|
1428
|
+
|
|
1429
|
+
查询某位置函数的调用关系。
|
|
1430
|
+
|
|
1431
|
+
| 参数 | 类型 | 必选 | 说明 |
|
|
1432
|
+
| --- | --- | --- | --- |
|
|
1433
|
+
| `file` | string | 是 | 源文件路径，相对工程根目录，支持 `.ets` 与 C/C++ 扩展名 |
|
|
1434
|
+
| `line` | number | 是 | 行号，0-based |
|
|
1435
|
+
| `character` | number | 是 | 列号（字符偏移），0-based |
|
|
1436
|
+
| `direction` | enum | 是 | `incoming`=谁调用了该函数；`outgoing`=该函数调用了谁。ArkTS 支持双向，C/C++（clangd）仅 `incoming` |
|
|
1437
|
+
|
|
1438
|
+
##### `restart`
|
|
1439
|
+
|
|
1440
|
+
原地重启 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`，应请用户排查并修复工程后再重试。**
|
|
1441
|
+
|
|
1442
|
+
| 参数 | 类型 | 必选 | 说明 |
|
|
1443
|
+
| --- | --- | --- | --- |
|
|
1444
|
+
| `target` | enum | 否 | 重启哪一侧：`arkts`（ArkTS ace-server）、`cpp`（C++ clangd）、`all`（双侧，默认）。省略等同 `all` |
|
|
1445
|
+
|
|
1172
1446
|
### `serve lsp`
|
|
1173
1447
|
|
|
1174
1448
|
启动本地 `LSP` 语言服务。智能体配置 `LSP` 服务后，可通过 `LSP` 协议获取代码补全、跳转定义、悬浮提示、引用查找、诊断等语言特性。当前支持 `ArkTS`和 `clangd`。
|
|
@@ -1218,72 +1492,42 @@ devecocli skills remove --skill skillname --agent agentname # skillname需替
|
|
|
1218
1492
|
| `--project-path <path>` | 可选，工程根路径，默认为当前工作目录 |
|
|
1219
1493
|
| `--auto-detect` | 可选，当前目录向下查找工程根（检查当前目录自身及其子目录，最多 3 层子目录）；适用于 `--arkts` 和 `--cpp`；指定了 `--project-path` 则忽略 |
|
|
1220
1494
|
|
|
1221
|
-
### `
|
|
1222
|
-
|
|
1223
|
-
基于 `DevEco Studio` 自带的 `apkanalyzer-apiscan` 插件，扫描源代码在两个 `SDK` 版本之间的 `API` 变更情况。
|
|
1224
|
-
|
|
1225
|
-
**子命令：**
|
|
1495
|
+
### `signature generate`
|
|
1226
1496
|
|
|
1227
|
-
|
|
1228
|
-
| --- | --- |
|
|
1229
|
-
| `devecocli check compat` | 默认执行工程级扫描 |
|
|
1230
|
-
| `devecocli check compat --modules <m1> [m2...]` | 按模块扫描 |
|
|
1231
|
-
| `devecocli check compat <file1> [file2...]` | 按文件扫描（仅支持 `.ets`/`.c`/`.cpp`） |
|
|
1232
|
-
| `devecocli check compat versions` | 列出可用的目标 `SDK` 版本 |
|
|
1497
|
+
自动生成调试签名材料（包括p12密钥库、csr证书请求文件、p7b配置文件、cer证书文件），并将签名配置写入项目的 `build-profile.json5` 中。
|
|
1233
1498
|
|
|
1234
1499
|
**命令格式：**
|
|
1235
1500
|
|
|
1236
1501
|
```bash
|
|
1237
|
-
devecocli
|
|
1238
|
-
```
|
|
1502
|
+
devecocli signature generate --product <product> --team-id <team-id> --force --help
|
|
1503
|
+
```
|
|
1239
1504
|
|
|
1240
1505
|
**参数：**
|
|
1241
1506
|
|
|
1242
|
-
| 参数名
|
|
1243
|
-
|
|
1244
|
-
|
|
|
1245
|
-
|
|
|
1246
|
-
|
|
|
1247
|
-
|
|
|
1248
|
-
| `--output-path` | 可选，报告输出路径。目录或文件（扩展名必须与 `--format` 匹配） |
|
|
1249
|
-
| `--limit` | 可选，控制台显示的最大记录数，默认 `100` |
|
|
1250
|
-
|
|
1251
|
-
**版本号说明：**
|
|
1252
|
-
|
|
1253
|
-
- 可用版本可通过 `devecocli check compat versions` 查看
|
|
1254
|
-
- `zsh` 环境下版本号需用引号包裹（包含括号），例如 `"<source_version>"`、`"<target_version>"`
|
|
1255
|
-
|
|
1256
|
-
**格式与输出组合：**
|
|
1257
|
-
|
|
1258
|
-
| 场景 | 允许的 `--format` | 行为 |
|
|
1259
|
-
| --- | --- | --- |
|
|
1260
|
-
| 控制台输出（无 `--output-path`） | `default` / `json` | `default` 输出文本表格，`json` 输出 `JSON` |
|
|
1261
|
-
| 文件输出（`--output-path <file>`，扩展名必须匹配 `--format`） | `default` / `csv` / `json` | `default`/`csv` 写 `.csv` 文件；`json` 写 `.json` 文件 |
|
|
1262
|
-
| 目录输出（`--output-path <dir>`，无扩展名） | `default` / `csv` / `json` | `default`/`csv` 生成 `apiChange-res{N}.csv`；`json` 生成 `apiChange-res{N}.json` |
|
|
1507
|
+
| 参数名 | 说明 |
|
|
1508
|
+
|-----------------------|-----------------------------------------|
|
|
1509
|
+
| --product \<product\> | 可选，指定product生成签名，默认为 `default` |
|
|
1510
|
+
| --team-id \<team-id\> | 可选，指定生效的team-id,默认使用自身作为团队信息 |
|
|
1511
|
+
| --force | 可选，强制覆盖已存在的证书文件 |
|
|
1512
|
+
| --help,--h | 可选，查看帮助信息 |
|
|
1263
1513
|
|
|
1264
1514
|
**示例：**
|
|
1265
1515
|
|
|
1266
1516
|
```bash
|
|
1267
|
-
#
|
|
1268
|
-
devecocli
|
|
1269
|
-
|
|
1270
|
-
# 输出 JSON 到控制台
|
|
1271
|
-
devecocli check compat --format json --source-version "<source_version>" --target-version "<target_version>"
|
|
1517
|
+
# 自动生成签名并写入工程配置
|
|
1518
|
+
devecocli signature generate
|
|
1272
1519
|
|
|
1273
|
-
#
|
|
1274
|
-
devecocli
|
|
1520
|
+
# 指定product
|
|
1521
|
+
devecocli signature generate --product default
|
|
1275
1522
|
|
|
1276
|
-
#
|
|
1277
|
-
devecocli
|
|
1523
|
+
# 指定team-id
|
|
1524
|
+
devecocli signature generate --team-id 1222
|
|
1278
1525
|
|
|
1279
|
-
#
|
|
1280
|
-
devecocli
|
|
1281
|
-
|
|
1282
|
-
# 文件级扫描
|
|
1283
|
-
devecocli check compat ./entry/src/main/ets/pages/Index.ets --source-version "<source_version>" --target-version "<target_version>"
|
|
1526
|
+
# 强制覆盖已存在的证书文件
|
|
1527
|
+
devecocli signature generate --force
|
|
1284
1528
|
|
|
1285
|
-
#
|
|
1286
|
-
devecocli
|
|
1529
|
+
# 查询帮助信息
|
|
1530
|
+
devecocli signature generate --help
|
|
1287
1531
|
```
|
|
1288
1532
|
|
|
1289
1533
|
## 常见问题
|