问题域/PD-01

上下文管理

Context Window Management

LLM 上下文窗口有限，长任务中如何保留关键信息、裁剪冗余内容、避免 token 超限崩溃。这不是一个"优化"问题，而是一个"生存"问题。

子问题

1.Token 估算：在调用 LLM 前精确估算当前 prompt 的 token 数

2.超限裁剪：按优先级裁剪内容（旧消息、工具结果、搜索素材）

3.摘要压缩：将长历史对话压缩为摘要，保留关键信息

4.滑动窗口：只保留最近 N 轮对话或最近 N 个工具结果

5.预算分配：为不同内容类型分配 token 预算

6.实时数据注入：每次会话前从外部数据源查询最新状态并填充 prompt 模板变量

7.多市场规则差异化注入：不同业务场景需要在 prompt 中注入不同的领域规则（如 A 股 T+1）

8.步数与信号双重终止：max_steps 硬限 + Agent 自主 STOP_SIGNAL 的协同终止策略

9.上下文边界自主管理：LLM 通过工具调用自主决定任务块的开始和结束，而非系统自动切割

10.归档摘要二级折叠：归档池本身超限时需要将多条归档合并为 meta-summary 防止前缀膨胀

11.感知差分注入：只在环境状态变化时注入感知信息，避免每轮重复相同的环境描述占用 token

12.历史查询按需加载：LLM 通过 REPL 查询接口按需搜索归档历史，无需全量加载到 prompt

13.裁剪通知机制：裁剪后注入系统消息告知 LLM 历史已丢失，防止 LLM 引用不存在的上下文

14.终端中间层截断：tmux/screen 等终端复用器对 send-keys 的字符数限制导致 prompt 被截断

15.多角色 Prompt 分层：编排器与 Worker Agent 需要不同结构的上下文，需要独立的生成路径

16.用户规则双源合并：内联配置与外部文件两种规则来源的合并与容错处理

17.工具 JSON Schema token 计算：将工具描述的 JSON Schema 也纳入 token 预算，遵循 OpenAI Cookbook 规则

18.记忆标记系统：用 Enum 标记消息状态（COMPRESSED/HINT），支持按标记过滤、排除、清理

19.压缩模型独立配置：为压缩任务选择成本效益最优的模型（如 GPT-3.5）而非主模型（如 GPT-4）

20.检索去重元数据持久化：压缩后保留已执行的搜索查询和已获取的文档 ID，防止 Agent 重复检索相同内容

21.动态压缩阈值自适应：摘要本身占用 token，固定阈值会导致摘要越长越频繁触发压缩的恶性循环

22.双层图上下文分治：外层会话摘要与内层检索压缩各自独立，避免不同粒度的上下文管理互相干扰

23.Observation 经济学量化：对比发现成本与读取成本，计算压缩 ROI 并展示给用户

24.Mode 继承与类型过滤：不同工作模式自动切换 observation 类型/概念过滤器

25.跨会话 transcript 恢复：从 JSONL transcript 反向提取先前 assistant 消息注入上下文

26.Observation 内容去重：基于 SHA256 哈希的 30 秒滑动窗口去重防止重复存储

27.经济意识注入：将 token 成本转化为 Agent 可感知的生存压力，引导自主控制输出长度

28.迭代预算提前提交：计算安全提交点并注入 prompt，避免 Agent 在最后一轮才提交导致超时

29.超限产物回收：迭代超限后通过独立工作流回收已生成但未提交的产物，避免浪费已消耗 token

30.工具消息修复链：压缩前需修复空 input、无效 ID、重复 block、乱序配对等 4 类 tool 消息缺陷

31.反向遍历截断：从最新消息开始逐条累加 token，超阈值时丢弃更早消息保证最新上下文完整

32.异步摘要双写：压缩摘要同时异步写入长期记忆库，实现会话内压缩与跨会话持久化的并行

33.Agent 自主压缩门控：compact 工具需要 50% 阈值门控防止过早压缩浪费 LLM 调用

34.链式摘要 cutoff 累加：多次摘要后有效列表与 state 列表的索引偏移需正确转换

35.摘要消息标记与过滤：链式摘要时需标记并过滤旧 summary 消息避免重复 offload

36.知识库外置持久化：将压缩后的摘要写入外部文件而非仅存内存，确保跨清除周期可用

37.读取拦截优化：对已实现文件的 read_file 调用重定向到摘要，避免重复读取原始文件消耗 token

38.事件驱动清除：以工具调用事件（如 write_file）而非 token 阈值作为清除触发条件

39.Agent 自主压缩决策：让 LLM 在输出中生成压缩指令，自主决定折叠哪些历史步骤

40.步骤级上下文重建：将压缩后的步骤列表重新格式化为结构化的 Previous Steps 文本

41.工具输出分片增量摘要：超长网页内容按 token 阈值分片，逐片增量提取 evidence 和 summary

42.双轨轨迹记录：同时维护压缩后的 messages 和完整的 full_trajectory 用于不同用途

43.工具输出压缩：将工具返回的大量原始数据压缩为结构化摘要，保留核心知识

44.Prompt 模板管理：通过外置配置文件系统化管理 system prompt，支持多语言切换

45.嵌入阶段文件过滤：根据文件类型设置差异化 token 阈值决定是否入库

46.RAG 上下文动态裁剪：根据输入大小决定是否执行检索以及检索结果是否注入 prompt

47.多提供商 tokenizer 选择：不同嵌入模型使用不同编码器，需运行时动态适配

48.记忆注入预算控制：跨会话记忆注入 system prompt 时的 token 预算精确控制与截断策略

49.去抖动记忆更新：多轮对话中记忆更新的去抖动批量处理，避免频繁 LLM 调用

50.中间件顺序依赖：压缩/修复/注入等中间件的执行顺序对正确性的影响

51.AI/Tool 消息对保护：压缩时不拆分工具调用与结果的配对关系

52.子 Agent 上下文隔离：通过架构设计避免子 Agent 内部对话污染主 Agent 上下文

53.摘要模型选择：为压缩任务选择成本效益最优的模型而非主模型

54.查询驱动预算分配：根据查询复杂度评分动态调整上下文预算比例

55.检索 ROI 量化：用 confidence_gain/lines_added 衡量每轮检索的成本效益

56.智能裁剪优先级：按来源类型×元素类型×相关度评分的多因子优先级裁剪超预算内容

57.压缩方向选择：根据场景决定保留最新消息（对话）还是最旧消息（任务上下文）

58.递归摘要收敛：超长文本需多轮滑动窗口摘要，需防止无限递归（MetaGPT 用 max_count=100 兜底）

59.ProviderChain 错误分类隔离：区分上下文溢出与可重试错误，避免无效 failover

60.压缩前记忆保存：在摘要替换历史前用隐藏 Agent 循环将重要信息持久化到文件

61.压缩安全性：使用结构化消息对象构建摘要 prompt，防止用户内容中的角色前缀注入

62.异常驱动 vs 预估驱动：不依赖 tokenizer 预估而是通过异常捕获触发截断的权衡

