通道参考
按领域整理 Desktop IPC 的方法、事件与传输方式。
业务代码看到的是 DesktopBridge 方法；真正的 channel 名称只在 Preload 和 Main 之间使用。当前命名遵循 <domain>:<action>，例如 cache:get、config:update-host、desktop-lyric:command。
请求与命令
| 领域 | Contract 方法 | 典型 channel / 传输 | 语义 |
|---|---|---|---|
| Bridge | getBridgeInfo | bridge:get-info / invoke | 获取能力与版本 |
| Backend | getBackendStatus、onBackendStatusChanged | backend:get-status、backend:status-changed | 查询和订阅内置后端状态 |
| App / Window | exitApp、relaunchApp、minimizeApp、sendAppCloseAction、enterFullScreen、exitFullScreen、getHostname | send、app:get-hostname / invoke | 执行窗口和应用命令，读取当前主机名 |
| Navigation | navigateTo、onNavigate | navigate-main-window、navigate-to | 主窗口导航与反向通知 |
| Media controls | setPlayerPlaying、onControlAudio | player-state-changed、control-audio / send + on | 同步播放状态和系统媒体按键 |
| Config | getHostConfig、updateHostConfig、selectDirectory | config:*、dialog:select-directory / invoke | 读取和保存宿主配置 |
| Auth | openLoginWindow、loginSuccess、setCookie；getMusicCookie 仅供旧版迁移 | send、set-music-cookie、get-music-cookie | 登录窗口、CookieJar 导入与旧凭据兼容 |
| Cache | get*、set*、delete*、clear*、get*Stats | cache:* / invoke | 页面、播放和分类缓存 |
| Updates | getUpdateStatus、checkForUpdates、downloadUpdate、quitAndInstallUpdate | updater:* | 更新生命周期 |
| Logs | writeLog、getLogDirectory、openCurrentLog、openLogDirectory | logger:* / invoke | Renderer 日志和日志目录 |
| Lyrics | openDesktopLyric、closeDesktopLyric、toggleDesktopLyric、sendDesktopLyricCommand | desktop-lyric:* | 桌面歌词控制与命令 |
| Dynamic island | toggleDynamicIsland、updateDynamicIslandPreferences、sendDynamicIslandCommand、onDynamicIslandModeChanged | dynamic-island:* | 灵动岛窗口、拖拽吸附与命中区域 |
| Taskbar lyric | toggleTaskbarLyric、updateTaskbarLyricPreferences、sendTaskbarLyricCommand、onTaskbarLyricLayoutChanged | taskbar-lyric:* | 任务栏嵌入、布局推送与内容宽度 |
| Playback wallpaper | getDesktopPlaybackWallpaperModel、updateDesktopPlaybackWallpaperPreferences、retryDesktopPlaybackWallpaper | desktop-playback-wallpaper:* | 播放背景状态和配置 |
| Playback controller | showDesktopPlaybackController、closeDesktopPlaybackController、setDesktopPlaybackControllerLayout | desktop-playback-controller:* | 播放控制器窗口 |
| Icons | getDesktopIconVisibility、setDesktopIconVisibility | desktop-icons:* | 桌面图标可见性 |
| Discord | getDiscordPresenceStatus、testDiscordPresenceConnection、publishDiscordPresenceSnapshot | discord-presence:* | Presence 状态与发布 |
| Video export | getVideoExportCaptureSource、prepareVideoExportWindow、selectVideoExportFile、writeVideoExportFile | video-export:* / invoke | 捕获、选择路径与写文件 |
| Audio feature transport | connectAudioFeatureTransport、publishAudioFeatureFrame | audio-feature-transport:connect / MessagePort | 高频音频特征帧 |
| Playback transport | connectPlaybackTransport、sendPlaybackTransportPayload | playback-transport:connect / MessagePort | 播放状态、歌词和跨窗口传输 |
事件订阅
以下 on* 方法都返回 Unsubscribe：
onBackendStatusChangedonUpdateStatusChangedonFullScreenChangedonNavigateonControlAudioonDesktopLyricCommandonDesktopPlaybackWallpaperModelChangedonDiscordPresenceStatusChanged
Preload 会接收 Electron event，但只把业务 payload 传给回调。Renderer 不应保存或使用 event 对象，也不应自行调用 ipcRenderer.removeListener。
高频传输
音频特征和播放传输不是普通的“一次调用一个结果”：
connect(role, connectionId, onPayload, onClose)
↓
MessageChannel / MessagePort
↓
publish(frame) 或 send(payload)
↓
返回 boolean，表示当前端口是否成功接收这类通道需要处理关闭、错误和重连；不要把高频帧放进 ipcRenderer.invoke 的循环中。
Channel 命名约束
- channel 使用小写领域名和 kebab-case 动作，例如
desktop-lyric:get-preferences。 - 查询/变更使用
invoke，无返回命令使用send，连续数据使用 MessagePort。 - 状态推送使用
:<status-changed>或:<model-changed>后缀。 - 新增 channel 必须同时更新 Contract、Preload、Main handler、Electron adapter、Browser fallback 和本页索引。