CoPaw 上下文管理设计解析

March 30, 2026 · View on GitHub

本文聚焦短期上下文管理，不涉及长期记忆模块。

AI Agent 在使用过程中，迟早会遇到一个让人头疼的问题：上下文窗口被塞满了。

工具调用返回了一大段 HTML、几千行日志、或者完整的文件内容——这些都会急剧消耗宝贵的 Token 配额。随着对话轮次增加，早期的信息要么被截断，要么把整个窗口撑爆，Agent 的表现开始下滑。

CoPaw 在设计上下文管理时，围绕这个问题给出了一套系统性的答案。本文将完整拆解 * CoPaw Context Management V2* 的数据结构与运行机制。

上下文长什么样？

在讨论"如何管理"之前，先看清楚"管理的是什么"。

CoPaw 的上下文分为两层：内存层与文件系统层。

内存层（In-Memory）

内存中维护两个核心字段：

  • compact_summary（可选）：当历史对话被压缩后，这里存放结构化摘要，包含 Goal、Constraints、Progress、KeyDecisions、 NextSteps 五个维度——相当于一份精炼的"工作备忘录"。同时还包含一个历史对话原始数据的路径引导，告诉 Agent 去哪里找 dialog/YYYY-MM-DD.jsonl，以及建议"从后往前读"。
  • messages：当前对话的完整消息列表，是 Agent 实际推理时消费的数据。

文件系统层（File Cache）

对于体积较大、不适合长期驻留内存的内容，CoPaw 将其 offload 到文件系统：

  • 历史对话原始数据：dialog/YYYY-MM-DD.jsonl，按日期分文件存储
  • 工具调用结果：tool_result/{uuid}.txt，设有 N 天 TTL，过期自动清理
flowchart TD
    A[Context] --> B[compact_summary]
    B --> C[dialog 路径引导 + Goal/Constraints/Progress/KeyDecisions/NextSteps]
    A --> E[messages: 完整对话历史]
    A --> F[文件系统缓存]
    F --> G[dialog/YYYY-MM-DD.jsonl]
    F --> H[tool_result/uuid.txt N天TTL]

这个设计让 Agent 既能在内存中快速访问近期对话，又能在需要时按需回溯历史——而不是把所有历史内容硬塞进上下文。

推理前做什么？Pre-Reasoning Hook

每轮推理正式开始前，CoPaw 会执行一个 Pre-Reasoning Hook，自动完成上下文的整理工作。整个流程分四步：

  1. 工具结果压缩（ToolCallResultCompact）：先处理工具调用结果，将超长内容截断并 offload 到文件系统
  2. 上下文检查（ContextChecker）：计算当前上下文的 Token 使用量，判断是否超出阈值
  3. 若超出阈值：
    • 保留最近 X% 的 Token（保障对话连贯性）
    • 对更早的历史对话调用 Compactor 生成结构化摘要
  4. 历史对话持久化（SaveDialog）：将被压缩的原始对话保存到文件系统
flowchart LR
    A[Pre-Reasoning Hook] --> B[ToolCallResultCompact]
    B --> C[ContextChecker]
    C --> D{Token > 阈值?}
    D -->|是| E[保留近期 X% Token]
    E --> F[Compact & 生成摘要]
    F --> G[SaveDialog: 持久化到文件]
    D -->|否| H[正常推理]

这个流程确保每次推理开始前，上下文都处于一个"干净"的状态。

工具结果 Offload：统一的两阶段截断

工具调用结果是上下文膨胀的主要来源之一。CoPaw 采用两阶段截断策略，将截断时机与截断力度分离：

  • 一次截断：在工具调用结果写入上下文时立即触发，所有工具（包括 read_file）统一适用。截断后将完整原始内容保存到 tool_result/{uuid}.txt，并在消息中附注文件路径与起始行提示。
  • 二次截断：在 Pre-Reasoning Hook 处理时，对已滑出 recent_n 范围的历史消息触发，截断更为激进，进一步压缩上下文占用。
