这不是一篇"我们选了 X 框架所以很先进"的文章。 这是一篇关于在真实约束下做取舍的记录——技术理想、团队现状、业务节奏，三者之间的反复拉扯，最终收敛成一个可以跑起来的方案。

一、为什么要建一个"面向 AI"的组件库

2026 年初，团队面临一个越来越尖锐的问题：AI Coding Agent 已经深度嵌入日常开发，但它对我们内部组件的理解几乎为零。

Cursor、Claude 等工具可以流畅地写出标准的 Element Plus 代码，因为社区语料足够丰富。但面对公司内部的定制组件——定制表格、复杂选择器、主题系统——AI 只能靠猜。猜错了就是一轮又一轮的手动修正，效率反而比不用 AI 更低。

问题的本质是：AI 缺少关于我们组件资产的结构化知识。

不是 AI 不够聪明，而是我们没有给它足够的上下文。

于是，项目的目标从一开始就不只是"建一个组件库"，而是：

建一个 AI 能正确理解、准确使用的组件资产体系，让 Coding Agent 成为可靠的页面生产力。

二、第一版方案：双栈 shadcn，技术上的"最优解"

2.1 方向的形成

2026 年 2 月 27 日，经过三轮讨论，团队初步收敛到一个方向：

• React + Vue3 双栈，按 shadcn/ui 模式建设
• 以 Tailwind CSS v4 为基线
• 采用 Monorepo 统一管理组件、主题、AI 资产
• 配套面向业务项目的 MCP、LLMs.txt、Skills

选择 shadcn 的理由看起来很充分：

shadcn 的"源码暴露"特性天然 AI 友好——模型可以直接看到组件实现，不需要猜测黑盒 API。而双栈覆盖则确保了 React（BI 项目）和 Vue3（大部分业务项目）都能受益。

2.2 治理原则：比技术选型更重要的事

方案讨论中，一个看似"技术细节"的问题被提升到了核心位置：多项目/多版本治理。

过去的经验告诉我们，组件库最终失控的原因往往不是技术选型，而是版本管理混乱——项目 A 用 Button@1.0，项目 B 用 Button@1.1，最终整个生态碎片化到无法维护。

为此，团队制定了三条不可违反的治理红线：

1. 同一业务项目中，不允许同名基础组件多版本并存
2. 组件库发布的是整体可用快照，不是按组件零散拼版本
3. 所有上层组件都必须与当前最新版基础组件保持兼容

升级策略同样明确：

• 默认策略：向后兼容升级——基础组件更新后，上层组件无需改动即可运行
• 破坏性变更：Fix Forward——在组件库内部同步修复所有受影响组件，修复完成后再发布新快照，不把迁移成本转嫁给业务项目

这套治理原则后来贯穿了所有后续方案的演进，成为少数从未动摇过的决策。

2.3 Monorepo 的工程蓝图

在"双栈 + 共享主题 + AI 资产"同时存在的前提下，Monorepo 是自然的选择：

1gubo-ui/
2  apps/
3    docs/                    # 文档站
4    playground-react/        # React 示例
5    playground-vue/          # Vue3 示例
6  packages/
7    ui-react/                # React 组件包
8    ui-vue/                  # Vue3 组件包
9    theme-tokens/            # 设计 token
10    theme-styles/            # 全局样式
11    chart-theme/             # 图表主题
12  consumer-assets/
13    llms-txt/                # LLMs 上下文模板
14    skills/                  # Skills 资产
15    mcp/                     # MCP 能力定义
16  tooling/
17    eslint-config/
18    tsconfig/
19    scripts/

依赖方向也做了严格约束：

技术栈选型上，推荐了 pnpm workspace + turbo + changesets 的组合——这在 2026 年已是 Monorepo 的成熟实践。

2.4 隐患已经埋下

看起来一切都很完美。但事后来看，有几个信号在当时被低估了：

• shadcn-vue 的 v4 重构仍在 dev 阶段，稳定性信号不足
• 现有 Vue3 业务项目大多运行在 Tailwind v3 上，全面切 v4 存在迁移成本
• shadcn 模式下组件的维护、发布、多版本治理复杂度远高于表面看起来的样子
• 团队对 cva（class-variance-authority）等 CSS 工程实践的学习曲线偏陡

这些约束不是不可克服，但它们叠加在一起时，给了这个方案一个隐性的标签："理论上最优，实践上高风险"。

三、转折：放弃 shadcn，回归务实

3.1 决定性的一天

2026 年 2 月 28 日下午，一场两个多小时的会议，方向发生了根本性调整。

触发点是一个关键事实的确认：UI 侧的设计体系与 shadcn/ui 现有体系不兼容，无法低成本融合。

