不是所有代码，
都需要变成图

只有两三步时，普通函数最清楚。真正让人头疼的是：分支越来越多、失败要重试、流程会暂停、过几小时还要接着运行。

State 不是记忆魔法，
只是一张共享表单

流程走到任何一步，都要知道目前已经有哪些事实。State 就把这些事实放在有名字的字段里。

Node 是一道工序：
读取 State，返回局部更新

清洗节点只负责清洗。它没有必要复制整张表单，更不应该偷偷修改全局变量。

def clean_node(state: State):
    clean = state["raw_text"].strip()
    return {"clean_text": clean}

到了岔路口，
路由函数只负责选方向

它读取当前 State，例如 difficulty，然后返回下一节点名称。它不生成答案，也不做数据库操作。

两个节点同时写一个字段，
到底该覆盖还是追加？

普通字段默认使用“新值覆盖旧值”。但日志、消息和并行结果通常需要保留双方内容，所以必须提前写清合并规则。

import operator
from typing import Annotated

class State(TypedDict):
    results: Annotated[
        list[str],
        operator.add
    ]

“不合格就修改”很容易，
难的是确保一定能停

循环需要两个出口：内容已经通过，或者修改次数达到上限。revision_count 必须放进 State，因为路由、存档和恢复都要看到真实次数。

不是把流程“全交给 AI”，
而是让它只处理语义任务

能用确定规则写清的事情，Python 更快、更便宜、更稳定。只有理解含义、生成语言或评价质量时，才需要模型。

已判断 0 / 6

模型只初始化一次，
节点只负责调用它

不要在每个节点里重复创建模型。统一模块便于切换供应商、设置超时与重试，也能避免配置散落。

def generate_answer(state: State):
    started = time.perf_counter()
    try:
        response = model.invoke(
            state["question"]
        )
        return {
          "answer": response.content,
          "latency_ms": elapsed(started)
        }
    except Exception as error:
        return {"error": type(error).__name__}

聊天不只是字符串，
每条消息都有角色与顺序

HumanMessage 表示用户说了什么，AIMessage 表示模型回答或提出工具调用，ToolMessage 把真实执行结果送回模型。

程序不要解析“差不多”的话，
而要接收有类型的结果

让模型自由回答“我觉得这可能是进阶题，因为……”很适合人读，却很不适合程序路由。Schema 把允许字段、类型和枚举提前写清。

Checkpoint 是存档，
thread_id 是存档槽编号

图在 super-step 边界保存 StateSnapshot。下次携带相同 thread_id，运行时才能找到这一段会话；换一个编号，就像打开全新的存档。

Time travel 不是修改过去，
而是从旧快照重新出发

Replay 使用旧 checkpoint 的 config 重新执行后续节点；Fork 先用 update_state 创建新 checkpoint，再沿新状态继续。原历史不会被删除。

同一次运行，
可以从三个角度观看

values 看每一步后的完整 State；updates 只看节点刚改了什么；messages 专门看模型 token 或消息片段。

工具不是神秘插件，
而是一个描述清楚的函数

模型要知道工具名称、用途和参数类型；执行层要知道如何验证输入、捕获错误并返回稳定结果。

模型不会直接执行工具，
它只会提出一个结构化申请

模型产生 tool_calls；工具节点从白名单中找到函数并执行；结果以 ToolMessage 返回；模型再决定回答还是继续调用。

模型可以做决定，
但安全边界必须是代码

未知工具、缺少参数、超时和工具异常都要返回明确的 ToolMessage，让模型知道发生了什么，而不是让整张图无提示崩溃。

程序不是卡死，
而是保存现场后等你回来

interrupt() 把可序列化提示交给外部，并让图暂停。Checkpointer 保存 State；恢复时使用相同 thread_id 和 Command(resume=...)。

恢复后节点会从头执行，
但发送、保存、扣费不能重复生效

幂等不是“绝不执行第二次”，而是相同业务操作即使被重试，最终外部结果仍然和执行一次相同。

任务数量运行前不知道，
就让 Planner 动态发出N 份工作单

Planner 先产生子任务；每个 Send 包含目标 worker 和该次独立输入；worker 并行返回局部结果；Reducer 合并后再统一排序和总结。

def dispatch(state: OverallState):
    return [
      Send("worker", task)
      for task in state["tasks"]
    ]

当“生成 → 审核 → 修改”已经很复杂，
把它收进一个可独立测试的小图

父图只关心 topic 和最终 draft；review_feedback、revision_count 等内部细节留在子图。边界越清晰，修改内部流程时越不容易影响父图。

Router 像医院分诊台：
先判断类型，再送往合适专家

一个明确的路由步骤对输入分类，可以选择一个专家，也可以把独立子问题并行分给多个专家，最后统一汇总。

主 Agent 不交出方向盘，
只把明确任务作为工具委派

主 Agent 理解用户整体目标，决定调用哪个专家、给它多少上下文，再把专家返回的局部结论汇总成统一回答。

Handoff 不是“问专家一句”，
而是把后续对话正式交接

例如售前确认需求后，把用户交给实施顾问；接下来几轮都由新角色负责。状态中的 active_agent 或 current_step 会持续影响行为。

Demo 会跑只是起点，
生产还要知道坏在哪里、如何恢复

持久化 checkpoint、身份隔离、超时重试、成本上限、日志脱敏、状态保留策略和副作用幂等，决定系统是否能长期运行。