diff --git a/docs/user-manual/en/2-providers/2.1-add.md b/docs/user-manual/en/2-providers/2.1-add.md index 85bf684fd..2e1102461 100644 --- a/docs/user-manual/en/2-providers/2.1-add.md +++ b/docs/user-manual/en/2-providers/2.1-add.md @@ -60,8 +60,8 @@ Presets are pre-configured provider templates that only require an API Key to us The Claude Desktop panel includes provider presets translated from the Claude Code preset catalog. When adding one, choose between: -- **Direct mode**: the provider exposes a native Anthropic Messages API that Claude Desktop can reach directly -- **Model mapping mode**: non-Claude models are mapped through the CC Switch local gateway into Sonnet / Opus / Haiku routes +- **Direct mode**: the provider exposes a native Anthropic Messages API and its model names are Claude Desktop-recognized role IDs (`claude-sonnet-*` / `claude-opus-*` / `claude-haiku-*`), so Claude Desktop can reach it directly +- **Model mapping mode**: model names outside the three role IDs (legacy Claude IDs, or non-Claude models like DeepSeek / Kimi) are mapped through the CC Switch local gateway into Sonnet / Opus / Haiku routes - **Claude Desktop Official**: restores Claude Desktop's official sign-in mode See [2.6 Claude Desktop](./2.6-claude-desktop.md) for the full workflow. diff --git a/docs/user-manual/en/2-providers/2.6-claude-desktop.md b/docs/user-manual/en/2-providers/2.6-claude-desktop.md index 1aa0fce40..7eb946cd8 100644 --- a/docs/user-manual/en/2-providers/2.6-claude-desktop.md +++ b/docs/user-manual/en/2-providers/2.6-claude-desktop.md @@ -7,7 +7,7 @@ The Claude Desktop panel lets you manage Claude Desktop provider configurations Once enabled, you can: - Use third-party Anthropic-compatible providers in Claude Desktop -- Configure model mapping for non-Claude models such as DeepSeek, Kimi, DouBao, OpenAI, and Gemini +- Configure model mapping for models outside the three role IDs: legacy Claude IDs (e.g. `claude-3-5-sonnet`) and non-Claude models like DeepSeek / Kimi / DouBao / OpenAI / Gemini all need it - Reuse Copilot / Codex OAuth account-based providers - Switch between Claude Desktop official mode and third-party providers @@ -51,13 +51,13 @@ If you already have many providers configured in Claude Code, this one-click imp Import rules: - Existing providers with the same ID are not overwritten -- Claude Code providers that can connect directly and use safe model names are imported as direct mode -- Providers that need model conversion are imported as model mapping mode when possible +- Providers whose model names are the three role IDs (`claude-sonnet-*` / `claude-opus-*` / `claude-haiku-*`) and can connect directly are imported as direct mode +- Providers whose model names are not the three role IDs (including legacy Claude IDs), or that need format conversion, are imported as model mapping mode when possible - `ANTHROPIC_DEFAULT_SONNET_MODEL`, `ANTHROPIC_DEFAULT_OPUS_MODEL`, and `ANTHROPIC_DEFAULT_HAIKU_MODEL` are converted into Desktop Sonnet / Opus / Haiku mappings - The legacy `[1M]` suffix is converted into the `supports1m` flag in the Claude Desktop profile - Providers whose model mapping cannot be inferred are skipped -After importing, review each provider's model mapping against your actual upstream models. Non-Claude models such as Kimi, DeepSeek, GLM, and DouBao usually need model mapping mode. +After importing, review each provider's model mapping against your actual upstream models. Any model that is not a `claude-sonnet-*` / `claude-opus-*` / `claude-haiku-*` role ID—including non-Claude models like Kimi, DeepSeek, GLM, and DouBao, as well as legacy Claude IDs—usually needs model mapping mode. If you already configured providers in Claude Code, prefer **Import existing providers from Claude Code**. This is the easiest migration path to Claude Desktop. @@ -71,7 +71,7 @@ You can choose: - **Custom configuration**: manually enter name, endpoint URL, API key, and model settings - **Claude Desktop Official**: restore Claude Desktop official sign-in mode -For ordinary Anthropic Messages API-compatible providers, you usually only need to: +For native Anthropic Messages API providers that already accept Claude Desktop's three role IDs (`claude-sonnet-*` / `claude-opus-*` / `claude-haiku-*`), you usually only need to: 1. Choose a preset or custom provider 2. Fill in **API Key** @@ -110,17 +110,17 @@ In direct mode, CC Switch points the Claude Desktop 3P profile to the provider e Use this when: - The provider exposes native Anthropic Messages API -- Model IDs use `claude-*` or `anthropic/claude-*` +- Model IDs are Claude Desktop-recognized role names: `claude-sonnet-*`, `claude-opus-*`, or `claude-haiku-*` (or the same with the `anthropic/claude-` prefix) - No format conversion is needed - CC Switch local routing does not need to stay running while in use The "Manually specify Claude Desktop models" option in direct mode is advanced. Most native Claude model providers do not need it because Claude Desktop can fetch `/v1/models` automatically. -Only fill it in when the provider's `/v1/models` is unavailable, or when the returned model names cannot be recognized by Claude Desktop. +Only fill it in when the provider's `/v1/models` is unavailable, or when the returned model names cannot be recognized by Claude Desktop. Manually entered model names must follow the `claude-sonnet-*`, `claude-opus-*`, or `claude-haiku-*` shape (legacy IDs like `claude-3-5-sonnet-…` are rejected). ### Model Mapping Mode -Model mapping mode is for providers that expose non-Claude models, such as DeepSeek and Kimi, or when CC Switch needs to convert the API format. +Model mapping mode is for providers whose models are not `claude-sonnet-*` / `claude-opus-*` / `claude-haiku-*` role IDs (including legacy Claude IDs and non-Claude models such as DeepSeek and Kimi), or when CC Switch needs to convert the API format. After **Needs model mapping** is enabled, Claude Desktop connects to the CC Switch local gateway: @@ -144,7 +144,7 @@ Supported API formats: | OpenAI Responses API | OpenAI Responses-compatible endpoints | | Gemini Native generateContent | Gemini native API | -In model mapping mode, Claude Desktop only sees `claude-*` style models. Real upstream model names are not written directly into the Claude Desktop profile. +In model mapping mode, Claude Desktop only sees the three role routes: `claude-sonnet-*`, `claude-opus-*`, and `claude-haiku-*`. Real upstream model names are not written directly into the Claude Desktop profile. ## Configure Model Mapping @@ -173,7 +173,7 @@ For DeepSeek: |------------|-------------------|-----------------|----| | Sonnet | DeepSeek V4 Pro | `deepseek-v4-pro` | Match provider capability | -The reason is that Claude Desktop now rejects non-`claude-*` models, so CC Switch local routing performs a model mapping pass. +The reason is that Claude Desktop now rejects models outside the Sonnet / Opus / Haiku role families, so CC Switch local routing performs a model mapping pass. ### Multiple Role Mapping @@ -185,7 +185,7 @@ You can configure Sonnet, Opus, and Haiku at the same time: | Opus | Higher quality or complex tasks | | Haiku | Fast, lower-cost model | -If the provider only has one model, one role is enough. Model mapping mode requires at least one valid mapping. +If the provider only has one model, filling in just one role's requested model is enough; blank roles automatically inherit the first filled model (Sonnet first), so the Haiku that sub-agents call is always available. Model mapping mode requires at least one requested model. ## Local Routing Toggle @@ -258,7 +258,7 @@ The Claude Desktop panel may show "Claude Desktop configuration needs attention" | Message | How to handle | |---------|---------------| | Current platform is not supported | Only macOS / Windows currently support writing 3P configuration | -| Profile contains non-`claude-*` model names | Switch to the current provider again, or edit the provider to use model mapping | +| Profile contains model names outside the Sonnet / Opus / Haiku role families | Switch to the current provider again, or edit the provider to use model mapping | | Model mapping is enabled but no valid route exists | Edit the provider and add at least one model mapping | | Local routing token has not been generated | Switch to the provider again; CC Switch will write a new local token | | Profile URL does not match the current provider | Switch to the current provider again so the profile points to the expected URL | @@ -285,7 +285,7 @@ Edit the provider, fill in **Menu display name** in model mapping, then enable t ### Why does direct mode fail? -Direct mode requires the provider to expose native Anthropic Messages API and accept Claude-safe model names used by Claude Desktop. If the provider uses OpenAI, Gemini, or non-Claude model IDs, enable **Needs model mapping**. +Direct mode requires the provider to expose native Anthropic Messages API and accept Claude Desktop's three role IDs (`claude-sonnet-*` / `claude-opus-*` / `claude-haiku-*`). If the provider uses OpenAI, Gemini, non-Claude model IDs, or legacy Claude IDs (e.g. `claude-3-5-sonnet-…`)—any ID outside the three roles—direct mode fails, so enable **Needs model mapping**. ### Can I close CC Switch? @@ -296,7 +296,7 @@ It depends on the mode: ### Are real upstream model names written into Claude Desktop? -Not in model mapping mode. The Claude Desktop profile only stores safe `claude-*` routes and display names. Real upstream model names stay in the CC Switch provider configuration and are mapped when requests pass through the local gateway. +Not in model mapping mode. The Claude Desktop profile only stores safe Sonnet / Opus / Haiku role routes and display names. Real upstream model names stay in the CC Switch provider configuration and are mapped when requests pass through the local gateway. ## Next Steps diff --git a/docs/user-manual/ja/2-providers/2.1-add.md b/docs/user-manual/ja/2-providers/2.1-add.md index 8b2017ed6..b913e89fd 100644 --- a/docs/user-manual/ja/2-providers/2.1-add.md +++ b/docs/user-manual/ja/2-providers/2.1-add.md @@ -60,8 +60,8 @@ Claude Desktop パネルには、Claude Code のプリセットカタログから変換されたプロバイダープリセットが含まれます。追加時には次のモードを選択できます： -- **直結モード**：プロバイダーがネイティブの Anthropic Messages API を提供し、Claude Desktop から直接アクセスできる場合 -- **モデルマッピングモード**：非 Claude モデルを CC Switch ローカルゲートウェイ経由で Sonnet / Opus / Haiku ルートへマッピング +- **直結モード**：プロバイダーがネイティブの Anthropic Messages API を提供し、モデル名が Claude Desktop の認識できる三つの役割 ID（`claude-sonnet-*` / `claude-opus-*` / `claude-haiku-*`）で、Claude Desktop から直接アクセスできる場合 +- **モデルマッピングモード**：三つの役割 ID 以外のモデル名（旧式 Claude ID や DeepSeek / Kimi などの非 Claude モデル）を CC Switch ローカルゲートウェイ経由で Sonnet / Opus / Haiku ルートへマッピング - **Claude Desktop Official**：Claude Desktop の公式サインインモードへ戻す 詳しい手順は [2.6 Claude Desktop](./2.6-claude-desktop.md) を参照してください。 diff --git a/docs/user-manual/ja/2-providers/2.6-claude-desktop.md b/docs/user-manual/ja/2-providers/2.6-claude-desktop.md index ebd934c6d..684b27728 100644 --- a/docs/user-manual/ja/2-providers/2.6-claude-desktop.md +++ b/docs/user-manual/ja/2-providers/2.6-claude-desktop.md @@ -7,7 +7,7 @@ Claude Desktop パネルでは、CC Switch 上で Claude Desktop のプロバイ 有効にすると、次のことができます。 - Claude Desktop でサードパーティの Anthropic 互換プロバイダーを使う -- DeepSeek、Kimi、DouBao、OpenAI、Gemini などの非 Claude モデルにモデルマッピングを設定する +- 三つの役割 ID 以外のモデルにマッピングを設定する：旧式 Claude ID（例：`claude-3-5-sonnet`）や DeepSeek / Kimi / DouBao / OpenAI / Gemini などの非 Claude モデルはいずれも必要 - Copilot / Codex OAuth のアカウント型プロバイダーを再利用する - Claude Desktop 公式モードとサードパーティプロバイダーを切り替える @@ -51,13 +51,13 @@ Claude Code 側に多くのプロバイダーがすでにある場合、この インポートルール： - 同じ ID のプロバイダーがすでにある場合は上書きしません -- 直接接続でき、モデル名が安全な Claude Code プロバイダーは直結モードとしてインポートされます -- モデル変換が必要なプロバイダーは、可能な場合モデルマッピングモードとしてインポートされます +- モデル名が三つの役割 ID（`claude-sonnet-*` / `claude-opus-*` / `claude-haiku-*`）で直接接続できるプロバイダーは直結モードとしてインポートされます +- モデル名が三つの役割 ID でない（旧式 Claude ID を含む）、または形式変換が必要なプロバイダーは、可能な場合モデルマッピングモードとしてインポートされます - `ANTHROPIC_DEFAULT_SONNET_MODEL`、`ANTHROPIC_DEFAULT_OPUS_MODEL`、`ANTHROPIC_DEFAULT_HAIKU_MODEL` は Desktop の Sonnet / Opus / Haiku マッピングに変換されます - 旧形式の `[1M]` サフィックスは Claude Desktop profile の `supports1m` フラグに変換されます - モデルマッピングを判断できないプロバイダーはスキップされます -インポート後は、各プロバイダーのモデルマッピングが実際のアップストリームモデルと合っているか確認してください。Kimi、DeepSeek、GLM、DouBao などの非 Claude モデルは通常、モデルマッピングモードが必要です。 +インポート後は、各プロバイダーのモデルマッピングが実際のアップストリームモデルと合っているか確認してください。`claude-sonnet-*` / `claude-opus-*` / `claude-haiku-*` の三つの役割 ID 以外のモデル——Kimi、DeepSeek、GLM、DouBao などの非 Claude モデルや旧式 Claude ID を含む——は通常、モデルマッピングモードが必要です。 すでに Claude Code でプロバイダーを設定している場合は、まず **Claude Code の既存プロバイダーをインポート** を使ってください。Claude Desktop へ移行する最も簡単な方法です。 @@ -71,7 +71,7 @@ Claude Code 側に多くのプロバイダーがすでにある場合、この - **カスタム設定**：名前、エンドポイント URL、API Key、モデル設定を手動入力する - **Claude Desktop Official**：Claude Desktop の公式サインインモードへ戻す -通常の Anthropic Messages API 互換プロバイダーでは、基本的に次の手順だけで十分です。 +Claude Desktop の三つの役割 ID（`claude-sonnet-*` / `claude-opus-*` / `claude-haiku-*`）をすでに受け付けるネイティブ Anthropic Messages API プロバイダーでは、基本的に次の手順だけで十分です。 1. プリセットまたはカスタムプロバイダーを選ぶ 2. **API Key** を入力する @@ -110,17 +110,17 @@ Claude Code 側に多くのプロバイダーがすでにある場合、この 適したケース： - プロバイダーがネイティブの Anthropic Messages API を公開している -- モデル ID が `claude-*` または `anthropic/claude-*` +- モデル ID が Claude Desktop の認識できる役割名：`claude-sonnet-*`、`claude-opus-*`、`claude-haiku-*`（または `anthropic/claude-` 接頭辞の同種名） - 形式変換が不要 - 使用中に CC Switch のローカルルーティングを起動し続ける必要がない 直結モードの「Claude Desktop モデルを手動指定」は高度な任意設定です。多くのネイティブ Claude モデルプロバイダーでは不要で、Claude Desktop が `/v1/models` を自動取得します。 -プロバイダーの `/v1/models` が使えない、または返されるモデル名を Claude Desktop が認識できない場合だけ手動で追加してください。 +プロバイダーの `/v1/models` が使えない、または返されるモデル名を Claude Desktop が認識できない場合だけ手動で追加してください。手動で入力するモデル名は `claude-sonnet-*`、`claude-opus-*`、`claude-haiku-*` の形式である必要があります（`claude-3-5-sonnet-…` のような旧式 ID は拒否されます）。 ### モデルマッピングモード -モデルマッピングモードは、DeepSeek や Kimi など Claude 系列ではないモデルを提供するプロバイダー、または CC Switch による API 形式変換が必要な場合に適しています。 +モデルマッピングモードは、プロバイダーのモデルが `claude-sonnet-*` / `claude-opus-*` / `claude-haiku-*` の三つの役割 ID でない場合（旧式 Claude ID や DeepSeek、Kimi などの非 Claude モデルを含む）、または CC Switch による API 形式変換が必要な場合に適しています。 **モデルマッピングが必要** をオンにすると、Claude Desktop は CC Switch のローカルゲートウェイへ接続します。 @@ -144,7 +144,7 @@ CC Switch は次を担当します。 | OpenAI Responses API | OpenAI Responses 互換エンドポイント | | Gemini Native generateContent | Gemini ネイティブ API | -モデルマッピングモードでは、Claude Desktop から見えるのは `claude-*` 形式のモデルだけです。実際のアップストリームモデル名は Claude Desktop profile に直接書き込まれません。 +モデルマッピングモードでは、Claude Desktop から見えるのは `claude-sonnet-*` / `claude-opus-*` / `claude-haiku-*` の 3 種類の役割ルートだけです。実際のアップストリームモデル名は Claude Desktop profile に直接書き込まれません。 ## モデルマッピングを設定する @@ -173,7 +173,7 @@ DeepSeek を使う場合： |------------|----------------|------------------|----| | Sonnet | DeepSeek V4 Pro | `deepseek-v4-pro` | プロバイダー能力に合わせる | -理由は、現在の Claude Desktop が非 `claude-*` モデルを拒否するためです。そのため CC Switch のルーティング機能で一度モデルマッピングを行います。 +理由は、現在の Claude Desktop が Sonnet / Opus / Haiku の役割ファミリー以外のモデルを拒否するためです。そのため CC Switch のルーティング機能で一度モデルマッピングを行います。 ### 複数役割のマッピング @@ -185,7 +185,7 @@ Sonnet、Opus、Haiku の 3 つを同時に設定できます。 | Opus | 高品質または複雑なタスク | | Haiku | 高速・低コストモデル | -プロバイダーにモデルが 1 つしかない場合は、1 つの役割だけでも構いません。モデルマッピングモードでは少なくとも 1 件の有効なマッピングが必要です。 +プロバイダーにモデルが 1 つしかない場合は、1 つの役割のリクエストモデルだけ入力すれば十分です。空欄の役割は最初に入力したモデル（Sonnet 優先）を自動的に引き継ぐため、サブ agent が呼び出す Haiku なども常に利用できます。モデルマッピングモードでは少なくとも 1 つのリクエストモデルが必要です。 ## ローカルルーティング切り替え @@ -258,7 +258,7 @@ Claude Desktop パネル上部に「Claude Desktop 設定の確認が必要で | 表示 | 対処方法 | |------|----------| | 現在のプラットフォームは未対応 | 3P 設定の書き込みは現在 macOS / Windows のみ対応 | -| profile に非 `claude-*` モデル名がある | 現在のプロバイダーへ再度切り替える、またはモデルマッピングを使うよう編集する | +| profile に Sonnet / Opus / Haiku の役割ファミリー以外のモデル名がある | 現在のプロバイダーへ再度切り替える、またはモデルマッピングを使うよう編集する | | モデルマッピングが有効だが有効なルートがない | プロバイダーを編集し、少なくとも 1 件のモデルマッピングを追加する | | ローカルルーティング token が未生成 | そのプロバイダーへ再度切り替えると、CC Switch が新しい token を書き込みます | | profile の URL が現在のプロバイダーと一致しない | 現在のプロバイダーへ再度切り替え、profile を正しい URL に戻します | @@ -285,7 +285,7 @@ Claude Desktop を完全に終了して再起動してください。Claude Desk ### 直結モードでエラーになるのはなぜ？ -直結モードでは、プロバイダーがネイティブの Anthropic Messages API を提供し、Claude Desktop が使う Claude 安全モデル名を受け入れる必要があります。プロバイダーが OpenAI、Gemini、または非 Claude モデル ID を使う場合は **モデルマッピングが必要** をオンにしてください。 +直結モードでは、プロバイダーがネイティブの Anthropic Messages API を提供し、Claude Desktop の三つの役割 ID（`claude-sonnet-*` / `claude-opus-*` / `claude-haiku-*`）を受け入れる必要があります。プロバイダーが OpenAI、Gemini、非 Claude モデル ID、または旧式 Claude ID（例：`claude-3-5-sonnet-…`）など三つの役割 ID 以外を使う場合は失敗するため、**モデルマッピングが必要** をオンにしてください。 ### CC Switch を閉じてもよい？ @@ -296,7 +296,7 @@ Claude Desktop を完全に終了して再起動してください。Claude Desk ### 実際のアップストリームモデル名は Claude Desktop に書き込まれる？ -モデルマッピングモードでは書き込まれません。Claude Desktop profile には安全な `claude-*` ルートと表示名だけが保存されます。実際のアップストリームモデル名は CC Switch のプロバイダー設定に保存され、ローカルゲートウェイを通るリクエスト時にマッピングされます。 +モデルマッピングモードでは書き込まれません。Claude Desktop profile には安全な Sonnet / Opus / Haiku 役割ルートと表示名だけが保存されます。実際のアップストリームモデル名は CC Switch のプロバイダー設定に保存され、ローカルゲートウェイを通るリクエスト時にマッピングされます。 ## 次のステップ diff --git a/docs/user-manual/zh/2-providers/2.1-add.md b/docs/user-manual/zh/2-providers/2.1-add.md index 674bd2617..8147997c1 100644 --- a/docs/user-manual/zh/2-providers/2.1-add.md +++ b/docs/user-manual/zh/2-providers/2.1-add.md @@ -60,8 +60,8 @@ Claude Desktop 面板内置从 Claude Code 预设目录转换而来的供应商预设。添加时可选择： -- **直连模式**：供应商原生支持 Anthropic Messages API，Claude Desktop 可直接访问 -- **模型映射模式**：非 Claude 模型通过 CC Switch 本地网关映射为 Sonnet / Opus / Haiku 路由 +- **直连模式**：供应商原生支持 Anthropic Messages API，且模型名是 Claude Desktop 可识别的三档角色 ID（`claude-sonnet-*` / `claude-opus-*` / `claude-haiku-*`），Claude Desktop 可直接访问 +- **模型映射模式**：模型名非三档角色 ID（旧式 Claude ID、或 DeepSeek / Kimi 等非 Claude 模型）通过 CC Switch 本地网关映射为 Sonnet / Opus / Haiku 路由 - **Claude Desktop Official**：恢复 Claude Desktop 官方登录模式 完整操作请参阅 [2.6 Claude Desktop](./2.6-claude-desktop.md)。 diff --git a/docs/user-manual/zh/2-providers/2.6-claude-desktop.md b/docs/user-manual/zh/2-providers/2.6-claude-desktop.md index 78f09bc6f..c5d576efa 100644 --- a/docs/user-manual/zh/2-providers/2.6-claude-desktop.md +++ b/docs/user-manual/zh/2-providers/2.6-claude-desktop.md @@ -7,7 +7,7 @@ Claude Desktop 面板用于在 CC Switch 中管理 Claude Desktop 的供应商 开启后，你可以： - 在 Claude Desktop 中使用第三方 Anthropic 兼容供应商 -- 为 DeepSeek、Kimi、DouBao、OpenAI、Gemini 等非 Claude 模型配置模型映射 +- 为三档角色 ID 之外的模型配置映射：旧式 Claude ID（如 `claude-3-5-sonnet`）、以及 DeepSeek / Kimi / DouBao / OpenAI / Gemini 等非 Claude 模型都需要 - 复用 Copilot / Codex OAuth 账号类供应商 - 在 Claude Desktop 官方模式和第三方供应商之间切换 @@ -51,13 +51,13 @@ Claude Desktop 与 Claude Code 是两个不同的应用入口。Claude Code 使 导入规则： - 已存在同 ID 供应商时不会覆盖 -- 能直连且模型名安全的 Claude Code 供应商会导入为直连模式 -- 需要模型转换的供应商会尝试导入为模型映射模式 +- 模型名为三档角色 ID（`claude-sonnet-*` / `claude-opus-*` / `claude-haiku-*`）且能直连的供应商会导入为直连模式 +- 模型名非三档角色 ID（含旧式 Claude ID）或需要格式转换的供应商会尝试导入为模型映射模式 - `ANTHROPIC_DEFAULT_SONNET_MODEL`、`ANTHROPIC_DEFAULT_OPUS_MODEL`、`ANTHROPIC_DEFAULT_HAIKU_MODEL` 会转换为 Desktop 的 Sonnet / Opus / Haiku 映射 - 旧的 `[1M]` 后缀会转换为 Claude Desktop profile 中的 `supports1m` 标记 - 无法判断模型映射的供应商会被跳过 -导入后请检查每个供应商的模型映射是否符合你的实际上游模型。尤其是 Kimi、DeepSeek、GLM、DouBao 这类非 Claude 模型，通常需要使用模型映射模式。 +导入后请检查每个供应商的模型映射是否符合你的实际上游模型。任何不是 `claude-sonnet-*` / `claude-opus-*` / `claude-haiku-*` 三档角色 ID 的模型——包括 Kimi、DeepSeek、GLM、DouBao 等非 Claude 模型，以及旧式 Claude ID——通常都需要使用模型映射模式。 如果你已经在 Claude Code 中配置过供应商，优先使用上面的 **将 Claude Code 中已有的供应商导入**。这是迁移到 Claude Desktop 最省事的路径。 @@ -71,7 +71,7 @@ Claude Desktop 与 Claude Code 是两个不同的应用入口。Claude Code 使 - **自定义供应商**：手动填写名称、接口地址、API Key 和模型设置 - **Claude Desktop Official**：恢复 Claude Desktop 官方登录模式 -对于普通 Anthropic Messages API 兼容供应商，通常只需要： +对于已经接受 Claude Desktop 三档角色 ID（`claude-sonnet-*` / `claude-opus-*` / `claude-haiku-*`）的原生 Anthropic Messages API 供应商，通常只需要： 1. 选择预设或自定义供应商 2. 填写 **API Key** @@ -110,17 +110,17 @@ Claude Desktop 与 Claude Code 是两个不同的应用入口。Claude Code 使 适用场景： - 供应商暴露原生 Anthropic Messages API -- 模型 ID 使用 `claude-*` 或 `anthropic/claude-*` +- 模型 ID 为 Claude Desktop 可识别的角色名：`claude-sonnet-*`、`claude-opus-*`、`claude-haiku-*`（或带 `anthropic/claude-` 前缀的同类名） - 不需要格式转换 - 不需要 CC Switch 在使用期间保持本地路由 直连模式的「手动指定 Claude Desktop 模型列表」是高级选项。多数原生 Claude 模型供应商不需要填写，Claude Desktop 会自动读取 `/v1/models`。 -仅当供应商的 `/v1/models` 不可用，或返回的模型名不能被 Claude Desktop 识别时，再手动添加模型。 +仅当供应商的 `/v1/models` 不可用，或返回的模型名不能被 Claude Desktop 识别时，再手动添加模型。手动填写的模型名必须是 `claude-sonnet-*`、`claude-opus-*` 或 `claude-haiku-*` 形态（旧式 `claude-3-5-sonnet-…` 会被拒绝）。 ### 模型映射模式 -模型映射模式适合供应商提供的不是 Claude 系列模型（比如 deepseek, kimi 等），或接口格式需要 CC Switch 转换。 +模型映射模式适合供应商提供的模型不是 `claude-sonnet-*` / `claude-opus-*` / `claude-haiku-*` 三档角色 ID（包括旧式 Claude ID 和 deepseek、kimi 等非 Claude 模型），或接口格式需要 CC Switch 转换。 开启「需要模型映射」后，Claude Desktop 会连接到 CC Switch 本地网关： @@ -144,7 +144,7 @@ CC Switch 会负责： | OpenAI Responses API | OpenAI Responses 兼容接口 | | Gemini Native generateContent | Gemini 原生接口 | -模型映射模式下，Claude Desktop 只看到 `claude-*` 形式的模型；真实模型名不会直接写进 Claude Desktop profile。 +模型映射模式下，Claude Desktop 只看到 `claude-sonnet-*` / `claude-opus-*` / `claude-haiku-*` 三类角色路由；真实模型名不会直接写进 Claude Desktop profile。 ## 配置模型映射 @@ -173,7 +173,7 @@ CC Switch 会负责： | -------- | --------------- | ----------------- | ---------------- | | Sonnet | DeepSeek V4 Pro | `deepseek-v4-pro` | 按供应商能力选择 | -这样做的原因是 Claude Desktop 现在会拒绝非 `claude-*` 模型，所以需要 CC Switch 的路由功能进行一轮模型映射。 +这样做的原因是 Claude Desktop 现在会拒绝不属于 Sonnet / Opus / Haiku 三类角色的模型，所以需要 CC Switch 的路由功能进行一轮模型映射。 ### 多角色映射 @@ -185,7 +185,7 @@ CC Switch 会负责： | Opus | 高质量或复杂任务模型 | | Haiku | 快速、低成本模型 | -如果供应商只有一个模型，也可以只配置一个角色。模型映射模式至少需要一条有效映射。 +如果供应商只有一个模型，只填写一个角色的实际请求模型也可以；留空的角色会自动沿用第一个已填模型（Sonnet 优先），因此 Haiku 等子 agent 调用始终有模型可用。模型映射模式至少需要填写一个实际请求模型。 ## 本地路由开关 @@ -258,7 +258,7 @@ Claude Desktop 面板顶部可能出现「Claude Desktop 配置需要检查」 | 提示 | 处理方式 | | ------------------------------------ | ------------------------------------------------ | | 当前平台暂不支持 | 目前仅 macOS / Windows 支持写入 3P 配置 | -| profile 中存在非 `claude-*` 模型名 | 重新切换当前供应商，或编辑供应商改用模型映射 | +| profile 中存在非 Sonnet / Opus / Haiku 角色模型名 | 重新切换当前供应商，或编辑供应商改用模型映射 | | 启用了模型映射但没有有效路由 | 编辑供应商，至少添加一条模型映射 | | 本地路由 token 尚未生成 | 重新切换该供应商，CC Switch 会写入新的本地 token | | profile 指向的地址与当前供应商不一致 | 重新切换当前供应商，让 profile 回到正确地址 | @@ -285,7 +285,7 @@ Claude Desktop 面板顶部可能出现「Claude Desktop 配置需要检查」 ### 直连模式下为什么报错？ -直连模式要求供应商提供原生 Anthropic Messages API，并接受 Claude Desktop 使用的 Claude 安全模型名。如果供应商使用 OpenAI、Gemini 或非 Claude 模型 ID，请开启「需要模型映射」。 +直连模式要求供应商提供原生 Anthropic Messages API，并接受 Claude Desktop 的三档角色 ID（`claude-sonnet-*` / `claude-opus-*` / `claude-haiku-*`）。如果供应商使用 OpenAI、Gemini、非 Claude 模型 ID，或旧式 Claude ID（如 `claude-3-5-sonnet-…`）等任何非三档角色 ID，直连都会失败，请开启「需要模型映射」。 ### 可以关闭 CC Switch 吗？ @@ -296,7 +296,7 @@ Claude Desktop 面板顶部可能出现「Claude Desktop 配置需要检查」 ### 是否会把真实上游模型名写入 Claude Desktop？ -模型映射模式不会。Claude Desktop profile 中只保存安全的 `claude-*` 路由和显示名；真实上游模型名保存在 CC Switch 的供应商配置中，请求经过本地网关时再映射。 +模型映射模式不会。Claude Desktop profile 中只保存安全的 Sonnet / Opus / Haiku 角色路由和显示名；真实上游模型名保存在 CC Switch 的供应商配置中，请求经过本地网关时再映射。 ## 下一步 diff --git a/src-tauri/src/claude_desktop_config.rs b/src-tauri/src/claude_desktop_config.rs index 2e2c15ceb..3739da2cd 100644 --- a/src-tauri/src/claude_desktop_config.rs +++ b/src-tauri/src/claude_desktop_config.rs @@ -35,45 +35,6 @@ pub const ONE_M_CONTEXT_MARKER: &str = "[1m]"; const CURRENT_OPUS_ROUTE_ID: &str = "claude-opus-4-8"; const LEGACY_OPUS_ROUTE_ID: &str = "claude-opus-4-7"; -const NON_ANTHROPIC_ROUTE_MARKERS: &[&str] = &[ - "ark-code", - "astron", - "command-r", - "deepseek", - "doubao", - "gemini", - "gemma", - "glm", - "gpt", - "grok", - "hermes", - "hy3", - "kimi", - "lfm", - "llama", - "longcat", - "mimo", - "minimax", - "mistral", - "mixtral", - "moonshot", - "nemotron", - "openai", - "qianfan", - "qwen", - "stepfun", - "seed-", - "hunyuan", - "nova-", - "ernie", - "codex", - "abab", - "jamba", - "arctic", - "solar", - "mercury", -]; - #[derive(Debug, Clone, Copy, Serialize)] #[serde(rename_all = "camelCase")] pub struct ClaudeDesktopDefaultRoute { @@ -264,19 +225,24 @@ pub fn provider_mode(provider: &Provider) -> ClaudeDesktopMode { pub fn is_claude_safe_model_id(model: &str) -> bool { let normalized = model.trim().to_ascii_lowercase(); - let has_allowed_shape = (normalized.starts_with(CLAUDE_ROUTE_PREFIX) - && normalized.len() > CLAUDE_ROUTE_PREFIX.len()) - || (normalized.starts_with(ANTHROPIC_CLAUDE_ROUTE_PREFIX) - && normalized.len() > ANTHROPIC_CLAUDE_ROUTE_PREFIX.len()) - || matches!(normalized.as_str(), "sonnet" | "opus" | "haiku") - || (normalized.starts_with("sonnet-") && normalized.len() > "sonnet-".len()) - || (normalized.starts_with("opus-") && normalized.len() > "opus-".len()) - || (normalized.starts_with("haiku-") && normalized.len() > "haiku-".len()); - has_allowed_shape - && !normalized.contains(ONE_M_CONTEXT_MARKER) - && !NON_ANTHROPIC_ROUTE_MARKERS - .iter() - .any(|marker| normalized.contains(marker)) + if normalized.contains(ONE_M_CONTEXT_MARKER) { + return false; + } + + let Some(route_tail) = normalized + .strip_prefix(ANTHROPIC_CLAUDE_ROUTE_PREFIX) + .or_else(|| normalized.strip_prefix(CLAUDE_ROUTE_PREFIX)) + else { + return false; + }; + + // 角色前缀后必须还有实际模型标识，拒绝 claude-sonnet- 这类退化值 + // （否则会写入 profile 并触发 Claude Desktop fail-all 拒收整组）。 + ["sonnet-", "opus-", "haiku-"].iter().any(|prefix| { + route_tail + .strip_prefix(prefix) + .is_some_and(|rest| !rest.is_empty()) + }) } fn inference_model_json(spec: &InferenceModelSpec) -> Value { @@ -713,26 +679,59 @@ pub fn map_proxy_request_model(mut body: Value, provider: &Provider) -> Result Option { + provider + .meta + .as_ref()? + .claude_desktop_model_routes + .iter() + .find(|(route_id, _)| route_id.trim() == requested) + .and_then(|(_, route)| { + let upstream_model = route.model.trim(); + (!upstream_model.is_empty()).then(|| upstream_model.to_string()) + }) +} + fn is_compatible_opus_route_alias(route_id: &str, requested: &str) -> bool { matches!( (route_id, requested), @@ -741,6 +740,22 @@ fn is_compatible_opus_route_alias(route_id: &str, requested: &str) -> bool { ) } +/// 按角色关键词(opus / haiku / sonnet)归类一个 Claude 模型名/route_id。 +/// 仅在命中明确角色词时返回 Some,未知模型返回 None(不回落,保持精确报错语义)。 +/// 与前端 `routeRoleFromId` 同序(opus → haiku → sonnet)。 +fn claude_role_keyword(model: &str) -> Option<&'static str> { + let normalized = model.to_ascii_lowercase(); + if normalized.contains("opus") { + Some("opus") + } else if normalized.contains("haiku") { + Some("haiku") + } else if normalized.contains("sonnet") { + Some("sonnet") + } else { + None + } +} + fn should_normalize_mimo_anthropic_thinking_history( provider: &Provider, upstream_model: &str, @@ -1540,6 +1555,63 @@ mod tests { assert!(err.to_string().contains("claude-opus-4-8")); } + #[test] + fn claude_desktop_proxy_maps_dated_role_alias_via_keyword() { + // 复现反馈：Claude Desktop 子 agent 请求带发布日期后缀的完整官方名 + // （claude-haiku-4-5-20251001），与 manifest 的简短 route_id（claude-haiku-4-5） + // 不精确相等，旧逻辑会报 route_unknown。角色关键词回落应将其映射到 Haiku 档。 + let mut provider = proxy_provider("proxy"); + provider + .meta + .as_mut() + .expect("meta") + .claude_desktop_model_routes = std::collections::HashMap::from([ + ( + "claude-sonnet-4-6".to_string(), + ClaudeDesktopModelRoute { + model: "deepseek-v4-pro".to_string(), + label_override: None, + supports_1m: Some(true), + }, + ), + ( + "claude-opus-4-8".to_string(), + ClaudeDesktopModelRoute { + model: "deepseek-v4-pro".to_string(), + label_override: None, + supports_1m: Some(true), + }, + ), + ( + "claude-haiku-4-5".to_string(), + ClaudeDesktopModelRoute { + model: "deepseek-v4-flash".to_string(), + label_override: None, + supports_1m: Some(true), + }, + ), + ]); + + let mapped = map_proxy_request_model( + json!({"model": "claude-haiku-4-5-20251001", "messages": []}), + &provider, + ) + .expect("dated Haiku alias should map via role keyword"); + assert_eq!(mapped["model"], json!("deepseek-v4-flash")); + + let mapped_sonnet = map_proxy_request_model( + json!({"model": "claude-sonnet-4-5-20250101", "messages": []}), + &provider, + ) + .expect("dated Sonnet alias should map via role keyword"); + assert_eq!(mapped_sonnet["model"], json!("deepseek-v4-pro")); + + // 不含任何角色关键词的模型仍然报错，避免被误映射。 + let err = map_proxy_request_model(json!({"model": "gpt-5"}), &provider) + .expect_err("model without a role keyword should still fail"); + assert!(err.to_string().contains("gpt-5")); + } + #[test] fn claude_desktop_proxy_accepts_opus_4_7_4_8_alias_during_rollout() { let mut provider = proxy_provider("proxy"); @@ -1695,6 +1767,14 @@ mod tests { supports_1m: Some(true), }, ), + ( + "claude-old".to_string(), + ClaudeDesktopModelRoute { + model: "legacy-upstream".to_string(), + label_override: None, + supports_1m: Some(false), + }, + ), ( "claude-sonnet-4-6".to_string(), ClaudeDesktopModelRoute { @@ -1708,7 +1788,7 @@ mod tests { }); let routes = proxy_model_routes(&provider).expect("routes"); - assert_eq!(routes.len(), 2); + assert_eq!(routes.len(), 3); let repaired = routes .iter() .find(|route| route.upstream_model == "deepseek-v4-pro") @@ -1716,6 +1796,15 @@ mod tests { assert_eq!(repaired.route_id, "claude-opus-4-8"); assert_eq!(repaired.label_override.as_deref(), Some("deepseek-v4-pro")); assert!(repaired.supports_1m); + let repaired_old = routes + .iter() + .find(|route| route.upstream_model == "legacy-upstream") + .expect("legacy route should be repaired"); + assert_eq!(repaired_old.route_id, "claude-haiku-4-5"); + assert_eq!( + repaired_old.label_override.as_deref(), + Some("legacy-upstream") + ); let mapped = map_proxy_request_model( json!({"model": "claude-opus-4-8", "messages": []}), @@ -1723,6 +1812,11 @@ mod tests { ) .expect("map repaired route"); assert_eq!(mapped["model"], json!("deepseek-v4-pro")); + + let legacy_mapped = + map_proxy_request_model(json!({"model": "claude-old", "messages": []}), &provider) + .expect("map stale profile route"); + assert_eq!(legacy_mapped["model"], json!("legacy-upstream")); } #[test] @@ -1741,12 +1835,20 @@ mod tests { fn claude_desktop_rejects_1m_suffix_as_model_id() { assert!(!is_claude_safe_model_id("claude-sonnet-4-6 [1m]")); assert!(!is_claude_safe_model_id(" claude-sonnet-4-6 [1M] ")); + assert!(!is_claude_safe_model_id("claude-old")); + assert!(!is_claude_safe_model_id("claude-3-5-sonnet-20241022")); assert!(!is_claude_safe_model_id("claude-deepseek-v4-pro")); assert!(!is_claude_safe_model_id("claude-gpt-5-4")); assert!(!is_claude_safe_model_id("claude-")); assert!(!is_claude_safe_model_id("anthropic/claude-")); + assert!(!is_claude_safe_model_id("sonnet")); assert!(!is_claude_safe_model_id("sonnet-")); + // 角色前缀后无实际标识的退化值必须拒绝 + assert!(!is_claude_safe_model_id("claude-sonnet-")); + assert!(!is_claude_safe_model_id("claude-opus-")); + assert!(!is_claude_safe_model_id("anthropic/claude-haiku-")); assert!(is_claude_safe_model_id(" claude-sonnet-4-6 ")); + assert!(is_claude_safe_model_id("anthropic/claude-opus-4-8")); } #[test] diff --git a/src/components/providers/forms/ClaudeDesktopProviderForm.tsx b/src/components/providers/forms/ClaudeDesktopProviderForm.tsx index f50712297..e8807fc91 100644 --- a/src/components/providers/forms/ClaudeDesktopProviderForm.tsx +++ b/src/components/providers/forms/ClaudeDesktopProviderForm.tsx @@ -118,44 +118,6 @@ const ANTHROPIC_CLAUDE_ROUTE_PREFIX = "anthropic/claude-"; const LEGACY_ONE_M_MARKER = "[1m]"; const ROLE_ROUTE_IDS = CLAUDE_DESKTOP_ROLE_ROUTE_IDS; const ROLE_ORDER: RouteRole[] = ["sonnet", "opus", "haiku"]; -const NON_ANTHROPIC_ROUTE_MARKERS = [ - "ark-code", - "astron", - "command-r", - "deepseek", - "doubao", - "gemini", - "gemma", - "glm", - "gpt", - "grok", - "hermes", - "hy3", - "kimi", - "lfm", - "llama", - "longcat", - "mimo", - "minimax", - "mistral", - "mixtral", - "moonshot", - "nemotron", - "openai", - "qianfan", - "qwen", - "stepfun", - "seed-", - "hunyuan", - "nova-", - "ernie", - "codex", - "abab", - "jamba", - "arctic", - "solar", - "mercury", -]; function envString( settingsConfig: Record | undefined, @@ -231,21 +193,37 @@ function initialRouteRows( }); } +// Proxy 模式对齐 Claude Code：固定 Sonnet / Opus / Haiku 三档。 +// 把任意来源的 route 行按角色归类到固定三槽（缺档留空），保证 UI 永远三行、 +// 用户不会漏配 Haiku 导致子 agent 找不到模型。 +function normalizeProxyRows(rows: RouteRow[]): RouteRow[] { + return ROLE_ORDER.map((role) => { + const match = rows.find( + (row) => row.route.trim() && routeRoleFromId(row.route) === role, + ); + return createRouteRow({ + route: ROLE_ROUTE_IDS[role], + model: match?.model ?? "", + labelOverride: match?.labelOverride ?? "", + supports1m: match?.supports1m ?? false, + }); + }); +} + function isClaudeSafeRoute(route: string) { const normalized = route.trim().toLowerCase(); if (normalized.includes(LEGACY_ONE_M_MARKER)) return false; - const hasAllowedShape = - [CLAUDE_ROUTE_PREFIX, ANTHROPIC_CLAUDE_ROUTE_PREFIX].some( - (prefix) => - normalized.startsWith(prefix) && normalized.length > prefix.length, - ) || - ["sonnet", "opus", "haiku"].includes(normalized) || - normalized.startsWith("sonnet-") || - normalized.startsWith("opus-") || - normalized.startsWith("haiku-"); - return ( - hasAllowedShape && - !NON_ANTHROPIC_ROUTE_MARKERS.some((marker) => normalized.includes(marker)) + const routeTail = normalized.startsWith(ANTHROPIC_CLAUDE_ROUTE_PREFIX) + ? normalized.slice(ANTHROPIC_CLAUDE_ROUTE_PREFIX.length) + : normalized.startsWith(CLAUDE_ROUTE_PREFIX) + ? normalized.slice(CLAUDE_ROUTE_PREFIX.length) + : ""; + + // 角色前缀后必须还有实际模型标识，拒绝 claude-sonnet- 这类退化值 + // （否则会写入 profile 并触发 Claude Desktop fail-all 拒收整组）。 + return ["sonnet-", "opus-", "haiku-"].some( + (prefix) => + routeTail.startsWith(prefix) && routeTail.length > prefix.length, ); } @@ -263,30 +241,6 @@ function defaultRouteRows( ); } -function nextRouteRow(current: RouteRow[], defaults: RouteRow[]): RouteRow { - const defaultRow = - defaults.find( - (route) => !current.some((existing) => existing.route === route.route), - ) ?? null; - - if (defaultRow) { - return createRouteRow({ - route: defaultRow.route, - model: defaultRow.model, - labelOverride: defaultRow.labelOverride, - supports1m: defaultRow.supports1m, - }); - } - - const usedRoutes = new Set(current.map((route) => route.route)); - return createRouteRow({ - route: routeIdForRole("sonnet", usedRoutes), - model: "", - labelOverride: "", - supports1m: true, - }); -} - export function ClaudeDesktopProviderForm({ submitLabel, onSubmit, @@ -334,9 +288,15 @@ export function ClaudeDesktopProviderForm({ providerType?: string; requiresOAuth?: boolean; } | null>(null); - const [routes, setRoutes] = useState(() => - initialRouteRows(initialData?.meta?.claudeDesktopModelRoutes), - ); + const [routes, setRoutes] = useState(() => { + const rows = initialRouteRows(initialData?.meta?.claudeDesktopModelRoutes); + // proxy 模式归一化成固定三档；但初始无任何 route 时保持空数组，交给 seed + // effect 用默认路由回填（默认 1M 声明、ANTHROPIC_MODEL 预填），避免过早 + // normalize 成空三档把 routes.length 撑到 3、永久挡住 seed。 + return initialMode === "proxy" && rows.length > 0 + ? normalizeProxyRows(rows) + : rows; + }); const didSeedDefaultRoutes = useRef( Object.keys(initialData?.meta?.claudeDesktopModelRoutes ?? {}).length > 0, ); @@ -435,13 +395,15 @@ export function ClaudeDesktopProviderForm({ setMode(preset.mode); if (preset.mode === "proxy" && preset.modelRoutes) { setRoutes( - preset.modelRoutes.map((r) => - createRouteRow({ - route: r.routeId, - model: r.upstreamModel, - labelOverride: r.labelOverride ?? "", - supports1m: r.supports1m, - }), + normalizeProxyRows( + preset.modelRoutes.map((r) => + createRouteRow({ + route: r.routeId, + model: r.upstreamModel, + labelOverride: r.labelOverride ?? "", + supports1m: r.supports1m, + }), + ), ), ); } else { @@ -485,28 +447,26 @@ export function ClaudeDesktopProviderForm({ ); }; - const updateRouteRole = (index: number, role: RouteRole) => { - setRoutes((current) => { - const usedRoutes = new Set( - current - .filter((_, i) => i !== index) - .map((row) => row.route) - .filter(Boolean), - ); - const route = routeIdForRole(role, usedRoutes); - return current.map((row, i) => (i === index ? { ...row, route } : row)); - }); - }; - const handleModelMappingChange = (checked: boolean) => { setMode(checked ? "proxy" : "direct"); if (checked) { + // 切到 proxy：归一化成固定 Sonnet / Opus / Haiku 三档； + // 若当前无路由则以后端默认路由作为来源（保留 Sonnet 默认模型）。 setRoutes((current) => { - if (current.length > 0 || defaultProxyRouteRows.length === 0) { + // 默认路由（默认 1M 声明、ANTHROPIC_MODEL 预填）异步加载完成前，若当前 + // 无路由则保持空数组，交给 seed effect 在加载后回填；不要过早 normalize + // 成空三档（会把 routes.length 撑到 3、永久挡住 seed）。 + if (current.length === 0 && defaultProxyRouteRows.length === 0) { return current; } - didSeedDefaultRoutes.current = true; - return defaultProxyRouteRows; + const useDefaults = + current.length === 0 && defaultProxyRouteRows.length > 0; + if (useDefaults) { + didSeedDefaultRoutes.current = true; + } + return normalizeProxyRows( + useDefaults ? defaultProxyRouteRows : current, + ); }); } }; @@ -522,7 +482,7 @@ export function ClaudeDesktopProviderForm({ } didSeedDefaultRoutes.current = true; - setRoutes(defaultProxyRouteRows); + setRoutes(normalizeProxyRows(defaultProxyRouteRows)); }, [defaultProxyRouteRows, mode, routes.length]); const handleFetchModels = async () => { @@ -614,19 +574,11 @@ export function ClaudeDesktopProviderForm({ .filter((route) => route.route || route.model); if (mode === "proxy") { - const invalid = routeEntries.find( - (route) => - !route.route || !route.model || !isClaudeSafeRoute(route.route), - ); - if (invalid) { - toast.error( - t("claudeDesktop.routeInvalid", { - defaultValue: "请填写 Desktop 显示模型和实际请求模型", - }), - ); - return; - } - if (routeEntries.length === 0) { + // 固定三档（Sonnet / Opus / Haiku），route_id 由 UI 生成、恒合法， + // 因此只要求至少填一个实际请求模型；留空档继承第一个已填档（Sonnet 优先）， + // 对齐 Claude Code 的兜底，保证落库三档齐全、子 agent 不会找不到 Haiku。 + const primary = routeEntries.find((route) => route.model); + if (!primary) { toast.error( t("claudeDesktop.routesRequired", { defaultValue: "至少填写一个模型映射", @@ -634,6 +586,19 @@ export function ClaudeDesktopProviderForm({ ); return; } + for (const route of routeEntries) { + if (!route.model) { + route.model = primary.model; + if (!route.labelOverride) { + route.labelOverride = primary.labelOverride || primary.model; + } + // 回填的是同一个上游模型，1M 能力声明应与 primary 一致， + // 避免同模型在不同档声明不同 1M（除非该档用户已显式勾选）。 + if (!route.supports1m) { + route.supports1m = primary.supports1m; + } + } + } } else { const invalid = routeEntries.find( (route) => !route.route || !isClaudeSafeRoute(route.route), @@ -642,7 +607,7 @@ export function ClaudeDesktopProviderForm({ toast.error( t("claudeDesktop.directModelInvalid", { defaultValue: - "直连模型必须使用 claude-* / anthropic/claude-* 模型名", + "直连模型必须使用 Claude Desktop 可识别的 Sonnet / Opus / Haiku 模型名", }), ); return; @@ -668,7 +633,7 @@ export function ClaudeDesktopProviderForm({ Record >((acc, route) => { acc[route.route] = { - model: route.model || route.route, + model: mode === "direct" ? route.route : route.model || route.route, labelOverride: route.labelOverride || (mode === "proxy" ? route.model : undefined), supports1m: route.supports1m || undefined, @@ -838,11 +803,11 @@ export function ClaudeDesktopProviderForm({ {needsModelMapping ? t("claudeDesktop.modelMappingOnHint", { defaultValue: - "Claude Desktop 目前对模型 ID 进行了限制，如果您的供应商提供的模型不是 Claude 系列模型，则需要打开本开关，并在使用过程中保持本地路由开启。", + "Claude Desktop 只接受 claude-sonnet-* / claude-opus-* / claude-haiku-* 三档角色 ID。开启后 CC Switch 会把这三档映射到供应商的实际模型，并在使用期间保持本地路由开启。", }) : t("claudeDesktop.modelMappingOffHint", { defaultValue: - "适合供应商已经暴露并接受 claude-* / anthropic/claude-* 模型名的 Anthropic Messages API；请求会由 Claude Desktop 直连供应商。", + "仅当供应商直接接受 Claude Desktop 可识别的三档角色 ID（claude-sonnet-* / claude-opus-* / claude-haiku-*）时才适用直连；其他模型名（含 claude-3-5-sonnet-… 等旧式 ID）请打开此开关走映射。", })}

