@deveco-test/hmos-deveco-cli 0.2.1 → 0.3.0-TD.1.2

package/README.md

@@ -91,12 +91,14 @@ devecocli init --path .\work\ARKTS\NewData
 | ------------------------- | ----------------------------------------- |
 | `devecocli create`        | 创建新的 HarmonyOS 项目                         |
 | `devecocli build`         | 构建项目并产出 `.hap` / `.hsp` / `.har` / `.app` |
+| `devecocli check lint`    | 检查代码规范并输出实践建议与报告                      |
 | `devecocli run`           | 安装并运行应用                                   |
 | `devecocli device list`   | 查看当前连接设备                                  |
 | `devecocli log`           | 查看 `hilog` 或崩溃日志                          |
 | `devecocli docs search`   | 搜索本地 HarmonyOS 文档                         |
 | `devecocli init`          | 安装内置技能或配置 `MCP`                           |
 | `devecocli skills`        | 管理 HarmonyOS 技能市场中的技能                     |
+| `devecocli signature generate` | 自动生成调试签名材料并配置到项目     |
 
 ## 命令集
 
@@ -131,6 +133,8 @@ Commands:
   init [options]         Install the deveco-cli skill or configure the deveco-mcp server into AI agents
   serve                  Host bundled auxiliary protocol servers
   docs [options]         Search and read HarmonyOS documentation from local docs directory
+  check                  Run DevEco project checks
+  signature              Generate application signature
   help [command]         display help for command
 ```
 
@@ -312,6 +316,29 @@ devecocli build --product oversea --modules entry --build-mode release
 devecocli build clean
 ```
 
+### `check lint`
+
+检查代码规范并输出实践建议与报告。
+
+**命令格式：**
+
+```bash
+devecocli check lint [path]
+```
+
+**参数：**
+
+| 参数名                        | 说明                                                                  |
+| ---------------------------- | --------------------------------------------------------------------- |
+| `[path]`                     | 可选，待检查的文件或目录；默认使用 `build-profile.json5` 所在的项目根目录，否则使用当前目录 |
+| `--config-path <path>`       | Code Linter 配置文件路径，仅支持 `.json` 或 `.json5`；默认使用待检查项目根目录下的 `code-linter.json5`，显式指定时必须与待检查路径属于同一项目 |
+| `--fix`                      | 自动修复可修复的问题                                                  |
+| `--incremental`              | 仅检查 Git 未提交文件                                                 |
+| `--product <name>`           | `build-profile.json5` 中定义的 product，默认为 `default`              |
+| `--format <default\|json>`   | 完整报告格式；`default` 输出 Markdown，`json` 输出 JSON                |
+| `--output-path <path>`       | 完整报告文件或目录；目录形式会自动生成带时间戳的报告文件               |
+| `--limit <number>`           | 未指定 `--output-path` 时，限制终端显示的问题数量                      |
+
 ### `device list`
 
 查询所有已连接的设备
@@ -353,7 +380,7 @@ devecocli device view -t "My Device Name"
 **命令格式：**
 
 ```bash
-devecocli run --module <module> --device <device> --product <product> --build-mode <mode> --ability <ability> --uninstall --skip-build
+devecocli run --module <module> --device <device> --product <product> --build-mode <mode> --ability <ability> --uninstall --skip-build --apply <txtFile>
 ```
 
 **参数：**
@@ -367,6 +394,7 @@ devecocli run --module <module> --device <device> --product <product> --build-mo
 | --ability    | 可选，待启动的 `Ability` ，默认：模块 `module.json5` 中的`mainElement`                                                |
 | --uninstall  | 可选，安装前先卸载已有应用                                                                                          |
 | --skip-build | 可选，跳过构建操作，直接安装应用 。\*\*说明：\*\*使用该参数时，需确保对应模块已有构建产物                                                      |
+| --apply \<fileName\> | 可选，**快速增量部署**：仅重编改动文件 → signed hqf → `bm quickfix -a -f -o` 安装 → 重启，比全量 `run` 快。`<fileName>` 是工程 `.hvigor/` 目录下的**纯文件名**（调用方把清单写到此目录，文件名做安全校验防穿越）；内容为本轮改动的源文件路径清单（每行一个相对工程根路径；`#`/空行忽略；`.ets`/`.ts`/`.cpp`/资源文件；changeFileList 增量累积，只需列本轮改的，历史文件自动保留）。模块从清单路径自动识别（无需 `--module`）。**前提**：先 `devecocli run` 全量构建部署一次（生成 buildConfig.json 缓存）；**没生效排查**：检查 `<module>/build/config/buildConfig.json` 有无内容（空/无 = 没跑过 `devecocli run`）；**失败兜底**：直接 `devecocli run`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
 
 **示例：**
 
@@ -377,6 +405,7 @@ devecocli run --module library@phone --device 127.0.0.1:5555
 devecocli run --product oversea --module entry --ability EntryAbility
 devecocli run --build-mode release
 devecocli run --uninstall
