CC Switch 多 CLI 配置管理
c39c903（版本 3.19.2），新一批核对日 2026-08-31、对应 3217f725（版本 3.20.1）。每篇正文都写明了自己依据的是哪一个，涉及两版差异处均带版本限定。
本专题共 90 篇。内容依据
官方仓库
的 README、docs/ 下的用户手册与发布说明、src/config/ 的预设定义
与 src-tauri/src/ 的后端源码整理。
文中出现的阈值与默认值均为源码中的默认配置，
不构成对实际运行结果的保证；该项目仍在快速迭代，请以仓库最新内容为准。
CC Switch 是什么：一个桌面应用管住多个 AI 客户端的配置
CC Switch 不是挡在你和模型之间的常驻中间层，而是一个替你改写本机 CLI 配置文件的桌面应用，数据落在一份 SQLite 里。这篇从仓库源码与文档口径出发，说清它管的是哪一层、为什么「总有一个供应商删不掉」是设计推论、切换后哪些工具要重启，以及它把哪些敏感数据放在了你本机。
认识与安装
README 自称支持八个工具而用户手册的表只列七个，这类口径差在这个仓库里不止一处（这一组读的是 v3.19.2 快照；到 v3.20.1 代码里已经是九个，而 README 与手册两处都还没跟上，差距反而拉大了）。这一组还包括三个平台各自的安装产物、~/.cc-switch/ 下那一个库两种备份的落盘结构，以及 Linux 上点不动、缩放黑屏时的那个逃生环境变量。
CC Switch 支持哪些 AI CLI：README 说八个、手册只列七个
CC Switch 到底管几个 AI CLI 工具？README 四处写「八个」，用户手册的三张清单都只有七个，而 package.json 与 Cargo.toml 的 description 只写了三个。这篇把三处口径的文件与行号标出来，给出可自己复核的比对动作，并说清为什么查「我的工具支不支持」不能只看标题行。
CC Switch 安装：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、用户手册与代码对这个数的写法并不一致。
CC Switch 在 Linux 上点不动、缩放黑屏：那个逃生环境变量
CC Switch 在 Wayland + NVIDIA 下内容区点不动、缩放黑屏，README FAQ 的处置是环境变量 CC_SWITCH_GDK_BACKEND。本文对读 README 与 main.rs 的 Linux 分支，讲清它为何不叫 GDK_BACKEND、两个取值各对什么环境、怎么判定与验证。
CC Switch 的版本门槛：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 条——差异从哪来、怎么自己数一遍，是这一组的开场（448 是 v3.19.2 的实测值；同一条命令在 v3.20.1 上数出来是 537，条数本身会随版本快速变化，重点是那个可复现的口径）。往下是预设的字段全集、category 同时决定 UI 分组和路由徽章、三种托管 OAuth 为什么必须开路由，以及切换之后插件配置为什么会不见。
CC Switch 有多少条预设：README 说 50+，我们数出 448 条
CC Switch 的预设到底有多少条？README 三处写「50+」，用户手册的表格只列几十行，而 src/config/ 下八个应用预设数组加起来是 448 条。这篇把三层口径各自的位置标出来，给出可复现的计数方法与一个会数错的 grep 陷阱，并说清 448 这个数究竟在数什么、不在数什么。
CC Switch 的一条预设长什么样：ProviderPreset 字段全集
CC Switch 的 Claude Code 预设接口 ProviderPreset 定义了 21 个字段，但把 72 条预设逐个字段数一遍会发现：出现次数满格的只有 4 个，另有一半字段只服务于个位数条目。本文给出完整字段表与出现次数，说清每个字段落在哪一层、改它会牵动什么。
CC Switch 的 category 不只是标签：它还决定路由与代理拦截
CC Switch 的预设里有个 category 字段，看着像给界面分组用的标签，实际上它在三个地方被当成开关读：分类筛选、providerNeedsRouting 的第一行早退、以及代理接管下的切换拦截。这篇给出八个取值的语义、八个应用的分类分布，并落到五条没填 category 的预设上，附可自己复现的计数方法。
CC Switch 的「切回官方登录」是怎么实现的
切回官方账号听上去像要写入一份官方配置，但在 CC Switch 的源码里恰恰相反：official 预设是一份刻意留空的配置，切过去之后还要专门擦掉残留的第三方凭据。本文按仓库快照逐处标出这套机制落在哪些文件的哪几行。
CC Switch 的三种托管 OAuth 必须开路由：判定链怎么走
CC Switch 里「这个供应商要不要开路由接管」不是看格式转换决定的。托管 OAuth 那三种 providerType 在判定链里排在 apiFormat 之前，一律返回 true。这篇把 providerNeedsRouting 的六步分支逐行标出位置，说清前端数组与后端方法的覆盖面差异，并给出复核动作。
CC Switch 的 universal 统一供应商：边界在哪
CC Switch 的「统一供应商」把一份网关配置分发给多个 CLI，但它的覆盖面、同步时机与合并方式都有明确边界。本文按 src/config/universalProviderPresets.ts 与 src-tauri 后端源码，逐条讲清它能同步到谁、什么时候才同步、同步时怎么合并，以及关掉一个开关会发生什么。
CC Switch 切换后配置少了一段：通用配置片段怎么回填
在 CC Switch 里切换供应商后，把该供应商保存的配置和切换前的 live 文件逐字比对会发现少了一段。这不是丢失，而是 switch_normal 回填这一步先把可共享改动同步进通用配置片段再剥离写回的结果。本文按源码行号拆开这条路径，给出可复现的四步核查动作并说清哪三个应用不产出通用片段、哪三个应用不走回填。
CC Switch 当前供应商删不掉：手册说能删、后端直接报错
CC Switch 的用户手册写「当前启用的供应商可以删除」，而后端 delete 对非累加模式应用直接返回「无法删除当前正在使用的供应商」，README FAQ 的标题也是「为什么删不掉」。这篇把三处原文的行号标出来，说清这条规则为什么按应用类型分叉，并给出删不掉时的判定与排除动作。
后端架构与 SQLite 存储
Commands → Services → DAO → Database 四层各管什么、所谓 SSOT 到底存了 16 张什么表（v3.19.2 实测值，v3.20.1 已是 17 张、schema 版本走到 18）、迁移编号为什么会跳号、配置不被写坏靠的是原子写入与自动备份这两件事。还有一篇讲怎么数 Tauri 命令数会数漏——grep 写法不对就少 19 个（同口径下 v3.19.2 是 294、v3.20.1 是 304，净增的十个里九个属于新接进来的那个应用）。
CC Switch 后端四层架构：Commands、Services、DAO 与数据库
cc-switch 的 README 把后端画成 Commands → Services → DAO → Database 四层。我们按仓库快照逐目录核对了这四层的文件数、行数与职责边界，并指出「DAO 层其实不是一个对象」「箭头有一处是反向的」这两处容易读错的地方，以及注释目录树与实际模块数对不上的一处差异。
CC Switch 的 SQLite 表：所谓 SSOT 到底存了哪些东西
CC Switch 把「所有数据存在一个 SQLite 库」写进 README 的核心设计，但把 `schema.rs` 的 16 张表读完会发现 SSOT 是分域的：Skills 的事实源在文件系统，MCP 的事实源在表里而 live 文件只是投影，还有五张表在同步时被整个跳过。本文按建表顺序过一遍并给出核查命令。
CC Switch 的数据库迁移：调度机制与跳掉的三个编号
CC Switch 把所有可同步数据放在一个 SQLite 库里，版本一升就要动表结构。这篇讲清 SCHEMA_VERSION 与 PRAGMA user_version 是怎么配合的、逐版本递推的迁移循环长什么样、两道版本拒绝分别拦什么，并把建表注释里 13/14/15 三个跳掉的编号还原成可复现的核查动作。
CC Switch 的配置不被写坏：原子写入与自动备份两件事
CC Switch 把「不被写坏」拆成两条互不重叠的路径：JSON/TOML 文件走 config.rs 的 atomic_write（临时文件加重命名），SQLite 库不走这条路，而是靠 rusqlite 在线备份 API 加轮换。这篇标出两条路径各自的文件与行号，以及 Windows 侧的特殊分支。
CC Switch 有多少个 Tauri 命令：294 到 304 与一个 grep 陷阱
cc-switch 的 Tauri 命令到底有多少个？按属性宏严格匹配数出来是 275，把带参数的写法一起算才是 294，差的 19 条全来自 `rename_all = "camelCase"`。这篇给出三条互相独立的计数路径，说清这个陷阱还会在哪些地方原样复现，以及 294 这个数能说明什么、不能说明什么。
CC Switch 启动时干了什么：启动序列、崩溃日志与托盘
CC Switch 的主进程在窗口出现之前要跑完一长串动作，而这串动作里有两处「必须早于」是靠顺序保证正确性的：旧配置校验早于建库、数据库版本预检早于任何写 schema。这篇把 lib.rs 的启动顺序、panic_hook 的崩溃日志、lightweight 的窗口销毁与重建、托盘的 ID 常量逐个落到文件与行号上，并给出在仓库快照 c39c903 里自己回查这些行号的办法，同时框清楚哪几个文件我们只读了常量与签名、主体并没有读完。
本地代理、熔断与故障转移
这是全仓最硬的一块。一条请求经过的完整管线、熔断器三状态与四个阈值（代码里同时存在 4 和 5 两个默认值）、故障转移怎么挑下一家、三个 thinking 整流器各修什么，以及文档说 Stream Check 会发真实请求而代码注释明写只探 base_url 可达性的那三处口径差。
CC Switch 的本地代理做什么：一条请求经过的完整管线
CC Switch 的本地代理不是把请求原样转出去。这篇按源码顺序把一条请求走过的每一站拆开：TCP 层为什么要在 hyper 解析前 peek 8192 字节、25 条路由为什么一个能力挂四个路径、请求体被加工过哪几道、响应回程怎么解压与计时、用量最后落在哪张表，并给出可自己复现的核查路径。
CC Switch 的熔断器：三个状态、四个阈值与那个 4 和 5
cc-switch 的代理层用一个三状态熔断器决定某个供应商还要不要继续被打。这篇把 Closed / Open / HalfOpen 的五条转移边钉到具体行号上，并摊开同一个 failure_threshold 在代码默认、路由兜底、列级 DEFAULT、Claude seed 四层各不相同的取值。
CC Switch 的故障转移：候选队列怎么挑下一家供应商
CC Switch 的本地代理开启故障转移后，选下一家的依据不是「当前供应商失败了再找备胎」，而是完全按故障转移队列从头走一遍，当前供应商本身不参与起点判定。这篇把 provider_router.rs 的两条互斥分支、熔断器被问两次的不同语义、尝试次数上限与切换落盘的四道闸门逐行标出来，并给出可自行复现的核查路径。
CC Switch 的格式转换层：三套协议适配器的位置与边界
CC Switch 的本地代理要同时伺候八个 AI CLI，但适配器只有 Claude、Codex、Gemini 三套实现。这篇把「协议转换」这件事在代理管线里拆成五段，指出真正调用适配器的那一行、它是按供应商而不是按工具开关的、以及三个 transform 大文件里我们没读到的部分，给出你自己就能跑一遍的核查动作。
CC Switch 的三个 thinking 整流器分别在修什么
CC Switch 的 proxy 下三个带 thinking 的模块常被当成同一件事的三个档位。实际上两个 rectifier 靠上游错误文本触发、属事后补救，optimizer 是请求前改写、默认关闭且只对 Bedrock 生效。本文把三者的触发条件、改写动作与默认开关落到文件行号上。
CC Switch 的 Stream Check：文档说发真实请求，代码只探连通
CC Switch 的模型检查（Stream Check）在用户手册与源码里是两件不同的事：手册说发真实 API 请求验模型与 Key，代码模块自述只探 base_url 可达性，默认超时与重试次数两边也各写各的，熔断恢复归谁管更是相反。这篇把三处差异的文件与行号标出来，并给出你自己核一遍的动作。
CC Switch 的测速超时：2 / 8 / 30 秒这三个数怎么用
CC Switch 的端点测速在源码里写死了三个常量：最小 2 秒、默认 8 秒、最大 30 秒。它们不是三档可选值，而是一个用 clamp 夹住的区间。这篇把三个常量所在的行、钳制发生的位置、以及「一次测速其实发两次请求」这件事讲清楚，并说明它们和代理转发的那套超时、和连通性检查的 8 秒是三套互不相干的配置。
CC Switch 的 27 个日志错误码与 HTTP 状态映射表
CC Switch 本地代理有两套互不重合的错误坐标系：`log_codes.rs` 里 27 个日志错误码打在日志文本里，`error_mapper.rs` 把内部错误折成十来个 HTTP 状态码返给客户端。这篇把两张表都摊开，说清为什么好几种完全不同的失败在客户端看来都是同一个 503，以及排查时该从哪一头往回查。
MCP / Prompts / Skills / 会话 / Deep Link
一个面板管多个应用的 MCP，难点全在各家配置文件路径与格式不一样；Prompts 那三份跨应用文件的同步与回填保护；Skills 装成软链还是复制的差别；以及 ccswitch:// 这个自定义协议能一键导入哪四类东西、解析器的边界在哪。
CC Switch 用一个面板管多个应用的 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 两个方向、取消勾选时的反向删除，以及导入的容错口径。
CC Switch 的 MCP 配置校验拦住了哪些写法
CC Switch 里名叫 validation.rs 的那个文件只有 69 行、两个公开函数、四条规则，一个单测都没有。真正会拒掉你那份 MCP 配置的判断分散在深链层、转换层和写入层。这篇把四层各自拦什么、报什么话、落在哪个文件的哪一行标出来，并给出可以自己复现的核查动作。
CC Switch 同步 CLAUDE.md 等三份文件：回填保护怎么做
CC Switch 的 Prompts 功能把提示词写进各个 CLI 的真实配置文件。这篇按源码讲清文件名映射落在哪一行、切换时的回填保护把 live 文件内容存到了哪、全部禁用为什么会把文件写成空串，以及手动导入与首次自动导入的 enabled 默认值为何相反，并给出可自己复现的核查路径。
CC Switch 装 Skills 是软链还是复制：两种策略的差别
CC Switch 装 Skill 时，用户手册第 100 行写的是「复制到本地」，而代码里默认的同步方式是 Auto——优先软链、失败才复制。这篇把 SyncMethod 三个取值和 Auto 分支的判断顺序逐条读一遍，讲清那个最容易被忽略的前置条件，再把复制路径的临时目录加 rename、拒绝同步的 SKILL.md 闸门，以及卸载前自动备份的 skill-backups 目录命名、保留数量与恢复校验一并标到具体行号上，最后给出你可以自己复现的四步核查路径。
CC Switch 的会话管理器能读哪些来源，读到的是什么
CC Switch 的 Session Manager 在代码里并发扫七个来源，用户手册的表只有六行；更要紧的是「能读到」不等于「能恢复」——七个来源里两个的 resume 命令是 None，而拉起终端的入口在非 macOS 上直接返回错误。本文按源码行号讲清七个根目录、两条读取分支与删除的路径校验。
CC Switch 的 ccswitch:// 一键导入：四类载荷与解析边界
CC Switch 的 ccswitch:// 深链只有一条固定骨架，但 provider / prompt / mcp / skill 四类载荷的参数契约互不相同。这篇把解析器每一道校验落到源码行号上，说清哪些参数要 Base64、用户手册与代码的四处口径差在哪，并给出你自己复核的方法。
用量、定价与云同步
用量数字有两条来源——代理请求日志和本地会话文件，口径不同结论就不同。这一组还包括模型定价表的三层来源与本地覆盖、用量脚本的模板类型与沙箱、S3 与 WebDAV 两条同步路线，以及切了供应商还是走老地址时环境变量冲突检查在查什么。
CC Switch 的 7 种用量脚本模板与那个 QuickJS 沙箱
CC Switch 的用量查询脚本在代码里有 7 种模板类型，用户手册第 2.5 节却写「三种预设模板」。这篇标出两处的确切位置，再把执行侧那个 QuickJS 沙箱拆开看：5 秒超时、16 MiB 内存、256 KiB 栈这三道限额是防谁的，以及为什么一个查余额的小脚本值得上沙箱。
CC Switch 的模型定价表：三层来源与本地覆盖
CC Switch 算出来的那个花费数字，价格是从哪查到的？内置种子 189 条、修价表 34 条、本地覆盖文件三层各管一段，而最反直觉的一处是本地文件刻意不存全量。本文标出每一层的文件与行号，说清 INSERT OR IGNORE 为什么逼出第二张表，并给出可自行复现的核查动作。
CC Switch 的用量数字从哪来：代理日志还是本地会话文件
CC Switch 的用量统计有两条数据来源——本地代理记下的请求，和从各个 CLI 的会话文件里解析出来的记录。两者写进同一张表，靠一列 data_source 区分，靠 token 数四元组加十分钟时间窗去重。这篇把表名、列名、六个取值、五个解析器读的路径和去重条件逐个落到源码行上，并给出你自己的核查动作。
CC Switch 的云同步两条路线：S3 与 WebDAV
CC Switch 的云同步看起来是 S3 和 WebDAV 两套功能，源码里其实是一层共享协议加两个传输层。这篇标出协议常量、产物集合、上传与落地顺序，说清自动同步的真实触发条件是表变更而不是按间隔、并且只做上传不自动下载，也标出用户手册与代码对不上的那两处，最后给出你自己就能跑一遍的三条核查动作。
CC Switch 切了供应商还走老地址：环境变量冲突检查
在 CC Switch 里切了供应商，命令行工具却像没变一样，常见嫌疑之一是系统环境变量。本文按 cc-switch 源码摊开冲突检查的关键词表、前缀与精确两种匹配语义、Windows 与非 Windows 各自扫哪些位置、删除前的强制备份规则，并给出可自行核对的判定动作与两处文档差异。
前端与界面层：面板、表单与状态
这一组走的是 src/ 那一侧。页面切换只靠一个联合类型加一串 case，没有路由库；有两个视图写了 case 分支却没有任何入口，唯一到达路径是 localStorage。还有预设怎么用四个正交开关决定表单长什么样、一个主按钮在不同应用下代表三种完全不同的动作、五个功能面板共用的那副骨架，以及搜索索引为什么要把凭据字段排除在外。
CC Switch 的页面切换：一个联合类型管住十几个视图
CC Switch 没有装任何路由库，整个应用的页面切换靠一个字符串联合类型、一份手抄的运行时清单和一个 switch 完成。本文顺着 src/App.tsx 的源码讲清这套结构怎么运转、把状态记在哪、非法值怎么兜底，以及想新增一个视图要动哪几处。
CC Switch 里有两个页面没有任何入口
在 v3.20.1 的 App.tsx 里，agents 与 universal 两个视图凑齐了类型成员、运行时清单、渲染分支和顶栏标题，唯独缺一处把它们传给 setCurrentView 的调用。本文给出行号与复核命令，说明这两个视图唯一的到达路径来自哪个浏览器存储键，并对照 v3.19.2 确认它不是新引入的。
CC Switch 怎么防首帧白闪：内联脚本与 CSP 哈希
拆开 CC Switch v3.20.1 防首屏闪烁的做法——index.html 第 7 行的内联主题脚本、tauri.conf.json 的 CSP 白名单为什么多一串 SHA-256、Windows 侧 on_page_load 延后显示窗口的钩子、React 起来后 ThemeProvider 如何接管，并给出哈希复算方法。
CC Switch 启动失败时该退出还是自救：两套渲染树
桌面应用启动期出错，是直接退出还是降级渲染一个恢复界面？CC Switch v3.20.1 的 main.tsx 把两种收场都写进了同一个文件，并且给恢复分支刻意砍掉了两层 Provider。本文按行号拆开这条分岔的判据、依赖边界与三档处置。
CC Switch 的预设怎么决定表单长什么样：四个开关
同一个供应商表单，选不同预设时渲染出来的输入框集合完全不同。本文按 v3.20.1 源码拆开这套机制：category、templateValues、providerType、apiFormat 四条互不干涉的判定路径分别控住哪几块，以及「没渲染的字段保存时也不写进 meta」是怎么逐个 case 兑现的。
一个按钮四种意思：CC Switch 的供应商主按钮
CC Switch 的供应商操作区只有一个主按钮，但它在不同被托管应用下分别代表切换、加入原生配置、加入故障转移队列三种完全不同的动作。本文按 v3.20.1 快照拆开 ProviderActions.tsx 的状态机，讲清优先级链、缺回调时的语义合并，以及禁用按钮为什么解释不了自己。
CC Switch 的共享凭据文件没身份标记会怎样
一个「model not found」的报错，倒推回去落在 ~/.codex/auth.json 只有一个凭据槽位、槽位上没写归属这件事。本文顺着 v3.20.1 的三条修复，讲清共享可变状态缺少所有权标记会长出什么形状的问题，以及 reconcileCodexLiveAuth 用什么办法绕开它。
CC Switch 五个功能面板共用一副骨架
skills、prompts、mcp、proxy、universal 五个目录管的事完全不搭界，代码却不是各写各的。本文按共享组件、命令式句柄、忙碌态冒泡、写操作串行锁四层，拆开 CC Switch v3.20.1 前端的复用梯度，并解释为什么 proxy 一件共享件都不用、universal 只用一件。
CC Switch 的搜索为什么把凭据字段排除在外
一个本地搜索框要先决定把记录的哪些字段拼成可匹配文本。CC Switch 的 MCP 列表页用显式白名单把 env 与 headers 挡在搜索之外，而同一个仓库的提示词列表页把正文也纳入了搜索。本文从 v3.20.1 的源码逐行讲清这组对照、白名单与黑名单的默认待遇差别，以及这段代码没有承诺的事。
CC Switch 的批量开关为什么必须串行跑
CC Switch 的批量开关没有并发发请求，而是过一个只有三十来行的 runSequentialBulkAction 逐条 await。理由写在代码注释里：多个应用适配器是整文件重写配置，并行写会互相覆盖。本文按文件行号拆开这条约束在工具层、hook 层、面板层各留下了什么痕迹。
CC Switch 的设置页为什么有两套保存语义
同一个设置页里，有的开关改完立刻落盘，有的要等你点保存按钮。这不是随手写出来的差异。本文顺着 SettingsPage.tsx 的即时保存函数读到它的回滚分支，讲清楚为什么这里非回滚不可，落到实现上其实是三份各写各的乐观更新代码，以及这套结构在这一版一行未动。
CC Switch 的环境变量冲突检测：前缀还是精确匹配
CC Switch 会扫描系统里的环境变量并弹出冲突横幅，但「什么算冲突」有一条写死在 Rust 里的判定规则。本文顺着 env_checker.rs 的关键词枚举、单元测试钉死的一组反例，以及前端那份硬编码应用清单，讲清这套检测覆盖到哪里、又从哪里开始失效。
CC Switch 的升级：退出码 0 不等于升级成功
命令返回 0 就报「升级成功」，是一类很常见的误报。CC Switch 升级被管理的 AI CLI 时不认退出码，而是在命令返回后重新读一次版本再判一次，并把「版本没变」与「装上却跑不起来」单独归成软失败。本文按 v3.20.1 的源码行号拆解这套二次判定的写法、它的缓存前提与边界。
CC Switch 的跨年折线图为什么会错位
CC Switch 用量看板的趋势图曾在跨年区间上出现「高亮的点和提示框描述的不是同一天」。根因是拿本地化的 MM/DD 文本当 Recharts 分类键，不同年份的桶撞成同一个值。这篇把 v3.19.2 与 v3.20.1 两版的 UsageTrendChart.tsx 对上，讲清键、刻度、提示为什么必须分家。
CC Switch 用量看板里 N/A 与 0 不是一回事
用量统计里最容易看错的就是空数字。CC Switch 在 v3.20.1 的源码里把「协议不上报」「真的是零」「解析失败」「价目表里没这个模型」拆成四条互不相同的渲染分支，本文逐条落到具体文件与行号，并说明混用两系 API 时它为什么只给口径标注而不给一个合计数。
工程化：封装、测试、翻译与权限
几百个 IPC 调用怎么收进一层薄封装、失败时怎么不抹掉上一次成功的数据、崩溃日志怎么才能不写进 API Key。测试那两篇讲的是一个桌面应用如何在没有桌面的 CI 里测前端；翻译那篇讲的是一套守错了方向的一致性测试——参照系选成英文，导致「代码要的键四种语言全都没有」这类问题根本抓不到。
CC Switch 怎么把几百个 IPC 调用收进一层封装
Tauri 应用里前端调后端靠的是字符串命令名，编译器管不住。CC Switch v3.20.1 把绝大多数 invoke 收进 src/lib/api 一层薄封装，这篇顺着源码讲清楚截断点选在哪、封装体只做哪三件事、哪几处刻意破例，以及那些注册了却在前端搜不到引用的命令该怎么描述。
CC Switch 的 keep-last-good：查询失败不抹掉上次成功值
额度查询一次网络抖动就被判成失败，一律掩盖失败又会让换过 Key 的人一直拿到过期数字。CC Switch v3.20.1 用一个白名单加一个纯决策函数把失败分成两类分别处置。本文按行号拆开这段逻辑，重点讲失败路径为什么也必须回写快照，并把它放回全站的轮询节律里看。
CC Switch 的崩溃日志怎么才能不写进你的 API Key
一个管着本机 API Key 的桌面应用，前端一崩就要写日志，而异常对象里最容易夹带的恰恰是密钥。本文顺着 CC Switch v3.20.1 的 frontendLogger 读它的两层脱敏链、截断护栏、跨引擎栈处理，以及那份把「该留的留下了」也一并锁死的脱敏契约测试。
没有桌面的 CI 里怎么测 CC Switch 的前端
CC Switch 是个 Tauri 桌面应用，但它的前端测试跑在没有窗口、没有 Rust 进程的 CI 容器里。本文顺着 v3.20.1 的 tests/msw/ 目录，讲清楚它把 invoke 翻译成 HTTP 的那一招，以及 MSW、API 层、invoke 层三个截断点各自的收益和代价。
CC Switch 的 i18n 测试守错了方向：参照系是 en 的代价
CC Switch 有一个专门校验多语言完整性的 vitest 用例，三条断言都能通过，但代码里仍有两个键在四种语言中全都没有定义。本文从 localeCoverage.test.ts 的参照系那一行出发，讲清这类测试为什么抓不到「代码要的键 en 也没有」，以及白名单写错一个键名为什么不会让测试变红。
CC Switch 向系统要了哪些权限：capability 白名单逐条对账
权限清单漏掉一条会怎样？不是报错也不是崩溃，而是按钮在、代码在、什么都不发生。本文按 CC Switch v3.20.1 的快照，把 capabilities/default.json 里的每条权限对到前端调用点上，讲清 capability 约束的到底是谁，以及新增的 process:allow-exit 修的是什么。
给 CC Switch 接一个新的 AI CLI，要改多少处
CC Switch 在 v3.20.1 里多托管了一个 AI 编程 CLI。本文沿仓库改动把「接一个新应用」拆成注册表、能力常量、预设数据、表单、命令层、测试夹具、翻译七类改点，逐类给出文件与标识符位置，并指出哪几处是同一件事抄了好几遍、又是哪一处已经对不上。
排查：症状、判定动作与排除项
这一组的每个症状都来自用户手册的实际章节或某个真实修复提交所引的 issue，不是编出来的场景。Windows 启动闪白屏、终端里能跑的 CLI 检测不到、WSL 路径下改不动配置、环境检查永久挂起、恢复提示词后没被管理的文件不见了。每篇都给可执行的判定动作，并且都写了最后一段——什么情况说明不是这个原因。
CC Switch 在 Windows 上启动闪白屏怎么办
桌面应用启动时先闪一下未着色的页面，根因通常不在显卡也不在开机速度，而在「窗口什么时候显示」与「主题什么时候生效」这两件事的先后顺序。本文按 CC Switch v3.20.1 的源码，拆开这条链路的三处改动，给出自查动作，以及哪些现象说明根因不在这里。
终端能跑的 CLI，CC Switch 却检测不到
命令行里明明能跑的 AI CLI，桌面端却报未安装，或者更新完还显示旧版本。根因通常不在检测逻辑，而在这个进程继承到的环境和你登录 shell 的环境不是同一份。本文按 v3.20.1 的源码拆开三种独立成因，给出三种对应的判定动作与验证口径，并说明哪些表现看着像是检测问题、其实要挂版本口径去别处排查。
CC Switch 编辑框显示的密钥不是当前生效的
打开 Codex 供应商的编辑表单，里面填着的密钥可能来自另一张卡，保存一次就固化进数据库。这篇按源码位置拆开成因：共享的 auth.json 没有供应商身份，而表单播种时优先读它。给出判定动作、v3.20.1 的处置写法，以及哪几种情况说明你遇到的其实是别的问题。
CC Switch 恢复提示词后，没被管理的文件不见了
从云端下载或导入备份之后，本地手写的 AGENTS.md、CLAUDE.md 变成了空文件。这不是同步没下全，而是恢复路径上的一次"写空"。本文按源码定位这行代码在哪、怎么判断你遇到的就是它、v3.20.1 改了什么，以及哪五种情况说明根因不在这里。
CC Switch 在 WSL 路径下改不动配置怎么办
把配置目录放在 WSL 的 UNC 路径上时，新建供应商能存、改已有的却一直失败。这个症状在 v3.19.2 上出现，根因是 Windows 原子写换成 ReplaceFileW 之后，rename 回退的触发条件只写了 NotFound。本文按源码给出三条不需要运行程序的判定动作、发布说明给的处置口径、以及可以拿来当自查清单的三条回归测试与两级持续集成门禁，同时写清哪几种看着沾边的症状其实另有根子。
CC Switch 环境检查卡住不动怎么排：子进程挂死的四个原因
CC Switch 的升级预检或工具检查迟迟不结束、又不报错，多半不是网络慢。本文按 v3.20.1 的源码把子进程挂死拆成四个成因——进程组、控制终端、作业控制与超时缺失，先给出分清是哪条环境检查链路的判定动作，再逐件说明对应改动落在哪一行、Windows 侧为什么要单独看，最后列出四种看着像挂死其实并不是的情况。
CC Switch 切到第三方，Codex 仍显示官方账号是不是串账了
切走第三方供应商后客户端仍显示官方账号，是不是把账单记到官方头上了？这篇按 CC Switch v3.20.1 的仓库文档与源码，拆开 auth.json 与 config.toml 的职责分离、代理层那段账号一致性校验的判据与三态设计，并给出逐步的判定动作和「不是这个原因」的排除清单。
CC Switch 报 model not found 该查哪几层
模型 ID 一个字都没抄错，请求却被打回 model not found。本文按 CC Switch v3.20.1 的源码与用户手册，把这类报错拆成共享凭据文件、模型目录指针、模型 ID 清洗三层，逐层给出可执行的判定动作、源码里的处置依据，以及什么情况下说明根因其实不在这里。
CC Switch 删除报错，东西其实已经删掉了
在 CC Switch 里删一条 Skill 备份，收到的是删除失败的提示，可那条备份其实已经不在了。这篇把 UnifiedSkillsPanel 里专门为此写的三重错误处理逐条拆开，标到具体行号上，给出一个不用翻磁盘就能做的判定信号组合，并给出处置与验证的落点，最后列出四种「不是这个原因」的情况。
CC Switch 会话不见了的六种解释
用 CC Switch 管理 Codex 供应商时，历史会话列表突然少了一大截。本文按 v3.20.1 的仓库文档与源码梳理这类症状的六种成因，给出每一种的判定动作、处置方式与验证办法，并指出其中只有一种是真限制、其余五种都是分组标签造成的误解，同时说清判断会话是否真的丢失应该以文件总数为准。
CC Switch 手册说能点，代码里其实没这个入口
CC Switch 的用户手册里描述了一些在 v3.20.1 源码里找不到接线的交互，比如点击请求日志行看详情，照着找会白费时间。这篇把用量看板与会话页几处对不上的地方逐条摆出来，给出一套只靠读文件就能完成的判定动作，并说明哪些情况其实是前置条件没满足、平台分支或双方各缺一块，不该归到文档滞后上。
CC Switch「连续失败三次就熔断」这说法是错的
CC Switch 的用户手册在三个章节给了三套健康徽章说法，其中「连续失败 3 次触发熔断」与它自己给出的失败阈值默认值直接打架。本文按源码把徽章的三条分支、熔断器的三个状态和两条触发路径捋清楚，并给出你自己动手判定的办法。文中行号与默认值均对应 v3.20.1 快照，只静态读源码，不涉及界面观感与运行表现。
CC Switch 点两下就并发跑了两个安装
升级按钮被连点两下，会不会真的并发跑起来两个全局安装？这篇按 CC Switch v3.20.1 的源码，把探测阶段等三个并发窗口、堵住它们的那把入口锁、以及检测到多处安装时的知情确认对话框逐层拆开，并给出「怎么判定是这个原因、处置后怎么验证、哪些情况说明根本不是它」的完整排查链路。
CC Switch 一键导入链接点了没反应怎么排
别人发来一条 ccswitch:// 一键导入链接，点下去毫无动静。本文按「确认框弹没弹」把这个现象切成协议层和载荷层两段，给出各自的判定动作、源码里能查到的处置依据、处置后怎么确认，以及什么情况说明根本不是这个原因；并指出手册在协议注册与必填字段两处都没有回指，读者得自己翻回去比对。
v3.20 版本追更：这两版之间改了什么
v3.19.2 到 v3.20.1 之间有一百个提交、三百多个文件变更。主线是接进第九个受管应用（README 到现在还写着八个）、官方账号多绑不串账、以及一万行代码只为把文档里那句「不支持」删掉。也有反直觉的：只加了一张表，schema 版本却跳了两级。最后一篇讲的是发布说明里的数字为什么不能直接当事实用。
CC Switch 接进第九个受管应用，动了一百多个文件
给一个配置管理工具接入一个新的 AI 编程 CLI，成本到底落在哪里？沿着 v3.19.2 到 v3.20.1 的仓库改动，把这次接入触及的前端组件、数据层、Rust 服务层、命令层、会话管理、数据库与国际化逐层拆开，并记录同一份仓库里三处文档给出三个不同应用数的现状。
CC Switch 首次导入既有配置：哪些碰哪些不碰
以 v3.20.1 快照里的 Pi 接入为例，逐条对照源码讲清 CC Switch 首次启动会导入哪些既有供应商、会回填什么用量、明确声明不动的又是哪几样，顺带拆开 models.json 的三层写保护，看它把哪几类冲突挡在了真正写入之前，以及数据库迁移那一步实际做了什么。
CC Switch 的两种用量来源：会话回读与代理记账
用量看板里同一张表混着两类行——请求真的走过本地网关当场记下的，和事后去读 AI CLI 会话文件补记的。本文从 data_source 这一列出发，讲清两类来源的写入位置、去重账本、覆盖仲裁，以及为什么每新接一个没有本地网关的应用，就得多出一个来源值。
CC Switch 绑多个官方账号，怎么不切一次串一次
v3.20.0 起 Codex 官方卡可以逐张绑定 ChatGPT 账号并共存，随之而来的问题是请求会不会记到别的账号头上。这篇按 v3.20.1 快照，把绑定卡与空官方卡的差别、代理层那段账号一致性校验的判据、官方卡退出故障转移的取舍，逐处落到文件与行号上。
CC Switch 只加一张表，schema 版本却跳两级
v3.20.0 的发布说明写「schema 从 v16 迁到 v17」，但 v3.20.1 的源码里常量已经是 18，而基线建表只多了一张。这篇把三个数字各自的口径、两次迁移分别做了什么、以及「为什么第二次不能补进上一个版本号」的源码注释逐条摊开。
CC Switch 用一万行代码删掉文档里那句「不支持」
CC Switch v3.20.1 里有一次改动，九个文件净增一万行，其中三份路由攻略每份只改两行——改掉的是「GPT 路由下没有网页搜索」这一句。这篇拆开这一万行落在哪、桥只搭在哪条路径上，以及它确立的那条原则：协议翻译层碰到对面表达不了的约束时，为什么选择报错而不是放宽。
CC Switch 把行号游标换成字节游标：什么算增量读
一个「跳过前 N 行」的增量扫描，为什么既没省掉 IO，又会永久丢掉正在写入的那一行。本文顺着 CC Switch v3.20.1 的会话日志扫描改动，逐行对照新旧两版源码，讲清字节游标、尾部指纹与「宁可少算不多算」这条取舍是怎么写进注释里的。
读一百条提交能读出什么：CC Switch 的版本体检
追一个开源项目的升级，不该只读发布说明。这篇用 CC Switch 从 v3.19.2 到 v3.20.1 的提交区间做示范：先把「一百条提交」这个数的口径钉死，说明同一个区间为什么会数出三个不同的值；再按类型、scope、文件、时间四个维度分桶，看清改动压在哪几个面上；最后反过来问哪些模块一行都没动，以及代理层那三块基础设施为什么是升级风险的关键。
CC Switch 发布说明里的数字不能直接当事实用
CC Switch v3.20.1 的发布说明顶部写着「26 commits | 66 files changed」，可你自己 git log 数出来是 28 和 74。这篇把同一份文档里的数字拆成三类：换个口径就能严丝合缝复现的、仓库里连测量脚本都找不到的、以及跟着版本走一年就会过期的，并给出判断依据。
设计取舍与文档治理
这一组不讲功能讲取舍，每一段都能指回具体源码。同一个「应用」概念在这个项目里有六套成员不同的枚举，各自服务不同判定；可逆性被拆成五件套；「不猜」被当成一种功能来实现。还有一篇把文档漂移的三种形态摆在一起——语言数越写越少、安全前提被后来的修复推翻、参数表整体过期。
CC Switch 里「应用」这个概念有六套枚举
在 CC Switch 的前端代码里问「哪些应用支持某个功能」，会得到好几个互不相同的答案。这篇把 appConfig.tsx 与 usage.ts 里那几个应用集合逐个摊开，讲清每一套服务的是哪一层判定，以及为什么把它们合并成一套反而会造出假成员。
CC Switch 文档漂移的三种形态：语言数、安全前提、参数表
同一个仓库里，贡献指南说三种语言、验收清单说四种；安全策略声明的 CSP 已被一次前端修复改掉；代理指南的参数表整表对不上建表默认值。用 CC Switch v3.20.1 快照里的三组实例，讲清文档漂移的三种形态各自长什么样、成因差在哪、分别该用什么动作现场核对。
CC Switch 的可逆性五件套：迁移会话历史怎么做到能退回去
一个第三方工具去改 Codex 自己的会话历史文件，出错就是用户资产受损。CC Switch v3.20.1 用只改一个字段、改前必备份、原子替换、悲观跳过、幂等可重试这五件事把风险压下去，本文逐条落到源码常量、原因码与函数位置上，并说清哪一段是这套设计覆盖不到的。
不猜是一种功能：CC Switch 的自定义配置取舍
配置工具要不要替用户推断模型能力，CC Switch 管理 Pi 的这条路径给了否定答案，写成「预设完整可靠、自定义配置不猜测」的原则。本文顺着 v3.20.1 的需求文档与源码，拆开这条原则落到能力字段、空值语义、表单规则与界面取舍上的具体形态，也说清它的代价落在了谁身上。
CC Switch 把「信任渲染进程」写成可证伪的决定
CC Switch 的 SECURITY.md 把「打包的渲染进程属于信任边界之内」写成一项范围划定决策，附上四条能用搜索命令复核的支撑事实和五条提前写死的失效条件；其中 CSP 那一条，在文档最后一次改动的 18 天后被一个前端修复推翻。本文按 v3.20.1 快照，把这套写法与那处差异逐条落到确切的行号与提交上。
留言讨论
评论发布后会被人工复核，违规内容将被删除。
如果发表没有反应，可以前往联系我们告诉我们。
想把 Claude Code、Codex 这些工具真正用进日常开发？
从工具配置到工程化落地，站内有成体系的 AI 编程教程。