agent/cpa-plugin

Fork 0

Files

T

chuan 42be14c8d0 docs: 第一个版本的讨论文档

2026-08-14 14:47:33 +08:00

20 KiB

Raw Blame History

数据模块

1. 定位

数据模块是 cpa-ext 的统一数据语言。它只回答三件事：

系统需要从 CLIProxyAPI（CPA）及相关来源关注什么数据；
这些数据在插件内部以什么稳定语义流转；
计费、统计、Key 管理、配额、审计和展示模块可以得到什么输出。

数据模块不负责采集回调、计算费用、执行扣款、生成统计图或决定界面权限。具体模块负责产生和消费数据，数据模块只定义契约。

本模块以两个已经实际工作的项目为需求来源：

cpa-plugin-key-billing 已经拿到并使用的数据，全部视为我们需要关注的数据；
cpa-usage-keeper 已经拿到并使用的数据，全部视为我们需要关注的数据；
两者已经对外提供的数据产品，全部纳入我们的输出能力全集；
第一版可以只实现其中一部分，但数据抽象不能阻止以后补齐其余能力。

2. 两个参考项目的数据总结

2.1 `cpa-plugin-key-billing`

它拿到的数据

数据域	实际取得的内容	主要来源
下游调用身份	`caller_scope`、Key 脱敏预览、标签、Key 是否仍在 CPA 配置中	请求 metadata、管理端同步的 CPA Key 列表
请求关联	`request_id`、入口 endpoint、请求格式、上游格式、流式标记、是否真实生成	request interceptor、request lifecycle
模型	用户/路由模型、实际上游模型、稳定 billing model	请求阶段、响应阶段
上游凭证	`auth_index`、provider、auth type、OAuth 账户或脱敏 provider API Key	CPA usage callback
请求终态	正常、失败、取消、拒绝	request lifecycle
原始用量	OpenAI/Codex、Claude、Gemini、Interactions 等响应中的 usage 和 response ID	翻译前响应、非流式响应、流式 chunk
标准 Token	非缓存输入、缓存读取、缓存写入、普通输出、推理输出、总量、无法分类数量	自身规范化逻辑
数据质量	complete、inconsistent、unclassified、未观察到用量	自身规范化逻辑
价格	模型匹配规则、每百万 Token 各分项价格、长上下文门槛与价格、价格来源	内置 models.dev 目录、管理员覆盖
套餐与周期	套餐 ID/名称、美元额度、日/周/月/自定义周期、周期开始与结束	插件配置与持久化状态
请求准入快照	请求进入时绑定的 Key、套餐和周期	请求 interceptor

它没有把 CPA 的 usage_plugin 当作完整用量事实：该回调缺少 RequestID，所以项目主要从带有请求关联信息的响应 hook 中恢复权威 Token，再在终态回调结算；usage_plugin 主要用来补充上游凭证身份。

它存储的数据

价格规则、套餐、Key 状态、上游凭证目录；
Key 的当前周期和生命周期累计；
按模型累计；
最近 30 天请求日志；
每次请求的标准 Token、金额分项、价格来源、长上下文状态和数据质量；
运行时未定价、无 Token、无法分类等诊断计数。

它输出的数据

输出域	已提供的数据
请求控制	放行或拒绝，额度耗尽时返回明确的 HTTP 错误
Key 目录	Key 标识/预览/标签、套餐、是否无限、是否阻断、周期额度、已用、使用率、周期结束时间
套餐管理	套餐及金额、周期，绑定、解绑和重置
请求账目	时间、Key、请求 ID、endpoint、上游凭证、模型、结果、Token、金额、价格来源和核算质量
汇总	Key 数量、阻断数量、生命周期请求/Token/金额、按模型汇总
价格管理	当前模型价格、自定义覆盖、价格刷新结果
运维诊断	持久化状态、配置状态、未定价/缺失/无法分类计数

2.2 `cpa-usage-keeper`

它拿到的数据