+devecocli run --apply changes.txt
 ```
 
 ### `log`
@@ -539,6 +568,44 @@ devecocli skills remove --skill skillname --agent agentname  # skillname需替
 }
 ```
 
+### `signature generate`
+
+自动生成调试签名材料（包括p12密钥库、csr证书请求文件、p7b配置文件、cer证书文件），并将签名配置写入项目的 `build-profile.json5` 中。
+
+**命令格式：**
+
+```bash
+devecocli signature generate  --product <product> --team-id <team-id> --force --help
+``` 
+
+**参数：**
+
+| 参数名                   | 说明                                      |
+|-----------------------|-----------------------------------------|
+| --product \<product\> | 可选，指定product生成签名，默认为 `default`          |
+| --team-id \<team-id\> | 可选，指定生效的team-id,默认使用自身作为团队信息            |
+| --force               | 可选，强制覆盖已存在的证书文件 |
+| --help,--h            | 可选，查看帮助信息                               |
+
+**示例：**
+
+```bash
+# 自动生成签名并写入工程配置
+devecocli signature generate
+
+# 指定product
+devecocli signature generate --product default
+
+# 指定team-id
+devecocli signature generate --team-id 1222
+
+# 强制覆盖已存在的证书文件
+devecocli signature generate --force
+
+# 查询帮助信息
+devecocli signature generate --help
+```
+
 ## 常见问题
 
 ### 如何本地推包运行

package/SKILL.md

@@ -13,7 +13,7 @@ description: >-
 - ❌ `hvigorw` directly → ✅ `devecocli build`
 - ❌ `hdc` directly (when a `devecocli` wrapper exists) → ✅ `devecocli device` / `devecocli log` / `devecocli run`
 
-Available commands: `build`, `run`, `update`, `device`, `skills`, `log`, `create`, `init`, `serve`, `docs`.
+Available commands: `build`, `check`, `run`, `update`, `device`, `skills`, `log`, `create`, `init`, `serve`, `docs`, `auth`.
 
 **Sandbox Rule**: Commands tagged `[Outside sandbox]` must be run outside the sandbox.
 
@@ -36,6 +36,11 @@ Compile and package project/modules. (Defaults: `--product default`, `--build-mo
 | Whole product bundle (.app) | `devecocli build --product <name>` |
 | Clean build outputs | `devecocli build clean` |
 
+### `devecocli check lint`
+Run DevEco Code Linter checks for TS/ArkTS code.
+- `[path]`: File or directory to lint. Defaults to the project root from `build-profile.json5`, otherwise the current directory.
+- Options: `--config-path <file>`, `--fix`, `--incremental`, `--product <name>`, `--format <default|json>`, `--output-path <path>`, `--limit <number>`.
+
 ### `devecocli docs`
 Search/read local HarmonyOS docs.
 - `search <keywords...>`: Match any keyword. Opts: `--catalog <name>`, `--format <default|json>`, `--limit <n>`.
@@ -54,6 +59,11 @@ Build, install, and launch.
 - `--ability <ability>`: Default from `module.json5`.
 - `--uninstall`: Uninstall existing app first (Fixes signing key issues).
 - `--skip-build`: Deploy existing artifacts.
+- `--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).
+  - `<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.
+  - **Prereq**: run `devecocli run` once first (full build + deploy + generates the `buildConfig.json` cache that `--apply` reuses).
+  - **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`.
+*Ex*: `devecocli run` → edit code → write `.hvigor/changes.txt` → `devecocli run --apply changes.txt`
 - **Previewer mode** (auto-detected from `--device`): When `--device` value matches previewer product names (e.g. `"Pura 90 Pro"`, `"MatePad 11.5'S"`, `phone`, `pad`), the CLI launches the DevEco Studio **previewer** instead of installing/running the app. Comma-separated names → multi-previewer (count = list length). When `--device` is a serial/IP:port/unmatched value, normal run mode is used. Omitting `--device` → normal run. Ensures the DevEco Studio desktop process is running first (throws immediately if not — does NOT auto-start Studio on any platform), then `hdc shell aa start -a DevEcoViewerAbility -b com.huawei.devecostudio -m DevEcoViewer --pi instanceId <pid> --ps paramJson <JSON with double-quotes escaped>` with project info (`bundleName` / `abilityName` / `moduleName` / `productName` / `productType` / `subProductType` / `instanceId` / `launchDeviceIndex` / `launchFlag` / `isCustom` / `nativeDebuggable` / `appDebuggable`). `instanceId` = CLI process.pid; `launchDeviceIndex` = -1 for single previewer, 0-based for multi. Skips build/install (except multi-previewer needs build+install with multiAppMode). **Smart matching**: case/whitespace/punctuation insensitive; accepts aliases (`phone`, `tablet`/`pad`, `fold`/`foldable`, `widefold`/`wide`, `triplefold`/`triple`) and short forms; substring match and Levenshtein ≤ 2 fallback. Ambiguous matches report candidates. Supported products: `Pura 90 Pro`, `MatePad 11.5'S`, `Mate X7`, `Pura X`, `Mate XT`.
   - **Windows/macOS**: uses DevEco Studio's bundled hdc, auto-detects Studio install path via ToolProvider. hdc target device is auto-selected via `selectDevice` (previewer mode does not use `--device` as hdc target).
   - **HarmonyOS native (2in1 PC)**: hdc does NOT auto-discover the local device — self-connect required. In previewer mode, `--device` is the product name (not hdc target). The CLI checks `hdc list targets` for a `127.0.0.1:<port>` entry: if found, uses it directly; if not found, warns `hdc 未自联` and fallbacks to `connectLocalDevice` (resolution: `DEVECO_HDC_PORT` env var → existing `hdc list targets` → interactive prompt → error). DevEco Studio is a system app there; local `pgrep` cannot see Studio's process due to UID isolation, so the CLI detects Studio via `hdc shell ps -ef | grep com.huawei.devecostudio` (hdcd runs as root) — requires hdc self-connect first. The CLI does NOT auto-start Studio on any platform.
