外观
LangGraph 状态、分支与持久化
1. 解决什么问题
生成、评审、修订和人工等待不能靠一个长函数可靠管理。LangGraph 把流程拆成可观察节点，通过状态传递信息，并把执行进度写入持久化 Checkpoint，便于暂停和恢复。
2. 原理与术语
State 是节点共享的数据契约；节点接收状态并返回局部更新；边控制下一步；条件边读取结果决定分支。Checkpoint 保存线程的图状态，不等同于业务教材版本。thread_id 是恢复同一执行历史的关键标识。
3. 输入输出与执行
本项目节点包括 prepare、generate、review、revise、human、produce。评审存在可修复错误且未到上限时进入 revise，否则转 human。人工通过后进入 produce，再结束图；图结束只说明素材已排队，不代表媒体制作和交付完成。
4. 混淆点
interrupt 不是让 Python 进程一直阻塞等待用户。它把暂停状态交给 Checkpointer，之后用 Command(resume=...) 重新进入。恢复时节点可能从开头执行，因此 interrupt 前的副作用必须可重复，不能在那里无保护地扣费或发送通知。
5. 最小示例
在项目环境检查真实图的节点，不执行模型：
python
from app.graph import build_graph
compiled = build_graph(None)
nodes = set(compiled.get_graph().nodes)
assert {"prepare", "review", "human", "produce"} <= nodes
print(sorted(nodes))6. 实际实现
run_workflow 使用 PostgresSaver，thread_id 由任务 ID 和 epoch 组成，调用采用 durability='sync'。编辑内容会增加 epoch，避免把旧图状态继续用于新教材。普通失败恢复尽量继续原 epoch；终止后恢复会开新 epoch。
7. 源码与状态
阅读 system/app/graph.py::State/build_graph/run_workflow，重点字段是 version、revision、lesson、review、retrieval_problem、human_round。cache_node 用 epoch 与节点键缓存输出；db.save_version 用 node_key 防止同一节点重复保存版本。缓存与 Checkpoint 分别解决业务重入和流程恢复。
8. 取舍与边界
同步 Checkpoint 降低进程退出前状态未落库的窗口，代价是写入延迟。它不能和远程模型 API 组成事务：模型已经返回而缓存尚未保存时，恢复仍可能再次调用模型。当前不保证外部推理或付费素材恰好执行一次。
9. 实验与验收
创建任务并等到 human，在操作台记下版本；然后重启 worker：
bash
docker compose restart worker重启后任务应仍等待同一版本人工决定。用真实任务 ID 和页面显示的版本替换变量，再提交：
bash
curl -s -H "X-API-Key: ${LAB_API_KEY:-}" -H 'Content-Type: application/json' \
-d "{\"action\":\"approve\",\"expected_version\":$VERSION}" \
"http://127.0.0.1:8000/api/jobs/$JOB_ID/decision"验收检查原内容没有重复生成、决策作用于正确版本、素材任务随后出现。强制中断执行中的恢复还需要结合租约实验，不应由普通 restart 结果推断全部故障路径。
10. 故障排查
总从头开始先检查 thread_id 和数据库卷；暂停后无法恢复检查决策版本；重复版本检查 node_key。递归上限只是最后防线，业务循环仍需要 max_revisions。修改图结构后恢复旧 Checkpoint 必须评估兼容性。
11. 面试题与追问
问：为什么既有 Checkpoint 又有版本表？ 前者保存执行位置，后者保存可审核和交付的内容。追问：重跑节点会怎样？ 读取缓存、检查业务幂等键；外部结果不明另行处理。再追问：END 代表什么？ 此处只代表编排结束，后台媒体状态独立推进。
STAR 应用：假设实验场景，R 为应核对的证据
| 对应 | S：情境 | T：目标 | A：行动 | R：验收证据 |
|---|---|---|---|---|
| 主问 | 进程在人工等待时退出 | 恢复执行位置与内容 | 使用稳定thread_id及PostgresSaver | 重启仍等待同一版本，不重复生成 |
| 追问一 | 节点业务写入后崩溃 | 减少重复业务结果 | 检查node_key与缓存再执行 | 同节点不应再新增一个教材版本 |
| 追问二 | 图已到END但视频未完成 | 区分编排与交付 | 查询后台任务和当前版本完整性 | 媒体未齐时不能下载交付包 |
这些是设计讨论的参考表达，实际执行前不能改写为已取得的历史成果。
12. 官方资料与版本
Persistence、Interrupts。项目 LangGraph 1.0.10、langgraph-checkpoint-postgres 3.2.0；核验日期 2026-11-03。数据库镜像为 PostgreSQL 16 系列，精确实测版本以验收报告为准。