Trellis上下文注入或导致缓存命中率下降
速览
用户发现Trellis 0.6.5在每次请求前通过buildContext()动态注入task文档内容到系统提示词，导致系统提示词变化，缓存命中率从1.3万骤降至3千。建议修改task文件后开新对话，或修改源码将注入改为用户消息。该设计影响token开支和缓存效率，需开发者注意。
AI 深度解读
背景
在 AI 应用的实际部署中，缓存（Cache）机制是降低 Token 开销、提升响应速度的关键手段。尤其是当用户通过 API 调用大语言模型（LLM）时，上游渠道（如 OpenAI、Azure、Anthropic 等）通常会根据请求中系统提示词（System Prompt）的哈希值或内容一致性来缓存计算结果。一旦系统提示词发生变动，缓存便会失效，导致后续请求需要重新计算，从而增加 Token 消耗和响应延迟。
Trellis 是一个基于大语言模型的多轮对话框架，支持动态注入任务上下文。近期有用户在 LINUX DO 论坛反映，在 Trellis 0.6.5 版本及特定环境（如 pi）下，发现了一个可稳定复现的缓存下降问题：第一次请求缓存命中约 1.3 万 Token，第二次请求可能跌至 3000 Token，第三次则完全重建缓存。该现象与 Trellis 内部的上下文注入机制密切相关。
核心内容
原帖作者通过数天的日志排查和现象观察，定位到缓存下降的根本原因在于 Trellis 的 before_agent_start 钩子函数。该钩子每次都会调用 buildContext() 方法，动态地将任务（task）相关的文档内容（如 PRD、需求说明等）注入到系统提示词（System Prompt）中。
具体流程如下：
- 用户在对话中引用某个 task，task 包含需要注入的文档（如 PRD、设计文档等）。
- 每次用户发送新消息前，Trellis 都会重新执行
buildContext()，将当前 task 中最新版本的文档内容拼接到系统提示词里。 - 如果用户在对话过程中修改了 task 关联的文档（例如编辑了 PRD 内容），那么下次发送消息时，系统提示词的内容就会发生变化（哪怕只是微小的改动）。
- 由于系统提示词是缓存命中的关键依据，一旦内容改变，上游渠道（如 OpenAI 的 API 缓存）就会认为这是一个全新的请求，导致缓存失效，从而出现 Token 命中量骤降的现象。
作者进一步指出，缓存下降了并不代表客户端缓存有问题，也可能是上游渠道的缓存策略导致的。但无论如何，这一现象对 Token 开支敏感的用户来说影响显著。
针对该问题，作者给出了自己的临时解决方案：
- 如果观察到对 task 相关文件有改动（如修改了 PRD），就开启一个新对话（continue），而不是继续原有的对话。这样能避免因系统提示词中途变化而导致的缓存失效。
- 作者也提到，理论上可以直接修改 Trellis 源码，将
buildContext()注入的内容改为注入到用户消息（User Message）中，而不是系统提示词。但考虑到 Trellis 的设计初衷，作者没有进行这种改动。
关键要点
- Trellis 的
before_agent_start钩子每次都会调用buildContext()，将 task 文档动态注入系统提示词，而非在对话开始时一次性注入。 - 系统提示词的内容随 task 文档的修改而变化，导致上游缓存失效，表现为 Token 命中量从 1.3 万跌至 3000 左右。
- 缓存下降可能由客户端缓存或上游渠道缓存引起，但作者观察到的现象更倾向于上游缓存失效。
- 临时解决方案：在修改 task 文档后，启动新对话（continue）而非继续原对话，以保持系统提示词的一致性。
- 可选的改进方向：将注入内容改为用户消息（User Message），因为用户消息的变化通常不会影响缓存命中（取决于上游策略），但作者未实际实施。
- 该问题在 Trellis 0.6.5 及特定环境（如 pi）下可稳定复现，其他版本或环境可能存在差异。
意义与影响
该发现对使用 Trellis 进行多轮对话或任务驱动的 AI 应用开发者具有重要参考价值。首先，它揭示了动态上下文注入对缓存效率的潜在风险：如果系统提示词频繁变化，缓存优势将大打折扣，Token 成本会显著上升。对于按 Token 计费的 API 用户，这种开销可能变得不可忽视。
其次，该问题提醒开发者注意框架设计中的缓存友好性。Trellis 的设计初衷可能是为了确保每次对话都能获取最新的任务上下文，但这种灵活性与缓存效率之间存在权衡。作者提出的“开新对话”方案虽然简单，但在实际工作流中可能增加操作复杂度，尤其当用户需要频繁修改任务文档时。
此外，该现象也反映了上游渠道缓存策略的局限性——系统提示词的任何微小变化都会导致缓存失效。如果上游渠道能支持更细粒度的缓存（如仅检查用户消息部分），或者 Trellis 提供更稳定的系统提示词生成策略，或许能缓解这一问题。
最后，该讨论为社区提供了一种自检思路：当遇到 Token 消耗异常或响应速度突然变慢时，可以检查系统提示词是否在对话过程中被动态修改，从而快速定位缓存失效的原因。开发者也可据此评估是否需要修改 Trellis 源码或调整自身使用习惯。