docs: add command-line tools reference (hvigorw, codelinter, hstack)

arkts-development/references/hvigor-commandline.md

@@ -0,0 +1,179 @@
+# Hvigor 命令行构建工具 (hvigorw)
+
+hvigorw 是 Hvigor 的 wrapper 包装工具，支持自动安装 Hvigor 构建工具和相关插件依赖，以及执行 Hvigor 构建命令。
+
+## 命令格式
+
+```bash
+hvigorw [taskNames...] <options>
+```
+
+## 编译构建任务
+
+| 任务 | 说明 |
+|------|------|
+| `clean` | 清理构建产物 build 目录 |
+| `assembleHap` | 构建 Hap 应用 |
+| `assembleApp` | 构建 App 应用 |
+| `assembleHsp` | 构建 Hsp 包 |
+| `assembleHar` | 构建 Har 包 |
+| `collectCoverage` | 基于打点数据生成覆盖率统计报表 |
+
+## 常用构建参数
+
+| 参数 | 说明 |
+|------|------|
+| `-p buildMode={debug\|release}` | 指定构建模式。默认：Hap/Hsp/Har 为 debug，App 为 release |
+| `-p debuggable=true/false` | 覆盖 buildOption 中的 debuggable 配置 |
+| `-p product={ProductName}` | 指定 product 进行编译，默认为 default |
+| `-p module={ModuleName}@{TargetName}` | 指定模块及 target 编译（需配合 `--mode module`） |
+| `-p ohos-test-coverage={true\|false}` | 执行测试框架代码覆盖率插桩编译 |
+| `-p parameterFile=param.json` | 设置 oh-package.json5 的参数配置文件 |
+
+## 构建示例
+
+```bash
+# 清理构建产物
+hvigorw clean
+
+# Debug 模式构建 Hap
+hvigorw assembleHap -p buildMode=debug
+
+# Release 模式构建 App
+hvigorw assembleApp -p buildMode=release
+
+# 构建指定 product
+hvigorw assembleHap -p product=free
+
+# 构建指定模块
+hvigorw assembleHap -p module=entry@default --mode module
+
+# 构建多个模块
+hvigorw assembleHar -p module=library1@default,library2@default --mode module
+```
+
+## 测试命令
+
+### Instrument Test (设备测试)
+
+```bash
+hvigorw onDeviceTest -p module={moduleName} -p coverage={true|false} -p scope={suiteName}#{methodName}
+```
+
+- `module`: 执行测试的模块，缺省执行所有模块
+- `coverage`: 是否生成覆盖率报告，默认 true
+- `scope`: 测试范围，格式 `{suiteName}#{methodName}` 或 `{suiteName}`
+- `ohos-debug-asan`: 是否启用 ASan 检测，默认 false (5.19.0+)
+
+**输出路径:**
+- 覆盖率报告: `<module-path>/.test/default/outputs/ohosTest/reports`
+- 测试结果: `<project>/<module>/.test/default/intermediates/ohosTest/coverage_data/test_result.txt`
+
+### Local Test (本地测试)
+
+```bash
+hvigorw test -p module={moduleName} -p coverage={true|false} -p scope={suiteName}#{methodName}
+```
+
+**输出路径:**
+- 覆盖率报告: `<module-path>/.test/default/outputs/test/reports`
+- 测试结果: `<project>/<module>/.test/default/intermediates/test/coverage_data/test_result.txt`
+
+## 日志级别
+
+| 参数 | 说明 |
+|------|------|
+| `-e, --error` | 设置日志级别为 error |
+| `-w, --warn` | 设置日志级别为 warn |
+| `-i, --info` | 设置日志级别为 info |
+| `-d, --debug` | 设置日志级别为 debug |
+| `--stacktrace` | 开启打印异常堆栈信息 |
+
+## 构建分析 (Build Analyzer)
+
+| 参数 | 说明 |
+|------|------|
+| `--analyze=normal` | 普通模式分析 |
+| `--analyze=advanced` | 进阶模式，更详细的任务耗时数据 |
+| `--analyze=ultrafine` | 超精细化模式，ArkTS 编译详细打点 (6.0.0+) |
+| `--analyze=false` | 不启用构建分析 |
+| `--config properties.hvigor.analyzeHtml=true` | 生成 HTML 可视化报告到 `.hvigor/report` |
+
+## 守护进程 (Daemon)
+
+| 参数 | 说明 |
+|------|------|
+| `--daemon` | 启用守护进程 |
+| `--no-daemon` | 关闭守护进程（命令行模式推荐） |
+| `--stop-daemon` | 关闭当前工程的守护进程 |
+| `--stop-daemon-all` | 关闭所有工程的守护进程 |
+| `--status-daemon` | 查询所有 Hvigor 守护进程信息 |
+| `--max-old-space-size=12345` | 设置老生代内存大小 (MB) |
+| `--max-semi-space-size=32` | 设置新生代半空间大小 (MB, 5.18.4+) |
+
+## 性能与内存优化
+
+| 参数 | 说明 |
+|------|------|
+| `--parallel` / `--no-parallel` | 开启/关闭并行构建（默认开启） |
+| `--incremental` / `--no-incremental` | 开启/关闭增量构建（默认开启） |
+| `--optimization-strategy=performance` | 性能优先模式，加快构建但占用更多内存 (5.19.2+) |
+| `--optimization-strategy=memory` | 内存优先模式（默认）(5.19.2+) |
+
+## 公共命令
+
+| 任务 | 说明 |
+|------|------|
+| `tasks` | 打印工程各模块包含的任务信息 |
+| `taskTree` | 打印工程各模块的任务依赖关系 |
+| `prune` | 清除 30 天未使用的缓存并删除 pnpm 未引用包 |
+| `buildInfo` | 打印 build-profile.json5 配置信息 (5.18.4+) |
+
+### buildInfo 扩展参数
+
+```bash
+# 打印工程级配置
+hvigorw buildInfo
+
+# 打印指定模块配置
+hvigorw buildInfo -p module=entry
+
+# 包含 buildOption 配置
+hvigorw buildInfo -p buildOption
+
+# JSON 格式输出
+hvigorw buildInfo -p json
+```
+
+## 其他参数
+
+| 参数 | 说明 |
+|------|------|
+| `-h, --help` | 打印帮助信息 |
+| `-v, --version` | 打印版本信息 |
+| `-s, --sync` | 同步工程信息到 `./hvigor/outputs/sync/output.json` |
+| `-m, --mode` | 指定执行目录级别 (如 `-m project`) |
+| `--type-check` | 开启 hvigorfile.ts 类型检查 |
+| `--watch` | 观察模式，用于预览和热加载 |
+| `--node-home <string>` | 指定 Node.js 路径 |
+| `--config, -c` | 指定 hvigor-config.json5 参数 |
+
+## CI/CD 常用命令组合
+
+```bash
+# 完整的 Release 构建流程
+hvigorw clean && hvigorw assembleApp -p buildMode=release --no-daemon
+
+# 带构建分析的 Debug 构建
+hvigorw assembleHap -p buildMode=debug --analyze=advanced --no-daemon
+
+# 运行测试并生成覆盖率报告
+hvigorw onDeviceTest -p coverage=true --no-daemon
+
+# 内存受限环境构建
+hvigorw assembleHap --optimization-strategy=memory --no-daemon
+
+# 清理缓存
+hvigorw prune
+hvigorw --stop-daemon-all
+```