Compaction UI v2.1.0
用于 OpenClaw 控制界面的内存压缩系统——支持后台执行与 toast 通知、可配置的令牌阈值自动触发、压缩输出中的对话摘要段落、专用设置标签页(含模型选择器)以及结果历史记录。
状态: ✅ 活跃
| 组件 | 状态 |
|---|---|
| 上下文仪表按钮 | ✅ 工作正常 |
| 后台压缩(toast) | ✅ 工作正常 |
| 自动压缩触发器 | ✅ 工作正常 |
| 对话摘要段落 | ✅ 工作正常 |
| 设置标签页(通过插件注册) | ✅ 工作正常 |
| 模型选择器 | ✅ 工作正常 |
| 最后结果存储与查看器 | ✅ 工作正常 |
| 设置持久化与重新加载 | ✅ 工作正常 |
| 授权层级 (OAuth > API > 回退) | ✅ 工作正常 |
| 聊天历史过滤器 | ✅ 工作正常 |
| 完全后台隔离(无聊天干扰) | ✅ 工作正常 |
功能特性
1. 上下文仪表按钮 (app-render.helpers.ts)
聊天工具栏中的一个圆形 SVG 进度环,同时作为手动压缩的触发按钮。
- 位置:
renderChatControls()中的会话选择器下拉菜单之后 - 数据来源:
sessionsResult.sessions[].totalTokens和来自会话行的contextTokens - 颜色: 绿色 (<60%), 黄色 (60-85%), 红色 (≥85%)
- 禁用条件: 利用率低于 20% 或正在进行压缩时
- 工具提示: 显示 "Context: XK / YK tokens (Z%)"
2. 后台压缩(Toast)
点击(或自动触发)后,压缩会在后台运行,使用标准的右下角 toast 通知系统 — 无阻塞模态框。UI 保持完全可交互。
- 运行中 toast: 显示 "内存压缩中" 并带有旋转动画
- 完成 toast: 显示 "压缩完成: XK → YK" 并带有勾选标记(5秒后自动消失)
- 错误 toast: 显示失败信息(5秒后自动消失)
- 使用与所有其他后台进程(cron、知识提取等)一致的
backgroundJobToasts系统
3. 自动压缩
每一次聊天响应(final 事件)之后,UI 会检查令牌使用量是否超过配置的阈值。如果超过:
- 自动触发后台压缩
- toast 显示 "自动压缩中 (X%)" 并带有当前利用率
- 5 分钟防抖机制防止重复触发
- 压缩成功后聊天会自动刷新
- 如果没有任何内容被压缩,toast 会被静默移除
4. 对话摘要段落
每个压缩输出现在都以 ## Conversation Summary 部分开头,位于结构化的 ## Goal 部分之前。这是一个 3-6 句的自然语言段落,用于:
- 描述对话的整体主题
- 解释讨论流程和关键转折点
- 总结对话的进展过程
- 使用过去时态,以叙述性概述的形式编写
实现方式: 通过 compact.ts 将自定义指令注入上游压缩 LLM 调用中。该指令会附加到任何用户提供的自定义指令(来自 /compact [instructions])之前,因此两者可以共存。
输出示例:
## Conversation Summary
对话始于用户请求改进压缩系统,特别是从阻塞式模态框转向后台 toast。讨论随后转向添加带有自动压缩控制的设置标签页。在实现并测试了这些功能后,用户发现设置无法在标签页导航间持久化,这导致了对模块级状态缓存的修复。最后,用户请求在压缩输出中添加一个叙述性摘要段落,以便更好地提供上下文。
## Goal
...
5. 设置标签页(通过插件注册)
一个专用的压缩标签页,位于 Agent 导航组下,通过插件 UI 架构注册。
注册方式: plugins-ui.ts → BUILTIN_UI_VIEWS,其中 id: "compaction",group: "agent",position: 7,icon: "archive"
信息卡片:
自动压缩卡片
- 开关: 启用/禁用自动压缩
- 阈值滑块: 10% 到 95%(默认值: 60%)
- 颜色编码: 绿色 (<60%), 黄色 (60-85%), 红色 (≥85%)
模型卡片
- 下拉菜单: 为压缩选择特定模型,或使用会话默认模型
- 按提供商分组,并显示上下文窗口大小
- 选择自定义模型时的警告标注(API 密钥提醒)
- 回退机制: 如果自定义模型失败,自动回退到会话默认模型
结果存储卡片
- 开关: 选择加入以保存压缩后的摘要文本以供审查
上次压缩卡片
- 压缩前/后: 以两列网格形式显示的大号样式化令牌计数
- 统计信息: 节省的令牌数、缩减百分比、触发器类型、时间戳、会话键
- 查看结果: 可展开的摘要查看器(启用存储时)
- 清除: 重置存储的结果
- 提示: 当存储关闭时,显示 "启用存储结果" 消息
状态管理:
- 模块级状态在一次会话内的多次渲染中保持持久化
- 每次访问设置标签页时,设置都会从后端重新加载(2 秒过期阈值)
- 导出
resetCompactionSettingsState()供测试和标签页切换使用
6. 授权层级
压缩通过 getApiKeyForModel 使用 resolveApiKeyForProvider — 与聊天相同的授权链:
OAuth → API 密钥 → 回退
无需单独配置。如果 OAuth(Claude Max)被配置为主要认证配置文件,压缩会自动使用它。自定义模型选择会独立地使用相同的授权链。
7. 结果存储
启用后,最新的压缩结果会持久化到 {agentDir}/compaction-config.json:
{
"settings": {
"autoEnabled": true,
"autoThresholdPercent": 60,
"storeLastResult": true,
"compactionModel": "anthropic/claude-sonnet-4-6"
},
"lastResult": {
"timestamp": 1709283600000,
"trigger": "manual",
"tokensBefore": 50614,
"tokensAfter": 4766,
"tokensSaved": 45848,
"percentReduction": 91,
"sessionKey": "agent:main:main",
"summary": "## Conversation Summary\n对话重点围绕...\n\n## Goal\n..."
}
}
当存储被禁用时,元数据(时间戳、令牌计数)仍会被保存,但摘要文本会被省略。
8. 聊天历史过滤器
- NO_REPLY/HEARTBEAT_OK 过滤: 跳过内容完全为这些文本的助手消息
- 压缩分隔线: 为
__openclaw.kind === "compaction"的消息渲染带标签的分隔线
架构
后端 RPC
| 方法 | 描述 |
|---|---|
sessions.compact | 执行压缩(完成后记录结果) |
compaction.getSettings | 从配置文件读取设置 |
compaction.saveSettings | 更新设置(阈值自动限制在 10-95% 范围内) |
compaction.getLastResult | 获取存储的上次压缩结果 |
compaction.clearLastResult | 清除存储的结果 |
修改的文件
| 文件 | 用途 |
|---|---|
src/gateway/server-methods/compaction.ts | 设置 RPC、配置文件 I/O、结果记录 |
src/gateway/server-methods/sessions.ts | sessions.compact RPC(压缩后记录结果) |
src/gateway/server-methods/plugins-ui.ts | 插件视图注册 |
src/gateway/server-methods.ts | 处理器连线 |
src/gateway/server-methods-list.ts | 方法注册 |
src/gateway/method-scopes.ts | 作用域注册 |
src/agents/pi-embedded-runner/compact.ts | 聊天摘要指令注入 |
ui/src/ui/app-render.helpers.ts | 上下文仪表 + 后台 toast 触发器 |
ui/src/ui/app-gateway.ts | 最终事件后的自动压缩检查 |
ui/src/ui/views/compaction-settings.ts | 设置标签页视图 |
ui/src/ui/app-render.ts | 视图连线 + 导入 |
ui/src/ui/views/chat.ts | 聊天历史过滤器 |
配置文件
{agentDir}/compaction-config.json — 每个 Agent 一个,首次保存设置时创建。
插件注册
压缩标签页在 plugins-ui.ts 中作为内置插件视图注册:
{
id: "compaction",
label: "Compaction",
subtitle: "Memory Management",
icon: "archive",
group: "agent",
position: 7,
pluginId: "compaction-ui",
}
已知问题
- 设置未在标签页访问之间持久化: 已在 v2.1.0 中修复。模块级别的
_state.loaded标志阻止了重新加载。现在,重新进入标签页时每 2 秒重新加载一次。 - 模型选择器需要 API 密钥: 如果您选择了自定义模型,请确保已配置该提供商的 API 密钥。UI 会显示一个警告标注。
- 压缩模型格式: 必须为
"provider/model"格式(例如"anthropic/claude-sonnet-4-6")。无效格式会被静默忽略,并回退到会话默认模型。 - parentId skip-set 传播必须仅限消息: 在从
readSessionMessages过滤内存清除消息时,跳过集必须仅通过包含message字段的条目传播。非消息协议条目 (type:"custom") 桥接了逻辑轮次之间的间隙 —— 如果它们的 ID 进入跳过集,则整个剩余对话都会被隐藏。修复方法是:仅检查parsed?.message条目是否在跳过集中,并仅将它们的 ID 添加到跳过集中。 - 绝无阻塞模态框:
app-render.helpers.ts中的仪表按钮绝不能渲染全屏覆盖模态框。压缩是一个后台进程;所有状态都通过右下角的 toast 系统进行通信。移除任何以compactState.phase为条件的position:fixed; inset:0覆盖层。按钮可以在运行时显示旋转图标,但绝不能阻塞 UI。
变更日志
v2.1.0
- 对话摘要段落: 压缩输出现在以叙述性段落
## Conversation Summary开头,位于结构化部分之前 - 模型选择器: 为压缩选择特定模型或使用会话默认模型,提供按提供商分组的下拉菜单
- 设置重新加载修复: 标签页现在每 2 秒从后端重新加载设置,而不是永久缓存
- 更新的参考文件: 将
references/与当前源代码同步
v2.0.0
- 后台压缩: 用后台任务 toast 替换了阻塞式全屏模态框
- 自动压缩: 在聊天响应后,当令牌使用量超过阈值时触发(可配置,默认 60%,5 分钟防抖)
- 设置标签页: 通过插件注册的压缩标签页,位于 Agent 导航组下
- 结果记录:
sessions.compact记录压缩前后的令牌计数和可选的摘要 - 授权层级: 与聊天相同的 OAuth → API → 回退链
- 设置 RPC:
compaction.getSettings、compaction.saveSettings、compaction.getLastResult、compaction.clearLastResult
v1.0.0
- 初始发布:上下文仪表按钮、带有动画阶段的阻塞式模态框、带 LLM 摘要功能的
sessions.compactRPC、聊天历史 NO_REPLY/HEARTBEAT_OK 过滤、压缩分隔线