AI Agent Engineer

AI Agent Engineer

2026-07-20 第九阶段动态资料、发布门禁与运行时审计记录

12 min read

2026-07-20 第九阶段动态资料、发布门禁与运行时审计记录

本阶段继续处理第八阶段留下的动态 SDK/协议页面、可选依赖示例、第三方参考层发布边界和 Mermaid 运行时风险。主 Agent 负责范围、术语、来源、冲突复核与最终门禁；三个专项 Agent 分别在 vault 外安装并验证 LangGraph、CrewAI、Matplotlib 与 scikit-learn 环境，另有专项审阅检查 Mermaid 本地化与可访问性。所有专项 Agent 都未修改项目文件，改动由主线统一落地。

证据边界

本阶段能证明固定版本、固定日期和当前测试/构建路径下的行为，不证明所有动态 API 长期不变，也不把离线 fixture、无密钥 runtime 或浏览器渲染冒充 live provider、生产并发、抓包级零连接、完整许可证清单或 Obsidian 桌面端验收。第三方参考页缺少逐页来源/许可元数据时继续 fail closed；没有为了提高公开页数量而批量推定许可。

1. 动态资料与事实边界

  • Google Gemini 入门页把 2026 年 6 月已 GA 的 Interactions API 调整为新项目主线，generateContent / Chats 明确标为仍受支持的 legacy 兼容层。两套 API 的状态、steps、流式事件、续接和工具结果不再混写；Gemini 3.5 示例改用 thinking_level，不再给 3.x 复制显式 temperature、top_p 或 top_k。
  • LangChain 参考层把 Python from 语句中非法的连字符模块名 langchain-voyageai 修为可导入模块 langchain_voyageai；安装分发名仍是 langchain-voyageai。同时删除虚构模型名，并把“所有 Provider 高级能力等价”的绝对表述收窄为统一调用入口加能力门禁。
  • 旧 Bedrock Claude 3.5 标识更新为当前 AWS model card 可核对的 Sonnet 4.6 示例，同时明确模型 ID、区域可用性和 bedrock_converse 支持仍要在目标账户复核。
  • MCP 稳定基线继续固定为 2025-11-25 规范；没有把候选扩展或实现特有能力写成稳定协议事实。
  • API、SDK、模型目录和传递依赖版本均保留核验日期；版本快照用于复现和漂移检测，不写成永久安装建议。

2. 可选依赖示例与课程合同

专项 Agent 都使用 Python 3.11.9、vault 外临时 venv、-B/PYTHONDONTWRITEBYTECODE，完成后核验并删除临时目录：

项目固定直接依赖单轮测试四模式结果本轮收紧的边界
LangGraph 可恢复审批流langgraph==1.2.9、langgraph-checkpoint-sqlite==3.1.0832/32thread_id 统一规范化；跨进程 start/inspect/resume 共享 SQLite 后恢复
CrewAI 持久化 Flowcrewai==1.15.4936/36flow_id 规范化；同 operation ID 异 payload 冲突不得产生第二次效果
Agent 评测看板matplotlib==3.11.01248/48至少一条完成运行后 p50/p95 才有定义；试运行不覆盖课程工件
工单意图路由scikit-learn==1.9.0936/36random_state 限于非负 32 位范围；虚拟环境移到 vault 外

这里的四模式是 normal、-O、-W error 和 -O -W error。CrewAI 的两个已知传递依赖 warning 仍按完整消息窄范围放行，其他 warning 会失败。

CrewAI 安装不是轻量合同

新 Python 3.11 venv 自带 pip 24.0 时，jsonschema → rpds-py 解析为 ResolutionImpossible；只在该临时 venv 把 pip 升到 26.1.2 后安装成功，pip check 无断裂依赖。当前一个直接依赖解析出 138 个 distribution、约 800 MB 环境，并传递引入 ChromaDB、LanceDB、MCP、OpenAI SDK 与 OpenTelemetry。课程命令已补上升级 pip 的可复现前置条件，同时明确：

  • 单行 requirements 不是完整 lockfile；
  • 测试关闭 CrewAI telemetry、AMP tracing 和隔离进程的 OpenTelemetry，但没有做抓包；
  • 无 API/LLM/HTTP 日志只证明当前路径，不证明任意部署组合零外发；
  • 生产项目应裁剪能力、锁定完整依赖、生成 SBOM，并做许可证、漏洞和出口审计。

基础 Python 与诊断质量

  • Python基础/Day31-35/code/example01.py 把 Matplotlib/NumPy 导入移入绘图入口，算法模块和 2 项测试可以在标准库基础环境执行；运行绘图仍需显式安装课程依赖。
  • Embedding 与 Reranking 的 CLI 等价测试曾各出现一次无法稳定复现的内部子进程 returncode=1；相同脚本压力运行和完整模式重跑均通过。原测试的 check=True 只显示 CalledProcessError，现改为显式断言返回码并在失败消息中保留解码后的 stderr，后续再现时不再丢失关键诊断。
  • 这两次退出没有足够证据归因于代码、并发安装、杀毒软件或 Windows 进程噪声；维护记录保留不确定性，而不是把成功重跑改写成“从未失败”。

3. 第三方参考层发布门禁

