背景
在 Harmony 应用开发中，ArkTS 作为默认开发语言，与 TypeScript 有诸多差异——强制静态类型、禁止动态对象布局、不支持 any/unknown、限制解构赋值……这些约束让很多从 TypeScript 迁移过来的开发者频繁踩坑。
更让人头疼的是，通用的 AI 编程助手（Claude Code、Cursor、OpenCode、Trae 等）并不了解 ArkTS 的这些特殊规则，经常生成不符合 ArkTS 规范的代码，导致编译失败。
安装与配置
核心安装命令
所有平台都推荐使用统一的一键安装命令：
npx skills add https://github.com/SummerKaze/skill-arkts-syntax-assistant.git
这条命令会自动下载并配置技能到对应工具的技能目录，无需手动操作。
平台一：Claude Code
安装步骤
- 打开终端，确保已安装 Node.js（建议 v18+）
- 执行安装命令：
npx skills add https://github.com/SummerKaze/skill-arkts-syntax-assistant.git
- 技能会自动安装到
~/.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
安装步骤
- 在 Cursor 中打开终端（
Ctrl+`` 或Cmd+``） - 执行安装命令：
npx skills add https://github.com/SummerKaze/skill-arkts-syntax-assistant.git
- 技能会自动安装到 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
安装步骤
- 打开 OpenCode 终端
- 执行安装命令：
npx skills add https://github.com/SummerKaze/skill-arkts-syntax-assistant.git
- 技能会安装到 OpenCode 的技能目录（通常是
~/.config/opencode/skills/）
验证安装
ls ~/.config/opencode/skills/arkts-syntax-assistant
使用方式
OpenCode 支持技能自动触发。当检测到以下场景时，技能会自动激活：
| 触发场景 | 技能响应 |
|---|---|
编辑 .ets 文件 | 加载 ArkTS 语法规则 |
| 提及 HarmonyOS/OpenHarmony | 加载完整技能知识 |
| 遇到编译错误 | 参考迁移指南修复 |
命令行调用
你也可以在对话中显式引用技能：
@arkts-syntax-assistant 帮我检查这段代码是否符合 ArkTS 规范
平台四：Trae
安装步骤
- 在 Trae 中打开内置终端
- 执行安装命令：
npx skills add https://github.com/SummerKaze/skill-arkts-syntax-assistant.git
- 技能会安装到 Trae 的技能目录
配置确认
ls ~/.trae/skills/arkts-syntax-assistant
使用方式
Trae 的 AI Agent 会在以下场景自动使用技能：
- 开发 HarmonyOS 应用时
- 处理 ArkTS/ETS 文件时
- 询问 TypeScript 到 ArkTS 迁移问题时
Builder 模式
在 Trae Builder 模式下，技能提供的编译脚本特别有用：
- AI 生成 ArkTS 代码
- 自动执行
scripts/run.sh编译验证 - 编译失败则分析错误并重试
- 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 类型、对象字面量等不合规代码
原因：技能未被触发，或上下文不足
解决：
- 显式提及 ArkTS 或 HarmonyOS：「用 ArkTS 写一个…」
- 在文件开头添加
.ets扩展名标识 - 在对话中引用技能：「参考 arkts-syntax-assistant 技能…」
问题 4：编译脚本执行失败
现象：执行 scripts/run.sh 提示 ohpm: command not found
原因：未安装 HarmonyOS SDK 或环境变量未配置
解决：
- 安装 DevEco Studio，它会自动安装 SDK
- 配置环境变量：
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」，节省大量查文档、改代码、重编译的时间。
