Compaction 与 Cache 连续性
长时间的 agent session 需要上下文管理。OpenSquilla 通过 compaction、受限历史、工具结果投影以及 cache 感知的 prompt 排布，使长期运行的任务持续推进。
Compaction 与记忆不同。记忆是持久回忆。Compaction 是活动 session 的连续性工具。
Compaction 做什么
当 session 历史接近配置的上下文预算时，OpenSquilla 可以将较旧的对话条目 compact 为一份持久摘要，并保留最近的尾部处于活动状态。
目标是保留：
- 用户目标；
- 当前状态；
- 待办步骤；
- 修改过的文件与 artifacts；
- 已知失败；
- 重要的工具结果；
- 下一步行动。
Compaction 并不保证每个旧词都对模型可见。当精确的历史文本很重要时，请导出 session 或保存文件。
用户可见的生命周期
根据表层和触发条件，用户可能会看到：
- compaction 已启动；
- compaction 已跳过；
- compaction 已完成；
- compaction 失败。
当不需要 compaction 时，OpenSquilla 会使用这条稳定信息：
Already within context budget; no compact was applied该消息是无操作，而不是失败。
何时手动 Compact
以下情况下手动 compaction 很有用：
- session 较长且你即将进入新阶段；
- 上一次工具密集的 turn 产生了大量上下文；
- UI 显示出上下文压力；
- 你希望下一次回答聚焦于当前状态而非整个对话历史。
当运行时表明 session 已在预算内时，避免反复 compact。
被动 Compaction
当 OpenSquilla 在 agent 工作之前或工作过程中检测到上下文压力时，可能发生被动 compaction。具体触发条件取决于模型上下文上限、配置的预算、当前历史以及工具输出大小。
如果被动 compaction 失败，最安全的用户应对方式通常是：
- 让当前 turn 干净地结束或失败；
- 如果精确历史很重要，导出 session；
- 用更窄的请求重试，或手动保存关键 artifacts；
- 如果失败反复出现，启用诊断。
Prompt Cache 连续性
Prompt cache 在稳定的 prompt 片段保持稳定时效果最佳。OpenSquilla 会尝试做到：
- 将稳定的 system prompt 和工具定义放在靠前位置；
- 将当前请求、易变的运行时上下文、检索到的历史和工具结果放在靠近尾部；
- 在可能影响 cache 连续性时，让模型/provider 切换通过诊断可见。
Cache 连续性是尽力而为的。路由、工具、附件、provider 变更或大量新上下文都可能降低 cache 复用率。
相关命令与表层
手动 compaction 主要在对话和 Web UI 流程中暴露。用于检查与恢复：
opensquilla sessions show <session-key>
opensquilla sessions export <session-key>
opensquilla diagnostics on与已降级的 compaction 记录相关的记忆修复面：
opensquilla memory repair list
opensquilla memory repair show --summary-id <id>
opensquilla memory raw-fallbacks list最佳实践
- 将重要的最终 artifacts 保存为文件或已发布的 artifacts。
- 将记忆用于持久偏好和可复用的项目事实。
- 用 session 导出保留精确的旧对话记录。
- 在很长的 session 进入新阶段之前使用手动 compaction。
- 不要反复 compact 一个简短或已在预算内的 session。