一个按钮四种意思：CC Switch 的供应商主按钮

供应商卡片上的主按钮，源码里给它的默认文案有时是「启用」，有时是「添加」，有时是「加入」。文案背后的动作也是三件不同的事：把当前 CLI 切到这个供应商、把这条记录加进被托管应用的原生配置、把它排进故障转移队列。同一个组件、同一个位置渲染出来的一个按钮，后果完全不同。

这不是偷懒，是一个被逼出来的设计：这个工具要同时伺候好几种被托管的 AI CLI，而这些 CLI 对「选中一个供应商」的定义本来就不一样。有的是单选切换，有的是往配置里累加成员，有的还要参与本地网关的转发排队。要把它们塞进同一张卡片，主按钮就只能做成状态机。本文把这台状态机拆开。

先说清楚这篇的依据

本文对应仓库快照 3217f725（仓库内版本号 3.20.1），核对日 2026-08-31。所有结论都来自静态阅读 src/components/providers/ 下的源码，我们没有编译、没有运行、也没有安装过这个桌面应用，因此下文不会出现任何关于界面长相、点击手感、切换快慢的描述。凡是提到「文案」的地方，指的都是源码里写死的默认文案字符串，不是我们在屏幕上看到的东西。

按钮状态是一个结构体，不是一堆 if

主按钮的全部呈现信息被收进 src/components/providers/ProviderActions.tsx 里的一个 MainButtonState 结构，六个字段：disabled、variant、className、icon、text，以及可选的 title。

计算这个结构体的是 getMainButtonState()（ProviderActions.tsx:143-259），它的四条分支各自 return 一份完整的 MainButtonState。渲染处不做任何判断，只是把字段摊开挂到按钮上（ProviderActions.tsx:366-385）。点击行为则由另一个函数 handleMainButtonClick()（ProviderActions.tsx:118-141）负责。

这个切法值得单独说一句：按钮的「长什么样」和「点下去干什么」在代码里是两条独立的线。好处很直接——JSX 里没有嵌套三元，读渲染部分不需要在脑子里模拟分支。代价同样直接：两个函数各自维护了一份顺序完全相同的优先级链，没有任何机制保证它们同步。谁往中间插一个新模式而只改了其中一个，结果就是按钮上写着 A、点下去做 B。这类不一致编译器抓不到，测试如果不覆盖两条线也抓不到。

四条互斥分支

getMainButtonState() 顶层是四条互斥分支，进入顺序固定，前面的命中了后面的就没有机会：

模式	判据（行号）	按钮的两种态
OMO	isOmo（:145）	「使用中」↔「启用」
累加成员制	isMembershipMode（:115、:165）	「移除」↔「添加」
故障转移	isFailoverMode（:113-114、:207）	「已加入」↔「加入」队列
普通	兜底（:228-258）	「使用中」（禁用）/「启用」

handleMainButtonClick() 用同一顺序派发动作，一一对应。

第二行还有一个小例外值得记一笔：累加模式下按钮文案本该是「添加」，但 pi 这个应用被单独挑出来改写成了「启用」（ProviderActions.tsx:201-203）。也就是说，同一条分支、同一个 return 语句，文案还要按被托管应用再分一次叉——按模式数出来的「四种意思」，是这台状态机的下限而不是上限。

判据比分支本身更值得看

真正决定走哪条分支的几个布尔量集中在 ProviderActions.tsx:108-115 这一小段里，其中两条最值得停下来看。

第一，isAdditiveMode 里硬写着一个排除项。 它的定义在 ProviderActions.tsx:108-110，形状是 isAdditiveAppId(appId) && !(appId === "opencode" && isOmo)——先问「这个应用是不是累加语义」，再把 OpenCode 下面的 OMO 条目从累加语义里剔出去。同一个被托管应用下的两类条目走不同的按钮语义，这个例外是写死在判据里的，不是靠上层传参绕开的。

isAdditiveAppId 的定义不在这个文件里，在 src/config/appConfig.tsx:83-85，名单常量在 :76-81。这是一份会随版本增删的枚举——具体哪几个应用在名单里，去读那几行即可，这里不抄，因为它下个版本就可能不一样。

