CC Switch 的页面切换：一个联合类型管住十几个视图

在一个桌面工具里，从设置页回到列表页这件事看上去太普通了，普通到你会默认它背后有个路由器。CC Switch 没有。它把整个应用的「当前在哪一页」压缩成了一个字符串 state，页面之间的关系全写在一个 switch 里。

这个选择带来的连锁反应比想象中多：类型安全从哪来、上次停在哪一页记在什么地方、存储里留下一个已经不合法的值时代码怎么收场、想加一页要改几处。这篇就顺着 src/App.tsx 把这条链路读一遍。

先说清楚这篇文章的依据

本文对应的快照是 CC Switch v3.20.1，仓库 commit 3217f725，核对日 2026-08-31。下面出现的所有行号都以这个快照为准，你在同版本的仓库里能逐行对上；换个版本行号大概率就不对了。

需要说明的是：我们只是静态地读源码，没有编译它、没有运行它，也从来没有安装过这个桌面应用。所以下面凡是涉及「看起来怎么样」的部分一律没有，只有代码里写了什么。

三件东西：类型、清单、初始值

页面这个概念在 src/App.tsx:116-130 是一个字符串联合类型 View。取值可以按名字分成两拨：一拨是各个被托管 CLI 共用的功能页，比如 providers、settings、mcp；另一拨的标识符本身就带着所属 CLI 的前缀，比如 openclawEnv、openclawTools 属于 OpenClaw，hermesMemory 属于 Hermes。这也就意味着这个联合类型的长度跟托管对象的数量直接挂钩——v3.20.1 里的这份清单，会随着被托管的 CLI 增减而变，不必去记它此刻有几项。

紧接着 :151-166 又有一个 VALID_VIEWS 数组，内容和上面那个联合类型逐字相同。这不是冗余写法，是没办法：TypeScript 的联合类型编译后什么都不剩，运行时想判断「从存储里读出来的这个字符串是不是合法视图」，必须另有一份实际存在的数组。于是同一批字符串在这个文件里出现了两遍，一份给编译器，一份给 includes()。

代价是它们要靠人工保持同步。加一个视图时如果只改了类型没改数组，TypeScript 一个字都不会提醒你——因为数组里的每一项仍然都是合法的 View，只是少了一项而已。

第三件是初始值。getInitialView()（:168-174）从 localStorage 的 cc-switch-last-view 键里读上次停留的视图，命中 VALID_VIEWS 就用它，否则回落到 providers。写回的地方在 :201，是一个依赖 [currentView] 的 useEffect，视图一变就落盘。同一套写法还用在应用维度上，键是 cc-switch-last-app（:141-148）。

这里有个值得注意的细节：getInitialView 只校验「这个值在清单里」，不校验「用户能不能走到这一页」。清单合法和路径可达是两件事，这个缝隙在 v3.20.1 里确实漏进了两个没有任何界面入口的视图——那个话题我们另有一篇专门讲，这里不展开。

为什么没有路由库

package.json 的依赖里 router 零命中。页面切换就是 setCurrentView(...) 改一个 state，没有 history、没有 URL、没有前进后退。

从这个应用的形态看，这个取舍是自洽的：它是一个 Tauri 壳里的单窗口工具，用户没有地址栏，不会复制链接给同事，也没有浏览器后退按钮可按。引入路由库要换来的那些能力，在这个场景里大部分用不上，反而要多维护一层 URL 与状态的映射。

代价也很直白：所有「从外部跳到某一页」的需求都得自己接线。比如顶栏那几个入口按钮，做法是先 setSettingsDefaultTab(...) 再 setCurrentView("settings") 两步（:1350-1365），分别指向 general、about、usage 三个 tab——因为没有 /settings?tab=usage 这种东西可用，页面内的位置只能靠另一个 state 传。

renderContent()：default 分支承接的是主页

:1007-1178 的 renderContent() 是一个 switch (currentView)，每个视图对应一个 case，返回对应的面板组件。比如 settings 渲染 src/components/settings/SettingsPage.tsx，mcp 渲染 src/components/mcp/UnifiedMcpPanel.tsx，sessions 渲染 src/components/sessions/SessionManagerPage.tsx。

有意思的是 providers 这个视图没有自己的 case，它落在 default 分支里（:1090-1160）。也就是说 case 的数量比视图取值少一个。

这个安排顺手解决了一类问题：任何未被显式处理的 currentView，在代码路径上都会落到 default 分支、返回供应商列表，而不是返回 undefined。配合前面 getInitialView 的回落，存储里就算留着一个谁也不认识的字符串，renderContent() 这个函数在代码上也没有一条路径会交不出内容。把最常用的页面放在 default 上，兜底和主路径就重合了。

