CC Switch 的预设怎么决定表单长什么样：四个开关

翻 CC Switch 的供应商表单代码，最先撞上的困惑是：同一个 ProviderForm，选中不同预设之后，渲染出来的字段集合差别可以很大——有的时候 API Key 那一块整个不出现，有的时候会多出几个预设自带的参数输入框，有的时候端点地址和测速那一整块被摘掉。找一个统一的「表单模式」变量是找不到的，代码里没有这么一个东西。

真正的答案是：没有单一开关，而是四条互不干涉的判定路径。预设条目上携带的 category、templateValues、providerType、apiFormat 四组字段各自控住一部分渲染条件，它们之间不做协调，也不共享状态。理解了这四条，src/components/providers/forms/ 下那堆看起来杂乱的 && 渲染守卫就有秩序了。

先说清楚这篇文章的依据

本文对应仓库快照 3217f725（仓库内版本号 3.20.1），核对日 2026-08-31。所有结论都来自静态读源码与仓库内的 md 文档，没有编译、没有运行、也没有安装过这个桌面应用，因此下文一概不涉及界面外观、控件位置或者操作感受，只讲「什么条件成立时这段 JSX 会被渲染」。行号一律以 v3.20.1 快照为准，这个项目迭代很快，行号大概率会漂。

前提：有三家根本不进这套表单

在讨论四个开关之前得先排除三个例外。ProviderForm.tsx:275-287 是一个纯分流函数：

export function ProviderForm(props: ProviderFormProps) {
  if (props.appId === "pi") return <PiProviderForm {...props} />;
  if (props.appId === "claude-desktop") return <ClaudeDesktopProviderForm {...props} />;
  if (props.appId === "grokbuild") return <GrokBuildProviderForm {...props} />;
  return <ProviderFormFull {...props} />;
}

这三家是彻底独立的整表单实现，下文说的四个开关对它们一概不适用。有意思的是 ProviderFormFull 内部还留了一道运行时断言（ProviderForm.tsx:303-305）：if (appId === "claude-desktop") throw new Error("ProviderFormFull should not receive claude-desktop")。同一个条件写了两遍，一遍分流一遍抛错，防的是后来者绕过分流函数直接引用内部组件。

预设是怎么被取到的：前缀加下标

ProviderForm.tsx:751-784 的 presetEntries 按 appId 选取预设数组，并就地编号：codex 一路是 codex-${index}，gemini 是 gemini-${index}，opencode、openclaw、hermes 同理，兜底那一路是 claude-${index}。

预设 ID 就是「前缀加数组下标」。 这个设计有两个直接后果值得记住。第一，下标即身份，往数组中间插一条会让此后所有条目的 ID 集体位移；AddProviderDialog.tsx 里多处用 parseInt(values.presetId.replace("<prefix>-", "")) 把 ID 反解回下标去回查原始预设，useProviderCategory.ts:49-51 也用同一套正则 /^(claude|codex|gemini|opencode|openclaw|hermes)-(\d+)$/ 反解。第二，只有 claude 那一路在编号之前先做了 .filter((p) => !p.hidden)（ProviderForm.tsx:779）——过滤发生在编号之前，所以隐藏条目不会在编号序列里留下空洞。

顺带说一句：上面那条正则里没有 claude-desktop、grokbuild、pi，正好和前一节的分流对上。

开关一：category 控大类

category 由预设携带，缺失时回退成 preset.isOfficial ? "official" : undefined（useProviderCategory.ts:64-66）。编辑既有条目时它被锁死成 initialCategory 且后续不再自动更新（useProviderCategory.ts:36-40），这一点在读代码时很容易漏掉。

它控住的渲染条件散在多个文件里，下面这张表只列本文用得上的几条：

