Koneko_api_for_QZ-Music/Koneko_插件开发文档_v0.0.1.md

# Koneko QZ Music v2/v3 鎻掍欢寮€鍙戞枃妗?
> 鐗堟湰锛?.0.4 | 浣滆€咃細浜戞眬(Miao-moe) | 鏁寸悊鏃ユ湡锛?026-06-20

---

## 涓€銆佹杩?
涓?QZ Music v2/v3 缂栧啓 6 涓煶涔愬钩鍙版嫇灞曟彃浠讹細
- QQ闊充箰 (`koneko_tx`)
- 閰风嫍闊充箰 (`koneko_kg`)
- 閰锋垜闊充箰 (`koneko_kw`)
- 缃戞槗浜戦煶涔?(`koneko_wy`)
- 鍜挄闊充箰 (`koneko_mg`)
- GIT闊虫簮 (`koneko_git`)

## 浜屻€佹彃浠惰鑼?
### 2.1 杩愯鐜

- Node.js 杩愯鏃讹紙Javet/V8锛?- CommonJS 妯″潡瑙勮寖
- `module.exports` 瀵煎嚭鎺ュ彛
- 涓嶆敮鎸?`axios`锛屼娇鐢ㄥ唴缃?`http`/`https` 妯″潡

### 2.2 ES5 鍏煎锛圝avet/V8 闄愬埗锛?
| 璇硶 | 鐘舵€?| 鏇夸唬 |
|------|------|------|
| `let` / `const` | 鉂?| `var` |
| 绠ご鍑芥暟 | 鉂?| `function() {}` |
| `async`/`await` | 鉂?| Promise 閾惧紡 |
| `catch { }` 鏃犲弬鏁?| 鉂?| `catch (e) { }` |
| `Promise.allSettled` | 鉂?| `Promise.all` + 鎵嬪姩鍖呰 |
| `Object.entries/values` | 鉂?| `for...in` |
| `Array.includes` | 鉂?| `indexOf` |
| `String.startsWith` | 鉂?| `indexOf(...) === 0` |
| `class` | 鉂?| 瀵硅薄瀛楅潰閲?|
| 妯℃澘瀛楃涓?`${}` | 鉁?| - |
| `Buffer` | 鉁?| - |

### 2.3 鎻掍欢瀵煎嚭鏍煎紡

```js
module.exports = {
  musicSearch: { search: fn, tipSearch: fn, hotSearch: fn },
  tipSearch: { getList: fn },
  hotSearch: { getList: fn },
  getUrl: fn,
  getLyric: fn,
  songList: { getListDetail: fn },
  album: { getListDetail: fn },
  pluginInfo: { info, env, ext, quality, supportFunc },
  // 缃戞槗浜戠壒鏈?  userPlaylist: fn,
  dailyRecommend: fn,
  personalFm: fn,
  myLikedSongs: fn
}
```

### 2.4 鎼滅储缁撴灉鏍煎紡

```js
{
  list: [{
    id: String,
    name: String,
    artists: String,   // 鐢?"銆? 鍒嗛殧
    source: String,    // tx/kg/kw/wy/mg
    pic: String,       // 灏侀潰澶у浘
    mPic: String,      // 灏侀潰涓浘
    sPic: String,      // 灏侀潰灏忓浘
    albumName: String,
    albumId: String,
    interval: String,  // "m:ss"
    qualities: { standard: '3.21MB', exhigh: '7.85MB', ... }
  }],
  allPage: Number,
  limit: Number,
  total: Number,
  source: String
}
```

### 2.5 鐜鍙橀噺

閫氳繃 `global.env` 璇诲彇锛?
```js
var env = global.env || {}
var CERU_KEY = env.ceru_key || ''
var WY_COOKIE = env.cookie || ''
var PLAYLIST_URL = env.playlist_url || ''
```

### 2.6 闊宠川鏍囪瘑

| ID | 鍚箟 |
|----|------|
| `standard` | 鏍囧噯闊宠川 (128k) |
| `exhigh` | 楂樺搧闊宠川 (320k) |
| `lossless` | 鏃犳崯闊宠川 (FLAC) |
| `hires` | Hi-Res |
| `jyeffect` | 楂樻竻鐜粫澹?|
| `sky` | 娌夋蹈鐜粫澹?|
| `jymaster` | 瓒呮竻姣嶅甫 |

## 涓夈€佸悇骞冲彴 API

### 3.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]
```

**灏侀潰鍥捐鍒?*锛?- 鏈変笓杈慖D锛歚https://y.gtimg.cn/music/photo_new/T002R500x500M000{albumId}.jpg`
- 鏃犱笓杈慖D锛歚https://y.gtimg.cn/music/photo_new/T001R500x500M000{singerMid}.jpg`

**getUrl 闊宠川鍙傛暟**锛歚128k` / `320k` / `999k`

### 3.2 閰风嫍闊充箰 (kg)

**鎼滅储鎺ュ彛**锛歚http://mobilecdn.kugou.com/api/v3/search/song`

**娉ㄦ剰**锛氳繑鍥炲瓧娈垫槸 `errcode`锛堜笉鏄?`error_code`锛?
**灏侀潰鍥?*锛氭悳绱㈢粨鏋滆嚜甯?`imgurl`锛屾浛鎹?`{size}` 涓?`400`

### 3.3 閰锋垜闊充箰 (kw)

**鎼滅储鎺ュ彛**锛歚http://search.kuwo.cn/r.s`

