Koneko_api_for_QZ-Music/QZ_Music-V2 插件规范（初版）│QZ_Music-V2-Plugin-Development-Guide.md

# 插件开发帮助文档

## 目录
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(/'/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.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): 初始版本

---

**文档结束**