agent_context/context/events/
inbound.rs

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

agent_context/context/events/
inbound.rs
