人工智能大模型AI 应用交互助手本地部署【免费下载链接】cherry-studio Cherry Studio 是一款支持多个 LLM 提供商的桌面客户端项目地址https://gitcode.com/CherryHQ/cherry-studio点击查看免费下载Cherry Studio 是一个基于 Electron 的多 LLM 提供商桌面客户端其源码划分为main主进程、renderer渲染进程、preload预加载桥与shared四个根目录。其中src/shared别名shared是跨进程原语层——承载跨进程共享的类型、契约与纯逻辑被主进程、渲染进程与预加载脚本共同导入。本文以 Shared Layer Architecture 为骨架结合仓库真实源码系统讲解shared的成员准入规则两条不变量、封闭的顶层目录集合、types与utils的形态划分、放置决策流程与反模式清单帮助你在 Cherry Studio 中正确判断某段代码是否属于shared、应放在哪个子目录。1.shared在分层架构中的位置在 Cherry Studio 的四层依赖模型中详见 Renderer Architectureshared与packages/ui一起位于最底层的Primitives第 4 层层目录角色1. App / compositionwindows/、routes/、顶层pages/入口、路由、应用壳2. Domain目标态features/domain/业务域纵向切片3. Sharedcomponents/→hooks//services/→utils//data//ipc//workers/跨域可复用件4. Primitivespackages/ui、shared、logger应用无关的基础层shared的特点在于它是跨进程的Electron 的 main 与 renderer 运行在各自的 V8 隔离环境realm中shared的模块在每个进程内各被加载一次因此它只允许导出类型、纯函数与不可变数据不能携带任何进程相关的运行时状态。它与面向单个进程的共享如 renderer 内部的components/、hooks/、services/的根本区别就是 Architecture Overview 中所说的src/shared/是cross-process primitive layer其准入门槛是跨进程而非恰好被多处使用。从源码看src/shared/当前实际只存在五个顶层目录与文档声明完全一致src/shared/ ├── ai/ # 核心领域AI 跨进程契约与纯逻辑 ├── data/ # 跨进程基础设施API 类型、Cache/Preference/BootConfig schema、migration 映射、presets ├── ipc/ # 跨进程基础设施IpcApi 框架define helpers、请求/事件 schema、错误模型、共享类型 ├── types/ # 形态桶无单一归属方的跨进程类型声明 ├── utils/ # 形态桶跨进程纯逻辑及其常量、类蓝图 └── IpcChannel.ts # v1 遗留 channel 枚举见 §6 待迁移项2. 两条不变量Invariants一切想进入shared的模块必须同时满足以下两条否则它就不属于这里。这两条是本文档的准入宪法也是理解shared全部规则的前提。2.1 不变量一跨进程Cross-process一个模块只有在main 与 renderer 两个进程都实际使用它时才属于shared——类型声明同样适用这条规则。原因shared是跨进程边界的唯一事实源single source of truth单进程代码本就有属于自己的进程层可以安放。只被一个进程可达→ 应放在该进程自己的层src/main/*或src/renderer/{utils,hooks,services}。禁止投机性放置no speculative placement如果某物只是可能会跨进程就先写在main/renderer待它真正跨进程时再移入shared。不要把代码预存在shared里等将来用——最常见的失败模式就是为以防万一加了一个类型或工具函数结果从未被跨进程使用最终沦为冗余cruft。2.1.1 唯一例外Cache schema 注册表Cache 子系统是 §2.1 的唯一豁免。所有 Cache 的key schema 与其 value 类型都必须放在shared/data/cache/cacheSchemas.tscacheValueTypes.ts无论由哪个进程消费——包括仅被渲染进程使用的类型如Tab、ChatScrollAnchor、AgentOpenExternalAppTarget等。源码中src/shared/data/cache/cacheSchemas.ts的头部注释印证了这一点它定义了 key 命名规范namespace.sub.key_name形式、模板 key${xxx}占位符、由 ESLint 规则data-schema-key/valid-key强制校验并统一从./cacheValueTypes引用值类型。也就是说一个渲染进程专用的 cache value 类型出现在这里属于合规行为而非 §2.1 违规——不要将其标记或迁移。豁免仅限 Cache 子系统其余一切位置仍适用 §2.1。2.2 不变量二无可变运行时状态No mutable runtime stateshared只导出类型、纯函数与不可变数据绝不导出类实例单例services / managers / registries也不导出任何持有运行时可变状态的模块级值。原因main 与 renderer 是相互隔离的 V8 realmshared模块每个进程加载一次。所谓共享单例是一个假象——它实际上会退化为 N 个互不同步的进程内实例。可变状态没有一致的共享归属者它应属于承载其生命周期与上下文的那个进程。new不是判定标准——运行时可变性 身份identity才是。new只被允许用于构建随后被冻结并导出的不可变数据例如由静态数据一次性构建、之后永不修改的Map/Set/RegExp查找表。仓库中src/shared/utils/command/definitions.ts的私有commandMapnew MapCommandId, RegisteredCommandDefinitionCommandId(...)正是文档点名的这类只读查找表实例。有状态类只从shared导出其定义蓝图实例则按进程创建。例如ContextKeyService的定义跨进程共享位于src/shared/utils/command/contextExpr.ts经src/shared/utils/command/index.ts导出但new ContextKeyService()的实例化发生在渲染进程的src/renderer/components/command/CommandContextKeyProvider.tsx中——蓝图在shared实例在进程内。准入对照表Allowed vs Banned允许Allowed禁止Bannedtype/interface/enum、schema 派生类型export const x new XService()任何导出的实例单例纯函数、谓词、转换器registry / manager / service 实例不可变数据——常量、定义、通过new Map/Set构建的冻结查找表任何持有运行时可变状态的模块级值有状态类的定义蓝图此类的一个活着的实例3. 封闭的顶层集合The Closed Top-Level Setshared的顶层是一组封闭集合closed set——这是 Naming Conventions §4.8顶层默认封闭原则在shared上的应用。恰好五个目录按三条有原则的类别划分目录类别为何能拥有顶层位置ai核心领域Core domainCherry Studio 本质是 AI 产品AI 的跨进程契约与纯逻辑是一等公民镜像src/main/ai/。只承载 AI 的跨进程切片——不含 AI UI 或按进程区分的服务data跨进程基础设施Cross-process infra数据层的跨进程契约API 实体/请求类型、cache/preference/bootConfig schema、migration 映射、presets。框架式、与领域无关ipc跨进程基础设施Cross-process infraIpcApi 框架routedefinehelpers、请求 事件 schema、错误模型、共享类型IpcContext、WindowId。与领域无关types形态桶Shape bucket无单一归属方的跨进程类型声明utils形态桶Shape bucket跨进程纯逻辑及其配套常量与类蓝图治理规则一个新能力永远不能赢得一个新的顶层目录。它要么是a核心领域只有ai要么是b真正的跨进程基础设施要么是c按形态shape分解进types/utils。其余一切 →types/utils。命名遵循 Naming Conventions §4.9ai/data/ipc是单数命名空间types/utils是复数桶。4. 形态划分typesvsutilsshared只有两个形态桶。由于没有 UI、没有 React、没有按进程区分的运行时渲染进程丰富的形态components/hooks/services/pages在这里坍缩为声明 vs 纯逻辑两类types/utils/类型别名、接口、枚举、schema 派生类型纯函数、谓词、转换器外加类型所需的小常量外加这些函数所需的常量 / 静态数据以及有状态类的蓝图两者之间的路由遵循 Naming Conventions §5.2 的按形态路由表。从源码观察src/shared/types/下是command.ts、mcp.ts、serializable.ts、miniAppManifest.ts等纯声明文件src/shared/utils/下是keywordSearch.ts、dataUrl.ts、conversationTitle.ts、serializable.ts等纯函数文件二者形态边界清晰。4.1 文件 vs 子目录以及 barrelBarrelindex.ts聚合导出规则以 Naming Conventions §6.4 为跨进程权威本节只覆盖shared特有细节默认是单个.ts文件。大多数主题就是一个文件——types/topic.ts、utils/topic.ts直接导入。只有当主题确实拥有多个文件时才升级为子目录Naming Conventions §4.4绝不预先创建。主题子目录恰好有一个index.ts作为其公共 API——types/topic/index.ts、utils/topic/index.ts显式具名导出禁止export *。这样无论主题是文件还是子目录导入面都完全一致shared/utils/topic两种形式皆可子目录内的其他文件保持私有。桶根types/与utils/没有index.ts。桶是类别category而非模块——一个把每个文件都重新导出的根 barrel 不会带来聚合 API只会为每次新增带来 churn 和导入环风险。要导入具体文件或主题绝不导入桶根。types/没有任何运行时测试。声明桶没有运行时行为可测因此types/下的行为测试expect(fn(...))…恰恰说明该文件含有逻辑——谓词、类型守卫、转换器、工厂或函数——应属于utils/按 §4 的形态路由。把逻辑移到utils/topic.ts从types/导入所需类型这是受祝福的utils → types方向测试随之移动。类型守卫x is T同样属于运行时谓词应与逻辑放在utils/而不是与接口一起留在types/。由校验函数构建的 schemaz.custom(isFoo)跟随函数进入utils/纯声明式 schemaz.object({…})可以留在types/。types/中唯一应当存在的测试是类型级测试expectTypeOf/assertType它断言类型契约本身、没有运行时可供迁移但它只是过渡性守护——仅当手写类型仍是事实源时才有价值一旦运行时 schemaZod / IpcApi接管契约、类型变为z.infer派生schema 自身的校验已涵盖它类型级测试应随那次迁移退役。4.2 常量与静态数据默认常量放在其领域/主题的单文件中紧邻其服务的逻辑AI 模型默认值 →ai/文件类型列表 →utils/file/。utils/constants.ts不是桶。它只承载真正全局、跨进程的残量KB/MB/GB、APP_NAME。只有当 100% 确定某个常量是应用全局且横切时才能加入只要它属于任何领域就该放进该领域的文件。——这正是旧config/constant.ts缺失的护栏也是它长成82 个导入方的杂物抽屉现已解散见 §6的原因。仓库现状src/shared/utils/constants.ts恰好只含KB、MB、GB、APP_NAME、LATEST_PRIVACY_POLICY_VERSION五个全局量与文档描述完全吻合。单进程常量 → 离开shared违反不变量一。没有config/桶。常量是数据一个放在其领域文件或utils/中的冻结值能表达config/目录想做的一切还不会招来无关的全局量。4.3 有状态类的蓝图Stateful-class blueprints有状态类的定义是纯代码因此它搭乘utils/下的主题模块——先例是utils/blacklistMatchPattern.ts中的有状态类MatchPatternMap。shared没有services/桶因为服务是按进程的不变量二。5. 放置决策Placement Decision按顺序经过两道门然后归类跨进程吗是否被两个进程都可达——不是 → 进入进程层src/main/*或src/renderer/*。例外Cache key 的 schema 条目与 value 类型即使单进程也留在shared/data/cache/——§2.1.1。无状态 / 不可变吗是否导出实例、是否持有可变状态——不是 → 只有蓝图和静态数据留下实例按进程放置。归类核心领域ai/ 基础设施data、ipc/ 形态types、utils。不属于前两者 → 按形态分解进types/utils绝不新开顶层目录。6. 反模式清单Anti-Patterns导出的实例单例——export const x new XService()或任何 registry / manager / service 实例。违反不变量二。单进程代码进入shared——仅为方便而把 main-only 或 renderer-only 的逻辑放在这里。违反不变量一。前重灾区现已解散的config/constant.ts——§7。Cache schema 注册表是唯一被认可的例外——§2.1.1。杂物抽屉式文件或目录——一个config/桶或constant.ts跨领域、跨进程地堆积无关全局量。应按领域 进程分解不要整块搬迁。每个能力开一个顶层目录——每个能力都按形态分解顶层是封闭的§3。shared中的有状态service——状态没有一致的共享归属者它属于main或renderer。7. 目标态 vs 当前态Target vs Current State顶层分解已是当前事实src/shared/只含ai/、data/、ipc/、types/、utils/五个目录。下表记录的是剩余已知差距而非已完成迁移的历史区域当前目标data/types/中的转换器/守卫——coerceSearchRole、deriveRootSpanId、readCherryMeta/withCherryMeta、knowledge.ts的字符串助手逻辑住在data类型桶内data/types/__tests__/下的行为测试暴露了它§4.1 末段悬而未决按形态路由会把它们移到utils位置但 schema 派生的守卫按惯例就近共置——决策已推迟IpcChannel.tsv1 channel 枚举位于根目录仍被遗留领域与 data/IpcApi 传输通道使用逐领域退役遗留条目然后把剩余的基础设施通道移到ipc/下8. 与周边文档的关系Architecture Overview——进程模型与shared的一句话总结。Renderer Architecture §2–§3——层模型及渲染进程如何依赖shared其 §6 拥有 command 的renderer 侧单元格本文拥有其shared单元格。Naming Conventions §4.8——顶层默认封闭本文是其在shared上的应用§4.9 单数 vs 复数§5.2 按形态路由。赞分享人工智能大模型AI 应用交互助手本地部署【免费下载链接】cherry-studio Cherry Studio 是一款支持多个 LLM 提供商的桌面客户端项目地址https://gitcode.com/CherryHQ/cherry-studio点击查看免费下载相关推荐Cherry Studio shared 跨进程基础层架构两大不变量、封闭顶层目录集与放置决策实战手册Cherry Studio shared 跨进程基础层架构两大不变量、封闭顶层目录集与放置决策实战手册 本文基于 Cherry Studio 仓库的官方架构AI 应用大模型桌面应用本地部署RAGCherry Studio 主进程架构解析src/main 封闭顶层目录集合与依赖规则Cherry Studio 主进程架构解析 src/main 封闭顶层目录集合与依赖规则 导读 本文是 Cherry Studio 桌面客户端主进程Elec人工智能大模型AI 应用交互助手本地部署Serial Studio 共享变量Shared Variables完整指南用 Data Tables 实现跨数据集校准、滤波与状态共享Serial Studio 共享变量Shared Variables完整指南用 Data Tables 实现跨数据集校准、滤波与状态共享 导读 本文是 S桌面应用数据可视化物联网创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考