ccx: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with this repository.

项目概述

CCX 是一个支持 Claude、OpenAI Chat、OpenAI Images、OpenAI Embeddings、Codex Responses 和 Gemini 的多上游 AI API 代理与协议转换网关，提供统一代理入口和 Web 管理界面。

技术栈: Go 1.25 + Gin（后端）+ Vue 3 + Vuetify 3 + TypeScript（前端）+ Docker
版本管理: 根目录 VERSION 是唯一版本源，构建时通过 backend-go/Makefile 的 -ldflags 注入运行时版本信息。

常用命令

# 根目录（推荐）
make dev              # 同时启动前端开发服务器和后端热重载
make run              # 构建前端并运行 Go 后端
make frontend-dev     # 前端开发服务器
make build            # 构建前端并编译 Go 后端
make clean            # 清理构建文件

# Go 后端开发 (backend-go/)
make dev              # 热重载开发模式
make run              # 复制前端产物后直接运行
make build            # 构建生产版本
make test             # 运行所有测试
make test-cover       # 测试 + 覆盖率报告
make fmt              # 格式化代码
make lint             # 代码检查
make deps             # 更新依赖

# 前端开发 (frontend/)
bun install
bun run dev
bun run build
bun run type-check

架构概览

Client -> backend :3000 ->
  |- /                            -> Web UI
  |- /api/*                       -> Admin API
  |- /v1/messages                 -> Claude Messages proxy
  |- /v1/chat/completions         -> OpenAI Chat proxy
  |- /v1/responses                -> Codex Responses proxy
  |- /v1/images/{...}             -> OpenAI Images proxy
  |- /v1/embeddings               -> OpenAI Embeddings proxy
  |- /v1/models                   -> Models API
  `- /v1beta/models/*             -> Gemini proxy

六类正式渠道：

• messages
• chat
• responses
• gemini
• images
• vectors

核心设计模式

1. Provider Pattern - backend-go/internal/providers/ 负责上游请求构造与响应处理。
2. Converter Pattern - backend-go/internal/converters/ 负责 Responses 场景的协议转换。
3. Session Manager - backend-go/internal/session/ 负责 Responses 多轮会话与 Trace 亲和性。
4. Scheduler Pattern - backend-go/internal/scheduler/ 负责优先级、促销期、熔断与故障转移。

API 总览

代理入口

• POST /v1/messages
• POST /v1/messages/count_tokens
• POST /v1/chat/completions
• POST /v1/responses
• POST /v1/responses/compact
• GET /v1/models
• GET /v1/models/:model
• POST /v1beta/models/{model}:generateContent
• POST /v1/images/generations
• POST /v1/images/edits
• POST /v1/images/variations
• POST /v1/embeddings
• GET /health