@deveco-test/deveco-cli 1.3.0-Test.10 → 1.3.0-Test.11

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 (7) hide show
  1. package/README.md +121 -15
  2. package/SKILL.md +14 -6
  3. package/THIRD-PARTY-LICENSES +193 -0
  4. package/dist/cli.js +106 -105
  5. package/dist/internal/doc-init-background.js +1 -1
  6. package/index.zip +0 -0
  7. package/package.json +2 -1
package/README.md CHANGED
@@ -438,8 +438,21 @@ devecocli check lint [path]
438
438
 
439
439
  **命令格式：**
440
440
 
441
+ ```bash
442
+ devecocli emulator list [--format <table|json>]
443
+ ```
444
+
445
+ **参数：**
446
+
447
+ | 参数名 | 说明 |
448
+ | --- | --- |
449
+ | `--format` | 可选，控制终端输出格式，取值为 `table` 或 `json`，默认为 `table` |
450
+
451
+ **示例：**
452
+
441
453
  ```bash
442
454
  devecocli emulator list
455
+ devecocli emulator list --format json
443
456
  ```
444
457
 
445
458
  ### `emulator start`
@@ -514,7 +527,7 @@ devecocli emulator sensor --target Phone --heartrate 80
514
527
  **说明：**
515
528
 
516
529
  - `--target` 支持模拟器名称或 `127.0.0.1:<port>` 序列号。
517
- - `battery --level` 取值范围为整数 `[1, 100]`。
530
+ - `battery --level` 会自动查询模拟器当前充电状态：充电时取值范围为整数 `[0, 100]`，未充电时为 `[1, 100]`。
518
531
  - `battery --status` 取值为 `charging` 或 `discharging`。
519
532
  - `geolocation` 支持 `--longitude`、`--latitude`、`--altitude`、`--direction`。
520
533
  - `scene` 取值为 `outdoorRunning`、`outdoorCycling`、`drivingNavigation`。
@@ -735,14 +748,13 @@ devecocli ui screenshot --device <name|serial> --display <displayId> --path <pat
735
748
  | ------------------------ | ------------------------ | ---------- |
736
749
  | --device \<name\|serial> | 真机或模拟器名称/序列号；多设备时必填 | 单设备自动选择 |
737
750
  | --display \<displayId> | 目标屏幕 ID，可选 | 默认屏幕 |
738
- | --path \<path> | 截图输出路径，可选；目录或父目录必须已存在 | `./screenshot-<timestamp>.png` |
751
+ | --path \<path> | 必填，文件夹路径或 PNG 文件路径；支持相对于当前目录的路径，目录必须存在且可写，目标文件不能已存在 | 无 |
739
752
 
740
753
  **示例：**
741
754
 
742
755
  ```bash
743
- devecocli ui screenshot --device Phone
744
756
  mkdir -p screenshots
745
- devecocli ui screenshot --device Phone --path ./screenshots/phone.png
757
+ devecocli ui screenshot --device Phone --path ./screenshots
746
758
  devecocli ui screenshot --device Phone --display 0 --path ./screenshots/phone.png
747
759
  ```
748
760
 
@@ -750,6 +762,7 @@ devecocli ui screenshot --device Phone --display 0 --path ./screenshots/phone.pn
750
762
 
751
763
  - `ui screenshot` 支持真机和模拟器。
752
764
  - 仅有一个可用设备时可省略 `--device`，多个设备同时连接时必须指定。
765
+ - `--path` 可以使用相对于当前目录的路径。可以指定已存在的文件夹并自动生成 PNG 文件名，也可以指定完整的 PNG 文件路径；不会自动创建目录或覆盖已有文件。
753
766
  - 截图能力统一通过 `ui screenshot` 提供，不放在模拟器场景操作命令中。
754
767
  - 截图统一使用 `hdc shell snapshot_display` 和 `hdc file recv` 实现；设置 `DEVECO_CLI_DEBUG=1` 可查看实际执行命令。
755
768
 
@@ -1061,16 +1074,18 @@ devecocli run --module <module> --device <device> --product <product> --build-mo
1061
1074
 
1062
1075
  **参数：**
1063
1076
 
