# 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 容灾**