文章简述

在 Harmony 应用开发中，ArkTS 作为默认开发语言，与 TypeScript 有诸多差异——强制静态类型、禁止动态对象布局、不支持 any/unknown、限制解构赋值……这些约束让很多从 TypeScript 迁移过来的开发者频繁踩坑。

更让人头疼的是，通用的 AI 编程助手（Claude Code、Cursor、OpenCode、Trae 等）并不了解 ArkTS 的这些特殊规则，经常生成不符合 ArkTS 规范的代码，导致编译失败。

这篇文章能帮你：

• 在 4 款主流 AI 编程工具中一键安装 ArkTS 语法助手技能
• 让 AI 真正理解 ArkTS 语法约束，生成可编译的代码
• 获得 TypeScript 迁移指导和高性能编程实践

解决方案/怎么做

核心安装命令

所有平台都推荐使用统一的一键安装命令：

npx skills add https://github.com/SummerKaze/skill-arkts-syntax-assistant.git

这条命令会自动下载并配置技能到对应工具的技能目录，无需手动操作。

---

平台一：Claude Code

安装步骤

1. 打开终端，确保已安装 Node.js（建议 v18+）
2. 执行安装命令：

npx skills add https://github.com/SummerKaze/skill-arkts-syntax-assistant.git

3. 技能会自动安装到 ~/.claude/skills/ 目录

验证安装

ls ~/.claude/skills/arkts-syntax-assistant

应能看到 SKILL.md、references/、scripts/ 等文件。

使用方式

安装后，当你在 Claude Code 中：

• 处理 .ets 文件
• 提及 ArkTS、HarmonyOS、OpenHarmony 相关问题
• 使用 @ohos 包

技能会自动激活，Claude 会参考技能中的语法规则和迁移指南来生成代码。

示例对话

Q：帮我把这段 TypeScript 代码转换为 ArkTS

// TypeScript 代码
type Person = { name: string, age: number }
let data = JSON.parse(jsonStr);
for (let key in obj) { ... }

Claude Code 会自动参考技能，给出正确的 ArkTS 写法：

// ArkTS 代码
interface Person {
  name: string;
  age: number;
}
let data: Record<string, Object> = JSON.parse(jsonStr);
for (let key of Object.keys(obj)) { ... }

---

平台二：Cursor

安装步骤

1. 在 Cursor 中打开终端（Ctrl+`` 或 Cmd+``）
2. 执行安装命令：

npx skills add https://github.com/SummerKaze/skill-arkts-syntax-assistant.git

3. 技能会自动安装到 Cursor 的技能目录

配置确认

Cursor 会在项目或用户级别的 .cursor/skills/ 目录下存储技能。你可以检查：

ls ~/.cursor/skills/arkts-syntax-assistant

使用方式

在 Cursor 的 AI 对话中（Composer 或 Chat），直接描述你的 ArkTS 开发需求：

• 「将这段 TS 代码迁移到 ArkTS」
• 「这个 ArkTS 编译错误怎么解决」
• 「ArkTS 高性能编程有什么建议」

Cursor 的 AI 会自动加载技能知识来回答。

Agent 模式增强

在 Cursor Agent 模式下，技能还支持自动编译验证：

# macOS/Linux
bash scripts/run.sh

# Windows
.\scripts\run.ps1

如果生成的代码编译失败，Agent 会自动重试修复，最多 3 次。

---

平台三：OpenCode

安装步骤

1. 打开 OpenCode 终端
2. 执行安装命令：

npx skills add https://github.com/SummerKaze/skill-arkts-syntax-assistant.git

3. 技能会安装到 OpenCode 的技能目录（通常是 ~/.config/opencode/skills/）

验证安装

ls ~/.config/opencode/skills/arkts-syntax-assistant

使用方式

OpenCode 支持技能自动触发。当检测到以下场景时，技能会自动激活：

触发场景	技能响应
编辑 .ets 文件	加载 ArkTS 语法规则
提及 HarmonyOS/OpenHarmony	加载完整技能知识
遇到编译错误	参考迁移指南修复

命令行调用

你也可以在对话中显式引用技能：

@arkts-syntax-assistant 帮我检查这段代码是否符合 ArkTS 规范

---

平台四：Trae

安装步骤

1. 在 Trae 中打开内置终端
2. 执行安装命令：

npx skills add https://github.com/SummerKaze/skill-arkts-syntax-assistant.git

3. 技能会安装到 Trae 的技能目录

配置确认

ls ~/.trae/skills/arkts-syntax-assistant

使用方式

Trae 的 AI Agent 会在以下场景自动使用技能：

• 开发 HarmonyOS 应用时
• 处理 ArkTS/ETS 文件时
• 询问 TypeScript 到 ArkTS 迁移问题时

Builder 模式

在 Trae Builder 模式下，技能提供的编译脚本特别有用：

1. AI 生成 ArkTS 代码
2. 自动执行 scripts/run.sh 编译验证
3. 编译失败则分析错误并重试
4. 3 次失败后询问用户介入

---

通用：技能文档导航

安装后，技能提供以下参考文档：

你想要	查看文档
学习 ArkTS 语法	references/zh/introduction-to-arkts.md
快速概览	references/zh/arkts-get-started.md
TS 迁移指南	references/zh/typescript-to-arkts-migration-guide.md
性能优化	references/zh/arkts-high-performance-programming.md
更多案例	references/zh/arkts-more-cases.md

---

踩坑记录

坑 1：npx 命令找不到

现象：执行 npx skills add 提示 npx: command not found

原因：Node.js 未安装或未添加到 PATH

解决：

# macOS (使用 Homebrew)
brew install node

# 或使用 nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
nvm install --lts

坑 2：技能安装到错误目录

现象：安装成功但 AI 工具未加载技能

原因：不同工具的技能目录不同

解决：手动确认技能目录并移动：

工具	默认技能目录
Claude Code	~/.claude/skills/
Cursor	~/.cursor/skills/ 或项目级 .cursor/skills/
OpenCode	~/.config/opencode/skills/
Trae	~/.trae/skills/

坑 3：AI 生成代码仍然不符合 ArkTS 规范

现象：安装技能后，AI 仍然生成 any 类型、对象字面量等不合规代码

原因：技能未被触发，或上下文不足

解决：

1. 显式提及 ArkTS 或 HarmonyOS：「用 ArkTS 写一个…」
2. 在文件开头添加 .ets 扩展名标识
3. 在对话中引用技能：「参考 arkts-syntax-assistant 技能…」

坑 4：编译脚本执行失败

现象：执行 scripts/run.sh 提示 ohpm: command not found

原因：未安装 HarmonyOS SDK 或环境变量未配置

解决：

1. 安装 DevEco Studio，它会自动安装 SDK
2. 配置环境变量：

export OHOS_SDK_HOME=/path/to/your/sdk
export PATH=$PATH:$OHOS_SDK_HOME/toolchains

---

总结

• 一条命令：npx skills add https://github.com/SummerKaze/skill-arkts-syntax-assistant.git 搞定所有平台
• 自动触发：处理 .ets 文件或提及 ArkTS/HarmonyOS 时自动激活
• 核心价值：TS 迁移指南 + 编译错误修复 + 高性能编程实践

技能让 AI 编程工具从「不懂鸿蒙」变成「精通 ArkTS」，节省大量查文档、改代码、重编译的时间。

---

互动

你在 Harmony 开发中用哪款 AI 编程工具？安装这个技能后体验如何？

遇到其他平台的安装问题，或者有技能功能建议，欢迎在评论区交流～

---