1064
- | 参数名 | 说明 |
1065
- | ------------ |--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
1066
- | --module | 可选，模块名称。如需指定模块的 `target` 信息，使用 `module@target` 形式。当工程中只有一个可运行模块（ `entry` / `feature` / `shared` ）时，可缺省 |
1067
- | --device | 设备名称或设备序列号，单设备时可选，多设备时必选 |
1068
- | --product | 可选，产品的名称，默认为 `default` |
1069
- | --build-mode | 可选，构建模式名称，默认为 `debug` |
1070
- | --ability | 可选，待启动的 `Ability` ，默认：模块 `module.json5` 中的`mainElement` |
1071
- | --uninstall | 可选，安装前先卸载已有应用 |
1072
- | --skip-build | 可选，跳过构建操作，直接安装应用 。\*\*说明：\*\*使用该参数时，需确保对应模块已有构建产物 |
1073
- | --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` |
1077
+ | 参数名 | 说明 |
1078
+ | ------------ |------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
1079
+ | --module | 可选，模块名称。如需指定模块的 `target` 信息，使用 `module@target` 形式。当工程中只有一个可运行模块（ `entry` / `feature` / `shared` ）时，可缺省 |
1080
+ | --device | 设备名称或设备序列号，单设备时可选，多设备时必选 |
1081
+ | --product | 可选，产品的名称，默认为 `default` |
1082
+ | --build-mode | 可选，构建模式名称，默认为 `debug` |
1083
+ | --ability | 可选，待启动的 `Ability` ，默认：模块 `module.json5` 中的`mainElement` |
1084
+ | --uninstall | 可选，安装前先卸载已有应用 |
1085
+ | --skip-build | 可选，跳过构建操作，直接安装应用 。\*\*说明：\*\*使用该参数时，需确保对应模块已有构建产物 |
1086
+ | --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` |
1087
+ | --hotreload [action] | 可选，**热重载 watch 会话**（须作为**后台进程**启动，该进程持久持有到 hvigor daemon 的 socket）：以热重载模式构建 hap（`hotReload=true debuggable=true`）、部署+拉起应用，然后进程自身连 socket 到 daemon 发 `CommonBuild assembleHap --hot-reload-build --watch` 并**保持连接**，保活 daemon 的 watch worker（rollup watch）供 `--hotreload-apply` 复用。进程常驻（onBuildOutput 流式到其 stdout）。**热重载调试结束必须 kill 此后台进程**（否则 watch worker/daemon 泄漏）；`stop` 同时关闭 hvigor daemon。用法：后台起 `devecocli run --module <m> --hotreload`，等 `.hotreload-mode` marker（或 stdout 出现 "watch session active"）即就绪，再跑 `--hotreload-apply`；结束 kill 后台进程 + `--hotreload stop` |
1088
+ | --hotreload-apply \<fileName\> | 可选，**热重载（不重启应用）**：读取 `.hvigor/<fileName>` 改动清单（格式与 `--apply` 相同），开**短连接** socket 到 daemon（由后台 `--hotreload` 进程保活），发 `CommonBuild assembleDevHqf --hot-compile` → watch worker 增量 hot 编译改动 `.ets`/`.ts` 为 abc（HotReloadArkTS；输出/报错经 WatchLog 实时流式），再**手搓** pack+sign：`app_packing_tool.jar` 打包 + `hap-sign-tool.jar` 签名（DevEco material 密码经 `DecipherUtil` 解密），最后 `bm quickfix -a -f -o` 安装，**应用不重启即生效**。**前提**：后台 `--hotreload` 进程在跑（持有 watch 会话）；超时即 watch 会话没活，重启后台 `--hotreload`。**范围（重要）**：热重载目标是**单个模块**（`--module` 必填，目标可为 entry/hsp/feature；`har` 依赖并入、OK）；**`feature`/`hsp` 依赖模块**（非目标）的改动不支持热重载（检测并 warn，需全量 `devecocli run` 重部署）；资源/native 改动需全量 run。编译报错经 WatchLog 路由到后台 `--hotreload` 进程、落盘 **`.hvigor/hotreload-watch.log`**（+其 stdout），apply 失败时读该文件把报错打出来（~15s 超时快速失败）。**`.hvigor/` 产物**：`.hvigor/<fileName>`=改动清单（入参）、`.hvigor/hotreload-watch.log`=watch 会话的 onBuildOutput/编译报错（后台进程写，可读/可删）。 |
1074
1089
 
