| name | hmos-arkui-knowledge-retriever |
| description | ArkUI 知识检索层，按问题语境自动路由到 ArkTS 声明式或 NDK(C-API)知识库进行精准检索，不涉及代码生成或修改。触发场景：(1) 用户查询 ArkUI/ArkTS API 用法、参数细节或版本支持 (2) 验证组件/装饰器的正确用法 (3) 排查 ArkUI 编译错误码或运行时异常 (4) 询问状态管理 V1/V2 差异或迁移 (5) 查询 NDK / Native / C-API 接口或头文件 (6) 其他 skill 调用检索获取 API 证据。 |
ArkUI Knowledge Retriever
使用场景
| 场景 | 用户输入特征 | 示例 |
|---|
| API 用法查询 | 询问特定 API 的参数、类型、版本 | "@Local 装饰器怎么用"、"Navigation 页面跳转参数" |
| 用法验证 | 已有代码需确认 API 正确性 | "ForEach 的第三个参数是什么"、"@Param 能不能装饰组件内变量" |
| 错误排查 | 编译错误码或运行时异常 | "错误码 100060 是什么意思"、"LazyForEach 数据源报错" |
| 方案对比 | 多个技术方案需要选型 | "V1 和 V2 状态管理有什么区别"、"Navigation 和 Router 哪个好" |
| NDK/C-API 查询 | 询问 Native 侧 C 接口、头文件、NDK 用法 | "OH_NativeXComponent 怎么用"、"native_node 如何创建节点" |
| 被其他 skill 调用 | develop-skill 在方案设计后调检索验证 | 开发流程中 Step 2 的针对性检索环节 |
核心原则
- 版本敏感：关注 API version 标注和废弃标记
- 来源标注：每个关键结论标注知识库来源路径
工作流程
Step 1: 理解查询意图 + 判断技术栈语境
分析用户问题，确定检索目标。本 skill 维护两个独立知识库，run.py 会根据查询语境自动路由：
| 技术栈 | 信号词 | 路由到 |
|---|
| ArkTS 声明式 | @装饰器、ArkTS、声明式、ForEach/LazyForEach、状态管理、NavDestination | references/knowledges/ |
| NDK / C-API | NDK、capi、native、OH_Native*、ArkUI_Native*、native_node、napi、C++ | references/ndk-knowledges/ |
| 跨域(两库合查) | XComponent、EGL/OpenGLES、surface | 两个库都查并合并 |
路由由 retriever.detect_domain() 自动完成；可用 --domain ndk|arkts|both 手动覆盖。无强信号时默认按 ArkTS 处理。关键词提取策略：
| 查询类型 | 关键词提取策略 | 示例 |
|---|
| 具体 API 查询 | 提取 API 名称 + 所属领域 | "@Local 装饰器" → @Local 组件内状态 |
| 概念性问题 | 提取核心概念词 | "V1 V2 有什么区别" → V1 V2 状态管理 迁移 |
| 错误排查 | 提取错误码或异常关键词 | "报错 100005" → 错误码 100005 |
| 用法验证 | 提取待验证的 API + 用法描述 | "ForEach 第三个参数" → ForEach keyGenerator |
| 被其他 skill 调用 | 直接使用调用方提供的关键词 | 开发流程中的针对性检索 |
Step 2: 执行检索
默认自动路由：无需指定知识库，run.py 根据 query 语境选 ArkTS 或 NDK 库（跨域两库合查）。返回结果中 routed_to 标明实际查询的库，每条结果的 knowledge_base 字段标明来源库。
python {skill_dir}/scripts/run.py query "LazyForEach IDataSource" --top-k 3 --include-code --format json
python {skill_dir}/scripts/run.py query "OH_NativeXComponent 怎么用" --top-k 3 --include-code --format json
python {skill_dir}/scripts/run.py query "XComponent surface" --top-k 5 --include-code --format json
python {skill_dir}/scripts/run.py query "native_node" --domain ndk --top-k 3 --include-code --format json
python {skill_dir}/scripts/run.py query "@Local 装饰器" --category 02-state-management --include-code --format json
python {skill_dir}/scripts/run.py query "Navigation 页面跳转" --full-content --no-compact --no-dedup --include-code --format json
检索策略：优先检索目标 API 的接口定义 → 再检索用法示例 → 最后检索已知限制和注意事项。
⚠️ 规则/约束/行为反直觉类问题必检 18-arkts-rules/：在"错误排查"与"用法验证"场景中，凡涉及约束 / 禁止项 / 报错行为 / 反直觉行为 / "为什么 X 不生效" / 时序 / 混用边界的问题，18-arkts-rules/ 的规则文件往往比 01-basics/、02-state-management/、06-interaction/ 的长文档更对症。
该分类不止是装饰器约束——它覆盖 7 个独立主题（焦点 / 手势事件 / 组件生命周期 / @Builder 族 / 冻结 / 复用 / 样式），每个都藏着高频反直觉行为。但这些规则文件篇幅短、关键词命中少，极易被长文档挤出 top-k 而漏召回。务必在常规检索之外，用 --category 强制针对性检索，并适当提高 --top-k：
python {skill_dir}/scripts/run.py query "stopPropagation 手势 父组件" --category 18-arkts-rules --top-k 8 --include-code --format json
若 --category 模糊检索仍返回空（短文件关键词不命中），直接 Read 下表对应文件全文——这些文件普遍很短（最长不过数百行），全文读取最稳妥，切忌凭"分类描述"主观判断"不归该分类"而跳过。
18-arkts-rules/ 主题映射（按问题特征定位必检文件）：
| 文件 | 主题 | 高频触发关键词 / 典型反直觉行为 |
|---|
arkts-focus-rules.md | 焦点系统 | 焦点/获焦/走焦、requestFocus、defaultFocus、tabIndex、tabStop、focusable、焦点组、onKeyEvent、Tab/方向键 → 「defaultFocus 不可与 FocusPriority 混用」「tabIndex 不可与 focusScopeId 同设」「焦点组不可与 tabIndex 混用」「容器叶子节点 focusable(true) 仍无法获焦」 |
arkts-interaction-rules.md | 手势/事件响应链 | 手势、stopPropagation、事件冒泡、触摸测试/hitTest、onTouch、onTouchIntercept、onGestureCollectIntercept、onChildTouchTest、onGestureRecognizerJudgeBegin、手势冲突/竞争 → 「stopPropagation 不中断父组件手势」「手势为非冒泡事件」「Touch 与手势是两条独立响应链」「各交互 API 顺序固定不可调换」 |
arkts-ui-basic-rules.md | 自定义组件/生命周期 | aboutToAppear/Disappear、onPageShow、@ComponentInit/Appear/Built/Disappear、getCurrentState、onMeasureSize/onPlaceChildren、跨 Ability 迁移 → 「最小化/后台不触发 @ComponentDisappear」「嵌套创建父 BUILT 后才执行子 Appear」「生命周期装饰器不能有入参」「与 @Computed 联用不生效」「aboutToDisappear 中禁改 @Link」 |
arkts-ui-extension.md | @Builder/@LocalBuilder/@BuilderParam/wrapBuilder/mutableBuilder | @Builder/@LocalBuilder/@BuilderParam、wrapBuilder/mutableBuilder、MutableBinding、UIUtils.makeBinding、按引用/按值/按回调传递、尾随闭包、this 指向 → 「@Builder 两参数以上不刷新」「仅 {} 字面量算按引用」「禁改入参(错误码140109)」「传 class 对象不刷新」「禁 @Watch 内执行 @Builder」「mutableBuilder 二次赋值才生效」 |
arkts-ui-freeze-rules.md | 组件冻结 | freezeWhenInactive、active/inactive、@Reusable/@ReusableV2 冻结、inheritFreezeOptions、BuilderNode 冻结、LazyForEach/Repeat 冻结、延后刷新 → 「active/inactive ≠ 可见性」「V2 复用自动冻结且解冻不补刷新」「冻结+复用混用解冻不触发 @Watch」「BuilderNode 中间层级需三方都配置才冻结」 |
arkts-ui-reuse-rules.md | 组件复用 | @Reusable/@ReusableV2、reuseId、aboutToReuse/Recycle、复用池、reusePool/poolAccepts、全局复用池、Repeat template → 「缓存池归父自定义组件→跨容器可复用」「V1 aboutToReuse 禁改父状态需 setTimeout」「V2 自动重置状态(按定义顺序)」「V1/V2 复用不可互相包含」「V2 复用不能直接用于 Repeat template」「@Reusable+ComponentContent 会 crash」 |
arkts-ui-styles-rules.md | @Styles/@Extend/@AnimatableExtend | @Styles、@Extend、@AnimatableExtend、样式封装 → 「@Extend 仅全局且必须指定组件」「@Styles 不支持参数」「两者都不支持 if/else 逻辑分支」「@AnimatableExtend 参数必须 number 或 AnimatableArithmetic」 |
Step 3: 组织检索结果
将检索到的内容按用户问题的结构组织回答：
- 直接回答：用检索结果中的权威文档回答问题
- 接口签名：附上完整的 API 接口定义（参数名、类型、顺序）
- 代码示例：附上知识库中的用法示例
- 来源标注：标注每条关键信息的知识库路径
知识库覆盖范围
本 skill 维护两个独立知识库，检索时按语境自动路由。
ArkTS 声明式（references/knowledges/，532 篇）
01-basics/ → 自定义组件、声明式UI、生命周期、基础概念 (12篇)
02-state-management/ → V1(@State/@Prop/@Link等) + V2(@Local/@Param等) + 迁移指南 (74篇)
03-layout/ → Flex/Grid/List/Scroll/RelativeContainer 等布局 (54篇)
04-components/ → 各类组件 + 组件公共接口 (118篇)
05-animation/ → 属性动画/显式动画/转场动画 (27篇)
06-interaction/ → 手势/触摸/按键/拖拽/焦点/事件系统 (51篇)
07-navigation/ → Navigation/NavDestination/路由 (41篇)
08-dialog-menu/ → 弹窗/菜单/下拉选择 (30篇)
09-rendering/ → ForEach/LazyForEach/Repeat/条件渲染 (25篇)
10-extension/ → RenderNode/自定义节点/Builder (20篇)
11-theme-style/ → 主题/样式系统 + @Extend/@Styles (18篇)
12-i18n/ → 国际化 (1篇)
13-accessibility/ → 无障碍 (4篇)
14-performance/ → 性能优化 (7篇)
15-advanced/ → 高级特性 (13篇)
16-window/ → 窗口管理 (7篇)
17-error-code/ → 错误码 (30篇)
NDK / C-API（references/ndk-knowledges/，262 篇）
guide/ → 开发指南:构建组件/事件/动画/布局/嵌入ArkTS/多线程 (32篇)
node/ → 节点系统:native_node.h + attributetype + node option/event/border (38篇)
text/ → 文本/选择/轮播:text/picker/swiper/styled-string/menu (29篇)
gesture-drag/ → 手势/触摸/拖拽:gesture/touch/drag 事件与识别器 (23篇)
window-display/ → 窗口/显示:windowmanager/displaymanager/画中画 (23篇)
animation/ → 动画:animate/animator/curve/transition/motionpath (20篇)
accessibility/ → native 无障碍接口 (16篇)
xcomponent/ → OH_NativeXComponent surface/事件 (16篇)
layout/ → 布局:grid/list/waterflow/margin/align (14篇)
render/ → 渲染/绘制:render/rendernode/shape/draw (9篇)
dialog/ → 对话框:native_dialog/customdialog (8篇)
common-types/ → 通用类型/接口/事件总览/杂项 (34篇)
检索结果可信度判断
- API version 标注：文档中明确标注 "从 API version X 开始支持" → 高可信
- 废弃标记：文档中有 "从 API version X 开始废弃" → 必须遵循，提示用户不可用
- V1/V2 标记：文档在
v1/ 或 v2/ 目录下 → 明确版本归属
- 无版本标注：视为不确定，建议用户额外确认
