@deveco-test/deveco-cli 1.3.0-Test.5 → 1.3.0-Test.7

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 (12) hide show
  1. package/README.md +157 -16
  2. package/SKILL.md +86 -6
  3. package/THIRD-PARTY-LICENSES +344 -5
  4. package/dist/cli.js +126 -101
  5. package/dist/internal/doc-init-background.js +8 -8
  6. package/docs.zip +0 -0
  7. package/index.zip +0 -0
  8. package/package.json +9 -3
  9. package/scripts/install-jieba-wasm.mjs +47 -0
  10. package/scripts/lib/jieba-wasm-vendor.mjs +102 -0
  11. package/scripts/postinstall.mjs +9 -0
  12. package/src/resources/aclPermission/aclPermissionsInfo.json +311 -0
package/README.md CHANGED
@@ -87,6 +87,7 @@ devecocli init --path D:\work\ARKTS\NewData
87
87
  | ------------------------- | ----------------------------------------- |
88
88
  | `devecocli create` | 创建新的 HarmonyOS 项目 |
89
89
  | `devecocli build` | 构建项目并产出 `.hap` / `.hsp` / `.har` / `.app` |
90
+ | `devecocli check lint` | 检查代码规范并输出实践建议与报告 |
90
91
  | `devecocli run` | 安装并运行应用 |
91
92
  | `devecocli device list` | 查看当前连接设备 |
92
93
  | `devecocli emulator list` | 查看本地模拟器实例 |
@@ -95,6 +96,7 @@ devecocli init --path D:\work\ARKTS\NewData
95
96
  | `devecocli docs search` | 搜索本地 HarmonyOS 文档 |
96
97
  | `devecocli init` | 安装内置技能或配置 `MCP` |
97
98
  | `devecocli skills` | 管理 HarmonyOS 技能市场中的技能 |
99
+ | `devecocli check compat` | 扫描源代码在两个 `SDK` 版本之间的 `API` 变更 |
98
100
 
99
101
  ## 命令集
100
102
 
@@ -131,6 +133,7 @@ Commands:
131
133
  init [options] Install the deveco-cli skill or configure the deveco-mcp server into AI agents
132
134
  serve Host bundled auxiliary protocol servers
133
135
  docs [options] Search and read HarmonyOS documentation from local docs directory
136
+ check Run DevEco project checks
134
137
  help [command] display help for command
135
138
  ```
136
139
 
@@ -312,6 +315,29 @@ devecocli build --product oversea --modules entry --build-mode release
312
315
  devecocli build clean
313
316
  ```
314
317
 
318
+ ### `check lint`
319
+
320
+ 检查代码规范并输出实践建议与报告。
321
+
322
+ **命令格式：**
323
+
324
+ ```bash
325
+ devecocli check lint [path]
326
+ ```
327
+
328
+ **参数：**
329
+
330
+ | 参数名 | 说明 |
331
+ | ---------------------------- | --------------------------------------------------------------------- |
332
+ | `[path]` | 可选，待检查的文件或目录；默认使用 `build-profile.json5` 所在的项目根目录，否则使用当前目录 |
333
+ | `--config-path <path>` | Code Linter 配置文件路径，仅支持 `.json` 或 `.json5`；默认使用待检查项目根目录下的 `code-linter.json5`，显式指定时必须与待检查路径属于同一项目 |
334
+ | `--fix` | 自动修复可修复的问题 |
335
+ | `--incremental` | 仅检查 Git 未提交文件 |
336
+ | `--product <name>` | `build-profile.json5` 中定义的 product，默认为 `default` |
337
+ | `--format <default\|json>` | 完整报告格式；`default` 输出 Markdown，`json` 输出 JSON |
338
+ | `--output-path <path>` | 完整报告文件或目录；目录形式会自动生成带时间戳的报告文件 |
339
+ | `--limit <number>` | 未指定 `--output-path` 时，限制终端显示的问题数量 |
340
+
315
341
  ### `emulator list`
316
342
 
317
343
  查看模拟器实例
@@ -324,7 +350,7 @@ devecocli emulator list
324
350
 
325
351
  ### `emulator start`
326
352
 
327
- 启动模拟器。首次使用时，需要签署 HarmonyOS 软件许可与服务协议，具体请参考 `emulator license accept`
353
+ 启动模拟器。首次使用时，需要签署 HarmonyOS 软件许可与服务协议，具体请参考 `emulator license`
328
354
 
