CC Switch 演进全史：从双应用配置切换器到九应用 All-in-One AI CLI 管理平台-平芜编程栈

CC Switch 演进全史：从双应用配置切换器到九应用 All-in-One AI CLI 管理平台

【免费下载链接】cc-switchA cross-platform desktop All-in-One assistant for Claude Code, Codex, OpenCode, OpenClaw, Grok Build & Hermes Agent. Only official website: ccswitch.io项目地址: https://gitcode.com/GitHub_Trending/cc/cc-switch

CC Switch 是一款基于 Tauri 2 的跨平台桌面应用，最初只是一个管理 Claude Code 与 Codex 配置的“切换器”，经过 v3.0.0 起的历次迭代，逐步成长为覆盖 Claude Code、Claude Desktop、Codex、Gemini CLI、OpenCode、OpenClaw、Hermes、Grok Build 与 Pi 共九个受管应用的 All-in-One 管理平台。本文以仓库根目录的 CHANGELOG.md 为骨架，结合 src-tauri/src 与 src/config 下的实现证据，系统梳理该项目的技术架构演进、九大应用的接入方式、本地代理与协议转换体系、用量统计与数据库迁移机制，帮助你快速理解这个仓库“从哪儿来、怎么长成、底层如何工作”。

一、项目定位：管什么、怎么管

CC Switch 的核心职责是让用户在不改手写配置文件的前提下，为多个终端 AI 编程客户端统一管理“接入哪个供应商、走哪条 API”。从 CHANGELOG 看，其能力体系在三年内沿三条主线扩张：

受管应用（managed apps）：从单一 Claude Code 起步，逐版本接入 Codex、Gemini CLI、OpenCode、OpenClaw、Hermes、Claude Desktop、Grok Build 与 Pi，各自拥有独立的配置读写模块。
本地路由（Local Routing，早期称 Local Proxy Takeover）：内置本地代理，接管应用的配置指向后完成跨协议的请求转发、格式转换、自动故障转移与用量记账。
横切面板：统一的 MCP、Skills、Prompts、Session 管理、Usage Dashboard、WebDAV/S3 云同步与项目 Profile 快照。

项目早期仅面向 Claude Code（v1.0.0 提供基础 provider 管理），v2.x 扩展多 provider 配置；v3.0.0 放弃 Electron、以 Tauri 2 完全重写（CHANGELOG.md v3.0.0 条目）；v3.6.0 时官方把定位正式升格为 “Provider Switcher” → “All-in-One AI CLI Management Platform”。截至 v3.20.0，数据库SCHEMA_VERSION已演进到 17（见 src-tauri/src/database/mod.rs），UI 支持中/英/日/繁中四语言（zh、en、ja、zh-TW，见 src/i18n/locales）。

二、版本代际与关键时间线

CHANGELOG 记录了从 v3.0.0 到 v3.20.0 的完整路径，可按技术代际划分为四个阶段。

2.1 Electron 时代（v1.x / v2.x，Tauri 重写之前）

早期版本只有“基础 provider 管理 + Claude Code 集成”与“多 provider 配置管理、快速切换、导入导出、预设模板”。官方将其定义为 v2.x（Electron 版本），此后被 v3.0.0 取代。

2.2 v3.0.0：Tauri 2 重写与数据层奠基

v3.0.0 是分水岭：应用从 Electron 迁移到 Tauri 2.0，按官方变更记录带来约 90% 的体积缩减、启动性能提升与 Rust 后端安全模型；引入显式权限声明、TypeScript strict mode、pnpm typecheck。v3.5.0 增加MCP（Model Context Protocol）管理——首次提供对~/.claude.json中 stdio/http MCP server 的增删改与启停；随后 v3.6.0 加入用量自动刷新、模板系统扩展、目录切换自动同步等能力，并完成 Rust/前端双端的大型重构（AppError统一错误、命令按域拆分、Service 层抽取、RwLock并发优化）。

2.3 v3.7.0 ~ v3.9.x：平台化架构落地

