cpa-ext

cpa-ext 是 CLIProxyAPI 的收敛式核心扩展。当前基础里程碑只接入 Usage 能力，用来验证动态库 ABI、RPC 注册、配置热更新和并发用量入口；持久化、统计 API、管理面板和多用户 Key 管理将在此边界后逐步加入。

当前兼容目标

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

契约来源以本仓库内 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. 发起一个 Codex 请求，确认宿主调用 usage.handle。

config_yaml 中包含宿主补充的 enabled 和 priority；插件会解析自己的 codex_only 配置。不要在日志、测试快照或管理接口中暴露 API Key、Auth ID、Bearer Token 或原始请求体。

工程布局

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