vault backup: 2026-06-09 23:15:17
This commit is contained in:
@@ -1,13 +1,20 @@
|
||||
---
|
||||
tags: [context-collapse, 上下文, 压缩, token, feature-flag]
|
||||
create time: 2026-06-09 22:30
|
||||
---
|
||||
|
||||
# CONTEXT_COLLAPSE — 上下文折叠
|
||||
|
||||
## 概述
|
||||
|
||||
CONTEXT_COLLAPSE 让模型内省上下文窗口使用情况，并智能压缩旧消息。当对话接近上下文限制时，自动将旧消息折叠为压缩摘要，保留关键信息的同时释放 token 空间。
|
||||
|
||||
> [!info]
|
||||
> Feature Flag: `FEATURE_CONTEXT_COLLAPSE=1`
|
||||
> 子 Feature: `FEATURE_HISTORY_SNIP=1`
|
||||
> 实现状态：核心逻辑全部 Stub，布线完整
|
||||
> 引用数：CONTEXT_COLLAPSE 20 + HISTORY_SNIP 16 = 36
|
||||
|
||||
## 一、功能概述
|
||||
|
||||
CONTEXT_COLLAPSE 让模型内省上下文窗口使用情况，并智能压缩旧消息。当对话接近上下文限制时，自动将旧消息折叠为压缩摘要，保留关键信息的同时释放 token 空间。
|
||||
## 正文
|
||||
|
||||
### 子 Feature
|
||||
|
||||
@@ -16,13 +23,13 @@ CONTEXT_COLLAPSE 让模型内省上下文窗口使用情况，并智能压缩旧
|
||||
| `CONTEXT_COLLAPSE` | 上下文折叠引擎（后台 LLM 调用压缩旧消息） |
|
||||
| `HISTORY_SNIP` | SnipTool — 标记消息进行折叠/修剪 |
|
||||
|
||||
## 二、实现架构
|
||||
### 实现架构
|
||||
|
||||
### 2.1 模块状态
|
||||
#### 模块状态
|
||||
|
||||
| 模块 | 文件 | 状态 |
|
||||
|------|------|------|
|
||||
| 折叠核心 | `src/services/contextCollapse/index.ts` | **Stub** — 接口完整（`ContextCollapseStats`、`CollapseResult`、`DrainResult`），函数全部空操作 |
|
||||
| 折叠核心 | `src/services/contextCollapse/index.ts` | **Stub** — 接口完整，函数全部空操作 |
|
||||
| 折叠操作 | `src/services/contextCollapse/operations.ts` | **Stub** — `projectView` 为恒等函数 |
|
||||
| 折叠持久化 | `src/services/contextCollapse/persist.ts` | **Stub** — `restoreFromEntries` 为空操作 |
|
||||
| CtxInspectTool | `packages/builtin-tools/src/tools/CtxInspectTool/CtxInspectTool.ts` | **实现** — 上下文内省工具 |
|
||||
@@ -33,9 +40,9 @@ CONTEXT_COLLAPSE 让模型内省上下文窗口使用情况，并智能压缩旧
|
||||
| QueryEngine 集成 | `src/QueryEngine.ts` | **布线** — 导入并使用 snip 投影 |
|
||||
| Token 警告 UI | `src/components/TokenWarning.tsx` | **布线** — 折叠进度标签 |
|
||||
|
||||
### 2.2 核心接口（已定义，待实现）
|
||||
#### 核心接口（已定义，待实现）
|
||||
|
||||
```ts
|
||||
```typescript
|
||||
// contextCollapse/index.ts
|
||||
interface ContextCollapseStats {
|
||||
// 上下文使用统计
|
||||
@@ -48,40 +55,30 @@ interface DrainResult {
|
||||
}
|
||||
|
||||
// 关键函数（全部 stub）：
|
||||
isContextCollapseEnabled() // → false
|
||||
isContextCollapseEnabled() // -> false
|
||||
applyCollapsesIfNeeded(messages) // 透传
|
||||
recoverFromOverflow(messages) // 透传（413 恢复）
|
||||
initContextCollapse() // 空操作
|
||||
```
|
||||
|
||||
### 2.3 预期数据流
|
||||
#### 预期数据流
|
||||
|
||||
```
|
||||
对话持续增长
|
||||
│
|
||||
▼
|
||||
上下文接近限制（由 query.ts 检测）
|
||||
│
|
||||
├── 溢出检测 (query.ts:440,616,802)
|
||||
│
|
||||
▼
|
||||
applyCollapsesIfNeeded(messages) [需要实现]
|
||||
│
|
||||
├── 后台 LLM 调用压缩旧消息
|
||||
├── 保留关键信息（决策、文件路径、错误）
|
||||
└── 替换旧消息为压缩摘要
|
||||
│
|
||||
├── 413 恢复 (query.ts:1093,1179)
|
||||
│ └── recoverFromOverflow() 紧急折叠
|
||||
│
|
||||
▼
|
||||
projectView() 过滤折叠后的消息视图
|
||||
│
|
||||
▼
|
||||
模型继续工作（在压缩后的上下文中）
|
||||
```mermaid
|
||||
flowchart TD
|
||||
A["对话持续增长"] --> B["上下文接近限制 由 query.ts 检测"]
|
||||
B --> C{"溢出检测"}
|
||||
C --> D["applyCollapsesIfNeeded(messages) 需要实现"]
|
||||
D --> E["后台 LLM 调用压缩旧消息"]
|
||||
E --> F["保留关键信息 决策/文件路径/错误"]
|
||||
F --> G["替换旧消息为压缩摘要"]
|
||||
C --> H{"413 恢复"}
|
||||
H --> I["recoverFromOverflow() 紧急折叠"]
|
||||
G --> J["projectView() 过滤折叠后的消息视图"]
|
||||
I --> J
|
||||
J --> K["模型继续工作 在压缩后的上下文中"]
|
||||
```
|
||||
|
||||
### 2.4 HISTORY_SNIP 子功能
|
||||
#### HISTORY_SNIP 子功能
|
||||
|
||||
SnipTool 提供手动折叠能力：
|
||||
|
||||
@@ -89,7 +86,7 @@ SnipTool 提供手动折叠能力：
|
||||
- SnipTool — 标记特定消息进行折叠/修剪
|
||||
- `collapseReadSearch.ts` 已完整实现，将 Snip 作为静默吸收操作处理
|
||||
|
||||
### 2.5 集成点
|
||||
#### 集成点
|
||||
|
||||
| 文件 | 位置 | 说明 |
|
||||
|------|------|------|
|
||||
@@ -99,25 +96,25 @@ SnipTool 提供手动折叠能力：
|
||||
| `src/utils/sessionRestore.ts` | 127,494 | 恢复折叠状态 |
|
||||
| `src/services/compact/autoCompact.ts` | 179,215 | 自动压缩时考虑折叠 |
|
||||
|
||||
## 三、需要补全的内容
|
||||
### 需要补全的内容
|
||||
|
||||
| 优先级 | 模块 | 工作量 | 说明 |
|
||||
|--------|------|--------|------|
|
||||
| 1 | `services/contextCollapse/index.ts` | 大 | 折叠状态机、LLM 调用、消息压缩 |
|
||||
| 2 | `services/contextCollapse/operations.ts` | 中 | `projectView()` 消息过滤 |
|
||||
| 3 | `services/contextCollapse/persist.ts` | 小 | `restoreFromEntries()` 磁盘持久化 |
|
||||
| 4 | `tools/CtxInspectTool/` | 已完成 | 上下文内省工具已实现（`packages/builtin-tools/src/tools/CtxInspectTool/`） |
|
||||
| 4 | `tools/CtxInspectTool/` | 已完成 | 上下文内省工具已实现 |
|
||||
| 5 | `tools/SnipTool/SnipTool.ts` | 中 | Snip 工具实现 |
|
||||
| 6 | `commands/force-snip.js` | 小 | `/force-snip` 命令 |
|
||||
|
||||
## 四、关键设计决策
|
||||
### 关键设计决策
|
||||
|
||||
1. **后台 LLM 压缩**：折叠不是简单截断，而是用 LLM 生成压缩摘要保留关键信息
|
||||
2. **413 恢复**：当 API 返回 413（请求过大）时，紧急折叠是最重要的恢复手段
|
||||
3. **与 autoCompact 协作**：折叠和自动压缩（compact）是不同的机制，折叠在消息级别，压缩在对话级别
|
||||
4. **持久化**：折叠状态持久化到磁盘，会话恢复时重载
|
||||
|
||||
## 五、使用方式
|
||||
### 使用方式
|
||||
|
||||
```bash
|
||||
# 启用 context collapse
|
||||
@@ -127,7 +124,7 @@ FEATURE_CONTEXT_COLLAPSE=1 bun run dev
|
||||
FEATURE_CONTEXT_COLLAPSE=1 FEATURE_HISTORY_SNIP=1 bun run dev
|
||||
```
|
||||
|
||||
## 六、文件索引
|
||||
### 文件索引
|
||||
|
||||
| 文件 | 职责 |
|
||||
|------|------|
|
||||
@@ -138,3 +135,7 @@ FEATURE_CONTEXT_COLLAPSE=1 FEATURE_HISTORY_SNIP=1 bun run dev
|
||||
| `src/query.ts` | 溢出检测和 413 恢复集成 |
|
||||
| `src/QueryEngine.ts` | Snip 投影使用 |
|
||||
| `src/components/TokenWarning.tsx` | 折叠进度 UI |
|
||||
|
||||
## 关联笔记
|
||||
|
||||
- [[claude-code-best/docs/features/token-budget]]
|
||||
|
||||
Reference in New Issue
Block a user