长对话不爆上下文llm-for-zotero 缓存感知 Agent 与转录压缩机制完整指南【免费下载链接】llm-for-zoteroAn open-source research agent system for your Zotero library.项目地址: https://gitcode.com/gh_mirrors/ll/llm-for-zoterollm-for-zotero是一个跑在 Zotero 里的开源研究 Agent 系统它的核心难题是如何在超长对话中不撑爆大模型的上下文窗口。这个项目用「缓存感知 转录压缩」双机制优雅解决预算策略监控上下文水位触发语义化转录压缩同时按各家模型厂商的提示词缓存Prompt Cache能力规划稳定前缀让你和 AI 的文献研读对话可以无限聊下去。一、为什么长对话一定会爆上下文任何 Agent 对话都会累积三类 Token类型来源增长特点用户消息你的每一句提问线性增长助手回复模型每次的完整输出线性增长工具结果读论文、读 PDF、执行命令返回的大段文本爆炸式增长粗暴的做法是删掉最老的消息但 Agent 会因此失忆忘了最初的研究目标、丢掉了工具调用和结果的配对关系直接报错或答非所问。llm-for-zotero 的做法是分层预算 语义压缩 缓存复用下面逐层拆解。二、上下文预算策略水位线机制压缩不是无脑触发而是由一套水位线策略控制的核心实现在 budgetPolicy.ts72%上下文水位 → 进入警告状态84%水位 → 触发转录压缩compact92%水位 → 硬限制强制收缩压缩目标 → 压到窗口容量的58%其中几个关键配比同样值得注意压缩后保留的最近尾巴占 18%语义摘要占 8%证据片段占 12%。此外还有一个回滞hysteresis机制刚压缩过的会话下次触发阈值会临时上浮 8 个百分点避免刚压完又立刻再压的抖动。这套逻辑在buildAgentContextBudgetState()中一次性算出shouldCompact、targetTokens、recentTailTokens等状态供运行时决策// src/agent/context/budgetPolicy.ts 中的默认策略 const DEFAULT_POLICY: AgentContextBudgetPolicy { warningRatio: 0.72, compactRatio: 0.84, hardRatio: 0.92, targetRatio: 0.58, recentTailRatio: 0.18, summaryRatio: 0.08, evidenceRatio: 0.12, hysteresisRatio: 0.08, minRecentMessages: 4, };三、转录压缩机制压缩后不失忆真正动手压缩的是 transcriptCompactor.ts它解决了三个经典难题。1. 切哪里——对齐到轮次边界findTailStart()从消息尾部向前扫描找出预算内能装下的最远位置然后把切点对齐到用户消息边界alignTailStartToProviderMessageBoundary()还会回退切点确保不会把助手发起工具调用 → 工具返回结果这一对消息拆开。这样模型看到的对话永远是结构完整的。2. 压成什么——语义检查点Semantic CheckpointbuildSummaryMessage()不会生成模糊的之前我们聊了……而是产出一条结构化检查点消息包含最新根目标从历史中提取User request:或上一份检查点里的根目标让 Agent 永远记得最初的研究意图最近 8 条用户消息 8 条助手消息的截断摘录各自带 messageId可按需回读原文工具使用统计例如paper_read x5, run_command x2被压缩的工具结果句柄列出所有trh_开头的 handle3. 工具结果去哪了——句柄化外存buildPortableAgentTranscript()把被丢弃的大块工具结果转存为工具结果句柄tool result handle对话里只留一行handletrh_xxx和运行摘要需要原文时 Agent 可以调用tool_result_read(handle)精确取回。摘要里还特意声明摘录不完整依赖被省略文本前先调用 conversation_read 或 tool_result_read等于给模型留了一张记忆索引卡而不是让它靠猜。这套压缩与恢复能力有专门的测试覆盖agentTranscriptCompactor.test.ts 和 agentTranscriptRecovery.test.ts。四、缓存感知把重复发送变成免费读取压缩省的是每次要发的 Token而提示词缓存省的是发送的成本和延迟。这两件事在 contextCache/manager.ts 里统一规划。1. 自动识别各家缓存能力resolvePromptCacheCapability()根据接入的供应商自动判定缓存类型供应商缓存模式遥测指标Anthropic / MiniMax显式缓存块ephemeral支持 1h TTLcache read / writeOpenAI / Codex / DeepSeek / Gemini / Kimi自动前缀匹配各自 cached tokens / 命中率其他无缓存退化为稳定前缀策略2. 稳定前缀 内容指纹buildContextCacheKey()用「供应商 : 模型 : 论文上下文列表 : 内容哈希」构造缓存键——只要模型和挂载的论文没变前缀部分就能命中缓存。同时设置了1024 Token 门槛太短的上下文开缓存得不偿失直接禁用below-cache-threshold。3. 用命中率决定 TTL 的聪明细节对 Anthropic是否启用 1 小时长缓存成本更高由shouldUseAnthropic1hCache()决定上下文至少 16000 Token、至少命中过 1 次、读次数不少于写次数、且最近命中率 ≥ 50% 才升级。这是一个典型的先观察、再花钱策略避免为一次性长上下文支付双倍缓存费。4. 证据缓存压缩之外还有一层事实记忆cacheManagement.ts 在 SQLite 里维护llm_for_zotero_agent_evidence表把读过的论文片段按会话证据键去重存储最多 12 条证据、每条 4 个片段、单片段上限 1200 字符。即使转录被压缩Agent 也能重新调出关键引文保证长对话中引用论文不翻车。五、双机制如何协同工作整个流程可以概括为一条流水线每轮请求前预算策略计算当前水位判断是否需要压缩若超阈值转录压缩器切出完整轮次尾巴 生成语义检查点大工具结果句柄化外存组装请求时缓存管理器为稳定前缀系统提示、论文上下文、工具定义规划缓存键与 TTL 提示命中缓存的部分按极低费率计费压缩保证总输入不超窗口——缓存让记住的更便宜压缩让忘掉的可找回。这套机制的完整行为有对应测试保障contextCacheManager.test.ts、agentPromptBudget.test.ts、agentRetention.test.ts。六、给使用者的实用建议 固定模型和挂载论文缓存键包含模型名和论文列表中途频繁切换模型/上下文会让前缀缓存反复失效长任务给一个清晰的总目标根目标提取依赖消息中的User request:结构目标表述越明确压缩后的检查点越可靠重要中间结论让 Agent 落盘写入 Zotero 笔记或文档后即使转录被压缩结论也永久留存观察用量面板缓存命中率、压缩次数等遥测数据会持续记录可用于判断自己使用模式的缓存效率总结llm-for-zotero 把长对话不爆上下文拆解成三个可独立演进的部分预算策略决定何时动手转录压缩用语义检查点和工具句柄做到压缩不失忆缓存感知则按各家供应商能力最大化前缀复用。三层配合让 Zotero 里的研究 Agent 既能聊得久又花得省。核心源码索引缓存规划src/contextCache/manager.ts转录压缩src/agent/context/transcriptCompactor.ts预算策略src/agent/context/budgetPolicy.tsAgent 证据缓存src/agent/context/cacheManagement.ts运行时主入口src/agent/runtime.ts【免费下载链接】llm-for-zoteroAn open-source research agent system for your Zotero library.项目地址: https://gitcode.com/gh_mirrors/ll/llm-for-zotero创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 长对话不爆上下文：llm-for-zotero 缓存感知 Agent 与转录压缩机制完整指南
长对话不爆上下文llm-for-zotero 缓存感知 Agent 与转录压缩机制完整指南【免费下载链接】llm-for-zoteroAn open-source research agent system for your Zotero library.项目地址: https://gitcode.com/gh_mirrors/ll/llm-for-zoterollm-for-zotero是一个跑在 Zotero 里的开源研究 Agent 系统它的核心难题是如何在超长对话中不撑爆大模型的上下文窗口。这个项目用「缓存感知 转录压缩」双机制优雅解决预算策略监控上下文水位触发语义化转录压缩同时按各家模型厂商的提示词缓存Prompt Cache能力规划稳定前缀让你和 AI 的文献研读对话可以无限聊下去。一、为什么长对话一定会爆上下文任何 Agent 对话都会累积三类 Token类型来源增长特点用户消息你的每一句提问线性增长助手回复模型每次的完整输出线性增长工具结果读论文、读 PDF、执行命令返回的大段文本爆炸式增长粗暴的做法是删掉最老的消息但 Agent 会因此失忆忘了最初的研究目标、丢掉了工具调用和结果的配对关系直接报错或答非所问。llm-for-zotero 的做法是分层预算 语义压缩 缓存复用下面逐层拆解。二、上下文预算策略水位线机制压缩不是无脑触发而是由一套水位线策略控制的核心实现在 budgetPolicy.ts72%上下文水位 → 进入警告状态84%水位 → 触发转录压缩compact92%水位 → 硬限制强制收缩压缩目标 → 压到窗口容量的58%其中几个关键配比同样值得注意压缩后保留的最近尾巴占 18%语义摘要占 8%证据片段占 12%。此外还有一个回滞hysteresis机制刚压缩过的会话下次触发阈值会临时上浮 8 个百分点避免刚压完又立刻再压的抖动。这套逻辑在buildAgentContextBudgetState()中一次性算出shouldCompact、targetTokens、recentTailTokens等状态供运行时决策// src/agent/context/budgetPolicy.ts 中的默认策略 const DEFAULT_POLICY: AgentContextBudgetPolicy { warningRatio: 0.72, compactRatio: 0.84, hardRatio: 0.92, targetRatio: 0.58, recentTailRatio: 0.18, summaryRatio: 0.08, evidenceRatio: 0.12, hysteresisRatio: 0.08, minRecentMessages: 4, };三、转录压缩机制压缩后不失忆真正动手压缩的是 transcriptCompactor.ts它解决了三个经典难题。1. 切哪里——对齐到轮次边界findTailStart()从消息尾部向前扫描找出预算内能装下的最远位置然后把切点对齐到用户消息边界alignTailStartToProviderMessageBoundary()还会回退切点确保不会把助手发起工具调用 → 工具返回结果这一对消息拆开。这样模型看到的对话永远是结构完整的。2. 压成什么——语义检查点Semantic CheckpointbuildSummaryMessage()不会生成模糊的之前我们聊了……而是产出一条结构化检查点消息包含最新根目标从历史中提取User request:或上一份检查点里的根目标让 Agent 永远记得最初的研究意图最近 8 条用户消息 8 条助手消息的截断摘录各自带 messageId可按需回读原文工具使用统计例如paper_read x5, run_command x2被压缩的工具结果句柄列出所有trh_开头的 handle3. 工具结果去哪了——句柄化外存buildPortableAgentTranscript()把被丢弃的大块工具结果转存为工具结果句柄tool result handle对话里只留一行handletrh_xxx和运行摘要需要原文时 Agent 可以调用tool_result_read(handle)精确取回。摘要里还特意声明摘录不完整依赖被省略文本前先调用 conversation_read 或 tool_result_read等于给模型留了一张记忆索引卡而不是让它靠猜。这套压缩与恢复能力有专门的测试覆盖agentTranscriptCompactor.test.ts 和 agentTranscriptRecovery.test.ts。四、缓存感知把重复发送变成免费读取压缩省的是每次要发的 Token而提示词缓存省的是发送的成本和延迟。这两件事在 contextCache/manager.ts 里统一规划。1. 自动识别各家缓存能力resolvePromptCacheCapability()根据接入的供应商自动判定缓存类型供应商缓存模式遥测指标Anthropic / MiniMax显式缓存块ephemeral支持 1h TTLcache read / writeOpenAI / Codex / DeepSeek / Gemini / Kimi自动前缀匹配各自 cached tokens / 命中率其他无缓存退化为稳定前缀策略2. 稳定前缀 内容指纹buildContextCacheKey()用「供应商 : 模型 : 论文上下文列表 : 内容哈希」构造缓存键——只要模型和挂载的论文没变前缀部分就能命中缓存。同时设置了1024 Token 门槛太短的上下文开缓存得不偿失直接禁用below-cache-threshold。3. 用命中率决定 TTL 的聪明细节对 Anthropic是否启用 1 小时长缓存成本更高由shouldUseAnthropic1hCache()决定上下文至少 16000 Token、至少命中过 1 次、读次数不少于写次数、且最近命中率 ≥ 50% 才升级。这是一个典型的先观察、再花钱策略避免为一次性长上下文支付双倍缓存费。4. 证据缓存压缩之外还有一层事实记忆cacheManagement.ts 在 SQLite 里维护llm_for_zotero_agent_evidence表把读过的论文片段按会话证据键去重存储最多 12 条证据、每条 4 个片段、单片段上限 1200 字符。即使转录被压缩Agent 也能重新调出关键引文保证长对话中引用论文不翻车。五、双机制如何协同工作整个流程可以概括为一条流水线每轮请求前预算策略计算当前水位判断是否需要压缩若超阈值转录压缩器切出完整轮次尾巴 生成语义检查点大工具结果句柄化外存组装请求时缓存管理器为稳定前缀系统提示、论文上下文、工具定义规划缓存键与 TTL 提示命中缓存的部分按极低费率计费压缩保证总输入不超窗口——缓存让记住的更便宜压缩让忘掉的可找回。这套机制的完整行为有对应测试保障contextCacheManager.test.ts、agentPromptBudget.test.ts、agentRetention.test.ts。六、给使用者的实用建议 固定模型和挂载论文缓存键包含模型名和论文列表中途频繁切换模型/上下文会让前缀缓存反复失效长任务给一个清晰的总目标根目标提取依赖消息中的User request:结构目标表述越明确压缩后的检查点越可靠重要中间结论让 Agent 落盘写入 Zotero 笔记或文档后即使转录被压缩结论也永久留存观察用量面板缓存命中率、压缩次数等遥测数据会持续记录可用于判断自己使用模式的缓存效率总结llm-for-zotero 把长对话不爆上下文拆解成三个可独立演进的部分预算策略决定何时动手转录压缩用语义检查点和工具句柄做到压缩不失忆缓存感知则按各家供应商能力最大化前缀复用。三层配合让 Zotero 里的研究 Agent 既能聊得久又花得省。核心源码索引缓存规划src/contextCache/manager.ts转录压缩src/agent/context/transcriptCompactor.ts预算策略src/agent/context/budgetPolicy.tsAgent 证据缓存src/agent/context/cacheManagement.ts运行时主入口src/agent/runtime.ts【免费下载链接】llm-for-zoteroAn open-source research agent system for your Zotero library.项目地址: https://gitcode.com/gh_mirrors/ll/llm-for-zotero创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考