agent_context/

lib.rs

//! # agent-context
//!
//! 通用、后端无关的 LLM 对话上下文管理器，基于 [kameo](https://crates.io/crates/kameo) Actor 模型构建。
//!
//! ## 核心概念
//!
//! ### 三区 + Scratch 消息模型
//!
//! 上下文消息按可变性分为三个存储区域，加上一个不存储的 Scratch 层，按序拼接为完整对话：
//!
//! | 区域 | 容器 | 可变性 | 用途 |
//! |------|------|--------|------|
//! | **immutable** | [`ReadOnly`] | 不可变 | 系统提示词、预设上下文等构造后不变的消息 |
//! | **compressed** | `Vec` | 仅压缩时写入 | 历史对话压缩后的摘要 |
//! | **incremental** | `Vec` | 完全可变 | 当前活跃对话，支持增删改查 |
//! | **scratch** | — | 不存储 | 每轮刷新的临时元数据（时间、工作目录等），通过 [`ScratchOpts`] 配置 |
//!
//! 拼接顺序：immutable → compressed → incremental → scratch（如有）。
//! Scratch 由调用方在每次 [`SendMsg`]/[`SendStreamMsg`] 时通过 Opts 传入，
//! 不存入任何区域，不触发变更事件，不参与序列化。
//!
//! ### 后端 trait
//!
//! [`ContextBackend`] 是核心抽象，封装 LLM 后端的：
//!
//! - **消息工厂**：[`user_message`](ContextBackend::user_message)、[`system_message`](ContextBackend::system_message)、[`tool_message`](ContextBackend::tool_message)
//! - **格式转换**：[`to_system_message`](ContextBackend::to_system_message)、[`to_request_messages`](ContextBackend::to_request_messages)
//! - **响应解析**：[`extract_messages_from_backend_response`](ContextBackend::extract_messages_from_backend_response)
//! - **模型对话**：[`send`](ContextBackend::send)、[`send_stream`](ContextBackend::send_stream)、[`estimate_tokens`](ContextBackend::estimate_tokens)
//! - **配置信息**：[`context_window`](ContextBackend::context_window)
//!
//! 实现 `ContextBackend` 即可让 AC 支持任意 LLM 后端（DeepSeek、智谱、OpenAI 等）。
//!
//! ### 变更通知
//!
//! 通过 [`with_on_change`](AgentContext::with_on_change) 注册回调，监听 [`ChangeEvent`] 实时追踪消息变化。
//!
//! ### 上下文压缩
//!
//! 当对话过长时，通过 [`CompressMsg`] 触发压缩。支持 [`CompressStrategy::Summarize`] 策略：保留最近 N 条，
//! 将更早的消息交由后端 LLM 生成摘要存入 compressed 区。
//!
//! ## 快速开始
//!
//! ```ignore
//! use agent_context::{AgentContext, AppendMsg, SendMsg, MessagesMsg, ContextBackend, ScratchOpts};
//!
//! // 1. 实现 ContextBackend（以你的 LLM SDK 类型）+ ScratchOpts
//! // 2. 创建 Actor
//! let ctx = AgentContext::new(my_backend, vec![backend.system_message("You are a helpful assistant.")]);
//! let actor = AgentContext::spawn(ctx);
//!
//! // 3. 发送消息（scratch 通过 opts 传入）
//! actor.ask(AppendMsg { message: user_msg }).await?;
//! actor.ask(SendMsg { opts: my_opts }).await?;
//!
//! // 4. 读取全部消息
//! let all: Vec<_> = actor.ask(MessagesMsg).await?;
//! ```

#![forbid(
    unused_must_use,
    clippy::panic,
    clippy::let_underscore_must_use,
    clippy::disallowed_types,
    clippy::disallowed_methods,
    clippy::allow_attributes,
    unfulfilled_lint_expectations
)]
#![deny(clippy::unwrap_used, clippy::expect_used)]

mod context;
mod error;
mod message;
mod readonly;
mod role;

pub use context::{
    AgentContext, AgentSendStream, AppendMsg, ChangeEvent, ClearMsg, CompressMsg, CompressStrategy,
    CompressedMsg, ContextBackend, ContextBackendResponse, EstimateTokensMsg, ExtendMsg,
    FindByRoleMsg, FromJsonlMsg, Get, ImmutableMsg, IncrementalMsg, InsertMsg, IsEmpty, IsFullMsg,
    Len, MessagesMsg, PopMsg, RemoveMsg, ResponseType, RetainMsg, ScratchOpts, SendMsg,
    SendStreamMsg, SilentAppendMsg, StreamEvent, ToJsonlMsg, ToolCallInfo, UpdateMsg,
};
pub use error::AgentError;
pub use message::ContextMessage;
pub use readonly::ReadOnly;
pub use role::Role;