# Spec: model-adapters

## ADDED Requirements

### Requirement: 统一模型适配器抽象
系统 SHALL 定义抽象基类 `ModelAdapter`，统一 `chat(prompt, params)` 接口，返回结构固定为：审查文本 + token 用量 + 耗时。

#### Scenario: 统一返回结构
- **WHEN** 任一适配器完成一次调用
- **THEN** 返回结构包含审查文本、token 用量与耗时三个字段

### Requirement: 三厂商 OpenAI 兼容适配器
系统 SHALL 实现 DeepSeek、Kimi、通义千问三个适配器，三者 MUST 统一按 OpenAI 兼容格式对接（统一 base_url + api_key + model 调用约定，可基于 OpenAI SDK），厂商差异只允许体现在配置项上，MUST NOT 为某厂商单独发明调用协议。

#### Scenario: 真实 API 调用
- **WHEN** 配置好任一厂商的 base_url 与 api_key 后发起调用
- **THEN** 该适配器以 OpenAI 兼容格式完成一次真实调用并返回统一结构

### Requirement: 工厂模式创建模型实例
系统 SHALL 通过工厂按配置创建模型实例，上层只传模型标识即可运行时切换。

#### Scenario: 运行时切换模型
- **WHEN** 上层以不同模型标识请求模型实例
- **THEN** 工厂返回对应厂商的适配器实例，上层代码无需改动

### Requirement: 并发控制与指数退避重试
适配层 SHALL 内置基于信号量的并发控制器与指数退避重试器，限流与网络抖动对上层透明。

#### Scenario: 限流自动重试
- **WHEN** API 返回限流或超时错误
- **THEN** 适配器自动按指数退避重试，超过阈值后向上报告失败

### Requirement: 密钥管理
系统 MUST NOT 在代码中硬编码任何 API Key；密钥一律走环境变量或 `.env`，不入库、不进 Git、不进前端 bundle。

#### Scenario: 密钥来源检查
- **WHEN** 检查仓库代码与前端构建产物
- **THEN** 不存在任何硬编码密钥，密钥仅从环境变量或 `.env` 读取