2-09 · llms 文档与 MCP Server：组件库的 AI 生态

# xiaoye-components

> 一套面向中后台场景的 Vue 3 组件库，基于 TypeScript 开发，包含 72 个基础组件和 31 个增强业务组件。所有基础组件前缀为 `xy-`（如 `xy-button`），增强组件前缀为 `xy-`（如 `xy-pro-table`），TypeScript 标识符使用 PascalCase（如 `XyButton`、`XyProTable`）。

## 安装

```bash
# 基础组件库
npm install xiaoye-components

# 增强业务组件库
npm install xiaoye-pro-components
```

## 全局注册

```ts
import { createApp } from 'vue'
import XyComponents from 'xiaoye-components'
import 'xiaoye-components/style.css'

const app = createApp(App)
app.use(XyComponents)
```

## 组件选择指南

### 弹层与浮层：该用哪个？

- **Dialog**：阻断式录入、二次确认、强提示。需要用户显式处理才能继续。
- **Drawer**：侧边滑出，适合详情展示、筛选面板、辅助录入，不阻断主内容。
- **Popover**：轻量气泡卡片，补充说明或简单操作，点击外部关闭。
- **Tooltip**：纯文字提示，不承载交互。
- **Popconfirm**：气泡确认框，适合轻量级删除/停用确认。
- **Message**：全局轻提示，自动消失，不阻断操作。
- **Notification**：全局通知，可手动关闭，适合系统级消息。

### 表单：该用哪个？

- **Form + FormItem**：基础表单，手动组织字段和校验。
- **SearchForm**：搜索筛选栏，声明式字段配置，自动折叠/展开。
- **ProForm**：增强表单，JSON Schema 驱动，支持联动和动态字段。
- **DialogForm / DrawerForm**：弹窗/抽屉内的表单，自带打开/关闭和提交逻辑。
- **StepsForm**：分步表单，向导式多步录入。
- **OverlayForm**：浮层表单，适合行内编辑或轻量弹层录入。

### 表格：该用哪个？

- **Table + TableColumn**：基础表格，模板声明式列定义。
- **ProTable**：增强表格，JSON 列配置 + 工具栏 + 分页 + 筛选 + 导出 + 可编辑 + 虚拟滚动。

### 页面：该用哪个？

- **ListPage**：标准列表页，搜索 + 表格 + 分页一体化。
- **CrudPage**：增删改查页面，内置新增/编辑/删除流程。
- **DetailPage**：详情页面容器。
- **SplitLayoutPage**：左右分栏页面，适合主从结构。

## 基础组件清单（xiaoye-components）

### 基础与展示

| 组件 | 标签 | 说明 |
|------|------|------|
| Button | `xy-button` | 按钮，支持 type/size/loading/plain/text/link/round/circle/block |
| ButtonGroup | `xy-button-group` | 按钮组，透传 type/size/direction |
| Link | `xy-link` | 文字链接 |
| Icon | `xy-icon` | Iconify 图标组件 |

### 反馈与浮层

| 组件 | 标签 | 说明 |
|------|------|------|
| Message | `$message` | 全局轻提示（命令式调用） |
| Notification | `xy-notification` / `$notify` | 全局通知 |
| Dialog | `xy-dialog` | 对话框，支持拖拽/调整尺寸/全屏/最大化/编程式调用 |
| Loading | `v-loading` / `$loading` | 加载指令/服务 |

## 增强组件清单（xiaoye-pro-components）

### 页面容器

| 组件 | 标签 | 说明 |
|------|------|------|
| ListPage | `xy-list-page` | 列表页面容器 |
| CrudPage | `xy-crud-page` | 增删改查页面 |
| SplitLayoutPage | `xy-split-layout-page` | 分栏页面 |

## 关键约定

- 组件标签统一使用 kebab-case：`xy-button`、`xy-form-item`、`xy-pro-table`
- TypeScript 标识符使用 PascalCase：`XyButton`、`XyFormItem`、`XyProTable`
- v-model 约定：`v-model="value"` 对应 `modelValue` / `update:model-value`
- 全局尺寸：`xs` / `sm` / `md` / `lg` / `xl`（默认 `md`），通过 ConfigProvider 或组件 size 属性控制
- 图标使用 Iconify 格式：`icon="mdi:loading"`、`icon="mdi:close"`
- 编程式调用：Dialog 支持 `XyDialogService.open/confirm/alert/prompt`，Message 通过 `$message`，Notification 通过 `$notify`

## 完整 API 参考

详见 [llms-full.txt](./llms-full.txt)，包含每个组件的完整 Props / Events / Slots / Exposes 定义。

import fs from "node:fs";
import path from "node:path";

const repoRoot = process.cwd();

function readFile(relativePath) {
  const absolute = path.join(repoRoot, relativePath);
  if (!fs.existsSync(absolute)) return null;
  return fs.readFileSync(absolute, "utf8");
}

function readManifest(relativePath) {
  const content = readFile(relativePath);
  if (!content) return [];
  return JSON.parse(content);
}