1075
1090
  **示例：**
1076
1091
 
@@ -1082,6 +1097,9 @@ devecocli run --product oversea --module entry --ability EntryAbility
1082
1097
  devecocli run --build-mode release
1083
1098
  devecocli run --uninstall
1084
1099
  devecocli run --apply changes.txt
1100
+ devecocli run --hotreload
1101
+ devecocli run --hotreload stop
1102
+ devecocli run --hotreload-apply changes.txt
1085
1103
  ```
1086
1104
 
1087
1105
  ### `log`
@@ -1221,7 +1239,7 @@ devecocli skills remove --skill skillname --agent agentname # skillname需替
1221
1239
 
1222
1240
  ### `serve mcp`
1223
1241
 
1224
- 启动本地 `MCP` 服务。智能体配置 `MCP` 服务后，可通过 `MCP` 协议调用 `ArkTS` / `C++` 语法检查工具。不同智能体平台配置 `MCP` 服务的界面不一样，一个智能体平台的配置示例如下。
1242
+ 启动本地 `MCP` 服务。智能体配置 `MCP` 服务后，可通过 `MCP` 协议调用下方列出的代码分析与语言特性工具。不同智能体平台配置 `MCP` 服务的界面不一样，一个智能体平台的配置示例如下。
1225
1243
  推荐通过 `devecocli init --mcp` 自动配置
1226
1244
 
1227
1245
  ```bash
@@ -1245,6 +1263,88 @@ devecocli skills remove --skill skillname --agent agentname # skillname需替
1245
1263
  }
