AI Agent Engineer

AI Agent Engineer

2026-07-19 第二阶段内容深审记录

14 min read

2026-07-19 第二阶段内容深审记录

本阶段以“先修事实错误、失效实践、路线倒置和发布风险，再扩展课程”为原则。主 Agent 统一标准、交叉依赖与最终修改，多个只读子 Agent 分别审计学习路线、核心领域、示例与链接、历史代码风险和第三方发布边界；子 Agent 不直接合并内容。

结论边界

本轮完成的是一组可验证的高优先级修复，不表示 875 篇源文档都已逐页深审。未带 content_origin / content_status 的历史页面仍是“未分类”，不能推断为原创或已验证。后续队列见本文末尾。

本轮主要优化

1. 统一学习路线与依赖关系

  • 修正 JSON 与 API 的先后关系，消除互相作为前置的循环表述；JSON 使用顺序 4，API 使用顺序 5。
  • Agent 平台路线改为“模型、提示、上下文、API 与安全/评测基础 → Tool Calling → Agent 核心”；MCP 改为需要标准化外部能力或上下文协议时再学习的能力支线，不再写成所有 Agent 的硬前置。
  • 实时多模态路线补上 Tool Calling 与 Agent 核心；RAG 路线补上模型/提示/上下文/API、安全评测与 ACL 边界；LLMOps 明确需要先掌握评测基础。
  • ai_learning_order 被明确为稳定的展示顺序，不再伪装成能同时表达所有角色路径、选修支线和硬依赖的 DAG。
  • 修复 Linux 目录中的错误课程链接，并把 Chunking、Embedding、向量数据库目录中被代码反引号包裹的真实 wikilink 恢复为可导航链接。

2. 深审 Tool Calling 的可靠性边界

  • 按 2026-07-19 的第一方资料更新 OpenAI function calling 的 strict 默认差异、Schema 子集与当前并行调用限制；同时保留 Anthropic、Google 的供应商差异提示，不把一家 API 语义外推为通用标准。
  • 把工具结果明确视为不可信输入；Schema 校验只证明结构，不证明所有权、授权、业务正确性或副作用安全。
  • 重写超时分类：只有已经证明 handler/下游提交尚未开始时才返回可重试的 TIMEOUT_BEFORE_EXECUTE；提交可能已经发生时返回 OUTCOME_UNKNOWN，先查询 receipt/operation 或人工复核，禁止盲目重试。
  • 幂等命名空间纳入 tenant、subject、tool 与 key；调用关联纳入 tenant、subject、operation 与 call ID，避免跨租户碰撞。模型 proposal 只承载 name/arguments，provider call ID 与应用 operation/idempotency context 由可信 adapter 分开绑定。
  • 写操作审批同时绑定请求意图、schema version 与显式 policy revision；版本变化会使旧审批失效。缓存与 receipt 的数据在存储/返回时做防御性深拷贝，调用方不能通过修改响应污染下一次命中。
  • 扩展离线 dispatcher、fixture 与测试：当前共有 57 项单元测试、18 个数据驱动 case、23 个步骤，覆盖参数、授权、审批过期/错配/版本变化、跨租户与同租户跨主体隔离、幂等冲突、调用 ID 冲突、显式错误重试分类、限流、执行前超时、提交后响应丢失、receipt 对账与 receipt 不可得的 uncertain 分支。

示例边界

dispatcher 使用进程内映射模拟幂等记录、下游 receipt 与 uncertain intent，只验证顺序重试下的契约与失败语义。生产实现仍需持久化、原子 in_progress/唯一约束、真实下游幂等键、状态查询、并发竞争测试、事务/补偿与可观测性；本轮没有把内存模拟写成生产存储方案。

3. 更新框架实践的版本与隐私事实

  • CrewAI 的可安装包快照更新为 crewai==1.15.4（2026-07-17 发布，声明 Python >=3.10,<3.14），并把“当前 PyPI 包版本”和“2026-07-14 逐页深读的概念文档”分开记录。
  • CrewAI 入口与生产安全课补充默认匿名遥测、share_crew=True 的更详细共享边界、OTEL_SDK_DISABLED=true 及其可能影响同进程其他 OpenTelemetry instrumentation 的部署注意事项。
  • LangChain 的 LCEL 示例不再把“依赖缺失后跳过”当成框架已验证。使用 Python 3.11.9 与隔离的 langchain-core==1.4.9 实际运行无密钥示例，并在课程中记录精确命令、输出和隔离环境要求。
  • 仍未声称 CrewAI 或 LangGraph 的真实框架 API 端到端已运行；它们进入下一阶段的 Layer B 实践队列。