第二，isMembershipMode 只是 isAdditiveMode 的别名。 一处赋值把两个名字绑成同一个值（:115），分支判断用 isMembershipMode（:165），判据计算用 isAdditiveMode。两个名字在同一个文件里指向同一件事，读代码时得先确认这一点，否则会误以为它们是两种不同的模式。

缺一个回调，「移除」就变成了「删除」

累加模式的点击派发里藏着一个需要留意的回退（ProviderActions.tsx:127-132）：这条分支要执行「从原生配置里移除这条成员」时，会先看父组件有没有把 onRemoveFromConfig 传下来；没传，就退化成调用 onDelete。

这两件事并不等价。前者动的是被托管 CLI 的配置文件，后者动的是这个工具自己的供应商记录。在缺回调的情况下，代码选择让两种语义在这一刻合并成同一个动作。

按我们实读的源码状态，这个回退是显式写出来的，不是遗漏。我们不推测作者为什么这么设计，只把它记下来：读这段代码时，「移除」这条路径的实际后果取决于父组件传了什么，而按钮文案不会跟着变。

判据的判据：isCurrent 和「已在配置里」都是算出来的

主按钮反复用到两个输入——「这条是不是当前生效的」和「这条在不在原生配置里」。它们都不是从后端直接取来的字段，而是父组件 ProviderList.tsx 现算出来的。

先看「当前生效」（ProviderList.tsx:439-455），这是整个目录里分支最密的一处：

const isCurrent =
  appId === "pi" ? false
  : isOmo ? isOmoCurrent
  : isOmoSlim ? isOmoSlimCurrent
  : appId === "hermes" ? isHermesCurrent
  : provider.id === currentProviderId;

五种语义并存：pi 永远返回 false，也就是这个应用下的条目从不被标成「当前」；OMO 与 OMO Slim 各有一份独立的「当前项」查询（ProviderList.tsx:168-169）；Hermes 的当前项来自它 live 配置里的 model.provider（ProviderList.tsx:117-119）；只有其余应用才是最朴素的 provider.id === currentProviderId。

再看「已加入配置」（ProviderList.tsx:122-136 的 isProviderInConfig）：只有少数几个走累加语义的应用会去查 live id 列表，其余 appId 一律直接 return true（ProviderList.tsx:133）。恒真意味着对非累加应用而言，这个输入不携带信息，只是让下游分支能统一取用。pi 又是单独一条路（ProviderList.tsx:217-223），而且带一道守卫：权威状态还没就绪时先返回 false（ProviderList.tsx:216-219），宁可先当作「不在配置里」，也不拿一个还没加载完的状态去驱动按钮。

把这两段和上一节的分支表放在一起读才完整：主按钮的四条分支是在判断语义，而语义所依赖的两个布尔本身，又各自是一条五分支和一条按应用分叉的链。

故障转移这条分支，能不能出现由父组件说了算

四条分支里的故障转移是最特殊的一条：它的开关不在 ProviderActions 自己身上。

ProviderList.tsx:151-153 有一个明确的能力判定，注释也把理由写在了上面：

// Only apps with an explicit local-routing capability participate in
// failover. Additive apps such as Pi never query or render this state.
const supportsFailover = isProxyAppId(appId);

isProxyAppId 定义在 src/config/appConfig.tsx:67-69，白名单常量在 :58-64——同样是一份会变的枚举，这里只记机制：只有具备本地网关能力的应用才参与故障转移。

有能力还不等于这个模式真的激活。ProviderList.tsx:162-165 要求三个条件同时成立：supportsFailover、isProxyTakeover === true、isAutoFailoverEnabled === true。队列里的优先级角标则是另一处小设计：它不是存下来的字段，而是由条目在队列里的下标加一得出（ProviderList.tsx:171-180）——队列顺序变了，角标自然跟着变，不需要额外同步。

值得注意的是这个能力判定所在的位置：它是在父组件里集中做出的，然后以「传不传对应的回调」的形式向下表达。子组件那一侧因此看不到一个显式的能力字段，只能从手里有没有回调倒推。这种写法省掉了一个 prop，代价是「这个应用支不支持故障转移」这件事在子组件的接口上不可见。