这不是一个技术问题，而是一个现实问题。如果继续走 shadcn 路线，官方基础组件仍需大幅重写样式和结构，等于是用了 shadcn 的壳但重做了里子——那 shadcn 的核心优势（社区语义统一、AI 语料丰富）就大打折扣。

最终结论简洁而决断：

• 不采用 shadcn 方案
• 基础组件按自有设计体系从零实现
• MVP 阶段只做 Vue3，不做 React
• 历史复杂业务组件不重造，通过 AI 增强使用

3.2 比"放弃"更重要的是"聚焦"

表面上看，这是一次"降级"——从双栈变单栈，从 shadcn 变自研，从全量组件变基础组件。

但实际上，这是一次关键的聚焦。

会后沉淀的核心判断是：

方案优先级是：结果价值 > 技术炫技。

具体来说：

• 现有业务项目以 Vue3 为主（除 BI 外），单栈覆盖率已经足够高
• shadcn 的"源码暴露"优势，可以用"清晰的设计体系 + Skills 增强"来替代
• 历史复杂业务组件（表格、Select Pro 等）短期重写成本高、收益低，不如让 AI 学会正确使用它们

这个判断让整个项目从"建一套完美的组件库"转向了"让 AI 能快速产出风格一致的业务页面"。目标没变，路径变了。

3.3 新的资产分层

方案调整后，资产体系重新梳理为四层：

关键变化在第四层——AI 增强层不仅服务于新组件库，也覆盖了历史复杂业务组件。这意味着即使不重写旧组件，AI 也能通过 Skills 学会正确使用它们。

四、1.0 阶段：让"跑通"先于"完美"

4.1 小步快跑

进入 2026 年 3 月，方案进一步细化为 1.0 阶段的可执行计划。

核心策略是"小步快跑"：

1. 先挑 1 个模板页，跑通端到端流程
2. 在流程稳定后，再逐步扩展到其他模板页
3. 每扩展一个模板页，都沉淀可复用的 Prompt 资产与规则

不追求一次性铺开全部模板页。第一步的目标是验证整个链路是否成立。

4.2 Skills 优先：又一次务实的选择

1.0 阶段最初的技术路线设想是 Skills + MCP + Prompt 资产 三件武器协同。但在 3 月 3 日的方案对齐会议上，这个组合被进一步精简：

1.0 阶段优先通过 Skills 实现全部 AI 增强能力，MCP 暂不建设，后续再考虑。

这不是一个随意的"砍需求"，而是基于几个务实的判断：

• Skills 安装在客户端，使用时不依赖网络环境——对内网开发场景更友好
• Skills 的实现和调试链路更短，适合快速验证效果
• 1.0 阶段核心目标是"跑通"，而不是"架构完美"

当然，这个选择也有代价。Skills 和 MCP 各有明确的优劣势：

MCP 的核心优势在于**"更新一次，全局生效"**——文档在服务端维护和更新，客户端只要 MCP 服务脚本本身稳定，就不需要推送任何更新，所有开发者下次调用时自动获取最新知识。这在组件库文档频繁迭代的阶段尤其有价值。

但在 1.0 阶段，我们需要的是最短的验证路径。Skills 恰好满足这个需求——它让整个链路从"开发 MCP Server → 部署 → 配置网络 → 联调"简化为"写 Skills → 安装 → 验证"。

关于 MCP 协议本身的理解和 Node.js 实现，可以参考我之前的文章：用 Node.js 开发一个 MCP 服务：从协议本质到最佳实践。后续当 Skills 验证跑通、Prompt 资产趋于稳定后，迁移到 MCP 是一个自然的演进方向。

Skills 在 1.0 阶段承担的完整职责

Skills 从最初设想的"环境检查入口"，升级为整个 AI 增强体系的唯一载体：

• 环境校验：检查项目依赖配置是否就绪（ElementPlus、主题库等）
• 知识供给：携带组件索引、使用规则、示例代码等结构化知识
• Prompt 资产分发：将组件级和模板级的 Prompt 资产内置于 Skills 中，在 AI 会话中按需注入
• 版本化交付：Skills 本身带版本号，确保不同项目可以使用与其组件版本匹配的知识资产

Prompt 资产：效果的核心

Prompt 资产是整个体系中对生成质量影响最大的部分。它按两个维度建设：

• 组件维度：强调组件使用边界、参数约束、常见错误与反例
• 模板维度：强调页面结构、视觉一致性、组件组合策略与交付标准

Prompt 资产以 Markdown 形式沉淀，在 1.0 阶段通过 Skills 携带并注入 AI 会话上下文。

整个协作流程是：

4.3 Prompt 资产的制作方法论

