Home

CCProxy Agent Wiki

CCProxy Agent 是运行在 Claude Code / Claude Desktop 与 CC Switch / 模型服务 之间的本地上下文保护网关。

它不替代 Claude Agent，也不试图重写 Claude 的原生 /compact。它的职责是在请求进入上游模型前保护 Token 预算、Agent 工具协议、多模态输入和路由配置，并在上游拒绝请求时执行一次可解释、可观测的恢复。

当前稳定版本：v0.4.92。当前定位是可日常使用的单用户 Windows 桌面应用，不是面向公网或多租户的企业网关。

为什么需要它

长时间编码会话常见的问题不是模型能力不足，而是请求在到达模型前已经失控：工具输出持续堆积、Token 估算与提供商统计不一致、原生 compact 触发过晚、图片占满上下文、CC Switch 端口变化，最终形成 198977 input + 1024 output > 200000 一类错误。

直接删除消息又会破坏 tool_use / tool_result 对应关系，使模型重复读取同一文件。CCProxy Agent 的核心价值是：在保留协议结构和最新证据的前提下，为请求腾出可用上下文空间。

核心能力

• 自动接管 Claude Code API Base URL 与 Observer Hooks。
• 自动接管 Claude Desktop 3P Gateway，并监控 CC Switch 配置漂移。
• 自动探测本地可用监听端口和 CC Switch 上游。
• 对完整结构化请求估算 Token，而不是只计算聊天文本。
• Agent 请求保持工具协议，不执行破坏性的通用文本压缩。
• 上下文 400 后只重试一次，避免代理层无限循环。
• 最新超长工具结果保留头尾证据，不整条清空。
• 图片先经过 Vision 模型转换为文本摘要，再进入主模型。
• 单一 EXE 管理启动、停止、配置、日志和保护事件。

阅读导航

• Business-Pain-Points：产品解决的真实问题与边界。
• Architecture：系统组件、控制面和数据面。
• Request-Lifecycle：一次请求从 Claude 到上游再返回的完整业务逻辑。
• Context-Recovery：Token 预算、compact、工具结果清理和 400 救援。
• Multimodal-Routing：图片提取、Vision 对比和摘要注入。
• Claude-Integration：Claude Code、Desktop、Hooks 和配置恢复。
• Configuration：配置字段和推荐阈值。
• Operations：启动、关闭、日志与排障。
• Security：本地监听、Hook token 和密钥边界。
• Testing-and-Releases：测试矩阵、EXE 烟测和发布流程。
• Production-Roadmap：从桌面稳定版演进到生产级架构。

能力边界

CCProxy Agent 不是模型 API 聚合计费系统，不保存完整聊天内容，不替代 CC Switch，也不会承诺任意超大 Agent 会话都能无损恢复。当请求已经超过上游硬限制时，任何恢复都必须在“保留信息”和“请求可发送”之间做取舍；本项目优先保留工具协议、最新结果头尾和用户最近意图。