harmony-next.skills
linhay/harmony-next.skills加载项目详情…
本应用为开源项目，仅供学习研究，请遵守其开源协议。
微信扫码咨询客服
POMOAI — 让开源 AI 即刻运行
加载项目详情…
本应用为开源项目，仅供学习研究，请遵守其开源协议。
如果你正在用 Claude Code、Codex 或 Gemini CLI 写鸿蒙应用，大概率遇到过这么一幕：让 Agent 写一段 ArkTS，它信心满满地调了
@ohos.app.ability.UIAbility，然后编译报错；或者你问它"这个 API 在 API 26 还在不在"，它给出一个看似合理、实则三年前就被废弃的签名。根因很简单——通用大模型对 HarmonyOS NEXT 这套相对封闭的官方生态，训练语料覆盖非常稀薄。
linhay/harmony-next.skills 是对这个问题的直接答案：把 HarmonyOS NEXT 的开发者知识打包成离线技能库，让 AI 编程助手在本地检索官方 API 声明，而不是靠记忆瞎猜。
HarmonyOS NEXT 从 API 12 一路演进到 API 26，官方文档只在 developer.huawei.com 上在线提供，且大量文档需要登录开发者账号才能完整访问。对 AI 助手来说这意味着两件事：一是联网抓取不稳定（国内网络环境 + 需要登录 + 反爬），二是"最新"这个概念在离线场景里根本不存在。
作者的做法很直接——把官方文档批量抓下来、离线化、做成快照。仓库里 harmony-next/references/JsEtsAPIReference/api26/ 存放的是 API 26.0.0 的声明、类型和签名快照，并且明确写清了快照边界：API 12–23 是本地离线快照，API 26 页面已纳入，完整指南与示例仍在补充中。这种"标注自己知识边界"的做法，在 AI 工具仓库里并不常见。
传统做法是让 Agent 联网查文档，像每次写代码都要跑去图书馆借书。本项目相当于给 Agent 配了一本随身携带的离线新华字典，外加一张索引表。关键设计是 渐进式披露（progressive disclosure）：
SKILL.md → KITS.md / TASK_MAP.md → INDEX.md → 目标文档
SKILL.md 是路由层，负责判断问题类型；KITS.md 按 Kit 组织（AbilityKit、ArkUI、ArkTS、ArkData、MediaKit、ConnectivityKit、Security 等），给出关键词和模块前缀；INDEX.md 是 257KB 的全库路径清单；JsEtsAPIReference/INDEX.md 是 180KB 的 API 分桶索引。真正需要时才打开 1–3 个目标 .md。这样既避免了把 4000+ 文档塞进上下文，也避免了无差别搜索命中一堆噪声。
KITS.md 里甚至直接给出了检索命令模板，例如查 AbilityKit 就是：
rg -n "(@ohos\.app\.ability\.|@ohos\.ability\.|UIAbility|Want)" INDEX.md | rg "JsEtsAPIReference/" | head
这套设计对 Agent 非常友好——它本质上把"人类查文档的路径"翻译成了"Agent 可执行的检索路径"。
这是本项目比同类"文档镜像"高一档的地方。仓库里有 20 个 Python 脚本（约 21 万字符），承担实际的设备与 IDE 操作：
| 脚本 | 职责 |
|---|---|
hvd_manager.py（60KB） | HarmonyOS 模拟器 HVD 生命周期管理：探测 HVD 根目录、环境变量优先级、设备类型/API 版本识别、崩溃模式识别（kernel panic、fatal signal、emulator crash） |
device_evidence_bundle.py（53KB） | 采集设备证据包，用于问题定位与回归取证 |
ux_audit_pipeline.py（42KB） | 离线 UI/UX 审计流水线 |
device_ui_action.py（22KB） | 通过 uitest/hdc 做 UI 自动化操作 |
profiler_trace_audit.py（19KB） | Profiler trace 审计 |
reference_compat.py（28KB） | 参考资料兼容性校验与链接重写（把华为在线链接映射到本地离线文档） |
commandline_tools_manager.py（16KB） | HarmonyOS 命令行工具下载安装与 PATH 配置 |
sync_api26_snapshot.py | 从新版 DevEco Studio 重新生成 API 26 声明快照 |
这些脚本直接对接 DevEco Studio 的私有接口：devecostudio:// 协议、CodeGenie、MCP、LanceDB、ArkUI Inspector、Previewer、Profiler、Doctor、UxTestService。等于给 Agent 装了一双"能操作鸿蒙 IDE 和模拟器的手"。
安装路径覆盖得相当全，每种主流 Agent 都有对应命令：
# Claude Code / Codex（Vercel Labs skills CLI）
npx skills add linhay/harmony-next.skills --skill harmony-next -a claude-code -g -y --copy
npx skills add linhay/harmony-next.skills --skill harmony-next -a codex -g -y --copy
# Gemini CLI
gemini skills install https://github.com/linhay/harmony-next.skills --path harmony-next --scope user
# DeepSeek Harness (DSH)
dsh plugin --profile demo add github:linhay/harmony-next.skills
也支持手动放入 $HOME/.agents/skills/harmony-next、/etc/codex/skills/harmony-next 等官方扫描位置。对 Claude.ai 还提供 harmony-next.skill.zip 上传流程（仓库里那个 11MB 的 zip 就是这个产物）。
但完整能力有前置条件：脚本要真正跑起来，需要本机安装 DevEco Studio 与 HarmonyOS SDK / 命令行工具，模拟器相关功能需要华为账号登录并接受许可协议（脚本里明确处理了 license-agreement-required 这个状态）。纯文档问答部分则完全无依赖、纯离线可用。
unittest 测试文件，覆盖 hvd_manager、device_evidence_bundle、ux_audit_pipeline、reference_compat、packaging_docs、skill_metadata 等模块，发布前在 CI 中强制执行 python3 -m unittest discover -s harmony-next/tests。sync_release_version.py），提交 master 或打 tag 自动发 Release，当前最新 v1.3.44。仓库创建于 2026-03-12，近半年已迭代 44 个小版本。HARMONY_NEXT_SKILL_DIR 变量，禁止硬编码仓库根路径；docs/agent-portability.md 专门记录各 Agent 的适配差异。references/templates/empty-ability-app/ 是可复制的 Empty Ability 最小工程，明确声明"不携带任何个人证书、p12、profile 或本机绝对路径"。
需要客观指出几个问题：
许可证标注不严谨。 package.json 和 README 都写着 MIT，但仓库根目录没有 LICENSE 文件，GitHub API 因此无法识别（返回 null）。这在法律上是模糊地带——虽然文档注明"文档来源为华为 HarmonyOS 官方资料，版权归原作者所有"，且仓库内还有 docs-linhay/dev/2026-06-08-issue-17-license-agreement-required.md 这样的相关讨论记录，但使用前应向作者确认授权状态。
单一作者依赖。 4 位贡献者中 3 位是机器人账号（Copilot、cursoragent、tonycoder-hub），实质贡献几乎全部来自 linhay 一人（107 次提交）。项目治理结构薄弱，作者若停止维护则无人接手。
依赖闭源商业环境。 核心脚本深度绑定 DevEco Studio 私有接口，这些接口随 IDE 版本变化可能随时失效。仓库自己也在 ideGuides/DevEco Studio IDE私有接口与AI自动化.md 里讨论了这类风险。离开华为生态，脚本层的价值大幅缩水，只剩文档检索能力。
快照的时效性天花板。 API 26 发布于 2026-08-29，而仓库 README 明确说明"完整指南和示例仍在补充中"。官方文档持续更新时，离线快照必然滞后，SKILL.md 自己也提示"涉及精确行为时须对照华为在线文档核验"。
规模带来的检索噪声。 4392 个文件、4278 个 Markdown，INDEX.md 单文件 257KB。即使有分层路由，Agent 在模糊查询下仍可能命中大量不相关条目。脚本层做了"渐进式披露"缓解，但无法根除。
这个项目折射出开源 AI 工具生态的一个清晰趋势：通用模型的能力缺口，正被"垂直知识包"填补。与其指望模型训练数据覆盖鸿蒙这种细分生态，不如把权威资料本地化并设计好检索路由，让模型在正确的上下文里工作。
同时也代表另一条路线——Agent Skill 正在成为新的分发格式。仓库同时适配 Gemini CLI、Claude Code、Codex、DSH，配置了 DSH 的 cordis.patch.yml 插件补丁，README 顶部直接内置"把这段话发给你的 Agent"的安装提示词。这套"一份技能、多端适配"的做法，很可能成为 AI 工具分发的社区惯例。
从数据看：367 星、24 fork、半年 44 个版本、Release 稳定输出——在"鸿蒙 + AI"这个足够窄的交集上，这已经是相当不错的专注度。做国产系统开发的团队，这个仓库值得直接装到 Agent 里试试。