v0.2.6 - CCR Virtual Tool Interception Engine, xAI Grok Support & Storage Lean

Highlights

• CCR 虚拟工具网关层自闭环拦截与递归续写 — 网关在响应层直接截断 ctx_expand 虚拟工具调用，本地从指纹库毫秒级提取原文并后台自动发起续写（最大 3 轮熔断），对下游客户端 100% 零侵入。
• xAI Grok 全链路接入 — 新增 xai / grok Provider，路由、/v1/models、SSE 缓存字段解析、云端 TTL 策略与思考链生命周期全面对齐。
• 存储瘦身与折叠铁律 — 指纹库文本从 ~48.7 MB 降至 0.99 MB，物理库 88.32 MB → 21.39 MB。

Added

虚拟工具网关层自闭环拦截与递归续写 (CCR Response Interception Engine)

• 新增 VirtualToolResponseHandler 与 StreamingVirtualToolHandler（ctxguard/proxy/virtual_tool_handler.py）；
• 在网关响应拦截层截断大模型发出的 tool_calls: ctx_expand / tool_use: ctx_expand（原生支持 OpenAI 与 Anthropic 协议）；
• 网关本地直接从 FingerprintRepository 毫秒级提取原文（0 API Tokens，0.1ms），并后台自动发起第 2 轮续写请求（Continuation Request，最大 3 轮深度熔断保护）；
• 对下游客户端（Cline、RooCode、Claude Code、Cursor、Codex 等）彻底屏蔽虚拟工具调用过程，真正做到 100% 零侵入、零崩溃、无感可逆；
• 实现 RESIDUAL_CCR_SKIPPED_MIXED 混合工具安全避让：当大模型同时输出客户端工具（如 read_file）与 ctx_expand 时，网关自动放行给客户端处理；
• 实现流式前置探测（0-TTFT）：前 256 字节普通文本或 stop 时极速 flush 直通，首字延迟零劣化；检测到 ctx_expand 时无缝拦截并启动后台 continuation stream 实时转发。

xAI Grok 全链路接入 (xAI Grok 4.6 Provider Support)

• ctxguard.yaml / ctxguard.yaml.example 新增 xai / grok Provider，上游指向 https://api.x.ai/v1，凭据读取 XAI_API_KEY；
• router.resolve_provider() 新增 grok 名称识别分支，grok-* 系列模型不再静默回退至 api.anthropic.com；
• GET /v1/models 新增暴露 grok-4.6（owned_by: xai）；
• 非流式 parse_cache_stats() 与流式 sse.py 同步新增 Grok / xAI / vLLM 缓存字段解析（cache_type: grok_cache）；
• CacheGuard 新增 grok 维度云端缓存 TTL 表项；
• ThinkingManager 覆盖 Grok 3 Think 思考链生命周期，跨轮次精准修剪历史 reasoning 块。

发布文档与物料同步

• README 更新 Dashboard 截图与真实生产环境累计实测数据（10,868 请求 / 1,742,154,963 原始 Tokens / 65.97% 压缩率）与测试徽章（224 passed）；
• 系统架构图新增 xAI Grok 上游席位（采用官方 xAI 标志）；
• 对齐 tests/test_context_tracker.py 中 3 个陈旧用例，并修正 ContextTracker.format_proactive_expansion 与调用方之间 workspace_key 参数名漂移。

Fixed

