| name | hmos-arkts-knowledge-retriever |
| description | 检索 ArkTS 语言指南文档，为代码开发、审查和调试提供语法参考。当需要查找 ArkTS 语法规则、库使用方法或代码示例时使用。提供基于索引的高效检索和可追溯的文档引用。 |
ArkTS 知识检索工具
技能概述
本技能用于快速检索 ArkTS 语言指南文档，为 HarmonyOS 开发提供准确的语法参考。通过结构化索引实现高效检索，返回可追溯的文档引用，帮助开发者在编码、审查和调试时快速找到正确的语法规则。
使用场景
- ✅ 查找 ArkTS 语法规则和用法
- ✅ 检索 ArkTS 标准库和常用库的使用方法
- ✅ 获取 ArkTS 并发编程和运行时相关文档
- ✅ 查找 ArkTS 代码示例和最佳实践
- ✅ 代码审查时验证语法正确性
- ✅ 调试时查找错误原因和解决方案
工作流程
1. 分析查询意图
根据用户问题确定检索类型：
| 查询类型 | 关键词示例 | 目标文档范围 |
|---|
| 语法规则 | 类、函数、接口、泛型 | 02-Basic-Syntax |
| 库使用 | JSON、XML、容器 | 03-Common-Library |
| 并发编程 | TaskPool、Worker、线程 | 04-Concurrency |
| 运行时 | 动态导入、模块加载 | 05-Runtime |
| 工具链 | 编译、混淆、字节码 | 07-Compilation-Toolchain |
| 迁移 | TypeScript 转 ArkTS | 09-Migration-Guide |
2. 执行检索
使用检索脚本查询索引：
python3 scripts/search_docs.py --query "<查询内容>"
检索参数：
--query: 查询字符串（必需）--scope: 限定范围（可选，如 02-Basic-Syntax）--top-k: 返回结果数量（默认 5）
3. 分析检索结果
检索结果包含以下信息：
- Reference: <文档路径>
- Section: <章节路径>
- Why it matches: <匹配原因>
- Guidance: <简要指导>
- Verification: <验证级别>
验证级别说明：
snippet_validated: 代码示例已通过验证doc_only: 仅文档说明，无代码验证
4. 返回结果
按照标准格式返回检索结果：
单结果格式：
📚 **参考文档**: [classes.md](references/arkts-language-guide/02-basic-syntax/classes.md)
📍 **章节**: Declaring a Class
💡 **匹配原因**: 查询涉及类声明语法，该章节详细说明了 class 关键字的使用方法。
📖 **指导**: 使用 `class` 关键字定义类，字段必须在类体中声明。ArkTS 不支持类表达式，必须使用命名类声明。
✅ **验证状态**: snippet_validated
多结果格式：
找到 3 个相关文档：
1. **类声明** - [classes.md](references/...)
- 章节: Declaring a Class
- 匹配: 类定义语法
2. **接口定义** - [interfaces.md](references/...)
- 章节: Declaring an Interface
- 匹配: 类型定义方式
3. **泛型使用** - [generics.md](references/...)
- 章节: Generic Classes
- 匹配: 泛型类语法
5. 深入阅读（可选）
如果检索结果不够详细，打开原文档：
Read: references/arkts-language-guide/02-basic-syntax/classes.md
检查清单
Critical（必须完成）
Warning（建议完成）
Info（可选优化）
决策树
用户查询
│
├─ 查询类型？
│ ├─ 语法规则 → 检索 02-Basic-Syntax
│ ├─ 库使用 → 检索 03-Common-Library
│ ├─ 并发编程 → 检索 04-Concurrency
│ ├─ 运行时 → 检索 05-Runtime
│ ├─ 工具链 → 检索 07-Compilation-Toolchain
│ └─ 迁移 → 检索 09-Migration-Guide
│
├─ 检索结果数量？
│ ├─ 0 个 → 扩大检索范围或建议用户重新描述
│ ├─ 1 个 → 返回详细结果
│ └─ 多个 → 按相关性排序，返回前 N 个
│
├─ 结果验证状态？
│ ├─ snippet_validated → 标注已验证，可信度高
│ └─ doc_only → 标注仅文档，建议用户验证
│
└─ 用户需要更多？
├─ 是 → 打开原文档，提供完整内容
└─ 否 → 结束检索
索引文件说明
doc_index.json
文档索引，包含所有语言指南的元数据：
{
"documents": [
{
"path": "02-Basic-Syntax/classes.md",
"title": "Classes",
"sections": ["Declaring a Class", "Fields", "Methods"],
"keywords": ["class", "field", "method", "constructor"],
"verification_level": "snippet_validated"
}
]
}
snippet_index.json
代码片段索引，包含已验证的代码示例：
{
"snippets": [
{
"file": "02-Basic-Syntax/classes.md",
"line": 15,
"code": "class User { name: string = ''; }",
"validated": true
}
]
}
topic_aliases.json
主题别名映射，用于查询扩展：
{
"aliases": {
"类": ["class", "classes", "类型定义"],
"函数": ["function", "functions", "方法"],
"并发": ["concurrency", "thread", "worker", "taskpool"]
}
}
检索策略
精确匹配
当查询包含明确的技术术语时：
python3 scripts/search_docs.py --query "class declaration" --scope "02-Basic-Syntax"
模糊匹配
当查询描述较为模糊时：
python3 scripts/search_docs.py --query "async task concurrency"
关联检索
当需要查找相关内容时：
python3 scripts/search_docs.py --query "generic class"
python3 scripts/search_docs.py --query "interface generic"
输出格式规范
标准输出
📚 **参考文档**: <文档名称>
📍 **章节**: <章节路径>
💡 **匹配原因**: <一句话说明>
📖 **指导**: <一两句基于文档的指导>
✅ **验证状态**: <snippet_validated/doc_only>
简洁输出
参考: [classes.md](references/...) - 类声明语法
详细输出
📚 **参考文档**: [classes.md](references/arkts-language-guide/02-basic-syntax/classes.md)
📍 **章节路径**: Classes > Declaring a Class
💡 **匹配原因**: 查询涉及类声明语法，该章节详细说明了 class 关键字的使用方法、字段声明和实例创建。
📖 **指导**:
- 使用 `class` 关键字定义类
- 字段必须在类体中声明，不能动态添加
- ArkTS 不支持类表达式，必须使用命名类声明
- 使用 `new` 关键字创建实例
📝 **代码示例**:
```typescript
class User {
name: string = '';
age: number = 0;
}
let user: User = new User();
user.name = 'Alice';
✅ 验证状态: snippet_validated（代码示例已通过验证）
🔗 相关文档:
## 注意事项
- ⚠️ 检索结果基于索引文件，如果文档更新需要重建索引
- ⚠️ 某些文档可能只有英文版本，检索时需使用英文关键词
- ⚠️ 代码示例的验证状态表示是否通过 arkts-cli 验证
- ⚠️ 对于复杂查询，建议多次检索并综合结果
## 相关资源
- [ArkTS 官方文档](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/arkts-get-started)
- [ArkTS API 参考](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/)
- [HarmonyOS 开发指南](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/)
