AI Agent Engineer

AI Agent Engineer

2026-07-19 第六阶段跨模块、传输与持久化证据链记录

15 min read

2026-07-19 第六阶段跨模块、传输与持久化证据链记录

本阶段落实第五阶段队列中的三项 Layer B 工作：真实 Parser/Knowledge Store/Chunking adapter、真实 loopback MCP Streamable HTTP、SQLite 持久化工具幂等与对账。主 Agent 先审计跨库原生合同，统一 ID scheme、坐标与发布术语，再复核专项 Agent 的目录隔离改动；专项 Agent 分别负责 MCP HTTP/OAuth boundary、Tool Calling persistence 与独立红队。所有实现继续采用离线、可重复 fixture，不以 mock 冒充真实 OAuth、provider、分布式数据库或 exactly-once。

本阶段结论边界

“真实”只描述本次真正跨过的边界：RAG adapter 确实导入三个现有 Python 模块，MCP 确实发生 127.0.0.1 HTTP 往返，Tool persistence 确实使用多连接 SQLite 文件。它不表示第 9 课 provenance 已导入外部 chunk，不表示 token 经过真实 AS/JWKS/introspection，也不表示 SQLite 与下游形成跨服务原子事务。

1. 跨模块 adapter：从局部绿灯到显式 wire bridge

先审计，拒绝字段直连

主线只读运行 Parser、Knowledge Store、Chunking 与第 9 课 provenance 的 26 + 31 + 32 + 62 = 151/151 项测试，并逐项核对真实 preimage、坐标与发布状态：

层当前原生合同adapter 必须补齐的字段/状态
Parserraw-byte hash、parse revision、1-based inclusive normalized line、content-addressed elm_tenant、逻辑 document、sequence、ACL、control event、完整 protected raw/canonical sidecar
Knowledge StoreSQLite integer revision、source/build hash、outbox、published pointer、ACL 与 tombstoneraw/parser lineage、可跨数据库复算的 revision fingerprint、corpus-wide release
Chunkingelement lexical-unit 半开 span、content/retrieval 双表示、chk_/idx_输出 artifact/schema、原生 ID scheme、generation、line crosswalk
provenance v1独立 LF+NFC char span、独立 parse/chunk/index/generationexternal parsed/chunk importer；当前不能声称与 Chunking 的同前缀 ID 等价

这次审计发现一个可执行反例：byte-identical 文档在不同 tenant 下会得到相同 parser native element ID。它适合作为内容地址，却不能充当逻辑资源或授权身份。新 fixture 保留这个冲突，adapter 另派生绑定 tenant、document、KB revision 与 native ID 的 xsrc_/xel_，并为每个 ID 保存显式 scheme。

新增真实 adapter 项目

  • 新增跨模块来源适配与原子发布。
  • cross_layer_adapter.py fresh 调用当前 inspect_documents.py、knowledge_store.py 与 chunking_lab.py；第 9 课 provenance 只提供受限 canonical JSON 实现，仍标记为独立重解析分支。
  • Fixture control binding 显式携带 tenant/document/sequence、URI/version、connector/upstream event/run、media/root section 与 ACL；这些字段不从正文或 parser manifest 猜测。
  • adapter v1 仅接受无 BOM strict UTF-8 Markdown，保留调用方给出的 absolute materialization root；在 resolve 前逐级拒绝已存在的 root/source/parent symlink，并拒绝 traversal 与未登记 kind。root-link-to-outside 测试确认零写入；Python 3.11 门禁不覆盖 NTFS junction/reparse point、hard link，也不宣称抵御并发路径替换的 TOCTOU。
  • heading 在 crosswalk 中保留为 context_only；body element 投影为 projected_as_body。缺 parser section path 时只能使用可信 root_section_path。
  • pipeline fingerprint 绑定 adapter、Parser、KB、Chunking、provenance 模块 bytes 与全部 contract revision；每次 evidence validation 从 protected raw snapshot fresh reparse、fresh rechunk并复算 native ID。
  • KB gate 重新计算 content/source/build hash、outbox event identity、revision/search body、ACL 与 pointer，不只比较数据库自报摘要。
  • release manifest 同时绑定 control/crosswalk、raw/parser、SQLite numeric locator、KB content fingerprint、capture/outbox/tombstone、chunk/index entry set、authorization 与 pipeline；旧 release 显式 supersede。
  • project_and_publish 先对 current revisions fresh preflight，再排空原生 KB outbox；content-only build 失败不会提前切换 KB pointer，旧 release 仍可服务，而 ACL/delete 已由 live deny state 立即阻断。
  • publish_capture 在任何 parser sidecar 参与新 pointer 前再次从 immutable raw fresh reparse；伪造但内部自洽的 parser record 会被拒绝，旧 pointer/generation 状态保持不变。
  • 34 项红队测试覆盖 strict fixture、路径/symlink、跨 tenant native ID collision、发布生命周期、授权非干扰、逐层篡改、故障门禁、artifact 与 CLI。artifact 自哈希只证明内部一致，不能代替可信 pipeline 重跑、MAC 或签名。

