# 模型重映射逻辑（当前实现）

最后更新：2026-03-02

本文描述当前代理中的模型重映射链路（含 Gemini 3/3.1 Pro 调整后的行为）。

## 1）整体流程

无论是 OpenAI 协议还是 Gemini 原生协议，请求模型都会经过两段处理：

1. 静态路由解析（全局规则）：
   - 在选账号前执行一次。
   - 代码：`src-tauri/src/proxy/common/model_mapping.rs` 的 `resolve_model_route`。
2. 动态账号感知改写（条件回退）：
   - 在选中账号后执行。
   - 代码：`src-tauri/src/proxy/token_manager.rs` 的 `resolve_dynamic_model_for_account`。

使用该流程的入口：
- `src-tauri/src/proxy/handlers/openai.rs`
- `src-tauri/src/proxy/handlers/gemini.rs`

## 2）静态路由优先级

`resolve_model_route(original_model, custom_mapping)` 的优先级从高到低为：

1. 官方动态淘汰转发规则：
   - `DYNAMIC_MODEL_FORWARDING_RULES`
2. 用户自定义精确映射：
   - `custom_mapping[original_model]`
3. 用户自定义通配符映射：
   - 按“非 `*` 字符数”比较，越具体优先级越高
4. 系统内置默认映射：
   - `map_claude_model_to_gemini`

都不命中时，模型名原样透传。

## 3）当前 Gemini Pro 内置映射策略

当前策略是：具体模型 ID 直接透传；只有泛别名会归一化。

具体 ID（不做跨版本强制改写）：
- `gemini-3-pro-high -> gemini-3-pro-high`
- `gemini-3-pro-low -> gemini-3-pro-low`
- `gemini-3-pro-preview -> gemini-3-pro-preview`
- `gemini-3.1-pro-high -> gemini-3.1-pro-high`
- `gemini-3.1-pro-low -> gemini-3.1-pro-low`
- `gemini-3.1-pro-preview -> gemini-3.1-pro-preview`

泛别名（仍映射到 preview 入口）：
- `gemini-3-pro -> gemini-3-pro-preview`
- `gemini-3.1-pro -> gemini-3.1-pro-preview`

代码位置：
- `src-tauri/src/proxy/common/model_mapping.rs`

## 4）动态账号感知改写（仅在需要时触发）

选中账号后，系统会读取该账号本地 quota 里的可用模型，判断当前模型是否可用。

行为如下：

1. 读取账号 JSON：`quota.models[*].name`。
2. 仅针对 Gemini 3/3.1 Pro 家族构造候选回退列表。
3. 候选顺序：
   - 先尝试当前模型
   - 再按预设顺序尝试同家族其他兼容模型
4. 选中第一个在账号可用集合里存在的模型。
5. 若都不命中，则保持当前模型不变。

关键点：
- 如果请求模型本身可用，不会发生重映射。
- 只有请求模型不可用且存在兼容候选时，才会重映射。

代码位置：
- `src-tauri/src/proxy/token_manager.rs`
  - `get_available_models_from_json`
  - `build_dynamic_model_candidates`
  - `resolve_dynamic_model_for_account`

## 5）日志观测点

可通过日志判断每一步是否触发：

- 静态映射日志：
  - `[Router] 系统默认映射: <original> -> <mapped>`
- 动态改写日志：
  - `[Dynamic-Model-Rewrite] account=<id> <from> -> <to>`

如果某次请求没有出现 `Dynamic-Model-Rewrite`，说明该账号直接使用了当前模型。

## 6）示例

示例 A（不改写）：
- 请求：`gemini-3-pro-high`
- 账号可用模型包含：`gemini-3-pro-high`
- 最终上游模型：`gemini-3-pro-high`

示例 B（发生回退改写）：
- 请求：`gemini-3-pro-high`
- 账号不可用：`gemini-3-pro-high`
- 账号可用：`gemini-3.1-pro-high`
- 最终上游模型：`gemini-3.1-pro-high`

示例 C（泛别名）：
- 请求：`gemini-3-pro`
- 静态阶段先映射为：`gemini-3-pro-preview`
- 动态阶段再根据账号可用模型决定是否继续回退。

## 7）设计目标

该设计同时满足三点：
- 具体模型优先保持用户原始意图。
- 泛别名保留历史兼容能力。
- 多账号能力不一致时，通过动态回退提升可用性。