下面是一份偏通用的需求文档，可以作为“AI Agent 上下文压缩系统”的 PRD / 技术需求基础。

# AI Agent 上下文压缩系统需求文档

## 1. 背景

AI Agent 在长任务中会持续积累：

- 用户消息
- 模型回复
- 工具调用记录
- 工具结果，例如命令输出、搜索结果、文件内容
- 任务状态、计划、错误、权限上下文

当上下文接近模型窗口上限时，系统必须减少上下文体积，同时尽量保留继续工作的能力。

本系统的核心目标不是简单删除历史，而是将低价值、大体积内容移出上下文，将旧对话压缩为可继续工作的摘要，并保留最近消息的完整细节。

## 2. 设计目标

系统应满足以下目标：

- 支持长时间、多轮任务持续运行。
- 降低工具大输出对上下文窗口的占用。
- 在压缩后保留任务连续性。
- 保留可追溯能力，必要时能找回旧工具输出。
- 尽量减少压缩本身的成本。
- 尽量保持 prompt cache 命中率。
- 支持自动压缩和手动压缩。
- 支持会话恢复后继续识别压缩边界。

## 3. 非目标

本系统不追求：

- 对所有历史做无损压缩。
- 永久保留所有原始上下文。
- 每次压缩后都能恢复完整逐字对话。
- 自动理解所有落盘文件的语义位置。
- 替代业务层记忆系统或知识库系统。

## 4. 核心设计理念

### 4.1 分级压缩

上下文压缩应分层处理，而不是一步到位：

```text
原始工具输出
  -> 大结果落盘，只保留预览和路径
  -> 旧工具结果清理或缓存删除
  -> 旧对话摘要压缩
  -> 只保留最近消息完整内容
```

越靠前的手段成本越低、信息损失越少；越靠后的手段越激进。

### 4.2 最近上下文保真

最近几轮消息通常包含当前任务状态、最新错误、刚修改的代码和即时决策。系统应优先完整保留最近上下文，而不是只依赖摘要。

### 4.3 旧历史变摘要

旧对话不应简单删除，而应转换为结构化摘要，摘要至少包含：

- 用户目标
- 已完成工作
- 关键文件与代码位置
- 重要错误和修复过程
- 当前任务状态
- 未完成事项
- 下一步建议
- 用户明确要求和偏好

### 4.4 大数据离开上下文，可追溯信息留在上下文

大工具输出应保存到外部存储，例如磁盘，只在上下文中保留：

```text
- 原始输出过大
- 完整输出保存路径
- 前若干 KB 预览
```

后续如需细节，Agent 可搜索或按片段读取该文件。

### 4.5 压缩边界显式化

每次完整压缩后，应插入一个边界标记：

```text
compact_boundary
```

该标记用于说明：边界之前的历史已由摘要覆盖。后续构造模型上下文时，应从最后一个边界开始读取，避免重复携带旧历史。

## 5. 功能需求

### 5.1 Token 计数与阈值判断

系统应维护当前上下文 token 估算。

要求：

- 优先使用最近一次 API usage 作为上下文基准。
- 对最新追加但尚未进入 API usage 的消息做粗略估算。
- 自动压缩阈值应低于模型最大上下文窗口。
- 应预留摘要输出空间，避免压缩请求本身超限。

示例策略：

```text
effective_context_window = model_context_window - reserved_summary_output_tokens
auto_compact_threshold = effective_context_window - safety_buffer_tokens
```

### 5.2 大工具结果落盘

当工具结果超过阈值时，系统应：

- 将完整结果写入会话级存储目录。
- 上下文中替换为预览文本。
- 预览中包含完整文件路径。
- 保留前若干字节或若干行作为快速判断线索。

示例上下文替换内容：

```text
<persisted-output>
Output too large. Full output saved to: /path/to/session/tool-results/id.txt

Preview:
...
</persisted-output>
```

要求：

- 每个工具调用结果应使用稳定唯一 ID 命名。
- 同一个工具调用结果重复处理时不应重复写入。
- 文件读取类工具可选择不参与二次落盘，避免“读落盘文件又落盘”的循环。
- 对图片、二进制、PDF 等特殊内容应有单独策略。

### 5.3 工具结果预算控制

系统应支持按“单轮工具结果总量”控制上下文膨胀。

要求：

- 不只判断单个工具结果大小，也判断同一轮多个工具结果的总大小。
- 超预算时优先替换最大的结果。
- 对某个工具结果是否替换的决策应保持稳定，避免下一轮改变历史前缀导致缓存失效。

### 5.4 微压缩

系统应提供轻量级微压缩机制。

适用对象：

- 旧 Bash 输出
- 旧 Grep/Search 输出
- 旧 WebFetch 输出
- 旧工具结果内容

可选策略：

- 将旧工具结果替换为占位符。
- 保留最近 N 个工具结果。
- 如果服务端支持缓存编辑，可通过 cache editing 删除旧工具结果引用。

