2026-07-21 第十一阶段检索、来源、MCP 与路线元数据记录

目标与证据边界

本阶段继续按“事实与安全错误 → 可运行实践 → 路线结构 → 表达体验”的顺序处理，没有按页面数量批量改写：

1. 逐页判断 RAG 组件、AI 安全与 AI 治理究竟是课程级硬前置，还是角色路线中的推荐顺序；
2. 对冻结的 LangChain Semantic Search 译文做来源、许可、39 个 Python fence 与当前 API 的独立终审；
3. 用原创、锁版本、可离线测试的 Retrieval Layer B 替代“复制上游片段即可运行”的错误学习路径；
4. 对 MCP 18 篇历史参考页逐页追溯仓库路径与许可切换，纠正内容形态和高风险事实；
5. 保持第三方/冻结参考层失败关闭，并用测试确认元数据重标不能绕过发布门禁。

三名只读子 Agent 分别审计路线、Semantic Search 与 MCP；另一名只读子 Agent复核 Retrieval Layer B 设计。主 Agent 统一决定术语、来源边界、修改范围、示例实现和最终验证，子 Agent 未直接修改或合并文件。

“离线示例通过”只证明固定依赖、合成数据与当前 adapter 合同；不证明真实 Embedding、远程 vector store、LangSmith、MCP host/SDK 或提供商服务已经端到端运行。

1. 学习路线元数据 v2 第三批

新增 7 门 v2 课程，覆盖从知识库到 RAG 的检索闭环，以及生产发布附近的安全/治理课程：

课程	稳定 ID	Domain	角色顺序	硬前置
Chunking 策略	chunking	retrieval-and-data	RAG 700/core	[]
Embedding	embedding	retrieval-and-data	RAG 800/core	[]
向量数据库	vector-database	retrieval-and-data	RAG 900/core	[]
语义搜索	semantic-search	retrieval-and-data	RAG 1000/core	[]
Reranking	reranking	retrieval-and-data	RAG 1100/core	[]
AI 安全	ai-safety	safety-governance	四条角色路线 core	[]
AI 治理	ai-governance	safety-governance	Agent 平台 1500/core	[]

全库由 16/56 门 v2 提升到 23/56，剩余 33 门 legacy。五个检索组件的首页都只表达能力准备、按需复习或后续联结，没有“必须完整完成上一门课程”的强语义；因此 knowledge-base 600 → chunking 700 → embedding 800 → vector-database 900 → semantic-search 1000 → reranking 1100 → rag 1200 → evaluation 1300 只进入 RAG track，不制造硬依赖链。

总路线新增一张明确标为“角色顺序、非硬依赖”的 RAG Mermaid 图。完整 AI 安全课程进入四条路线的生产发布附近，AI 治理进入 Agent 平台；它们不能替代更早的章节级安全/评测 milestone，milestone 也不等于提前完成整门课程。

集成测试固定 23 个 ID、五个 RAG order、空硬前置和 AI 安全/治理的平台顺序，并继续校验角色 order 唯一、硬前置闭包与 DAG 无环。

2. Semantic Search 严格终审

2.1 最强可追溯来源不是单一文件

本地译文由官方主 MDX 与两个 tab snippets 展开而成。最接近 2026-05-07 获取日期的可复现复合快照是 langchain-ai/docs@1dd0bd5a：

• knowledge-base.mdx blob 02bc453a836ea4d86d09f5d57569f7863723c99d；
• embeddings-tabs-py.mdx blob 04137e51176697f2ce760e70f786ad4e52c3a984；
• vectorstore-tabs-py.mdx blob 4a2d460f4ee40953d92e9292c9dbb7afeeac4c4e；
• MIT LICENSE blob c38f6f284dc464af69e9f618bc0304d299d0bdf0。

这些文件与本地结构及原始特征错误高度吻合，但抓取时没有保存 deployment revision、响应头或响应哈希，所以只能写“可追溯到复合 blobs”，不能声称线上部署精确对应该 commit。

2.2 运行与许可阻断

• 39/39 Python fence 可由 ast.parse 解析，但普通 .py 只编译 38/39；一个顶层 await 仅适合 notebook/支持 top-level await 的 REPL。
• 15 个 Embedding 与 11 个 vector-store tabs 被展平成一条线性文档，会反复覆盖 embeddings / vector_store；固定输出无法同时对应这些互斥分支。
• PDF 不在仓库，安装说明缺少 langchain-text-splitters 等依赖；OpenSearch、Astra DB、MongoDB、PGVector 与 Pinecone 等分支还有缺失导入、变量、数据库或凭据。
• text-embedding-3-large 默认维度、DeterministicFakeEmbedding 与固定 1536 维输出互相矛盾。测试桩不具备语义能力，且当前实现需要未被 langchain-core 自动安装的 NumPy。
• 当前 InMemoryVectorStore raw score 是余弦相似度且越大越相似；通用 similarity_search_with_score 的语义仍由后端决定。similarity_score_threshold 使用 relevance score，不是任意 raw score。
• LangChain 仓库 MIT 可以覆盖其文档代码与说明，但不能当然覆盖页面复制的大段 NIKE 10-K 输出；公开实质正文还必须保留 Copyright (c) 2025 LangChain 与 MIT 文本。

