cpa-ext

cpa-ext 是 CLIProxyAPI 的收敛式核心扩展，提供持久化用量与价格展示、下游 Key 管理、模型准入和上游凭证定向路由。一个 Key 代表一个调用用户；管理员可以创建、禁用或永久归档 Key，并按 Key 查看统计。

每个 Key 同时拥有独立的美元额度账户。管理员可以分配本周期额度、设置日/周/月自动重置和并发上限，并查看不可变的扣费、额度调整与重置账目。额度采用请求结束后结算的软限制：余额为正时放行，实际 Usage 到达后扣费，最后一个或多个在途请求可能产生负余额，之后的新请求返回 429。

当前兼容目标

• CLIProxyAPI 源码：CLIProxyAPI/，检查时 revision 为 f43aad7637ad813745bf7d341acb5663617570c5
• Native ABI：1
• RPC schema：最高 3，注册时按宿主版本向下协商
• 插件 ID / 动态库文件名：cpa-ext
• 已声明能力：frontend_auth_provider（独占）、scheduler、request_interceptor、request_lifecycle_plugin、usage_plugin、management_api

契约来源以本仓库内 CLIProxyAPI/sdk/pluginabi/types.go、CLIProxyAPI/sdk/pluginapi/types.go、CLIProxyAPI/internal/pluginhost/rpc_schema.go 为准。

环境与构建（WSL/Linux）

需要 Go 1.24+ 和 GCC。Ubuntu/Debian 可先准备 C 工具链：

sudo apt-get update
sudo apt-get install -y build-essential
./scripts/check-env.sh
./scripts/build.sh

从 PowerShell 也可调用 WSL 构建入口：

./scripts/build.ps1

产物为 bin/cpa-ext.so，适用于运行在 WSL/Linux 的 CLIProxyAPI。普通开发测试不需要 CGO：

go test ./...

加载到 CLIProxyAPI

1. 将 bin/cpa-ext.so 放进 Linux CLIProxyAPI 配置的插件目录（默认 plugins/）。
2. 合并 config.example.yaml 中的 plugins 配置。
3. 重启宿主，确认日志中成功加载插件 cpa-ext。
4. 首次启动会创建名称为 default、值为 000000 的下游 Key，保持现有 Codex 配置可用。
5. 发起一个 Codex 请求，确认管理页面出现该 Key 的用量和实际上游 Auth ID。

Key 管理与路由

管理页面提供：

• 自动生成或手动输入 Key，完整 Key 可随时复制；
• active / disabled 状态切换，以及不可恢复但保留历史的归档；
• CPA 自动选择上游，或严格绑定一个 OAuth/API Key 上游凭证；
• 按客户端请求模型配置允许列表；
• 模型允许列表支持精确名称和 * 通配符，例如 deepseek-*；
• 分配美元额度、设置自动重置时间和每用户并发上限；
• 查看当前额度、已用、余额以及最近扣费账目；
• 累计、今日和最近请求统计。

严格绑定的账号不可用或不支持目标模型时请求直接失败，不回退到其他账号。新 Key 在创建时复制 default 当时的路由与模型规则，之后独立维护。

现有和新建 Key 的初始额度都是 $0，默认不自动重置、并发上限为 4。管理员分配额度后才能发起模型请求。金额以微美元整数保存；修改额度不会清空本周期已用金额，手动或自动重置不会结转旧余额。允许模型没有价格配置时，请求会在触达上游前以 503 拒绝。

config_yaml 中包含宿主补充的 enabled 和 priority；插件会解析 codex_only、数据库路径和首次导入 Key。完整下游 Key 只通过受 CPA Management Key 保护的 Key 管理接口返回，不写入普通日志或错误消息；上游 Token、Cookie 和原始凭证不会由插件读取或保存。

请求明细与汇总

请求明细由服务端分页，每页 100 条，默认按请求时间和稳定 ID 倒序展示。管理接口支持时间范围、用户 Key、模型、结果、上游 Auth ID、端点和完整 Request ID 筛选；连续翻页使用与筛选条件绑定的游标，数字页码跳转使用 SQLite 索引定位。用户页的今日汇总、各用户用量和近 7 日 Token 由数据库独立聚合，不受当前明细页影响。

升级已有数据库时，插件会从原始 Usage 和请求终态事实自动建立轻量查询投影。事实表、计费账目和历史统计保持不变；重试执行继续分别展示，没有 Usage 的取消或失败请求仍然可见，缺少 Request ID 的旧回调沿用双向唯一时间匹配规则。

工程布局

• cmd/cpa-ext：仅负责 C ABI、请求字节复制和 C 内存释放。
• internal/plugin：RPC dispatcher、契约 DTO、原子配置与 Usage 接入。
• scripts：环境检查与可复现构建。
• CLIProxyAPI：上游契约参考，不属于插件实现。