# cpa-ext

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

## 当前兼容目标

- 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 工具链：

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

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

```powershell
./scripts/build.ps1
```

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

```powershell
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 上游凭证；
- 按客户端请求模型配置允许列表；
- 累计、今日和最近请求统计。

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

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

## 工程布局

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