前言¶
在本地模型推理場景中，上下文窗口達到上限會導致請求被拒絕，進而中斷正在進行的會話。傳統的壓縮方案往往難以穩定工作，或者無法滿足對歷史細節的檢索需求。
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 上獲取源碼。
