chore: reset version to v0.0.1

2026-06-20 12:48:28 +08:00
parent cf5d093f0b
commit 42ff3bde8e
16 changed files with 1687 additions and 2017 deletions
--- a/插件规范│QZ-Music-Plugin-Development-Guide.md
+++ b/插件规范│QZ-Music-Plugin-Development-Guide.md
@@ -1,119 +1,104 @@
-# QZ Music 插件开发帮助文档
-
-## 目录
-1. [概述](#概述)
-2. [核心设计原则](#核心设计原则)
-3. [从 LX Music 迁移指南](#从-lx-music-迁移指南)
-4. [插件基本结构](#插件基本结构)
-5. [数据格式规范](#数据格式规范)
-6. [示例代码详解](#示例代码详解)
-7. [平台配置参考](#平台配置参考)
-8. [常见问题](#常见问题)
+# 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 |
+鏈枃妗ｇ敤浜庢寚瀵煎紑鍙戣€呯紪鍐?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` |
+| 杩愯鏃?| Node.js | JavaScript 杩愯鏃?|
+| 妯″潡瑙勮寖 | CommonJS | 鍏ㄥ眬浜嬩欢鐩戝惉 |
+| 瀵煎嚭鏂瑰紡 | `module.exports` | `send(EVENT_NAMES.inited)` |
+| 閫氫俊鏂瑰紡 | 鐩存帴鍑芥暟璋冪敤 | 浜嬩欢椹卞姩 |
+| HTTP 璇锋眰 | `axios` 鎴栧唴缃?`httpFetch` | `globalThis.lx.request` |

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

+QZ Music 鎻掍欢灞炰簬**瀹屾暣闊虫簮鎻掍欢**锛屾牳蹇冨姛鑳藉寘鎷細
+- 鎼滅储姝屾洸
+- 鑾峰彇闊抽鎾斁 URL
+- 鑾峰彇姝岃瘝
+- 鑾峰彇姝屽崟/涓撹緫淇℃伅
+- 鑾峰彇鐑悳/鎺掕姒?
 ---

-## 核心设计原则
+## 鏍稿績璁捐鍘熷垯

-### 1. 单平台原则（重要）
-
-**每个插件只支持一个音乐平台**，例如：
- ✅ 网易云音乐插件（仅支持 wy）
- ✅ QQ音乐插件（仅支持 tx）
- ❌ 聚合插件（同时支持 wy + tx + kw）
-
-**原因说明**：
-```
-用户向插件传配置只能通过环境变量（env）
-如果插件支持多平台，切换平台时需要修改环境变量，操作繁琐
-单平台插件更清晰，维护成本低，不易出现"代码屎山"
+### 1. 鍗曞钩鍙板師鍒欙紙閲嶈锛?
+**姣忎釜鎻掍欢鍙敮鎸佷竴涓煶涔愬钩鍙?*锛屼緥濡傦細
+- 鉁?缃戞槗浜戦煶涔愭彃浠讹紙浠呮敮鎸?wy锛?- 鉁?QQ闊充箰鎻掍欢锛堜粎鏀寔 tx锛?- 鉂?鑱氬悎鎻掍欢锛堝悓鏃舵敮鎸?wy + tx + kw锛?
+**鍘熷洜璇存槑**锛?```
+鐢ㄦ埛鍚戞彃浠朵紶閰嶇疆鍙兘閫氳繃鐜鍙橀噺锛坋nv锛?濡傛灉鎻掍欢鏀寔澶氬钩鍙帮紝鍒囨崲骞冲彴鏃堕渶瑕佷慨鏀圭幆澧冨彉閲忥紝鎿嶄綔绻佺悙
+鍗曞钩鍙版彃浠舵洿娓呮櫚锛岀淮鎶ゆ垚鏈綆锛屼笉鏄撳嚭鐜?浠ｇ爜灞庡北"
 ```

-**如需多平台支持**：建议自建后端服务，统一处理搜索和 URL 获取，前端插件只作为代理。
-
-### 2. 配置方式
-
-通过 `process.env` 或插件内置的 `env` 配置读取环境变量：
+**濡傞渶澶氬钩鍙版敮鎸?*锛氬缓璁嚜寤哄悗绔湇鍔★紝缁熶竴澶勭悊鎼滅储鍜?URL 鑾峰彇锛屽墠绔彃浠跺彧浣滀负浠ｇ悊銆?
+### 2. 閰嶇疆鏂瑰紡

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

-// 读取自定义服务端地址
-const CUSTOM_SERVER = process.env.SERVER_URL || '默认地址'
+// 璇诲彇鑷畾涔夋湇鍔＄鍦板潃
+const CUSTOM_SERVER = process.env.SERVER_URL || '榛樿鍦板潃'
 ```

-### 3. 支持的音质标识
-
-| 标识 | 说明 |
+### 3. 鏀寔鐨勯煶璐ㄦ爣璇?
+| 鏍囪瘑 | 璇存槑 |
 |------|------|
-| `128k` | 标准音质，MP3 格式 |
-| `320k` | 高品音质，MP3 格式 |
-| `flac` | 无损音质，16bit FLAC |
-| `flac24bit` | 无损音质，24bit FLAC |
-| `hires` | 高解析度无损 |
+| `128k` | 鏍囧噯闊宠川锛孧P3 鏍煎紡 |
+| `320k` | 楂樺搧闊宠川锛孧P3 鏍煎紡 |
+| `flac` | 鏃犳崯闊宠川锛?6bit FLAC |
+| `flac24bit` | 鏃犳崯闊宠川锛?4bit FLAC |
+| `hires` | 楂樿В鏋愬害鏃犳崯 |

 ---

-## 从 LX Music 迁移指南
+## 浠?LX Music 杩佺Щ鎸囧崡

-### 迁移对照表
-
-| LX Music | QZ 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` 参数 | 音质参数位置 |
+| `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 原代码：**
+#### 姝ラ 1锛氫慨鏀规ā鍧楀鍏?
+**LX Music 鍘熶唬鐮侊細**
 ```javascript
 const { EVENT_NAMES, request, on, send, env, version } = globalThis.lx
 ```

-**QZ Music 新代码：**
+**QZ Music 鏂颁唬鐮侊細**
 ```javascript
 const axios = require('axios')
 const crypto = require('crypto')

-// 环境变量
+// 鐜鍙橀噺
 const API_KEY = process.env.API_KEY || ''
 ```

-#### 步骤 2：修改 HTTP 请求
+#### 姝ラ 2锛氫慨鏀?HTTP 璇锋眰

-**LX Music 原代码：**
+**LX Music 鍘熶唬鐮侊細**
 ```javascript
 function httpRequest(url) {
  return new Promise((resolve, reject) => {
@@ -125,7 +110,7 @@ function httpRequest(url) {
 }
 ```

-**QZ Music 新代码：**
+**QZ Music 鏂颁唬鐮侊細**
 ```javascript
 async function httpRequest(url, options = {}) {
  const response = await axios({
@@ -138,11 +123,10 @@ async function httpRequest(url, options = {}) {
 }
 ```

-#### 步骤 3：修改函数导出
-
-**LX Music 原代码：**
+#### 姝ラ 3锛氫慨鏀瑰嚱鏁板鍑?
+**LX Music 鍘熶唬鐮侊細**
 ```javascript
-// 事件监听方式
+// 浜嬩欢鐩戝惉鏂瑰紡
 on(EVENT_NAMES.request, ({ action, source, info }) => {
  switch (action) {
    case 'musicUrl':
@@ -150,72 +134,68 @@ on(EVENT_NAMES.request, ({ action, source, info }) => {
  }
 })

-// 初始化事件
-send(EVENT_NAMES.inited, {
+// 鍒濆鍖栦簨浠?send(EVENT_NAMES.inited, {
  status: true,
  sources: musicSource
 })
 ```

-**QZ Music 新代码：**
+**QZ Music 鏂颁唬鐮侊細**
 ```javascript
-// 直接导出函数
+// 鐩存帴瀵煎嚭鍑芥暟
 module.exports = {
-  // 搜索功能
+  // 鎼滅储鍔熻兘
  musicSearch,
  
-  // 获取音频 URL
+  // 鑾峰彇闊抽 URL
  getUrl,
  
-  // 获取歌词
+  // 鑾峰彇姝岃瘝
  getLyric,
  
-  // 获取歌单
+  // 鑾峰彇姝屽崟
  songList,
  
-  // 获取专辑
+  // 鑾峰彇涓撹緫
  album,
  
-  // 获取热搜
+  // 鑾峰彇鐑悳
  hotSearch,
  
-  // 插件信息
+  // 鎻掍欢淇℃伅
  pluginInfo: {
-    info: { id: 'wy', name: '网易云', version: '3' },
+    info: { id: 'wy', name: '缃戞槗浜?, version: '3' },
    quality: [...],
    supportFunc: [...]
  }
 }
 ```

-#### 步骤 4：修改返回数据格式
-
-**LX Music 原代码：**
+#### 姝ラ 4锛氫慨鏀硅繑鍥炴暟鎹牸寮?
+**LX Music 鍘熶唬鐮侊細**
 ```javascript
-// 直接返回 URL 字符串
-return 'https://example.com/music.mp3'
+// 鐩存帴杩斿洖 URL 瀛楃涓?return 'https://example.com/music.mp3'

-// 或返回歌词对象
-return {
-  lyric: '[00:00.000]歌词内容',
-  tlyric: '[00:00.000]翻译歌词'
+// 鎴栬繑鍥炴瓕璇嶅璞?return {
+  lyric: '[00:00.000]姝岃瘝鍐呭',
+  tlyric: '[00:00.000]缈昏瘧姝岃瘝'
 }
 ```

-**QZ Music 新代码：**
+**QZ Music 鏂颁唬鐮侊細**
 ```javascript
-// 搜索返回统一格式
+// 鎼滅储杩斿洖缁熶竴鏍煎紡
 return {
  list: [{
    id: '123456',
-    name: '歌曲名',
-    artists: '歌手名',
+    name: '姝屾洸鍚?,
+    artists: '姝屾墜鍚?,
    source: 'wy',
-    pic: '封面URL',
-    mPic: '中封面URL',
-    sPic: '小封面URL',
-    albumName: '专辑名',
-    albumId: '专辑ID',
+    pic: '灏侀潰URL',
+    mPic: '涓皝闈RL',
+    sPic: '灏忓皝闈RL',
+    albumName: '涓撹緫鍚?,
+    albumId: '涓撹緫ID',
    interval: '03:45',
    qualities: { '128k': '4.2M', 'flac': '35M' }
  }],
@@ -226,99 +206,89 @@ return {
  source: 'wy'
 }

-// 歌词返回格式
+// 姝岃瘝杩斿洖鏍煎紡
 return {
-  lyric: '歌词内容',
-  tlyric: '翻译歌词'
+  lyric: '姝岃瘝鍐呭',
+  tlyric: '缈昏瘧姝岃瘝'
 }
 ```

 ---

-## 插件基本结构
+## 鎻掍欢鍩烘湰缁撴瀯

-### 文件头部注释
+### 鏂囦欢澶撮儴娉ㄩ噴

 ```javascript
 /**
- * @name 网易云音乐源
- * @description QZ Music 音源插件
+ * @name 缃戞槗浜戦煶涔愭簮
+ * @description QZ Music 闊虫簮鎻掍欢
 * @version 3.0.0
- * @author 开发者
- * @homepage https://github.com/your-repo
+ * @author 寮€鍙戣€? * @homepage https://github.com/your-repo
 * @license MIT
 * 
- * 支持平台: 网易云音乐 (wy)
- * 支持音质: 128k, 320k, flac, flac24bit, hires
+ * 鏀寔骞冲彴: 缃戞槗浜戦煶涔?(wy)
+ * 鏀寔闊宠川: 128k, 320k, flac, flac24bit, hires
 */
 ```

-### 核心导入
+### 鏍稿績瀵煎叆

 ```javascript
 'use strict'

-// 标准 Node.js 模块
+// 鏍囧噯 Node.js 妯″潡
 const axios = require('axios')
 const crypto = require('crypto')
 ```

-### 配置区域
+### 閰嶇疆鍖哄煙

 ```javascript
-// ========== 用户可配置区域 ==========
+// ========== 鐢ㄦ埛鍙厤缃尯鍩?==========

-// 服务端地址（用户可通过环境变量覆盖）
-const API_BASE = process.env.SERVER_URL || 'https://your-server.com'
+// 鏈嶅姟绔湴鍧€锛堢敤鎴峰彲閫氳繃鐜鍙橀噺瑕嗙洊锛?const API_BASE = process.env.SERVER_URL || 'https://your-server.com'

-// API 密钥（用户通过环境变量设置）
-const API_KEY = process.env.API_KEY || ''
+// API 瀵嗛挜锛堢敤鎴烽€氳繃鐜鍙橀噺璁剧疆锛?const API_KEY = process.env.API_KEY || ''

-// 当前平台标识（单平台插件固定值）
-const PLATFORM = 'wy'  // wy: 网易云, tx: QQ音乐, kw: 酷我, kg: 酷狗, mg: 咪咕
+// 褰撳墠骞冲彴鏍囪瘑锛堝崟骞冲彴鎻掍欢鍥哄畾鍊硷級
+const PLATFORM = 'wy'  // wy: 缃戞槗浜? tx: QQ闊充箰, kw: 閰锋垜, kg: 閰风嫍, mg: 鍜挄

-// 支持的音质列表
-const SUPPORT_QUALITIES = ['128k', '320k', 'flac', 'flac24bit', 'hires']
+// 鏀寔鐨勯煶璐ㄥ垪琛?const SUPPORT_QUALITIES = ['128k', '320k', 'flac', 'flac24bit', 'hires']
 ```

-### 导出结构
+### 瀵煎嚭缁撴瀯

 ```javascript
-// ========== 插件导出 ==========
+// ========== 鎻掍欢瀵煎嚭 ==========

 module.exports = {
-  // 核心功能（必须实现）
-  musicSearch,      // 歌曲搜索
-  getUrl,           // 获取音频 URL
+  // 鏍稿績鍔熻兘锛堝繀椤诲疄鐜帮級
+  musicSearch,      // 姝屾洸鎼滅储
+  getUrl,           // 鑾峰彇闊抽 URL
  
-  // 可选功能
-  getLyric,         // 获取歌词
-  songList,         // 歌单详情
-  album,            // 专辑详情
-  hotSearch,        // 热搜词
-  tipSearch,        // 搜索提示
-  leaderboard,      // 排行榜
-  
-  // 插件信息（必须）
+  // 鍙€夊姛鑳?  getLyric,         // 鑾峰彇姝岃瘝
+  songList,         // 姝屽崟璇︽儏
+  album,            // 涓撹緫璇︽儏
+  hotSearch,        // 鐑悳璇?  tipSearch,        // 鎼滅储鎻愮ず
+  leaderboard,      // 鎺掕姒?  
+  // 鎻掍欢淇℃伅锛堝繀椤伙級
  pluginInfo: {
    info: {
-      id: 'wy',                    // 平台标识
-      name: '网易云',               // 显示名称
-      description: '网易云音乐插件', // 描述
-      version: '3'                 // 版本号
-    },
-    env: [                          // 环境变量配置
-      { key: 'API_KEY', name: 'API密钥', description: '服务端API密钥' }
+      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' },
+    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',
+    supportFunc: [                  // 鏀寔鐨勫姛鑳?      'search_song',
      'search_playlist',
      'playlist',
      'album',
@@ -330,25 +300,19 @@ module.exports = {

 ---

-## 数据格式规范
+## 鏁版嵁鏍煎紡瑙勮寖

-### 搜索结果统一格式
+### 鎼滅储缁撴灉缁熶竴鏍煎紡

 ```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: {              // 音质 -> 文件大小
+      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',
@@ -356,108 +320,95 @@ module.exports = {
      }
    }
  ],
-  total: Number,               // 总数量
-  page: Number,                // 当前页码
-  limit: Number,               // 每页数量
-  allPage: Number,             // 总页数
-  source: String               // 平台标识
+  total: Number,               // 鎬绘暟閲?  page: Number,                // 褰撳墠椤电爜
+  limit: Number,               // 姣忛〉鏁伴噺
+  allPage: Number,             // 鎬婚〉鏁?  source: String               // 骞冲彴鏍囪瘑
 }
 ```

-### 歌词统一格式
+### 姝岃瘝缁熶竴鏍煎紡

 ```javascript
 {
-  lyric: String,       // 普通歌词 (LRC 格式)
-  tlyric: String,      // 翻译歌词
-  qrc: String,         // 逐字歌词 (QRC 格式)
-  roma: String         // 音译歌词
+  lyric: String,       // 鏅€氭瓕璇?(LRC 鏍煎紡)
+  tlyric: String,      // 缈昏瘧姝岃瘝
+  qrc: String,         // 閫愬瓧姝岃瘝 (QRC 鏍煎紡)
+  roma: String         // 闊宠瘧姝岃瘝
 }

-// 注意：至少返回 lyric 或 qrc 之一
+// 娉ㄦ剰锛氳嚦灏戣繑鍥?lyric 鎴?qrc 涔嬩竴
 ```

-### 歌单详情统一格式
+### 姝屽崟璇︽儏缁熶竴鏍煎紡

 ```javascript
 {
-  list: [/* 歌曲列表，格式同搜索结果 */],
+  list: [/* 姝屾洸鍒楄〃锛屾牸寮忓悓鎼滅储缁撴灉 */],
  page: Number,
  limit: Number,
  total: Number,
  source: String,
  info: {
-    name: String,        // 歌单名
-    img: String,         // 封面图
-    desc: String,        // 描述
-    author: String       // 作者
-  }
+    name: String,        // 姝屽崟鍚?    img: String,         // 灏侀潰鍥?    desc: String,        // 鎻忚堪
+    author: String       // 浣滆€?  }
 }
 ```

-### 专辑详情统一格式
+### 涓撹緫璇︽儏缁熶竴鏍煎紡

 ```javascript
 {
-  list: [/* 歌曲列表，格式同搜索结果 */],
+  list: [/* 姝屾洸鍒楄〃锛屾牸寮忓悓鎼滅储缁撴灉 */],
  page: Number,
  limit: Number,
  total: Number,
  source: String,
  info: {
-    name: String,        // 专辑名
-    img: String,         // 封面图
-    desc: String,        // 描述
-    author: String       // 艺术家
-  }
+    name: String,        // 涓撹緫鍚?    img: String,         // 灏侀潰鍥?    desc: String,        // 鎻忚堪
+    author: String       // 鑹烘湳瀹?  }
 }
 ```

 ---

-## 示例代码详解
+## 绀轰緥浠ｇ爜璇﹁В

-### 完整插件模板
+### 瀹屾暣鎻掍欢妯℃澘

 ```javascript
 /**
- * @name 网易云音乐源
- * @description QZ Music 音源插件示例
+ * @name 缃戞槗浜戦煶涔愭簮
+ * @description QZ Music 闊虫簮鎻掍欢绀轰緥
 * @version 3.0.0
- * @author 开发者
- * 
- * 支持平台: 网易云音乐 (wy)
- * 支持音质: 128k, 320k, flac
+ * @author 寮€鍙戣€? * 
+ * 鏀寔骞冲彴: 缃戞槗浜戦煶涔?(wy)
+ * 鏀寔闊宠川: 128k, 320k, flac
 */

 'use strict'

-// ==================== 核心导入 ====================
+// ==================== 鏍稿績瀵煎叆 ====================

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

-// ==================== 配置区域 ====================
+// ==================== 閰嶇疆鍖哄煙 ====================

-// 平台标识（固定值，单平台插件）
+// 骞冲彴鏍囪瘑锛堝浐瀹氬€硷紝鍗曞钩鍙版彃浠讹級
 const PLATFORM = 'wy'

-// 服务端配置
-const CONFIG = {
+// 鏈嶅姟绔厤缃?const CONFIG = {
  serverUrl: process.env.SERVER_URL || 'https://api.example.com',
  apiKey: process.env.API_KEY || '',
  timeout: 10000
 }

-// 支持的音质
-const SUPPORT_QUALITIES = ['128k', '320k', 'flac']
+// 鏀寔鐨勯煶璐?const SUPPORT_QUALITIES = ['128k', '320k', 'flac']

-// ==================== 工具函数 ====================
+// ==================== 宸ュ叿鍑芥暟 ====================

 /**
- * 文件大小格式化
- * @param {number} size - 字节数
- * @returns {string} 格式化后的字符串
+ * 鏂囦欢澶у皬鏍煎紡鍖? * @param {number} size - 瀛楄妭鏁? * @returns {string} 鏍煎紡鍖栧悗鐨勫瓧绗︿覆
 */
 function sizeFormate(size) {
  if (!size || isNaN(size)) return ''
@@ -468,9 +419,8 @@ function sizeFormate(size) {
 }

 /**
- * 播放时间格式化
- * @param {number} time - 秒数
- * @returns {string} 格式化后的字符串
+ * 鎾斁鏃堕棿鏍煎紡鍖? * @param {number} time - 绉掓暟
+ * @returns {string} 鏍煎紡鍖栧悗鐨勫瓧绗︿覆
 */
 function formatPlayTime(time) {
  if (!time || isNaN(time)) return '--/--'
@@ -480,20 +430,18 @@ function formatPlayTime(time) {
 }

 /**
- * 歌手名称格式化
- * @param {Array} singerList - 歌手列表
- * @returns {string} 用 "、" 连接的歌手名
+ * 姝屾墜鍚嶇О鏍煎紡鍖? * @param {Array} singerList - 姝屾墜鍒楄〃
+ * @returns {string} 鐢?"銆? 杩炴帴鐨勬瓕鎵嬪悕
 */
 function formatSingerName(singerList) {
  if (!singerList || !Array.isArray(singerList)) return ''
-  return singerList.map(s => s.name || s).join('、')
+  return singerList.map(s => s.name || s).join('銆?)
 }

 /**
- * HTML 实体解码
- * @param {string} str - 含 HTML 实体的字符串
- * @returns {string} 解码后的字符串
- */
+ * HTML 瀹炰綋瑙ｇ爜
+ * @param {string} str - 鍚?HTML 瀹炰綋鐨勫瓧绗︿覆
+ * @returns {string} 瑙ｇ爜鍚庣殑瀛楃涓? */
 function decodeName(str) {
  if (!str) return ''
  return str
@@ -505,35 +453,31 @@ function decodeName(str) {
    .replace(/&nbsp;/g, ' ')
 }

-// ==================== 核心功能 ====================
+// ==================== 鏍稿績鍔熻兘 ====================

 /**
- * 搜索歌曲
- * @param {string} str - 搜索关键词
- * @param {number} page - 页码，从 1 开始
- * @param {number} limit - 每页数量
- * @returns {Promise<Object>} 搜索结果
+ * 鎼滅储姝屾洸
+ * @param {string} str - 鎼滅储鍏抽敭璇? * @param {number} page - 椤电爜锛屼粠 1 寮€濮? * @param {number} limit - 姣忛〉鏁伴噺
+ * @returns {Promise<Object>} 鎼滅储缁撴灉
 */
 async function musicSearch(str, page = 1, limit = 20) {
-  // 构造请求参数
-  const params = {
+  // 鏋勯€犺姹傚弬鏁?  const params = {
    keyword: str,
    page: page,
    limit: limit
  }
  
-  // 发送请求
-  const url = `${CONFIG.serverUrl}/search`
+  // 鍙戦€佽姹?  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),
@@ -563,19 +507,17 @@ async function musicSearch(str, page = 1, limit = 20) {
 }

 /**
- * 获取音乐播放 URL
- * @param {string} songId - 歌曲 ID
- * @param {string} quality - 音质标识
- * @returns {Promise<string>} 播放 URL
+ * 鑾峰彇闊充箰鎾斁 URL
+ * @param {string} songId - 姝屾洸 ID
+ * @param {string} quality - 闊宠川鏍囪瘑
+ * @returns {Promise<string>} 鎾斁 URL
 */
 async function getUrl(songId, quality) {
-  // 检查音质
-  if (!SUPPORT_QUALITIES.includes(quality)) {
+  // 妫€鏌ラ煶璐?  if (!SUPPORT_QUALITIES.includes(quality)) {
    quality = SUPPORT_QUALITIES[0]
  }
  
-  // 发送请求
-  const url = `${CONFIG.serverUrl}/music/url`
+  // 鍙戦€佽姹?  const url = `${CONFIG.serverUrl}/music/url`
  const response = await axios.get(url, {
    params: { id: songId, quality: quality },
    headers: { 'X-API-Key': CONFIG.apiKey },
@@ -585,16 +527,16 @@ async function getUrl(songId, quality) {
  const data = response.data
  
  if (!data.url || !data.url.startsWith('http')) {
-    throw new Error('获取链接失败')
+    throw new Error('鑾峰彇閾炬帴澶辫触')
  }
  
  return data.url
 }

 /**
- * 获取歌词
- * @param {string} songId - 歌曲 ID
- * @returns {Promise<Object>} 歌词对象
+ * 鑾峰彇姝岃瘝
+ * @param {string} songId - 姝屾洸 ID
+ * @returns {Promise<Object>} 姝岃瘝瀵硅薄
 */
 async function getLyric(songId) {
  const url = `${CONFIG.serverUrl}/music/lyric`
@@ -613,11 +555,11 @@ async function getLyric(songId) {
 }

 /**
- * 获取歌单详情
- * @param {string} id - 歌单 ID
- * @param {number} page - 页码
- * @param {number} limit - 每页数量
- * @returns {Promise<Object>} 歌单详情
+ * 鑾峰彇姝屽崟璇︽儏
+ * @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`
@@ -629,7 +571,7 @@ async function songList(id, page = 1, limit = 20) {
  
  const data = response.data
  
-  // 转换歌曲列表
+  // 杞崲姝屾洸鍒楄〃
  const list = data.songs.map(item => ({
    id: String(item.id),
    name: decodeName(item.name),
@@ -660,10 +602,10 @@ async function songList(id, page = 1, limit = 20) {
 }

 /**
- * 获取专辑详情
- * @param {string} id - 专辑 ID
- * @param {number} page - 页码
- * @returns {Promise<Object>} 专辑详情
+ * 鑾峰彇涓撹緫璇︽儏
+ * @param {string} id - 涓撹緫 ID
+ * @param {number} page - 椤电爜
+ * @returns {Promise<Object>} 涓撹緫璇︽儏
 */
 async function album(id, page = 1) {
  const url = `${CONFIG.serverUrl}/album`
@@ -675,7 +617,7 @@ async function album(id, page = 1) {
  
  const data = response.data
  
-  // 转换歌曲列表
+  // 杞崲姝屾洸鍒楄〃
  const list = data.songs.map(item => ({
    id: String(item.id),
    name: decodeName(item.name),
@@ -706,8 +648,7 @@ async function album(id, page = 1) {
 }

 /**
- * 获取热搜词
- * @returns {Promise<Object>} 热搜列表
+ * 鑾峰彇鐑悳璇? * @returns {Promise<Object>} 鐑悳鍒楄〃
 */
 async function hotSearch() {
  const url = `${CONFIG.serverUrl}/hotsearch`
@@ -722,10 +663,10 @@ async function hotSearch() {
  }
 }

-// ==================== 插件导出 ====================
+// ==================== 鎻掍欢瀵煎嚭 ====================

 module.exports = {
-  // 核心功能
+  // 鏍稿績鍔熻兘
  musicSearch,
  getUrl,
  getLyric,
@@ -733,23 +674,23 @@ module.exports = {
  album,
  hotSearch,
  
-  // 插件信息
+  // 鎻掍欢淇℃伅
  pluginInfo: {
    info: {
      id: PLATFORM,
-      name: '网易云',
-      description: '网易云音乐插件',
+      name: '缃戞槗浜?,
+      description: '缃戞槗浜戦煶涔愭彃浠?,
      version: '3'
    },
    env: [
-      { key: 'SERVER_URL', name: '服务端地址', description: '自定义服务端地址' },
-      { key: 'API_KEY', name: 'API密钥', description: '服务端API密钥' }
+      { 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' }
+      { name: '鏍囧噯闊宠川', ui: '鏍?, id: '128k' },
+      { name: '楂樺搧闊宠川', ui: 'HQ', id: '320k' },
+      { name: '鏃犳崯闊宠川', ui: 'SQ', id: 'flac' }
    ],
    supportFunc: ['search_song', 'search_playlist', 'playlist', 'album', 'lyric']
  }
@@ -758,24 +699,21 @@ module.exports = {

 ---

-## 平台配置参考
+## 骞冲彴閰嶇疆鍙傝€?
+### 鍚勫钩鍙版爣璇嗗鐓ц〃

-### 各平台标识对照表
-
-| 平台 | 标识 | 常见歌曲 ID 字段 |
+| 骞冲彴 | 鏍囪瘑 | 甯歌姝屾洸 ID 瀛楁 |
 |------|------|-----------------|
-| 网易云音乐 | `wy` | `id`, `songmid` |
-| QQ音乐 | `tx` | `songmid`, `id` |
-| 酷我音乐 | `kw` | `rid`, `id`, `hash` |
-| 酷狗音乐 | `kg` | `hash`, `id` |
-| 咪咕音乐 | `mg` | `copyrightId`, `id` |
-| 汽水音乐 | `qx` | `id` |
-
-### 音质支持参考
+| 缃戞槗浜戦煶涔?| `wy` | `id`, `songmid` |
+| QQ闊充箰 | `tx` | `songmid`, `id` |
+| 閰锋垜闊充箰 | `kw` | `rid`, `id`, `hash` |
+| 閰风嫍闊充箰 | `kg` | `hash`, `id` |
+| 鍜挄闊充箰 | `mg` | `copyrightId`, `id` |
+| 姹芥按闊充箰 | `qx` | `id` |

+### 闊宠川鏀寔鍙傝€?
 ```javascript
-// 各平台常见音质配置
-const PLATFORM_QUALITIES = {
+// 鍚勫钩鍙板父瑙侀煶璐ㄩ厤缃?const PLATFORM_QUALITIES = {
  wy: ['128k', '320k', 'flac', 'flac24bit', 'hires'],
  tx: ['128k', '320k', 'flac', 'flac24bit', 'hires'],
  kw: ['128k', '320k', 'flac', 'flac24bit'],
@@ -787,70 +725,59 @@ const PLATFORM_QUALITIES = {

 ---

-## 常见问题
+## 甯歌闂

-### Q1: 如何从 LX Music 迁移到 QZ Music？
+### Q1: 濡備綍浠?LX Music 杩佺Щ鍒?QZ Music锛?
+**A**: 鍙傝€冩湰鏂囨。鐨?浠?LX Music 杩佺Щ鎸囧崡"绔犺妭锛屼富瑕佷慨鏀圭偣锛?1. 灏?`globalThis.lx.request` 鏀逛负 `axios`
+2. 灏嗕簨浠剁洃鍚敼涓哄嚱鏁板鍑?3. 淇敼鏁版嵁杩斿洖鏍煎紡
+4. 娣诲姞 `module.exports` 瀵煎嚭

-**A**: 参考本文档的"从 LX Music 迁移指南"章节，主要修改点：
-1. 将 `globalThis.lx.request` 改为 `axios`
-2. 将事件监听改为函数导出
-3. 修改数据返回格式
-4. 添加 `module.exports` 导出
+### Q2: 鎻掍欢鍔犺浇澶辫触鎬庝箞鍔烇紵

-### Q2: 插件加载失败怎么办？
+**A**: 妫€鏌ヤ互涓嬪嚑鐐癸細
+1. 鏂囦欢璇硶鏄惁姝ｇ‘锛歚node -c your-plugin.js`
+2. `pluginInfo` 鏄惁瀹屾暣
+3. 瀵煎嚭鐨勫嚱鏁板悕鏄惁姝ｇ‘
+4. 渚濊禆妯″潡鏄惁宸插畨瑁咃紙濡?`axios`锛?
+### Q3: 鎼滅储杩斿洖绌虹粨鏋滐紵

-**A**: 检查以下几点：
-1. 文件语法是否正确：`node -c your-plugin.js`
-2. `pluginInfo` 是否完整
-3. 导出的函数名是否正确
-4. 依赖模块是否已安装（如 `axios`）
+**A**: 妫€鏌ワ細
+1. API 璇锋眰鏄惁鎴愬姛锛堟煡鐪嬫棩蹇楋級
+2. 鍝嶅簲鏁版嵁瑙ｆ瀽鏄惁姝ｇ‘
+3. 鏁版嵁鏍煎紡鏄惁绗﹀悎瑙勮寖
+4. 杩斿洖鐨?`source` 鏄惁涓庡钩鍙版爣璇嗕竴鑷?
+### Q4: 闊抽鏃犳硶鎾斁锛?
+**A**: 妫€鏌ワ細
+1. `getUrl` 杩斿洖鐨?URL 鏄惁鏈夋晥
+2. URL 鏄惁浠?`http` 寮€澶?3. 闊宠川鏍囪瘑鏄惁姝ｇ‘
+4. 鏄惁鏈夎法鍩熸垨鏉冮檺闂

-### Q3: 搜索返回空结果？
-
-**A**: 检查：
-1. API 请求是否成功（查看日志）
-2. 响应数据解析是否正确
-3. 数据格式是否符合规范
-4. 返回的 `source` 是否与平台标识一致
-
-### Q4: 音频无法播放？
-
-**A**: 检查：
-1. `getUrl` 返回的 URL 是否有效
-2. URL 是否以 `http` 开头
-3. 音质标识是否正确
-4. 是否有跨域或权限问题
-
-### Q5: 用户如何配置插件？
-
-**A**: 用户通过 QZ Music 的设置界面配置环境变量：
+### Q5: 鐢ㄦ埛濡備綍閰嶇疆鎻掍欢锛?
+**A**: 鐢ㄦ埛閫氳繃 QZ Music 鐨勮缃晫闈㈤厤缃幆澧冨彉閲忥細

 ```
-SERVER_URL = 自定义服务端地址
-API_KEY = 用户的API密钥
+SERVER_URL = 鑷畾涔夋湇鍔＄鍦板潃
+API_KEY = 鐢ㄦ埛鐨凙PI瀵嗛挜
 ```

-插件通过 `process.env` 读取：
-
+鎻掍欢閫氳繃 `process.env` 璇诲彇锛?
 ```javascript
-const SERVER_URL = process.env.SERVER_URL || '默认地址'
+const SERVER_URL = process.env.SERVER_URL || '榛樿鍦板潃'
 ```

 ---

-## 附录
+## 闄勫綍

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

- QZ Music 官方文档
- 提供的音源文件（lx&qz官方部分音源）
- Node.js 官方文档
- axios 文档
+### 鐗堟湰鍘嗗彶

-### 版本历史
-
- v1.0.0 (2024-05-28): 初始版本
+- v1.0.0 (2024-05-28): 鍒濆鐗堟湰

 ---

-**文档结束**
+**鏂囨。缁撴潫**