v3.7.0 把 Gemini CLI 作为第三个受管应用接入，同时上线 MCP v3.7 统一架构、Claude Skills 管理系统、Prompts（系统提示词）管理与ccswitch://深链协议——官方在版本说明中明确将其定义为从“Provider Switcher”向“All-in-One AI CLI 管理平台”的战略升级。v3.8.0 将单 JSON 存储升级为SQLite + JSON 双层持久化，引入 schema 版本、事务与 SQL 导入导出（首次启动自动迁移config.json），并加入日语支持。v3.9.0 系列是平台核心：Local API Proxy（基于 Axum）、Per-App Takeover（逐应用接管并自动备份/重定向实时配置）、Auto Failover（熔断器 + 独立故障转移队列 + 健康追踪）。其中 v3.9.1 将默认代理端口从 5000 调整为15721以避免与 macOS AirPlay Receiver 冲突，这一端口沿用至今（src-tauri/src/proxy/http_client.rs 中仍以 15721 为默认回退）。

2.4 v3.10.0 ~ v3.20.0：应用扩张与体系收口

v3.10.x：接入 OpenCode；新增全局代理设置、Thinking Signature Rectifier。
v3.11.x：接入 OpenClaw；发布 Session Manager、独立备份管理面板与 Oh My OpenCode（OMO）集成。
v3.12.x：新增 OpenAI Responses API 双向转换、Bedrock Optimizer、Stream Check 恢复；v3.12.3 支持 GitHub Copilot 反向代理与 macOS 签名公证。
v3.13.0：Lightweight（纯托盘）模式、provider 模型自动获取、配额/余额内联展示、官方账号 seeding。
v3.14.x：Hermes Agent 作为第六个受管应用接入（YAML 配置、MCP/Skills/Session/用量全覆盖）；Gemini Native API 代理。
v3.15.0：Claude Desktop 成为一等管理面；大范围反向代理加固。
v3.16.x：四语言（新增繁中）、模型价格自动同步（models.dev）、S3 云同步、Grok Build 相关 OAuth 前置工作。
v3.17.0：项目 Profiles（profiles表，schema v11→v12）；Codex 官方账号可走代理接管。
v3.18.0：Grok Build 成为第八个受管应用；xAI OAuth Device Code 登录；渲染进程崩溃上报。
v3.19.x：DeepSeek、Volcengine Ark Coding Plan 等切换为原生 Responses 直连并引入“官方厂商模型目录镜像”机制。
v3.20.0：Pi 成为第九个受管应用（schema v16→v17，新增session_usage_dedup账本表）；Codex 多 ChatGPT 账号绑定；WebSearch 桥接。

三、九大受管应用的接入方式差异

从 CHANGELOG 各版本可以归纳出一套清晰的接入模型分类——接管式（takeover）与叠加式（additive），理解这一点是阅读源码的钥匙。

版本	应用	配置载体	接入模型 / 特点
v1.x	Claude Code	`~/.claude/settings.json`、`~/.claude.json`	起步应用；可走本地路由接管
v3.1.0	Codex	`~/.codex/auth.json`+`config.toml`	auth.json 密钥写入 + TOML 段感知编辑
v3.7.0	Gemini CLI	`.env`+`settings.json`	环境变量探测（`GOOGLE_GEMINI_BASE_URL`等）
v3.10.0	OpenCode	`opencode.json`	叠加式：provider 存活以配置中存在为准
v3.11.0	OpenClaw	`openclaw.json`（JSON5 往返编辑）	叠加式：Env/Tools/AgentsDefaults/Workspace 面板
v3.14.0	Hermes	`~/.hermes/config.yaml`	叠加式：`custom_providers:`前缀、四协议
v3.15.0	Claude Desktop	受管 3P profile	专属桌面面 + 代理网关 + 角色化 model mapping
v3.18.0	Grok Build	`~/.grok/config.toml`	复用 Codex Responses 转发路径，独立路由命名空间
v3.20.0	Pi	`~/.pi/agent/models.json`	叠加式：存在即启用，58 个预设，内容修订冲突检测

