Expand description
§agent-context
通用、后端无关的 LLM 对话上下文管理器，基于 kameo Actor 模型构建。
§核心概念
§三区 + Scratch 消息模型
上下文消息按可变性分为三个存储区域，加上一个不存储的 Scratch 层，按序拼接为完整对话：
| 区域 | 容器 | 可变性 | 用途 |
|---|---|---|---|
| immutable | ReadOnly | 不可变 | 系统提示词、预设上下文等构造后不变的消息 |
| compressed | Vec | 仅压缩时写入 | 历史对话压缩后的摘要 |
| incremental | Vec | 完全可变 | 当前活跃对话，支持增删改查 |
| scratch | — | 不存储 | 每轮刷新的临时元数据（时间、工作目录等），通过 CommonOpts 配置 |
拼接顺序：immutable → compressed → incremental → scratch（如有）。
Scratch 由调用方在每次 SendMsg/SendStreamMsg 时通过 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 等）。
§变更通知
通过 with_on_change 注册回调，监听 ChangeEvent 实时追踪消息变化。
§上下文压缩
SendMsg/SendStreamMsg 发送前自动检测上下文是否已满。
当 CommonOpts::auto_compress 为 true 时自动压缩；为 false 时返回错误。
也可通过 CompressMsg 手动触发压缩，支持 CompressStrategy::Summarize 策略。
§快速开始
ⓘ
use agent_context::{AgentContext, AppendMsg, SendMsg, SendStreamMsg, MessagesMsg, 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 = AgentContext::spawn(ctx);
// 3. 非流式对话
actor.ask(AppendMsg { message: user_msg }).await?;
actor.ask(SendMsg { opts: my_opts }).await?;
// 4. 流式对话
let mut stream = actor.ask(SendStreamMsg { opts: my_opts }).await??;
while let Some(chunk) = stream.next().await { /* 逐块处理 */ }
let chunks = stream.take_chunks(); // 取出原始 chunk 自行处理
// 5. 读取全部消息
let all: Vec<_> = actor.ask(MessagesMsg).await?;Structs§
- Agent
Context - LLM 对话上下文管理器，kameo Actor。
- Agent
Send Stream - 流式对话的 Stream 返回类型。
- Append
Msg - 追加一条消息到 incremental 区末尾。Reply =
()。 - Clear
Msg - 清空整个 incremental 区。Reply =
()。 - Common
Opts - 请求级公共配置，内嵌于各后端的 Opts 类型。
- Compress
Msg - 触发上下文压缩。Reply =
Result<(), AgentError>。 - Compressed
Msg - 获取 compressed 区的消息副本。Reply =
Vec<Message>。 - Estimate
Tokens Msg - 估算三区全部消息的 token 数量。Reply =
usize。 - Extend
Msg - 批量追加消息到 incremental 区。Reply =
()。 - Find
ByRole Msg - 按角色筛选三区全部消息。Reply =
Vec<Message>。 - From
Jsonl Msg - 从 JSONL 字符串加载消息到 incremental 区。Reply =
Result<(), AgentError>。 - Get
- 按全局索引获取消息。Reply =
Option<Message>。 - Immutable
Msg - 获取 immutable 区的消息副本。Reply =
Vec<Message>。 - Incremental
Msg - 获取 incremental 区的消息副本。Reply =
Vec<Message>。 - Insert
Msg - 在 incremental 区指定索引插入消息。Reply =
Result<(), AgentError>。 - IsEmpty
- 检查三区是否全部为空。Reply =
bool。 - Len
- 获取三区总消息数。Reply =
usize。 - Messages
Msg - 获取三区全部消息的拼接结果。Reply =
Vec<Message>。 - PopMsg
- 弹出 incremental 区最后一条消息。Reply =
Option<Message>。 - Read
Only - 只读容器：构造后不可变，仅暴露切片访问。
- Remove
Msg - 移除 incremental 区指定索引的消息。Reply =
Result<(), AgentError>。 - Retain
Msg - 按角色保留 incremental 区消息，其余移除。Reply =
()。 - SendMsg
- 非流式对话。Reply =
Result<Response, AgentError>。 - Send
Stream Msg - 流式对话。Reply =
AgentSendStream<B>。 - ToJsonl
Msg - 将三区全部消息导出为 JSONL 字符串，每行一条 JSON。Reply =
Result<String, AgentError>。 - Tool
Call Info - 工具调用信息。从后端 Response 中提取，供 consumer 执行工具并构造 Tool 角色消息。
- Update
Msg - 替换 incremental 区指定索引的消息。Reply =
Result<(), AgentError>。
Enums§
- Agent
Error - Agent 上下文操作错误类型。
- Change
Event - incremental 区的变更事件，通过
with_on_change回调发送。 - Compress
Strategy - 上下文压缩策略。
- Response
Type - 响应内容类型枚举。
- Role
- LLM 对话消息角色，对应 OpenAI/DeepSeek/智谱等 API 的标准消息角色。
- Stream
Event - 流式输出事件，由
ContextBackend::classify_chunk产出。
Traits§
- Context
Backend - 后端 trait：抽象 LLM 后端的完整接口。
- Context
Backend Response - 后端 Response 类型约束，流式/非流式 Response 均需实现。
- Context
Message - 后端消息类型必须实现此 trait。