官方在类文档里用加粗警告把这点讲死了——别对着建造器直接 invoke：

    !!! warning
        `StateGraph` is a builder class and cannot be used directly for execution.
        You must first call `.compile()` to create an executable graph that supports
        methods like `invoke()`, `stream()`, `astream()`, and `ainvoke()`.

类的泛型签名也值得一眼——它带了 4 个类型参数，暗示了后面要学的东西：

class StateGraph(Generic[StateT, ContextT, InputT, OutputT]):

类顶部的属性声明，就是这张"图纸"的全部家当。记住它们，后面所有方法都在往这几个容器里塞东西：

    edges: set[tuple[str, str]]
    nodes: dict[str, StateNodeSpec[Any, ContextT]]
    branches: defaultdict[str, dict[str, BranchSpec]]
    channels: dict[str, BaseChannel]
    managed: dict[str, ManagedValueSpec]
    schemas: dict[type[Any], dict[str, BaseChannel | ManagedValueSpec]]
    waiting_edges: set[tuple[tuple[str, ...], str]]

看 __init__ 的核心部分（跳过一堆弃用参数兼容代码）：

        self.nodes = {}
        self.edges = set()
        self.branches = defaultdict(dict)
        self.schemas = {}
        self.channels = {}
        self.managed = {}
        self.compiled = False
        self.waiting_edges = set()

        self.state_schema = state_schema
        self.input_schema = cast(type[InputT], input_schema or state_schema)
        self.output_schema = cast(type[OutputT], output_schema or state_schema)
        self.context_schema = context_schema

        self._node_defaults = _NodeDefaults()

        self._add_schema(self.state_schema)
        self._add_schema(self.input_schema, allow_managed=False)
        self._add_schema(self.output_schema, allow_managed=False)

_add_schema 内部有个很妙的"同名字段冲突"处理，体现了设计的细致：

            for key, channel in channels.items():
                if key in self.channels:
                    if self.channels[key] != channel:
                        if isinstance(channel, LastValue):
                            pass                        # ← 同名但新的是 LastValue：容忍
                        else:
                            raise ValueError(
                                f"Channel '{key}' already exists with a different type"
                            )
                else:
                    self.channels[key] = channel

昨天只用了 add_node("A", node) 两个参数，但真实签名有一长串关键字参数——每一个都是后面某一天的主题：

    def add_node(
        self,
        node: str | StateNode[NodeInputT, ContextT],
        action: StateNode[NodeInputT, ContextT] | None = None,
        *,
        defer: bool = False,
        metadata: dict[str, Any] | None = None,
        input_schema: type[NodeInputT] | None = None,
        retry_policy: RetryPolicy | Sequence[RetryPolicy] | None = None,
        cache_policy: CachePolicy | None = None,
        error_handler: StateNode[Any, ContextT] | None = None,
        destinations: dict[str, str] | tuple[str, ...] | None = None,
        timeout: float | timedelta | TimeoutPolicy | None = None,
        **kwargs,
    ) -> Self:

实现体里最核心的三段。第一段——自动推断节点名：

        if not isinstance(node, str):
            action = node
            if isinstance(action, Runnable):
                node = action.get_name()
            else:
                node = getattr(action, "__name__", action.__class__.__name__)

第二段——一堆护栏校验（这些就是昨天报错的来源）：

        if node in self.nodes:
            raise ValueError(f"Node `{node}` already present.")   # 重名
        if node == END or node == START:
            raise ValueError(f"Node `{node}` is reserved.")       # 占用保留名
        for character in (NS_SEP, NS_END):
            if character in node:
                raise ValueError(
                    f"'{character}' is a reserved character and is not allowed in the node names."
                )

第三段——打包成 StateNodeSpec 存进 nodes（这里取最常见的分支）：

            self.nodes[node] = StateNodeSpec[StateT, ContextT](
                coerce_to_runnable(action, name=node, trace=False),
                metadata,
                input_schema=self.state_schema,
                retry_policy=retry_policy,
                cache_policy=cache_policy,
                error_handler_node=handler_node_name,
                ends=ends,
                defer=defer,
                timeout=timeout,
            )

add_edge 接受两种起点：单个字符串，或一个字符串列表。它俩进不同的容器：

        if isinstance(start_key, str):
            if start_key == END:
                raise ValueError("END cannot be a start node")   # END 不能当起点
            if end_key == START:
                raise ValueError("START cannot be an end node")   # START 不能当终点
            ...
            self.edges.add((start_key, end_key))                 # ← 普通边进 edges
            return self

        # start_key 是列表的情况：
        for start in start_key:
            if start not in self.nodes:
                raise ValueError(f"Need to add_node `{start}` first")
        ...
        self.waiting_edges.add((tuple(start_key), end_key))       # ← 汇合边进 waiting_edges

compile 签名里最常用的就是 checkpointer（存档器）——这是"持久化"的入口：

    def compile(
        self,
        checkpointer: Checkpointer = None,
        *,
        cache: BaseCache | None = None,
        store: BaseStore | None = None,
        interrupt_before: All | list[str] | None = None,
        interrupt_after: All | list[str] | None = None,
        debug: bool = False,
        name: str | None = None,
        ...
    ) -> CompiledStateGraph[StateT, ContextT, InputT, OutputT]:

compile 内部干的四件大事（挑核心行）：

        checkpointer = ensure_valid_checkpointer(checkpointer)   # ① 规整存档器
        ...
        self.validate(interrupt=(...))                            # ② 校验结构
        # ③ 挑出输出通道、流式通道
        output_channels = (...)
        stream_channels = (...)
        # ④ 造出 CompiledStateGraph（继承 Pregel），把节点/边翻译成通道与 PregelNode

翻译的证据——把节点变成 PregelNode 就发生在 attach_node：

            self.nodes[key] = PregelNode(
                triggers=[branch_channel],       # 被哪个通道"触发"就跑
                channels=(...),                  # 读哪些状态字段
                mapper=mapper,
                writers=[ChannelWrite(write_entries)],  # 结果写回哪些通道
                ...
                bound=node.runnable,             # ← 你写的那个函数在这
            )

✋ 10 分钟动手

# 1. 亲眼看 7 个内部容器的声明
sed -n '201,207p' libs/langgraph/langgraph/graph/state.py

# 2. 看 __init__ 如何初始化并立刻解析 schema
sed -n '251,269p' libs/langgraph/langgraph/graph/state.py

# 3. 找到 add_node 真正的实现（有 body 的那个）
sed -n '662,676p' libs/langgraph/langgraph/graph/state.py

# 4. 在 REPL 里搭个空图，打印内部容器看看
python3 -c "from langgraph.graph import StateGraph; from typing_extensions import TypedDict; \
class S(TypedDict): x:int
g=StateGraph(S); g.add_node('A', lambda s:{'x':s['x']+1}); \
print('nodes=',list(g.nodes)); print('channels=',list(g.channels))"

# 5. 看 add_edge 怎么分流普通边/汇合边
sed -n '938,967p' libs/langgraph/langgraph/graph/state.py