1246
1264
  ```
1247
1265
 
1266
+ #### MCP 工具
1267
+
1268
+ `deveco-mcp` 服务遵循 [MCP](https://modelcontextprotocol.io) 规范，通过 `tools/list` 暴露工具、由模型经 `tools/call` 调用。每个工具由**名称**、**描述**和 **JSON Schema 入参**定义；返回值为 `content` 文本数组，`isError: true` 表示执行错误。
1269
+
1270
+ **工具总览：**
1271
+
1272
+ | 工具名 | 用途 | 支持语言 |
1273
+ | --- | --- | --- |
1274
+ | `check` | 静态语法分析，返回结构化诊断信息 | ArkTS、C/C++ |
1275
+ | `hover` | 获取指定位置的悬浮信息（类型、文档） | ArkTS、C/C++ |
1276
+ | `definition` | 查找符号定义位置 | ArkTS、C/C++ |
1277
+ | `declaration` | 查找符号声明位置（ArkTS 中可能与定义不同） | ArkTS、C/C++ |
1278
+ | `references` | 查找符号在全工程中的所有引用 | ArkTS、C/C++ |
1279
+ | `implementation` | 查找符号的实现（如接口实现） | ArkTS、C/C++ |
1280
+ | `workspaceSymbol` | 按名称在全工程搜索符号 | ArkTS、C/C++ |
1281
+ | `documentSymbol` | 获取单文件的符号树（函数、类、变量及范围） | ArkTS、C/C++ |
1282
+ | `callHierarchy` | 查询函数调用关系（incoming=调用方，outgoing=被调用方） | ArkTS 双向、C/C++ 仅 incoming |
1283
+ | `restart` | 原地重启（重置状态 + 重新 sync/init），不杀进程、客户端不断开；ERROR 态可用 | ArkTS、C/C++（可按 target 单选） |
1284
+
1285
+ **可用性说明：**
1286
+
1287
+ - `check` 与 `restart` 始终注册；其余 7 个语言特性工具仅在 DevEco Studio 附带标准 LSP 服务入口（`standardIndex/index.js`）时注册，老版本将不暴露这些工具。
1288
+ - 所有语言特性工具需项目进入 `READY` 状态（`ohpm install` + `hvigor sync` + LSP 初始化完成）后才可用；未就绪时返回 `please retry in N seconds`，模型可稍后重试。`restart` 例外：它正是用于把 server 从 `ERROR` 态拉回，调用后返回"约 10 秒后重试"，后台异步重置并重新 sync/init。
1289
+ - C/C++ 工具需要工程包含 C++ 模块；无 C++ 代码时返回 `No C++ code`。
1290
+ - 支持的文件扩展名：ArkTS 为 `.ets`；C/C++ 为 `.c` `.cc` `.cpp` `.cxx` `.c++` `.h` `.hh` `.hpp` `.hxx` `.h++` `.ipp` `.ixx` `.inl` `.inc` `.tpp`。
1291
+ - 不属于当前工程的路径会被拒绝。
1292
+
1293
+ **入参定义：**
1294
+
1295
+ ##### `check`
1296
+
1297
+ 对传入的源文件进行静态语法分析并返回诊断信息，支持 ArkTS 与 C/C++ 在同一次调用中混合传入。
1298
+
1299
+ | 参数 | 类型 | 必选 | 说明 |
1300
+ | --- | --- | --- | --- |
1301
+ | `files` | string[] | 是 | 待检查的源文件路径列表，相对工程根目录，至少 1 个 |
1302
+
1303
+ ##### `hover` / `definition` / `declaration` / `references` / `implementation`
1304
+
1305
+ 位置类语言特性，共享同一入参结构。返回该位置符号的类型/文档信息、定义/声明位置、引用列表或实现列表。
1306
+
1307
+ | 参数 | 类型 | 必选 | 说明 |
1308
+ | --- | --- | --- | --- |
1309
+ | `file` | string | 是 | 源文件路径，相对工程根目录，支持 `.ets` 与 C/C++ 扩展名 |
1310
+ | `line` | number | 是 | 行号，0-based |
1311
+ | `character` | number | 是 | 列号（字符偏移），0-based |
1312
+
1313
+ ##### `workspaceSymbol`
1314
+
1315
+ 按名称在全工程搜索符号，无需打开具体文件。
1316
+
1317
+ | 参数 | 类型 | 必选 | 说明 |
1318
+ | --- | --- | --- | --- |
1319
+ | `query` | string | 是 | 符号名称或片段，非空 |
1320
+
1321
+ ##### `documentSymbol`
1322
+
1323
+ 获取单个文件的符号树，适合文件概览、结构化拆解和大文件切片。
1324
+
1325
+ | 参数 | 类型 | 必选 | 说明 |
1326
+ | --- | --- | --- | --- |
1327
+ | `file` | string | 是 | 源文件路径，相对工程根目录，支持 `.ets` 与 C/C++ 扩展名 |
1328
+
1329
+ ##### `callHierarchy`
1330
+
1331
+ 查询某位置函数的调用关系。
1332
+
1333
+ | 参数 | 类型 | 必选 | 说明 |
1334
+ | --- | --- | --- | --- |
1335
+ | `file` | string | 是 | 源文件路径，相对工程根目录，支持 `.ets` 与 C/C++ 扩展名 |
1336
+ | `line` | number | 是 | 行号，0-based |
1337
+ | `character` | number | 是 | 列号（字符偏移），0-based |
1338
+ | `direction` | enum | 是 | `incoming`=谁调用了该函数；`outgoing`=该函数调用了谁。ArkTS 支持双向，C/C++（clangd）仅 `incoming` |
1339
+
1340
+ ##### `restart`
1341
+
1342
+ 原地重启 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`，应请用户排查并修复工程后再重试。**
1343
+
1344
+ | 参数 | 类型 | 必选 | 说明 |
1345
+ | --- | --- | --- | --- |
1346
+ | `target` | enum | 否 | 重启哪一侧：`arkts`（ArkTS ace-server）、`cpp`（C++ clangd）、`all`（双侧，默认）。省略等同 `all` |
1347
+
1248
1348
  ### `serve lsp`
1249
1349
 
1250
1350
  启动本地 `LSP` 语言服务。智能体配置 `LSP` 服务后，可通过 `LSP` 协议获取代码补全、跳转定义、悬浮提示、引用查找、诊断等语言特性。当前支持 `ArkTS`和 `clangd`。
@@ -1367,6 +1467,12 @@ devecocli check compat [files...] --source-version <ver> --target-version <ver>
1367
1467
  - 可用版本可通过 `devecocli check compat versions` 查看
1368
1468
  - `zsh` 环境下版本号需用引号包裹（包含括号），例如 `"<source_version>"`、`"<target_version>"`
