CCX 本地开发指南：从环境搭建到热重载联调与基准数据更新

本文档面向 CCX（Claude / Codex / Gemini API Proxy）的开发者，系统讲解如何从零搭建本地开发环境、选择适合的开发方式（根目录 Make / 后端专项 / 前端专项）、理解 Go 后端的文件变更与热重载规则，并在提交前完成构建、测试、Lint 等验证流程，最后介绍模型能力基准数据的自动更新方法。读完本文，你将掌握一套可复现、可验证的 CCX 本地开发工作流。

环境准备

前置依赖

CCX 采用 Go 后端 + Bun 前端 + Make 构建的标准技术栈，开始开发前请确保以下工具就绪：

工具	最低版本	安装方式 (macOS)	安装方式 (Linux)	说明
Go	1.25	brew install go	go.dev/dl	后端编译与运行
Bun	1.x	brew install oven-sh/bun/bun	curl -fsSL https://bun.sh/install | bash	前端依赖管理与构建
Git	-	Xcode CLT 自带	apt install git / yum install git	版本管理
Make	-	Xcode CLT 自带	通常已预装	构建脚本

macOS 用户如果还没有 Xcode Command Line Tools，先执行：

xcode-select --install

一键安装所有依赖

项目根目录 Makefile 提供了 make install 目标，它会依次完成：

1. cd frontend && bun install——安装 Vue 3 + Vuetify 前端依赖；
2. cd desktop/frontend && bun install——安装桌面端（Wails 3）前端依赖；
3. cd backend-go && go mod download——下载 Go 后端模块；
4. cd desktop && go mod download——下载桌面端 Go 依赖；
5. 执行 scripts/install-wails3.sh 安装 Wails 3 CLI；
6. 若环境中尚无 air，自动执行 go install github.com/air-verse/air@latest 安装 Air 热重载工具（已安装则跳过）。

make install

验证环境

安装完成后，用以下命令确认工具链版本符合要求：

go version     # 应 >= 1.25
bun --version  # 应 >= 1.x
make help      # 确认可用命令

make help 会以彩色列表输出 CCX 的全部可用命令，包括环境准备、开发、构建、工具四大类，是探索项目命令面的最快入口。

推荐开发方式

方式	适用场景	说明
根目录 Make	日常联调	同时启动前端开发服务器和后端热重载
backend-go Make	后端专项开发	只运行 Go 后端命令
frontend Bun	前端专项开发	只运行 Vue/Vite 前端命令
Docker	接近生产环境验证	不适合作为主要热重载开发方式

方式一：根目录开发（推荐）

根目录 Makefile 是前后端联调开发的事实来源，日常开发建议从这里出发：

make help
make dev
make run
make frontend-dev
make build
make clean

各目标作用与源码实现对应关系如下：

• make dev：启动前端开发服务器，并在 backend-go/ 下以热重载模式运行 Go 后端。从源码看，该目标会先在后台执行 cd frontend && bun run dev，再调用 cd backend-go && $(MAKE) dev 触发 Air 热重载；
• make run：先通过 embed-frontend 目标把最新前端构建产物嵌入后端（backend-go/frontend/dist），再执行 cd backend-go && $(MAKE) run 直接运行；
• make build：先嵌入前端产物，再编译 Go 后端生产二进制；
• make frontend-dev：仅启动前端开发服务器（cd frontend && bun run dev），适合纯前端改动；
• make clean：清理前后端与桌面端构建文件。

根目录 Makefile 还包含 desktop-dev（构建 CCX 核心并启动 Wails 3 桌面外壳开发模式）、container-verify（隔离验证）与 benchmark-update 等工具目标，可在 make help 中查看全貌。

方式二：backend-go 目录开发

只改 Go 代码时，以 backend-go/Makefile 为命令事实来源：

cd "backend-go"
make help
make dev
make run
make build
make test
make test-cover
make fmt
make lint
make deps

各目标说明（结合 backend-go/Makefile 源码）：