329
355
  **命令格式：**
330
356
 
@@ -394,12 +420,20 @@ devecocli emulator sensor --target Phone --heartrate 80
394
420
  **说明：**
395
421
 
396
422
  - `--target` 支持模拟器名称或 `127.0.0.1:<port>` 序列号。
397
- - `battery --level` 取值范围为整数 `[0, 100]`。
423
+ - `battery --level` 取值范围为整数 `[1, 100]`。
398
424
  - `battery --status` 取值为 `charging` 或 `discharging`。
399
425
  - `geolocation` 支持 `--longitude`、`--latitude`、`--altitude`、`--direction`。
400
426
  - `scene` 取值为 `outdoorRunning`、`outdoorCycling`、`drivingNavigation`。
401
427
  - `sensor` 支持 `--light-intensity`、`--humidity`、`--temperature`、`--steps`、`--heartrate`。
402
- - 折叠状态覆盖 3 类设备形态，去重后支持 13 个可输入 `state`，底层均映射为 `Emulator -instance <name> -foldedState <state>`。
428
+ - `fold <state>` 会根据目标模拟器的设备类型校验状态，设备与参数必须匹配：
429
+
430
+ | 设备类型 | 支持的 `state` |
431
+ | --- | --- |
432
+ | `foldable` | `open`、`half-open`、`close` |
433
+ | `2in1_foldable` | `open`、`vertical-open`、`half-open`、`close` |
434
+ | `triplefold` | `single`、`double`、`triple`、`left-folded-right-half-folded`、`left-half-folded-right-expanded`、`left-expanded-right-folded`、`left-half-folded-right-folded`、`left-expanded-right-half-folded`、`left-half-folded-right-half-folded` |
435
+
436
+ 校验以目标模拟器实际返回的 `deviceType` 为准。非上述三种设备类型以及不属于目标设备类型的状态会在命令下发前被拒绝。校验通过后，底层映射为 `Emulator -instance <name> -foldedState <state>`。
403
437
  - 设置 `DEVECO_CLI_DEBUG=1` 可查看底层命令映射，例如 `Emulator -instance <name> -shake`。
404
438
 
405
439
  ### `ui screenshot`
@@ -512,7 +546,7 @@ devecocli emulator image list --format json
512
546
 
513
547
  ### `emulator image download`
514
548
 
515
- 下载模拟器镜像。首次使用时，需要签署 HarmonyOS `SDK` 许可协议，具体请参考 `emulator license accept`
549
+ 下载模拟器镜像。首次使用时，需要签署 HarmonyOS `SDK` 许可协议，具体请参考 `emulator license`
516
550
 
517
551
  **命令格式：**
518
552
 
@@ -571,9 +605,19 @@ devecocli emulator image remove --device-type phone --os-version "HarmonyOS 6.0.
571
605
  devecocli emulator license view
572
606
  ```
573
607
 
608
+ ### `emulator license`
609
+
610
+ 交互式查看并接受协议。打印完整协议文本后提示 y/N 确认。使用模拟器需要同意 HarmonyOS 软件许可与服务协议，下载镜像需要同意 HarmonyOS `SDK` 许可协议。若已同意则直接提示已接受。非交互终端下会报错，请改用 `emulator license accept`
611
+
612
+ **命令格式：**
613
+
614
+ ```bash
615
+ devecocli emulator license
616
+ ```
617
+
574
618
  ### `emulator license accept`
575
619
 
576
- 查看并接受协议。使用模拟器需要同意 HarmonyOS 软件许可与服务协议，下载镜像需要同意 HarmonyOS `SDK` 许可协议
620
+ 非交互式同意模拟器所有协议，直接写入同意记录，跳过协议展示和确认提示。适用于自动化脚本、CI 或非交互终端环境。若已同意则直接提示已接受
577
621
 
578
622
  **命令格式：**
579
623
 
@@ -622,20 +666,21 @@ devecocli device view -t "My Device Name"
622
666
  **命令格式：**
623
667
 
624
668
  ```bash
