CC Switch 怎么把几百个 IPC 调用收进一层封装

Tauri 应用的前后端通信长这样：前端写 invoke("get_providers", { app: appId })，后端 Rust 侧有个带 #[tauri::command] 属性的函数接住它。问题出在中间那个字符串——它是运行时才解析的，TypeScript 编译器不认识它，后端把函数改个名，前端连一条编译报错都不会有，只有代码真的执行到那一步才会炸。

一个只有十几个命令的小工具，散着写也没事。CC Switch 这种规模就不行了：它要同时管住多个 AI 编程 CLI 的供应商配置、提示词、Skills、MCP、会话与用量，还带一个本地代理层，命令名是几百个的量级。这几百个字符串放在哪一层，基本决定了这个前端往后还能不能改动。

先说清楚这篇是怎么来的

本文只静态读源码。对应的仓库快照是 3217f725（仓库内版本号 3.20.1），核对日 2026-08-31，涉及跨版本的地方以 v3.19.2 快照作对照。我们没有编译过它，没有安装过这个桌面应用，也没有运行过任何界面，所以下面不会出现任何关于外观、操作手感或响应速度的描述——凡是写出来的，都能在仓库里按文件加行号找到。

截断点选在 src/lib/api/

先看边界事实。用下面两条命令可以自己复现口径：

grep -rln 'from "@tauri-apps/api/core"' src --include=*.ts --include=*.tsx | sort
grep -rhoE 'invoke(<[^>]*>)?\("[a-zA-Z0-9_]+' src/lib/api | sed 's/.*"//' | sort -u | wc -l

第一条数的是「哪些文件碰了 Tauri 的核心 API」，第二条数的是「src/lib/api/ 里一共出现过多少个不同的后端命令名」。在 v3.20.1 这个快照上，引用核心 API 的文件里，绝大多数集中在 src/lib/api/ 一个目录下；去重后的命令名是几百条的量级。具体数字这里不写死，因为它每个版本都在变，你按上面的命令重数一遍比记住一个数字有用。

关键在于剩下的那一小撮例外。它们不是漏网之鱼，而是几类结构上就进不了 API 层的调用，几个代表：

位置	命令	性质
src/main.tsx:91	get_init_error	启动早期主动拉后端初始化错误，此时 React 应用还没挂载
src/components/theme-provider.tsx:109	set_window_theme	同步原生窗口主题，属窗口层而非业务数据
src/components/DatabaseUpgrade.tsx:271	open_external	打开发布页
src/components/DatabaseUpgrade.tsx:282	open_app_config_folder	打开配置目录
src/lib/clipboard.ts:5	copy_text_to_clipboard	系统剪贴板能力，见后文

这张表要读的不是「有几处例外」，而是这些例外的共同点：全都不在业务数据流上。启动期的初始化错误比应用本身还早；窗口主题和外部打开是宿主能力；剪贴板是系统能力。真正的业务读写——供应商、设置、Skills、会话、用量——一条都没漏出来。这就是「截断点选在哪」的答案：不是按调用量切，是按数据性质切。

封装体只做三件事

进了 src/lib/api/ 之后，封装薄到有点出人意料。看 src/lib/api/providers.ts:50-52：

async getAll(appId: AppId): Promise<Record<string, Provider>> {
  return await invoke("get_providers", { app: appId });
},

绝大多数方法都是这个形状：给命令起一个 TypeScript 侧的名字、把参数改成对象形状、标上返回类型。不做校验，不做缓存，不做重试。 有一条硬证据：

grep -rn 'useQuery\|useMutation' src/lib/api | wc -l

结果是 0。这个项目用了 TanStack Query，但缓存和请求策略一律不在 API 层，全在 src/lib/query/ 和 src/hooks/ 里。API 层被刻意压成一层没有状态的翻译纸——上面换缓存策略不用动它，下面后端改命令名只改它。

三处刻意的破例

薄归薄，有几处专门写了逻辑，而且都跟安全或契约有关，值得单独看。

第一处是 src/lib/api/settings.ts:215-226 的 openExternal()：调 open_external 之前，前端先 new URL(url)，把 protocol 取出来小写比对，不是 http 也不是 https 就直接 throw，解析失败也 throw。这是在前端侧加了一道 scheme 白名单。注意这只是前端这一层的检查，后端有没有自己的校验属于另一块源码，不在本文核对范围内。

