功能模块

cpa-ext 采用组合式模块架构。每个模块拥有清晰的职责、数据和接口，可以独立测试与演进；Core 负责组合业务，插件运行时只负责把 CLIProxyAPI 的能力调用适配到 Core 和相应模块。

模块列表

模块	状态	职责
数据模块	设计中	定义整个插件流转时共同关注的数据、来源、语义、质量和输出契约
Core 核心业务模块	设计中	组合认证、准入、路由、采集、计费、持久化、统计通知和管理用例，形成完整业务闭环
插件运行时与 CPA 集成	设计中	负责 ABI/RPC、能力注册、CPA 适配、配置、生命周期、构建和宿主验证
CPA 数据采集模块	设计中	从 CPA 请求生命周期、用量、管理接口和上游响应取得数据并生成标准事实
上游账户与配额模块	设计中	将 CPA Auth 抽象为稳定上游账户，维护 priority、可绑定性、配额、订阅和账户池
本地持久化模块	设计中	使用 SQLite 安全保存事实、账本、目录、快照和可重建聚合
价格目录与计价政策模块	设计中	管理价格来源、不可变版本、模型别名、长上下文和 Fast/priority 政策
计费模块	设计中	API Key 套餐、金额额度、请求准入、费用结算和账本
Key 准入与账户路由模块	设计中	决定 Key 是否可用，并可将指定 Key 路由到指定上游账户
统计分析模块	设计中	把不可变事实与账本增量处理为可重建聚合、实时查询和权限化展示投影
HTTP API 模块	设计中	冻结管理员与用户接口、精确路径、DTO、金额、错误、权限、分页和幂等契约
管理与展示 UI 模块	设计中	提供用户金额视图和管理员统计、账户、配额、价格与诊断界面
安全模块	设计中	定义认证旁路防护、secret、租户、账本、网络、native 和供应链安全边界
部署与运维模块	设计中	构建安装、配置、readiness、监控、备份恢复、升级回滚和故障 Runbook
测试与发布门禁	设计中	将业务闭环、故障、安全、性能、容量、soak 和平台兼容转成发布证据

跨模块只能通过数据模块定义的明确契约协作。数据模块定义“系统关注什么”，不负责计费、聚合或展示；计费模块不能依赖统计查询才能决定是否放行请求；统计模块不能重新决定一笔请求应该扣多少钱。

结构关系

CLIProxyAPI
    │ ABI / JSON RPC
    ▼
Dev runtime & CPA adapters
    │
    ▼
Core application use cases
    ├─ Collection
    ├─ Upstream accounts & quota
    ├─ Access & Routing
    ├─ Pricing policy
    ├─ Billing
    ├─ Statistics query facade
    └─ Management use cases
             │
             ▼
         Persistence

Data contracts：贯穿所有模块
HTTP API：把 Core/Query 用例暴露给管理员和用户
UI：只通过 HTTP API 访问业务
Security / Operations / Test Plan：贯穿设计、实现与发布

实现顺序

Core 会从第一条纵向链路开始逐步长成，不应等所有领域模块完成后一次编写。推荐顺序：

P0 runtime/performance spike：验证双 Go runtime、零常驻 goroutine、SQLite driver、callback-driven pump、schema 3 协商、stream hook RPC 字节量、disable/reconfigure/restart 和 24h soak；失败则确定 sidecar 或 CPA host-contract 改造；
冻结数据契约 v1；
建立 Dev runtime 最小可加载骨架，并完成 required-plugin readiness + sentinel/gateway 门禁；
建立 SQLite、migration、Repository、ProjectionEvent 和 Unit of Work；
打通 Collection 的 durable Request/Execution/Usage 事实链，并建立 UpstreamAccount/Auth 引用目录；
实现不可变 Pricing Snapshot、GPT-5.6/Fast golden cases 和发布流程；
实现 Billing 纯领域计算和不可变账本；
实现 Access/Route，并由 Core 组合出真实请求闭环；
完成插件自管 Key、管理用例和 v1 Management/User API；
实现 Statistics MVP 增量聚合和查询；
实现用户金额页与管理员 UI；
按 Operations 完成打包、备份、监控和升级流程，并通过 Test Plan 全部门禁。

第八步结束时必须先形成最小价值闭环：签发 Key → 金额准入 → 指定 Codex 账户 → 调用 → 按实际 Usage 扣费 → 额度耗尽拒绝。取消、失败和迟到 Usage 也必须在这个闭环中验收，不能留到 UI 阶段。

第一版 c-shared 动态库默认采用 callback-driven maintenance；复杂常驻聚合、归档、备份和 provider refresh 只有 soak gate 通过后才进入动态库，否则由 sidecar/运维命令承担。CPA home.enabled 整体不支持，二进制升级要求排空并重启 CPA。

Security 不是最后补做的模块：exclusive/sentinel/gateway、secret 处理、租户 scope 和 fail-closed 从第一条纵向链路就必须实现。每个阶段都执行 Test Plan 对应 gate，不能等发布前一次性补测试。

5.3 KiB Raw Blame History Unescape Escape

功能模块

模块列表

结构关系

实现顺序

5.3 KiB

Raw Blame History