CC Switch 多 CLI 配置管理
c39c903（版本 3.19.2）。
本专题共 40 篇。内容依据
官方仓库
的 README、docs/ 下的用户手册与发布说明、src/config/ 的预设定义
与 src-tauri/src/ 的后端源码整理。
文中出现的阈值与默认值均为源码中的默认配置，
不构成对实际运行结果的保证；该项目仍在快速迭代，请以仓库最新内容为准。
一个桌面应用管八个 AI CLI：CC Switch 到底替你做了什么
CC Switch 不是挡在你和模型之间的常驻中间层，而是一个替你改写本机 CLI 配置文件的桌面应用，数据落在一份 SQLite 里。这篇从仓库源码与文档口径出发，说清它管的是哪一层、为什么「总有一个供应商删不掉」是设计推论、切换后哪些工具要重启，以及它把哪些敏感数据放在了你本机。
认识与安装
README 自称支持八个工具而用户手册的表只列七个，这类口径差在这个仓库里不止一处。这一组还包括三个平台各自的安装产物、~/.cc-switch/ 下那一个库两种备份的落盘结构，以及 Linux 上点不动、缩放黑屏时的那个逃生环境变量。
README 说八个、用户手册只列七个：支持工具清单的三处口径差
CC Switch 到底管几个 AI CLI 工具？README 四处写「八个」，用户手册的三张清单都只有七个，而 package.json 与 Cargo.toml 的 description 只写了三个。这篇把三处口径的文件与行号标出来，给出可自己复核的比对动作，并说清为什么查「我的工具支不支持」不能只看标题行。
三个平台怎么装：msi / dmg / AppImage 与 brew、paru 的取舍
CC Switch 在 Windows、macOS、Linux 上各有两到三种安装方式。这篇按 README 与用户手册的原文把产物文件名、包管理器命令、系统要求逐条列清，重点标出一处会让你比对文件名时对不上的口径差：README 给的 Linux 包名没有架构后缀，而 CI 脚本拼出来的名字带架构。
`~/.cc-switch/` 里有什么：一个库、一份设置、两种备份与一批软链
CC Switch 把数据落在 ~/.cc-switch/ 下，README FAQ 列了五条路径。这篇把五条路径逐个对到 src-tauri 里的拼接代码，重点讲清一件反直觉的事：目录里同时存在三套互不相干的备份保留策略，其中一个可配、两个硬编码，README、用户手册与代码对这个数的写法并不一致。
Linux 上点不动、缩放黑屏：`CC_SWITCH_GDK_BACKEND` 这个逃生开关
CC Switch 在 Wayland + NVIDIA 下内容区点不动、缩放黑屏，README FAQ 的处置是环境变量 CC_SWITCH_GDK_BACKEND。本文对读 README 与 main.rs 的 Linux 分支，讲清它为何不叫 GDK_BACKEND、两个取值各对什么环境、怎么判定与验证。
README 写 Rust 1.85+ 而 toolchain 钉的是 1.95：四条版本门槛的两层口径
想从源码构建 CC Switch，README 的「环境要求」给了 Node.js 18+、pnpm 8+、Rust 1.85+、Tauri CLI 2.8+ 四条。但这四条在仓库里各有第二个出处，其中三条对不上：Rust 在同一个仓库的两个文件里差了十个小版本。本文标出每一处的文件与行号，并给出可复现的比对动作。
供应商与预设：这个项目的主线
README 说「50+ 预设」，八个应用预设数组逐条数出来是 448 条——差异从哪来、怎么自己数一遍，是这一组的开场。往下是预设的字段全集、category 同时决定 UI 分组和路由徽章、三种托管 OAuth 为什么必须开路由，以及切换之后插件配置为什么会不见。
README 说「50+ 预设」，八个预设文件里数出来 448 条
CC Switch 的预设到底有多少条？README 三处写「50+」，用户手册的表格只列几十行，而 src/config/ 下八个应用预设数组加起来是 448 条。这篇把三层口径各自的位置标出来，给出可复现的计数方法与一个会数错的 grep 陷阱，并说清 448 这个数究竟在数什么、不在数什么。
一条预设长什么样：`ProviderPreset` 的字段全集与各自作用
CC Switch 的 Claude Code 预设接口 ProviderPreset 定义了 21 个字段，但把 72 条预设逐个字段数一遍会发现：出现次数满格的只有 4 个，另有一半字段只服务于个位数条目。本文给出完整字段表与出现次数，说清每个字段落在哪一层、改它会牵动什么。
`category` 不只是个标签：它同时决定 UI 分组、路由判定和代理接管拦截
CC Switch 的预设里有个 category 字段，看着像给界面分组用的标签，实际上它在三个地方被当成开关读：分类筛选、providerNeedsRouting 的第一行早退、以及代理接管下的切换拦截。这篇给出八个取值的语义、八个应用的分类分布，并落到五条没填 category 的预设上，附可自己复现的计数方法。
「切回官方登录」是怎么实现的：CC Switch 里 official 类预设的机制
切回官方账号听上去像要写入一份官方配置，但在 CC Switch 的源码里恰恰相反：official 预设是一份刻意留空的配置，切过去之后还要专门擦掉残留的第三方凭据。本文按仓库快照逐处标出这套机制落在哪些文件的哪几行。
三种托管 OAuth 必须开路由：`OAUTH_PROVIDER_TYPES` 的判定链
CC Switch 里「这个供应商要不要开路由接管」不是看格式转换决定的。托管 OAuth 那三种 providerType 在判定链里排在 apiFormat 之前，一律返回 true。这篇把 providerNeedsRouting 的六步分支逐行标出位置，说清前端数组与后端方法的覆盖面差异，并给出复核动作。
universal 统一供应商：一份配置同步多个工具的边界在哪
CC Switch 的「统一供应商」把一份网关配置分发给多个 CLI，但它的覆盖面、同步时机与合并方式都有明确边界。本文按 src/config/universalProviderPresets.ts 与 src-tauri 后端源码，逐条讲清它能同步到谁、什么时候才同步、同步时怎么合并，以及关掉一个开关会发生什么。
切换之后配置少了一段：CC Switch 通用配置片段的提取与回填
在 CC Switch 里切换供应商后，把该供应商保存的配置和切换前的 live 文件逐字比对会发现少了一段。这不是丢失，而是 switch_normal 回填这一步先把可共享改动同步进通用配置片段再剥离写回的结果。本文按源码行号拆开这条路径，给出可复现的四步核查动作并说清哪三个应用不产出通用片段、哪三个应用不走回填。
手册说能删、后端直接报错：当前供应商删除规则的两处矛盾
CC Switch 的用户手册写「当前启用的供应商可以删除」，而后端 delete 对非累加模式应用直接返回「无法删除当前正在使用的供应商」，README FAQ 的标题也是「为什么删不掉」。这篇把三处原文的行号标出来，说清这条规则为什么按应用类型分叉，并给出删不掉时的判定与排除动作。
后端架构与 SQLite 存储
Commands → Services → DAO → Database 四层各管什么、所谓 SSOT 到底存了 16 张什么表、迁移编号为什么会跳号、配置不被写坏靠的是原子写入与自动备份这两件事。还有一篇讲怎么数 Tauri 命令数会数漏——grep 写法不对就少 19 个。
CC Switch 后端四层：Commands → Services → DAO → Database 各自管什么
cc-switch 的 README 把后端画成 Commands → Services → DAO → Database 四层。我们按仓库快照逐目录核对了这四层的文件数、行数与职责边界，并指出「DAO 层其实不是一个对象」「箭头有一处是反向的」这两处容易读错的地方，以及注释目录树与实际模块数对不上的一处差异。
16 张表读一遍：所谓 SSOT 到底存了哪些东西
CC Switch 把「所有数据存在一个 SQLite 库」写进 README 的核心设计，但把 `schema.rs` 的 16 张表读完会发现 SSOT 是分域的：Skills 的事实源在文件系统，MCP 的事实源在表里而 live 文件只是投影，还有五张表在同步时被整个跳过。本文按建表顺序过一遍并给出核查命令。
数据库怎么升级：迁移调度与建表注释里跳掉的三个编号
CC Switch 把所有可同步数据放在一个 SQLite 库里，版本一升就要动表结构。这篇讲清 SCHEMA_VERSION 与 PRAGMA user_version 是怎么配合的、逐版本递推的迁移循环长什么样、两道版本拒绝分别拦什么，并把建表注释里 13/14/15 三个跳掉的编号还原成可复现的核查动作。
原子写入与自动备份：配置不被写坏靠的是哪两件事
CC Switch 把「不被写坏」拆成两条互不重叠的路径：JSON/TOML 文件走 config.rs 的 atomic_write（临时文件加重命名），SQLite 库不走这条路，而是靠 rusqlite 在线备份 API 加轮换。这篇标出两条路径各自的文件与行号，以及 Windows 侧的特殊分支。
数命令数会数漏：294 个 Tauri 命令与一个 grep 陷阱
cc-switch 的 Tauri 命令到底有多少个？按属性宏严格匹配数出来是 275，把带参数的写法一起算才是 294，差的 19 条全来自 `rename_all = "camelCase"`。这篇给出三条互相独立的计数路径，说清这个陷阱还会在哪些地方原样复现，以及 294 这个数能说明什么、不能说明什么。
启动序列、崩溃日志、轻量模式与托盘：主进程都干了什么
CC Switch 的主进程在窗口出现之前要跑完一长串动作，而这串动作里有两处「必须早于」是靠顺序保证正确性的：旧配置校验早于建库、数据库版本预检早于任何写 schema。这篇把 lib.rs 的启动顺序、panic_hook 的崩溃日志、lightweight 的窗口销毁与重建、托盘的 ID 常量逐个落到文件与行号上，并给出在仓库快照 c39c903 里自己回查这些行号的办法，同时框清楚哪几个文件我们只读了常量与签名、主体并没有读完。
本地代理、熔断与故障转移
这是全仓最硬的一块。一条请求经过的完整管线、熔断器三状态与四个阈值（代码里同时存在 4 和 5 两个默认值）、故障转移怎么挑下一家、三个 thinking 整流器各修什么，以及文档说 Stream Check 会发真实请求而代码注释明写只探 base_url 可达性的那三处口径差。
本地代理模式做什么：一条请求经过的完整管线
CC Switch 的本地代理不是把请求原样转出去。这篇按源码顺序把一条请求走过的每一站拆开：TCP 层为什么要在 hyper 解析前 peek 8192 字节、25 条路由为什么一个能力挂四个路径、请求体被加工过哪几道、响应回程怎么解压与计时、用量最后落在哪张表，并给出可自己复现的核查路径。
CC Switch 熔断器：三个状态、四个阈值，以及代码里同时存在的 4 和 5
cc-switch 的代理层用一个三状态熔断器决定某个供应商还要不要继续被打。这篇把 Closed / Open / HalfOpen 的五条转移边钉到具体行号上，并摊开同一个 failure_threshold 在代码默认、路由兜底、列级 DEFAULT、Claude seed 四层各不相同的取值。
故障转移怎么挑下一家：候选队列与「忽略当前供应商」
CC Switch 的本地代理开启故障转移后，选下一家的依据不是「当前供应商失败了再找备胎」，而是完全按故障转移队列从头走一遍，当前供应商本身不参与起点判定。这篇把 provider_router.rs 的两条互斥分支、熔断器被问两次的不同语义、尝试次数上限与切换落盘的四道闸门逐行标出来，并给出可自行复现的核查路径。
格式转换层落在哪：三套协议适配器的位置与边界
CC Switch 的本地代理要同时伺候八个 AI CLI，但适配器只有 Claude、Codex、Gemini 三套实现。这篇把「协议转换」这件事在代理管线里拆成五段，指出真正调用适配器的那一行、它是按供应商而不是按工具开关的、以及三个 transform 大文件里我们没读到的部分，给出你自己就能跑一遍的核查动作。
三个 thinking 整流器分别在修什么：两个是事后补救，一个是事前改写
CC Switch 的 proxy 下三个带 thinking 的模块常被当成同一件事的三个档位。实际上两个 rectifier 靠上游错误文本触发、属事后补救，optimizer 是请求前改写、默认关闭且只对 Bedrock 生效。本文把三者的触发条件、改写动作与默认开关落到文件行号上。
文档说发真实请求，代码只探连通性：Stream Check 的三处口径差
CC Switch 的模型检查（Stream Check）在用户手册与源码里是两件不同的事：手册说发真实 API 请求验模型与 Key，代码模块自述只探 base_url 可达性，默认超时与重试次数两边也各写各的，熔断恢复归谁管更是相反。这篇把三处差异的文件与行号标出来，并给出你自己核一遍的动作。
测速的超时钳制：2 / 8 / 30 秒这三个数是怎么用的
CC Switch 的端点测速在源码里写死了三个常量：最小 2 秒、默认 8 秒、最大 30 秒。它们不是三档可选值，而是一个用 clamp 夹住的区间。这篇把三个常量所在的行、钳制发生的位置、以及「一次测速其实发两次请求」这件事讲清楚，并说明它们和代理转发的那套超时、和连通性检查的 8 秒是三套互不相干的配置。
27 个日志错误码与错误到 HTTP 状态的映射表
CC Switch 本地代理有两套互不重合的错误坐标系：`log_codes.rs` 里 27 个日志错误码打在日志文本里，`error_mapper.rs` 把内部错误折成十来个 HTTP 状态码返给客户端。这篇把两张表都摊开，说清为什么好几种完全不同的失败在客户端看来都是同一个 503，以及排查时该从哪一头往回查。
MCP / Prompts / Skills / 会话 / Deep Link
一个面板管多个应用的 MCP，难点全在各家配置文件路径与格式不一样；Prompts 那三份跨应用文件的同步与回填保护；Skills 装成软链还是复制的差别；以及 ccswitch:// 这个自定义协议能一键导入哪四类东西、解析器的边界在哪。
一个面板管多个应用的 MCP：各自配置文件路径与格式差异
CC Switch 的统一 MCP 面板把一条服务器条目投影到多个 CLI 的本地配置里，但落盘的文件路径、承载键与字段写法各不相同。本文按源码行号梳理六个应用各自写到哪个文件、哪个键、要做哪些字段改名与类型换算，并指出往返转换里不守恒的那一处。
双向同步与「应用没装就跳过」：CC Switch 里 MCP 同步的实际行为
在 CC Switch 的 MCP 面板里勾一个应用，落盘时到底发生了什么？这篇按 src-tauri/src/mcp/ 与 services/mcp.rs 的源码，拆开 should_sync_*_mcp() 守卫、DB→live 与 live→DB 两个方向、取消勾选时的反向删除，以及导入的容错口径。
MCP 配置校验拦住了哪些写法
CC Switch 里名叫 validation.rs 的那个文件只有 69 行、两个公开函数、四条规则，一个单测都没有。真正会拒掉你那份 MCP 配置的判断分散在深链层、转换层和写入层。这篇把四层各自拦什么、报什么话、落在哪个文件的哪一行标出来，并给出可以自己复现的核查动作。
`CLAUDE.md` / `AGENTS.md` / `GEMINI.md`：三份文件的同步与回填保护
CC Switch 的 Prompts 功能把提示词写进各个 CLI 的真实配置文件。这篇按源码讲清文件名映射落在哪一行、切换时的回填保护把 live 文件内容存到了哪、全部禁用为什么会把文件写成空串，以及手动导入与首次自动导入的 enabled 默认值为何相反，并给出可自己复现的核查路径。
Skills 装成软链还是复制：两种策略的差别与 skill-backups
CC Switch 装 Skill 时，用户手册第 100 行写的是「复制到本地」，而代码里默认的同步方式是 Auto——优先软链、失败才复制。这篇把 SyncMethod 三个取值和 Auto 分支的判断顺序逐条读一遍，讲清那个最容易被忽略的前置条件，再把复制路径的临时目录加 rename、拒绝同步的 SKILL.md 闸门，以及卸载前自动备份的 skill-backups 目录命名、保留数量与恢复校验一并标到具体行号上，最后给出你可以自己复现的四步核查路径。
会话管理器能读哪些来源，读到的又是什么
CC Switch 的 Session Manager 在代码里并发扫七个来源，用户手册的表只有六行；更要紧的是「能读到」不等于「能恢复」——七个来源里两个的 resume 命令是 None，而拉起终端的入口在非 macOS 上直接返回错误。本文按源码行号讲清七个根目录、两条读取分支与删除的路径校验。
`ccswitch://` 一键导入：四类载荷与解析器的边界
CC Switch 的 ccswitch:// 深链只有一条固定骨架，但 provider / prompt / mcp / skill 四类载荷的参数契约互不相同。这篇把解析器每一道校验落到源码行号上，说清哪些参数要 Base64、用户手册与代码的四处口径差在哪，并给出你自己复核的方法。
用量、定价与云同步
用量数字有两条来源——代理请求日志和本地会话文件，口径不同结论就不同。这一组还包括模型定价表的三层来源与本地覆盖、用量脚本的模板类型与沙箱、S3 与 WebDAV 两条同步路线，以及切了供应商还是走老地址时环境变量冲突检查在查什么。
7 种用量脚本模板与那个 QuickJS 沙箱
CC Switch 的用量查询脚本在代码里有 7 种模板类型，用户手册第 2.5 节却写「三种预设模板」。这篇标出两处的确切位置，再把执行侧那个 QuickJS 沙箱拆开看：5 秒超时、16 MiB 内存、256 KiB 栈这三道限额是防谁的，以及为什么一个查余额的小脚本值得上沙箱。
模型定价表的三层来源与本地覆盖
CC Switch 算出来的那个花费数字，价格是从哪查到的？内置种子 189 条、修价表 34 条、本地覆盖文件三层各管一段，而最反直觉的一处是本地文件刻意不存全量。本文标出每一层的文件与行号，说清 INSERT OR IGNORE 为什么逼出第二张表，并给出可自行复现的核查动作。
切了供应商还是走老地址：CC Switch 的环境变量冲突检查在查什么
在 CC Switch 里切了供应商，命令行工具却像没变一样，常见嫌疑之一是系统环境变量。本文按 cc-switch 源码摊开冲突检查的关键词表、前缀与精确两种匹配语义、Windows 与非 Windows 各自扫哪些位置、删除前的强制备份规则，并给出可自行核对的判定动作与两处文档差异。
用量数字从哪来：代理请求日志 vs 本地会话文件
CC Switch 的用量统计有两条数据来源——本地代理记下的请求，和从各个 CLI 的会话文件里解析出来的记录。两者写进同一张表，靠一列 data_source 区分，靠 token 数四元组加十分钟时间窗去重。这篇把表名、列名、六个取值、五个解析器读的路径和去重条件逐个落到源码行上，并给出你自己的核查动作。
云同步两条路线：共享协议层下的 S3 与 WebDAV
CC Switch 的云同步看起来是 S3 和 WebDAV 两套功能，源码里其实是一层共享协议加两个传输层。这篇标出协议常量、产物集合、上传与落地顺序，说清自动同步的真实触发条件是表变更而不是按间隔、并且只做上传不自动下载，也标出用户手册与代码对不上的那两处，最后给出你自己就能跑一遍的三条核查动作。
想把 Claude Code、Codex 这些工具真正用进日常开发？
从工具配置到工程化落地，站内有成体系的 AI 编程教程。