1369
1469
 
1470
+ **`compat versions` 参数：**
1471
+
1472
+ | 参数名 | 说明 |
1473
+ | --- | --- |
1474
+ | `--format` | 可选，输出格式。`default` 或 `json`。默认 `default`（文本输出，每行一个版本号） |
1475
+
1370
1476
  **格式与输出组合：**
1371
1477
 
1372
1478
  | 场景 | 允许的 `--format` | 行为 |
package/SKILL.md CHANGED
@@ -39,13 +39,13 @@ Run DevEco Code Linter checks for TS/ArkTS code.
39
39
 
40
40
  ### `devecocli emulator`
41
41
  Manage local emulator instances and system images.
42
- - `list`: Show instances (status, serial, device type).
42
+ - `list`: Show instances (status, serial, device type). Opt: `--format <table|json>` (default: `table`).
43
43
  - `start <names...>`: Start instances. Quote names with spaces. (See Troubleshooting if blocked).
44
44
  - `stop <names...>`: Stop by name or serial (`127.0.0.1:<port>`).
45
45
  - Scene control commands require Emulator 7.0 or later. Use `DEVECO_CLI_DEBUG=1` to inspect the underlying `Emulator` command mapping.
46
46
  - `shake` / `power` / `rotate <left|right>` / `volume <up|down>` (Req: `--target <nameOrSerial>`): Basic emulator controls.
47
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.
48
- - `battery` (Req: `--target`; one of `--level <0-100>` or `--status <charging|discharging>`): Set battery state.
48
+ - `battery` (Req: `--target`; one of `--level <0-100>` or `--status <charging|discharging>`): Set battery state. `--level` checks the current emulator charging state automatically (`0-100` while charging, `1-100` otherwise).
49
49
  - `geolocation` (Req: `--target`; one of `--longitude`, `--latitude`, `--altitude`, `--direction`): Inject GPS data.
50
50
  - `scene <outdoorRunning|outdoorCycling|drivingNavigation>` (Req: `--target`): Start motion simulation.
51
51
  - `sensor` (Req: `--target`; one of `--light-intensity`, `--humidity`, `--temperature`, `--steps`, `--heartrate`): Inject sensor data.
@@ -58,9 +58,9 @@ Manage local emulator instances and system images.
58
58
  ### `devecocli ui`
59
59
  Inspect UI on a connected physical device or running emulator.
60
60
  - `screenshot`: Capture a screenshot from a physical device or running emulator. `--device <name|serial>` is optional when exactly one device is connected, and required when multiple devices are connected.
61
- - Optional: `--display <displayId>`, `--path <path>` (existing directory or PNG file path whose parent exists; create the directory first; default: `./screenshot-<timestamp>.png`).
61
+ - Optional: `--display <displayId>`. Required: `--path <path>` (existing directory or PNG file path, including paths relative to the current directory; writable destination; no overwrite).
62
62
  - Implementation uses `hdc shell snapshot_display` and `hdc file recv`; set `DEVECO_CLI_DEBUG=1` to inspect the actual `hdc` commands.
63
- *Ex*: `mkdir -p screenshots && devecocli ui screenshot --device Phone --path ./screenshots/phone.png`
63
+ *Ex*: `devecocli ui screenshot --device Phone --path ./screenshots/phone.png`
64
64
 
65
65
  ### `devecocli docs`
66
66
  Search/read local HarmonyOS docs.
@@ -85,6 +85,14 @@ Build, install, and launch.
85
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
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
87
  *Ex*: `devecocli run` → edit code → write `.hvigor/changes.txt` → `devecocli run --apply changes.txt`
