AI Agent Engineer

AI Agent Engineer

2026-07-19 第八阶段三家 Provider 合同与流式状态机记录

9 min read

2026-07-19 第八阶段三家 Provider 合同与流式状态机记录

本阶段把第七阶段提出的 Provider 合同缺口落实为一个完全离线、可审计的课程项目。主 Agent 统一三家 API 的版本边界、术语、续接语义、文档计数与最终验证；专项 Agent 分别执行文档一致性、代码红队和官方事实核验。红队发现的高风险问题均先复现，再由主线修复并加入回归；当前没有已知 P0/P1。

证据边界

docs/LLM API集成/examples/provider_contracts/ 不读取密钥、不导入三家 SDK、不访问网络。它证明的是固定日期的官方 API Reference/SDK 类型基线下，本地 projection parser、身份关联、终态门禁、资源上限和 continuation builder 的合同。OpenAI/Gemini fixture 是 typed-sse-projection，Anthropic 是 wire-sse-envelope-projection；不是原始 SSE 字节、SDK 实例、live conformance、服务端 exactly-once 或模型质量评测。

1. 当前基线与版本边界

  • OpenAI Responses + openai-python 2.46.0（2026-07-17）；普通 HTTP previous_response_id 续接与 WebSocket 当前连接缓存分开记录。
  • Anthropic Messages + anthropic-python 0.117.0（2026-07-16）；顶层 system 仍是广泛兼容默认，mid-conversation system 只在已核验模型与位置约束下放行；eager/fine-grained tool input 的非法 JSON 进入 recovery。
  • Gemini Interactions 稳定 v1 + google-genai 2.12.1（2026-07-16）；稳定 v1 的 Step 判别器按官方 Reference 固定为 15 类。当前 v1beta OpenAPI 中出现的 MCP server step 不计入稳定合同，在本地 parser 中 fail closed。
  • Gemini status_update 是可选中间通知，terminal Interaction 状态权威；last_event_id 只用于仍可检索的已存储 Interaction GET stream 恢复。
  • 三份 fixture 各自绑定 provider、API family/version、contract revision、SDK baseline、核验日期和 HTTPS source URL；示例 ID 与模型值为合成 opaque 值。

2. 实现与教学结构

新增项目页 项目：三家 Provider 合同测试、三个版本化 fixture、provider_contracts.py 与 test_provider_contracts.py。项目保留供应商差异，不做事件名称替换表：

  • OpenAI：按 sequence_number + output_index + item_id 关联；完整 Item lifecycle、non-function terminal binding、direct caller 保留与 HTTP storage proof；stateless 路径重放 caller-validated input Items + 完整 raw output Items。
  • Anthropic：保留 named SSE envelope、thinking/redacted thinking、签名、citation 与 server/client tool 混合；calls 只暴露可执行 client calls，非法输入或截断兄弟调用进入独立 recovery_calls，续接强制 is_error。
  • Gemini：按 event_id 去重、按 step index 做流内关联；区分可选 status_update 与 terminal；current usage 字段原样保存；create 与 GET 完整 steps 的输入历史来源分开；opaque model/hosted steps 无法证明时 fail closed。

三家 turn 都保存本地 canonical snapshot digest。构造器在复制 history/call/block 前重新核对 digest，能发现解析后嵌套对象变异；这不是签名或跨进程真实性证明。五种 builder 都要求显式重发 caller controls，并检查本轮观察到的 function name 出现在对应 Provider tool 声明中。

3. 红队闭环

发现修复与回归
OpenAI reasoning/message 等非函数 Item 可在 terminal 中被替换按 output index 保存 output_item.done，terminal 做完整 Item 一致性校验，并加入篡改 fixture
三家 frozen dataclass 的嵌套 dict 可在解析后改写，导致 call/result 错配增加 provider-specific snapshot digest，builder 入口 fail closed；三家各有变异回归
Anthropic 截断轮中已完整的兄弟 tool call 可能被 naive caller 先执行将所有 max_tokens 调用放入 recovery_calls；只有明确 stop_reason=tool_use 且输入可解析的调用进入 calls
深层工具 JSON 在 json.loads 前泄漏裸 RecursionError增加字符串扫描式 nesting guard，并把 parser/load_fixture 的递归异常转成稳定合同错误
畸形 HTTPS source URL 泄漏 urlsplit 的 ValueErrorURL 校验捕获并返回结构化 validation error
Gemini v1 把 v1beta MCP step 算入稳定 union稳定 v1 只保留 15 类； MCP 前瞻类型加入未知 step 负向测试
续接可提交不含真实 call name 的同形状 tools三家 builder 检查 observed function name 与声明集合
Gemini prior history 接受非首位 user_input、孤儿或重复 function_result要求初始 user_input、function call/result 配对、名称一致与完整结果
结果 iterable 可被无限供给而持续增长_bind_results 在超过预期数量时立即失败