第二处是同文件 :205-213 的 syncCurrentProvidersLive()。后端这个命令失败时返回的是 { success, message } 结构而不是 reject，于是这里把 success 不为真的情况转成 throw new Error(result?.message || ...)。这一步的意义是让上层的错误路径能接住它——如果不转，调用方拿到的是一个「成功返回的失败对象」，得每个调用点自己判断一遍。

第三处是 src/lib/api/model-fetch.ts:75-121 的 showFetchModelsError()：先做前端预检（缺 baseUrl、缺 apiKey 分不同提示，:80-92），再按后端返回的错误字符串分流——HTTP 401|403 归鉴权失败，All candidates failed 与 HTTP 404|405 归端点不存在，timeout|timed out 归超时，Failed to parse 归不支持，其余走通用兜底（:120）。这种写法很直白，但它把后端的错误文案变成了事实上的协议：后端改一个字的措辞，这边的分类就失配。这不是评价谁对谁错，只是描述这层封装的契约是怎么维系的。

AppId：一行类型收口所有应用标识

src/lib/api/types.ts:2-11 定义了一个联合类型 AppId，文件头注释写明「与后端命令参数 app 一致」。所有 API 方法接的都是它，不是裸 string。

这个设计的收益在跨版本 diff 里看得最清楚。对 src/lib/api/types.ts 跑 git diff v3.19.2..v3.20.1，v3.20.1 在这个文件里只加了一行：新接入的那家 CLI 的标识。类型层的改动面就是一行——所有拿 appId 做分支的地方都从这一处取值，不用在各处补零散的字符串常量。

要说清楚的是，「类型层只改一行」不等于「接一家新的什么都不用写」。这家 CLI 另有一个专属的供应商表单组件 src/components/providers/forms/PiProviderForm.tsx:530，它和另外三个供应商表单（ProviderForm.tsx:462、ClaudeDesktopProviderForm.tsx:343、GrokBuildProviderForm.tsx:161）共用同一个 providerSchema。也就是说，专属的界面与字段逻辑照写不误，收口层管住的只是标识与类型这一层。

把 diff 范围限定在 src/lib 和 src/hooks 这两个目录看，同一版在这里新增的四个文件（src/lib/api/pi.ts、src/lib/query/pi.ts、src/lib/piPromptSlug.ts、src/lib/piPromptTemplate.ts）全是这家客户端的专属逻辑，跟收口层是分开的。注意这只是这两个目录下的口径，整版的改动面比它大得多——发布说明里另有一套整版自称的规模，两者是包含关系，不是同一个数。这也是判断一个收口设计有没有真收住的办法：看接入一家新的会不会渗透到公共代码里。

一层封装里的三处不统一

这层封装内部并不统一，有三处对不上，说清楚位置就行，不做评判。

第一处是导出风格。grep -rn 'export const [a-zA-Z]*[Aa]pi' src/lib/api 能数出一批 xxxApi 对象命名空间（providersApi、settingsApi、skillsApi 这类）；但另有几个文件不用对象、直接导出裸函数，用这条命令可以数出来：

