AI Agent Engineer

AI Agent Engineer

2026-07-21 第十六阶段工具协议与 RAG 生命周期深审记录

15 min read

2026-07-21 第十六阶段工具协议与 RAG 生命周期深审记录

阶段结论

本阶段对 Tool Calling、MCP、RAG与知识库构建执行协议、授权、恢复、生命周期和资源边界深审。课程顺序与顶层知识域未改变；重点是修复会让“离线测试全绿”仍掩盖越权、审计证据替换、请求状态耗尽或重复投递的合同缺口。

本阶段确认并修复了四条高风险链路：

  • Tool Result v2 的 call binding 原先没有覆盖 downstream request、receipt 与 status_ref，替换恢复证据后仍可能保持其余摘要合法；
  • SQLite 持久化 adapter 未完全继承 v2 的审批者身份、右开过期边界、业务状态复核与 status-query 用途隔离；
  • 知识库查询原先可把搜索投影 ACL/正文当作在线事实，投影单边扩权或正文篡改可能在后台对账前进入查询路径；
  • MCP validator 与 Streamable HTTP 教学服务器分别存在无效成功响应提前消费 pending request、无 cursor 轮询重复交付同一 SSE event 的状态语义问题。

RAG 两个离线项目同时补上文件、JSON 深度、集合、来源正文、top-k 与去重窗口预算；source event ID 不能再被绑定到另一条事件。课程明确区分“无密钥摘要的一致性检查”和“跨信任边界真实性证明”，不把 SHA-256 自洽误写成签名、MAC 或来源认证。

结论边界

本阶段证明当前标准库教学实现、fixtures、负向测试、CLI 和公开站点构建自洽；不证明真实 Provider/MCP SDK、OAuth/IAM、LLM 语义质量、分布式 exactly-once、持久事件总线、密码学 attestation 或生产容量。长期 /goal 继续保持 active。

多 Agent 协作与接管

主 Agent 冻结了共享术语、事实日期、目录边界和验收方法，并把工作拆给三个专项 Agent：

  1. Tool Calling 运行时、审批、幂等与恢复合同；
  2. MCP schema、生命周期、授权与 Streamable HTTP；
  3. RAG/知识库来源、投影、ACL 与 provenance 生命周期。

三个专项 Agent 完成了资料核对、攻击面定位、缺陷复现或部分修改，但随后同时触发服务用量上限，未能完成各自收口。主 Agent 没有把中断状态写成“子 Agent 已完成”，而是接管其工作区修改，逐项检查实现、补测试、统一文档并重跑全部门禁。接管后额外发现 SQLite adapter 的 v2 时间边界兼容回归，以及未授权知识候选在 ACL 过滤前消耗 limit 的非干扰问题。

所有 Agent 均未 stage、commit、push、reset 或修改分配范围外的用户状态；跨课程术语、测试数字、来源日期、迁移边界和最终链接由主 Agent 统一处理。

Tool Calling：从结果摘要到完整恢复证据

Audit v2 与调用绑定

Tool Result v2 离线项目现在把 call_binding_sha256 绑定到：

  • tenant、subject、provider/API family、response/call/operation；
  • idempotency key、adapter 与完整工具合同；
  • request/result SHA-256；
  • downstream request ID、receipt ID 与 opaque status_ref。

这样只替换 receipt 或恢复引用也会导致重算失败。call_fingerprint 增加 dispatch/query_status 用途，已经用于状态查询的 provider call identity 不能再发起新写操作。

审批、TOCTOU 与未知结果

审批摘要新增 response ID 和 approver_id；运行时验证审批者 allowlist、字段形状与 now < expires_at。首次退款写入前重新读取当前订单状态；审批后订单变为不可退款时返回业务规则拒绝。写 handler 抛异常或输出合同失败不能被解释为“肯定没有副作用”，而是进入 unknown 并阻止盲目 dispatch 重放。

Fixture 在 JSON 解析前限制为 65,536 bytes，并限制 case、step、角色、标识符、时间和可移植 JSON 域；本机文件路径不会进入读取错误。

