Class ConversationMessage

tutorials/02_session_and_messages.py:150–212

一条完整的对话消息。 和 Tutorial 01 里简单的 Message 不同，这里： - content 不再是一个字符串，而是一个 ContentBlock 列表 - 多了 usage 字段来追踪 token 消耗 对应源码: session.rs:36-40

@dataclass(frozen=True)
class ConversationMessage:
    """
    一条完整的对话消息。

    和 Tutorial 01 里简单的 Message 不同，这里：
    - content 不再是一个字符串，而是一个 ContentBlock 列表
    - 多了 usage 字段来追踪 token 消耗

    对应源码: session.rs:36-40
    """
    role: str                            # "user" | "assistant" | "tool" | "system"
    blocks: tuple[ContentBlock, ...]     # 内容块列表（用 tuple 因为不可变）
    usage: Optional[TokenUsage] = None   # 只有 assistant 消息才有 usage

    # 下面是几个方便创建消息的方法（工厂方法）
    # "工厂方法"就是"帮你快速创建对象的函数"，省得每次都写一堆参数

    @staticmethod
    def user_text(text: str) -> "ConversationMessage":
        """创建一条用户文字消息"""
        return ConversationMessage(
            role="user",
            blocks=(TextBlock(text=text),),
        )

    @staticmethod
    def assistant_text(text: str, usage: Optional[TokenUsage] = None) -> "ConversationMessage":
        """创建一条助手文字消息"""
        return ConversationMessage(
            role="assistant",
            blocks=(TextBlock(text=text),),
            usage=usage,
        )

    @staticmethod
    def assistant_with_tool_use(
        text: str, tool_id: str, tool_name: str, tool_input: str,
        usage: Optional[TokenUsage] = None,
    ) -> "ConversationMessage":
        """创建一条包含文字和工具调用的助手消息"""
        return ConversationMessage(
            role="assistant",
            blocks=(
                TextBlock(text=text),
                ToolUseBlock(id=tool_id, name=tool_name, input=tool_input),
            ),
            usage=usage,
        )

    @staticmethod
    def tool_result(
        tool_use_id: str, tool_name: str, output: str, is_error: bool = False,
    ) -> "ConversationMessage":
        """创建一条工具结果消息"""
        return ConversationMessage(
            role="tool",
            blocks=(ToolResultBlock(
                tool_use_id=tool_use_id,