63.字符-token 粗估比例：token_limit * 4 作为字符上限的近似精度与适用范围

64.搜索结果预压缩：在工具层对原始网页内容做第一层 LLM 摘要减少下游 token 压力

65.累计预算追踪：跨多次 LLM 调用追踪总 token 消耗，而非仅检查单次请求

66.工具描述计入预算：将工具的 JSON Schema 描述也纳入 token 预算计算

67.六类记忆分类提取：从会话中按 profile/preferences/entities/events/cases/patterns 分类提取长期记忆

68.记忆合并决策：新提取记忆与已有记忆的 skip/create/merge/delete 四种处理策略

69.记忆语言检测：根据用户消息的 Unicode 范围自动检测语言，确保提取记忆与用户语言一致

70.归档摘要结构化：LLM 生成包含里程碑/意图/概念/错误/待办的 Markdown 结构化摘要

71.归档相关性检索：commit 后的归档通过关键词匹配 + 时间排序按需召回

72.多模态元素上下文：为图片/表格/公式等非文本元素提取周围文本作为 LLM 理解辅助

73.上下文粒度选择：根据文档类型选择页面级或块级上下文窗口

74.上下文配置热更新：运行时动态调整上下文参数并传播到所有处理组件

75.缓存前缀保护：压缩时保护消息前缀的字节一致性以维持 prompt caching 命中率

76.归档内容可追溯：被压缩的消息不丢弃而是归档为文件，Agent 可按需读取

77.元数据优先注入：上下文只注入文件/结果的元数据，LLM 按需通过工具读取全文

78.ToolMessage 二次截断：历史压缩后仍超预算时对工具输出内容做 head/tail 截断兜底

79.关键词驱动摘要提取：用中英文完成/总结关键词从内容末尾反向定位摘要段落

80.多供应商消息格式适配：同一压缩逻辑需为 Anthropic/OpenAI/Google 各实现一套检测和替换

81.视觉操作结果精细压缩：区分截图工具（全替换）和操作工具（保留文本移除media）的差异化处理

82.服务端 vs 客户端上下文管理：OpenAI previousResponseId 模式下客户端无需压缩的架构选择

83.DOM 无障碍树压缩：ariaTree 等大型结构化文本数据的独立保留策略（仅保留最新1份）

84.辩论历史双轨管理：共享 history 与角色独立 history 的同步维护

85.LLM 提供商占位消息兼容：不同 API 对空消息列表的差异化要求

86.报告字段提取时机：工具调用循环中仅在最终响应时提取报告内容

87.Tensor 级滚动窗口：在 GPU Tensor 上直接截断而非字符串操作，保持梯度计算图完整

88.批量轨迹停用：同一 batch 中不同样本轨迹长度差异大，需按样本级别停用超长轨迹

89.多模态 token 长度失真：vision token 展开后数量远超语义长度，需去重后再判断是否超限

90.GPU batch 对齐填充：多 GPU 推理要求 batch size 整除 GPU 数，需 dummy 序列填充和裁剪

91.Tier 分级压缩：根据关闭时间分级压缩（30 天 Tier1、90 天 Tier2），渐进式信息衰减

92.Agent 审查工作流：analyze 导出候选 → 人工/Agent 审查 → apply 应用摘要，关键任务可人工确认

93.压缩效果强制验证：摘要长度必须 < 原始长度，否则跳过并记录警告，防止无效压缩

94.Git 集成追踪：记录压缩时的 commit hash，支持版本控制和审计

95.批量并发控制：Semaphore 限流 + 独立错误处理，单个失败不影响其他

96.Mode 继承与深度合并：parent--override 模式配置的递归加载与 deepMerge 策略

97.Worktree 多项目上下文合并：git worktree 场景下父仓库与工作树 observation 的统一时间线

98.Timeline 按文件聚合：将散落的 observation 按修改文件分组，减少上下文碎片化

99.显示层截断与模型层完整的解耦：UI 折叠大文本但模型收到完整内容的双轨处理

100.上下文文件名多态配置：支持单文件名或文件名数组，适配不同项目约定

101.子目录记忆扫描限流：限制子目录扫描数量（默认 200）防止大型 monorepo 启动卡顿

102.分类摘要隔离：不同语义类别的记忆需要独立维护摘要，避免主题混杂导致信息丢失

103.CRUD 级增量 patch：单条记忆变更时用 before/after 差异判断是否需要更新摘要，避免全量重写

104.检索充分性提前终止：多层检索中每层后判断已有信息是否足够，避免不必要的深层检索消耗 token

105.引用追溯：摘要中嵌入 [ref:ITEM_ID] 引用，支持从压缩摘要反向定位原始记忆条目

106.推理模型 token 耗尽：reasoning 占用 >80% completion tokens 导致 content 为空，需检测并自动扩容重试

107.模型限制动态发现：中转平台可能施加额外限制，需从 API 错误中自动学习真实值并持久化

108.批处理双重约束：同时满足 input token 预算和 output token 预算的贪心分组策略

109.Lost-in-the-middle 防护：即使模型支持超长上下文，单批 input 也需 Hard Cap 防止注意力衰减

110.混合注意力 cache hit 对齐：同一模型中 FullAttention 和 SlidingWindow 层的 cache hit 长度需跨组对齐到 LCM

111.Speculative decoding block 回退：draft token 被拒绝后已分配的 block 需要安全回收而非立即释放

112.RLHF 权重更新后缓存失效：模型权重更新后所有 prefix cache 必须失效，需要原子性 reset 机制

113.分布式 KV 传输协调：P/D 分离架构中 prefill 节点和 decode 节点间的 KV block 异步传输与调度协调

114.Agent 角色定制压缩：为 Writer/Reviewer 等不同角色提供差异化的上下文视图

115.节点级 token 预算权重分配：按 Agent 重要性分配 token 预算比例

116.增量摘要与全量摘要切换：根据是否有历史摘要选择增量或全量 ReSum 策略

117.中间件透明注入：通过 wrap_node 包装使节点代码无需感知压缩逻辑

各项目的解法39 solutions

Signals

横向对比