const baseManifest = readManifest("packages/components/component-manifest.json");
const proManifest = readManifest("packages/pro-components/component-manifest.json");

const TYPE_EXPANSIONS = {
  ButtonType: "'default' | 'primary' | 'success' | 'warning' | 'danger'",
  ButtonNativeType: "'button' | 'submit' | 'reset'",
  ComponentSize: "'sm' | 'md' | 'lg'",
  InputType: "'text' | 'textarea' | 'number' | 'password' | 'email' | 'search' | 'tel' | 'url'",
  InputAutoSize: "{ minRows?: number; maxRows?: number } | boolean",
  InputModelModifiers: "{ lazy?: true; number?: true; trim?: true }",
  TableAlign: "'left' | 'center' | 'right'",
  TableSortOrder: "'ascending' | 'descending' | null",
  TableSortable: "boolean | 'custom'",
  TableColumnType: "'default' | 'selection' | 'index' | 'expand'",
  TableColumnFixed: "boolean | 'left' | 'right'",
  TableLayout: "'fixed' | 'auto'",
  DialogCloseReason: "'close' | 'backdrop' | 'escape' | 'programmatic'",
  DialogTransition: "string | TransitionProps",
  Placement: "'top' | 'top-start' | 'top-end' | 'bottom' | 'bottom-start' | 'bottom-end' | 'right' | 'right-start' | 'right-end' | 'left' | 'left-start' | 'left-end'",
  TooltipEffect: "'dark' | 'light'",
  FormTrigger: "'blur' | 'change'",
  ValidateState: "'idle' | 'validating' | 'success' | 'error'",
  SearchFormFieldBuiltinComponent: "'input' | 'select' | 'checkbox' | 'checkbox-group' | 'radio' | 'radio-button' | 'radio-group' | 'cascader' | 'date-picker' | 'time-picker' | 'time-select' | 'input-number' | 'switch' | 'transfer' | 'avatar' | 'image' | 'progress' | 'tag' | 'timeline' | 'tree' | 'steps'",
  ProTableDensity: "'sm' | 'md' | 'lg'",
  ProTableEditableMode: "'table' | 'row' | 'cell'",
  ProTableEditableTrigger: "'click' | 'dblclick' | 'manual'",
  ProTableSelectionMode: "'single' | 'multiple'",
  ProTableExportType: "'csv' | 'excel'",
  ProTableContextmenuScope: "'row' | 'cell' | 'header'",
};

export type ComponentSize = "" | "xs" | "sm" | "md" | "lg" | "xl";

