<div align="center">

English | 简体中文

<img src="./assets/hero-banner.svg" alt="HarmonyOS AI Skill" width="100%"/>

🧠 HarmonyOS AI Skill

鸿蒙最大的 AI 编程知识库 · 让 11+ AI 工具真正会写 ArkTS

4461 行实战知识 · 243 个章节 · 105+ 代码示例 · 生产覆盖 API 24，跟踪 HarmonyOS 7 / API 26 Beta1

<br/>

问 Cursor 怎么写 ArkUI，它给你输出 React 组件？ 让 Claude 改 module.json5，它当 package.json 改？ 问 Copilot @ObjectLink 怎么用，它说"这 API 不存在"？

通用大模型从来没系统学过鸿蒙——它们的训练数据里几乎没有 ArkTS、Stage 模型、HarmonyOS Kit。 所以我把华为官方文档、最佳实践、API 参考浓缩成一份4461 行、可直接喂进 LLM 上下文的知识包，从 ArkTS 严格语法到 60+ Kit、从液态玻璃到 AI super frame、从应用接续到 PersistenceV2，全都覆盖。

一份 Markdown 源文件，自动产出 11+ AI 工具的配置。 装上之后，AI 会像读过华为文档的工程师一样，给你符合鸿蒙规范的代码——而不是把 @State 写成 useState。

<br/>

🚀 安装 · 📖 知识内容 · 🛠️ 支持的工具 · ✅ 验证效果

</div>

---

<div align="center"> <img src="./assets/before-after.svg" alt="装前 vs 装后对比" width="100%"/> </div>

---

⚡ 快速开始（Claude Code，30 秒）

按你的系统选择对应命令——直接复制粘贴到终端即可：

🍎 macOS

git clone https://github.com/DengShiyingA/harmonyos-ai-skill.git ~/src/harmonyos-ai-skill
mkdir -p ~/.claude/skills
ln -s ~/src/harmonyos-ai-skill/harmonyos-development ~/.claude/skills/harmonyos-development
# 重启 Claude Code，然后问："What skills are available?"

🐧 Linux

git clone https://github.com/DengShiyingA/harmonyos-ai-skill.git ~/src/harmonyos-ai-skill
mkdir -p ~/.claude/skills
ln -s ~/src/harmonyos-ai-skill/harmonyos-development ~/.claude/skills/harmonyos-development
# 重启 Claude Code，然后问："What skills are available?"

🪟 Windows（PowerShell 7+）

⚠️ 必须在 PowerShell 中运行，不要用 CMD（命令提示符）——New-Item 是 PowerShell 命令，CMD 不认识。右键开始菜单 → "Windows PowerShell（管理员）"。

# 先开启「开发人员模式」：设置 → 隐私和安全性 → 开发者选项 → 打开（一次性）
git clone https://github.com/DengShiyingA/harmonyos-ai-skill.git $HOME\src\harmonyos-ai-skill
New-Item -ItemType Directory -Force $HOME\.claude\skills | Out-Null
New-Item -ItemType SymbolicLink -Path $HOME\.claude\skills\harmonyos-development -Target $HOME\src\harmonyos-ai-skill\harmonyos-development
# 重启 Claude Code，然后问："What skills are available?"

不想开发者模式？把 New-Item -ItemType SymbolicLink ... 换成 Copy-Item -Recurse $HOME\src\harmonyos-ai-skill\harmonyos-development $HOME\.claude\skills\ 即可（但上游更新后需要重新复制）。

用其他工具（Cursor / Copilot / ChatGPT ...）？查看下方完整安装指南。

---

为什么需要这个？

| 问题 | 普通 AI | 装上 Skill 后 | |---|---|---| | 用什么写 UI？ | "用 React Native 啊" | "用 ArkUI，@Component struct 声明式组件" | | 状态怎么管？ | "useState / Redux" | "@State / @ObjectLink，新项目用 V2 装饰器（API 23 已稳定）" | | 路由跳转？ | "react-router 或 Vue Router" | "Navigation + NavPathStack.pushPath()，Router 已被淘汰" | | HTTP 请求？ | "axios / fetch" | "@kit.NetworkKit 的 http.createHttp()，或 @ohos/axios 三方库" | | 申请相机权限？ | 给一段 Android Manifest | module.json5 配置 + abilityAccessCtrl 三步流程（含 settings 降级） | | 后台播放音乐？ | 模糊提示需要 service | "必须创建 AVSession + 申请 KEEP_BACKGROUND_RUNNING 长时任务" |

