组件知识体系真正要解决的，不是查文档，而是减少猜测
摘要：组件文档如果只写 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 和工程协作来说，差别非常大。
很多团队会高估组件 API 的复用价值，低估页面模式的复用价值。
但从我的经验来看，真正反复出现的不是“某个 prop 的传值方式”，而是：
- 汇总页 + 明细页
- 多 Tab 报表
- 表格列点击下钻
- 弹窗内表格
- 组织树九级下钻
- 动态表头切换
- 查询区 + 结果区联动
这些东西本质上不是单个组件能力，而是：
围绕组件形成的页面级模式。
如果这些模式不进组件知识库，后续每次遇到相似需求，AI 还是要重新猜一次。
页面级案例并不等于整页代码搬运
页面级案例不是整页复制，而是提炼出：
- 页面模式是什么
- 主导组件是谁
- 关键协作点在哪里
- 最小关键代码是什么
比如一个“汇总页指标点击跳转明细页”的页面级案例，真正要沉淀的不是整个页面，而是这些内容：
- 主导组件：表格组件
- 页面层次：汇总页 → 明细页
- 关键交互：单元格点击
- 参数方式：privateParams 透传
- 关联能力：路由 / 查询配置 / 可能的弹窗联动
这样一来，知识库里保存的是“模式”，不是“业务包袱”。
页面级案例应该归属到主导组件下
页面级案例一旦开始沉淀，很快会遇到一个问题：
这种案例到底归谁？
我的判断一直很明确：
页面级案例仍然应该归属到主导组件下面。
比如：
汇总页点击指标下钻明细页
- 主导组件是表格
- 归到表格组件知识库下
组织树九级下钻报表
- 主导组件是组织树报表组件
- 归到组织树报表组件知识库下
表格列点击弹窗
- 主导行为仍然是表格列交互
- 归到表格组件知识库下，弹窗只作为相关组件出现
这样做的好处是：
- 场景不会复制
- 入口足够稳定
- AI 检索路径更清晰
- 示例永远只维护一份
组件网关真正的价值，是组织检索顺序
光有组件文档还不够，真正让体系稳定的是组件网关。
我后来越来越觉得，组件网关不只是给人看的，它其实是在帮 AI 建立“正确的检索顺序”。
比如一个需求来了，正确顺序不应该是：
全仓库乱搜而应该是：
先找类型
→ 再找组件
→ 再找场景
→ 再找示例这种顺序一旦建立起来，AI 的猜测空间就会显著缩小。
统一入口，比多写几个组件更重要
很多团队做组件体系时，重心都放在“再补一个组件”上。
但实际开发里，真正浪费时间的往往不是少一个组件，而是：
- 已经有组件，但不知道在哪
- 已经有用法，但不知道怎么找
- 已经有类似实现，但不知道谁是主归属
- 已经有工具，但不知道该走哪个入口
这时候，如果没有统一入口，所有知识都会变成离散资产。
而统一入口的意义就在于：
先收敛发现路径，再谈复用效率。
资源维度必须稳定
我现在更倾向于把前端资源按类型分成几类，比如：
- 业务组件
- 布局
- 逻辑复用
- 全局服务
- 工具
这个划分看起来普通，但它有一个关键好处：
分类稳定。
它不是按某个业务域来拆的，而是按资源角色来拆的。
这样即使业务变化很大，入口结构也不会一直震荡。
真正高价值的是“主归属规则”
光有分类还不够，场景一多，马上会遇到另一个问题：
这段知识到底该归到哪个目录下？
比如一个“表格列点击打开弹窗”的场景，它同时涉及：
- 表格组件
- 弹窗组件
- 路由
- 参数透传
如果你没有主归属规则，这类场景就会开始复制：
- 这里存一份
- 那里再存一份
- 最后没人知道哪个是最新的
所以我后来给自己定了一条很重要的规则：
跨组件场景只保留一份，放在主导组件下面。
这样一来，组件网关不仅是目录结构，也是归属规则。
最后一句
组件文档如果只写 API，它最多是一本说明书；组件网关如果只是把文档收集起来，它最多是一个目录。
真正高价值的，是把组件能力、真实场景、主归属规则和页面级案例组织成一个统一知识体系。
这样做的意义不是“文档更全”，而是：
下次再遇到类似问题的时候，不需要再从头猜。