flowchart LR
    A[工具调用完成] --> T[一次截断<br>写入上下文时立即执行]
    T --> S[完整内容写入 tool_result/uuid.txt<br>消息附注文件路径 + 起始行]
    S --> B{Pre-Reasoning Hook<br>该消息在 recent_n 内?}
    B -->|是| C[无需处理<br>保持一次截断结果]
    B -->|否| D[二次截断<br>更激进压缩<br>file_path 不变]

这样设计的好处在于：一次截断保证所有工具结果从写入那刻起就不会撑爆上下文；二次截断则随着对话推进自动"淡化" 历史信息，始终为近期内容留出充足空间。

以 Browser Use 类工具为例

阶段行为
一次截断工具返回结果后立即截断，完整内容写入 tool_result/uuid.txt，消息附注 "FullText saved to xxxx，请从第 N 行开始读"
在 recent_n 内Pre-Reasoning Hook 不做额外处理，保持一次截断结果
超出 recent_n（二次截断）解析已有的消息结果，对原始内容做更激进的截断，同步更新消息中的 meta 信息（如行号提示）；file_path 不变，仍指向原文件

二次截断的关键在于：原始完整内容始终保存在同一个文件路径下，无论经过多少轮截断，Agent 都能通过文件引用找到原始内容；截断只影响上下文中的消息片段和 meta 信息，不改变文件。

flowchart LR
    A[Browser Use Result] -->|一次截断| B[上下文: 片段 + file_path + 起始行]
    B --> C{超出 recent_n?}
    C -->|否| D[保持不变]
    C -->|是| E[解析现有消息<br>对原始内容二次截断<br>更新 meta 信息]
    E --> F[上下文: 更短片段 + 同一 file_path]

两阶段截断的代码实现与示例

截断逻辑的入口是 truncate_text_output，它根据文本中是否已包含 <<<TRUNCATED>>> 标记来分发到两个不同的函数：

def truncate_text_output(text, start_line=1, total_lines=0,
                         max_bytes=DEFAULT_MAX_BYTES,
                         file_path=None, encoding="utf-8") -> str:
    if TRUNCATION_NOTICE_MARKER in text:
        return _retruncate(text, max_bytes=max_bytes, encoding=encoding)
    else:
        return _truncate_fresh(text, start_line=start_line,
                               total_lines=total_lines,
                               max_bytes=max_bytes,
                               file_path=file_path, encoding=encoding)

一次截断（_truncate_fresh）

触发时机：工具调用完成、结果写入上下文时立即执行，此时文本中尚不含截断标记。

核心逻辑：

  1. 若文本字节数未超过 max_bytes，直接返回原文；
  2. 否则按字节切片，保留截断点前最后一个完整行，计算下一段应从哪一行开始；
  3. 在末尾追加截断通知（<<<TRUNCATED>>>），提示后续从 start_line=N 继续读取。

示例：假设一个工具返回了 3 000 行的 HTML 内容（共 200 KB），而 max_bytes = 50 KB：

# 原始工具输出（200 KB，共 3000 行）
<html>
  <head>...</head>
  <body>
    ...（大量内容）
  </body>
</html>

# 一次截断后写入上下文（50 KB，约 750 行）
<html>
  <head>...</head>
  <body>
    ...（前 750 行）
<<<TRUNCATED>>>
The output above was truncated.
The full content is saved to the file and contains 3000 lines in total.
This excerpt starts at line 1 and covers the next 51200 bytes.
If the current content is not enough, call `read_file` with file_path=tool_result/abc123.txt start_line=751 to read more.

完整原始内容同时写入 tool_result/abc123.txt，上下文中仅保留截断片段与续读提示。

二次截断（_retruncate）

触发时机：Pre-Reasoning Hook 处理时，对已滑出 recent_n 范围的历史消息执行，进一步压缩上下文占用。

核心逻辑：

  1. 从文本中分离出 <<<TRUNCATED>>> 前的原始内容与后面的通知部分；
  2. 若原始内容仍未超出新的 max_bytes（带 100 字节宽松量），直接返回原文；
  3. 否则按新的更小字节限制重新切片，并通过正则替换通知中的 字节数 与 续读行号，file_path 保持不变。

示例：同样是上面那条工具消息，在它滑出 recent_n 之后，二次截断将 max_bytes 从 50 KB 压缩到 10 KB：

