前言¶
在本地模型推理场景中，上下文窗口达到上限会导致请求被拒绝，进而中断正在进行的会话。传统的压缩方案往往难以稳定工作，或者无法满足对历史细节的检索需求。
Context Guardian 旨在解决这个问题。它提供了两种工作模式：一种是通过 OpenAI 兼容代理前置在本地模型（如 Ollama、vLLM）前的方案；另一种是 DeepSeek Harness (DSH) 原生引擎。两者均采用确定性压缩策略，确保在压缩上下文时不会导致会话崩溃，并将原始数据完整保存在磁盘上，支持对已归档细节的检索。
是什么¶
Context Guardian 是由 LuminariSoftwares 维护的一个插件。其核心功能是解决本地模型因上下文溢出而导致的会话中断问题。
该项目采用 MIT 许可证。它通过 Python 实现代理服务，并提供了一套与 DeepSeek Harness 集成的原生引擎，支持对上下文进行确定性压缩和归档管理。
核心功能¶
Context Guardian 包含以下核心能力：
- OpenAI 兼容代理：作为代理服务运行，支持 Ollama、LM Studio、vLLM、LiteLLM 等本地后端。
- DeepSeek Harness 原生引擎：作为 DSH 的插件集成，提供上下文压缩功能。
- 确定性压缩：在上下文达到阈值时执行压缩操作。
- 失败即开放（Fails Open）：即使在压缩失败的情况下，也会保持会话可用，不会导致会话崩溃。
- 磁盘持久化：在压缩过程中，原始数据会完整保存在磁盘上。
- 历史细节检索：支持通过特定关键词检索已归档的上下文细节。
安装与启用¶
安装代理¶
首先通过 pip 安装并启动代理服务。该代理默认监听 8786 端口。
pip install context-guardian && context-guardian
配置 DeepSeek Harness¶
Context Guardian 提供了原生 DSH 引擎。用户需在 DSH 的 Agent 预设中添加对应的引擎配置，以启用确定性压缩功能。
典型用法¶
配置上游模型¶
在使用代理模式时，需要通过环境变量指定上游本地模型的地址。
GUARDIAN_UPSTREAM_URL=http://localhost:11434/v1
配置客户端¶
如果你的客户端（如 Claude Code）需要指向该代理，请设置以下环境变量：
ANTHROPIC_BASE_URL=http://localhost:8786
检索已归档上下文¶
在会话运行过程中，可以使用命令检索之前被归档的原始上下文细节。
context-guardian-recall "<term>"
适用场景与注意¶
适用场景：
* 本地模型上下文窗口有限，需要长期维持会话的场景。
* 需要在压缩上下文的同时，保留历史关键信息以便随时调用的场景。
注意事项：
* 兼容性：LM Studio、vLLM 和 LiteLLM 被预期可以工作，但目前尚未经过完整测试。
* 环境变量配置：必须将 GUARDIAN_NUM_CTX 设置为模型实际支持的上下文窗口大小。
* API 支持：当配置了代理并指向 Anthropic Messages API 时，代理会对该接口进行压缩处理。
短结尾¶
Context Guardian 为本地模型推理提供了一个稳定、确定性的上下文管理方案。无论是作为代理还是 DSH 引擎，它都能有效防止会话因上下文溢出而中断，同时保留了完整的历史数据供后续检索。你可以通过目录页查看更多插件信息，或在 GitHub 上获取源码。