4. 文档与路线同步

  • LLM API 目录由 20 项可靠客户端 + 82 项旧 Provider 描述更新为 20 + 96；总计 116 项离线测试，并明确 projection、SDK integration、live eval、生产审计的证据边界。
  • 08 课补充 Mermaid 三状态机、OpenAI HTTP/WebSocket 存储差异、Anthropic system 能力门禁与 recovery calls、Gemini v1/v1beta 分界、15 类 Step、retention、GET/create history、usage 与原生 tool/response_format 形状。
  • Anthropic API 入门页收窄了关于 system role 的绝对化表述，增加工具终态门禁、schema/语义/权限校验、稳定 is_error 错误结果、fine-grained 输入风险和单轮循环上限。
  • 04/06/07 的日期、Gemini Interactions 参考、usage 缺失语义与 projection 边界已同步；总路线新增本阶段维护记录链接。

5. 实际验证

  • Provider 合同：96 项在 normal、-O、warnings-as-errors、-O + warnings-as-errors 四模式全部通过。
  • Python 全库：在 Python 3.11.9 下发现 68 个 test_*.py；按课程目录声明的可选依赖跳过 5 个文件后，63 个基础环境文件共 2483 项，在 normal、-W error、-O、-O -W error 四模式分别 2483/2483 通过（合计 9,932 次测试执行）。5 个未纳入基础回归的文件只依赖课程已声明的 CrewAI、LangGraph、Matplotlib 或 scikit-learn，未把缺依赖伪装成通过。
  • 相关脚本：Provider 两个文件完成 py_compile 与 normal/-O warnings-as-errors 回归；不访问网络、不读取 API key。
  • 站点：.website npm test 为 35/35 通过；npm run build 发现 893 个 staged Markdown、输出 2,432 个 HTML 页面和 2,676 个 public 文件。brokenLocalLinks、forbiddenFiles、progressMetadataLeaks、sensitiveLeaks、selfRedirects、tableWikilinkLeaks、checkboxProgressRuntimeLeaks、interactiveCheckboxes 与 katexErrors 均为 0；构建还报告 56 个课程索引、225 个资源、8 个阶段导航、56 个课程导航和 106 个文件夹导航。
  • 工作区：git diff --check 通过；生成的 __pycache__/.pyc 不属于交付内容，已在最终检查中清理。

6. 核心来源

7. 后续队列

  1. 在 vault 外建立有凭据门控、低费用、无副作用的 live contract suite，分别验证真实 SSE framing、SDK typed-object 解码、HTTP/WebSocket、timeout、429、恢复游标和默认重试。
  2. 脱敏捕获真实 wire/SDK fixtures，记录 API version、SDK、模型、日期与 schema hash，再与本地 projections 做 golden diff。
  3. 将 provider turn、request/execution ledger、审批、业务幂等键与 SQLite 幂等与 Outbox 恢复 连接；离线 parser 不证明 exactly-once。
  4. 为 OpenAI built-in/programmatic、Anthropic server tools、Gemini hosted/opaque steps、GenerateContent 与多模态 tool result 建立各自能力/证据层，不把它们塞回稳定 v1 的函数投影。
  5. 在 Obsidian 与 Quartz 中人工抽查 Mermaid、宽表、callout、移动端布局；随后继续审阅其他知识库的易变 SDK/协议页面。

前序记录见 第七阶段外部来源工件与路线可移植性记录；来源、许可与原创/整理/第三方标记继续遵循 内容质量与来源标记规范。

Backlinks