**灏侀潰鍥?*锛歚https://img2.kuwo.cn/star/albumcover/300/{ALBUMID}.jpg`

**闊宠川淇℃伅**锛氬湪 `N_MINFO` 瀛楁涓В鏋?
### 3.4 缃戞槗浜戦煶涔?(wy)

**鎼滅储鎺ュ彛**锛歚https://music.163.com/api/search/get/web`锛圙ET锛屼笉闇€瑕?weapi锛?
**灏侀潰鍥?*锛歚picId` 闇€ Base64 缂栫爜

```js
var picIdB64 = Buffer.from(String(s.album.picId)).toString('base64').replace(/=/g, '')
var pic = 'https://p2.music.126.net/' + picIdB64 + '/' + picIdStr + '.jpg'
```

**鍔犲瘑鎺ュ彛**锛?- `eapi`锛欰ES-128-ECB锛宬ey = `e82ckenh8dichen8`
- `weapi`锛欰ES-128-CBC + RSA

**Cookie 鍔熻兘**锛堥渶璁剧疆 `cookie` 鐜鍙橀噺锛夛細
- `userPlaylist()` - 涓汉姝屽崟锛堥渶 `playlist_url`锛?- `dailyRecommend()` - 姣忔棩鎺ㄨ崘
- `personalFm()` - 绉佷汉FM
- `myLikedSongs()` - 鎴戝枩娆㈢殑闊充箰
- `songList(id)` - 姝屽崟璇︽儏
- `album(id)` - 涓撹緫璇︽儏
- `getLyric(id)` - 姝岃瘝鑾峰彇

### 3.5 鍜挄闊充箰 (mg)

**鎼滅储绛惧悕**锛歁D5 鎷兼帴

```js
var sign = crypto.createHash('md5').update(
  str + signatureMd5 + 'yyapp2d16148780a1dcc7408e06336b98cfd50' + deviceId + time
).digest('hex')
```

**灏侀潰鍥?*锛氭悳绱㈢粨鏋滃彲鑳借繑鍥炵浉瀵硅矾寰勶紝闇€鎷兼帴 `https://d.musicapp.migu.cn`

### 3.6 GIT闊虫簮 (git)

绾煶婧愭彃浠讹紝鏃犳悳绱㈠姛鑳斤紝浠?`getUrl`

## 鍥涖€乬etUrl 瀹圭伨鏈哄埗

鎵€鏈夊钩鍙扮粺涓€浣跨敤**骞跺彂娴嬮€?*妯″紡锛?
```js
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 ''
})
```

### 闊虫簮 API 鍒楄〃

| API | 骞冲彴 | 璇存槑 |
|-----|------|------|
| 鑱嗘緶 | 鍏ㄩ儴 | 闇€ `ceru_key`锛屾渶绋冲畾 |
| HUIBQ | 鍏ㄩ儴 | `X-Request-Key: share-v3` |
| 鏄熸捣 | 鍏ㄩ儴 | 鑱氬悎鎺ュ彛 |
| 蹇靛績 | tx/kg/kw/mg | 涓汉缁存姢 |
| 闀块潚 | tx/kg/kw/mg | 涓汉缁存姢 |
| 鏄熸捣澶?| 鍏ㄩ儴 | 澶囩敤 |
| fish | 鍏ㄩ儴 | 涓汉缁存姢 |
| HYW | 鍏ㄩ儴 | 闇€ `X-Card-Key` |
| 蹇嗛煶 | tx | 鐩存帴杩斿洖 URL |
| 鏀堕泦QQ | tx | QQ涓撶敤 |
| 鏀堕泦KW | kw | 閰锋垜涓撶敤 |
| bb | wy | 缃戞槗浜戜笓鐢?|
| ymc | wy | 缃戞槗浜戜笓鐢?|
| unms | wy | 缃戞槗浜戜笓鐢?|
| 瀹樻柟 weapi | wy | 缃戞槗浜戝畼鏂?|

## 浜斻€佺増鏈鐞?
- 鎵€鏈夊钩鍙扮粺涓€鐗堟湰鍙?- 褰撳墠鐗堟湰锛歚0.0.1`
- 鏂囦欢鍚嶆牸寮忥細`Koneko_{骞冲彴鍚峿_v{鐗堟湰鍙穧.js`

## 鍏€佸父瑙侀棶棰?
| 闂 | 鍘熷洜 | 瑙ｅ喅 |
|------|------|------|
| `Cannot find module 'axios'` | 鐢ㄤ簡 axios | 鏀圭敤鍐呯疆 `http`/`https` |
| `Field 'list' is required` | 杩斿洖 `songs` 鑰岄潪 `list` | 鏀瑰瓧娈靛悕涓?`list` |
| 鎼滅储鏃犵粨鏋?| 瀛楁鍚嶄笉鍖归厤 | 妫€鏌?`errcode` vs `error_code` |
| 鎾斁澶辫触 | `mapBr` 杩斿洖鏍煎紡涓嶅 | tx/kg/kw/mg/git 鐢?`320k`锛寃y 鐢?`320000` |
| 灏侀潰鍥句笉鏄剧ず | URL 鏍煎紡閿欒 | 妫€鏌ュ悇骞冲彴鎷兼帴瑙勫垯 |

## 涓冦€佺浉鍏抽摼鎺?
- Gitea: http://171.80.3.149:4321/miao-moe
- CeruMusic: http://171.80.3.149:4321/miao-moe/CeruMusic
- QZMusic PC: http://171.80.3.149:4321/miao-moe/QZMusic_PC