2026-07-22 第二十四阶段检索、工具与 Agent 运行时深审记录
阶段结论
本阶段把学习路线中的“检索证据 → 上下文/Skill → MCP 能力传输 → Tool Calling 的授权执行 → Agent 状态恢复 → 框架实现”收敛为可核验的边界链。重点不是增加某个框架的 API 清单，而是让学习者能区分：谁提出动作、谁持有身份和授权、什么可安全重放、什么只能对账，以及离线合同测试究竟不能证明什么。
覆盖 RAG、Embedding、Reranking、Agent Skills、MCP、Tool Calling、Agent 核心 与 LangGraph。
本阶段不证明什么
固定 fixture、内存 host、SQLite 单机竞争、无密钥 shim、静态 provider profile 和网站构建不能证明真实模型路由、生产身份、人工批准、真实 MCP host、供应商 SDK、外部副作用、跨区域故障恢复或 exactly-once 已经成立。它们只证明当前教学合同会在声明的负向路径上失败关闭，且能在受限环境重复运行。
多 Agent 分工与主 Agent 复核
- 检索专项逐篇收紧 RAG 主线、Embedding、Reranking 与语义检索的 provenance、ACL、预算、数值和评测边界；主 Agent 复跑各项目测试并修复复核发现的问题。
- 协议与能力专项核验 MCP 稳定规范、Streamable HTTP cursor/会话语义、任务结构边界及 Agent Skills 的客户端差异、资源路径和输入大小限制。
- Tool Calling 专项完成 dispatcher 与 SQLite outbox 两层的运行时审阅；独立只读审阅实际复现深嵌输出、审批时间上界和跨 provider profile 重放问题，主 Agent 补测试并修复。
- Agent 核心专项审阅状态机、审批、预算、receipt、checkpoint 与恢复语义；LangChain 专项以官方文档和隔离解析环境核对
create_agent、structured output、interrupt/replay、版本快照和四模式命令。 - 最后一名只读 Agent 横向比对八个课程目录的术语、学习顺序、wikilink 和渲染态本地资源链接；未发现 P0、P1 或 P2。
开始时工作树已包含本阶段范围内的大量未提交修改；本阶段未回退或重归属既有工作，只在逐页阅读、上下文核验和回归后补充实际发现的问题。
关键改动
检索：把“命中”还原为带身份与访问边界的证据
- RAG 01–11 进一步明确 source/provenance artifact、离线引用、ACL-before-score、投影、版本、预算、跨层评测和外部来源工件的关系；检索分数、引用或摘要都不能越过当前访问控制或替代原始证据。
- Embedding、Reranking 与语义检索示例收紧超大数值、确定性排序、降级与评测边界，避免 Python 数值行为或“全绿”结果被误读为向量空间/线上召回已经可靠。
- 学习顺序保持“语料与切分 → 表示/检索 → 重排与生成 → 评测/安全/生产证据”，并把 retrieval 产物和 Agent/Tool 的不可信输入边界相连。
Skills、MCP 与 Tool Calling：职责不再混写
- Agent Skills 的新入口区分 Skill（给客户端的渐进式工作说明）、Tool Calling（应用执行一个受控动作）和 MCP（客户端—服务器能力协议）。客户端可支持的目录、自动激活和预授权不同，Skill 文件本身不构成身份、授权或 sandbox。
- Skill 验证器拒绝非规范资源引用，文本统计示例统一 1 MiB UTF-8 输入上限；56 项测试锁定路径逃逸、frontmatter、脚本与资源边界。
- MCP 课程以稳定
2025-11-25规范为基线，明确候选草案不应当作既定事实；HTTP loopback 收紧 JSON 深度、cursorless 轮询、POST SSE 与 GET cursor 的边界，离线消息验证将任务对象限制为结构验证，而非虚构调度/持久化能力。 - Tool Result v2 dispatcher 现在先执行有界 JSON 域校验再递归扫描敏感键，超深 handler 输出会生成
OUTPUT_CONTRACT_VIOLATION，不再抛出递归异常。审批有效期要求now < expires_at <= MAX_PORTABLE_UNIX_SECONDS；内存 idempotency record、unknown outcome 和 status reconciliation 都绑定首次 provider/API family/adapter revision，跨 profile 只能 conflict，不能借 replay 绕过批准或对账。 - SQLite 层与内存层对齐上述时间/profile 语义，并在持久化审计中复核。教材继续明确这只提供 at-least-once-compatible primitives，而不是分布式 exactly-once。
Agent runtime 与框架：恢复重做动作，不重写历史决策
- bounded Agent 项目恢复 pending 工作时执行冻结 action，而不是重新跑 policy 生成新动作；approval target scope、lookup observation、pending close contract 与 receipt 语义均进入 checkpoint 校验。
- 等待人工批准的轮询不消耗步骤预算，receipt 查询会消耗工具预算；写入的 transient/permanent 异常、畸形 receipt 和“可能已写入但结果无效”均失败关闭，并保留显式 reconciliation 所需的 action/target/idempotency 信息。
- LangChain 课程补齐 normal、
-O、-W error、-O -W error四模式命令，并让每个命令从仓库根目录独立运行；课程区分固定教学合同与动态生态快照。当前核验快照为langchain 1.3.14、langgraph 1.2.9、langchain-core 1.5.0，而 LCEL 教学示例明确固定并实际验证langchain-core==1.4.9。
跨课程术语与依赖边界
| 概念 | 本轮稳定含义 | 不能替代什么 |
|---|---|---|
| Skill | 客户端可渐进读取的工作说明和资源包 | 身份、授权、工具执行或 sandbox |
| MCP | 客户端与服务器之间发现、调用、资源/提示和传输的协议 | 用户授权、业务对象访问控制或审批 |
| Tool Calling | 模型提出、宿主验证并执行的受控应用动作 | 模型拥有服务凭据或任意外部副作用权限 |
| approval | 对特定新 intent、主体、参数、profile 与版本的人工确认 | 当前 AuthZ、资源状态或安全 replay 的永久通行证 |
| AuthZ | 执行/恢复时按当前主体和资源重新判定的许可 | approval、idempotency key 或 hash |
| idempotency / replay | 同作用域、同语义、同 provider profile 的重复抑制或结果复用 | 跨 provider 迁移、未知结果自动成功或 exactly-once |
| provenance / ACL projection | 检索证据的来源身份、版本与当前可见投影 | 相关性分数、生成引用或模型断言 |
| checkpoint / receipt | 可校验的运行时恢复状态与下游结果证据 | 真实分布式提交、签名来源或仍然有效的权限 |
来源、原创与第三方材料边界
本阶段新增中文讲解、Mermaid 图、表格、教学代码、fixture 和测试均为本项目原创；仅概括一手规范、官方文档和论文中的工程边界，未复制无明确再分发许可的正文、图或代码。核心核验来源包括：
- Model Context Protocol specification 2025-11-25、MCP transports、MCP authorization 与 MCP tasks；
- Agent Skills specification 与 GitHub Copilot agent skills documentation（客户端差异仅作边界说明）；
- OpenAI function calling guide、LangChain agents、LangChain structured output、LangGraph interrupts 与 langchain-core on PyPI；
- 各检索课程已列出的原始论文、数据库/检索系统文档与 RAG 官方资料；本记录不把它们的版本快照或离线实验结果夸大为线上检索质量证明。
验证证据
| 检查 | 结果 |
|---|---|
| RAG 离线项目 | 73、72、37、42 项测试，均在四种 Python 模式通过 |
| Embedding / Reranking | 32 / 30 项测试，均在四种 Python 模式通过 |
| Agent Skills | 56 项测试，四种模式通过；validator 与文本统计 CLI 输出符合合同 |
| MCP | 离线消息验证 108 项、HTTP loopback 80 项，均在四种模式通过；PASS/BLOCK CLI 已运行 |
| Tool Calling | dispatcher 120 项、SQLite persistence 94 项，均在四种模式通过；18 场景、23 步 fixture CLI 通过 |
| Agent 核心 | 68 项测试，四种模式与 demo 通过 |
| LangChain / LangGraph | 离线循环 63、检索 17、create_agent 8、SQLite interrupt 10 项，均在四种模式通过；LCEL 固定合同实际运行 |
| 跨课程终审 | 八个目录的 wikilink 与渲染态本地资源链接可达；术语、计数和学习依赖无 P0/P1/P2 |
| 网站测试与发布验证 | .website 的 npm test：48/48 通过；npm run build 成功；发布校验产出 927 个公开页面、231 个资源，0 个本地断链、禁止文件、敏感泄漏或 KaTeX 错误 |
后续队列
- 在隔离、最小权限、成本上限和脱敏前提下接入真实 MCP host、provider SDK、身份系统、审批流和下游 API，记录精确版本、真实异常和回滚路径；不要把教学 fixture 直接接生产。
- 为跨进程/跨区域恢复补 durable quota、fencing/lease、provider side idempotency、签名/来源验证和可审计审批，而不是扩大内存或单 SQLite 教学实现的承诺。
- 针对真实语料、权限变化、长上下文和业务目标持续评测 RAG；将 provenance/ACL/评测样本的治理接入受控制品库，而不是凭单次离线结果冻结结论。
- 随 MCP、Agent Skills、LangChain/LangGraph 和供应商 API 演进，按课程的
source_checked、版本锁和集成测试更新动态内容；固定教学合同应保留复现环境与迁移说明。
本记录聚焦第二十四阶段；本轮完整交付以课程内的 source_checked、版本锁、交叉链接和最终发布验证为准。