禁用了，就没法解释为什么禁用

MainButtonState 里那个可选的 title 字段，对应的是一个相当具体的可用性问题，源码里有完整交代。ProviderActions.tsx:64-67 的注释把问题和解法都写清楚了：

// 因 Button 基类带 disabled:pointer-events-none，title 必须挂在外层非禁用
// 的 wrapper 上才会在 hover 时显示（见下方 <span> 包裹）。

为了让禁用按钮不响应指针事件，基础 Button 组件在 disabled 状态下带上了 pointer-events-none。这个类名一挂，浏览器原生的 title 提示也一起失效——元素收不到指针事件，自然也不会触发提示。于是就形成一个死结：按钮越是需要解释自己为什么不可用，越是没办法解释。

这个项目给的解法在 ProviderActions.tsx:366-385：主按钮外面套一层只干两件事的 <span>——承载 title，以及在禁用时挂上 cursor-not-allowed。按这段注释给出的解释，包裹层自身不带 disabled，指针事件仍会落在它上面，提示与光标样式因此都能生效。

顺着注释的用途说明还能读出一件事：title 是可选字段，它服务的只有禁用态。按钮能点的时候不需要解释自己，需要解释的恰恰是点不动的那些情况——而哪一种禁用需要解释、哪一种不需要，是在四条分支里一处一处判断出来的，没有统一规则兜底。

删除按钮的四层判断

同一个组件里，删除按钮的可用性走的是另一套逻辑（ProviderActions.tsx:262-268）。读法是四层：只读条目一律不可删；pi 看状态是否就绪；OMO 与累加模式恒可删（这两种模式下「当前在用」这个概念要么不存在、要么不阻止删除）；其余应用则是「正在用的那条不能删」。

注意它和主按钮的关系：两者都吃 isCurrent、isOmo、isAdditiveMode 这几个量，但组合方式完全不同——主按钮拿它们决定语义，删除按钮拿它们决定保护。同一批输入，两条互不相干的判断链，改动其中一条不会自动惊动另一条。

主按钮只是操作区的第一格

把视野拉回整块操作区就能看清主按钮的位置。ProviderActions.tsx:387-477 是一排图标按钮，顺序固定：编辑（:388，只读时禁用并换提示）、复制（:403，仅当 onDuplicate 存在时才渲染）、连通检测（:415，isTesting 为真时换一个图标组件）、用量配置（:433）、打开终端（:447，仅当 onOpenTerminal 存在）、删除（:462）。它们共用同一个尺寸类常量（ProviderActions.tsx:105）。

再往前，openclaw 与 hermes 在图标区之前还多一个「设为默认 / 启用」按钮（ProviderActions.tsx:281-364）；openclaw 且存在多个候选模型时，这个按钮还会变成下拉菜单，让人挑具体哪个模型作为默认（ProviderActions.tsx:300-346）。

这里有个规律：**按钮是否存在，靠的是「回调传没传」；按钮是否可用，靠的是判据布尔。**两种控制手段混在同一块区域里，前者由父组件决定，后者由本组件计算。

这套写法的代价

把这个文件从头读到尾，会反复撞见同一个模式：一个 appId === "xxx" 的比较，决定一小段语义。整个 src/components/providers/ 目录里这类按被托管应用分叉的写法随处可见，主按钮把它们集中在了一个函数里而已。

它的直接后果是：给这个工具接一个新的被托管 CLI，改动不会集中在一个地方。你得判断它是切换语义还是累加语义（改 appConfig.tsx 的名单）、要不要参与故障转移（看它在不在具备本地网关能力的名单里，以及父组件传不传对应回调）、「当前生效」该怎么算（改 ProviderList.tsx 那条五分支）、删除该受什么保护（改 canDelete 那条三元链）。这些点分散在判据、分支、渲染、回调四处，没有一个统一的能力声明表把它们收拢起来。

这是把「多种语义压进一个按钮」这个产品决策，如实换算成的代码形态。要读懂那个按钮，就得把 ProviderActions.tsx:108-268 这一段完整看一遍，再回头补上 ProviderList.tsx 里算判据的那几十行——中间没有可以跳过的部分。

---

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