坐标与能力标签保持诚实

Parser 行坐标、Chunking element lexical span 与 provenance canonical char span不能无损互换。公共 citation 因此保留 native line locator、[unit_start, unit_end)、exact/prefix/suffix 和各层 ID；canonical char mapping 固定为：

{
  "mapping_status": "unavailable",
  "reason_code": "parser_projection_is_not_one_exact_canonical_span"
}

release 固定声明：

{
  "evidence_level": "document-revision-bridge",
  "external_chunk_to_citation_verified": false
}

exact/prefix/suffix 借鉴 W3C Text Quote Selector，但项目没有输出 W3C JSON-LD，也不声明 conformance。受限 canonical JSON 也没有冒充完整 RFC 8785 JCS。

查询与生命周期

  • tenant、KB live state 与 ACL 在相关性评分前执行；public response 不包含全局 generation 或过滤计数。
  • same-ACL 内容更新未完成时继续服务旧 release；KB pointer 已切换但 adapter 未切换时，不返回混合 revision。
  • ACL 变化和 delete 通过 access_blocked/deleted 立即阻断；resurrection 必须用更高 sequence 并等待新 release。
  • stale capture、parser/KB/chunk/citation/manifest 篡改与未知 retrieval outcome 均 fail closed。
  • retrieval_unavailable 单独返回 dependency_unavailable，离线 release gate 必须 BLOCK，不能伪装成无答案。

2. MCP：从消息状态机进入真实 loopback transport

  • 新增Loopback Streamable HTTP 与 OAuth 资源边界及 examples/streamable_http/。
  • 使用标准库在 127.0.0.1 随机端口真实运行 POST/GET/DELETE、JSON response、POST SSE、GET SSE 和 Last-Event-ID 恢复。
  • 严格检查 Origin、Accept/Content-Type、header/body/response/并发预算、MCP-Protocol-Version、session owner/TTL/capacity/DELETE 与 event replay scope。
  • 实现 401/403、WWW-Authenticate、Protected Resource Metadata 文档/challenge 形状与 RFC 8707 authorization/token request 两次 resource binding；由于资源 URI 是 HTTP loopback，它不宣称 RFC 9728 合规。
  • Offline token policy 每次请求复核 issuer、audience/resource、scope、tenant、authorization revision、expiry 与 revocation；错误不回显 bearer 或 session。
  • 已解析 claim/principal 使用 Unicode-safe 精确比较，而非仅支持 ASCII str 的 compare_digest；非 ASCII subject/tenant 可完成 session/resource 往返，错误 Unicode issuer/resource/revision 稳定返回 401，非法 UTF-8 surrogate fixture 在注册时拒绝。
  • MCP resource URI 使用固定 ASCII authority kb://tenant/，tenant 只作为 UTF-8 percent-encoded path segment；Unicode 及 / ? # 不会破坏 RFC 3986 URI 语法。
  • stable 固定为 2025-11-25；initialize body 提议 Draft 时按 stable 生命周期返回 server 支持的替代版本，由 client 决定是否断开；后续 header 仍只接受已协商 stable。2026-07-28 release candidate 仅作为迁移观察，不进入当前 wire contract。

