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：生成报告 ```markdown ## 文档知识验证报告 ### 验证目标 - 文档：{文件名} - 章节：{章节名} ### 声明验证 | # | 文档描述 | 声明类型 | 验证源 | 验证源内容 | 判定 | |---|---------|---------|-------|-----------|------| | 1 | {原文} | {类型} | {来源} | {正确描述} | {一致/不一致} | ### 代码二次验证（仅不一致项） | # | 文档描述 | 标准规定 | 代码实际 | 根因类型 | |---|---------|---------|---------|---------| | 1 | {原文} | {标准} | {代码值} | {A/B/C/D} | **代码追踪证据：** | 层级 | 文件:行号 | 关键逻辑 | 输出值 | |------|----------|---------|-------| | 入口层 | {path}:{line} | {代码片段} | — | | 数据层 | {path}:{line} | {代码片段} | {值} | | 处理层 | {path}:{line} | {代码片段} | {值} | ### 错误详情（如有） **错误 #1：{根因类型}** - 文档位置：{文件:行号} - 文档描述：{原文} - 标准描述：{标准内容} - 代码实际：{代码行为} - 验证依据：{标准链接 + 代码文件:行号} ### 修正建议 {根据根因类型给出针对性建议： - A 类：改文档对齐标准 - B 类：建议提单改代码 - C 类：分别说明文档/代码的修正方向 - D 类：文档补充"OpenHarmony 相对标准的扩展说明"} ``` ## 高频错误模式速查 > 当需要快速判断常见错误类型时，读取 [references/common-errors.md](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](references/common-errors.md) — 高频文档错误模式库，当需要快速识别常见错误类型时读取