ccNexus: Instructions file for Claude Code

CLAUDE.md

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

项目概述

ccNexus 是一个智能 API 端点轮换代理，专为 Claude Code 和 Codex CLI 设计。

核心功能：

• 多端点轮换与自动故障转移
• API 格式转换（Claude ↔ OpenAI ↔ Gemini）
• Codex Token Pool 管理（自动轮换、刷新、失效隔离）
• 实时统计与监控
• WebDAV 云同步

两种运行模式：

• 桌面模式：基于 Wails v2 的跨平台 GUI 应用（cmd/desktop/）
• 服务器模式：无头 HTTP API 代理（cmd/server/）

常用开发命令

开发与构建

# 桌面应用开发模式（支持热重载）
cd cmd/desktop && wails dev

# 构建桌面应用（指定平台）
wails build -platform linux/amd64    # Linux
wails build -platform darwin/amd64   # macOS
wails build -platform windows/amd64  # Windows

# 构建服务器
cd cmd/server && go build -ldflags="-s -w" -o ccnexus-server .

# 运行服务器
cd cmd/server && go run main.go

测试

# 运行所有测试
go test ./... -count=1

# 运行特定目录的测试
cd internal/proxy && go test -v ./...
cd internal/transformer/convert && go test -v ./...

Docker

# 构建镜像
docker build -f cmd/server/Dockerfile -t ccnexus .

# 使用 docker-compose
cd cmd/server && docker-compose up -d

代码质量

go fmt ./...    # 格式化代码
go vet ./...    # 静态分析
go mod tidy     # 清理依赖

核心架构

目录结构

ccNexus/
├── cmd/
│   ├── desktop/          # 桌面应用入口（Wails）
│   │   ├── frontend/     # Vue.js 前端
│   │   └── main.go       # 桌面应用入口
│   └── server/           # 服务器模式入口
│       └── main.go       # 服务器入口
└── internal/
    ├── proxy/            # HTTP 代理核心
    ├── transformer/      # API 格式转换器
    ├── storage/          # SQLite 数据存储
    ├── config/           # 配置管理
    ├── webdav/           # WebDAV 同步
    ├── logger/           # 日志系统
    └── tray/             # 系统托盘（桌面模式）

关键组件

代理层 (internal/proxy/proxy.go)

• 管理多个 API 端点，自动故障转移
• 跟踪当前端点和活动请求
• 使用连接池优化的 HTTP 客户端
• 处理流式和非流式响应

转换器 (internal/transformer/)

• 在不同 API 格式之间转换请求和响应
• 支持流式传输的增量转换
• 处理工具调用和函数调用
• 类型定义：internal/transformer/types.go

存储层 (internal/storage/sqlite.go)

• SQLite WAL 模式数据库
• 管理端点、凭证、使用统计、应用配置
• 线程安全操作

关键文件路径

• 数据库：~/.ccNexus/ccnexus.db
• 配置常量：internal/config/config.go（第 13-20 行：认证模式和端点 URL）
• 代理路由：internal/proxy/proxy.go（第 108-114 行）