叠加式的关键规则（v3.20.0 Pi 条目明确）：provider 的启用状态由目标配置文件内是否存在其 key 决定，且多个 provider 可共存；CC Switch 不物化 Pi 内建 provider、不读写其auth.json、不触碰defaultProvider/defaultModel。前端预设定义可对照 src/config/piProviderPresets.ts、src/config/openclawProviderPresets.ts 等文件。

官方账号例外规则：凡是category = official的 provider（OpenAI Official、Claude Official、Google Official、Grok Official 等）都被排除出自动故障转移与可达性探测，原因是“把入站授权重放到另一个账号/端点”既无意义也有风险——该判定在后端以is_codex_official_provider/official_provider_supports_proxy_takeover之类的谓词集中实现（src-tauri/src/codex_config.rs），而非依赖卡片分类标签。

四、本地路由与协议转换体系（源码主线）

4.1 架构与端口

本地代理基于 Axum，默认监听127.0.0.1:15721（listen 地址为localhost时会归一化为127.0.0.1，见 v3.16.2 Fixed）。启用 Local Routing 时，CC Switch 会先把目标应用正在使用的实时配置文件完整备份，再改写其中的base_url/模型 provider 指向本地代理（“takeover”）；停止路由时从备份恢复。v3.16.2 之后恢复流程改为“刷新备份而非覆盖实时文件”，并用PROXY_MANAGED占位符 + 备份/实时占位所有权信号来判断谁拥有 Live 配置，避免热切换与代理启停互相覆盖。代码主线在 src-tauri/src/proxy（66 个文件，含 forwarder、各 provider 适配器、转换器、熔断器、健康检查与媒体净化器）。

4.2 三种上游格式与双向桥

随着 Codex/Grok Build 客户端转向 OpenAI Responses、而 Claude 系列客户端讲 Anthropic Messages，项目逐步实现了完整的跨格式双向转换：

Responses ↔ Anthropic Messages（transform_codex_anthropic.rs、streaming_codex_anthropic.rs）：v3.17.0 引入原生 Anthropic Messages 作为 Codex upstream；v3.19.0 完成 reasoning、tool result、system/developer 角色的无损往返（带版本化 signature 的加密 reasoning 封装）。
Responses → Chat Completions（Codex Chat 路由，v3.16.0 起）：把 Codex 的 Responses 请求转成 Chat，再重建回 Responses 形态，保留reasoning_content、工具调用、previous_response_id跟随请求等。
Anthropic ↔ OpenAI Chat：供 Claude 系客户端走 Chat 型第三方网关。
Gemini Native API（gemini_url.rs、streaming_gemini.rs等，v3.14.0）：直连generateContent，全流式 + schema 转换 + shadow request。

各桥共享一套正交机制：媒体升维（tool-result 图片从工具文本里“提出”并重发为原生媒体，v3.19.0，避免 ~9000 倍 token 膨胀）、prompt cache 断点注入（Anthropic 5 分钟 TTL 标准断点，v3.17.0）、reasoning effort 透传与方言改写（v3.19.1/3.20.0 针对 DeepSeek/StepFun/ModelScope/Novita/Nvidia 等的纠偏）、工具 schema 归一化（缺失/null/union 参数类型一律归为type: object）。这些细节都可在 src-tauri/src/proxy 下对应转换模块中找到测试佐证。

4.3 直连模式与厂商目录镜像

v3.19.1 之后出现一条与“本地转换”相反的收敛路线：当上游本身实现 Responses API 时，DeepSeek、Volcengine Ark Coding Plan、Tencent Hunyuan（TokenHub）等预设改声明openai_responses，让 Codex直连网关、无需本地路由。为保证能力自洽，项目推出“官方厂商模型目录逐字镜像”机制——第一个案例是 src-tauri/src/resources/codex_deepseek_catalog_template.json（目录中的文件由 CHANGELOG v3.19.1 指名），严格限定base_url落在deepseek.com且 profile 为 native-Responses 才生效，避免把厂商能力错误授予聚合商。直连带来的副作用是流量绕过本地代理，Codex 用量改由 session-log 导入记账（归并到单一Codex (Session)源）。

