English | 简体中文

🧠 HarmonyOS AI Skill

鸿蒙开发知识包 · 让 11+ AI 编程工具真正"懂"鸿蒙

"让 AI 像熟读华为文档的工程师一样，帮你写 ArkTS / ArkUI"

用 Cursor 写鸿蒙，AI 给你输出 React？ 让 Claude 改 module.json5，它写成 package.json？ 问 Copilot @ObjectLink 咋用，它说"这 API 不存在"？

问题不在 AI —— 在于没人给它喂过鸿蒙知识。

所以我喂了。一份 Markdown 源文件，自动产出 11+ AI 工具的配置。

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

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?"

用其他工具？查看下方完整安装指南。

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

依赖： 只需 git 和 curl（或直接复制粘贴）。无其他依赖。

这份知识包教会 AI 读写、审查和调试 HarmonyOS NEXT 原生应用所需的一切（约 4200 行密集、可操作的知识，237 个章节，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 可复用样式
• 状态管理 — V1 装饰器（@State、@Prop、@Link、@Provide/@Consume、@Observed + @ObjectLink、@Watch）+ V2 装饰器（@ComponentV2、@Local、@ObservedV2 + @Trace、@Monitor）+ 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、Audio Kit、AVPlayer/AVRecorder、Image Kit（decode/transform/encode）、Scan Kit、Account Kit、Payment Kit、Push Kit、Map Kit、Core Vision Kit（OCR/人脸/抠图）、Form Kit（服务卡片）、AVSession Kit、Location Kit、Notification Kit、Share Kit
• 数据持久化 — relationalStore（SQLite CRUD）、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（日期处理）
• 多设备 — 响应式断点（xs/sm/md/lg/xl）、GridRow/GridCol、折叠屏适配
• 打包与工具 — HAP/HSP/HAR、原子化服务、DevEco Studio 6.x（hvigor）、OHPM、ArkCompiler

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

下方所有 curl 命令都使用环境变量 $RAW —— 先在终端运行一次（在当前 session 中持续有效）：

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

选择以下三种方式之一：

# 方式 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
cp -r ~/src/harmonyos-ai-skill/harmonyos-development .claude/skills/

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

# Recommended — modern glob-scoped .mdc rule
mkdir -p .cursor/rules
curl -o .cursor/rules/harmonyos.mdc "$RAW/dist/cursor/harmonyos.mdc"

# OR legacy single-file rules (if your Cursor version predates .mdc)
curl -o .cursorrules "$RAW/dist/cursor/.cursorrules"

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

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

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

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

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

1. Download the file: curl -o harmonyos-instructions.md "$RAW/dist/cline/custom-instructions.md"
2. In VS Code: open Cline / Roo settings → Custom Instructions
3. Paste the file contents into the workspace or global instructions field

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

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

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

部分工具支持多层 AGENTS.md（最近的优先 / 合并），详见各工具文档。

# Project-level (takes precedence):
curl -o GEMINI.md "$RAW/dist/gemini-cli/GEMINI.md"

# Global (applies to every Gemini CLI session):
mkdir -p ~/.gemini
curl -o ~/.gemini/GEMINI.md "$RAW/dist/gemini-cli/GEMINI.md"

1. 在 GitHub 上打开 dist/plain/harmonyos-knowledge.md
2. 点击 Raw → Ctrl/Cmd + A → Ctrl/Cmd + C
3. 在你的 AI 工具中：
   • ChatGPT: Settings → Personalization → Custom Instructions → "How would you like ChatGPT to respond?" → 粘贴
   • Gemini web: 新建对话 → 启用 System Instructions → 粘贴
   • DeepSeek / Qwen / 文心一言 / Kimi: 创建"智能体" / "角色" / "Bot" → 粘贴到系统提示
4. 开始提问鸿蒙开发问题 —— AI 已加载知识

# 先拉取模型
ollama pull qwen2.5-coder:14b

# 带鸿蒙系统提示启动
ollama run qwen2.5-coder:14b \
  --system "$(curl -s $RAW/dist/system-prompt/system.txt)"

或者写入自定义 Modelfile：

# 1. Download the system prompt
curl -o system.txt "$RAW/dist/system-prompt/system.txt"

# 2. Create a Modelfile (replace the SYSTEM block contents with the file you just downloaded)
cat > Modelfile <<EOF
FROM qwen2.5-coder:14b
SYSTEM """
$(cat system.txt)
"""
EOF

# 3. Register the custom model
ollama create harmonyos-coder -f Modelfile
ollama run harmonyos-coder

# Python 示例
import anthropic
client = anthropic.Anthropic()

with open("dist/system-prompt/system.txt") as f:
    system_prompt = f.read()

response = client.messages.create(
    model="claude-opus-4-6",
    system=system_prompt,
    max_tokens=2048,
    messages=[{"role": "user", "content": "How do I make a service card in HarmonyOS?"}],
)