• xAI / Grok 通道 Cloudflare 400 修复（重复 Authorization 请求头）：upstream.build_headers() 透传客户端鉴权头时与 Provider 侧注入的 Authorization 并存产生重复头，Cloudflare 边缘节点直接返回 400；现改为确定性去重。
• 全压缩器纯净占位符清洗（No-Deception Placeholder Cleanup）：tool_injection.enabled: false 时彻底清洗 5 个压缩模块（tool_delta、git_diff、ast_code、log_truncator、dedup）中的折叠占位符，严禁输出任何 Use ctx_expand 诱导文本。
• 单会话指纹去重铁律与消除跨会话致盲（Storage Invariant 2）：废除 DedupCompressor 跨会话全局查库去重，去重判断严格锁定当前会话作用域；确保新会话首读 100% 全量放行原文。
• 跨会话内容指纹库深度瘦身与全压缩器单写治理（Storage Lean & Fold-Only Persistence）：
  • 修复 5 大压缩算子同时写入 64-char sha 与 12-char short_sha 的双重写入 Bug，重构为仅单写 12 位 short_sha；
  • 确立"仅折叠入库"铁律（Storage Invariant 3）；
  • FingerprintRepository 默认容量上限 10,000 → 1,000，淘汰批次 250 → 50，原生支持长短哈希双向智能前缀检索；
  • 新增 purge_and_vacuum(keep_limit=1000)，指纹库文本 ~48.7 MB → 0.99 MB，物理库 88.32 MB → 21.39 MB。

Upgrade Notes

• dedup.max_records 默认值下调为 1000；老库可执行一次 purge_and_vacuum() 完成瘦身。
• 使用 xAI Grok 需配置环境变量 XAI_API_KEY。

---

完整变更见 CHANGELOG.md。

v0.2.3 - Multi-Worker Distributed Session Cache, In-Memory Hot LRU & Async Offloading

Release v0.2.3: Multi-Worker Distributed Session Cache, In-Memory Hot LRU & Async Offloading

🚀 Highlights & Breakthroughs

1. 多 Worker 进程分布式前缀共享与 0 缓存击穿彻底解决 (Distributed Session Cache Guard)

   • 彻底定位并消除了多 Worker 轮询分发时的跨进程内存隔离导致的间歇性 0 缓存击穿现象。
   • 在 SQLite WAL 库中新增 session_cache 表与 idx_session_cache_updated 复合索引，构建 L1 RAM Hot + L2 SQLite WAL 双级热同步架构。
   • 路由层全面引入 pipeline.cache_guard.has_compressed_history(session_id) 跨进程历史感知，彻底杜绝客户端未序列化原始报文（raw body_bytes）直通发往上游导致 KV Cache 瞬间清零的隐患。

2. 纯内存热 LRU 缓存与宿主机 SSD 零写磨损 (In-Memory Hot LRU & Zero SSD Wear)

   • 参照 Headroom 内存优先架构，引入 10,000 条容量的 Python OrderedDict 纯内存热缓存，指纹读取 100% 纳秒级 O(1) 命中，杜绝高频磁盘 I/O。
   • SQLite 持久化改为每 250 次写入批量惰性淘汰，并新增 idx_fingerprints_lru 复合索引加速范围扫描。
   • 历史前缀去重跳过（if sha in fingerprint_store: continue），长会话磁盘事务写入次数削减 99% 以上。

3. CPU 密集流水线异步多线程卸载 (Async Pipeline Offloading)

   • 重构 Pipeline.process 为异步方法，使用 asyncio.to_thread 将 AST 代码树解析、正则分词与 SHA-256 哈希计算卸载到底层工作线程池。
   • 彻底释放主 asyncio 事件循环，彻底消除长会话大请求阻塞其他并发 Agent 请求的排队延迟问题。
   • CLI 新增 -w / --workers 参数，支持 Uvicorn 多进程并行加速，充分利用多核 CPU。

4. 系统提示词不可变性与通用清洗算子安全守卫

   • 严格落实 Cache Invariant 2，在 BaseCompressor.process 基类中显式跳过 system 与 developer 角色消息，守住字节级不变性。

5. 官方文档中心精简与架构沉淀

   • 清理多余冲突目录与过时副本，统一以 docs/ 为标准文档中心。
   • 新增踩坑 13（多 Worker 内存隔离与缓存击穿）、踩坑 14（通用算子角色守卫）以及面试 Q10、Q11 问答。

