Discuss the “more aggressive” wording for reactive_compact / 讨论 reactive_compact 的“更激进”表述

[Batman0x0000001]

Background

While studying the s08_context_compact chapter, I noticed a small possible ambiguity in one sentence about compact_history and reactive_compact.

The current README says:

This triggers reactive_compact: more aggressive than compact_history, it retreats from the tail, but still avoids leaving an orphaned tool_result.

My guess is that the word “aggressive” is describing the exceptional trigger after the API returns prompt_too_long. My only question is whether the phrase “more aggressive than compact_history” may be read in more than one way.

When comparing how the two functions actually rewrite messages, I feel that “aggressive” may have two different meanings here.

What the functions do

compact_history(messages) replaces the current active conversation history with a single summary message:

return [{"role": "user", "content": f"[Compacted]\n\n{summary}"}]

So after calling it, messages becomes roughly:

[
  user: [Compacted] + summary
]

The original recent tool_use / tool_result messages are no longer kept in the active context.

reactive_compact(messages) summarizes the earlier history and preserves the recent message tail:

return [
    {"role": "user", "content": f"[Reactive compact]\n\n{summary}"},
    *messages[tail_start:]
]

So after calling it, messages becomes roughly:

[
  user: [Reactive compact] + summary of earlier history,
  ...recent original messages...
]

Question

From the chapter content, compact_history seems “more aggressive” because it compresses the whole conversation history into one summary message.

From the trigger-timing perspective, reactive_compact can also be called “more aggressive” because it is triggered only after an actual API call has failed, such as prompt_too_long or too many tokens.

So this issue is only about whether the word “aggressive” is clear enough here.

Proposed documentation clarification

Would it be clearer to describe the distinction like this?

compact_history is the normal full-history compaction path. It replaces the active conversation with a single summary message.

reactive_compact is an exceptional fallback used after the API reports prompt_too_long. It summarizes older history while preserving the most recent message tail, so that the agent still has the latest tool_use/tool_result context.

Or more briefly:

reactive_compact is more aggressive mainly in trigger timing, not necessarily in retaining less context. It is an exceptional fallback that summarizes earlier conversation history while preserving the recent message tail.

Why this issue

The core of this chapter is context compaction. Distinguishing the following points is important for understanding and learning:

• proactive compaction before the next model call.
• emergency compaction after a model call fails.
• full-history summary.
• older-history summary plus recent-tail preservation.

This issue is only about clarifying the explanation, not changing the implementation.

---

背景

我在学习 s08_context_compact 这一章时，注意到其中一句关于 compact_history 和 reactive_compact 的文档表述可能存在一点点歧义。

当前 README 中写道：

这时触发 reactive_compact：比 compact_history 更激进，从尾部回退，但仍要避免留下孤立 tool_result。

我猜测“激进”这个词可能是在描述 API 返回 prompt_too_long 后的异常触发。我的疑问只在于：“比 compact_history 更激进”这个说法可能会有不止一种理解方式。

对比两个函数实际对 messages 的改写方式，我感觉这里的“激进”可能有两种不同含义。

函数作用

compact_history(messages) 会把当前活跃对话历史整体替换成一条摘要消息：

return [{"role": "user", "content": f"[Compacted]\n\n{summary}"}]

所以调用后， messages 大致变成：

[
  user: [Compacted] + summary
]

原始的最近 tool_use / tool_result 消息都不再保留在当前上下文中。

reactive_compact(messages) 会摘要较早的历史并保留最近的尾部消息：

return [
    {"role": "user", "content": f"[Reactive compact]\n\n{summary}"},
    *messages[tail_start:]
]

所以调用后， messages 大致变成：

[
  user: [Reactive compact] + earlier history summary,
  ...recent original messages...
]

疑惑点

如果从这一章节的内容上来看：compact_history 似乎“更激进”，因为它把整个对话历史压成了一条摘要消息。

如果从触发时机这个角度看：reactive_compact 又可以说“更激进”，因为它是在实际 API 调用已经失败，比如 prompt_too_long 或 too many tokens 后才触发。

所以这里想讨论的只是“激进”这个字眼是否足够清楚。

建议的文档澄清

是否可以把两者区别改成类似下面的表述？

compact_history 是正常触发的全量摘要。它会把当前对话替换成一条摘要消息。

reactive_compact 是 API 返回 prompt_too_long 后的异常兜底策略。它会摘要较早的历史，同时保留最近的消息尾部，让 agent 仍然拥有最近的 tool_use/tool_result 上下文。

或者更简短地说明：

reactive_compact 的“激进”主要体现在触发时机上，而不一定是保留上下文更少。它是一个异常兜底策略，会摘要较早历史对话并保留最近尾部消息。

为什么提出这个 issue

这一章的核心是讲上下文压缩。区分下面几件事对于理解与学习很重要：

• 下一次模型调用前的主动压缩。
• 模型调用失败后的应急压缩。
• 全历史摘要。
• 较早历史摘要 + 最近尾部消息保留。

这个 issue 只建议澄清文档表述，不要求修改实现。