Cherry Studio 电源中枢 PowerService 深度解析Electron powerMonitor 与电源管理的统一封装【免费下载链接】cherry-studio Cherry Studio 是一款支持多个 LLM 提供商的桌面客户端项目地址: https://gitcode.com/CherryHQ/cherry-studioCherry Studio 的PowerService源码是系统电源管理的统一中枢一个由应用生命周期托管lifecycle-managed的单例服务它独占所有 ElectronpowerMonitor/powerSaveBlocker相关的职责使应用其余部分永远不需要直接触碰这些底层 API。本文基于仓库中的 power 模块说明文档 并结合源码实现完整讲解它的五大职责电源通知事件、关机屏障、防睡眠、状态查询以及生命周期集成读者读完后将掌握在 Cherry Studio 中如何安全地监听系统挂起/恢复、在系统关机前执行清理、以及为长任务申请阻止系统睡眠的完整实战方案。为什么需要 PowerService集中管理电源职责Electron 桌面应用常常需要感知系统电源状态笔记本合盖挂起、屏幕锁定、电源从电池切换到交流电、系统即将关机、长时间后台任务需要阻止睡眠等。如果每个模块都各自直接调用powerMonitor/powerSaveBlocker会带来三个典型问题事件去重缺失macOS 上suspend/resume事件会触发两次见 electron/electron#24803各调用方需要各自实现去重逻辑关机清理不完整系统关机时如果直接退进程正在进行的文件写入、状态持久化会被截断阻止睡眠失控多个模块同时申请阻止睡眠时没有引用计数很难知道谁在阻止睡眠、何时可以安全释放。PowerService 正是为解决这些问题而生它把上述所有电源关注点收敛到单一服务之后对外暴露类型化事件、关机屏障、引用计数的防睡眠持有hold和电平触发level-triggered的查询 API。职责总览职责领域提供能力通知事件类型化Emitter→EventonSuspend/onResume/onLockScreen/onUnlockScreen/onPowerSourceChange。其中 suspend/resume 与电源来源power-source会基于内部状态去重应对 macOS 双重触发electron/electron#24803lock/unlock 为透传转发关机屏障registerShutdownHandler(fn)→Disposable。系统关机时处理器串行执行并被硬超时约束随后应用退出。跨平台macOS/Linux 使用powerMonitor的shutdown事件 preventDefaultWindows 使用paymoapp/electron-shutdown-handler防睡眠preventSleep(reason?)→Disposable。基于引用计数持有只有至少存在一个持有 AND 用户通过app.power.prevent_sleep_when_busy偏好开启时OS 阻塞器prevent-app-suspension才处于激活状态。isPreventingSleep()返回有效状态查询getPowerPhase()/getPowerSource()/isOnBatteryPower()/getSystemIdleTime()/getSystemIdleState(thresholdSec)—— 电平触发式迟到的调用者无需观察过边沿事件即可对账当前状态快速上手三类典型用法按照 README 的 Quick Start以下是完整可用的入门代码。PowerService已注册进应用容器通过application.get(PowerService)即可获取import { application } from application const power application.get(PowerService) // 1. 在某个工作的存续期内保持机器唤醒 // 仅当用户开启了 app.power.prevent_sleep_when_busy 时真正生效 const hold power.preventSleep(job:export) try { await doWork() } finally { hold.dispose() // 幂等可重复调用 } // 2. 响应系统挂起/恢复 this.registerDisposable(power.onSuspend(() pauseLongPoll())) this.registerDisposable(power.onResume(() resumeLongPoll())) // 3. 在 OS 关机前执行清理 this.registerDisposable(power.registerShutdownHandler(() flushCriticalState()))三个要点值得注意preventSleep返回的Disposable与事件订阅、关机处理器注册返回的Disposable都能安全地交给生命周期基类如BaseService的registerDisposable统一管理服务停止时自动释放registerShutdownHandler的处理器可以是同步函数也可以是返回Promise的异步函数类型为() void | Promisevoid串行执行、错误隔离所有 API 都遵循绝不抛出、总是返回可用对象的约定调用方无需防御式try/catch。电源通知事件类型化 Emitter 与去重机制PowerService 通过类型化Emitter对外暴露五个事件内部状态为powerPhaseactive | suspended与powerSourceac | battery | unknown见 PowerService.ts 事件定义与初始化suspend / resume 去重内部维护powerPhase状态机。收到suspend时若当前已是suspended则直接忽略否则置状态并触发onSuspendresume同理。这正是针对 macOS 双重触发electron/electron#24803的防御power-source 去重updatePowerSource()仅在来源真正变化时才更新状态并触发onPowerSourceChange重复的on-ac/on-battery事件不会重复广播lock / unlock 透传屏幕锁定/解锁没有需要去重的状态机直接转发初始状态播种服务初始化时即从powerMonitor.onBatteryPower读取当前电源来源并写入powerSource保证第一个查询/事件就是正确的见 PowerService.ts#L118。单元测试 PowerService.test.ts 中的事件用例完整覆盖了这些行为重复suspend只触发一次回调、未挂起时收到resume不触发、lock-screen 透传两次、电源来源仅在真实变化时广播。关机屏障在系统关机前完成清理有界串行执行registerShutdownHandler(handler)将处理器推入内部数组并返回可注销的Disposable按索引移除。当系统报告即将关机时executeShutdownHandlers()会串行依次await每个处理器错误隔离单个处理器抛错仅记录日志不影响后续处理器执行硬超时兜底整体执行受SHUTDOWN_HANDLER_TIMEOUT_MS 50005 秒约束通过Promise.race([run, timeout])实现——即使某个处理器永久挂起5 秒后也会强制进入退出流程绝不拖住用户机器的关机操作见 PowerService.ts#L23 与 #L188-L213。测试中的 force-quits when a handler hangs past the timeout 用例用假定时器验证了这一点一个永不 resolve 的处理器不会阻塞退出。macOS / LinuxpreventDefault → 执行处理器 → quit在 macOS/Linux 上powerMonitor.on(shutdown, ...)监听器收到事件后先调用event.preventDefault()推迟系统关机然后串行执行所有关机处理器最后调用application.quit()而不是裸app.quit()走应用正常的退出流程见 PowerService.ts#L215-L235。实现细节Electron 类型定义中shutdown监听器签名为() void但运行时确实会传入带preventDefault的事件对象。源码将事件参数声明为可选event?: Electron.Event既兼容类型重载又能在运行时调用preventDefault。Windows原生关机消息钩子 隐藏窗口Windows 路径使用paymoapp/electron-shutdown-handler原生插件通过WM_QUERYENDSESSION钩住系统关机消息见 PowerService.ts#L237-L287流程为blockShutdown()→ 执行处理器 →releaseShutdown()→application.quit()。源码注释中披露了几个关键的工程决策自建隐藏窗口而非复用主窗口主窗口是单例、可能在服务初始化时尚未存在、且销毁重建会更换 HWND而插件需要稳定的 HWND 挂接关机消息。因此服务自建一个show: falsepaintWhenInitiallyHidden: falseskipTaskbar: true的BrowserWindow仅作为原生句柄载体、从不加载任何内容零渲染进程开销由于不加载内容且paintWhenInitiallyHidden: false阻止激活/绘制Electron 不会为该窗口派生独立渲染进程在窗口子系统已初始化的前提下实测边际成本仅约 0.7 MB RSS可视为近乎免费必须显式调用blockShutdown()若只挂监听器而不调用blockShutdown插件只会观察到关机事件而不会真正按住系统——这一调用是 Windows 路径成为真正屏障的关键且必须在监听器挂载之后调用。对应测试用例断言了setWindowHandle、on(shutdown)、blockShutdown均被调用回调执行后releaseShutdown与quit各调用一次。退出流程的一致性无论哪个平台最终都经由application.quit()走before-quit流程。这意味着如果应用存在活动的Application.preventQuit持有例如正在进行数据迁移它会像拦截用户主动退出一样拦截 OS 发起的关机——受关机处理器硬超时的限制因为 OS 不能被无限期阻塞见 README Notes。防睡眠引用计数持有 用户偏好门控设计模型防睡眠采用通用注册表 正交门控模型见 PowerService.ts#L293-L356持有注册表任何需要机器保持唤醒的 worker 调用preventSleep(reason?)注册一个持有返回Disposable工作结束时dispose()释放偏好门控preventEnabled来自用户偏好app.power.prevent_sleep_when_busy由服务内部自行读取自读模式与TrayService/ThemeService/ProxyService一致并通过pref.subscribeChange(...)实时订阅变化有效状态 门控开启 AND 持有数 0applyBlockerState()是唯一的幂等收敛点任何路径获取持有、释放持有、偏好变更、服务停止都汇聚到这里决定启动/停止 OS 阻塞器。持有的数据结构是Mapsymbol, { reason?: string; since: number }而非裸计数器dispose()通过Map.delete天然幂等第二次调用返回false即不再动作且持有可枚举便于排查谁在持有、从何时开始的泄漏问题见 PowerService.ts#L77。prevent-app-suspension 的选择阻塞器使用powerSaveBlocker.start(prevent-app-suspension)见 PowerService.ts#L316该模式保持系统运行但允许显示器休眠——对后台工作任务、下载而言是正确选择不同于会阻止显示器休眠的prevent-display-sleep。尽力而为、绝不抛出applyBlockerState()将powerSaveBlocker.start/stop的任何失败记录日志并吞掉因此preventSleep()永远返回一个可用的Disposable即使 OS 阻塞器启动失败也不影响调用方调用方无需任何防御式try/catch优雅降级内聚在 provider 内部而不是散落在每个调用点失败后的自动恢复下一次preventSleep/dispose/ 偏好变更会重新运行收敛逻辑可纠正当前不一致的阻塞状态见 PowerService.ts#L310-L330。测试对此有专门用例powerSaveBlocker.start抛出异常时preventSleep不抛、仍返回可用且可幂等释放的持有。引用计数行为测试验证了完整语义见 PowerService.test.ts偏好关闭时即使有持有也不启动阻塞器偏好开启且无持有时不启动持有到达时启动一次prevent-app-suspension多个持有共享同一个阻塞器只有最后一个释放后才停止持有期间用户关闭偏好阻塞器立即释放持有期间用户开启偏好阻塞器立即启动。查询 API电平触发式状态读取查询类 API 均为电平触发level-triggered设计迟到的调用者无需观察到边沿事件即可对账当前状态见 PowerService.ts#L358-L381getPowerPhase(): active | suspended—— 返回内部状态机当前值getPowerSource(): ac | battery | unknown—— 返回已去重的当前电源来源isOnBatteryPower(): boolean—— 直接转发powerMonitor.onBatteryPowergetSystemIdleTime(): number—— 系统空闲秒数将服务于 Job 系统的after-idle追赶策略见 catchUp.ts 中的预留注释getSystemIdleState(thresholdSec): active | idle | locked | unknown—— 按阈值判定空闲状态。测试验证了这些 API 正确转发到底层powerMonitor并透传阈值参数。生命周期集成WhenReady 阶段的自足服务PowerService声明为Injectable(PowerService)且ServicePhase(Phase.WhenReady)见 PowerService.ts#L52-L54即在应用 WhenReady 阶段初始化——此时应用已经 readypowerSaveBlocker/BrowserWindow可直接使用无需app.whenReady()体操onInit()依次初始化电源事件、关机屏障、防睡眠三个子系统onStop()清理清空关机处理器、停止活动阻塞器、清空全部持有。它注册于应用服务注册表见 serviceRegistry.ts与TrayService/ThemeService/ProxyService一样采用自读偏好模式。实战Job 系统如何接入防睡眠Job 系统是preventSleep的首个注册者。在 JobManager.ts#L1798-L1832 中每个任务尝试attempt开始时获取持有finally中释放const task (async () { // 尽力而为受用户 app.power.prevent_sleep_when_busy 偏好门控。 // preventSleep 绝不抛出、总是返回 Disposable因此这里无需防御。 const sleepHold application.get(PowerService).preventSleep(job:${row.type}:${row.id}) try { const output await handler.execute(ctx) // ... 完成/失败分类、重试调度 } finally { // ... 释放 } })()值得注意的细节是按尝试per-attempt持有任务在两次重试之间处于delayed状态非工作状态不应持有机器唤醒——注释明确指出这一设计意图见 JobManager.ts#L1802-L1803。流式传输等后续 worker 可通过同一 API 自行注册。用户偏好与开关位置防睡眠的用户开关位于设置 → 通用Settings → General。偏好定义位于数据分类配置 target-key-definitions.json{ targetKey: app.power.prevent_sleep_when_busy, type: boolean, defaultValue: false, status: classified, description: Prevent system sleep while the app has active work (v2 new feature, no v1 source) }关键事实默认值为false用户未开启时即使有 worker 请求系统也不会被阻止睡眠该偏好为 v2 新增特性无 v1 来源。总结Cherry Studio 的PowerService展示了如何以单一生命周期托管服务封装 Electron 电源 API 的全部复杂性类型化且去重的通知事件、跨平台有界关机屏障、引用计数 偏好门控的防睡眠注册表、电平触发的状态查询以及自读偏好与 WhenReady 阶段的优雅集成。对于需要与操作系统电源生命周期打交道的 Electron 应用这是一份值得借鉴的完整参考实现——进一步深入可阅读 PowerService 源码、单元测试 以及 Job 系统调用示例。【免费下载链接】cherry-studio Cherry Studio 是一款支持多个 LLM 提供商的桌面客户端项目地址: https://gitcode.com/CherryHQ/cherry-studio创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Cherry Studio 电源中枢 PowerService 深度解析：Electron powerMonitor 与电源管理的统一封装
Cherry Studio 电源中枢 PowerService 深度解析Electron powerMonitor 与电源管理的统一封装【免费下载链接】cherry-studio Cherry Studio 是一款支持多个 LLM 提供商的桌面客户端项目地址: https://gitcode.com/CherryHQ/cherry-studioCherry Studio 的PowerService源码是系统电源管理的统一中枢一个由应用生命周期托管lifecycle-managed的单例服务它独占所有 ElectronpowerMonitor/powerSaveBlocker相关的职责使应用其余部分永远不需要直接触碰这些底层 API。本文基于仓库中的 power 模块说明文档 并结合源码实现完整讲解它的五大职责电源通知事件、关机屏障、防睡眠、状态查询以及生命周期集成读者读完后将掌握在 Cherry Studio 中如何安全地监听系统挂起/恢复、在系统关机前执行清理、以及为长任务申请阻止系统睡眠的完整实战方案。为什么需要 PowerService集中管理电源职责Electron 桌面应用常常需要感知系统电源状态笔记本合盖挂起、屏幕锁定、电源从电池切换到交流电、系统即将关机、长时间后台任务需要阻止睡眠等。如果每个模块都各自直接调用powerMonitor/powerSaveBlocker会带来三个典型问题事件去重缺失macOS 上suspend/resume事件会触发两次见 electron/electron#24803各调用方需要各自实现去重逻辑关机清理不完整系统关机时如果直接退进程正在进行的文件写入、状态持久化会被截断阻止睡眠失控多个模块同时申请阻止睡眠时没有引用计数很难知道谁在阻止睡眠、何时可以安全释放。PowerService 正是为解决这些问题而生它把上述所有电源关注点收敛到单一服务之后对外暴露类型化事件、关机屏障、引用计数的防睡眠持有hold和电平触发level-triggered的查询 API。职责总览职责领域提供能力通知事件类型化Emitter→EventonSuspend/onResume/onLockScreen/onUnlockScreen/onPowerSourceChange。其中 suspend/resume 与电源来源power-source会基于内部状态去重应对 macOS 双重触发electron/electron#24803lock/unlock 为透传转发关机屏障registerShutdownHandler(fn)→Disposable。系统关机时处理器串行执行并被硬超时约束随后应用退出。跨平台macOS/Linux 使用powerMonitor的shutdown事件 preventDefaultWindows 使用paymoapp/electron-shutdown-handler防睡眠preventSleep(reason?)→Disposable。基于引用计数持有只有至少存在一个持有 AND 用户通过app.power.prevent_sleep_when_busy偏好开启时OS 阻塞器prevent-app-suspension才处于激活状态。isPreventingSleep()返回有效状态查询getPowerPhase()/getPowerSource()/isOnBatteryPower()/getSystemIdleTime()/getSystemIdleState(thresholdSec)—— 电平触发式迟到的调用者无需观察过边沿事件即可对账当前状态快速上手三类典型用法按照 README 的 Quick Start以下是完整可用的入门代码。PowerService已注册进应用容器通过application.get(PowerService)即可获取import { application } from application const power application.get(PowerService) // 1. 在某个工作的存续期内保持机器唤醒 // 仅当用户开启了 app.power.prevent_sleep_when_busy 时真正生效 const hold power.preventSleep(job:export) try { await doWork() } finally { hold.dispose() // 幂等可重复调用 } // 2. 响应系统挂起/恢复 this.registerDisposable(power.onSuspend(() pauseLongPoll())) this.registerDisposable(power.onResume(() resumeLongPoll())) // 3. 在 OS 关机前执行清理 this.registerDisposable(power.registerShutdownHandler(() flushCriticalState()))三个要点值得注意preventSleep返回的Disposable与事件订阅、关机处理器注册返回的Disposable都能安全地交给生命周期基类如BaseService的registerDisposable统一管理服务停止时自动释放registerShutdownHandler的处理器可以是同步函数也可以是返回Promise的异步函数类型为() void | Promisevoid串行执行、错误隔离所有 API 都遵循绝不抛出、总是返回可用对象的约定调用方无需防御式try/catch。电源通知事件类型化 Emitter 与去重机制PowerService 通过类型化Emitter对外暴露五个事件内部状态为powerPhaseactive | suspended与powerSourceac | battery | unknown见 PowerService.ts 事件定义与初始化suspend / resume 去重内部维护powerPhase状态机。收到suspend时若当前已是suspended则直接忽略否则置状态并触发onSuspendresume同理。这正是针对 macOS 双重触发electron/electron#24803的防御power-source 去重updatePowerSource()仅在来源真正变化时才更新状态并触发onPowerSourceChange重复的on-ac/on-battery事件不会重复广播lock / unlock 透传屏幕锁定/解锁没有需要去重的状态机直接转发初始状态播种服务初始化时即从powerMonitor.onBatteryPower读取当前电源来源并写入powerSource保证第一个查询/事件就是正确的见 PowerService.ts#L118。单元测试 PowerService.test.ts 中的事件用例完整覆盖了这些行为重复suspend只触发一次回调、未挂起时收到resume不触发、lock-screen 透传两次、电源来源仅在真实变化时广播。关机屏障在系统关机前完成清理有界串行执行registerShutdownHandler(handler)将处理器推入内部数组并返回可注销的Disposable按索引移除。当系统报告即将关机时executeShutdownHandlers()会串行依次await每个处理器错误隔离单个处理器抛错仅记录日志不影响后续处理器执行硬超时兜底整体执行受SHUTDOWN_HANDLER_TIMEOUT_MS 50005 秒约束通过Promise.race([run, timeout])实现——即使某个处理器永久挂起5 秒后也会强制进入退出流程绝不拖住用户机器的关机操作见 PowerService.ts#L23 与 #L188-L213。测试中的 force-quits when a handler hangs past the timeout 用例用假定时器验证了这一点一个永不 resolve 的处理器不会阻塞退出。macOS / LinuxpreventDefault → 执行处理器 → quit在 macOS/Linux 上powerMonitor.on(shutdown, ...)监听器收到事件后先调用event.preventDefault()推迟系统关机然后串行执行所有关机处理器最后调用application.quit()而不是裸app.quit()走应用正常的退出流程见 PowerService.ts#L215-L235。实现细节Electron 类型定义中shutdown监听器签名为() void但运行时确实会传入带preventDefault的事件对象。源码将事件参数声明为可选event?: Electron.Event既兼容类型重载又能在运行时调用preventDefault。Windows原生关机消息钩子 隐藏窗口Windows 路径使用paymoapp/electron-shutdown-handler原生插件通过WM_QUERYENDSESSION钩住系统关机消息见 PowerService.ts#L237-L287流程为blockShutdown()→ 执行处理器 →releaseShutdown()→application.quit()。源码注释中披露了几个关键的工程决策自建隐藏窗口而非复用主窗口主窗口是单例、可能在服务初始化时尚未存在、且销毁重建会更换 HWND而插件需要稳定的 HWND 挂接关机消息。因此服务自建一个show: falsepaintWhenInitiallyHidden: falseskipTaskbar: true的BrowserWindow仅作为原生句柄载体、从不加载任何内容零渲染进程开销由于不加载内容且paintWhenInitiallyHidden: false阻止激活/绘制Electron 不会为该窗口派生独立渲染进程在窗口子系统已初始化的前提下实测边际成本仅约 0.7 MB RSS可视为近乎免费必须显式调用blockShutdown()若只挂监听器而不调用blockShutdown插件只会观察到关机事件而不会真正按住系统——这一调用是 Windows 路径成为真正屏障的关键且必须在监听器挂载之后调用。对应测试用例断言了setWindowHandle、on(shutdown)、blockShutdown均被调用回调执行后releaseShutdown与quit各调用一次。退出流程的一致性无论哪个平台最终都经由application.quit()走before-quit流程。这意味着如果应用存在活动的Application.preventQuit持有例如正在进行数据迁移它会像拦截用户主动退出一样拦截 OS 发起的关机——受关机处理器硬超时的限制因为 OS 不能被无限期阻塞见 README Notes。防睡眠引用计数持有 用户偏好门控设计模型防睡眠采用通用注册表 正交门控模型见 PowerService.ts#L293-L356持有注册表任何需要机器保持唤醒的 worker 调用preventSleep(reason?)注册一个持有返回Disposable工作结束时dispose()释放偏好门控preventEnabled来自用户偏好app.power.prevent_sleep_when_busy由服务内部自行读取自读模式与TrayService/ThemeService/ProxyService一致并通过pref.subscribeChange(...)实时订阅变化有效状态 门控开启 AND 持有数 0applyBlockerState()是唯一的幂等收敛点任何路径获取持有、释放持有、偏好变更、服务停止都汇聚到这里决定启动/停止 OS 阻塞器。持有的数据结构是Mapsymbol, { reason?: string; since: number }而非裸计数器dispose()通过Map.delete天然幂等第二次调用返回false即不再动作且持有可枚举便于排查谁在持有、从何时开始的泄漏问题见 PowerService.ts#L77。prevent-app-suspension 的选择阻塞器使用powerSaveBlocker.start(prevent-app-suspension)见 PowerService.ts#L316该模式保持系统运行但允许显示器休眠——对后台工作任务、下载而言是正确选择不同于会阻止显示器休眠的prevent-display-sleep。尽力而为、绝不抛出applyBlockerState()将powerSaveBlocker.start/stop的任何失败记录日志并吞掉因此preventSleep()永远返回一个可用的Disposable即使 OS 阻塞器启动失败也不影响调用方调用方无需任何防御式try/catch优雅降级内聚在 provider 内部而不是散落在每个调用点失败后的自动恢复下一次preventSleep/dispose/ 偏好变更会重新运行收敛逻辑可纠正当前不一致的阻塞状态见 PowerService.ts#L310-L330。测试对此有专门用例powerSaveBlocker.start抛出异常时preventSleep不抛、仍返回可用且可幂等释放的持有。引用计数行为测试验证了完整语义见 PowerService.test.ts偏好关闭时即使有持有也不启动阻塞器偏好开启且无持有时不启动持有到达时启动一次prevent-app-suspension多个持有共享同一个阻塞器只有最后一个释放后才停止持有期间用户关闭偏好阻塞器立即释放持有期间用户开启偏好阻塞器立即启动。查询 API电平触发式状态读取查询类 API 均为电平触发level-triggered设计迟到的调用者无需观察到边沿事件即可对账当前状态见 PowerService.ts#L358-L381getPowerPhase(): active | suspended—— 返回内部状态机当前值getPowerSource(): ac | battery | unknown—— 返回已去重的当前电源来源isOnBatteryPower(): boolean—— 直接转发powerMonitor.onBatteryPowergetSystemIdleTime(): number—— 系统空闲秒数将服务于 Job 系统的after-idle追赶策略见 catchUp.ts 中的预留注释getSystemIdleState(thresholdSec): active | idle | locked | unknown—— 按阈值判定空闲状态。测试验证了这些 API 正确转发到底层powerMonitor并透传阈值参数。生命周期集成WhenReady 阶段的自足服务PowerService声明为Injectable(PowerService)且ServicePhase(Phase.WhenReady)见 PowerService.ts#L52-L54即在应用 WhenReady 阶段初始化——此时应用已经 readypowerSaveBlocker/BrowserWindow可直接使用无需app.whenReady()体操onInit()依次初始化电源事件、关机屏障、防睡眠三个子系统onStop()清理清空关机处理器、停止活动阻塞器、清空全部持有。它注册于应用服务注册表见 serviceRegistry.ts与TrayService/ThemeService/ProxyService一样采用自读偏好模式。实战Job 系统如何接入防睡眠Job 系统是preventSleep的首个注册者。在 JobManager.ts#L1798-L1832 中每个任务尝试attempt开始时获取持有finally中释放const task (async () { // 尽力而为受用户 app.power.prevent_sleep_when_busy 偏好门控。 // preventSleep 绝不抛出、总是返回 Disposable因此这里无需防御。 const sleepHold application.get(PowerService).preventSleep(job:${row.type}:${row.id}) try { const output await handler.execute(ctx) // ... 完成/失败分类、重试调度 } finally { // ... 释放 } })()值得注意的细节是按尝试per-attempt持有任务在两次重试之间处于delayed状态非工作状态不应持有机器唤醒——注释明确指出这一设计意图见 JobManager.ts#L1802-L1803。流式传输等后续 worker 可通过同一 API 自行注册。用户偏好与开关位置防睡眠的用户开关位于设置 → 通用Settings → General。偏好定义位于数据分类配置 target-key-definitions.json{ targetKey: app.power.prevent_sleep_when_busy, type: boolean, defaultValue: false, status: classified, description: Prevent system sleep while the app has active work (v2 new feature, no v1 source) }关键事实默认值为false用户未开启时即使有 worker 请求系统也不会被阻止睡眠该偏好为 v2 新增特性无 v1 来源。总结Cherry Studio 的PowerService展示了如何以单一生命周期托管服务封装 Electron 电源 API 的全部复杂性类型化且去重的通知事件、跨平台有界关机屏障、引用计数 偏好门控的防睡眠注册表、电平触发的状态查询以及自读偏好与 WhenReady 阶段的优雅集成。对于需要与操作系统电源生命周期打交道的 Electron 应用这是一份值得借鉴的完整参考实现——进一步深入可阅读 PowerService 源码、单元测试 以及 Job 系统调用示例。【免费下载链接】cherry-studio Cherry Studio 是一款支持多个 LLM 提供商的桌面客户端项目地址: https://gitcode.com/CherryHQ/cherry-studio创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考