AI Agent Engineer

AI Agent Engineer

2026-07-19 第七阶段外部来源工件与路线可移植性记录

12 min read

2026-07-19 第七阶段外部来源工件与路线可移植性记录

本阶段落实第六阶段队列中的 provenance external artifact v2，同时处理课程路线依赖语义和项目命令的机器可移植性。主 Agent 统一 wire contract、信任边界、术语、课程位置与最终验证；专项 Agent 分别执行 v1/v2 合同审计、课程依赖审计、绝对路径审计、provider 合同缺口审计与只读红队。红队发现的高风险问题均由主线复现、修复并增加回归，最终复核未留下 P0/P1。

本阶段结论边界

external-provenance-bundle-v2 证明的是：在带外批准的 canonical JSON value、版本化算法和 consumer-owned live state 下，受保护 artifact 能跨 JSON boundary 保持可重建关系并 fail closed。它不是来源真实性、签名、AuthN、SLSA/in-toto conformance、分布式发布一致性或物理删除证明；第 9 课 reference engine 也尚未自动导入第 10 课 artifact。

1. 从 producer 摘要到可独立验证的外部 artifact

新增External Provenance Artifact v2，并扩展第 10 课 CrossLayerEngine.export_external_provenance_bundle()。完整 protected bundle 携带：

  • parser、normalizer、mapping、knowledge-state、chunk、index、ID 与坐标版本合同；
  • source event、inline raw/canonical、ACL snapshot、完整 parser record、KB revision、adapter elements 与 crosswalk；
  • 完整 chunk、index entry、显式 tenant/document/source/revision route；
  • generation、capture/tombstone/auth/pipeline、document/entry closure；
  • payload 自哈希，以及 attestation.mode: none、trust_scope: self-consistency-only 的诚实声明。

consumer 只接受 bounded strict UTF-8 JSON text/bytes，不接受 producer 的内存对象。TrustedImportPolicy 独立固定 canonical bundle-value digest、generation、pipeline 与 authorization revision；pretty/compact JSON 若解析成同一值，会得到同一 digest，因此这不是 exact wire-byte pin。完整 wire-byte 身份、签名者身份和跨组织信任仍需 transport digest、签名 envelope、可信控制面或透明日志。

可重建语义

consumer 使用当前受信任的 Parser 与 Chunking 实现 fresh rebuild，并逐项验证：

  • raw/canonical/parser record、parser config 与完整元素顺序；
  • knowledge-store/source-build-state/v1 下的 source/build state、KB revision identity 与 producer document snapshot；
  • crosswalk、adapter element、chunk、entry、ACL/access snapshot、route、coverage 与 generation closure；
  • native line locator、element lexical span、exact/prefix/suffix；
  • canonical_mapping.status: unavailable 与 document-revision-bridge，不因成功传输而升级证据能力。

缺少完整原 producer release manifest 时，其 hash 改为带 opaque-producer-reference-only 标签的诊断引用；consumer 不把无法重建的摘要冒充已验证 closure。capture_artifact_sha256 等 producer identity 输入仍依赖带外 policy 与 generation pin，不等于 consumer 亲自重建了 producer 数据库。

2. 红队闭环：从结构合法到边界可用

独立红队先复现，再由主线逐项关闭下列问题：

问题修复与回归
1200 层 JSON 逸出裸 RecursionErrordecoder 前扫描 container depth，并将防御性递归错误统一为结构化 failure
StagedExternalBundle/PublishedExternalBundle 可手工构造公开构造器拒绝，import/publish 使用私有 provenance marker；伪造 object 无法发布
query body 可自报 tenant/oncall grouptenant/groups/auth 从 host-owned ConsumerLiveState 的 principal grant 签发；query body 只接受 query_id/query/top_k
context 可跨 live-state snapshot 复用TrustedRequestContext 绑定签发它的精确 live-state marker
相同公共结果的两个主体争用同一 trace每次 host 签发 128-bit 随机 request nonce；trace 绑定 nonce、bundle、generation 与 public trace，audit 分别归属
public 与 protected audit 同时返回public query 只返回公共 schema；audit 写入 host-owned sink，写入失败则整次查询 fail closed
public citation 原样输出敏感 source_uri公共投影只保留类型化 logical source/KB identity；URI/version 只进入 protected audit sink
Schema URI 上限 300、实现上限 1000独立 sourceUri 合同统一为 1000；普通和长 URI 的真实 exporter bundle 均通过 Draft 2020-12 validator
D:/... 可逃逸临时 parser rootportable path grammar 拒绝 drive/stream、反斜杠、traversal、设备名、危险结尾与超长 segment；resolve 后做 descendant check，exclusive create
materialization 抛裸 OSError路径物化与 parser rebuild 分别转成稳定结构化错误
只比较 element/crosswalk 集合，可重排语义parser → crosswalk → adapter element 顺序逐项绑定；即使重建下游 chunk/entry/hash 也拒绝
KB source/build 与 producer snapshot 被当作 opaque hash绑定单一版本化 knowledge-state 算法并完整复算 producer document snapshot

专项文件包括：

  • docs/RAG/examples/provenance/external_provenance_v2.py；
  • docs/RAG/examples/provenance/external-provenance-bundle-v2.schema.json；
  • docs/RAG/examples/provenance/test_external_provenance_v2.py；
  • 第 9/10/11 课及 Parser、Knowledge Store、Chunking 目录的能力边界和交叉链接。

42 项专项测试覆盖 strict JSON、trusted policy、identity/route/path/order/coordinate/coverage、live authorization、trace、发布状态机、protected audit delivery 与非泄露。最终只读红队确认没有剩余 P0/P1。

3. 学习路线：展示顺序不再冒充依赖拓扑

