tomevault-io 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，应列出所有可选值
修复文档规范
当需要补充类型定义时，遵循以下规范：
使用源码中的类型名称：不要内联类型，使用源码定义的 type 名称（如
ShouldFixParam）类型定义格式：使用 ```ts 代码块直接给出源码中的类型定义
类型定义位置：放在
# 属性表格后面，紧接表格，不要分割表格事件参数格式：事件参数使用函数签名形式，如：
| clickRow | 点击某行触发 | `(data: T, index: number, key: TableRowKey) => void` |无需重复定义类型：如果类型定义已在文档中以属性表格形式列出（如
AnchorLinkProps对应AnchorLink组件属性），则无需额外补充类型定义扩展点文档格式：扩展点使用单独的
# 扩展点章节，格式如下：# 扩展点 ## 组件名 | 名称 | 说明 | | --- | --- | | header | 扩展整个头部内容 |
示例：
# 属性
| 属性 | 说明 | 类型 | 默认值 |
| --- | --- | --- | --- |
| shouldFix | 自定义元素固定规则 | `(data: ShouldFixParam) => boolean` | `undefined` |
```ts
type ShouldFixParam = {
offsetTop?: number,
offsetBottom?: number,
viewportHeight?: number
}
事件
| 事件名 | 说明 | 参数 |
|---|---|---|
| change | 固定状态改变时触发 | (isFixed: boolean) => void |
## 输出格式
按以下格式输出校验结果：
```markdown
## 组件名
### 遗漏属性
| 属性 | 说明 | 类型 | 默认值 |
|------|------|------|--------|
### 类型需修正
| 属性 | 文档类型 | 源码类型 |
|------|---------|---------|
### 遗漏事件
| 事件 | 参数 |
|------|------|
### 遗漏方法
| 方法 | 说明 | 参数 | 返回值 |
|------|------|------|--------|
### 遗漏扩展点
| 扩展点 | 说明 |
|------|------|
### 其他问题
（描述其他发现的问题）
### demos 文档问题
| 文件 | 问题描述 |
|------|---------|
若无问题，输出：文档与源码一致，未发现问题。
示例
输入：检查 button 组件的文档
处理：
- 读取
components/button/index.ts，提取ButtonProps接口 - 读取
components/button/index.md，提取属性表格 - 发现
download属性在源码中定义但文档未提及 - 发现
htmlType类型不够精确（文档写string，源码是枚举）
输出：
## Button
### 遗漏属性
| 属性 | 说明 | 类型 | 默认值 |
|------|------|------|--------|
| download | 超链接的下载属性，tagName 为 a 时生效 | string | undefined |
### 类型需修正
| 属性 | 文档类型 | 源码类型 |
|------|---------|---------|
| htmlType | string | "submit" \| "reset" \| "button" |
Source: ksc-fe/kpc — distributed by TomeVault.