53 lines
2.0 KiB
Markdown
53 lines
2.0 KiB
Markdown
# 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 工具链：
|
||
|
||
```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. 发起一个 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`：上游契约参考，不属于插件实现。
|