agent_context/context/events/
inbound.rs

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

agent_context/context/events/
inbound.rs
