clz/arkts-skills
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

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

Browse Source
This commit is contained in:
CHE LIANG ZHAO
2026-01-22 16:29:45 +08:00
parent ab3e0b5590
commit 6e5c7961d4
4 changed files with 626 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

134
arkts-development/SKILL.md
View File

@@ -141,11 +141,145 @@ ArkTS enforces stricter rules than TypeScript for performance and safety:
See [references/migration-guide.md](references/migration-guide.md) for complete TypeScript → ArkTS migration details. See [references/migration-guide.md](references/migration-guide.md) for complete TypeScript → ArkTS migration details.
## Command Line Build (hvigorw)
hvigorw is the Hvigor wrapper tool for command-line builds.
```bash
# Common build tasks
hvigorw clean # Clean build directory
hvigorw assembleHap -p buildMode=debug # Build Hap (debug)
hvigorw assembleApp -p buildMode=release # Build App (release)
hvigorw assembleHar # Build Har library
hvigorw assembleHsp # Build Hsp
# Build specific module
hvigorw assembleHap -p module=entry@default --mode module
# Run tests
hvigorw onDeviceTest -p module=entry -p coverage=true
hvigorw test -p module=entry # Local test
# CI/CD recommended
hvigorw assembleApp -p buildMode=release --no-daemon
```
Common parameters:
| Parameter | Description |
|-----------|-------------|
| `-p buildMode={debug\|release}` | Build mode |
| `-p product={name}` | Target product (default: default) |
| `-p module={name}@{target}` | Target module (with `--mode module`) |
| `--no-daemon` | Disable daemon (recommended for CI) |
| `--analyze=advanced` | Enable build analysis |
| `--optimization-strategy=memory` | Memory-optimized build |
See [references/hvigor-commandline.md](references/hvigor-commandline.md) for complete command reference.
## Code Linter (codelinter)
codelinter is the code checking and fixing tool for ArkTS/TS files.
```bash
# Basic usage
codelinter # Check current project
codelinter /path/to/project # Check specified project
codelinter -c ./code-linter.json5 # Use custom rules
# Check and auto-fix
codelinter --fix
codelinter -c ./code-linter.json5 --fix
# Output formats
codelinter -f json -o ./report.json # JSON report
codelinter -f html -o ./report.html # HTML report
# Incremental check (Git changes only)
codelinter -i
# CI/CD with exit codes
codelinter --exit-on error,warn # Non-zero exit on error/warn
```
| Parameter | Description |
|-----------|-------------|
| `-c, --config <file>` | Specify rules config file |
| `--fix` | Auto-fix supported issues |
| `-f, --format` | Output format: default/json/xml/html |
| `-o, --output <file>` | Save result to file |
| `-i, --incremental` | Check only Git changed files |
| `-p, --product <name>` | Specify product |
| `-e, --exit-on <levels>` | Exit code levels: error,warn,suggestion |
See [references/codelinter.md](references/codelinter.md) for complete reference.
## Stack Trace Parser (hstack)
hstack parses obfuscated crash stacks from Release builds back to source code locations.
```bash
# Parse crash files directory
hstack -i crashDir -o outputDir -s sourcemapDir -n nameCacheDir
# Parse with C++ symbols
hstack -i crashDir -o outputDir -s sourcemapDir --so soDir -n nameCacheDir
# Parse single crash stack
hstack -c "at func (entry|entry|1.0.0|src/main/ets/pages/Index.ts:58:58)" -s sourcemapDir
```
| Parameter | Description |
|-----------|-------------|
| `-i, --input` | Crash files directory |
| `-c, --crash` | Single crash stack string |
| `-o, --output` | Output directory (or file with `-c`) |
| `-s, --sourcemapDir` | Sourcemap files directory |
| `--so, --soDir` | Shared object (.so) files directory |
| `-n, --nameObfuscation` | NameCache files directory |
Requirements:
- Must provide either `-i` or `-c` (not both)
- Must provide at least `-s` or `--so`
- For method name restoration, provide both `-s` and `-n`
See [references/hstack.md](references/hstack.md) for complete reference.
## Code Obfuscation (ArkGuard)
Enable in `build-profile.json5`:
```json
"arkOptions": {
"obfuscation": {
"ruleOptions": {
"enable": true,
"files": ["./obfuscation-rules.txt"]
}
}
}
```
Common rules in `obfuscation-rules.txt`:
```text
-enable-property-obfuscation # Property name obfuscation
-enable-toplevel-obfuscation # Top-level scope obfuscation
-enable-filename-obfuscation # Filename obfuscation
-keep-property-name apiKey # Whitelist specific names
```
See [references/arkguard-obfuscation.md](references/arkguard-obfuscation.md) for complete guide.
## Reference Files ## Reference Files
- **Migration Guide**: [references/migration-guide.md](references/migration-guide.md) - Complete TypeScript to ArkTS migration rules and examples - **Migration Guide**: [references/migration-guide.md](references/migration-guide.md) - Complete TypeScript to ArkTS migration rules and examples
- **Component Patterns**: [references/component-patterns.md](references/component-patterns.md) - Advanced component patterns and best practices - **Component Patterns**: [references/component-patterns.md](references/component-patterns.md) - Advanced component patterns and best practices
- **API Reference**: [references/api-reference.md](references/api-reference.md) - Common HarmonyOS APIs - **API Reference**: [references/api-reference.md](references/api-reference.md) - Common HarmonyOS APIs
- **ArkGuard Obfuscation**: [references/arkguard-obfuscation.md](references/arkguard-obfuscation.md) - Code obfuscation configuration and troubleshooting
- **Hvigor Command Line**: [references/hvigor-commandline.md](references/hvigor-commandline.md) - Complete hvigorw build tool reference
- **CodeLinter**: [references/codelinter.md](references/codelinter.md) - Code checking and fixing tool
- **Hstack**: [references/hstack.md](references/hstack.md) - Crash stack trace parser for Release builds
## Development Environment ## Development Environment

