我们公司的组件库有一百多个组件，但文档几乎为零。新同事来了，不知道每个组件怎么用、支持哪些 props，只能翻源码。我每周至少被问三次：“这个按钮的 size 参数是 ‘large’ 还是 ‘lg’？” 我烦了，写了个脚本：用 AI 读取组件的 TypeScript 类型定义，自动生成 Storybook 文档和示例代码。现在每次提交组件，CI 自动跑一遍，文档实时更新。同事再也不问我了，CTO 看到说：“这个自动化做得好，省了半个前端的人力。”

前言

组件文档的重要性，每个前端都懂。但现实是：业务需求压过来，谁有时间写文档？结果就是组件库越来越膨胀，文档越来越荒废。新人来了，要么猜，要么问，要么翻源码。

我试过手动写 Storybook，一个组件写半小时，一百个组件写完，我可能已经离职了。后来我想：能不能让 AI 自动生成？组件的 props 类型、默认值、描述，不都写在代码里了吗？让 AI 提取出来，再套个模板，不就完事了？

今天我把这套自动化流程拆给你看：怎么用 AI 解析 TS 类型，怎么生成 Storybook 的 stories 文件，怎么集成到 CI。以后你只需要写好组件，文档的事交给 AI。

金句：最好的文档不是 “人写的”，而是 “代码里长出来的”。

一、痛点：手动写文档的三大坑

痛点	具体表现
耗时长	一个组件平均花 30 分钟写文档（props 表格 + 示例代码 + 说明）
不同步	改了组件 props，忘了改文档，文档变成 “废纸”
没人愿意写	团队集体拖延，文档库永远是 “建设中”

我们团队曾试图用react-docgen-typescript自动提取 props，但它只能生成原始 JSON，还得人工转成 Markdown 或 Storybook。而且它不懂业务描述，比如 “size 的 large 表示大号按钮，用于主操作”，这种描述还是得人写。

AI 的出现正好填补了这个缺口：它既能解析类型，又能生成自然语言描述，还能帮你写示例代码。

二、我是怎么做的？三步全自动

第一步：提取组件类型信息

我用react-docgen-typescript把组件的 props、类型、默认值、是否必填提取成 JSON。写一个脚本extract-props.ts：

import * as docgen from 'react-docgen-typescript';

const options = {
  savePropValueAsString: true,
  shouldExtractLiteralValuesFromEnum: true,
};

const parser = docgen.withCustomConfig('./tsconfig.json', options);
const docs = parser.parse('./src/components/Button/index.tsx');

// docs[0] 结构：
// {
//   displayName: 'Button',
//   props: {
//     size: { type: { name: "'small' | 'medium' | 'large'" }, required: false, defaultValue: 'medium' },
//     children: { type: { name: 'ReactNode' }, required: true }
//   }
// }

第二步：用 AI 生成 Storybook 内容

把提取的 JSON 喂给 AI，提示词：

你是一名前端技术文档专家。请根据以下组件的 props 信息，生成一份 Storybook 的 stories 文件代码。

要求：

1. 为每个 prop 生成控制台（controls）配置
2. 生成至少 3 个示例：基础用法、不同尺寸、自定义样式
3. 用 Markdown 格式输出，包含组件描述和 Props 表格

组件信息：

[粘贴上一步的JSON]

AI 会输出类似这样的 Storybook 代码：

// Button.stories.tsx
import type { Meta, StoryObj } from '@storybook/react';
import { Button } from './Button';

const meta: Meta<typeof Button> = {
  title: 'Components/Button',
  component: Button,
  parameters: {
    docs: {
      description: {
        component: '通用按钮组件，支持三种尺寸和两种主题色。主要用于表单提交、弹窗确认等操作。'
      }
    }
  },
  argTypes: {
    size: {
      control: 'radio',
      options: ['small', 'medium', 'large'],
      description: '按钮尺寸'
    },
    children: { control: 'text', description: '按钮内容' }
  }
};

export default meta;

export const Default: StoryObj<typeof Button> = {
  args: { children: '按钮', size: 'medium' },
};

export const Large: StoryObj<typeof Button> = {
  args: { children: '大按钮', size: 'large' },
};

export const Small: StoryObj<typeof Button> = {
  args: { children: '小按钮', size: 'small' },
};

第三步：集成到 CI

我在项目的.github/workflows/docs.yml里加了一个 job：

- name: Auto generate Storybook
  run: |
    npm run extract:props
    npm run ai:generate-stories
    npm run build:storybook
  env:
    OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}

每次git push到 main 分支，GitHub Actions 自动跑一遍，重新生成文档并部署到 GitHub Pages。从此文档永远最新。

金句：AI 自动生成文档，让 “文档过时” 成为历史。

三、实测效果：节省了多少时间？

我们组件库有 87 个组件，人工写一个平均 30 分钟，总计 43.5 小时。用 AI 自动生成后，每个组件约 2 分钟（人工 review 和微调），总计约 3 小时。节省了 93% 的时间。

指标	手工	AI 辅助	变化
单组件文档耗时	30 分钟	2 分钟	↓ 93%
文档与代码同步率	经常滞后	实时同步	-
新人上手询问次数（月均）	12 次	2 次	↓ 83%

同事现在想查组件用法，直接打开 Storybook。没人再问我了，我可以安心写代码。

四、注意事项（坑点）

• AI 会脑补不存在的 props：有时会生成示例里用了你没提供的 prop，必须人工删掉。
• 复杂泛型可能解析错：react-docgen-typescript对高阶组件、泛型组件的解析不够准，需要手动修正输入 JSON。
• 保护公司组件库隐私：不要直接把整个组件库代码喂给云端 AI。可以用本地模型（如 Ollama + CodeLlama），或者只传类型 JSON（不传实现细节）。
• 示例代码要人工跑一遍：AI 生成的示例可能无法直接运行（比如忘记 import 样式），你至少编译一次确保没语法错误。

五、完整的 Prompt 模板（复制可用）

# 角色
你是一名前端技术文档专家，擅长为React组件生成Storybook文档。

# 任务
根据以下组件的props信息，生成一个完整的Storybook stories文件。

# 输入格式
JSON对象，包含displayName和props

# 输出要求
1. 使用TypeScript语法
2. 包含meta配置（title, component, parameters, argTypes）
3. 生成至少3个Story：Default, Large, Small（或其他合适的变体）
4. 在parameters.docs.description.component中写一段组件用途说明
5. 每个argType的control要合理（radio/select/text等）

# 组件信息
[粘贴JSON]

六、写在最后

以前我觉得文档是 “良心活”，写了加分，不写也没人扣分。现在 AI 帮我自动生成，我才发现：文档不是负担，而是杠杆——它让组件的复用率大大提升，团队效率自然就上去了。

如果你也被组件文档折磨过，或者想知道怎么把 AI 接入你的工程化流程，点个赞让我看到。