agent_context/

lib.rs

//! # agent-context
//!
//! 通用、后端无关的 LLM 对话上下文管理器，基于 [kameo](https://crates.io/crates/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`](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`](ContextBackend::extract_messages)
//! - **模型对话**：[`send`](ContextBackend::send)、[`send_stream`](ContextBackend::send_stream)、[`estimate_tokens`](ContextBackend::estimate_tokens)
//!
//! 实现 `ContextBackend` 即可让 AC 支持任意 LLM 后端（DeepSeek、智谱、OpenAI 等）。
//!
//! ### 变更通知
//!
//! 通过 [`RequestSubscribeChange`] 动态注册订阅者 Actor，接收 [`NotifyChange`] 实时追踪消息变化。
//!
//! ### 上下文压缩
//!
//! [`RequestSend`]/[`RequestSendStream`] 发送前自动检测上下文是否已满。
//! 当 [`CommonOpts::auto_compress`] 为 `true` 时自动压缩；为 `false` 时返回错误。
//! 也可通过 [`RequestCompress`] 手动触发压缩，支持 [`CompressStrategy::Summarize`] 策略。
//! 通过 [`RequestSubscribeCompressed`] 注册压缩结果订阅者，可在压缩后修改摘要与保留消息。
//!
//! ## 快速开始
//!
//! ```ignore
//! use agent_context::{
//!     AgentContext, RequestAppend, RequestSend, RequestSendStream, RequestMessages,
//!     RequestSubscribeChange, ContextBackend, CommonOpts, NotifyChange,
//! };
//! 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);
//! actor.ask(RequestSubscribeChange { recipient: app_ref.recipient() }).await?;
//!
//! // 3. 非流式对话
//! actor.ask(RequestAppend { message: user_msg }).await?;
//! actor.ask(RequestSend { opts: my_opts }).await?;
//!
//! // 4. 流式对话
//! let mut stream = actor.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.ask(RequestAppend { message: m }).await?;
//! }
//!
//! // 5. 读取全部消息
//! let all: Vec<_> = actor.ask(RequestMessages).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, CompressStrategy, CommonOpts, ContextBackend,
    ContextBackendResponse, NotifyChange, NotifyCompressedForReply, RequestAppend, RequestClear,
    RequestCompress, RequestCompressed, RequestEstimateTokens, RequestExtend, RequestFindByRole,
    RequestFromJsonl, RequestGet, RequestImmutable, RequestIncremental, RequestInsert,
    RequestIsEmpty, RequestLen, RequestMessages, RequestPop, RequestRemove, RequestRetain,
    RequestSend, RequestSendStream, RequestSubscribeChange, RequestSubscribeCompressed,
    RequestToJsonl, RequestUnsubscribeChange, RequestUnsubscribeCompressed, RequestUpdate,
    ResponseType, StreamEvent, ToolCallInfo,
};
pub use error::AgentError;
pub use message::ContextMessage;
pub use readonly::ReadOnly;
pub use role::Role;