function expandType(typeStr) {
  if (!typeStr) return typeStr;
  let result = typeStr;
  for (const [ref, expansion] of Object.entries(TYPE_EXPANSIONS)) {
    const patterns = [
      new RegExp(`\\b${ref}\\b`, "g"),
      new RegExp(`\\b${ref}\\s*\\[\\s*["']`, "g"),
    ];
    for (const pattern of patterns) {
      if (pattern.test(result)) {
        result = result.replace(new RegExp(`\\b${ref}\\b`, "g"), `(${expansion})`);
      }
    }
  }
  result = result.replace(/\bXxxProps\["([^"]+)"\]/g, "$1");
  result = result.replace(/\bButtonProps\["([^"]+)"\]/g, "$1");
  result = result.replace(/\bInputProps\["([^"]+)"\]/g, "$1");
  result = result.replace(/\bSelectProps\["([^"]+)"\]/g, "$1");
  result = result.replace(/\bTableProps\["([^"]+)"\]/g, "$1");
  result = result.replace(/\bFormProps\["([^"]+)"\]/g, "$1");
  result = result.replace(/\bDialogProps\["([^"]+)"\]/g, "$1");
  result = result.replace(/\bButtonGroupProps\["([^"]+)"\]/g, "$1");
  result = result.replace(/\bButtonGroupDirection\b/g, "'horizontal' | 'vertical'");
  result = result.replace(/\bButtonInstance\["([^"]+)"\]/g, "$1");
  result = result.replace(/\bInputInstance\["([^"]+)"\]/g, "$1");
  result = result.replace(/\bSelectInstance\["([^"]+)"\]/g, "$1");
  result = result.replace(/\bTableInstance\["([^"]+)"\]/g, "$1");
  result = result.replace(/\bFormInstance\["([^"]+)"\]/g, "$1");
  result = result.replace(/\bDialogInstance\["([^"]+)"\]/g, "$1");
  result = result.replace(/\bDialogServiceHandle\["([^"]+)"\]/g, "$1");
  result = result.replace(/\bDialogServiceResult\["([^"]+)"\]/g, "$1");
  result = result.replace(/\bSelectValue<T>\b/g, "T | T[] | null");
  result = result.replace(/\bSelectValueChangeHandler<T>\b/g, "(value: T | T[] | null) => void");
  result = result.replace(/\bSelectVisibleChangeHandler\b/g, "(value: boolean) => void");
  result = result.replace(/\bSelectSearchChangeHandler\b/g, "(value: string) => void");
  result = result.replace(/\bButtonClickHandler\b/g, "(event: MouseEvent) => void");
  result = result.replace(/\bInputValueChangeHandler\b/g, "(value: string | number) => void");
  result = result.replace(/\bInputFocusHandler\b/g, "(event: FocusEvent) => void");
  result = result.replace(/\bDialogBeforeCloseFn\b/g, "(done: (cancel?: boolean) => void, reason?: 'close' | 'backdrop' | 'escape' | 'programmatic') => void | Promise<void>");
  result = result.replace(/\bDialogModelValueChangeHandler\b/g, "(value: boolean) => void");
  result = result.replace(/\bDialogFullscreenChangeHandler\b/g, "(value: boolean) => void");
  result = result.replace(/\bDialogResizeHandler\b/g, "(event: MouseEvent, width: number, height: number) => void");
  result = result.replace(/\bTableRowClickHandler<T>\b/g, "(row: T, column: TableResolvedColumn<T> | undefined, event: MouseEvent | KeyboardEvent) => void");
  result = result.replace(/\bTableSelectionChangeHandler<T>\b/g, "(selection: T[]) => void");
  result = result.replace(/\bTableSortChangePayload<T>\b/g, "{ column: TableResolvedColumn<T>; prop: string | undefined; order: 'ascending' | 'descending' | null }");
  result = result.replace(/\bTableFilterChangeHandler\b/g, "(value: Record<string, (string | number | boolean)[]>) => void");
  result = result.replace(/\bTableScrollPayload\b/g, "{ scrollLeft: number; scrollTop: number }");
  result = result.replace(/\bFormProp\b/g, "string | string[]");
  result = result.replace(/\bFormRules\b/g, "Record<string, XyFormRule[]>");
  result = result.replace(/\bXyFormRule\b/g, "RuleItem & { required?: boolean; trigger?: 'blur' | 'change' | ('blur' | 'change')[] }");
  result = result.replace(/\bTableTreeProps\b/g, "{ hasChildren?: string; children?: string; checkStrictly?: boolean }");
  result = result.replace(/\bTableSortState\b/g, "{ prop?: string; order?: 'ascending' | 'descending' | null }");
  result = result.replace(/\bTableOverflowTooltip\b/g, "boolean | TableOverflowTooltipOptions");
  result = result.replace(/\bTableOverflowTooltipOptions\b/g, "{ effect?: 'dark' | 'light'; enterable?: boolean; hideAfter?: number; offset?: number; placement?: Placement; popperClass?: string; showAfter?: number; showArrow?: boolean }");
  result = result.replace(/\bStyleValue\b/g, "string | CSSProperties | Array<string | CSSProperties>");
  result = result.replace(/\bTransitionProps\b/g, "TransitionProps");
  return result;
}

| `size`         | 按钮尺寸                   | `ButtonProps["size"]`                                           | 跟随全局配置    |

function extractApiSection(docContent, sectionTitle) {
  const headingPattern = new RegExp(
    `^###\\s+${escapeRegExp(sectionTitle)}\\s*$`,
    "m"
  );
  const match = headingPattern.exec(docContent);
  if (!match) return null;

  const startIndex = match.index + match[0].length;
  const nextHeading = docContent.indexOf("\n### ", startIndex);
  const nextH2 = docContent.indexOf("\n## ", startIndex);
  let endIndex = docContent.length;
  if (nextHeading !== -1) endIndex = Math.min(endIndex, nextHeading);
  if (nextH2 !== -1) endIndex = Math.min(endIndex, nextH2);

  const sectionText = docContent.slice(startIndex, endIndex);
  const tableMatch = sectionText.match(/\|[\s\S]*?\|[\s\S]*?\|/);
  if (!tableMatch) return null;

  const tableLines = sectionText.split("\n").filter((line) => line.trim().startsWith("|"));
  if (tableLines.length < 2) return null;

  return parseMarkdownTable(tableLines.join("\n"));
}

function parseMarkdownTable(tableText) {
  const lines = tableText.trim().split("\n").filter(Boolean);
  if (lines.length < 2) return [];

  const headerCells = splitMarkdownRow(lines[0]);
  const rows = [];

  for (let i = 2; i < lines.length; i++) {
    const cells = splitMarkdownRow(lines[i]);
    if (cells.length === 0) continue;
    const row = {};
    headerCells.forEach((header, idx) => {
      row[header.trim()] = (cells[idx] || "").trim();
    });
    rows.push(row);
  }
  return rows;
}

function splitMarkdownRow(line) {
  let trimmed = line.trim();
  if (trimmed.startsWith("|")) trimmed = trimmed.slice(1);
  if (trimmed.endsWith("|")) trimmed = trimmed.slice(0, -1);
  const placeholder = "\x00PIPE\x00";
  const withPlaceholders = trimmed.replace(/\\\|/g, placeholder);
  const cells = withPlaceholders.split("|").map((cell) =>
    cell.trim().replace(new RegExp(placeholder, "g"), "|")
  );
  return cells;
}

