openharmonyinsight/oh-doc-knowledge-verifier

文档知识正确性验证

Task and Boundaries

验证 OpenHarmony API 文档中的知识性描述是否正确。这类问题主要与代码实现无关，而是文档本身对标准规范、数学定义、技术概念的描述存在错误。

核心工作流：知识验证（对照权威标准）→ 发现问题 → 代码实现二次验证（对照业务代码）→ 判定根因。

适用范围：

• 文档中对标准规范属性/参数的描述（如 SVG transform、CSS 属性等）
• 文档中对数学定义的描述（如变换矩阵、颜色空间、插值公式等）
• 文档中对技术概念的描述（如渲染管线、动画原理等）
• 当知识验证发现文档与标准不一致时，进一步对照业务代码确定实际行为，区分根因类型

不适用：

• 纯代码逻辑层面的"代码与文档不一致"问题
• 文档结构、模板、标签等格式问题
• SDK d.ts 类型定义与文档的一致性

Trigger Signals

• "文档描述是否准确"
• "这个参数说明对不对"
• "文档里说 X，但标准里是 Y"
• "帮我看下这个描述有没有写反"
• "文档纠错"、"描述验证"
• "文档与代码对照"、"看下代码是不是这样实现的"
• "标准说 X，文档说 Y，代码实际是什么"

Initial Checks

1. 获取验证目标：用户提供文档片段或属性名 + 具体描述
2. 定位文档文件：在文档仓库下搜索
3. 提取可验证声明：从文档中识别出所有可验证的知识性陈述

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：逐条对比

对每条声明进行对比验证：

文档描述 → 权威验证源描述 → 是否一致

重点关注的高频错误模式：

1. 参数作用写反：两个参数的描述互换（如 SVG matrix 的 b/c）
2. 方向描述错误：x/y 方向搞反、顺时针/逆时针搞反
3. 类型描述错误：整数写成浮点、百分比写成像素等
4. 默认值错误：默认值与标准不符
5. 枚举值遗漏或错误：遗漏标准枚举值或写错值名
6. 作用域描述过宽或过窄：描述的适用范围与标准不符

步骤 4：代码实现二次验证（条件触发）

触发条件： 当步骤 3 发现文档与权威标准不一致时，必须进一步对照业务代码实现，区分根因类型。

核心目的： 仅靠标准对比无法判断是"文档写错了"还是"代码实现错了"——必须看代码实际行为才能下结论。同一份文档可能有三种根因：

| 根因类型 | 文档 | 标准 | 代码 | 处置 | |---------|------|------|------|------| | A. 文档错误 | ✗ | ✓ | ✓ | 改文档 | | B. 代码错误 | ✓ | ✗ | ✗ | 改代码 | | C. 三方不一致 | ✗ | ✓ | ✗ | 改文档+改代码，并明确文档对齐代码还是标准 | | D. 平台有意扩展 | ✗ | ✓ | ✗(刻意) | 文档补充"扩展说明" |

验证流程：

1. 定位代码仓
2. 四层追踪：
   • 入口层（前端桥接）：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/
3. 比对代码实际值：找到默认值初始化、钳位逻辑、回退分支
4. 判定根因：根据上表归类

代码追踪必须给出：

• 具体文件路径和行号（如 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

1. 禁止用代码实现作为标准规范型声明的唯一验证源：代码可能有 bug 或偏差，标准才是权威
2. 禁止仅凭标准结论就判定"文档错误"：发现知识不一致时，必须先看代码确认实际行为，区分根因类型（A/B/C/D），再决定改文档还是改代码
3. 禁止凭记忆判断参数含义：特别是矩阵、变换等数学概念，必须查定义
4. 禁止忽略标准版本差异：SVG 1.1 和 SVG 2 可能有差异，需确认文档引用的版本
5. 禁止将竞品文档等同于标准：竞品文档也可能有错，仅作交叉参考

Exceptions and Fallbacks

1. 找不到对应标准：扩展搜索范围，或使用竞品文档 + 数学定义交叉验证，并在报告中标注验证置信度
2. 标准描述模糊：列出多种可能的理解，分别验证
3. 标准版本冲突：以最新正式版标准为准
4. 代码路径无法追踪：明确告知用户无法验证，并列出已搜索的路径；不要凭推测下结论
5. 代码刻意扩展标准（D 类）：文档应补充"OpenHarmony 相对标准的扩展说明"，而非强制对齐标准

References

• references/common-errors.md — 高频文档错误模式库，当需要快速识别常见错误类型时读取