🧪 Test & Validation

• 145 passed (120 unit tests + 25 integration tests 100% pass rate).

v0.2.2 - Codex Responses Native, Stream Transport Isolation & Cache Guard

CtxGuard v0.2.2: Codex Responses 原生通道支持、并发流物理隔离与 Prompt Cache 守卫

CtxGuard v0.2.2 是一次针对生产级真实开发环境的高可靠性版本更新。本版本深度攻克了 Codex 桌面版/CLI 原生通信协议壁垒、解决了多并发流式断连问题，并彻底修复了多轮会话云端 Prompt Cache 缓存个位数下跌的根因，保障长链路 AI Agent 编码过程中的零卡顿与稳定缓存加速。

---

核心新特性与优化亮点

1. Codex Responses API 原生透明通道 (Transparent Passthrough)

• 废弃强制降级转换：对原生支持 Responses API 规范的上游中转服务直接透传，不再强制转译为 ChatCompletions，保留最纯正的 Codex 协议交互。
• 完整保留 Codex 专有工具与数据结构：修复 custom_tool_call 与 custom_tool_call_output 在代理层被意外截断丢失的问题，保证 Codex 读取终端、读写文件及执行代码的全部系统级工具链 100% 正常调用。
• 完整闭合 SSE 事件序列：保留并精准闭合 response.created、response.output_item.added、response.text.delta、response.output_item.done 与 response.completed，彻底根除客户端界面出现空白卡顿的现象。

2. 并发流独立客户端物理隔离 (Stream Transport Isolation)

• 请求级独立连接池：针对流式请求引入独立的 HTTP 客户端生命周期管理，每个 SSE 流使用独立的会话实例，彻底杜绝并发场景下连接池交叉影响。
• 解决桌面端双并发绞杀：Codex 桌面端在发起主对话（gpt-5.6-sol）的同时会高频并发触发会话标题生成（gpt-5.6-luna）。修复了全局 client 异常调用导致主连接中断并报 stream disconnected before completion: Transport error: network error: error decoding response body 的严重问题。
• 轻量模型智能兼容重映射：自动将上游不支持的 Codex 专用标题模型 gpt-5.6-luna 透明重映射为稳定快速的 gpt-5.5，使桌面端双路请求 100% 成功。
• 本地代理智能嗅探：自动识别本地 Clash / Clash Verge 代理端口（http://127.0.0.1:7897），并在代理故障时安全降级回退。

3. 多轮会话 Prompt Cache 缓存守卫加固 (Cache Invariant 1 & 2)

• 严格遵循 Cache Invariant 1（禁止原始 Body 穿透）：当会话在首轮建立压缩历史后，后续请求禁止直接透传客户端原始 body_bytes，强制将一致序列化后的压缩前缀注入 raw_body，彻底解决后续轮次云端 KV Cache 命中数跌至个位数的问题。
• 严格遵循 Cache Invariant 2（系统与开发者指令绝对不可变）：对 developer / system 角色内容实施绝对不可变保护，防止语义剪枝或引用替换破坏系统提示词一致性。
• SSE 跨厂商 Usage 精准解析：全面支持解析 OpenAI 格式、DeepSeek、Gemini 以及 Responses 格式下的 cached_tokens，精准记录并在控制面板实时呈现云端缓存命中指标。

---

自动化测试与工程质量

• 测试用例扩充：新增 Codex 原生 Responses 流式透传、双路并发流隔离防断连、developer 指令缓存守卫不变性等回归测试。
• 100% 测试通过率：全量 169/169 自动化单元测试与端到端测试全部绿灯通过（耗时 6.19s）。

---

安装与使用

# 方式一：从 GitHub Releases 附件 Wheel 包直接安装
pip install ctxguard-0.2.2-py3-none-any.whl

# 方式二：直接从 GitHub 仓库安装最新主分支
pip install -U git+https://github.com/255308153/CtxGuard.git

