messages: list[dict[str, Any]] = field(default_factory=list) 核心对话历史：Anthropic 格式的消息列表

在 Python特别是使用dataclasses或Pydantic中这行代码的设计非常地道且考究。它完美平衡了Python 语言特性与Anthropic API 的架构规范。我们可以从Python 代码设计和Anthropic 协议设计两个维度拆解为什么要这样设计1. 为什么用field(default_factorylist)而不是default[]这是 Pythondataclass的核心机制与避坑指南。陷阱Mutable Default Argument如果直接写messages: list []Python 会在加载类定义时只创建一个列表对象。后续该类所有的实例只要未显式传参都会共享同一个列表用户 A 的对话记录会直接漏给用户 B。解决方案default_factorylist是一个工厂函数。它告诉dataclass“每次创建一个新实例时调用一次list()即[]生成一个全新的、独立的列表。”2. 为什么类型注解是list[dict[str, Any]]Anthropic API 的消息结构在 JSON 层面上天然对应 Python 的字典列表JSON[ {role: user, content: Hello!}, {role: assistant, content: Hi there!} ]list[...]对话历史是一个严格有序的时间序列列表能够保持消息的先后顺序。dict[str, Any]键Key一定是字符串如role,content。值Value用Any是因为content不仅可以传字符串还可以传复合结构如多模态图片、Tool Use / Function Calling 结构Python# 多模态/工具调用的 content 往往是一个 list[dict] content: [ {type: text, text: What is in this image?}, {type: image, source: {...}} ]因此Any灵活地容纳了纯文本、多模态以及工具调用Tool Calls的复杂数据。3. 为什么是 Anthropic 格式与 OpenAI 有何区别Anthropic 的 Messages API 设计强调了严格的交替对话逻辑与职责分离① 角色严格限定为user和assistant不同于 OpenAI 把system消息直接混在messages列表中如{role: system, ...}Anthropic 强制规定messages中只能出现user和assistantsystem提示词必须作为 API 的顶层单独参数传递例如client.messages.create(system..., messages...)。因此这里的messages列表是极其纯粹的对话历史。② 严格交替Strict AlternationAnthropic 要求messages中的角色必须交替出现user-assistant-user...且第一条消息通常必须是user。总结设计细节解决的核心问题default_factorylist隔离状态防止多会话共享同一列表引发数据污染。dict[str, Any]支持多模态 工具兼容文本、图片、Tool Call 等复杂数据结构。Anthropic 专属逻辑职责分离剥离system设定专注于严格交替的user/assistant上下文。