---
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]]