| name | harmony-build |
| description | Compile a HarmonyOS project using DevEco Studio's built-in hvigor tool. Use when the user wants to build, compile, or package a HarmonyOS/ArkTS project into a HAP. Handles ohpm dependency installation, SDK patch workaround, sync, assembleHap, error classification, and auto-invokes harmony-fix for code errors. |
harmony-build
编译鸿蒙（HarmonyOS）工程，使用 DevEco Studio 内置的 hvigorw 工具执行 HAP 打包。
参数
$ARGUMENTS 为可选的工程目录路径。未提供时使用当前工作目录。
执行步骤
-
确定工程目录
- 若
$ARGUMENTS 非空，使用该路径作为工程目录；否则使用当前工作目录。
-
前置检查
- 检查工程目录是否存在：
test -d "<工程目录>"，若不存在则报错退出，提示用户确认路径。
- 检查 DevEco Studio 是否已安装：
test -f "/Applications/DevEco-Studio.app/Contents/tools/hvigor/bin/hvigorw.js"，若不存在则报错退出，提示用户安装 DevEco Studio。
- 检查
DEVECO_SDK_HOME 目录是否存在：test -d "/Applications/DevEco-Studio.app/Contents/sdk"，若不存在则报错退出，提示用户确认 SDK 路径是否正确。
- 检查工程根目录必要文件是否存在：
test -f "<工程目录>/build-profile.json5"，若不存在则报错退出，提示这不是一个有效的 HarmonyOS 工程目录。test -f "<工程目录>/local.properties"，若不存在则警告（不退出），提示用户尚未配置 SDK 路径，可能导致编译失败，建议通过 DevEco Studio 打开工程自动生成该文件。- 若
local.properties 存在，提取其中 sdk.dir 的值，检查该目录是否存在（test -d "<sdk.dir值>"），若不存在则警告，提示 SDK 路径无效，建议重新配置。
-
安装依赖
在工程目录下运行以下命令（timeout 设为 300000ms）：
cd <工程目录> && \
DEVECO_SDK_HOME=/Applications/DevEco-Studio.app/Contents/sdk \
/Applications/DevEco-Studio.app/Contents/tools/ohpm/bin/ohpm install \
--all \
--registry https://ohpm.openharmony.cn/ohpm,https://ohpm-repo.corp.kuaishou.com/repos/ohpm \
--strict_ssl true
- 若命令失败，提取输出中的 ERROR 行展示给用户，建议检查网络或 registry 配置，并退出。
-
同步工程
在工程目录下运行以下命令（timeout 设为 300000ms）：
cd <工程目录> && \
DEVECO_SDK_HOME=/Applications/DevEco-Studio.app/Contents/sdk \
/Applications/DevEco-Studio.app/Contents/tools/node/bin/node \
/Applications/DevEco-Studio.app/Contents/tools/hvigor/bin/hvigorw.js \
--sync -p product=default \
--analyze=normal --parallel --incremental --no-daemon
- 若输出含
BUILD FAILED，先执行步骤 10（还原 replace），再提取 ERROR 行展示给用户并退出。
-
执行编译
在工程目录下运行以下命令（timeout 设为 1200000ms）：
cd <工程目录> && \
DEVECO_SDK_HOME=/Applications/DevEco-Studio.app/Contents/sdk \
/Applications/DevEco-Studio.app/Contents/tools/node/bin/node \
/Applications/DevEco-Studio.app/Contents/tools/hvigor/bin/hvigorw.js \
--mode module -p product=default assembleHap \
--analyze=normal --parallel --incremental --no-daemon
-
解析结果
- 从输出末尾查找
BUILD SUCCESSFUL 或 BUILD FAILED。
- 成功：显示耗时（如
BUILD SUCCESSFUL in 59 s）。
- 失败：将错误按以下两类分别处理，并以结构化格式汇总输出：
错误分类规则：
[代码错误]：输出中包含 Error Message: ... At File: ...ets:<行>:<列> 格式的行，属于 ArkTS 编译错误，可通过修改源码修复。解析方式：
- 匹配
Error Message: (.+) At File: (.+\.ets):(\d+):(\d+) 提取消息、文件路径、行号、列号
- 对应的错误码从同一段落前面的
N ERROR: <code> <type> 行提取
[构建错误]：hvigor 错误码（如 10505001）、Script Error、Configuration Error、EPERM 等，属于构建系统或配置问题
真实错误输出示例（来自 hvigor 构建日志）：
1 ERROR: 10505001 ArkTS Compiler Error
Error Message: Property 'Black2' does not exist on type 'typeof Color'. Did you mean 'Black'? At File: /Users/.../KSSlideStoryboardFrameView.ets:18:28
COMPILE RESULT:FAIL {ERROR:2 WARN:13453}
输出规则：
- 存在代码错误时：仅输出简要汇总，不逐条列出（详细信息由 harmony-fix 在修复时逐文件展开）：
编译失败，共 N 个代码错误，涉及 M 个文件。即将自动修复...
若同时存在构建错误，附加一行：
另有 K 个构建错误（需人工排查），完整日志目录：<工程目录>/.hvigor/outputs/build-logs/
- 仅有构建错误（无代码错误）时：逐条列出构建错误供人工排查：
编译失败，共 N 个构建错误（需人工排查）：
────────────────────────────────
• 10505001 ArkTS Compiler Error: ArkTS compilation failed
完整日志目录: <工程目录>/.hvigor/outputs/build-logs/
解析细节：
- 日志目录：
<工程目录>/.hvigor/outputs/build-logs/
- 定位日志文件：取该目录下修改时间最新的文件作为主日志；若在其中未找到任何代码错误匹配行，则扫描目录下所有日志文件合并去重后再解析
- 终端输出的 ANSI 颜色码（
[31m、[39m）需去除后解析
- 文件路径统一输出绝对路径，方便其他 skill 直接定位文件
- 同一文件的多个错误合并在一起展示
COMPILE RESULT:FAIL {ERROR:N WARN:M} 中的 ERROR 数即为代码错误总数- 若某错误无法归类，归入
[构建错误]
-
自动修复代码错误（仅当存在 [代码错误] 时执行）
直接调用 /harmony-fix <工程目录> 执行自动修复流程，无需等待用户确认。
-
最终状态确认
harmony-fix 执行完毕后，按上述日志文件定位规则重新解析最新日志，输出最终结论：
BUILD SUCCESSFUL：编译通过（经过 N 轮自动修复）- 仍有代码错误：
编译仍有 X 个代码错误未解决（初始 Y 个），完整日志：<路径>
- 仅剩构建错误：
代码错误已全部修复，但仍有 X 个构建错误需人工排查，完整日志：<路径>
-
还原 SDK patch 调用
无论编译成功或失败（包括 harmony-fix 执行完毕后），都必须执行此步骤：
- 将
hvigorconfig.ts 中的 // replace(replaceFileList) // temporarily commented out for CLI build 恢复为 replace(replaceFileList)
- 若该行未被注释（步骤 4 已跳过），跳过此步骤
- 例外：若步骤 5（sync）失败提前退出，在退出前也须执行本步骤
错误处理规则
| 错误情况 | 提示内容 |
|---|
| 工程目录不存在 | 显示实际路径，提示用户检查参数或当前目录 |
| DevEco Studio 未安装 | 提示安装路径应为 /Applications/DevEco-Studio.app |
DEVECO_SDK_HOME 目录不存在 | 显示实际路径 /Applications/DevEco-Studio.app/Contents/sdk，提示用户确认 DevEco Studio 安装完整 |
build-profile.json5 不存在 | 提示这不是有效的 HarmonyOS 工程目录，请确认路径正确 |
local.properties 不存在（警告） | 提示 SDK 路径未配置，建议用 DevEco Studio 打开工程自动生成，继续尝试编译 |
local.properties 中 SDK 路径无效（警告） | 显示当前 sdk.dir 值，提示目录不存在，建议重新配置，继续尝试编译 |
| ohpm install 失败 | 提取并展示 ERROR 行，建议检查网络连接或 registry 地址是否可访问 |
| hvigorw sync 失败（BUILD FAILED） | 提取并展示 ERROR 行，建议检查 SDK 路径或工程配置 |
| 编译失败（BUILD FAILED） | 按 [代码错误] / [构建错误] 分类输出；若有代码错误，自动调用 /harmony-fix 修复并重新编译；构建错误需人工排查，给出完整日志路径 |
| 命令超时 | 提示网络或资源问题，建议重试或检查系统资源占用 |
示例
/harmony-build
/harmony-build /Users/me/projects/my-harmony-app
