fix: address phase 1 ai review

docs/api.md

@@ -42,7 +42,7 @@
 
 ## 对外接口
 
-> **重要约定**：`model` 字段传的是**能力别名**（如 `title-standard` / `image-hd`），不是具体供应商模型名。后台把别名映射到当前的具体模型，换供应商时调用方零改动。供应商特有参数放 `parameters` 透传对象，核心字段保持稳定。
+> **重要约定**：`model` 字段传的是**能力别名**（如 `title-standard` / `image-hd`），不是具体供应商模型名。后台把别名映射到当前的具体模型，换供应商时调用方零改动。供应商特有参数放 `parameters`，但只允许 Provider 白名单内的安全参数透传；`model`、`n`、`size`、`resolution`、`messages`、`image*` 等核心/计费字段由服务端固定，调用方传入时忽略。
 
 ### `POST /api/v1/generate/title`
 
@@ -54,7 +54,7 @@
   "model": "title-standard",      // 能力别名，非具体模型名；可选，缺省用该操作的默认别名
   "image_url": "https://...",     // 可选，看图生成时传商品图（或 image_base64）
   "resolution": "1K",             // 可选，影响计费规则匹配
-  "parameters": {}                // 可选，供应商特有参数透传，未知字段忽略
+  "parameters": {}                // 可选，安全供应商参数；未知字段/核心字段忽略
 }
 ```
 
@@ -84,7 +84,7 @@
   "image_base64": "data:image/png;base64,...",  // 或 image_url；改图类模型(如映射到 gpt-image-2)原图必传
   "resolution": "1K",
   "aspect_ratio": "1:1",
-  "parameters": {}                // 可选，供应商特有参数透传
+  "parameters": {}                // 可选，安全供应商参数；未知字段/核心字段忽略
 }
 ```
 
@@ -101,7 +101,7 @@
 }
 ```
 
-要点：上游失败返回 `upstream_error` 且**不扣点**（已预扣则退回）。结果默认存对象存储返回 `image_url`，避免同步响应体过大。
+要点：改图类模型缺原图返回 `bad_request`，不落 500；上游失败返回 `upstream_error` 且**不扣点**（已预扣则退回）。结果默认存对象存储返回 `image_url`，避免同步响应体过大。
 
 ### `GET /api/v1/balance`
 
@@ -217,9 +217,9 @@ class Provider(Protocol):
 要点：
 
 - `ResolvedModel` 来自数据库 AiModel（形状同 `cmbot/config/ai_models.json`，外加 `capabilities`；`api_key` 在库中以 Fernet 加密，使用时解密，不落明文）。
-- `TextGenerationResult` 包含 `text`、清洗后的 `titles`、`model_used`、`raw`；`ImageGenerationResult` 包含图片 bytes、`model_used`、`raw`。图片落对象存储并返回 URL 属 T-302 之后的 API 编排职责。
+- `TextGenerationResult` 包含 `text`、清洗后的 `titles`、`model_used`、`raw`；`ImageGenerationResult` 包含图片 bytes、`model_used`、`raw`。`raw` 仅供本次解析/排障摘要使用，调用记录不得整包保存或打印，避免 base64 大图和上游敏感字段入库；图片落对象存储并返回 URL 属 T-302 之后的 API 编排职责。
 - 适配器按 `api_type`（`chat`/`gemini`/`images`/`images_edits`/`auto`）从注册表选取，新增供应商 = 新增一个适配器，不改对外接口。
-- `parameters` 为供应商特有参数透传；适配器负责把统一入参翻译成各家上游格式。
+- `parameters` 为供应商特有参数的安全子集；适配器负责白名单过滤并把统一入参翻译成各家上游格式，核心字段不可被 `parameters` 或 `extra_body` 覆盖。
 - 配置热生效：每次调用读当前 AiModel/ModelAlias，后台改动及时反映（或带缓存失效）。
 - 配置审计：后台保存/删除 AiModel、ModelAlias 时写 `AiConfigAuditLog`；记录 actor/action/target/changed_fields/changes/created_at，admin 只读查看；密钥变更只记录 empty/set 状态。
 - 区分异常：别名/能力不匹配 → 业务错误（400 类，如 `model_not_allowed`）；上游网络/超时/服务错误 → `upstream_error`（502，触发退点）。