上传文件至「/」

添加插件规范
2026-06-20 12:11:09 +08:00
parent 8bdeb35994
commit 00b348d8a0
5 changed files with 5274 additions and 0 deletions
--- a/6a2d8996cc974039d1dfbbf7_Koneko_插件开发文档_v0.0.3.md
+++ b/6a2d8996cc974039d1dfbbf7_Koneko_插件开发文档_v0.0.3.md
--- a/6a2d8996cc974039d1dfbbf7_Koneko插件开发避坑指南_v0.0.3.md
+++ b/6a2d8996cc974039d1dfbbf7_Koneko插件开发避坑指南_v0.0.3.md
@@ -0,0 +1,359 @@
+# Koneko QZ Music v2 插件开发避坑指南
+
+> 版本: 0.0.3 | 作者: 云汀(Miao-moe) | 目标: 支持到别的 AI 继续开发
+
+---
+
+## 一、项目背景
+
+QZ Music v2 是一款 Android 音乐播放器，支持通过**拓展插件**接入多平台音源。插件系统基于 Node.js 运行时（Javet/V8），每个插件是一个单独的 `.js` 文件，通过 `module.exports` 导出接口。
+
+### 1.1 插件加载机制
+
+- canary 12-4 版本之前：直接加载 `.js` 文件
+- **canary 12-4 及之后**：需要 `文件夹 + plugin.json + index.js` 结构（但用户要求只用 `.js`，所以当前版本是单文件）
+- 运行时环境变量通过 `global.env` 访问，**不是** `process.env`
+
+### 1.2 插件导出格式
+
+```js
+module.exports = {
+  musicSearch: { search: fn, tipSearch: fn, hotSearch: fn },
+  tipSearch: { getList: fn },
+  hotSearch: { getList: fn },
+  getUrl: fn,
+  pluginInfo: { info: {...}, env: [...], ext: [...], quality: [...], supportFunc: [] },
+  // 网易云特有
+  userPlaylist: fn,
+  dailyRecommend: fn,
+  personalFm: fn,
+  myLikedSongs: fn
+}
+```
+
+---
+
+## 二、Javet/V8 兼容性大坑（最重要）
+
+QZ Music 使用 Javet 作为 JS 运行时（基于 V8），**不支持现代 ES 语法**，必须用保守写法：
+
+| 语法 | 是否支持 | 正确写法 |
+|------|---------|---------|
+| `let` / `const` | ❌ | `var` |
+| 箭头函数 `() => {}` | ❌ | `function() {}` |
+| `async` / `await` | ❌ | `Promise` 链式调用 |
+| `catch { }`（无参数）| ❌ | `catch (e) { }` |
+| `Promise.allSettled` | ❌ | `Promise.all` + 手动包装 |
+| `Object.entries` / `Object.values` | ❌ | `for...in` 遍历 |
+| `Array.prototype.includes` | ❌ | `indexOf(...) !== -1` |
+| `String.prototype.startsWith` | ❌ | `indexOf(...) === 0` |
+| `BigInt` 字面量 | ⚠️ 慎用 | `BigInt('0x' + hex)` |
+| `class` | ❌ | 对象字面量 |
+| 模板字符串 `${}` | ✅ | 可用 |
+| `Buffer` | ✅ | Node.js 内置 |
+| `require` | ✅ | CommonJS |
+
+### 2.1 Promise.allSettled 替代方案
+
+```js
+// ❌ 不支持
+Promise.allSettled(promises)
+
+// ✅ 正确写法
+Promise.all(promises.map(function(p) {
+  return p.then(function(v) {
+    return { status: 'fulfilled', value: v }
+  }).catch(function(e) {
+    return { status: 'rejected', reason: e }
+  })
+})).then(function(results) {
+  for (var i = 0; i < results.length; i++) {
+    if (results[i].status === 'fulfilled') {
+      return results[i].value
+    }
+  }
+  throw new Error('all failed')
+})
+```
+
+---
+
+## 三、搜索结果格式大坑
+
+App 的 `MusicListResponse` 反序列化要求**必须有 `list` 字段**，不是 `songs`！
+
+### 3.1 正确的搜索返回格式
+
+```js
+return {
+  list: [
+    {
+      id: '歌曲ID字符串',
+      name: '歌曲名',
+      artists: '歌手1、歌手2',
+      albumName: '专辑名',
+      albumId: '专辑ID',
+      source: 'tx', // tx/kg/kw/wy/mg/git
+      pic: '封面大图URL',
+      mPic: '封面中图URL',
+      sPic: '封面小图URL',
+      interval: '3:45', // 播放时长 m:ss
+      qualities: {
+        standard: '3.21MB',
+        exhigh: '7.85MB',
+        lossless: '25.3MB',
+        hires: '48.2MB'
+      }
+    }
+  ],
+  allPage: 5,    // 总页数
+  limit: 30,     // 每页条数
+  total: 150,    // 总条数
+  source: 'tx'   // 平台标识
+}
+```
+
+### 3.2 字段名对照表
+
+| 含义 | 正确字段名 | 错误字段名 |
+|------|----------|----------|
+| 歌手 | `artists` | `artist` |
+| 封面图 | `pic` / `mPic` / `sPic` | `picUrl` |
+| 时长 | `interval` (字符串 m:ss) | `duration` |
+| 歌曲列表 | `list` | `songs` |
+
+---
+
+## 四、各平台 API 踩坑记录
+
+### 4.1 QQ音乐 (tx)
+
+**搜索签名**：`zzcSign` = SHA1 + 自定义索引提取 + XOR 混淆 + base64
+
+```js
+var PART_1_INDEXES = [23, 14, 6, 36, 16, 40, 7, 19]
+var PART_2_INDEXES = [16, 1, 32, 12, 19, 27, 8, 5]
+var SCRAMBLE_VALUES = [89, 39, 179, 150, 218, 82, 58, 252, 177, 52, 186, 123, 120, 64, 242, 133, 143, 161, 121, 179]
+```
+
+**封面图规则**：
+- 有专辑ID：`https://y.gtimg.cn/music/photo_new/T002R500x500M000{albumId}.jpg`
+- 无专辑ID（歌手图）：`https://y.gtimg.cn/music/photo_new/T001R500x500M000{singerMid}.jpg`
+
+**getUrl 音质参数**：API 需要带 `k`，如 `320k`，不是 `320`
+
+### 4.2 酷狗音乐 (kg)
+
+**搜索接口**：`http://mobilecdn.kugou.com/api/v3/search/song`
+
+**重要**：返回字段是 `errcode`（不是 `error_code`）！
+
+```js
+// ✅ 正确
+if (result.errcode !== 0) { ... }
+
+// ❌ 错误
+if (result.error_code !== 0) { ... }
+```
+
+**封面图**：搜索结果自带 `imgurl` 字段，替换 `{size}` 为 `400`
+
+```js
+var picUrl = item.imgurl ? item.imgurl.replace('{size}', '400') : ''
+```
+
+**getUrl 音质参数**：`128k` / `320k` / `999k`
+
+### 4.3 酷我音乐 (kw)
+
+**搜索接口**：`http://search.kuwo.cn/r.s`
+
+**封面图**：`https://img2.kuwo.cn/star/albumcover/300/{ALBUMID}.jpg`
+
+**音质信息**：在 `N_MINFO` 字段中，格式为 `level:xxx,bitrate:xxx,format:xxx,size:xxx;...`
+
+```js
+var parts = info.N_MINFO.split(';')
+for (var j = 0; j < parts.length; j++) {
+  var m = parts[j].match(/level:(\w+),bitrate:(\d+),format:(\w+),size:([\w.]+)/)
+  if (m) {
+    if (m[2] === '20900') qualities.jymaster = m[4]
+    else if (m[2] === '4000') qualities.hires = m[4]
+    else if (m[2] === '2000') qualities.lossless = m[4]
+    else if (m[2] === '320') qualities.exhigh = m[4]
+    else if (m[2] === '128') qualities.standard = m[4]
+  }
+}
+```
+
+**getUrl 音质参数**：`128k` / `320k` / `999k`
+
+### 4.4 网易云音乐 (wy)
+
+**搜索接口**：`https://music.163.com/api/search/get/web`（简单 GET，不需要 weapi 加密）
+
+**封面图**：`picId` 需要 Base64 编码后拼接
+
+```js
+var picIdStr = String(s.album.picId)
+var picIdB64 = Buffer.from(picIdStr).toString('base64').replace(/=/g, '')
+var pic = 'https://p2.music.126.net/' + picIdB64 + '/' + picIdStr + '.jpg'
+```
+
+**getUrl 音质参数**：数字格式 `128000` / `320000` / `999000`（不是带k的）
+
+**加密接口**：
+- `eapi`：AES-128-ECB，key = `e82ckenh8dichen8`
+- `weapi`：AES-128-CBC + RSA（用于需要登录的接口）
+
+**ext 功能**：
+- `userPlaylist`：需要 `playlist_url` 环境变量（网易云个人主页链接）
+- `dailyRecommend`：每日推荐
+- `personalFm`：私人FM
+- `myLikedSongs`：我喜欢的音乐
+
+### 4.5 咪咕音乐 (mg)
+
+**搜索签名**：MD5 拼接
+
+```js
+var sign = crypto.createHash('md5').update(
+  str + signatureMd5 + 'yyapp2d16148780a1dcc7408e06336b98cfd50' + deviceId + time
+).digest('hex')
+```
+
+**封面图**：搜索结果可能返回相对路径，需要拼接域名
+
+```js
+var img = data.img3 || data.img2 || data.img1 || ''
+if (img && img.indexOf('http') !== 0) img = 'https://d.musicapp.migu.cn' + img
+```
+
+**getUrl 音质参数**：`128k` / `320k` / `999k`
+
+### 4.6 GIT音源 (git)
+
+- 无搜索功能（返回空列表）
+- 纯音源插件，只有 `getUrl`
+- getUrl 音质参数：`128k` / `320k` / `999k`
+
+---
+
+## 五、getUrl 测速容灾逻辑
+
+所有平台统一使用**并发测速**模式：同时请求多个 API，取第一个成功的结果。
+
+```js
+function getUrl(songId, quality) {
+  var apis = buildApis(songId, quality)
+  var promises = []
+  for (var i = 0; i < apis.length; i++) {
+    (function(api) {
+      promises.push(
+        httpGet(api.url, api.headers, 8000).then(function(res) {
+          var url = api.extract(res)
+          if (url) return { name: api.name, url: url }
+          throw new Error('no url')
+        }).catch(function(err) {
+          throw err
+        })
+      )
+    })(apis[i])
+  }
+  return Promise.all(promises.map(function(p) {
+    return p.then(function(v) { return { status: 'fulfilled', value: v } })
+            .catch(function(e) { return { status: 'rejected', reason: e } })
+  })).then(function(results) {
+    for (var i = 0; i < results.length; i++) {
+      if (results[i].status === 'fulfilled') return results[i].value.url
+    }
+    return ''
+  })
+}
+```
+
+### 5.1 音源 API 列表
+
+| API | 支持平台 | 特点 |
+|-----|---------|------|
+| 聆澜 | 全部 | 需要 `ceru_key`，最稳定 |
+| HUIBQ (lxmusicapi) | 全部 | `X-Request-Key: share-v3` |
+| 星海 | 全部 | 聚合接口 |
+| 念心 | tx/kg/kw/mg | 个人维护 |
+| 长青 | tx/kg/kw/mg | 个人维护 |
+| 星海备 | 全部 | 备用 |
+| fish | 全部 | 个人维护 |
+| HYW | 全部 | 需要 `X-Card-Key` |
+| 忆音 | tx | 直接返回 URL |
+| 收集QQ | tx | 专用 |
+| 收集KW | kw | 专用 |
+| bb | wy | 网易云专用 |
+| ymc | wy | 网易云专用 |
+| unms | wy | 网易云专用 |
+| 官方 | wy | 网易云官方 weapi |
+
+---
+
+## 六、版本号管理规范
+
+**所有平台统一版本号**，每次修改全部升级：
+
+- 当前版本：`0.0.3`
+- 下次修改：`0.0.4`
+- 再下次：`0.0.5`
+
+文件名格式：`Koneko_{平台名}_v{版本号}.js`
+
+---
+
+## 七、常见报错与解决
+
+| 报错 | 原因 | 解决 |
+|------|------|------|
+| `Cannot find module 'axios'` | 用了 axios | 改用 `http`/`https` 内置模块 |
+| `String cannot be converted to JSONObject` | 搜索返回了非对象/字符串 | 加 `.catch()` 兜底返回正确格式 |
+| `Field 'list' is required` | 搜索返回 `songs` 而非 `list` | 改字段名为 `list` |
+| `SyntaxError: Invalid or unexpected token` | 用了 `catch { }` | 改为 `catch (e) { }` |
+| `FileNotFoundException: plugin.json` | 12-4版本需要文件夹结构 | 创建 `plugin.json` + `index.js` |
+| 搜索无结果 | 字段名不匹配 | 检查 `errcode` vs `error_code` |
+| 播放失败 | `mapBr` 返回格式不对 | QQ/kg/kw/mg/git 用 `320k`，wy 用 `320000` |
+| 封面图不显示 | URL 格式错误或跨域 | 检查各平台封面图拼接规则 |
+
+---
+
+## 八、环境变量
+
+```js
+var env = global.env || {}
+var CERU_KEY = env.ceru_key || ''      // 聆澜API密钥
+var WY_COOKIE = env.cookie || ''        // 网易云Cookie
+var PLAYLIST_URL = env.playlist_url || '' // 网易云个人主页链接
+```
+
+在 QZ Music 设置中配置环境变量，插件通过 `global.env` 读取。
+
+---
+
+## 九、完整代码参考
+
+6个平台的完整代码见产物目录：
+
+- `Koneko_QQ音乐_v0.0.3.js`
+- `Koneko_酷狗音乐_v0.0.3.js`
+- `Koneko_酷我音乐_v0.0.3.js`
+- `Koneko_网易云音乐_v0.0.3.js`
+- `Koneko_咪咕音乐_v0.0.3.js`
+- `Koneko_GIT音源_v0.0.3.js`
+
+---
+
+## 十、后续开发建议
+
+1. **每次修改全部平台统一升级版本号**
+2. **先在浏览器/ curl 测试 API 是否可用**
+3. **注意 Javet 兼容性，避免现代 JS 语法**
+4. **搜索返回务必包含 `list` 字段**
+5. **getUrl 注意各平台音质参数格式差异**
+6. **封面图 URL 确保可访问（注意跨域和防盗链）**
+7. **所有异步操作加 `.catch()` 兜底**
+8. **优先使用官方搜索接口，音源用第三方 API 容灾**
--- a/插件规范│QZ-Music-Plugin-Development-Guide.md
+++ b/插件规范│QZ-Music-Plugin-Development-Guide.md
@@ -0,0 +1,856 @@
+# 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(/&apos;/g, "'")
+    .replace(/&quot;/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): 初始版本
+
+---
+
+**文档结束**
--- 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: 初始版本
+
+---
+
+**文档结束**
--- a/插件规范（初版）│QZ_Music-V2-Plugin-Development-Guide.md
+++ b/插件规范（初版）│QZ_Music-V2-Plugin-Development-Guide.md
@@ -0,0 +1,871 @@
+# 插件开发帮助文档
+
+## 目录
+1. [概述](#概述)
+2. [核心设计原则](#核心设计原则)
+3. [从其他平台迁移指南](#从其他平台迁移指南)
+4. [插件基本结构](#插件基本结构)
+5. [数据格式规范](#数据格式规范)
+6. [示例代码详解](#示例代码详解)
+7. [平台配置参考](#平台配置参考)
+8. [常见问题](#常见问题)
+
+---
+
+## 概述
+
+本文档用于指导开发者编写音源插件。本系统使用 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 API_KEY = global.env.API_KEY || ''
+
+// 读取自定义服务端地址
+const CUSTOM_SERVER = global.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 {
+  lyric: '歌词内容',
+  tlyric: '翻译歌词'
+}
+```
+
+---
+
+## 插件基本结构
+
+### 文件头部注释
+
+```javascript
+/**
+ * @name 平台A音源
+ * @description 音源插件
+ * @version 3.0.0
+ * @author 开发者
+ * @homepage https://github.com/your-repo
+ * @license MIT
+ * 
+ * 支持平台: 平台A
+ * 支持音质: 128k, 320k, flac
+ */
+```
+
+### 核心导入
+
+```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               // 平台标识
+}
+```
+
+### 歌词统一格式
+
+```javascript
+{
+  lyric: String,       // 普通歌词
+  tlyric: String,      // 翻译歌词
+  qrc: String,         // 逐字歌词
+  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 平台A音源
+ * @description 音源插件示例
+ * @version 3.0.0
+ * @author 开发者
+ * 
+ * 支持平台: 平台A
+ * 支持音质: 128k, 320k, flac
+ */
+
+'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']
+
+// ==================== 工具函数 ====================
+
+/**
+ * 文件大小格式化
+ * @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} artistList - 创作者列表
+ * @returns {string} 用 "、" 连接的创作者名
+ */
+function formatArtistName(artistList) {
+  if (!artistList || !Array.isArray(artistList)) return ''
+  return artistList.map(a => a.name || a).join('、')
+}
+
+/**
+ * HTML 实体解码
+ * @param {string} str - 含 HTML 实体的字符串
+ * @returns {string} 解码后的字符串
+ */
+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, ' ')
+}
+
+// ==================== 核心功能 ====================
+
+/**
+ * 搜索内容
+ * @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.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: page,
+    limit: limit,
+    allPage: Math.ceil(data.total / limit),
+    source: PLATFORM
+  }
+}
+
+/**
+ * 获取播放 URL
+ * @param {string} id - 内容 ID
+ * @param {string} quality - 音质标识
+ * @returns {Promise<string>} 播放 URL
+ */
+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: id, 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} id - 内容 ID
+ * @returns {Promise<Object>} 歌词对象
+ */
+async function getLyric(id) {
+  const url = `${CONFIG.serverUrl}/lyric`
+  const response = await axios.get(url, {
+    params: { id: id },
+    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}/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 || ''
+    }
+  }
+}
+
+/**
+ * 获取合集详情
+ * @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.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 || ''
+    }
+  }
+}
+
+/**
+ * 获取热搜词
+ * @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: '平台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']
+}
+```
+
+---
+
+## 常见问题
+
+### 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 || '默认地址'
+```
+
+---
+
+## 附录
+
+### 参考资源
+
+- Node.js 官方文档
+- axios 文档
+
+### 版本历史
+
+- v1.0.0 (2024-05-28): 初始版本
+
+---
+
+**文档结束**