11-03 · 组件库的 AI 生态闭环

// packages/xiaoye-primitives/src/composables/shared-context.ts:6
export type ComponentSize = "" | "xs" | "sm" | "md" | "lg" | "xl";

export interface SharedConfigContext {
  namespace: ComputedRef<string>;
  locale: ComputedRef<Locale>;
  zIndex: ComputedRef<number>;
  size: ComputedRef<ComponentSize>;
  dialog: ComputedRef<unknown>;
  loading: ComputedRef<unknown>;
  message: ComputedRef<unknown>;
  notification: ComputedRef<unknown>;
}

export const DEFAULT_NAMESPACE = "xy";
export const DEFAULT_Z_INDEX = 2000;
export const DEFAULT_SIZE: ComponentSize = "md";

| 属性           | 说明                       | 类型                                                           | 默认值          |
| -------------- | -------------------------- | -------------------------------------------------------------- | --------------- |
| `type`         | 按钮类型                   | `ButtonType` | `'default'`     |
| `size`         | 按钮尺寸                   | `ButtonProps["size"]`                                           | 跟随全局配置    |
| `disabled`     | 是否禁用交互               | `boolean`                                                      | `false`         |
| `icon`         | 前置 Iconify 图标          | `string`                                                       | —               |

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'",
};

# xiaoye-components 完整 API 参考

> 自动生成于 2026-09-22T22:47:21.402Z
> 包含 103 个组件的完整 Props / Events / Slots / Exposes 定义

| `type` | `('default' | 'primary' | 'success' | 'warning' | 'danger')` | 'default' | 按钮类型 |
| `size` | `size` | 跟随全局配置 | 按钮尺寸 |

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'");

{
  "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": "跟随全局配置"
    }
  ],
  "exposes": [
    { "name": "ref", "description": "按钮根节点引用", "type": "ref" },
    { "name": "size", "description": "解析后的尺寸", "type": "size" },
    { "name": "type", "description": "解析后的按钮类型", "type": "type" },
    { "name": "disabled", "description": "解析后的禁用状态", "type": "disabled" }
  ]
}

const server = new McpServer(
  {
    name: "xiaoye-components",
    version: "0.1.0",                    // ← 断点 C：包版本已是 0.1.1（package.json:3）
  },
  {
    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.`,
  }
);

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 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.`,
          },
        ],
      };
    }

    const lines = [
      `# Search results for "${query}" (${matches.length} found)`,
      "",
    ];

    for (const comp of matches) {
      const tag = comp.tags[0] || comp.name;
      lines.push(`## ${comp.title}`);
      lines.push(`- Name: ${comp.name}`);
      lines.push(`- Tag: \`${tag}\``);
      lines.push(`- Layer: ${comp.layer}`);
      if (comp.description) {
        lines.push(`- Description: ${comp.description}`);
      }
      lines.push(
        `- API: ${comp.props.length} props, ${comp.events.length} events, ${comp.slots.length} slots, ${comp.exposes.length} exposes`
      );
      lines.push("");
    }

    lines.push(
      "Use get_component_api with a component name to see full API details."
    );

配置完成后，你可以在 AI 对话中直接提问：

- "帮我用 xiaoye-components 写一个用户列表页" → AI 会调用 search_components("list") 找到 ListPage
- "xy-dialog 有哪些 props？" → AI 会调用 get_component_api("dialog") 返回完整 API
- "表单组件有哪些？" → AI 会调用 list_components({ layer: "base" }) 过滤基础组件

/**
 * 生成物漂移守卫：校验"由事实源生成"的产物是否与事实源保持同步。
 *
 * 流程：快照当前生成物到临时目录 → 重新执行生成命令 → 逐文件对比
 * （--ignore 可按行正则过滤时间戳等易变行）→ 无论通过与否都还原快照，
 * 保证对工作区零副作用（不能用 git diff 判断，本地未提交改动会误报）。
 */

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;
}

// 修复方向示意（非现有源码）：把 TYPE_EXPANSIONS 从"手工誊抄"变成"解析生成"
// 思路：从 prepare-package 管线已产出的 d.ts 里抽取类型别名的字面量联合，
// 生成器启动时先装载生成映射，TYPE_EXPANSIONS 仅兜底解析失败项。
import { parseTypeAliases } from "./lib/dts-type-reader.mjs";