# 二次截断前（上下文中已有一次截断结果，50 KB）
<html>
  <head>...</head>
  <body>
    ...（前 750 行）
<<<TRUNCATED>>>
...This excerpt starts at line 1 and covers the next 51200 bytes.
...call `read_file` with file_path=tool_result/abc123.txt start_line=751 to read more.

# 二次截断后（进一步压缩至 10 KB，约 150 行）
<html>
  <head>...</head>
  <body>
    ...（前 150 行）
<<<TRUNCATED>>>
...This excerpt starts at line 1 and covers the next 10240 bytes.
...call `read_file` with file_path=tool_result/abc123.txt start_line=151 to read more.

关键点：file_path 始终指向 tool_result/abc123.txt，Agent 随时可通过文件引用获取完整原始内容；截断只影响上下文片段与 meta 信息。

ReadFile 工具的特殊处理

read_file 与 Browser Use 类工具共享同一套两阶段截断机制，但有一个关键区别：它读取的文件本身已存在于文件系统 ，无需在一次截断时另行保存。

阶段行为
一次截断在读取时即完成截断，结果写入上下文；原始文件路径已知，无需额外保存到 tool_result/
在 recent_n 内Pre-Reasoning Hook 不做任何修改，保持读取时的截断结果
超出 recent_n（二次截断）与其他工具相同，对消息内容做更激进的截断，更新 meta 信息
flowchart LR
    A[ReadFile 调用] -->|读取时截断| B[上下文: 截断内容<br>原始文件路径已知]
    B --> C{超出 recent_n?}
    C -->|否| D[无需修改]
    C -->|是| E[二次截断<br>更新 meta 信息<br>与其他工具行为一致]

Markdown 文件的特殊保护

对于 skill.md、规则文件等 Markdown 文件，CoPaw 在截断时给予更大的保护阈值。

Markdown 文件通常承载结构化的知识或指令，过度截断会破坏其完整语义。因此，在一次截断和二次截断时，Markdown 文件的截断触发上限均高于普通工具输出，确保 Agent 能读到尽可能完整的结构化内容。

flowchart LR
    A[工具结果] --> B{是 Markdown 文件?}
    B -->|是| C[更高截断阈值<br>更大保护]
    B -->|否| D[标准截断阈值]
    C --> E[一次 / 二次截断逻辑]
    D --> E

长期记忆的触发逻辑

本节超出上下文管理的核心范畴，简要介绍 CoPaw 的长期记忆写入机制。

长期记忆由三个触发路径驱动：

  1. 主 Agent 主动写入：

    • Memory.md（长期记忆主干，记录用户偏好等持久信息）
    • YYYY-MM-DD.md（当日日志）

  2. 上下文压缩触发时，由 Summarizer（ReAct Agent） 写入：

    • 个性化信息（用户偏好、习惯等）
    • Try-error 信息（失败尝试与修正经验）

  3. 定时任务（每日 00:00）：

    • 汇总最近的 YYYY-MM-DD.md 文件
    • 将日志整合更新到 Memory.md
flowchart TD
    A[Main Agent] --> B[写入 Memory.md]
    A --> C[写入 YYYY-MM-DD.md]
    D[上下文达到压缩阈值?] -->|是| E[Summarizer Agent]
    E --> F[记录: 个性化信息]
    E --> G[记录: Try-Error 经验]
    H[定时任务 00:00] --> I[汇总最近 YYYY-MM-DD.md]
    I --> J[更新 Memory.md]

这套机制确保了短期对话中的重要信息能够沉淀为长期记忆，不因对话结束而丢失。

小结

CoPaw 上下文管理的核心设计哲学可以用一句话概括：

让内存只放"现在需要的"，让文件系统保管"之后可能需要的"。

通过 Pre-Reasoning Hook 的四步流程、统一的两阶段截断策略，以及文件系统的持久化支撑，CoPaw 在有限的上下文窗口内为 Agent 提供了最大程度的信息可用性——无论对话持续多久，Agent 总能找到它需要的上下文。

本文设计对应实现可参考 CoPaw MemoryManager 与 ReMe ReMeLight。