Documentation
¶
Overview ¶
Package compaction 提供长对话压缩(任务 S01:Compaction LLM 摘要 + Surface Replace)。
对齐上游:packages/compaction/compaction + compaction-engine-basic
设计要点:
- 触发:当事件文本(token)预算超过阈值(config.MaxTokens)时,压缩最老的 surface;
- 替换:生成一条 assistant/message 摘要事件,携带 SurfaceOp{replace start..end} (复用 M21 的读时表面替换,源事件保持 append-only,不修改历史);
- 续航:压缩后事件列表仍可继续追加新事件(turn 继续走),且 request/header 重建 只需「有效事件」,无需原始被替换事件;
- 摘要引擎:Summarizer 接口抽象;内置 BasicEngine(无 LLM,做前缀归纳)与 LLMEngine(可选,注入 llm.LLMAdapter 生成更精炼摘要)。
本文件实现 compaction 的 BasicEngine(任务 S01 引擎库)。
BasicEngine 是不依赖 LLM 的确定性摘要引擎:从被压缩的旧事件中抽取用户消息, 拼接为一段「过去对话摘要」,并受 maxRunes 约束截断。用于无 LLM 键或离线场景, 保证压缩永远可用;有 LLM 时可用 LLMEngine 替换获得更精炼摘要。
本文件复刻官方 compaction/tool-pairing 的核心:工具调用/结果的括号配平。 压缩会改变历史位置,安全切点必须从工具调用与结果的配平关系导出,而不能只看 step 标记——若切点落在 tool_call 与对应 tool_result 之间,压缩后的历史就会出现 "有调用没结果"的非法形态,模型会因此卡住。
pruner.go 复刻官方 compaction-tool-result-pruner 的纯文本修剪:超长工具结果 保留头部与尾部、中间替换为省略标记,按 rune(Unicode code point)切分,不拆 代理对;未超阈值时原样返回、changed=false。
Index ¶
- Constants
- Variables
- func BalancedCuts(events []session.SessionEvent) ([]bool, error)
- func EstimateTokens(events []session.SessionEvent) int
- func IsBalancedAt(events []session.SessionEvent, cut int) (bool, error)
- func NearestBalancedFrom(events []session.SessionEvent, start int) int
- func PruneText(text string, threshold, head, tail int) (string, bool)
- func ShouldCompact(events []session.SessionEvent, maxTokens int) bool
- type BasicEngine
- type Compactor
- type Config
- type Result
- type Summarizer
Constants ¶
const BasicEngineSumm = "【摘要】过去对话摘要如下:"
BasicEngineSumm 是 BasicEngine 生成的摘要标题/前缀。
const PruneMarker = "\n... [内容已省略] ...\n"
PruneMarker 是中间被移除段的替换标记。
Variables ¶
var ErrUnbalanced = errors.New("compaction: unbalanced tool pairing")
ErrUnbalanced 表示历史中出现没有对应调用的工具结果(或整体无法配平)。
Functions ¶
func BalancedCuts ¶
func BalancedCuts(events []session.SessionEvent) ([]bool, error)
BalancedCuts 返回每个切点是否配平。N 个事件有 N+1 个切点:cut[0] 在最前, cut[i] 在第 i 个事件之后,cut[N] 在末尾。配平 = 当前进行中调用数为 0。
func EstimateTokens ¶
func EstimateTokens(events []session.SessionEvent) int
EstimateTokens 估算事件列表的总 token 数(用于触发判断)。
func IsBalancedAt ¶
func IsBalancedAt(events []session.SessionEvent, cut int) (bool, error)
IsBalancedAt 判断 cut 位置(0..len(events))是否配平。
func NearestBalancedFrom ¶
func NearestBalancedFrom(events []session.SessionEvent, start int) int
NearestBalancedFrom 从 start 切点向后(含 start)找第一个配平切点;找不到返回 -1。 用于把一个期望的压缩边界安全地后移到不拆散工具对的位置。
func PruneText ¶
PruneText 修剪超长文本。runes 长度 <= threshold 时原样返回;否则保留前 head 个、后 tail 个 rune,中间放 PruneMarker。head/tail 非负,tail 超出时按可用量。
func ShouldCompact ¶
func ShouldCompact(events []session.SessionEvent, maxTokens int) bool
ShouldCompact 判断是否需要压缩。
Types ¶
type BasicEngine ¶
type BasicEngine struct{}
BasicEngine 是一个确定性的摘要引擎(无 LLM)。
func (*BasicEngine) Summarize ¶
func (b *BasicEngine) Summarize(ctx context.Context, events []session.SessionEvent, maxRunes int) (string, error)
Summarize 抽取旧事件中的用户消息,前若干条作为摘要;超长截断到 maxRunes。
type Compactor ¶
type Compactor struct {
// contains filtered or unexported fields
}
Compactor 驱动 "触发判断 → 选取替换范围 → 摘要 → 生成替换事件" 全流程。
func New ¶
func New(cfg Config, summarizer Summarizer) *Compactor
New 创建压缩器。summarizer 为 nil 时使用 BasicEngine。
func (*Compactor) Compact ¶
Compact 对事件列表执行一次压缩:把最老的(保留最近 KeepTail 条消息)summarize 掉, 生成一条 assistant/message 替换事件(SurfaceOp replace 该范围),并返回追加后的有效列表。
func (*Compactor) ShouldCompact ¶
func (c *Compactor) ShouldCompact(events []session.SessionEvent) bool
ShouldCompact 便捷判断(用配置阈值)。
type Config ¶
type Config struct {
MaxTokens int // 事件文本 token 估算超此值触发压缩
KeepTail int // 保留最近消息条数(不被替换)
SummaryMaxRunes int // 摘要最大字符数
}
Config 是压缩器的配置。
type Result ¶
type Result struct {
Start uint64 // 被替换范围起始 seq(含)
End uint64 // 被替换范围终止 seq(含)
Summary string // 摘要文本
Replacement session.SessionEvent // 新生成的摘要替换事件(含 SurfaceOp)
// Effective 为压缩后的有效事件列表(= 原始列表 + 追加的 Replacement)
Effective []session.SessionEvent
}
Result 是一次压缩的输出。
type Summarizer ¶
type Summarizer interface {
// Summarize 返回归纳后的摘要字符串。
Summarize(ctx context.Context, events []session.SessionEvent, maxRunes int) (string, error)
}
Summarizer 把一段「将被替换」的旧事件归纳为摘要文本。