| name | oh-doc-knowledge-verifier |
| description | 文档知识正确性验证。检视 OpenHarmony API 文档中的技术描述是否与权威标准规范（W3C、CSS 等）、数学定义或行业事实一致。当发现知识性问题时，进一步对照业务代码实现，区分"文档描述错误"、"代码实现错误"或"三方均异常"。触发词：文档描述验证、文档知识正确性、描述是否准确、参数说明验证、文档纠错、文档与代码对照。 |
文档知识正确性验证
Task and Boundaries
验证 OpenHarmony API 文档中的知识性描述是否正确。这类问题主要与代码实现无关，而是文档本身对标准规范、数学定义、技术概念的描述存在错误。
核心工作流：知识验证（对照权威标准）→ 发现问题 → 代码实现二次验证（对照业务代码）→ 判定根因。
适用范围：
- 文档中对标准规范属性/参数的描述（如 SVG transform、CSS 属性等）
- 文档中对数学定义的描述（如变换矩阵、颜色空间、插值公式等）
- 文档中对技术概念的描述（如渲染管线、动画原理等）
- 当知识验证发现文档与标准不一致时，进一步对照业务代码确定实际行为，区分根因类型
不适用：
- 纯代码逻辑层面的"代码与文档不一致"问题
- 文档结构、模板、标签等格式问题
- SDK d.ts 类型定义与文档的一致性
Trigger Signals
- "文档描述是否准确"
- "这个参数说明对不对"
- "文档里说 X，但标准里是 Y"
- "帮我看下这个描述有没有写反"
- "文档纠错"、"描述验证"
- "文档与代码对照"、"看下代码是不是这样实现的"
- "标准说 X，文档说 Y，代码实际是什么"
Initial Checks
- 获取验证目标：用户提供文档片段或属性名 + 具体描述
- 定位文档文件：在文档仓库下搜索
- 提取可验证声明：从文档中识别出所有可验证的知识性陈述
Execution Strategy
步骤 1：声明分类
对每条文档声明判断其知识来源类型，不同类型使用不同的验证源：
| 类型 | 特征 | 验证源 |
|---|
| 标准规范型 | 行为由外部标准（W3C、CSS、IEEE 等）定义 | 标准规范原文 |
| 数学事实型 | 由数学定义决定，不存在歧义 | 数学公式/定义 |
| 竞品对标型 | 同类平台通用行为，多家实现一致 | Android/iOS/Chrome 等文档交叉验证 |
分类判断规则：
- 如果属性/参数来自 W3C 标准（SVG、CSS、DOM 等） → 标准规范型
- 如果描述涉及数学公式、矩阵运算、几何变换 → 数学事实型
- 如果描述的是平台通用行为且无标准约束 → 竞品对标型
- 不确定时，默认按标准规范型处理，尝试查找对应标准
步骤 2：查找权威验证源
按声明类型查找验证源：
标准规范型：
- W3C SVG 规范：
https://www.w3.org/TR/SVG/
- CSS 规范：
https://www.w3.org/Style/CSS/
- Web API 规范：
https://developer.mozilla.org/（MDN 作为标准参考）
- 使用 WebSearch 搜索
{属性名} W3C specification
数学事实型：
- 使用 WebSearch 搜索
{概念} mathematical definition
- 对比多个来源确认数学定义的一致性
竞品对标型：
- Android：
https://developer.android.com/
- iOS：
https://developer.apple.com/
- Web：
https://developer.mozilla.org/
- Flutter：
https://api.flutter.dev/
步骤 3：逐条对比
对每条声明进行对比验证：
文档描述 → 权威验证源描述 → 是否一致
重点关注的高频错误模式：
- 参数作用写反：两个参数的描述互换（如 SVG matrix 的 b/c）
- 方向描述错误：x/y 方向搞反、顺时针/逆时针搞反
- 类型描述错误：整数写成浮点、百分比写成像素等
- 默认值错误：默认值与标准不符
- 枚举值遗漏或错误：遗漏标准枚举值或写错值名
- 作用域描述过宽或过窄：描述的适用范围与标准不符
步骤 4：代码实现二次验证（条件触发）
触发条件： 当步骤 3 发现文档与权威标准不一致时，必须进一步对照业务代码实现，区分根因类型。
核心目的： 仅靠标准对比无法判断是"文档写错了"还是"代码实现错了"——必须看代码实际行为才能下结论。同一份文档可能有三种根因：
| 根因类型 | 文档 | 标准 | 代码 | 处置 |
|---|
| A. 文档错误 | ✗ | ✓ | ✓ | 改文档 |
| B. 代码错误 | ✓ | ✗ | ✗ | 改代码 |
| C. 三方不一致 | ✗ | ✓ | ✗ | 改文档+改代码，并明确文档对齐代码还是标准 |
| D. 平台有意扩展 | ✗ | ✓ | ✗(刻意) | 文档补充"扩展说明" |
验证流程：
- 定位代码仓
- 四层追踪：
- 入口层（前端桥接）：
frameworks/bridge/declarative_frontend/jsview/
- 数据层（属性存储）：
frameworks/core/components_ng/property/、frameworks/core/components/common/properties/
- 处理层（校验/钳位）：
frameworks/core/components_ng/render/、frameworks/core/components/common/painter/
- 渲染层（绘制修正）：
frameworks/core/components_ng/render/adapter/
- 比对代码实际值：找到默认值初始化、钳位逻辑、回退分支
- 判定根因：根据上表归类
代码追踪必须给出：
- 具体文件路径和行号（如
js_view_abstract.cpp:2198）
- 关键代码片段（默认值赋值、条件分支、钳位逻辑）
- 实际输出值（数据层 + 渲染层叠加结果）
禁止的做法：
- 禁止仅凭标准结论就判定"文档错误"——必须确认代码是否与标准一致
- 禁止忽略 API 版本条件分支——
PlatformVersion::VERSION_TEN 等判断可能导致不同 API 版本默认值不同
步骤 5：生成报告
## 文档知识验证报告
### 验证目标
- 文档：{文件名}
- 章节：{章节名}
### 声明验证
| # | 文档描述 | 声明类型 | 验证源 | 验证源内容 | 判定 |
|---|---------|---------|-------|-----------|------|
| 1 | {原文} | {类型} | {来源} | {正确描述} | {一致/不一致} |
### 代码二次验证（仅不一致项）
| # | 文档描述 | 标准规定 | 代码实际 | 根因类型 |
|---|---------|---------|---------|---------|
| 1 | {原文} | {标准} | {代码值} | {A/B/C/D} |
**代码追踪证据：**
| 层级 | 文件:行号 | 关键逻辑 | 输出值 |
|------|----------|---------|-------|
| 入口层 | {path}:{line} | {代码片段} | — |
| 数据层 | {path}:{line} | {代码片段} | {值} |
| 处理层 | {path}:{line} | {代码片段} | {值} |
### 错误详情（如有）
**错误 #1：{根因类型}**
- 文档位置：{文件:行号}
- 文档描述：{原文}
- 标准描述：{标准内容}
- 代码实际：{代码行为}
- 验证依据：{标准链接 + 代码文件:行号}
### 修正建议
{根据根因类型给出针对性建议：
- A 类：改文档对齐标准
- B 类：建议提单改代码
- C 类：分别说明文档/代码的修正方向
- D 类：文档补充"OpenHarmony 相对标准的扩展说明"}
高频错误模式速查
当需要快速判断常见错误类型时，读取 references/common-errors.md
| 错误模式 | 典型表现 | 检查方法 |
|---|
| 参数作用互换 | 两个参数描述写反 | 对比标准定义中每个参数的数学含义 |
| 方向描述错误 | x/y、水平/垂直、顺时针/逆时针搞反 | 查标准定义，数学公式无歧义 |
| 顺序/索引错误 | 参数位置与标准不一致 | 对比标准函数签名的参数顺序 |
| 类型与值域错误 | 取值范围或数据类型描述错误 | 查标准中的类型定义和约束条件 |
Prohibited Practices
- 禁止用代码实现作为标准规范型声明的唯一验证源：代码可能有 bug 或偏差，标准才是权威
- 禁止仅凭标准结论就判定"文档错误"：发现知识不一致时，必须先看代码确认实际行为，区分根因类型（A/B/C/D），再决定改文档还是改代码
- 禁止凭记忆判断参数含义：特别是矩阵、变换等数学概念，必须查定义
- 禁止忽略标准版本差异：SVG 1.1 和 SVG 2 可能有差异，需确认文档引用的版本
- 禁止将竞品文档等同于标准：竞品文档也可能有错，仅作交叉参考
Exceptions and Fallbacks
- 找不到对应标准：扩展搜索范围，或使用竞品文档 + 数学定义交叉验证，并在报告中标注验证置信度
- 标准描述模糊：列出多种可能的理解，分别验证
- 标准版本冲突：以最新正式版标准为准
- 代码路径无法追踪：明确告知用户无法验证，并列出已搜索的路径；不要凭推测下结论
- 代码刻意扩展标准（D 类）：文档应补充"OpenHarmony 相对标准的扩展说明"，而非强制对齐标准
References
