# 🧰 HarmonyOS NEXT 开发者专家技能包给 Gemini CLI、Claude Code、Codex 等 AI 编程助手使用的 HarmonyOS NEXT 离线参考技能库。 [![release](https://img.shields.io/github/v/release/linhay/harmony-next.skills?style=flat-square)](https://github.com/linhay/harmony-next.skills/releases/latest) [![skills.sh](https://skills.sh/b/linhay/harmony-next.skills)](https://skills.sh/linhay/harmony-next.skills) ![docs](https://img.shields.io/badge/docs-3,708%20markdown%20files-7c3aed?style=flat-square) ![js-ets](https://img.shields.io/badge/JsEtsAPIReference-3,678%20files-b45309?style=flat-square) > 面向 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`](./harmony-next/SKILL.md) | 技能规则唯一来源：告诉 Agent 如何检索、哪些内容优先信文档 | | [`references/KITS.md`](./harmony-next/references/KITS.md) | 按 Kit 导航（AbilityKit、ArkUI、ArkData…） | | [`references/TASK_MAP.md`](./harmony-next/references/TASK_MAP.md) | 按任务反查（UI、网络、媒体、NDK…） | | [`references/INDEX.md`](./harmony-next/references/INDEX.md) | 全库文件索引（3,708 个 Markdown 路径） | | [`JsEtsAPIReference/INDEX.md`](./harmony-next/references/JsEtsAPIReference/INDEX.md) | API 分桶索引（modules、topics、errors…） | | [`references/templates/empty-ability-app`](./harmony-next/references/templates/empty-ability-app/) | 可复制的 HarmonyOS NEXT smoke fixture（最小工程） | | [`docs/agent-portability.md`](./docs/agent-portability.md) | Agent 安装与适配路径说明 | | `harmony-next/references/` | 所有 Markdown 正文（含 3,678 个 API 文档） | **自动化与诊断脚本**（按需使用）： | 脚本 | 功能 | 入口命令示例 | | --- | --- | --- | | [`commandline_tools_manager.py`](./harmony-next/scripts/commandline_tools_manager.py) | Command Line Tools 下载与安装 | `python3 harmony-next/scripts/commandline_tools_manager.py install ...` | | [`device_evidence_bundle.py`](./harmony-next/scripts/device_evidence_bundle.py) | 设备证据采集与 WebView DevTools 转发诊断 | `python3 harmony-next/scripts/device_evidence_bundle.py webview-devtools ...` | | [`device_ui_action.py`](./harmony-next/scripts/device_ui_action.py) | 单次 UI 操作与前后证据采集 | `python3 harmony-next/scripts/device_ui_action.py tap ...` | | [`ux_audit_pipeline.py`](./harmony-next/scripts/ux_audit_pipeline.py) | 一键离线 UI/UX 体检 | `python3 harmony-next/scripts/ux_audit_pipeline.py doctor ...` | | [`profiler_trace_audit.py`](./harmony-next/scripts/profiler_trace_audit.py) | 离线 Trace 性能审计 | `python3 harmony-next/scripts/profiler_trace_audit.py audit ...` | | [`hvd_manager.py`](./harmony-next/scripts/hvd_manager.py) | HVD 设备管理 | `python3 harmony-next/scripts/hvd_manager.py doctor ...` | **特殊领域文档**： - [`DevEco模拟器私有接口与AI自动化.md`](./harmony-next/references/ideGuides/DevEco模拟器私有接口与AI自动化.md) - [`ArkWeb WebView CDP调试与字段到达证明.md`](./harmony-next/references/ideGuides/ArkWeb%20WebView%20CDP调试与字段到达证明.md) - [`DevEco Studio IDE私有接口与AI自动化.md`](./harmony-next/references/ideGuides/DevEco%20Studio%20IDE私有接口与AI自动化.md) - [`minimal-project-scaffold.md`](./harmony-next/references/quickStart/ets/minimal-project-scaffold.md) ## 🚀 快速接入 ### 通用方式（推荐） ```bash npx skills add linhay/harmony-next.skills ``` 当前仓库只有一个 skill，直接运行上面的命令会自动安装 `harmony-next`。如果想先查看可用技能： ```bash npx skills add linhay/harmony-next.skills --list ``` ### Gemini CLI ```bash gemini skills install https://github.com/linhay/harmony-next.skills --path harmony-next --scope user ``` ### Claude Code ```bash npx skills add linhay/harmony-next.skills --skill harmony-next -a claude-code -g -y --copy ``` 或手动添加仓库目录： ```bash git clone https://github.com/linhay/harmony-next.skills.git claude --add-dir /path/to/harmony-next.skills/harmony-next ``` ### Codex ```bash 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`](./docs/agent-portability.md)）。各 Host 只负责加载 skill；HarmonyOS 检索规则以 `harmony-next/SKILL.md` 为准。 ## 🧭 推荐检索路径 ```text 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`](./harmony-next/references/ideGuides/DevEco模拟器私有接口与AI自动化.md) - [`DevEco Studio IDE私有接口与AI自动化.md`](./harmony-next/references/ideGuides/DevEco%20Studio%20IDE私有接口与AI自动化.md)

展开：模拟器/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.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 纳入；索引重建；链接兼容审计 | ## 🔧 维护与贡献参考库更新后运行校验： ```bash 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](./README_en.md) --- 感谢 [LINUX DO](https://linux.do/) 的支持。 [![Star History Chart](https://api.star-history.com/svg?repos=linhay/harmony-next.skills&type=Date)](https://www.star-history.com/#linhay/harmony-next.skills&Date)