架构总览
primerouter 是一个 API 网关——你的请求经过认证、路由、格式转换、计费、最终落到上游模型供应商。本页面只讲对外可见的关键链路与设计原则，不涉及内部实现细节。
请求流转
┌─────────┐
│ 客户端 │ (你的 SDK / 工具)
└────┬────┘
│ HTTPS
▼
┌─────────────────────────────────────┐
│ 1. 认证 Bearer / API key │
├─────────────────────────────────────┤
│ 2. 限流 用户 + 模型双维度 │
├─────────────────────────────────────┤
│ 3. 路由选择 权重 / 优先级 / 亲和 │
│ ┌────────────────┐ │
│ │ Ability 表查询 │ │
│ │ group×model×ch │ │
│ └────────────────┘ │
├─────────────────────────────────────┤
│ 4. 格式适配 OpenAI ⇄ Claude ⇄ │
│ Gemini ⇄ 上游原生 │
├─────────────────────────────────────┤
│ 5. 预扣配额 按估算 token 上限 │
├─────────────────────────────────────┤
│ 6. 上游请求 HTTPS 直连 │
│ ▲ ▼ │
│ 响应/SSE 上游 API │
├─────────────────────────────────────┤
│ 7. 结算 用 upstream usage 字节 │
│ 一致结算，多退少补 │
├─────────────────────────────────────┤
│ 8. 审计 trace-id + upstream SHA │
│ + parity 字段写入账本 │
└─────────────────┬───────────────────┘
▼
你的客户端关键设计原则
适配器隔离
每个上游供应商是一个独立的适配器，负责：
- 请求转换：把统一请求格式转换成上游期望的 JSON
- 认证头：注入对应的 Bearer / API key / 签名
- 响应解析：把上游响应（含 SSE 流）解析为统一格式
- 用量计算：从上游响应中精确读取 token 数
新增上游不影响其他渠道。
配额与计费分离
PreConsume → Settle → Refund 三步走：
- 请求进来时按估算上限预扣
- 上游响应返回后用真实
usage结算 - 失败 / 提前结束时 退款
任何一步异常不会导致重复扣费或漏计。
审计轨迹
每条请求生成的账本记录至少包含：
| 字段 | 含义 |
|---|---|
trace_id | 唯一请求 ID（响应 header 也带） |
upstream_provider | 实际路由到哪个供应商 |
upstream_model | 上游模型完整标识 |
upstream_sha | 上游响应可验证签名（如有） |
prompt_tokens / completion_tokens | 与上游字节一致 |
parity | 与上游 usage 比对结果 |
这是「不膨胀 token」承诺的可程序化验证依据。
对外可见的边界
primerouter 暴露给你的接口边界：
| 边界 | 说明 |
|---|---|
| REST / SSE 端点 | https://primerouter.ai（base_url） |
| 管理后台 | https://primerouter.ai/console |
| Chat 页面 | https://primerouter.ai/chat（也可 console 内访问） |
| API Reference | 见 API 文档 |