维度	MiroThinker	DeerFlow	DeepResearch	GPT-Researcher	AI-Trader	AIRI	AgentOrchestrator	AgentScope	agentic-rag-for-dummies	ClaudeMem	ClawWork	CoPaw	DeepAgents	DeepCode	DeepTutor	DeepWiki	FastCode	LightRAG	MetaGPT	Moltis	OpenClaw	Open	OpenManus	OpenViking	PageIndex	RAG-Anything	Refly	Stagehand	system-prompts-and-models-of-ai-tools	TradingAgents	VRAG	beads	claude-mem	iflow-cli	memU	moyin-creator	seedance-2	vLLM	vibe-blog
估算方式	tiktoken o200k_base 精确估算	tokens/messages/fraction 三阈值	AutoTokenizer 精确计数	trim_context_to_word_limit 词数上限	无 token 估算，依赖 max_steps 步数间接控制上下文增长	字符数/4 粗估 token（brain.ts:1925），无精确 tokenizer	无显式 token 估算，依赖 Agent 插件自身的上下文管理	tiktoken 精确计数，支持 vision/tool tokens	tiktoken cl100k_base 逐消息 encode，仅计算 content 字段	字符数/4 常量估算，无 tokenizer 依赖	无预估算，依赖 LLM 响应后的 usage_metadata 实时扣减	Qwen2.5 HuggingFace tokenizer 精确编码，异常降级 len//4	count_tokens_approximately 近似估算，支持 tools 参数计入	tiktoken 精确计算 + 字符数/4 回退双轨	四级降级：API响应 > tiktoken > litellm > 词数×1.3	tiktoken 精确计数 + len//4 fallback，按 embedder_type 选编码器	tiktoken 精确编码计数，模型自适应 + cl100k_base 回退	—	tiktoken(OpenAI) + anthropic SDK(Claude) + 字符×0.5 fallback 三级适配	不做预估，依赖 API 错误响应触发（9 种模式匹配）	—	无预估，异常驱动：捕获 token 超限异常后才触发截断	tiktoken 精确编码，含图片 tile 计算和工具描述计数	len(content)//4 粗估 token，auto_commit_threshold=8000 触发归档	tiktoken 按模型编码精确计算每页 token	LightRAG tokenizer 精确 encode/decode，支持字符级 fallback	双模：字符/3.5 快速估算 + Kitoken 精确计数 + 大文件中位数积分 O(1)	无显式 token 估算，依赖滑动窗口固定保留数量控制	—	无 token 估算，不计算当前 prompt 大小	attention_mask.sum() 计算有效 token 数，image_pad 连续去重后计语义长度	SQL CHAR_LENGTH 函数计算 4 字段总和	字符数/4 简单估算，CHARS_PER_TOKEN_ESTIMATE=4 常量	比例阈值（currentTokens/tokensLimit），默认 128K 窗口	prompt 模板注入 target_length 硬约束，LLM 自行控制输出长度	字符数/1.5 保守粗估，不引入 tiktoken，前端友好	—	block 级精确计算：cdiv(num_tokens, block_size) 得到所需 block 数	tiktoken o200k_base 优先，降级字符估算（中文/1.5 + 英文/4）
压缩策略	移除最后一轮对话对	LLM 摘要替换旧消息 + 悬挂工具调用修复	AgentFold 步骤级合并 + ReSum 全量替换	25000 词硬裁剪 + visited_urls 去重	无压缩，消息列表只追加不裁剪	启发式摘要（动作序列+玩家指令提取），零 LLM 调用	无压缩，通过三层分离控制各层内容量	LLM 生成 5 字段结构化摘要（任务/状态/发现/下一步/上下文）	LLM 驱动结构化摘要（Focus/Findings/Gaps），400-600 词上限	结构化 observation 替代原始对话，6 字段拆解存储	WrapUp 滑动窗口取最近10条+关键词过滤，截断至5条摘要	LLM 增量摘要（ReMeFs compact），previous_summary 累积	LLM 摘要 + 工具参数截断双管齐下	Clean-Slate 全量清除 + LLM 生成结构化代码摘要外置	NoteAgent LLM 摘要压缩 + ToolTrace 50KB 源头截断	无压缩，超限直接跳过文件或去掉 RAG 上下文	无摘要压缩，直接从尾部截断 context 保留头部高相关内容	—	4 种 CompressType 枚举：pre/post × msg/token 组合，配置驱动选择	LLM 流式摘要，全量历史替换为单条 [Conversation Summary] 消息	—	LLM 压缩节点：独立 compression_model 将研究消息压缩为结构化摘要	无压缩，仅滑动窗口截断（max_messages=100）	LLM 结构化摘要归档 + 六类记忆提取，非就地替换而是归档+提取双轨	树结构节点合并 + token 阈值瘦身	无压缩，仅截断；80% 阈值句子边界回退	缓存友好：从最新消息向最旧压缩，保护前缀字节一致性	多模态滑动窗口：截图保留最近2张、ariaTree保留最近1份，旧内容替换为文本占位符	—	全量清除（RemoveMessage），非压缩/摘要	无压缩/摘要，纯左截断滚动窗口丢弃最旧内容	Tier 分级：Tier1 结构化摘要（70%），Tier2 极简化（95%）	SDK Agent 将工具输出压缩为结构化 XML observation（type/title/facts/narrative）	/compress 全量摘要替换，AI 生成对话摘要	Category Summary 增量合并：新记忆 + 旧摘要 → LLM 生成受控长度新摘要	无历史压缩；safeTruncate 在段落/句子边界截断 + 提示后缀	—	无压缩，通过 block 分页避免浪费；sliding window 自动回收窗口外 block	三层递进：L1 embedding 筛选 → L2 LLM 主动压缩 → L3 ReSum 增量摘要
触发机制	ensure_summary_context() 调用前检查	三触发 OR 逻辑（任一满足）	LLM 主动 <compress> 标签 + 90% 阈值	递归搜索完成后裁剪	每个交易日重建 Agent，STOP_SIGNAL 主动终止	活跃上下文>30条自动裁剪 + LLM主动调用enterContext/exitContext	spawn/start 时一次性组合，运行时不动态调整	双层：Formatter 超 max_tokens 截断 + Agent 超阈值压缩	动态阈值：BASE + summary_tokens * 0.9，每轮工具调用后判定	Hook 事件驱动（startup/resume/clear/compact）	max_iterations=15 硬编码循环上限触发 WrapUp	pre_reasoning Hook 阈值触发（max_input × 0.7 × 0.9）	fraction 0.85 自适应 + ContextOverflowError 降级兜底	write_file 事件驱动 + 190K token 阈值 + 50 条消息硬限	每次工具调用后自动触发 NoteAgent 压缩	三层：入库阈值过滤 → 请求 8000 token 预检 → 运行时错误捕获	prompt_tokens > available_input_tokens 时触发截断	—	aask() 调用前自动触发 compress_messages，对上层透明	错误驱动：API 返回 context_length_exceeded 等错误后自动压缩重试	—	子图出口自动触发：Researcher 子图的 compress_research 节点在研究完成后必经	累计 input token 超 max_input_tokens 时抛异常终止	Session.commit() 手动触发，可配置 auto_commit_threshold 自动触发	分组 token 总数超过 LLM 上限时自动分割	每次多模态元素处理时按需提取上下文	剩余预算比 < 20% 时触发，每轮 Agent Loop 调用前检查	每步执行前自动触发（prepareStep 回调 + CUA executeStep 入口）	—	图拓扑驱动：分析师完成后固定进入清除节点	每轮生成前自动触发：rolling_state 截断 + deactivate_batch 停用	时间驱动：30 天/90 天阈值自动识别候选	PostToolUse Hook 事件驱动，每次工具调用自动触发 observation 采集	compressionTokenThreshold 比例阈值（默认 0.8）自动触发	写入触发：memorize 时全量更新；CRUD 时 patch 增量更新	调用前预估：90% 硬拒绝 + 50% 输出空间软警告	—	每步调度时 allocate_slots 检查，不足时触发 preemption 抢占	usage_ratio 双阈值：0.7 触发 L1，0.9 触发 L2/L3
实现位置	openai_client.py LLM 客户端内部	AgentMiddleware 独立中间件	infer.py 推理主循环 + react_agent.py	deep_research.py 技能层	prompts/ 模板层 + BaseAgent 循环层双层实现	Brain类内聚管理，context-summary.ts纯函数辅助	独立 prompt-builder.ts + orchestrator-prompt.ts 双模块	Formatter 层（截断）+ Agent 层（压缩）	LangGraph 独立节点 should_compress_context + compress_context	独立 MCP 插件，通过 system prompt 注入上下文	prompt 层经济引导 + 代码层迭代限制 + LangGraph WrapUp 工作流	AgentScope register_instance_hook + Formatter 双层	AgentMiddleware.wrap_model_call 中间件拦截	独立 ConciseMemoryAgent 类 + CodeImplementationAgent 协作	Agent 层（NoteAgent）+ 数据结构层（ToolTrace.__post_init__）	data_pipeline.py + simple_chat.py + rag.py 分布式三文件	AnswerGenerator（token 层）+ IterativeAgent（行数层）双层	—	BaseLLM 基类统一实现，所有 Provider 子类继承	三层分布：provider_chain 分类 → runner 检测 → chat 压缩重试	—	LangGraph 子图节点：compress_research 作为 ResearcherState 子图的最后一个节点	LLM 层（TokenCounter + check_token_limit）	Session/SessionCompressor/MemoryExtractor/MemoryDeduplicator 四层分离	utils.py count_tokens + page_index.py 分组算法	独立 ContextExtractor 类，注入到所有 ModalProcessor	独立 context-manager.ts 模块，与 Agent 循环解耦	双层：CUA 客户端层（供应商格式）+ AI SDK 层（统一格式）	—	LangGraph 图节点（Msg Clear X），框架原语级	Tensor 原生操作，generation.py 的 _update_rolling_state 方法	存储层（Dolt 表字段）+ 独立压缩引擎（internal/compact）	独立 Worker 进程 + SQLite，与主 Claude Code 会话解耦	CLI 内置，闭源 Node.js 实现	MemorizeMixin._update_category_summaries + CRUDMixin._patch_category_summaries	model-registry 注册层 + script-parser 调度层 + batch-processor 分批层	—	推理引擎核心层：Scheduler → KVCacheManager → BlockPool	MiddlewarePipeline 中间件，before_node 钩子透明注入
容错设计	降级 len//4 估算	摘要失败回退保留最后 15 条	独立 ReSum 模型服务器不占主模型窗口	Semaphore(2) 并发控制	指数退避重试 max_retries=3，无上下文溢出处理	exitContext自动触发（enterContext时auto_exit），200条硬上限兜底	agentRulesFile 读取失败静默跳过，buildPrompt 无内容返回 null	压缩失败时记录警告但不中断流程	fallback_response 节点在超限时消费压缩上下文生成兜底答案	数据库初始化失败返回空字符串，transcript 解析跳过畸形行	WrapUp 回收已有产物，不浪费已消耗 token	tokenizer 降级 + 4 步 tool 消息修复链 + 全局 try/except	offload 失败非致命，ContextOverflowError 降级到摘要	tokenizer 不可用时回退字符估算，摘要生成 3 次重试	LLMContextError + ProviderContextWindowError 双层异常 + 消息匹配自动映射	tiktoken 异常降级为 char/4；LLM 报错降级为无 RAG 重试	未知模型回退 cl100k_base，context_budget<0 时降级空 context	—	未知 CompressType 返回 NO_COMPRESS，未知模型 fallback cl100k_base	ContextWindow 不 failover（换提供商无用），压缩失败返回原始错误	—	渐进式截断重试：remove_up_to_last_ai_message 逐轮移除 + 最多 3 次重试	TokenLimitExceeded 不重试，Agent 优雅终止并记录错误	create+merge 矛盾决策自动归一化为 none，LLM 不可用时降级为 CREATE	三级降级 + validate_and_truncate 索引越界防护	tokenizer 不可用时回退字符截断；异常返回空字符串	DriveFile 上传失败则跳过压缩，ToolMessage 二次截断兜底	Google CUA 5次指数退避重试；output.type 校验防止非 content 类型被误压缩	—	占位 HumanMessage 保证 Anthropic API 兼容	超长轨迹静默停用不影响 batch 其他样本，图片裁剪失败回退文本提示	指数退避重试（3 次，1s→2s→4s），429/5xx 可重试	Worker 不可用时静默降级返回空上下文，不阻塞主会话	maxSessionTurns 硬限兜底，超限开启新会话	patch 返回 need_update=false 跳过无效更新；updated_content='empty' 清空摘要	Error-driven Discovery 从 400 错误自动学习模型限制并持久化缓存	—	分配失败返回 None 触发抢占链，RLHF 场景支持 reset_prefix_cache	三层降级链 L3→L2→L1 + tiktoken→字符估算降级
Prompt模板化	—	SYSTEM_PROMPT_TEMPLATE 含 memory/skills/subagent 动态占位符	—	—	三市场独立模板文件，str.format() 动态变量注入	—	三层分离：常量基础指令 + 配置派生 + 用户规则，Markdown 段落拼接	—	—	ModeConfig 定义完整 prompt 模板，支持继承覆盖	f-string 模板注入6项经济指标+分级生存引导	—	—	CONVERSATION_SUMMARY_PROMPT 外置于 code_prompts.py	YAML 多语言 prompt + 单例缓存 + zh→cn→en 降级链	Jinja2 模板 RAG_TEMPLATE 含 contexts 条件注入	—	—	—	分段限额：Memory 8K / ProjectContext 8K / Workspace 6K 字符独立上限	—	—	Python 常量定义，按 Agent 类型分文件（toolcall/swe）	YAML+Jinja2 PromptManager，支持变量校验/max_length截断/线程安全缓存	—	—	SkillPromptModule 接口 + ContextBlock 结构化注入	—	—	f-string 内联模板，无外置配置文件	—	Go template 渲染，强调 COMPRESS 目标和结构化输出	ModeConfig JSON 文件驱动所有 prompt 模板，支持继承（parent--override）	contextFileName 支持多文件名配置，环境变量引用	6-block 模块化 prompt（objective/workflow/rules/output/examples/input），支持 per-category 覆盖	PromptCompiler Mustache 插值引擎，4 模板 + 运行时热更新	—	—	trim_prompt 占位符替换 + ReSum 初始/增量双 prompt 模板
多维停止决策	—	—	150 分钟超时 + 100 次调用上限 + 110K token 硬限三重终止	—	STOP_SIGNAL + max_steps 双重终止条件	—	—	—	—	—	迭代上限(15) + 活动完成标志 + 破产检测三重停止条件	—	—	—	—	—	置信度+行数+ROI+停滞+连续低效+严格停滞 6 重检查	—	—	—	—	—	—	—	—	—	—	—	—	—	max_turns 步数限制 + active_mask done 信号 + max_model_len 长度停用	单一停止条件：摘要长度 >= 原始长度则跳过	—	—	—	—	—	—	—
保留策略	—	keep 参数支持 messages/tokens/fraction 三种保留方式	ReSum 保留 system+摘要；AgentFold 保留最新步骤原文+历史折叠摘要	—	全量保留，每步 assistant+tool 消息线性追加	Minecraft保留最新半数活跃消息；Satori保留最近5条	全量保留，不裁剪——通过文件化注入绕过 shell 截断而非压缩内容	反向遍历保留最近 N 条消息，保护工具对完整性	全量清除 messages[1:] + 摘要替代，retrieval_keys 跨周期累积	配置驱动：最近 N 条 observation + M 条 session summary	全量消息累积无压缩，仅在 WrapUp 时取最近10条	保留 system prompt + 最近 N 条（默认 3），配对感知动态调整	fraction 0.10 保留最近消息，无 profile 时 keep 6 条	仅保留 system_prompt + initial_plan + 知识库摘要，历史全清	—	代码文件 81920 token 入库，文档文件 8192 token 入库，无历史裁剪	保留头部（高相关度），尾部截断；智能裁剪按优先级评分选取	—	System Prompt 永不裁剪，threshold=0.8 为输出预留 20%	压缩前 silent_turn 将重要信息写入 MEMORY.md，压缩后仅保留摘要	—	双轨保留：compressed_research（精简）+ raw_notes（完整原始内容）	—	归档消息完整保留在 history/archive_NNN/，Agent 可按需回溯	—	滑动窗口保留前后 N 页/块，默认 window=1	ArchivedRef 路由表永不截断，归档内容可通过 read_file 按需读取	截图/视觉操作保留最近2个，ariaTree保留最近1个，视觉操作保留文本移除media	—	报告提取到顶层字段，消息全量丢弃	左截断保留最新上下文，right_side 同步截断保持 prompt/response 对齐	永久性优雅衰减：原始内容不可恢复，只保留摘要	按 totalObservationCount 配置限制查询数量（默认 50），LIMIT SQL 裁剪	大文本 UI 层首尾各 2000 字符截断，模型层保留完整	—	—	—	引用计数 + LRU 驱逐队列，ref_cnt=0 的 block 按 FIFO 顺序驱逐	低优先级先裁（research→content→instructions），工具结果替换为占位文本
供应商适配	—	—	—	—	DeepSeekChatOpenAI 子类修复 tool_calls.args 格式差异	—	—	—	—	—	OpenRouter 直接用 reported cost，其他用本地 price/1M 公式	DashScope 专用 Formatter，多模态固定 100 token 估算	—	—	—	—	—	—	—	ProviderErrorKind 枚举统一分类，9 种模式覆盖 Anthropic/OpenAI/Google	—	8 供应商 30+ 模型映射表 + 三家异常模式匹配（OpenAI/Anthropic/Gemini）	—	vlm.get_completion_async 统一接口，vlm.is_available() 可用性检查	—	—	—	Anthropic/Google/OpenAI 三套独立 find+compress 函数，OpenAI 用服务端 previousResponseId 免压缩	—	—	—	—	—	OpenAI 兼容协议，支持多模型切换	—	三层查表按模型名查找，prefix 降序匹配，覆盖 50+ 模型	—	—	—
实时数据注入	—	—	—	—	每日从 JSONL 查询价格/持仓/收益注入 system prompt	感知差分注入：仅环境状态变化时注入[PERCEPTION]块	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	PromptCompiler {{variable}} 动态注入场景/角色/风格等运行时数据	—	—	—
滑动窗口回收	—	—	—	—	—	Satori Bot slice(-5)激进裁剪 + 系统消息通知LLM历史丢失	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	SlidingWindowManager 自动计算窗口外 token 数并替换为 null_block	—
摘要提取	—	—	—	—	—	从llmLog提取动作序列+从消息提取玩家指令，固定格式≤600字符	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	LLM 生成 Markdown 结构化摘要（里程碑/意图/概念/错误/待办）	—	—	39 个中英文关键词反向搜索 + 段落边界扩展，≤ 100 tokens	—	—	—	—	—	—	—	—	—	—	—	—
子Agent隔离	—	task 工具独立上下文，结果以单条 ToolMessage 返回	—	—	—	双服务独立上下文：Minecraft Brain vs Satori Bot各自管理	Worker 走 buildPrompt 三层组合，Orchestrator 走独立生成器，互不干扰	—	每个子 Agent 独立 AgentState，context_summary 和 retrieval_keys 天然隔离	—	—	—	每个子Agent独立 SummarizationMiddleware 实例和阈值	每个文件实现周期独立，write_file 后 clean-slate 天然隔离	—	—	—	—	—	—	—	每个 Researcher 子图独立压缩，压缩后的摘要才传递给 Supervisor	—	user/agent/session/resources 四 scope 隔离，owner_space 权限校验	—	—	元数据优先：ContextBlock 只存 meta，LLM 按需 read_file 读取内容	—	—	TypedDict 双轨制：辩论状态与消息流完全分离	—	不涉及（beads 无子 Agent 概念）	—	—	—	—	—	—	compress_for_writer/reviewer 按角色定制上下文视图
摘要模型选择	—	优先用轻量模型（thinking_enabled=False）节省成本	ReSum-Tool-30B 独立摘要模型，不占用主模型推理资源	—	—	不使用LLM摘要，纯确定性启发式生成	—	支持独立压缩模型（如 GPT-3.5）降低成本	复用主模型（ChatOllama qwen3:4b），未使用独立压缩模型	—	—	复用主模型（通过 MemoryManager.chat_model 共享）	复用主模型，不单独指定摘要模型	—	—	—	—	—	—	—	—	独立 compression_model 可配置为 gpt-4.1-mini 等低成本模型	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—
归档折叠	—	—	—	—	—	超10条归档时合并最旧N条为meta-summary（二级压缩）	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—
上下文边界自主管理	—	—	—	—	—	LLM通过REPL调用enterContext/exitContext自主划分任务块	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—
历史查询接口	—	—	—	—	—	history runtime提供search/recent/turns/contexts等REPL查询方法	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—
运行时热更新	—	—	—	—	—	—	不支持——prompt 在 spawn 时一次性生成，运行中不可变	—	—	3 级配置优先级（env > file > defaults），env 变量即时生效	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	update_context_config 动态修改参数并传播到所有处理器	—	—	—	—	—	不支持（压缩后需重启查询才能看到效果）	—	—	—	—	—	—	—
文件化注入	—	—	—	—	—	—	长 prompt 写入 .md 文件，通过 $(cat file) shell 替换注入避免 tmux 截断	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	viking:// URI 寻址，.abstract.md/.overview.md 隐藏文件存储 L0/L1	—	—	—	—	—	—	—	不涉及（压缩后内容直接存数据库，非文件）	通过 SessionStart Hook 的 additionalContext 注入，或写入 AGENTS.md 文件	IFLOW.md 三级分层加载 + @file.md 模块化导入	—	—	—	—	—
AI/Tool消息对保护	—	DanglingToolCallMiddleware 在 before_model 修复悬挂对	ReSum 整体压缩所有历史，不拆分消息对；AgentFold 按步骤粒度折叠	—	—	—	—	用 set 追踪 tool_call_id，成对删除/保留	未显式保护，RemoveMessage 删除 messages[1:] 含所有 AI/Tool 对	—	—	check_valid_messages 验证 ID 匹配，动态缩小 keep_length	PatchToolCallsMiddleware 自动补全悬挂 tool_call	—	—	—	—	—	—	压缩为全量替换（单条摘要），不存在拆分配对问题	—	remove_up_to_last_ai_message 按 AI 消息边界截断，隐式保护消息对完整性	—	—	—	—	ToolPairGroup 原子组：AIMessage + 所有 ToolMessage 整体归档或保留	—	—	—	—	—	—	—	—	—	—	—	—
记忆标记系统	—	—	—	—	—	—	—	Enum 标记（COMPRESSED/HINT），支持按标记过滤	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—
工具描述计入预算	—	—	—	—	—	—	—	遵循 OpenAI Cookbook 规则计算工具 JSON Schema tokens	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—
多模态上下文	—	—	—	—	—	—	—	支持 vision token 计算（base+tile 模式）	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	为图片/表格/公式提取周围文本作为 LLM 理解辅助	—	截图+ariaTree+视觉操作结果三类多模态内容分类压缩	—	—	pixel_values/image_grid_thw 增量 torch.cat 拼接，image_pad 连续去重	不支持（仅文本压缩）	—	—	—	—	—	CrossAttentionManager 独立管理 encoder KV，不参与 prefix caching	—
压缩效果验证	—	—	—	—	—	—	—	检查 metadata 是否存在，失败时记录警告	—	—	—	—	CLI 层计算并展示 token 节省百分比	—	—	—	—	—	—	摘要为空时返回错误拒绝替换，但不验证摘要长度 < 原始长度	—	—	—	merge_memory_bundle 要求 LLM 返回 decision=merge 且 abstract+content 非空	—	—	—	—	—	—	—	强制验证：摘要长度 < 原始长度，否则跳过并记录警告	—	—	—	—	—	—	无显式验证，依赖 usage_ratio 阈值判断
增量摘要与全量摘要切换	—	—	有 last_summary 时用增量模板 QUERY_SUMMARY_PROMPT_LAST，否则全量	—	—	—	—	—	支持增量：existing_summary 作为 PRIOR COMPRESSED CONTEXT 前缀传入	—	—	始终增量：传入 previous_summary 在历史摘要基础上追加	仅全量摘要，链式摘要时过滤旧 summary 避免重复	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	memorize 走全量合并（新条目+旧摘要），CRUD 走 patch（before/after 差异）	—	—	—	—
检索去重追踪	—	—	—	—	—	—	—	—	retrieval_keys Set 用 parent::/search:: 前缀区分，注入摘要尾部指导 Agent	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	enable_item_references 时 summary 内嵌 [ref:ITEM_ID] 引用，检索时可追溯原始条目	—	—	—	—
知识库外置	—	—	—	—	—	—	—	—	—	SQLite WAL 模式持久化，跨会话可用	—	—	—	implement_code_summary.md 文件持久化代码摘要，跨轮次可读	—	—	—	—	—	—	—	—	—	所有记忆写入 VikingFS 文件系统，跨会话持久化	—	—	—	—	—	—	—	Dolt 数据库持久化，支持 Git 版本控制	SQLite 持久化 + 可选 Chroma 向量库，跨会话跨清除周期可用	—	—	—	—	—	—
读取拦截优化	—	—	—	—	—	—	—	—	—	Context Index 语义索引替代原文，按需 get_observations 获取详情	—	—	—	read_file 调用被拦截重定向到 read_code_mem 返回摘要	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	不涉及（无读取拦截机制）	三层渐进检索：Context Index → get_observations → mem-search，避免重复读取原始文件	—	—	—	—	—	—
分割粒度	—	AI/Tool 消息对保护，不拆分工具调用序列	AgentFold 按步骤级折叠，ReSum 按整体对话压缩，NestBrowse 按 64K 分片	—	—	—	—	—	—	observation 级（每条独立记录），非消息级或对话级	—	—	—	—	按工具调用粒度，每次调用独立压缩为一个 ToolTrace	TextSplitter 按词分割，350 词/块，100 词重叠	检索层按代码元素（函数/类）粒度，LLM 层按 token 粒度	—	BrainMemory 字符级滑动窗口（window_size - 20 步进），非语义分割	—	—	—	消息级别截断，不拆分单条消息	六类记忆（profile/preferences/entities/events/cases/patterns）独立存储	页级分组，overlap_page 保证语义连贯性	page（页面级）和 chunk（块级）双模式	—	—	—	—	—	Issue 级别（单个任务整体压缩）	—	—	—	—	—	固定 block_size（1/8/16/32/64/128/256 token），GPU 上限 32	—
累计预算	—	未实现跨调用累计追踪，仅单次触发检查	—	—	—	—	—	—	—	—	EconomicTracker 跨调用累计 total_token_cost 并实时扣减 balance	—	—	—	—	—	IterativeAgent 跨轮追踪 total_lines 和 budget_usage_pct	—	CostManager 跨调用累计 prompt/completion tokens 和 cost，支持 max_budget	runner 用 saturating_add 累计 total_input/output_tokens，但不用于触发压缩	—	—	跨调用累加 total_input_tokens，单例模式保证全局唯一	—	—	—	—	—	—	—	—	OpenTelemetry 指标追踪 token 累计使用量	—	—	—	—	—	—	TokenBudgetMiddleware 按节点权重分配预算，总预算 500K token
工具输出压缩	—	—	NestBrowse 的 process_response 将网页内容分片提取 evidence+summary	—	—	—	—	—	—	—	—	head+tail 截断（默认 10000 字符），保留首尾各半	write_file/edit_file 参数 >2000字符截断为前20字符+标记	—	—	—	—	—	—	—	—	搜索阶段预压缩：max_content_length 截断 + summarize_webpage 结构化摘要	—	—	—	—	—	—	—	—	—	—	—	summarizeToolOutput 按 tokenBudget 独立压缩 shell 输出	—	—	—	—	—
二次截断兜底	—	—	—	—	—	—	—	—	—	—	—	Formatter 反向遍历逐条计数，超阈值直接 break 丢弃旧消息	—	—	—	—	—	—	—	sanitize_tool_result 50KB 硬限制 + base64/hex blob 剥离	—	final_report 阶段：token_limit*4 字符估算 → 每次重试缩减 10%	—	—	—	—	压缩后仍超预算时，每条 ToolMessage 截断至 ≤ 4096 tokens	—	—	—	—	—	—	—	—	—	—	—	—
Agent审查工作流	—	—	—	—	—	—	—	—	—	—	—	—	compact_conversation 可配置 HITL 审批	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	三模式：analyze 导出 → 人工/Agent 审查 → apply 应用	—	—	—	—	—	—	无，压缩自动执行无人工确认
批量并发控制	—	SubagentLimitMiddleware 硬限 [2,4] 截断超额 task 调用	—	—	—	—	—	—	—	—	—	—	—	—	—	OpenAI embedder batch_size=500，Ollama 单文档串行处理	—	—	—	—	—	—	—	—	—	—	—	—	—	—	active_mask 位图追踪活跃轨迹，GPU padding 对齐确保 batch 可整除	Semaphore 限流（默认 5 并发）+ 独立错误处理	—	—	—	60K Hard Cap + 双重约束贪心分批 + runStaggered 并发 + 单批次指数退避重试	—	—	无并发压缩，中间件串行执行
记忆注入预算	—	max_injection_tokens=2000 + tiktoken 精确截断留 5% 余量	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	per-category target_length 覆盖全局默认 400 token	—	—	—	—
渐进式加载	—	Skills 只注入索引（名称+路径），Agent 按需 read_file 加载	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	Category → Item → Resource 三层递进检索，每层后 LLM 判断是否继续	—	—	—	—
查询驱动预算	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	按查询复杂度 0-100 动态分配 60%-100% 行数预算	—	—	—	—	—	—	—	—	—	—	—	—	—	—	不涉及（压缩不依赖查询复杂度）	—	—	三层 sufficiency check：category 够用就不查 item，item 够用就不查 resource	—	—	—	无，使用固定权重分配（writer 35%、revision 15%）
树构建	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	BuildingTree URI 索引树 + DirectoryDefinition 预设目录 + 递归初始化	自底向上合并，token 超限节点递归拆分	—	—	—	—	—	—	不涉及（无树状结构）	—	—	—	—	—	—	—
缓存前缀保护	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	system + 前 N 条 ≥ 4096 tokens 作为不可压缩前缀	Anthropic system message 标记 cacheControl ephemeral 利用 prompt caching	—	—	—	—	—	—	—	—	—	SHA256/xxHash 内容寻址，block hash 链式依赖保证前缀一致性	—
就地修改策略	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	所有压缩操作 in-place 修改消息数组，避免 base64 大字符串深拷贝	—	—	—	—	—	—	—	—	—	—	—
辩论轮次控制	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	count 计数器 + max_rounds 参数硬性截止	—	—	—	—	—	—	—	—	—
Git集成	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	记录压缩时的 commit hash（compacted_at_commit 字段）	—	—	—	—	—	—	—
Observation经济学	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	discovery_tokens vs read_tokens 对比，计算并展示 savings 百分比	—	—	—	—	—	—
分类摘要隔离	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	每个 category 独立 summary，10 个默认类别各自维护，互不干扰	—	—	—	—
推理模型适配	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	检测 reasoning_tokens 占比 >80% 时自动双倍 max_tokens 重试	—	—	—
混合注意力协调	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	—	HybridKVCacheCoordinator 迭代定点算法对齐多组 cache hit 长度	—

