doc-validator

KPC 组件文档校验

本 skill 用于校验 KPC 组件的 API 文档与源码的一致性，确保文档完整准确。

校验流程

1. 收集源码信息

读取组件目录下的所有源码文件：

• index.ts - 主组件，提取 Props 接口、Events 接口、typeDefs、defaults、公共方法
• group.ts / item.ts 等子组件 - 同样提取上述信息
• *.vdt - 模板文件，确认哪些属性实际被使用

关键提取点：

• 属性：从接口定义和 typeDefs 提取属性名、类型、默认值
• 事件：从 Events 接口提取事件名和参数类型
• 方法：从类中提取公共方法签名
• 扩展点：从 Blocks 接口提取扩展点名称

2. 收集文档信息

读取以下文档文件：

• index.md - API 文档，提取所有属性表格：

  ## 组件名
  
  | 属性 | 说明 | 类型 | 默认值 |
  

• demos/*.md - 示例文档，校验示例代码与源码一致性

解析表格内容，记录文档中声明的所有属性、方法、事件。同时校验 demos 中的示例代码是否与实际 API 行为一致。

3. 对比分析

逐项对比，找出以下问题：

demos 文档检查要点：

• 示例中对属性/方法的描述是否准确
• 示例代码中的默认值声明是否与源码一致
• 示例中提到的行为是否与源码逻辑一致

4. 特殊规则

无需文档化的内容：

• 原生 DOM 属性（如 className, style, id 等）
• 原生 DOM 事件（如 onClick, onMouseEnter, keydown, focusout 等）
• 继承自基类的通用属性

原生事件判断规则：

• 事件名直接对应原生 DOM 事件名（如 keydown, focusout, click, blur, focus 等）
• 即使源码 Events 接口中定义了这类事件，也无需文档化
• 仅当事件是组件特有的复合事件（如 change, select, show, hide 等）才需要文档化

无需关注的差异：

• 默认值 undefined 与 false 逻辑等价时（如 disabled 属性），无需指出

需要特别注意的内容：

• 有条件生效的属性：需明确说明生效条件（如 download 仅在 tagName 为 a 时生效）
• 废弃属性：保留文档说明，标注已废弃和替代方案
• 类型应精确：枚举类型不应简单写为 string，应列出所有可选值

修复文档规范

当需要补充类型定义时，遵循以下规范：

1. 使用源码中的类型名称：不要内联类型，使用源码定义的 type 名称（如 ShouldFixParam）

2. 类型定义格式：使用 ```ts 代码块直接给出源码中的类型定义

3. 类型定义位置：放在 # 属性 表格后面，紧接表格，不要分割表格

4. 事件参数格式：事件参数使用函数签名形式，如：

   | clickRow | 点击某行触发 | `(data: T, index: number, key: TableRowKey) => void` |
   

5. 无需重复定义类型：如果类型定义已在文档中以属性表格形式列出（如 AnchorLinkProps 对应 AnchorLink 组件属性），则无需额外补充类型定义

6. 扩展点文档格式：扩展点使用单独的 # 扩展点 章节，格式如下：

   # 扩展点
   
   ## 组件名
   
   | 名称 | 说明 |
   | --- | --- |
   | header | 扩展整个头部内容 |
   

示例：

# 属性

| 属性 | 说明 | 类型 | 默认值 |
| --- | --- | --- | --- |
| shouldFix | 自定义元素固定规则 | `(data: ShouldFixParam) => boolean` | `undefined` |

```ts
type ShouldFixParam = {
    offsetTop?: number,
    offsetBottom?: number,
    viewportHeight?: number
}

事件

## 输出格式

按以下格式输出校验结果：

```markdown
## 组件名

### 遗漏属性

| 属性 | 说明 | 类型 | 默认值 |
|------|------|------|--------|

### 类型需修正

| 属性 | 文档类型 | 源码类型 |
|------|---------|---------|

### 遗漏事件

| 事件 | 参数 |
|------|------|

### 遗漏方法

| 方法 | 说明 | 参数 | 返回值 |
|------|------|------|--------|

### 遗漏扩展点

| 扩展点 | 说明 |
|------|------|

### 其他问题

（描述其他发现的问题）

### demos 文档问题

| 文件 | 问题描述 |
|------|---------|

若无问题，输出：文档与源码一致，未发现问题。

示例

输入：检查 button 组件的文档

处理：

1. 读取 components/button/index.ts，提取 ButtonProps 接口
2. 读取 components/button/index.md，提取属性表格
3. 发现 download 属性在源码中定义但文档未提及
4. 发现 htmlType 类型不够精确（文档写 string，源码是枚举）

输出：

## Button

### 遗漏属性

| 属性 | 说明 | 类型 | 默认值 |
|------|------|------|--------|
| download | 超链接的下载属性，tagName 为 a 时生效 | string | undefined |

### 类型需修正

| 属性 | 文档类型 | 源码类型 |
|------|---------|---------|
| htmlType | string | "submit" \| "reset" \| "button" |