Cherry Studio 主进程服务生命周期归属决策指南何时进入 Lifecycle 体系何时使用直接导入单例【免费下载链接】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 的主进程包含数十个以Service命名的类但“叫 Service”并不等于应该由生命周期Lifecycle体系管理。本文基于仓库中 lifecycle-decision-guide.md 的决策框架结合 src/main/core/lifecycle 的源码实现给出判断一个主进程服务究竟属于生命周期体系还是保持普通单例的完整判定标准、决策流程图、快速对照表与常见误区清单。读完本文你将能在新增或重构主进程服务时快速确定其归属、正确选择Conditional/Pausable/Activatable三种可选行为并规避 8 类最常见的误用模式。核心判定原则Lifecycle 管理的是资源不是逻辑Lifecycle 管理资源而不是逻辑。一个类名叫XxxService并不意味着它应该进入生命周期体系。判断的唯一标准是它是否拥有超出单次方法调用生命周期的资源或副作用并且在关机shutdown时需要进行清理从源码看这一原则体现在 BaseService.ts 的设计中所有生命周期服务都是受容器管理的单例重复实例化会直接抛错框架为它们提供状态机Created → Initializing → Ready ⇄ Paused → Stopping → Stopped → Destroyed、生命周期钩子onInit()/onReady()/onAllReady()/onStop()/onDestroy()/onPause()/onResume()、以及统一的registerDisposable()自动清理机制。如果一个类并不需要这些能力把它放进生命周期体系只会白白继承一个从未被覆写的空钩子。应该进入 Lifecycle 的两种情形满足其一即可情形一拥有长期存活的资源资源在onInit()时创建、跨多次调用存活、并且需要显式清理。典型的资源类别与示例类别示例数据库连接SQLite / better-sqlite3、Drizzle ORM网络服务HTTP server、mDNS browser、WebSocket server原生 / 操作系统资源SelectionHook系统线程、Tray、BrowserWindow文件系统chokidarwatcher、Winston DailyRotateFile transport定时器setIntervalGC、轮询子进程长期运行的 gateway / worker非一次性脚本有状态存储需要在关机时 flush 的内存缓存仓库中的CacheService是该情形的典型落地。在 CacheService.ts 中它以Injectable(CacheService)ServicePhase(Phase.BeforeReady)注册onInit()里注册 IPC 处理器、启动 GC 定时器registerInterval每 10 分钟清理过期条目、加载持久化缓存onStop()里 flush 未写完的持久化写入、清空全部内存缓存、销毁订阅通知器。文档中的示例代码GC 定时器 缓存清理正是对该实现的抽象Injectable(CacheService) export class CacheService extends BaseService { private gcTimer: NodeJS.Timeout | null null protected onInit() { this.gcTimer setInterval(() this.gc(), 600_000) } protected onStop() { clearInterval(this.gcTimer!) this.cache.clear() } }注意CacheService的 GC 定时器在真实实现中是通过this.registerInterval()注册的见 BaseService.ts该工具会调用unref()并自动在onStop()时clearInterval无需手写清理而onStop()中清空缓存、清理通知器的逻辑则与示例一致。相比裸写setIntervalregisterInterval把定时器纳入了统一 Disposable 追踪体系。情形二注册持久化副作用在初始化时修改全局状态、并贯穿整个服务生命周期存活、需要“撤销”的副作用。典型类别与示例类别示例事件监听器nativeTheme.on()、powerMonitor.on()、autoUpdater.on()全局快捷键globalShortcut.register()订阅preferenceService.subscribeChange()会话拦截器session.webRequest.onHeadersReceived()IPC 处理器ipcMain.handle()注册见下文专项说明全局 API 篡改Monkey-patching 全局 API什么时候 IPC 处理器应该住在服务内部这是一个**“放置位置”问题而不是“晋升”问题**。下面这张表的前提是服务已经是生命周期服务它拥有资源或有状态的处理器本表只决定某个处理器是否应该放在它内部。表中任何一行都不会单独把一个类晋升为生命周期服务——尤其注意第 3 行“属于该服务领域”的意思是并入已有的领域服务绝不意味着“为了承载 IPC 注册而专门创建一个生命周期服务”。当一个生命周期服务满足任意以下条件时应该自包含self-contain自己的 IPC 处理器条件原因处理器访问服务实例状态this.xxx处理器与服务生命周期耦合——服务停止处理器也必须停止服务需要支持stop()/start()/restart()重启后游离的处理器会引用过期状态处理器在语义上属于该服务的领域就近放置提升可维护性与可发现性如果处理器完全是无状态的例如返回app.getVersion()它就不需要生命周期管理——一个唯一职责是注册无状态 IPC 的类不是生命周期服务。应该把该处理器并入它的领域服务或从直接导入的单例中注册。对于自包含的处理器BaseService提供了内建的 IPC 追踪this.ipcHandle()和this.ipcOn()分别包装ipcMain.handle()与ipcMain.on()并自动在停止/销毁时通过ipcMain.removeHandler()/ipcMain.removeListener()注销返回Disposable。完整用法见 IPC Handler Management。仓库的StorageMonitorService是标准范式——把全部 IPC 注册收敛到private registerIpcHandlers()方法并从onInit()调用见 lifecycle-usage.md。实现细节在 BaseService.ts 中ipcHandle/ipcOn返回的 Disposable 都是通过this.registerDisposable()注册的也就是说 IPC 处理器与事件订阅、定时器共用同一条清理通道。onStop()返回后框架统一执行_cleanupDisposables()即使onStop()抛错清理也会在finally中执行确保处理器被移除。_doStop()与_doDestroy()中的自动去激活逻辑同样依赖这套机制见 BaseService.ts。不应该进入 Lifecycle 的情形以下五类服务不要进入生命周期体系无状态编排Stateless orchestration——调用其他服务、组合结果自身不拥有任何东西。DataApi 业务逻辑服务——仓库层 / 数据访问包装类它们只查询DbService如MessageRepository、TopicService。数据库连接由DbService管理这些类只是封装查询。使用直接导入单例。请求级资源Request-scoped——在单次方法调用内创建并释放的资源如BackupManager.backup()中创建的 S3 连接。无 init 无 cleanup——如果继承BaseService却永远不会覆写onInit()/onStop()。纯工具Pure utility——没有运行时状态的函数或 SDK 包装。仓库中的ExportService是反例的典型。在 ExportService.ts 中它是一个普通类export class ExportService不继承BaseService、没有任何生命周期装饰器所有工作都在方法内部完成markdown → docx 转换、调用dialog.showSaveDialog保存没有任何需要清理的资源在 export.ts 中通过模块级实例const exportService new ExportService()直接导入使用。文档中的示例与之一致export class ExportService { private md new MarkdownIt() async exportToDocx(messages: Message[]) { const doc new Document({ sections: this.buildSections(messages) }) const buffer await Packer.toBuffer(doc) await dialog.showSaveDialog(/* ... */) } } export const exportService new ExportService()类似的BackupManager在 LegacyBackupManager.ts 中以export const legacyBackupManager new BackupManager()形式作为直接导入单例存在——它的 S3 连接在backup()调用内部创建并在返回时释放属于请求级资源。决策流程图┌───────────────────────────────────┐ │ Owns long-lived resources? │ │ (connections, timers, native │ │ modules, servers, processes) │ └─────┬────────────────┬────────────┘ yes │ │ no ▼ ▼ ┌───────────┐ ┌──────────────────────────┐ │ Lifecycle │ │ Registers persistent │ └───────────┘ │ side effects? │ │ (listeners, shortcuts, │ │ subscriptions, etc.) │ └─────┬───────────┬────────┘ yes │ │ no ▼ ▼ ┌───────────┐ ┌────────────────┐ │ Lifecycle │ │ Direct-import │ └───────────┘ │ singleton │ └────────────────┘先问“是否拥有长期存活的资源”再问“是否注册持久化副作用”两个答案都是“否”时直接使用export const x new X()形式的直接导入单例即可。快速对照表LifecycleDirect-import singleton示例DbService、CacheService、MainWindowServiceExportService、BackupManager长期存活资源有无或请求级持久化副作用有无onInit/onStop有意义会是空的模式Injectableapplication.get()export const x new X()生命周期服务注册到 serviceRegistry.ts 的services对象中供Application.registerAll()统一注册主进程代码通过application.get(ServiceName)访问而直接导入单例则完全游离于容器之外。两者是互补关系——文档与源码都明确“依赖 PreferenceService”不是进入生命周期的理由任何代码都可以直接调用application.get(PreferenceService)只有当服务自身拥有资源时才需要注册。在 Conditional、Pausable、Activatable 之间选择一旦确定服务属于生命周期体系它可能还需要可选行为。决策表如下场景使用理由服务只在特定平台/架构上运行Conditional启动时排除零开销服务需要临时挂起/恢复如窗口失焦Pausable保留实例与资源只是暂停执行服务始终需要 IPC但重资源按需加载ActivatableIPC 始终可用资源只在需要时分配服务有运行时开关偏好、特性开关控制启停Activatable统一的 activate/deactivate 模式即使资源很轻量服务无条件运行且资源全量无默认行为决策流程Does the service need to be entirely excluded on some platforms? ├─ Yes, condition is known at boot and immutable │ → Conditional (platform, arch, env var, etc.) └─ No Does the service have heavy resources OR a runtime toggle controlling on/off? ├─ Yes → Activatable │ IPC registered in onInit() (always available) │ Resources in onActivate()/onDeactivate() │ Service decides trigger (preference, event, IPC, etc.) └─ No Does the service need temporary pause/resume? ├─ Yes → Pausable └─ No → No extra interface neededConditional启动时一次性排除Conditional在注册时同步求值早于服务实例化条件不满足的服务在启动时被静默跳过运行时不可再改变。条件工厂函数定义在 conditions.tsonPlatform(...)、onArch(...)、onCpuVendor(...)、onEnvVar(name, value?)、when(fn, desc)以及组合器not()、anyOf()、allOf()多个条件用 AND 逻辑嵌套组合可表达OR(AND(x1,x2), AND(y1,y2))这类复杂布尔表达式。条件求值的运行时上下文platform、arch、cpuModel、env封装为ConditionContext便于在测试中注入 mock见 types.ts。需要特别注意的是Conditional被排除的服务必须用application.getOptional()访问get()会抛错且存在传递性排除——若 A 被排除依赖 A 的 B 也会被自动排除。条件服务的注册与访问规则详见 lifecycle-usage.md。Activatable 与 Pausable 的对比ActivatablePausable目的按需加载/释放资源临时挂起执行状态维度与LifecycleState正交改变LifecycleStateIPC 处理器始终可用在onInit中注册暂停时保留停止时移除资源未激活时不分配暂停时保留触发方式服务自决自身或外部通过application.activateLifecycleManager级联触发级联无级联级联到依赖服务循环支持重复 activate/deactivate支持重复 pause/resume源码层面Activatable与Pausable是两个独立接口见 types.ts通过isActivatable()/isPausable()类型守卫识别_doActivate()是幂等的、带并发守卫且要求服务处于Ready状态_doStop()会先自动去激活再执行onStop()见 BaseService.ts。仓库中 SelectionServiceimplements Activatable以偏好项feature.selection.enabled作为运行时开关、NodeTraceService 与 ClaudeCodeTraceBridgeService 都是Activatable的真实落地。生命周期框架自身在 Activatable.test.ts 中对激活幂等性、onActivate抛错后isActivated保持false、并发守卫、自激活/外部激活双路径等行为均有单测覆盖。什么时候 Activatable 不合适轻量资源且无运行时开关Map、总是需要的简单状态——不值得拆分直接在onInit()中加载未激活时不需要 IPC——考虑用Conditional整体排除资源需要跨服务协调释放——考虑Pausable支持级联。常见误区8 条空钩子——extends BaseService却不覆写onInit()/onStop()。如果两者都为空就不要使用生命周期。请求级 ≠ 长期存活——BackupManager在backup()内部创建 S3 连接并在返回时释放这是请求级资源不需要生命周期。“依赖 PreferenceService”——这不是生命周期关注点。任何代码都可以调用application.get(PreferenceService)。只有服务自身拥有资源时才需要注册。用Conditional处理运行时条件——Conditional只在启动时求值一次。对运行时会变化的条件用户偏好、事件改用Activatable。冗余的跨阶段DependsOn——WhenReady 服务不需要DependsOn([PreferenceService])或DependsOn([DbService])。阶段顺序由容器保证BeforeReady 总是先于 WhenReady 就绪。只为同阶段服务声明DependsOn// ❌ 冗余——PreferenceService 是 BeforeReady保证已就绪 Injectable(MainWindowService) ServicePhase(Phase.WhenReady) DependsOn([PreferenceService]) // -- 删除这行 export class MainWindowService extends BaseService { ... } // ✅ 正确——只声明同阶段依赖 Injectable(AgentBootstrapService) ServicePhase(Phase.WhenReady) DependsOn([ApiServerService]) // ApiServerService 也是 WhenReady export class AgentBootstrapService extends BaseService { ... }阶段BeforeReady/Background/WhenReady与依赖规则的完整说明见 lifecycle-overview.mdLifecycleManager.startPhase()会自动保证跨阶段就绪顺序。在onAllReady中 await 业务工作——onAllReady是启动完成后的补充钩子不是初始化的一部分。框架会并行调用每个服务的钩子并不等待完成fire-and-forget。onAllReady里的await someLongRunning()会变成静默的后台工作引导流程照常继续。如果服务确实需要延迟业务工作例如等待安静窗口后做恢复用setTimeout调度、把 Promise 记录在实例上、并在onStop中 join——关机路径上的 join 是有上限的SERVICE_STOP_TIMEOUT_MS每个服务每轮 5 秒完整模板与上限说明见 Lifecycle Usage — onAllReady patterns。把ALL_SERVICES_READY当作“所有副作用已完成”——该事件在每个onAllReady钩子被调用后立即触发而不是它们完成后。需要等待某个特定服务延迟工作的监听者必须与该服务直接协调例如服务在完成时发出的Signal而不是订阅ALL_SERVICES_READY。这一点在 lifecycle-overview.md 中有专门对比onAllReady是“推”框架调用每个服务事件是“发布/订阅”仅订阅者收到。“生命周期服务当作 IPC 桶”——一个只用来注册 IPC 处理器的类默认不是生命周期服务。注册是一种副作用但无状态处理器不需要关机时的撤销且“属于该领域”IPC 表格第 3 行只决定处理器在已是生命周期的服务内部的放置位置永远不把一个仅含 IPC 的类晋升为生命周期服务。应把这类处理器并入所属的领域服务或使用直接导入单例。延伸阅读Lifecycle Overview生命周期系统架构——引导阶段、钩子、服务状态、事件与并行初始化顺序Lifecycle Usage Guide装饰器、IPC/定时器助手、条件激活、暂停/恢复、Activatable 的完整代码示例Application Overview面向使用方的 API注册、引导、服务访问、运行时控制serviceRegistry.ts生命周期服务的集中注册表BaseService.ts生命周期基类与钩子/资源清理实现lifecycle/tests生命周期各组件BaseService、LifecycleManager、ServiceContainer、Activatable、conditions 等的单元测试【免费下载链接】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 主进程服务生命周期归属决策指南：何时进入 Lifecycle 体系，何时使用直接导入单例
Cherry Studio 主进程服务生命周期归属决策指南何时进入 Lifecycle 体系何时使用直接导入单例【免费下载链接】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 的主进程包含数十个以Service命名的类但“叫 Service”并不等于应该由生命周期Lifecycle体系管理。本文基于仓库中 lifecycle-decision-guide.md 的决策框架结合 src/main/core/lifecycle 的源码实现给出判断一个主进程服务究竟属于生命周期体系还是保持普通单例的完整判定标准、决策流程图、快速对照表与常见误区清单。读完本文你将能在新增或重构主进程服务时快速确定其归属、正确选择Conditional/Pausable/Activatable三种可选行为并规避 8 类最常见的误用模式。核心判定原则Lifecycle 管理的是资源不是逻辑Lifecycle 管理资源而不是逻辑。一个类名叫XxxService并不意味着它应该进入生命周期体系。判断的唯一标准是它是否拥有超出单次方法调用生命周期的资源或副作用并且在关机shutdown时需要进行清理从源码看这一原则体现在 BaseService.ts 的设计中所有生命周期服务都是受容器管理的单例重复实例化会直接抛错框架为它们提供状态机Created → Initializing → Ready ⇄ Paused → Stopping → Stopped → Destroyed、生命周期钩子onInit()/onReady()/onAllReady()/onStop()/onDestroy()/onPause()/onResume()、以及统一的registerDisposable()自动清理机制。如果一个类并不需要这些能力把它放进生命周期体系只会白白继承一个从未被覆写的空钩子。应该进入 Lifecycle 的两种情形满足其一即可情形一拥有长期存活的资源资源在onInit()时创建、跨多次调用存活、并且需要显式清理。典型的资源类别与示例类别示例数据库连接SQLite / better-sqlite3、Drizzle ORM网络服务HTTP server、mDNS browser、WebSocket server原生 / 操作系统资源SelectionHook系统线程、Tray、BrowserWindow文件系统chokidarwatcher、Winston DailyRotateFile transport定时器setIntervalGC、轮询子进程长期运行的 gateway / worker非一次性脚本有状态存储需要在关机时 flush 的内存缓存仓库中的CacheService是该情形的典型落地。在 CacheService.ts 中它以Injectable(CacheService)ServicePhase(Phase.BeforeReady)注册onInit()里注册 IPC 处理器、启动 GC 定时器registerInterval每 10 分钟清理过期条目、加载持久化缓存onStop()里 flush 未写完的持久化写入、清空全部内存缓存、销毁订阅通知器。文档中的示例代码GC 定时器 缓存清理正是对该实现的抽象Injectable(CacheService) export class CacheService extends BaseService { private gcTimer: NodeJS.Timeout | null null protected onInit() { this.gcTimer setInterval(() this.gc(), 600_000) } protected onStop() { clearInterval(this.gcTimer!) this.cache.clear() } }注意CacheService的 GC 定时器在真实实现中是通过this.registerInterval()注册的见 BaseService.ts该工具会调用unref()并自动在onStop()时clearInterval无需手写清理而onStop()中清空缓存、清理通知器的逻辑则与示例一致。相比裸写setIntervalregisterInterval把定时器纳入了统一 Disposable 追踪体系。情形二注册持久化副作用在初始化时修改全局状态、并贯穿整个服务生命周期存活、需要“撤销”的副作用。典型类别与示例类别示例事件监听器nativeTheme.on()、powerMonitor.on()、autoUpdater.on()全局快捷键globalShortcut.register()订阅preferenceService.subscribeChange()会话拦截器session.webRequest.onHeadersReceived()IPC 处理器ipcMain.handle()注册见下文专项说明全局 API 篡改Monkey-patching 全局 API什么时候 IPC 处理器应该住在服务内部这是一个**“放置位置”问题而不是“晋升”问题**。下面这张表的前提是服务已经是生命周期服务它拥有资源或有状态的处理器本表只决定某个处理器是否应该放在它内部。表中任何一行都不会单独把一个类晋升为生命周期服务——尤其注意第 3 行“属于该服务领域”的意思是并入已有的领域服务绝不意味着“为了承载 IPC 注册而专门创建一个生命周期服务”。当一个生命周期服务满足任意以下条件时应该自包含self-contain自己的 IPC 处理器条件原因处理器访问服务实例状态this.xxx处理器与服务生命周期耦合——服务停止处理器也必须停止服务需要支持stop()/start()/restart()重启后游离的处理器会引用过期状态处理器在语义上属于该服务的领域就近放置提升可维护性与可发现性如果处理器完全是无状态的例如返回app.getVersion()它就不需要生命周期管理——一个唯一职责是注册无状态 IPC 的类不是生命周期服务。应该把该处理器并入它的领域服务或从直接导入的单例中注册。对于自包含的处理器BaseService提供了内建的 IPC 追踪this.ipcHandle()和this.ipcOn()分别包装ipcMain.handle()与ipcMain.on()并自动在停止/销毁时通过ipcMain.removeHandler()/ipcMain.removeListener()注销返回Disposable。完整用法见 IPC Handler Management。仓库的StorageMonitorService是标准范式——把全部 IPC 注册收敛到private registerIpcHandlers()方法并从onInit()调用见 lifecycle-usage.md。实现细节在 BaseService.ts 中ipcHandle/ipcOn返回的 Disposable 都是通过this.registerDisposable()注册的也就是说 IPC 处理器与事件订阅、定时器共用同一条清理通道。onStop()返回后框架统一执行_cleanupDisposables()即使onStop()抛错清理也会在finally中执行确保处理器被移除。_doStop()与_doDestroy()中的自动去激活逻辑同样依赖这套机制见 BaseService.ts。不应该进入 Lifecycle 的情形以下五类服务不要进入生命周期体系无状态编排Stateless orchestration——调用其他服务、组合结果自身不拥有任何东西。DataApi 业务逻辑服务——仓库层 / 数据访问包装类它们只查询DbService如MessageRepository、TopicService。数据库连接由DbService管理这些类只是封装查询。使用直接导入单例。请求级资源Request-scoped——在单次方法调用内创建并释放的资源如BackupManager.backup()中创建的 S3 连接。无 init 无 cleanup——如果继承BaseService却永远不会覆写onInit()/onStop()。纯工具Pure utility——没有运行时状态的函数或 SDK 包装。仓库中的ExportService是反例的典型。在 ExportService.ts 中它是一个普通类export class ExportService不继承BaseService、没有任何生命周期装饰器所有工作都在方法内部完成markdown → docx 转换、调用dialog.showSaveDialog保存没有任何需要清理的资源在 export.ts 中通过模块级实例const exportService new ExportService()直接导入使用。文档中的示例与之一致export class ExportService { private md new MarkdownIt() async exportToDocx(messages: Message[]) { const doc new Document({ sections: this.buildSections(messages) }) const buffer await Packer.toBuffer(doc) await dialog.showSaveDialog(/* ... */) } } export const exportService new ExportService()类似的BackupManager在 LegacyBackupManager.ts 中以export const legacyBackupManager new BackupManager()形式作为直接导入单例存在——它的 S3 连接在backup()调用内部创建并在返回时释放属于请求级资源。决策流程图┌───────────────────────────────────┐ │ Owns long-lived resources? │ │ (connections, timers, native │ │ modules, servers, processes) │ └─────┬────────────────┬────────────┘ yes │ │ no ▼ ▼ ┌───────────┐ ┌──────────────────────────┐ │ Lifecycle │ │ Registers persistent │ └───────────┘ │ side effects? │ │ (listeners, shortcuts, │ │ subscriptions, etc.) │ └─────┬───────────┬────────┘ yes │ │ no ▼ ▼ ┌───────────┐ ┌────────────────┐ │ Lifecycle │ │ Direct-import │ └───────────┘ │ singleton │ └────────────────┘先问“是否拥有长期存活的资源”再问“是否注册持久化副作用”两个答案都是“否”时直接使用export const x new X()形式的直接导入单例即可。快速对照表LifecycleDirect-import singleton示例DbService、CacheService、MainWindowServiceExportService、BackupManager长期存活资源有无或请求级持久化副作用有无onInit/onStop有意义会是空的模式Injectableapplication.get()export const x new X()生命周期服务注册到 serviceRegistry.ts 的services对象中供Application.registerAll()统一注册主进程代码通过application.get(ServiceName)访问而直接导入单例则完全游离于容器之外。两者是互补关系——文档与源码都明确“依赖 PreferenceService”不是进入生命周期的理由任何代码都可以直接调用application.get(PreferenceService)只有当服务自身拥有资源时才需要注册。在 Conditional、Pausable、Activatable 之间选择一旦确定服务属于生命周期体系它可能还需要可选行为。决策表如下场景使用理由服务只在特定平台/架构上运行Conditional启动时排除零开销服务需要临时挂起/恢复如窗口失焦Pausable保留实例与资源只是暂停执行服务始终需要 IPC但重资源按需加载ActivatableIPC 始终可用资源只在需要时分配服务有运行时开关偏好、特性开关控制启停Activatable统一的 activate/deactivate 模式即使资源很轻量服务无条件运行且资源全量无默认行为决策流程Does the service need to be entirely excluded on some platforms? ├─ Yes, condition is known at boot and immutable │ → Conditional (platform, arch, env var, etc.) └─ No Does the service have heavy resources OR a runtime toggle controlling on/off? ├─ Yes → Activatable │ IPC registered in onInit() (always available) │ Resources in onActivate()/onDeactivate() │ Service decides trigger (preference, event, IPC, etc.) └─ No Does the service need temporary pause/resume? ├─ Yes → Pausable └─ No → No extra interface neededConditional启动时一次性排除Conditional在注册时同步求值早于服务实例化条件不满足的服务在启动时被静默跳过运行时不可再改变。条件工厂函数定义在 conditions.tsonPlatform(...)、onArch(...)、onCpuVendor(...)、onEnvVar(name, value?)、when(fn, desc)以及组合器not()、anyOf()、allOf()多个条件用 AND 逻辑嵌套组合可表达OR(AND(x1,x2), AND(y1,y2))这类复杂布尔表达式。条件求值的运行时上下文platform、arch、cpuModel、env封装为ConditionContext便于在测试中注入 mock见 types.ts。需要特别注意的是Conditional被排除的服务必须用application.getOptional()访问get()会抛错且存在传递性排除——若 A 被排除依赖 A 的 B 也会被自动排除。条件服务的注册与访问规则详见 lifecycle-usage.md。Activatable 与 Pausable 的对比ActivatablePausable目的按需加载/释放资源临时挂起执行状态维度与LifecycleState正交改变LifecycleStateIPC 处理器始终可用在onInit中注册暂停时保留停止时移除资源未激活时不分配暂停时保留触发方式服务自决自身或外部通过application.activateLifecycleManager级联触发级联无级联级联到依赖服务循环支持重复 activate/deactivate支持重复 pause/resume源码层面Activatable与Pausable是两个独立接口见 types.ts通过isActivatable()/isPausable()类型守卫识别_doActivate()是幂等的、带并发守卫且要求服务处于Ready状态_doStop()会先自动去激活再执行onStop()见 BaseService.ts。仓库中 SelectionServiceimplements Activatable以偏好项feature.selection.enabled作为运行时开关、NodeTraceService 与 ClaudeCodeTraceBridgeService 都是Activatable的真实落地。生命周期框架自身在 Activatable.test.ts 中对激活幂等性、onActivate抛错后isActivated保持false、并发守卫、自激活/外部激活双路径等行为均有单测覆盖。什么时候 Activatable 不合适轻量资源且无运行时开关Map、总是需要的简单状态——不值得拆分直接在onInit()中加载未激活时不需要 IPC——考虑用Conditional整体排除资源需要跨服务协调释放——考虑Pausable支持级联。常见误区8 条空钩子——extends BaseService却不覆写onInit()/onStop()。如果两者都为空就不要使用生命周期。请求级 ≠ 长期存活——BackupManager在backup()内部创建 S3 连接并在返回时释放这是请求级资源不需要生命周期。“依赖 PreferenceService”——这不是生命周期关注点。任何代码都可以调用application.get(PreferenceService)。只有服务自身拥有资源时才需要注册。用Conditional处理运行时条件——Conditional只在启动时求值一次。对运行时会变化的条件用户偏好、事件改用Activatable。冗余的跨阶段DependsOn——WhenReady 服务不需要DependsOn([PreferenceService])或DependsOn([DbService])。阶段顺序由容器保证BeforeReady 总是先于 WhenReady 就绪。只为同阶段服务声明DependsOn// ❌ 冗余——PreferenceService 是 BeforeReady保证已就绪 Injectable(MainWindowService) ServicePhase(Phase.WhenReady) DependsOn([PreferenceService]) // -- 删除这行 export class MainWindowService extends BaseService { ... } // ✅ 正确——只声明同阶段依赖 Injectable(AgentBootstrapService) ServicePhase(Phase.WhenReady) DependsOn([ApiServerService]) // ApiServerService 也是 WhenReady export class AgentBootstrapService extends BaseService { ... }阶段BeforeReady/Background/WhenReady与依赖规则的完整说明见 lifecycle-overview.mdLifecycleManager.startPhase()会自动保证跨阶段就绪顺序。在onAllReady中 await 业务工作——onAllReady是启动完成后的补充钩子不是初始化的一部分。框架会并行调用每个服务的钩子并不等待完成fire-and-forget。onAllReady里的await someLongRunning()会变成静默的后台工作引导流程照常继续。如果服务确实需要延迟业务工作例如等待安静窗口后做恢复用setTimeout调度、把 Promise 记录在实例上、并在onStop中 join——关机路径上的 join 是有上限的SERVICE_STOP_TIMEOUT_MS每个服务每轮 5 秒完整模板与上限说明见 Lifecycle Usage — onAllReady patterns。把ALL_SERVICES_READY当作“所有副作用已完成”——该事件在每个onAllReady钩子被调用后立即触发而不是它们完成后。需要等待某个特定服务延迟工作的监听者必须与该服务直接协调例如服务在完成时发出的Signal而不是订阅ALL_SERVICES_READY。这一点在 lifecycle-overview.md 中有专门对比onAllReady是“推”框架调用每个服务事件是“发布/订阅”仅订阅者收到。“生命周期服务当作 IPC 桶”——一个只用来注册 IPC 处理器的类默认不是生命周期服务。注册是一种副作用但无状态处理器不需要关机时的撤销且“属于该领域”IPC 表格第 3 行只决定处理器在已是生命周期的服务内部的放置位置永远不把一个仅含 IPC 的类晋升为生命周期服务。应把这类处理器并入所属的领域服务或使用直接导入单例。延伸阅读Lifecycle Overview生命周期系统架构——引导阶段、钩子、服务状态、事件与并行初始化顺序Lifecycle Usage Guide装饰器、IPC/定时器助手、条件激活、暂停/恢复、Activatable 的完整代码示例Application Overview面向使用方的 API注册、引导、服务访问、运行时控制serviceRegistry.ts生命周期服务的集中注册表BaseService.ts生命周期基类与钩子/资源清理实现lifecycle/tests生命周期各组件BaseService、LifecycleManager、ServiceContainer、Activatable、conditions 等的单元测试【免费下载链接】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），仅供参考
