hmos-arkui-knowledge-retriever

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 的针对性检索环节

核心原则

1. 版本敏感：关注 API version 标注和废弃标记
2. 来源标注：每个关键结论标注知识库来源路径

工作流程

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 字段标明来源库。

# ArkTS 查询（自动路由到 knowledges）
python {skill_dir}/scripts/run.py query "LazyForEach IDataSource" --top-k 3 --include-code --format json

# NDK / C-API 查询（自动路由到 ndk-knowledges）
python {skill_dir}/scripts/run.py query "OH_NativeXComponent 怎么用" --top-k 3 --include-code --format json

# 跨域查询（XComponent 等，两库合查）
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

# 完整文档（关闭 compact 和去重）
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：

# 规则/约束/反直觉行为类问题：额外强制检索 18-arkts-rules，提高 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: 组织检索结果

将检索到的内容按用户问题的结构组织回答：

1. 直接回答：用检索结果中的权威文档回答问题
2. 接口签名：附上完整的 API 接口定义（参数名、类型、顺序）
3. 代码示例：附上知识库中的用法示例
4. 来源标注：标注每条关键信息的知识库路径

知识库覆盖范围

本 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篇)

检索结果可信度判断

1. API version 标注：文档中明确标注 "从 API version X 开始支持" → 高可信
2. 废弃标记：文档中有 "从 API version X 开始废弃" → 必须遵循，提示用户不可用
3. V1/V2 标记：文档在 v1/ 或 v2/ 目录下 → 明确版本归属
4. 无版本标注：视为不确定，建议用户额外确认