知识不在 AI 脑子里，得喂进去。这就是这个仓库做的事。

只维护一份知识源文件 harmonyos-development/SKILL.md，即可自动产出所有 AI 工具的配置文件。

<details> <summary><b>🤔 什么是 "skill"（技能包）？</b>（点击展开）</summary>

Skill 是一段领域知识（Markdown 格式），AI 编程工具会在对话时自动加载为背景上下文。安装后，AI 就"知道"了这个领域——它会给出符合 HarmonyOS 规范的回答，而不是泛泛的 TypeScript / React 建议。不同工具叫法不同（skills、rules、instructions、system prompt），但原理一样：额外文本被插入到模型的上下文中。

</details>

依赖： 只需 git 和 curl（或直接复制粘贴）。无其他依赖。 保鲜度： 跟随官方版本节奏更新。生产基线覆盖到 HarmonyOS 6.1.1 Release (API 24)（2026/05/26），并跟踪 HarmonyOS 7 / 26.0.0 Beta1（API 26，2026/06/12）预览能力。

知识包内容

<div align="center"> <img src="./assets/knowledge-map.svg" alt="知识架构图" width="100%"/> </div>

这份知识包教会 AI 读写、审查和调试 HarmonyOS NEXT 原生应用所需的一切（4461 行密集、可操作的知识，243 个章节，105+ 代码示例）：

• 语言与框架 — ArkTS 严格模式规则、命名规范、13 条高性能编码规则（const、TypedArray、HashMap、lazy import 等）、编码风格指南
• 应用架构 — Stage 模型：UIAbility、ExtensionAbility、AbilityStage、WindowStage 生命周期；module.json5 / app.json5 配置
• ArkUI 组件 — 组件生命周期（7 个回调 + 执行顺序）、布局容器（Column/Row/Stack/Flex/RelativeContainer/List）性能对比、@Reusable 组件复用、Tabs 底部导航、Swiper 轮播、WaterFlow 瀑布流、Grid 网格、TextInput 输入框、AlertDialog/Toast、10 种表单组件速查、AttributeModifier 可复用样式
• 状态管理（V2 已稳定） — V1 装饰器（@State/@Prop/@Link/@Provide-@Consume/@Observed+@ObjectLink/@Watch）+ V2 装饰器（@ComponentV2/@Local/@Param+@Once/@Param+@Event/@ObservedV2+@Trace/@Monitor）+ AppStorageV2 + PersistenceV2（自动持久化）+ StateStore 全局状态，含观察深度规则、批量更新、装饰器选择优先级
• 导航路由 — Navigation + NavPathStack 完整 API、Router 基础路由（已弃用，含迁移说明）、App Linking 深链接
• 动画 — animateTo()、.animation()、keyframeAnimateTo()、Curve 枚举、弹簧曲线、geometryTransition 共享元素转场、动画性能提示
• 列表操作 — 下拉刷新（Refresh）、上拉加载（onReachEnd）、左滑删除（swipeAction）、拖拽排序、ListItemGroup 分组粘性头、滚动到底部、保持滚动位置
• 性能优化 — LazyForEach + IDataSource、@Reusable、cachedCount、onVisibleAreaChange、冷启动优化（lazy import）、内存优化（LRUCache/Purgeable）
• HarmonyOS Kits — 7 大类 60+ Kit 含 import key + 代码示例
• Kit 详细章节 — Camera Kit（含 API 24 Follow the Person 主体追踪）、Audio Kit、AVPlayer/AVRecorder、Image Kit（decode/transform/encode）、Scan Kit、Account Kit、Payment Kit、Push Kit、Map Kit、Weather Service Kit、Core Vision Kit（OCR/人脸/抠图）、Form Kit（服务卡片）、AVSession Kit、Location Kit、Notification Kit、Share Kit
• 数据持久化 — relationalStore（SQLite CRUD + sendable）、preferences（KV 存储）、fileIo（文件读写）、DocumentViewPicker（文件选择器）
• 网络 — HTTP 请求、WebSocket、网络状态监听、后台上传下载（request.agent 断点续传）
• 并发 — TaskPool vs Worker 对比、@Concurrent 规则、@Sendable 共享堆机制
• 系统能力 — 权限申请完整流程（check→request→settings 降级）、沉浸式窗口（expandSafeArea/避让区）、深色模式（资源限定词/colorMode 监听）、软键盘适配（KeyboardAvoidMode）、横竖屏切换、剪贴板、自定义字体、桌面快捷方式、手势冲突处理（hitTestBehavior/priorityGesture）、EventHub 事件通信、startAbilityByType
• Web — ArkWeb 组件、JS↔ArkTS 桥接、Cookie 管理、请求拦截
• 跨设备 — 应用接续（onContinue/onCreate 数据迁移）、跨模块资源访问（HAR/HSP）
• 工程质量 — 安全编码规则 + 网络安全配置（HTTPS/证书固定）、代码混淆（ArkGuard）、arkxtest 测试框架（JsUnit + UiTest）、18 条常见陷阱（gotchas）
• 三方库 — @ohos/axios（HTTP 客户端）、@ohos/pulltorefresh（下拉刷新）、@ohos/lottie（JSON 动画）、@ohos/imageknife（图片缓存）、dayjs（日期处理）
• API 23 / 24 新特性 — Navigation 路由栈绑定、Menu anchorPosition、UDMF/drag/crypto C API、relationalStore sendable 增强、AI super frame、Camera Kit "Follow the Person" 主体追踪、延迟预览、DevEco Studio API 24 支持
• 最新兼容与调测 — Native APIAVAILABLE/弱引用、Linux CI、jsLeakWatcher、HWASan、ContainerReader 容器断点、全局组件复用
• 多设备 — 响应式断点（xs/sm/md/lg/xl）、GridRow/GridCol、折叠屏适配
• 打包与工具 — HAP/HSP/HAR、原子化服务、DevEco Studio 6.1+（hvigor）、OHPM、ArkCompiler

