doc-validator

name	doc-validator
description	校验 KPC 组件文档与源码的一致性。当用户询问文档是否有遗漏、错误，检查 API 文档与源码是否一致，或提到"文档校验"、"检查文档"时触发此技能。

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. 对比分析

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

问题类型	说明
属性遗漏	源码有但文档未提及
属性多余	文档有但源码不存在
类型不符	文档类型与源码定义不一致
默认值错误	文档默认值与源码不符
事件遗漏	源码定义的事件未文档化
方法遗漏	公共方法未文档化
扩展点遗漏	源码定义的 Blocks 未文档化
demos 文档错误	示例文档中的描述、默认值等与源码不一致

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
}

事件

事件名	说明	参数
change	固定状态改变时触发	(isFixed: boolean) => void

## 输出格式

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

```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" |