Cherry Studio 主进程架构详解src/main 的封闭目录体系、依赖方向与治理规则【免费下载链接】cherry-studioAI productivity studio with smart chat, autonomous agents, and 300 assistants. Unified access to frontier LLMs项目地址: https://gitcode.com/GitHub_Trending/ch/cherry-studioCherry Studio 的 Electron 主进程目录src/main/采用一套封闭的顶层分类体系closed top-level set每个目录只承载一类职责新能力必须对号入座而不得新开顶层目录。本文基于仓库的规范文档 Main Process Architecture 与当前源码完整讲解这 8 个顶层目录的职责边界、features与services的放置规则、依赖方向约束、logger/application两条环境基础设施例外、顶层目录的封闭治理以及主进程从 preboot 到 bootstrap 的真实启动链路帮助你在阅读或扩展该代码库时做出与项目约定一致的结构性决策。1. 顶层封闭集合8 个目录各自唯一的章程src/main/的顶层目录不是开放模块列表而是一个锁定locked的原则性分类集合每个目录只放一种东西、因一个独立理由占据顶层位置集合本身已锁定新增能力永远按其性质归入现有分类而不是获得新的顶层目录。当前实际的顶层布局与文档中的目录树一致src/main/ ├── main.ts # process entry: preboot → application.bootstrap() ├── ipc.ts # legacy IPC registration (being retired into ipc/) ├── core/ # business-agnostic app runtime (lifecycle/DI, paths, logger, window, scheduler/job, preboot, security) ├── ipc/ # IpcApi — the typed main↔renderer boundary ├── data/ # the data layer (DB/Cache/Preference/DataApi/BootConfig, schemas, migration) ├── ai/ # the AI subsystem — the products core domain ├── features/ # business domains, one dir each (each bundles its own services/utils) ├── services/ # business feature services (single file, or a subdirectory) ├── utils/ # cross-domain stateless helpers └── i18n/ # main-process locale catalog and resolver各目录的章程如下目录分类为什么值得一个顶层位置core应用运行时App runtime与业务无关、只关心让应用跑起来的基础设施。判定标准把core/原样搬去另一个 Electron 应用、换上别的业务代码就得到另一个应用。注意业务无关是必要不充分条件core只放应用不可移除的底座——可移除的能力即便必须在启动早期执行也要去services/。一种东西应用底座——生命周期/DI 容器、路径注册表、日志器、窗口管理器、调度器与任务、preboot、诊断、安全原语IPC 来源信任。ipc跨进程边界Electron 定义性的进程间通信机制特殊且重要到足以独立成层。IpcApischema router handler是已迁移领域的类型化边界根目录遗留的ipc.ts作为受跟踪的存量差距与它并存。data数据层通用业务数据存储——一等数据层故独立。承载 DbService / CacheService / PreferenceService / DataApiService / BootConfig、数据库 schema 以及 v1→v2 迁移器迁移器按设计要读取领域数据属于一次性迁移代码。ai核心领域Cherry Studio就是一个 AI 客户端AI 因此获得自己的顶层位置一切与 AI 本质相关的东西都在这里provider、中间件、MCP、agents、流管理器。它与shared/ai镜像对应。features领域模块业务领域一个领域一个目录。复杂领域在自己的目录内捆绑相关的 services / utils 等。services业务服务业务功能服务。简单服务是单个文件较大的组织成自己的子目录。utils无状态工具跨领域、无单一归属的无状态函数。门槛是无状态而非纯工具可以通过环境别名application/logger触达基础设施但它不持有状态、不产生对外副作用。i18n主进程本地化主进程自己的locales/目录与t()/getI18n()解析器。这是封闭集合一次有意的、受治理的扩充与src/renderer/i18n/镜像让每个进程拥有独立目录utils/i18n/的备选方案正是为了这种跨进程对称性而被否决。两个入口文件main.ts进程入口——先执行 preboot再application.bootstrap()因为index按命名规范保留给 barrel所以入口用了显式文件名和ipc.ts遗留 IPC 注册正在退役进ipc/。命名遵循命名规范 §4.9core/data/ai/ipc/i18n是单数命名空间features/services/utils是复数桶bucket。从源码看这套章程是真实落地的src/main 顶层 恰好是上述 8 个目录加两个入口文件core/下是application/、lifecycle/、paths/、logger/、window/、scheduler/、job/、preboot/、security/、utilityProcess/、power/等纯底座模块其 core/README 给出了同样的判定准则——如果一个模块移除后应用无论做什么功能都会坏它属于core/如果只会坏某个具体功能它属于别处如services/、data/。features/下当前有apiGateway、fileProcessing、knowledge、miniApp四个多文件大领域与文档点名的例子knowledge、apiGateway、fileProcessing完全吻合。2.features与services同一类东西的两个尺寸services/和features/本质是同一类东西——业务逻辑——只是尺寸不同。划分遵循跨进程命名规范§4.10晋升而非默认——且分步进行。一个小的自包含服务最初是桶根目录下的单文件services/TopicService.ts有状态的Service/Manager类是与其类名一致的PascalCase通用辅助工具是utils/topic.ts——主题专属的辅助则内联直到下面的子目录步骤。当单个文件装不下时先原地生长为camelCase主题子目录——services/topic/内含TopicService.ts及其辅助文件——而不是直接升格为 feature。注意形状目录是主题名不带Service后缀命名规范 §4.5只有类文件保留后缀例如 WebSearchService。只有当它长大为一个大型多文件领域、需要捆绑自己的 services、utils 和辅助时才获得features/domain/的位置如 knowledge、apiGateway、fileProcessing。不要为预期中的模块预先创建子目录或 feature。ai/不是普通 feature。它是产品的核心领域有自己的顶层位置§1它是基础性的不是众多领域之一。按角色路由命名规范 §5.2持有长生命周期资源或持久副作用的有状态类 → 生命周期Service见 Lifecycle Reference无状态模块 → 默认utils/仅因对外副作用或被迫向上的依赖才晋升到services/§5.2 路由表大领域 →features/domain/。读操作从不晋升——为查询而触达基础设施的辅助仍是辅助。仓库中可以看到这条阶梯的完整形态services/根下有ThemeService.ts、TrayService.ts、ShortcutService.ts等单文件服务webSearch/、oauth/、codeCli/、proxy/等是主题子目录各自以index.ts暴露而features/knowledge/、features/apiGateway/则是捆绑了完整内部结构的领域模块。2.1 子目录与 Barrel单个.ts文件是默认形态只有主题实际拥有多个文件时才升级为子目录。Barrel 遵循命名规范 §6.4跨进程权威此处应用于services/和utils/桶根目录services/和utils/没有index.ts。桶是分类不是模块——导入具体文件或主题永远不导入整个桶。services/topic/子目录恰好有一个index.ts作为其公共 API显式命名导出不用export *其余文件对它保持私有。复杂的utils/topic/子目录同样只有一个index.ts。为什么每个主题都只通过一个公共入口被导入——就像单文件模块一样——内部文件保持私有消费者永不深导。对utils/来说文件与目录共享主题名因此当文件长成目录时导入规格main/utils/topic甚至不变。features/domain/是同一单入口思想高一层级的应用消费者通过它的唯一公共入口导入领域而非其内部文件。2.2 服务如何接入生命周期serviceRegistry 实证业务目录里的服务最终都汇入生命周期系统。serviceRegistry.ts 是集中式服务注册表所有需要 DI 管理的类DbService、AiService、KnowledgeService、WindowManager、IpcApiService等 70 余个都登记在services常量对象中注释明确要求由生命周期系统管理的服务不应导出单例实例主进程代码通过application.get(ServiceName)访问服务只导出类用于类型引用。ServiceRegistry类型由typeof services自动推导serviceList则供Application.registerAll()使用——这正是第 3 节application.get()而非直接导入规则的类型安全底座。3. 依赖方向一切流向业务无关的底座章程隐含方向依赖流向业务无关的基础基础层Foundation——core/与utils/不携带业务认知它们之下不存在任何业务代码。数据层Data layer——data/是位于基础之上的存储层。业务层Business——ai/、features/、services/是业务层它们向下依赖data/、core/、utils/。ai/在业务层内部是基础性的features/和services/可以依赖它它不得导入任何 feature。feature 领域之间相互隔离features/domain/不得导入兄弟feature——共享应通过services/、ai/、data/或shared完成。ipc/是边界适配器handler 保持薄边界策略 IpcError映射 委托通过两种方式触达业务代码——生命周期服务注册在serviceRegistry.ts经application.get(XxxService)解析绝不直接导入非生命周期模块无状态主题 barrel 或直接导入的单例经其 curated 入口导入而为了拿 DI 句柄去虚构一个生命周期服务是反模式。参见 Handler: Pure Function vs Service Delegate。禁止导入 renderersrc/main与src/preload不得导入渲染进程代码。跨进程类型放shared仅主进程用的类型留在src/main——放置规则见 Shared Layer Architecture。由 ESLintno-restricted-imports规则强制禁止src/mainsrc/preload中出现renderer§7 跟踪唯一的剩余例外。这个强制项在仓库中可以直接验证eslint.config.mjs 中有一个专门作用于src/main/**与src/preload/**的配置块注释写明边界守卫主进程和 preload 不得导入渲染进程代码跨进程符号属于shared仅主进程符号在src/main规则typescript-eslint/no-restricted-imports引用了BAN_RENDERER_FROM_MAIN模式同样的禁令还被复制到 utility process 子进程入口文件的 child-safe zone 配置块中。有两条依赖横切所有目录但它们不是分层边而是环境基础设施访问logger日志和applicationDI 容器/服务定位器。一次原始导入扫描会显示几乎所有东西都依赖core原因只是这两个别名上文规则只涉及领域之间的直接模块导入。从源码结构看内部方向边目前没有自动化强制不同于为 renderer 提出的import/no-restricted-paths分区见 Renderer Architecture §5——方向由约定与评审维持而外部main↔renderer 边界禁 renderer 导入则是被强制的即上文的 ESLint 规则。3.1 边界适配器的实现证据IpcApiServiceIpcApiService.ts 精确体现了边界适配器保持薄的章程它的类注释自称纯传输管pure transport plumbing全部业务逻辑和资源生命周期都留在它所委托的各领域服务中。它拥有单个IpcApi_Requesthandler先做来源信任门validateSender来自core/security/未信任发送者得到FORBIDDEN_SENDER错误与审计日志再经IpcRouter.dispatch按 zod schemashared/ipc/schemas路由与校验最后把异常序列化为结构化IpcError返回——绝不向ipcMain.handlethrow。它通过Injectable(IpcApiService)ServicePhase(Phase.BeforeReady)在 Bootstrap 的 BeforeReady 阶段注册保证任何窗口打开前 handler 已就绪。而根目录的 ipc.ts约 9.8KB 的遗留单体注册仍在并存——这正是 §7 记录的target vs current差距。4. 封闭顶层治理新增目录出局顶层集合封闭且锁定——把在src/main/下新增目录视为出局选项。这是 命名规范 §4.8顶层默认封闭的严格端§4.8 只承认在证明必要性现有分类无法容纳这些文件与完备性的前提下新增顶层目录而 main 的分类已经覆盖整个空间——因此新能力被路由进现有分类永远不给自己的目录。唯一有意的扩充是i18n/§1为使主进程拥有与src/renderer/i18n/对称的本地化目录它是带记录理由的受治理例外不是规则松动。renderer§6 与shared§2 的顶层受同等治理约束。新能力从不获得新顶层目录按性质路由该能力是……归属与 AI 本质相关ai/业务数据 / 存储data/一条 IPC 路由ipc/IpcApi业务无关、不可移除的应用运行时基础设施core/业务服务services/——若它是大型多文件领域则features/domain/纯的、领域无关的逻辑utils/5. 反模式清单规范明确列出以下反模式把业务代码任何 Cherry Studio做什么所特有的东西放进core/——core/必须只保留应用运行时。features/domain/导入兄弟feature跨领域耦合。ai/导入features/核心领域向上依赖一个 feature。为单一能力新开顶层目录§4。用临时存储散布业务数据绕过data/子系统或用临时通道走命令式调用绕过ipc/的 IpcApi。6. 启动链路实证main.ts 如何兑现目录职责规范文档描述的是目标态而 main.ts 展示了这套目录分工在真实启动序列中如何咬合——其头部注释开宗明义不要在这里添加新代码。如果你有这个冲动你几乎肯定误解了启动时序或服务架构。新服务属于生命周期系统见core/lifecycle/不可移除的 preboot 步骤属于core/preboot/需要在 preboot 期执行的可移除能力属于其性质归属地如services/并从这里被调用。本文件是胶水——它只该变小。实际序列与文档分工一一对应preboot同步、先于 bootstrapresolveUserDataLocation()core/preboot/→requireSingleInstance()→configureChromiumFlags()→initCrashTelemetry()→ 声明特权 schemeCHERRY_MEDIA_SCHEME_DECLARATION来自services/mediaProtocolMINI_APP_SCHEME_DECLARATION来自features/miniApp/——注意可移除能力确实住在自己的性质归属地只是被入口胶水调用→application.initPathRegistry()冻结路径注册表core/paths/。bootstrapstartApp()内先跑可移除的早期能力——runDataReset()services/dataReset、runUserDataRelocation()services/userDataRelocation/、备份恢复门与 v2 迁移门core/preboot/的门 data/migration/的领域读取随后application.registerAll(serviceList)application.bootstrap()在app.whenReady()并行运行生命周期阶段Background / BeforeReady / WhenReady。runningbootstrapPromise落地后记录版本services/VersionService再执行遗留的registerIpc()——注释坦承它造成 bootstrap 与 IPC 就绪之间的时序耦合标注TODO(v2): decompose into per-service ipcHandle/ipcOn inside lifecycle services即 §7 所跟踪差距的现场。兜底顶层startApp().catch(...)仅在bootstrap()未处理的意外错误上触发执行application.forceExit(1)。这与 core/README 的三阶段术语表preboot / bootstrap / runninglifecycle 阶段运行在 bootstrap内部及 §1 中core只放不可移除底座、可移除的早期执行能力去services/的判定规则完全一致。7. 子系统参考地图各子系统的深度文档独立存在主进程架构页只负责目录布局。规范文档给出的参考地图已转为仓库根相对路径子系统位置参考文档服务生命周期IoC、分阶段 bootstrapcore/lifecycle/、core/application/Lifecycle Reference启动阶段preboot / bootstrap / runningcore/preboot/、core/application/core/README窗口管理器core/window/Window Manager ReferenceUtility 进程崩溃隔离的 workercore/utilityProcess/Utility Process Reference调度器与任务core/scheduler/、core/job/Job Scheduler Reference路径注册表core/paths/paths/READMEIPC 来源信任门validateSendercore/security/IpcApi Overview §Security数据系统DB/Cache/Preference/DataApi/BootConfigdata/Data System ReferenceIPCIpcApiipc/IPC ReferenceAI 子系统ai/AI Reference8. 当前偏差target vs current文档描述的是目标态。当前代码与目标态不符时差距在 §7 被跟踪——该页不改动任何代码。只列结构性偏差封闭顶层集合 §4、桶 barrel §2.1、放置 §2逐文件的命名后缀审计§5.2不在范围。领域现状目标遗留ipc.tsv1 IPC 注册位于进程根与 IpcApi 并存各领域增量迁移进ipc/IpcApi直至ipc.ts退役§1设计内by-design的边不是偏差被刻意省略data/migration/v2/迁移器读取领域数据§1以及任意层通过logger/application的环境访问§3。9. 小结与延伸阅读src/main/的 8 个顶层目录构成封闭锁定集合i18n/是唯一有记录的受治理扩充新能力按 §4 路由表对号入座。services/→services/topic/→features/domain/是一条尺寸晋升阶梯桶根无index.ts、主题子目录恰好一个index.ts。依赖向下汇聚到core/utils/ai/是业务层内基础feature 间隔离ipc/保持薄并以application.get()取生命周期服务logger/application是横切的环境例外而非分层边。main↔renderer 边界由 ESLint 强制eslint.config.mjs内部方向边当前靠约定与评审。唯一已跟踪的结构性差距是根目录遗留ipc.ts其退役路径由 IpcApi 迁移指南 覆盖。延伸阅读Architecture Overview进程模型、数据流、monorepo 树本文档的跨进程父级、Renderer Architecture 与 Shared Layer Architecture同级各进程目录参考、Naming Conventions§4.8 顶层封闭、§4.9 单数/复数、§4.10 feature 与类型桶、§5.2 按形状路由。【免费下载链接】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 主进程架构详解：src/main 的封闭目录体系、依赖方向与治理规则
Cherry Studio 主进程架构详解src/main 的封闭目录体系、依赖方向与治理规则【免费下载链接】cherry-studioAI productivity studio with smart chat, autonomous agents, and 300 assistants. Unified access to frontier LLMs项目地址: https://gitcode.com/GitHub_Trending/ch/cherry-studioCherry Studio 的 Electron 主进程目录src/main/采用一套封闭的顶层分类体系closed top-level set每个目录只承载一类职责新能力必须对号入座而不得新开顶层目录。本文基于仓库的规范文档 Main Process Architecture 与当前源码完整讲解这 8 个顶层目录的职责边界、features与services的放置规则、依赖方向约束、logger/application两条环境基础设施例外、顶层目录的封闭治理以及主进程从 preboot 到 bootstrap 的真实启动链路帮助你在阅读或扩展该代码库时做出与项目约定一致的结构性决策。1. 顶层封闭集合8 个目录各自唯一的章程src/main/的顶层目录不是开放模块列表而是一个锁定locked的原则性分类集合每个目录只放一种东西、因一个独立理由占据顶层位置集合本身已锁定新增能力永远按其性质归入现有分类而不是获得新的顶层目录。当前实际的顶层布局与文档中的目录树一致src/main/ ├── main.ts # process entry: preboot → application.bootstrap() ├── ipc.ts # legacy IPC registration (being retired into ipc/) ├── core/ # business-agnostic app runtime (lifecycle/DI, paths, logger, window, scheduler/job, preboot, security) ├── ipc/ # IpcApi — the typed main↔renderer boundary ├── data/ # the data layer (DB/Cache/Preference/DataApi/BootConfig, schemas, migration) ├── ai/ # the AI subsystem — the products core domain ├── features/ # business domains, one dir each (each bundles its own services/utils) ├── services/ # business feature services (single file, or a subdirectory) ├── utils/ # cross-domain stateless helpers └── i18n/ # main-process locale catalog and resolver各目录的章程如下目录分类为什么值得一个顶层位置core应用运行时App runtime与业务无关、只关心让应用跑起来的基础设施。判定标准把core/原样搬去另一个 Electron 应用、换上别的业务代码就得到另一个应用。注意业务无关是必要不充分条件core只放应用不可移除的底座——可移除的能力即便必须在启动早期执行也要去services/。一种东西应用底座——生命周期/DI 容器、路径注册表、日志器、窗口管理器、调度器与任务、preboot、诊断、安全原语IPC 来源信任。ipc跨进程边界Electron 定义性的进程间通信机制特殊且重要到足以独立成层。IpcApischema router handler是已迁移领域的类型化边界根目录遗留的ipc.ts作为受跟踪的存量差距与它并存。data数据层通用业务数据存储——一等数据层故独立。承载 DbService / CacheService / PreferenceService / DataApiService / BootConfig、数据库 schema 以及 v1→v2 迁移器迁移器按设计要读取领域数据属于一次性迁移代码。ai核心领域Cherry Studio就是一个 AI 客户端AI 因此获得自己的顶层位置一切与 AI 本质相关的东西都在这里provider、中间件、MCP、agents、流管理器。它与shared/ai镜像对应。features领域模块业务领域一个领域一个目录。复杂领域在自己的目录内捆绑相关的 services / utils 等。services业务服务业务功能服务。简单服务是单个文件较大的组织成自己的子目录。utils无状态工具跨领域、无单一归属的无状态函数。门槛是无状态而非纯工具可以通过环境别名application/logger触达基础设施但它不持有状态、不产生对外副作用。i18n主进程本地化主进程自己的locales/目录与t()/getI18n()解析器。这是封闭集合一次有意的、受治理的扩充与src/renderer/i18n/镜像让每个进程拥有独立目录utils/i18n/的备选方案正是为了这种跨进程对称性而被否决。两个入口文件main.ts进程入口——先执行 preboot再application.bootstrap()因为index按命名规范保留给 barrel所以入口用了显式文件名和ipc.ts遗留 IPC 注册正在退役进ipc/。命名遵循命名规范 §4.9core/data/ai/ipc/i18n是单数命名空间features/services/utils是复数桶bucket。从源码看这套章程是真实落地的src/main 顶层 恰好是上述 8 个目录加两个入口文件core/下是application/、lifecycle/、paths/、logger/、window/、scheduler/、job/、preboot/、security/、utilityProcess/、power/等纯底座模块其 core/README 给出了同样的判定准则——如果一个模块移除后应用无论做什么功能都会坏它属于core/如果只会坏某个具体功能它属于别处如services/、data/。features/下当前有apiGateway、fileProcessing、knowledge、miniApp四个多文件大领域与文档点名的例子knowledge、apiGateway、fileProcessing完全吻合。2.features与services同一类东西的两个尺寸services/和features/本质是同一类东西——业务逻辑——只是尺寸不同。划分遵循跨进程命名规范§4.10晋升而非默认——且分步进行。一个小的自包含服务最初是桶根目录下的单文件services/TopicService.ts有状态的Service/Manager类是与其类名一致的PascalCase通用辅助工具是utils/topic.ts——主题专属的辅助则内联直到下面的子目录步骤。当单个文件装不下时先原地生长为camelCase主题子目录——services/topic/内含TopicService.ts及其辅助文件——而不是直接升格为 feature。注意形状目录是主题名不带Service后缀命名规范 §4.5只有类文件保留后缀例如 WebSearchService。只有当它长大为一个大型多文件领域、需要捆绑自己的 services、utils 和辅助时才获得features/domain/的位置如 knowledge、apiGateway、fileProcessing。不要为预期中的模块预先创建子目录或 feature。ai/不是普通 feature。它是产品的核心领域有自己的顶层位置§1它是基础性的不是众多领域之一。按角色路由命名规范 §5.2持有长生命周期资源或持久副作用的有状态类 → 生命周期Service见 Lifecycle Reference无状态模块 → 默认utils/仅因对外副作用或被迫向上的依赖才晋升到services/§5.2 路由表大领域 →features/domain/。读操作从不晋升——为查询而触达基础设施的辅助仍是辅助。仓库中可以看到这条阶梯的完整形态services/根下有ThemeService.ts、TrayService.ts、ShortcutService.ts等单文件服务webSearch/、oauth/、codeCli/、proxy/等是主题子目录各自以index.ts暴露而features/knowledge/、features/apiGateway/则是捆绑了完整内部结构的领域模块。2.1 子目录与 Barrel单个.ts文件是默认形态只有主题实际拥有多个文件时才升级为子目录。Barrel 遵循命名规范 §6.4跨进程权威此处应用于services/和utils/桶根目录services/和utils/没有index.ts。桶是分类不是模块——导入具体文件或主题永远不导入整个桶。services/topic/子目录恰好有一个index.ts作为其公共 API显式命名导出不用export *其余文件对它保持私有。复杂的utils/topic/子目录同样只有一个index.ts。为什么每个主题都只通过一个公共入口被导入——就像单文件模块一样——内部文件保持私有消费者永不深导。对utils/来说文件与目录共享主题名因此当文件长成目录时导入规格main/utils/topic甚至不变。features/domain/是同一单入口思想高一层级的应用消费者通过它的唯一公共入口导入领域而非其内部文件。2.2 服务如何接入生命周期serviceRegistry 实证业务目录里的服务最终都汇入生命周期系统。serviceRegistry.ts 是集中式服务注册表所有需要 DI 管理的类DbService、AiService、KnowledgeService、WindowManager、IpcApiService等 70 余个都登记在services常量对象中注释明确要求由生命周期系统管理的服务不应导出单例实例主进程代码通过application.get(ServiceName)访问服务只导出类用于类型引用。ServiceRegistry类型由typeof services自动推导serviceList则供Application.registerAll()使用——这正是第 3 节application.get()而非直接导入规则的类型安全底座。3. 依赖方向一切流向业务无关的底座章程隐含方向依赖流向业务无关的基础基础层Foundation——core/与utils/不携带业务认知它们之下不存在任何业务代码。数据层Data layer——data/是位于基础之上的存储层。业务层Business——ai/、features/、services/是业务层它们向下依赖data/、core/、utils/。ai/在业务层内部是基础性的features/和services/可以依赖它它不得导入任何 feature。feature 领域之间相互隔离features/domain/不得导入兄弟feature——共享应通过services/、ai/、data/或shared完成。ipc/是边界适配器handler 保持薄边界策略 IpcError映射 委托通过两种方式触达业务代码——生命周期服务注册在serviceRegistry.ts经application.get(XxxService)解析绝不直接导入非生命周期模块无状态主题 barrel 或直接导入的单例经其 curated 入口导入而为了拿 DI 句柄去虚构一个生命周期服务是反模式。参见 Handler: Pure Function vs Service Delegate。禁止导入 renderersrc/main与src/preload不得导入渲染进程代码。跨进程类型放shared仅主进程用的类型留在src/main——放置规则见 Shared Layer Architecture。由 ESLintno-restricted-imports规则强制禁止src/mainsrc/preload中出现renderer§7 跟踪唯一的剩余例外。这个强制项在仓库中可以直接验证eslint.config.mjs 中有一个专门作用于src/main/**与src/preload/**的配置块注释写明边界守卫主进程和 preload 不得导入渲染进程代码跨进程符号属于shared仅主进程符号在src/main规则typescript-eslint/no-restricted-imports引用了BAN_RENDERER_FROM_MAIN模式同样的禁令还被复制到 utility process 子进程入口文件的 child-safe zone 配置块中。有两条依赖横切所有目录但它们不是分层边而是环境基础设施访问logger日志和applicationDI 容器/服务定位器。一次原始导入扫描会显示几乎所有东西都依赖core原因只是这两个别名上文规则只涉及领域之间的直接模块导入。从源码结构看内部方向边目前没有自动化强制不同于为 renderer 提出的import/no-restricted-paths分区见 Renderer Architecture §5——方向由约定与评审维持而外部main↔renderer 边界禁 renderer 导入则是被强制的即上文的 ESLint 规则。3.1 边界适配器的实现证据IpcApiServiceIpcApiService.ts 精确体现了边界适配器保持薄的章程它的类注释自称纯传输管pure transport plumbing全部业务逻辑和资源生命周期都留在它所委托的各领域服务中。它拥有单个IpcApi_Requesthandler先做来源信任门validateSender来自core/security/未信任发送者得到FORBIDDEN_SENDER错误与审计日志再经IpcRouter.dispatch按 zod schemashared/ipc/schemas路由与校验最后把异常序列化为结构化IpcError返回——绝不向ipcMain.handlethrow。它通过Injectable(IpcApiService)ServicePhase(Phase.BeforeReady)在 Bootstrap 的 BeforeReady 阶段注册保证任何窗口打开前 handler 已就绪。而根目录的 ipc.ts约 9.8KB 的遗留单体注册仍在并存——这正是 §7 记录的target vs current差距。4. 封闭顶层治理新增目录出局顶层集合封闭且锁定——把在src/main/下新增目录视为出局选项。这是 命名规范 §4.8顶层默认封闭的严格端§4.8 只承认在证明必要性现有分类无法容纳这些文件与完备性的前提下新增顶层目录而 main 的分类已经覆盖整个空间——因此新能力被路由进现有分类永远不给自己的目录。唯一有意的扩充是i18n/§1为使主进程拥有与src/renderer/i18n/对称的本地化目录它是带记录理由的受治理例外不是规则松动。renderer§6 与shared§2 的顶层受同等治理约束。新能力从不获得新顶层目录按性质路由该能力是……归属与 AI 本质相关ai/业务数据 / 存储data/一条 IPC 路由ipc/IpcApi业务无关、不可移除的应用运行时基础设施core/业务服务services/——若它是大型多文件领域则features/domain/纯的、领域无关的逻辑utils/5. 反模式清单规范明确列出以下反模式把业务代码任何 Cherry Studio做什么所特有的东西放进core/——core/必须只保留应用运行时。features/domain/导入兄弟feature跨领域耦合。ai/导入features/核心领域向上依赖一个 feature。为单一能力新开顶层目录§4。用临时存储散布业务数据绕过data/子系统或用临时通道走命令式调用绕过ipc/的 IpcApi。6. 启动链路实证main.ts 如何兑现目录职责规范文档描述的是目标态而 main.ts 展示了这套目录分工在真实启动序列中如何咬合——其头部注释开宗明义不要在这里添加新代码。如果你有这个冲动你几乎肯定误解了启动时序或服务架构。新服务属于生命周期系统见core/lifecycle/不可移除的 preboot 步骤属于core/preboot/需要在 preboot 期执行的可移除能力属于其性质归属地如services/并从这里被调用。本文件是胶水——它只该变小。实际序列与文档分工一一对应preboot同步、先于 bootstrapresolveUserDataLocation()core/preboot/→requireSingleInstance()→configureChromiumFlags()→initCrashTelemetry()→ 声明特权 schemeCHERRY_MEDIA_SCHEME_DECLARATION来自services/mediaProtocolMINI_APP_SCHEME_DECLARATION来自features/miniApp/——注意可移除能力确实住在自己的性质归属地只是被入口胶水调用→application.initPathRegistry()冻结路径注册表core/paths/。bootstrapstartApp()内先跑可移除的早期能力——runDataReset()services/dataReset、runUserDataRelocation()services/userDataRelocation/、备份恢复门与 v2 迁移门core/preboot/的门 data/migration/的领域读取随后application.registerAll(serviceList)application.bootstrap()在app.whenReady()并行运行生命周期阶段Background / BeforeReady / WhenReady。runningbootstrapPromise落地后记录版本services/VersionService再执行遗留的registerIpc()——注释坦承它造成 bootstrap 与 IPC 就绪之间的时序耦合标注TODO(v2): decompose into per-service ipcHandle/ipcOn inside lifecycle services即 §7 所跟踪差距的现场。兜底顶层startApp().catch(...)仅在bootstrap()未处理的意外错误上触发执行application.forceExit(1)。这与 core/README 的三阶段术语表preboot / bootstrap / runninglifecycle 阶段运行在 bootstrap内部及 §1 中core只放不可移除底座、可移除的早期执行能力去services/的判定规则完全一致。7. 子系统参考地图各子系统的深度文档独立存在主进程架构页只负责目录布局。规范文档给出的参考地图已转为仓库根相对路径子系统位置参考文档服务生命周期IoC、分阶段 bootstrapcore/lifecycle/、core/application/Lifecycle Reference启动阶段preboot / bootstrap / runningcore/preboot/、core/application/core/README窗口管理器core/window/Window Manager ReferenceUtility 进程崩溃隔离的 workercore/utilityProcess/Utility Process Reference调度器与任务core/scheduler/、core/job/Job Scheduler Reference路径注册表core/paths/paths/READMEIPC 来源信任门validateSendercore/security/IpcApi Overview §Security数据系统DB/Cache/Preference/DataApi/BootConfigdata/Data System ReferenceIPCIpcApiipc/IPC ReferenceAI 子系统ai/AI Reference8. 当前偏差target vs current文档描述的是目标态。当前代码与目标态不符时差距在 §7 被跟踪——该页不改动任何代码。只列结构性偏差封闭顶层集合 §4、桶 barrel §2.1、放置 §2逐文件的命名后缀审计§5.2不在范围。领域现状目标遗留ipc.tsv1 IPC 注册位于进程根与 IpcApi 并存各领域增量迁移进ipc/IpcApi直至ipc.ts退役§1设计内by-design的边不是偏差被刻意省略data/migration/v2/迁移器读取领域数据§1以及任意层通过logger/application的环境访问§3。9. 小结与延伸阅读src/main/的 8 个顶层目录构成封闭锁定集合i18n/是唯一有记录的受治理扩充新能力按 §4 路由表对号入座。services/→services/topic/→features/domain/是一条尺寸晋升阶梯桶根无index.ts、主题子目录恰好一个index.ts。依赖向下汇聚到core/utils/ai/是业务层内基础feature 间隔离ipc/保持薄并以application.get()取生命周期服务logger/application是横切的环境例外而非分层边。main↔renderer 边界由 ESLint 强制eslint.config.mjs内部方向边当前靠约定与评审。唯一已跟踪的结构性差距是根目录遗留ipc.ts其退役路径由 IpcApi 迁移指南 覆盖。延伸阅读Architecture Overview进程模型、数据流、monorepo 树本文档的跨进程父级、Renderer Architecture 与 Shared Layer Architecture同级各进程目录参考、Naming Conventions§4.8 顶层封闭、§4.9 单数/复数、§4.10 feature 与类型桶、§5.2 按形状路由。【免费下载链接】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），仅供参考