160
arkts-development/references/codelinter.md Normal file
View File

@@ -0,0 +1,160 @@
# CodeLinter 代码检查工具
codelinter 是 HarmonyOS 的代码检查与修复工具，可集成到门禁或 CI/CD 环境中。
## 命令格式
```bash
codelinter [options] [dir]
```
- `options`: 可选配置参数
- `dir`: 待检查的工程根目录（可选，默认为当前目录）
## 命令参数
| 参数 | 说明 |
|------|------|
| `--config, -c <filepath>` | 指定规则配置文件 (code-linter.json5) |
| `--fix` | 检查同时执行自动修复 |
| `--format, -f <format>` | 输出格式: `default`/`json`/`xml`/`html` |
| `--output, -o <filepath>` | 指定结果保存位置（不在命令行显示） |
| `--version, -v` | 查看版本 |
| `--product, -p <productName>` | 指定生效的 product |
| `--incremental, -i` | 仅检查 Git 增量文件（新增/修改/重命名） |
| `--help, -h` | 查询帮助 |
| `--exit-on, -e <levels>` | 指定返回非零退出码的告警级别 |
## 基本用法
### 在工程根目录下执行
```bash
# 使用默认规则检查当前工程
codelinter
# 指定规则配置文件
codelinter -c ./code-linter.json5
# 检查并自动修复
codelinter -c ./code-linter.json5 --fix
```
### 在非工程目录下执行
```bash
# 检查指定工程目录
codelinter /path/to/project
# 检查多个目录或文件
codelinter dir1 dir2 file1.ets
# 指定规则文件和工程目录
codelinter -c /path/to/code-linter.json5 /path/to/project
# 检查并修复指定工程
codelinter -c ./code-linter.json5 /path/to/project --fix
```
## 输出格式
```bash
# 默认文本格式输出到命令行
codelinter /path/to/project
# JSON 格式输出
codelinter /path/to/project -f json
# HTML 格式保存到文件
codelinter /path/to/project -f html -o ./report.html
# XML 格式保存到文件
codelinter /path/to/project -f xml -o ./report.xml
```
## 增量检查
对 Git 工程中的增量文件执行检查（仅检查新增、修改、重命名的文件）：
```bash
codelinter -i
codelinter --incremental
```
## 指定 Product
当工程存在多个 product 时，指定生效的 product：
```bash
codelinter -p free /path/to/project
codelinter --product default
```
## 退出码 (--exit-on)
用于 CI/CD 中根据告警级别控制流程。告警级别：`error`、`warn`、`suggestion`
退出码计算方式（3位二进制数，从高到低表示 error, warn, suggestion）：
| 配置 | 检查结果包含 | 二进制 | 退出码 |
|------|-------------|--------|--------|
| `--exit-on error` | error, warn, suggestion | 100 | 4 |
| `--exit-on error` | warn, suggestion | 000 | 0 |
| `--exit-on error,warn` | error, warn | 110 | 6 |
| `--exit-on error,warn,suggestion` | error | 100 | 4 |
| `--exit-on error,warn,suggestion` | error, warn, suggestion | 111 | 7 |
```bash
# 仅 error 级别返回非零退出码
codelinter --exit-on error
# error 和 warn 级别返回非零退出码
codelinter --exit-on error,warn
# 所有级别都返回非零退出码
codelinter --exit-on error,warn,suggestion
```
## CI/CD 集成示例
```bash
# 完整的 CI 检查流程
codelinter -c ./code-linter.json5 \
-f json \
-o ./codelinter-report.json \
--exit-on error,warn
# 增量检查（仅检查变更文件）
codelinter -i -c ./code-linter.json5 --exit-on error
# 检查并自动修复，生成 HTML 报告
codelinter -c ./code-linter.json5 \
--fix \
-f html \
-o ./codelinter-report.html
```
## 规则配置文件 (code-linter.json5)
默认规则清单可在检查完成后，根据命令行提示查看生成的 `code-linter.json5` 文件。
示例配置：
```json5
{
"files": [
"**/*.ets",
"**/*.ts"
],
"ignore": [
"**/node_modules/**",
"**/oh_modules/**",
"**/build/**"
],
"ruleSet": ["plugin:@ohos/recommended"],
"rules": {
"@ohos/no-any": "error",
"@ohos/no-console": "warn"
}
}
```

