# Doc Validator

> 校验 KPC 组件文档与源码的一致性。当用户询问文档是否有遗漏、错误，检查 API 文档与源码是否一致，或提到"文档校验"、"检查文档"时触发此技能。 Use when this capability is needed.

- Skill: `tomevault-io/doc-validator` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/doc-validator`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/doc-validator/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/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. 对比分析

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

| 问题类型 | 说明 |
|---------|------|
| 属性遗漏 | 源码有但文档未提及 |
| 属性多余 | 文档有但源码不存在 |
| 类型不符 | 文档类型与源码定义不一致 |
| 默认值错误 | 文档默认值与源码不符 |
| 事件遗漏 | 源码定义的事件未文档化 |
| 方法遗漏 | 公共方法未文档化 |
| 扩展点遗漏 | 源码定义的 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. **扩展点文档格式**：扩展点使用单独的 `# 扩展点` 章节，格式如下：
   ```markdown
   # 扩展点

   ## 组件名

   | 名称 | 说明 |
   | --- | --- |
   | header | 扩展整个头部内容 |
   ```

示例：
```markdown
# 属性

| 属性 | 说明 | 类型 | 默认值 |
| --- | --- | --- | --- |
| 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`，源码是枚举）

**输出**：
```markdown
## Button

### 遗漏属性

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

### 类型需修正

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

---
> Source: [ksc-fe/kpc](https://github.com/ksc-fe/kpc) — distributed by [TomeVault](https://tomevault.io).
<!-- tomevault:4.0:skill_md:2026-06-21 -->