本文档是《xiaoye-components 组件库源码专栏》的阶段一交付物之一，基于全仓扫描产出（2026-09-16 修订：字重令牌扩档、生成物守卫等实态对齐），作为后续全部篇章的事实基线。所有文件路径均相对仓库根目录。
xiaoye-components 是一套 AI 协作研发 的 Vue 3 企业级组件库 monorepo，以 Stripe 设计语言为视觉蓝本。当前发布状态（本地与 npm 同步）：
| 包 | npm 名 | 版本 | 角色 | 发布状态 |
|---|---|---|---|---|
| packages/components | xiaoye-components | 1.1.0 | 基础组件层（72 个组件） | 已发布 |
| packages/pro-components | xiaoye-pro-components | 2.0.0 | 增强组件层（31 个组件） | 已发布（独立大版本） |
| packages/xiaoye-primitives | xiaoye-primitives | 1.1.0 | 基础设施层（composables + utils + 令牌源） | 已发布 |
| packages/mcp-server | xiaoye-mcp-server | 0.1.1 | AI 工具 MCP Server | 已发布 |
| packages/theme | @xiaoye/theme（private） | — | 全部组件样式（约 1.84 万行 CSS） | 内部 |
| packages/tokens | @xiaoye/tokens（private） | — | 令牌 TS 常量层（生成物） | 内部 |
| apps/docs | @xiaoye/docs（private） | — | VitePress 文档站 | 内部 |
| apps/playground | @xiaoye/playground（private） | — | 本地联调 | 内部 |
四个发布包独立版本（changesets fixed: []），跨包联动靠 updateInternalDependencies: "patch"。
关键依赖设计：
pro-components → components → primitives → (@floating-ui/dom, vue peer)，无环。peerDependencies: workspace:^（packages/pro-components/package.json），保证宿主应用与增强层共享同一基础库实例——Symbol.for 安装标记与 ConfigProvider 的 provide/inject 才能跨包生效。scripts/config/aliases.ts 的统一 alias 直连源码（该文件被库构建 / vitest / 文档站 / playground 四条工具链复用）。packages/xiaoye-primitives/src/theme/tokens.css 是全库设计令牌唯一事实源，同时承载浮层 composables；components/src/composables/index.ts 一行 export * from "xiaoye-primitives" 做二次转发。packages/components/component-manifest.json（72 条）与 packages/pro-components/component-manifest.json（31 条）是各自层的唯一数据事实源，同时驱动：
exports.ts 导出聚合index.ts 全局安装列表（installableComponentExportNames 鸭子类型过滤）config.ts 直接 import manifest.ts）styleImports ↔ theme/index.css 的 @import 双向 diff）scripts/check-components.mjs 六向校验、scripts/check-pro-components.mjs 十一组校验，均挂进 pnpm lint）scripts/generate-llm-files.mjs）全库浮层（tooltip/popover/popconfirm/dropdown/dialog/drawer + 7 个表单弹层 + image-viewer + menu 子菜单）共享同一组基础设施：
| composable | 职责 |
|---|---|
use-floating-visibility.ts | visible/rendered/isAnimating 三态状态机、开闭延迟、动画期 toggle 守卫 |
use-overlay-stack.ts | 模块级全局浮层栈，zIndex 自 2000 发号，isTopMost 栈顶裁决 |
use-floating-panel.ts | @floating-ui/dom 定位封装（offset/flip/shift/size/arrow 管道） |
use-dismissible-layer.ts | Escape/外点关闭统一收口，栈顶守卫 |
use-overlay-dialog.ts | 模态编排层（teleport/destroyOnClose/modal/lockScroll 聚合） |
use-focus-trap.ts | 焦点陷阱（Tab 循环/焦点还原/逃逸拦截） |
use-list-navigation.ts | 列表键盘导航（上下/Home/End/循环） |
packages/xiaoye-primitives/src/theme/tokens.css（410 行）：基元层 58 个（--xy-{色板}-{阶}，双主题共享）+ 语义层 66 个（--xy-{角色}[-{状态}]，暗色只覆写 58 个值）+ 刻度层 45 个（--xy-{刻度}-{档}，主题无关；字重 12 档）。切换协议为 [data-theme="dark"] 属性，组件 CSS 中 [data-theme] 选择器出现 0 次（纯变量级联换肤）。--xy-mix-light 变量在暗色下从白色反转为容器底色，使全库 800+ 处 color-mix() 公式同一写法下语义自动反转。生成物 TS 常量层由 pnpm generate:tokens 产出（packages/tokens/src/*），同步性由 check:tokens 守卫。
message/notification 两类走 withInstallFunction 在 app.use 时捕获 app._context；loading 指令+服务双注册（manifest 双 kind）；dialog 服务采用 reactive({ current, queue }) 串行队列 + 每 entry 自带 Promise resolver 的句柄模型（alert 服务为同族变奏）。树外配置经 config-provider 的四组全局注册表下发。
llms.txt（发现，手写）→ llms-full.txt（参考，约 19.3 万字符，脚本从文档 md 反向解析生成）→ scripts/.llm-cache/api-schema.json（数据，103 组件）→ xiaoye-mcp-server（查询层，list_components / get_component_api / search_components 三工具 + 内置选型指导 prompt）。生成物同步由 check:llms 守卫。
vitest.setup.ts 全局 mock @iconify/vue；tests/types/fixtures/ 105 个夹具，@ts-expect-error 负向断言锁死类型契约（含 pro-root-boundary.ts 守卫增强层 API 面）；scripts/visual-audit.mjs，Playwright 元素级截图 × 双主题 × pixelmatch 0.5% 阈值 + 基线目录（1064 张）；vitepress dev 起 webServer），tests/e2e/admin-flow.spec.ts 走真实业务闭环、docs-demos.spec.ts 高危 demo 定点回归。scripts/config/library-build.ts 的 createLibraryConfig，ES-only 单格式，dts 输出 dist/types；scripts/prepare-package.mjs（808 行）做发布级 d.ts 后处理（别名重写、SFCWithInstall 泛型简化、TS Compiler API 重建组件 index.d.ts）。pnpm changeset → push main → release.yml 开 Version Packages PR → 合并后自动 build:lib + changeset publish；release job 内重跑 check/typecheck/test/build 做门禁兜底（防直推 main 绕过 CI）。--no-file-parallelism 防 OOM，注释记录踩坑）→ build；lint 链前置四道守卫（check:tokens / check:llms / check:components / check:pro-components）；docs.yml 仅构建冒烟。:::demo 语法）+ Vite pre-transform 插件（自动注入异步组件与虚拟模块导入）+ virtual:xy-demo-source:* 内存注册表——「运行的代码 = 展示的代码」，另附 TS→JS 双视图（utils/ts2js.ts）。| 指标 | 数值 |
|---|---|
| 基础组件 / 增强组件 | 72 / 31 |
| 单测 spec 文件 | 114 个（76 基础 + 34 增强 + 4 基建） |
| 类型测试夹具 | 105 个 + 聚合/边界夹具 |
| primitives 代码量 | composables + utils 约 1600 行 |
| theme CSS | components 72 文件约 16,800 行 + pro 31 文件约 1,600 行 |
| 令牌变量 | 约 217 个唯一命名（+48 个 @deprecated 兼容命名；字重 12 档） |
| 组件级 CSS 变量 | 378 个 --xy-{block}-{slot} |
var(--xy-*) 引用 | 约 5,000 处（theme 包） |
| color-mix() 使用 | 800+ 处 |
| 最大单文件 | pro-table.vue（1779 行）、col.css（3020 行） |
| 模式 | 成员 | 代表 |
|---|---|---|
| A 纯展示/静态渲染 | icon, link, text, badge, divider, avatar, image, watermark, card, breadcrumb, tag, empty, result, skeleton, alert, timeline, descriptions, collapse, collapse-transition, statistic, countdown, progress, steps | button, tag |
| B 受控表单 | input, input-number, input-tag, auto-complete, select, tree-select, cascader, date-picker, time-picker, time-select, switch, radio, checkbox, rate, slider, check-card, upload, editor | input, select |
| C 浮层 | tooltip, popover, popconfirm, dropdown, dialog, drawer（+B 类弹层复用同一套） | tooltip |
| D 命令式服务 | message, notification, loading, dialog(服务形态) | message |
| E group 复合 | button-group, radio-group, checkbox-group, avatar-group, check-card-group, carousel, form | checkbox-group |
| F 布局/导航 | row, col, space, splitter, scrollbar, affix, backtop, anchor, tabs, menu | row/col |
| G 复杂数据展示 | table, tree, transfer, pagination, scheduler, charts, audio-player, video-player | table |
| H 基础设施型 | config-provider, icon | config-provider |
增强层 31 个按 docsGroup 分：form 9 / page 11 / data 5 / detail 3 / workflow 3；组合关系呈三级金字塔：pro-table（数据工作台）→ list-page（列表页预设）→ crud-page（整页 CRUD），schema 底座为 field-schema.ts（23 种内建组件映射）+ core.ts（协议类型层）。