88
+ - `--hotreload [action]`: **Hot-reload watch session** — must be started as a **background process** (the process holds a persistent socket to the hvigor daemon). It builds the hap in hot-reload mode (`hotReload=true debuggable=true`), deploys+launches the app, then the process itself connects a socket to the daemon and sends `CommonBuild assembleHap --hot-reload-build --watch`, **staying connected** so the daemon's watch worker (rollup watch) stays alive for `--hotreload-apply` to reuse. The process stays alive (onBuildOutput streams to its stdout). **Must be stopped (kill the background process) when the hot-reload debug session ends** — otherwise the watch worker/daemon leaks. `--hotreload stop` additionally stops the hvigor daemon.
89
+ - **Usage**: start `devecocli run --module <m> --hotreload` as a background process; wait for the `.hotreload-mode` marker (or "watch session active" on its stdout) = ready; then run `devecocli run --module <m> --hotreload-apply <file>` (foreground). When done: kill the background process + `devecocli run --hotreload stop`.
90
+ - `--hotreload-apply <fileName>`: **Hot reload without app restart** — reads the changed-file list from `.hvigor/<fileName>` (same format/merge rules as `--apply`), opens a **short socket** to the daemon (kept alive by the background `--hotreload` process) and sends `CommonBuild assembleDevHqf --hot-compile` → the watch worker incrementally hot-compiles changed `.ets`/`.ts` into abc (HotReloadArkTS; output/errors streamed live via WatchLog), then **manually** packs + signs a hqf from that abc (`app_packing_tool.jar` + `hap-sign-tool.jar`, DevEco material password decrypted via `DecipherUtil`), and installs it via `bm quickfix -a -f -o`. The app is **not restarted** — changes take effect immediately.
91
+ - **Prereq**: the background `devecocli run --hotreload` process must be running (holds the watch session). If `--hotreload-apply` times out, the watch session isn't alive — (re)start the background `--hotreload`.
92
+ - **Scope (important)**: hot reload targets a **single module** (`--module` required; the target can be entry/hsp/feature; `har` deps are folded in and fine). **`har` dependency changes are auto-routed** to the dependent main module's (entry/feature/hsp) `hotReload/changedFileList.json` — so editing a har's `.ets` and listing it hot-reloads via the target module. Changes in **`feature`/`hsp` dependency modules** (not the target) are NOT hot-reloadable — they're detected and warned (run a full `devecocli run` to redeploy those). `@State`/state-decorator changes are **not** hot-reloadable (state isn't re-initialized); hot-reloadable changes are non-state code: UI property values (`.fontColor`/`.fontSize`), `Text`/`Button` literal labels, method bodies, expressions. Resources/native changes need a full run.
93
+ - **Compile errors**: ArkTS compile errors from the hot compile are routed (via WatchLog) to the **background `--hotreload` process**, which writes them to **`.hvigor/hotreload-watch.log`** (and its stdout). On failure, `--hotreload-apply` reads that file and prints the errors inline (fast-fail, ~15s timeout if the watch session is dead).
94
+ - **Artifacts under `.hvigor/`** (shared with `--apply`): `.hvigor/<fileName>` = the changed-file list you write; `.hvigor/hotreload-watch.log` = the watch session's onBuildOutput/compile-errors (written by the background `--hotreload` process; safe to read/delete). The hot-reload marker is `<module>/build/<product>/.hotreload-mode`.
95
+ *Ex*: background `devecocli run --module entry --hotreload` → (ready) → edit `.fontColor` in `entry/src/main/ets/pages/Index.ets` → write path to `.hvigor/changes.txt` → `devecocli run --module entry --hotreload-apply changes.txt` (UI updates without restart). When done: kill the background process + `devecocli run --hotreload stop`.
88
96
 
89
97
  ### `devecocli signature generate` `[Outside sandbox]`
90
98
  Auto-generate HarmonyOS signing materials (local p12/csr + cloud cert + test profile) and write signing config to `build-profile.json5`.
@@ -115,7 +123,7 @@ Inspect UI on a connected device. All subcommands accept `--device <name|serial>
115
123
  |---|---|---|
116
124
  | `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
125
  | `window list` | List active windows | `--format default\|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`) |
126
+ | `screenshot` | Capture a screenshot of the device screen | `--display <displayId>`, required `--path <path>` (existing directory or PNG file path; relative paths supported; writable destination; no overwrite) |
119
127
  | `click [x] [y]` | Tap at the specified coordinates or node | `--id <id>` (auto-resolves to center), `--window <windowId>` (used with `--id`) |
120
128
  | `doubleclick [x] [y]` | Double-tap at the specified coordinates or node | `--id <id>`, `--window <windowId>` |
121
129
  | `longclick [x] [y]` | Long-press at the specified coordinates or node | `--id <id>`, `--window <windowId>` |