const RUNTIME_ALIASES = parseTypeAliases([
  "packages/components/dist/components.d.ts",
  "packages/pro-components/dist/pro-components.d.ts",
]);                                        // ComponentSize → 六档，随构建自动更新

const TYPE_EXPANSIONS = { ...RUNTIME_ALIASES, ...MANUAL_FALLBACKS };
// 顺手可加一道自检：RUNTIME_ALIASES 与 MANUAL_FALLBACKS 的交集非空即报错，
// 让"誊抄漂移"从静默失真变成 lint 红灯。

// 修复方向示意（非现有源码）：index.ts:15 的 version 改为从包声明读取
import pkg from "../package.json" with { type: "json" };

const server = new McpServer(
  {
    name: "xiaoye-components",
    version: pkg.version,   // Changesets bump 时握手帧里的版本自动跟进
  },
  { /* instructions 不变 */ }
);

$ git log --since='2026-09-16 00:00' --until='2026-09-17 00:00' --format='%h %s'
8f6b5ea Merge pull request #1 from zhangzhengyang27/changeset-release/main
4423210 chore: version packages
f0b37a2 fix(primitives): focus-trap 延迟回调增加环境防护
2a0bded ci: 修复 Release 权限缺失与 CI 测试 OOM flaky
075b46b fix(docs): 移除 cssCodeSplit:true 覆盖，修复构建产物样式全丢
a6a998f docs: 文档站接入 Umami 访问统计
09775c6 docs: 彻底下线专栏与 CodeGraph 指南
5135def docs: 顶部导航移除 CodeGraph 与专栏入口
7645d5c feat: 设计令牌体系重构为 Stripe 设计语言

feat: 设计令牌体系重构为 Stripe 设计语言

以 design.hagicode.com 收录的 Stripe DESIGN.md（含官方亮/暗 token 目录）为蓝本，
建立基元/语义/刻度三层令牌架构：

- tokens.css 全面重写：六族数字标度色板、语义角色统一命名、五级蓝调海拔、
  单调 z-index 阶梯（修复 dropdown>modal 倒挂）、九档无坍缩字号、Stripe 圆角刻度
- 暗色主题采用官方暗色值（靛黑页面底/提亮品牌色/白色透明度边框/黑色主导阴影）
- 全仓 3444 处旧变量名迁移到新命名；旧名经 @deprecated 兼容层继续生效
- packages/tokens TS 层改为由 scripts/generate-tokens.mjs 从 tokens.css 生成
- 删除未接线的前台主题死代码（theme/src/front，--xyu-* 体系）
- 重写 theming/design-tokens/专栏令牌文档，AGENTS.md 新增令牌约定
- 视觉巡检 103 页/532 组亮暗截图零控制台报错，已重存基线

$ git show 7645d5c --stat -- llms-full.txt packages/xiaoye-primitives/src/theme/tokens.css packages/tokens
 llms-full.txt                                      | 4 ++--
 packages/tokens/src/index.ts                       |   2 +-
 packages/tokens/src/primitives.ts                  | 204 +++------
 packages/tokens/src/scales.ts                      |  42 ++
 packages/tokens/src/semantic.ts                    | 182 +++++---
 packages/xiaoye-primitives/src/theme/tokens.css    | 525 +++++++++++++++++-------
 6 files changed, 618 insertions(+), 341 deletions(-)

$ pnpm generate:tokens        # tokens.css → packages/tokens/src/*.ts（TS 常量层）
$ pnpm generate:llm           # 105 份文档 md → llms-full.txt + api-schema.json
$ pnpm lint                   # 头部四连：check:tokens → check:llms → check:components → check:pro-components
[check:tokens] 生成物与事实源一致（4 个文件）
[check:llms] 生成物与事实源一致（1 个文件）

// package.json:12-16（lint 链头部是四份事实源校验，eslint 排最末）
"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 \"^> 自动生成于\"",
"check:pro-components": "node scripts/check-pro-components.mjs",
"lint": "pnpm check:tokens && pnpm check:llms && pnpm check:components && pnpm check:pro-components && eslint .",

## 组件选择指南

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

- **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**：左右分栏页面，适合主从结构。