| name | harmony-fix |
| description | Fix ArkTS compilation errors in a HarmonyOS project. Reads errors from the latest build log, groups them by file, fixes each file in one pass, and re-compiles to verify. Repeats until no progress is made or all errors are resolved. Designed for fully automated use with large error volumes. |
harmony-fix
读取 HarmonyOS 工程最近一次编译日志中的代码错误，按文件聚合后逐文件修复，重新编译验证，持续循环直到无进展为止。全程不需要人工确认。
参数
$ARGUMENTS 为可选的工程目录路径。未提供时使用当前工作目录。
执行步骤
1. 确定工程目录
若 $ARGUMENTS 非空，使用该路径；否则使用当前工作目录。
2. 解析编译错误
日志目录：<工程目录>/.hvigor/outputs/build-logs/
定位日志文件：
- 取该目录下修改时间最新的文件作为主日志
- 若在其中未找到任何
Error Message: ... At File: ...ets 匹配行，则扫描目录下所有日志文件合并去重后再解析
- 若日志目录不存在，则触发一次编译（命令同步骤 4，timeout 1200000ms），直接从编译的终端输出（stdout + stderr）中提取错误；若编译输出中也无代码错误，告知用户无可修复的代码错误并退出
解析方式：
- 去除 ANSI 颜色码（
\x1b\[[0-9;]*m）
- 匹配
Error Message: (.+) At File: (.+\.ets):(\d+):(\d+) 提取所有代码错误
- 若无匹配行，告知用户无可修复的代码错误并退出
- 输出本轮错误汇总：
第 N 轮开始，共 X 个代码错误，涉及 Y 个文件
3. 按文件聚合修复
将所有错误按文件路径分组，对每个文件执行一次完整修复：
3.1 读取文件
- 读取出错文件的完整内容（非仅报错行附近）
- 列出该文件的所有待修复错误（行号 + 错误信息）
3.2 分析错误并确定修复方案
以编译器报错信息为主要输入，结合文件内容按以下优先级依次判断修复方式：
第一步：直接判断
- 报错信息已明确指出修复方向（如
Did you mean 'Black'?、Expected N arguments）→ 直接修复，无需查文档
第二步：查阅本地参考文档
- 报错信息不足以判断正确写法时，按下表查阅对应参考文档：
| 文档 | 路径（相对 ~/.jarvis/skills/） | 适用情况 |
|---|
| 错误码文档 | harmony-fix/references/errcode/ | 有明确错误码（如 10905301）时首选；含「错误描述」「可能原因」「处理步骤」 |
| ArkTS 语言介绍 | harmony-fix/references/learning-arkts/ArkTS语言介绍.md | ArkTS 语法约束违反、TypeScript 写法在 ArkTS 中不合法 |
| ArkTS 编程规范 | harmony-fix/references/learning-arkts/ArkTS编程规范.md | 装饰器用法错误、代码模式不合规 |
| API 参考文档 | harmony-fix/references/harmonyos_references/ | 需确认正确的属性名、方法签名、参数类型 |
查文档的方式：
- 有错误码：用 Grep 在
harmony-fix/references/errcode/ 中搜索错误码数字
- 需确认 API：用 Grep 在
harmony-fix/references/harmonyos_references/ 中搜索类型名或方法名
- 语法或装饰器问题：Read
harmony-fix/references/learning-arkts/ArkTS语言介绍.md 或 ArkTS编程规范.md 查阅对应章节
- 同一文件内相同错误码或相同类型名只查一次
第三步：网络搜索（兜底）
- 经过前两步仍无法确定修复方案时，使用 WebSearch 搜索该错误
- 搜索关键词：以报错信息的核心内容 +
ArkTS 或 HarmonyOS 为关键词，例如：ArkTS "arkts-no-any-unknown" fix、HarmonyOS <错误码> solution
- 根据搜索结果中的解释和示例确定修复方案后再执行修复
第四步：基于模型知识尝试修复（最终兜底）
- 经过前三步均无法确定明确修复方案时，结合报错信息、文件上下文以及模型自身对 ArkTS/TypeScript 语法和 HarmonyOS API 的知识，推断最可能的修复方式并尝试修复
- 此步骤允许修复不完全精确，后续编译轮次会验证并继续修正
3.3 一次性修复该文件的全部错误
- 综合文件完整内容 + 编译器报错信息 + 必要时查阅的参考文档或网络搜索结果，在一次编辑中修复该文件的所有错误
- 仅修改最小必要范围，不做重构或无关改动
- 输出修改说明（文件路径、涉及行号、改了什么）
对所有涉及错误的文件依次执行上述步骤。
4. 重新编译
所有文件修复完成后重新编译（timeout 1200000ms）。
注意：此编译命令须与 harmony-build 步骤 6 保持一致，修改时需同步更新。
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
5. 判断是否继续
重新按上述日志文件定位规则解析最新日志，统计当前代码错误数 current，与本轮开始前的错误数 previous 比较：
| 情况 | 动作 |
|---|
BUILD SUCCESSFUL | 输出成功耗时和轮次汇总，结束 |
current < previous（有进展） | 输出本轮进展（X → Y 个错误，减少 Z 个），返回步骤 2 开始下一轮 |
current >= previous（无进展） | 停止循环，进入步骤 6 |
| 只剩构建错误（无代码错误） | 告知用户构建错误需人工排查，输出完整日志路径，结束 |
6. 无进展时的收尾输出
当错误数不再减少时，输出以下信息供人工排查：
自动修复已无法继续推进（错误数未减少）。
修复汇总：
初始错误数：X
当前剩余：Y（经过 N 轮）
剩余代码错误：
文件: <路径>
• 第 L 行，第 C 列 | <错误信息>
...
完整日志目录：<工程目录>/.hvigor/outputs/build-logs/
注意事项
- 只处理代码错误（
Error Message: ... At File: ...ets），不处理 EPERM、配置类等构建系统错误
- 全程不询问用户，自动推进所有修复轮次
- 每轮开始前输出轮次和错误数，每轮结束后输出本轮改动汇总，保持进度可见
- 同一文件内的多个错误在一次编辑中处理完，避免行号因多次编辑产生偏移
适用场景
主要用于大模块自动转码后的编译修复流程：将一个大型模块从其他语言/框架批量转换为 ArkTS 代码后，转码产物往往存在大量编译错误（数十至数百个），需要在无人值守的情况下自动完成修复并验证编译通过。
此 skill 针对该场景做了专项设计：全程不需要人工确认、按文件聚合处理避免行号漂移、以"有进展则继续"作为循环终止条件以应对错误数量多且相互关联的情况。
示例
/harmony-fix
/harmony-fix /Users/me/projects/my-harmony-app
