메뉴
检查并修复 HarmonyOS 项目的 ArkTS 语法错误，自动化构建项目。当需要编译项目、修复编译错误、生成 HAP/App 产物时使用。提供静态语法检查、错误自动修复、循环构建直到成功的完整工作流程。支持错误优先级分类（P0/P1/P2）、最大重试机制、构建产物自动定位。
Codex 또는 Claude로 설치 이 Prompt를 복사해 Codex, Claude 또는 다른 어시스턴트에 붙여 넣으면 Skill 페이지를 검토하고 설치를 진행할 수 있습니다.
SOC 직업 분류 기준
**MUST** use 'devecocli' for HarmonyOS apps (scaffold, build, run, debug, devices, emulators, logs, docs, 鸿蒙开发文档, skills). **REQUIRED** and **MANDATORY** if workspace has build-profile.json5 or oh-package.json5, or user mentions HarmonyOS, 鸿蒙, DevEco, ArkTS, ArkUI, docs, 鸿蒙文档, 知识, 搜索, or skills.
检查 HarmonyOS 项目中的废弃 SDK 接口并提供修复建议。当需要清理废弃 API、升级 API 版本、优化代码质量或进行静态语法检查时使用。提供详细的迁移方案、修复优先级分类和代码示例。
检索 ArkTS 语言指南文档，为代码开发、审查和调试提供语法参考。当需要查找 ArkTS 语法规则、库使用方法或代码示例时使用。提供基于索引的高效检索和可追溯的文档引用。
编写、审查或改进ArkUI代码，遵循状态管理(V1/V2)、组件结构、布局选择、性能优化的最佳实践。触发场景：构建新页面或组件、实现状态管理、开发布局(列表/网格/瀑布流)、添加动画手势、搭建导航路由、处理弹窗模态、MVVM架构设计、V1迁移V2。
帮助开发者将ArkUI状态管理从V1迁移到V2。触发场景：(1) V1项目升级到V2；(2) 迁移@Component/@State/@Prop/@Link/@Observed/@ObjectLink/@Provide/@Consume/@Watch/@Reusable装饰器；(3) 迁移LocalStorage/AppStorage/PersistentStorage/Environment应用级状态；(4) 将ForEach/LazyForEach迁移到Repeat；(5) 解决animateTo在V2中的兼容问题；(6) 处理V1与V2混用场景；(7) 询问V1和V2装饰器对应关系或差异。
Handle HarmonyOS avoid-area adaptation through a declarative scene and resource index. Use when the task involves safe area expansion, status bar or navigation bar avoidance, notch or cutout handling, immersive full-screen layouts, or soft keyboard overlap handling.
| name | hmos-arkts-syntax-checker |
| description | 检查并修复 HarmonyOS 项目的 ArkTS 语法错误，自动化构建项目。当需要编译项目、修复编译错误、生成 HAP/App 产物时使用。提供静态语法检查、错误自动修复、循环构建直到成功的完整工作流程。支持错误优先级分类（P0/P1/P2）、最大重试机制、构建产物自动定位。 |
本技能专门用于自动化构建 HarmonyOS 项目，通过静态语法检查、错误修复和循环构建的流程，确保项目能够成功编译并生成产物。
开始
│
├─→ 步骤0: 检查MCP工具依赖
│ ├─→ MCP工具可用 → 继续执行
│ └─→ MCP工具不可用 → 提示安装 → 终止
│
├─→ 步骤1: 扫描项目源文件
│ └─→ 获取所有 .ets 文件列表
│
├─→ 步骤2: 静态语法检查
│ └─→ mcp_codegenie-mcp_check_ets_files
│
├─→ 步骤3: 分析诊断结果
│ ├─→ 有错误 → 步骤4: 修复错误
│ └─→ 无错误 → 步骤5: 构建项目
│
├─→ 步骤4: 修复错误
│ ├─→ 应用修复方案
│ └─→ 返回步骤2（重新检查）
│
├─→ 步骤5: 构建项目
│ └─→ mcp_codegenie-mcp_build_project
│
├─→ 步骤6: 检查构建结果
│ ├─→ 构建失败 → 分析错误 → 步骤4
│ └─→ 构建成功 → 步骤7
│
└─→ 步骤7: 输出构建产物
└─→ 完成
⚠️ 重要提示：本技能依赖MCP工具
在执行任何构建操作之前，必须先检查MCP工具是否可用：
依赖的MCP工具：
mcp_codegenie-mcp_check_ets_files - ETS文件静态语法检查mcp_codegenie-mcp_build_project - 项目构建mcp_codegenie-mcp_harmonyos_knowledge_search - HarmonyOS知识搜索（可选）检查方法：
尝试调用 mcp_codegenie-mcp_check_ets_files 或 mcp_codegenie-mcp_build_project
如果工具不可用，会收到错误提示
如果MCP工具未安装：
❌ MCP工具未安装或不可用
本技能需要依赖 CodeGenie MCP Server 工具才能正常工作。
📦 安装方式：
在 MCP 配置文件中添加以下配置：
{
"mcpServers": {
"codegenie-mcp": {
"command": "npx",
"args": [
"-y",
"@deveco-codegenie/mcp@beta",
"--registry=https://registry.npmjs.org"
],
"env": {
"PROJECT_PATH": "${workspaceFolder}",
"DEVECO_PATH": "path to deveco studio"
}
}
}
}
📚 详细文档：
- GitHub: https://github.com/open-deveco/deveco-toolbox
- 飞书指导文档: https://my.feishu.cn/wiki/open-deveco/deveco-toolbox
💡 安装完成后，请重新使用本技能。
验证成功后继续执行后续步骤。
首先分析项目结构和配置：
关键配置文件：
build-profile.json5 - 项目级构建配置entry/build-profile.json5 - 模块级构建配置module.json5 - 模块配置oh-package.json5 - 依赖配置使用 Glob 工具搜索项目中的 ETS 文件：
# 搜索所有 .ets 文件
**/*.ets
# 排除目录
- oh_modules/
- build/
- .preview/
调用 MCP 工具进行 ArkTS 静态语法检查：
mcp_codegenie-mcp_check_ets_files
参数: files - ETS 文件路径列表
诊断信息类型：
| 错误码 | 类型 | 说明 | 优先级 |
|---|---|---|---|
| 28007 | Warning | 权限警告 | P2 |
| 6133 | Warning | 未使用的变量/符号 | P2 |
| 6387 | Information | 使用了废弃的 API | P1 |
| addTryCatch | Warning | 需要异常处理 | P2 |
| addAsyncCatch | Warning | 异步函数需要异常处理 | P2 |
| 其他 | Error | 语法错误/类型错误 | P0 |
根据错误类型采取不同的修复策略：
P0 - 必须修复（阻止编译）：
P1 - 强烈建议修复：
P2 - 可选优化：
详细修复示例: 参考 error-fixing-examples.md
使用 MCP 工具构建项目：
mcp_codegenie-mcp_build_project
参数:
- buildTarget: "hap" 或 "app"
- buildMode: "debug" 或 "release"
- product: "default" (可选)
- module: "entry@default" (可选)
构建目标选择：
hap - 生成单个 HAP 包（用于测试/调试）app - 生成 APP 包（用于发布）如果构建失败，分析错误信息：
常见构建错误：
Error: Cannot find module '@ohos/xxx' → 安装依赖Error: Resource not found → 检查资源文件Error: Signing failed → 检查签名配置Error: ArkTS compiler error → 返回步骤2重新检查构建成功后，产物位置：
项目根目录/
├── entry/build/default/outputs/default/entry-default-signed.hap
└── build/outputs/default/{project-name}-default-signed.app
输出示例: 参考 output-examples.md
开始构建流程
│
├─ MCP工具可用？
│ ├─ 否 → 提示安装MCP工具 → 终止
│ └─ 是 → 继续
│
├─ 静态检查结果？
│ ├─ 有错误 → 错误类型？
│ │ ├─ P0 语法错误 → 必须修复 → 重新检查
│ │ ├─ P1 废弃 API → 建议修复 → 重新检查
│ │ └─ P2 代码质量 → 可选修复 → 继续构建
│ │
│ └─ 无错误 → 执行构建
│
├─ 构建结果？
│ ├─ 成功 → 输出产物路径 → 完成
│ │
│ └─ 失败 → 错误类型？
│ ├─ 依赖问题 → 安装依赖 → 重新构建
│ ├─ 签名问题 → 提示手动修复 → 终止
│ ├─ 资源问题 → 检查资源文件 → 重新构建
│ └─ 编译错误 → 返回静态检查
│
└─ 重试次数 > 5？
├─ 是 → 终止，输出失败报告
└─ 否 → 继续循环
为避免无限循环，设置最大重试次数：
const MAX_RETRY_COUNT = 5;
let retryCount = 0;
while (retryCount < MAX_RETRY_COUNT) {
// 1. 静态检查
const diagnostics = await checkEtsFiles(files);
// 2. 分析错误
const errors = filterErrors(diagnostics);
if (errors.length === 0) {
// 3. 构建项目
const buildResult = await buildProject();
if (buildResult.success) {
return { success: true, output: buildResult.output };
}
} else {
// 4. 修复错误
await fixErrors(errors);
}
retryCount++;
}
return { success: false, error: 'Max retry count exceeded' };
每次循环按以下优先级修复：
某些错误可以跳过：
| 工具名称 | 用途 | 必需参数 |
|---|---|---|
mcp_codegenie-mcp_check_ets_files | ETS 文件静态语法检查 | files: string[] |
mcp_codegenie-mcp_build_project | 构建项目 | buildTarget: "hap"|"app" |
mcp_codegenie-mcp_harmonyos_knowledge_search | 搜索 HarmonyOS 开发文档 | keywords: string[] |
| 工具名称 | 用途 |
|---|---|
Glob | 搜索文件 |
Read | 读取文件内容 |
Write | 写入文件内容 |
SearchReplace | 编辑文件 |