经验法则： 纯鸿蒙项目用"始终开启"的规则文件；混合仓库（如同时有 Android 和鸿蒙代码）用 Cursor 的 .mdc 按文件类型匹配，或 Claude Code 的按描述加载。

问 AI：

"解释 ArkUI 中 @ObjectLink 是什么，什么时候用它代替 @State？"

回答正确加载的标志：

• ✅ 提到必须用 @Observed 装饰类，@ObjectLink 才能工作
• ✅ 提到 @State 作用于对象数组时，只响应数组操作（push/splice/重新赋值），不响应单个元素的属性变化
• ✅ 提到在行组件中用 @ObjectLink 来观察元素级别的变化
• ✅ 或提到整体重新赋值对象来触发重新渲染

如果回答模糊或像 React（"用 state hook"），说明知识未加载。

其他验证问题：

• "FA 模型和 Stage 模型有什么区别？"
• "鸿蒙中如何声明和动态申请权限？"
• "HTTP 请求用哪个 Kit？"
• "怎么开发服务卡片？"

harmonyos-ai-skill/
├─ .gitignore
├─ LICENSE
├─ README_EN.md
├─ harmonyos-development/
│  └─ SKILL.md                          ← 唯一的知识源文件，只编辑这里
├─ scripts/
│  └─ build-dist.sh                     ← 重新生成所有 dist/ 文件
├─ dist/                                ← 自动生成 —— 不要手动编辑
│  ├─ claude-code/harmonyos-development/SKILL.md
│  ├─ cursor/harmonyos.mdc
│  ├─ cursor/.cursorrules
│  ├─ copilot/copilot-instructions.md
│  ├─ windsurf/.windsurfrules
│  ├─ continue/harmonyos.md
│  ├─ cline/custom-instructions.md
│  ├─ agents-md/AGENTS.md
│  ├─ gemini-cli/GEMINI.md
│  ├─ plain/harmonyos-knowledge.md
│  └─ system-prompt/system.txt
└─ README.md

单源工作流：

1. 编辑 harmonyos-development/SKILL.md
2. 运行 ./scripts/build-dist.sh
3. 同时提交源文件和重新生成的 dist/

cd /path/to/your/clone
git pull
./scripts/build-dist.sh
# 然后重新复制你所用工具的配置文件

如果是通过 ln -s 安装的，只需 git pull —— 符号链接会自动获取最新内容。

源格式是 Claude Code 的 SKILL.md —— YAML frontmatter + Markdown 正文：

---
name: my-skill-name
description: >
  第一句：这个 skill 涵盖的领域。
  然后列出 AI 可能匹配的所有触发短语：
  关键词、API 名称、命令名、用户问题、同义词。
---

# My Skill

## 何时使用
- 具体场景的列表

## 参考资料
密集、可引用的资料：表格、代码片段、API 签名、
规则、陷阱。避免废话，多用列表和紧凑示例。

• 聚焦 —— 一个 skill 一个领域，不要混合鸿蒙 + iOS + Android
• 密集 —— 删掉每一句不能教会 AI 新知识的话
• 触发词丰富 —— 在 description 中列出所有可能的用户表达方式（中英文都写）。LLM 的匹配是模糊的，但显式关键词能提高命中率
• 可操作 —— 优先用具体的代码/配置片段，而非抽象解释
• 诚实面对空白 —— 如果某功能已弃用就说明，没有数据就不写

编辑源文件后，运行 ./scripts/build-dist.sh 重新生成 dist/ 下的所有工具配置。

AI 仍然给出泛泛的 TypeScript/React 回答

• 确认文件放在了正确的路径（见上方支持的 AI 工具表格）
• Claude Code：运行 "What skills are available?" —— 如果没有列出 harmonyos-development，重启 Claude Code 或检查 ~/.claude/skills/
• 项目规则工具（Cursor、Copilot 等）：确保你编辑的文件在规则文件所在的仓库内，规则不会在仓库外生效
• 粘贴类工具（ChatGPT、DeepSeek 等）：系统提示是按对话生效的，粘贴后要开新对话

规则文件太长，超出工具的上下文限制？ 不太可能 —— SKILL.md 约 4200 行（~150 KB），主流 AI 工具（Claude/GPT-4/Gemini 等）都能接受。如果确实遇到限制（如部分本地小模型），手动裁剪 dist/plain/harmonyos-knowledge.md。

curl 返回 404？ URL 中的分支可能已变更。检查 https://github.com/DengShiyingA/harmonyos-ai-skill/branches 并更新 $RAW。

上游仓库更新后怎么同步？ 见上方更新到最新版本章节。

基于 MIT 协议 开源 —— 个人和商业项目均可自由使用。

欢迎贡献：

1. Fork 本仓库
2. 编辑 harmonyos-development/SKILL.md（唯一需要编辑的文件 —— dist/ 是自动生成的）
3. 运行 ./scripts/build-dist.sh 重新生成配置文件
4. 同时提交源文件和 dist/，然后开 PR

欢迎提交：事实纠正、新的 gotcha、更新的 API 名称、description 字段的翻译（提高触发匹配率）。