compaction

package
v0.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 9, 2026 License: MIT Imports: 7 Imported by: 0

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

View Source
const BasicEngineSumm = "【摘要】过去对话摘要如下:"

BasicEngineSumm 是 BasicEngine 生成的摘要标题/前缀。

View Source
const PruneMarker = "\n... [内容已省略] ...\n"

PruneMarker 是中间被移除段的替换标记。

Variables

View Source
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

func PruneText(text string, threshold, head, tail int) (string, bool)

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

func (c *Compactor) Compact(ctx context.Context, events []session.SessionEvent) (Result, error)

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 是压缩器的配置。

func (Config) WithDefaults

func (c Config) WithDefaults() Config

WithDefaults 填充默认值后返回副本。

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 把一段「将被替换」的旧事件归纳为摘要文本。

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL