CC Switch 发布说明里的数字不能直接当事实用

打开 CC Switch v3.20.1 的中文发布说明，第 56 行是一句很像数据的话：

更新规模：26 commits | 66 files changed | +7,474 / -1,000 lines

如果你顺手在仓库里数一遍，会得到另一组数字：

git log --oneline v3.20.0..v3.20.1 | wc -l        # 28
git diff --shortstat v3.20.0 v3.20.1              # 74 files changed, 8373 insertions(+), 1004 deletions(-)

28 不是 26，74 不是 66。第一反应通常是「文档写错了」，但这次不是。把这类差异查清楚，比记住哪个数字对更有用——因为同一份发布说明里，还躺着另外两类性质完全不同的数字，其中一类你永远也验不了。

这篇文章的依据

下面所有数字都来自对 farion1231/cc-switch 仓库快照 3217f725（仓库内版本号 3.20.1）的静态阅读，核对日 2026-08-31，对比基线是 v3.19.2。所有 git 统计都在本地克隆里跑，命令原样列出，你可以用同一条命令重算。我们只读源码和文档，没有编译、没有运行、也没有安装过这个桌面应用，因此本文不涉及任何界面、操作或速度层面的描述。

第一类：口径差

先把 v3.20.1 那组数字对上。文档数的不是「tag 到 tag」，而是「上一个 tag 到本次发版收尾那一串提交之前」——也就是把发版收尾的 release / changelog 提交排除在外（v3.20.1 是两个，v3.20.0 是三个）：

git log --oneline v3.20.0..9485cf2f~1 | wc -l        # 26
git diff --shortstat v3.20.0 9485cf2f~1             # 66 files changed, 7474 insertions(+), 1000 deletions(-)
git diff --name-only v3.20.0 9485cf2f~1 | wc -l     # 66

四个数字全部严丝合缝。9485cf2f 是 v3.20.1 的 chore(release) 提交，它后面还跟着一个把发布说明本身写进仓库的 docs(release) 提交（就是快照 3217f725）。

同样的口径拿去验 v3.20.0。它的发布说明第 60 行写「69 commits | 284 files changed | +53,108 / -6,678 lines」，而按 tag 区间数出来是 72 个提交、291 个文件、+54,385 / −6,682。换成文档口径：

git log --oneline v3.19.2..af31a87b~1 | wc -l       # 69
git diff --shortstat v3.19.2 af31a87b~1            # 284 files changed, 53108 insertions(+), 6678 deletions(-)

又是四个数字全对上。被排除掉的三个提交分别是 0b5da510（写入 v3.20.0 发布说明）、18ca2da0（v3.20.0 的发版提交）和 af31a87b（起草 CHANGELOG 里的未发布小节）。

两版用的是同一套口径，说明这不是偶然，是这个项目稳定的统计方式。 它的含义也很好理解：一份发布说明在统计「这一版改了多少」时，数的是内容提交，不包含把这份说明自己写进仓库的那一次提交——它在描述一个还不包含它自己的范围。

顺带说一句这个区间还有多少种数法。同样是「v3.19.2 到 v3.20.1」这一句话，取值就有好几个：

口径	命令	提交数
tag 到 tag	git log --oneline v3.19.2..v3.20.1	100
v3.19.2 到 v3.20.0	git log --oneline v3.19.2..v3.20.0	72
v3.20.0 到 v3.20.1	git log --oneline v3.20.0..v3.20.1	28
文档口径（排除发版收尾提交）	见上	69 / 26

还有一个更隐蔽的坑：tag v3.19.2 指向的提交是 43eaf073，但如果你在 2026-08-10 前后随手 clone 一份代码留作「上一版」，HEAD 很可能停在 c39c9032——它比 tag 晚了两个提交。以它为起点数到 v3.20.1，得到的是 98 而不是 100。所以引用「两个版本之间 N 条提交」时，N 本身没有意义，带上口径才有。

第二类：验不了的数字

v3.20.1 发布说明第 19 行有这么一条：Claude 会话日志改为字节游标增量扫描，12 MB 的活跃会话文件从整读 6.04 秒降到增量 9.3 毫秒。性能一节里还有一条（第 130 行）：1,017 个会话文件（409 MB）的冻结快照回放，产出与旧扫描器逐位一致的汇总。

这两条读起来比「26 commits」更有说服力——精确到小数点后两位，还带样本规模。但它们在仓库里的处境和上一类完全不同：

grep -rln "6\.04" --include=*.rs --include=*.md --include=*.ts --include=*.tsx .

命中的只有 CHANGELOG.md、三语发布说明 docs/release-notes/v3.20.1-{en,ja,zh}.md，以及 src/icons/extracted/index.ts——最后这个是无关的 SVG 路径数据里恰好含有 6.04 这个字串。src-tauri/ 下没有任何 .rs 文件含这个数字。

