从零开始 · 面向 mcpgw 读者

用图解理解整个 mcpgw 网关项目

这套教程带你层层深入：先建立 mcpgw 的宏观全景（是什么 / 架构 / 一次调用的生命周期），再写透向量检索专章（Embedder / 缓存 / VectorStrategy / 装配配置）与 Hybrid 检索（RRF）。其余各 crate 内部（09–14）为施工中占位，将逐步补全。每一课都对照 mcpgw 真实源码（crate 文件 + 符号名）。

宏观理解细节 / 源码生活类比关键要点

📌 对照 mcpgw master（M2-A 向量检索合并后）· 最后核验 2026-06 · 源码引用以"文件 + 符号名"为主（行号会随代码更新而变）

第一部分 · 宏观全景

01mcpgw 是什么工具爆炸 · 3 元工具渐进式发现 02整体架构全景workspace 各 crate · 依赖方向 · 传输 03一次工具调用的生命周期search → get_details → call 数据流

第二部分 · 检索深入 · 向量检索

04向量检索总览为何语义检索 · 对比 BM25 · 透明降级 05Embedder 抽象 & OpenAiEmbedderEmbedder/EmbedError · 独立 crate · env 密钥 06CachingEmbedder 缓存内容哈希缓存 · 跨 rebuild 持久 · 锁纪律 07VectorStrategy 余弦 + 降级余弦 + 内置 BM25 双重降级 · 防 NaN 08装配与配置build_strategy/embedder · [retrieval.vector]

第三部分 · 各 crate 内部

09catalog 工具目录工具目录与命名空间（施工中） 10upstream 上游 I/O活上游 I/O · 连接/摄取/路由（施工中） 11gateway + metatoolsArcSwap 快照 · 3 元工具（施工中） 12downstream 下游服务rmcp ServerHandler · stdio + HTTP（施工中） 13retrieval 内核与 BM25RetrievalStrategy(async) 与 BM25（施工中） 14config 配置系统[server]/[upstream]/[retrieval] 配置（施工中）

第四部分 · 后续

15Hybrid 检索（RRF）RRF 融合 BM25+向量 · opt-in · 默认仍 bm25

没有匹配的课程，换个关键词试试。