harmonyos-sdk-api-lookup

HarmonyOS SDK API Lookup

在本 skill 目录下的 api-references/ 中搜索 HarmonyOS API 参考 Markdown 文档，支持两种查询模式：

1. API 查询 - 查找具体 API 的签名、类型、权限、系统能力、版本等信息
2. 功能查询 - 根据功能需求，定位相关 Kit 和模块，组合完整实现方案并给出代码示例

API 参考信息

• 主路径: 本 skill 目录下的 api-references/
• 规模: 4000+ 个 .md 文件
• 文件名特性: 文件名自带领域、Kit 名称、API 类型、模块名和页面主题，例如：
  • 媒体-Camera Kit（相机服务）-ArkTS [email protected] (相机管理)-Interface (CameraManager).md
  • 媒体-Audio Kit（音频服务）-ArkTS [email protected] (音频管理)-Functions.md
  • 系统-网络-Connectivity Kit（短距通信服务）-ArkTS [email protected] (WLAN).md

目录结构

api-references/
├── ... ArkTS API / C API / 错误码 / 组件 / 指南页面

核心搜索流程（文件名优先）

始终先搜索文件名，再读取候选 Markdown；只在候选过多或文件名无法定位时做全文搜索。

第一步：拆分查询关键词

根据用户问题提取 2 到 5 类关键词：

关键词类型	示例
Kit 名称	Camera Kit, Audio Kit, Connectivity Kit, Ability Kit
模块名	@ohos.multimedia.camera, @ohos.net.http, @hms.scan
API / 类型名	CameraManager, createCameraInput, HttpRequest, PhotoOutput
中文功能词	相机, 拍照, 网络, 定位, 剪贴板, 权限
API 类型	ArkTS API, C API, Interface, Functions, Enums, 错误码

第二步：按文件名缩小候选集

列出文件，再对文件名做二次过滤：

文件名里已经包含 Kit 名称，所以不需要读取单独的 Kit 索引。命中多个文件时，优先读取最精确的页面：

1. 具体 Interface (Xxx).md / Class (Xxx).md / Functions.md
2. 具体模块页面：@ohos.xxx (...).md
3. Enums.md / Types.md / Interfaces (其他).md
4. 错误码、指南、概览页面

第三步：检查大小并读取目标 Markdown

读取候选文档前，先检查文件大小和行数，避免把超大 Markdown 一次性读入上下文：

Get-Item "harmonyos-sdk-api-lookup/api-references/目标文件.md" | Select-Object Length,FullName
(Get-Content "harmonyos-sdk-api-lookup/api-references/目标文件.md" | Measure-Object -Line).Lines

按以下规则读取：

1. 小文件：小于 3000 行，可以整文件读取。
2. 大文件：达到 3000 行以上，禁止整文件读取；必须先搜索 API 名、类型名、标题或关键词。用搜索结果定位后读取邻近上下文，多次少量读取。

常用领域定位提示

功能领域	优先文件名关键词
网络/HTTP/WebSocket	网络, Connectivity Kit, Network Kit, @ohos.net, http, webSocket
文件/存储	文件, Core File Kit, ArkData, file, fs, picker
相机/拍照	Camera Kit, 相机, @ohos.multimedia.camera
音频/音效	Audio Kit, 音频, @ohos.multimedia.audio
视频/播放/录制	Media Kit, 媒体, AVPlayer, AVRecorder
图片处理	Image Kit, 图片, image
蓝牙/WiFi/NFC	Connectivity Kit, 蓝牙, WLAN, NFC, wifi, bluetooth
定位/GPS	Location Kit, 位置, 定位, geoLocationManager
传感器	Sensor Service Kit, 传感器, sensor
通知	Notification Kit, 通知, notification
加密/安全	Crypto Architecture Kit, Universal Keystore Kit, 加密, 密钥
设备信息/电池/振动	Basic Services Kit, deviceInfo, batteryInfo, vibrator
剪贴板	Basic Services Kit, pasteboard, 剪贴板
UI 组件	ArkUI, 组件, 组件名
Web/WebView	ArkWeb, Web, webview, @ohos.web
后台任务	Background Tasks Kit, 后台任务, backgroundTaskManager
应用生命周期	Ability Kit, Ability, Want, UIAbility
扫码/二维码	Scan Kit, 扫码, 二维码, @hms.scan
地图	Map Kit, 地图, @hms.map
推送	Push Kit, 推送, @hms.push
支付/内购	IAP Kit, Payment Kit, 支付, 内购
语音识别/合成	Speech Kit, Core Speech Kit, 语音
OCR/图像识别	Vision Kit, Core Vision Kit, OCR, 图像识别

关键类型定义: （列出代码中用到的 interface / enum 定义摘要）

注意事项:

• 版本要求、平台限制、权限申请、常见错误码等

功能查询的分析技巧

分析 API 关系的方法：

• 返回值 -> 参数链: 方法 A 返回 TypeX，方法 B 接收 TypeX 作为参数，则 A 的输出可能是 B 的输入
• 配置对象模式: 一个功能通常有 XxxConfig / XxxOptions 接口，先构造配置再调用
• 生命周期模式: 有 create/open + start/execute + stop/close/release 时，需要完整管理资源
• 回调/监听模式: 有 on(event, callback) / off(event) 时，注册后需在适当时机取消
• 错误码页面: 同一 Kit 下通常有独立错误码 Markdown，功能方案中需要引用常见错误码

注意事项

• 绝不猜测 API 签名，只返回 api-references/ Markdown 中实际存在的定义
• 代码示例中的所有 API 调用必须与文档签名严格一致
• 同一功能有 Promise 和 callback 两种形式时，优先返回 Promise 形式
• 标记为废弃的 API 需注明替代方案

权限信息提取规则（防幻觉）

权限信息仅在文档中出现明确的权限标注时才记录：

1. 有效权限标注格式（必须包含以下关键词）：

   • **需要权限：** ohos.permission.xxx
   • **权限：** ohos.permission.xxx
   • required_permission: ohos.permission.xxx

2. 以下内容 ≠ 权限要求（常见误判）：

   • 文档中提到"悬浮窗"、"自由窗口"、"浮动窗口"等场景描述
   • 文档中提到"非全屏模式下不生效"、"自由窗口状态下不生效"等限制
   • 文档中提到窗口类型（如 TYPE_FLOAT）或窗口模式

3. 无权限标注时的处理：

   • 若文档中没有明确的权限标注，required_permission 必须返回 null
   • 不得根据场景描述猜测权限要求
   • 不得将其他 API 的权限关联到当前 API

4. 返回权限信息时必须标注来源：

   • 格式：需要权限: ohos.permission.xxx [来源: {文件名}:{行号}]
   • 示例：需要权限: ohos.permission.INTERNET [来源: @ohos.net.http.md:52]