# 启动代理网关
ctxguard start --port 8787

v0.2.0 - Multi-Language Tree-sitter AST, Tool Delta Shadow State & CoT Manager

CtxGuard v0.2.0: 工业级多语言 AST、影子状态增量差分与智能守护系统

CtxGuard v0.2.0 是一次重磅架构升级，深度融合并超越了业界顶级上下文优化方案，全面引入了基于 Tree-sitter 纯 C 绑定的多语言 AST 代码骨架引擎、会话级 Tool Delta 影子状态机增量差分、终端超长日志智能截断、跨厂商思考链生命周期治理以及敏感凭证安全脱敏器。

---

核心新特性与优化亮点

1. 工业级 Tree-sitter 纯 C 多语言 AST 代码骨架引擎 (TreeSitterSkeletonizer)

• 9+ 门语言原生支持：Python, JavaScript, TypeScript, TSX, Go, Rust, Java, C, C++ 毫秒级语法树解析。
• 微秒级性能：基于官方预编译纯 C 绑定，单文件解析耗时 < 1ms，比纯 Python AST 方案快 5~10 倍。
• 100% 语法鲁棒性：逐字节精准定位函数与类体，完美免疫注释括号、模板字符串及 JSX 嵌套。
• 无损可逆展开：提取签名与 Docstring，折叠实现体并存入本地 SQLite 指纹池，支持通过 ctx_expand 随时无损调阅。

2. Tool 调用影子状态机与增量差分器 (ToolDeltaCompressor)

• 会话级影子快照：维护每个 Session 的环境与文件状态快照（针对 list_dir、find_by_name、git status 等探针指令）。
• Jaccard 集合相似度探测：智能识别同源状态探测（相似度 >= 0.5 触发）。
• 集合增量差分：精确计算 + Added 与 - Removed 项，折叠海量未变更条目为 ... (K items unchanged)，将 2500+ Tokens 的状态刷新压缩至 30 Tokens（Token 消耗削减 90%+）。

3. 终端超长日志全局 Head-Tail 智能截断器 (LogTruncator)

• 针对超长构建与测试日志：自动识别 npm test、cargo build、pip install 产生的数千行长日志。
• 智能滑动窗口：保留头部 25 行（环境参数、版本信息）与尾部 75 行（核心报错堆栈与退出代码），中间折叠并存入指纹池（Token 消耗降低 80%+）。

4. 跨轮次思考链（CoT / Thinking）生命周期治理 (ThinkingManager)

• DeepSeek-R1：多轮历史中自动剥离 reasoning_content 与 标签，严格遵守 DeepSeek 官方规范，杜绝思考过程二次计费。
• Google Gemini：自动剔除历史 块，保持 Payload 纯净。
• Anthropic Claude 3.7：在前置窗口内保留 thinking + signature 保证 100% 享受官方 KV Cache 缓存折扣；当思考累积超限（默认 16K）或冷重整时安全修剪历史废弃思考，杜绝爆窗。

5. 敏感数据与 API 密钥安全脱敏器 (SecretRedactor)

• 多凭证类型识别：自动拦截并脱敏 OpenAI / Anthropic / GitHub / AWS / JWT 密钥及 Bearer Tokens。
• 私钥与证书保护：PEM 私钥证书与数据库连接密码自动打码，杜绝明文凭据外泄至云端。

---

自动化测试与工程质量

• 测试用例：全量 156/156 单元测试与端到端测试 100% 通过（耗时 4.36s）。
• 零外部服务依赖：纯 Python + C 扩展架构，无需 Docker / Redis / Milvus，单文件免运维。

---

安装与使用

# 方式一：从 Release 附件 Wheel 包直接安装
pip install ctxguard-0.2.0-py3-none-any.whl

# 方式二：直接从 GitHub 仓库安装
pip install -U git+https://github.com/255308153/CtxGuard.git

# 启动代理网关
ctxguard start --port 8787