switch 算出内容之后，:1164-1177 外面套了 <AnimatePresence mode="wait">，key 是 currentView，过渡时长在代码里写的是 0.2 秒；:1094-1157 的列表区里层还有一个 key={activeApp} 的 0.15 秒过渡。两层 key 是刻意分开的：换视图整块重绘，换被管理的应用只重绘列表区。这里只能说代码里的配置是这样，具体呈现成什么样我们没有运行过，不做判断。

非法组合的两条自愈守卫

视图是全局的，但不是每个视图对每个被托管的 CLI 都成立。用户可能停在 mcp 页，然后把当前应用切成一个没有 MCP 能力的目标——这时候 currentView 就成了一个非法组合。

:228-246 用两条判断处理这件事：currentView === "mcp" 且当前应用折算后是 pi 时退回 providers（:229-232）；sessions 视图则跟一串 !== 白名单比对，不在名单里同样退回 providers（:233-245）。

同一节还有一条对应用维度的守卫（:221-225）：当前应用被设置里隐藏了，就切到 getFirstVisibleApp()，实现是 APP_IDS.find((app) => visibleApps[app]) ?? "claude"（:217-219）。v3.19.2 时这里是一串顺序 if 判断，v3.20.1 收成了一行 find，语义等价，但新增应用时不用再补一个分支。

这两条守卫加上 default 兜底，构成了这套「无路由」方案的完整性保证：状态可以被外部因素改成非法值，但每次渲染前都有一层收敛。

switch 之外的那张父子关系表

有一件事 switch 表达不了：页面之间的层级。

:1287-1292 的返回按钮里藏着一条特例——skillsDiscovery 的上一层是 skills，其余所有视图的上一层一律是 providers。同一条规则在 Escape 键的处理里又出现了一次（:680）。也就是说，整个应用的页面层级其实只有一处例外，作者没有为它建一张父子映射表，而是写成了一个三元表达式，写了两遍。

Escape 那段（:657-687）本身值得看。整个应用只注册了一个 window 级 keydown 监听，处理两件事：Cmd/Ctrl + , 跳设置，Escape 回退一层。Windows 上就是 Ctrl + ,。Escape 在真正执行回退前有四道前置判断：事件已被 defaultPrevented 就放行；document.body.style.overflow === "hidden" 就放行；当前已经在 providers 就不动；焦点在可编辑元素上就放行。

第二条是这里最巧的一手——它把「body 的滚动被锁了」当作「有模态层开着」的信号。写这把锁的地方是 src/components/common/FullScreenPanel.tsx:36-50 的 lockBodyScroll / unlockBodyScroll，带引用计数。同一个文件的 :84-108 还自己监听 Escape 并显式 stopPropagation()，注释写明是为了不让事件冒泡到 App.tsx 的全局监听。外壳和面板之间对这个按键有一套写在注释里的约定。

顺带一提，用户手册 docs/user-manual/zh/1-getting-started/1.3-interface.md:178-182 把 Cmd/Ctrl + F 和上面两个并列成全局快捷键，但外壳的监听里并没有它——搜索快捷键分散实现在 ProviderList.tsx:281、ProviderPresetSelector.tsx:199、DailyMemoryPanel.tsx:153 三个组件内部，只在这些组件挂载时才有效。两处口径不一致，以实读的源码为准，就这些。

测试把 localStorage 当成了输入参数

tests/integration/App.test.tsx 里有个细节反向印证了前面的结构。:207-208 每个用例前都清掉 cc-switch-last-view 和 cc-switch-last-app；:354 用 localStorage.setItem("cc-switch-last-app", "pi") 预置初始应用；:447 用 cc-switch-last-view = "skills" 直接把应用送进 Skills 视图再断言顶栏按钮。

没有路由的应用没有「导航到某页」的测试 API，于是这两个存储键就成了事实上的入口参数。这也说明它们不是可有可无的偏好项，而是外壳的持久化状态本身。

想加一个视图，要改哪几处

把上面这些串起来，新增一个页面的改动点是确定的：src/App.tsx:116-130 的 View 联合类型加一项；:151-166 的 VALID_VIEWS 手抄一遍；renderContent() 里加一个 case；标题映射那一串条件渲染里加一行（:1300-1321 是十几行 currentView === "xxx" && t(...) 堆出来的）；如果这个页面不是所有应用都支持，还要去 :228-246 的自愈守卫里补判据；如果它有上一层，:1287-1292 和 :680 两处返回逻辑都要改。

六到七处手改，没有一处会在漏改时报错。漏掉 VALID_VIEWS，getInitialView 里的 includes() 就认不出这个新值，读取时走的是末尾 return "providers" 那条路；漏掉守卫，这个 view 在不支持它的应用下仍然会被对应的 case 命中并渲染，代码里没有任何一处会在此时把它拦下来。这就是把路由摊平进单文件的真实成本：结构简单到一眼能读完，但正确性全靠人记住有哪几处要一起动。

要不要为此引入路由库，取决于这个文件还会长多久、视图还会加多少个。项目本身没有给出这个判断，我们也不替它给。

---

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