625
- devecocli run --module <module> --device <device> --product <product> --build-mode <mode> --ability <ability> --uninstall --skip-build
669
+ devecocli run --module <module> --device <device> --product <product> --build-mode <mode> --ability <ability> --uninstall --skip-build --apply <txtFile>
626
670
  ```
627
671
 
628
672
  **参数：**
629
673
 
630
- | 参数名 | 说明 |
631
- | ------------ | ------------------------------------------------------------------------------------------------------ |
632
- | --module | 可选，模块名称。如需指定模块的 `target` 信息，使用 `module@target` 形式。当工程中只有一个可运行模块（ `entry` / `feature` / `shared` ）时，可缺省 |
633
- | --device | 设备名称或设备序列号，单设备时可选，多设备时必选 |
634
- | --product | 可选，产品的名称，默认为 `default` |
635
- | --build-mode | 可选，构建模式名称，默认为 `debug` |
636
- | --ability | 可选，待启动的 `Ability` ，默认：模块 `module.json5` 中的`mainElement` |
637
- | --uninstall | 可选，安装前先卸载已有应用 |
638
- | --skip-build | 可选，跳过构建操作，直接安装应用 。\*\*说明：\*\*使用该参数时，需确保对应模块已有构建产物 |
674
+ | 参数名 | 说明 |
675
+ | ------------ |--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
676
+ | --module | 可选，模块名称。如需指定模块的 `target` 信息，使用 `module@target` 形式。当工程中只有一个可运行模块（ `entry` / `feature` / `shared` ）时，可缺省 |
677
+ | --device | 设备名称或设备序列号，单设备时可选，多设备时必选 |
678
+ | --product | 可选，产品的名称，默认为 `default` |
679
+ | --build-mode | 可选，构建模式名称，默认为 `debug` |
680
+ | --ability | 可选，待启动的 `Ability` ，默认：模块 `module.json5` 中的`mainElement` |
681
+ | --uninstall | 可选，安装前先卸载已有应用 |
682
+ | --skip-build | 可选，跳过构建操作，直接安装应用 。\*\*说明：\*\*使用该参数时，需确保对应模块已有构建产物 |
683
+ | --apply \<fileName\> | 可选，**快速增量部署**：仅重编改动文件 → signed hqf → `bm quickfix -a -f -o` 安装 → 重启，比全量 `run` 快。`<fileName>` 是工程 `.hvigor/` 目录下的**纯文件名**（调用方把清单写到此目录，文件名做安全校验防穿越）；内容为本轮改动的源文件路径清单（每行一个相对工程根路径；`#`/空行忽略；`.ets`/`.ts`/`.cpp`/资源文件；changeFileList 增量累积，只需列本轮改的，历史文件自动保留）。模块从清单路径自动识别（无需 `--module`）。**前提**：DevEco Studio ≥6.1.1（hvigor `assembleDevHqf` 支持，低于拒绝并提示升级）；先 `devecocli run` 全量构建部署一次（生成 buildConfig.json 缓存）；**没生效排查**：检查 `<module>/build/config/buildConfig.json` 有无内容（空/无 = 没跑过 `devecocli run`）；**失败兜底**：直接 `devecocli run` |
639
684
 
640
685
  **示例：**
641
686
 
@@ -646,6 +691,7 @@ devecocli run --module library@phone --device 127.0.0.1:5555
646
691
  devecocli run --product oversea --module entry --ability EntryAbility
647
692
  devecocli run --build-mode release
648
693
  devecocli run --uninstall
694
+ devecocli run --apply changes.txt
649
695
  ```
650
696
 
651
697
  ### `log`
@@ -811,7 +857,7 @@ devecocli skills remove --skill skillname --agent agentname # skillname需替
811
857
 
812
858
  ### `serve lsp`
813
859
 
814
- 启动本地 `LSP` 语言服务。智能体配置 `LSP` 服务后，可通过 `LSP` 协议获取 `ArkTS` 代码补全、跳转定义、悬浮提示、引用查找、诊断等语言特性。当前支持 `ArkTS`（`ace-server`）。
860
+ 启动本地 `LSP` 语言服务。智能体配置 `LSP` 服务后，可通过 `LSP` 协议获取代码补全、跳转定义、悬浮提示、引用查找、诊断等语言特性。当前支持 `ArkTS`和 `clangd`。
815
861
 
816
862
  ```bash
