95 lines
3.7 KiB
Markdown
95 lines
3.7 KiB
Markdown
---
|
||
title: 上下文压缩与历史视图
|
||
created: 2026-04-19
|
||
updated: 2026-04-23
|
||
type: concept
|
||
tags: [runtime, agent, api, backend]
|
||
sources: [packages/backend/src/modules/netaclaw/runtime/compaction.ts, packages/backend/src/modules/netaclaw/session-tree/context_builder.ts, packages/backend/src/modules/netaclaw/session-tree/types.ts, packages/backend/src/modules/netaclaw/service/chat_orchestrator.ts, packages/frontend/src/modules/agent/store/chat.ts, packages/frontend/src/modules/agent/views/chat.vue]
|
||
---
|
||
|
||
# 上下文压缩与历史视图
|
||
|
||
上下文压缩用于长对话的 token 控制。早期实现更接近在线性消息表上标记 `compactedAt` 和摘要消息；当前架构下，压缩结果应进入 [[session-tree-runtime]]，成为 `compaction` 节点，并由 active path 决定是否参与模型上下文。
|
||
|
||
## 核心目标
|
||
|
||
- 控制模型上下文窗口。
|
||
- 保留长会话的可读摘要。
|
||
- 避免切断 assistant/tool 成对消息。
|
||
- 支持前端在历史中展示压缩事件。
|
||
- 与分支、子 Agent 批次、模型切换共享同一会话树。
|
||
|
||
## 运行流程
|
||
|
||
```text
|
||
ChatOrchestrator 准备运行
|
||
-> SessionTreeContextBuilder 读取 active path
|
||
-> 估算上下文 token
|
||
-> 达到阈值时触发 compaction
|
||
-> CompactionService 生成摘要
|
||
-> appendCompaction 写入 session tree
|
||
-> runtimeContext 使用摘要后的上下文
|
||
-> 前端 snapshot/patch 展示 compaction 节点
|
||
```
|
||
|
||
## 与 Session Tree 的关系
|
||
|
||
压缩不应只作为消息 metadata 存在。新的表达方式是：
|
||
|
||
- `compaction` entry 保存摘要、`firstKeptEntryId`、`tokensBefore`、details。
|
||
- `activePath` 决定压缩摘要是否对当前分支生效。
|
||
- `runtimeContext.messages` 由 `context_builder.ts` 构造，负责把压缩节点转成模型可消费消息。
|
||
- 前端 `visibleEntries` 把压缩节点渲染为会话中的结构化提示。
|
||
|
||
这让压缩和分支天然兼容。
|
||
|
||
## 手动与自动触发
|
||
|
||
手动触发仍可通过对话命令或 UI 入口发起。自动触发由 Agent 配置中的上下文阈值控制，运行前由后端判断是否需要压缩。
|
||
|
||
配置页面需要注意：
|
||
|
||
- 压缩阈值是 Agent 运行配置的一部分。
|
||
- 辅助模型配置会影响压缩质量和成本。
|
||
- 压缩结果在刷新后应从 session tree 恢复。
|
||
|
||
当前还要注意一个过渡事实：
|
||
|
||
- legacy `netaclaw_message.compactedAt` 相关逻辑仍存在，主要用于兼容旧历史与压缩服务本身。
|
||
- 但 Agent Chat 的主展示和主恢复路径已经切到 Session Tree，压缩节点应该被理解为 `compaction entry`，不是“数据库里某几条 message 被隐藏了”这么简单。
|
||
|
||
## 前端展示
|
||
|
||
Agent 对话页需要展示：
|
||
|
||
- 压缩开始、完成、失败状态。
|
||
- 摘要内容。
|
||
- 压缩前 token 数和保留边界。
|
||
- 当前是否处于压缩后的 active path。
|
||
|
||
前端不应自行计算“哪些历史已经压缩”，而应依赖后端 snapshot 和 compaction entry。
|
||
|
||
## 与子 Agent 的关系
|
||
|
||
子 Agent 批次也写入会话树，因此压缩时需要明确哪些批次节点进入摘要、哪些仅用于 UI 展示。当前建议：
|
||
|
||
- `subagent_batch` 和 `subagent_result` 可作为可见节点保留。
|
||
- 进入模型上下文时使用其摘要信息，而不是完整工具日志。
|
||
- 压缩摘要应保留子任务结论和影响主任务的关键事实。
|
||
|
||
随着子 Agent 回放投影落地，这里的边界也更清楚：
|
||
|
||
- evidence summary、process replay、tool execution 主要属于 UI/回放层。
|
||
- 真正进入压缩摘要和后续 prompt 的，应该是对主任务有语义价值的结论，而不是完整过程事件。
|
||
|
||
详见 [[subagent-session]]。
|
||
|
||
## 相关页面
|
||
|
||
- [[agent-runtime]]
|
||
- [[session-tree-runtime]]
|
||
- [[subagent-session]]
|
||
- [[frontend-architecture]]
|
||
- [[websocket-gateway]]
|
||
- [[prompt-builder]]
|