数据域	实际取得的内容	主要来源
用量事件	provider、endpoint、auth type/index、request ID、API Key、模型/别名、请求与响应 service tier、reasoning effort、executor、时间、失败、延迟、TTFT、完整 Token 分项	CPA Redis usage queue / HTTP usage queue
请求环境	client IP、X-Forwarded-For、User-Agent、source、API group key	CPA usage payload
下游 Key	完整 CPA API Key、展示值、别名、删除/同步状态	CPA Management API
上游 Auth File	auth index、名称、文件、email、provider、label、状态、priority、disabled、note、account/project、订阅起止与 plan type	CPA Management API
Provider API Key 配置	provider 类型、名称、prefix、base URL、lookup key 等归一化元数据	CPA 各 provider management API
模型目录	模型 ID、owner、创建时间	CPA `/v1/models`
上游配额	Codex 主/次窗口、允许状态、使用率、重置时间、额外限制、reset credits；以及其他 provider 的 quota	CPA 代调用各 provider API
上游订阅	Codex plan、tier、有效期；其他 provider 的订阅/账户资料	auth metadata、provider API
请求日志	按 request ID 获取的请求日志、预览与下载数据	CPA request-log management API
价格	模型价格快照、条件规则、service tier、reasoning、模型、Key、auth、endpoint、executor 等价格维度	models.dev、管理员配置

它存储的数据

原始 Redis inbox 及处理/重试状态；
标准化的逐次用量事件和归档；
CPA API Key 与上游身份目录；
模型价格设置、同步快照和条件价格规则；
小时/日 overview、activity、latency、identity 等预聚合及各自 checkpoint；
配额快照和应用设置；
排名等派生结果。

它输出的数据

输出域	已提供的数据
Overview	请求数、Token、金额、RPM、TPM、日均值、缓存命中率和时间序列
实时状态	Token 速度、请求速度、TTFT/Latency P50/P95、响应分布、当前模型/Key/Auth Top、缓存水平
事件明细	可分页筛选的逐请求记录，包含模型、身份、结果、Token、金额、延迟和请求日志入口
Analysis	Token 时序、模型使用、Key/模型/Auth 构成、Key×模型热力图、金额分项、模型效率
Activity	日/周/月/年活动格、成功失败、成功率和各 Token 分项
身份目录	下游 Key 与上游账号/provider 的元数据、别名、启停状态、订阅和累计使用情况
配额	各上游账号的窗口、使用率、剩余、重置时间、订阅层级和 reset credits
价格	当前价格、价格来源、同步状态、条件规则及预览
排名与导出	本地排名、事件导出、请求日志查看/下载

3. 我们的数据关注全集

两个项目的数据取并集后，数据模块定义以下九个数据域。这里的“需要”表示契约需要容纳，不表示所有字段都必须在 MVP 首日采集完成。

3.1 请求与执行

必须同时表达两个层级：

Request：一次下游用户请求；
Execution：一次 CPA after-auth 可观察到的上游逻辑执行段。

一个 Request 可以因为重试、故障切换或路由产生多个 Execution。Execution 不保证等于一个物理 HTTP dispatch：当前 CPA 在 auth refresh 后的内部重发不会再次触发 after-auth，应以 subattempt_count/observability=partial 表达，而不是伪造额外 Execution。未来宿主提供 dispatch lifecycle 时再增加 DispatchAttempt。

关注字段：

request/event/trace/execution ID；
endpoint、source、source format、upstream format；
requested model、routed model、upstream model、model alias；
stream、generate、reasoning effort；
requested、reported、effective service tier；
requested、started、first-token、completed 时间；
outcome、HTTP status、标准错误类别；
settlement status（与请求 outcome 分开，允许 canceled/failed 请求在迟到 Usage 后结算）；
latency、TTFT；
重试序号及最终尝试标记。

3.2 下游身份

关注字段：

account/member ID；
credential ID；
credential secret version/public ID/HMAC key ID/status；
自管 Key 的 public key ID、HMAC digest、digest secret version；
CPA 根据 Principal 派生的稳定 caller scope（仅用于请求期关联，不作为业务主键）；
兼容模式下 CPA 原生 API Key 的稳定 scope/hash；
脱敏预览、别名、标签；
启用、删除、同步状态；
套餐/计费账户绑定。