817
863
  {
@@ -826,11 +872,106 @@ devecocli skills remove --skill skillname --agent agentname # skillname需替
826
872
  "extensions": [
827
873
  ".ets"
828
874
  ]
875
+ },
876
+ "clangd": {
877
+ "command": [
878
+ "devecocli",
879
+ "serve",
880
+ "lsp",
881
+ "--cpp"
882
+ ],
883
+ "extensions": [
884
+ ".c",
885
+ ".cpp",
886
+ ".cc",
887
+ ".cxx",
888
+ ".h",
889
+ ".hpp",
890
+ ".hxx",
891
+ ".hh"
892
+ ]
829
893
  }
830
894
  }
831
895
  }
832
896
  ```
833
897
 
898
+ **参数：**
899
+
900
+ | 参数名 | 说明 |
901
+ | --- | --- |
902
+ | `--arkts` | 与 `--cpp` 二选一，启动 ArkTS 语言服务（ace-server） |
903
+ | `--cpp` | 与 `--arkts` 二选一，启动 C/C++ 语言服务（clangd） |
904
+ | `--project-path <path>` | 可选，工程根路径，默认为当前工作目录 |
905
+ | `--auto-detect` | 可选，当前目录向下查找工程根（检查当前目录自身及其子目录，最多 3 层子目录）；适用于 `--arkts` 和 `--cpp`；指定了 `--project-path` 则忽略 |
906
+
907
+ ### `check compat`
908
+
909
+ 基于 `DevEco Studio` 自带的 `apkanalyzer-apiscan` 插件，扫描源代码在两个 `SDK` 版本之间的 `API` 变更情况。
910
+
911
+ **子命令：**
912
+
913
+ | 子命令 | 说明 |
914
+ | --- | --- |
915
+ | `devecocli check compat` | 默认执行工程级扫描 |
916
+ | `devecocli check compat --modules <m1> [m2...]` | 按模块扫描 |
917
+ | `devecocli check compat <file1> [file2...]` | 按文件扫描（仅支持 `.ets`/`.c`/`.cpp`） |
918
+ | `devecocli check compat versions` | 列出可用的目标 `SDK` 版本 |
919
+
920
+ **命令格式：**
921
+
922
+ ```bash
923
+ devecocli check compat [files...] --source-version <ver> --target-version <ver> [--modules <m...>] [--format <default|csv|json>] [--output-path <path>] [--limit <n>]
924
+ ```
925
+
926
+ **参数：**
927
+
928
+ | 参数名 | 说明 |
929
+ | --- | --- |
930
+ | `--source-version` | 必填，当前工程 `SDK` 版本 |
931
+ | `--target-version` | 必填，目标 `SDK` 版本 |
932
+ | `--modules` | 可选，指定扫描的模块（多个以空格分隔）。与文件参数互斥 |
933
+ | `--format` | 可选，输出格式。`default`/`csv`/`json`。默认 `default`（控制台输出文本，文件输出 `csv`） |
934
+ | `--output-path` | 可选，报告输出路径。目录或文件（扩展名必须与 `--format` 匹配） |
935
+ | `--limit` | 可选，控制台显示的最大记录数，默认 `100` |
936
+
937
+ **版本号说明：**
938
+
939
+ - 可用版本可通过 `devecocli check compat versions` 查看
940
+ - `zsh` 环境下版本号需用引号包裹（包含括号），例如 `"<source_version>"`、`"<target_version>"`
941
+
942
+ **格式与输出组合：**
943
+
944
+ | 场景 | 允许的 `--format` | 行为 |
945
+ | --- | --- | --- |
946
+ | 控制台输出（无 `--output-path`） | `default` / `json` | `default` 输出文本表格，`json` 输出 `JSON` |
947
+ | 文件输出（`--output-path <file>`，扩展名必须匹配 `--format`） | `default` / `csv` / `json` | `default`/`csv` 写 `.csv` 文件；`json` 写 `.json` 文件 |
948
+ | 目录输出（`--output-path <dir>`，无扩展名） | `default` / `csv` / `json` | `default`/`csv` 生成 `apiChange-res{N}.csv`；`json` 生成 `apiChange-res{N}.json` |
949
+
950
+ **示例：**
951
+
952
+ ```bash
953
+ # 工程级扫描，输出到控制台
954
+ devecocli check compat --source-version "<source_version>" --target-version "<target_version>"
955
+
956
+ # 输出 JSON 到控制台
957
+ devecocli check compat --format json --source-version "<source_version>" --target-version "<target_version>"
958
+
959
+ # 输出报告到目录（默认 csv）
960
+ devecocli check compat --output-path ./report --source-version "<source_version>" --target-version "<target_version>"
961
+
962
+ # 输出 JSON 报告到目录（生成 apiChange-res{N}.json）
963
+ devecocli check compat --output-path ./report --format json --source-version "<source_version>" --target-version "<target_version>"
964
+
965
+ # 输出报告到指定文件
966
+ devecocli check compat --output-path ./report.json --format json --source-version "<source_version>" --target-version "<target_version>"
967
+
968
+ # 文件级扫描
969
+ devecocli check compat ./entry/src/main/ets/pages/Index.ets --source-version "<source_version>" --target-version "<target_version>"
970
+
971
+ # 模块级扫描
972
+ devecocli check compat --modules entry har1 --source-version "<source_version>" --target-version "<target_version>"
973
+ ```
974
+
834
975
  ## 常见问题
835
976
 
836
977
  [FAQ](https://gitcode.com/openharmony-sig/deveco-cli/wiki/FAQ.md)
package/SKILL.md CHANGED
@@ -1,14 +1,14 @@
1
1
  ---
2
2
  name: deveco-cli
3
3
  description: >-
4
- **MUST** use 'devecocli' for HarmonyOS apps (scaffold, build, run, debug, devices, emulators, logs, docs, 鸿蒙开发文档, skills). **REQUIRED** and **MANDATORY** if workspace has build-profile.json5 or oh-package.json5, or user mentions HarmonyOS, 鸿蒙, DevEco, ArkTS, ArkUI, docs, 鸿蒙文档, 知识, 搜索, or skills.
4
+ **MUST** use 'devecocli' for HarmonyOS apps (scaffold, build, run, debug, devices, emulators, logs, docs, UI inspection, 鸿蒙开发文档, skills). **REQUIRED** and **MANDATORY** if workspace has build-profile.json5 or oh-package.json5, or user mentions HarmonyOS, 鸿蒙, DevEco, ArkTS, ArkUI, docs, 鸿蒙文档, 知识, 搜索, skills, UI, UI测试, 组件调试.
5
5
  ---
6
6
 
7
7
  # DevEco CLI
8
8
 
9
- `devecocli` wraps DevEco Studio's `hvigor`, `ohpm`, `hdc`, emulator toolchain, and HarmonyOS-skills installer. **Prefer `devecocli` over invoking underlying tools directly.**
9
+ `devecocli` wraps DevEco Studio's `hvigor`, `ohpm`, `hdc`, emulator toolchain, and bundled skills installer. **Prefer `devecocli` over invoking underlying tools directly.**
10
10
 
11
- Available commands: `build`, `run`, `update`, `device`, `emulator`, `ui`, `skills`, `log`, `create`, `init`, `serve`, `docs`.
11
+ Available commands: `build`, `check`, `run`, `update`, `device`, `emulator`, `ui`, `skills`, `log`, `create`, `init`, `serve`, `docs`, `signature`, `login`, `logout`, `whoami`.
12
12
 
13
13
  **Sandbox Rule**: Commands tagged `[Outside sandbox]` must be run outside the sandbox.
14
14
 
@@ -31,6 +31,12 @@ Compile and package project/modules. (Defaults: `--product default`, `--build-mo
31
31
  | Whole product bundle (.app) | `devecocli build --product <name>` |
