cpa-plugin/AGENTS.md

billing

当前项目的本质是对 CLIProxyAPI 的核心扩展，功能边界会非常收敛

• 更好的统计、展示
• 初期优先保证codex的正常使用
• 能最简单的管理多用户key

参考

• CLIProxyAPI 原始项目
• cpa-plugin-key-billing CLIProxyAPI 下游 API Key 计费与订阅额度插件
• cpa-usage-keeper 用量持久化与分析面板

上游依赖与参考仓库边界

.externals/CLIProxyAPI/ 是锁定官方基线的 Git submodule，用于宿主构建、契约核对和集成测试。宿主修复仍以根仓库 patch/ 中的补丁维护，不直接提交到官方 submodule。

.externals/cpa-plugin-key-billing/、.externals/cpa-usage-keeper/ 不是本项目的实际开发仓库，只用于测试、契约核对和实现对比。

• 默认不检查两个参考插件目录的 Git 状态、提交历史、分支、远端或工作区改动。
• 不为这两个参考插件仓库修复问题，不修改或提交其中的代码，也不处理其 Git 状态。
• 上述限制不影响运行时测试：可直接加载已经构建好的参考插件；测试 CPA 插件组合时，按需启用 cpa-key-billing 作为对照插件，但不得因此进入其仓库做源码或 Git 操作。
• 只有在 billing 的兼容性验证、测试或实现判断确有必要时，才按最小范围只读查看相关文件。
• CPA submodule 只允许按 patch/README.md 应用、验证或重新生成本项目维护的宿主补丁；除此以外的 CPA 修改，以及两个参考插件的修改、构建、提交或维护，必须由用户明确提出。
• 项目的实现、提交和工作区清洁度只以 billing 根仓库为准。

DO

• 阅读 docs/dev.md 了解开发前置知识
• 阅读 TODOS.md 了解计划

本地与远端发布约定

• 本地 CPA 在 WSL 中运行，项目运行目录统一使用 cpa-plugin/.runtime；Windows 客户端经 127.0.0.1 访问 WSL 时，localhost 转发层可能不会立即向 CPA 传递客户端断开，取消链路测试优先在 WSL 内直连执行。
• 从 PowerShell 跨 WSL 或 SSH 执行包含 Bash 变量、命令替换或多层引号的逻辑时，优先在 .runtime/tmp/ 创建临时脚本后传入目标环境执行，不拼接复杂的单行 shell；临时脚本不提交。
• CLIProxyAPI 宿主补丁保存在 patch/，当前已验证基线为 v7.2.139 / 0a14eb70，必须按 usage-context、usage-identity、request-lifecycle-cancel 的顺序应用；升级 CPA 后按 docs/operations.md 核对补丁和已知上游测试例外。
• 构建本项目 patched CPA 时必须按上游 release workflow 使用 -ldflags 注入 main.Version、main.Commit 和 main.BuildDate。Version 固定使用“当前上游最新 tag + -dev”格式（例如 v7.2.139-dev），用于明确区分官方 Release 与本项目补丁构建；不得发布只显示 dev、none 或 unknown 的产物。上传前先在本地执行二进制并核对完整版本输出。
• CPA Linux 可执行文件解压后约 60 MiB，gzip -9 后约 20 MiB。上传远端时使用 gzip/tar.gz 或 scp -C，不要直接传输未压缩二进制；部署后的运行文件仍需解压为原始可执行文件。
• 实际服务器为 root@akko.pchuan.top，CPA 根目录为 /root/cpa。只维护本项目的 billing 和已要求启用的 keeper，不启用或部署其他参考插件。
• 远端替换 CPA 或 billing 前，先停止 /root/cpa/cpa.sh 管理的进程，并把旧二进制、插件和 data/cpa-ext.db* 备份到 /root/cpa/backups/<timestamp>/；新版本启动失败时恢复旧二进制和插件。
• 功能、协议、计费、取消链路与真实模型请求验收全部在本地 CPA 完成；至少核对：无 Key 被拒绝、有效 billing Key 请求成功、请求明细只有一条且包含 Request ID 和 Token、额度发生一次扣减、active_requests 回到 0。
• 本地验收通过后可直接发布远端。远端只允许执行压缩包校验、旧文件与数据库备份、二进制和插件替换、进程启动、健康检查及插件注册状态检查；禁止为验收向远端模型端点发送请求，包括任何 /v1/responses、/v1/chat/completions 或 compact 请求。
• 管理密钥和下游 Key 从远端 secret 文件或管理 API 在脚本内部读取，禁止在终端输出、提交或写入普通日志；验证结果只输出 Key 名称、状态、额度配置和布尔结论。