153
arkts-development/references/hstack.md Normal file
View File

@@ -0,0 +1,153 @@
# 堆栈解析工具 (hstack)
hstack 是用于将 Release 应用混淆后的 crash 堆栈解析为源码对应堆栈的工具，支持 Windows、Mac、Linux 三个平台。
## 命令格式
```bash
hstack [options]
```
## 命令参数
| 参数 | 说明 |
|------|------|
| `-i, --input` | 指定 crash 文件归档目录 |
| `-c, --crash` | 指定一条 crash 堆栈 |
| `-o, --output` | 指定解析结果输出目录（使用 `-c` 时指定输出文件） |
| `-s, --sourcemapDir` | 指定 sourcemap 文件归档目录 |
| `--so, --soDir` | 指定 shared object (.so) 文件归档目录 |
| `-n, --nameObfuscation` | 指定 nameCache 文件归档目录 |
| `-v, --version` | 查看版本 |
| `-h, --help` | 查询帮助 |
## 参数约束
- crash 文件目录 (`-i`) 与 crash 堆栈 (`-c`) **必须且只能提供一项**
- sourcemap (`-s`) 与 shared object (`--so`) 目录**至少提供一项**
- 如需还原混淆的方法名，需**同时提供** sourcemap 和 nameCache 文件
- 路径参数不支持特殊字符：`` `~!@#$^&*=|{};,\s\[\]<>? ``
## 环境配置
1. 将 Command Line Tools 的 `bin` 目录配置到 PATH 环境变量
2. 配置 Node.js 到环境变量
3. 解析 C++ 异常需配置 SDK 的 `native\llvm\bin` 目录到环境变量 `ADDR2LINE_PATH`
## 使用示例
### 解析 crash 文件目录
```bash
# 完整解析命令
hstack -i crashDir -o outputDir -s sourcemapDir --so soDir -n nameCacheDir
# 仅使用 sourcemap 解析 (ArkTS)
hstack -i crashDir -o outputDir -s sourcemapDir
# 仅使用 so 文件解析 (C++)
hstack -i crashDir -o outputDir --so soDir
# 包含方法名还原
hstack -i crashDir -o outputDir -s sourcemapDir -n nameCacheDir
```
### 解析单条堆栈
```bash
# 输出到控制台
hstack -c "at har (entry|har|1.0.0|src/main/ets/pages/Index.ts:58:58)" -s sourcemapDir
# 输出到文件
hstack -c "at har (entry|har|1.0.0|src/main/ets/pages/Index.ts:58:58)" -s sourcemapDir -o result.txt
```
## 输出说明
- 解析结果输出到 `-o` 指定目录，文件以原始 crash 文件名加 `_` 前缀命名
- 不指定 `-o` 时：
- 使用 `-i` 输入：输出到 crashDir 目录
- 使用 `-c` 输入：直接输出到控制台
## 文件获取
### Sourcemap 文件
构建产物中的 sourcemap 文件，包含：
- 路径信息映射
- 行列号映射 (mappings 字段)
- package-info 信息
### NameCache 文件
构建产物中的 nameCache 文件，包含：
- `IdentifierCache`: 标识符混淆映射
- `MemberMethodCache`: 成员方法混淆映射，格式为 `"源码方法名:起始行:结束行": "混淆后方法名"`
### Shared Object (.so) 文件
构建 Release 应用时，默认 so 文件不包含符号表。如需生成包含符号表的 so 文件，在模块 `build-profile.json5` 中配置：
```json5
{
"buildOption": {
"externalNativeOptions": {
"arguments": "-DCMAKE_BUILD_TYPE=RelWithDebInfo"
}
}
}
```
## 堆栈解析原理
### Crash 堆栈格式
```
at har (entry|har|1.0.0|src/main/ets/components/mainpage/MainPage.js:58:58)
at i (entry|entry|1.0.0|src/main/ets/pages/Index.ts:71:71)
```
路径格式：`引用方packageName|被引用方packageName|version|源码相对路径`
### 解析步骤
1. **根据路径信息找到 sourcemap**
- 从路径 `entry|har|1.0.0|src/main/ets/...` 在 entry 模块 sourcemap 中查找对应字段
2. **利用 sourcemap 还原路径和行列号**
- 根据 `sources` 和 `mappings` 字段解析
- 如包含 `package-info`，可进行二次解析获取更准确的源码位置
3. **利用 nameCache 还原方法名**
- 查找混淆后方法名对应的所有条目
- 根据还原后的行号范围匹配正确的源码方法名
### 解析示例
原始堆栈：
```
at i (entry|entry|1.0.0|src/main/ets/pages/Index.ts:71:71)
```
还原后：
```
at callHarFunction (entry/src/main/ets/pages/Index.ets:25:3)
```
## CI/CD 集成
```bash
# 自动化解析脚本示例
hstack \
-i ./crash-logs \
-o ./parsed-logs \
-s ./build/sourcemap \
--so ./build/libs \
-n ./build/nameCache
```
## 常见问题
1. **方法名未还原**: 确保同时提供 `-s` 和 `-n` 参数
2. **C++ 堆栈未解析**: 检查 `ADDR2LINE_PATH` 环境变量配置
3. **so 文件无符号表**: 配置 `RelWithDebInfo` 构建选项

179
arkts-development/references/hvigor-commandline.md Normal file
View File

@@ -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
```