---

支持的 AI 工具

1. 原生 skill 格式（按描述自动匹配加载）

| 工具 | 安装路径 | 激活方式 | |---|---|---| | Claude Code CLI | ~/.claude/skills/harmonyos-development/ | Claude 读取 SKILL.md frontmatter 中的 description，当你的问题涉及 HarmonyOS / ArkTS / ArkUI / Stage 模型等时自动加载，无需手动调用 | | Claude Agent SDK | 将 harmonyos-development/ 放在任意位置，通过 SDK 的 skills 参数指定 | 同 Claude Code —— 基于描述自动加载 |

2. 项目规则文件（项目内每次会话自动附加）

| 工具 | 安装路径 | 源文件 | 作用域 | |---|---|---|---| | Cursor（现代版） | .cursor/rules/harmonyos.mdc | dist/cursor/harmonyos.mdc | 按 glob 匹配 *.ets、module.json5、oh-package.json5、build-profile.json5 | | Cursor（旧版） | .cursorrules（仓库根目录） | dist/cursor/.cursorrules | 始终生效 | | GitHub Copilot | .github/copilot-instructions.md | dist/copilot/copilot-instructions.md | 仓库内始终生效 | | Windsurf / Codeium | .windsurfrules（仓库根目录） | dist/windsurf/.windsurfrules | 始终生效 | | Continue.dev | .continue/rules/harmonyos.md | dist/continue/harmonyos.md | 始终生效 | | Cline / Roo Code | Settings → Custom Instructions | dist/cline/custom-instructions.md | 按工作区或全局 | | OpenAI Codex CLI · sst/opencode · Amp · Aider · Jules | AGENTS.md（仓库根目录） | dist/agents-md/AGENTS.md | 遵循 AGENTS.md 标准 | | Google Gemini CLI | GEMINI.md（仓库根目录）或 ~/.gemini/GEMINI.md（全局） | dist/gemini-cli/GEMINI.md | Gemini CLI 读取任一路径 |

3. 通用 —— 粘贴到任何聊天 / API