最佳实践

1.必须有估算：不管用什么方案，调用前必须知道当前 token 用量

2.预留安全边际：MiroThinker 的 85% 策略值得借鉴，为输出预留 15-20% 空间

3.分层裁剪优于一刀切：工具结果 > 旧对话 > 系统提示，按重要性分级

4.压缩后要验证格式：悬挂工具调用修复是容易被忽略但很关键的细节

5.考虑多提供商差异：不同 LLM 的 tokenizer 不同，需要适配

6.周期性任务优先考虑会话隔离：每个周期重建 Agent 比跨周期压缩更简单可靠

7.步数限制应配置化：不同场景（日线 30 步 vs 加密货币 10 步）需要不同的 max_steps

8.领域规则直接写入 prompt 模板：A 股 T+1 等硬性规则比工具返回更可靠

9.启发式摘要优于 LLM 摘要：游戏等实时场景中，从动作日志提取摘要比调用 LLM 更快且零成本

10.双层裁剪互为兜底：活跃上下文裁剪保证 LLM 输入可控，总历史硬上限保证内存安全

11.归档前缀需要缓存：buildContextHistoryMessage 结果缓存到 exitContext 时才失效，避免每轮重建

12.长 prompt 写文件再用 $(cat) 注入，比内联传递更可靠