SQLite adapter 升级

SQLite 持久化项目升级为 persistent-tool-runtime-v2：

  • ledger 持久化 approver_id 并把它纳入审批摘要复算；
  • intent 接收与 worker 下游提交前分别检查业务状态；
  • status helper 为查询派生独立 host-owned call identity，并绑定 query_status purpose；
  • portable UTC、approval TTL 与 lease window 共同在 reservation 前检查；
  • 旧 v1 数据库被明确拒绝，当前没有原地迁移工具，避免把缺少新列的旧表静默当成 v2。

接管回归最初暴露 77 项中的时间边界失败：新的 approval TTL 上界比旧 lease-only “安全时间”更严格。修复后没有放宽新合同，而是让测试时间同时满足 approval 与 lease 两个窗口，并把持久化测试扩展到 81 项。

MCP：稳定规范、pending 原子性与教学传输语义

课程以 2026-07-21 当日官方稳定版 2025-11-25 为实现基线；官方页面中的 2026-07-28 仍是相对当前日期的 Draft RC，不写成已发布稳定规范。授权章节分别处理 token passthrough、confused deputy、SSRF 与工具结果提示注入，避免把四类威胁压成同一个“OAuth 问题”。

离线 validator 现在：

  • 显式区分 JSON-RPC request、notification、success response 与 error response；
  • 在读取和解析前限制文件大小、JSON 深度、字符串、数组、对象、schema 递归与 pending 数量；
  • 递归验证声明的教学 JSON Schema 子集，并拒绝未实现关键词；
  • 覆盖 tools/list、sampling text result 与 tasks/list 的有限结果合同；
  • 对尚未实现的 prompts/logging/completion/tasks get/result/cancel 明确失败，而不是接受未验证成功响应；
  • 只有 method-specific 成功结果通过后才消费 pending request，合法 JSON-RPC error 可以终结 pending，但不伪造业务成功。

Loopback Streamable HTTP 服务器限制 JSON 深度，并把无 Last-Event-ID GET 明确实现为教学级 at-most-once poll：同一 session 的第二次 cursorless GET 不会重复返回上一事件；显式 cursor replay 仍绑定 session。本实现没有 durable queue、ack、retention、断线活性或跨实例 session store，不能据此声称生产可靠投递。

RAG 与知识库：先授权候选，再检查投影

离线可引用问答与 provenance

离线可引用问答限制 fixture bytes、JSON 深度、文档/query/fact/list 数量、阶段候选和上下文预算；读取失败不回显本机路径。来源到引用证据链进一步限制来源 bytes、事件/query 数、subject groups、top-k 与 processed-event 去重窗口。

Provenance engine 为每个 event_id 保存类型化事件指纹：完全相同重放为 noop，同 ID 改绑 tenant、document、sequence、content 或 ACL 会失败；内存窗口达到 10,000 项后停止接收新 ID，而不是静默遗忘旧绑定。生产实现仍需持久 dedupe、归档、轮换与告警。

在线知识查询的可信事实边界

知识库增量项目不再把 search_acl 或 search_revisions.content 直接当作事实：

  1. published pointer 同时连接 canonical revision 与搜索投影；
  2. canonical ACL 在关键词匹配与 limit 窗口前执行；
  3. 未授权文档不返回，也不消耗公开候选窗口；
  4. 对已授权候选重新计算 canonical content/source/build hash、搜索正文 hash，并比较 canonical/search ACL；
  5. 投影单边扩权无法获得可见性，后台 reconcile() 会报告不一致；已授权候选的正文或 ACL 不一致会让查询直接失败关闭。

这修复了已复现的高风险反例：篡改 search_acl 给 guest 授权，或篡改搜索投影正文注入私有 canary，在旧实现中可能早于 require_reconciled() 进入返回路径。新增测试还证明排在前面的私有候选不会挤占授权用户的 limit。

这里的 hash 仍只证明当前可信代码下的内部一致性。若攻击者可同时改写 canonical 正文、ACL、全部 hash 与查询代码，必须依赖受保护事实存储、MAC/签名、远端 attestation 或其他独立信任根。

