🔌 插件开发概览
EchoMusic 插件系统提供了一套高自由度的本地扩展机制，定位类似 VS Code 或 Obsidian 的插件体系。插件可以定制界面、扩展功能、处理音频数据，并与播放器深度集成。
插件系统架构
整体架构
┌────────────────────────────────────────┐
│ EchoMusic 主应用 │
│ ┌──────────┐ ┌──────────┐ │
│ │ 主窗口 │ │ Mini 播放器│ │
│ │ (Electron)│ │ (独立窗口) │ │
│ ├──────────┤ ├──────────┤ │
│ │ 插件 A │ │ 插件 A │ ← 若开启 │
│ │ 插件 B │ │ │ miniPlayer│
│ │ 插件 C │ │ │ │
│ └──────────┘ └──────────┘ │
│ ┌──────────┐ │
│ │ 桌面歌词 │ │
│ │ (独立窗口) │ │
│ ├──────────┤ │
│ │ 插件 A │ ← 若开启 desktopLyric │
│ └──────────┘ │
│ ▲ │
│ │ ctx 对象注入 │
│ │ │
│ ┌────┴─────┐ │
│ │ 插件管理器 │ 加载 / 卸载 / 生命周期 │
│ └──────────┘ │
└────────────────────────────────────────┘ctx API 体系
ctx 是插件的核心入口对象，按功能分为 8 大模块：
ctx
├── 🏗️ 宿主运行时 → vue / app / router / pinia
├── 📦 状态管理 → stores.player / playlist / lyric / settings / theme
├── 🎨 UI 扩展 → addPage / sidebar / settings / 右键菜单 / mount / teleport
├── 🎵 播放 & 音频 → 播放控制 / 播放队列 / 频谱 / 音源 / 歌词
├── 💾 数据 & 文件 → KV 存储 / 文件系统 / 外观订阅
├── 🪟 窗口 & 系统 → 浮窗 / NowPlaying / 进程 / 图标
├── 🎨 主题 & 样式 → surface / pageTransition / accentGradient / scroll
└── 📋 插件管理 → 生命周期 / 市场 / 安装 / 故障上报完整的插件 API 速查请见 API 总览 →。内部 API（FFmpeg 引擎/桌面歌词等）详见 内部 API 参考 →。
多窗口模型
EchoMusic 有三个独立的渲染窗口，彼此不共享 JS 内存：
| 窗口 | 说明 | 插件参与方式 |
|---|---|---|
| 主窗口 | 完整的播放器界面、设置、插件管理等 | 默认加载所有已启用插件 |
| Mini 播放器 | 精简的迷你播放窗口 | 需在 manifest 中声明 runtime.miniPlayer: true |
| 桌面歌词 | 悬浮桌面歌词窗口 | 需在 manifest 中声明 runtime.desktopLyric: true |
如果插件只操作主窗口（例如添加设置面板、注册页面），无需开启 miniPlayer 或 desktopLyric。
插件生命周期
[用户启用插件]
│
▼
┌─────────────┐ ┌──────────────────┐
│ 加载 manifest │ ──▶ │ 校验 version / │
│ │ │ capabilities │
└─────────────┘ └──────┬───────────┘
│
┌────────▼──────────┐
│ 版本不符？ │
│ → 提示"版本不兼容" │
│ 阻止启用 │
└────────┬──────────┘
│ 通过
┌────────▼──────────┐
│ 加载入口 JS (ESM) │
│ 注入 ctx 对象 │
└────────┬──────────┘
│
┌────────▼──────────┐
│ activate(ctx) │
│ 插件注册资源 │
└────────┬──────────┘
│
┌──────────────┼──────────────┐
│ │ │
▼ ▼ ▼
正常运行 用户禁用/卸载 崩溃/异常
│ │ │
│ ┌──────▼──────┐ │
│ │deactivate() │ │
│ │自动清理资源 │ │
│ │ctx.dispose()│ │
│ └──────┴──────┘ │
│ │
└──────────────┬──────────────┘
│
┌────────▼──────────┐
│ 插件停止 │
│ 卸载时删除插件目录 │
│ 清除 KV 数据和故障记录│
└───────────────────┘安全模型
信任边界
- 插件是用户主动启用的本地代码，运行在 Electron 渲染进程中
- EchoMusic 不对插件做沙箱隔离——插件可以访问主渲染进程的所有 API
- 因此必须只启用来源可信的插件
能力声明（Capabilities）
插件对敏感 API 的访问采用显式声明机制：
| Capability | 授予的 API 访问 |
|---|---|
audioSource | ctx.player.audioSource.register() — 接管音源解析 |
audioSpectrum | ctx.audio.spectrum — 读取/订阅音频频谱数据 |
kugouApi | ctx.kugou — 调用酷狗 API |
localFiles | ctx.fs — 扫描/读写本地文件 |
lyricEffects | ctx.lyricEffects.register() — 注册歌词动效 |
lyrics | ctx.lyrics.registerResolver() — 提供自定义歌词 |
process | ctx.process.launch() — 启动插件目录内的程序 |
遵循最小权限原则：只声明插件实际需要的 capability。
开发环境要求
- Node.js：建议 18+
- 代码环境：浏览器 ESM（不支持 Node.js 内置模块如
fs、path） - Vue 依赖：通过
ctx.vue获取，不要使用 bare import（如import { ref } from 'vue'） - 构建工具（可选）：如需使用 TypeScript 或 Vue SFC，使用 Vite / esbuild 打包为单文件 ESM
文档导航
入门
| 文档 | 适合人群 | 内容 |
|---|---|---|
| 快速开始 → | 新手 | 从零搭建第一个插件（5 分钟） |
| Manifest 配置参考 → | 所有人 | manifest.json 完整字段说明 |
| API 总览 → | 所有人 | ctx 对象完整插件 API 速查表 |
深入
| 文档 | 内容 |
|---|---|
| UI 扩展指南 → | 页面、设置面板、右键菜单、组件注入、CSS 动态注入 |
| 播放器与音频引擎 → | 播放控制、播放队列、频谱、歌词系统、自定义音源 |
| 音频频谱 → | 实时 FFT 频谱数据订阅、可视化、VU 表 |
| 文件存储与数据 → | 文件系统读写、KV 存储、外观订阅、主题 API |
| 窗口与系统 → | 浮窗、Now Playing、进程、图标、跨窗口通信 |
| 发布与分发 → | 插件源、版本管理、在线安装、安全模式、故障上报、TypeScript/Vue SFC 打包 |