function extractComponentApi(docContent, _componentName) {
  const api = {
    props: [],
    events: [],
    slots: [],
    exposes: [],
  };

  const h3Headings = [...docContent.matchAll(/^###\s+(.+)$/gm)].map(
    (m) => m[1].trim()
  );

  const propsHeading = h3Headings.find((h) => /Attributes$|Options$/i.test(h));
  const eventsHeading = h3Headings.find((h) => /Events$/i.test(h));
  const slotsHeading = h3Headings.find((h) => /Slots$/i.test(h));
  const exposesHeading = h3Headings.find(
    (h) => /Exposes$/i.test(h) || /Methods$/i.test(h)
  );

  if (propsHeading) {
    const rows = extractApiSection(docContent, propsHeading);
    if (rows && rows.length > 0) {
      api.props = rows
        .map((row) => ({
          name: cleanMarkdown(row["属性"] || row["字段"] || row["名称"] || ""),
          description: cleanMarkdown(row["说明"] || ""),
          type: expandType(cleanMarkdown(row["类型"] || "")),
          default: cleanMarkdown(row["默认值"] || ""),
        }))
        .filter((p) => p.name);
    }
  }

  if (eventsHeading) {
    const rows = extractApiSection(docContent, eventsHeading);
    if (rows && rows.length > 0) {
      api.events = rows
        .map((row) => ({
          name: cleanMarkdown(row["事件"] || row["事件名"] || ""),
          description: cleanMarkdown(row["说明"] || ""),
          params: expandType(cleanMarkdown(row["参数"] || "")),
        }))
        .filter((e) => e.name);
    }
  }

  if (slotsHeading) {
    const rows = extractApiSection(docContent, slotsHeading);
    if (rows && rows.length > 0) {
      api.slots = rows
        .map((row) => ({
          name: cleanMarkdown(row["插槽"] || ""),
          description: cleanMarkdown(row["说明"] || ""),
          props: cleanMarkdown(row["参数"] || row["接收参数"] || ""),
        }))
        .filter((s) => s.name);
    }
  }

  if (exposesHeading) {
    const rows = extractApiSection(docContent, exposesHeading);
    if (rows && rows.length > 0) {
      api.exposes = rows
        .map((row) => ({
          name: cleanMarkdown(
            row["暴露项"] || row["名称"] || row["方法"] || ""
          ),
          description: cleanMarkdown(row["说明"] || ""),
          type: expandType(
            cleanMarkdown(row["类型"] || row["签名"] || "")
          ),
        }))
        .filter((e) => e.name);
    }
  }

  return api;
}

function cleanMarkdown(text) {
  return text
    .replace(/`([^`]+)`/g, "$1")
    .replace(/\[([^\]]+)\]\([^)]+\)/g, "$1")
    .trim();
}

function processComponents(manifest, docsDir, layer) {
  const results = [];

  for (const entry of manifest) {
    const docPath = path.join(docsDir, `${entry.name}.md`);
    const docContent = readFile(docPath);
    if (!docContent) {
      results.push({
        name: entry.name,
        title: entry.docsText,
        description: "",
        tags: entry.installChecks.map((c) => c.name),
        exports: entry.installExports,
        layer,
        props: [],
        events: [],
        slots: [],
        exposes: [],
      });
      continue;
    }

    const api = extractComponentApi(docContent, entry.name);
    const description = extractDescription(docContent);

    results.push({
      name: entry.name,
      title: entry.docsText,
      description,
      tags: entry.installChecks.map((c) => c.name),
      exports: entry.installExports,
      layer,
      ...api,
    });
  }

  return results;
}

const baseComponents = processComponents(
  baseManifest,
  "apps/docs/components",
  "base"
);
const proComponents = processComponents(
  proManifest,
  "apps/docs/pro-components",
  "pro"
);

const allComponents = [...baseComponents, ...proComponents];

const schema = {
  version: "1.0.0",
  generatedAt: new Date().toISOString(),
  components: allComponents,
};

const schemaDir = path.join(repoRoot, "scripts/.llm-cache");
if (!fs.existsSync(schemaDir)) {
  fs.mkdirSync(schemaDir, { recursive: true });
}

fs.writeFileSync(
  path.join(schemaDir, "api-schema.json"),
  JSON.stringify(schema, null, 2),
  "utf8"
);

console.log(`API Schema 已生成：${allComponents.length} 个组件`);

function generateLlmsFull(components) {
  const sections = [];

  sections.push(`# xiaoye-components 完整 API 参考`);
  sections.push(``);
  sections.push(`> 自动生成于 ${new Date().toISOString()}`);
  sections.push(`> 包含 ${components.length} 个组件的完整 Props / Events / Slots / Exposes 定义`);
  sections.push(``);

  const grouped = {
    base: { basic: [], form: [], feedback: [], data: [] },
    pro: { form: [], data: [], detail: [], page: [], workflow: [] },
  };

  for (const comp of components) {
    const manifest = comp.layer === "base" ? baseManifest : proManifest;
    const entry = manifest.find((e) => e.name === comp.name);
    const docsGroup = entry?.docsGroup || "basic";
    if (grouped[comp.layer] && grouped[comp.layer][docsGroup]) {
      grouped[comp.layer][docsGroup].push(comp);
    }
  }

  const groupLabels = {
    basic: "基础与展示",
    form: "表单输入",
    feedback: "反馈与浮层",
    data: "数据展示",
    detail: "详情",
    page: "页面容器",
    workflow: "工作流",
  };

  sections.push(`## 基础组件（@xiaoye/components）`);
  sections.push(``);

  for (const [groupKey, label] of Object.entries(groupLabels)) {
    const comps = grouped.base[groupKey];
    if (!comps || comps.length === 0) continue;

    sections.push(`### ${label}`);
    sections.push(``);

    for (const comp of comps) {
      sections.push(renderComponent(comp));
    }
  }

  sections.push(`## 增强组件（@xiaoye/pro-components）`);
  sections.push(``);

  for (const [groupKey, label] of Object.entries(groupLabels)) {
    const comps = grouped.pro[groupKey];
    if (!comps || comps.length === 0) continue;

    sections.push(`### ${label}`);
    sections.push(``);

    for (const comp of comps) {
      sections.push(renderComponent(comp));
    }
  }

  return sections.join("\n");
}

