# Oh Doc Knowledge Verifier

> 文档知识正确性验证。检视 OpenHarmony API 文档中的技术描述是否与权威标准规范（W3C、CSS 等）、数学定义或行业事实一致。当发现知识性问题时，进一步对照业务代码实现，区分"文档描述错误"、"代码实现错误"或"三方均异常"。触发词：文档描述验证、文档知识正确性、描述是否准确、参数说明验证、文档纠错、文档与代码对照。

- Skill: `openharmonyinsight/oh-doc-knowledge-verifier` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add openharmonyinsight/oh-doc-knowledge-verifier`
- Raw SKILL.md: https://api.skillmd.com/api/skills/openharmonyinsight/oh-doc-knowledge-verifier/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: openharmonyinsight (https://skillmd.com/u/openharmonyinsight)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/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：生成报告

```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) — 高频文档错误模式库，当需要快速识别常见错误类型时读取