个人记录（2026.5.14-5.15）——cc-switch-main 源码说明

JM1011M

450人浏览 · 2026-06-05 15:04:15

JM1011M · 2026-06-05 15:04:15 发布

记录（2026.5.14-5.15）——cc-switch-main 源码说明

1. 这个项目到底是什么

cc-switch-main 是一个桌面端控制台，用来统一管理 Claude Code、Codex、Gemini CLI、OpenCode、OpenClaw、Hermes 等工具的配置、供应商切换、本地代理接管、MCP、技能、提示词和会话能力。

通俗理解：它像一个“总控面板”，你不用分别去改每个工具的配置文件，而是在一个桌面应用里统一操作。

2. 它是怎么工作的

先看最粗的一条链路：

用户打开桌面应用。
React 前端渲染界面。
前端通过 Tauri invoke 调用 Rust 命令。
Rust 读取数据库、改本地配置、必要时启动本地代理。
如果开启“接管”，Claude/Codex/Gemini 这类工具会把请求先发给本机代理。
本机代理再把请求转发到当前选中的真实供应商。

通俗理解：前端负责“让你点”，Rust 负责“真正干活”，本地代理负责“代替这些工具出去联网”。

3. 技术栈

前端

React 18
TypeScript
Vite
Tailwind CSS
TanStack Query

通俗理解：界面和交互主要是常规现代前端技术。

桌面和系统能力

Tauri 2
Rust
SQLite

通俗理解：真正能读写本地文件、拉起本地服务、做托盘和深链的，是 Rust 这一层。

4. 顶层目录作用

源码：

https://github.com/farion1231/cc-switch.git

目录/文件	作用	通俗理解
`src/`	React 前端源码	你看到的桌面界面基本都在这里
`src-tauri/`	Rust 后端源码	真正改配置、起代理、存数据的地方
`assets/`	图片和资源文件	图标、品牌图、静态素材
`docs/`	项目文档	给开发者和用户看的说明
`tests/`	测试代码	保证关键逻辑不被改坏
`package.json`	前端依赖和脚本	前端怎么启动、怎么构建，看它
`src-tauri/Cargo.toml`	Rust 依赖和构建入口	Rust 版的依赖清单
`README_ZH.md`	中文项目说明	想先看项目功能，先看它

5. 前端部分

5.1 `src/main.tsx`

作用：

挂载 React 应用
初始化主题、国际化、React Query
监听后端发来的事件

通俗理解：这是前端“开机文件”。

5.2 `src/App.tsx`

作用：

控制当前显示哪个页面
控制当前管理哪个应用
连接 Providers、Settings、MCP、Skills、Sessions 等页面
监听后端状态变化并刷新界面

通俗理解：这是整台桌面应用的“主控屏”。

5.3 `src/components/`

这个目录按业务拆得比较直白：

目录	作用	通俗理解
`components/providers/`	供应商管理 UI	新增、编辑、切换供应商的界面
`components/settings/`	设置页	应用级设置都在这里
`components/mcp/`	MCP 管理	管 MCP 服务和导入导出
`components/skills/`	技能管理	管技能安装、发现、导入
`components/sessions/`	会话管理	看不同工具的会话
`components/proxy/`	代理相关 UI	开关代理、接管、故障切换
`components/openclaw/`	OpenClaw 专属页面	只和 OpenClaw 有关的界面
`components/hermes/`	Hermes 专属页面	只和 Hermes 有关的界面
`components/ui/`	通用 UI 组件	按钮、弹窗、列表等基础零件

通俗理解：这个目录就是“界面零件库 + 业务页面集合”。

5.4 `src/lib/api/`

重点文件：

src/lib/api/providers.ts
src/lib/api/settings.ts
src/lib/api/proxy.ts

作用：

把前端动作包装成 Tauri invoke(...)
让前端去调 Rust 命令