function escapeTableCell(text) {
  return String(text).replace(/\|/g, "\\|");
}

function renderComponent(comp) {
  const lines = [];
  const tag = comp.tags[0] || comp.name;

  lines.push(`#### ${comp.title}`);
  if (comp.description) {
    lines.push(``);
    lines.push(comp.description);
  }
  lines.push(``);
  lines.push(`标签：\`${tag}\` 导出：\`${comp.exports.join("`, `")}\``);
  lines.push(``);

  if (comp.props.length > 0) {
    lines.push(`**Props**`);
    lines.push(``);
    lines.push(`| 属性 | 类型 | 默认值 | 说明 |`);
    lines.push(`|------|------|--------|------|`);
    for (const prop of comp.props) {
      const type = prop.type || "-";
      const defaultVal = escapeTableCell(prop.default || "-");
      const desc = escapeTableCell(prop.description || "");
      lines.push(`| \`${prop.name}\` | \`${type}\` | ${defaultVal} | ${desc} |`);
    }
    lines.push(``);
  }

  if (comp.events.length > 0) {
    lines.push(`**Events**`);
    lines.push(``);
    lines.push(`| 事件 | 参数 | 说明 |`);
    lines.push(`|------|------|------|`);
    for (const event of comp.events) {
      const params = event.params || "-";
      const desc = escapeTableCell(event.description || "");
      lines.push(`| \`${event.name}\` | \`${params}\` | ${desc} |`);
    }
    lines.push(``);
  }

  if (comp.slots.length > 0) {
    lines.push(`**Slots**`);
    lines.push(``);
    lines.push(`| 插槽 | 说明 |`);
    lines.push(`|------|------|`);
    for (const slot of comp.slots) {
      const desc = escapeTableCell(slot.description || "");
      const propsInfo = slot.props ? `（接收 ${escapeTableCell(slot.props)}）` : "";
      lines.push(`| \`${slot.name}\` | ${desc}${propsInfo} |`);
    }
    lines.push(``);
  }

  if (comp.exposes.length > 0) {
    lines.push(`**Exposes**`);
    lines.push(``);
    lines.push(`| 名称 | 类型 | 说明 |`);
    lines.push(`|------|------|------|`);
    for (const expose of comp.exposes) {
      const type = expose.type || "-";
      const desc = escapeTableCell(expose.description || "");
      lines.push(`| \`${expose.name}\` | \`${type}\` | ${desc} |`);
    }
    lines.push(``);
  }

  lines.push(`---`);
  lines.push(``);

  return lines.join("\n");
}

| `type` | `('default' | 'primary' | 'success' | 'warning' | 'danger')` | 'default' | 按钮类型 |

const llmsFullContent = generateLlmsFull(allComponents);
fs.writeFileSync(
  path.join(repoRoot, "llms-full.txt"),
  llmsFullContent,
  "utf8"
);

console.log(`llms-full.txt 已生成`);
console.log(`基础组件：${baseComponents.length} 个`);
console.log(`增强组件：${proComponents.length} 个`);

const withApi = allComponents.filter(
  (c) => c.props.length > 0 || c.events.length > 0 || c.slots.length > 0
);
const withoutApi = allComponents.filter(
  (c) => c.props.length === 0 && c.events.length === 0 && c.slots.length === 0
);
console.log(`有 API 数据：${withApi.length} 个`);
console.log(`无 API 数据：${withoutApi.length} 个`);
if (withoutApi.length > 0) {
  console.log(
    `缺少 API 的组件：${withoutApi.map((c) => c.name).join(", ")}`
  );
}

#### Button 按钮

页面主操作、次要操作和轻量文本动作入口。

标签：`xy-button` 导出：`XyButton`, `XyButtonGroup`

**Props**