13.buildPrompt 无内容时返回 null 而非空字符串，保持向后兼容

14.用户规则文件读取失败应静默跳过，不阻塞 Agent 启动流程

15.双层防护优于单层：Formatter 保证不超 API 限制，Agent 压缩保留语义，两层互补

16.结构化摘要优于自由文本：用 Pydantic Schema 约束摘要格式，确保包含任务/状态/发现/下一步/上下文 5 要素

17.反向遍历保留策略：从最新消息开始倒序遍历，保留最近 N 条完整消息，避免拆分工具对

18.压缩摘要应附带操作元数据（已检索 ID、已执行查询），而非仅保留语义内容

19.动态阈值公式应考虑摘要自身的 token 占用，避免压缩-膨胀循环

20.经济学可视化：展示 savings 百分比让用户理解压缩价值，而非仅静默压缩

21.结构化存储优于原文保留：拆解为 type/title/facts 等字段后可按维度过滤聚合

22.渐进式披露分层：最近 N 条展开 + 其余压缩为表格行，兼顾信息密度和 token 效率

23.配置优先级链：env > file > defaults 三级覆盖，支持运行时动态调整无需重启

24.双层限制互补：prompt 告知预算（软限制）+ 代码硬编码上限（硬限制），防止 Agent 忽略提示

