# QZ Music 插件开发帮助文档

## 目录
1. [概述](#概述)
2. [核心设计原则](#核心设计原则)
3. [从 LX Music 迁移指南](#从-lx-music-迁移指南)
4. [插件基本结构](#插件基本结构)
5. [数据格式规范](#数据格式规范)
6. [示例代码详解](#示例代码详解)
7. [平台配置参考](#平台配置参考)
8. [常见问题](#常见问题)

---

## 概述

本文档用于指导开发者编写 QZ Music 音源插件。QZ Music 使用 Node.js 运行时环境，插件采用 CommonJS 模块规范，通过 `module.exports` 导出功能接口。

### 与 LX Music 的区别

| 特性 | QZ Music | LX Music |
|------|----------|----------|
| 运行时 | Node.js | JavaScript 运行时 |
| 模块规范 | CommonJS | 全局事件监听 |
| 导出方式 | `module.exports` | `send(EVENT_NAMES.inited)` |
| 通信方式 | 直接函数调用 | 事件驱动 |
| HTTP 请求 | `axios` 或内置 `httpFetch` | `globalThis.lx.request` |

### 插件类型

QZ Music 插件属于**完整音源插件**，核心功能包括：
- 搜索歌曲
- 获取音频播放 URL
- 获取歌词
- 获取歌单/专辑信息
- 获取热搜/排行榜

---

## 核心设计原则

### 1. 单平台原则（重要）

**每个插件只支持一个音乐平台**，例如：
- ✅ 网易云音乐插件（仅支持 wy）
- ✅ QQ音乐插件（仅支持 tx）
- ❌ 聚合插件（同时支持 wy + tx + kw）

**原因说明**：
```
用户向插件传配置只能通过环境变量（env）
如果插件支持多平台，切换平台时需要修改环境变量，操作繁琐
单平台插件更清晰，维护成本低，不易出现"代码屎山"
```

**如需多平台支持**：建议自建后端服务，统一处理搜索和 URL 获取，前端插件只作为代理。

### 2. 配置方式

通过 `process.env` 或插件内置的 `env` 配置读取环境变量：

```javascript
// 读取用户配置的 API 密钥
const API_KEY = process.env.API_KEY || ''

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

### 3. 支持的音质标识

| 标识 | 说明 |
|------|------|
| `128k` | 标准音质，MP3 格式 |
| `320k` | 高品音质，MP3 格式 |
| `flac` | 无损音质，16bit FLAC |
| `flac24bit` | 无损音质，24bit FLAC |
| `hires` | 高解析度无损 |

---

## 从 LX Music 迁移指南

### 迁移对照表

| LX Music | QZ Music | 说明 |
|----------|----------|------|
| `globalThis.lx` | `require` 模块 | 不再需要全局对象 |
| `globalThis.lx.request` | `axios` 或 `httpFetch` | 使用标准 HTTP 库 |
| `globalThis.lx.env` | `process.env` | 环境变量读取方式 |
| `on(EVENT_NAMES.request, ...)` | 直接导出函数 | 改为函数导出 |
| `send(EVENT_NAMES.inited, ...)` | `module.exports` | 改为模块导出 |
| `musicInfo.songmid` | `musicInfo.id` | 字段名可能不同 |
| `info.type` | `quality` 参数 | 音质参数位置 |

### 迁移步骤

#### 步骤 1：修改模块导入

**LX Music 原代码：**
```javascript
const { EVENT_NAMES, request, on, send, env, version } = globalThis.lx
```

**QZ Music 新代码：**
```javascript
const axios = require('axios')
const crypto = require('crypto')

// 环境变量
const API_KEY = process.env.API_KEY || ''
```

#### 步骤 2：修改 HTTP 请求

**LX Music 原代码：**
```javascript
function httpRequest(url) {
  return new Promise((resolve, reject) => {
    request(url, { headers }, (err, resp) => {
      if (err) return reject(err)
      resolve(resp.body)
    })
  })
}
```

**QZ Music 新代码：**
```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：修改函数导出

**LX Music 原代码：**
```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
})
```

**QZ Music 新代码：**
```javascript
// 直接导出函数
module.exports = {
  // 搜索功能
  musicSearch,
  
  // 获取音频 URL
  getUrl,
  
  // 获取歌词
  getLyric,
  
  // 获取歌单
  songList,
  
  // 获取专辑
  album,
  
  // 获取热搜
  hotSearch,
  
  // 插件信息
  pluginInfo: {
    info: { id: 'wy', name: '网易云', version: '3' },
    quality: [...],
    supportFunc: [...]
  }
}
```

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

**LX Music 原代码：**
```javascript
// 直接返回 URL 字符串
return 'https://example.com/music.mp3'

// 或返回歌词对象
return {
  lyric: '[00:00.000]歌词内容',
  tlyric: '[00:00.000]翻译歌词'
}
```

**QZ Music 新代码：**
```javascript
// 搜索返回统一格式
return {
  list: [{
    id: '123456',
    name: '歌曲名',
    artists: '歌手名',
    source: 'wy',
    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: 'wy'
}

// 歌词返回格式
return {
  lyric: '歌词内容',
  tlyric: '翻译歌词'
}
```

---

## 插件基本结构

### 文件头部注释

```javascript
/**
 * @name 网易云音乐源
 * @description QZ Music 音源插件
 * @version 3.0.0
 * @author 开发者
 * @homepage https://github.com/your-repo
 * @license MIT
 * 
 * 支持平台: 网易云音乐 (wy)
 * 支持音质: 128k, 320k, flac, flac24bit, hires
 */
```

### 核心导入

```javascript
'use strict'

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

### 配置区域

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

// 服务端地址（用户可通过环境变量覆盖）
const API_BASE = process.env.SERVER_URL || 'https://your-server.com'

// API 密钥（用户通过环境变量设置）
const API_KEY = process.env.API_KEY || ''

// 当前平台标识（单平台插件固定值）
const PLATFORM = 'wy'  // wy: 网易云, tx: QQ音乐, kw: 酷我, kg: 酷狗, mg: 咪咕

// 支持的音质列表
const SUPPORT_QUALITIES = ['128k', '320k', 'flac', 'flac24bit', 'hires']
```

### 导出结构

```javascript
// ========== 插件导出 ==========

module.exports = {
  // 核心功能（必须实现）
  musicSearch,      // 歌曲搜索
  getUrl,           // 获取音频 URL
  
  // 可选功能
  getLyric,         // 获取歌词
  songList,         // 歌单详情
  album,            // 专辑详情
  hotSearch,        // 热搜词
  tipSearch,        // 搜索提示
  leaderboard,      // 排行榜
  
  // 插件信息（必须）
  pluginInfo: {
    info: {
      id: 'wy',                    // 平台标识
      name: '网易云',               // 显示名称
      description: '网易云音乐插件', // 描述
      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' },
      { name: 'Hi-Res', ui: 'HR', id: 'hires' }
    ],
    supportFunc: [                  // 支持的功能
      'search_song',
      'search_playlist',
      'playlist',
      'album',
      'lyric'
    ]
  }
}
```

---

## 数据格式规范

### 搜索结果统一格式

```javascript
{
  list: [
    {
      id: String,              // 歌曲唯一标识
      name: String,             // 歌曲名（已解码 HTML 实体）
      artists: String,          // 歌手名（用 "、" 分隔）
      source: String,           // 平台标识: 'wy'/'tx'/'kw'/'kg'/'mg'
      pic: String,              // 大封面图 URL（500x500）
      mPic: String,             // 中封面图 URL（300x300）
      sPic: String,             // 小封面图 URL（150x150）
      albumName: String,        // 专辑名
      albumId: String,          // 专辑 ID
      interval: String,         // 时长 "mm:ss"
      qualities: {              // 音质 -> 文件大小
        '128k': '4.2M',
        '320k': '8.5M',
        'flac': '35M',
        'hires': '68M'
      }
    }
  ],
  total: Number,               // 总数量
  page: Number,                // 当前页码
  limit: Number,               // 每页数量
  allPage: Number,             // 总页数
  source: String               // 平台标识
}
```

### 歌词统一格式

```javascript
{
  lyric: String,       // 普通歌词 (LRC 格式)
  tlyric: String,      // 翻译歌词
  qrc: String,         // 逐字歌词 (QRC 格式)
  roma: String         // 音译歌词
}

// 注意：至少返回 lyric 或 qrc 之一
```

### 歌单详情统一格式

```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
/**
 * @name 网易云音乐源
 * @description QZ Music 音源插件示例
 * @version 3.0.0
 * @author 开发者
 * 
 * 支持平台: 网易云音乐 (wy)
 * 支持音质: 128k, 320k, flac
 */

'use strict'

// ==================== 核心导入 ====================

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

// ==================== 配置区域 ====================

// 平台标识（固定值，单平台插件）
const PLATFORM = 'wy'

// 服务端配置
const CONFIG = {
  serverUrl: process.env.SERVER_URL || 'https://api.example.com',
  apiKey: process.env.API_KEY || '',
  timeout: 10000
}

// 支持的音质
const SUPPORT_QUALITIES = ['128k', '320k', 'flac']

// ==================== 工具函数 ====================

/**
 * 文件大小格式化
 * @param {number} size - 字节数
 * @returns {string} 格式化后的字符串
 */
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'
}

/**
 * 播放时间格式化
 * @param {number} time - 秒数
 * @returns {string} 格式化后的字符串
 */
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')
}

/**
 * 歌手名称格式化
 * @param {Array} singerList - 歌手列表
 * @returns {string} 用 "、" 连接的歌手名
 */
function formatSingerName(singerList) {
  if (!singerList || !Array.isArray(singerList)) return ''
  return singerList.map(s => s.name || s).join('、')
}

/**
 * HTML 实体解码
 * @param {string} str - 含 HTML 实体的字符串
 * @returns {string} 解码后的字符串
 */
function decodeName(str) {
  if (!str) return ''
  return str
    .replace(/'/g, "'")
    .replace(/"/g, '"')
    .replace(/&lt;/g, '<')
    .replace(/&gt;/g, '>')
    .replace(/&amp;/g, '&')
    .replace(/&nbsp;/g, ' ')
}

// ==================== 核心功能 ====================

/**
 * 搜索歌曲
 * @param {string} str - 搜索关键词
 * @param {number} page - 页码，从 1 开始
 * @param {number} limit - 每页数量
 * @returns {Promise<Object>} 搜索结果
 */
async function musicSearch(str, page = 1, limit = 20) {
  // 构造请求参数
  const params = {
    keyword: str,
    page: page,
    limit: 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.songs.map(item => ({
    id: String(item.id),
    name: decodeName(item.name),
    artists: formatSingerName(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: page,
    limit: limit,
    allPage: Math.ceil(data.total / limit),
    source: PLATFORM
  }
}

/**
 * 获取音乐播放 URL
 * @param {string} songId - 歌曲 ID
 * @param {string} quality - 音质标识
 * @returns {Promise<string>} 播放 URL
 */
async function getUrl(songId, quality) {
  // 检查音质
  if (!SUPPORT_QUALITIES.includes(quality)) {
    quality = SUPPORT_QUALITIES[0]
  }
  
  // 发送请求
  const url = `${CONFIG.serverUrl}/music/url`
  const response = await axios.get(url, {
    params: { id: songId, quality: 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
}

/**
 * 获取歌词
 * @param {string} songId - 歌曲 ID
 * @returns {Promise<Object>} 歌词对象
 */
async function getLyric(songId) {
  const url = `${CONFIG.serverUrl}/music/lyric`
  const response = await axios.get(url, {
    params: { id: songId },
    headers: { 'X-API-Key': CONFIG.apiKey },
    timeout: CONFIG.timeout
  })
  
  const data = response.data
  
  return {
    lyric: data.lyric || '',
    tlyric: data.tlyric || ''
  }
}

/**
 * 获取歌单详情
 * @param {string} id - 歌单 ID
 * @param {number} page - 页码
 * @param {number} limit - 每页数量
 * @returns {Promise<Object>} 歌单详情
 */
async function songList(id, page = 1, limit = 20) {
  const url = `${CONFIG.serverUrl}/playlist`
  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.songs.map(item => ({
    id: String(item.id),
    name: decodeName(item.name),
    artists: formatSingerName(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 || ''
    }
  }
}

/**
 * 获取专辑详情
 * @param {string} id - 专辑 ID
 * @param {number} page - 页码
 * @returns {Promise<Object>} 专辑详情
 */
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.songs.map(item => ({
    id: String(item.id),
    name: decodeName(item.name),
    artists: formatSingerName(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 || ''
    }
  }
}

/**
 * 获取热搜词
 * @returns {Promise<Object>} 热搜列表
 */
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: '网易云',
      description: '网易云音乐插件',
      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 字段 |
|------|------|-----------------|
| 网易云音乐 | `wy` | `id`, `songmid` |
| QQ音乐 | `tx` | `songmid`, `id` |
| 酷我音乐 | `kw` | `rid`, `id`, `hash` |
| 酷狗音乐 | `kg` | `hash`, `id` |
| 咪咕音乐 | `mg` | `copyrightId`, `id` |
| 汽水音乐 | `qx` | `id` |

### 音质支持参考

```javascript
// 各平台常见音质配置
const PLATFORM_QUALITIES = {
  wy: ['128k', '320k', 'flac', 'flac24bit', 'hires'],
  tx: ['128k', '320k', 'flac', 'flac24bit', 'hires'],
  kw: ['128k', '320k', 'flac', 'flac24bit'],
  kg: ['128k', '320k', 'flac', 'flac24bit', 'hires'],
  mg: ['128k', '320k', 'flac', 'flac24bit'],
  qx: ['128k', '320k', 'flac']
}
```

---

## 常见问题

### Q1: 如何从 LX Music 迁移到 QZ Music？

**A**: 参考本文档的"从 LX Music 迁移指南"章节，主要修改点：
1. 将 `globalThis.lx.request` 改为 `axios`
2. 将事件监听改为函数导出
3. 修改数据返回格式
4. 添加 `module.exports` 导出

### 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**: 用户通过 QZ Music 的设置界面配置环境变量：

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

插件通过 `process.env` 读取：

```javascript
const SERVER_URL = process.env.SERVER_URL || '默认地址'
```

---

## 附录

### 参考资源

- QZ Music 官方文档
- 提供的音源文件（lx&qz官方部分音源）
- Node.js 官方文档
- axios 文档

### 版本历史

- v1.0.0 (2024-05-28): 初始版本

---

**文档结束**