| 属性 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `type` | `('default' | 'primary' | 'success' | 'warning' | 'danger')` | 'default' | 按钮类型 |
| `size` | `size` | 跟随全局配置 | 按钮尺寸 |
| `disabled` | `boolean` | false | 是否禁用交互 |
| `icon` | `string` | — | 前置 Iconify 图标 |
| `native-type` | `('button' | 'submit' | 'reset')` | 'button' | 原生按钮类型 |

{
  "name": "button",
  "title": "Button 按钮",
  "description": "页面主操作、次要操作和轻量文本动作入口。",
  "tags": ["xy-button", "xy-button-group"],
  "exports": ["XyButton", "XyButtonGroup"],
  "layer": "base",
  "props": [
    {
      "name": "type",
      "description": "按钮类型",
      "type": "('default' | 'primary' | 'success' | 'warning' | 'danger')",
      "default": "'default'"
    },
    {
      "name": "size",
      "description": "按钮尺寸",
      "type": "size",
      "default": "跟随全局配置"
    }
  ],
  "events": [
    {
      "name": "click",
      "description": "点击按钮时触发；当 loading 或 disabled 时不会触发",
      "params": "(event: MouseEvent) => void"
    }
  ],
  "slots": [
    { "name": "default", "description": "按钮主内容", "props": "" }
  ],
  "exposes": [
    { "name": "ref", "description": "按钮根节点引用", "type": "ref" },
    { "name": "size", "description": "解析后的尺寸", "type": "size" }
  ]
}

import fs from "node:fs";
import path from "node:path";
import { fileURLToPath } from "node:url";

const __dirname = path.dirname(fileURLToPath(import.meta.url));

interface ComponentProp {
  name: string;
  description: string;
  type: string;
  default: string;
}

interface ComponentEvent {
  name: string;
  description: string;
  params: string;
}

interface ComponentSlot {
  name: string;
  description: string;
  props: string;
}

interface ComponentExpose {
  name: string;
  description: string;
  type: string;
}

interface ComponentData {
  name: string;
  title: string;
  description: string;
  tags: string[];
  exports: string[];
  layer: "base" | "pro";
  props: ComponentProp[];
  events: ComponentEvent[];
  slots: ComponentSlot[];
  exposes: ComponentExpose[];
}

interface ApiSchema {
  version: string;
  generatedAt: string;
  components: ComponentData[];
}

function loadSchema(): ApiSchema {
  const schemaPaths = [
    path.resolve(__dirname, "../../scripts/.llm-cache/api-schema.json"),
    path.resolve(process.cwd(), "scripts/.llm-cache/api-schema.json"),
  ];

  for (const schemaPath of schemaPaths) {
    if (fs.existsSync(schemaPath)) {
      const content = fs.readFileSync(schemaPath, "utf8");
      return JSON.parse(content);
    }
  }

  console.error(
    "Error: api-schema.json not found. Run `pnpm generate:llm` first."
  );
  process.exit(1);
}

const schema = loadSchema();
const components = schema.components;

const baseComponents = components.filter((c) => c.layer === "base");
const proComponents = components.filter((c) => c.layer === "pro");

export { schema, components, baseComponents, proComponents };
export type {
  ComponentData,
  ComponentProp,
  ComponentEvent,
  ComponentSlot,
  ComponentExpose,
  ApiSchema,
};

const server = new McpServer(
  {
    name: "xiaoye-components",
    version: "0.1.0",
  },
  {
    instructions: `You are working with xiaoye-components, a Vue 3 component library for mid-office and back-office scenarios.

Key conventions:
- Component tags use kebab-case with "xy-" prefix: xy-button, xy-dialog, xy-pro-table
- TypeScript identifiers use PascalCase with "Xy" prefix: XyButton, XyDialog, XyProTable
- v-model convention: v-model="value" maps to modelValue / update:model-value
- Global sizes: "sm" | "md" | "lg"
- Icons use Iconify format: icon="mdi:loading"

When suggesting components, prefer:
- Dialog for blocking interactions, Drawer for side panels
- ProTable over Table for data-heavy pages
- SearchForm for filter bars, ProForm for complex forms
- ListPage/CrudPage for standard CRUD pages

Always call list_components first to see what's available, then get_component_api for specific API details.`,
  }
);

server.tool(
  "list_components",
  "List all available components with brief descriptions. Returns component name, title, tags, and layer (base/pro).",
  {
    layer: z
      .enum(["all", "base", "pro"])
      .default("all")
      .describe("Filter by component layer: base (@xiaoye/components) or pro (@xiaoye/pro-components)"),
  },
  async ({ layer }) => {
    const list =
      layer === "base"
        ? baseComponents
        : layer === "pro"
          ? proComponents
          : components;

    const lines = [
      `# xiaoye-components (${list.length} components)`,
      "",
      "| Component | Tag | Layer | Description |",
      "|-----------|-----|-------|-------------|",
    ];

    for (const comp of list) {
      const tag = comp.tags[0] || comp.name;
      lines.push(
        `| ${comp.name} | \`${tag}\` | ${comp.layer} | ${comp.description || comp.title} |`
      );
    }

    return {
      content: [{ type: "text", text: lines.join("\n") }],
    };
  }
);