25.WrapUp 自身也要追踪 token：回收工作流的 LLM 调用同样扣减余额，避免回收成本超过回收价值

26.双重防线互补：Hook 层做语义摘要保留信息，Formatter 层做硬截断保证绝不超限

27.配对感知分割：压缩边界必须检查 tool_use/tool_result 配对完整性，动态调整保留数量

28.本地 tokenizer 优先：优先加载本地 tokenizer 避免网络依赖，失败时降级为字符估算

29.参数截断前置于摘要：先截断大工具参数再做 LLM 摘要，减少摘要模型输入量和成本

30.ContextOverflowError 降级兜底：即使估算未触发阈值，实际调用超限时自动降级到摘要流程

31.offload 与摘要并行：两者互不依赖，asyncio.gather 并行执行减少延迟

32.Clean-Slate 适合文件级独立任务：当每个子任务（如实现一个文件）相对独立时，激进清除比渐进压缩更高效

33.知识库外置比内存摘要更可靠：写入文件的摘要不受上下文清除影响，且可被多个 Agent 共享

34.read_file 拦截可显著节省 token：已有摘要的文件无需重新读取原始内容

35.三重终止兜底：时间 + 调用次数 + token 数三维限制确保 Agent 不会无限运行

36.摘要模型与主模型分离：用更小的专用模型做摘要，主模型专注推理任务