因此 Semantic Search 继续为 third-party / needs-review，公开站只生成质量待复核 stub。本地页新增复合来源、恢复门禁和四类阻断说明；没有为了减少 stub 数量恢复全文。

3. 原创 Retrieval 主线与 Layer B

Retrieval 与 RAG 组件完成以下重写：

• 用 Mermaid 分开离线摄取与在线查询，并把受信任身份、ACL/filter 下推放在候选离开数据边界之前；Reranker 只接触已授权候选；
• 区分 raw similarity/distance、[0,1] relevance score、threshold retriever 与只返回 Document 的 Retriever；
• 记录 InMemoryVectorStore==1.4.9 没有 relevance 映射，调用该路径会 NotImplementedError，不能因基类有方法就推断支持；
• 补充远程 Embedding 的正文外发、远程 vector store metadata 外发、恶意文档、LangSmith trace、服务端 filter 下推和本地持久化副作用；
• 说明多数 top-k 对无关问题仍会返回候选，“无答案”需要经标注集校准的后端特定门或独立充分性判断。

新增 docs/LangChain/00-初学者路线/examples/retrieval_layer_b/：

文件	作用
in_memory_retrieval.py	透明三维教学 Embedding + 真实 InMemoryVectorStore；稳定 ID、完整 metadata、filter、raw score、Retriever 与 JSON CLI
test_in_memory_retrieval.py	17 项正/负向测试，含重复/缺失 ID、metadata、跨 tenant、score、invoke/batch、CLI 与 AST 无运行时 assert
requirements.txt	固定 langchain-core==1.4.9 与 Python 3.11 兼容的 numpy==2.4.6

示例在添加前拒绝空/重复 ID、缺 metadata、chunk_id != Document.id 和非法 scope；添加后用 get_by_ids 按 ID 建表验证完整往返，不依赖返回顺序。查询 filter 是 InMemory 的进程内 callable，明确不冒充远程数据库 ACL。调用范围使用 tracing_context(enabled=False)，避免全机 tracing 配置让离线教学意外外发 trace。

17 项测试已在 Python 3.11.9 的隔离依赖环境中通过 normal、-O、warnings-as-errors 与组合模式；CLI 输出 langchain-core 1.4.9、NumPy 2.4.6、唯一授权命中 alpha:refund:v1，以及两条 query 对应的稳定 batch ID。精确浮点只检查有限性、方向和数学上应为 1 的教学向量，不保存脆弱的长浮点快照。

4. MCP 18 页来源、许可与事实审计

4.1 内容形态与固定来源

18 页全部是本地中文摘要，不是上游正文镜像或完整翻译；原入口只把一页称为“本地摘要”是不准确的。现已逐页标为 curated / needs-review，但仍位于冻结参考树，因此公开门禁全部生成 stub，不能靠元数据重标发布。

抓取时刻之前最近的官方仓库提交是 76ceb47f，18 个来源路径当时均存在；没有响应哈希或部署 revision，所以该 commit 只是最强近时仓库映射。

许可历史	页面	处置
固定 blob 完整存在于 2026-01-05 许可切换前，MIT	版本管理、示例服务器	恢复候选；仍需固定来源、许可通知与事实复核
页面在切换后创建，普通文档贡献 CC BY 4.0	使用 Agent Skills 构建、客户端最佳实践	恢复候选；必须补项目署名、固定来源、改动说明与通用 CC BY 文本
切换前后均有贡献，单一页级许可证未证明	其余 14 页	继续 stub，等待双重通知支持或迁出后的独立原创重写

4.2 已修 P1

• Elicitation 明确分 form 与 URL mode；form 不得请求密码、API key、access token 或支付凭据。
• Roots 继续明确为协调范围，不是 sandbox/ACL；真实文件边界由 host、OS 权限和沙箱强制。
• 本地 server 的用户确认 UI 属于具体 host，不是 MCP 自动保证的权限模型。
• 远程页面把 Claude Custom Connectors 标为厂商语境；Streamable HTTP session 是 server 可选分配，不是所有远程连接必备。
• 固定来源中的组合 skills 是 build-mcp-server、build-mcp-app、build-mcpb，不再虚构 client/debug/deploy skills。
• Session hijacking 与 prompt injection 被拆成两条威胁链；前者使用 session ID、用户绑定、TLS、Origin、过期、撤销和重认证控制。
• Example Clients 上游页已于 2026-05-27 删除；原 URL 虽最终返回 200，却重定向到入门页。页面改用固定 blob，并明确只是一份历史生态快照。

