feat(music): add Kugou (酷狗音乐) as a music source (#69)

Adds a self-contained Kugou provider (bilibili-style: direct API calls, no
embedded API server, no new npm dependency) plus full backend + WebUI wiring.

Provider (src/music/kugou.ts): search, song-url (with device registration),
lyrics (KRC decode), song detail, playlist, album, personal FM, QR login +
cookie persistence, and quality. Request signing / crypto / KRC decoding are
ported from the MIT-licensed MakcRe/KuGouMusicApi using Node's built-in
crypto and zlib (no third-party crypto packages).

Wiring: the "kugou" platform is threaded through the provider contract, queue,
play-history, bot instance/manager dispatch (getProviderFor + the -k command
flag), index/server composition, the music/player/auth routers (unified
/search/all, /quality, the platform coercions, QR login), the cookie store,
and the WebUI (search source tab + badge, SongCard badge, brand token, and a
Kugou QR/cookie login card in Settings).

Verified live during development: search, lyrics, and album playback resolve
correctly. NOT verifiable in CI (Kugou anti-bot blocks the build host's IP):
play-URL resolution, QR login, and VIP audio — these are built faithfully to
the reference and need end-to-end testing on a non-flagged IP / a Kugou
account. See the header comment in kugou.ts.

Includes src/music/kugou.test.ts (mappers + KRC→LRC). An adversarial review
pass fixed: pagination truncating on filtered counts, an ms/seconds duration
heuristic, dfid soft-fail caching, the /v5/url random-dfid fallback, the FM
body identity, and an unguarded nickname decode.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

web/src/components/SongCard.vue

@@ -7,8 +7,8 @@
         <span class="song-name">{{ song.name }}</span>
         <span
           class="platform-badge"
-          :class="song.platform === 'bilibili' ? 'badge-bilibili' : song.platform === 'qq' ? 'badge-qq' : song.platform === 'youtube' ? 'badge-youtube' : song.platform === 'local' ? 'badge-local' : 'badge-netease'"
-        >{{ song.platform === 'bilibili' ? 'B站' : song.platform === 'qq' ? 'QQ' : song.platform === 'youtube' ? 'YouTube' : song.platform === 'local' ? '本地' : '网易云' }}</span>
+          :class="song.platform === 'bilibili' ? 'badge-bilibili' : song.platform === 'qq' ? 'badge-qq' : song.platform === 'youtube' ? 'badge-youtube' : song.platform === 'local' ? 'badge-local' : song.platform === 'kugou' ? 'badge-kugou' : 'badge-netease'"
+        >{{ song.platform === 'bilibili' ? 'B站' : song.platform === 'qq' ? 'QQ' : song.platform === 'youtube' ? 'YouTube' : song.platform === 'local' ? '本地' : song.platform === 'kugou' ? '酷狗' : '网易云' }}</span>
       </div>
       <div class="song-artist">{{ song.artist }}</div>
     </div>
@@ -140,6 +140,11 @@ function formatDuration(seconds: number): string {
   color: var(--color-primary);
 }
 
+.badge-kugou {
+  background: var(--brand-kugou-12);
+  color: var(--brand-kugou);
+}
+
 .song-artist {
   font-size: 12px;
   color: var(--text-secondary);

web/src/stores/player.ts

@@ -10,7 +10,7 @@ export interface Song {
   album: string;
   duration: number;
   coverUrl: string;
-  platform: 'netease' | 'qq' | 'bilibili' | 'youtube' | 'local';
+  platform: 'netease' | 'qq' | 'bilibili' | 'youtube' | 'local' | 'kugou';
 }
 
 export type Source = 'netease' | 'qq';

web/src/styles/variables.scss

@@ -80,6 +80,8 @@
   --brand-bilibili-15: rgba(0, 161, 214, 0.15);
   --brand-youtube: #ff0000;
   --brand-youtube-12: rgba(255, 0, 0, 0.12);
+  --brand-kugou: #2ca2f9;
+  --brand-kugou-12: rgba(44, 162, 249, 0.12);
 }
 
 // Dark theme (default)

web/src/views/Search.vue

@@ -72,6 +72,11 @@
           :class="{ active: selectedSource === 'bilibili' }"
           @click="selectedSource = 'bilibili'"
         >B站</button>
+        <button
+          class="source-btn"
+          :class="{ active: selectedSource === 'kugou' }"
+          @click="selectedSource = 'kugou'"
+        >酷狗</button>
         <button
           v-if="hasLocalSongs"
           class="source-btn"
@@ -89,7 +94,7 @@
           单曲<span class="tab-count">{{ filteredSongs.length }}</span>
         </button>
         <button
-          v-if="selectedSource !== 'bilibili' && selectedSource !== 'local'"
+          v-if="selectedSource !== 'bilibili' && selectedSource !== 'local' && selectedSource !== 'kugou'"
           class="tab"
           :class="{ active: activeTab === 'albums' }"
           @click="activeTab = 'albums'"
@@ -97,7 +102,7 @@
           专辑<span class="tab-count">{{ filteredAlbums.length }}</span>
         </button>
         <button
-          v-if="selectedSource !== 'bilibili' && selectedSource !== 'local'"
+          v-if="selectedSource !== 'bilibili' && selectedSource !== 'local' && selectedSource !== 'kugou'"
           class="tab"
           :class="{ active: activeTab === 'playlists' }"
           @click="activeTab = 'playlists'"
@@ -182,12 +187,12 @@ const router = useRouter();
 
 const SOURCE_STORAGE_KEY = 'search-source';
 
-type SearchSource = 'netease' | 'qq' | 'bilibili' | 'local';
+type SearchSource = 'netease' | 'qq' | 'bilibili' | 'local' | 'kugou';
 
 function loadSource(): SearchSource {
   try {
     const stored = localStorage.getItem(SOURCE_STORAGE_KEY);
-    if (stored === 'netease' || stored === 'qq' || stored === 'bilibili' || stored === 'local') return stored;
+    if (stored === 'netease' || stored === 'qq' || stored === 'bilibili' || stored === 'local' || stored === 'kugou') return stored;
   } catch { /* localStorage blocked */ }
   return 'netease';
 }
@@ -232,7 +237,7 @@ watch(selectedSource, (src) => {
 
 // B站 / 本地上传没有专辑和歌单页签，切换时强制回到单曲。
 watch(selectedSource, (src) => {
-  if ((src === 'bilibili' || src === 'local') && activeTab.value !== 'songs') {
+  if ((src === 'bilibili' || src === 'local' || src === 'kugou') && activeTab.value !== 'songs') {
     activeTab.value = 'songs';
   }
 });
@@ -351,6 +356,7 @@ function badgeLabel(platform: string): string {
   if (platform === 'bilibili') return 'B站';
   if (platform === 'youtube') return 'YouTube';
   if (platform === 'local') return '本地';
+  if (platform === 'kugou') return '酷狗';
   return '网易云';
 }
 
@@ -359,6 +365,7 @@ function badgeClass(platform: string): string {
   if (platform === 'bilibili') return 'badge-bilibili';
   if (platform === 'youtube') return 'badge-youtube';
   if (platform === 'local') return 'badge-local';
+  if (platform === 'kugou') return 'badge-kugou';
   return 'badge-netease';
 }
 
@@ -645,6 +652,11 @@ onMounted(() => {
   color: var(--color-primary);
 }
 
+.badge-kugou {
+  background: var(--brand-kugou-12);
+  color: var(--brand-kugou);
+}
+
 .fav-badge {
   position: absolute;
   top: 8px;

web/src/views/Settings.vue

@@ -377,6 +377,76 @@
           <button class="btn-primary btn-save" @click="saveCookie('bilibili')">保存Cookie</button>
         </div>
       </div>
+
+      <!-- Kugou -->
+      <div class="account-card">
+        <div class="account-header">
+          <Icon icon="mdi:music-circle-outline" class="account-icon kugou-icon" />
+          <div class="account-info">
+            <div class="account-name">酷狗音乐</div>
+            <div class="account-status" :class="{ logged: kugouAuth.loggedIn }">
+              {{ kugouAuth.loggedIn ? `已登录: ${kugouAuth.nickname}` : '未登录' }}
+            </div>
+          </div>
+        </div>
+
+        <div class="login-methods">
+          <button
+            class="login-btn"
+            :class="{ active: kugouLoginMode === 'qr' }"
+            @click="startQrLogin('kugou')"
+            :disabled="kugouQr.loading"
+          >
+            <Icon icon="mdi:qrcode" />
+            扫码登录
+          </button>
+          <button
+            class="login-btn"
+            :class="{ active: kugouLoginMode === 'cookie' }"
+            @click="kugouLoginMode = 'cookie'"
+          >
+            <Icon icon="mdi:cookie" />
+            Cookie登录
+          </button>
+        </div>
+
+        <!-- QR Code -->
+        <div v-if="kugouLoginMode === 'qr'" class="qr-section">
+          <div v-if="kugouQr.loading" class="qr-loading">
+            <Icon icon="mdi:loading" class="spin" />
+            生成二维码中...
+          </div>
+          <div v-else-if="kugouQr.dataUrl" class="qr-wrap">
+            <img :src="kugouQr.dataUrl" class="qr-image" alt="QR Code" />
+            <div class="qr-status" :class="kugouQr.status">
+              <template v-if="kugouQr.status === 'waiting'">
+                <Icon icon="mdi:cellphone" /> 请使用酷狗音乐APP扫码
+              </template>
+              <template v-else-if="kugouQr.status === 'scanned'">
+                <Icon icon="mdi:check" /> 已扫码，请在手机上确认
+              </template>
+              <template v-else-if="kugouQr.status === 'confirmed'">
+                <Icon icon="mdi:check-circle" /> 登录成功!
+              </template>
+              <template v-else-if="kugouQr.status === 'expired'">
+                <Icon icon="mdi:refresh" /> 二维码已过期
+                <button class="btn-link" @click="startQrLogin('kugou')">重新生成</button>
+              </template>
+            </div>
+          </div>
+        </div>
+
+        <!-- Cookie -->
+        <div v-if="kugouLoginMode === 'cookie'" class="cookie-section">
+          <textarea
+            v-model="kugouCookie"
+            class="textarea"
+            placeholder="粘贴酷狗Cookie (token=...; userid=...)..."
+            rows="3"
+          />
+          <button class="btn-primary btn-save" @click="saveCookie('kugou')">保存Cookie</button>
+        </div>
+      </div>
     </section>
 
     <!-- Audio Quality requires quality -->
@@ -792,6 +862,7 @@ const editForm = reactive({
 const neteaseCookie = ref('');
 const qqCookie = ref('');
 const bilibiliCookie = ref('');
+const kugouCookie = ref('');
 const commandPrefix = ref('!');
 
 // Audio quality
@@ -823,11 +894,13 @@ async function setQuality(q: string) {
 const neteaseLoginMode = ref<'qr' | 'cookie' | null>(null);
 const qqLoginMode = ref<'qr' | 'cookie' | null>(null);
 const bilibiliLoginMode = ref<'qr' | 'cookie' | null>(null);
+const kugouLoginMode = ref<'qr' | 'cookie' | null>(null);
 
 // Auth status
 const neteaseAuth = reactive({ loggedIn: false, nickname: '', avatarUrl: '' });
 const qqAuth = reactive({ loggedIn: false, nickname: '', avatarUrl: '' });
 const bilibiliAuth = reactive({ loggedIn: false, nickname: '', avatarUrl: '' });
+const kugouAuth = reactive({ loggedIn: false, nickname: '', avatarUrl: '' });
 
 // QR state
 interface QrState {
@@ -847,22 +920,28 @@ const qqQr = reactive<QrState>({
 const bilibiliQr = reactive<QrState>({
   loading: false, dataUrl: '', key: '', status: 'waiting', pollTimer: null,
 });
+const kugouQr = reactive<QrState>({
+  loading: false, dataUrl: '', key: '', status: 'waiting', pollTimer: null,
+});
 
 function getQrState(platform: string): QrState {
   if (platform === 'bilibili') return bilibiliQr;
+  if (platform === 'kugou') return kugouQr;
   return platform === 'netease' ? neteaseQr : qqQr;
 }
 
 async function checkAuthStatus() {
   try {
-    const [nRes, qRes, bRes] = await Promise.all([
+    const [nRes, qRes, bRes, kRes] = await Promise.all([
       axios.get('/api/auth/status', { params: { platform: 'netease' } }),
       axios.get('/api/auth/status', { params: { platform: 'qq' } }),
       axios.get('/api/auth/status', { params: { platform: 'bilibili' } }),
+      axios.get('/api/auth/status', { params: { platform: 'kugou' } }),
     ]);
     Object.assign(neteaseAuth, nRes.data);
     Object.assign(qqAuth, qRes.data);
     Object.assign(bilibiliAuth, bRes.data);
+    Object.assign(kugouAuth, kRes.data);
   } catch {
     // API not ready
   }
@@ -872,6 +951,7 @@ async function startQrLogin(platform: string) {
   const qr = getQrState(platform);
   if (platform === 'netease') neteaseLoginMode.value = 'qr';
   else if (platform === 'bilibili') bilibiliLoginMode.value = 'qr';
+  else if (platform === 'kugou') kugouLoginMode.value = 'qr';
   else qqLoginMode.value = 'qr';
 
   // Stop existing poll
@@ -1032,7 +1112,9 @@ async function toggleBot(botId: string, connected: boolean) {
 }
 
 async function saveCookie(platform: string) {
-  const cookie = platform === 'bilibili' ? bilibiliCookie.value : platform === 'netease' ? neteaseCookie.value : qqCookie.value;
+  const cookie = platform === 'bilibili' ? bilibiliCookie.value
+    : platform === 'kugou' ? kugouCookie.value
+    : platform === 'netease' ? neteaseCookie.value : qqCookie.value;
   if (!cookie) return;
   try {
     await axios.post('/api/auth/cookie', { platform, cookie });
@@ -1557,6 +1639,7 @@ onUnmounted(() => {
   if (neteaseQr.pollTimer) clearInterval(neteaseQr.pollTimer);
   if (qqQr.pollTimer) clearInterval(qqQr.pollTimer);
   if (bilibiliQr.pollTimer) clearInterval(bilibiliQr.pollTimer);
+  if (kugouQr.pollTimer) clearInterval(kugouQr.pollTimer);
 });
 </script>
 
@@ -1698,6 +1781,10 @@ onUnmounted(() => {
   &.bilibili-icon {
     color: var(--brand-bilibili);
   }
+
+  &.kugou-icon {
+    color: var(--brand-kugou);
+  }
 }
 
 .account-name {