509 lines
21 KiB
Markdown
509 lines
21 KiB
Markdown
# 上下文压缩 (Context Compaction) — 设计文档
|
||
|
||
> 日期：2026-04-17
|
||
> 范围：NetaClaw 单 Agent 对话场景
|
||
> 参考：Hermes Agent `context_compressor.py`
|
||
|
||
## 1. 目标
|
||
|
||
为 NetaClaw Agent 引擎添加上下文压缩能力，解决长对话撞上下文窗口限制的问题。同时在前端实时显示 token 用量与压缩状态。
|
||
|
||
**非目标（本期不做）**：Crew 子 Agent 压缩、向量检索式记忆召回、多级摘要树、摘要导出/导入、跨会话共享摘要。
|
||
|
||
## 2. 触发机制
|
||
|
||
双模式触发：
|
||
|
||
### 2.1 自动触发（阈值驱动）
|
||
|
||
**架构决策**：压缩逻辑不放在 `runAgent()` 内部（它是纯函数，不持有状态），而是放在 `gateway/server.ts` 的 `handleChat` 流程中，在调用 `runAgent()` 之前执行。这样可以直接访问 Midway DI 容器中的 Service 和 DB 实体。
|
||
|
||
在 `server.ts` 的 `handleChat` 方法中，构建 messages 数组后、调用 `runAgent()` 前插入检查点：
|
||
|
||
```typescript
|
||
// server.ts handleChat 内部
|
||
const estimated = estimateMessagesTokens(messages);
|
||
const ctxMax = getModelMaxTokens(agentConfig.model);
|
||
const thresholdPercent = agentEntity.compactionThresholdPercent ?? 70;
|
||
const threshold = thresholdPercent / 100 * ctxMax;
|
||
const state = this.sessionState.get(sid);
|
||
|
||
if (estimated >= threshold && !state?.compactionInFlight) {
|
||
state.compactionInFlight = true;
|
||
this.send({ type: 'compaction_start', sessionId: sid, reason: 'auto' });
|
||
try {
|
||
const result = await this.compactionService.compress({
|
||
messages, sessionId: sid, agentId, agentEntity,
|
||
});
|
||
messages = result.compressedMessages;
|
||
this.send({ type: 'compaction_done', sessionId: sid, ... });
|
||
} catch (err) {
|
||
this.send({ type: 'compaction_failed', sessionId: sid, error: err.message });
|
||
// 不修改 messages，继续原对话
|
||
} finally {
|
||
state.compactionInFlight = false;
|
||
}
|
||
}
|
||
|
||
// 然后正常调用 runAgent({ agentConfig, tools, userMessage, history: messages, ... })
|
||
```
|
||
|
||
**`compactionInFlight` 存储位置**：存入 `sessionState` Map（与 `thinkLevel`、`todoStore` 同级）。这是连接级互斥（同一 WS 连接内有效）。PM2 多进程下同一用户的 WS 连接固定在一个进程上（Socket.IO sticky session），所以可接受。
|
||
|
||
### 2.2 手动触发（`/compact` 指令）
|
||
|
||
前端输入框识别 `/compact` 前缀，直接 emit WebSocket `compact` 事件。不经过 LLM，不占用工具槽位。网关收到后强制执行压缩流程，无论当前 token 占用多少。
|
||
|
||
**为什么不做成 LLM 工具**：放进 `tools/builtin/` 会占用工具槽位与 system prompt 描述 token，LLM 可能不合时宜地主动调用，增加模型决策负担。放在网关层与输入框前缀指令层，彻底脱离 LLM 视线。
|
||
|
||
## 3. 核心算法（四阶段有损压缩）
|
||
|
||
### 阶段 1：裁剪旧工具结果（零成本预处理）
|
||
|
||
从消息数组末尾反向走，累计 token。当累计 token 超过 `tailTokenBudget`（默认 = 阈值 token x 20%）后，把前面所有 `role=tool` 且内容超过 200 字符的消息内容替换为占位符：`"[旧工具输出已清除以节省上下文]"`。
|
||
|
||
此阶段不调用 LLM。如果只做完这一步 token 已经降到阈值以下，跳过阶段 2/3。
|
||
|
||
### 阶段 2：确定压缩区间边界
|
||
|
||
- `compressStart = protectFirstN`（默认 3，即系统提示 + 首轮用户 + 首轮助手）
|
||
- 向前对齐：若 `compressStart` 落在孤立的 tool 结果上（无对应 assistant tool_call），向后跳一位
|
||
- `compressEnd = findTailCutByTokens(messages, tailTokenBudget)`，从末尾反向累积 token 到预算耗尽为止
|
||
- 硬下限：至少保留 3 条尾部消息
|
||
- 向后对齐：避免切开 `assistant(toolCalls) <-> tool(result)` 配对组
|
||
|
||
### 阶段 3：LLM 摘要中间区间
|
||
|
||
- `middle = messages[compressStart : compressEnd]`
|
||
- `serialized = serializeForSummary(middle)`，每条消息按 `[ROLE] content` 格式序列化，长内容截断为头 4000 字符 + 尾 1500 字符
|
||
- 调用 `AuxiliaryLLMClient.summarize(serialized, previousSummary?)`
|
||
- 摘要 token 预算：`max(2000, min(compressedTokens x 0.20, 12000))`
|
||
- 返回一条 `role=user` 的消息（避免与随后的 assistant 连续同角色），content 前缀固定字符串：`[CONTEXT COMPACTION] 此前若干轮对话已被压缩以节省上下文空间...`
|
||
|
||
### 阶段 4：装配 + 清理孤儿
|
||
|
||
- 新数组：`[...head, summaryMessage, ...tail]`
|
||
- 收集 tail 中所有 `tool_call_id`，与 assistant 消息中的 `toolCalls[].id` 交叉验证
|
||
- 孤儿 tool 结果 -> 删除
|
||
- 孤儿 tool_call -> 补占位 tool 结果 `"[结果来自已压缩的历史 -- 见上方摘要]"`
|
||
|
||
### Token 估算
|
||
|
||
```typescript
|
||
function estimateTokens(message: LLMMessage): number {
|
||
let n = Math.floor(message.content.length / 4) + 10;
|
||
for (const tc of message.toolCalls ?? []) {
|
||
n += Math.floor((tc.arguments?.length ?? 0) / 4);
|
||
}
|
||
return n;
|
||
}
|
||
```
|
||
|
||
### 迭代压缩
|
||
|
||
第二次及以后的压缩：从 DB 读取当前会话最近的 `is_compaction_summary=true` 消息作为 `previousSummary`，传给 auxiliary model，prompt 切换为"更新版"模板，保留仍相关的旧摘要内容并合并新轮次。
|
||
|
||
### 摘要 Prompt 模板
|
||
|
||
**首次压缩**：
|
||
|
||
```
|
||
为后续助手创建一份结构化的交接摘要，以便在早期对话被压缩后继续工作。
|
||
|
||
待摘要轮次：
|
||
{serialized_conversation}
|
||
|
||
请使用以下结构：
|
||
|
||
## 目标
|
||
[用户想达成什么]
|
||
|
||
## 约束与偏好
|
||
[用户偏好、编码风格、约束、重要决策]
|
||
|
||
## 进度
|
||
### 已完成
|
||
[完成的工作 -- 包含具体文件路径、运行的命令、获得的结果]
|
||
### 进行中
|
||
[当前正在进行的工作]
|
||
### 受阻
|
||
[遇到的阻碍或问题]
|
||
|
||
## 关键决策
|
||
[重要的技术决策及原因]
|
||
|
||
## 相关文件
|
||
[读取、修改或创建的文件 -- 每个简要说明]
|
||
|
||
## 下一步
|
||
[需要做什么以继续工作]
|
||
|
||
## 关键上下文
|
||
[任何具体的值、错误消息、配置细节、或没有显式保留就会丢失的数据]
|
||
|
||
## 工具与模式
|
||
[使用了哪些工具、如何高效使用、任何工具特定的发现]
|
||
|
||
目标 ~{summary_budget} tokens。要具体，包含文件路径、命令输出、错误消息、具体值。
|
||
仅写摘要正文，不要任何前缀或开场白。
|
||
```
|
||
|
||
**迭代更新**：
|
||
|
||
```
|
||
你正在更新一份上下文压缩摘要。下方是上次压缩生成的摘要，自那以后产生了新的对话轮次需要合并。
|
||
|
||
之前的摘要：
|
||
{previous_summary}
|
||
|
||
待合并的新轮次：
|
||
{serialized_new_turns}
|
||
|
||
使用同样的结构更新。保留所有仍相关的现有信息，添加新进度，把"进行中"的项移到"已完成"，仅当明显过时时才移除信息。
|
||
|
||
[同上结构]
|
||
|
||
目标 ~{summary_budget} tokens。
|
||
```
|
||
|
||
### 关键参数
|
||
|
||
| 参数 | 默认 | 说明 |
|
||
|---|---|---|
|
||
| `thresholdPercent` | 70 | 触发压缩的上下文占比 |
|
||
| `protectFirstN` | 3 | 保护的头部消息数 |
|
||
| `tailTokenBudgetRatio` | 0.20 | 尾部预算占阈值 token 的比例 |
|
||
| `summaryMinTokens` | 2000 | 摘要最小输出 token |
|
||
| `summaryMaxTokens` | 12000 | 摘要最大输出 token |
|
||
| `summaryRatio` | 0.20 | 摘要目标为被压缩内容的 20% |
|
||
| `charsPerToken` | 4 | token 估算系数 |
|
||
|
||
## 4. 辅助模型
|
||
|
||
### 4.1 配置分层
|
||
|
||
1. **模型渠道管理页扩展** -- `model_channel` 表新增 `isAuxiliary` 标记字段（boolean, default false）
|
||
2. **系统默认辅助渠道** -- `dict_type` + `dict_info` 字典系统新增 `netaclaw.default_auxiliary_channel_id`
|
||
3. **Agent 级覆盖** -- `netaclaw_agent.auxiliary_model_channel_id`：为空 = 使用系统默认
|
||
4. **解析优先级**：`Agent.auxiliaryModelChannelId -> dict_info(netaclaw.default_auxiliary_channel_id) -> 抛 "未配置辅助模型" 错误`
|
||
|
||
### 4.2 接口
|
||
|
||
`AuxiliaryLLMClient` 作为 Midway `@Provide()` Service 实现（非纯函数），通过 `@Inject()` 获取 `channelService` 和字典 Service 来解析渠道配置：
|
||
|
||
```typescript
|
||
@Provide()
|
||
export class AuxiliaryLLMClient {
|
||
@Inject()
|
||
channelService: NetaClawModelChannelService;
|
||
|
||
@InjectEntityModel(DictInfoEntity)
|
||
dictInfoRepo: Repository<DictInfoEntity>;
|
||
|
||
async resolveChannel(agentId: number): Promise<ModelChannelConfig> { ... }
|
||
|
||
async summarize(params: {
|
||
agentId: number;
|
||
serialized: string;
|
||
previousSummary?: string;
|
||
summaryBudget: number;
|
||
}): Promise<{ summary: string; usage: { input: number; output: number } }>
|
||
}
|
||
```
|
||
|
||
在 `server.ts` 中通过 `@Inject() auxiliaryClient: AuxiliaryLLMClient` 注入，传给 `CompactionService`。
|
||
|
||
- 内部复用现有 `LLMProvider` 接口（Anthropic/OpenAI/DeepSeek）
|
||
- `thinking` 固定为 `off`（摘要不需要推理）
|
||
- `temperature` 固定为 0.3（摘要要稳定）
|
||
|
||
## 5. 数据库变更
|
||
|
||
### 5.1 `netaclaw_message` 新增字段
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|---|---|---|
|
||
| `compactedAt` | datetime nullable | 该消息被压缩的时刻 |
|
||
| `compactedIntoId` | int nullable | 关联的摘要消息 ID |
|
||
| `isCompactionSummary` | boolean default false | 标记该消息本身就是摘要 |
|
||
|
||
索引：`(sessionId, compactedAt)`、`(sessionId, isCompactionSummary)`
|
||
|
||
### 5.5 压缩后 DB 回写流程（新增 `SessionService.applyCompaction()`）
|
||
|
||
压缩完成后需要在事务中执行以下操作：
|
||
|
||
```typescript
|
||
// SessionService 新增方法
|
||
async applyCompaction(params: {
|
||
sessionId: string;
|
||
compressedMessageIds: number[]; // 被压缩的原始消息 ID 列表
|
||
summaryContent: string; // 摘要文本
|
||
}): Promise<{ summaryMessageId: number }> {
|
||
return this.entityManager.transaction(async (manager) => {
|
||
// 1. INSERT 摘要消息
|
||
const summary = await manager.save(NetaClawMessageEntity, {
|
||
sessionId: params.sessionId,
|
||
role: 'user',
|
||
content: params.summaryContent,
|
||
isCompactionSummary: true,
|
||
});
|
||
// 2. 批量 UPDATE 被压缩消息
|
||
await manager.update(NetaClawMessageEntity,
|
||
{ id: In(params.compressedMessageIds) },
|
||
{ compactedAt: new Date(), compactedIntoId: summary.id },
|
||
);
|
||
return { summaryMessageId: summary.id };
|
||
});
|
||
}
|
||
```
|
||
|
||
**前提**：`loadHistory()` 返回值需要包含消息 `id` 字段。当前返回 `LLMMessage[]` 不含 `id`，需要扩展为 `LLMMessageWithId`（新增 `id: number` 字段），或在 `loadHistory` 内部维护 `id -> LLMMessage` 的映射。
|
||
|
||
### 5.2 `netaclaw_agent` 新增字段
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|---|---|---|
|
||
| `auxiliaryModelChannelId` | int nullable | 辅助模型渠道 ID |
|
||
| `compactionStrategy` | varchar(32) default 'lossy' | 枚举，一期仅 `lossy` |
|
||
| `compactionThresholdPercent` | int default 70 | 触发阈值百分比 |
|
||
| `compactionProtectFirstN` | int default 3 | 保护头部消息数 |
|
||
|
||
### 5.3 `model_channel` 新增字段
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|---|---|---|
|
||
| `isAuxiliary` | boolean default false | 是否可作为辅助模型渠道 |
|
||
|
||
### 5.4 字典表新增条目
|
||
|
||
使用项目现有的 `dict_type` + `dict_info` 字典系统（位于 `modules/dict/entity/`）：
|
||
|
||
1. 在 `dict_type` 表新增一条：`name='NetaClaw配置', key='netaclaw'`
|
||
2. 在 `dict_info` 表新增一条：`typeId=<上面的id>, name='default_auxiliary_channel_id', value='<channel_id>'`
|
||
|
||
## 6. WebSocket 协议扩展
|
||
|
||
```typescript
|
||
// Client -> Server
|
||
| { type: 'compact'; sessionId: string }
|
||
|
||
// Server -> Client
|
||
| { type: 'compaction_start'; sessionId: string; reason: 'manual' | 'auto' }
|
||
| { type: 'compaction_done'; sessionId: string;
|
||
removedCount: number; summaryMessageId: number;
|
||
tokensBefore: number; tokensAfter: number }
|
||
| { type: 'compaction_failed'; sessionId: string; error: string }
|
||
| { type: 'token_update'; sessionId: string;
|
||
current: { inputTokens; outputTokens; totalTokens; apiCalls },
|
||
context: { usedTokens; maxTokens; percent; thresholdPercent; estimated: true } }
|
||
```
|
||
|
||
注意：
|
||
- `context.thresholdPercent` 为新增字段，前端用于绘制阈值刻度线
|
||
- `context.estimated: true` 标记 `usedTokens` 是估算值（非精确 tokenizer 计数）
|
||
- **token 估算系数统一为 `1/4`**（即 `charsPerToken=4`）。现有 `server.ts` 第 322 行使用 `1/3`，需同步修改为 `1/4` 以保持一致
|
||
|
||
## 7. 消息历史加载变化
|
||
|
||
`SessionService.loadHistory(sessionId, options)` 新增 `options`：
|
||
|
||
```typescript
|
||
{ view: 'compacted' | 'full' } // 默认 compacted
|
||
```
|
||
|
||
- `compacted` 模式：过滤掉 `compactedAt IS NOT NULL` 的消息，保留摘要消息
|
||
- `full` 模式：返回全量消息（含原始被压缩的消息和摘要消息，按 createTime 排序）
|
||
|
||
**送给 LLM 的 messages 永远走 `compacted` 模式**，前端"查看完整历史"按钮才切 `full`。
|
||
|
||
**返回类型变更**：当前 `loadHistory` 返回 `LLMMessage[]`（不含 `id`）。压缩需要消息 ID 来标记被压缩的消息。新增 `LLMMessageWithId` 类型：
|
||
|
||
```typescript
|
||
export interface LLMMessageWithId extends LLMMessage {
|
||
id: number;
|
||
}
|
||
```
|
||
|
||
`loadHistory` 内部返回 `LLMMessageWithId[]`，但传给 `runAgent` 时仍然只取 `LLMMessage` 部分（向后兼容）。
|
||
|
||
**需要同步修改的调用处**：
|
||
- `server.ts` 第 115 行：`const history = await this.sessionService.loadHistory(sid)` -> 传入 view 参数
|
||
- 前端 `store/chat.ts` 中 `loadMessages()` 调用的 HTTP 端点（如有）
|
||
|
||
### 7.1 需要修改的类型定义文件清单
|
||
|
||
新增 WebSocket 事件类型需要同步更新以下文件：
|
||
|
||
| 文件 | 修改内容 |
|
||
|---|---|
|
||
| `backend gateway/protocol.ts` | `ClientMessage` 联合类型新增 `compact`；`ServerEvent` 联合类型新增 `compaction_start/done/failed`；`ServerTokenUpdateEvent.context` 新增 `thresholdPercent` 和 `estimated` |
|
||
| `backend gateway/server.ts` | `onMessage` switch 新增 `compact` 分支；`sessionState` Map 类型新增 `compactionInFlight` |
|
||
| `frontend types/index.d.ts` | `TokenUpdateEvent.context` 新增 `thresholdPercent`；新增 `CompactionStartEvent/DoneEvent/FailedEvent` 类型 |
|
||
| `frontend store/chat.ts` | `handleWSEvent` switch 新增 `compaction_start/done/failed` 分支；新增 `compactionState` 响应式状态 |
|
||
| `frontend hooks/websocket.ts` | 注册 `compaction_*` 事件回调 |
|
||
|
||
## 8. 前端 UI
|
||
|
||
### 8.1 底部进度条式 Token 显示
|
||
|
||
聊天界面底部工具栏新增横跨整个宽度的极细进度条（高度 3px），位于输入框上方。
|
||
|
||
**进度条视觉规则**：
|
||
- 0 -- threshold：绿色 `#67C23A`
|
||
- threshold -- 90%：橙色 `#E6A23C`
|
||
- 90% -- 100%：红色 `#F56C6C`，细微脉冲动画
|
||
- 阈值刻度线：进度条上以一条竖向细线标记（深灰 1px），悬停显示"自动压缩阈值 70%"
|
||
- 压缩进行中：进度条变为蓝色渐变动画，状态行显示"正在压缩上下文..."
|
||
|
||
**状态行**：
|
||
- 左：`{used}/{max} tokens . 阈值 {threshold}% . 已压缩 {count} 次`，悬停显示输入/输出/工具 token 分解
|
||
- 右：`[/compact]` 按钮，点击触发手动压缩
|
||
|
||
### 8.2 输入框斜杠命令识别
|
||
|
||
```typescript
|
||
const raw = inputText.value.trim();
|
||
if (raw === '/compact') {
|
||
socket.emit('compact', { sessionId });
|
||
inputText.value = '';
|
||
return;
|
||
}
|
||
```
|
||
|
||
封装为 `parseSlashCommand(raw)`，预留扩展。
|
||
|
||
### 8.3 压缩过程消息流视觉反馈
|
||
|
||
- `compaction_start` -> 末尾插入"正在压缩上下文..."气泡
|
||
- `compaction_done` -> 替换为"上下文已压缩 . 移除 N 条消息 . 节省 XX% token [查看摘要]"
|
||
- `compaction_failed` -> "压缩失败：{error} 可继续原对话或 [开新对话]"
|
||
|
||
点击 `[查看摘要]` 弹出 drawer 显示摘要内容（Markdown 渲染）。
|
||
|
||
这些气泡入库为 `role=system, metadata.systemType='compaction_event'` 记录，刷新可见历史压缩事件。
|
||
|
||
### 8.4 历史视图切换
|
||
|
||
左侧会话列表每个已压缩会话项右侧增加"完整/压缩"切换图标。切换后调用 `loadHistory(sid, { view })` 重拉取。
|
||
|
||
完整视图时，消息列表上方显示 sticky 提示条："当前显示完整历史（含已压缩消息）. [切换回压缩视图]"。
|
||
|
||
### 8.5 Agent 编辑页"上下文压缩"子区域
|
||
|
||
`src/modules/agent/views/agent-edit.vue` 的"模型"Tab 新增：
|
||
- 辅助模型：下拉（继承全局默认 / 渠道列表，仅 isAuxiliary=true）
|
||
- 压缩策略：下拉（当前仅 lossy，灰色提示"更多策略开发中"）
|
||
- 触发阈值：滑块 30%-95%，步进 5%，默认 70%
|
||
- 保护头部：数字输入 1-10，默认 3
|
||
|
||
留空 = 继承系统级配置。
|
||
|
||
### 8.6 模型管理页扩展
|
||
|
||
渠道编辑表单新增 checkbox：`可作为辅助模型`。勾选后该渠道出现在 Agent 编辑页"辅助模型"下拉中。
|
||
|
||
## 9. 错误处理
|
||
|
||
| 错误场景 | 处理策略 |
|
||
|---|---|
|
||
| 辅助模型渠道未配置 | emit `compaction_failed` with `reason='no_auxiliary_model'`，前端提示 |
|
||
| 辅助模型 API 超时/5xx | 不修改 messages，emit 失败，原对话可继续 |
|
||
| 摘要返回空字符串/异常短（<200字符） | 视为失败 |
|
||
| 压缩中用户发新消息 | `compactionInFlight=true` 时排队等待 |
|
||
| 并发自动 + 手动触发 | session 级互斥锁，后来者跳过 |
|
||
| DB 写摘要失败 | 回滚内存 messages，emit 失败 |
|
||
|
||
## 10. 边界场景
|
||
|
||
- **首次对话，消息数 < `protectFirstN`**：永远不触发
|
||
- **整体小但单条超长**（如粘贴 10 万字符文档）：阶段 1/2 不生效，跳过压缩，UI 告警"建议拆分"
|
||
- **模型切换导致 `ctxMax` 突变**（200k -> 64k）：下次 LLM 调用前若已超标，立即触发自动压缩
|
||
- **系统提示本身就超阈值**：抛"系统提示过长"错误，引导精简
|
||
|
||
## 11. 测试策略
|
||
|
||
### 单元测试（Jest，后端）
|
||
|
||
1. `estimateTokens` 边界值断言
|
||
2. `ContextCompressor.compress` 纯函数：消息数组、保护边界、孤儿处理、迭代摘要
|
||
3. `AuxiliaryLLMClient.resolve` 三种解析路径
|
||
4. 阶段 1 裁剪规则
|
||
5. 阶段 2 边界对齐（不切开 tool_call/result 组）
|
||
|
||
### 集成测试（Jest + 测试数据库 neta_test）
|
||
|
||
1. 完整流程：40 条消息 -> `/compact` -> DB `compactedAt` 写入 -> `loadHistory(compacted)` 减少
|
||
2. `loadHistory(full)` vs `loadHistory(compacted)` 对比
|
||
3. 迭代压缩：第二次的 prompt 含 previousSummary
|
||
|
||
### 端到端验证（手动清单，写入 feature_list.json）
|
||
|
||
- 单 Agent 连续发消息到 80% -> 观察自动压缩动画
|
||
- 任意节点输入 `/compact` -> 观察手动流程
|
||
- 压缩后继续，验证 Agent 记得 Goal 与文件路径
|
||
- 切换会话视图（压缩/完整）
|
||
- 配置无效渠道 -> 验证失败提示
|
||
- 辅助模型欠费模拟 -> 验证错误路径
|
||
- 压缩中输入新消息 -> 验证排队
|
||
|
||
## 12. 实施里程碑（三个 PR 粒度）
|
||
|
||
### PR 1 -- 后端核心
|
||
- DB 迁移（`netaclaw_message` + `netaclaw_agent` + `model_channel` 字段）
|
||
- `ContextCompressor` + `AuxiliaryLLMClient` + Token 估算
|
||
- 集成到 `runtime/agent.ts`（自动触发）
|
||
- 单元测试
|
||
|
||
### PR 2 -- 网关与协议
|
||
- WebSocket `compact` / `compaction_*` / `token_update` 事件
|
||
- `SessionService.loadHistory({ view })`
|
||
- 手动触发流程
|
||
- 集成测试
|
||
|
||
### PR 3 -- 前端 UI
|
||
- `token-stats.vue` 进度条化
|
||
- `/compact` 前缀识别 + 斜杠命令解析器
|
||
- 压缩过程消息气泡 + 摘要 drawer
|
||
- 会话视图切换按钮
|
||
- Agent 编辑页"上下文压缩"子区域
|
||
- 模型渠道页 `isAuxiliary` 勾选
|
||
|
||
## 13. 关键文件参考
|
||
|
||
| 组件 | 文件路径 |
|
||
|---|---|
|
||
| Agent 运行时 | `packages/backend/src/modules/netaclaw/runtime/agent.ts` |
|
||
| ReAct 尝试 | `packages/backend/src/modules/netaclaw/runtime/attempt.ts` |
|
||
| 思考系统 | `packages/backend/src/modules/netaclaw/runtime/thinking.ts` |
|
||
| 模型选择 | `packages/backend/src/modules/netaclaw/runtime/model_selection.ts` |
|
||
| LLM 提供者 | `packages/backend/src/modules/netaclaw/plugins/llm_providers/*.ts` |
|
||
| 会话服务 | `packages/backend/src/modules/netaclaw/gateway/session.ts` |
|
||
| WebSocket 协议 | `packages/backend/src/modules/netaclaw/gateway/protocol.ts` |
|
||
| WebSocket 网关 | `packages/backend/src/modules/netaclaw/gateway/server.ts` |
|
||
| 消息实体 | `packages/backend/src/modules/netaclaw/entity/message.ts` |
|
||
| Agent 实体 | `packages/backend/src/modules/netaclaw/entity/agent.ts` |
|
||
| 模型渠道实体 | `packages/backend/src/modules/netaclaw/entity/model_channel.ts` |
|
||
| 前端聊天页 | `packages/frontend/src/modules/agent/views/chat.vue` |
|
||
| Token 统计组件 | `packages/frontend/src/modules/agent/components/token-stats.vue` |
|
||
| 消息组件 | `packages/frontend/src/modules/agent/components/message-item.vue` |
|
||
| WebSocket Hook | `packages/frontend/src/modules/agent/hooks/websocket.ts` |
|
||
| 聊天 Store | `packages/frontend/src/modules/agent/store/chat.ts` |
|
||
| Agent 编辑页 | `packages/frontend/src/modules/agent/views/agent-edit.vue` |
|
||
| 模型渠道页 | `packages/frontend/src/modules/agent/views/model-channel.vue` |
|
||
|
||
## 14. 设计总结
|
||
|
||
| 维度 | 决策 |
|
||
|---|---|
|
||
| 触发 | 手动 `/compact` + 自动阈值双模式 |
|
||
| 算法 | 四阶段有损压缩（裁工具结果 -> 边界 -> LLM 摘要 -> 装配清理孤儿） |
|
||
| 辅助模型 | 全局默认 + Agent 覆盖，通过模型渠道管理 |
|
||
| 压缩策略 | 一期仅 `lossy`，DB 字段预留扩展 |
|
||
| 阈值 | Agent 可配置，系统默认 70% |
|
||
| 持久化 | 入库 + `compactedAt` 标记 + 视图切换 |
|
||
| UI | 底部进度条 + 阈值刻度线 + 压缩事件气泡 + 摘要 drawer |
|
||
| 范围 | 仅单 Agent 场景，Crew 二期做 |
|
||
| 失败 | 不修改历史，用户可继续或开新会话 |
|
||
|