| 工具 | 粘贴位置 | 源文件 | |---|---|---| | ChatGPT / GPT-4 / GPT-5 | Settings → Personalization → Custom Instructions（或单次对话 system prompt） | dist/plain/harmonyos-knowledge.md | | Google Gemini / AI Studio | System Instructions 字段 | dist/plain/harmonyos-knowledge.md | | DeepSeek / Qwen / 文心一言 / Kimi / 智谱 | 系统提示 / 角色设定字段 | dist/plain/harmonyos-knowledge.md | | Ollama 本地模型 | --system 参数 | dist/system-prompt/system.txt | | Anthropic / OpenAI / 任意 LLM API | 请求体的 system 消息 | dist/system-prompt/system.txt |

两个文件区别很小：plain/ 是原始 Markdown；system-prompt/ 在前面加了一句角色定位（"You are an expert HarmonyOS NEXT developer…"）。

---

安装

下方所有 curl 命令都使用环境变量 $RAW —— 每个新终端首次使用前都需要先运行一次：

export RAW=https://raw.githubusercontent.com/DengShiyingA/harmonyos-ai-skill/main

Windows PowerShell 用户： 用 $env:RAW = "..."，并把下方 curl -o foo 改为 Invoke-WebRequest -Uri "..." -OutFile foo。 HOME 路径差异： macOS/Linux 是 ~；Windows PowerShell 是 $HOME；CMD 是 %USERPROFILE%。

Claude Code CLI

选择以下三种方式之一：

# 方式 A — 直接复制（最简单，获得静态快照）
git clone https://github.com/DengShiyingA/harmonyos-ai-skill.git ~/src/harmonyos-ai-skill
mkdir -p ~/.claude/skills
cp -r ~/src/harmonyos-ai-skill/harmonyos-development ~/.claude/skills/

# 方式 B — 符号链接（推荐：上游 git pull 后自动同步）
git clone https://github.com/DengShiyingA/harmonyos-ai-skill.git ~/src/harmonyos-ai-skill
mkdir -p ~/.claude/skills
ln -s ~/src/harmonyos-ai-skill/harmonyos-development ~/.claude/skills/harmonyos-development

# 方式 C — 仅项目级别（提交到你的鸿蒙项目，团队成员开箱即用）
cd <你的鸿蒙项目根目录>
mkdir -p .claude/skills/harmonyos-development
curl -o .claude/skills/harmonyos-development/SKILL.md "$RAW/harmonyos-development/SKILL.md"

安装后重启 Claude Code。验证方法：问 "What skills are available?" —— 应该列出 harmonyos-development。

Cursor

执行位置： 你的鸿蒙项目根目录（含 entry/、module.json5 那个）

# 推荐 —— 现代 .mdc 规则，按文件类型激活
mkdir -p .cursor/rules
curl -o .cursor/rules/harmonyos.mdc "$RAW/dist/cursor/harmonyos.mdc"

# 或：旧版单文件规则（Cursor 不支持 .mdc 时使用）
curl -o .cursorrules "$RAW/dist/cursor/.cursorrules"

.mdc 规则仅在编辑 .ets、module.json5 等文件时自动激活，非鸿蒙项目不会占用上下文。

GitHub Copilot

执行位置： 你的鸿蒙项目根目录

mkdir -p .github
curl -o .github/copilot-instructions.md "$RAW/dist/copilot/copilot-instructions.md"

在仓库内对 Copilot Chat 和内联建议始终生效。提交后团队共享。

Windsurf / Codeium

执行位置： 你的鸿蒙项目根目录

curl -o .windsurfrules "$RAW/dist/windsurf/.windsurfrules"

Continue.dev

执行位置： 你的鸿蒙项目根目录

mkdir -p .continue/rules
curl -o .continue/rules/harmonyos.md "$RAW/dist/continue/harmonyos.md"

Cline / Roo Code

1. 下载文件：curl -o harmonyos-instructions.md "$RAW/dist/cline/custom-instructions.md"
2. 在 VS Code 中打开 Cline / Roo 设置 → Custom Instructions
3. 将文件内容粘贴到工作区或全局 Instructions 字段

AGENTS.md standard (Codex CLI, opencode, Amp, Aider, Jules)

一个文件即可服务所有遵循 AGENTS.md 标准 的工具：

curl -o AGENTS.md "$RAW/dist/agents-md/AGENTS.md"

用户级（全局）作用域，各工具读取不同路径：

| 工具 | 全局路径 | |---|---| | OpenAI Codex CLI | ~/.codex/AGENTS.md | | sst/opencode | `~/.config/opencode/AGE