人工审批最容易出错的地方,不是「没人点同意」,而是同一个同意被用了两次:页面重试、双开标签页、用户点了返回再点一次,后端拿着一个已经消费过的答复继续往下跑,图早就换到下一个问题上了。LangGraph 1.2.20(2026-11-05)专门修这一类问题——同一个任务里的每次 interrupt() 有了自己的 id,并新增一个 strict resume 模式,不认识或已用过的答复会被直接拒绝,而不是静默忽略。
pip install langgraph==1.2.22。本篇不需要任何模型 API Key:节点全是确定性函数,全部行为可以在本机复现,这对排查审批问题反而更合适。四条边界先记住:① strict 模式只在根图生效,嵌套子图继承配置但不会独立再校验;② 走远程图时这个配置键会在序列化前被丢弃(_sanitize_config 的黑名单),所以远程部署要另行验证;③ 同一节点里连续调用两次 interrupt(),两次可能拿到同一个 id,别把 id 当成「这是第几个问题」的指纹;④ 严格模式拒绝的是「过期答复」,它不是授权系统,谁有权限点同意仍需你自己判。
先弄清:interrupt、checkpoint、resume 三件套怎么配合
把这三个概念摆清楚,后面的报错才不会看错对象。关键的一点常被忽略:节点恢复时是从函数第一行重新执行的,不是像协程那样从挂起的那一行继续。
| 环节 | 发生了什么 | 对代码的要求 |
|---|---|---|
执行到 interrupt(payload) | 图挂起,checkpoint 保存状态,payload 与 id 通过 get_state().interrupts 暴露给调用方 | payload 要能独立看懂,别依赖外部变量 |
| 人做决定 | 你的界面记录「针对哪个 id、做了什么决定、谁点的、什么时候」 | 这一步在 LangGraph 之外,必须自己存 |
| 恢复 | 用同一 thread 提交 Command(resume=...) | 节点从第一行重跑,interrupt() 的返回值变成你给的答复 |
| 副作用 | 重跑意味着 interrupt() 之前的代码会再执行一次 | 发消息、扣款这类动作必须幂等或挪到挂起之后 |
Step 1:装版本,建一张最小的审批图
先不要接模型。一个 review 节点加一个 apply 节点,就足够复现所有边界行为;等逻辑跑通,再把 review 换成「让模型生成摘要给人看」。
# approval_graph.py
from typing import TypedDict
from langgraph.graph import StateGraph, START, END
from langgraph.types import interrupt, Command
from langgraph.checkpoint.memory import MemorySaver
class S(TypedDict, total=False):
request: str
decision: str
applied: bool
def review(state: S):
# 第一次执行到这里就挂起,payload 交给调用方展示给人
verdict = interrupt({"ask": "是否批准这次发布?", "target": state["request"]})
return {"decision": verdict}
def apply(state: S):
# 真正的副作用放这里,避免在 review 里重复执行
return {"applied": True}
builder = StateGraph(S)
builder.add_node("review", review)
builder.add_node("apply", apply)
builder.add_edge(START, "review")
builder.add_edge("review", "apply")
builder.add_edge("apply", END)
graph = builder.compile(checkpointer=MemorySaver())
# run_once.py
from approval_graph import graph
cfg = {"configurable": {"thread_id": "deploy-1"}}
out = graph.invoke({"request": "release v1.2.3"}, cfg)
print(out) # 输出里带 __interrupt__
state = graph.get_state(cfg)
for i in state.interrupts:
print(i.id, i.value) # 32 位十六进制 id + payload
thread_id 是恢复时的定位键。同一个 thread 才能接着上次的 checkpoint 走;换一个 id 就是一张全新的图,这也是「多标签页互相打架」的根源——它们共用同一个 thread。Step 2:先复现旧行为,看清「重放为什么能过」
在不开严格模式的默认状态下,指向不存在或已消费中断的 map,会被静默接受。这不算 bug,而是历史的宽松语义:图只要拿到能用的答复就继续。
# replay.py
from langgraph.types import Command
from approval_graph import graph
cfg = {"configurable": {"thread_id": "deploy-1"}}
graph.invoke({"request": "release v1.2.3"}, cfg)
card = graph.get_state(cfg).interrupts[0]
# 第一次:正常批准
print(graph.invoke(Command(resume={card.id: "approve"}), cfg))
# 第二次:把同一张票据再投一次(模拟页面重试)
print(graph.invoke(Command(resume={card.id: "approve"}), cfg)) # 不报错
这就是真实事故的形状:前端超时重试、用户双击、脚本重跑,都会把同一份答复再投一次。图的语义是「继续」,于是第二次调用可能落到下一个挂起点上,用旧问题的答案回答了新问题。要拦住它,需要的是「这个 id 现在是不是还在等待」的校验,而不是更严的提示词。
Step 3:打开严格模式,只需要一个 config 键
严格模式通过配置键启用,不需要改节点代码、也不新增公开参数。键名是库里的常量 CONFIG_KEY_STRICT_RESUME,字符串值是 __pregel_strict_resume。
# strict.py
cfg = {
"configurable": {
"thread_id": "deploy-1",
"__pregel_strict_resume": True, # 打开严格恢复
}
}
graph.invoke({"request": "release v1.2.3"}, cfg)
| 条件 | 严格校验是否生效 | 说明 |
|---|---|---|
| 根图 + 该键为 True | 生效 | 推荐用法 |
| 嵌套子图 | 不再独立校验 | 继承父级配置,只由根图把关 |
| checkpoint 已被后续写入取代 | 跳过校验 | 重放已完成任务时属于预期行为 |
| 经远程图调用 | 该键被丢弃 | 序列化前清洗,远程侧不会收到 |
这是内部配置键,不是稳定 API。它出现在库的常量里而不是公开文档的示例里,升级小版本时应把它当作「需要回归验证的行为」而不是「写一次长期有效」。上线前把这张表的四行都跑一遍,比读 changelog 更可靠。
Step 4:改成按 id 答复,从 pending 列表里取
严格模式要判断「这个 id 还在不在等」,所以答复必须写成 map 形式:键是中断 id,值是你的决定。map 形式的键要求是 32 位十六进制摘要,正好就是 interrupts 里给出的 id。
# approve_by_id.py
from langgraph.types import Command
from approval_graph import graph
cfg = {
"configurable": {
"thread_id": "deploy-1",
"__pregel_strict_resume": True,
}
}
graph.invoke({"request": "release v1.2.3"}, cfg)
state = graph.get_state(cfg)
pending = {i.id: i for i in state.interrupts}
print("待答复:", list(pending))
# 真正的审批:只对当前 pending 的 id 作答
target_id = next(iter(pending))
out = graph.invoke(Command(resume={target_id: "approve"}), cfg)
print(out)
Step 5:把三类拒绝逐个跑出来,确认它们真的发生
拒绝时抛的是 UnknownInterruptError,带三个字段:reason、interrupt_ids(不处于等待的 id)、pending_ids(仍在等待的 id)。用它就能在前端给出「这条审批已失效,请刷新后重试」这种可操作的提示。
# refusals.py
from langgraph.types import Command
from langgraph.errors import UnknownInterruptError
from approval_graph import graph
def probe(label, payload, cfg):
try:
graph.invoke(Command(resume=payload), cfg)
print(label, "-> 通过")
except UnknownInterruptError as e:
print(label, "-> 拒绝:", e.reason, e.interrupt_ids, e.pending_ids)
# 场景一:随便编一个 32 位 id(等价于已消费的旧票据)
probe("unknown-id", {"0" * 32: "approve"}, cfg)
# 场景二:空 map
probe("empty-map", {}, cfg)
# 场景三:同时挂着多个问题时只给单值
probe("ambiguous", "approve", cfg)
| 场景 | reason | 非严格模式下的旧行为 |
|---|---|---|
| map 里带未知或已消费的 id | not_pending | 静默接受 |
| 提交空 map | empty_map | 静默接受 |
| 有多个 pending 却只给一个值 | ambiguous | 抛普通 RuntimeError |
还有一条容易误解的规则:当没有任何 pending 中断时,传单个值是合法的,用来恢复那些停在静态断点(interrupt_before / interrupt_after)上的图。所以「单值一律禁止」是错的,别在网关层做这种一刀切校验。
更贴近真实业务的是「同时挂两个审批」:一条分支等发布批准,另一条分支等预算批准。这种图在严格模式下必须一次性把两个 id 都答完,只给一个会直接命中歧义拒绝。
# two_gates.py
from langgraph.graph import StateGraph, START, END
from langgraph.types import interrupt, Command
from langgraph.checkpoint.memory import MemorySaver
def release_gate(state):
return {"release_ok": interrupt("批准发布?")}
def budget_gate(state):
return {"budget_ok": interrupt("批准预算?")}
b = StateGraph(dict)
b.add_node("release", release_gate)
b.add_node("budget", budget_gate)
b.add_edge(START, "release")
b.add_edge(START, "budget") # 两个分支并行,各自挂起
b.add_edge(["release", "budget"], END)
graph2 = b.compile(checkpointer=MemorySaver())
cfg2 = {"configurable": {"thread_id": "ship-9",
"__pregel_strict_resume": True}}
graph2.invoke({}, cfg2)
ids = {i.value: i.id for i in graph2.get_state(cfg2).interrupts}
print(ids) # 两个问题,两个 id
# 一次调用同时答复两个;缺一个就会被判为歧义
graph2.invoke(Command(resume={ids["批准发布?"]: "yes",
ids["批准预算?"]: "no"}), cfg2)
len(pending) > 1,就禁用「一键全部同意」按钮,强制逐个确认。审批面板里两个问题挨在一起时,人眼很容易点错,这比后端拦截更早生效。四条结构上的约定,能让你少踩大部分坑。它们不是框架强制要求,而是从「节点会从第一行重跑」这个事实推出来的:
| 约定 | 原因 | 违反后的表现 |
|---|---|---|
| 审批单独成节点 | 恢复时整节点重跑,混着业务逻辑会重复执行 | 审批通过后通知发两次、库存扣两次 |
| 副作用放在审批之后 | 挂起前执行的代码无法回滚 | 拒绝之后系统状态已被改过 |
| payload 自带上下文 | 审批人要能只看 payload 就做决定 | 界面得反查数据库才能渲染,容易看到旧值 |
| 一个 thread 一次只推进一件事 | 并发答复同一 thread 容易互相覆盖 | 两个审批人同时点,后到的覆盖先到的 |
Step 6:收口到服务层,把「一次性」写进流程
严格模式解决的是「答复与 pending 不匹配」,剩下的三件事必须由服务层承担:谁能批、批的是哪一个动作、这条决定留痕在哪。下面这段可以当作最小实现。
# approvals.py
import time, uuid
# 审批票据:interrupt_id -> 票据(一次性核销)
TICKETS = {}
def issue_ticket(thread_id, interrupt_id, action, actor):
TICKETS[(thread_id, interrupt_id)] = {
"ticket": uuid.uuid4().hex,
"action": action, # 与 payload 里的目标动作绑定
"actor": actor,
"issued_at": time.time(),
"used": False,
}
def redeem(thread_id, interrupt_id, actor):
item = TICKETS.get((thread_id, interrupt_id))
if not item:
raise PermissionError("没有对应票据")
if item["used"]:
raise PermissionError("票据已核销")
if item["actor"] != actor:
raise PermissionError("票据不属于当前审批人")
item["used"] = True # 先核销再提交,失败也不复用
return item
# 调用侧:先核销,再由严格模式兜底
item = redeem("deploy-1", target_id, "alice")
graph.invoke(Command(resume={target_id: "approve"}), cfg)
| 职责 | 放哪 | 为什么 |
|---|---|---|
| 答复是否属于当前 pending | LangGraph(strict resume) | 只有图知道挂起状态 |
| 票据是否已核销、是否本人 | 你的服务层 | 图不认人,也不存业务票据 |
| 审批对象是否被篡改 | 服务层把 action 写进票据并与 payload 比对 | 防止「换了目标沿用旧同意」 |
| 审计留痕 | 持久化表 + 日志 | 事后追责与复盘 |
升级时还有一处代码要改:UnknownInterruptError 不是 RuntimeError 的子类,老代码里那个 except RuntimeError 拦不住它。上线前把捕获顺序调好,否则用户看到的是 500 而不是「审批已失效」。
# errors_to_http.py
from langgraph.errors import UnknownInterruptError
def resume_or_explain(graph, payload, cfg):
try:
return graph.invoke(Command(resume=payload), cfg)
except UnknownInterruptError as e:
# 先捕获具体异常,再捕获兜底
if e.reason == "not_pending":
return {"code": 409, "msg": "这条审批已失效,请刷新后重新确认",
"pending": list(e.pending_ids)}
if e.reason == "empty_map":
return {"code": 400, "msg": "没有提交任何决定"}
return {"code": 409, "msg": "有多个待审批项,请逐项确认",
"pending": list(e.pending_ids)}
except RuntimeError as e:
return {"code": 409, "msg": str(e)}
上线后要盯的指标不多,但每一条都对应一种真实故障。把它们接到现有监控里,比事后翻日志有效:
| 指标 | 异常信号 | 可能是哪里坏了 |
|---|---|---|
not_pending 拒绝率 | 突然升高 | 前端在重试,或票据没核销就复用 |
ambiguous 拒绝数 | 持续大于 0 | 界面没做逐项确认,仍在提交单值 |
| 挂起时长 | 长尾很长 | 没人认领审批,需要加提醒或超时策略 |
| 票据核销与实际推进的差值 | 差值持续扩大 | 核销后恢复失败,属于要立刻查的漏推进 |
做到哪一步算成功
| 检查项 | 期望现象 | 对应步骤 |
|---|---|---|
| 能挂起 | 首次 invoke 返回 __interrupt__,get_state().interrupts 有 id 与 payload | Step 1 |
| 旧行为可复现 | 不开严格模式时,重复投同一 id 不报错 | Step 2 |
| 严格模式生效 | 同样操作抛 UnknownInterruptError,reason=not_pending | Step 3、5 |
| 按 id 可推进 | 用当前 pending 的 id 作答,图继续走到 apply | Step 4 |
| 三类拒绝齐全 | unknown-id、empty-map、ambiguous 分别命中三种 reason | Step 5 |
| 服务层兜底 | 同一票据第二次核销被拒,且日志有记录 | Step 6 |
常见问题速查
| 现象 | 大概率原因与处理 |
|---|---|
| 加了键但没生效 | 键放错了层级(要在 configurable 里)、拼写不符,或当前是嵌套子图;用根图配置再试 |
| 远程部署后拦不住重放 | 该键在远程调用的配置清洗中被丢弃;远程侧要单独验证,或把校验前移到你的网关 |
| 同一节点两次 interrupt 的 id 一样 | 符合当前实现;判断「是否同一个问题」要用 payload,不要用 id |
| 提交单值报「multiple pending interrupts」 | 同时挂了多个问题,必须按 id 逐个答复;没有 pending 时单值才合法 |
| 报错后图坏了 | 不会:校验发生在写入前,pending 仍可继续回答;刷新拿新 id 重试即可 |
| 节点恢复后重复发通知 | 恢复是从节点第一行重跑;把副作用移到挂起之后,或用幂等键去重 |
| 升级到更高小版本后行为变化 | 把 Step 3 的四行条件表当回归清单跑一遍,别只看 release note 标题 |
| 想要「谁能批」的强约束 | 严格模式不做授权;在服务层用票据 + 角色校验,图只负责状态一致性 |