37.Agent 自主压缩优于外部规则：让 LLM 判断哪些步骤可折叠，比 FIFO 滑动窗口更有语义感知

38.源头截断优于下游裁剪：在数据结构创建时就限制大小，防止大数据进入后续流水线

39.多级降级保证可用性：API > tiktoken > litellm > 估算，确保任何环境都能追踪 token

40.压缩后保留原始数据引用：ToolTrace 同时存储 summary 和 truncated raw_answer，支持回溯

41.代码文件与文档文件应设置不同的 token 阈值，代码可分块所以阈值更宽松

42.运行时降级应捕获多种错误关键词而非单一字符串匹配

43.token 计数器必须有 fallback 路径，避免 tiktoken 加载失败导致整个流水线中断

44.悬挂修复必须在压缩之后、模型调用之前：DanglingToolCallMiddleware 的 before_model 时机是关键

45.记忆注入用 tiktoken 精确计量而非字符估算：不同语言的 token/字符比差异大

46.Skills 用索引+按需加载替代全量注入：10 个 Skill 可节省 4000+ token

47.悬挂修复先于压缩：DanglingToolCallMiddleware 必须在 SummarizationMiddleware 之前执行

48.fraction 触发适配多模型：使用窗口占比而非绝对 token 数，自动适配不同模型的上下文窗口

