ccx: Instructions file for Codex

仓库协作指南

重要约定

• 始终使用简体中文回复。
• 遵循 SOLID / KISS / DRY / YAGNI；优先修复根因，避免无关重构。
• 禁止停止或杀掉本项目正在运行的服务进程；默认用户已通过开发命令启动服务，如需让代码生效，只能提示用户手动重启或使用用户明确指定的安全方式。
• 修改文档时，优先以以下文件为事实源：VERSION、Makefile、backend-go/Makefile、frontend/package.json、backend-go/main.go。

项目概览

• CCX 是一个多上游 AI API 代理与协议转换网关，当前正式支持六类渠道：messages、chat、responses、gemini、images、vectors。
• 根目录 VERSION 是唯一发布版本源；后端构建时通过 backend-go/Makefile 的 -ldflags 注入运行时版本信息。

项目结构与模块

• backend-go/：主 Go 服务（Gin），负责路由、认证、调度、协议转换、指标与日志；前端构建产物嵌入到 backend-go/frontend/dist/。
• frontend/：Vue 3 + Vite + Vuetify 管理界面。
• dist/：发布构建产物，禁止手动编辑。
• .config/：运行时配置与持久化目录（如 config.json、metrics.db、backups/）。
• refs/：外部参考项目存档，仅供对照，默认只读。
• 文档入口：README.md、README.zh-CN.md、backend-go/README.md、docs/guide/architecture.md、docs/guide/development.md、docs/guide/environment.md、docs/guide/release.md。

构建 / 测试 / 开发命令

• 全栈开发（推荐）：根目录 make dev（前端 bun run dev + 后端 air 热重载）。
• 根目录常用命令：make run、make build、make frontend-dev、make clean。
• 仅后端：cd backend-go && make dev|run|build|test|test-cover|fmt|lint|deps。
• 后端本地构建：cd backend-go && make build-local。
• 前端：cd frontend && bun install 后执行 bun run dev|build|preview|type-check|lint。
• Docker：docker-compose up -d 用于接近生产环境的验证。

代码风格

• Go：保持包职责单一、接口清晰；修改后运行 go fmt ./...。
• 前端：遵循现有 Vuetify / TypeScript / Prettier 风格；保持 strict 类型约束。
• 不要手动编辑生成产物：dist/、frontend/dist/、backend-go/frontend/dist/。
• 配置/密钥：.env / .json 只提交示例文件或文档化内容，禁止提交真实密钥。

路由与能力边界

• 实际代理与管理路由以 backend-go/main.go 为准。
• 常见代理入口包括：
  • /v1/messages
  • /v1/chat/completions
  • /v1/responses
  • /v1/images/generations
  • /v1/images/edits
  • /v1/images/variations
  • /v1/embeddings
  • /v1beta/models/*
  • /v1/alpha/*（Codex 记忆层 history/notes 透传，粘 Responses 渠道池；上游未实现时如实透传错误）
• 管理入口统一位于 /api/{type}/channels/*。
• 能力测试当前只适用于 messages、chat、responses、gemini；不要假设 images 或 vectors 具备 capability-test。
• 渠道保活验证位于 backend-go/internal/healthcheck/：L1（带 key 拉模型列表）六类渠道通用，L2（最便宜模型的普通真实调用）仅 messages、chat、responses、gemini；配置为全局/渠道级 healthCheck，频率硬下限 30 分钟；管理端点 GET /api/{type}/channels/:id/health 与 POST /api/{type}/channels/:id/health/check。
• 上游余额探测位于 backend-go/internal/balanceprobe/（探测器在 internal/upstreamprobe/balance.go）：用渠道 key 查上游剩余额度（auto/newapi_token/sub2api/newapi_billing），六类渠道通用；配置为全局/渠道级 balanceCheck，newapi 订阅托管渠道默认开启 auto，间隔硬下限 30 分钟；结果落 key_health（check_kind=balance）并聚合写配额真相 provider_api 级参与调度；管理端点 GET /api/{type}/channels/:id/balance 与 POST /api/{type}/channels/:id/balance/check。