32
32
  | Clean build outputs | `devecocli build clean` |
33
33
 
34
+ ### `devecocli check lint`
35
+ Run DevEco Code Linter checks for TS/ArkTS code.
36
+ - `[path]`: File or directory to lint. Defaults to the project root from `build-profile.json5`, otherwise the current directory.
37
+ - Options: `--config-path <file>`, `--fix`, `--incremental`, `--product <name>`, `--format <default|json>`, `--output-path <path>`, `--limit <number>`.
38
+ - Set `DEVECO_CLI_CLT_PATH` to the Command Line Tools root when DevEco Studio is not installed; CLT is not discovered automatically from PATH or default installation directories.
39
+
34
40
  ### `devecocli emulator`
35
41
  Manage local emulator instances and system images.
36
42
  - `list`: Show instances (status, serial, device type).
@@ -38,7 +44,7 @@ Manage local emulator instances and system images.
38
44
  - `stop <names...>`: Stop by name or serial (`127.0.0.1:<port>`).
39
45
  - Scene control commands require Emulator 7.0 or later. Use `DEVECO_CLI_DEBUG=1` to inspect the underlying `Emulator` command mapping.
40
46
  - `shake` / `power` / `rotate <left|right>` / `volume <up|down>` (Req: `--target <nameOrSerial>`): Basic emulator controls.