49.配置驱动而非硬编码：所有阈值通过 YAML 配置，运维可调无需改代码

50.双层漏斗优于单层控制：检索层用行数预算粗筛，LLM 层用 token 预算精裁

51.安全边际独立配置：reserve_tokens 与 max_tokens 分离，避免输出截断

52.截断后必须验证：重建 prompt 后再次 count_tokens 确认未超限

53.压缩对调用者透明：在 LLM 基类统一拦截，上层 Role/Action 无需感知 token 限制

54.多 tokenizer 分级适配：精确 SDK > tiktoken > 字符估算，逐级降级而非一刀切

55.ContextWindow 错误不应触发 failover：消息太长在所有提供商都会失败，应回传调用方处理

56.压缩前先保存记忆：silent_turn 模式确保压缩丢失的细节仍可通过记忆搜索恢复

57.独立压缩模型降本：压缩任务用 gpt-4.1-mini 等便宜模型，不必复用主研究模型

58.按 AI 消息边界截断：比按字符数截断更安全，自动保护消息对完整性

59.搜索结果入口即压缩：在工具返回时就做第一层摘要，减少后续压缩压力

60.异常终止优于静默裁剪：超限时明确抛异常让调用方决策，避免静默丢上下文导致幻觉

61.单例模式保证计数器唯一：同一配置的 LLM 实例共享累计计数器，防止多处创建导致计数分散

62.工具描述也要计入 token：工具越多 token 开销越大，必须纳入预算检查

63.分层按需加载优于全量读取：L0 摘要满足 90% 浏览需求，仅深入时加载 L2

64.压缩应产出结构化知识而非简单截断：归档+记忆提取比丢弃消息更有价值

65.记忆去重需向量+LLM双重判断：纯向量阈值不够精确，LLM 理解语义重复更可靠

66.矛盾决策需安全网：LLM 返回 create+merge 等矛盾组合时自动归一化，防止数据损坏

67.截断时用 80% 阈值在句子边界回退，避免语义断裂

68.复用下游 LLM 的 tokenizer 做上下文截断，确保 token 计数一致

69.为有/无上下文场景准备双 prompt 模板，避免发送空 context 字段

70.缓存友好压缩方向：从最新消息开始压缩而非最旧，保护前缀缓存命中率（Anthropic 90% / OpenAI 50% 成本节省）

71.归档而非丢弃：被压缩的消息上传为文件并留下引用消息，Agent 可通过工具按需回溯

72.两级 Prompt 缓存：全局静态点（System Prompt 后）+ 会话动态点（最后 3 条消息），最大化缓存复用

73.占位符替换优于直接删除：保留 'screenshot taken' 让 LLM 知道此处曾有截图，维持对话连贯性

74.多模态内容分类保留：截图需前后对比保留2张，DOM树只需最新状态保留1份，不同类型不同策略

75.就地修改避免深拷贝：base64 图片数据量大，in-place 修改比创建新数组节省大量内存

76.全量清除适合无需跨节点共享消息的串行管道，比滑动窗口更简单可靠

77.辩论状态用 TypedDict 而非消息列表，可精确控制每个角色看到的上下文范围

78.双阈值分层控制：用 max_prompt_length 做软截断（可继续生成），用 max_model_len 做硬停用（防 OOM）

79.active_mask 位图优于动态 resize：用布尔掩码追踪活跃样本，避免动态删除 batch 元素导致索引混乱

80.多模态 token 去重计长：连续 image_pad 压缩为 1 个再计算语义长度，避免过早停用有效轨迹

81.永久性优雅衰减：压缩后原始内容不可恢复，强制信息衰减防止数据库无限膨胀

82.时间驱动触发优于 token 阈值：避免过早压缩活跃引用的任务，30 天阈值平衡信息保留与空间节省

83.结构化摘要模板：Summary + Key Decisions + Resolution 三段式，保留语义而非字面内容

84.压缩前强制验证：摘要长度 < 原始长度才应用，否则跳过并记录警告，防止无效压缩浪费 API 调用

85.Agent 审查可选：支持 analyze → 人工/Agent 审查 → apply 流程，关键任务可人工确认避免误压缩

86.用经济学指标（savings%）量化压缩效果，让用户和 Agent 都能评估记忆系统的 ROI

87.三层渐进检索比一次性注入更经济：大多数情况标题索引就够，按需深入

88.去重窗口要足够短（30秒）：太长会误杀合法的相似 observation，太短则无法去重

89.比例阈值优于固定值：用占比而非绝对 token 数触发压缩，自动适配不同模型窗口大小

90.工具输出独立预算：shell 等高膨胀工具应有独立的 tokenBudget，不与对话压缩混为一谈

91.per-category 差异化预算：不同类别的记忆重要性不同，应支持独立的 target_length 配置

92.patch 优于全量重写：单条记忆变更时先让 LLM 判断 need_update，跳过无效更新节省成本

93.并行更新受影响类别：asyncio.gather 同时更新所有受影响的 category summary，而非串行处理

94.prefix 匹配按 key 长度降序排列，避免短前缀误匹配更具体的模型变体

95.依赖注入解耦注册表与持久化层，避免 model-registry ↔ store 循环依赖

96.Error-driven Discovery 的正则要覆盖主流 API 的多种错误格式（DeepSeek/OpenAI/智谱）

97.批处理设置 60K Hard Cap，即使模型支持 1M 上下文也不要一次塞满

98.用引用计数而非标记清除管理共享 block，释放时尾部优先保证 LRU 语义

99.block hash 使用链式依赖（前一个 block 的 hash 参与下一个的计算），保证前缀匹配的正确性

100.null_block 哨兵模式：用单个不可释放的 null_block 替代已回收位置，避免数组重排

101.低成本操作优先：embedding 筛选成本远低于 LLM 压缩，应作为第一道防线

102.工具结果替换而非删除：保持消息列表结构完整，避免悬挂引用

103.环境变量驱动阈值：FOLD_THRESHOLD 和 SUMMARY_THRESHOLD 可运行时调整

104.编码器双降级：o200k_base → cl100k_base → 字符估算，覆盖所有模型系列