harmony-build

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 为可选的工程目录路径。未提供时使用当前工作目录。

执行步骤

1. 确定工程目录

   • 若 $ARGUMENTS 非空，使用该路径作为工程目录；否则使用当前工作目录。

2. 前置检查

   • 检查工程目录是否存在：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 路径无效，建议重新配置。

3. 安装依赖 在工程目录下运行以下命令（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 配置，并退出。

4. 同步工程 在工程目录下运行以下命令（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 行展示给用户并退出。

5. 执行编译 在工程目录下运行以下命令（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
   

6. 解析结果

   • 从输出末尾查找 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 数即为代码错误总数
   • 若某错误无法归类，归入 [构建错误]

7. 自动修复代码错误（仅当存在 [代码错误] 时执行） 直接调用 /harmony-fix <工程目录> 执行自动修复流程，无需等待用户确认。

8. 最终状态确认 harmony-fix 执行完毕后，按上述日志文件定位规则重新解析最新日志，输出最终结论：

   • BUILD SUCCESSFUL：编译通过（经过 N 轮自动修复）
   • 仍有代码错误：编译仍有 X 个代码错误未解决（初始 Y 个），完整日志：<路径>
   • 仅剩构建错误：代码错误已全部修复，但仍有 X 个构建错误需人工排查，完整日志：<路径>

9. 还原 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