壓縮 UI v2.1.0
OpenClaw 控制介面的記憶體壓縮系統 — 背景執行並顯示 Toast 通知,可設定 Token 門檻值自動觸發,壓縮輸出包含會話摘要段落,專屬設定分頁含模型選擇器及結果歷史記錄。
狀態:✅ 運作中
| 元件 | 狀態 |
|---|---|
| 上下文儀表按鈕 | ✅ 運作中 |
| 背景壓縮(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: 顯示「Memory Compaction」並附帶旋轉圖示
- 完成 Toast: 顯示「Compacted: XK → YK」並附帶勾號(5 秒後自動消失)
- 錯誤 Toast: 顯示失敗訊息(5 秒後自動消失)
- 使用與所有其他背景程序(cron、知識萃取等)一致的
backgroundJobToasts系統
3. 自動壓縮
每次聊天回應後(final 事件),UI 會檢查 Token 用量是否超過設定的門檻值。若超過:
- 自動觸發背景壓縮
- Toast 顯示「Auto-Compacting (X%)」及目前使用率
- 5 分鐘防抖機制避免重複觸發
- 壓縮成功後聊天會自動重新整理
- 若未壓縮任何內容則靜默移除 Toast
4. 會話摘要段落
每次壓縮輸出現在都會以 ## Conversation Summary 段落開頭,位於結構化的 ## Goal 段落之前。這是一個 3-6 句的自然語言段落,其功能為:
- 描述會話的整體主題
- 說明討論流程與關鍵轉折
- 總結會話的進展方式
- 以過去式敘述方式呈現
實作方式: 透過 compact.ts 將自訂指令注入上游壓縮 LLM 呼叫中。該指令會預先添加到使用者提供的自訂指令(來自 /compact [instructions])之前,因此兩者會共存。
輸出範例:
## Conversation Summary
The conversation began with the user requesting improvements to the compaction
system, specifically moving from a blocking modal to background toasts. Discussion
then shifted to adding a settings tab with auto-compaction controls. After
implementing and testing those features, the user noticed settings weren't
persisting across tab navigations, which led to a fix for the module-level
state cache. Finally, the user requested adding a narrative summary paragraph
to the compaction output for better context.
## Goal
...
5. 設定分頁(插件註冊)
位於 Agent 導航群組下的專屬 Compaction 分頁,透過 Plugin UI 架構註冊。
註冊方式: plugins-ui.ts → BUILTIN_UI_VIEWS,包含 id: "compaction"、group: "agent"、position: 7、icon: "archive"
卡片:
自動壓縮卡片
- 開關: 啟用/停用自動壓縮
- 門檻滑桿: 10% 到 95%(預設:60%)
- 顏色標示: 綠色 (<60%)、黃色 (60-85%)、紅色 (≥85%)
模型卡片
- 下拉選單: 選擇壓縮專用模型,或使用工作階段預設模型
- 按提供商分組,並顯示上下文視窗大小
- 自訂模型時顯示警告提示(API 金鑰提醒)
- 備援機制: 若自訂模型失敗,會自動回退到工作階段預設模型
結果儲存卡片
- 開關: 選擇是否儲存壓縮後的摘要文字以供檢視
上次壓縮卡片
- 壓縮前/後: 以 2 欄網格顯示大型格式化 Token 計數
- 統計資料: 節省 Token 數、減少百分比、觸發類型、時間戳記、工作階段金鑰
- 檢視結果: 可展開的摘要檢視器(當儲存功能啟用時)
- 清除: 重設儲存的結果
- 提示: 當儲存功能關閉時顯示「啟用儲存結果」訊息
狀態管理:
- 模組層級狀態在同一個工作階段內跨重新渲染保持不變
- 每次進入設定分頁時都會從後端重新載入設定(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\nThe conversation focused on...\n\n## Goal\n..."
}
}
當儲存功能停用時,仍會儲存中繼資料(時間戳記、Token 計數),但會省略摘要文字。
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 | Handler 接線 |
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 — 每個代理程式獨立,首次儲存設定時建立。
插件註冊
壓縮分頁在 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
- 自動壓縮: 聊天回應後 Token 用量超過門檻值時自動觸發(可設定,預設 60%,5 分鐘防抖)
- 設定分頁: 插件註冊的 Compaction 分頁,位於 Agent 導航群組下
- 結果記錄:
sessions.compact記錄壓縮前後的 Token 計數與可選摘要 - 驗證層級: 與聊天相同的 OAuth → API → 備用金鑰鏈
- 設定 RPC:
compaction.getSettings、compaction.saveSettings、compaction.getLastResult、compaction.clearLastResult
v1.0.0
- 初始發行:上下文儀表按鈕、附帶動畫階段的阻擋式彈窗、具 LLM 摘要功能的
sessions.compactRPC、聊天歷史 NO_REPLY/HEARTBEAT_OK 過濾、壓縮分隔線