Skip to content

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

Choose a tag to compare

View all tags
@255308153 255308153 released this 17 Sep 15:20
· 14 commits to main since this release
v0.2.2
c158289

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
Assets 4
Loading