category 取值	影响	出处
official	API Key 输入框置灰	forms/shared/ApiKeySection.tsx:59
official	端点输入框与测速整块不渲染	ProviderForm.tsx:1851-1852、ClaudeFormFields.tsx:737
official	模型选择器整块不渲染	ProviderForm.tsx:2412
cloud_provider	「上游格式」下拉不渲染	ClaudeFormFields.tsx:812
cloud_provider	跳过端点与 Key 的空值校验	ProviderForm.tsx:1414-1415
omo / omo-slim	切到完全不同的字段组件与只读 JSON 预览	ProviderForm.tsx:2568-2586、:2680-2692

ApiKeySection.tsx:59 那一行写法很典型：disabled={disabled ?? category === "official"}——外部没显式传 disabled 时，才由 category 兜底决定。这些取值枚举是 v3.20.1 的现状，随版本增减是常态，别把它当成固定清单。

开关二：templateValues 直接生成输入框

这是四条路径里最字面的一条：预设自带一张参数表，表里写几条就渲染几个输入框。ClaudeFormFields.tsx:702-734 直接对 templateValueEntries.map(([key, config]) => ...)，label、placeholder、默认值全部取自 config，表单代码本身对这些参数叫什么名字一无所知。

真正讲究的是回写。useTemplateValues.ts:200-241 的 handleTemplateValueChange 不是拿新值把整份配置重算一遍，而是先用 collectTemplatePaths（useTemplateValues.ts:30-58）递归扫描预设配置，找出所有含 ${key} 占位符的路径（对象键与数组下标混合的路径都支持），再只把这些路径上的值写回当前配置（applyTemplateValuesToConfigString，useTemplateValues.ts:110-155）。这么绕一圈的收益很具体：用户手工改过的其他字段不会被一次输入冲掉。整份重算是做不到这件事的。

校验则刻意留了余地——validateTemplateValues（useTemplateValues.ts:244-270）逐条要求非空并返回第一个缺失字段的 label，但 ProviderForm.tsx:1135-1145 把它归到软性提示而不是硬拒绝。

还有个边界：这套只有 claude 一路吃。useTemplateValues.ts:171-176 里那句 if (entry && "settingsConfig" in entry.preset) 带着「只处理 ProviderPreset（Claude 预设）」的注释，ProviderForm.tsx:830-831 传入 presetEntries 时也加了 appId === "claude" ? ... : [] 的守卫。

开关三：providerType 整块替换认证区

getPresetProviderType()（ProviderForm.tsx:145-154）从预设里读出三选一的 "github_copilot" | "codex_oauth" | "xai_oauth"，其余值一律返回 undefined。随后 ProviderForm.tsx:795-806 把「预设声明的 providerType」和「已存 meta 里的 providerType」合并判定；其中一条分支还额外接受一条从已填端点地址推断的兜底路径（ProviderForm.tsx:799）。

渲染侧的关键只有一行，ClaudeFormFields.tsx:689：

{shouldShowApiKey && !usesOAuth && (<ApiKeySection ... />)}

预设一旦声明自己走 OAuth，API Key 输入块整个消失。 usesOAuth 的组成见 ProviderForm.tsx:2379-2384，除了三种 providerType，还包括 templatePreset?.requiresOAuth === true。三个 OAuth 区块各自独立 && 渲染（ClaudeFormFields.tsx:652-686）。Codex 侧是同一套写法：CodexFormFields.tsx:734 用 {!isCodexOauthPreset && !isXaiOauthPreset && (<ApiKeySection ...>)}，且端点输入框对 xAI OAuth 也隐藏（CodexFormFields.tsx:779，注释说明托管 OAuth 端点由 adapter 硬定向，不需要展示）。

连模型下拉的数据源都跟着换——ClaudeFormFields.tsx:446-459 按 Copilot、Codex OAuth、xAI、普通四种情况分别选 fetch 函数和 loading 状态，renderModelInput（ClaudeFormFields.tsx:462-564）再按同样四分支选不同的输入控件形态。

开关四：apiFormat 决定高级区出现哪几组字段

Codex 侧最典型，CodexFormFields.tsx:449-452 只有两行外加一段注释：

// 思考能力随 Chat 格式显示（仅 Chat Completions 转换路径用得上）；模型映射常驻
//（填了才生成 catalog）。两者都已与「路由接管」概念解耦。
const isChatFormat = apiFormat === "openai_chat";
const isAnthropicFormat = apiFormat === "anthropic";