自管 Key 的完整值只在创建/轮换成功时展示一次，持久层只保存摘要；CPA 原生 Key 即使在兼容迁移模式由 CPA 配置持有，也不得复制进插件事件、日志或跨模块消息。

3.3 上游身份

关注字段：

auth ID/index/type；
provider、executor type；
名称、别名、email/account、文件标识；
provider prefix、base URL、lookup key；
priority、disabled、status、note；
account/project ID；
plan/tier 和订阅有效期。

秘密凭证不属于数据流转契约。

3.4 用量

统一为互不重叠、跨 provider 可比较的字段：

uncached input；
cache read；
cache creation/write；
non-reasoning output；
reasoning output；
total；
unclassified；
generate 标记。

同时保留规范化质量：complete、normalized、partial、inconsistent、unclassified、missing，以及修正动作/异常代码。原始 provider 计数可以作为受限审计快照保存，但不能直接成为跨模块语义。

3.5 金额与价格

关注字段：

settlement currency；
金额的定点整数值；
未缓存输入、缓存读取、缓存写入、输出的金额分项；
base amount、final charged amount；
每百万 Token 的实际应用价格；
service tier / Fast multiplier；
长上下文门槛及是否命中；
price version、source、effective time；
价格是否可用及不可用原因；
billing record ID、request/execution ID、usage revision；
charge、late settlement、credit、refund、adjustment 类型及被修正记录；
pending/awaiting usage/settled/unmeasured/inconsistent 状态；
occurred at 与 booked at。

用户侧核心金额只使用最终结算金额；Token、价格与倍率是后台审计数据。

3.6 下游套餐、周期与余额

关注字段：

plan、额度金额和周期规则；
BillingAccount 与 plan 的绑定、Credential → BillingAccount 绑定；
cycle start/end；
limit、spent、remaining；
blocked/allowed；
管理员调整及其原因；
请求准入时使用的周期快照。

3.7 上游配额与订阅

它和我们分配给用户的金额额度是不同概念，必须分开表达。

关注字段：

provider/account；
plan/tier、订阅起止；
primary/secondary/additional windows；
used、limit、remaining、percentage；
allowed、limit reached；
window duration、reset at/after；
window usage token/cost；
reset credit 数量、状态和过期时间；
snapshot time 和数据新鲜度。

3.8 模型、价格与配置目录

关注字段：

CPA 可用模型及 owner；
模型别名和路由映射；
provider/model 对应关系；
价格目录、管理员覆盖和条件规则；
Key、auth、provider 的当前配置事实；
同步时间、来源、版本和删除状态。

3.9 诊断、日志与数据质量

关注字段：

schema version、producer version；
source/provenance、observed at、persisted at；
idempotency key；
缺失、修正、冲突、未定价状态；
inbox/checkpoint/retry/archive 状态；
请求日志引用和受控下载信息；
原始数据哈希或受限审计引用。

Prompt、模型完整响应、Authorization、Cookie、OAuth token 和 provider API Key 默认不进入通用数据契约。

4. 核心抽象

数据模块不要求所有内容塞进一张表。它定义以下稳定对象，存储模块可以分别落库。

DownstreamAccount
  └─ BillingAccount
       └─ DownstreamCredential (1..N)
            ├─ CredentialSecretVersion (1..N)
            └─ Request
                 └─ Execution (1..N)
                      ├─ Usage
                      ├─ Outcome & Performance
                      └─ UpstreamIdentity

Usage + PricingSnapshot
  └─ BillingRecord
       └─ LedgerEntry

Usage / BillingRecord / Identity / QuotaSnapshot
  └─ Aggregate & View

4.1 `RequestRecord`

用户视角的一次请求。保存下游身份、入口、请求模型、最终结果、时间以及所有 Execution 的关联，不直接猜测每次上游尝试的细节。

4.2 `ExecutionRecord`

一次 CPA after-auth 可观察到的逻辑执行段。保存上游凭证、provider、实际模型、tier、格式、终态、性能、重试关系和 observability；不能宣称等于每个物理 HTTP dispatch。

4.3 `UsageRecord`