示例占位：

```text
[Old tool result content cleared]
```

### 5.5 自动完整压缩

当上下文超过自动压缩阈值时，系统应触发完整压缩。

流程：

```text
当前消息
  -> 清理/微压缩
  -> 判断 token 阈值
  -> 生成摘要请求
  -> 调用模型生成结构化摘要
  -> 构造压缩后上下文
```

完整压缩后的上下文应包含：

```text
compact_boundary
compact_summary
preserved_recent_messages
restored_attachments
hook_results / session_context
```

### 5.6 手动压缩

系统应提供用户主动触发压缩的能力。

要求：

- 支持用户附加压缩指令。
- 支持只压缩某一段历史。
- 支持保留最近消息。
- 压缩失败时应给出明确错误。

### 5.7 摘要生成

摘要生成应使用专门 prompt。

要求：

- 明确禁止工具调用。
- 只允许输出文本摘要。
- 使用结构化格式。
- 摘要应面向“继续工作”，不是面向聊天回顾。
- 应优先记录技术决策、文件路径、错误和当前状态。

### 5.8 Prompt Cache 友好

压缩请求本身也可能很贵，因此应尽量复用已有 prompt cache。

要求：

- 压缩请求的系统提示、工具列表、模型配置应尽量与主请求保持一致。
- 摘要请求应只在已有上下文后追加一条“请总结”的消息。
- 不必要的参数变化应避免，例如改变 thinking 配置或输出限制导致缓存 key 不一致。
- 失败时应回退到普通摘要请求。

### 5.9 压缩后上下文恢复

压缩完成后，系统应恢复必要运行上下文：

- 最近读取过的重要文件
- 当前计划
- 已加载技能或工具说明
- MCP / 外部工具状态
- 用户自定义系统提示
- hook 结果
- session metadata

目标是让模型压缩后能继续工作，而不是重新探索所有环境。

### 5.10 会话持久化与恢复

系统应将压缩边界、摘要、保留消息关系写入会话记录。

要求：

- 恢复会话时能识别最后一个压缩边界。
- 不应重新加载已被摘要覆盖的旧历史。
- 如果保留了最近消息，应能正确重建消息父子关系。
- 落盘工具结果文件应有清理策略。

## 6. 读取落盘结果的策略

当 Agent 需要查看落盘结果时，应优先：

1. 根据摘要和预览判断关键词。
2. 用搜索工具查找关键词。
3. 根据搜索结果行号使用文件读取工具读取局部片段。
4. 避免直接读取整个大文件。
5. 避免用 shell 命令完整打印落盘文件。

推荐流程：

```text
Search(path, keyword)
Read(path, offset=line-20, limit=80)
```

## 7. 清理策略

落盘结果不应永久保存。

要求：

- 工具结果文件应按会话目录组织。
- 应有默认保留期，例如 30 天。
- 用户可配置保留天数。
- 后台任务定期清理过期文件。
- 删除过期文件后，应尝试删除空目录。
- 如果用户显式配置存在错误，应避免误删。

## 8. 异常与降级

系统应处理以下情况：

- 压缩请求本身超过上下文限制。
- 摘要模型无响应或返回空摘要。
- 用户中断压缩。
- 落盘失败。
- 落盘文件被清理或不存在。
- 压缩后仍超过阈值。
- 连续自动压缩失败。

要求：

- 自动压缩连续失败应有熔断机制。
- 压缩请求超限时可丢弃最旧消息组后重试。
- 落盘失败时应保留原工具结果或返回明确错误。
- 压缩失败不应破坏当前会话。

## 9. 安全与隐私

系统应注意：

- 落盘文件可能包含敏感信息。
- 文件路径不应暴露给无权限上下文。
- 读取落盘文件应走正常权限校验。
- 清理机制应防止路径穿越。
- 压缩摘要不应无必要复制密钥、token、隐私数据。

## 10. 观测指标

系统应记录以下指标：

- 压缩触发次数
- 自动压缩成功率
- 压缩前 token 数
- 压缩后 token 数
- 摘要请求 input/output token
- 大工具结果落盘次数
- 落盘前后大小变化
- microcompact 节省 token 数
- 压缩失败原因
- 连续失败次数
- prompt cache 命中率变化
- 清理删除文件数量

## 11. 验收标准

系统可认为满足需求，当：

- 长会话能在接近上下文上限时自动压缩并继续执行。
- 大工具输出不会长期完整占据上下文。
- 压缩后模型能基于摘要继续当前任务。
- 最近消息在压缩后仍完整可见。
- 用户可手动触发压缩。
- 落盘结果可通过路径和搜索找回。
- 旧落盘文件会按配置自动清理。
- 连续压缩失败不会造成无限重试。
- 会话恢复后不会重新加载已压缩旧历史。