@@ -68,6 +78,31 @@ Fetch hilog or crash logs. Req `--device <name|serial>` on multi-device hosts.
 - `--tail <num>` / `--follow`: Keep last N lines / stream real-time (no `--to`).
 *Ex*: `devecocli log --crash --bundle-name com.example.app`, `devecocli log --level E --from 5m --tail 200`
 
+### `devecocli ui`
+Inspect UI on a connected device. All subcommands accept `--device <name|serial>` (Req on multi-device hosts).
+
+| Subcommand | Description | Key Options |
+|---|---|---|
+| `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` |
+| `window list` | List active windows | `--format default\|json`, `--all` (include system windows) |
+| `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) |
+| `click [x] [y]` | Tap at the specified coordinates or node | `--id <id>` (auto-resolves to center), `--window <windowId>` (used with `--id`) |
+| `doubleclick [x] [y]` | Double-tap at the specified coordinates or node | `--id <id>`, `--window <windowId>` |
+| `longclick [x] [y]` | Long-press at the specified coordinates or node | `--id <id>`, `--window <windowId>` |
+| `swipe <x1> <y1> <x2> <y2>` | Swipe from one point to another (precise coordinates, custom speed) | `--speed <n>` (200–40000, px/s) |
+| `fling <x1> <y1> <x2> <y2>` | Fling from one point to another | `--speed <n>` (200–40000, px/s) |
+| `drag <x1> <y1> <x2> <y2>` | Drag from one point to another | `--speed <n>` (200–40000, px/s) |
+| `dircfling <direction>` | Quick directional fling (system default speed, ideal for scrolling) | `direction`: `up`, `down`, `left`, `right` |
+| `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`) |
+
+- **Coordinates vs `--id`**: Mutually exclusive. Provide either `x y` or `--id <id>`. For `text`, if neither is given, text goes to the currently focused field.
+- **`--window`**: May only be used together with `--id`. Default is focused window. Secondary display operations via `--id` + `--window` are not supported.
+- **`swipe` vs `dircfling`**: `swipe` requires exact start/end coordinates and supports `--speed`; `dircfling` only needs a direction (`up/down/left/right`) and uses system default speed (ideal for page/list scrolling).
+- **Text encoding**: Special characters in `text` are Base64-encoded internally to safely pass through device shell.
+- `--format json` pairs well with `jq`.
+- `--mode full`: full layout tree, no filtering.
+- `--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.
+
 ## 2. Setup
 
 ### `devecocli init`
@@ -81,6 +116,19 @@ MUTUALLY EXCLUSIVE modes for setup:
 - `-f, --force`: Overwrite existing config.
 *MCP Rules*: Global MCP (no `--project`) only supports `opencode` and `cursor`. Others require `--project`.
 
+### `devecocli auth login`
+Sign in to your Huawei Developer account. Opens a browser for OAuth authentication. Required before `signature generate`.
+*Ex*: `devecocli auth login`
+
+### `devecocli auth logout`
+Sign out and clear locally stored credentials.
+
+### `devecocli auth status`
+Show the current logged-in user.
+
+### `devecocli auth team list`
+List team accounts the current user has joined.
+
 ### `devecocli skills`
 Manage HarmonyOS skills in AI agents/projects.
 - `list [-l|--long]` / `find <keyword>`: List or search skills.
@@ -105,6 +153,8 @@ Manage HarmonyOS skills in AI agents/projects.
   `devecocli log --crash --bundle-name <bundle>`
 - **Release build**:
   `devecocli build --product oversea --build-mode release`
+- **First-time signing setup**:
+  `devecocli login` -> `devecocli signature generate --product default` -> `devecocli build` -> `devecocli run`
 
 ## Troubleshooting