linhay / harmony-next.skills

🧰 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 ...

特殊领域文档：

• 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

展开：模拟器/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 的支持。