2026-07-19 第三阶段框架恢复与路线元数据记录
本阶段把第二阶段队列中的两项高优先级工作变成可运行证据：为 LangGraph 与 CrewAI 分别增加真实 runtime 的 Layer B 恢复项目，并让第一批学习路线关系从手写说明进入严格校验的元数据。主 Agent 统一状态、幂等、恢复、来源和路线语义；专项 Agent 只读审计版本 API、课程衔接和验证边界，最终修改与冲突处理仍由主 Agent 完成。
结论边界
本阶段完成的是框架恢复实践和路线元数据的首批迁移，不表示全部 56 门课程、所有框架参考页或全部源文档都已逐页深审。真实模型调用、多 worker 并发、生产数据库、桌面端视觉检查及其余课程迁移仍在后续队列中。
1. LangGraph：从概念说明到真实可恢复审批流
- 新增 项目：LangGraph 可恢复审批流，原测试与升级清单后移为第 09 节，并同步目录与前后导航。
- 新增
examples/langgraph_layer_b/：直接运行langgraph==1.2.9、langgraph-checkpoint-sqlite==3.1.0，隔离环境解析到langgraph-checkpoint==4.1.1与langchain-core==1.4.9。 - 示例用真实
StateGraph、SqliteSaver、interrupt()、Command(resume=...)和durability="sync"，验证跨数据库连接和跨 Python 进程恢复。 - 应用包装层在 resume 前检查 thread 是否存在、受信任
owner_id绑定、目标节点与 pending interrupt，避免把 runtime 对未知或已完成 thread 的默认行为误当成授权拒绝；示例 owner 参数只模拟认证边界，不替代真实 AuthN/AuthZ。 - 审批同时绑定 request ID 与动作指纹；interrupt 前不做业务写入。最终动作只产生确定性 dry-run receipt，明确不声称外部副作用 exactly-once。
- 主线补充
sync、async、exit的写入时机边界，并统一 LCEL 已在隔离langchain-core==1.4.9环境真实运行的证据。
2. CrewAI：持久状态与业务回执分层
- 新增 项目：真实 CrewAI 持久化 Flow 和
examples/crewai_layer_b/，直接运行crewai==1.15.4，不调用模型、不需要 API key。 - 示例验证
Flow、结构化FlowState、@start()、@router()、@listen()、显式@persist(...)与SQLiteFlowPersistence；路由标签与 listener 方法名分开，避免锁定版本中的自监听问题。 - Flow state UUID 只标识执行 lineage；业务
operation_id与payload_hash负责幂等和冲突检测。Layer A 中原本容易混淆的确定性名称同步改为operation_id。 - 独立 SQLite receipt ledger 与 Flow persistence 分工：测试在“receipt 已提交、Flow state 尚未保存”处注入故障，新进程用同一 UUID 水合后复用 receipt，串行
effect_count保持 1。 - 同 UUID 恢复、从快照 fork、未知 UUID 失败关闭分别测试；正文明确
@persist水合不是节点级 checkpoint 跳过，也不等于分布式 exactly-once。 - 匿名 telemetry、AMP tracing、Flow 生命周期事件与本地日志分别说明；AMP tracing 由每个 Flow 的
tracing=False显式关闭，不把环境变量false误写成可靠 opt-out。Windows 测试在导入前启用 UTF-8，并只对锁定版本的两条完整传递依赖 warning 做窄范围 allowlist。
3. 学习路线元数据 v2：展示顺序与依赖关系解耦
- 新增 学习路线元数据v2规范，定义稳定课程 ID、知识域、全局目录顺序、角色无关硬前置，以及四条角色路线各自的顺序与
core/recommended/optional类型。 .website/scripts/prepare-content.mjs改用固定yaml@2.9.0AST 读取课程元数据。legacy 页面继续严格验证；页面一旦声明 schema 2，就不能缺字段或静默回退。- 验证器检查 ID/domain/JavaScript 安全正整数类型、catalog order 唯一、硬前置存在/重复/自环/全图环、track order/kind 配对、角色与类型枚举、每个角色顺序唯一，以及非规范 YAML tag/anchor。
- 顶层课程索引若因发布策略退化为不含路线信息的 stub，构建直接失败；manifest 分开报告 legacy 与 v2 数量。
- 第一批只迁移 Tool Calling、Agent 核心、评测体系和 LLMOps，且只落两条已审硬边：
tool-calling → agent-core、evaluation → llmops。没有把 MCP、环境型 Agent 或完整安全课程猜成普遍硬前置。 - 总路线补充框架的按需插入位置，并说明 legacy 展示顺序、角色推荐路径与真正硬依赖不是同一个概念。
实际验证
| 检查 | 结果 | 证据边界 |
|---|---|---|
| LangChain Layer A | 63/63 通过 | 普通、python -O、warnings-as-errors；框架无关离线循环与 LCEL 依赖分支 |
| LangGraph Layer B | 7/7 通过 | 普通、python -O、warnings-as-errors；真实 SQLite checkpoint、interrupt/resume 与两个独立进程 |
| CrewAI Layer A | 36/36 通过 | 普通、python -O、warnings-as-errors；标准库离线研究简报合同 |
| CrewAI Layer B | 7/7 通过 | 普通、python -O、warnings-as-errors；真实 Flow persistence、fork、故障注入与两个独立进程 |
.website 单元测试 | 33/33 通过 | 包含路线 v2 成功路径、缺失/类型/tag/track/前置/环/重复位置失败关闭、进度序列值完整剥离及既有发布策略 |
.website 完整构建 | 通过 | 879 篇源 Markdown；722 篇正文、157 个 stub、204 个资源；legacy 52、v2 4；生成 882 篇 staged Markdown |
| 站点与导航校验 | 全部通过 | 2,398 个 HTML 页面、56 个课程入口；断裂本地链接、禁止文件、学习进度泄漏、敏感信息、自重定向和 KaTeX 错误均为 0 |
| 补充检查 | 通过 | git diff --check 无格式错误；两个新 Layer B 目录没有 .pyc |
第一次完整构建曾被公开泄漏门禁拦截：元数据规范正文写出了学习者进度字段的字面量。该说明改为不暴露私有字段名的语义描述后，第二次构建通过。这个失败被保留在记录中，因为它证明门禁确实作用于新增维护文档，而不是只扫描旧课程。
核心来源
以下动态事实、版本与 API 在 2026-07-19 核对；课程只保留必要解释与直接链接：
- LangGraph Interrupts：interrupt 恢复和节点重放语义。
- LangGraph Persistence 与 Checkpointers：thread、checkpoint 与 durability 边界。
- PyPI：langgraph 1.2.9、langgraph-checkpoint 4.1.1 与 SQLite checkpointer 3.1.0：隔离运行的 runtime 与序列化依赖快照。
- CrewAI Flows 与 Checkpointing：Flow 装饰器、状态水合、同 UUID 与 fork 边界。
- CrewAI Telemetry、Tracing 与 1.15.4 tracing enablement 源码：匿名遥测、AMP tracing 与锁定版本覆盖优先级。
- PyPI：crewai 1.15.4：锁定运行版本和 Python 约束。
- YAML Document API 与项目锁定的
yaml@2.9.0：课程 frontmatter 的 AST 解析和失败关闭验证。
后续队列
- 路线 v2 逐页迁移：审阅剩余 52 门课程的稳定 ID、知识域、角色顺序与真实硬前置；迁移前不把字段缺失解释为“无依赖”。
- 消费者统一：在项目边界允许时，让 vault 级 Dataview view、Homepage 与 CourseNavigator 消费同一份已验证路线模型；当前因
docs/与.website/的编辑边界未修改外层 vault helper。 - 框架深水区：为 LangGraph 验证生产 checkpointer 的并发、迁移、加密与多租户隔离；为 CrewAI 单独验证 checkpoint API、多 worker 并发和 persistence schema 迁移。
- 真实模型集成：在有预算、凭据隔离和数据集后增加少量 provider smoke test；继续把模型质量证据与确定性 runtime 测试分开报告。
- 冻结参考层治理：逐页修复 LangChain 旧链接和来源/许可字段；不要把 2026-05-07 的译文参考层批量改写成当前 API 教程。
- 跨课程贯穿项目：继续把 RAG、评测、安全、LLMOps 与运行监控接入同一条有 ACL、trace、回归门、回滚和事故演练的证据链。
- 视觉与交互抽查：在 Obsidian 和公开站点中人工检查本阶段 Mermaid、长表格、Callout、Dataview 与课程导航的实际布局。
前序记录见 2026-07-19-第二阶段内容深审记录；来源分类继续遵循 内容质量与来源标记规范。