@@ -168,7 +176,7 @@ Manage HarmonyOS skills in AI agents/projects.
168
176
 
169
177
  ### `devecocli check compat` `[Outside sandbox]`
170
178
  Scan source code for breaking API changes between two SDK versions. Built on top of DevEco Studio's `arkanalyzer-apiscan` plugin.
171
- - `versions`: List available target SDK versions.
179
+ - `versions`: List available target SDK versions. Opts: `--format <default|json>` (default: `default`).
172
180
  - Default (no args): project-level scan.
173
181
  - `--modules <m1> [m2...]`: Module-level scan.
174
182
  - `<file1> [file2...]`: File-level scan (`.ets`/`.c`/`.cpp` only).
package/THIRD-PARTY-LICENSES CHANGED
@@ -866,6 +866,39 @@ SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
866
866
 
867
867
  -----------
868
868
 
869
+ The following npm package may be included in this product:
870
+
871
+ - @socket.io/component-emitter@3.1.2
872
+
873
+ This package contains the following license:
874
+
875
+ (The MIT License)
876
+
877
+ Copyright (c) 2014 Component contributors <dev@component.io>
878
+
879
+ Permission is hereby granted, free of charge, to any person
880
+ obtaining a copy of this software and associated documentation
881
+ files (the "Software"), to deal in the Software without
882
+ restriction, including without limitation the rights to use,
883
+ copy, modify, merge, publish, distribute, sublicense, and/or sell
884
+ copies of the Software, and to permit persons to whom the
885
+ Software is furnished to do so, subject to the following
886
+ conditions:
887
+
888
+ The above copyright notice and this permission notice shall be
889
+ included in all copies or substantial portions of the Software.
890
+
891
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
892
+ EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
893
+ OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
894
+ NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
895
+ HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
896
+ WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
897
+ FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
898
+ OTHER DEALINGS IN THE SOFTWARE.
899
+
900
+ -----------
901
+
869
902
  The following npm packages may be included in this product:
870
903
 
871
904
  - body-parser@2.2.2
@@ -1153,6 +1186,97 @@ SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
1153
1186
 
1154
1187
  -----------
1155
1188
 
1189
+ The following npm package may be included in this product:
1190
+
1191
+ - engine.io-parser@5.2.3
1192
+
1193
+ This package contains the following license:
1194
+
1195
+ (The MIT License)
1196
+
1197
+ Copyright (c) 2014-present Guillermo Rauch and Socket.IO contributors
1198
+
1199
+ Permission is hereby granted, free of charge, to any person obtaining
1200
+ a copy of this software and associated documentation files (the
1201
+ 'Software'), to deal in the Software without restriction, including
1202
+ without limitation the rights to use, copy, modify, merge, publish,
1203
+ distribute, sublicense, and/or sell copies of the Software, and to
1204
+ permit persons to whom the Software is furnished to do so, subject to
1205
+ the following conditions:
1206
+
1207
+ The above copyright notice and this permission notice shall be
1208
+ included in all copies or substantial portions of the Software.
1209
+
1210
+ THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
1211
+ EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
1212
+ MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
1213
+ IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
1214
+ CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
1215
+ TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
1216
+ SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
1217
+
1218
+ -----------
1219
+
1220
+ The following npm package may be included in this product:
1221
+
1222
+ - engine.io-client@6.6.6
1223
+
1224
+ This package contains the following license:
1225
+
1226
+ (The MIT License)
1227
+
1228
+ Copyright (c) 2014-present Guillermo Rauch and Socket.IO contributors
1229
+
1230
+ Permission is hereby granted, free of charge, to any person obtaining
1231
+ a copy of this software and associated documentation files (the
1232
+ 'Software'), to deal in the Software without restriction, including
1233
+ without limitation the rights to use, copy, modify, merge, publish,
1234
+ distribute, sublicense, and/or sell copies of the Software, and to
1235
+ permit persons to whom the Software is furnished to do so, subject to
1236
+ the following conditions:
1237
+
1238
+ The above copyright notice and this permission notice shall be
1239
+ included in all copies or substantial portions of the Software.
1240
+
1241
+ THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
1242
+ EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
1243
+ MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
1244
+ IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
1245
+ CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
1246
+ TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
1247
+ SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
1248
+
1249
+ -----------
1250
+
1251
+ The following npm package may be included in this product:
1252
+
1253
+ - socket.io-parser@4.2.6
1254
+
1255
+ This package contains the following license:
1256
+
1257
+ (The MIT License)
1258
+
1259
+ Copyright (c) 2014-present Guillermo Rauch and Socket.IO contributors
1260
+
1261
+ Permission is hereby granted, free of charge, to any person obtaining a copy of
1262
+ this software and associated documentation files (the 'Software'), to deal in
1263
+ the Software without restriction, including without limitation the rights to
1264
+ use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
1265
+ the Software, and to permit persons to whom the Software is furnished to do so,
1266
+ subject to the following conditions:
1267
+
1268
+ The above copyright notice and this permission notice shall be included in all
1269
+ copies or substantial portions of the Software.
1270
+
1271
+ THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
1272
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
1273
+ FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
1274
+ COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
1275
+ IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
1276
+ CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
1277
+
1278
+ -----------
1279
+
1156
1280
  The following npm packages may be included in this product:
1157
1281
 
1158
1282
  - content-type@1.0.5
@@ -1906,6 +2030,35 @@ THE SOFTWARE.
1906
2030
 
1907
2031
  -----------
1908
2032
 
2033
+ The following npm package may be included in this product:
2034
+
2035
+ - ws@8.21.1
2036
+
2037
+ This package contains the following license:
2038
+
2039
+ Copyright (c) 2011 Einar Otto Stangvik <einaros@gmail.com>
2040
+ Copyright (c) 2013 Arnout Kazemier and contributors
2041
+ Copyright (c) 2016 Luigi Pinca and contributors
2042
+
2043
+ Permission is hereby granted, free of charge, to any person obtaining a copy of
2044
+ this software and associated documentation files (the "Software"), to deal in
2045
+ the Software without restriction, including without limitation the rights to
2046
+ use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
2047
+ the Software, and to permit persons to whom the Software is furnished to do so,
2048
+ subject to the following conditions:
2049
+
2050
+ The above copyright notice and this permission notice shall be included in all
2051
+ copies or substantial portions of the Software.
2052
+
2053
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
2054
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
2055
+ FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
2056
+ COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
2057
+ IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
2058
+ CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
2059
+
2060
+ -----------
2061
+
1909
2062
  The following npm package may be included in this product:
1910
2063
 
1911
2064
  - ipaddr.js@1.9.1
@@ -2384,6 +2537,16 @@ IN THE SOFTWARE.
2384
2537
 
2385
2538
  -----------
2386
2539
 
2540
+ The following npm package may be included in this product:
2541
+
2542
+ - xmlhttprequest-ssl@2.1.2
2543
+
2544
+ This package contains the following license:
2545
+
2546
+ http://creativecommons.org/licenses/MIT/
2547
+
2548
+ -----------
2549
+
2387
2550
  The following npm package may be included in this product:
2388
2551
 
2389
2552
  - zod-to-json-schema@3.25.2
@@ -3768,6 +3931,36 @@ SOFTWARE.
3768
3931
 
3769
3932
  -----------
3770
3933
 
3934
+ The following npm package may be included in this product:
3935
+
3936
+ - socket.io-client@4.8.3
3937
+
3938
+ This package contains the following license:
3939
+
3940
+ The MIT License (MIT)
3941
+
3942
+ Copyright (c) 2014-present Guillermo Rauch and Socket.IO contributors
3943
+
3944
+ Permission is hereby granted, free of charge, to any person obtaining a copy
3945
+ of this software and associated documentation files (the "Software"), to deal
3946
+ in the Software without restriction, including without limitation the rights
3947
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
3948
+ copies of the Software, and to permit persons to whom the Software is
3949
+ furnished to do so, subject to the following conditions:
3950
+
3951
+ The above copyright notice and this permission notice shall be included in
3952
+ all copies or substantial portions of the Software.
3953
+
3954
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
3955
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
3956
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
3957
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
3958
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
3959
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
3960
+ THE SOFTWARE.
3961
+
3962
+ -----------
3963
+
3771
3964
  The following npm package may be included in this product:
3772
3965
 
3773
3966
  - define-properties@1.2.1