一次 Execution 对应的标准 Token 事实，包含质量和来源。Request 层用量由明确规则合并，不覆盖底层执行事实。当前 CPA 对部分 Usage 缺少 RequestID/AttemptID，无法可靠归属时必须保持 unmeasured/未关联事实，不能按时间或上游账户猜配。

4.4 `BillingRecord`

计费模块对 Usage 应用价格后产生的不可变金额事实。它引用 Usage revision 和价格快照，迟到结算、退款或人工修正通过新增记录表达；金额一旦入账，统计模块不得重新计算并改写历史。

4.5 `IdentityRecord`

统一承载下游 Key/账户和上游 auth/provider 的非秘密身份信息，但通过明确的 identity kind 区分，不能只靠一个字符串猜类型。

4.6 `QuotaSnapshot`

某个上游身份在某一时刻的 provider 配额和订阅快照。它是时间点事实，不覆盖历史；也不与下游金额余额混用。

4.7 `CatalogSnapshot`

模型、价格、路由和配置目录的带版本快照，使历史请求可以解释当时使用的模型和价格。

4.8 `AggregateRecord`

从不可变事实派生的小时、日、活动、延迟、身份和排名数据。它可以删除并重建，不是账本真相。

4.9 `ProjectionEvent`

跨 Request、Usage、Billing、Ledger 多表的统一追加变化流。它携带单调 event_seq、唯一 event_id、kind、fact ID/revision、occurred/booked time、可选 supersedes ID 和确定性统计差量。领域事实与对应 ProjectionEvent 必须在同一事务提交；统计 projector 只按这条流推进，不能比较各表互不相关的自增 ID。

5. 统一数据元信息

所有可持久化的事实对象都应携带或可追溯到：

字段	含义
`schema_version`	数据契约版本
`event_id`	全局稳定事件 ID
`idempotency_key`	重复回调或重放时去重
`source`	CPA callback、response hook、Redis、Management API、provider API 等
`observed_at`	来源数据被观察到的时间
`occurred_at`	业务事实真实发生时间
`persisted_at`	成功落库时间
`quality`	完整、修正、部分、矛盾、缺失等
`producer_version`	产生该规范化数据的插件版本

字段缺失必须保持“未知”，不能自动等价为零、空字符串或成功。

6. 数据模块输出契约

数据模块定义四类输出，具体模块按需实现和消费。

6.1 事实输出

Request、Execution、Usage、Billing、Ledger、ProjectionEvent；
Downstream/Upstream Identity；
Quota、Subscription、Catalog 快照；
数据质量和诊断事件。

6.2 查询输出

逐请求和逐执行明细；
Key、账户、上游身份、模型和价格目录；
套餐、周期、余额和账本；
配额、订阅和重置时间；
请求日志的受控引用。

6.3 聚合输出

完整能力集合至少容纳：

请求、Token、金额、RPM、TPM；
时间序列和日均；
成功率、错误分布；
TTFT/Latency 分位数和分布；
缓存读取率；
模型、Key、账户、Auth、Provider 构成及 Top；
Key×模型热力图；
金额分项和模型效率；
活动格、排名和历史对比。

6.4 控制输出

请求允许/拒绝及稳定错误码；
Key、套餐、价格和绑定的变更结果；
配额刷新/重置结果；
同步、归档、重建和诊断结果。

控制输出由业务模块决定，数据模块只定义其可交换的数据形状。

7. 模块边界

模块	对数据模块的关系
CPA 适配层	把 CPA 回调、响应和 Management API 数据翻译成标准事实
存储模块	按契约持久化、查询、去重、归档和迁移
Core/Key 模块	维护下游身份、金额账户和绑定关系
上游账户模块	维护 CPA Auth 引用、priority、bindability 和 Quota/Subscription 快照
价格模块	维护不可变 PriceVersion、模型 alias 和计价政策
计费模块	消费 Usage、Pricing、Plan，输出 Billing 和 Ledger
统计模块	消费不可变事实，输出可重建的 Aggregate
API/UI 模块	将同一数据按用户或管理员权限投影，不发明新的业务事实

数据模块自身：

不依赖 UI；
不依赖某一种数据库；
不调用 CPA；
不计算价格；
不聚合统计；
不保存或传播秘密；
不把参考项目现有字段名直接当成永久领域语义。

