kpc-doc

将 KPC (King Design) 组件库文档转换为 AI Agent 友好的结构化 Markdown，通过 CLI 命令按需查询。

功能特性

• 58 个组件完整文档收录（属性、方法、事件、扩展点、示例）
• 按需加载 — 清单文件仅 7KB，查询时按组件名加载单个文件
• 框架适配 — 支持 react / vue / intact，自动切换包名和语法说明
• VDT → React 自动转换 — 无原生 React 代码的示例自动转换为 JSX
• 多种输出 — Markdown（默认）、JSON、紧凑模式

快速开始

# 安装依赖
npm install

# 构建数据（需要同级目录存在 ../kpc 源码）
npm run build:data

# 构建 CLI
npm run build

# 使用
node dist/cli.js button                    # 查看 Button 完整文档
node dist/cli.js button table form         # 批量查看多个组件
node dist/cli.js table --type props        # 仅查看 Table 属性
node dist/cli.js dialog --type demos       # 仅查看 Dialog 示例
node dist/cli.js select --framework vue    # Vue 框架输出
node dist/cli.js --list                    # 列出所有组件
node dist/cli.js --search 选择             # 搜索组件

开发模式

# 直接运行（不需要先 build）
npx tsx src/cli.ts button --type demos --framework react

# 批量查询多个组件
npx tsx src/cli.ts button table form --type props --framework react

CLI 参数

kpc-doc [components...] [options]

Arguments:
  components             组件名，支持多个 (如 button Table date-picker)

Options:
  -f, --framework <fw>   目标框架: react | vue | intact (默认: react)
  -t, --type <type>      信息类型: props | events | methods | slots | demos | all (默认: all)
  -l, --list             列出所有可用组件
  -s, --search <keyword> 按关键词搜索组件
  --compact              紧凑输出 (省略样式)
  --json                 JSON 格式输出
  -V, --version          版本号
  -h, --help             帮助信息

批量查询说明：传入多个组件名时，Markdown 输出以 --- 分隔，JSON 输出为数组。不存在的组件会自动跳过并在 stderr 提示。

数据来源与构建

数据流

third-party/kpc/                          ← KPC 源码（外部依赖）
  components/button/index.md              ← 组件 API 文档
  components/button/demos/basic/index.md  ← 示例代码
  ...
        │
        ▼  npm run build:data
        │
src/data/                                 ← 生成的结构化数据
  index.json                              ← 清单 (~7KB)
  components/button.json                  ← 按组件拆分
  components/table.json
  ...

数据来源

src/data/ 下的文件由 scripts/build-data.ts 从 KPC 源码（默认路径 ../kpc/）的 Markdown 文档中解析生成。构建脚本会：

1. 扫描 kpc/components/*/index.md，提取属性、方法、事件、扩展点表格
2. 扫描 kpc/components/*/demos/*/index.md，提取示例代码（含多框架代码块）
3. 输出为按组件拆分的 JSON 文件

如果 KPC 源码不在默认路径，可指定：

npm run build:data -- --kpc-root /path/to/kpc

数据文件结构

src/data/
  index.json              ← 清单 (库元信息 + 组件列表, ~7KB)
  components/
    button.json           ← Button 完整文档 (~15KB)
    table.json            ← Table 完整文档 (~88KB)
    ...                   ← 共 58 个文件

注：src/data/ 目录为构建产物。如需更新数据，重新执行 npm run build:data 即可。

项目结构

src/
  cli.ts                  ← CLI 入口
  index.ts                ← 编程 API 导出
  core/
    types.ts              ← 通用类型定义
    registry.ts           ← 组件注册中心 (懒加载)
    normalizer.ts         ← 名称标准化
  parser/
    markdown.ts           ← 通用 Markdown 解析器
    kpc.ts                ← KPC 文档适配解析器
  formatter/
    output.ts             ← Markdown / JSON 格式化
    vdt-to-react.ts       ← VDT → React 自动转换器
scripts/
  build-data.ts           ← 数据构建脚本

设计原则

• 低耦合 — 通用解析器 (parser/markdown.ts) 和库特定适配器 (parser/kpc.ts) 分离，未来可扩展到其他组件库
• 预编译 — 文档在构建时解析为 JSON，运行时零文件系统依赖
• 按需加载 — 清单与组件数据分离，查询单组件不加载全部数据