五、Provider 预设、模型映射与定价

5.1 预设生态与分类

每个受管应用都有独立的前端预设模块（如 src/config/claudeProviderPresets.ts、src/config/codexProviderPresets.ts、src/config/codexTemplates.ts 等）。预设带category（official/cn_official/aggregator/third_party等）与可选的endpointCandidates（备选端点，供地址管理器与延迟测试使用）、apiKeyUrl与推广文案。v3.16.0 起选取器默认排序为四层：官方 → prime partner → 赞助商 → 其余按显示名排序。重要限制：预设只对新建 provider 生效，已保存的 provider 保留创建时的配置——这一点在多个版本的 Upgrade notes 反复出现。

5.2 模型映射与 Codex 目录

Claude Code 走角色化映射（ANTHROPIC_MODEL/ANTHROPIC_DEFAULT_HAIKU/SONNET/OPUS_MODEL，v3.16.3 增补 Fable 层）；Claude Desktop 走 route_id 映射；Codex 则通过生成~/.codex/cc-switch-model-catalog.json（相对文件名写入config.toml的model_catalog_json）把 model mapping 表投影为 Codex 能读的目录。v3.20.0 起每个模型行可声明自己的reasoningLevels（8 个标准档 none→ultra 的多选）与默认档，写入 src/config/codexProviderPresets.ts 的 preset 结构并带到 Codex picker；未知取值会被丢弃，防止笔误打到 Codex。

5.3 定价：内置表、models.dev 同步与本地覆盖文件

用量成本在记账时刻以内置model_pricing表冻结（schema.rs 的seed_model_pricing+ensure_model_pricing_seeded幂等播种）。定价有三层来源优先级：内置播种 → models.dev 自动同步（可选，默认关，见 src-tauri/src/services/model_pricing.rs）→ 用户手工覆盖。手工覆盖/删除自 v3.19.0 起记入可读文件~/.cc-switch/model-pricing.json，并以此在数据库重建后复现；删除用 tombstone 实现，不再被重新播种复活。模型 ID 匹配存在严格的归一化规则（剥 vendor 前缀、剥日期后缀、@→-、丢弃[1m]标记），6 位 YYMMDD（如doubao-seed-2-1-pro-260628）与 8 位日期后缀均被支持（src-tauri/src/services/usage_stats.rs）。缓存计数语义分三类存储（v13 schema 新增input_token_semantics列），防止 cache-write token 被重复计价。

六、统一面板：MCP / Skills / Prompts / Sessions

6.1 MCP

v3.7.0 起 MCP 统一为跨应用面板，v3.16.0 后支持MCP 导入/导出、逐应用启用、SSE/stdio/http 传输与批量 per-app 开关。数据库是 MCP server 的唯一事实源（mcp_servers表），各应用的实时配置文件只是投影。Grok Build 需要做方言处理（Grok 从command/url推断 transport、使用headers，导入导出时需转换type与http_headers）。Pi 因没有原生 MCP registry 而刻意排除在 MCP 同步之外。前端主面板见 src/components/mcp/UnifiedMcpPanel.tsx 与表单 src/components/mcp/McpWizardModal.tsx。

6.2 Skills

Skills 支持从 GitHub 仓库发现/安装、从skills.sh搜索安装、ZIP 本地导入，安装状态由数据库 SSOT 记录并投影到各应用目录。其安全红线在 v3.19.0 中被系统性收紧：目录名校验、仓库坐标白名单、解压上限（10,000 条目 / 512 MB / symlink 目标 4 KB）等，防止 zip-slip 与路径穿越把文件写到受管目录之外。Skills 相关代码可参考 src-tauri/src/services/skill.rs 与前端 src/components/skills。

6.3 Prompts

