ccLoad CLAUDE.md

CLAUDE.md

ccLoad:Claude/OpenAI/Gemini/Codex 多协议 API 网关(渠道/Key/URL 选择 + 故障切换 + 协议转换 + 成本计量)。 本文件是 AI 操作手册——只记命令、硬约束、反直觉机制与入口;展开细节读对应代码。

命令

必须 -tags sonic;环境变量见 .env。

make build          # 构建(注入版本号+strip)
make dev            # 开发运行
bash .agents/skills/sync-cliproxy-core/scripts/verify.sh --tests # 协议快照审计+定向测试
bash .agents/skills/ccload-release/scripts/release.sh --self-test # 发布脚本自检
go test -tags sonic ./internal/...
make race-fast      # 高价值 race 子集
make race           # 全量 race(可用 RACE_P/RACE_PARALLEL 调并行度)
make verify-web     # 前端验证(含 node:test)
golangci-lint run ./...   # 提交前必须零警告

测试策略

• 迭代只跑受影响包:go test -tags sonic ./internal/app -run 'TestXxx';提交前全量 ./internal/...。Go 测试、make verify-web、make build、lint 相互独立,可并行
• 不用 -count=1,除非排查缓存或不稳定测试
• 积极 t.Parallel():并行测试必须独立 Store/Server、随机监听端口、局部 mock,不共享可变 fixture;调用 t.Setenv/t.Chdir,或修改进程环境、工作目录、http.DefaultTransport、全局模型目录、包级 session/cache、全局 goroutine 计数的测试必须串行
• 优先并行化含 sleep、deadline、轮询、异步日志等待的高耗时测试;不为凑并行数改纯解析微测试
• 并行化前后同命令计时(/usr/bin/time -p go test -tags sonic -count=1 ./internal/app),收益属噪声就撤销;新增/调整并行测试后跑 go test -race -tags sonic -count=1 -shuffle=on ./internal/app

代码规范(硬约束)

• 必须 -tags sonic;用 any,不用 interface{}
• YAGNI,拒绝过度工程;Fail-Fast:配置错误 log.Fatal() 退出
• Context:defer cancel() 无条件调用,用 context.AfterFunc 监听取消
• lint 启用 errcheck/govet/staticcheck/unused/revive/bodyclose(gosec 已禁)
• Web 单选下拉必须可搜索:禁止让原生 <select> 直接出现在最终 UI,统一由 searchable-select.js 增强并复用 createSearchableCombobox;原生 <select> 只允许作为隐藏的表单/业务值载体,禁止页面私造下拉。动态选项、禁用态、原生 input/change、表单提交、键盘/ARIA 与 <dialog> 顶层菜单都必须保留;多选控件未提供可搜索实现前禁止新增

架构与入口

internal/app/        HTTP+业务:proxy_* / admin_* / selector_* / *_cache / *_service
internal/protocol/   协议契约与注册;builtin/ 是 ccLoad 适配层;cliproxy/ 是上游转换核心快照
internal/storage/    存储(factory/hybrid_store/sync_manager/migrate;sql/ sqlite/)
internal/cooldown/   冷却决策   internal/util/  classifier/cost_calculator/money/...
internal/{model,config,version,testutil}/   web/  管理后台前端(HTML+assets/{css,js,locales})
www/                 独立介绍站(`make www-setup` 复制共享资源后可脱离仓库部署,别和 web/ 混淆)