发布 stub 对 curated / needs-review 参考页现在使用质量/来源待复核原因，而不是误报为“完全缺元数据”；该变化只改善说明，不放宽门禁。

5. 已完成验证

• Retrieval Layer B：17/17，normal、-O、warnings-as-errors 与组合模式均通过；CLI 正常和非法 query 路径通过。
• Python 离线回归：基础组 65 个文件在四种模式下均为 2,491/2,491；连同锁依赖的 LangGraph（8）、CrewAI（9）和 Retrieval（17）隔离组，本轮新鲜复跑共覆盖 68 个文件、每种模式 2,525 项、合计 10,100 次，0 失败、0 跳过。70 个当前测试文件的 path<TAB>file-byte-SHA256 清单哈希为 8213FE452ADAA36FDBFC2B2310C37E82C3EEA1F80C861DF29310079892CCCE0D。
• 本轮严格离线，缓存中缺少 Matplotlib 3.11.0 与 scikit-learn 1.9.0 工件，因此没有把这两个未修改隔离组的第十阶段结果冒充为新鲜复跑；Matplotlib 3.10.5 的补充通过也不计入上述锁版本总数。
• 网站单元/策略测试：npm test 为 45/45。
• 路线与发布策略专项：prepare-content.test.mjs 为 39/39。
• 完整发布构建：npm run build 通过；893 篇源 Markdown 分为 547 篇全文与 346 篇受控 stub，另发布 217 个资源和 3 个生成页，共形成 896 个 Markdown 页面。
• 站点验证：生成 2,394 个 HTML 页面、2,735 个公开文件；本地断链、禁用文件、学习进度泄露、敏感信息泄露、自重定向、表格 wikilink 泄露、交互式 checkbox 与 KaTeX 错误均为 0。
• 依赖审计：npm audit --omit=dev 为 0 个当前 registry 已知漏洞；不代表未来无漏洞。
• git diff --check 通过；新增示例没有 __pycache__ 或 .pyc。
• 未调用真实模型、Embedding provider、远程 vector store、LangSmith 或 MCP server，也未使用凭据。

冷缓存首次恢复 Quartz 插件时曾触发 npm 可选 Rollup 二进制缺失；依赖恢复流程完成后，正式构建与全部发布门禁通过。该现象属于本机冷启动依赖恢复风险，不是内容或链接错误，后续仍应在全新 CI runner 上复核冷缓存可重复性。

6. 核心一手来源

• LangChain Retrieval、v1 迁移指南与当前 Semantic Search。
• langchain-core 1.4.9 固定提交的 InMemoryVectorStore、VectorStore/Retriever与fake embeddings。
• PyPI：langchain-core 1.4.9、NumPy 2.4.6与NumPy 2.5.1。
• MCP 2026-05-07 近时固定 tree、2026-01-05 许可切换与已归档旧 MIT 文档仓库。
• MCP 2025-11-25 Transports、Elicitation与Security Best Practices。

7. 后续队列

1. 先为 MCP 两个 MIT 与两个 CC BY 候选设计页面绑定的精确来源注册、通用 CC BY 许可副本、可见署名/改动说明 HTML 断言，再决定是否恢复；其余 14 页不批量补单一许可证。
2. Semantic Search 不再修补整页翻译；后续把真实语义模型、合成 fixture、gold queries、异步脚本与 provider opt-in contract tests 分层加入原创路线，再评估删除或进一步压缩冻结页。
3. 迁移剩余 33 门 legacy；优先审阅 API、向量基础、数据标注、数据可视化、MLOps 与隐私计算的角色类型，不从 legacy order 猜硬依赖。
4. 让 Homepage、CourseNavigator 与外层 Dataview 共同消费 v2 角色 track；在 56 门全部迁移前，CourseNavigator 继续明确只显示 legacy catalog order。
5. 为真实 Embedding/vector store 增加凭据门控、默认无副作用的 opt-in suite，验证模型 revision、数据外发、服务端 ACL、score 校准、删除与索引迁移。
6. 在 Obsidian 桌面端抽查本阶段 Mermaid、宽表、callout、长代码块与移动端阅读体验；Quartz 构建不能替代 Obsidian UI 验证。

本记录只覆盖第十一阶段，不表示整个长期 /goal 已完成。