课程审计发现两个学习体验问题：总路线曾写一个并不存在的“安全与评测基础”课程，且课程侧栏的 legacy order 容易被理解为严格前置顺序。现已：

  • 在早期安全与评测 milestone中链接现有威胁建模、提示注入、工具越权、身份最小权限、评测目标、用例分层与确定性断言章节，并给出最小完成证据；
  • 将 Tool Calling 明确为 Agent 核心的普遍硬前置；
  • 将 MCP 定位为按需互操作分支，而非所有 Agent runtime 的硬前置；
  • 将框架实践定位为按状态、恢复、协作和控制需求选用的分支；
  • 将 Course Navigator 的 LEARNING ROADMAP 改为 COURSE CATALOG，明确 legacy order 只是展示顺序；
  • 为上述导航语义增加网站回归测试。

这次只迁移了已经逐页核验的第一批关系。缺少 v2 prerequisite metadata 表示“尚未迁移”，不表示“已确认无依赖”。

4. 项目命令与发布路径可移植性

路径专项审计在 22 个主线项目页发现 23 处当前机器绝对项目根。逐页改为从同时包含 docs/ 与 .website/ 的项目根目录运行，并使用项目相对路径；没有机械替换冻结第三方正文。覆盖 Agent Skills/Core、Benchmark、CrewAI、JSON、LangChain、LLM API、MLOps、OCR、上下文/提示词、图像/视频/语音、工作流、数据合成、正则、评测与监控项目。

smoke 进一步发现并修复 3 个原本不可运行的 unittest 命令：

  • LLM API 集成：20 tests；
  • 上下文工程：15 tests；
  • 提示词工程：15 tests。

.website/scripts/prepare-content.mjs 新增发布前门禁：完整发布的课程 Markdown 若仍含指向 AI Agent Engineer 项目目录的 Windows 绝对路径，构建会在脱敏前失败；维护记录可保留历史证据。网站测试同时覆盖失败样例与合法项目相对路径。

5. Provider 合同只读审计

本阶段没有扩张到真实 provider 集成，但完成了下一阶段缺口审计。当前 LLM API 示例仍以可靠 client 骨架为主，尚未形成 OpenAI Responses、Anthropic Messages 与 Gemini Interactions 的完整 wire/SDK 合同，也没有覆盖 provider-specific continuation、streaming tool-argument event state machine、strict tool schema 与 structured final output 的组合边界。

2026-07-19 核验的官方 Python SDK release snapshot 为：

这些版本只用于记录审计时点，不应写成长期安装建议；进入实现时要重新锁版并以官方 API/SDK 文档和实际事件流为准。

6. 实际验证

  • External v2 专项：42/42，在 normal、-O、warnings-as-errors、-O + warnings-as-errors 四模式全部通过。
  • RAG provenance 目录：109/109，四模式全部通过；其中第 9 课 67 项、external v2 42 项。
  • RAG integration 目录：36/36，四模式全部通过。
  • Python 全库：发现 67 个 test_*.py；62 个基础环境可运行文件在四模式分别为 2387/2387，四轮全部通过。
  • 可选依赖边界：5 个文件未纳入基础回归，因为当前环境未安装课程明确声明的 CrewAI、LangGraph、Matplotlib 或 scikit-learn；没有把未执行写成通过。
  • 路径项目 smoke：20 个唯一工作目录共 902 项单元测试，加 LangChain 5 项自检，全部通过；其中三处错误命令已由全库四模式再次覆盖。
  • JSON/Schema：RAG examples 下 6 个 JSON/schema 文件通过 strict UTF-8、重复键与非有限数检查；标准 URI 与长 URI 的真实 exporter bundle 均为 Draft 2020-12 0 errors。
  • 路径与差异：当前机器绝对项目根精确命中 0；git diff --check 通过；验证产生的 4 个 .pyc 和 2 个 __pycache__ 已清理，生成目录没有进入 Git status。
  • 站点测试：.website npm test 为 35/35。
  • 站点构建：发布 891 个 Markdown 页面、220 个资源与 2665 个 public files；broken local links、forbidden files、progress metadata leaks、sensitive leaks、self redirects、table wikilink leaks、checkbox leaks 与 KaTeX errors 全部为 0。

7. 核心来源

8. 后续队列

  1. Provider contract project：新增三家 provider 合同测试，覆盖真实 request/response、streaming tool arguments、continuation、并行调用、错误 taxonomy、strict tools 与 structured final output；避免仅比较 SDK 对象表面形状。
  2. Schema CI 与跨语言向量：让 exporter artifact 自动经过 JSON Schema，并为 canonicalization、duplicate key、Unicode、path 与 ID preimage 建立跨实现测试向量。
  3. 正式 attestation：定义 predicate type，接入 DSSE 或等价签名 envelope、PKI/KMS、key rotation、透明日志和可信 policy 分发。
  4. 可信运行控制面：接入真实 AuthN/IdP/PDP、live-state freshness、durable protected audit、immutable store、事务/CAS cutover、并发 reader 与灾难恢复。
  5. RAG 第 9 课迁移：定义 v1/v2 old-ID crosswalk 和 downgrade reader；只有证明 canonical slice 才能迁为 canonical-span-verified。
  6. 外部索引删除证明：覆盖 sparse/dense/vector/graph/cache 的撤权、删除传播、备份擦除与 purge audit。
  7. 环境卫生：统一课程项目虚拟环境放置策略，避免在内容目录生成 .venv；为 5 个可选依赖项目配置独立 CI/环境矩阵。
  8. 人工渲染验收：在 Obsidian 与 Quartz 中抽查 RAG11 Mermaid、宽表、callout、课程导航和移动端布局。

前序记录见第六阶段跨模块、传输与持久化证据链记录；内容来源与许可继续遵循内容质量与来源标记规范。

Backlinks