# 网易云歌词插件 — 使用说明

> 基于 HuluMusic (MusicFree) 插件协议的歌词搜索与下载插件

## 功能

| 功能 | 说明 |
|------|------|
| 搜索歌曲 | 支持按歌曲名/歌手搜索，返回歌曲列表 |
| 歌词搜索 | 支持 `lyric` 类型搜索，用于歌词关联 |
| 获取歌词 | 获取带时间戳的 LRC 歌词，**含中文翻译** |
| 获取歌曲详情 | 根据 ID 查询歌曲信息 |
| 获取专辑信息 | 查询专辑及专辑内歌曲列表 |
| 导入单曲 | 通过网易云歌曲链接或 ID 导入单曲 |

## 插件文件

- **文件名**：`网易云歌词插件.js`
- **平台名**：`网易云歌词`
- **版本**：1.0.0
- **数据源**：网易云音乐公开接口

## 安装方法

### 方法一：本地安装

1. 打开 HuluMusic App
2. 进入 **侧边栏 → 设置 → 插件设置**
3. 点击 **从本地安装**
4. 选择 `网易云歌词插件.js` 文件
5. 安装完成后在插件列表中确认已启用

### 方法二：网络安装

1. 将 `网易云歌词插件.js` 上传到任意可公开访问的服务器（GitHub raw / Gitee raw / 个人服务器）
2. 进入 **设置 → 插件设置 → 从网络安装**
3. 输入文件的 raw URL
4. 点击确认安装

## 使用方法

### 1. 搜索并播放歌曲

安装插件后，在搜索页输入歌曲名或歌手名即可搜索。搜索结果会显示来自「网易云歌词」的歌曲。

### 2. 获取歌词

播放歌曲时，如果歌曲来自本插件，App 会自动调用 `getLyric` 获取歌词。

### 3. 歌词关联（跨平台歌词匹配）

如果当前播放的歌曲没有歌词，可以使用歌词搜索功能关联其他平台的歌词：

1. 在播放页打开歌词面板
2. 点击歌词选项 → **搜索歌词**
3. 输入歌曲名搜索
4. 从搜索结果中选择匹配的歌词
5. 歌词将关联到当前歌曲

> 关联后，App 会调用本插件的 `getLyric` 获取实际歌词内容。

### 4. 导入单曲

在导入页面粘贴网易云歌曲分享链接（如 `https://music.163.com/#/song?id=186016`），插件会自动解析并导入。

## 配置项

插件支持用户自定义变量，在 **插件设置 → 插件详情** 中配置：

| 变量名 | 说明 | 默认值 |
|--------|------|--------|
| `showTranslation` | 是否获取翻译歌词。`true`=获取翻译，`false`=只获取原文 | `true` |

## 插件协议说明

本插件遵循 `IPlugin.IPluginDefine` 接口规范：

```
module.exports = {
    platform: "网易云歌词",        // 来源名（必须）
    version: "1.0.0",             // 插件版本
    search(query, page, type),     // 搜索：支持 music/lyric/album/artist
    getLyric(musicItem),           // 获取歌词：返回 { rawLrc, translation }
    getMusicInfo(musicBase),       // 获取歌曲详情
    getAlbumInfo(albumItem, page), // 获取专辑信息
    importMusicItem(urlLike),      // 导入单曲
}
```

### 沙箱可用依赖

插件运行在沙箱中，以下依赖通过 `require()` 引入：

| 包名 | 用途 |
|------|------|
| `axios` | HTTP 请求 |
| `qs` | URL 参数序列化 |
| `dayjs` | 日期格式化 |
| `crypto-js` | 加密/哈希 |
| `cheerio` | HTML 解析 |
| `big-integer` | 大整数运算 |
| `he` | HTML 实体解码 |
| `webdav` | WebDAV 客户端 |

环境变量（通过 `env` 访问）：
- `env.getUserVariables()` — 用户自定义变量
- `env.appVersion` — App 版本
- `env.os` — 操作系统
- `env.lang` — 语言

## 测试结果

插件已通过以下测试：

- ✅ 语法检查通过
- ✅ 沙箱加载测试通过（模拟 HuluMusic 插件环境）
- ✅ 真实 API 联调：搜索「晴天 周杰伦」返回 20 条结果，歌词 39 行
- ✅ 翻译测试：搜索「See You Again」，原文 68 行 + 中文翻译 67 行
- ✅ 歌词搜索类型（`lyric`）测试通过
- ✅ 导入单曲测试通过

## 注意事项

1. **网络要求**：需要能访问 `music.163.com`，建议在 WiFi 环境使用
2. **版权声明**：本插件仅供学习交流使用，歌词版权归原网站所有，请合理合法使用
3. **接口稳定性**：基于互联网公开接口，如接口变更可能导致插件失效
4. **翻译歌词**：并非所有歌曲都有翻译，无翻译时只返回原文歌词

## 技术架构

```
HuluMusic App
    │
    ▼
PluginManager (插件管理器)
    │  读取 .js 文件 → new Plugin(funcCode, path)
    ▼
Plugin (沙箱执行)
    │  Function() 沙箱环境
    ├── require("axios") → 网络请求
    ├── require("qs") → 参数序列化
    └── env.getUserVariables() → 用户配置
    │
    ▼
网易云歌词插件
    │
    ├── search() → POST /api/search/get/web
    ├── getLyric() → GET /api/song/lyric
    ├── getMusicInfo() → GET /api/song/detail
    └── getAlbumInfo() → GET /api/album/{id}
    │
    ▼
返回标准数据结构 → 缓存 → 展示
```