server.tool(
  "get_component_api",
  "Get the full API reference for a specific component, including Props, Events, Slots, and Exposes.",
  {
    name: z
      .string()
      .describe(
        "Component name in kebab-case (e.g. 'button', 'dialog', 'pro-table', 'search-form')"
      ),
  },
  async ({ name }) => {
    const comp = components.find(
      (c) =>
        c.name === name ||
        c.tags.includes(name) ||
        c.tags.includes(`xy-${name}`) ||
        c.exports.some(
          (e) => e.toLowerCase() === name.toLowerCase() || e === `Xy${name.charAt(0).toUpperCase()}${name.slice(1)}`
        )
    );

    if (!comp) {
      const suggestions = components
        .filter((c) => c.name.includes(name) || c.title.includes(name))
        .slice(0, 5)
        .map((c) => c.name);

      return {
        content: [
          {
            type: "text",
            text: `Component "${name}" not found.${
              suggestions.length > 0
                ? ` Did you mean: ${suggestions.join(", ")}?`
                : ` Call list_components to see all available components.`
            }`,
          },
        ],
        isError: true,
      };
    }

    const lines = renderComponentApi(comp);
    return {
      content: [{ type: "text", text: lines.join("\n") }],
    };
  }
);

server.tool(
  "search_components",
  "Search components by keyword. Searches component names, titles, descriptions, and tag names.",
  {
    query: z
      .string()
      .describe(
        "Search keyword (e.g. 'form', 'table', 'dialog', 'upload', 'date')"
      ),
  },
  async ({ query }) => {
    const lowerQuery = query.toLowerCase();
    const matches = components.filter((comp) => {
      const searchable = [
        comp.name,
        comp.title,
        comp.description,
        ...comp.tags,
        ...comp.exports,
      ]
        .join(" ")
        .toLowerCase();
      return searchable.includes(lowerQuery);
    });

    if (matches.length === 0) {
      return {
        content: [
          {
            type: "text",
            text: `No components found matching "${query}". Call list_components to see all available components.`,
          },
        ],
      };
    }

function renderComponentApi(comp: ComponentData): string[] {
  const lines: string[] = [];
  const tag = comp.tags[0] || comp.name;

  lines.push(`# ${comp.title}`);
  if (comp.description) {
    lines.push("");
    lines.push(comp.description);
  }
  lines.push("");
  lines.push(`- **Tag**: \`${tag}\``);
  lines.push(`- **Exports**: ${comp.exports.map((e) => `\`${e}\``).join(", ")}`);
  lines.push(`- **Layer**: ${comp.layer === "base" ? "@xiaoye/components" : "@xiaoye/pro-components"}`);

  if (comp.props.length > 0) {
    lines.push("");
    lines.push("## Props");
    lines.push("");
    lines.push("| Property | Type | Default | Description |");
    lines.push("|----------|------|---------|-------------|");
    for (const prop of comp.props) {
      lines.push(
        `| \`${prop.name}\` | \`${prop.type}\` | ${prop.default || "-"} | ${prop.description} |`
      );
    }
  }

async function main() {
  const transport = new StdioServerTransport();
  await server.connect(transport);
  console.error(
    `xiaoye-components MCP server running (${components.length} components loaded)`
  );
}

main().catch((err) => {
  console.error("Fatal error:", err);
  process.exit(1);
});

"check:tokens": "node scripts/check-generated.mjs --name tokens --generate \"node scripts/generate-tokens.mjs\" --path packages/tokens/src",
"check:llms": "node scripts/check-generated.mjs --name llms --generate \"node scripts/generate-llm-files.mjs\" --path llms-full.txt --ignore \"^> 自动生成于\"",

"lint": "pnpm check:tokens && pnpm check:llms && pnpm check:components && pnpm check:pro-components && eslint .",

/**
 * 生成物漂移守卫：校验"由事实源生成"的产物是否与事实源保持同步。
 *
 * 流程：快照当前生成物到临时目录 → 重新执行生成命令 → 逐文件对比
 * （--ignore 可按行正则过滤时间戳等易变行）→ 无论通过与否都还原快照，
 * 保证对工作区零副作用（不能用 git diff 判断，本地未提交改动会误报）。
 * 失败时把重新生成的产物保留在临时目录作为证据，并输出修复处方。
 *
 * 用法示例：
 *   node scripts/check-generated.mjs --name tokens \
 *     --generate "node scripts/generate-tokens.mjs" --path packages/tokens/src
 *   node scripts/check-generated.mjs --name llms \
 *     --generate "node scripts/generate-llm-files.mjs" --path llms-full.txt \
 *     --ignore "^> 自动生成于"
 */

