🧰 HarmonyOS NEXT 开发者专家技能包

给 Gemini CLI、Claude Code、Codex 等 AI 编程助手使用的 HarmonyOS NEXT 离线参考技能库。

面向 API 12-23 的本地知识源，覆盖 ArkTS、ArkUI、NDK、工具链、调试、发布与多端适配。

🎯 解决的问题

AI 编程助手在 HarmonyOS 开发中经常碰到的几类问题：

• 找不到 @ohos.* 模块的真实文档
• 不确定某个 ArkUI 组件或 NDK 头文件是否存在
• API 版本差异、新增内容未纳入知识库
• 旧文档链接失效或迁移
• DevEco Studio 模拟器、hdc、uitest 等本地自动化的验证路径不清晰

本仓库把这些不确定性变成可定位、可跳转、可验证的本地文件查询。

Before / After

没有 skill：模型凭记忆猜 @ohos.* 模块、ArkUI 组件名或 DevEco 命令，答案看起来合理但缺少来源。

使用本 skill：先按 SKILL.md → KITS.md / TASK_MAP.md → INDEX.md 命中文档路径，再打开目标 Markdown，最后给出代码片段和 hdc / uitest / wrapper 脚本验证命令。

✨ 核心特性

• 完全离线检索：不依赖模型记忆，先命中文档路径再读取正文
• 为 Agent 工作流设计：按 SKILL.md → KITS/TASK_MAP → INDEX 层层递进检索
• 覆盖范围广：不只 API 手册，还包含 IDE、签名、调试、发布、性能、NDK 实战指引
• 私有能力隔离：DevEco 模拟器、IDE 未公开接口单独成章，默认先验证版本和风险
• 自动化优先：支持非交互式自动化策略，提供证据采集、UI/UX 离线体检、trace 审计等脚本
• 可运行的最小工程：提供 empty-ability-app 模板，可直接复制用于 smoke 测试

📚 内容导览

自动化与诊断脚本（按需使用）：

特殊领域文档：

• DevEco模拟器私有接口与AI自动化.md
• ArkWeb WebView CDP调试与字段到达证明.md
• DevEco Studio IDE私有接口与AI自动化.md
• minimal-project-scaffold.md

🚀 快速接入

通用方式（推荐）

npx skills add linhay/harmony-next.skills

当前仓库只有一个 skill，直接运行上面的命令会自动安装 harmony-next。如果想先查看可用技能：

npx skills add linhay/harmony-next.skills --list

Gemini CLI

gemini skills install https://github.com/linhay/harmony-next.skills --path harmony-next --scope user

Claude Code

npx skills add linhay/harmony-next.skills --skill harmony-next -a claude-code -g -y --copy

或手动添加仓库目录：

git clone https://github.com/linhay/harmony-next.skills.git
claude --add-dir /path/to/harmony-next.skills/harmony-next

Codex

npx skills add linhay/harmony-next.skills --skill harmony-next -a codex -g -y --copy

本仓库当前还不是 Codex plugin；npx skills 只会把 skill 安装到 Codex 可扫描的 skill 目录，不会安装 MCP/tools/apps。

也可手动放入官方路径（常用如 $HOME/.agents/skills/harmony-next；完整路径见 docs/agent-portability.md）。

DeepSeek Harness（DSH）

本仓库提供官方 DSH profile bundle dsh-harmony-next。推荐通过 DSH profile 安装：

# 从 GitHub 安装
dsh plugin --profile demo add github:linhay/harmony-next.skills

# 或从本地 checkout 安装
dsh plugin --profile demo add /path/to/harmony-next.skills

# 检查 bundle layer
dsh --profile demo --dump-config

Bundle 只注册 harmony-next skill 及其离线参考资源，不安装 MCP、tools 或 apps。DSH bundle 的 manifest 是根目录的 package.json，patch 是 cordis.patch.yml。

如果只需要 filesystem skill，也可以手动安装到 DSH 的兼容根目录：

# DSH_SOURCE 指向本仓库的本地 checkout
DSH_SOURCE=/path/to/harmony-next.skills

# 项目级 skill
mkdir -p .dsh/skills/harmony-next
cp -R "$DSH_SOURCE/harmony-next/." .dsh/skills/harmony-next/

# 或用户级 skill（默认 ~/.dsh/skills）
mkdir -p "$HOME/.dsh/skills/harmony-next"
cp -R "$DSH_SOURCE/harmony-next/." "$HOME/.dsh/skills/harmony-next/"

DSH 也支持 .agents/skills、$DSH_AGENTS_HOME/skills 等兼容根目录；发现优先级和更新方式见 docs/agent-portability.md。

各 Host 只负责加载 skill；HarmonyOS 检索规则以 harmony-next/SKILL.md 为准。

🧭 推荐检索路径

SKILL.md → KITS.md / TASK_MAP.md → INDEX.md → 目标 Markdown

设计原则：先定规则，再按 Kit 或任务缩小范围，用索引命中真实路径，最后只打开 1-3 个文件读细节。

📦 适用场景

• ArkTS / ArkUI 开发：组件、装饰器、状态管理、UIAbility 等 API 确认与示例
• NDK / C API：头文件对应真实文档、跨语言调用、CMake 配置
• IDE / 工具链 / 调试：签名、模拟器、真机调试、性能分析与发布流程
• DevEco 模拟器自动化：免 IDE 启动、HVD、hdc/uitest 自动化、抓包诊断
• DevEco IDE 私有能力：CodeGenie、ArkUI Inspector、离线 trace 审计、UI/UX 体检
• Agent 工程化集成：作为 Gemini CLI、Claude Code、Codex 的本地知识检索层

⚠️ 安全边界：私有接口与本地自动化

涉及 DevEco 模拟器、IDE 私有接口、设备日志、截图、抓包、HVD 创建/删除等操作时，必须先阅读对应的私有接口文档。这些流程要求：

• 执行前验证 DevEco / Emulator / SDK 版本和命令能力
• 明确产物目录、脱敏边界和失败时的 blocked 输出
• 非交互模式下的执行策略、超时与脱敏契约

私有接口文档入口：

• DevEco模拟器私有接口与AI自动化.md
• DevEco Studio IDE私有接口与AI自动化.md

📈 版本重点

🔧 维护与贡献

参考库更新后运行校验：

python3 harmony-next/scripts/check_packaging_docs.py
python3 harmony-next/scripts/reference_compat.py generate
python3 harmony-next/scripts/reference_compat.py check
python3 harmony-next/scripts/reference_compat.py audit
python3 -m unittest discover -s harmony-next/tests -p 'test_*.py' -v

📜 来源与许可

• 数据源：华为 HarmonyOS 官方文档
• 本仓库为 AI 辅助开发重新封装，英文说明见 README_en.md

感谢 LINUX DO 的支持。