.website/scripts/prepare-content.mjs 为已知上游参考树增加显式 fail-closed 前缀：深度学习完整复刻、LangChain 固定日期参考层、MCP 旧译文和 Agent Skills 旧参考层。页面若已有 source/source_url，却没有逐页 content_origin，公开层只生成来源跳转页；相邻 LangChain 旧附件也不会因 Markdown 变成 stub 而继续公开。

当前门禁把 186 个已知上游 Markdown 安全降为 third-party-metadata-missing stub，并额外阻止 12 个缺少对应发布证据的 LangChain 图片附件。这个数字是待逐页审阅队列，不是应该机械回填的字段数量。只有核对原始来源、版本、内容来源、再分发许可和本项目修改后，页面才能恢复全文发布。

4. Mermaid 安全、本地化与可访问性

  • Quartz 插件原本固定从 cdnjs 加载 Mermaid 11.4.0；运行时补丁现在从项目锁文件的 mermaid==11.16.0 复制入口与全部 ESM chunk，由当前站点同源加载，build 与 fresh dev 都走同一路径。
  • 恢复原图源码时由 innerHTML 改为 textContent，Mermaid securityLevel 固定为 strict；补丁同时验证源码与编译 bundle，旧/warm runtime 可重复执行而不会重新引入 CDN。
  • 构建验证逐文件比较已发布 Mermaid 入口和 103 个 chunk 与已安装包的 SHA-256，并拒绝 cdnjs loader；不是只检查文件名或单个入口。
  • Mermaid 放大按钮达到约 44×44 px，键盘 focus 可见，并在触摸/窄屏保持可见。构建预览和 fresh dev 都验证了图形渲染、暗色主题切换与全屏克隆，浏览器控制台无 error/warning。
  • .website/legal/Mermaid-MIT.txt 保存 Mermaid 顶层 MIT 许可，生成的第三方声明记录 11.16.0 与同源来源；这仍不是完整传递依赖 attribution inventory，后续需由 SBOM/许可证报告补齐。
  • 从 11.4.0 升级后，npm audit --omit=dev 为 0 个已知漏洞；审计结果是当前 registry advisory 快照，不是长期安全保证。

5. 实际验证

  • Provider 合同：96 项在 normal、-O、warnings-as-errors、-O + warnings-as-errors 四模式全部通过。
  • 基础 Python：64 个无需课程可选依赖的文件、每模式 2,485 项；四模式完整重跑。
  • 可选依赖：上表 4 个文件每模式共 38 项；均在各自隔离环境完整重跑。
  • Python 聚合：68 个测试文件，每模式 2,523 项，四模式合计 10,092 次测试方法执行。基础环境与四个隔离环境分别统计，没有把“未安装”写成通过。
  • Embedding + Reranking 诊断改动：每模式 59 项，四模式定向重跑通过；两个 CLI 各完成 30 次单进程压力，Embedding 的 normal/optimized 双子进程完成 100 轮压力。
  • 站点：npm test 为 38/38；npm audit --omit=dev 为 0 个已知漏洞。最后一次 npm run build 统计 891 个源 Markdown，其中 548 个全文、343 个 stub，连同 3 个生成页共 staged 894 个 Markdown；发布 213 个资源、2,386 个 HTML 页面和 2,723 个 public files。brokenLocalLinks、forbiddenFiles、progressMetadataLeaks、sensitiveLeaks、selfRedirects、tableWikilinkLeaks、checkboxProgressRuntimeLeaks、interactiveCheckboxes 与 katexErrors 全部为 0；导航统计为 8 个阶段、56 个课程和 73 个文件夹。

6. 核心来源

7. 后续队列

  1. 对 186 个 safe stub 逐页核对来源、版本、许可和修改边界；优先处理学习路线实际会引用的页面，不批量添加 content_origin。
  2. 单独核验 LangChain Academy/raw 资料、Agent Skills 参考层与其他外部完整材料的再分发许可；本地学习可见不等于公开站点可复制。
  3. 为生产依赖生成 SBOM 与完整许可证/NOTICE 报告；当前 Mermaid 顶层 MIT 文件和 npm lock 不能替代传递依赖 attribution。
  4. 为 LangGraph、CrewAI、Matplotlib 和 scikit-learn 项目建立独立 CI/锁文件矩阵；重点控制 CrewAI 的依赖体积、解析漂移、可选组件和 telemetry/exporter 边界。
  5. 建立有凭据门控、低费用、无副作用的三家 Provider live contract suite，验证真实 SDK 对象、SSE framing、重试、429、超时和恢复游标。
  6. 在 Obsidian 桌面端抽查 Mermaid、宽表、callout、wikilink 与移动端阅读体验；本阶段浏览器验证只覆盖 Quartz build/dev。
  7. 若内部 CLI 的无 stderr 退出再次出现，利用新增诊断保留命令、返回码、stderr、系统负载和并发环境，再决定是否属于代码、解释器或 Windows 运行噪声。
  8. 继续审阅尚未进入现代主线的动态 SDK/框架页面、课程元数据 v2 迁移和跨知识库重复内容；本阶段不是整个长期目标的完成声明。

前序记录见第八阶段三家 Provider 合同与流式状态机记录；来源、许可与原创/整理/第三方标记继续遵循内容质量与来源标记规范。

Backlinks