/** 列出目标下的全部文件（相对仓库根的路径）；目标是单文件时返回它自身。 */
function collectFiles(target) {
  const abs = path.join(repoRoot, target);
  if (!fs.existsSync(abs)) return [];
  if (fs.statSync(abs).isFile()) return [target];
  const files = [];
  const walk = (dir) => {
    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
      const child = path.join(dir, entry.name);
      if (entry.isDirectory()) walk(child);
      else if (entry.isFile()) files.push(child);
    }
  };
  walk(abs);
  return files.map((file) => path.relative(repoRoot, file));
}

/** 还原快照：删掉生成新造的文件、写回快照内容、清理生成留下的空目录。 */
function restore(snapshot, targets, knownDirs) {
  for (const target of targets) {
    for (const rel of collectFiles(target)) {
      if (!snapshot.has(rel)) fs.rmSync(path.join(repoRoot, rel));
    }
  }
  for (const [rel, content] of snapshot) {
    const abs = path.join(repoRoot, rel);
    fs.mkdirSync(path.dirname(abs), { recursive: true });
    fs.writeFileSync(abs, content);
  }
  for (const target of targets) {
    const abs = path.join(repoRoot, target);
    if (!fs.existsSync(abs) || !fs.statSync(abs).isDirectory()) continue;
    const dirs = [];
    const walk = (dir) => {
      dirs.push(dir);
      for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
        if (entry.isDirectory()) walk(path.join(dir, entry.name));
      }
    };
    walk(abs);
    for (const dir of dirs.reverse()) {
      if (fs.readdirSync(dir).length === 0 && !knownDirs.has(dir)) fs.rmdirSync(dir);
    }
  }
}

function filterLines(content, ignores) {
  return content.split("\n").filter((line) => !ignores.some((regex) => regex.test(line)));
}

function diffEntries(rel, beforeText, afterText, ignores) {
  const before = filterLines(beforeText, ignores);
  const after = filterLines(afterText, ignores);
  const diffs = [];
  const total = Math.max(before.length, after.length);
  for (let i = 0; i < total && diffs.length < 5; i += 1) {
    if (before[i] !== after[i]) {
      diffs.push({ line: i + 1, before: before[i], after: after[i] });
    }
  }
  return { rel, before, after, diffs };
}

const { name, generate, path: targets, ignore: ignoreArgs } = parseArgs(process.argv.slice(2));
const ignorePatterns = ignoreArgs.map((pattern) => new RegExp(pattern));

const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), `xy-check-${name}-`));
const snapshot = new Map();
const knownDirs = new Set();
for (const target of targets) {
  const abs = path.join(repoRoot, target);
  if (fs.existsSync(abs)) knownDirs.add(fs.statSync(abs).isDirectory() ? abs : path.dirname(abs));
  for (const rel of collectFiles(target)) {
    snapshot.set(rel, fs.readFileSync(path.join(repoRoot, rel), "utf8"));
  }
}

let failed = false;
try {
  execSync(generate, { stdio: "inherit", cwd: repoRoot });
} catch {
  console.error(`[check:${name}] 生成命令执行失败：${generate}`);
  failed = true;
}

const entries = [];
if (!failed) {
  const afterFiles = new Map();
  for (const target of targets) {
    for (const rel of collectFiles(target)) {
      afterFiles.set(rel, fs.readFileSync(path.join(repoRoot, rel), "utf8"));
    }
  }
  for (const rel of new Set([...snapshot.keys(), ...afterFiles.keys()])) {
    if (!snapshot.has(rel)) {
      entries.push({ rel, reason: "生成新增、工作区缺失" });
    } else if (!afterFiles.has(rel)) {
      entries.push({ rel, reason: "生成后缺失" });
    } else {
      const diff = diffEntries(rel, snapshot.get(rel), afterFiles.get(rel), ignorePatterns);
      if (diff.diffs.length > 0 || diff.before.length !== diff.after.length) entries.push(diff);
    }
  }
  failed = entries.length > 0;
}

if (failed) {
  const evidenceDir = path.join(tempRoot, "regenerated");
  for (const target of targets) {
    for (const rel of collectFiles(target)) {
      const dest = path.join(evidenceDir, rel);
      fs.mkdirSync(path.dirname(dest), { recursive: true });
      fs.copyFileSync(path.join(repoRoot, rel), dest);
    }
  }
  console.error(`[check:${name}] 重新生成产物已保留为证据：${evidenceDir}（工作区快照即将原样还原）`);
}

restore(snapshot, targets, knownDirs);

if (failed) {
  console.error(`[check:${name}] 生成物与事实源不同步（${entries.length} 处）：`);
  for (const entry of entries) {
    console.error(`  - ${entry.rel}${entry.reason ? `（${entry.reason}）` : ""}`);
    for (const diff of entry.diffs ?? []) {
      console.error(`    L${diff.line}: ${JSON.stringify(diff.before)} -> ${JSON.stringify(diff.after)}`);
    }
  }
  console.error(`[check:${name}] 处方：运行 ${generate} 后随事实源一并提交`);
  process.exit(1);
}

fs.rmSync(tempRoot, { recursive: true, force: true });
console.log(`[check:${name}] 生成物与事实源一致（${snapshot.size} 个文件）`);