@ant-design/cli 的设计哲学：为什么不用向量数据库做传统RAG？
一、它的设计目的是什么？算是 antd 的“附赠品”吗？
官方文档中直接说明：
antd 官方为 AI Agent 打造的「antd 知识的权威离线查询接口」。
它确实是 antd 生态的“基础设施型附属品”，但这不是简单的营销赠品——它解决的是一个真实痛点：LLM 对 antd API 的记忆不可靠（版本多、API 变化快、幻觉率高）。SKILL.md 的核心规则说得很直白：
“Always query before writing — Don’t guess antd APIs from memory.”
它让 agent 在写 antd 代码前，能从权威、离线、版本精准的数据源查询事实，而不是靠模型记忆或临时搜网页。这也解释了它为什么做了这么多工程：
- 构建期把 antd 全量文档结构化打包（
data/下 60+ 个版本快照） - 运行时零网络（离线是设计约束，不是巧合）
- 提供 MCP server + SKILL +
antd setup命令，全面接入 agent 生态
二、对比 Context7 这类 MCP 工具
两者都是“给 LLM 提供文档查询”的 MCP 工具，但设计哲学几乎相反：
| 维度 | antd-cli | Context7 类工具 |
|---|---|---|
| 数据来源 | antd 官方仓库 checkout，构建期抽取 | 联网抓取第三方文档（URL 解析） |
| 查询方式 | 确定性结构化查找（findComponent O(n) 遍历） |
向量语义检索 |
| 版本精度 | versions.json 索引 → 精确到 5.12.x 历史快照 |
通常只有“当前最新版” |
| 网络依赖 | 完全离线 | 运行时需联网 |
| 结果形式 | 结构化字段（{name, type, default, since}） |
相关文档片段 |
| 正确性保证 | 高（antd 官方数据 + 构建期强校验） | 中（第三方抓取可能有损、过时） |
| 覆盖范围 | 仅 antd | 成千上万个库 |
关键差异是“精确 vs 相似”：antd-cli 回答 Button 在 5.12.0 下的 props 是确定性的——同一输入永远同一输出；而语义检索是概率性的，可能返回相似但错误的 API。对 antd 这种“版本敏感、API 严谨”的场景，精确性压倒一切。这也是它敢在 loader.ts 里做“最近的更早 minor”这种精细版本匹配的原因——Context7 这类工具做不到按版本快照回答。
三、为什么不用向量数据库？
这是它设计里最清醒的决策，有四层原因：
1. 数据结构化程度极高，不需要语义检索
props / tokens / demos 都是 key-value 结构化数据。查询是精确 key 匹配（组件名 → prop 名），不是“找一段意思相近的话”。向量检索擅长的是非结构化文本的模糊匹配，在这里是杀鸡用牛刀，还引入不确定性。
2. 精确性 > 相似性
antd 的 API 答案是“非对即错”的。例如 Button.size 在 v5 是 large | middle | small，v6 改成 large | medium | small——语义检索可能返回“相似的”但错误的值。向量相似度高的结果 ≠ 正确结果。对工具输出来说，确定性是可验证的前提。
3. 数据量太小，向量化是负收益
整个 data/ 打包也就几百 KB（发布时还压缩成 .json.gz）。一次 findComponent 的 O(n) 数组遍历是纳秒级。而向量数据库需要：嵌入模型（要么内置导致体积爆炸、要么联网）、索引构建、相似度计算——成本和复杂度全无必要。
4. 离线约束
向量检索离不开嵌入模型：内置会让包体积从几百 KB 膨胀到几十 MB；联网又破坏“运行时零网络”这个核心设计。而 detectVersion → loadMetadataForVersion → findComponent 这套纯文件读取 + 遍历的方案，天然满足离线。
四、它算 RAG 吗？
不算传统 RAG，但属于“检索增强”家族的一员。
| 概念 | 定义 | antd-cli 符合吗 |
|---|---|---|
| 传统RAG | 非结构化文档切块 → 向量化 → 语义检索 → 拼进 prompt 增强生成 | ❌ 没有嵌入、没有向量、没有语义相似度 |
| 工具调用检索（Tool-use retrieval） | LLM 调用一个确定性检索工具获取事实，返回结构化结果 | ✅ 这正是它的实现 |
| 知识库查询 | 从预先结构化/打包的知识源精确查询 | ✅ |
它是“检索增强”思想的一个确定性实现。用结构化精确检索替代了 RAG 中的“向量检索”组件——效果上比 RAG 更适合“事实型、版本敏感”的知识（antd API 恰恰是这种）。
如果非要套检索增强生成的框架：agent 拿到 antd info 的 JSON 结果后，把这份事实喂给 LLM 生成代码——这个闭环在架构上是 RAG 式的（外部知识 → 检索 → 增强 LLM 输出），但检索实现不是向量化，而是结构化查找。
五、总结
antd-cli 是 antd 官方为 AI agent 做的“确定性知识检索工具”。它刻意不用向量数据库、不做传统 RAG，是因为 antd API 查询需要的是“精确事实”而非“语义相似”——而结构化快照 + 版本索引 + O(n) 查找，是满足“离线 + 精确 + 版本敏感”这三个约束的最简方案。
它是一个很好的反例：不是所有检索都要上 RAG 和向量库——当数据是结构化的、查询是精确的、正确性要求是硬约束时，确定性查找永远优于语义检索。