8. 如何参考两个项目

8.1 从 `cpa-plugin-key-billing` 参考

重点查看：

internal/plugin/usage_tracker.go：请求与响应用量关联；
internal/plugin/upstream_usage.go：跨 provider Token 语义；
internal/billing/pricing.go：标准 Token、数据质量、价格和金额分项；
internal/billing/account.go：终态用量到费用记录；
internal/billing/state.go：价格、套餐、Key、周期、累计和日志；
internal/billing/log.go、keys.go：请求账目和管理输出；
internal/billing/credentials.go：上游凭证的安全展示身份。

吸收它对请求关联、Token 不重叠、质量显式化、请求准入周期快照和上游身份脱敏的定义；不要继承其 JSON 大状态、浮点余额、30 天日志限制和把重试只保留为最终 provider usage 的数据损失。

8.2 从 `cpa-usage-keeper` 参考

重点查看：

internal/entities/usage_event.go：逐请求事件字段；
internal/entities/usage_identity.go、cpa_api_key.go：身份目录；
internal/service/sync.go：用量规范化、来源和 inbox 处理；
internal/service/tokenprocessor/：Token 修正与质量判断；
internal/pricing/、internal/entities/model_price_*：价格快照与条件；
internal/quota/：上游配额、订阅和 provider 抽象；
internal/service/dto/usage.go、analysis.go、usage_activity.go：查询和分析输出；
internal/repository/usage*.go：明细、聚合、checkpoint 和归档。

吸收它完整的事件、身份、配额、价格、实时和分析数据面；不要把其 Redis/HTTP 拉取方式、明文 CPA Key 存储方式、GORM 实体或动态历史费用重算直接变成我们的领域契约。

9. 本模块的完成标准

两个参考项目实际使用的输入数据均能映射到本模块的数据域；
两个参考项目实际提供的输出均能由本模块的事实或派生数据表达；
Request 与 Execution、下游额度与上游配额、Usage 与 Billing、事实与聚合均明确分离；
未知、缺失、零和失败具有不同语义；
所有金额可使用定点整数，所有历史收费可追溯到价格快照；
所有秘密字段均被排除或明确限定在受保护配置边界；
后续模块只能扩展契约版本，不能用自己的私有字段重新定义同一个业务事实。

20 KiB Raw Blame History Unescape Escape

数据模块

1. 定位

2. 两个参考项目的数据总结

2.1 cpa-plugin-key-billing

它拿到的数据

它存储的数据

它输出的数据

2.2 cpa-usage-keeper

它拿到的数据

它存储的数据

它输出的数据

3. 我们的数据关注全集

3.1 请求与执行

3.2 下游身份

3.3 上游身份

3.4 用量

3.5 金额与价格

3.6 下游套餐、周期与余额

3.7 上游配额与订阅

3.8 模型、价格与配置目录

3.9 诊断、日志与数据质量

4. 核心抽象

4.1 RequestRecord

4.2 ExecutionRecord

4.3 UsageRecord

4.4 BillingRecord

4.5 IdentityRecord

4.6 QuotaSnapshot

4.7 CatalogSnapshot

4.8 AggregateRecord

4.9 ProjectionEvent

5. 统一数据元信息

6. 数据模块输出契约

6.1 事实输出

6.2 查询输出

6.3 聚合输出

6.4 控制输出

7. 模块边界

8. 如何参考两个项目

8.1 从 cpa-plugin-key-billing 参考

8.2 从 cpa-usage-keeper 参考

9. 本模块的完成标准

20 KiB

Raw Blame History

2.1 `cpa-plugin-key-billing`

2.2 `cpa-usage-keeper`

4.1 `RequestRecord`

4.2 `ExecutionRecord`

4.3 `UsageRecord`

4.4 `BillingRecord`

4.5 `IdentityRecord`

4.6 `QuotaSnapshot`

4.7 `CatalogSnapshot`

4.8 `AggregateRecord`

4.9 `ProjectionEvent`

8.1 从 `cpa-plugin-key-billing` 参考

8.2 从 `cpa-usage-keeper` 参考