Trae组件库文档自动化生成需五步：一、用Trae CLI初始化项目；二、在源码嵌入JSDoc+Trae标记；三、配置velite.config.js启用组件集合；四、用trae-docs启动本地服务；五、通过CI/CD自动构建发布。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
如果您正在使用Trae框架开发前端组件库，但尚未实现文档的自动化生成，则可能是由于缺乏标准化的元数据提取机制或未集成合适的文档构建工具链。以下是解决此问题的步骤：
一、基于Trae CLI初始化组件库结构
Trae官方提供配套的CLI工具，用于快速搭建符合规范的组件库项目骨架，内置文档生成入口和约定式目录结构，确保源码与文档模板天然对齐。
1、全局安装Trae CLI工具：npm install -g @trae/cli
2、创建新组件库项目：trae create my-component-library --template=component-lib
立即学习“前端免费学习笔记（深入）”；
3、进入项目并运行初始化脚本：cd my-component-library && npm run init:docs
二、在组件源码中嵌入JSDoc+Trae专属标记
Trae文档系统依赖静态分析能力，通过解析带有特定语义的JSDoc注释提取props、events、slots及示例代码，要求注释格式严格遵循Trae Schema规范，否则无法被velite或trae-docs插件识别。
1、为组件导出对象添加@component标签，并注明分类与状态：/** @component {name: 'Button', category: 'ui', status: 'stable'} */
2、对每个prop使用@prop声明类型、默认值与描述：/** @prop {string} [variant='primary'] - 按钮样式变体 */
3、在组件文件末尾添加@example区块，内含可执行的Trae SFC代码片段：/** @example <Button variant="outline">Click me</Button> */
三、配置velite.config.js启用Trae文档集合
Velite作为Trae生态默认的静态内容生成器，需显式声明components集合，并绑定Trae专用的schema校验与transform逻辑，以支持从SFC中提取setup语法糖定义的响应式API。
PigX UI Pro 前端开发指南 - Vue 3 + TypeScript + Element Plus。当用户提到 PigX UI、PigX 前端、lgb-mgui 项目、Vue 3 企业级后台开发、Element Plus 后台开发时使用此技能。
1、打开项目根目录下的velite.config.js文件
2、导入Trae预设配置：import { traecomponents } from '@trae/docs-config'
3、在collections中注册组件集合：components: traecomponents({ srcDir: './src/components' })
四、使用trae-docs启动本地文档服务
trae-docs是Trae官方维护的轻量级文档服务运行时，无需构建即可实时预览解析结果，支持热重载和交互式Props调试面板，适用于开发阶段快速验证文档完整性。
1、安装文档运行时依赖：npm install --save-dev @trae/docs
2、在package.json中添加脚本："docs:dev": "trae-docs dev"
3、启动服务并访问http://localhost:5173：npm run docs:dev
五、集成CI/CD触发文档自动构建与发布
通过GitHub Actions或GitLab CI监听docs/**与src/components/**路径变更，在推送至main分支时自动执行文档构建并部署至GitHub Pages，确保文档始终与最新代码版本一致。
1、在项目根目录创建.github/workflows/docs.yml
2、配置on.push.paths包含src/components/**和docs/**
3、在jobs中调用trae-docs build并使用peaceiris/actions-gh-pages部署：npm run docs:build && gh-pages -d dist/docs -r https://token@github.com/owner/repo.git
