# 插件开发帮助文档

> **版本**: 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(/'/g, "'")
    .replace(/"/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: 初始版本

---

**文档结束**