Prompts 采用单激活约束，把选中的提示词写入各应用对应文件：Claude 为~/.claude/CLAUDE.md、Codex 为~/.codex/AGENTS.md、Gemini 为~/.gemini/GEMINI.md。Hermes 曾有一个被修正的经典坑：早期把 prompt 写进 Hermes 根本不读的~/.hermes/AGENTS.md，而 Hermes 真正加载的是~/.hermes/SOUL.md（v3.19.2 Fixed #5777）——现在 Hermes 读写在SOUL.md。Pi 则维护专门的 prompt 库（写入全局AGENTS.md，自动把已存在的非匹配内容先备份为一条库条目），并提供SYSTEM.md/APPEND_SYSTEM.md编辑器与~/.pi/agent/prompts/*.md斜杠命令模板管理器。相关实现见 src-tauri/src/services/pi_prompt_files.rs。

6.4 Session Manager

Session Manager 提供跨应用的会话浏览/搜索/删除：Claude 读~/.claude/projects下的 JSONL（含subagents/workflows/wf_*/子代理目录），Codex 读rollout-{uuid}JSONL 及state_5.sqlite线程表，Gemini/OpenCode/OpenClaw/Hermes/Grok Build/Pi 各有对应 provider 实现——目录 src-tauri/src/session_manager/providers 下有claude.rs、codex.rs、gemini.rs、opencode.rs、openclaw.rs、hermes.rs、grokbuild.rs、pi.rs全套实现。会话恢复命令针对各 CLI 当前语法生成（例如 OpenCode 已从过时的opencode session resume <id>修正为opencode -s <id>，v3.17.0 Fixed）。

七、Usage Dashboard、Codex 会话用量与历史重建

7.1 用量来源

用量数据来自两大类：代理记账（proxy_request_logs，含去重键session:{app_type}:{provider_id}:{id}）与会话日志导入（Claude/Codex/Gemini/OpenCode/Grok Build/Pi 的本地 session 文件）。两类数据在仪表盘去重合并；Claude Desktop 曾因命名空间不统一出现双重计数（v3.19.1 Fixed #5938），修复后claude会话行可被claude-desktop代理行吸收（单向规则）。细节行 30 天后聚合进usage_daily_rollups并被裁剪，因此历史错误的自我纠正只在保留窗口内生效。

7.2 Codex 会话用量的顽疾与修复

Codex 的 JSONL 有 fork/sub-agent 先回放父会话历史的特性。早期解析器用启发式找“接管边界”，导致 v3.17.0 起出现逐日数十亿 token 的夸大记账。修复分两步：v3.17.0 以显式父身份（forked_from_id/subagent.thread_spawn.parent_thread_id）定位边界、对齐 token signature 剥离回放前缀；v3.18.0 用 schema v16 触发一次性自动重建 + 提供 “Rebuild Codex Usage” 手动动作（后端命令在 src-tauri/src/commands/usage.rs）；v3.19.2 又解决了滚动文件中多累计计数器交错导致的高倍计数，并用 ~1,900 个真实文件/1.7 GB 语料验证误差在 0.001% 以内。

7.3 导入性能

v3.19.2 对导入做了批处理优化：token 事件每 1,000 行一个事务提交、批次间释放连接锁、游标与模型定价预载、热点语句 prepare 缓存——1,920 个 rollout 文件/1.7 GB 的完整重导从 36.3s 降到 11.1s（macOS release），Windows 提速更显著，等价性用重放前后 82,000 行逐列字节一致验证。Pi 导入则使用增量指纹（只解析追加字节）并通过 schema v17 新增的session_usage_dedup账本表对重写/分叉会话去重（该表保持设备本地、排除出云同步）。

八、数据库迁移与备份/同步（数据安全底线）

8.1 Schema 演进

SQLite 以user_version记录 schema 版本，当前为17（src-tauri/src/database/mod.rs）。每个大版本升级前自动创建预迁移备份；检测到“过新”数据库时会进入专用恢复屏而绝不先跑 DDL（v3.16.4 新增），防止降级后损坏数据。迁移逻辑集中在 src-tauri/src/database/schema.rs，其中含播种、修复与 guarded repair 分支（只改仍持旧内建值的行，绝不覆盖用户编辑过的价格）。