• make dev：检测 air 是否安装，缺失时自动执行 install-air，随后以 air 启动热重载。启动时会提示监听 *.go, *.yaml, *.toml, *.env 文件变化，修改代码后自动重启；
• make run：先执行 copy-frontend 将 ../frontend/dist 产物复制到 frontend/dist（前端产物不存在时给出警告提示），再以 go run -ldflags=... 直接运行，带版本信息注入；
• make build：以 CGO_ENABLED=0 go build -ldflags="$(LDFLAGS) -s -w" 构建静态二进制到 dist/ccx-go。其中 LDFLAGS 由 ../VERSION（根目录 VERSION 文件为唯一版本源）、构建时间与 Git 短提交哈希拼接而成，通过 -X main.Version / BuildTime / GitCommit 注入 backend-go/version.go，与 docs/guide/architecture.md 中"构建与版本"一节描述的机制一致；
• make test：go test -v ./... 运行全部 Go 测试（覆盖 internal/ 下大量单元与集成测试，如 internal/autopilot/、internal/config/、internal/handlers/ 等）；
• make test-cover：go test -v -cover -coverprofile=coverage.out ./... 生成覆盖率数据，并用 go tool cover -html 输出可视化报告 coverage.html；
• make fmt：go fmt ./... 统一代码格式；
• make lint：golangci-lint run，工具缺失时自动安装；
• make deps：go mod tidy && go mod download 整理并更新依赖。

方式三：frontend 目录开发

前端脚本以 frontend/package.json 为准，优先使用 Bun：

cd "frontend"
bun install
bun run dev
bun run build
bun run preview
bun run type-check
bun run lint

从 package.json 的 scripts 段可以看出，前端命令背后是完整的 Vue 3 工具链：

• dev：vite 启动开发服务器；
• build：先执行 vue-tsc --noEmit 做 TypeScript 类型检查，再执行 vite build 产出静态资源；
• preview：vite preview 预览构建产物；
• type-check：vue-tsc --noEmit 独立类型检查；
• lint：eslint . --ext .vue,.js,.ts 检查 Vue/JS/TS 文件；
• 另有 test（vitest run）、lint:fix、format（prettier）等脚本可供使用。

如果需要验证 pnpm 兼容性，可运行 pnpm install；日常开发、构建和依赖变更仍以 Bun 为准。

Windows 环境建议

如果没有 make，可分别使用 Go 和 Bun 命令完成同样的开发闭环：

cd backend-go
air
go test ./...
go fmt ./...

cd ../frontend
bun install
bun run dev

推荐安装：Go、Bun、Make、Git。

文件变更与重载规则

自动热重载

• Go 源码：make dev / cd "backend-go" && make dev 下，Air 监听 *.go 文件变化并自动重启进程；
• 配置文件：backend-go/.config/config.json 修改后自动生效，无需重启。

关于配置热重载的底层实现，可以追溯到 backend-go/internal/config/config.go 中的 ConfigManager：它持有 fsnotify.Watcher（第 1486 行）与 reloadCh 信号通道（第 1491 行），由 watcher 监听配置文件变化、专门的 goroutine 消费信号并触发 reload；重载前还会比对"自身保存的文件摘要"，避免把自身写回误判为外部变更（第 1496 行）。配置加载末尾会发布 config_reloaded 事件（publishConfigReloaded，第 2360 行），internal/autopilot/ 中的 Manager 可通过 RegisterOnConfigChange 回调感知配置变更（第 1434 行注释）。因此调度策略、熔断参数等运行时配置可以在不中断服务的情况下更新。

需要重启

• 环境变量文件：backend-go/.env（端口、访问密钥、日志等级等环境变量在启动时读取，修改后需重启进程；详见 docs/guide/environment.md 中的"修改这些访问控制环境变量后需要重启服务"说明）；
• 依赖或构建配置变更：如 go.mod、package.json、vite.config.ts 等。

常用验证命令

在提交改动前，至少执行以下检查：

make build
cd "backend-go" && make test
cd "frontend" && bun run build

如果只改后端代码，建议额外执行：

cd "backend-go" && make lint

这条链路分别覆盖：生产构建可用性、Go 全量测试、前端类型检查与构建、静态检查（golangci-lint），与 docs/guide/release.md 中描述的发布前验证要求对齐。

更新模型能力基准数据

CCX 的模型能力、定价与 benchmark 数据以 shared/model-registry/ccx_model_registry.json 为唯一权威源（参见 docs/guide/architecture.md 的 Model Registry 一节）。更新它只需两条命令：

make benchmark-update        # 抓取各源并写入注册表
make benchmark-update-dry    # 预览变更（不写入）

二者底层都调用 scripts/update-benchmark-data.mjs（benchmark-update-dry 会附加 --dry-run 参数），脚本支持丰富的参数透传，例如 make benchmark-update ARGS='--force-litellm'。

