AI Agent Engineer

AI Agent Engineer

2026-07-19 第五阶段来源、MCP 与工具结果证据链记录

13 min read

2026-07-19 第五阶段来源、MCP 与工具结果证据链记录

本阶段落实第四阶段队列中的三项 Layer B 工作：来源到引用的 provenance、MCP Resources/订阅安全、Tool Result 双投影与未知结果对账。主 Agent 统一来源基线、身份语义、公共/受保护边界、跨课程术语和最终回归；专项 Agent 分别审阅 MCP、Tool Result 与文档一致性。所有并行修改按目录隔离，最终由主 Agent 复查反例并补修残余缺口。

结论边界

本阶段完成的是标准库离线 reference implementation、稳定规范子集和高优先级课程深审，不表示整个 vault 已逐页验证，也不证明真实 OAuth、SDK、网络传输、向量数据库、LLM、分布式 exactly-once、签名制品或物理删除已经实现。摘要字段证明同一受信任流水线内的一致性，不是跨服务认证或第三方 attestation。

1. 从来源到引用：补齐可复算 Layer B

  • 新增 从来源到引用的离线证据链，用 UTF-8 Markdown fixture 串起 source event、canonical revision、parse revision、element、chunk、index entry、published generation、ACL-before-score、extractive claim 与 citation。
  • canonical_revision_id、parse_revision_id、element_id、chunk_id、index_entry_id 与 index_generation_id 都基于受限 canonical JSON 域和完整 SHA-256；原文与检索文本分别保存 content_sha256、retrieval_sha256。
  • 公共 citation 保留 source URI/version、raw/canonical/parse/element/chunk/index 身份和精确半开字符 span；全局 generation、selected entry IDs、聚合过滤摘要和授权版本只进入受保护审计，避免私有语料变化影响公共响应。教学 trace_id 哈希完整 runtime query，只用于篡改复算；生产公共 request ID 必须随机且不可推导授权上下文。
  • 验证器不信任 audit 自报的 selected set，而是从可信 query、当前 ACL、索引代际和词法规则重算候选、排序、top-k、filter summary、claim、span 与 trace。
  • generation 绑定 source snapshot、tombstone、authorization revision、pipeline fingerprint 与完整 entry set；新代际发布后旧代际进入 superseded，ACL 收紧、撤权、删除和 stale snapshot 均失败关闭。
  • Fixture 同时绑定原始 JSON SHA-256 与严格加载后的类型化模型 SHA-256；加载后篡改内存对象必须重新验证。评测 artifact 另绑定 fixture、pipeline、snapshot、tombstone、auth、index manifest 与 harness revision。

上游局部合同加固

  • 文档解析项目：parse revision 绑定 raw hash、parser 名称/版本和 config hash；element 身份再绑定 parse revision、类型、坐标空间、行 span 与正文哈希。
  • 知识库构建项目：对账直接重算 canonical/search 实际正文哈希，不再只相信数据库内两个摘要字段互相相等。
  • Chunking 项目：index_entry_id 绑定 chunk、实际 retrieval hash、index revision 与 ACL snapshot；标题路径或表头上下文变化会使旧索引记录失效。
  • RAG09 明确标为独立 reference model，而不是上述四个脚本的 wire integration。解析项目使用行坐标，Chunking 使用 lexical-unit span，知识库使用 SQLite 整数 revision，RAG09 使用 canonical character span；生产接线仍需 versioned adapter 和迁移测试。

2. MCP：Resources、订阅与授权快照

  • 教学 profile 固定在当日官方 latest 2025-11-25；2026-07-28 只作为 /specification/draft 下的 release candidate 记录，不混入稳定合同。
  • 离线 fixture 扩展为 54 个场景：Resources list/templates/read/subscribe/unsubscribe、list changed、updated、失败订阅/取消、child resource、分页、URI、RFC 6570 template、canonical Base64 和聚合大小门禁。
  • 单页最多 256 项，read 最多 64 个 content items 且聚合内容不超过 64 KiB；请求/响应 exact fields、cursor、URI、MIME、text/blob 互斥和重复内容均严格校验。
  • 成功 subscribe 后才创建活动订阅；失败 subscribe 不授权 updated，失败 unsubscribe 保留原订阅，重复 pending 操作被拒绝。授权修订变化会清空旧订阅并阻断 stale reread/update。
  • 课程额外注入的 transport_context 明确不是 MCP wire 字段；它把 active token、audience、RFC 8707 resource indicator、tenant、scope、authorization revision 与 revocation policy 绑定到资源操作。Roots 继续只作客户端协调提示，不能替代 token、ACL 或沙箱。

