2026-07-21 第十七阶段框架运行时与生产反馈闭环深审记录
阶段结论
本阶段对 LangChain、CrewAI、评测体系、LLMOps 与 运行监控 做了以运行时合同和证据交接为中心的深审。没有把框架页面当成独立的 API 摘要，而是把它们接入“工具/状态合同 → 离线评测 → 受控发布 → 运行观察 → 人工确认的回归候选”的学习闭环。
本轮新增的两个核心学习节点是：
- 无密钥 create_agent 运行时合同：在锁定版本中真的运行
create_agent，同时明确 fake model shim 与真实 Provider smoke test 的证据边界； - 从离线证据到线上回归闭环：定义冻结评测、完整摘要、发布门、Canary、运行证据、人工分诊和新版本回归数据之间的单向交接。
顶层 All of AI 也补入了跨框架的 Mermaid 证据闭环图。它是项目生命周期视图，不是课程硬前置图，更不表示 LangChain 或 CrewAI 自动提供授权、正确性、事务性或生产可靠性。
结论边界
本阶段证明的是当前锁定依赖、离线 fixtures、显式负向路径和公开站点构建之间的自洽。它不证明真实模型会选择正确工具，不证明 Provider 端 schema、IAM/对象级授权、成本、网络故障、跨服务事务、持久遥测或容量治理已经通过生产验证。完整 SHA-256 只用于变更检测，绝不是签名、来源认证或批准授权。
多 Agent 协作与主 Agent 统一复核
主 Agent 先固定术语和验收边界，再并行分配三个不重叠范围：
- LangChain、
create_agent、LangGraph interrupt/checkpoint 与课程引用层； - CrewAI Flow、持久化、审查/恢复语义与隔离运行时；
- 评测、LLMOps、运行监控之间的 evidence handoff、MLflow 和 OpenTelemetry 事实核对。
专项 Agent 只能在各自目录修改；主 Agent 随后逐项检查依赖版本、失败关闭路径、断言是否在 -O 下仍有效、交叉链接和来源日期，并独立重跑关键测试。最后由主 Agent 把课程地图、维护记录和跨知识域术语合并。所有 Agent 均未 stage、commit、push、reset，亦未触及分配范围外的用户状态。
LangChain：把框架 API 放回可验证的三层合同
新增 Layer B：真实 create_agent，无 Provider 密钥
初学者路线现在清楚分为三层，而不是让一个离线 Python 样例冒充框架或生产验证：
| 层 | 教学实现 | 证明什么 | 明确不证明什么 |
|---|---|---|---|
| Layer A | 无框架离线工具循环 | allowlist、预算、call ID、错误分类 | LangChain 运行时和 Provider schema |
| Layer B | 真正的 create_agent + FakeMessagesListChatModel shim | 固定版本的 Agent graph、ToolNode、ToolMessage.tool_call_id、未知工具/参数错误 | bind_tools 端到端序列化、模型质量、授权与网络 |
| Layer C | LangGraph 可恢复审批流 | checkpoint/interrupt 后的状态、owner、动作、策略、指纹与 approval request 复核 | 分布式事务、外部副作用 exactly-once |
Layer B 固定 langchain==1.3.14、langchain-core==1.4.9 与 langgraph==1.2.9，并在构建 Agent 之前核验已安装版本。三个预写轨迹覆盖正常工具调用、unknown tool 和 Pydantic 参数错误；错误路径不会执行函数。这个设计拒绝把假模型的绿灯说成 Provider 兼容性：真实项目仍要用隔离账户、费用上限和脱敏 trace 做少量 bind_tools smoke test。
Layer C 进一步让恢复路径在真正 resume 之前重新比较 schema、graph、policy、owner、action、正文、action fingerprint 和 approval request ID。LangGraph 的 interrupt 会从节点开头重跑，因此节点前的外部副作用仍要设计成幂等或移到 interrupt 后；本课程不将 checkpoint 描述成事务日志。
引用层、升级边界与目录
LangChain 的完整第三方材料保留为冻结参考，而课程主线改为原创导航、现行概念边界与可运行项目。相关页面明确标记 content_origin: third-party / content_status: frozen-reference，避免学习者把历史完整复刻误当成当前 API 保证。目录、01-Learn 与初学者路线已加入 Layer B 的前后链接和版本升级清单。
精确放行六张已核验参考图
首次公开构建正确拒绝了这些页面的本地图片：LangChain/attachments/ 仍是冻结参考层的默认拒绝目录。没有改为放开整个附件树，也没有把带 MIT 来源的页面降级成空 stub；专项 Agent 将六张与当前课程直接相关的图逐字节比对上游 langchain-ai/docs，主 Agent 复算本地 SHA-256，随后只将这六个文件加入发布白名单，并在复制前强制复算摘要、为“其余附件仍拒绝”和篡改摘要补了单元测试。
共同上游提交为 f9dff44ce4a5a9cbf72f85eec08598e35a768328，其 LICENSE 仍为 MIT；下表的 blob 与完整摘要为本次来源记录。它们是再分发范围核验，不是对上游长期不变或图中产品行为仍然有效的保证。
| 本地允许文件 | 上游固定版本资源 | Git blob | 本地 SHA-256 |
|---|---|---|---|
LangChain/attachments/images/rag_indexing.png | raw | f12374f1b76f0db28a169b93c5a4c75ffa9d0f7d | d24e6b3c8631685e5efd85e0cf7714dce7a7f1e3186655b1e00cbeccb894431b |
LangChain/attachments/images/rag_retrieval_generation.png | raw | 1cd2956f78a51b7ea2b92e693780fc5912edd8e1 | 723d38f4c3e9fb1c84eb4fdaa32ff2375b04f2e154692ac117a06028afc610f3 |
LangChain/attachments/images/langgraph-hybrid-rag-tutorial.png | raw | 65402f1e047a8b2767e3162bb7e9b9f2497ab761 | e8a37e3d1df2e71e724506714acb32da3465a3b6b1c81f3e8ac2283c74b887f4 |
LangChain/attachments/oss/images/agentic-rag-output.png | raw | 2efa1353429a230ac2b512fcf1c4aa02c43400f1 | 23e192104524074fb91cb17d8fca7ef0f6777f6c5910deadd30b9ac98ba51c39 |
LangChain/attachments/oss/images/sql-agent-langgraph.png | raw | e03c90fc5482984ee37aec1cf20e47be792c0752 | 72cb96ea3b2db9054e076197b69b536e081aa6ef3a11965b900c558d4e5a4755 |
LangChain/attachments/images/data_analysis_slack_response.png | raw | 54ab937c66295bc9e8bce735c8dc41c2bdbe2933 | 36f3f251bcf8603adc9462b699047f269f5e2f3ff654c386d927668217654092 |
CrewAI：恢复状态不等于批准，Memory 也不等于 ACL
CrewAI 部分将当前 PyPI 观测版本 1.15.5 与课程隔离实测基线 1.15.4 分开记录。多 @start() 流程可能并行，单起点 fixture 不能证明调度器并发安全；@persist() 是兼容性表面而不是跨版本永久合同。未知 persistence ID 的 resume/fork 包装器现在在调用 kickoff 前失败关闭。
离线研究 Flow 的发布前检查重新读取当前 catalog、确认 source fingerprint 仍匹配，并重算确定性 reviewer 结论，因此已审查草稿或 catalog 在暂停期间被篡改不会被写出。课程还澄清：
- human feedback 在 Flow 中可用于路由或暂停，不能替代有 scope、主体、到期与审计的授权；
- Memory/Knowledge 的可检索性不能替代多租户对象级 ACL；
- trace 与 telemetry 必须遵守数据最小化、访问控制和保留策略，不能因为“可观测”而采集原始输入输出。
评测、发布与监控：证据交接而非自动污染回写
新闭环页把交接物拆为评测证据、发布门证据、运行证据和回归候选。评测项目新增完整 evidence_sha256 与 evaluator 版本；发布门同时保存显示用短指纹和必填的 candidate_gate_evidence_sha256；监控项目将 release manifest 与门禁摘要绑定到 release_evidence。短指纹只能供人读，完整摘要才是跨文件的变更检测引用。
为避免误导，三个课程的 fixture 保持独立，只共享字段语义和 **64 个十六进制字符（256 位摘要）**约束，并不假装组成一次真实发布。真实系统应从受控制品库或 API 传递同一份已经验证的摘要。监控失败仅生成不含原始内容的受限 trace 引用和 needs_human_triage 候选；经过许可、脱敏、去重和根因复核之后，才可形成新的 dataset/rubric/grader 版本，旧冻结集不能被线上日志原地改写。
同时修正了两个容易造成错误工程决策的表述：
- MLflow 的经典
mlflow.models.evaluate()/EvaluationMetric与 GenAImlflow.genai.evaluate()/Scorer体系不可互操作；自动评测面向新 Trace/会话的异步 LLM judge，不支持 code-based scorer，也不会自动补评历史 Trace。 - OpenTelemetry 的语义约定有版本和稳定性边界。当前核心 SemConv 为 1.43.0，GenAI 约定已经迁至独立仓库；采集端与消费端必须一起锁定、记录和兼容测试。release hash、完整 SHA、request/session/user ID、prompt 和模型输出都不能作为高基数 metric label。
监控指标还纠正了 burn rate 与 error_budget_remaining_ratio 的概念混淆：前者描述消耗速率，不能被写成剩余预算比例。
核心来源
动态事实均核对至 2026-07-21，优先采用官方文档：
- LangChain Agents、Tools、v1 migration、LangGraph interrupts 与 persistence；
- LangChain docs repository（固定图资源提交） 与 MIT license；
- CrewAI Flows 与 checkpointing；
- MLflow classic model evaluation 与 automatic evaluation；
- OpenTelemetry Semantic Conventions 与 versioning and stability；
- NIST AI RMF Core 与 NIST SP 800-61 Rev. 3。
验证证据
| 检查 | 结果 |
|---|---|
| LangChain Layer A | 63 项；normal 与 -O、均使用 -B -W error 通过 |
LangChain Layer B create_agent | 8 项；normal 与 -O、均使用 -B -W error 通过；三条 CLI 轨迹逐项比较 JSON 合同 |
| LangGraph Layer C | 10 项；normal 与 -O、均使用 -B -W error 通过 |
| LangChain Retrieval Layer B | 17 项；normal 与 -O、均使用 -B -W error 通过 |
| CrewAI Layer A | 39 项；normal、-O、-W error、-O -W error 均通过 |
| CrewAI Layer B | 9 项；normal、-O、-W error、-O -W error 均通过 |
| 离线分层评测 | 37 项；normal 与 -O、均使用 -B -W error 通过 |
| LLMOps 发布门 | 63 项；normal 与 -O、均使用 -B -W error 通过 |
| 运行监控审计 | 38 项；normal 与 -O、均使用 -B -W error 通过 |
| CLI 优化模式等价 | 评测、发布门和监控健康路径均比较 normal / -O 输出与退出码，一致通过 |
| 第三方元数据与图资源 | 所有标为 third-party 的页面均有绝对 source_url；六张精确 allowlist 图片的 SHA-256 复算和构建期摘要守卫通过，未列入附件仍拒绝 |
| 交叉链接与目录 | 独立只读审阅解析 534 个 wikilink、5 个 heading anchor；缺失和歧义均为 0，LangChain/CrewAI/评测/LLMOps/监控目录收录完整 |
| 站点单元测试 | 47/47 通过（含精确 LangChain 图资源 allowlist 与默认拒绝测试） |
| 完整公开构建 | 910 个源 Markdown；570 个全文、340 个 fail-closed stub、229 个资源；913 个 staged Markdown、2454 个 HTML 页面、2807 个 public files |
| 发布与导航门禁 | broken local links、禁止文件、进度/敏感信息泄漏、自重定向、表格 wikilink 泄漏、交互 checkbox、KaTeX 错误均为 0；57 课程入口、10 知识域、4 条角色路径、75 个导航文件夹 |
| 作用域卫生 | git diff --check 通过；本阶段相关目录未发现新 .pyc；未 stage 文件 |
所有框架依赖测试均通过 uv run --isolated --with-requirements 在隔离环境执行。CrewAI 首次解析依赖时会下载公开 PyPI 包，之后的固定 fixture 运行不访问模型 Provider、不读取密钥、不写业务数据库。未调用真实模型、真实 Provider、生产 telemetry 或外部业务 API。
后续队列
- 为 LangChain 的真实 Provider/
bind_tools加入少量隔离账号 smoke test，记录 schema、超时、费用、错误分类和脱敏 trace；不要把它并入无密钥单元测试。 - 在升级 CrewAI 到观测版本
1.15.5前，重新跑 Layer A/B，特别核验 Flow 调度、持久化与 listener 语义。 - 将评测摘要、release manifest、审批与监控证据接到真实受控制品库、身份系统和遥测后端，并补并发、保留、灾备和跨服务失败测试。
- 对尚未本轮逐页核验的评测、LLMOps、监控基础章节按来源逐页审阅；不以批量修改
source_checked冒充复核。 - 在 Obsidian 阅读视图抽查本轮 Mermaid、表格、callout 和移动端布局；Quartz 构建通过不能替代桌面端渲染检查。
本记录只覆盖第十七阶段，不表示整个长期 /goal 已完成。