查询 HarmonyOS 官方文档。用户提到鸿蒙开发、ArkTS API、官方文档时启用。通过华为文档 REST API 搜索目录、按章节获取内容、查找相关文档。支持用户直接粘贴官方链接定位到具体文档和章节。

HarmonyOS 官方文档查询技能

适用场景

用户要求"查鸿蒙官方文档"。
用户在进行 HarmonyOS / ArkTS 开发，需要 API 用法、参数说明、版本差异或示例。
用户粘贴了华为开发者文档链接。
需要在回答中附带官方出处链接与摘要。

前置条件

Node.js >= 18（零外部依赖，仅使用内置 https 模块）
脚本位于 scripts/ 目录下

脚本概览

脚本	路径	用途
getCatalogTree	`scripts/getCatalogTree.mjs`	搜索/浏览文档目录树
getDocumentById	`scripts/getDocumentById.mjs`	获取文档大纲、章节内容、超链接
getRecommendInfo	`scripts/getRecommendInfo.mjs`	获取相关文档推荐

所有脚本共用 scripts/api.mjs 工具模块，统一请求 svc-drcn.developer.huawei.com。

脚本 1：getCatalogTree — 目录树查询

入参

参数	必需	说明
`catalogName`	否	文档目录名称（见优先级表）；不传则在 P0+P1 中搜索
`--search <keyword>`	否	搜索关键词，匹配文档标题和 objectId
`--depth <N>`	否	限制树形展示深度

catalogName 优先级

优先级	catalogName	说明	何时使用
P0	`harmonyos-guides`	开发指南	默认搜索，开发指导类问题
P0	`harmonyos-references`	API 参考	默认搜索，API 用法类问题
P1	`best-practices`	最佳实践	涉及架构设计、规范类问题
P1	`harmonyos-faqs`	FAQ	报错排查、常见问题
P2	`harmonyos-releases`	版本说明	仅用户主动问版本差异时使用
P2	`harmonyos-roadmap`	变更预告	仅用户主动问未来变更时使用

用法

node scripts/getCatalogTree.mjs --search "UIAbility"
node scripts/getCatalogTree.mjs harmonyos-references --search "router"
node scripts/getCatalogTree.mjs harmonyos-guides --depth 2

输出字段

每条搜索结果包含：文档标题、objectId（传给 getDocumentById）、目录路径、官方链接。

脚本 2：getDocumentById — 文档内容获取

子命令

子命令	用法	说明
`outline`	`outline <objectId>`	首选。返回文档元信息 + 章节大纲（anchorList），不加载正文
`section`	`section <objectId> <anchorId>`	获取指定章节内容，末尾自动列出本节引用的文档链接
`full`	`full <objectId>`	获取完整文档正文（文档较短或需全文时用）
`links`	`links <objectId>`	提取文档中所有超链接（区分文档链接和外部链接）
`url`	`url <URL>`	从官方链接自动定位（核心能力，见下文）

入参说明

参数	来源	说明
`objectId`	getCatalogTree 搜索结果、文档 URL 倒数第一段	文档唯一标识，如 `arkui-overview`
`anchorId`	outline 输出中方括号内的值	章节锚点 ID，如 `两种开发范式`、`oncreate`
`URL`	用户粘贴的华为文档链接	支持带 `#锚点` 自动跳转到章节

URL 解析规则（核心）

华为文档 URL 格式：

https://developer.huawei.com/consumer/cn/doc/{catalogName}/{objectId}
https://developer.huawei.com/consumer/cn/doc/{catalogName}/{objectId}#{anchorId}

URL 路径的最后两段对应 catalogName 和 objectId：

https://...doc/harmonyos-guides/arkui-overview → catalogName=harmonyos-guides, objectId=arkui-overview
https://...doc/harmonyos-guides/arkui-overview#两种开发范式 → 额外携带 anchorId=两种开发范式

处理逻辑：

带 #anchorId：自动获取文档并返回对应章节内容（等效于 section 命令）
不带 #：显示文档大纲（等效于 outline 命令）

用法

# 用户粘贴链接 — 带锚点，直接定位到章节
node scripts/getDocumentById.mjs url "https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/arkui-overview#两种开发范式"

# 用户粘贴链接 — 不带锚点，显示大纲
node scripts/getDocumentById.mjs url https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/arkui-overview

# 先看大纲，再按章节获取
node scripts/getDocumentById.mjs outline arkui-overview
node scripts/getDocumentById.mjs section arkui-overview 两种开发范式

# 获取完整文档
node scripts/getDocumentById.mjs full start-overview

# 提取超链接
node scripts/getDocumentById.mjs links arkui-overview

关键流程：先看大纲 → 再取章节

先执行 outline 获取 anchorList（章节列表）
根据用户问题关键词匹配对应 anchorId
执行 section 只获取相关章节内容
section 输出末尾会自动列出 "本节引用的文档链接" 及其 objectId

超链接导航

文档正文中的超链接格式为 https://developer.huawei.com/consumer/cn/doc/{catalogName}/{objectId}，可以：

直接使用 url 命令打开
从 links 或 section 输出获取 objectId，用 outline/section 继续查看

脚本 3：getRecommendInfo — 相关文档推荐

入参

参数	必需	说明
`--id <objectId>`	是	当前文档的 objectId
`--title <title>`	是	当前文档的标题（从 outline 获取）
`--num <count>`	否	推荐数量，默认 10

用法

node scripts/getRecommendInfo.mjs --id arkui-overview --title "ArkUI简介"

执行流程

流程 A：用户粘贴了文档 URL

用户粘贴 URL
  │
  └─ node scripts/getDocumentById.mjs url <URL>
       │
       ├─ URL 带 #anchorId → 直接返回对应章节内容
       └─ URL 不带 # → 返回文档大纲 → 按需获取章节

流程 B：用户提出关键词问题

用户提问（关键词）
  │
  └─ node scripts/getCatalogTree.mjs --search <keyword>
       │
       ├─ 找到匹配 → node scripts/getDocumentById.mjs outline <objectId>
       │                → 匹配 anchorId → section 获取
       │
       └─ P0 没找到 → 追加 P1 搜索 → 还没找到 → 更换关键词

流程 C：查找相关文档

当前文档已获取
  │
  ├─ 1. 优先：section/links 中 "本节引用的文档链接" → 用 objectId 直接跳转
  ├─ 2. 其次：node scripts/getRecommendInfo.mjs --id <id> --title <title>
  └─ 3. 最后：node scripts/getCatalogTree.mjs --search <新关键词>

搜索策略

默认只搜 P0（指南 + API 参考），覆盖大多数开发问题
P0 没找到 → 追加 P1（最佳实践 + FAQ）
P2 仅在用户明确要求版本差异/变更预告时使用
objectId 优先使用不带 V5 的版本以获取最新内容

回答风格约束

简明直接，先给结论，再给依据。
必须包含：结论 + 依据摘要（节选关键段落） + 官方链接。
不确定内容必须明确说明不确定，不可臆造。
涉及 API 时优先给最小可运行示例。
如果文档获取失败，如实告知用户并提供手动链接。

harmonyos-official-docs