| name | harmonyos |
| description | 当用户编写、调试或审查 HarmonyOS NEXT 应用（ArkTS / ArkUI / Stage 模型 / @ohos.* API / DevEco Studio / hvigor / hdc），需要查阅华为开发者官方文档（版本说明 / 指南 / API 参考 / 最佳实践 / FAQ），或询问 HarmonyOS API 签名、错误码、能力可用性时使用。先在 `references/INDEX.md` 中 grep 关键词定位目标路径，再 Read 命中的 `.md`，不要遍历目录或一次性读多个文件。 |
HarmonyOS
HarmonyOS NEXT 开发者文档离线镜像。来源：developer.huawei.com/consumer/cn/doc/。每个 .md 顶部带 YAML frontmatter，含原始 URL、面包屑、doc_updated_at 等元信息。
快速上手
-
通过索引定位文件——不要直接 grep references/：
rg -n "<关键词>" references/INDEX.md | head
-
Read 命中的 .md。文件前 8 行 frontmatter 给出原始 URL 与最后更新时间。
-
当用户需要参考链接时，从 frontmatter 的 url 字段返回——这是华为官方文档的规范引用。
分类
| 路径 | 内容 |
|---|
references/harmonyos-releases/ | 版本说明、API Level、SDK 变更日志 |
references/harmonyos-guides/ | 应用框架、ArkTS、ArkUI、媒体、网络等使用指南 |
references/harmonyos-references/ | API 参考（@ohos.* 模块、组件签名、错误码） |
references/best-practices/ | 性能、兼容性、能耗等官方最佳实践 |
references/harmonyos-faqs/ | 常见问题与解答 |
每个分类有专属 INDEX.md（含标题与统计），范围明确时可缩到分类内查找：
rg -n "UIAbility" references/harmonyos-references/INDEX.md
rg -n "@ohos\.app\.ability" references/harmonyos-references/INDEX.md
内链已本地化
文档中原本指向 5 个白名单根 URL 的链接已自动改写为指向本仓库内 .md 的相对路径。指向白名单外的链接保留为绝对 https URL。
编码规则（写代码前必读）
rules/arkts-coding-rules.md 是 HarmonyOS 官方 ArkTS / ArkUI / API 使用强制规则，三段：
- ArkTS / ets 语法约束 — 违反编译不通过（如不支持
any、var、解构赋值、Function.bind、for..in 等）
- HarmonyOS API 使用规范 — 必须遵循 API Level、权限配置、
module.json5 / oh-package.json5、资源 $r 引用、国际化、深色主题
- ArkUI 动画规范 — 优先声明式 +
@State、复杂子树 renderGroup(true)、避免动画中改 width/height/padding
为用户写或修改 ArkTS / ArkUI 代码前先 Read 这份文件。规则简洁、列表化，可一次性加载到上下文。
工作流程
- 先弄清用户问的是什么——功能查询、API 签名、错误码、版本差异，还是最佳实践？
- 用关键词在
references/INDEX.md 中匹配（明显属于某个分类时可直接到对应 <category>/INDEX.md）
- 仅
Read 命中的 .md，不要主动读邻居文件，除非确有必要
- 回答时引用 frontmatter 的
url 字段作为出处
- 如果本地文件比用户项目要求的版本陈旧（对比
doc_updated_at），或本地完全没命中而该话题确属鸿蒙领域，用下方"在线兜底"调华为文档 API 拉取最新内容并明确说明走了在线兜底
质量约束
@ohos.* API 的签名、入参、返回值以 references/ 内的文档为准，不要凭训练时记忆补全- ArkUI 示例优先使用声明式语法（
@Entry / @Component / build()），除非文档明确是 NDK 或系统服务
- 不要修改
references/ 下任何文件——它们是只读参考资料
- 不要把 frontmatter 字段（
content_hash / scraped_at / category）当成代码内容塞进生成的代码里
- 当两份文档冲突（例如旧版指南与新版本说明），明确指出冲突并同时引用两边
在线兜底（不要用 WebFetch / 浏览器）
developer.huawei.com/consumer/cn/doc/ 是 SPA 站点：WebFetch 拿不到正文（只返回加载占位页），curl 直接抓 URL 也只有 1.5KB 空壳。要拉最新内容请直接调华为文档 API（HTML 端点，毫秒级）：
URL="https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/application-dev-guide"
OBJECT_ID="${URL##*/}"
OBJECT_ID="${OBJECT_ID%%\?*}"
curl -sL -X POST "https://developer.huawei.com/consumer/cn/documentPortal/getDocumentById" \
-H "Content-Type: application/json" \
-d "{\"objectId\":\"${OBJECT_ID}\",\"language\":\"cn\"}" \
| jq -r '.value.content.content'
返回结构：
{
"code": 0,
"value": {
"title": "应用开发导读",
"lang": "cn",
"anchorList": [...],
"content": {"type": "html", "content": "<html>...<h1>...</h1>...</html>"}
}
}
需要 Markdown 时把 HTML 喂给 pandoc -f html -t markdown，或用 Python markdownify：
curl ... | jq -r '.value.content.content' | pandoc -f html -t gfm
