Semi UI Vue AI 元数据

Semi UI Vue 组件的 AI 友好型元数据系统。

概述

此包为 Semi UI Vue 组件提供 AI 可读的组件元数据。它使 AI 代理能够理解、搜索并根据自然语言描述智能推荐组件。

核心功能

• 语义搜索：AI 可以使用自然语言搜索组件
• 自动生成：所有元数据自动从 Markdown 文档提取
• 丰富元数据：包含场景、关键词、属性、使用示例、无障碍信息
• 构建时生成：注册表在构建过程中生成

项目架构

packages/semi-ui-mcp/ai-metadata/
├── src/
│   ├── generators/           # 元数据生成器
│   │   ├── frontmatter.ts    # 从 MD 文件解析 YAML frontmatter
│   │   ├── api-table-parser.ts  # 解析 API 表格和代码示例
│   │   ├── md-parser.ts      # MD 解析入口
│   │   └── registry.ts       # 生成组件注册表
│   ├── search/               # 搜索引擎
│   │   └── engine.ts         # 语义搜索实现
│   └── metadata/
│       └── types.ts          # TypeScript 类型定义
├── dist/
│   ├── registry.ts           # 生成的注册表（70 个组件）
│   ├── registry.js
│   └── registry.d.ts
└── package.json

组件分类

| 分类 | 说明 | |------|------| | data-input | 输入类组件（Input、Select、Checkbox 等） | | data-display | 展示类组件（Table、List、Card 等） | | feedback | 反馈类组件（Toast、Modal、Notification 等） | | navigation | 导航类组件（Menu、Breadcrumb、Pagination 等） | | layout | 布局类组件（Grid、SplitPanel 等） | | utility | 工具类组件（Portal、ResizeObserver） | | plus | Plus 组件 |

用户场景标签

组件被打上相关的用户场景标签：

| 场景标签 | 说明 | |----------|------| | form-submission | 表单提交操作 | | action-trigger | 触发动作/事件 | | confirmation | 确认对话框 | | selection | 选择选项 | | filtering | 过滤数据 | | dialog | 模态对话框 | | notification | 通知/提醒 | | data-display | 展示数据 | | hierarchical-data | 层级数据结构 | | date-selection | 日期选择 | | 以及更多 80+ 场景标签... |

使用方法

自然语言搜索组件

import { searchComponents } from '@transsionfe/semi-ui-vue-ai-metadata/registry';
import { componentRegistry } from '@transsionfe/semi-ui-vue-ai-metadata/registry';

const results = searchComponents({
    description: '需要一个提交按钮',
    scenario: 'form-submission',
    category: 'data-input'
}, componentRegistry);

console.log(results);
// 输出: [Button, ...]

获取组件元数据

import { getComponentMetadata } from '@transsionfe/semi-ui-vue-ai-metadata/registry';
import { componentRegistry } from '@transsionfe/semi-ui-vue-ai-metadata/registry';

const buttonMeta = getComponentMetadata('Button', componentRegistry);
console.log(buttonMeta);
/*
{
    componentName: 'Button',
    displayName: 'Button 按钮',
    description: '用户使用按钮来触发一个操作或者进行跳转。',
    scenarios: ['form-submission', 'action-trigger', 'confirmation', 'navigation'],
    keywords: ['button', '按钮', 'trigger', 'action', 'click', 'navigation'],
    propsMetadata: { ... },
    usageExamples: [ ... ]
}
*/

获取所有组件名称

import { getAllComponentNames } from '@transsionfe/semi-ui-vue-ai-metadata/registry';
import { componentRegistry } from '@transsionfe/semi-ui-vue-ai-metadata/registry';

const names = getAllComponentNames(componentRegistry);
console.log(names);
// 输出: ['Button', 'Input', 'Select', 'Modal', ...] (共 70 个组件)

检查组件是否存在

import { hasComponent } from '@transsionfe/semi-ui-vue-ai-metadata/registry';
import { componentRegistry } from '@transsionfe/semi-ui-vue-ai-metadata/registry';

console.log(hasComponent('Button', componentRegistry));      // true
console.log(hasComponent('NonExistent', componentRegistry)); // false

安装

npm install @transsionfe/semi-ui-vue-ai-metadata

构建

# 安装依赖
npm install

# 构建（自动生成注册表）
npm run build

# 仅生成注册表
npm run generate:registry

# 开发模式（监听）
npm run dev

工作原理

1. MD 文件解析

系统扫描 Markdown 文档文件：

---
localeCode: zh-CN
category: 输入类
title: Button 按钮
brief: 用户使用按钮来触发一个操作或者进行跳转。
---

## API 参考

### Button

| 属性 | 说明 | 类型 | 默认值 |
| ---- | ---- | ---- | ------ |
| type | 按钮类型 | string | "primary" |
| disabled | 禁用状态 | boolean | false |

2. 自动元数据提取

• Frontmatter：提取分类、标题、简介、场景
• API 表格：解析属性、类型、描述、默认值
• 代码示例：提取使用示例和代码片段
• 无障碍信息：解析 ARIA 属性、键盘交互
• 最佳实践：提取推荐和不推荐的用法

3. 智能推断

当 MD 文件没有显式 AI 元数据时，系统会推断：

// 从组件名推断场景
inferScenariosFromName('Button')
// → ['form-submission', 'action-trigger', 'confirmation', 'navigation']

// 从描述生成关键词
generateKeywords('Button', { brief: '用户使用按钮来触发一个操作...' })
// → ['button', '按钮', 'trigger', 'action', 'click', 'navigation']

4. 注册表生成

构建时流程：

1. 扫描 docs 目录下的所有 .md 文件
2. 解析 frontmatter 和 API 表格
3. 提取代码示例和无障碍信息
4. 生成 TypeScript 注册表文件
5. 编译为 JavaScript

AI 使用示例

当 AI 代理需要帮助用户选择组件时：

用户: "我需要一个可以选择的组件，从下拉列表中选择"

AI 搜索:
const results = searchComponents({
    description: '从下拉列表中选择',
    scenario: 'selection'
}, componentRegistry);

// 返回: Select, Cascader, TreeSelect, 等

统计信息

• 组件总数：70
• 有 Props 元数据的组件：65+
• 有使用示例的组件：70
• 有无障碍信息的组件：40+
• 平均每组件关键词数：5-10

贡献

添加新组件

1. 在 packages/docs/src/examples/components/{分类}/{组件名}/index.md 创建 MD 文件
2. 确保 frontmatter 包含必要字段：

   category: 输入类  # 或 展示类、反馈类 等
   title: 组件名称
   brief: 一句话描述

3. 添加正确格式的 API 表格
4. 重新构建：npm run build

更新场景标签

修改 src/generators/frontmatter.ts 中的 inferScenariosFromName()：

const scenariosMap: Record<string, UserScenario[]> = {
    '新组件': ['场景1', '场景2', '场景3'],
    // ...
};

开源协议

MIT