数据源：deepswe、benchlm.ai、dradar (codexradar)、Artificial Analysis、litellm（价格/上下文）。从脚本源码可见，每个源都有独立的抓取模块（scripts/benchmark-sources/ 下的 deepswe.mjs、benchlm.mjs、dradar.mjs、artificialanalysis.mjs、litellm.mjs），映射逻辑集中在 scripts/benchmark-sources/mapper.mjs，支持 --skip-deepswe、--skip-benchlm、--skip-dradar、--skip-litellm、--skip-artificial-analysis、--models <model1,model2> 等选项。

Artificial Analysis 是唯一需要 API key 的源。未设置时自动跳过，其余源照常更新：

export ARTIFICIAL_ANALYSIS_API_KEY=your-key   # 缺失则自动跳过 AA，不报错
make benchmark-update                          # 显式跳过用 --skip-artificial-analysis

也可以将 ARTIFICIAL_ANALYSIS_API_KEY=xxx 写入根目录 .env（已 gitignore），脚本启动时通过 process.loadEnvFile 自动加载且不覆盖已有进程环境变量（脚本第 78-79 行），显式传参仍然优先。

更新完成后，脚本会继续调用 generate-model-registry.mjs 重新生成代码与运行时预置，并将 benchmark 可视化数据写入 docs/public/benchmark/。新增模型时，在 scripts/benchmark-sources/mapper.mjs（deepswe/benchlm）及各源文件内的 *_MODEL_MAP 中补上映射，下次 make benchmark-update 即会自动捕获并创建其 benchmarkProfile。

本地访问入口

开发环境启动后，CCX 提供以下入口：

• Web 管理界面：http://localhost:3688
• 代理 API：http://localhost:3688/v1
• 健康检查：http://localhost:3688/health
• 前端开发服务器：默认 http://localhost:5173

端口与监听地址的默认行为可在 docs/guide/environment.md 中确认：后端默认 PORT=3688；BIND_HOST 留空时保持默认 :PORT 行为，等价于监听所有网卡（常见显示为 0.0.0.0:3688 或 *:3688），设置 BIND_HOST=127.0.0.1 时只允许本机访问。前端开发服务器端口由 VITE_FRONTEND_PORT 控制（默认 5173），Vite 通过代理把 /api 请求转发到后端。

Windows / WSL / Docker 访问建议

Windows 下 cmd、PowerShell、WSL 与 Docker 可能处在不同网络环境中，localhost / 127.0.0.1 不一定指向运行 CCX 的进程。跨环境调用时建议使用 Windows 主机的局域网 IPv4 地址，例如：

http://192.168.1.23:3688/v1

获取地址：

ipconfig

验证连通性：

curl.exe -i http://192.168.1.23:3688/health

CCX 后端在 BIND_HOST 留空时默认监听 :PORT，等价于监听所有网卡地址；通常不需要额外修改为 0.0.0.0。如需仅本机访问，设置 BIND_HOST=127.0.0.1。如果局域网 IP 无法访问，优先检查 Windows 防火墙是否允许对应端口入站。

常见开发任务速查

只调试后端

cd "backend-go"
make dev

Air 热重载会监听 Go 源码与配置文件变化，适合在改动 internal/scheduler/、internal/config/ 等模块时快速迭代。

只调试前端

cd "frontend"
bun install
bun run dev

开发服务器运行在 http://localhost:5173，Vite 代理将 /api 请求转发到后端，API 配置逻辑与代理设置详见 docs/guide/environment.md 的"API 基础URL 生成逻辑"与"开发服务器代理配置"两节。

前后端联调

make dev

这是推荐的日常联调入口：一条命令同时拉起前端开发服务器与后端热重载进程。

验证生产构建

make build

该目标会先执行 embed-frontend 将最新前端产物嵌入后端，再编译 Go 二进制，输出到 backend-go/dist/（dist/ccx-go），是提交与发布前最后一道构建关卡。

延伸阅读

• 架构设计：docs/guide/architecture.md
• 环境变量：docs/guide/environment.md
• 发布流程：docs/guide/release.md
• 后端构建与版本注入实现：backend-go/Makefile、backend-go/version.go
• 配置热重载实现：backend-go/internal/config/config.go
• 基准数据更新脚本：scripts/update-benchmark-data.mjs