再往下查：src-tauri/ 下没有 benches/ 目录，src-tauri/Cargo.toml 里既没有 [[bench]] 段也没有 criterion 依赖（grep -n "bench\|criterion" src-tauri/Cargo.toml 无输出）。那个 1,017 文件 / 409 MB 的回放快照同理，仓库里找不到对应的夹具或脚本。

这两个数字来自作者本机的一次性测量，记录在 bcee61be 这个提交的说明里，文档如实转述了它。这不是造假，但从仓库出发无法验证，也无法在下一个版本用同一口径重测一遍——没有 bench，就没有可比的基线。所以引用它的正确写法是「这次改动自带的基准记录是这个数」，而不能把它当成一条无条件成立的性能结论，更不能推成「快了 N 倍，你的机器也会这样」。

顺便说清楚这条改动本身是可查的：旧实现用行号游标，每轮从字节 0 一路读到文件尾（v3.19.2 时是这样）；v3.20.1 改成字节游标后，SyncCursor 多了 last_byte_offset 与 last_tail_fingerprint 两个可空字段，定义在 src-tauri/src/services/session_usage.rs:65-74。机制可以从源码读出来，性能倍数不能。

第三类：会过期的数字

v3.20.0 的发布说明第 238 行写「schema 从 v16 迁移到 v17」。这句话在它发布的那天是对的。但如果你在 v3.20.1 的快照上照抄它，就会写错——src-tauri/src/database/mod.rs:56 现在是：

pub(crate) const SCHEMA_VERSION: i32 = 18;

原因是 v3.20.1 又叠了一次迁移 migrate_v17_to_v18（src-tauri/src/database/schema.rs:1588），给 session_log_sync 表补上了前面那两个可空列。也就是说，v3.20.0 的发布说明写的是 v16→v17，到 v3.20.1 快照，代码里的 SCHEMA_VERSION 已经是 18。

这类数字的特点是：它绑定的是「发布那一刻」，不是「仓库现在」。 发布说明是一份历史文档，它不会因为后面又改了而自动更新。翻旧版发布说明找参数，务必回代码确认一次当前值。

这里还有一个纯属巧合的雷。src-tauri/src/database/schema.rs:299 有一条注释是「18. Session Log Sync 表（会话日志同步状态）」——这个 18 是建表顺序的序号（前面是 17.，后面 schema.rs:339 是「19. Profiles 表」），跟 schema 版本号 18 数值撞车纯属偶然。版本号只有 database/mod.rs:56 那一处。看到数字先看它在什么上下文里，别急着串起来。

一个反面参照：总量行数

git diff --shortstat v3.19.2 v3.20.1 会告诉你 309 个文件、+62,517 / −7,445。这个数字口径清晰、随时可复算，属于第一类，但它同样不能直接拿来用——里面含 Cargo.lock、pnpm-lock.yaml 这类生成文件，以及 src/icons/extracted/index.ts 这种图标数据文件（这两版里被 4 个提交碰过）。把它当成「有人手写了六万行代码」是误读。

口径可复现，和数字含义正确，是两件事。

同一份文档里也有一验就中的数字

不要把结论推到「发布说明不可信」。v3.20.1 致谢段第 208 行写：本版 26 个提交里有 8 个来自 5 位外部贡献者。用同一口径数作者：

git log --format='%an' v3.20.0..9485cf2f~1 | sort | uniq -c | sort -rn

维护者一人 18 条，26 − 18 = 8；余下的作者去重恰好 5 位。再往前一步，这 26 个提交标题里出现的 issue / PR 编号去重后也是 8 个，与 8 个外部提交一一对应。

可复现的数字和不可复现的数字，就写在同一份文件里，中间只隔了几十行。 分辨它们靠的不是对项目的信任程度，而是三个问题。

判断依据

问题	能验	验不了
这个数字的输入是不是全在仓库里？	提交数、文件数、增删行数、作者分布	耗时、内存、样本回放规模
有没有一条命令能把它重算出来？	git log / git diff / grep 可复算	需要作者本机的数据集和运行环境
它绑定的是版本还是快照？	历史版本的统计（发布后不再变）	参数、版本号、条目数（下个版本就变）

对第一类，你要做的是问清口径，而不是质疑数字；对第二类，转述时必须保留出处，写成「该改动自带的基准记录」；对第三类，翻旧文档拿到的任何参数值，都要回当前代码核一次。

这三条不只对这一个项目有效，但也别把它当成放之四海的方法论——它是从这份发布说明的具体行号里读出来的，你换一个项目，得重新做一遍这个拆分。

---

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