总路线与 Markdown 修复

All of AI 中两张基线表原先把 Obsidian alias 的裸 | 当成表格分隔符，导致源码列数错误。现已转义 alias pipe 并恢复四列角色路径表与两列硬前置证据表。其他由站点生成流程专门规范化的路线快照没有做机械批量替换。

核心来源

本阶段优先使用官方规范、官方产品文档和原始论文，动态事实复核日期为 2026-07-21：

验证证据

检查结果
Tool Result v2112 项，normal 与 -O -B -W error 均通过；18 case、23 step CLI 双模式逐字一致
SQLite 持久化81 项，normal 与 -O -B -W error 均通过；unknown 退出码 1、status 恢复退出码 0，双模式输出逐字一致
MCP validator101 项，normal 与 -O -B -W error 均通过；CLI 双模式逐字一致
MCP loopback80 项，normal 与 -O -B -W error 均通过；demo/attack CLI 双模式逐字一致
RAG cited QA71 项，normal 与 -O -B -W error 均通过；正常 evaluate 为 0、故障为 1，双模式逐字一致
RAG provenance71 项，normal 与 -O -B -W error 均通过；正常 evaluate 为 0、故障为 1，双模式逐字一致
Cross-layer adapter36 项，normal 与 -O -B -W error 均通过
External Provenance v242 项，normal 与 -O -B -W error 均通过
Knowledge Store38 项，normal 与 -O -B -W error 均通过；主程序双模式逐字一致
本阶段 Python 合计每种模式 632 项，normal 与优化模式共 1,264 次用例执行
站点单元测试46/46 通过
完整公开构建907 个源 Markdown；561 个全文、346 个 fail-closed stub、220 个资源；生成 910 个 staged Markdown、2432 个 HTML 页面与 2776 个 public files
导航与发布门禁57 个课程入口、10 个知识域、4 条角色路径、72 个导航文件夹；broken local links、禁止文件、进度/敏感信息泄漏、自重定向、表格 wikilink 泄漏、交互 checkbox 与 KaTeX 错误均为 0
作用域检查git diff --check、过时测试数字扫描、生成缓存清理、维护记录链接与独立对抗性复核均通过

本阶段没有调用真实模型、Provider、OAuth 服务、远端 MCP server 或外部业务 API，也没有使用任何 --apply 型批量写回命令。SQLite CLI 等价性测试只在系统临时目录生成隔离数据库；它们未进入仓库。

后续队列

  1. 为 persistent-tool-runtime-v1 → v2 设计显式迁移、回滚和双读测试；当前实现只做安全拒绝。
  2. 将 Tool/MCP Provider adapter 接到锁定 SDK/API 版本的脱敏 capture/replay 与隔离账号测试，覆盖真实流式中断、OAuth discovery、token audience 和错误 union。
  3. 用成熟 Draft 2020-12 validator 替换 MCP 教学 schema 子集，并为未实现的 prompts/logging/completion/tasks 方法逐个增加完整结果合同。
  4. 为 MCP Streamable HTTP 增加持久 event store、ack/retention、session 迁移、跨实例恢复与断线活性；继续保留明确的 delivery guarantee。
  5. 把 RAG event dedupe、canonical store、ACL snapshot、projection cutover 与 citation manifest 移到可事务化的持久实现，补并发、缓存、副本和灾难恢复测试。
  6. 对跨信任边界的 Tool audit、MCP artifact 与 RAG manifest 加签或使用等价 attestation；无密钥 hash 不能升级为真实性声明。
  7. 继续接入真实 sparse/dense/reranker/LLM 组件、人工标注与统计置信区间；当前确定性项目不衡量模型语义质量。
  8. 在 Obsidian 阅读视图抽查本阶段 Mermaid、长表、callout 与移动端布局；Quartz 通过不能替代桌面端渲染。
  9. 继续逐章审阅尚未进入本阶段的框架实践、评测、安全与生产化课程，不做机械批量回填。

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

Backlinks