Koneko_api_for_QZ-Music/QZMusicV2 插件规范│QZ-Music-Plugin-Development-Guide.md

# QZ Music 鎻掍欢寮€鍙戝府鍔╂枃妗?
## 鐩綍
1. [姒傝堪](#姒傝堪)
2. [鏍稿績璁捐鍘熷垯](#鏍稿績璁捐鍘熷垯)
3. [浠?LX Music 杩佺Щ鎸囧崡](#浠?lx-music-杩佺Щ鎸囧崡)
4. [鎻掍欢鍩烘湰缁撴瀯](#鎻掍欢鍩烘湰缁撴瀯)
5. [鏁版嵁鏍煎紡瑙勮寖](#鏁版嵁鏍煎紡瑙勮寖)
6. [绀轰緥浠ｇ爜璇﹁В](#绀轰緥浠ｇ爜璇﹁В)
7. [骞冲彴閰嶇疆鍙傝€僝(#骞冲彴閰嶇疆鍙傝€?
8. [甯歌闂](#甯歌闂)

---

## 姒傝堪

鏈枃妗ｇ敤浜庢寚瀵煎紑鍙戣€呯紪鍐?QZ Music 闊虫簮鎻掍欢銆俀Z 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锛?
**鍘熷洜璇存槑**锛?```
鐢ㄦ埛鍚戞彃浠朵紶閰嶇疆鍙兘閫氳繃鐜鍙橀噺锛坋nv锛?濡傛灉鎻掍欢鏀寔澶氬钩鍙帮紝鍒囨崲骞冲彴鏃堕渶瑕佷慨鏀圭幆澧冨彉閲忥紝鎿嶄綔绻佺悙
鍗曞钩鍙版彃浠舵洿娓呮櫚锛岀淮鎶ゆ垚鏈綆锛屼笉鏄撳嚭鐜?浠ｇ爜灞庡北"
```

**濡傞渶澶氬钩鍙版敮鎸?*锛氬缓璁嚜寤哄悗绔湇鍔★紝缁熶竴澶勭悊鎼滅储鍜?URL 鑾峰彇锛屽墠绔彃浠跺彧浣滀负浠ｇ悊銆?
### 2. 閰嶇疆鏂瑰紡

閫氳繃 `process.env` 鎴栨彃浠跺唴缃殑 `env` 閰嶇疆璇诲彇鐜鍙橀噺锛?
```javascript
// 璇诲彇鐢ㄦ埛閰嶇疆鐨?API 瀵嗛挜
const API_KEY = process.env.API_KEY || ''

// 璇诲彇鑷畾涔夋湇鍔＄鍦板潃
const CUSTOM_SERVER = process.env.SERVER_URL || '榛樿鍦板潃'
```

### 3. 鏀寔鐨勯煶璐ㄦ爣璇?
| 鏍囪瘑 | 璇存槑 |
|------|------|
| `128k` | 鏍囧噯闊宠川锛孧P3 鏍煎紡 |
| `320k` | 楂樺搧闊宠川锛孧P3 鏍煎紡 |
| `flac` | 鏃犳崯闊宠川锛?6bit FLAC |
| `flac24bit` | 鏃犳崯闊宠川锛?4bit 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: '涓皝闈RL',
    sPic: '灏忓皝闈RL',
    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: '鏈嶅姟绔疉PI瀵嗛挜' }
    ],
    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锛?00x500锛?      mPic: String,             // 涓皝闈㈠浘 URL锛?00x300锛?      sPic: String,             // 灏忓皝闈㈠浘 URL锛?50x150锛?      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: '鏈嶅姟绔疉PI瀵嗛挜' }
    ],
    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 = 鐢ㄦ埛鐨凙PI瀵嗛挜
```

鎻掍欢閫氳繃 `process.env` 璇诲彇锛?
```javascript
const SERVER_URL = process.env.SERVER_URL || '榛樿鍦板潃'
```

---

## 闄勫綍

### 鍙傝€冭祫婧?
- QZ Music 瀹樻柟鏂囨。
- 鎻愪緵鐨勯煶婧愭枃浠讹紙lx&qz瀹樻柟閮ㄥ垎闊虫簮锛?- Node.js 瀹樻柟鏂囨。
- axios 鏂囨。

### 鐗堟湰鍘嗗彶

- v1.0.0 (2024-05-28): 鍒濆鐗堟湰

---

**鏂囨。缁撴潫**