for f in src/lib/api/*.ts; do grep -q 'export const .*[Aa]pi = {' "$f" || echo "$f"; done

config.ts、connectivity-check.ts、copilot.ts、env.ts、globalProxy.ts、model-fetch.ts 属于后一类（index.ts 与 types.ts 不算）。以上为按仓库中的参数语义组合的示例命令，未经实测，以官方文档与实际输出为准。

第二处是桶文件的处理随之分叉。src/lib/api/index.ts:1-33 里，对象式的走 export { xxxApi } from ...，裸函数式的走 export * as configApi from "./config"（:17-19，configApi / authApi / copilotApi 三个是这种）。而 connectivity-check、env、globalProxy、model-fetch 根本没进桶，调用方必须写全路径 @/lib/api/connectivity-check——src/hooks/useStreamCheck.ts:4-7 就是这么导的。

第三处是命名。命令名以 snake_case 为绝对主流，但 src/lib/api/usage.ts:25 的 queryProviderUsage 与 :39 的 testUsageScript 是 camelCase，两条都在用量脚本这一块。以上三处都是「A 处一个写法、B 处另一个写法」的并存事实，以我们实读的仓库状态为准，至于为什么会这样，不在能核实的范围内。

一个能力两条实现：剪贴板

src/lib/clipboard.ts:3-18 是全仓少见的写法：先试 invoke("copy_text_to_clipboard")，失败了再退到浏览器的 navigator.clipboard.writeText；两条都失败时优先抛 web 侧的错误，只有 web 侧抛出的不是 Error 实例才回落到原生侧的错误。

它没被收进 src/lib/api/，而是单独放在 src/lib 根下。从结构上看这合理——它不是「调某个后端命令」，而是「同一个能力有原生和 Web 两条路」，抽象层次跟那些一对一透传的方法不是一回事。

注册了、但前端搜不到引用的那些命令

收口做得好，就能反过来做一件事：拿后端注册表跟前端调用点对账。

口径是这样的：从 src-tauri/src/lib.rs 的 tauri::generate_handler![...] 列表里抽出所有命令名（v3.20.1 里这段在 :1372-1714），然后逐个在前端源码里搜带引号的完整字符串：

grep -rl "\"<命令名>\"" src --include=*.ts --include=*.tsx

在 v3.20.1 这个快照上，有十几个命令零命中。举几个具体的：enter_lightweight_mode、exit_lightweight_mode、is_lightweight_mode 这组轻量模式开关，get_proxy_config、update_proxy_config、is_proxy_running 这组代理配置读写，以及 import_from_deeplink。

最后这个尤其典型：src-tauri/src/lib.rs:1520-1521 里，import_from_deeplink 和 import_from_deeplink_unified 是同时注册的，而前端只调后者（src/lib/api/deeplink.ts:110）。新旧两个命令并存，旧的还留在注册表里。

措辞上必须克制：零命中只说明「前端 TypeScript 源码里搜不到这个字符串」。这些命令完全可能被 Rust 侧内部调用，也可能是留给外部集成的入口——我们没有核实后端的调用图，所以不能说它们是死代码。这个对账结果的正确用法是当线索，不是当结论。

顺带一个同口径下的现象：grep -rn '#\[tauri::command\]' src-tauri/src | wc -l 数出来的命令属性数量，和 handler 注册列表逐行抽取去重后的数量对不上，后者更多。差额的成因我们没有核实（已经排除了一种可能：属性和 fn 之间隔着文档注释导致行内 grep 漏抓，比如 src-tauri/src/commands/auth.rs:111 的 auth_start_login 就是这种写法）。两个数字都会随版本变，这里只记录现象和口径。

这层封装没做什么

薄封装的代价也要说清楚。在 src/lib 和 src/hooks 这两个目录里，我们没有找到：

• 统一的错误包装层。没有 invokeSafe 之类的东西，每个调用点自己 try/catch。
• 统一的请求超时设置。只有两处各自写死的超时——一处在模型定价同步模块，一处在更新检查模块，值也不一样。
• 请求级的重试退避策略。重试完全靠 TanStack Query 的 retry / retryDelay 在各处逐个硬写。

这三条是「我们在这两个目录里没有搜到」，不是「一定不存在」。但组合起来能看出这层设计的取向：它承担的是命名与类型的收口，不承担可靠性。可靠性的活儿被推到了上一层的查询层去做——那一层有条件轮询、有失败降级策略、有分级的刷新节律，跟这一层完全不是一个关注点。关于查询层怎么处理失败与缓存，我们另有一篇专门讲。

你可以怎么复核

如果你也在维护一个 Tauri 应用，这套对账方法是可以直接搬的：

1. 先定住截断点，用 grep -rln 'from "@tauri-apps/api/core"' src 数一遍有多少文件碰了 invoke。数字远大于你的 API 目录文件数，说明收口已经漏了。
2. 把漏出去的逐个看一遍，判断它是不是「结构上进不了 API 层」的那几类（启动期、窗口层、系统能力）。是就留着，不是就该收回去。
3. 从后端注册表抽命令名，跟前端源码对账，把零命中的挑出来当线索——只当线索。

Windows 下用 PowerShell 的话，上面几条 grep 换成 Select-String 即可，-r 对应 -Recurse 配 Get-ChildItem；在 Git Bash 或 WSL 里原样可用。以上为按仓库中的命令语义组合的示例，未经实测，请以你本机工具的实际行为为准。

这些命令的价值不在于跑出哪个数，而在于口径可复现——下个版本再跑一遍，差异就是这一版在 IPC 边界上真正动过的东西。

---

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