组件知识体系必要性探索
摘要：组件文档如果只写 API，它最多是一份说明书。组件网关如果只做文档导航，它最多是一个目录。真正高价值的，是把组件能力、真实使用场景、主归属规则和页面级案例组织成一个可复用的知识体系，让人和 AI 都少猜一点。
我后来在整理组件体系的时候，慢慢意识到一件事：
组件知识体系真正要解决的，不是“把文档放哪”，而是“怎么让人和 AI 都少猜一点”。
如果一个系统里已经有很多组件、工具、服务、复用逻辑，但使用者每次还是得靠记忆和搜索去判断：
- 这个需求应该用哪个组件
- 这个工具到底归谁管
- 这个场景有没有现成案例
- 这个能力是运行时服务还是开发工具
那这个组件体系其实还没有真正组织起来。
所以我后来开始把这件事拆成两层来看：
- 组件文档本身应该沉淀什么
- 组件网关应该怎么组织这些知识
如果组件文档只写 API，AI 还是不会用
以前我做组件文档的时候，总觉得把 API 写全就够了：
- Props
- Events
- Slots
- Methods
后来我发现，这对人类都不一定够，对 AI 更不够。
因为 AI 真正缺的，不是“这个组件有哪些参数”，而是：
这个组件在真实项目里通常怎么被组合使用。
所以我后来开始把组件文档拆成两层：
- 组件说明
- 使用场景沉淀
只有这样，组件文档才真正变成可复用知识，而不是参数表。
API 只能回答“能做什么”，回答不了“通常怎么做”
很多组件最难的地方，不是它单个 prop 的含义，而是组合方式。
比如一个表格组件，真正复杂的地方可能是：
- 单元格点击跳转
- 弹窗联动
- 多 Tab
- 动态表头
- 组织树下钻
- 查询配置联动
- 权限控制
- 参数透传
这些东西你靠一份 Props 表是看不出来的。
所以如果文档只有 API，AI 在真实场景下还是得重新猜。
场景沉淀才是真正的复用入口
我后来给组件加了 specs/ 目录，用来沉淀真实场景。
结构很简单：
specs/
001-xxx/
spec.md
example.vue其中：
spec.md放场景标题、关键字、来源、组件组合example.vue放关键代码
这样一个组件的知识就不再只是“它是什么”，而变成：
- 它怎么用
- 常见组合是什么
- 类似需求应该参考哪个例子
页面级场景比组件级场景更重要
后来我又发现，有些组件其实已经不只是组件了，它们是页面骨架。
比如报表表格组件。它最常见的问题不是某个 prop 怎么传，而是：
- 汇总页怎么做
- 明细页怎么跳
- 多 Tab 怎么组织
- 组织树怎么下钻
- 动态表头怎么切换
这时候沉淀的就不是单个组件交互，而是：
页面级使用场景。
也就是说，组件知识库不该只写组件 API，还应该沉淀围绕这个组件形成的页面模式。
组件网关真正的价值，是组织检索顺序
光有组件文档还不够，真正让体系稳定的是组件网关。
我后来越来越觉得，组件网关不只是给人看的，它其实是在帮 AI 建立“正确的检索顺序”。
比如一个需求来了，正确顺序不应该是：
全仓库乱搜而应该是：
先找类型
→ 再找组件
→ 再找场景
→ 再找示例这种顺序一旦建立起来，AI 的猜测空间就会显著缩小。
统一入口，比多写几个组件更重要
很多团队做组件体系时，重心都放在“再补一个组件”上。
但实际开发里，真正浪费时间的往往不是少一个组件，而是：
- 已经有组件，但不知道在哪
- 已经有用法，但不知道怎么找
- 已经有类似实现，但不知道谁是主归属
- 已经有工具，但不知道该走哪个入口
这时候，如果没有统一入口，所有知识都会变成离散资产。
而统一入口的意义就在于：
先收敛发现路径，再谈复用效率。
资源维度必须稳定
我现在更倾向于把前端资源按类型分成几类，比如：
- 业务组件
- 布局
- 逻辑复用
- 全局服务
- 工具
这个划分看起来普通，但它有一个关键好处：
分类稳定。
它不是按某个业务域来拆的，而是按资源角色来拆的。
这样即使业务变化很大，入口结构也不会一直震荡。
真正高价值的是“主归属规则”
光有分类还不够，场景一多，马上会遇到另一个问题：
这段知识到底该归到哪个目录下？
比如一个“表格列点击打开弹窗”的场景，它同时涉及：
- 表格组件
- 弹窗组件
- 路由
- 参数透传
如果你没有主归属规则，这类场景就会开始复制：
- 这里存一份
- 那里再存一份
- 最后没人知道哪个是最新的
所以我后来给自己定了一条很重要的规则：
跨组件场景只保留一份，放在主导组件下面。
这样一来，组件网关不仅是目录结构，也是归属规则。
最后一句
组件文档如果只写 API，它最多是一本说明书；组件网关如果只是把文档收集起来，它最多是一个目录。
真正高价值的，是把组件能力、真实场景、主归属规则和页面级案例组织成一个统一知识体系。
这样做的意义不是“文档更全”，而是：
下次再遇到类似问题的时候，不需要再从头猜。