8.2 SQL 备份的可靠性

v3.19.2 修补了 dump/import 四个缺陷：TEXT 非 UTF-8 中止导出、NUL 截断语句、REAL 存储类丢失、AUTOINCREMENT 高水位与auto_vacuum丢失；校验被提前到建表之前，截断/缺核心表的 SQL 文件直接拒绝导入。备份先写临时文件、完整性校验通过后才原子发布（不覆盖已有文件），恢复则先在 staging 库整体校验再碰 live 库。恢复后还会做投影重建：把恢复出的数据库向外重放——每个受管应用的实时配置文件（Pi 除外，其models.json仍是事实源）、各应用 prompt 文件、运行日志级别与托盘用量缓存都会重建，并重新叠回本地设置与用户价格覆盖。

8.3 云同步与 Profiles

WebDAV（v3.12 起双版本协议）与 S3-compatible（v3.16.2 起，AWS SigV4）二选一启用；两个传输共享一个同步锁，同步/恢复/Skills 操作全局串行，避免并发恢复。项目 Profile（v3.17.0，schema v12）把 provider/MCP/Skills/Prompts 状态保存为命名快照，按 scope（Claude Code/Claude Desktop/Codex）记录current_profile_id_<scope>标记，切换即快照应用——前端实现见 src/components/profiles/ProfileSwitcher.tsx 与 src/components/profiles/scope.ts，后端在 src-tauri/src/services/profile.rs 与 src-tauri/src/commands/profile.rs。

九、跨平台、OAuth 与发布工程

Windows/WSL：v3.19.2 改用ReplaceFileW原子写导致\\wsl.localhost路径报ERROR_NOT_SUPPORTED(50)（fallback 只处理 NotFound），v3.20.0 将错误 50 也落入 rename 路径修复，并新增对真实 WSL2 文件系统的 CI 原子写契约测试。CLI 探测 v3.20.0 起合并注册表 PATH、扫描独立安装目录、以where.exe显式探测 PATH 默认项（跳过 Store alias），解决一系列 “not installed”/“版本不刷新” 问题。wsl.localhost路径识别逻辑集中在 src-tauri/src/config.rs、src-tauri/src/commands/misc.rs 等处。
macOS：v3.12.3 起 CI 完成代码签名与 Apple notarization（codesign --verify+spctl -a+stapler validate硬性把关）；v3.19.2 修复中文/日文 IME 在 provider 表单的输入损坏（IME-safe input 共享组件，见 src/components/ui/ime-safe-input.tsx）。
Linux：v3.16.5 提供CC_SWITCH_GDK_BACKEND逃生舱以绕开 AppImage 强制GDK_BACKEND=x11的 Wayland 输入问题。
OAuth 集成：GitHub Copilot（v3.12.3）、Codex OAuth / ChatGPT 多账号（v3.20.0，Auth Center 持有任意数量账号并可逐卡片绑定）、xAI Grok OAuth（v3.18.0，走官方 CLI 公开 client identity + Device Code）。OAuth 令牌写入~/.cc-switch/xai_oauth_auth.json（Unix0600），访问令牌仅驻内存。
发布：CI 覆盖 Linux/macOS/Windows（v3.18.0），Windows ARM64（v3.16.4）；更新包走dl.ccswitch.io（Cloudflare R2 镜像）优先、GitHub 兜底（v3.19.0）；src-tauri/wix提供 MSI 模板，v3.20.0 修复了其中双反斜杠被 Handlebars 吃掉导致写入垃圾注册表键的历史缺陷。

十、安全加固脉络（可引用的硬边界）

CHANGELOG 的 Security 小节是一条值得单独提炼的加固史：