这是真实 HTTP，但 token 是进程内预置 claims lookup。课程明确排除 authorization server、authorization code + PKCE、JWKS/验签、introspection、TLS、代理、HTTP/2、跨节点 session 与官方 SDK conformance。

3. Tool Calling：从内存幂等进入 SQLite operation ledger

  • 新增SQLite 持久化幂等与 Outbox 恢复及 examples/persistence/。
  • 直接复用 Tool Result v2 的 request digest、call binding、approval、逐工具 output schema 与双投影，不另造一套结果合同。
  • BEGIN IMMEDIATE + UNIQUE(tenant, subject, tool, key) 原子预占执行 scope；同 key 同意图 replay，同 key 异意图 conflict。
  • operation intent 与 outbox 同本地事务；local receipt、ledger succeeded 与 outbox delivered 也同事务，并用 trigger failure 注入验证回滚。
  • worker 使用可过期 lease；effect 前重新检查当前 tool contract revision 与当前资源授权。合同漂移或撤权时不执行下游。
  • 模拟“下游已提交、本地未落 receipt”时保持 OUTCOME_UNKNOWN；重复 dispatch 不自动重放，只有显式 status query 重授权、重算 request/contract/receipt/output 后才 receipt_reconciled。
  • approval ID/digest/expiry/accepted-at 持久化并复算；课程明确区分“有效期内原子接受 immutable intent”与“下游 commit 时仍未过期”两种业务语义。
  • database audit 对孤立 downstream receipt 只输出不可逆 status_* 引用，不回显 tenant、subject、tool 或 idempotency key。
  • now 与 now + lease_seconds 在任何 reservation 前受 portable UTC 上限约束；时间格式改用 UTC epoch + timedelta，避免 Windows fromtimestamp 越界后留下半提交 intent。
  • now 明确只是可重复测试的 deterministic control input；生产仍需受控 wall-clock/数据库时间、clock-skew 监控与 fencing，不能把跨进程 lease 时间视为可信边界。
  • audit 在单一 SQLite connection 的显式 read transaction 中统一读取 integrity/FK、operation/outbox/receipt 语义与 counts，避免合法 reconcile 夹在多次 SELECT 之间造成假 BLOCK；FULL synchronous 也进入 PASS gate。
  • CLI 的 rc2 只输出稳定、无路径的 error.code；fixture/DB 打开失败测试确认不会回显原始 OSError、fixture 路径或数据库路径。

SQLite 采用 STRICT、WAL、FULL synchronous、foreign keys 和 parameterized SQL。WAL 的 reader/writer 并行仍只有一个 writer，而且依赖同主机 wal-index；downstream_receipts 只是同一 SQLite 文件中的独立事务 stand-in。课程只声明 local durable ledger 与 at-least-once-compatible building blocks；当前没有持续枚举 backlog 的 poller，因此不声明交付活性，更不声明跨服务 exactly-once。

4. 跨课程一致性与学习体验

  • RAG09 继续保留“独立 reference model”警告，并链接 RAG10 的真实 adapter；Parser、Knowledge Store 与 Chunking 目录同步指向两阶段学习顺序。
  • RAG10 和三个上游目录统一使用 scheme + value、native locator、loss profile、control plane、release pointer 与 protected audit 术语。
  • MCP 目录把第 6 课无网络消息验证与第 8 课真实 HTTP 黑盒测试分层，避免把 transport_context 误认为 wire 字段。
  • Tool Calling 06/07/08 形成“内存顺序语义 → Tool Result v2 结果证据 → SQLite 持久恢复”路线；所有章节继续区分业务 digest 与 idempotency key/call binding。
  • 项目命令全部限定当前仓库 cwd；临时 SQLite 示例使用 GUID 文件名，避免重复运行误读旧 ledger。
  • 新增课程、fixture、代码、Mermaid 与测试均标为项目原创；第三方规范仅作事实与边界核验。

