One-Line Positioning

harmony-next.skills is DeepSeek Harness's official HarmonyOS NEXT offline skill pack, bundling 3700+ ArkTS/ArkUI/NDK documents, DevEco toolchain documentation, and a set of executable Python automation scripts into a skill that can be instantly recalled during conversations, enabling the AI to provide verifiable HarmonyOS answers even without network access.

Core Capabilities

• Inject the harmony-next skill into DSH conversations; the AI follows the hierarchical index SKILL.md → KITS.md/TASK_MAP.md → INDEX.md to hit real document paths, then reads only 1-3 target files to answer
• Covers offline snapshots for HarmonyOS API 12-23: 3678 documents under JsEtsAPIReference/ including modules/topics/types/errors/guides, plus IDE debugging, signing, publishing, multi-device adaptation, performance, and other topics
• Uses 6 Python scripts to invoke DevEco toolchain from command line: CLI tool download/install, HDC emulator management and launch, device evidence collection, step-by-step UI operations, offline UI/UX health checks, Profiler trace offline analysis
• Provides copy-pasteable minimal HarmonyOS NEXT test project empty-ability-app template with Smoke UI and hdc + uitest verification paths
• Returns structured blocked JSON (with decision/failureCode/missingConfig) when script execution encounters missing environment, enabling AI to gracefully degrade to official CLI instead of infinite loops

Technical Implementation

• Language: JavaScript (ESM) + Python 3
• Key Dependencies: Only depends on Node.js built-ins node:fs, node:url (index.js); scripts side depends on Python 3, optionally cv2/numpy/PIL/requests/scipy/skimage/werkzeug/opencc for UI/UX health checks
• Architecture Pattern: DSH profile bundle —— package.json uses dsh.bundle.patch to point to cordis.patch.yml, injecting a provider named dsh-harmony-next; index.js's apply(ctx) registers a provider on ctx.skills that returns the harmony-next Skill definition
• Entry Files: index.js (DSH-side hook) + harmony-next/SKILL.md (skill content and frontmatter)

Applicable Scenarios

When you need AI programming assistants (DSH, Gemini CLI, Claude Code, Codex, etc.) to answer HarmonyOS NEXT questions by looking up evidence in offline documents rather than guessing @ohos.* modules, ArkUI components, or DevEco commands based on model memory. Typical users are engineers doing ArkTS/ArkUI business development, NDK integration, emulator automation, or DevEco Studio debugging.

Prerequisites and Compatibility

Installation

dsh plugin --profile web add github:linhay/harmony-next.skills

Configuration

This plugin requires no additional configuration.

After installation, index.js reads frontmatter fields like description, metadata.version, whenToUse from harmony-next/SKILL.md, and registers them to DSH's ctx.skills provider list with bundled source and rank=600; the two boolean fields disable-model-invocation and user-invocable are also automatically parsed from frontmatter (former defaults to off, latter to on).

FAQ

Q: What exactly does this plugin do?

A: It injects a skill named harmony-next into DSH. After entering the conversation, the AI searches the local 3700+ HarmonyOS documents following the path SKILL.md → KITS/TASK_MAP → INDEX, and calls Python scripts as needed for DevEco emulator launch, HDC evidence collection, UI/UX health checks, and Profiler trace auditing.

Q: Why can't I see a new tool icon after installation?

A: Normal. This bundle only registers Skills, not MCP/tools/apps; you should see the harmony-next skill using the / command or skills list.

Q: Do I need to install DevEco Studio first to use it?

A: Not for pure document scenarios like querying APIs, writing ArkUI components, or viewing NDK header files; you only need local DevEco when running emulator, HDC, UI automation, or performance trace scripts.

Q: What if the documentation data doesn't match Huawei's official website?

A: The built-in references/ is an offline snapshot of API 12-23, not fetched in real-time; when users ask about "latest version" or encounter new APIs, the skill rules require comparing with GitHub Releases and checking Huawei's online documentation.

Q: Can the emulator scripts run on Windows or Linux?

A: The scripts themselves are cross-platform, but the repository-verified paths for hvd_manager.py launch, device_evidence_bundle.py mainly work on macOS DevEco installations; Windows/Linux need self-verification of DevEco installation paths, image root directories, and HDC port mappings.

Q: How much space does the bundle take?

A: The references/ offline documents alone are about 54 MB, plus 10 scripts and tests, making it significantly larger than ordinary skill packs; ensure sufficient disk space before installation.

Q: How to uninstall?

A: Like other profile bundles, remove dsh-harmony-next from the DSH profile's bundle layer; you can also manually delete ~/.dsh/skills/harmony-next/ or .dsh/skills/harmony-next/ directories.

Difficulty Level

Beginner — the bundle is ready to use after installation with no configuration or hooks needed; if only using document retrieval, you don't even need to touch the scripts; running emulators or trace toolchains requires step-by-step configuration of the local DevEco environment.

Known Issues and Limitations

• Offline documentation has latency vs. Huawei's official website: built-in references/ is a snapshot of API 12-23; when encountering "latest interfaces" or new APIs, must check official online documentation (harmony-next/SKILL.md:18-20)
• Emulator image download is deliberately blocked: hvd_manager.py download-image returns blocked; currently verified path is still DevEco Studio SDK Manager UI operation (harmony-next/SKILL.md:88)
• First launch of DevEco Emulator requires explicit confirmation with --accept-license after user has read the agreement; scripts won't check this for you by default (harmony-next/scripts/hvd_manager.py:670-671)
• UI/UX health check scripts have heavy Python dependencies: when default interpreter lacks modules like cv2/numpy/PIL, scripts directly error with missingConfig=["uxPythonDependencies"] instead of degrading (harmony-next/SKILL.md:72)
• DevEco emulator and IDE private interfaces (CodeGenie, devecostudio://, UxTestService, hdc/uitest automation, etc.) are version-sensitive capabilities; plugin ID, paths, ports, and parameters must be re-confirmed before use; documentation explicitly states "not wrapping private interfaces into stable public APIs" (harmony-next/SKILL.md:177-181)

🧰 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

展开：模拟器/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 脚本和规则子集。

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

📈 版本重点

🔧 维护与贡献

参考库更新后运行校验：

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