3. Tool Result v2：模型投影、审计投影与未知结果

  • Fixture 升级为 tool-cases-v2：18 个 case、23 个 dispatch/query_status step，覆盖读写授权、审批、幂等、call 冲突、rate limit、执行前超时、提交后响应丢失、receipt 对账与持续未知。
  • 每个工具都有 exact output schema。业务数据一律标为 untrusted_data，错误状态、恢复动作和 OUTCOME_UNKNOWN 只能来自 dispatcher 的固定错误目录，handler 不能注入顶层 status、recovery、sensitive/control 字段。
  • model_result 是唯一允许送回模型/provider 的投影；主体引用、provider context、完整工具合同、downstream request/receipt/status ref、redactions 与摘要只进入 protected_audit。
  • request_sha256 绑定主体、工具、参数和 input/output/effect revision；result_sha256 绑定完整模型投影；call_binding_sha256 再绑定 provider/API family、response/call/operation、adapter、完整工具合同、幂等键与前两个摘要。三者都要求完整 64 位小写十六进制并重新计算。
  • 主 Agent 的追加反例证明旧实现只替换 idempotency_key 仍可复用 package；修复后幂等键进入 call-level binding，但仍从业务 request digest 排除，使“同一意图可用新 call 重试”与“结果必须绑定当前执行键”同时成立。
  • 跨 call package、model result 交换、伪 request/result/call digest、来源标签伪造、结果集合缺失/重复/未知，以及 provider payload 泄漏受保护审计都会被拒绝。
  • 显式 query_operation_status 会重新检查当前主体和资源授权；没有可信 receipt 时继续保持 OUTCOME_UNKNOWN，不能猜测成功或自动重放非幂等写操作。
  • OpenAI Responses、Anthropic Messages 与 Gemini Interactions adapter 只序列化已验证的 model projection；它们是 schema-only 教学 adapter，不是实际 SDK 或流式 continuation 集成测试。

4. 跨课程一致性修复

  • 文档解析、知识库构建、Chunking 与 RAG 的项目命令统一以当前项目根目录为 cwd，避免公开仓库用户误用 vault 外层路径。
  • 修正 22→29 学习路线中的遗漏：Chunking 后明确经过 Embedding、向量数据库、语义搜索和 Reranking 再进入 RAG。
  • 深审入口和项目页补齐 content_origin、content_status 与 execution_verified；动态官方资料页保持 dynamic，不因本地测试通过而误标为静态已验证事实。
  • RAG 公共/内部概念统一称“公共响应”和“受保护审计”；第 8 课的固定 enum privileged_audit 与第 9 课的 protected_audit 明确属于两个不同 schema。
  • 引用、生成与拒答明确区分第 8 课的 fixture fact/revision schema 与第 9 课的完整 source/span citation，避免同页示例和实践命令看似矛盾。
  • AI 安全入口补充不可信 tool result、逐工具 exact output schema、双投影、显式状态查询、完整摘要绑定，以及与 MCP/RAG 课程的交叉链接。

实际验证

检查结果证据边界
7 个相关离线项目三模式回归1,239/1,239 通过普通、python -O、warnings-as-errors 各 413 项：文档解析 26、知识库 31、Chunking 32、RAG 第 8 课 68、RAG provenance 62、MCP 94、Tool Result 100
组合优化/警告回归194/194 通过MCP 94 与 Tool Result 100 另在 -O -W error 组合模式通过
CLI 与故障注入通过provenance 正常 PASS/检索故障 BLOCK；MCP 54 场景为 16 正向通过、38 负向按预期拒绝；Tool Result 18 case/23 step 均 passed=true
专项攻击复核通过parser/config 复用、正文与摘要同时篡改、标题/表头旧索引、stale generation、citation/audit 篡改、MCP URI/token/subscription 绕过、Tool Result 交换/伪摘要/状态注入/幂等键替换均按预期失败关闭
.website 单元测试与完整构建通过发布策略、来源门禁、路线元数据、资源与链接由统一站点门禁复核
补充检查通过git diff --check、范围内 wikilink 解析、JSON 解析及项目下 __pycache__ / .pyc 扫描；未触碰三项已知外层本机/子模块状态

核心来源

本记录的 source_checked 表示本阶段来源与改动在 2026-07-19 汇总复核。动态 SDK、候选规范和产品消息形状仍需在实施当天锁定版本并重跑 contract tests。

后续队列

  1. 真实跨模块 adapter：把文档解析、canonical store、Chunking、真实索引与 RAG citation 接到同一 versioned artifact schema；为 line/char/page/bbox/DOM/JSON Pointer 等坐标空间分别写迁移与 round-trip 测试。
  2. 真实 MCP transport 与 OAuth：使用官方 SDK 测试 Streamable HTTP/SSE、token 签名、issuer/audience/resource/expiry、401/403、introspection、重连与分布式订阅恢复。
  3. 真实 provider contract tests：锁定 OpenAI/Anthropic/Gemini SDK/API 版本，覆盖流式 tool call、并行结果顺序、continuation token/interaction、thinking item 延续和 provider 错误。
  4. 持久化幂等与对账：把单进程 mock 升级为原子数据库事务、唯一约束、outbox、receipt/status 查询和并发/崩溃恢复测试；不宣称 exactly-once。
  5. 签名与跨信任证明：为 artifact manifest 引入受控签名/MAC、密钥轮换、不可变存储、审批主体与验证策略，而不是只比较自报 SHA-256。
  6. 真实检索与对抗评测：加入 Embedding、向量数据库、reranker、LLM、间接提示注入、数据投毒、越权和撤权后的缓存/索引失效实验。
  7. 权限与删除深水区：实现层级继承、显式 deny、ABAC/provenance、保留期、备份擦除和可审计 purge 证据。
  8. 视觉抽查：在 Obsidian 与公开站点人工检查新增 Mermaid、Callout、宽表和跨课程导航；自动构建通过不等于桌面端视觉已验证。

前序记录见 2026-07-19-第四阶段RAG评测安全生产证据链记录；内容来源和许可继续遵循 内容质量与来源标记规范。

Backlinks