🧰 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 测试

📚 内容导览

入口 / 模块	用途
`SKILL.md`	技能规则唯一来源：告诉 Agent 如何检索、哪些内容优先信文档
`references/KITS.md`	按 Kit 导航（AbilityKit、ArkUI、ArkData…）
`references/TASK_MAP.md`	按任务反查（UI、网络、媒体、NDK…）
`references/INDEX.md`	全库文件索引（3,708 个 Markdown 路径）
`JsEtsAPIReference/INDEX.md`	API 分桶索引（modules、topics、errors…）
`references/templates/empty-ability-app`	可复制的 HarmonyOS NEXT smoke fixture（最小工程）
`docs/agent-portability.md`	Agent 安装与适配路径说明
`harmony-next/references/`	所有 Markdown 正文（含 3,678 个 API 文档）

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

脚本	功能	入口命令示例
`commandline_tools_manager.py`	Command Line Tools 下载与安装	`python3 harmony-next/scripts/commandline_tools_manager.py install ...`
`device_evidence_bundle.py`	设备证据采集与 WebView DevTools 转发诊断	`python3 harmony-next/scripts/device_evidence_bundle.py webview-devtools ...`
`device_ui_action.py`	单次 UI 操作与前后证据采集	`python3 harmony-next/scripts/device_ui_action.py tap ...`
`ux_audit_pipeline.py`	一键离线 UI/UX 体检	`python3 harmony-next/scripts/ux_audit_pipeline.py doctor ...`
`profiler_trace_audit.py`	离线 Trace 性能审计	`python3 harmony-next/scripts/profiler_trace_audit.py audit ...`
`hvd_manager.py`	HVD 设备管理	`python3 harmony-next/scripts/hvd_manager.py doctor ...`

特殊领域文档：

🚀 快速接入

通用方式（推荐）

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 输出
非交互模式下的执行策略、超时与脱敏契约

私有接口文档入口：

展开：模拟器/IDE 私有接口使用规则摘要

DevEco 模拟器私有接口 触发词：DevEco Studio、HarmonyOS Emulator、免 IDE 启动、HVD、hdc、uitest、aa、bm、snapshot_display 等。规则：先读 SKILL.md 的私有接口章节，每次执行前重新验证版本和能力；在用户已授权的本地环境内，自动化策略用于描述执行模式、产物目录和脱敏契约；wrapper 脚本阻塞时建议先尝试官方 CLI 路径采集证据。

DevEco Studio IDE 私有接口 触发词：CodeGenie、MCP、devecostudio://、inspect.sh、ArkUI Inspector、Profiler、UxTestService 等。规则：默认只做静态只读分析（插件 XML、jar、配置、离线 trace 等）；启动 IDE/GUI、本地服务、设备连接、MCP 配置等需记录目标、产物和脱敏边界；离线 trace 审计和 UI/UX 体检只使用已验证的 wrapper 脚本和规则子集。

完整细节请务必查阅上述两份文档。

📈 版本重点

版本	关键更新
`v1.3.35`	增加 DeepSeek Harness（DSH）官方 profile bundle 与 filesystem skill fallback 适配
`v1.3.30`	模拟器应用沙箱速查与 HVD doctor 的 DevEco Emulator 优先级修正
`Unreleased`	一键离线 UI/UX 体检 CLI（`ux_audit_pipeline.py`）
`Unreleased`	设备调试证据包 CLI（`device_evidence_bundle.py`）
`Unreleased`	离线 Trace 性能审计 CLI（`profiler_trace_audit.py`）
`Unreleased`	HVD launch 改进：trace socket 守护、镜像校验、许可协议处理
`Unreleased`	WebView DevTools 诊断、CDP 字段证明、单次 UI 操作证据与 Emulator 崩溃分类
`v1.3.23`	Release workflow 更新到 Node 24
`v1.3.7`	新增可复制最小测试工程模板；SDK 版本适配验证（含 6.0.2(22)）；`uitest` smoke
`v1.3.6`	模拟器非交互自动化策略
`v1.3.5`	DevEco Studio IDE 私有接口参考
`v1.2.0`	API 23 纳入；索引重建；链接兼容审计

🔧 维护与贡献

参考库更新后运行校验：

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 的支持。

安装

说明文档