Cherry Studio 渲染进程窗口架构指南三层入口约定、prepareWindow 预热与窗口运行时设计【免费下载链接】cherry-studioAI productivity studio with smart chat, autonomous agents, and 300 assistants. Unified access to frontier LLMs项目地址: https://gitcode.com/GitHub_Trending/ch/cherry-studio本篇技术指南围绕 Cherry Studio 渲染进程renderer的多窗口体系展开基于 src/renderer/windows/README.md 梳理其统一的三层入口约定entryPoint → App → 业务组件、prepareWindow首帧预热机制、窗口级运行时runtime leaf的归属规则以及声明式 Logger 窗口来源标注。读完你将掌握如何为 Cherry Studio 新增一个渲染窗口而不破坏 Fast Refresh、主题闪烁theme flash的消除原理、main/subWindow 与轻量窗口在运行时职责上的分界以及为什么某些副作用必须挂在 Provider 内、Tab 路由之外的叶子节点上。一、渲染进程多窗口体系总览Cherry Studio 的渲染进程并不是单个 React 应用而是由多个独立 BrowserWindow 构成的多窗口体系。每个窗口都是一个独立的 HTML 入口 React 应用目录结构如下每个子目录即一个窗口src/renderer/windows/ ├── main/ # 主窗口 ├── subWindow/ # 子窗口如独立标签页窗口 ├── quickAssistant/ # 快捷助手 ├── migrationV2/ # v2 数据迁移preboot 特例 ├── userDataRelocation/ # 用户数据迁移preboot 特例 ├── selection/ │ ├── action/ # 划词操作窗口 │ └── toolbar/ # 划词工具栏 ├── screenshot/ # 截图窗口 ├── prepareWindow.ts # 共享 L1 序言 └── README.md所有窗口遵循完全一致的三层结构约定这一约定既是代码组织规范也是工程性能Fast Refresh与首帧渲染体验无主题闪烁的设计基础。二、三层入口约定entryPoint → App → 业务 UI2.1 三层职责划分层文件职责规则L1entryPoint.tsx引导副作用导入样式、await prepareWindow(...)、createRoot().render(XxxApp /)固定文件名。不定义任何组件——只挂载一个组件L2XxxApp.tsxProvider 根Provider/QueryClientProvider/ThemeProvider等。可挂载一个内部运行时叶子节点组合该窗口聚焦的初始化 hookslocale / custom-CSS / background / fullscreen 等并将弹窗/Toast 宿主PopupHost//ToastHost/作为兄弟叶子挂载固定名称WindowNameApp默认导出由 L1 挂载L3不固定窗口的实际 UI按语义命名——无强制后缀index.html中的script src指向该窗口的entryPoint.tsx。以主窗口为例src/renderer/windows/main/index.html 第 43 行script typemodule src/windows/main/entryPoint.tsx/script而 src/renderer/windows/main/entryPoint.tsx 完整体现了 L1 的职责边界import renderer/assets/styles/index.css import renderer/assets/styles/tailwind.css import { createRoot } from react-dom/client import { prepareWindow } from renderer/windows/prepareWindow import MainApp from ./MainApp await prepareWindow({ preference: all }) const root createRoot(document.getElementById(root) as HTMLElement) root.render(MainApp /)注意 L1 中只有三类内容样式副作用导入、prepareWindow预热、createRoot().render()。没有组件定义、没有业务逻辑。2.2 为什么要把 L1 与 L2 拆开Fast Refresh 边界文档给出了明确的工程理由在模块顶层调用createRoot().render()的模块不是 React Fast Refresh 边界编辑它会导致整页重新加载。因此entryPoint.tsx保持极简几乎不被触碰组件放在独立的XxxApp.tsx纯组件模块中UI 编辑可以热替换hot-swap只有极少修改的entryPoint.tsx才会触发整页 reload。这是开发体验DX层面的关键设计多窗口体系下每个窗口都是独立的 HTML 页面若入口文件包含了大量组件代码任何 UI 改动都会触发该窗口整页刷新破坏开发效率。2.3 L3 命名约束语义化而非后缀化L3 的命名不属于约定的一部分——请按语义命名永远不要加后缀。尤其注意不要发明新的...AppShell名字。AppShell是共享布局组件族的特定名称src/renderer/components/layout/AppShell 及AppShellTabBar不是通用的内容后缀。从 src/renderer/windows/main/MainApp.tsx 可见主窗口的 L3 直接复用共享布局AppShell子窗口则使用自己的 src/renderer/windows/subWindow/SubWindowAppShell.tsx——这些都是共享布局族的具体成员而非通用命名模式。三、prepareWindow首帧预热消灭主题闪烁prepareWindow.ts是所有窗口的共享 L1 序言位于 src/renderer/windows/prepareWindow.ts。其核心 APIexport async function prepareWindow(options: PrepareWindowOptions): Promisevoid interface PrepareWindowOptions { /** 首帧读取的偏好键 —— all 表示预热整个缓存 */ preference: all | UnifiedPreferenceKeyType[] }3.1 工作原理export async function prepareWindow(options: PrepareWindowOptions): Promisevoid { // 生产环境为 no-op在首次 DataApi 请求前暴露 DevTools 控制面 DataApiDevtools.exposeControlSurface() const preferencesWarm options.preference all ? preferenceService.preloadAll() : preferenceService.preload(options.preference) await Promise.all([initI18n(), preferencesWarm]) }关键语义在首次渲染之前初始化 i18n 并预热偏好缓存使usePreference在第一帧就读到已保存的值而不是回退到默认值——这就是**无主题闪烁no theme flash**的来源源码注释明确称之为 the source of the theme flash。两条偏好预热路径都是 best-effort 且永不 reject预热失败会降级为默认值并依赖usePreference的按需自愈lazy per-key self-heal。DataApiDevtools.exposeControlSurface()在首个await之前同步执行确保 payload 捕获在任何事件被记录前就已启用。3.2 all 与按键列表两种模式的取舍窗口类型preference 参数说明main/subWindowall预热完整缓存仅需一次内存内 IPC 拉取轻量窗口quickAssistant/selection-action/selection-toolbar/screenshot精确按键列表只预热首帧实际读取的键最小化开销migrationV2/userDataRelocation不调用preboot 特例自带 i18n、无偏好保持独立轻量窗口的按键列表是逐窗口手工枚举的。例如快捷助手窗口 src/renderer/windows/quickAssistant/entryPoint.tsx 预热了 9 个键await prepareWindow({ preference: [ app.language, ui.custom_css, ui.theme_mode, ui.theme_user.color_primary, ui.window_style, feature.quick_assistant.assistant_id, feature.quick_assistant.model_id, chat.default_model_id, feature.quick_assistant.read_clipboard_at_startup ] })划词工具栏 src/renderer/windows/selection/toolbar/entryPoint.tsx 则预热 6 个键语言、自定义 CSS、主题、主色、紧凑模式、动作项。新增窗口时必须精确列出其首帧读取的偏好键而不是图省事用all或漏掉某个键——前者浪费 IPC 开销后者会导致首帧读到默认值。3.3 测试验证src/renderer/windows/tests/prepareWindow.test.ts 用 4 个用例锁定了这些契约preference: all时只调preloadAll不调preload且initI18n被调用按键列表时精确调用preload([ui.theme_mode, app.language])不调preloadAllDevTools 控制面在首个await之前同步暴露prepareWindow只有在 i18n 与偏好预热都完成后才 resolve对两个 Promise 分别手动控制 resolve 时机进行断言。这说明Promise.all([initI18n(), preferencesWarm])的两者皆备才放行渲染语义是有测试保障的。四、窗口运行时叶子节点Runtime Leaf副作用归属的关键决策4.1 为什么需要独立于 Tab 的运行时叶子窗口级的副作用订阅、必须存活整个窗口生命周期的 DOM 同步应放在 L2XxxApp挂载的一个小运行时叶子组件中且位置在Provider 内部、所有TabRouter/Activity之外。原因隐藏的Activity子树会销毁 effects——任何挂在 tab 下的订阅在 tab 进入后台时都会丢失。该叶子组件是headless的只跑 hooks、渲染nullPopup/Toast 宿主则作为 App JSX 中显式的兄弟节点挂载因此窗口的宿主组合在 JSX 中清晰可见。4.2 全 chrome 窗口useWindowRuntimemain与subWindow都调用useWindowRuntime()——共享的窗口运行时定义在 src/renderer/hooks/useWindowRuntime.ts。其职责清单源码逐条可见locale 同步useLanguageSync()轻量窗口也复用 dayjs locale 设置仅渲染本地化日期的窗口需要custom CSSuseCustomCss()轻量窗口也复用逐字使用同一 CSS根背景macOS 透明窗口用 vibrancy 感知的背景color-mix(in srgb, var(--background) 55%, transparent)其他窗口用var(--sidebar)app 路径快照mount 时通过ipcApi.request(app.get_info)把homePath写入内联文件路径基址、resourcesPath写入缓存非阻塞、失败仅记日志全屏处理Windows 进入全屏时弹提示 Toastwindow.fullscreen_changedIPC 订阅useIpcOn卸载时自动清理ESC 退出全屏受shortcut.app.fullscreen.exit偏好门控纯按键、无修饰键时生效主题/Agent 自动重命名同步useTopicAutoRenameSync/useAgentSessionAutoRenameSync每个 BrowserWindow 有独立的 SWR 缓存所以各自保留失效逻辑MiniApp 启动器列表收敛IPC 侧写入后每个窗口恰好同步一次且在Activity之外。成员的严格规则某个关注点只有 main 与 subWindow都以完全相同方式需要才归属useWindowRuntime。它不接收配置、不包含任何 main-only 行为因此不可能隐藏窗口间的差异——这正是它与已退役的useAppInit大杂烩grab-bag之间的分界线。4.3 Main-only 关注点MainWindowRuntimeMain-only 的关注点明确放在 src/renderer/windows/main/MainApp.tsx 中的MainWindowRuntime内显式排除在useWindowRuntime之外启动 spinner 移除 init计时器结束与只有main/index.html创建的标记配对#spinner元素、console.time(init)绝不能在别的窗口运行useAppUpdateHandler更新事件只到达主窗口useAutoBackupEvents自动备份事件useStorageMonitorNotification、useTopicNamingErrorNotification面向主窗口的 Toast不能跨窗口重复。这些是刻意保持为 React hooks 的它们依赖 React 可见的 cache/toast 状态并自行管理 effect 清理而 renderer 没有服务生命周期容器若做成 service 只会引入手工 start/stop。对照子窗口 src/renderer/windows/subWindow/SubWindowApp.tsxSubWindowRuntime只调用useWindowRuntime() 注册 image-mode 弹窗完全没有Main-only 关注点——两个窗口运行时组合的差异一目了然。4.4 轻量窗口只取公共 hooks不用完整运行时quickAssistant/selection-action/selection-toolbar/screenshot不使用useWindowRuntime它们不渲染本地化日期、无 chrome。它们改为挂载useLanguageSync 与全 chrome 窗口逐字相同的 custom CSS。useLanguageSyncsrc/renderer/hooks/useLanguageSync.ts与useCustomCss之所以是独立 hooks正是因为轻量窗口要复用它们。useLanguageSync的注释澄清了职责边界初始语言已由prepareWindow的initI18n()应用该 hook 只响应运行时的偏好变化它刻意不碰 dayjs locale——日期本地化是独立关注点仅在useWindowRuntime中为渲染本地化日期的窗口main/subWindow同步。唯一的例外是screenshot它是像素对齐的全屏画布用户自定义 CSS 若改变了布局会让选区与实际截取的屏幕区域错位因此它不使用 custom CSS 那一半。4.5 两条硬性规则不要把 main-only 行为塞进useWindowRuntime窗口间差异需要用配置标志来掩盖——这就是坏味道不要把非首帧的工作推进prepareWindow首帧预热只负责第一帧就拿到值不应承担运行期初始化。五、Logger 窗口来源声明式 meta而非命令式调用每个窗口在index.html中声明式地标注其 logger 来源而不是在entryPoint.tsx里调用meta namelogger-window-source contentmainWindow /LoggerService构造时读取该 meta。src/renderer/windows/main/index.html 第 6 行与 src/renderer/windows/selection/toolbar/index.html 第 6 行分别声明了mainWindow与SelectionToolbar。这一设计的优势meta在任何模块脚本运行前就被解析因此在任何 import-time 日志之前来源就已确定——entryPoint.tsx里不需要任何排序规则也不需要每个窗口单独的initLogger副作用模块新增窗口时必须使用唯一的 source 字符串复用已有字符串会把两个窗口的日志混在一起无文档上下文如 workers改用loggerService.initWindowSource(Worker)它会覆盖meta 推导的值。完整机制参见 docs/references/logging/README.md。六、各窗口一览窗口L2 根L3 内容mainMainAppsrc/renderer/components/layout/AppShell共享subWindowSubWindowAppSubWindowAppShellquickAssistantQuickAssistantAppHomeWindowmigrationV2MigrationApp组件内src/renderer/windows/migrationV2/componentsuserDataRelocationRelocationApp组件内进度/恢复 UIselection/actionSelectionActionAppActionWindowselection/toolbarSelectionToolbarAppSelectionToolbar设置页也复用screenshotScreenshotAppCaptureOverlay每个显示器一个池化窗口6.1 特例窗口说明migrationV2 / userDataRelocationpreboot 特例自带 i18n各自的i18n/index.ts、locales.ts、resolver.ts不读取偏好保持独立运行——这也是它们不经过标准prepareWindow流程的原因。selection/toolbar刻意省略index.css字体 / markdown / 聊天样式保持最轻量窗口的最小体积其index.html还内联了一段强制透明背景、禁用选中的样式确保悬浮工具栏形态正确。CSS 副作用导入按入口保持独立这是规范而非例外。6.2 轻量窗口的 Redux 取舍quickAssistant是值得注意的工程决策实例它刻意不挂 ReduxProvidersrc/renderer/windows/quickAssistant/QuickAssistantApp.tsx 注释明确说明。其下游 assistant/model 数据已来自 v2 Preference DataApi 层usePreference、useQuery(/models/:id)不依赖 Redux rehydration因此也不需要PersistGate。同时它采用双层 ErrorBoundary外层包裹所有 ProviderProvider 渲染抛错时回退到无上下文的致命 fallback 而非白屏内层只包裹 L3 内容——AI 输出可能格式错误内容崩溃时显示主题化错误卡片而窗口运行时与 popup/toast 宿主内层边界之外的兄弟节点继续运行。七、新增一个窗口的检查清单综合文档约定与源码实现为 Cherry Studio 新增渲染窗口时应逐项核对目录在src/renderer/windows/下按窗口名建子目录含entryPoint.tsx、XxxApp.tsx、index.htmlL1entryPoint.tsx只做样式副作用导入 await prepareWindow(...)createRoot().render(XxxApp /)不定义组件L2XxxApp.tsx固定命名WindowNameApp并默认导出组装 Provider、运行时叶子headless、PopupHost//ToastHost/兄弟节点L3按语义命名不加后缀、不发明...AppShellpreference 预热全 chrome 窗口用all轻量窗口精确列出首帧读取的键preboot 特例迁移类不走此流程运行时归属mainsubWindow 共有且一致 →useWindowRuntimemain-only →MainWindowRuntime或对应窗口自己的叶子轻量窗口只挂useLanguageSyncuseCustomCssscreenshot 例外运行时叶子位置Provider 内、所有 TabRouter/Activity之外Logger metaindex.html中声明唯一的logger-window-source字符串CSS 副作用按需保留在入口轻量窗口考虑最小化参考 toolbar 省略index.css。窗口的创建、生命周期、池化机制与 init-data 投递由主进程负责参见 docs/references/window-manager/README.md窗口如何读取初始化数据见 src/renderer/hooks/useWindowInitData.ts。【免费下载链接】cherry-studioAI productivity studio with smart chat, autonomous agents, and 300 assistants. Unified access to frontier LLMs项目地址: https://gitcode.com/GitHub_Trending/ch/cherry-studio创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Cherry Studio 渲染进程窗口架构指南：三层入口约定、prepareWindow 预热与窗口运行时设计
Cherry Studio 渲染进程窗口架构指南三层入口约定、prepareWindow 预热与窗口运行时设计【免费下载链接】cherry-studioAI productivity studio with smart chat, autonomous agents, and 300 assistants. Unified access to frontier LLMs项目地址: https://gitcode.com/GitHub_Trending/ch/cherry-studio本篇技术指南围绕 Cherry Studio 渲染进程renderer的多窗口体系展开基于 src/renderer/windows/README.md 梳理其统一的三层入口约定entryPoint → App → 业务组件、prepareWindow首帧预热机制、窗口级运行时runtime leaf的归属规则以及声明式 Logger 窗口来源标注。读完你将掌握如何为 Cherry Studio 新增一个渲染窗口而不破坏 Fast Refresh、主题闪烁theme flash的消除原理、main/subWindow 与轻量窗口在运行时职责上的分界以及为什么某些副作用必须挂在 Provider 内、Tab 路由之外的叶子节点上。一、渲染进程多窗口体系总览Cherry Studio 的渲染进程并不是单个 React 应用而是由多个独立 BrowserWindow 构成的多窗口体系。每个窗口都是一个独立的 HTML 入口 React 应用目录结构如下每个子目录即一个窗口src/renderer/windows/ ├── main/ # 主窗口 ├── subWindow/ # 子窗口如独立标签页窗口 ├── quickAssistant/ # 快捷助手 ├── migrationV2/ # v2 数据迁移preboot 特例 ├── userDataRelocation/ # 用户数据迁移preboot 特例 ├── selection/ │ ├── action/ # 划词操作窗口 │ └── toolbar/ # 划词工具栏 ├── screenshot/ # 截图窗口 ├── prepareWindow.ts # 共享 L1 序言 └── README.md所有窗口遵循完全一致的三层结构约定这一约定既是代码组织规范也是工程性能Fast Refresh与首帧渲染体验无主题闪烁的设计基础。二、三层入口约定entryPoint → App → 业务 UI2.1 三层职责划分层文件职责规则L1entryPoint.tsx引导副作用导入样式、await prepareWindow(...)、createRoot().render(XxxApp /)固定文件名。不定义任何组件——只挂载一个组件L2XxxApp.tsxProvider 根Provider/QueryClientProvider/ThemeProvider等。可挂载一个内部运行时叶子节点组合该窗口聚焦的初始化 hookslocale / custom-CSS / background / fullscreen 等并将弹窗/Toast 宿主PopupHost//ToastHost/作为兄弟叶子挂载固定名称WindowNameApp默认导出由 L1 挂载L3不固定窗口的实际 UI按语义命名——无强制后缀index.html中的script src指向该窗口的entryPoint.tsx。以主窗口为例src/renderer/windows/main/index.html 第 43 行script typemodule src/windows/main/entryPoint.tsx/script而 src/renderer/windows/main/entryPoint.tsx 完整体现了 L1 的职责边界import renderer/assets/styles/index.css import renderer/assets/styles/tailwind.css import { createRoot } from react-dom/client import { prepareWindow } from renderer/windows/prepareWindow import MainApp from ./MainApp await prepareWindow({ preference: all }) const root createRoot(document.getElementById(root) as HTMLElement) root.render(MainApp /)注意 L1 中只有三类内容样式副作用导入、prepareWindow预热、createRoot().render()。没有组件定义、没有业务逻辑。2.2 为什么要把 L1 与 L2 拆开Fast Refresh 边界文档给出了明确的工程理由在模块顶层调用createRoot().render()的模块不是 React Fast Refresh 边界编辑它会导致整页重新加载。因此entryPoint.tsx保持极简几乎不被触碰组件放在独立的XxxApp.tsx纯组件模块中UI 编辑可以热替换hot-swap只有极少修改的entryPoint.tsx才会触发整页 reload。这是开发体验DX层面的关键设计多窗口体系下每个窗口都是独立的 HTML 页面若入口文件包含了大量组件代码任何 UI 改动都会触发该窗口整页刷新破坏开发效率。2.3 L3 命名约束语义化而非后缀化L3 的命名不属于约定的一部分——请按语义命名永远不要加后缀。尤其注意不要发明新的...AppShell名字。AppShell是共享布局组件族的特定名称src/renderer/components/layout/AppShell 及AppShellTabBar不是通用的内容后缀。从 src/renderer/windows/main/MainApp.tsx 可见主窗口的 L3 直接复用共享布局AppShell子窗口则使用自己的 src/renderer/windows/subWindow/SubWindowAppShell.tsx——这些都是共享布局族的具体成员而非通用命名模式。三、prepareWindow首帧预热消灭主题闪烁prepareWindow.ts是所有窗口的共享 L1 序言位于 src/renderer/windows/prepareWindow.ts。其核心 APIexport async function prepareWindow(options: PrepareWindowOptions): Promisevoid interface PrepareWindowOptions { /** 首帧读取的偏好键 —— all 表示预热整个缓存 */ preference: all | UnifiedPreferenceKeyType[] }3.1 工作原理export async function prepareWindow(options: PrepareWindowOptions): Promisevoid { // 生产环境为 no-op在首次 DataApi 请求前暴露 DevTools 控制面 DataApiDevtools.exposeControlSurface() const preferencesWarm options.preference all ? preferenceService.preloadAll() : preferenceService.preload(options.preference) await Promise.all([initI18n(), preferencesWarm]) }关键语义在首次渲染之前初始化 i18n 并预热偏好缓存使usePreference在第一帧就读到已保存的值而不是回退到默认值——这就是**无主题闪烁no theme flash**的来源源码注释明确称之为 the source of the theme flash。两条偏好预热路径都是 best-effort 且永不 reject预热失败会降级为默认值并依赖usePreference的按需自愈lazy per-key self-heal。DataApiDevtools.exposeControlSurface()在首个await之前同步执行确保 payload 捕获在任何事件被记录前就已启用。3.2 all 与按键列表两种模式的取舍窗口类型preference 参数说明main/subWindowall预热完整缓存仅需一次内存内 IPC 拉取轻量窗口quickAssistant/selection-action/selection-toolbar/screenshot精确按键列表只预热首帧实际读取的键最小化开销migrationV2/userDataRelocation不调用preboot 特例自带 i18n、无偏好保持独立轻量窗口的按键列表是逐窗口手工枚举的。例如快捷助手窗口 src/renderer/windows/quickAssistant/entryPoint.tsx 预热了 9 个键await prepareWindow({ preference: [ app.language, ui.custom_css, ui.theme_mode, ui.theme_user.color_primary, ui.window_style, feature.quick_assistant.assistant_id, feature.quick_assistant.model_id, chat.default_model_id, feature.quick_assistant.read_clipboard_at_startup ] })划词工具栏 src/renderer/windows/selection/toolbar/entryPoint.tsx 则预热 6 个键语言、自定义 CSS、主题、主色、紧凑模式、动作项。新增窗口时必须精确列出其首帧读取的偏好键而不是图省事用all或漏掉某个键——前者浪费 IPC 开销后者会导致首帧读到默认值。3.3 测试验证src/renderer/windows/tests/prepareWindow.test.ts 用 4 个用例锁定了这些契约preference: all时只调preloadAll不调preload且initI18n被调用按键列表时精确调用preload([ui.theme_mode, app.language])不调preloadAllDevTools 控制面在首个await之前同步暴露prepareWindow只有在 i18n 与偏好预热都完成后才 resolve对两个 Promise 分别手动控制 resolve 时机进行断言。这说明Promise.all([initI18n(), preferencesWarm])的两者皆备才放行渲染语义是有测试保障的。四、窗口运行时叶子节点Runtime Leaf副作用归属的关键决策4.1 为什么需要独立于 Tab 的运行时叶子窗口级的副作用订阅、必须存活整个窗口生命周期的 DOM 同步应放在 L2XxxApp挂载的一个小运行时叶子组件中且位置在Provider 内部、所有TabRouter/Activity之外。原因隐藏的Activity子树会销毁 effects——任何挂在 tab 下的订阅在 tab 进入后台时都会丢失。该叶子组件是headless的只跑 hooks、渲染nullPopup/Toast 宿主则作为 App JSX 中显式的兄弟节点挂载因此窗口的宿主组合在 JSX 中清晰可见。4.2 全 chrome 窗口useWindowRuntimemain与subWindow都调用useWindowRuntime()——共享的窗口运行时定义在 src/renderer/hooks/useWindowRuntime.ts。其职责清单源码逐条可见locale 同步useLanguageSync()轻量窗口也复用 dayjs locale 设置仅渲染本地化日期的窗口需要custom CSSuseCustomCss()轻量窗口也复用逐字使用同一 CSS根背景macOS 透明窗口用 vibrancy 感知的背景color-mix(in srgb, var(--background) 55%, transparent)其他窗口用var(--sidebar)app 路径快照mount 时通过ipcApi.request(app.get_info)把homePath写入内联文件路径基址、resourcesPath写入缓存非阻塞、失败仅记日志全屏处理Windows 进入全屏时弹提示 Toastwindow.fullscreen_changedIPC 订阅useIpcOn卸载时自动清理ESC 退出全屏受shortcut.app.fullscreen.exit偏好门控纯按键、无修饰键时生效主题/Agent 自动重命名同步useTopicAutoRenameSync/useAgentSessionAutoRenameSync每个 BrowserWindow 有独立的 SWR 缓存所以各自保留失效逻辑MiniApp 启动器列表收敛IPC 侧写入后每个窗口恰好同步一次且在Activity之外。成员的严格规则某个关注点只有 main 与 subWindow都以完全相同方式需要才归属useWindowRuntime。它不接收配置、不包含任何 main-only 行为因此不可能隐藏窗口间的差异——这正是它与已退役的useAppInit大杂烩grab-bag之间的分界线。4.3 Main-only 关注点MainWindowRuntimeMain-only 的关注点明确放在 src/renderer/windows/main/MainApp.tsx 中的MainWindowRuntime内显式排除在useWindowRuntime之外启动 spinner 移除 init计时器结束与只有main/index.html创建的标记配对#spinner元素、console.time(init)绝不能在别的窗口运行useAppUpdateHandler更新事件只到达主窗口useAutoBackupEvents自动备份事件useStorageMonitorNotification、useTopicNamingErrorNotification面向主窗口的 Toast不能跨窗口重复。这些是刻意保持为 React hooks 的它们依赖 React 可见的 cache/toast 状态并自行管理 effect 清理而 renderer 没有服务生命周期容器若做成 service 只会引入手工 start/stop。对照子窗口 src/renderer/windows/subWindow/SubWindowApp.tsxSubWindowRuntime只调用useWindowRuntime() 注册 image-mode 弹窗完全没有Main-only 关注点——两个窗口运行时组合的差异一目了然。4.4 轻量窗口只取公共 hooks不用完整运行时quickAssistant/selection-action/selection-toolbar/screenshot不使用useWindowRuntime它们不渲染本地化日期、无 chrome。它们改为挂载useLanguageSync 与全 chrome 窗口逐字相同的 custom CSS。useLanguageSyncsrc/renderer/hooks/useLanguageSync.ts与useCustomCss之所以是独立 hooks正是因为轻量窗口要复用它们。useLanguageSync的注释澄清了职责边界初始语言已由prepareWindow的initI18n()应用该 hook 只响应运行时的偏好变化它刻意不碰 dayjs locale——日期本地化是独立关注点仅在useWindowRuntime中为渲染本地化日期的窗口main/subWindow同步。唯一的例外是screenshot它是像素对齐的全屏画布用户自定义 CSS 若改变了布局会让选区与实际截取的屏幕区域错位因此它不使用 custom CSS 那一半。4.5 两条硬性规则不要把 main-only 行为塞进useWindowRuntime窗口间差异需要用配置标志来掩盖——这就是坏味道不要把非首帧的工作推进prepareWindow首帧预热只负责第一帧就拿到值不应承担运行期初始化。五、Logger 窗口来源声明式 meta而非命令式调用每个窗口在index.html中声明式地标注其 logger 来源而不是在entryPoint.tsx里调用meta namelogger-window-source contentmainWindow /LoggerService构造时读取该 meta。src/renderer/windows/main/index.html 第 6 行与 src/renderer/windows/selection/toolbar/index.html 第 6 行分别声明了mainWindow与SelectionToolbar。这一设计的优势meta在任何模块脚本运行前就被解析因此在任何 import-time 日志之前来源就已确定——entryPoint.tsx里不需要任何排序规则也不需要每个窗口单独的initLogger副作用模块新增窗口时必须使用唯一的 source 字符串复用已有字符串会把两个窗口的日志混在一起无文档上下文如 workers改用loggerService.initWindowSource(Worker)它会覆盖meta 推导的值。完整机制参见 docs/references/logging/README.md。六、各窗口一览窗口L2 根L3 内容mainMainAppsrc/renderer/components/layout/AppShell共享subWindowSubWindowAppSubWindowAppShellquickAssistantQuickAssistantAppHomeWindowmigrationV2MigrationApp组件内src/renderer/windows/migrationV2/componentsuserDataRelocationRelocationApp组件内进度/恢复 UIselection/actionSelectionActionAppActionWindowselection/toolbarSelectionToolbarAppSelectionToolbar设置页也复用screenshotScreenshotAppCaptureOverlay每个显示器一个池化窗口6.1 特例窗口说明migrationV2 / userDataRelocationpreboot 特例自带 i18n各自的i18n/index.ts、locales.ts、resolver.ts不读取偏好保持独立运行——这也是它们不经过标准prepareWindow流程的原因。selection/toolbar刻意省略index.css字体 / markdown / 聊天样式保持最轻量窗口的最小体积其index.html还内联了一段强制透明背景、禁用选中的样式确保悬浮工具栏形态正确。CSS 副作用导入按入口保持独立这是规范而非例外。6.2 轻量窗口的 Redux 取舍quickAssistant是值得注意的工程决策实例它刻意不挂 ReduxProvidersrc/renderer/windows/quickAssistant/QuickAssistantApp.tsx 注释明确说明。其下游 assistant/model 数据已来自 v2 Preference DataApi 层usePreference、useQuery(/models/:id)不依赖 Redux rehydration因此也不需要PersistGate。同时它采用双层 ErrorBoundary外层包裹所有 ProviderProvider 渲染抛错时回退到无上下文的致命 fallback 而非白屏内层只包裹 L3 内容——AI 输出可能格式错误内容崩溃时显示主题化错误卡片而窗口运行时与 popup/toast 宿主内层边界之外的兄弟节点继续运行。七、新增一个窗口的检查清单综合文档约定与源码实现为 Cherry Studio 新增渲染窗口时应逐项核对目录在src/renderer/windows/下按窗口名建子目录含entryPoint.tsx、XxxApp.tsx、index.htmlL1entryPoint.tsx只做样式副作用导入 await prepareWindow(...)createRoot().render(XxxApp /)不定义组件L2XxxApp.tsx固定命名WindowNameApp并默认导出组装 Provider、运行时叶子headless、PopupHost//ToastHost/兄弟节点L3按语义命名不加后缀、不发明...AppShellpreference 预热全 chrome 窗口用all轻量窗口精确列出首帧读取的键preboot 特例迁移类不走此流程运行时归属mainsubWindow 共有且一致 →useWindowRuntimemain-only →MainWindowRuntime或对应窗口自己的叶子轻量窗口只挂useLanguageSyncuseCustomCssscreenshot 例外运行时叶子位置Provider 内、所有 TabRouter/Activity之外Logger metaindex.html中声明唯一的logger-window-source字符串CSS 副作用按需保留在入口轻量窗口考虑最小化参考 toolbar 省略index.css。窗口的创建、生命周期、池化机制与 init-data 投递由主进程负责参见 docs/references/window-manager/README.md窗口如何读取初始化数据见 src/renderer/hooks/useWindowInitData.ts。【免费下载链接】cherry-studioAI productivity studio with smart chat, autonomous agents, and 300 assistants. Unified access to frontier LLMs项目地址: https://gitcode.com/GitHub_Trending/ch/cherry-studio创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