以 common-table-v2（一个内部的复杂表格组件）为例，1.0 阶段探索出了一套 Prompt 资产的制作方法。

每个组件级 Prompt 资产至少包含六个必要模块：

1. 组件定位

• 适用场景（何时用）
• 不适用场景（何时不用）
• 与相似组件的选型边界（和谁容易混淆）

2. 前置条件

• 依赖要求（如 ElementPlus、主题库）
• 环境检查要点

3. 最小可用接入方式

• 推荐最小示例
• 生成代码时必须满足的结构约束

4. 关键配置约束

• 高频参数组合规则
• 必选 / 可选参数说明

5. 常见错误与反例

• 易错写法
• 正确修复方式

6. 结果验收标准

• 可运行性
• 视觉一致性
• 交互与数据行为完整性

在必要内容完整后，还可以逐步补充增强内容：场景化生成模板、代码风格约束、失败案例库、质量检查清单等。

核心思路是：先跑通再完善，以生成效果为验收依据持续迭代。 这些 Prompt 资产在 1.0 阶段随 Skills 版本一起发布，后续如果引入 MCP，可以无缝迁移到服务端按需分发。

调试流程也被标准化：

这个循环保证了 Prompt 资产不是拍脑袋写出来的，而是从真实失败中迭代出来的。

五、复盘：几个值得记住的判断

5.1 技术选型的"兼容性"不只是 API 层面

shadcn 方案被放弃，根因不是 shadcn 不好，而是它的视觉体系与我们的设计体系不兼容。这种"不兼容"在技术评估阶段很容易被忽略——API 层面看起来都能对接，但到了样式和交互细节层面，融合成本远超预期。

选型时不仅要看技术 API 是否能集成，还要看设计语言是否能融合。

5.2 "不重写"有时是更好的决策

面对大量历史复杂业务组件，本能反应是"迁移到新库"。但现实是：

• 这些组件已经在生产环境跑了很久，稳定性经过验证
• 重写意味着重新踩一遍所有边界 case
• 迁移期间新旧并存的混乱可能比不迁移更糟

最终选择用 Skills 增强 AI 对旧组件的使用能力，而不是重写它们——这对页面产出目标的影响不大，但显著降低了时间和风险。

5.3 "先跑通"不等于"不考虑演进"

从 MCP 退回到 Skills 优先，看似是又一次"降级"。但这个决策有一个关键前提：Skills 中沉淀的 Prompt 资产，未来可以无缝迁移到 MCP。

换言之，我们不是在"放弃 MCP"，而是在选择一个更短的验证路径来打磨内容本身。当 Prompt 资产的质量和覆盖范围通过 Skills 验证稳定后，迁移到 MCP 只是换一个分发通道——内容不需要重做。

这个思路值得泛化：在架构决策中，如果两个方案的核心资产是可迁移的，那么先选实现成本低的方案验证资产质量，再迁移到更优的分发架构，往往是更明智的路径。

5.4 AI 的瓶颈不在智力，在上下文

当我们说"AI 用不好我们的组件"时，问题往往不是模型能力不够，而是我们没有给它足够、正确、结构化的上下文。

Prompt 资产的核心价值就在这里：它不是在"教 AI 写代码"，而是在给 AI 它所缺失的领域知识——哪些参数必选、哪些组合会出 bug、哪些写法看起来对但实际上不行。

这些知识原本只存在于资深开发者的经验里。把它们结构化、资产化，就是在把"口口相传"变成"系统能力"。

5.5 Monorepo 不是必须的起点

最终方案对 Monorepo 的态度是"需要评估，不急于拍板"。短期先按 npm 包模式快速落地，同时保留向 Monorepo 演进的空间。

这个判断值得借鉴：在 MVP 速度与长期治理之间，选择不阻塞当前交付的路径，同时不关闭未来演进的可能性。

六、方案演进时间线

最后，用一张时间线回顾整个演进过程：

七、结语

回头看这次演进，最大的收获不是最终方案本身，而是做决策的过程：

• 敢于在投入了大量设计精力后，因为一个关键事实而调整方向
• 在"技术最优"和"现实可行"之间反复选择后者，并且不觉得这是妥协
• 把"AI 能正确使用"从锦上添花变成核心设计目标
• 每一次"简化"都保留了向更完整架构演进的可能性

组件库建设是一个长期工程，这只是第一个阶段的起点。但如果你也在面对类似的问题——如何让团队的组件资产真正被 AI 有效消费——希望这篇记录能提供一些有价值的参考。

毕竟，让 AI 用对你的组件，本质上是在把团队的隐性知识变成显性资产。 这件事的价值，远不止于组件库本身。