[智能体-326]：messages: Annotated[list[str], operator.add]， 这是什么语法
一、基础语法演示（纯 Python，无第三方库）
Annotated只是带元数据的类型注解，operator.add是附加的自定义规则，原生 Python 不会自动执行规则，仅做标记。
python
运行
from typing import Annotated import operator # 定义变量：类型 list[str]，附加元数据 operator.add messages: Annotated[list[str], operator.add] = ["你好"] # 手动模拟「合并逻辑」（对应框架内部逻辑） new_msg = ["今天天气不错"] # operator.add(a, b) 等价于 a + b messages = operator.add(messages, new_msg) print(messages)输出：
plaintext
['你好', '今天天气不错']二、核心场景：LangGraph 状态合并（最常用）
LangGraph 会自动读取 Annotated 里的合并函数，多节点更新状态时执行对应逻辑。
1. 安装依赖
bash
运行
pip install langgraph2. 完整可运行代码
python
运行
from typing import Annotated import operator from langgraph.graph import StateGraph, START, END # 1. 定义状态类 class ChatState(dict): # 关键写法：列表类型 + 合并规则 = 列表相加(追加) messages: Annotated[list[str], operator.add] # 2. 定义节点函数（每个节点都会更新 messages） def node_a(state: ChatState) -> ChatState: return {"messages": ["节点A：我收到请求了"]} def node_b(state: ChatState) -> ChatState: return {"messages": ["节点B：开始处理内容"]} # 3. 构建图 builder = StateGraph(ChatState) builder.add_node("A", node_a) builder.add_node("B", node_b) # 流转：START → A → B → END builder.add_edge(START, "A") builder.add_edge("A", "B") builder.add_edge("B", END) # 编译运行 graph = builder.compile() # 初始状态：空列表 result = graph.invoke({"messages": []}) # 打印最终结果 print(result["messages"])运行结果
plaintext
['节点A：我收到请求了', '节点B：开始处理内容']逻辑说明
- 初始
messages = [] - 节点 A 返回
["节点A：..."]，框架执行[] + ["节点A..."] - 节点 B 返回
["节点B：..."]，框架执行["节点A..."] + ["节点B..."] - 最终列表追加，不会覆盖旧数据。
三、对比：默认覆盖 vs operator.add 追加
1. 不写 operator.add（默认覆盖）
python
运行
from typing import Annotated from langgraph.graph import StateGraph, START, END class ChatState(dict): # 无合并函数：默认直接覆盖原值 messages: list[str] def node_a(state): return {"messages": ["A 消息"]} def node_b(state): return {"messages": ["B 消息"]} builder = StateGraph(ChatState) builder.add_node("A", node_a) builder.add_node("B", node_b) builder.add_edge(START, "A") builder.add_edge("A", "B") builder.add_edge("B", END) graph = builder.compile() res = graph.invoke({"messages": []}) print(res["messages"]) # 只保留最后一个：['B 消息']2. 自定义合并函数（拓展用法）
不用operator.add，自己写合并逻辑：
python
运行
from typing import Annotated from langgraph.graph import StateGraph, START, END # 自定义合并：新列表放前面 def merge_func(old_list, new_list): return new_list + old_list class ChatState(dict): messages: Annotated[list[str], merge_func] def node_a(state): return {"messages": ["A"]} def node_b(state): return {"messages": ["B"]} builder = StateGraph(ChatState) builder.add_node("A", node_a) builder.add_node("B", node_b) builder.add_edge(START, "A") builder.add_edge("A", "B") builder.add_edge("B", END) graph = builder.compile() res = graph.invoke({"messages": []}) print(res["messages"]) # ['B', 'A']四、总结关键点
Annotated[list[str], operator.add]- 第一层：类型注解，标明是字符串列表
- 第二层：合并回调函数，给框架使用
operator.add(a, b)=a + b，列表场景就是尾部追加- 仅在 LangGraph / Pydantic 这类框架中会自动解析该规则，原生 Python 只做注释。