41
- - `fold <state>` (Req: `--target <nameOrSerial>`): Set foldable display state.
47
+ - `fold <state>` (Req: `--target <nameOrSerial>`): Set foldable display state, matched against the target emulator's reported `deviceType`. `foldable` uses `open|half-open|close`; `2in1_foldable` uses `open|vertical-open|half-open|close`; `triplefold` uses `single|double|triple` or one of its six left/right folded-state combinations. Other device types and cross-device states are rejected before execution.
42
48
  - `battery` (Req: `--target`; one of `--level <0-100>` or `--status <charging|discharging>`): Set battery state.
43
49
  - `geolocation` (Req: `--target`; one of `--longitude`, `--latitude`, `--altitude`, `--direction`): Inject GPS data.
44
50
  - `scene <outdoorRunning|outdoorCycling|drivingNavigation>` (Req: `--target`): Start motion simulation.
@@ -74,6 +80,24 @@ Build, install, and launch.
74
80
  - `--ability <ability>`: Default from `module.json5`.
75
81
  - `--uninstall`: Uninstall existing app first (Fixes signing key issues).
76
82
  - `--skip-build`: Deploy existing artifacts.
83
+ - `--apply <fileName>`: **Fast incremental deploy** — rebuilds only changed files into a signed hqf, installs via `bm quickfix -a -f -o`, then restarts the app. Much faster than a full `devecocli run` for iterating on code changes. Modules are auto-detected from the file paths in `<fileName>` (no `--module` needed).
84
+ - `<fileName>`: a plain file name (no path separators) under the project's `.hvigor/` directory; the caller writes the changed-file list there. File name is sanitized to prevent path traversal. Content: list of **source file paths changed this round** (one per line, relative to project root or absolute; `#` comments and blank lines ignored; typically `.ets`/`.ts`/`.cpp`/resource files). The changeFileList is **incrementally merged** — only list files changed since the last apply; previously listed files are retained automatically.
85
+ - **Prereq**: DevEco Studio ≥6.1.1 (hvigor `assembleDevHqf` support; below is rejected with an upgrade hint); run `devecocli run` once first (full build + deploy + generates the `buildConfig.json` cache that `--apply` reuses).
86
+ - **If changes don't take effect**: check `<module>/build/config/buildConfig.json` has content — empty/missing means `devecocli run` wasn't run; on any apply failure, fall back to a full `devecocli run`.
87
+ *Ex*: `devecocli run` → edit code → write `.hvigor/changes.txt` → `devecocli run --apply changes.txt`
88
+
89
+ ### `devecocli signature generate` `[Outside sandbox]`
90
+ Auto-generate HarmonyOS signing materials (local p12/csr + cloud cert + test profile) and write signing config to `build-profile.json5`.
91
+ - **Prereq**: `devecocli login` first; run from a project directory (with `build-profile.json5`); a connected device or emulator is required for device registration.
92
+ - `--product <name>`: Product name for local p12/csr file naming (default: `default`).
93
+ - `--team-id <id>`: Specify the team-id (default: current user's id).
94
+ - `--force`: Force regenerate even if existing materials are valid.
95
+ - Generates under `~/.ohos/config/`: `.p12` keystore, `.csr`, downloaded `.cer` certificate, `.p7b` profile.
96
+ - Writes `signingConfigs` + `products` entries to `build-profile.json5` with encrypted key/store passwords (AES-128-GCM).
97
+ - Cloud cert name: `auto_debug_<teamId>.cer`. Local files: `<product>_<project>_<hash>=.{p12,csr,cer,p7b}`.
98
+ - Error handling (aligned with DevEco Studio JAR): 401→re-login, 403→no AGC permission, `205389872`→cert limit, `205389904`→not Harmony user, `205389938`→provision limit, invalid `.cer`→retry.
99
+ *Ex*: `devecocli signature generate --product default`
100
+
77
101
 
78
102
  ### `devecocli log`
79
103
  Fetch hilog or crash logs. Req `--device <name|serial>` on multi-device hosts.
@@ -84,6 +108,31 @@ Fetch hilog or crash logs. Req `--device <name|serial>` on multi-device hosts.
84
108
  - `--tail <num>` / `--follow`: Keep last N lines / stream real-time (no `--to`).
85
109
  *Ex*: `devecocli log --crash --bundle-name com.example.app`, `devecocli log --level E --from 5m --tail 200`
86
110
 
111
+ ### `devecocli ui`
112
+ Inspect UI on a connected device. All subcommands accept `--device <name|serial>` (Req on multi-device hosts).
113
+
114
+ | Subcommand | Description | Key Options |
115
+ |---|---|---|
116
+ | `layout` | Dump ArkUI accessibility layout tree — **visible area only** (on-screen nodes) | `--id <id>`, `--window <windowId>`, `--all-windows`, `--depth <n>` (0=unlimited, 1=root only, 2=root+children), `--format default\|json`, `--mode full\|simplified` |
117
+ | `window list` | List active windows | `--format table\|json`, `--all` (include system windows) |
118
+ | `screenshot` | Capture a screenshot of the device screen | `--display <displayId>`, `--path <path>` (existing directory or PNG file path whose parent exists; default: `./screenshot-<timestamp>.png`) |
119
+ | `click [x] [y]` | Tap at the specified coordinates or node | `--id <id>` (auto-resolves to center), `--window <windowId>` (used with `--id`) |
120
+ | `doubleclick [x] [y]` | Double-tap at the specified coordinates or node | `--id <id>`, `--window <windowId>` |
121
+ | `longclick [x] [y]` | Long-press at the specified coordinates or node | `--id <id>`, `--window <windowId>` |
122
+ | `swipe <x1> <y1> <x2> <y2>` | Swipe from one point to another | `--speed <n>` (200–40000, px/s) |
123
+ | `fling <x1> <y1> <x2> <y2>` | Fling from one point to another | `--speed <n>` (200–40000, px/s) |
124
+ | `drag <x1> <y1> <x2> <y2>` | Drag from one point to another | `--speed <n>` (200–40000, px/s) |
125
+ | `dircfling <direction>` | Fling in a fixed direction | `direction`: `up`, `down`, `left`, `right` |
126
+ | `text <text> [x] [y]` | Input text at a target location or the currently focused field | `--id <id>` (auto-resolves to center), `--window <windowId>` (used with `--id`) |
127
+
128
+ - Coordinates and `--id` are mutually exclusive. Provide either `x y` or `--id <id>`; for `text`, if neither is given the text goes to the currently focused field.
129
+ - `--window <windowId>` may only be used together with `--id`.
130
+ - Default: focused window only. Use `--window <id>` or `--all-windows` to target specific/all windows (mutually exclusive).
131
+ - `--format json` pairs well with `jq`.
132
+ - `--mode raw`: full layout tree, no filtering.
133
+ - `--mode simplified` (default): folds meaningless wrapper containers (non-root, no `id`, no text, not interactive) by lifting their surviving children up. `--depth` truncates after folding.
134
+
135
+
87
136
  ## 2. Setup
88
137
 
89
138
  ### `devecocli init`
@@ -97,12 +146,37 @@ MUTUALLY EXCLUSIVE modes for setup:
97
146
  - `-f, --force`: Overwrite existing config.
98
147
  *MCP Rules*: Global MCP (no `--project`) only supports `opencode` and `cursor`. Others require `--project`.
99
148
 
149
+ ### `devecocli login`
150
+ Sign in to your Huawei Developer account. Opens a browser for OAuth authentication. Required before `signature generate`.
151
+ *Ex*: `devecocli login`
152
+
153
+ ### `devecocli logout`
154
+ Sign out and clear locally stored credentials.
155
+
156
+ ### `devecocli whoami`
157
+ Show the current logged-in user.
158
+
100
159
  ### `devecocli skills`
101
160
  Manage HarmonyOS skills in AI agents/projects.
102
161
  - `list [-l|--long]` / `find <keyword>`: List or search skills.
103
162
  - `add (--all | --skill <name>) [--agent <a,b…>] [--project <path>] [--path <path>] [-f]`: Install.
104
163
  - `remove --skill <name> [...]`: Uninstall.
105
164
 
165
+ ### `devecocli check compat` `[Outside sandbox]`
166
+ Scan source code for breaking API changes between two SDK versions. Built on top of DevEco Studio's `arkanalyzer-apiscan` plugin.
167
+ - `versions`: List available target SDK versions.
168
+ - Default (no args): project-level scan.
169
+ - `--modules <m1> [m2...]`: Module-level scan.
170
+ - `<file1> [file2...]`: File-level scan (`.ets`/`.c`/`.cpp` only).
171
+ - `--source-version <v>` (Req) / `--target-version <v>` (Req): SDK version pair. Run `devecocli check compat versions` first; on zsh, **quote the value** (e.g. `"<source_version>"`, `"<target_version>"`).
172
+ - `--format <default|csv|json>` (default: `default`): Console output accepts `default` (text) or `json`; file output (via `--output-path`) accepts `default` (csv), `csv`, or `json`. `csv` requires `--output-path`.
173
+ - `--output-path <path>`: Directory (writes `apiChange-*.csv`/`apiChange-*.json`) or explicit file (extension must match `--format`).
174
+ - `--limit <n>` (default `100`): Max records shown on console when no `--output-path`.
175
+
176
+ Validation order: `files` + `--modules` mutually exclusive → `--source-version`/`--target-version` required → `csv` requires `--output-path` → project dir valid → modules exist → files exist + extension valid → versions in catalog + `target > source` → format/extension match → output target writable.
177
+
178
+ *Ex*: `devecocli check compat --source-version "<source_version>" --target-version "<target_version>" --output-path ./report`
179
+
106
180
  ## 3. Maintenance
107
181
 
108
182
  - **`devecocli update`** `[Outside sandbox]`: Update CLI to latest version.
@@ -116,15 +190,21 @@ Manage HarmonyOS skills in AI agents/projects.
116
190
  `devecocli log --crash --bundle-name <bundle>`
117
191
  - **Release build**:
118
192
  `devecocli build --product oversea --build-mode release`
193
+ - **First-time signing setup**:
194
+ `devecocli login` -> `devecocli signature generate --product default` -> `devecocli build` -> `devecocli run`
119
195
 
120
196
  ## Troubleshooting
121
197
 
122
198
  - **"Product / Build mode `<x>` not found"**: Check `build-profile.json5`.
123
199
  - **"Multiple entry modules" / "No entry module"**: Pass `--modules` (build) or `--module` (run).
124
200
  - **"No active devices" / "Multiple devices connected"**: Connect/start emulator. Pass `-t <serial>` (device view) or `--device <name|serial>` (run/log).
125
- - **`error:install sign info inconsistent`**: Signing key changed. Run `devecocli run --uninstall`.
201
+ - **`error:install sign info inconsistent`**: Signing key changed. Run `devecocli run --uninstall` or `devecocli signature generate --force`.
202
+ - **`Not logged in. Run devecocli login first`**: Run `devecocli login` to authenticate.
203
+ - **`Provision number exceeds limit`**: Test provision quota is full. Delete old test provisions in DevEco Studio (Signing Configs) or AGC console, then retry `devecocli signature generate`.
204
+ - **`Invalid AccessToken. Sign in and try again`**: Token expired. Run `devecocli login` again.
126
205
  - **`skills add` agent not found**: Valid: `codebuddy`, `cursor`, `opencode`, `qoder`, `trae-cn`.
127
- - **`emulator start` / `image download` blocked on agreement**: User MUST run `devecocli emulator license accept` in interactive TTY. Agents cannot do this. Do not retry until accepted.
206
+ - **`emulator start` / `image download` blocked on agreement**: User MUST accept agreements. Interactive: `devecocli emulator license` (requires TTY). Non-interactive (CI/scripts): `devecocli emulator license accept`. Agents cannot run the interactive form; suggest the user run it, or use `license accept` if a non-TTY flow is acceptable. Do not retry until accepted.
128
207
  - **`image download` failure / timeout**: Do NOT auto-retry. Give the command to the user to run manually in their terminal.
129
208
  - **`emulator create` timeout**: Treat as user-action step. Ask user to open DevEco Studio -> Device Manager. Check `emulator list` after user confirms. Do NOT auto-retry or edit SDK files.
130
209
  - **`image list` duplicate OS rows**: `phone`/`foldable`/`widefold`/`triplefold` share the same image. Download/remove ONCE per OS version.
210
+ **`ui layout` missing expected node**: `layout` only returns on-screen nodes. The user must scroll the target into view on the device before retrying (no CLI input subcommands in this build).