实际验证

  • 专项项目：RAG adapter 34/34、MCP loopback 78/78、Tool SQLite 77/77；均进入下述四模式统一回归并通过，独立终审另以 normal 与 -O -W error 复核。
  • Python 统一回归：发现 66 个 test_*.py；其中 61 个在 normal、-O、-W error、-O -W error 四种模式分别运行 2338/2338，四轮均通过。
  • 可选依赖边界：5 个测试文件未纳入基础 Python 回归，原因是当前环境未安装课程显式声明的 CrewAI、LangGraph、Matplotlib 或 scikit-learn 可选依赖；没有用“跳过”伪装成已执行。
  • CLI 合同：MCP demo 为 rc0/PASS、attack 为 rc0/BLOCK（四个预期攻击全部被拒）；Tool dispatch 为 rc0/PASS/fresh，after_downstream_commit 为 rc1/BLOCK/OUTCOME_UNKNOWN，显式 status 为 rc0/PASS/receipt_reconciled，audit 为 rc0/PASS，缺失 fixture 为 rc2/FIXTURE_IO_ERROR 且无路径回显。
  • 结构与安全：3 个新增 JSON/schema 通过 strict UTF-8、重复键与非有限数检查；本阶段 160 个 scoped wikilink 为 0 missing；未发现真实凭据或绝对用户路径；git diff --check 通过，仓库内无新增 __pycache__、.pyc、SQLite/WAL/SHM 测试产物。
  • 站点：.website npm test 为 33/33；npm run build 发布 889 个 Markdown 页面与 217 个资源，生成 2655 个 public files，broken local links、forbidden files、progress metadata leaks、sensitive leaks、self redirects、table wikilink leaks、checkbox leaks、KaTeX errors 均为 0。

核心来源

以下来源在 2026-07-19 由主线或专项 Agent 复核；动态规范与 SDK 仍需在实施当天重新锁版。

后续队列

  1. provenance external artifact v2：定义 protected document/chunk artifact 的持久 schema 与 locator union，让第 9 课 engine 真正导入第 10 课 parser/chunk，不再独立重解析。
  2. 真实 OAuth/SDK interoperability：用官方 MCP SDK 与真实 AS 测试 PKCE、PRM/discovery、resource、JWKS/introspection、step-up、代理、TLS 与撤权延迟。
  3. 真实 provider contract tests：锁定 OpenAI/Anthropic/Gemini SDK，覆盖流式/并行 tool call、continuation 与 provider 错误。
  4. 分布式工具恢复：把 SQLite stand-in 替换为独立 ledger、队列和真实下游，加入 fencing/heartbeat/DLQ、process kill、网络分区与 receipt/status contract tests。
  5. 并发 release/cutover：把 Python 内存 published pointer 升级为 immutable artifact store + transactional outbox + CAS，并测试 reader/build/delete/ACL 竞态。
  6. 真实检索与 LLM evidence：加入 Embedding、向量库、reranker、LLM claim splitting/entailment、间接提示注入与投毒实验。
  7. 签名与删除证明：为跨信任 manifest 引入 MAC/签名、密钥轮换、透明日志、保留期、备份擦除与 purge audit。
  8. 视觉与迁移验收：人工检查 Obsidian/Quartz 的 Mermaid、宽表、callout 与导航，并为 scheme/schema major version 写迁移 round-trip。

前序记录见第五阶段来源、MCP 与工具结果证据链记录；内容来源与许可继续遵循内容质量与来源标记规范。

Backlinks