@@ -905,26 +870,35 @@ export function ClaudeDesktopProviderForm({ defaultValue: "模型映射", })} - {renderActionButtons( - () => - setRoutes((current) => [ - ...current, - nextRouteRow(current, defaultProxyRouteRows), - ]), - t("claudeDesktop.addRoute", { - defaultValue: "添加模型", - }), + {!usesManagedOAuth && ( + )}

{t("claudeDesktop.routeMapHint", { defaultValue: - "选择模型角色后，CC Switch 会自动生成 Claude Desktop 兼容路由；菜单显示名可以写 DeepSeek、Kimi 等品牌模型，实际请求模型按右侧填写内容发送。", + "为 Sonnet、Opus、Haiku 三档分别填写实际请求模型；菜单显示名可写 DeepSeek、Kimi 等品牌名。留空的档会自动沿用 Sonnet（或第一个已填档）的模型，确保子 agent 调用的 Haiku 始终可用。", })}

-
+
{t("claudeDesktop.routeModelLabel", { defaultValue: "模型角色", @@ -945,101 +919,75 @@ export function ClaudeDesktopProviderForm({ defaultValue: "声明支持 1M", })} -
- {routes.map((route, index) => ( -
- - - updateRoute(index, { - labelOverride: event.target.value, + {routes.map((route, index) => { + const role = routeRoleFromId(route.route); + const roleLabel = + role === "opus" + ? t("claudeDesktop.routeRoleOpus", { + defaultValue: "Opus", }) - } - placeholder="DeepSeek V4 Pro" - /> -
+ : role === "haiku" + ? t("claudeDesktop.routeRoleHaiku", { + defaultValue: "Haiku", + }) + : t("claudeDesktop.routeRoleSonnet", { + defaultValue: "Sonnet", + }); + return ( +
+
+ {roleLabel} +
- updateRoute(index, { model: event.target.value }) + updateRoute(index, { + labelOverride: event.target.value, + }) } - placeholder="kimi-k2 / deepseek-chat" - className="flex-1" + placeholder="DeepSeek V4 Pro" /> - {fetchedModels.length > 0 && ( - +
+ + updateRoute(index, { model: event.target.value }) + } + placeholder="kimi-k2 / deepseek-chat" + className="flex-1" + /> + {fetchedModels.length > 0 && ( + + updateRoute(index, { + model: id, + labelOverride: route.labelOverride || id, + }) + } + /> + )} +
+
- - -
- ))} + ); + })}
)} @@ -1081,7 +1029,7 @@ export function ClaudeDesktopProviderForm({

{t("claudeDesktop.directModelListHint", { defaultValue: - "仅当供应商的 /v1/models 不可用或没有返回 Claude Desktop 可识别的 claude-* 模型名时填写；这些模型名会原样发送给供应商。", + "仅当供应商的 /v1/models 不可用或没有返回 Claude Desktop 可识别的 Sonnet / Opus / Haiku 模型名时填写；勾选 1M 会向 Claude Desktop 声明支持 1M 上下文。", })}

{renderActionButtons( @@ -1116,7 +1064,7 @@ export function ClaudeDesktopProviderForm({ route: event.target.value, }) } - placeholder="claude-deepseek-chat" + placeholder="claude-sonnet-4-6" className="flex-1" /> {fetchedModels.length > 0 && ( diff --git a/src/i18n/locales/en.json b/src/i18n/locales/en.json index 1bc58d4cf..1ea3d07f6 100644 --- a/src/i18n/locales/en.json +++ b/src/i18n/locales/en.json @@ -187,10 +187,10 @@ "modeDirect": "Direct", "modeProxy": "Requires routing", "modelMappingToggle": "Needs model mapping", - "modelMappingOffHint": "If your provider does not offer native Claude series models, please enable this switch.", - "modelMappingOnHint": "Claude Desktop currently restricts model IDs. If your provider offers non-Claude models, enable this switch and keep local routing running while in use.", + "modelMappingOffHint": "Direct mode works only when the provider accepts Claude Desktop's three role IDs (claude-sonnet-* / claude-opus-* / claude-haiku-*); for any other model name (including legacy IDs like claude-3-5-sonnet-…), enable this switch to use mapping.", + "modelMappingOnHint": "Claude Desktop only accepts the three role IDs claude-sonnet-* / claude-opus-* / claude-haiku-*. When enabled, CC Switch maps these three roles to your provider's actual models and keeps local routing running while in use.", "routeMapTitle": "Model mapping", - "routeMapHint": "Choose a model role and CC Switch will generate a Claude Desktop-compatible route automatically. Use the menu display name for branded models such as DeepSeek or Kimi; requested model IDs are sent upstream exactly as entered.", + "routeMapHint": "Fill in the actual request model for each of the Sonnet, Opus, and Haiku tiers. Use the menu display name for branded models such as DeepSeek or Kimi. Any tier left blank inherits the Sonnet tier's model (or the first tier you filled in), so the Haiku that sub-agents call is always available.", "routeModelLabel": "Model role", "routeRoleSonnet": "Sonnet", "routeRoleOpus": "Opus", @@ -201,15 +201,15 @@ "supports1mShort": "1M", "directModelListTitle": "Manually specify Claude Desktop models (advanced, optional)", "directModelListCollapsedHint": "Native Claude model providers usually do not need this. Claude Desktop will fetch /v1/models automatically.", - "directModelListHint": "Only fill this when the provider's /v1/models is unavailable or does not return Claude Desktop-safe claude-* model IDs. Checking 1M declares 1M context support to Claude Desktop.", - "directModelInvalid": "Direct models must use claude-* / anthropic/claude-* model IDs", + "directModelListHint": "Only fill this when the provider's /v1/models is unavailable or does not return Claude Desktop-recognized Sonnet / Opus / Haiku model IDs. Checking 1M declares 1M context support to Claude Desktop.", + "directModelInvalid": "Direct models must use Claude Desktop-recognized Sonnet / Opus / Haiku model IDs", "addModel": "Add model", "addRoute": "Add model", "routeInvalid": "Choose a model role and enter the requested model", "routesRequired": "At least one model mapping is required", "statusTitle": "Claude Desktop configuration needs attention", "statusUnsupported": "This platform does not support writing Claude Desktop 3P configuration yet.", - "statusStaleRawModels": "The Claude Desktop profile contains non-claude-* model IDs. Newer Claude Desktop versions may reject it; switch to the current provider again to repair it.", + "statusStaleRawModels": "The Claude Desktop profile contains model IDs outside the Sonnet / Opus / Haiku role families. Newer Claude Desktop versions may reject it; switch to the current provider again to repair it.", "statusMissingRouteMappings": "The current provider has model mapping enabled but no valid routes. Edit the provider and add at least one mapping.", "statusGatewayTokenMissing": "The local routing token has not been generated yet. Switching to this provider again will write a new local token.", "statusBaseUrlMismatch": "The Claude Desktop profile points to a different URL than the current provider. Current: {{actual}}; expected: {{expected}}. Switch to the current provider again to repair it.", diff --git a/src/i18n/locales/ja.json b/src/i18n/locales/ja.json index 2847b2974..3608ddcb1 100644 --- a/src/i18n/locales/ja.json +++ b/src/i18n/locales/ja.json @@ -187,10 +187,10 @@ "modeDirect": "直結", "modeProxy": "ルーティング必要", "modelMappingToggle": "モデルマッピングが必要", - "modelMappingOffHint": "プロバイダーがネイティブの Claude シリーズモデルを提供していない場合は、このスイッチを有効にしてください。", - "modelMappingOnHint": "Claude Desktop は現在モデル ID を制限しています。お使いのプロバイダーが Claude 系列以外のモデルを提供する場合、このスイッチを有効にし、使用中はローカルルーティングを起動したままにしてください。", + "modelMappingOffHint": "プロバイダーが Claude Desktop の三つの役割 ID（claude-sonnet-* / claude-opus-* / claude-haiku-*）を受け付ける場合のみ直結できます。それ以外のモデル名（claude-3-5-sonnet-… などの旧式 ID を含む）はこのスイッチを有効にしてマッピングを使ってください。", + "modelMappingOnHint": "Claude Desktop は claude-sonnet-* / claude-opus-* / claude-haiku-* の三つの役割 ID のみ受け付けます。有効にすると CC Switch がこの三役割をプロバイダーの実モデルにマッピングし、使用中はローカルルーティングを起動したままにします。", "routeMapTitle": "モデルマッピング", - "routeMapHint": "モデル役割を選ぶと、CC Switch が Claude Desktop 互換ルートを自動生成します。DeepSeek や Kimi などのブランド名はメニュー表示名に入れ、実際のリクエストモデルは右側の入力どおりに送信されます。", + "routeMapHint": "Sonnet・Opus・Haiku の各区分に実際のリクエストモデルを入力してください。DeepSeek や Kimi などのブランド名はメニュー表示名に入れられます。空欄の区分は Sonnet（または最初に入力した区分）のモデルを引き継ぐため、サブ agent が呼び出す Haiku が常に利用可能になります。", "routeModelLabel": "モデル役割", "routeRoleSonnet": "Sonnet", "routeRoleOpus": "Opus", @@ -201,15 +201,15 @@ "supports1mShort": "1M", "directModelListTitle": "Claude Desktop モデルを手動指定（高度・任意）", "directModelListCollapsedHint": "ネイティブ Claude モデルのプロバイダーでは通常不要です。Claude Desktop が /v1/models を自動取得します。", - "directModelListHint": "プロバイダーの /v1/models が使えない、または Claude Desktop が認識できる claude-* モデル ID を返さない場合だけ入力してください。1M をオンにすると Claude Desktop に 1M コンテキスト対応を宣言します。", - "directModelInvalid": "直結モデルは claude-* / anthropic/claude-* のモデル ID を使う必要があります", + "directModelListHint": "プロバイダーの /v1/models が使えない、または Claude Desktop が認識できる Sonnet / Opus / Haiku モデル ID を返さない場合だけ入力してください。1M をオンにすると Claude Desktop に 1M コンテキスト対応を宣言します。", + "directModelInvalid": "直結モデルは Claude Desktop が認識できる Sonnet / Opus / Haiku モデル ID を使う必要があります", "addModel": "モデルを追加", "addRoute": "モデルを追加", "routeInvalid": "モデル役割を選択し、リクエストモデルを入力してください", "routesRequired": "少なくとも 1 つのモデルマッピングが必要です", "statusTitle": "Claude Desktop 設定の確認が必要です", "statusUnsupported": "このプラットフォームでは Claude Desktop 3P 設定の書き込みはまだサポートされていません。", - "statusStaleRawModels": "Claude Desktop profile に claude-* ではないモデル ID が含まれています。新しい Claude Desktop では拒否される可能性があります。現在のプロバイダーへ再度切り替えると修復できます。", + "statusStaleRawModels": "Claude Desktop profile に Sonnet / Opus / Haiku の役割ファミリー以外のモデル ID が含まれています。新しい Claude Desktop では拒否される可能性があります。現在のプロバイダーへ再度切り替えると修復できます。", "statusMissingRouteMappings": "現在のプロバイダーはモデルマッピングを有効にしていますが、有効なルートがありません。プロバイダーを編集し、少なくとも 1 つのマッピングを追加してください。", "statusGatewayTokenMissing": "ローカルルーティング token がまだ生成されていません。このプロバイダーへ再度切り替えると新しい token が書き込まれます。", "statusBaseUrlMismatch": "Claude Desktop profile の URL が現在のプロバイダーと一致しません。現在: {{actual}}、期待値: {{expected}}。現在のプロバイダーへ再度切り替えると修復できます。", diff --git a/src/i18n/locales/zh-TW.json b/src/i18n/locales/zh-TW.json index 8d06015e3..2c1f928e6 100644 --- a/src/i18n/locales/zh-TW.json +++ b/src/i18n/locales/zh-TW.json @@ -187,10 +187,10 @@ "modeDirect": "直連", "modeProxy": "需要路由", "modelMappingToggle": "需要模型對應", - "modelMappingOffHint": "如果您的供應商提供的不是原生 Claude 系列模型，請開啟此開關。", - "modelMappingOnHint": "Claude Desktop 目前對模型 ID 進行了限制，如果您的供應商提供的模型不是 Claude 系列模型，則需要開啟本開關，並在使用過程中保持本地路由開啟。", + "modelMappingOffHint": "僅當供應商直接接受 Claude Desktop 可識別的三檔角色 ID（claude-sonnet-* / claude-opus-* / claude-haiku-*）時才適用直連；其他模型名（含 claude-3-5-sonnet-… 等舊式 ID）請開啟此開關走對應。", + "modelMappingOnHint": "Claude Desktop 只接受 claude-sonnet-* / claude-opus-* / claude-haiku-* 三檔角色 ID。開啟後 CC Switch 會把這三檔對應到供應商的實際模型，並在使用期間保持本地路由開啟。", "routeMapTitle": "模型對應", - "routeMapHint": "選擇模型角色後，CC Switch 會自動產生 Claude Desktop 相容路由；選單顯示名稱可以填寫 DeepSeek、Kimi 等品牌模型，實際請求模型依右側填寫內容發送。", + "routeMapHint": "為 Sonnet、Opus、Haiku 三檔分別填寫實際請求模型；選單顯示名稱可寫 DeepSeek、Kimi 等品牌名。留空的檔會自動沿用 Sonnet（或第一個已填檔）的模型，確保子 agent 呼叫的 Haiku 始終可用。", "routeModelLabel": "模型角色", "routeRoleSonnet": "Sonnet", "routeRoleOpus": "Opus", @@ -201,15 +201,15 @@ "supports1mShort": "1M", "directModelListTitle": "手動指定 Claude Desktop 模型清單（進階，選填）", "directModelListCollapsedHint": "原生 Claude 模型供應商通常不需填寫，Claude Desktop 會自動讀取 /v1/models。", - "directModelListHint": "僅當供應商的 /v1/models 不可用或沒有回傳 Claude Desktop 可識別的 claude-* 模型名稱時填寫；勾選 1M 會向 Claude Desktop 聲明支援 1M 上下文。", - "directModelInvalid": "直連模型必須使用 claude-* / anthropic/claude-* 模型名稱", + "directModelListHint": "僅當供應商的 /v1/models 不可用或沒有回傳 Claude Desktop 可識別的 Sonnet / Opus / Haiku 模型名稱時填寫；勾選 1M 會向 Claude Desktop 聲明支援 1M 上下文。", + "directModelInvalid": "直連模型必須使用 Claude Desktop 可識別的 Sonnet / Opus / Haiku 模型名稱", "addModel": "新增模型", "addRoute": "新增模型", "routeInvalid": "請選擇模型角色並填寫實際請求模型", "routesRequired": "至少填寫一個模型對應", "statusTitle": "Claude Desktop 設定需要檢查", "statusUnsupported": "目前平台暫不支援 Claude Desktop 3P 設定寫入。", - "statusStaleRawModels": "Claude Desktop profile 中存在非 claude-* 模型名稱，新版 Claude Desktop 可能拒絕載入；重新切換目前供應商可修復。", + "statusStaleRawModels": "Claude Desktop profile 中存在非 Sonnet / Opus / Haiku 角色模型名稱，新版 Claude Desktop 可能拒絕載入；重新切換目前供應商可修復。", "statusMissingRouteMappings": "目前供應商啟用了模型對應，但沒有有效路由；請編輯供應商並補全至少一個模型對應。", "statusGatewayTokenMissing": "目前本地路由 token 尚未產生；重新切換該供應商會寫入新的本地 token。", "statusBaseUrlMismatch": "Claude Desktop profile 指向的位址與目前供應商不一致；目前為 {{actual}}，應為 {{expected}}。重新切換目前供應商可修復。", diff --git a/src/i18n/locales/zh.json b/src/i18n/locales/zh.json index befba5daf..d7c114b5f 100644 --- a/src/i18n/locales/zh.json +++ b/src/i18n/locales/zh.json @@ -187,10 +187,10 @@ "modeDirect": "直连", "modeProxy": "需要路由", "modelMappingToggle": "需要模型映射", - "modelMappingOffHint": "如果您的供应商提供的不是原生 Claude 系列模型，请打开此开关。", - "modelMappingOnHint": "Claude Desktop 目前对模型 ID 进行了限制，如果您的供应商提供的模型不是 Claude 系列模型，则需要打开本开关，并在使用过程中保持本地路由开启。", + "modelMappingOffHint": "仅当供应商直接接受 Claude Desktop 可识别的三档角色 ID（claude-sonnet-* / claude-opus-* / claude-haiku-*）时才适用直连；其他模型名（含 claude-3-5-sonnet-… 等旧式 ID）请打开此开关走映射。", + "modelMappingOnHint": "Claude Desktop 只接受 claude-sonnet-* / claude-opus-* / claude-haiku-* 三档角色 ID。开启后 CC Switch 会把这三档映射到供应商的实际模型，并在使用期间保持本地路由开启。", "routeMapTitle": "模型映射", - "routeMapHint": "选择模型角色后，CC Switch 会自动生成 Claude Desktop 兼容路由；菜单显示名可以写 DeepSeek、Kimi 等品牌模型，实际请求模型按右侧填写内容发送。", + "routeMapHint": "为 Sonnet、Opus、Haiku 三档分别填写实际请求模型；菜单显示名可写 DeepSeek、Kimi 等品牌名。留空的档会自动沿用 Sonnet（或第一个已填档）的模型，确保子 agent 调用的 Haiku 始终可用。", "routeModelLabel": "模型角色", "routeRoleSonnet": "Sonnet", "routeRoleOpus": "Opus", @@ -201,15 +201,15 @@ "supports1mShort": "1M", "directModelListTitle": "手动指定 Claude Desktop 模型列表（高级，可选）", "directModelListCollapsedHint": "原生 Claude 模型供应商通常不用填写，Claude Desktop 会自动读取 /v1/models。", - "directModelListHint": "仅当供应商的 /v1/models 不可用或没有返回 Claude Desktop 可识别的 claude-* 模型名时填写；勾选 1M 会向 Claude Desktop 声明支持 1M 上下文。", - "directModelInvalid": "直连模型必须使用 claude-* / anthropic/claude-* 模型名", + "directModelListHint": "仅当供应商的 /v1/models 不可用或没有返回 Claude Desktop 可识别的 Sonnet / Opus / Haiku 模型名时填写；勾选 1M 会向 Claude Desktop 声明支持 1M 上下文。", + "directModelInvalid": "直连模型必须使用 Claude Desktop 可识别的 Sonnet / Opus / Haiku 模型名", "addModel": "添加模型", "addRoute": "添加模型", "routeInvalid": "请选择模型角色并填写实际请求模型", "routesRequired": "至少填写一个模型映射", "statusTitle": "Claude Desktop 配置需要检查", "statusUnsupported": "当前平台暂不支持 Claude Desktop 3P 配置写入。", - "statusStaleRawModels": "Claude Desktop profile 中存在非 claude-* 模型名，新版 Claude Desktop 可能拒绝加载；重新切换当前供应商可修复。", + "statusStaleRawModels": "Claude Desktop profile 中存在非 Sonnet / Opus / Haiku 角色模型名，新版 Claude Desktop 可能拒绝加载；重新切换当前供应商可修复。", "statusMissingRouteMappings": "当前供应商启用了模型映射，但没有有效路由；请编辑供应商并补全至少一个模型映射。", "statusGatewayTokenMissing": "当前本地路由 token 尚未生成；重新切换该供应商会写入新的本地 token。", "statusBaseUrlMismatch": "Claude Desktop profile 指向的地址与当前供应商不一致；当前为 {{actual}}，应为 {{expected}}。重新切换当前供应商可修复。", diff --git a/tests/components/ClaudeDesktopProviderForm.test.tsx b/tests/components/ClaudeDesktopProviderForm.test.tsx index 8e510b92f..43427b002 100644 --- a/tests/components/ClaudeDesktopProviderForm.test.tsx +++ b/tests/components/ClaudeDesktopProviderForm.test.tsx @@ -1,4 +1,4 @@ -import { fireEvent, render, screen } from "@testing-library/react"; +import { fireEvent, render, screen, waitFor } from "@testing-library/react"; import { QueryClientProvider } from "@tanstack/react-query"; import type { ComponentProps } from "react"; import { describe, expect, it, vi } from "vitest"; @@ -13,18 +13,20 @@ vi.mock("@/lib/api/providers", () => ({ function renderForm( initialData: ComponentProps["initialData"], + onSubmit = vi.fn(), ) { const queryClient = createTestQueryClient(); - return render( + const view = render( , ); + return { ...view, onSubmit }; } describe("ClaudeDesktopProviderForm", () => { @@ -47,16 +49,17 @@ describe("ClaudeDesktopProviderForm", () => { }, }); - const input = screen.getByPlaceholderText( + // 固定三档（Sonnet / Opus / Haiku）下有三个菜单显示名输入，取 Sonnet（首个）。 + const input = screen.getAllByPlaceholderText( "DeepSeek V4 Pro", - ) as HTMLInputElement; + )[0] as HTMLInputElement; input.focus(); fireEvent.change(input, { target: { value: "DeepSeek V4 Pro" } }); - const currentInput = screen.getByPlaceholderText( + const currentInput = screen.getAllByPlaceholderText( "DeepSeek V4 Pro", - ) as HTMLInputElement; + )[0] as HTMLInputElement; expect(currentInput).toHaveValue("DeepSeek V4 Pro"); expect(document.activeElement).toBe(currentInput); }); @@ -81,16 +84,174 @@ describe("ClaudeDesktopProviderForm", () => { }); const input = screen.getByPlaceholderText( - "claude-deepseek-chat", + "claude-sonnet-4-6", ) as HTMLInputElement; input.focus(); fireEvent.change(input, { target: { value: "claude-12345" } }); const currentInput = screen.getByPlaceholderText( - "claude-deepseek-chat", + "claude-sonnet-4-6", ) as HTMLInputElement; expect(currentInput).toHaveValue("claude-12345"); expect(document.activeElement).toBe(currentInput); }); + + it("代理模式始终渲染 Sonnet / Opus / Haiku 三档（即使只配了一档）", () => { + renderForm({ + name: "Proxy Provider", + settingsConfig: { + env: { + ANTHROPIC_BASE_URL: "https://api.example.com", + ANTHROPIC_AUTH_TOKEN: "sk-test", + }, + }, + meta: { + claudeDesktopMode: "proxy", + claudeDesktopModelRoutes: { + "claude-sonnet-4-6": { model: "upstream-sonnet" }, + }, + }, + }); + + // 固定三档：每档各一个「菜单显示名」输入框，无论初始只配了几档。 + expect(screen.getAllByPlaceholderText("DeepSeek V4 Pro")).toHaveLength(3); + }); + + it("代理模式初始无路由且默认路由未就绪时不渲染空三档", () => { + // mock 的 getClaudeDesktopDefaultRoutes 返回 []，模拟默认路由尚未就绪。 + // 修复前：normalizeProxyRows([]) 会渲染 3 条空行并把 routes.length 撑到 3， + // 永久挡住 seed effect 的默认路由回填。修复后应保持空、等待 seed。 + renderForm({ + name: "Proxy Provider", + settingsConfig: { + env: { + ANTHROPIC_BASE_URL: "https://api.example.com", + ANTHROPIC_AUTH_TOKEN: "sk-test", + }, + }, + meta: { + claudeDesktopMode: "proxy", + claudeDesktopModelRoutes: {}, + }, + }); + + expect(screen.queryAllByPlaceholderText("DeepSeek V4 Pro")).toHaveLength(0); + }); + + it("保存模型映射时补齐固定三档并把留空档回填为 Sonnet 模型", async () => { + const onSubmit = vi.fn(); + renderForm( + { + name: "Proxy Provider", + settingsConfig: { + env: { + ANTHROPIC_BASE_URL: "https://api.example.com", + ANTHROPIC_AUTH_TOKEN: "sk-test", + }, + }, + meta: { + claudeDesktopMode: "proxy", + claudeDesktopModelRoutes: { + "claude-old": { + model: "upstream-old", + }, + }, + }, + }, + onSubmit, + ); + + fireEvent.click(screen.getByRole("button", { name: "保存" })); + + await waitFor(() => expect(onSubmit).toHaveBeenCalled()); + const submitted = onSubmit.mock.calls[0][0]; + // claude-old 迁移到 Sonnet；留空的 Opus / Haiku 回填为 Sonnet 的上游模型， + // 保证落库三档齐全，子 agent 调用的 Haiku 始终可解析。 + expect(submitted.meta.claudeDesktopModelRoutes).toMatchObject({ + "claude-sonnet-4-6": { + model: "upstream-old", + labelOverride: "upstream-old", + }, + "claude-opus-4-8": { model: "upstream-old" }, + "claude-haiku-4-5": { model: "upstream-old" }, + }); + expect( + Object.keys(submitted.meta.claudeDesktopModelRoutes).sort(), + ).toEqual(["claude-haiku-4-5", "claude-opus-4-8", "claude-sonnet-4-6"]); + }); + + it("回填空档时继承 Sonnet 的 1M 声明", async () => { + const onSubmit = vi.fn(); + renderForm( + { + name: "Proxy Provider", + settingsConfig: { + env: { + ANTHROPIC_BASE_URL: "https://api.example.com", + ANTHROPIC_AUTH_TOKEN: "sk-test", + }, + }, + meta: { + claudeDesktopMode: "proxy", + claudeDesktopModelRoutes: { + "claude-sonnet-4-6": { model: "deepseek-v4-pro", supports1m: true }, + }, + }, + }, + onSubmit, + ); + + fireEvent.click(screen.getByRole("button", { name: "保存" })); + + await waitFor(() => expect(onSubmit).toHaveBeenCalled()); + const routes = onSubmit.mock.calls[0][0].meta.claudeDesktopModelRoutes; + // 留空的 Opus / Haiku 回填同一上游模型，1M 声明应与 Sonnet 一致。 + expect(routes["claude-sonnet-4-6"]).toMatchObject({ + model: "deepseek-v4-pro", + supports1m: true, + }); + expect(routes["claude-opus-4-8"]).toMatchObject({ + model: "deepseek-v4-pro", + supports1m: true, + }); + expect(routes["claude-haiku-4-5"]).toMatchObject({ + model: "deepseek-v4-pro", + supports1m: true, + }); + }); + + it("保存直连模型列表时不会保留旧 route 作为隐藏映射目标", async () => { + const onSubmit = vi.fn(); + renderForm( + { + name: "Direct Provider", + settingsConfig: { + env: { + ANTHROPIC_BASE_URL: "https://api.example.com", + ANTHROPIC_AUTH_TOKEN: "sk-test", + }, + }, + meta: { + claudeDesktopMode: "direct", + claudeDesktopModelRoutes: { + "claude-old": { + model: "claude-old", + }, + }, + }, + }, + onSubmit, + ); + + fireEvent.click(screen.getByRole("button", { name: "保存" })); + + await waitFor(() => expect(onSubmit).toHaveBeenCalled()); + const submitted = onSubmit.mock.calls[0][0]; + expect(submitted.meta.claudeDesktopModelRoutes).toMatchObject({ + "claude-sonnet-4-6": { + model: "claude-sonnet-4-6", + }, + }); + }); });