Update to v0.0.4: add aggregated plugins with API failover, update docs

2026-06-20 12:31:39 +08:00
commit c6eeb253d0
14 changed files with 7890 additions and 0 deletions
--- a/插件规范(v1.0.3).md
+++ b/插件规范(v1.0.3).md
@@ -0,0 +1,862 @@
+# 插件开发帮助文档
+
+> **版本**: v1.0.3
+> 
+> 撰写人: 蜻蜓的好朋友 : Miao-moe  
+> GitHub: [Miao-moe](https://github.com/Miao-moe)
+
+## 目录
+1. [概述](#概述)
+2. [核心设计原则](#核心设计原则)
+3. [从其他平台迁移指南](#从其他平台迁移指南)
+4. [插件基本结构](#插件基本结构)
+5. [数据格式规范](#数据格式规范)
+6. [示例代码详解](#示例代码详解)
+7. [平台配置参考](#平台配置参考)
+8. [开发建议](#开发建议)
+9. [常见问题](#常见问题)
+
+---
+
+## 概述
+
+本文档用于指导开发者编写音源插件。本系统使用 Node.js 运行时环境，插件采用 CommonJS 模块规范，通过 `module.exports` 导出功能接口。
+
+### 与其他系统的区别
+
+| 特性 | 本系统 | 其他系统 |
+|------|--------|----------|
+| 运行时 | Node.js | JavaScript 运行时 |
+| 模块规范 | CommonJS | 全局事件监听 |
+| 导出方式 | `module.exports` | 事件发送 |
+| 通信方式 | 直接函数调用 | 事件驱动 |
+| HTTP 请求 | `axios` 或内置 `httpFetch` | 全局请求对象 |
+
+### 插件类型
+
+本系统插件属于**完整音源插件**，核心功能包括：
+- 搜索内容
+- 获取播放 URL
+- 获取歌词
+- 获取列表/合集信息
+- 获取热搜/排行榜
+
+---
+
+## 核心设计原则
+
+### 1. 单平台原则（重要）
+
+**每个插件只支持一个平台**，例如：
+- ✅ 平台A插件（仅支持 A）
+- ✅ 平台B插件（仅支持 B）
+- ❌ 聚合插件（同时支持 A + B + C）
+
+**原因说明**：
+```
+用户向插件传配置只能通过环境变量（env）
+如果插件支持多平台，切换平台时需要修改环境变量，操作繁琐
+单平台插件更清晰，维护成本低，不易出现"代码屎山"
+```
+
+**如需多平台支持**：建议自建后端服务，统一处理搜索和 URL 获取，前端插件只作为代理。
+
+### 2. 配置方式
+
+通过 `global.env` 读取环境变量（JSON 格式）：
+
+```javascript
+// 读取用户配置的 API 密钥
+const env = global.env || {}
+const API_KEY = env.API_KEY || ''
+
+// 读取自定义服务端地址
+const CUSTOM_SERVER = env.SERVER_URL || '默认地址'
+```
+
+**环境变量加载方式**：
+```javascript
+const plugin = require('./index.js')
+global.env = $envCommand  // 由系统注入，格式为 JSON
+
+// 在插件代码中通过 global.env 读取
+const env = global.env || {}
+const API_KEY = env.API_KEY || ''
+```
+
+### 3. 支持的音质标识
+
+| 标识 | 说明 |
+|------|------|
+| `128k` | 标准音质 |
+| `320k` | 高品音质 |
+| `flac` | 无损音质 |
+| `flac24bit` | 高解析度无损 |
+| `hires` | 超高解析度 |
+
+---
+
+## 从其他平台迁移指南
+
+### 迁移对照表
+
+| 其他系统 | 本系统 | 说明 |
+|----------|--------|------|
+| `globalThis.lx` | `require` 模块 | 不再需要全局对象 |
+| `globalThis.lx.request` | `axios` 或 `httpFetch` | 使用标准 HTTP 库 |
+| `globalThis.lx.env` | `global.env` | 环境变量读取方式 |
+| `on(EVENT_NAMES.request, ...)` | 直接导出函数 | 改为函数导出 |
+| `send(EVENT_NAMES.inited, ...)` | `module.exports` | 改为模块导出 |
+| `musicInfo.songmid` | `musicInfo.id` | 字段名可能不同 |
+| `info.type` | `quality` 参数 | 音质参数位置 |
+
+### 迁移步骤
+
+#### 步骤 1：修改模块导入
+
+**其他系统原代码：**
+```javascript
+const { EVENT_NAMES, request, on, send, env, version } = globalThis.lx
+```
+
+**本系统新代码：**
+```javascript
+const axios = require('axios')
+const crypto = require('crypto')
+
+// 环境变量从 global.env 读取
+const env = global.env || {}
+const API_KEY = env.API_KEY || ''
+```
+
+#### 步骤 2：修改 HTTP 请求
+
+**其他系统原代码：**
+```javascript
+function httpRequest(url) {
+  return new Promise((resolve, reject) => {
+    request(url, { headers }, (err, resp) => {
+      if (err) return reject(err)
+      resolve(resp.body)
+    })
+  })
+}
+```
+
+**本系统新代码：**
+```javascript
+async function httpRequest(url, options = {}) {
+  const response = await axios({
+    url,
+    method: options.method || 'GET',
+    headers: options.headers,
+    timeout: options.timeout || 10000
+  })
+  return response.data
+}
+```
+
+#### 步骤 3：修改函数导出
+
+**其他系统原代码：**
+```javascript
+// 事件监听方式
+on(EVENT_NAMES.request, ({ action, source, info }) => {
+  switch (action) {
+    case 'musicUrl':
+      return getMusicUrl(info.musicInfo, info.type)
+  }
+})
+
+// 初始化事件
+send(EVENT_NAMES.inited, {
+  status: true,
+  sources: musicSource
+})
+```
+
+**本系统新代码：**
+```javascript
+// 直接导出函数
+module.exports = {
+  // 搜索功能
+  musicSearch,
+  
+  // 获取 URL
+  getUrl,
+  
+  // 获取歌词
+  getLyric,
+  
+  // 获取列表
+  songList,
+  
+  // 获取合集
+  album,
+  
+  // 获取热搜
+  hotSearch,
+  
+  // 插件信息
+  pluginInfo: {
+    info: { id: 'A', name: '平台A', version: '3' },
+    quality: [...],
+    supportFunc: [...]
+  }
+}
+```
+
+#### 步骤 4：修改返回数据格式
+
+**其他系统原代码：**
+```javascript
+// 直接返回 URL 字符串
+return 'https://example.com/audio.mp3'
+
+// 或返回歌词对象（其他系统格式）
+return {
+  lyric: '[00:00.000]歌词内容',
+  tlyric: '[00:00.000]翻译歌词'
+}
+```
+
+**本系统新代码：**
+```javascript
+// 搜索返回统一格式
+return {
+  list: [{
+    id: '123456',
+    name: '内容名',
+    artists: '创作者',
+    source: 'A',
+    pic: '封面URL',
+    mPic: '中封面URL',
+    sPic: '小封面URL',
+    albumName: '合集名',
+    albumId: '合集ID',
+    interval: '03:45',
+    qualities: { '128k': '4.2M', 'flac': '35M' }
+  }],
+  total: 100,
+  page: 1,
+  limit: 20,
+  allPage: 5,
+  source: 'A'
+}
+
+// 歌词返回格式（见下文歌词格式规范）
+// 系统支持多种歌词格式，返回有的即可
+return {
+  lrc: 'LRC格式歌词',
+  qrc: 'QRC逐字歌词',
+  krc: 'KRC歌词',
+  ttml: 'TTML歌词',
+  translate: '翻译歌词'
+}
+
+// 或直接返回歌词文本字符串（系统会自动判断格式）
+return '[00:00.000]歌词内容\n[00:05.000]第二行歌词...'
+```
+
+---
+
+## 插件基本结构
+
+### 核心导入
+
+```javascript
+'use strict'
+
+// 标准 Node.js 模块
+const axios = require('axios')
+const crypto = require('crypto')
+```
+
+### 配置区域
+
+```javascript
+// ========== 用户可配置区域 ==========
+
+// 从 global.env 读取环境变量（JSON 格式）
+const env = global.env || {}
+
+// 服务端地址（用户可通过环境变量覆盖）
+const API_BASE = env.SERVER_URL || 'https://your-server.com'
+
+// API 密钥（用户通过环境变量设置）
+const API_KEY = env.API_KEY || ''
+
+// 当前平台标识（单平台插件固定值）
+const PLATFORM = 'A'
+
+// 支持的音质列表
+const SUPPORT_QUALITIES = ['128k', '320k', 'flac']
+```
+
+### 导出结构
+
+```javascript
+// ========== 插件导出 ==========
+
+module.exports = {
+  // 核心功能（必须实现）
+  musicSearch,      // 内容搜索
+  getUrl,           // 获取 URL
+  
+  // 可选功能
+  getLyric,         // 获取歌词
+  songList,         // 列表详情
+  album,            // 合集详情
+  hotSearch,        // 热搜词
+  tipSearch,        // 搜索提示
+  leaderboard,      // 排行榜
+  
+  // 插件信息（必须）
+  pluginInfo: {
+    info: {
+      id: 'A',                    // 平台标识
+      name: '平台A',               // 显示名称
+      description: '平台A插件',     // 描述
+      version: '3'                 // 版本号
+    },
+    env: [                          // 环境变量配置
+      { key: 'API_KEY', name: 'API密钥', description: '服务端API密钥' }
+    ],
+    ext: [],                        // 扩展功能
+    quality: [                      // 支持的音质
+      { name: '标准音质', ui: '标', id: '128k' },
+      { name: '高品音质', ui: 'HQ', id: '320k' },
+      { name: '无损音质', ui: 'SQ', id: 'flac' }
+    ],
+    supportFunc: [                  // 支持的功能
+      'search_song',
+      'search_playlist',
+      'playlist',
+      'album',
+      'lyric'
+    ]
+  }
+}
+```
+
+---
+
+## 数据格式规范
+
+### 搜索结果统一格式
+
+```javascript
+{
+  list: [
+    {
+      id: String,              // 唯一标识
+      name: String,             // 名称
+      artists: String,          // 创作者（用 "、" 分隔）
+      source: String,           // 平台标识
+      pic: String,              // 大封面 URL
+      mPic: String,             // 中封面 URL
+      sPic: String,             // 小封面 URL
+      albumName: String,        // 合集名
+      albumId: String,          // 合集 ID
+      interval: String,         // 时长 "mm:ss"
+      qualities: {              // 音质 -> 文件大小
+        '128k': '4.2M',
+        '320k': '8.5M',
+        'flac': '35M'
+      }
+    }
+  ],
+  total: Number,               // 总数量
+  page: Number,                // 当前页码
+  limit: Number,               // 每页数量
+  allPage: Number,             // 总页数
+  source: String               // 平台标识
+}
+```
+
+### 歌词返回格式
+
+**重要说明**：系统会自动判断歌词格式（lrc、qrc、krc、ttml 等），插件只需返回对应的歌词字段即可。
+
+```javascript
+// 推荐返回格式
+{
+  lrc: String,       // LRC 格式歌词
+  qrc: String,       // QRC 逐字歌词
+  krc: String,       // KRC 歌词
+  ttml: String,      // TTML 歌词
+  translate: String  // 翻译歌词
+}
+
+// 或者直接返回歌词文本字符串（系统会自动判断格式）
+return '[00:00.000]歌词内容\n[00:05.000]第二行歌词...'
+```
+
+**字段说明**：
+
+| 字段 | 说明 | 格式 |
+|------|------|------|
+| `lrc` | 标准 LRC 歌词 | `[mm:ss.ms]歌词内容` |
+| `qrc` | 逐字歌词 | QRC 格式（Base64 编码） |
+| `krc` | KRC 歌词 | KRC 格式 |
+| `ttml` | TTML 歌词 | TTML/XML 格式 |
+| `translate` | 翻译歌词 | LRC 格式或纯文本 |
+
+**注意事项**：
+- 以上字段均为可选，返回有的即可
+- 系统会自动识别歌词格式
+- `translate` 用于翻译歌词
+- 直接返回歌词文本字符串也是允许的，系统会尝试自动判断其格式
+- 不同平台可能返回不同格式，如：平台A可能返回 `qrc` + `translate`，平台B可能返回 `lrc` + `tlyric`
+
+### 列表详情统一格式
+
+```javascript
+{
+  list: [/* 内容列表，格式同搜索结果 */],
+  page: Number,
+  limit: Number,
+  total: Number,
+  source: String,
+  info: {
+    name: String,        // 列表名
+    img: String,         // 封面图
+    desc: String,        // 描述
+    author: String       // 创建者
+  }
+}
+```
+
+### 合集详情统一格式
+
+```javascript
+{
+  list: [/* 内容列表，格式同搜索结果 */],
+  page: Number,
+  limit: Number,
+  total: Number,
+  source: String,
+  info: {
+    name: String,        // 合集名
+    img: String,         // 封面图
+    desc: String,        // 描述
+    author: String       // 创作者
+  }
+}
+```
+
+---
+
+## 示例代码详解
+
+### 完整插件模板
+
+```javascript
+'use strict'
+
+// ==================== 核心导入 ====================
+
+const axios = require('axios')
+const crypto = require('crypto')
+
+// ==================== 配置区域 ====================
+
+// 从 global.env 读取环境变量（JSON 格式）
+const env = global.env || {}
+
+// 平台标识（固定值，单平台插件）
+const PLATFORM = 'A'
+
+// 服务端配置
+const CONFIG = {
+  serverUrl: env.SERVER_URL || 'https://api.example.com',
+  apiKey: env.API_KEY || '',
+  timeout: 10000
+}
+
+// 支持的音质
+const SUPPORT_QUALITIES = ['128k', '320k', 'flac']
+
+// ==================== 工具函数 ====================
+
+function sizeFormate(size) {
+  if (!size || isNaN(size)) return ''
+  if (size > 104857600) return (size / 104857600).toFixed(1) + 'MB'
+  if (size > 1048576) return (size / 1048576).toFixed(1) + 'MB'
+  if (size > 1024) return (size / 1024).toFixed(1) + 'KB'
+  return size + 'B'
+}
+
+function formatPlayTime(time) {
+  if (!time || isNaN(time)) return '--/--'
+  const m = Math.floor(time / 60)
+  const s = Math.floor(time % 60)
+  return m + ':' + s.toString().padStart(2, '0')
+}
+
+function formatArtistName(artistList) {
+  if (!artistList || !Array.isArray(artistList)) return ''
+  return artistList.map(a => a.name || a).join('、')
+}
+
+function decodeName(str) {
+  if (!str) return ''
+  return str
+    .replace(/&apos;/g, "'")
+    .replace(/&quot;/g, '"')
+    .replace(/&lt;/g, '<')
+    .replace(/&gt;/g, '>')
+    .replace(/&amp;/g, '&')
+    .replace(/&nbsp;/g, ' ')
+}
+
+// ==================== 核心功能 ====================
+
+async function musicSearch(str, page = 1, limit = 20) {
+  const params = { keyword: str, page, limit }
+  
+  const url = CONFIG.serverUrl + '/search'
+  const response = await axios.get(url, { 
+    params,
+    headers: { 'X-API-Key': CONFIG.apiKey },
+    timeout: CONFIG.timeout
+  })
+  
+  const data = response.data
+  
+  const list = data.items.map(item => ({
+    id: String(item.id),
+    name: decodeName(item.name),
+    artists: formatArtistName(item.artists),
+    source: PLATFORM,
+    pic: item.picUrl || '',
+    mPic: item.picUrl || '',
+    sPic: item.picUrl || '',
+    albumName: decodeName(item.album?.name || ''),
+    albumId: String(item.album?.id || ''),
+    interval: formatPlayTime(item.duration),
+    qualities: {
+      '128k': sizeFormate(item.size128),
+      '320k': sizeFormate(item.size320),
+      'flac': sizeFormate(item.sizeFlac)
+    }
+  }))
+  
+  return {
+    list,
+    total: data.total,
+    page,
+    limit,
+    allPage: Math.ceil(data.total / limit),
+    source: PLATFORM
+  }
+}
+
+async function getUrl(id, quality) {
+  if (!SUPPORT_QUALITIES.includes(quality)) {
+    quality = SUPPORT_QUALITIES[0]
+  }
+  
+  const url = CONFIG.serverUrl + '/url'
+  const response = await axios.get(url, {
+    params: { id, quality },
+    headers: { 'X-API-Key': CONFIG.apiKey },
+    timeout: CONFIG.timeout
+  })
+  
+  const data = response.data
+  
+  if (!data.url || !data.url.startsWith('http')) {
+    throw new Error('获取链接失败')
+  }
+  
+  return data.url
+}
+
+async function getLyric(id) {
+  const url = CONFIG.serverUrl + '/lyric'
+  const response = await axios.get(url, {
+    params: { id },
+    headers: { 'X-API-Key': CONFIG.apiKey },
+    timeout: CONFIG.timeout
+  })
+  
+  const data = response.data
+  
+  // 返回歌词对象，系统会自动判断格式
+  // 返回有的字段即可，不需要全部字段
+  return {
+    lrc: data.lrc || '',
+    qrc: data.qrc || '',
+    krc: data.krc || '',
+    ttml: data.ttml || '',
+    translate: data.translate || ''
+  }
+  
+  // 或者直接返回歌词文本
+  // return data.lyric
+}
+
+async function songList(id, page = 1, limit = 20) {
+  const url = CONFIG.serverUrl + '/list'
+  const response = await axios.get(url, {
+    params: { id, page, limit },
+    headers: { 'X-API-Key': CONFIG.apiKey },
+    timeout: CONFIG.timeout
+  })
+  
+  const data = response.data
+  
+  const list = data.items.map(item => ({
+    id: String(item.id),
+    name: decodeName(item.name),
+    artists: formatArtistName(item.artists),
+    source: PLATFORM,
+    pic: item.picUrl || '',
+    mPic: item.picUrl || '',
+    sPic: item.picUrl || '',
+    albumName: decodeName(item.album?.name || ''),
+    albumId: String(item.album?.id || ''),
+    interval: formatPlayTime(item.duration),
+    qualities: {}
+  }))
+  
+  return {
+    list,
+    page,
+    limit,
+    total: data.total,
+    source: PLATFORM,
+    info: {
+      name: data.name || '',
+      img: data.cover || '',
+      desc: data.description || '',
+      author: data.creator?.name || ''
+    }
+  }
+}
+
+async function album(id, page = 1) {
+  const url = CONFIG.serverUrl + '/album'
+  const response = await axios.get(url, {
+    params: { id, page },
+    headers: { 'X-API-Key': CONFIG.apiKey },
+    timeout: CONFIG.timeout
+  })
+  
+  const data = response.data
+  
+  const list = data.items.map(item => ({
+    id: String(item.id),
+    name: decodeName(item.name),
+    artists: formatArtistName(item.artists),
+    source: PLATFORM,
+    pic: item.picUrl || data.cover || '',
+    mPic: item.picUrl || data.cover || '',
+    sPic: item.picUrl || data.cover || '',
+    albumName: decodeName(data.name || ''),
+    albumId: String(id),
+    interval: formatPlayTime(item.duration),
+    qualities: {}
+  }))
+  
+  return {
+    list,
+    page,
+    limit: 1000,
+    total: data.total,
+    source: PLATFORM,
+    info: {
+      name: data.name || '',
+      img: data.cover || '',
+      desc: data.description || '',
+      author: data.artist?.name || ''
+    }
+  }
+}
+
+async function hotSearch() {
+  const url = CONFIG.serverUrl + '/hotsearch'
+  const response = await axios.get(url, {
+    headers: { 'X-API-Key': CONFIG.apiKey },
+    timeout: CONFIG.timeout
+  })
+  
+  return {
+    source: PLATFORM,
+    list: response.data.list || []
+  }
+}
+
+// ==================== 插件导出 ====================
+
+module.exports = {
+  musicSearch,
+  getUrl,
+  getLyric,
+  songList,
+  album,
+  hotSearch,
+  
+  pluginInfo: {
+    info: {
+      id: PLATFORM,
+      name: '平台A',
+      description: '平台A插件',
+      version: '3'
+    },
+    env: [
+      { key: 'SERVER_URL', name: '服务端地址', description: '自定义服务端地址' },
+      { key: 'API_KEY', name: 'API密钥', description: '服务端API密钥' }
+    ],
+    ext: [],
+    quality: [
+      { name: '标准音质', ui: '标', id: '128k' },
+      { name: '高品音质', ui: 'HQ', id: '320k' },
+      { name: '无损音质', ui: 'SQ', id: 'flac' }
+    ],
+    supportFunc: ['search_song', 'search_playlist', 'playlist', 'album', 'lyric']
+  }
+}
+```
+
+---
+
+## 平台配置参考
+
+### 各平台标识对照表
+
+| 平台 | 标识 | 常见 ID 字段 |
+|------|------|-------------|
+| 平台A | `A` | `id` |
+| 平台B | `B` | `id` |
+| 平台C | `C` | `id`, `hash` |
+| 平台D | `D` | `hash`, `id` |
+| 平台E | `E` | `id` |
+| 平台F | `F` | `id` |
+
+### 音质支持参考
+
+```javascript
+const PLATFORM_QUALITIES = {
+  A: ['128k', '320k', 'flac', 'flac24bit', 'hires'],
+  B: ['128k', '320k', 'flac', 'flac24bit', 'hires'],
+  C: ['128k', '320k', 'flac', 'flac24bit'],
+  D: ['128k', '320k', 'flac', 'flac24bit', 'hires'],
+  E: ['128k', '320k', 'flac', 'flac24bit'],
+  F: ['128k', '320k', 'flac']
+}
+```
+
+---
+
+## 开发建议
+
+### 多文件开发
+
+**推荐使用多文件开发模式**，将不同功能模块分离，防止代码堆叠：
+
+```
+plugin/
+├── index.js          # 主入口，导出模块
+├── search.js         # 搜索相关功能
+├── lyric.js          # 歌词相关功能
+├── playlist.js       # 列表相关功能
+├── utils.js          # 工具函数
+└── config.js         # 配置常量
+```
+
+### 使用 ncc 打包
+
+开发完成后，使用 `ncc` 将多文件打包为单文件即可：
+
+```bash
+# 安装 ncc
+npm install -g @vercel/ncc
+
+# 打包
+ncc build index.js -o dist
+
+# 输出的 dist/index.js 即为最终插件文件
+```
+
+**ncc 打包优点**：
+- 将多文件合并为单文件，便于分发
+- 自动处理依赖关系
+- 保持 CommonJS 兼容性
+
+---
+
+## 常见问题
+
+### Q1: 如何从其他系统迁移到本系统？
+
+**A**: 参考本文档的"从其他平台迁移指南"章节，主要修改点：
+1. 将 `globalThis.lx.request` 改为 `axios`
+2. 将事件监听改为函数导出
+3. 修改数据返回格式
+4. 添加 `module.exports` 导出
+5. 环境变量从 `global.env` 读取
+
+### Q2: 插件加载失败怎么办？
+
+**A**: 检查以下几点：
+1. 文件语法是否正确：`node -c your-plugin.js`
+2. `pluginInfo` 是否完整
+3. 导出的函数名是否正确
+4. 依赖模块是否已安装（如 `axios`）
+
+### Q3: 搜索返回空结果？
+
+**A**: 检查：
+1. API 请求是否成功（查看日志）
+2. 响应数据解析是否正确
+3. 数据格式是否符合规范
+4. 返回的 `source` 是否与平台标识一致
+
+### Q4: 播放失败？
+
+**A**: 检查：
+1. `getUrl` 返回的 URL 是否有效
+2. URL 是否以 `http` 开头
+3. 音质标识是否正确
+4. 是否有跨域或权限问题
+
+### Q5: 用户如何配置插件？
+
+**A**: 用户通过设置界面配置环境变量：
+
+```
+SERVER_URL = 自定义服务端地址
+API_KEY = 用户的API密钥
+```
+
+插件通过 `global.env` 读取：
+
+```javascript
+const env = global.env || {}
+const SERVER_URL = env.SERVER_URL || '默认地址'
+```
+
+### Q6: 歌词格式应该返回什么？
+
+**A**: 返回包含 `lrc`、`qrc`、`krc`、`ttml`、`translate` 等字段的对象，或直接返回歌词文本字符串。系统会自动判断歌词格式。
+
+---
+
+## 附录
+
+### 参考资源
+
+- Node.js 官方文档
+- axios 文档
+- @vercel/ncc 打包工具
+
+### 版本历史
+
+- v1.0.3: 当前版本
+- v1.0.0: 初始版本
+
+---
+
+**文档结束**