Crate agent_context 

agent-context

通用、后端无关的 LLM 对话上下文管理器，基于 kameo Actor 模型构建。

核心概念

三区 + Scratch 消息模型

上下文消息按可变性分为三个存储区域，加上一个可选且不存储的 Scratch 层，按序拼接为完整对话：

区域	容器	可变性	用途
immutable	ReadOnly	不可变	系统提示词、预设上下文等构造后不变的消息
compressed	Vec	仅压缩时写入	历史对话压缩后的摘要
incremental	Vec	完全可变	当前活跃对话，支持增删改查
scratch	—	可选，不存储	每轮刷新的临时元数据（时间、工作目录等），通过 CommonOpts 配置

拼接顺序：immutable → compressed → incremental → scratch（如有）。 Scratch 由调用方在每次 RequestSend/RequestSendStream 时通过 CommonOpts 传入， 不存入任何区域，不触发变更事件，不参与序列化。

后端 trait

ContextBackend 是核心抽象，封装 LLM 后端的：

• 消息工厂：user_message、system_message、tool_message
• 格式转换：to_system_message、to_request_messages
• 响应解析：extract_messages
• 模型对话：send、send_stream、estimate_tokens

实现 ContextBackend 即可让 AC 支持任意 LLM 后端（DeepSeek、智谱、OpenAI 等）。

上下文压缩

RequestSend/RequestSendStream 发送前自动检测上下文是否已满。 当 CommonOpts::auto_compress 为 true 时自动压缩；为 false 时返回错误。 也可通过 RequestCompress 手动触发压缩，支持 CompressStrategy::Summarize 策略。 通过 RequestSubscribeCompressed 注册压缩结果订阅者，可在压缩后修改摘要与保留消息。

快速开始

use agent_context::{
    AgentContext, RequestAppend, RequestSend, RequestSendStream, RequestMessages,
    ContextBackend, CommonOpts,
};
use futures::StreamExt;

// 1. 实现 ContextBackend（以你的 LLM SDK 类型）
// 2. 创建 Actor
let ctx = AgentContext::new(my_backend, vec![backend.system_message("You are a helpful assistant.")]);
let actor_ref = AgentContext::spawn(ctx);

// 3. 非流式对话
actor_ref.ask(RequestAppend { message: user_msg }).await?;
actor_ref.ask(RequestSend { opts: my_opts }).await?;

// 4. 流式对话
let mut stream = actor_ref.ask(RequestSendStream { opts: my_opts }).await??;
while let Some(chunk) = stream.next().await { /* 逐块处理 */ }
let chunks = stream.take_chunks();
let msg = backend.merge_chunks(&chunks).expect("chunk merge failed");
let msgs = backend.to_request_messages(vec![msg])?;
for m in msgs {
    actor_ref.ask(RequestAppend { message: m }).await?;
}

// 5. 读取全部消息
let all: Vec<_> = actor_ref.ask(RequestMessages).await?;

Structs

AgentContext

LLM 对话上下文管理器，kameo Actor。

AgentSendStream

流式对话的 Stream 返回类型。

CommonOpts

请求级公共配置，内嵌于各后端的 Opts 类型。

NotifyCompressedForReply

压缩完成通知，通过 RequestSubscribeCompressed 注册的订阅者处理。

ReadOnly

只读容器：构造后不可变，仅暴露切片访问。

RequestAppend

追加一条消息到 incremental 区末尾。

RequestClear

清空整个 incremental 区。

RequestCompress

触发上下文压缩。

RequestCompressed

获取 compressed 区的消息副本。

RequestEstimateTokens

估算三区全部消息的 token 数量。

RequestExportAll

将三区全部消息导出为字符串（完整上下文）。Reply = Result<String, AgentError>。

RequestExportIncremental

将 incremental 区消息导出为字符串。Reply = Result<String, AgentError>。

RequestExtend

批量追加消息到 incremental 区。

RequestFindByRole

按角色筛选三区全部消息。

RequestGet

按全局索引获取消息。

RequestImmutable

获取 immutable 区的消息副本。

RequestImportIncremental

从字符串导入消息到 incremental 区。Reply = Result<(), AgentError>。

RequestIncremental

获取 incremental 区的消息副本。

RequestInsert

在 incremental 区指定索引插入消息。

RequestIsEmpty

检查三区是否全部为空。

RequestLen

获取三区总消息数。

RequestMessages

获取三区全部消息的拼接结果。

RequestPop

弹出 incremental 区最后一条消息。

RequestRemove

移除 incremental 区指定索引的消息。

RequestRetain

按角色保留 incremental 区消息，其余移除。

RequestSend

非流式对话。

RequestSendStream

流式对话。

RequestSubscribeCompressed

设置压缩结果订阅者。Reply = ()。

RequestUnsubscribeCompressed

清除压缩结果订阅者。Reply = ()。

RequestUpdate

替换 incremental 区指定索引的消息。

ToolCallInfo

工具调用信息。从后端 Response 中提取，供 consumer 执行工具并构造 Tool 角色消息。

Enums

AgentError

Agent 上下文操作错误类型。

CompressStrategy

压缩策略参数。

ResponseType

响应内容类型枚举。

Role

LLM 对话消息角色，对应 OpenAI/DeepSeek/智谱等 API 的标准消息角色。

StreamEvent

流式输出事件，由 ContextBackend::classify_chunk 产出。

Traits

ContextBackend

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

ContextBackendResponse

后端 Response 类型约束，流式/非流式 Response 均需实现。

ContextMessage

后端消息类型必须实现此 trait。