Trait ContextBackend 

pub trait ContextBackend:
    Send
    + Sync
    + Clone
    + 'static {
    type Message: ContextMessage;
    type Opts: ScratchOpts + Clone + Default + Send + Sync;
    type Response: Clone + Send + Sync + ContextBackendResponse;

    // Required methods
    fn user_message(&self, content: impl Into<String> + Send) -> Self::Message;
    fn system_message(&self, content: impl Into<String> + Send) -> Self::Message;
    fn tool_message(
        &self,
        tool_call_id: impl Into<String> + Send,
        content: impl Into<String> + Send,
    ) -> Self::Message;
    fn merge_chunks(
        &self,
        responses: &[Self::Response],
    ) -> Option<Self::Message>;
    fn extract_messages_from_backend_response(
        &self,
        responses: &[Self::Response],
    ) -> Result<Vec<Self::Message>, AgentError>;
    fn estimate_tokens(
        &self,
        messages: &[Self::Message],
    ) -> impl Future<Output = Result<usize, AgentError>> + Send;
    fn context_window(&self) -> usize;
    fn send(
        &self,
        messages: &[Self::Message],
        opts: &Self::Opts,
    ) -> impl Future<Output = Result<Self::Response, AgentError>> + Send;
    fn send_stream(
        &self,
        messages: Vec<Self::Message>,
        opts: Self::Opts,
    ) -> impl Stream<Item = Result<Self::Response, AgentError>> + Send + 'static;

    // Provided methods
    fn to_system_message(&self, msg: Self::Message) -> Self::Message { ... }
    fn to_request_messages(
        &self,
        messages: Vec<Self::Message>,
    ) -> Result<Vec<Self::Message>, AgentError> { ... }
    fn classify_chunk(
        &self,
        response: &Self::Response,
        saw_thinking: &mut bool,
    ) -> Vec<StreamEvent<Self::Response>> { ... }
    fn message_to_jsonl(
        &self,
        msg: &Self::Message,
    ) -> Result<String, AgentError> { ... }
    fn message_from_jsonl(
        &self,
        line: &str,
    ) -> Result<Self::Message, AgentError> { ... }
}

后端 trait：抽象 LLM 后端的完整接口。

实现此 trait 即可让 AgentContext 对接任意 LLM 后端（DeepSeek、智谱、OpenAI 等）。

方法分类

类别	方法	类型
消息工厂	user_message、system_message、tool_message	关联函数
格式转换	to_system_message、to_request_messages	关联函数（默认实现）
请求选项	通过 Default::default() 获取 Self::Opts 默认值	类型约束
响应解析	extract_messages_from_backend_response	实例方法
模型对话	estimate_tokens、send、send_stream	实例方法
配置信息	context_window	实例方法

Required Associated Types

type Message: ContextMessage

后端消息类型，必须实现 ContextMessage。

type Opts: ScratchOpts + Clone + Default + Send + Sync

后端自定义的请求选项类型，AC 不感知字段含义，只做透传。

典型用途：传递 temperature、max_tokens、thinking 等模型参数。 实现 Default trait 获取默认值，CLI 可在此基础上覆盖。

type Response: Clone + Send + Sync + ContextBackendResponse

后端完整的 API 响应类型。

• 非流式：ChatCompletion（含 choices + usage）
• 流式：ChatCompletionChunk（含 delta content / reasoning_content）

Required Methods

fn user_message(&self, content: impl Into<String> + Send) -> Self::Message

构造一条 User 角色消息。

fn system_message(&self, content: impl Into<String> + Send) -> Self::Message

构造一条 System 角色消息。

fn tool_message( &self, tool_call_id: impl Into<String> + Send, content: impl Into<String> + Send, ) -> Self::Message

构造一条 Tool 角色消息（工具调用结果）。

fn merge_chunks(&self, responses: &[Self::Response]) -> Option<Self::Message>

将流式分块合并为单条消息。

累加 content、reasoning_content、tool_calls，构造完整的 assistant 消息。

fn extract_messages_from_backend_response( &self, responses: &[Self::Response], ) -> Result<Vec<Self::Message>, AgentError>

从后端原始响应中提取消息列表。非流式传 &[单个 Response]，流式传 &[所有累积 chunk]。

fn estimate_tokens( &self, messages: &[Self::Message], ) -> impl Future<Output = Result<usize, AgentError>> + Send

估算消息列表的 token 数量。I/O 操作（可能需要调用远程 tokenizer API）。

fn context_window(&self) -> usize

模型上下文窗口大小（token 数），用于 IsFullMsg 检测。

fn send( &self, messages: &[Self::Message], opts: &Self::Opts, ) -> impl Future<Output = Result<Self::Response, AgentError>> + Send

非流式对话。发送全部消息，返回完整 Response（含 usage 等元数据）。

fn send_stream( &self, messages: Vec<Self::Message>, opts: Self::Opts, ) -> impl Stream<Item = Result<Self::Response, AgentError>> + Send + 'static

流式对话。参数为 owned（数据已移动），返回 'static 流。

Provided Methods

fn to_system_message(&self, msg: Self::Message) -> Self::Message

将消息转换为 System 角色（用于压缩摘要等场景）。

默认实现调用 ContextMessage::with_role。

fn to_request_messages( &self, messages: Vec<Self::Message>, ) -> Result<Vec<Self::Message>, AgentError>

将后端响应消息转换为请求格式。

对 !preserve_reasoning() 的消息剥离 reasoning_content，减少网络传输和 token 消耗。

默认实现调用 ContextMessage::without_reasoning。

fn classify_chunk( &self, response: &Self::Response, saw_thinking: &mut bool, ) -> Vec<StreamEvent<Self::Response>>

将流式分块分类为结构化事件，同时更新阶段状态。

默认实现基于 ContextBackendResponse::response_type 判断阶段：

• 含 reasoning_content → StreamEvent::Thinking
• 第一个 content（且之前有思考链）→ StreamEvent::ContentFirst
• 后续 content → StreamEvent::Content

fn message_to_jsonl(&self, msg: &Self::Message) -> Result<String, AgentError>

将消息序列化为 JSONL 行（供应商原生格式）。

默认实现直接序列化 Self::Message。多供应商 enum 后端需覆写， 提取内层供应商原生消息序列化，跳过 enum 变体名包装。

fn message_from_jsonl(&self, line: &str) -> Result<Self::Message, AgentError>

从 JSONL 行反序列化为消息。

默认实现直接反序列化为 Self::Message。多供应商 enum 后端需覆写， 按当前供应商类型解析后包装为 enum 变体。

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

Implementors