agent_context/context/events/
inbound.rs

1//! 请求者 → AgentContext 的请求消息与参数。
2//!
3//! 以 `Request` 前缀命名，与 [`super::outbound`] 中的 `Notify` 前缀对应。
4
5use crate::role::Role;
6
7// ---------------------------------------------------------------------------
8// 变更消息
9// ---------------------------------------------------------------------------
10
11/// 追加一条消息到 incremental 区末尾。
12///
13/// 通知所有订阅者 [`super::NotifyChange::Appended`]。
14pub struct RequestAppend<M> {
15    /// 要追加的消息
16    pub message: M,
17}
18
19/// 批量追加消息到 incremental 区。
20///
21/// 每条消息单独通知所有订阅者 [`super::NotifyChange::Appended`]。
22pub struct RequestExtend<M> {
23    /// 要批量追加的消息列表
24    pub messages: Vec<M>,
25}
26
27/// 替换 incremental 区指定索引的消息。
28///
29/// 仅对 incremental 区有效。通知所有订阅者 [`super::NotifyChange::Updated`]。
30pub struct RequestUpdate<M> {
31    /// incremental 区索引
32    pub index: usize,
33    /// 新消息
34    pub message: M,
35}
36
37/// 在 incremental 区指定索引插入消息。
38///
39/// 通知所有订阅者 [`super::NotifyChange::Inserted`]。
40pub struct RequestInsert<M> {
41    /// incremental 区插入位置
42    pub index: usize,
43    /// 要插入的消息
44    pub message: M,
45}
46
47/// 移除 incremental 区指定索引的消息。
48///
49/// 通知所有订阅者 [`super::NotifyChange::Removed`]。
50pub struct RequestRemove {
51    /// incremental 区索引
52    pub index: usize,
53}
54
55/// 弹出 incremental 区最后一条消息。
56///
57/// 通知所有订阅者 [`super::NotifyChange::Popped`]。
58pub struct RequestPop;
59
60/// 按角色保留 incremental 区消息，其余移除。
61///
62/// 通知所有订阅者 [`super::NotifyChange::Retained`]。
63pub struct RequestRetain {
64    /// 要保留的角色
65    pub role: Role,
66}
67
68/// 清空整个 incremental 区。
69///
70/// 通知所有订阅者 [`super::NotifyChange::Cleared`]。
71pub struct RequestClear;
72
73// ---------------------------------------------------------------------------
74// 查询消息
75// ---------------------------------------------------------------------------
76
77/// 获取三区总消息数。
78pub struct RequestLen;
79
80/// 检查三区是否全部为空。
81pub struct RequestIsEmpty;
82
83/// 按全局索引获取消息。
84///
85/// 索引按 immutable → compressed → incremental 顺序计算。越界返回 `None`。
86pub struct RequestGet(pub usize);
87
88/// 获取三区全部消息的拼接结果。
89///
90/// 顺序：immutable → compressed → incremental。
91pub struct RequestMessages;
92
93/// 获取 immutable 区的消息副本。
94pub struct RequestImmutable;
95
96/// 获取 compressed 区的消息副本。
97pub struct RequestCompressed;
98
99/// 获取 incremental 区的消息副本。
100pub struct RequestIncremental;
101
102/// 按角色筛选三区全部消息。
103pub struct RequestFindByRole(pub Role);
104
105// ---------------------------------------------------------------------------
106// 对话消息
107// ---------------------------------------------------------------------------
108
109/// 非流式对话。
110///
111/// 发送前根据 [`crate::CommonOpts`] 检查上下文是否已满，满则自动压缩或返回错误。
112/// 然后拼接三区消息 + scratch，发送给后端 LLM。
113/// 成功后自动将响应消息存入 incremental 区，通知所有订阅者 [`super::NotifyChange::Appended`]。
114pub struct RequestSend<O> {
115    /// 传递给后端 `send()` 的请求选项
116    pub opts: O,
117}
118
119/// 流式对话。
120///
121/// 发送前根据 [`crate::CommonOpts`] 检查上下文是否已满，满则自动压缩或返回错误。
122/// 然后拼接三区消息 + scratch，发送给后端 LLM。
123pub struct RequestSendStream<O> {
124    /// 传递给后端 `send_stream()` 的请求选项
125    pub opts: O,
126}
127
128// ---------------------------------------------------------------------------
129// 压缩消息
130// ---------------------------------------------------------------------------
131
132/// 压缩策略参数。
133#[derive(Debug, Clone)]
134pub enum CompressStrategy {
135    /// 摘要压缩：保留最近 `keep` 条，将更早的消息交由后端 LLM 生成摘要存入 compressed 区。
136    Summarize {
137        /// 保留的最新消息条数
138        keep: usize,
139        /// 自定义摘要提示词，`None` 时使用内置默认提示词
140        prompt: Option<String>,
141    },
142}
143
144/// 触发上下文压缩。
145///
146/// 根据 [`CompressStrategy`] 对 incremental 区执行压缩。
147/// 摘要由后端 LLM 生成，通过 `opts` 传递请求选项。
148/// 也可通过 [`crate::CommonOpts::auto_compress`] 在 [`RequestSend`]/[`RequestSendStream`] 时自动触发。
149pub struct RequestCompress<O> {
150    /// 压缩策略
151    pub strategy: CompressStrategy,
152    /// 传递给后端 `send()` 的请求选项
153    pub opts: O,
154}
155
156// ---------------------------------------------------------------------------
157// 工具消息
158// ---------------------------------------------------------------------------
159
160/// 估算三区全部消息的 token 数量。
161///
162/// 委托给后端的 [`estimate_tokens`](crate::ContextBackend::estimate_tokens)。
163/// 失败时降级返回 0。
164pub struct RequestEstimateTokens;
165
166/// 将三区全部消息导出为 JSONL 字符串，每行一条 JSON。
167///
168/// 消息按 immutable → compressed → incremental 顺序输出。
169pub struct RequestToJsonl;
170
171/// 从 JSONL 字符串加载消息到 incremental 区。
172///
173/// 每行一条 JSON，空行跳过。解析失败或触发 `preserve_reasoning` 时返回错误。
174/// 加载的消息逐条通知所有订阅者 [`super::NotifyChange::Appended`]。
175pub struct RequestFromJsonl {
176    /// JSONL 字符串，每行一条消息
177    pub jsonl: String,
178}
agent_context/context/events/inbound.rs

agent_context/context/events/
inbound.rs
