miao-moe/Koneko_api_for_QZ-Music

Fork 0

Files

miao-moe c6eeb253d0 Update to v0.0.4: add aggregated plugins with API failover, update docs

2026-06-20 12:31:39 +08:00

20 KiB

Raw Blame History

插件开发帮助文档

版本: v1.0.3

撰写人: 蜻蜓的好朋友 : Miao-moe
GitHub: Miao-moe

概述

本文档用于指导开发者编写音源插件。本系统使用 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 格式）：

// 读取用户配置的 API 密钥
const env = global.env || {}
const API_KEY = env.API_KEY || ''

// 读取自定义服务端地址
const CUSTOM_SERVER = env.SERVER_URL || '默认地址'

环境变量加载方式：

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：修改模块导入

其他系统原代码：

const { EVENT_NAMES, request, on, send, env, version } = globalThis.lx

本系统新代码：

const axios = require('axios')
const crypto = require('crypto')

// 环境变量从 global.env 读取
const env = global.env || {}
const API_KEY = env.API_KEY || ''

步骤 2：修改 HTTP 请求

其他系统原代码：

function httpRequest(url) {
  return new Promise((resolve, reject) => {
    request(url, { headers }, (err, resp) => {
      if (err) return reject(err)
      resolve(resp.body)
    })
  })
}

本系统新代码：

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：修改函数导出

其他系统原代码：

// 事件监听方式
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
})

本系统新代码：

// 直接导出函数
module.exports = {
  // 搜索功能
  musicSearch,
  
  // 获取 URL
  getUrl,
  
  // 获取歌词
  getLyric,
  
  // 获取列表
  songList,
  
  // 获取合集
  album,
  
  // 获取热搜
  hotSearch,
  
  // 插件信息
  pluginInfo: {
    info: { id: 'A', name: '平台A', version: '3' },
    quality: [...],
    supportFunc: [...]
  }
}

步骤 4：修改返回数据格式

其他系统原代码：

// 直接返回 URL 字符串
return 'https://example.com/audio.mp3'

// 或返回歌词对象（其他系统格式）
return {
  lyric: '[00:00.000]歌词内容',
  tlyric: '[00:00.000]翻译歌词'
}

本系统新代码：

// 搜索返回统一格式
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]第二行歌词...'

插件基本结构

核心导入

'use strict'

// 标准 Node.js 模块
const axios = require('axios')
const crypto = require('crypto')

配置区域

// ========== 用户可配置区域 ==========

// 从 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']

导出结构

// ========== 插件导出 ==========

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'
    ]
  }
}

数据格式规范

搜索结果统一格式

{
  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 等），插件只需返回对应的歌词字段即可。

// 推荐返回格式
{
  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

列表详情统一格式

{
  list: [/* 内容列表，格式同搜索结果 */],
  page: Number,
  limit: Number,
  total: Number,
  source: String,
  info: {
    name: String,        // 列表名
    img: String,         // 封面图
    desc: String,        // 描述
    author: String       // 创建者
  }
}

合集详情统一格式

{
  list: [/* 内容列表，格式同搜索结果 */],
  page: Number,
  limit: Number,
  total: Number,
  source: String,
  info: {
    name: String,        // 合集名
    img: String,         // 封面图
    desc: String,        // 描述
    author: String       // 创作者
  }
}

示例代码详解

完整插件模板

'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`

音质支持参考

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 将多文件打包为单文件即可：

# 安装 ncc
npm install -g @vercel/ncc

# 打包
ncc build index.js -o dist

# 输出的 dist/index.js 即为最终插件文件

ncc 打包优点：

将多文件合并为单文件，便于分发
自动处理依赖关系
保持 CommonJS 兼容性

常见问题

Q1: 如何从其他系统迁移到本系统？

A: 参考本文档的"从其他平台迁移指南"章节，主要修改点：

将 globalThis.lx.request 改为 axios
将事件监听改为函数导出
修改数据返回格式
添加 module.exports 导出
环境变量从 global.env 读取

Q2: 插件加载失败怎么办？

A: 检查以下几点：

文件语法是否正确：node -c your-plugin.js
pluginInfo 是否完整
导出的函数名是否正确
依赖模块是否已安装（如 axios）

Q3: 搜索返回空结果？

A: 检查：

API 请求是否成功（查看日志）
响应数据解析是否正确
数据格式是否符合规范
返回的 source 是否与平台标识一致

Q4: 播放失败？

A: 检查：

getUrl 返回的 URL 是否有效
URL 是否以 http 开头
音质标识是否正确
是否有跨域或权限问题

Q5: 用户如何配置插件？

A: 用户通过设置界面配置环境变量：

SERVER_URL = 自定义服务端地址
API_KEY = 用户的API密钥

插件通过 global.env 读取：

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: 初始版本

文档结束

20 KiB Raw Blame History Unescape Escape

插件开发帮助文档

目录

概述

与其他系统的区别

插件类型

核心设计原则

1. 单平台原则（重要）

2. 配置方式

3. 支持的音质标识

从其他平台迁移指南

迁移对照表

迁移步骤

步骤 1：修改模块导入

步骤 2：修改 HTTP 请求

步骤 3：修改函数导出

步骤 4：修改返回数据格式

插件基本结构

核心导入

配置区域

导出结构

数据格式规范

搜索结果统一格式

歌词返回格式

列表详情统一格式

合集详情统一格式

示例代码详解

完整插件模板

平台配置参考

各平台标识对照表

音质支持参考

开发建议

多文件开发

使用 ncc 打包

常见问题

Q1: 如何从其他系统迁移到本系统？

Q2: 插件加载失败怎么办？

Q3: 搜索返回空结果？

Q4: 播放失败？

Q5: 用户如何配置插件？

Q6: 歌词格式应该返回什么？

附录

参考资源

版本历史

20 KiB

Raw Blame History