4. 建立内容来源与发布门禁

  • 新增 内容质量与来源标记规范，统一 content_origin、content_status、来源日期、执行证据和第三方许可边界。
  • 将审计中发现的 21 个旧状态值迁移到受控枚举；构建已确认当前不存在规范外 content_status。
  • 优先标记 11 个高风险或动态顶层入口，包括 Python、Agentic Design Patterns、MCP、Agent Skills、LangChain、CrewAI、LLM API、Tool Calling、现代 LLM、实时多模态和环境型 Agent；其余 45 个顶层课程入口仍待逐页判断，不做未经审阅的批量归类。
  • 公开构建现在使用固定的 yaml@2.9.0 AST 解析器校验 frontmatter 及已填写的来源/状态字段；字段缺失仍允许渐进迁移，解析错误、空值、重复字段、未知枚举、merge key 与 alias/复杂映射键都会失败。治理字段若藏在 flow mapping、缩进/序列映射、tag/anchor、转义或折叠显式键中也会失败关闭，不能用合法但非规范的 YAML 形式绕过门禁；无关字段的 alias value 不在该门禁范围内。
  • content_origin: third-party 的页面必须给出绝对 HTTP(S) source_url，并同时匹配已登记的上游 origin/path、该项目允许的许可证与构建时复制的许可声明；任意来源加 license: MIT 不能放行。许可白名单仍限于当前策略中的 MIT、Apache-2.0 与 CC0-1.0，但它只是必要条件。来源未登记、来源/许可错配、许可证缺失、为空、unknown、专有、拼写错误或未进入白名单时生成来源 stub。若同一顶层课程仍有按资源白名单会公开的图片、附件、示例代码或数据，构建直接失败，防止“正文被拦截但资源继续泄漏”。mixed 入口不被错误当作整页第三方内容。

5. 给冻结 Python 参考层补安全警告

没有改写许可不明的第三方正文或代码，而是在维护入口集中标明四类已确认风险：

  • Python 3.11.9 下把裸 coroutine 交给 asyncio.wait() 会失败；
  • 历史异步下载示例关闭 TLS 校验，且缺少超时、状态、大小与解析边界；
  • 公开课爬虫会访问真实第三方站点、冒用 User-Agent，且缺少限速与站点政策核对；
  • 2020 年 requirements.txt 只是历史环境快照，不应在现代环境直接安装。

主线练习改用本地 fixture/测试服务器、诚实身份、隔离环境和最小依赖。公开站仍只为许可不明的完整参考层生成来源跳转页。

实际验证

检查结果证据边界
.website 单元测试28/28 通过包含来源枚举、YAML AST 与非规范键失败关闭、许可/source URL 门禁、通用第三方 stub 正文隔离、附件失败关闭、既有发布策略与路线生成
.website 完整构建通过875 篇源 Markdown；718 篇正文、157 个 stub、198 个资源；生成 878 个页面
站点校验全部为 0断裂本地链接、禁止文件、进度泄漏、敏感信息、自重定向、表格 wikilink 泄漏、交互式复选框与 KaTeX 错误
导航校验通过8 个阶段、56 个课程入口、106 个导航文件夹
Tool Calling 单元测试57/57 通过普通模式与 python -O 各运行一次
Tool Calling 数据驱动 CLI18 case / 23 step 全通过使用仓库内 fixture，无网络、无密钥
LangChain LCEL 最小运行通过Python 3.11.9、隔离的 langchain-core==1.4.9；不是 LangGraph 或真实模型端到端验证
全现代示例审计基线变更前 1,917 项通过这是本轮早期基线：56 个现代示例测试文件分别在普通与 -O 模式运行；随后新增的 Tool Calling 测试已单独复验，但尚未重新生成全库聚合总数；另有 2 组可选科学计算套件因未安装声明依赖而未执行

整站构建不等于 Obsidian 桌面端渲染验证。本轮没有自动点击检查 Callout、Dataview 和所有 Mermaid 的视觉布局；站点构建已覆盖链接、HTML 和 KaTeX 等可自动验证边界。

核心来源

以下动态资料均在 2026-07-19 复核；课程正文只摘取必要事实并保留直接链接：

下一阶段队列

按风险和学习收益继续处理：

  1. 框架真实 Layer B：为 LangGraph 增加实际 StateGraph、checkpointer、interrupt/resume；为 CrewAI 增加 Flow、持久状态和恢复的最小真实运行，并把框架测试与现有无依赖骨架分开报告。
  2. 路线元数据模型：将展示顺序与硬依赖、角色路径、选修关系拆开，设计 domain、roles、hard_prerequisites、track_order 等可校验字段，再让 Obsidian/Quartz 共用同一来源。
  3. 示例统一执行器与 CI：解决全库 unittest discover 为 0、pytest 模块名碰撞和可选依赖跳过不可见的问题；输出 passed/skipped/failed 与实际依赖环境，不把 skip 当成框架已验证。
  4. 来源字段继续迁移：逐页审阅剩余 45 个顶层入口及第三方子层；Python、Agentic、MCP、Agent Skills、LangChain、D2L 等参考层应分别保留 source、commit/retrieved、license 与冻结状态，不能机械继承入口字段。
  5. 历史示例现代化策略：继续隔离高风险网络、TLS、爬虫和旧依赖示例；优先增加现代替代练习，不直接重写冻结第三方正文。
  6. RAG、评测、安全与生产化纵向复核：用统一的贯穿项目核对检索权限、数据新鲜度、离线/在线评测、成本延迟、安全事件和回滚证据，减少跨课程重复与术语漂移。
  7. Obsidian 视觉抽查：在桌面端检查本轮路线表、Callout、Mermaid、长表格和跨目录链接的实际渲染。

上一阶段记录见 2026-07-18-内容审计与重构记录；其中“框架真实 Layer B”和“路线元数据模型”的首批落实见 2026-07-19-第三阶段框架恢复与路线元数据记录。后续页面审阅与来源标记继续遵循 内容质量与来源标记规范。

Backlinks