通俗理解：这里像“前端拨号台”，前端要做什么，基本先从这里打电话给 Rust。

5.5 `src/lib/query/` 和 `src/hooks/`

重点文件：

src/lib/query/*
src/hooks/useProviderActions.ts

作用：

做请求缓存
做 mutation 封装
把“切换供应商”这种复杂动作打包成一个前端行为

通俗理解：这里是“前端业务协调层”，避免把复杂逻辑全塞进页面组件。

6. Rust 后端部分

6.1 `src-tauri/src/main.rs`

作用：

做平台级初始化
调用真正入口 cc_switch_lib::run()

通俗理解：这是 Rust 端“引导文件”，但不是主要逻辑所在地。

6.2 `src-tauri/src/lib.rs`

作用：

初始化数据库
初始化日志和 panic hook
注册 Tauri 插件
注册所有前端可调用命令
处理单实例、深链、托盘、退出清理

通俗理解：这是整个桌面应用的“总入口”和“总装配厂”。

6.3 `src-tauri/src/commands/`

重点文件：

commands/provider.rs
commands/settings.rs
commands/proxy.rs

作用：

接收前端参数
调用 service 层
把结果返回给前端

通俗理解：这是后端“接口层”，前端点按钮后，多半先到这里。

6.4 `src-tauri/src/services/`

这是主要业务层，最值得重点读。

`services/provider/`

作用：

管供应商的增删改查
读取 live 配置导入供应商
切换当前供应商
同步配置到不同应用

通俗理解：这是“供应商大脑”。

`services/proxy.rs`

作用：

启动本地代理
停止本地代理
备份 live 配置
接管 Claude/Codex/Gemini 的 live 配置
退出时恢复原配置

通俗理解：这是“接管和还原中心”。

其它常见模块

模块	作用	通俗理解
`services/mcp.rs`	MCP 管理	管 MCP 配置和同步
`services/prompt.rs`	提示词管理	管 prompts
`services/skill.rs`	技能管理	管技能导入、迁移、同步
`services/webdav*.rs`	WebDAV 同步	做配置备份和同步

6.5 `src-tauri/src/proxy/`

这个目录非常关键。

它不是“改个地址就结束”的代理，而是一套本地代理网关。

文件/目录	作用	通俗理解
`server.rs`	启动本地监听端口	真正把本机代理服务跑起来
`handlers.rs`	处理不同 API 路径	收到请求后按接口类型分流
`provider_router.rs`	选择当前供应商	决定这次请求到底发给谁
`circuit_breaker.rs`	熔断	某供应商连续失败就先别再打它
`failover_switch.rs`	故障切换	当前供应商挂了就切下一个
`response_handler.rs`	响应处理	处理普通响应和流式响应
`thinking_optimizer.rs`	参数修正/优化	对特定模型请求做兼容和优化
`session.rs`	会话标识处理	把请求和会话对应起来

通俗理解：这整个目录就是“本机上的小型 API 网关”。

7. 关键文件为什么重要

文件	为什么重要	通俗理解
`src/main.tsx`	前端入口	前端从这里开机
`src/App.tsx`	前端主调度	整个界面的大脑
`src/lib/api/providers.ts`	前端调供应商命令的入口	点“切换供应商”会走它
`src/hooks/useProviderActions.ts`	供应商相关前端业务动作封装	前端复杂动作集中在这里
`src-tauri/src/lib.rs`	Rust 总入口	后端总装配点
`src-tauri/src/commands/provider.rs`	供应商命令入口	前端切换供应商先到这里
`src-tauri/src/services/provider/mod.rs`	供应商业务核心	真正的供应商逻辑中心
`src-tauri/src/services/proxy.rs`	代理/接管核心	决定怎么接管和恢复
`src-tauri/src/proxy/server.rs`	本地代理服务启动	真正监听本机端口
`src-tauri/src/proxy/provider_router.rs`	供应商路由	决定请求发给哪个上游