first commit

openspec/changes/init-promptcr-platform/specs/model-adapters/spec.md

@@ -0,0 +1,38 @@
+# 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` 读取