CtxGuard - 面向 AI Agent 的上下文治理与缓存加速反向代理网关

CtxGuard 是一个部署在客户端与大模型服务商之间的透明反向代理网关，目标是在不改动业务代码的前提下，对 AI Agent 发出的请求做上下文治理与缓存加速。据项目自述，在 Claude Code、Cursor、Codex 这类长链路编码 Agent 的使用场景中，工具调用频繁执行会让请求上下文迅速膨胀：未修改的代码差异、冗长的构建日志、重复的状态探测输出与历史思考链都会持续占用上下文窗口，推高 Token 费用；同时客户端工具定义的无序序列化与动态提示词拼接，容易让服务商的前缀缓存（Prompt Cache）频繁失效。CtxGuard 试图在协议中转层解决这两个问题，适合需要长期运行 Agent、对 Token 成本与响应延迟敏感的开发者和团队。

维护者与状态

项目由 255308153 维护，仓库创建于 2026-09-14，最后一次提交为 2026-10-08。最新 release 为 v0.2.6，发布于 2026-09-18。截至 2026-10-10，仓库星标数为 202。许可证为 MIT。

主要能力

以下能力均来自项目自述，尚未经过独立验证。

前缀防抖与 Prompt Cache 保活

据项目说明，CtxGuard 对多轮对话中未变更的历史消息跳过反序列化与字典重构，直接转发原始 HTTP 请求的底层二进制切片，以避免空格、换行符与浮点格式漂移；同时在网关层递归遍历 tools 列表及其内部 JSON Schema 定义，按字母序做确定性重排序，以解决客户端字典无序导致的前缀缓存击穿。项目还称将上下文划分为静态系统区与动态交互区，会话建立后锁定头部提示词快照，动态注入项只追加在末尾活跃窗口。

Tree-sitter 多语言语法树引擎

项目自述内置 TreeSitterSkeletonizer，采用官方预编译的纯 C 语言 Tree-sitter 绑定，覆盖 Python、JavaScript、TypeScript、TSX、Go、Rust、Java、C、C++ 等语言，逐字节提取函数与类签名及 Docstring；当解析器不可用时，可回退到 Python 原生 ast。

敏感数据脱敏

据项目说明，SecretRedactor 模块会自动拦截并脱敏 OpenAI、Anthropic、GitHub、AWS、JWT 密钥及 Bearer Token，并对 PEM 私钥证书与包含密码的数据库连接字符串自动打码。

可逆内容指纹池与响应拦截

项目自述在网关层拦截云端模型发出的 tool_calls: ctx_expand，在本地提取原文并自动发起第二轮续写请求，对下游客户端屏蔽虚拟工具调用过程，以避免 Tool not found 报错。内容去重严格限定在单会话内，新会话首次读取文件全量放行；热点指纹索引基于 OrderedDict 维护在内存中，容量由 dedup.max_records 控制，默认 1,000 条。项目还称只把真正被折叠的内容写入 SQLite，未折叠的普通对话与历史前缀不落盘。

时序知识图谱与自进化学习

据项目说明，学习引擎以插件形式解耦为 ClaudePlugin、CtxGuardGatewayPlugin、GeminiPlugin、CodexPlugin，可离线扫描 Claude Code、Gemini CLI、Codex 等外部工具轨迹，也能接入网关自身中转的多 Agent 请求。分析器分三级：Tier 1 通过 LiteLLM 或目标大模型做语义分析；Tier 2 自动检测并调用宿主机已安装的 claude -p、gemini -p、codex exec 命令行，复用终端现有订阅权限；Tier 3 在断网或无模型环境下降级为本地规则提取。项目称学习前会反向解析项目现有的 AGENTS.md、.cursorrules 等规则文件，新规则增量更新，本轮未触发的历史规则自动结转保留。检索侧结合 BM25 词频、稠密向量嵌入与图谱实体关联做三路加权打分。

监控控制台

项目自述提供 Web Dashboard，默认地址为 http://127.0.0.1:8787/dashboard，可查看全局 Token 流向、会话压缩曲线、知识图谱与规则库。

使用入口

仓库地址：https://github.com/255308153/CtxGuard

据项目说明，安装方式为克隆仓库后本地安装：

git clone https://github.com/255308153/CtxGuard.git
cd CtxGuard
pip install -e .

启动网关：

ctxguard start --port 8787
ctxguard start --port 8787 -w 4

项目自述提供四种客户端接入方式：ctxguard wrap claude 等命令可直接拉起 Agent 并自动探测上游配置；eval $(ctxguard env --eval) 可在当前终端会话注入环境变量；ctxguard env --patch 可改写本地客户端配置指向代理网关；也可手动把兼容 OpenAI 或 Anthropic 协议的工具指向 http://127.0.0.1:8787/v1 或 http://127.0.0.1:8787。项目还列出 ctxguard stats、ctxguard savings、ctxguard learn --dry-run、ctxguard learn --apply 等命令，用于查看吞吐与节约明细、预览或写入学习结果。

许可与限制

许可证为 MIT。

关于适用边界，项目自述对 Anthropic 与 DeepSeek 的思考内容默认实施 100% 透传保真，以避免修改思考内容引发 Anthropic 400 签名错误；冷热双态生命周期在热会话期间锁定已缓存前缀，仅在闲置超时且显式配置时才执行全量基线重塑。项目说明中提到的配置项包括 piggyback_extraction、learn、output_shaper、adaptive_pipeline 等开关，其中输出端塑造默认关闭。需要说明的是，素材中给出的压缩率、延迟、Token 节省与成本节省等数字均为项目自述的测试与统计结果，本站未做独立复现，读者应自行评估；项目也未在素材中说明具体的硬件要求与支持的操作系统范围。