高级区还有一条自动展开策略（ClaudeFormFields.tsx:233-256，Codex 侧对应 CodexFormFields.tsx:465-492）：检测到任一高级值非默认就自动展开，且只会折叠转展开、不会自动折叠（注释在 ClaudeFormFields.tsx:249）。唯一的例外是 xAI OAuth 预设，它的高级值都是预设自带的，强制保持折叠（CodexFormFields.tsx:483-485）。

保存侧：没渲染的字段也不会被偷偷带上

四个开关讲完，还剩最容易出 bug 的一半——保存。ProviderForm.tsx:1759-1823 构造 nextMeta 时，是一整块 ? ... : undefined 三元链，条件与渲染侧一一对应：codexChatReasoning 和 promptCacheRouting 只在 localCodexApiFormat === "openai_chat" 时才写进 meta；impersonateClaudeCode、maxOutputTokens 则是 codex 一路且格式为 "anthropic" 时才写。

apiKeyField 要单独拎出来说，它是这串条件里唯一一个分两条分支的字段：claude 一路和 codex 一路的写入条件并不相同，claude 侧压根不看 apiFormat，codex 侧才额外要求格式是 "anthropic"。把它和上面两个并排记成「都要 anthropic 格式」，回仓库对代码时就会对不上。此外还有一层与格式无关的前置：category 为 official 时，apiFormat、apiKeyField、customUserAgent、isFullUrl 这一组一律不落进 meta（ProviderForm.tsx:1772-1830）——这也是开关一在保存侧留下的痕迹。

写完之后还有四条兜底清理（ProviderForm.tsx:1833-1844），把 codexFastMode、providerType、authBinding、githubAccountId 中值为假的键从 meta 里 delete 掉。配合前面的三元链，效果是 meta 里不会残留上一次表单状态留下的空壳字段。

顺带记一个默认值：claude 一路的 apiKeyField 默认是 "ANTHROPIC_AUTH_TOKEN"（ProviderForm.tsx:2114），保存侧也据此判断——只有当它被改成别的值时才落进 meta（判定就在 ProviderForm.tsx:1759-1823 这块三元链里）。这是 v3.20.1 的默认配置，可配，且会随版本变。

这里有个不太舒服的事实值得说出来：「渲染条件不成立的字段，保存时也不写进 meta」这条一致性没有任何统一机制兜底，它是靠保存侧逐个 case 手写条件、去对齐渲染侧逐个 case 手写条件实现的。两边都是人工维护的三元链，中间没有共享的「字段可见性」声明。新加一个 apiFormat 相关字段时，只改渲染侧不改保存侧，或者反过来，代码都能编译通过。

想自己核一遍的话

顺序建议是：先读 ProviderForm.tsx:275-287 确认分流，再读 :751-784 看预设怎么编号，然后拿 category / templateValues / providerType / apiFormat 这四个词在 src/components/providers/forms/ 下各 grep 一遍——每个词的命中点会自然分成「读取处」「渲染守卫」「保存条件」三簇，四条路径的正交性就是这么看出来的。最后再回到 ProviderForm.tsx:1759-1844 对一遍保存侧，看渲染守卫和保存条件是不是逐条对得上。

---

本文依据 CC Switch 官方仓库（github.com/farion1231/cc-switch）的 README、docs/ 下的用户手册、 路由指南与发布说明，以及 src/、src-tauri/、tests/ 的源码整理， 核对日 2026-08-31，对应仓库快照 3217f725（仓库内版本号 3.20.1）。 本文内容为仓库源码与文档口径，我们没有安装或运行过这个桌面应用， 因此不涉及界面外观、操作手感与切换速度的任何描述。 文中出现的阈值与默认值均为源码中的默认配置，不构成对实际运行结果的保证。 该项目仍在快速迭代，版本与默认值随时可能变动，请以仓库最新内容为准。 安全相关做法请结合自身环境评估，本文不构成安全方案建议。