用量脚本沙箱（v3.19.2）：JS 运行时 5 秒中断、16 MiB 内存、256 KiB 栈上限。
日志与错误脱敏（v3.18.0 / v3.20.0）：全部后端日志出口脱敏，URL 剥 userinfo/query/fragment，请求/响应体只记字节数与安全分类；fetch models 错误体严格隐藏凭据（直至 1 字符）。
深链确认可见性（v3.19.0 系列）：ccswitch://导入确认展示完整载荷（命令、参数、env、脚本全文），凭据形值掩码；URL-safe Base64 在前后端解码一致性修复（v3.19.0 Security），确保“预览即所写”。
解压/读取边界：仓库 skill 安装 zip-slip 防护与归档硬限制（v3.19.0）；Grok 会话目录递归 16 层、50 MiB 上限、不跟随 symlink（v3.19.2）；代理缓冲响应 128 MiB 上限、解压在解码器读侧预算化防压缩炸弹（v3.19.2）。
原型污染与注入：common-config snippet 遍历跳过__proto__/constructor（v3.19.0）；终端启动以 POSIX 单引号转义项目路径（v3.19.0）；SQL 导入期间启用 SQLite authorizer 拒绝ATTACH/DETACH等越库语句。

十一、升级与降级语义（实用清单）

CHANGELOG 各版本的 “Upgrade notes” 已沉淀为一套稳定约定，可直接作为使用与排障手册：

数据库版本不可回退：跑过 v17 构建后，旧版本构建拒绝打开数据库；降级需先恢复预迁移备份。
预设只影响新 provider：需对照版本修正（如 Volcengine Agent Plan 端点、Kimi reasoning effort、BytePlus native Responses、模型 ID 替换、OpenCode Go 直连等）时，请从预设重建或手动改对应字段；个别修正（Kimi passthrough、平台推理纠正、配额探测放宽）对既有 provider 立即生效。
自动修复有边界：价格类 repair 只在行仍持“先前内建值”时改写，绝不碰用户编辑；用量类错误只向前纠正，历史行常保留（必要时用 “Rebuild Codex Usage” 手动重建）。
安装/自更新的 PATH 前提：v3.19.1 起 Settings → About 触发的工具安装/升级会合并登录 shell 的 PATH；grok update的 node 依赖问题经由官方 xAI installer 兜底。
已知遗留：被早期 takeover-restore bug 清掉的 ChatGPT 登录需手动执行一次codex login；被 IME bug 写坏的文本需重编一次；MSI 旧垃圾注册表键不会被自动清理。

十二、写给进一步阅读者：源码入口索引

若想沿 CHANGELOG 的线索深入代码，以下路径是最直接的入口：

数据库层：src-tauri/src/database/mod.rs（SCHEMA_VERSION与迁移框架）、src-tauri/src/database/schema.rs（播种/迁移/修复）、src-tauri/src/database/backup.rs（SQL 备份与恢复）
命令层：src-tauri/src/commands/provider.rs、src-tauri/src/commands/profile.rs、src-tauri/src/commands/usage.rs、src-tauri/src/commands/pi.rs
代理/转换：src-tauri/src/proxy（forwarder、各 provider 适配器与 streaming/transform 模块）
服务层：src-tauri/src/services/profile.rs、src-tauri/src/services/session_usage_codex.rs、src-tauri/src/services/session_usage_pi.rs、src-tauri/src/services/model_pricing.rs
各应用配置：codex_config.rs、claude_desktop_config.rs、gemini_config.rs、openclaw_config.rs、hermes_config.rs、grok_config.rs、pi_config/下的 Rust 模块
前端预设与面板：src/config 下的*ProviderPresets.ts、src/components/providers、src/components/mcp、src/components/profiles、src/components/usage

配套的每个版本发布说明（zh/en/ja 三语）存放在 docs/release-notes，路由使用指南在 docs/guides，用户手册在 docs/user-manual——三者与 CHANGELOG 互为印证，共同构成理解 CC Switch 从“切换器”走向“All-in-One AI CLI 管理平台”的最完整一手资料。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

CC Switch 演进全史：从双应用配置切换器到九应用 All-in-One AI CLI 管理平台