上下文压缩与历史视图

上下文压缩用于长对话的 token 控制。早期实现更接近在线性消息表上标记 compactedAt 和摘要消息；当前架构下，压缩结果应进入 session-tree-runtime，成为 compaction 节点，并由 active path 决定是否参与模型上下文。

核心目标

控制模型上下文窗口。
保留长会话的可读摘要。
避免切断 assistant/tool 成对消息。
支持前端在历史中展示压缩事件。
与分支、子 Agent 批次、模型切换共享同一会话树。

运行流程

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。

3.7 KiB Raw Blame History Unescape Escape