fix(profile): apply custom avatar immediately on idle setCustomAvatar / connect

Review feedback on PR #56:

1. setCustomAvatar(buf) now triggers applyIdleAvatar when the bot is idle
   (currentSong=null OR avatarEnabled=false). Spec said this; original impl
   only stored the buffer, so a fresh upload from Settings was invisible
   until next stop event. Track currentSong in BotProfileManager for the
   idle check.

2. onConnect drops the !avatarEnabled guard — on a fresh connect there's
   no song playing yet, so the spec matrix wants the custom avatar shown
   regardless of sync. Previously bots reconnected with a stale TS3
   server-side avatar.

3. CustomAvatarRow: defer the initializing=false flip to nextTick so the
   load-time data-url assignment's queued watcher sees initializing=true
   and bails. Removes the redundant PUT-on-mount that echoed the just-
   loaded bytes back to the server.

4. BotInstance avatar load wrapped in try/catch — a corrupt/locked file
   no longer crashes startup; we log and continue with no custom avatar.

Tests rewritten: 10 cases covering the full behavior matrix
(idle vs playing × sync on/off × custom set/null × stop/connect).

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

.claude/settings.local.json

@@ -13,7 +13,10 @@
       "mcp__Claude_Preview__*",
       "mcp__Claude_in_Chrome__*",
       "mcp__scheduled-tasks__*",
-      "Bash(npx vitest:*)"
+      "Bash(npx vitest:*)",
+      "Bash(cp \"C:\\\\Users\\\\saopig1\\\\.claude\\\\projects\\\\C--Users-saopig1-Music-teamspeak-music-bot\\\\b5a64d6f-051e-4b87-966c-ece97d2b879b\\\\tool-results\\\\webfetch-1776569008470-exv7qe.bin\" /tmp/design.gz)",
+      "Bash(gunzip -f /tmp/design.gz)",
+      "Read(//tmp/**)"
     ],
     "deny": [
       "Bash(git push * main)",

.github/workflows/docker-publish.yml

@@ -0,0 +1,64 @@
+name: Build and Publish Docker Image
+
+on:
+  push:
+    tags:
+      - 'v*.*.*'
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: 'Extra tag to publish (optional, e.g. "edge")'
+        required: false
+        default: ''
+
+env:
+  REGISTRY: ghcr.io
+  IMAGE_NAME: zhangtianyao1/teamspeak-music-bot
+
+jobs:
+  build-and-push:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: write
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up QEMU
+        uses: docker/setup-qemu-action@v3
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Log in to GHCR
+        uses: docker/login-action@v3
+        with:
+          registry: ${{ env.REGISTRY }}
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Extract image metadata
+        id: meta
+        uses: docker/metadata-action@v5
+        with:
+          images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
+          tags: |
+            type=semver,pattern={{version}}
+            type=semver,pattern={{major}}.{{minor}}
+            type=semver,pattern={{major}}
+            type=raw,value=latest,enable=${{ startsWith(github.ref, 'refs/tags/v') }}
+            type=raw,value=${{ inputs.tag }},enable=${{ inputs.tag != '' }}
+
+      - name: Build and push
+        uses: docker/build-push-action@v6
+        with:
+          context: .
+          file: scripts/docker/Dockerfile
+          platforms: linux/amd64,linux/arm64
+          push: true
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
+          cache-from: type=gha
+          cache-to: type=gha,mode=max

.gitignore

@@ -6,5 +6,6 @@ dist/
 config.json
 cookies/
 .superpowers/
+.worktrees/
 /bin/
 scripts/navbar_bigger.png

README.md

@@ -254,9 +254,11 @@ sudo systemctl start tsmusicbot
 | `!vol <0-100>` | 设置音量 |
 | `!queue` | 查看播放队列 |
 | `!mode <seq\|loop\|random\|rloop>` | 切换播放模式 |
-| `!playlist <ID>` | 加载歌单 |
+| `!playlist <歌单名或ID>` | 加载歌单（支持名称模糊搜索和 ID） |
+| `!playlist -q <歌单名>` | 从 QQ 音乐搜索并加载歌单 |
 | `!album <ID>` | 加载专辑 |
-| `!fm` | 私人 FM（网易云） |
+| `!artist <歌手名>` | 按歌手循环播放（支持 `-q`/`-b`/`-y`） |
+| `!fm` | 私人 FM（网易云，自动续播） |
 | `!lyrics` | 显示当前歌词 |
 | `!now` | 当前播放信息 |
 | `!vote` | 投票跳过当前歌曲 |
@@ -485,6 +487,13 @@ A：`git pull` 拉取最新代码，然后 `npm install && npm run build && npm
 - **竞争条件防护**：generation 计数器防止快速切歌时旧头像覆盖新头像；UTF-8 字节长度截断中文昵称；文件传输操作带超时保护。
 - **TS3 适配**：描述通过 `clientedit`（非 `clientupdate`）设置，需要 `b_client_modify_description` 权限；昵称和 Away 通过合并的单条 `clientupdate` 避免命令队列超时。
 
+**新命令 & FM 修复**
+
+- **新增 `!artist <歌手名>` 命令**：搜索指定歌手的歌曲并循环播放，支持 `-q`（QQ 音乐）/ `-b`（B站）/ `-y`（YouTube）平台切换。一次加载最多 50 首，自动按歌手名过滤并设为 Loop 模式。
+- **歌单模糊搜索**：`!playlist` 现在支持歌单名称模糊搜索（如 `!playlist 华语经典`），自动匹配公开歌单 + 个人歌单（网易云 + QQ）。纯数字 ID 和 URL 解析保持兼容。
+- **修复 `!fm` 播放中断**：私人 FM 几首歌后静音的 bug 已修复。新增自动续播机制（队列低位自动拉取新歌），播放器健康帧追踪防止临时 URL 失败导致永久静音。
+- **QQ 音乐个人歌单**：QQ Music provider 新增 `getUserPlaylists` 支持，登录后可通过 `!playlist -q <名称>` 模糊搜索个人歌单。
+
 **协议层 & 稳定性**
 
 - **升级 `@honeybbq/teamspeak-client` 到 `0.2.1`**，移除内置 TS6 兼容层（`ts6-compat.ts`），改用库自带的通用 `clientinit` 协议（`3.?.? [Build: 5680278000]`），TS3/TS6 单一代码路径。

docs/superpowers/plans/2026-04-27-fm-artist-playlist.md

@@ -0,0 +1,517 @@
+# FM Bug Fix + Artist Loop + Playlist Fuzzy Search — Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Fix FM audio dropout bug, add `!artist` command for artist-based loop playback, and support playlist name fuzzy search in `!playlist`.
+
+**Architecture:** All changes stay within existing files. The FM fix adds auto-refill logic and a success-tracking mechanism in the player. Playlist search reuses the existing `provider.search()` API that already returns playlists. The `!artist` command is a new command method following the same pattern as `cmdPlay`/`cmdFm`.
+
+**Tech Stack:** TypeScript, Node.js, ffmpeg-static, @honeybbq/teamspeak-client
+
+---
+
+## File Map
+
+| File | Change | Purpose |
+|------|--------|---------|
+| `src/bot/instance.ts` | Modify | Add `isFmMode`, `refillFm()`, fix `cmdFm()`, modify `cmdPlaylist()`, add `cmdArtist()`, modify `playNext()` to trigger FM refill |
+| `src/bot/commands.ts` | Modify | Register `artist` in PUBLIC_COMMANDS, update help text |
+| `src/audio/player.ts` | Modify | Track healthy frame count, reset `consecutiveFailures` after sustained successful playback |
+
+---
+
+### Task 1: Fix FM — Track healthy playback in AudioPlayer
+
+**Files:**
+- Modify: `src/audio/player.ts:62-82` (add field)
+- Modify: `src/audio/player.ts:243-261` (sendNextFrame — track healthy frames)
+
+- [ ] **Step 1: Add healthy frame counter field**
+
+In `src/audio/player.ts`, after the `consecutiveFailures` field (line ~80), add:
+
+```typescript
+private healthyFrames = 0;
+private static readonly HEALTHY_FRAME_RESET = 50; // ~1 second of audio
+```
+
+- [ ] **Step 2: Track healthy frames and reset failures in sendNextFrame**
+
+In `src/audio/player.ts`, in the `sendNextFrame()` method, after line 257 (`this.framesPlayed++;`), add:
+
+```typescript
+this.healthyFrames++;
+if (this.healthyFrames >= AudioPlayer.HEALTHY_FRAME_RESET) {
+  this.consecutiveFailures = 0;
+  this.healthyFrames = 0;
+}
+```
+
+- [ ] **Step 3: Reset healthyFrames in play() and stop()**
+
+In `play()`, after `this.framesPlayed = 0;` (line ~95), add:
+
+```typescript
+this.healthyFrames = 0;
+```
+
+In `stop()`, after `this.framesPlayed = 0;` (line ~181), add:
+
+```typescript
+this.healthyFrames = 0;
+```
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add src/audio/player.ts
+git commit -m "fix(player): reset consecutiveFailures after sustained healthy playback"
+```
+
+---
+
+### Task 2: Fix FM — Add auto-refill logic in BotInstance
+
+**Files:**
+- Modify: `src/bot/instance.ts:62-66` (add fields)
+- Modify: `src/bot/instance.ts:557-573` (cmdFm)
+- Modify: `src/bot/instance.ts:642-673` (playNext — add refill trigger)
+
+- [ ] **Step 1: Add isFmMode field**
+
+In `src/bot/instance.ts`, after `private profileManager: BotProfileManager;` (line ~66), add:
+
+```typescript
+private isFmMode = false;
+```
+
+- [ ] **Step 2: Add refillFm method**
+
+In `src/bot/instance.ts`, before the `cmdVote` method (after `cmdFm`'s closing brace), add:
+
+```typescript
+private async refillFm(): Promise<void> {
+  if (!this.isFmMode || !this.neteaseProvider.getPersonalFm) return;
+  try {
+    const songs = await this.neteaseProvider.getPersonalFm();
+    if (songs.length === 0) return;
+    for (const song of songs) {
+      this.queue.add({ ...song, platform: "netease" });
+    }
+    this.logger.debug({ count: songs.length }, "FM queue refilled");
+  } catch (err) {
+    this.logger.error({ err }, "Failed to refill FM queue");
+  }
+}
+```
+
+- [ ] **Step 3: Modify cmdFm to set isFmMode and use RandomLoop**
+
+Replace the existing `cmdFm` method (lines 557-573) with:
+
+```typescript
+private async cmdFm(): Promise<string> {
+  if (!this.neteaseProvider.getPersonalFm) {
+    return "Personal FM is only available for NetEase Cloud Music";
+  }
+  const songs = await this.neteaseProvider.getPersonalFm();
+  if (songs.length === 0)
+    return "No FM songs available (need to login first)";
+
+  this.queue.clear();
+  for (const song of songs) {
+    this.queue.add({ ...song, platform: "netease" });
+  }
+  this.queue.setMode(PlayMode.RandomLoop);
+  this.isFmMode = true;
+  this.player.resetFailures();
+
+  const first = this.queue.play();
+  if (first) await this.resolveAndPlay(first);
+  this.emit("stateChange");
+  return `Personal FM started: ${first?.name ?? "unknown"} - ${first?.artist ?? ""}`;
+}
+```
+
+- [ ] **Step 4: Modify playNext to trigger FM refill and check isFmMode**
+
+In `playNext()`, replace the `else` branch (lines 665-668) that handles `queue.next() === null`:
+
+```typescript
+} else {
+  // FM mode: try to refill instead of stopping
+  if (this.isFmMode) {
+    await this.refillFm();
+    const refillNext = this.queue.next();
+    if (refillNext) {
+      const started = await this.resolveAndPlay(refillNext);
+      if (!started) {
+        this.player.stop();
+        this.profileManager.onSongChange(null).catch(() => {});
+      }
+      this.emit("stateChange");
+    } else {
+      this.player.stop();
+      this.profileManager.onSongChange(null).catch(() => {});
+    }
+  } else {
+    this.player.stop();
+    this.profileManager.onSongChange(null).catch(() => {});
+  }
+}
+```
+
+Also add a proactive refill after successful advance. At the end of the `if (next)` block, after `this.emit("stateChange");` is handled outside the if/else, add this right after `resolveAndPlay` succeeds (inside the `if (next)` block, after the retry loop):
+
+After the `if (!started)` block and before the closing `}` of `if (next)`, insert:
+
+```typescript
+// Proactive FM refill when running low
+if (this.isFmMode && this.queue.size() - (this.queue.getCurrentIndex()) <= 3) {
+  this.refillFm().catch(err => this.logger.error({ err }, "Proactive FM refill failed"));
+}
+```
+
+Wait — `this.emit("stateChange")` is outside the `if (next)` block. Let me re-read the original code structure...
+
+The original `playNext()` structure is:
+```
+if (next) {
+    let started = await resolveAndPlay(next)
+    if (!started) { retry loop... }
+    if (!started) { stop }
+} else {
+    stop
+}
+emit("stateChange")
+```
+
+So I need to add the proactive refill inside the `if (next)` block, right after `resolveAndPlay` succeeds. Let me write this more carefully:
+
+```typescript
+private async playNext(): Promise<void> {
+    if (this.isAdvancing || !this.connected) return;
+    this.isAdvancing = true;
+    try {
+      this.voteSkipUsers.clear();
+      const next = this.queue.next();
+      if (next) {
+        let started = await this.resolveAndPlay(next);
+        if (!started) {
+          for (let i = 0; i < 3 && this.connected; i++) {
+            const retry = this.queue.next();
+            if (!retry) break;
+            if (await this.resolveAndPlay(retry)) {
+              started = true;
+              break;
+            }
+          }
+        }
+        if (!started) {
+          this.player.stop();
+          this.profileManager.onSongChange(null).catch(() => {});
+        } else if (this.isFmMode && this.queue.size() - this.queue.getCurrentIndex() <= 3) {
+          // Proactive refill: when queue is running low, fetch more FM songs
+          this.refillFm().catch(err => this.logger.error({ err }, "Proactive FM refill failed"));
+        }
+      } else {
+        // Queue exhausted — in FM mode, refill instead of stopping
+        if (this.isFmMode) {
+          await this.refillFm();
+          const refillNext = this.queue.next();
+          if (refillNext) {
+            await this.resolveAndPlay(refillNext);
+          } else {
+            this.player.stop();
+            this.profileManager.onSongChange(null).catch(() => {});
+          }
+        } else {
+          this.player.stop();
+          this.profileManager.onSongChange(null).catch(() => {});
+        }
+      }
+      this.emit("stateChange");
+    } finally {
+      this.isAdvancing = false;
+    }
+  }
+```
+
+OK this is getting complex. Let me simplify the plan — I'll structure it more clearly.
+
+Also I need to clear `isFmMode` when user issues stop/clear or manually plays something else.
+
+- [ ] **Step 5: Clear isFmMode in stop/clear/play commands**
+
+In `cmdStop()`, after `this.queue.clear();`, add:
+
+```typescript
+this.isFmMode = false;
+```
+
+In `cmdClear()` (same line), add:
+
+```typescript
+this.isFmMode = false;
+```
+
+In `cmdPlay()`, after `this.queue.clear();`, add:
+
+```typescript
+this.isFmMode = false;
+```
+
+In `cmdPlaylist()`, after `this.queue.clear();`, add:
+
+```typescript
+this.isFmMode = false;
+```
+
+In `cmdAlbum()`, after `this.queue.clear();`, add:
+
+```typescript
+this.isFmMode = false;
+```
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add src/bot/instance.ts
+git commit -m "fix: FM auto-refill to prevent audio dropout after initial batch"
+```
+
+---
+
+### Task 3: Playlist Fuzzy Search
+
+**Files:**
+- Modify: `src/bot/instance.ts:524-539` (cmdPlaylist)
+
+- [ ] **Step 1: Modify cmdPlaylist to support name search**
+
+Replace the `cmdPlaylist` method (lines 524-539) with:
+
+```typescript
+private async cmdPlaylist(cmd: ParsedCommand): Promise<string> {
+  if (!cmd.args) return "Usage: !playlist <playlist name or ID>";
+  const provider = this.getProvider(cmd.flags);
+
+  // Determine if input is a numeric ID or a name search
+  const id = this.extractId(cmd.args);
+  const isNumericId = /^\d+$/.test(cmd.args.trim());
+
+  let playlistId: string;
+
+  if (isNumericId || id !== cmd.args) {
+    // Input is a numeric ID or URL containing an ID — use existing logic
+    playlistId = id;
+  } else {
+    // Name-based search
+    const result = await provider.search(cmd.args);
+    let playlists = result.playlists ?? [];
+
+    // Also search user's personal playlists if logged in
+    if (provider.getUserPlaylists) {
+      try {
+        const userPlaylists = await provider.getUserPlaylists();
+        const query = cmd.args.toLowerCase();
+        const matched = userPlaylists.filter(
+          p => p.name.toLowerCase().includes(query)
+        );
+        // Merge: public results first (API-ranked), then user matches
+        playlists = [...playlists, ...matched];
+      } catch {
+        // User playlists unavailable — continue with public results
+      }
+    }
+
+    if (playlists.length === 0)
+      return `No playlists found for: ${cmd.args}`;
+    playlistId = playlists[0].id;
+  }
+
+  const songs = await provider.getPlaylistSongs(playlistId);
+  if (songs.length === 0) return "Playlist is empty or not found";
+
+  this.queue.clear();
+  this.isFmMode = false;
+  for (const song of songs) {
+    this.queue.add({ ...song, platform: provider.platform });
+  }
+  const first = this.queue.play();
+  if (first) await this.resolveAndPlay(first);
+  this.emit("stateChange");
+  return `Loaded ${songs.length} songs. Now playing: ${first?.name ?? "unknown"}`;
+}
+```
+
+- [ ] **Step 2: Update help text to reflect new usage**
+
+In `cmdHelp()` (line ~633), change the playlist line from:
+
+```
+`${p}playlist <id> — Load playlist`
+```
+
+to:
+
+```
+`${p}playlist <name or id> — Load playlist by name or ID`
+```
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add src/bot/instance.ts
+git commit -m "feat: support playlist name fuzzy search in !playlist command"
+```
+
+---
+
+### Task 4: Artist Loop Command
+
+**Files:**
+- Modify: `src/bot/commands.ts:8-11` (PUBLIC_COMMANDS)
+- Modify: `src/bot/commands.ts:248-260` (AUDIO_COMMANDS in instance.ts — actually in instance.ts)
+- Modify: `src/bot/instance.ts:244-314` (executeCommand switch + add cmdArtist)
+
+Wait, AUDIO_COMMANDS is in instance.ts executeCommand. Let me check...
+
+Actually looking back at instance.ts, the AUDIO_COMMANDS set is local to executeCommand. I don't need to add artist there since it will be handled in the switch.
+
+- [ ] **Step 1: Register `artist` in PUBLIC_COMMANDS**
+
+In `src/bot/commands.ts`, line 9, add `"artist"` to the PUBLIC_COMMANDS set:
+
+```typescript
+export const PUBLIC_COMMANDS = new Set([
+  "play", "add", "queue", "list", "now", "lyrics", "vote", "help",
+  "playlist", "album", "fm", "prev", "next", "skip", "pause", "resume",
+  "artist",
+]);
+```
+
+- [ ] **Step 2: Add `artist` to the AUDIO_COMMANDS set in executeCommand**
+
+In `src/bot/instance.ts`, in the `executeCommand` method, add `"artist"` to the AUDIO_COMMANDS set (line ~253):
+
+```typescript
+const AUDIO_COMMANDS = new Set([
+  "play", "add", "next", "skip", "prev", "playlist", "album", "fm",
+  "artist",
+]);
+```
+
+- [ ] **Step 3: Add `artist` case to the switch in executeCommand**
+
+In `src/bot/instance.ts`, after the `case "fm":` block (line ~300), add:
+
+```typescript
+case "artist":
+  return this.cmdArtist(cmd);
+```
+
+- [ ] **Step 4: Implement cmdArtist method**
+
+Add the `cmdArtist` method in `src/bot/instance.ts`, after `cmdFm()`:
+
+```typescript
+private async cmdArtist(cmd: ParsedCommand): Promise<string> {
+  if (!cmd.args) return "Usage: !artist <artist name>";
+  const provider = this.getProvider(cmd.flags);
+  const result = await provider.search(cmd.args, 50);
+  if (result.songs.length === 0)
+    return `No results found for artist: ${cmd.args}`;
+
+  const query = cmd.args.toLowerCase();
+  let filtered = result.songs.filter(
+    s => s.artist.toLowerCase().includes(query)
+  );
+
+  // Fallback to unfiltered results if filtering drops everything
+  if (filtered.length === 0) {
+    filtered = result.songs.slice(0, 20);
+  }
+
+  this.queue.clear();
+  this.isFmMode = false;
+  for (const song of filtered) {
+    this.queue.add({ ...song, platform: provider.platform });
+  }
+  this.queue.setMode(PlayMode.Loop);
+  this.player.resetFailures();
+
+  const first = this.queue.play();
+  if (first) await this.resolveAndPlay(first);
+  this.emit("stateChange");
+  return `Artist mode: ${cmd.args} — ${filtered.length} songs loaded. Now playing: ${first?.name ?? "unknown"}`;
+}
+```
+
+- [ ] **Step 5: Update help text**
+
+In `cmdHelp()`, add the artist help line after the fm line:
+
+```
+`${p}artist <name> — Play songs by artist (loop)`
+```
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add src/bot/commands.ts src/bot/instance.ts
+git commit -m "feat: add !artist command for artist-based loop playback"
+```
+
+---
+
+### Task 5: Type-check and verify
+
+**Files:**
+- All modified files
+
+- [ ] **Step 1: Run type check**
+
+```bash
+cd /home/proxxy/project/teamspeak-music-bot && npm run typecheck
+```
+
+Expected: No errors.
+
+- [ ] **Step 2: Verify command parsing**
+
+```bash
+cd /home/proxxy/project/teamspeak-music-bot && node --loader ts-node/esm -e "
+const { parseCommand } = await import('./src/bot/commands.ts');
+console.log(parseCommand('!artist 周杰伦', '!'));
+console.log(parseCommand('!artist 周杰伦 -q', '!'));
+console.log(parseCommand('!playlist 华语经典', '!'));
+console.log(parseCommand('!playlist 123456', '!'));
+"
+```
+
+Expected: All parse correctly; `artist` with args "周杰伦", `playlist` with args "华语经典" and "123456".
+
+- [ ] **Step 3: Commit any fixes from type check**
+
+```bash
+git add -A && git commit -m "chore: type fixes from final verification"
+```
+(Only if there were issues)
+
+---
+
+### Self-Review Checklist
+
+1. **Spec coverage:**
+   - FM bug fix → Tasks 1, 2 (healthy frame tracking + auto-refill)
+   - Playlist fuzzy search → Task 3
+   - Artist loop → Task 4
+   - Verification → Task 5
+
+2. **No placeholders** — all steps have exact code.
+
+3. **Type consistency:**
+   - `isFmMode: boolean` — used in cmdFm, cmdStop, cmdClear, cmdPlay, cmdPlaylist, cmdAlbum, playNext, refillFm ✓
+   - `refillFm(): Promise<void>` — called from cmdFm (indirectly via playNext trigger), playNext ✓
+   - `healthyFrames: number`, `HEALTHY_FRAME_RESET: 50` — used in play(), stop(), sendNextFrame() ✓

docs/superpowers/plans/2026-05-06-music-source-tabs.md

@@ -0,0 +1,911 @@
+# Music Source Tabs Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Add NetEase / QQ source-switcher tabs to Home (推荐歌单 / 每日推荐 / 我的歌单) and Library (我的歌单), with per-section persistence and graceful degradation when only one source is logged in.
+
+**Architecture:** A single shared `<SourceTabs>` Vue component handles the tab UI and self-hides when fewer than 2 sources are available. The Pinia store splits the affected fields into `{ netease, qq }` objects, fetches from both platforms in `fetchHomeData()` based on `authStatus`, and consumers select with a reactive `activeSource` ref persisted to localStorage.
+
+**Tech Stack:** Vue 3 (Composition API + `<script setup>`), Pinia, TypeScript, SCSS (CSS variables from `web/src/styles/variables.scss`).
+
+**Spec:** `docs/superpowers/specs/2026-05-06-music-source-tabs-design.md`
+
+---
+
+## File Structure
+
+**New:**
+- `web/src/components/SourceTabs.vue` — shared tab UI (presentational, no store deps)
+
+**Modified:**
+- `web/src/stores/player.ts` — state shape change + `authStatus` + `fetchHomeData` rewrite
+- `web/src/views/Home.vue` — 3 sections wired to SourceTabs
+- `web/src/views/Library.vue` — 1 section wired; remove dead `liked` block
+
+**Unchanged:**
+- Backend (already supports `?platform=qq`)
+- All other web pages
+
+---
+
+## Task 1: Build the SourceTabs component
+
+**Files:**
+- Create: `web/src/components/SourceTabs.vue`
+
+This task is fully independent of store changes — the component is presentational, takes typed props, and emits an update event. It can land and be committed alone (build will pass; component is just unused until later tasks).
+
+- [ ] **Step 1.1: Create the component file**
+
+Write `web/src/components/SourceTabs.vue`:
+
+```vue
+<template>
+  <div v-if="sources.length >= 2" class="source-tabs">
+    <button
+      v-for="src in sources"
+      :key="src"
+      type="button"
+      class="source-tab"
+      :class="{ active: src === modelValue }"
+      @click="$emit('update:modelValue', src)"
+    >
+      {{ LABELS[src] }}
+    </button>
+  </div>
+</template>
+
+<script setup lang="ts">
+type Source = 'netease' | 'qq';
+
+const LABELS: Record<Source, string> = {
+  netease: '网易云',
+  qq: 'QQ',
+};
+
+defineProps<{
+  modelValue: Source;
+  sources: Source[];
+}>();
+
+defineEmits<{
+  'update:modelValue': [value: Source];
+}>();
+</script>
+
+<style lang="scss" scoped>
+.source-tabs {
+  display: inline-flex;
+  gap: 4px;
+  margin-left: 12px;
+  align-items: center;
+}
+
+.source-tab {
+  padding: 4px 10px;
+  min-height: 28px;
+  font-size: var(--fs-sm);
+  font-weight: var(--fw-medium);
+  color: var(--text-secondary);
+  background: transparent;
+  border: none;
+  border-radius: var(--radius-sm);
+  cursor: pointer;
+  transition: color var(--transition-fast), background var(--transition-fast);
+
+  &:hover {
+    color: var(--text-primary);
+    background: var(--hover-bg);
+  }
+
+  &.active {
+    color: var(--color-primary);
+    background: var(--color-primary-12);
+    font-weight: var(--fw-semi);
+  }
+}
+
+@media (max-width: 768px) {
+  .source-tabs {
+    margin-left: 8px;
+    gap: 2px;
+  }
+
+  .source-tab {
+    padding: 6px 10px;
+    min-height: 36px; // larger touch target on mobile
+    font-size: var(--fs-xs);
+  }
+}
+</style>
+```
+
+Why these choices:
+- `v-if="sources.length >= 2"` — auto-hide when only one source available; parent doesn't need wrapper logic
+- Min-height 28px desktop / 36px mobile — comfortable touch on phones
+- `--color-primary-12` (12% primary tint) — matches existing active-state pattern in the codebase
+- No `--brand-netease/qq` in active state — keeps tab visually consistent regardless of which platform; brand colors are reserved for SongCard platform badges where they identify content origin
+
+- [ ] **Step 1.2: Verify it imports cleanly via type check**
+
+Run from project root:
+
+```
+npx tsc --noEmit
+```
+
+Expected: exit code 0, no output.
+
+Then verify the web project also type-checks:
+
+```
+cd web && npx vue-tsc --noEmit && cd ..
+```
+
+Expected: exit code 0, no output.
+
+- [ ] **Step 1.3: Commit**
+
+```
+git add web/src/components/SourceTabs.vue
+git commit -m "feat(web): add SourceTabs component for platform switcher
+
+Presentational component for switching between netease and qq music
+sources. Auto-hides when fewer than 2 sources are passed in. Mobile
+breakpoint enlarges touch target to 36px.
+
+Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>"
+```
+
+---
+
+## Task 2: Refactor the store (state + fetchHomeData)
+
+**Files:**
+- Modify: `web/src/stores/player.ts`
+
+This task changes types, which will break Home.vue and Library.vue at compile time. **Do not run tsc/build between Task 2 and Task 4** — they are migrated in a single coherent commit. After Task 4, type-check confirms the whole change.
+
+- [ ] **Step 2.1: Add the `Source` type alias and update state shape**
+
+In `web/src/stores/player.ts`, locate the `state: () => ({ ... })` block (around line 47-63).
+
+**Find:**
+
+```ts
+    // Home page cache
+    recommendPlaylists: [] as PlaylistItem[],
+    dailySongs: [] as Song[],
+    userPlaylists: [] as PlaylistItem[],
+    bilibiliPopular: [] as Song[],
+    lastFetchTime: 0,
+```
+
+**Replace with:**
+
+```ts
+    // Home page cache, split by source
+    recommendPlaylists: { netease: [] as PlaylistItem[], qq: [] as PlaylistItem[] },
+    dailySongs:         { netease: [] as Song[],         qq: [] as Song[] },
+    userPlaylists:      { netease: [] as PlaylistItem[], qq: [] as PlaylistItem[] },
+    bilibiliPopular: [] as Song[],
+    authStatus: { netease: false, qq: false },
+    lastFetchTime: 0,
+```
+
+Also add this exported type at the top of the file, right after the existing `Song` interface (around line 12):
+
+```ts
+export type Source = 'netease' | 'qq';
+```
+
+- [ ] **Step 2.2: Rewrite `fetchHomeData()`**
+
+In the same file, find the `fetchHomeData` action (around line 352-378).
+
+**Replace the entire action body with:**
+
+```ts
+    async fetchHomeData() {
+      if (this.lastFetchTime > 0 && Date.now() - this.lastFetchTime < HOME_CACHE_TTL) {
+        return;
+      }
+
+      // 1. Fetch auth status for both platforms first.
+      const [neAuthRes, qqAuthRes] = await Promise.allSettled([
+        axios.get('/api/auth/status', { params: { platform: 'netease' } }),
+        axios.get('/api/auth/status', { params: { platform: 'qq' } }),
+      ]);
+      this.authStatus.netease =
+        neAuthRes.status === 'fulfilled' && !!neAuthRes.value.data?.loggedIn;
+      this.authStatus.qq =
+        qqAuthRes.status === 'fulfilled' && !!qqAuthRes.value.data?.loggedIn;
+
+      // 2. NetEase data: recommend playlists work anonymously; daily/user
+      // playlists need login but Promise.allSettled isolates failures.
+      const neteasePromises = [
+        axios.get('/api/music/recommend/playlists', { params: { platform: 'netease' } }),
+        axios.get('/api/music/recommend/songs',     { params: { platform: 'netease' } }),
+        axios.get('/api/music/user/playlists',      { params: { platform: 'netease' } }),
+      ];
+
+      // 3. QQ data: only fetch when QQ is logged in. When not logged in,
+      // resolve to empty payloads so the same indexed handling works.
+      const emptyPlaylists = { data: { playlists: [] } };
+      const emptySongs     = { data: { songs: [] } };
+      const qqPromises = this.authStatus.qq
+        ? [
+            axios.get('/api/music/recommend/playlists', { params: { platform: 'qq' } }),
+            axios.get('/api/music/recommend/songs',     { params: { platform: 'qq' } }),
+            axios.get('/api/music/user/playlists',      { params: { platform: 'qq' } }),
+          ]
+        : [
+            Promise.resolve(emptyPlaylists),
+            Promise.resolve(emptySongs),
+            Promise.resolve(emptyPlaylists),
+          ];
+
+      const biliPromise = axios.get('/api/music/bilibili/popular?limit=12');
+
+      const results = await Promise.allSettled([
+        ...neteasePromises,
+        ...qqPromises,
+        biliPromise,
+      ]);
+
+      const [neRecPL, neDaily, neUserPL, qqRecPL, qqDaily, qqUserPL, bili] = results;
+
+      if (neRecPL.status === 'fulfilled') {
+        this.recommendPlaylists.netease = neRecPL.value.data.playlists ?? [];
+      }
+      if (neDaily.status === 'fulfilled') {
+        this.dailySongs.netease = neDaily.value.data.songs ?? [];
+      }
+      if (neUserPL.status === 'fulfilled') {
+        this.userPlaylists.netease = neUserPL.value.data.playlists ?? [];
+      }
+      if (qqRecPL.status === 'fulfilled') {
+        this.recommendPlaylists.qq = qqRecPL.value.data.playlists ?? [];
+      }
+      if (qqDaily.status === 'fulfilled') {
+        this.dailySongs.qq = qqDaily.value.data.songs ?? [];
+      }
+      if (qqUserPL.status === 'fulfilled') {
+        this.userPlaylists.qq = qqUserPL.value.data.playlists ?? [];
+      }
+      if (bili.status === 'fulfilled') {
+        this.bilibiliPopular = bili.value.data.songs ?? [];
+      }
+
+      this.lastFetchTime = Date.now();
+    },
+```
+
+**Do NOT type-check yet** — Home/Library still reference the old shape. They'll be migrated in Tasks 3 and 4.
+
+---
+
+## Task 3: Migrate Home.vue to multi-source tabs
+
+**Files:**
+- Modify: `web/src/views/Home.vue`
+
+- [ ] **Step 3.1: Add a localStorage helper module**
+
+Create `web/src/stores/sourceTabs.ts`:
+
+```ts
+import type { Source } from './player.js';
+
+const STORAGE_KEY = 'source-tabs';
+
+export type TabKey =
+  | 'home.recommend'
+  | 'home.daily'
+  | 'home.user'
+  | 'library.user';
+
+function readAll(): Partial<Record<TabKey, Source>> {
+  try {
+    const raw = localStorage.getItem(STORAGE_KEY);
+    if (!raw) return {};
+    const parsed = JSON.parse(raw);
+    return typeof parsed === 'object' && parsed !== null ? parsed : {};
+  } catch {
+    return {};
+  }
+}
+
+export function loadTabSource(key: TabKey, fallback: Source = 'netease'): Source {
+  const all = readAll();
+  const v = all[key];
+  return v === 'netease' || v === 'qq' ? v : fallback;
+}
+
+export function saveTabSource(key: TabKey, value: Source): void {
+  try {
+    const all = readAll();
+    all[key] = value;
+    localStorage.setItem(STORAGE_KEY, JSON.stringify(all));
+  } catch {
+    // localStorage may be unavailable (private browsing); silently no-op
+  }
+}
+```
+
+This is a separate file rather than inline so Library can reuse it without duplication.
+
+- [ ] **Step 3.2: Update Home.vue template**
+
+Replace the three `<section>` blocks (推荐歌单 / 每日推荐 / 我的歌单) and the `<script setup>` block.
+
+**Find** the entire `<template>` 推荐歌单 section (currently around lines 53-67):
+
+```vue
+    <!-- 推荐歌单 -->
+    <section class="section" v-if="store.recommendPlaylists.length > 0">
+      <h2 class="section-title">推荐歌单</h2>
+      <div class="playlist-grid">
+        <RouterLink
+          v-for="playlist in store.recommendPlaylists"
+          :key="playlist.id"
+          :to="`/playlist/${playlist.id}?platform=${playlist.platform}`"
+          class="playlist-card hover-scale"
+        >
+          <CoverArt :url="playlist.coverUrl" :size="160" :radius="10" :show-shadow="true" />
+          <div class="playlist-name">{{ playlist.name }}</div>
+        </RouterLink>
+      </div>
+    </section>
+```
+
+**Replace with:**
+
+```vue
+    <!-- 推荐歌单 -->
+    <section class="section" v-if="recommendAvailable.length > 0">
+      <h2 class="section-title">
+        推荐歌单
+        <SourceTabs v-model="recommendSource" :sources="recommendAvailable" />
+      </h2>
+      <div class="playlist-grid">
+        <RouterLink
+          v-for="playlist in (store.recommendPlaylists[recommendSourceSafe] ?? [])"
+          :key="playlist.id"
+          :to="`/playlist/${playlist.id}?platform=${playlist.platform}`"
+          class="playlist-card hover-scale"
+        >
+          <CoverArt :url="playlist.coverUrl" :size="160" :radius="10" :show-shadow="true" />
+          <div class="playlist-name">{{ playlist.name }}</div>
+        </RouterLink>
+      </div>
+    </section>
+```
+
+**Find** the 每日推荐 section (currently around lines 36-51):
+
+```vue
+    <!-- 每日推荐 -->
+    <section class="section" v-if="store.dailySongs.length > 0">
+      <h2 class="section-title">每日推荐</h2>
+      <div class="daily-grid">
+        <div
+          v-for="song in store.dailySongs.slice(0, 12)"
+          :key="song.id"
+          class="daily-card hover-scale"
+          @click="store.playSong(song)"
+        >
+          <CoverArt :url="song.coverUrl" :size="120" :radius="10" :show-shadow="true" />
+          <div class="daily-name">{{ song.name }}</div>
+          <div class="daily-artist">{{ song.artist }}</div>
+        </div>
+      </div>
+    </section>
+```
+
+**Replace with:**
+
+```vue
+    <!-- 每日推荐 -->
+    <section class="section" v-if="dailyAvailable.length > 0">
+      <h2 class="section-title">
+        每日推荐
+        <SourceTabs v-model="dailySource" :sources="dailyAvailable" />
+      </h2>
+      <div class="daily-grid">
+        <div
+          v-for="song in (store.dailySongs[dailySourceSafe] ?? []).slice(0, 12)"
+          :key="song.id"
+          class="daily-card hover-scale"
+          @click="store.playSong(song)"
+        >
+          <CoverArt :url="song.coverUrl" :size="120" :radius="10" :show-shadow="true" />
+          <div class="daily-name">{{ song.name }}</div>
+          <div class="daily-artist">{{ song.artist }}</div>
+        </div>
+      </div>
+    </section>
+```
+
+**Find** the 我的歌单 section (currently around lines 69-95):
+
+```vue
+    <!-- 我的歌单 -->
+    <section class="section" v-if="store.userPlaylists.length > 0">
+      <h2 class="section-title">
+        我的歌单
+        <span class="section-count">{{ store.userPlaylists.length }}</span>
+      </h2>
+      <div class="playlist-grid">
+        <RouterLink
+          v-for="pl in visibleUserPlaylists"
+          :key="pl.id"
+          :to="`/playlist/${pl.id}?platform=${pl.platform}`"
+          class="playlist-card hover-scale"
+        >
+          <CoverArt :url="pl.coverUrl" :size="160" :radius="10" :show-shadow="true" />
+          <div class="playlist-name">{{ pl.name }}</div>
+          <div class="playlist-count">{{ pl.songCount }} 首</div>
+        </RouterLink>
+      </div>
+      <button
+        v-if="store.userPlaylists.length > USER_PLAYLIST_LIMIT"
+        class="expand-btn"
+        @click="userPlaylistsExpanded = !userPlaylistsExpanded"
+      >
+        <Icon :icon="userPlaylistsExpanded ? 'mdi:chevron-up' : 'mdi:chevron-down'" />
+        {{ userPlaylistsExpanded ? '收起' : `展开全部 ${store.userPlaylists.length} 个歌单` }}
+      </button>
+    </section>
+```
+
+**Replace with:**
+
+```vue
+    <!-- 我的歌单 -->
+    <section class="section" v-if="userAvailable.length > 0">
+      <h2 class="section-title">
+        我的歌单
+        <span class="section-count">{{ currentUserPlaylists.length }}</span>
+        <SourceTabs v-model="userSource" :sources="userAvailable" />
+      </h2>
+      <div class="playlist-grid">
+        <RouterLink
+          v-for="pl in visibleUserPlaylists"
+          :key="pl.id"
+          :to="`/playlist/${pl.id}?platform=${pl.platform}`"
+          class="playlist-card hover-scale"
+        >
+          <CoverArt :url="pl.coverUrl" :size="160" :radius="10" :show-shadow="true" />
+          <div class="playlist-name">{{ pl.name }}</div>
+          <div class="playlist-count">{{ pl.songCount }} 首</div>
+        </RouterLink>
+      </div>
+      <button
+        v-if="currentUserPlaylists.length > USER_PLAYLIST_LIMIT"
+        class="expand-btn"
+        @click="userPlaylistsExpanded = !userPlaylistsExpanded"
+      >
+        <Icon :icon="userPlaylistsExpanded ? 'mdi:chevron-up' : 'mdi:chevron-down'" />
+        {{ userPlaylistsExpanded ? '收起' : `展开全部 ${currentUserPlaylists.length} 个歌单` }}
+      </button>
+    </section>
+```
+
+- [ ] **Step 3.3: Update Home.vue `<script setup>`**
+
+**Find** the `<script setup lang="ts">` block (currently around lines 119-153):
+
+```ts
+<script setup lang="ts">
+import { ref, computed, onMounted } from 'vue';
+import { Icon } from '@iconify/vue';
+import axios from 'axios';
+import { usePlayerStore, type Song } from '../stores/player.js';
+import CoverArt from '../components/CoverArt.vue';
+
+const store = usePlayerStore();
+const USER_PLAYLIST_LIMIT = 20;
+const userPlaylistsExpanded = ref(false);
+const visibleUserPlaylists = computed(() =>
+  userPlaylistsExpanded.value
+    ? store.userPlaylists
+    : store.userPlaylists.slice(0, USER_PLAYLIST_LIMIT)
+);
+
+async function playFm() {
+  try {
+    const res = await axios.get('/api/music/personal/fm');
+    const songs: Song[] = res.data.songs;
+    if (songs.length > 0) {
+      await store.play(songs[0].name, songs[0].platform);
+      for (let i = 1; i < songs.length; i++) {
+        await store.addToQueue(songs[i].name, songs[i].platform);
+      }
+    }
+  } catch {
+    // Ignore
+  }
+}
+
+onMounted(() => {
+  store.fetchHomeData();
+});
+</script>
+```
+
+**Replace with:**
+
+```ts
+<script setup lang="ts">
+import { ref, computed, watch, onMounted } from 'vue';
+import { Icon } from '@iconify/vue';
+import axios from 'axios';
+import { usePlayerStore, type Song, type Source } from '../stores/player.js';
+import { loadTabSource, saveTabSource } from '../stores/sourceTabs.js';
+import CoverArt from '../components/CoverArt.vue';
+import SourceTabs from '../components/SourceTabs.vue';
+
+const store = usePlayerStore();
+const USER_PLAYLIST_LIMIT = 20;
+const userPlaylistsExpanded = ref(false);
+
+// Available sources per section. Recommend playlists are public for both
+// platforms — netease always; qq only when logged in. Daily and user
+// playlists need login on both sides.
+const recommendAvailable = computed<Source[]>(() => {
+  const s: Source[] = ['netease'];
+  if (store.authStatus.qq) s.push('qq');
+  return s;
+});
+const dailyAvailable = computed<Source[]>(() => {
+  const s: Source[] = [];
+  if (store.authStatus.netease) s.push('netease');
+  if (store.authStatus.qq) s.push('qq');
+  return s;
+});
+const userAvailable = computed<Source[]>(() => {
+  const s: Source[] = [];
+  if (store.authStatus.netease) s.push('netease');
+  if (store.authStatus.qq) s.push('qq');
+  return s;
+});
+
+// Persisted active source per section.
+const recommendSource = ref<Source>(loadTabSource('home.recommend'));
+const dailySource     = ref<Source>(loadTabSource('home.daily'));
+const userSource      = ref<Source>(loadTabSource('home.user'));
+
+watch(recommendSource, (v) => saveTabSource('home.recommend', v));
+watch(dailySource,     (v) => saveTabSource('home.daily',     v));
+watch(userSource,      (v) => saveTabSource('home.user',      v));
+
+// Fallback when persisted source is no longer available (e.g. user logged
+// out of QQ since last visit). We render against `*Safe` but never write
+// back, so the user's preference is preserved for when they log in again.
+const recommendSourceSafe = computed<Source>(() =>
+  recommendAvailable.value.includes(recommendSource.value)
+    ? recommendSource.value
+    : recommendAvailable.value[0] ?? 'netease'
+);
+const dailySourceSafe = computed<Source>(() =>
+  dailyAvailable.value.includes(dailySource.value)
+    ? dailySource.value
+    : dailyAvailable.value[0] ?? 'netease'
+);
+const userSourceSafe = computed<Source>(() =>
+  userAvailable.value.includes(userSource.value)
+    ? userSource.value
+    : userAvailable.value[0] ?? 'netease'
+);
+
+const currentUserPlaylists = computed(() => store.userPlaylists[userSourceSafe.value] ?? []);
+const visibleUserPlaylists = computed(() =>
+  userPlaylistsExpanded.value
+    ? currentUserPlaylists.value
+    : currentUserPlaylists.value.slice(0, USER_PLAYLIST_LIMIT)
+);
+
+async function playFm() {
+  try {
+    const res = await axios.get('/api/music/personal/fm');
+    const songs: Song[] = res.data.songs;
+    if (songs.length > 0) {
+      await store.play(songs[0].name, songs[0].platform);
+      for (let i = 1; i < songs.length; i++) {
+        await store.addToQueue(songs[i].name, songs[i].platform);
+      }
+    }
+  } catch {
+    // Ignore
+  }
+}
+
+onMounted(() => {
+  store.fetchHomeData();
+});
+</script>
+```
+
+Note: The 我的歌单 template uses `userSource` (not `userSourceSafe`) on the `<SourceTabs>` v-model so the user's click maps directly to the persisted ref. The grid below the tabs uses `currentUserPlaylists` which derives from `userSourceSafe`, so even if `userSource` points at an unavailable platform momentarily, the grid still renders something sensible. Same pattern for 推荐歌单 / 每日推荐.
+
+---
+
+## Task 4: Migrate Library.vue and remove dead code
+
+**Files:**
+- Modify: `web/src/views/Library.vue`
+
+- [ ] **Step 4.1: Replace the template**
+
+**Find** the `<template>` block (currently lines 1-64) and **replace the entire template with:**
+
+```vue
+<template>
+  <div class="library-page">
+    <h1 class="page-title">音乐库</h1>
+
+    <!-- 我的歌单 -->
+    <section class="section" v-if="userAvailable.length > 0">
+      <h2 class="section-title">
+        我的歌单
+        <span class="section-count">{{ currentUserPlaylists.length }}</span>
+        <SourceTabs v-model="userSource" :sources="userAvailable" />
+      </h2>
+      <div class="playlist-grid">
+        <RouterLink
+          v-for="pl in currentUserPlaylists"
+          :key="pl.id"
+          :to="`/playlist/${pl.id}?platform=${pl.platform}`"
+          class="playlist-card hover-scale"
+        >
+          <CoverArt :url="pl.coverUrl" :size="160" :radius="10" :show-shadow="true" />
+          <div class="playlist-name">{{ pl.name }}</div>
+          <div class="playlist-count">{{ pl.songCount }} 首</div>
+        </RouterLink>
+      </div>
+    </section>
+
+    <!-- 最近播放 -->
+    <section class="section">
+      <h2 class="section-title">最近播放</h2>
+      <div v-if="historyLoading" class="loading">加载中...</div>
+      <div v-else-if="history.length === 0" class="empty">暂无播放记录</div>
+      <div v-else class="song-list">
+        <SongCard
+          v-for="(song, i) in history.slice(0, 10)"
+          :key="`hist-${song.id}-${i}`"
+          :song="song"
+          :index="i + 1"
+          :active="store.currentSong?.id === song.id"
+          @play="store.play(song.name, song.platform)"
+          @add="store.addToQueue(song.name, song.platform)"
+        />
+      </div>
+    </section>
+
+    <div v-if="!historyLoading && userAvailable.length === 0 && history.length === 0" class="empty-state">
+      <Icon icon="mdi:music-box-outline" class="empty-icon" />
+      <div>登录网易云或QQ音乐后，这里将显示你的歌单和播放记录</div>
+    </div>
+  </div>
+</template>
+```
+
+Changes from the previous version:
+- "我的歌单" section: same data binding pattern as Home (`userAvailable`, `currentUserPlaylists`, `<SourceTabs>`)
+- "我的收藏" section: removed entirely (the `/api/music/user/liked` endpoint never existed)
+- Empty state condition: replaced `liked.length === 0` with `userAvailable.length === 0`
+
+- [ ] **Step 4.2: Replace the script block**
+
+**Find** the `<script setup lang="ts">` block (currently lines 66-105) and **replace with:**
+
+```ts
+<script setup lang="ts">
+import { ref, computed, watch, onMounted } from 'vue';
+import { Icon } from '@iconify/vue';
+import axios from 'axios';
+import { usePlayerStore, type Song, type Source } from '../stores/player.js';
+import { loadTabSource, saveTabSource } from '../stores/sourceTabs.js';
+import CoverArt from '../components/CoverArt.vue';
+import SongCard from '../components/SongCard.vue';
+import SourceTabs from '../components/SourceTabs.vue';
+
+const store = usePlayerStore();
+
+const history = ref<Song[]>([]);
+const historyLoading = ref(true);
+
+const userAvailable = computed<Source[]>(() => {
+  const s: Source[] = [];
+  if (store.authStatus.netease) s.push('netease');
+  if (store.authStatus.qq) s.push('qq');
+  return s;
+});
+
+const userSource = ref<Source>(loadTabSource('library.user'));
+watch(userSource, (v) => saveTabSource('library.user', v));
+
+const userSourceSafe = computed<Source>(() =>
+  userAvailable.value.includes(userSource.value)
+    ? userSource.value
+    : userAvailable.value[0] ?? 'netease'
+);
+
+const currentUserPlaylists = computed(() => store.userPlaylists[userSourceSafe.value] ?? []);
+
+onMounted(async () => {
+  if (!store.activeBotId) {
+    await store.fetchBots();
+  }
+
+  store.fetchHomeData();
+
+  if (store.activeBotId) {
+    try {
+      const res = await axios.get(`/api/player/${store.activeBotId}/history`);
+      history.value = res.data.history ?? [];
+    } catch {
+      // API may not be ready
+    }
+  }
+
+  historyLoading.value = false;
+});
+</script>
+```
+
+Changes:
+- Removed `liked` ref and the `/api/music/user/liked` axios call
+- Added auth-driven `userAvailable`, persisted `userSource`, and `currentUserPlaylists` computed
+- Imports `Source` type and `SourceTabs` component
+
+- [ ] **Step 4.3: Style — `.section-title` already supports inline children**
+
+The existing `.section-title` style (Library.vue and Home.vue both) already uses `display: flex; align-items: center; gap: 8px;`. SourceTabs uses `display: inline-flex` with its own `margin-left`, so it sits inline with the title and count. **No style changes are required in either Home.vue or Library.vue.**
+
+---
+
+## Task 5: Verify the build and types
+
+- [ ] **Step 5.1: Run TypeScript backend type check**
+
+```
+npx tsc --noEmit
+```
+
+Expected: exit code 0, no output. (No backend files were touched.)
+
+- [ ] **Step 5.2: Run web type check + production build**
+
+```
+npm run build:web
+```
+
+Expected: build completes with `✓ built in N.NNs` and no TypeScript errors. The script runs `vue-tsc --noEmit && vite build`, so failures here mean a type or template error in our changes.
+
+- [ ] **Step 5.3: Run the existing test suite to confirm no regression**
+
+```
+npm test
+```
+
+Expected: same baseline as before this feature (`Test Files 2 failed | 26 passed (28)`, `Tests 2 failed | 161 passed (163)`). The 2 pre-existing failures are in `dist/` and `.claude/worktrees/` and are unrelated to our changes — they should remain at exactly 2.
+
+If any **source-tree** test fails (anything not in `dist/` or `.claude/worktrees/`), stop and investigate.
+
+---
+
+## Task 6: Manual smoke test on the dev server
+
+This task verifies behavior the type system can't catch.
+
+- [ ] **Step 6.1: Start the dev server**
+
+```
+npm run dev
+```
+
+Wait for `Web server started` and `WebUI: http://localhost:3000` log lines.
+
+- [ ] **Step 6.2: Test scenario A — only NetEase logged in**
+
+Open http://localhost:3000 in a browser. Confirm:
+
+- 推荐歌单 section displays NetEase playlists, **no tab bar visible** (single source, SourceTabs auto-hidden)
+- 每日推荐 section: visible only if NetEase login provides daily songs; **no tab bar**
+- 我的歌单 section: visible if NetEase has user playlists; **no tab bar**
+- Navigate to `/library`: 我的歌单 section: same — no tab bar, NetEase playlists shown
+
+Open DevTools → Application → Local Storage → `localhost:3000` → `source-tabs` should be absent or `{}` (no clicks happened).
+
+- [ ] **Step 6.3: Test scenario B — both NetEase and QQ logged in**
+
+If QQ is not logged in, log in via Settings → QQ Music → 扫码登录.
+
+Hard reload the browser (Cmd/Ctrl+Shift+R) to bypass the 5-min `lastFetchTime` cache.
+
+Confirm:
+
+- 推荐歌单: tab bar shows `[网易云] [QQ]`, NetEase active by default
+- Click `QQ` — playlist grid switches to QQ data, no flicker (data already in store)
+- Click `网易云` — back to NetEase
+- Same for 每日推荐 and 我的歌单
+- Navigate to `/library`, confirm 我的歌单 has its own tab bar with independent state
+- Reload the page — Home tabs and Library tab persist their last-selected source independently
+
+Check `localStorage['source-tabs']`: should contain JSON with up to 4 keys (`home.recommend`, `home.daily`, `home.user`, `library.user`).
+
+- [ ] **Step 6.4: Test scenario C — fallback when persisted source becomes unavailable**
+
+While logged into both:
+1. On Home, switch 推荐歌单 to `QQ`. Confirm `localStorage['source-tabs']['home.recommend'] === 'qq'`.
+2. Go to Settings → log out of QQ.
+3. Hard-reload Home.
+
+Confirm:
+- 推荐歌单 tab bar disappears (only NetEase available)
+- Grid shows NetEase playlists (graceful fallback via `recommendSourceSafe`)
+- `localStorage['source-tabs']['home.recommend']` is **still `'qq'`** (preference preserved)
+4. Log back into QQ → reload → 推荐歌单 grid is QQ again (preference restored)
+
+- [ ] **Step 6.5: Test mobile layout**
+
+Open DevTools → Toggle device toolbar → set width to 375px (iPhone SE).
+
+Confirm on Home and Library:
+- Section title + tab bar fit on the same line without overflow
+- Tab buttons are at least 36px tall (use Inspect → check computed `min-height`)
+- Tabs are tappable (clicking still switches sources)
+
+- [ ] **Step 6.6: Stop the dev server**
+
+Kill the `npm run dev` process.
+
+---
+
+## Task 7: Final commit
+
+- [ ] **Step 7.1: Stage and commit Task 2 + 3 + 4 changes**
+
+```
+git add web/src/stores/player.ts web/src/stores/sourceTabs.ts web/src/views/Home.vue web/src/views/Library.vue
+git status
+```
+
+Expected `git status` output: 4 modified/new files staged, working tree otherwise clean (apart from pre-existing `.claude/worktrees/` and `test-ts6-version.cjs` untracked).
+
+```
+git commit -m "feat(web): per-platform source tabs on Home and Library
+
+Recommend playlists, daily songs, and user playlists on Home now show
+a [网易云][QQ] tab when both platforms are logged in. Library 我的歌单
+gets the same tab. Selection persists per-section in localStorage and
+falls back gracefully when the persisted source becomes unavailable
+(e.g., user logged out). Removes dead 我的收藏 block from Library that
+referenced a non-existent /api/music/user/liked endpoint.
+
+Spec: docs/superpowers/specs/2026-05-06-music-source-tabs-design.md
+
+Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>"
+```
+
+- [ ] **Step 7.2: Verify commit landed**
+
+```
+git log --oneline -3
+```
+
+Expected:
+```
+<sha> feat(web): per-platform source tabs on Home and Library
+<sha> feat(web): add SourceTabs component for platform switcher
+<sha> docs: spec for multi-source tabs on Home and Library
+```
+
+---
+
+## Done
+
+The branch should now have 3 new commits on top of the merge commit, all green builds and tests, and the feature working in dev mode.

docs/superpowers/plans/2026-05-07-album-search-and-playback.md

@@ -0,0 +1,520 @@
+# Album Search & Playback Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Surface albums in search results and allow playing the whole album from the web UI. Currently `SearchResult.albums` is always `[]` and Search.vue only renders songs.
+
+**Architecture:** Extend `search()` in netease + qq providers to populate `albums`. Aggregate them in `/search/all`. Add a new "专辑" (and "歌单") section to Search.vue. Reuse `Playlist.vue` as the album detail page by branching on `route.meta.kind` between `/playlist/:id` and `/album/:id` endpoints. The existing `getAlbumSongs(id)` and `/api/music/album/:id` endpoint already work.
+
+**Tech Stack:** Node 20 + TS, Express 5, Vue 3 + Vue Router 4, axios. No new deps.
+
+---
+
+## Spec Reference
+
+`docs/superpowers/specs/2026-05-07-custom-avatar-and-album-search-design.md` — section "专辑搜索".
+
+## File Structure
+
+| File | Action | Responsibility |
+|---|---|---|
+| `src/music/provider.ts` | Read-only | Verify `Album` and `SearchResult.albums` shape (no change expected) |
+| `src/music/netease.ts` | Modify | `search()` adds a third parallel call (`type=10`) and maps albums |
+| `src/music/qq.ts` | Modify | `search()` adds `req_album` section and maps albums |
+| `src/music/netease.test.ts` | Modify | New tests for albums in search response |
+| `src/music/qq.test.ts` | Modify (or create if absent) | Tests for albums in qq search |
+| `src/web/api/music.ts` | Modify | `/search/all` returns `{songs, albums, playlists}` |
+| `web/src/views/Search.vue` | Modify | Render albums + playlists sections |
+| `web/src/views/Playlist.vue` | Modify | Branch endpoint by `route.meta.kind === 'album'` |
+| `web/src/router/index.ts` | Modify | Add `/album/:id` route reusing Playlist component, set `meta.kind = 'album'` |
+
+## Conventions
+
+- TDD throughout. Each task: failing test → implement → verify → commit.
+- Mock HTTP via existing fixtures pattern (look at `src/music/netease.test.ts` for setup).
+- Keep all platform-specific quirks inside the provider class — no leaking into Search.vue logic.
+
+---
+
+### Task 1: netease.ts — fetch albums in search
+
+**Files:**
+- Modify: `src/music/netease.ts`
+- Modify: `src/music/netease.test.ts`
+
+- [ ] **Step 1: Read the existing test setup so we mock the same way**
+
+```bash
+grep -n 'cloudsearch\|MockAdapter\|axios.create\|mock\|nock\|fixture' src/music/netease.test.ts | head -20
+```
+
+- [ ] **Step 2: Write the failing test**
+
+Append to `src/music/netease.test.ts` inside the existing `describe`:
+
+```ts
+  it("populates SearchResult.albums from cloudsearch type=10", async () => {
+    // Adjust the fixture/mock helper to your existing test pattern.
+    // The test should: arrange a mock that returns a non-empty albums array
+    // for type=10, run search(), assert result.albums has the expected shape.
+    mockApi.onGet("/cloudsearch", { params: expect.objectContaining({ type: 10 }) }).reply(200, {
+      result: {
+        albums: [
+          { id: 42, name: "Album A", picUrl: "https://x/p.jpg", artists: [{ name: "Artist X" }] },
+        ],
+      },
+    });
+    mockApi.onGet("/cloudsearch", { params: expect.objectContaining({ type: 1 }) }).reply(200, { result: { songs: [] } });
+    mockApi.onGet("/cloudsearch", { params: expect.objectContaining({ type: 1000 }) }).reply(200, { result: { playlists: [] } });
+
+    const provider = makeProvider();
+    const r = await provider.search("foo", 5);
+    expect(r.albums).toEqual([
+      { id: "42", name: "Album A", artist: "Artist X", coverUrl: "https://x/p.jpg", platform: "netease" },
+    ]);
+  });
+```
+
+If the existing tests use a different mock library (e.g. `msw` or manual axios stubbing), translate the fixture above to match. Do not introduce new test deps.
+
+- [ ] **Step 3: Run test to verify it fails**
+
+Run: `npx vitest run src/music/netease.test.ts`
+Expected: FAIL — `result.albums` is `[]`
+
+- [ ] **Step 4: Implement the change**
+
+In `src/music/netease.ts` `search()` (~line 93), change the `Promise.all` from 2 to 3 calls:
+
+```ts
+const [songRes, playlistRes, albumRes] = await Promise.all([
+  this.api.get("/cloudsearch", { params: { keywords: query, type: 1, limit, ...this.cookieParams } }),
+  this.api.get("/cloudsearch", { params: { keywords: query, type: 1000, limit: 5, ...this.cookieParams } }),
+  this.api.get("/cloudsearch", { params: { keywords: query, type: 10, limit: 5, ...this.cookieParams } }),
+]);
+```
+
+After the existing `playlists: Playlist[] = ...` mapping, add:
+
+```ts
+const albums: Album[] = (albumRes.data?.result?.albums ?? []).map((a: any) => ({
+  id: String(a.id),
+  name: a.name ?? "",
+  artist: (a.artists ?? []).map((x: any) => x.name).join(" / "),
+  coverUrl: a.picUrl ?? "",
+  platform: "netease",
+}));
+```
+
+Update the `return { songs, playlists, albums: [] }` to `return { songs, playlists, albums }`.
+
+(Make sure `Album` is imported from `./provider.js`; if not yet imported, add it to the existing import.)
+
+- [ ] **Step 5: Run test to verify it passes**
+
+Run: `npx vitest run src/music/netease.test.ts`
+Expected: PASS
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add src/music/netease.ts src/music/netease.test.ts
+git commit -m "feat(netease): include albums in search results"
+```
+
+---
+
+### Task 2: qq.ts — fetch albums in search
+
+**Files:**
+- Modify: `src/music/qq.ts`
+- Modify or Create: `src/music/qq.test.ts`
+
+- [ ] **Step 1: Verify whether qq.test.ts exists**
+
+```bash
+ls src/music/qq.test.ts
+```
+
+If absent, create a minimal one mirroring `netease.test.ts` style: instantiate provider, mock the `qqDirectApi` axios instance, assert `r.albums.length > 0` after a `search()` call.
+
+- [ ] **Step 2: Write the failing test**
+
+Add to `src/music/qq.test.ts`:
+
+```ts
+it("populates SearchResult.albums from a parallel album search request", async () => {
+  // Mock returns an album list under req_album.data.body.album.list
+  mockApi.onGet("/cgi-bin/musicu.fcg").reply((cfg) => {
+    const data = JSON.parse(cfg.params?.data ?? "{}");
+    if (data.req_album) {
+      return [200, { req_album: { data: { body: { album: { list: [
+        { albumMID: "abc", albumName: "Aero", singerName: "S", albumPic: "https://x/p.jpg" },
+      ] } } } } }];
+    }
+    if (data.req_0) {
+      return [200, { req_0: { data: { body: { song: { list: [] } } } } }];
+    }
+    return [200, {}];
+  });
+
+  const provider = makeProvider();
+  const r = await provider.search("foo", 5);
+  expect(r.albums).toEqual([
+    { id: "abc", name: "Aero", artist: "S", coverUrl: expect.stringContaining("https://"), platform: "qq" },
+  ]);
+});
+```
+
+Verify the actual QQ API response shape against a real call before finalizing the field names — `albumMID` vs `mid`, `albumPic` vs `pic`, etc. If unsure, log a real response once and freeze the shape in the fixture.
+
+- [ ] **Step 3: Run test to verify it fails**
+
+Run: `npx vitest run src/music/qq.test.ts`
+Expected: FAIL — `r.albums` is `[]`
+
+- [ ] **Step 4: Implement the change**
+
+In `src/music/qq.ts` `search()` (~line 63), change `reqData` to include both `req_0` (songs) and `req_album` (albums):
+
+```ts
+const reqData = JSON.stringify({
+  req_0: {
+    module: "music.search.SearchCgiService",
+    method: "DoSearchForQQMusicDesktop",
+    param: { searchid: "1", query, num_per_page: Math.min(limit, 50), search_type: 0 },
+  },
+  req_album: {
+    module: "music.search.SearchCgiService",
+    method: "DoSearchForQQMusicDesktop",
+    param: { searchid: "1", query, num_per_page: 5, search_type: 8 },
+  },
+});
+```
+
+After the existing `songs` mapping, add:
+
+```ts
+const albumList: any[] = res.data?.req_album?.data?.body?.album?.list ?? [];
+const albums: Album[] = albumList.map((a: any) => ({
+  id: String(a.albumMID ?? a.mid ?? a.albumID ?? ""),
+  name: a.albumName ?? a.title ?? "",
+  artist: a.singerName ?? (a.singer ?? []).map((s: any) => s.name).join(" / "),
+  coverUrl: a.albumMID
+    ? `https://y.gtimg.cn/music/photo_new/T002R300x300M000${a.albumMID}.jpg`
+    : (a.albumPic ?? ""),
+  platform: "qq",
+}));
+```
+
+Change `return { songs, playlists: [], albums: [] }` to `return { songs, playlists: [], albums }`.
+
+- [ ] **Step 5: Run test to verify it passes**
+
+Run: `npx vitest run src/music/qq.test.ts`
+Expected: PASS
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add src/music/qq.ts src/music/qq.test.ts
+git commit -m "feat(qq): include albums in search results"
+```
+
+---
+
+### Task 3: /search/all — aggregate albums + playlists
+
+**Files:**
+- Modify: `src/web/api/music.ts`
+
+- [ ] **Step 1: Look at the current aggregation**
+
+In `src/web/api/music.ts` near line 40 the `/search/all` handler builds only `songs`. Extend it.
+
+- [ ] **Step 2: Write a failing integration test (if test infra allows)**
+
+If there's already a test file for music.ts, add a test that mocks the providers and asserts `res.body.albums.length > 0`. If not, skip and rely on Task 1+2 unit coverage + manual verification in Task 4.
+
+- [ ] **Step 3: Aggregate albums + playlists**
+
+Replace the existing `songs = ...` block + `res.json({ songs })` at lines ~54–62 with:
+
+```ts
+const songs = [
+  ...(neteaseResult.status === "fulfilled" ? neteaseResult.value.songs : []),
+  ...(qqResult.status === "fulfilled" ? qqResult.value.songs : []),
+  ...(bilibiliResult.status === "fulfilled" ? bilibiliResult.value.songs : []),
+];
+const albums = [
+  ...(neteaseResult.status === "fulfilled" ? neteaseResult.value.albums : []),
+  ...(qqResult.status === "fulfilled" ? qqResult.value.albums : []),
+];
+const playlists = [
+  ...(neteaseResult.status === "fulfilled" ? neteaseResult.value.playlists : []),
+  ...(qqResult.status === "fulfilled" ? qqResult.value.playlists : []),
+];
+
+res.json({ songs, albums, playlists });
+```
+
+(Bilibili intentionally skipped for albums/playlists — no album concept; playlists likewise minor.)
+
+- [ ] **Step 4: Verify by curl**
+
+Build + run, then:
+
+```bash
+curl -s 'http://localhost:3000/api/music/search/all?q=Beyond' \
+  | python3 -c 'import json,sys;d=json.load(sys.stdin);print({k: len(v) for k, v in d.items()})'
+```
+
+Expected: `{'songs': N>0, 'albums': N>0, 'playlists': N>=0}`
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add src/web/api/music.ts
+git commit -m "feat(api): /search/all returns albums and playlists"
+```
+
+---
+
+### Task 4: Album route reusing Playlist.vue
+
+**Files:**
+- Modify: `web/src/router/index.ts`
+- Modify: `web/src/views/Playlist.vue`
+
+- [ ] **Step 1: Look at the current router config and Playlist load logic**
+
+```bash
+grep -n "path:\|component:\|meta" web/src/router/index.ts
+grep -n "loadPlaylist\|/api/music/playlist\|onMounted" web/src/views/Playlist.vue
+```
+
+- [ ] **Step 2: Add /album/:id route**
+
+In `web/src/router/index.ts`, find the `/playlist/:id` route entry. Right after it, add:
+
+```ts
+  {
+    path: '/album/:id',
+    component: () => import('../views/Playlist.vue'),
+    meta: { kind: 'album' },
+  },
+```
+
+(If `/playlist/:id` is `meta:`-less, also add `meta: { kind: 'playlist' }` to it for symmetry.)
+
+- [ ] **Step 3: Branch the endpoint inside Playlist.vue**
+
+Find the load function (probably `onMounted(async () => { axios.get('/api/music/playlist/' + id, ...) })`). Refactor:
+
+```ts
+const route = useRoute();
+const kind = (route.meta.kind as string) ?? 'playlist'; // 'playlist' | 'album'
+const endpoint = kind === 'album' ? '/api/music/album/' : '/api/music/playlist/';
+// ... use `${endpoint}${route.params.id}` ...
+```
+
+For the hero metadata, the playlist endpoint returns `{songs}` only (no top-level cover/title) — verify what the Album endpoint currently returns. If both only return `{songs}`, the existing Playlist.vue must already derive the cover from somewhere (probably the first song's coverUrl, or an additional `/api/music/playlist/:id/detail` call). Keep the existing pattern; if a separate detail call is needed for albums, fetch the metadata from `/api/music/song/<firstSong.id>` to get the album name + cover, OR add a thin `/api/music/album/:id/detail` endpoint that returns `{ name, coverUrl, description }`.
+
+**Decision:** if Playlist.vue currently uses ONLY `/api/music/playlist/:id` and derives metadata from songs, do the same for albums (no new endpoint). If it calls a separate detail endpoint, add a matching `/api/music/album/:id/detail` returning `{ name, coverUrl }` from the first song's `album` and `coverUrl` fields.
+
+- [ ] **Step 4: Verify in browser**
+
+Run `cd web && npm run dev`. Visit `/album/<some-netease-album-id>` (pick one from a search). Expect: hero header + song list + play-all button — same UX as a playlist page.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add web/src/router/index.ts web/src/views/Playlist.vue
+git commit -m "feat(web): /album/:id route reusing Playlist view"
+```
+
+---
+
+### Task 5: Search.vue — render albums + playlists sections
+
+**Files:**
+- Modify: `web/src/views/Search.vue`
+
+- [ ] **Step 1: Read current Search.vue**
+
+```bash
+sed -n '1,120p' web/src/views/Search.vue
+```
+
+Identify: the `results.value = res.data.songs` line and the `<div v-else-if="results.length > 0">` block.
+
+- [ ] **Step 2: Refactor to three result lists**
+
+Replace the script:
+
+```ts
+import type { Song } from '../stores/player.js';
+
+interface Album { id: string; name: string; artist: string; coverUrl: string; platform: string; }
+interface Playlist { id: string; name: string; coverUrl: string; songCount?: number; platform: string; }
+
+const songs = ref<Song[]>([]);
+const albums = ref<Album[]>([]);
+const playlists = ref<Playlist[]>([]);
+const loading = ref(false);
+const searched = ref(false);
+
+async function doSearch() {
+  if (!query.value.trim()) return;
+  loading.value = true;
+  searched.value = true;
+  try {
+    const res = await axios.get('/api/music/search/all', { params: { q: query.value } });
+    songs.value = res.data.songs ?? [];
+    albums.value = res.data.albums ?? [];
+    playlists.value = res.data.playlists ?? [];
+  } catch {
+    songs.value = []; albums.value = []; playlists.value = [];
+  } finally {
+    loading.value = false;
+  }
+}
+```
+
+- [ ] **Step 3: Render the sections**
+
+Replace the existing `<div v-else-if="results.length > 0" class="results">` block:
+
+```vue
+    <template v-else-if="songs.length || albums.length || playlists.length">
+      <section v-if="albums.length" class="result-section">
+        <h2 class="section-title">专辑</h2>
+        <div class="card-grid">
+          <router-link
+            v-for="al in albums"
+            :key="`${al.platform}-${al.id}`"
+            :to="`/album/${al.id}?platform=${al.platform}`"
+            class="card hover-scale"
+          >
+            <CoverArt :url="al.coverUrl" :size="160" :radius="10" :show-shadow="true" />
+            <div class="card-name">{{ al.name }}</div>
+            <div class="card-sub">{{ al.artist }}</div>
+          </router-link>
+        </div>
+      </section>
+
+      <section v-if="playlists.length" class="result-section">
+        <h2 class="section-title">歌单</h2>
+        <div class="card-grid">
+          <router-link
+            v-for="pl in playlists"
+            :key="`${pl.platform}-${pl.id}`"
+            :to="`/playlist/${pl.id}?platform=${pl.platform}`"
+            class="card hover-scale"
+          >
+            <CoverArt :url="pl.coverUrl" :size="160" :radius="10" :show-shadow="true" />
+            <div class="card-name">{{ pl.name }}</div>
+          </router-link>
+        </div>
+      </section>
+
+      <section v-if="songs.length" class="result-section">
+        <h2 class="section-title">单曲</h2>
+        <SongCard
+          v-for="(song, i) in songs"
+          :key="`${song.platform}-${song.id}`"
+          :song="song"
+          :index="i + 1"
+          :active="store.currentSong?.id === song.id"
+          @play="store.playSong(song)"
+          @playNext="store.playNextSong(song)"
+          @add="store.addSong(song)"
+        />
+      </section>
+    </template>
+
+    <div v-else-if="searched" class="empty">未找到相关结果</div>
+```
+
+(Import `CoverArt`: `import CoverArt from '../components/CoverArt.vue';`.)
+
+- [ ] **Step 4: Add minimal styles**
+
+Append to the `<style lang="scss" scoped>` block:
+
+```scss
+.result-section {
+  margin-bottom: 32px;
+  .section-title { font-size: 18px; margin: 0 0 12px; opacity: 0.85; }
+}
+.card-grid {
+  display: grid;
+  grid-template-columns: repeat(auto-fill, minmax(140px, 1fr));
+  gap: 16px;
+}
+.card {
+  display: flex;
+  flex-direction: column;
+  gap: 6px;
+  text-decoration: none;
+  color: inherit;
+  .card-name { font-size: 14px; line-height: 1.3; max-height: 2.6em; overflow: hidden; }
+  .card-sub  { font-size: 12px; opacity: 0.6; }
+}
+```
+
+- [ ] **Step 5: Build + visually verify**
+
+```bash
+cd web && npm run build
+```
+
+Then `npm run dev` → search "周杰伦" → see three sections; click an album card → arrives at `/album/:id` with songs + play-all.
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add web/src/views/Search.vue
+git commit -m "feat(web): show album + playlist sections in search"
+```
+
+---
+
+### Task 6: Open PR
+
+- [ ] **Step 1: Push branch**
+
+```bash
+git checkout -b feat/album-search
+git push -u origin feat/album-search
+```
+
+- [ ] **Step 2: Create the PR**
+
+```bash
+gh pr create --title "feat(search): album section + album playback" --body "Closes part of #51 (album half).
+
+## Summary
+- netease.search() / qq.search() now populate SearchResult.albums
+- /api/music/search/all returns albums + playlists alongside songs
+- Search.vue renders three sections: 专辑 / 歌单 / 单曲
+- /album/:id route reuses Playlist.vue with meta.kind='album'
+- bilibili / youtube intentionally still return albums:[] (no album API)
+
+## Test plan
+- [x] vitest covers netease + qq search returning non-empty albums
+- [x] curl /search/all?q=周杰伦 returns {songs, albums, playlists}
+- [x] Manual: search → click album card → /album/:id → play all
+
+🤖 Generated with [Claude Code](https://claude.com/claude-code)"
+```
+
+---
+
+## Self-Review Checklist
+
+- [x] Spec coverage: backend album search → Tasks 1+2; aggregator → Task 3; album detail route → Task 4; UI sections → Task 5
+- [x] No "TBD"/placeholder text — every step shows the actual diff or command
+- [x] Type names consistent: `Album` (capital A), `albums` (lowercase plural), `SearchResult.albums`
+- [x] Bilibili/YouTube explicitly out of scope per spec — confirmed in Task 3 by skipping them in albums aggregation
+- [x] Routes use `meta.kind` — same key referenced in Playlist.vue (Task 4) and `/album/:id` registration (Task 4 Step 2)

docs/superpowers/plans/2026-05-07-custom-bot-avatar.md

@@ -0,0 +1,903 @@
+# Custom Bot Avatar Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Let users upload a fixed avatar per bot. When `avatarEnabled=true`, the avatar follows the song cover during playback and reverts to the custom avatar (instead of clearing) on stop. When `avatarEnabled=false` and a custom avatar exists, the bot always shows the custom avatar.
+
+**Architecture:** New SQLite column stores a relative file path; bytes live on disk under `data/avatars/<botId>.<ext>` (mirrors `data/cookies/`). `BotProfileManager` gains a `customAvatar` Buffer; the existing `clearAvatar()` becomes "restore custom or clear"; `onConnect()` immediately applies the custom avatar when sync is off. Three new REST endpoints (GET/PUT/DELETE) under `/api/bot/:id/avatar` accept base64 JSON (avoids adding multer; bump `express.json()` limit).
+
+**Tech Stack:** Node 20 + TS + Express 5, better-sqlite3, Vue 3 + axios. No new runtime deps.
+
+---
+
+## Spec Reference
+
+`docs/superpowers/specs/2026-05-07-custom-avatar-and-album-search-design.md` — section "自定义头像".
+
+## File Structure
+
+| File | Action | Responsibility |
+|---|---|---|
+| `src/data/database.ts` | Modify | Add `custom_avatar_path` column + migration + accessor methods |
+| `src/data/avatars.ts` | **Create** | Read/write/delete avatar files under `data/avatars/` |
+| `src/bot/profile.ts` | Modify | `customAvatar` field, `setCustomAvatar`, `applyIdleAvatar`, modify `clearAvatar`, modify `onConnect` |
+| `src/bot/instance.ts` | Modify | Load custom avatar on start, pass to ProfileManager |
+| `src/web/api/bot.ts` | Modify | Add GET/PUT/DELETE `/avatar` endpoints |
+| `src/web/server.ts` | Modify | Bump `express.json()` limit to `400kb` |
+| `src/index.ts` | Modify | Pass `AVATAR_DIR` to bot manager / API router |
+| `src/data/database.test.ts` | Modify | Test custom avatar path persistence + migration idempotency |
+| `src/data/avatars.test.ts` | **Create** | Unit tests for avatar store |
+| `src/bot/profile.test.ts` | **Create** | Tests for new precedence logic with a mock TS3Client |
+| `web/src/components/AvatarUpload.vue` | **Create** | Reusable avatar picker + preview + delete |
+| `web/src/views/Settings.vue` | Modify | Add custom avatar row in profile features list; insert into create-bot and edit-bot forms |
+
+## Conventions
+
+- TDD: failing test → implement → verify → commit, every step.
+- Commits use conventional format: `feat(profile):`, `feat(api):`, `feat(web):`, `test(...)`. Each task ends with one commit.
+- Tests live in vitest (`npm test`).
+- All paths absolute or relative to repo root.
+
+---
+
+### Task 1: DB migration + getter/setter for custom avatar path
+
+**Files:**
+- Modify: `src/data/database.ts`
+- Modify: `src/data/database.test.ts`
+
+- [ ] **Step 1: Write the failing test**
+
+Add to `src/data/database.test.ts` after the existing tests (find the closing `});` of the last test case in the `describe` block, insert before it):
+
+```ts
+  it("persists and clears customAvatarPath on a bot instance", () => {
+    const inst = {
+      id: "bot-1",
+      name: "B",
+      serverAddress: "x",
+      serverPort: 9987,
+      nickname: "n",
+      defaultChannel: "",
+      channelPassword: "",
+      autoStart: false,
+      serverProtocol: "",
+      ts6ApiKey: "",
+      serverPassword: "",
+    };
+    botDb.saveBotInstance(inst);
+    expect(botDb.getCustomAvatarPath("bot-1")).toBeNull();
+    botDb.setCustomAvatarPath("bot-1", "avatars/bot-1.png");
+    expect(botDb.getCustomAvatarPath("bot-1")).toBe("avatars/bot-1.png");
+    botDb.setCustomAvatarPath("bot-1", null);
+    expect(botDb.getCustomAvatarPath("bot-1")).toBeNull();
+  });
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `npx vitest run src/data/database.test.ts`
+Expected: FAIL — `botDb.getCustomAvatarPath is not a function`
+
+- [ ] **Step 3: Add the column to migration + interface + statements**
+
+In `src/data/database.ts`:
+
+1. Find `BotDatabase` interface (~line 54), add two methods before `close()`:
+
+```ts
+  getCustomAvatarPath(botId: string): string | null;
+  setCustomAvatarPath(botId: string, path: string | null): void;
+```
+
+2. Find `migrateSchema()` (~line 66). After the `for (const col of profileCols)` loop, append:
+
+```ts
+  if (!names.includes("custom_avatar_path")) {
+    db.exec("ALTER TABLE bot_instances ADD COLUMN custom_avatar_path TEXT");
+  }
+```
+
+3. In `createDatabase()` after the existing `prepare(...)` calls (~line 180), add:
+
+```ts
+  const selectCustomAvatar = db.prepare(
+    `SELECT custom_avatar_path FROM bot_instances WHERE id = ?`,
+  );
+  const updateCustomAvatar = db.prepare(
+    `UPDATE bot_instances SET custom_avatar_path = ? WHERE id = ?`,
+  );
+```
+
+4. Inside the returned object, add (before `close()`):
+
+```ts
+    getCustomAvatarPath(botId) {
+      const row = selectCustomAvatar.get(botId) as { custom_avatar_path: string | null } | undefined;
+      return row?.custom_avatar_path ?? null;
+    },
+
+    setCustomAvatarPath(botId, path) {
+      updateCustomAvatar.run(path, botId);
+    },
+```
+
+- [ ] **Step 4: Run test to verify it passes**
+
+Run: `npx vitest run src/data/database.test.ts`
+Expected: PASS — all tests including the new one
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add src/data/database.ts src/data/database.test.ts
+git commit -m "feat(db): custom_avatar_path column + accessors"
+```
+
+---
+
+### Task 2: Avatar storage helper
+
+**Files:**
+- Create: `src/data/avatars.ts`
+- Create: `src/data/avatars.test.ts`
+
+- [ ] **Step 1: Write the failing test**
+
+Create `src/data/avatars.test.ts`:
+
+```ts
+import { describe, it, expect, beforeEach } from "vitest";
+import { mkdtempSync, rmSync, existsSync, readFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { createAvatarStore } from "./avatars.js";
+
+let dir: string;
+
+beforeEach(() => {
+  dir = mkdtempSync(join(tmpdir(), "avatar-test-"));
+});
+
+describe("createAvatarStore", () => {
+  it("write returns a relative path under the store dir", () => {
+    const store = createAvatarStore(dir);
+    const buf = Buffer.from("fake-png");
+    const rel = store.write("bot-1", "image/png", buf);
+    expect(rel).toBe("bot-1.png");
+    expect(readFileSync(join(dir, "bot-1.png")).equals(buf)).toBe(true);
+  });
+
+  it("write picks correct extension for jpeg / webp", () => {
+    const store = createAvatarStore(dir);
+    expect(store.write("a", "image/jpeg", Buffer.from(""))).toBe("a.jpg");
+    expect(store.write("b", "image/webp", Buffer.from(""))).toBe("b.webp");
+  });
+
+  it("write rejects unsupported MIME types", () => {
+    const store = createAvatarStore(dir);
+    expect(() => store.write("c", "image/gif", Buffer.from(""))).toThrow(
+      /unsupported/i,
+    );
+  });
+
+  it("read returns the bytes for an existing file", () => {
+    const store = createAvatarStore(dir);
+    store.write("bot-1", "image/png", Buffer.from("hello"));
+    const buf = store.read("bot-1.png");
+    expect(buf?.equals(Buffer.from("hello"))).toBe(true);
+  });
+
+  it("read returns null when path is missing", () => {
+    const store = createAvatarStore(dir);
+    expect(store.read("missing.png")).toBeNull();
+  });
+
+  it("remove deletes the file (idempotent)", () => {
+    const store = createAvatarStore(dir);
+    store.write("bot-1", "image/png", Buffer.from("x"));
+    store.remove("bot-1.png");
+    expect(existsSync(join(dir, "bot-1.png"))).toBe(false);
+    expect(() => store.remove("bot-1.png")).not.toThrow();
+  });
+
+  it("write replaces any existing file for the same botId regardless of old extension", () => {
+    const store = createAvatarStore(dir);
+    store.write("bot-1", "image/png", Buffer.from("old"));
+    const rel = store.write("bot-1", "image/jpeg", Buffer.from("new"));
+    expect(rel).toBe("bot-1.jpg");
+    expect(existsSync(join(dir, "bot-1.png"))).toBe(false);
+    expect(existsSync(join(dir, "bot-1.jpg"))).toBe(true);
+  });
+});
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `npx vitest run src/data/avatars.test.ts`
+Expected: FAIL — module not found
+
+- [ ] **Step 3: Implement the store**
+
+Create `src/data/avatars.ts`:
+
+```ts
+import { mkdirSync, writeFileSync, readFileSync, rmSync, readdirSync, existsSync } from "node:fs";
+import { join } from "node:path";
+
+const MIME_TO_EXT: Record<string, string> = {
+  "image/png": "png",
+  "image/jpeg": "jpg",
+  "image/webp": "webp",
+};
+
+export interface AvatarStore {
+  /** Returns the relative path written (e.g. "bot-1.png"). */
+  write(botId: string, mime: string, buffer: Buffer): string;
+  read(relPath: string): Buffer | null;
+  remove(relPath: string): void;
+  getDir(): string;
+}
+
+export function createAvatarStore(dir: string): AvatarStore {
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+  return {
+    write(botId, mime, buffer) {
+      const ext = MIME_TO_EXT[mime];
+      if (!ext) throw new Error(`unsupported avatar MIME: ${mime}`);
+      // Remove any existing avatar for this bot regardless of extension.
+      for (const name of readdirSync(dir)) {
+        if (name.startsWith(`${botId}.`)) rmSync(join(dir, name), { force: true });
+      }
+      const rel = `${botId}.${ext}`;
+      writeFileSync(join(dir, rel), buffer);
+      return rel;
+    },
+    read(relPath) {
+      const full = join(dir, relPath);
+      if (!existsSync(full)) return null;
+      return readFileSync(full);
+    },
+    remove(relPath) {
+      rmSync(join(dir, relPath), { force: true });
+    },
+    getDir() {
+      return dir;
+    },
+  };
+}
+```
+
+- [ ] **Step 4: Run test to verify it passes**
+
+Run: `npx vitest run src/data/avatars.test.ts`
+Expected: PASS — all 7 tests
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add src/data/avatars.ts src/data/avatars.test.ts
+git commit -m "feat(data): avatar file store helper"
+```
+
+---
+
+### Task 3: BotProfileManager — custom avatar precedence
+
+**Files:**
+- Modify: `src/bot/profile.ts`
+- Create: `src/bot/profile.test.ts`
+
+- [ ] **Step 1: Write the failing test**
+
+Create `src/bot/profile.test.ts`:
+
+```ts
+import { describe, it, expect, beforeEach, vi } from "vitest";
+import { BotProfileManager } from "./profile.js";
+import type { TS3Client } from "../ts-protocol/client.js";
+
+function makeMockTs(): TS3Client & {
+  uploadCalls: Buffer[];
+  clearCalls: number;
+} {
+  const calls: Buffer[] = [];
+  let clears = 0;
+  const ts: any = {
+    uploadCalls: calls,
+    get clearCalls() { return clears; },
+    getHost: () => "127.0.0.1",
+    getHttpQuery: () => null,
+    fileTransferInitUpload: vi.fn().mockResolvedValue({}),
+    uploadFileData: vi.fn().mockImplementation(async (_h, _i, stream: any) => {
+      const chunks: Buffer[] = [];
+      for await (const c of stream) chunks.push(c as Buffer);
+      calls.push(Buffer.concat(chunks));
+    }),
+    fileTransferDeleteFile: vi.fn().mockResolvedValue(undefined),
+    sendCommandNoWait: vi.fn().mockImplementation(async (cmd: string) => {
+      if (/client_flag_avatar=$/.test(cmd)) clears++;
+    }),
+  };
+  return ts;
+}
+
+const noopLogger: any = { child: () => noopLogger, info: () => {}, debug: () => {}, warn: () => {}, error: () => {} };
+
+const cfgOn = { avatarEnabled: true, descriptionEnabled: false, nicknameEnabled: false, awayStatusEnabled: false, channelDescEnabled: false, nowPlayingMsgEnabled: false };
+const cfgOff = { ...cfgOn, avatarEnabled: false };
+
+describe("BotProfileManager custom avatar precedence", () => {
+  let ts: ReturnType<typeof makeMockTs>;
+  beforeEach(() => { ts = makeMockTs(); });
+
+  it("on stop with custom avatar set + sync on, uploads custom (does not clear)", async () => {
+    const pm = new BotProfileManager(ts as any, noopLogger, cfgOn, "Bot");
+    const custom = Buffer.from([1, 2, 3, 4]);
+    pm.setCustomAvatar(custom);
+    await pm.onSongChange(null);
+    expect(ts.uploadCalls.at(-1)?.equals(custom)).toBe(true);
+    expect(ts.clearCalls).toBe(0);
+  });
+
+  it("on stop with no custom avatar, falls back to clear", async () => {
+    const pm = new BotProfileManager(ts as any, noopLogger, cfgOn, "Bot");
+    await pm.onSongChange(null);
+    expect(ts.clearCalls).toBe(1);
+    expect(ts.uploadCalls.length).toBe(0);
+  });
+
+  it("on connect with sync off + custom avatar set, applies custom immediately", async () => {
+    const pm = new BotProfileManager(ts as any, noopLogger, cfgOff, "Bot");
+    pm.setCustomAvatar(Buffer.from([9, 9]));
+    await pm.onConnect();
+    expect(ts.uploadCalls.length).toBe(1);
+    expect(ts.uploadCalls[0].equals(Buffer.from([9, 9]))).toBe(true);
+  });
+
+  it("on connect with sync off + no custom avatar, does not touch avatar", async () => {
+    const pm = new BotProfileManager(ts as any, noopLogger, cfgOff, "Bot");
+    await pm.onConnect();
+    expect(ts.uploadCalls.length).toBe(0);
+    expect(ts.clearCalls).toBe(0);
+  });
+
+  it("setCustomAvatar(null) makes subsequent onSongChange(null) clear again", async () => {
+    const pm = new BotProfileManager(ts as any, noopLogger, cfgOn, "Bot");
+    pm.setCustomAvatar(Buffer.from([1]));
+    pm.setCustomAvatar(null);
+    await pm.onSongChange(null);
+    expect(ts.clearCalls).toBe(1);
+  });
+});
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `npx vitest run src/bot/profile.test.ts`
+Expected: FAIL — `pm.setCustomAvatar is not a function` and/or `onConnect` not exported
+
+- [ ] **Step 3: Look at the existing profile.ts to understand `onConnect` shape**
+
+Run: `grep -n 'onConnect\|public async\|public ' src/bot/profile.ts | head -10`
+
+`onConnect` likely already exists; if not, locate where reconnect resets state. Add or extend it.
+
+- [ ] **Step 4: Implement `customAvatar`, `setCustomAvatar`, `applyIdleAvatar`; modify `clearAvatar` and `onConnect`**
+
+In `src/bot/profile.ts`:
+
+1. Inside the class, add fields next to `defaultNickname` (around line 27):
+
+```ts
+  private customAvatar: Buffer | null = null;
+```
+
+2. After the `constructor`, add:
+
+```ts
+  /** Set/clear the persistent idle avatar. Pass null to remove. */
+  setCustomAvatar(buffer: Buffer | null): void {
+    this.customAvatar = buffer;
+  }
+```
+
+3. Find `clearAvatar()` (~line 173). Change the body so that if `this.customAvatar` is set, we upload it instead of clearing the flag. Replace the existing method with:
+
+```ts
+  private async clearAvatar(gen: number): Promise<void> {
+    if (this.customAvatar && this.customAvatar.length > 0) {
+      await this.applyIdleAvatar(gen);
+      return;
+    }
+    try {
+      await this.withTimeout(
+        this.tsClient.fileTransferDeleteFile(0n, ["/avatar"]),
+        FILE_TRANSFER_TIMEOUT_MS,
+      );
+    } catch {
+      // File may not exist or transfer timed out — that's fine
+    }
+    if (this.generation !== gen) return;
+    try {
+      await this.tsClient.sendCommandNoWait("clientupdate client_flag_avatar=");
+    } catch (err) {
+      this.handleFeatureError("avatar", err);
+    }
+  }
+```
+
+4. Add a new private method right below `clearAvatar`:
+
+```ts
+  private async applyIdleAvatar(gen: number): Promise<void> {
+    if (!this.customAvatar || this.customAvatar.length === 0) return;
+    if (this.permDenied.avatar) return;
+    try {
+      await this.withTimeout(this.doAvatarUpload(this.customAvatar), FILE_TRANSFER_TIMEOUT_MS);
+      if (this.generation !== gen) return;
+      this.logger.info({ bytes: this.customAvatar.length }, "Idle (custom) avatar applied");
+    } catch (err) {
+      this.handleFeatureError("avatar", err);
+    }
+  }
+```
+
+5. Find `onConnect` (the existing method that resets per-feature flags). At its end, immediately after the `permDenied` reset, add:
+
+```ts
+    if (!this.config.avatarEnabled && this.customAvatar) {
+      const gen = ++this.generation;
+      void this.applyIdleAvatar(gen);
+    }
+```
+
+If `onConnect` does not exist as a method, search for where reconnect resets `permDenied` and add the block there.
+
+- [ ] **Step 5: Run test to verify it passes**
+
+Run: `npx vitest run src/bot/profile.test.ts`
+Expected: PASS — 5/5
+
+Run also: `npx vitest run src/audio src/data src/bot` — confirm no regressions.
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add src/bot/profile.ts src/bot/profile.test.ts
+git commit -m "feat(profile): custom avatar with idle/playback precedence"
+```
+
+---
+
+### Task 4: Wire avatar load on bot start
+
+**Files:**
+- Modify: `src/bot/instance.ts`
+- Modify: `src/bot/manager.ts` (if it constructs the instance)
+- Modify: `src/index.ts`
+
+- [ ] **Step 1: Confirm where `BotProfileManager` is constructed and how `BotInstance` receives DB**
+
+Run: `grep -n 'new BotProfileManager\|profileManager =\|database\|botDb' src/bot/instance.ts src/bot/manager.ts | head -20`
+
+Identify the BotInstance constructor params and verify that the DB and the avatar dir can flow in.
+
+- [ ] **Step 2: Add `AVATAR_DIR` constant + `avatarStore` to `src/index.ts`**
+
+Find where `COOKIE_DIR` / `createCookieStore` are set up (~line 48 in src/index.ts) and add directly after:
+
+```ts
+const AVATAR_DIR = process.env.AVATAR_DIR ?? join(DATA_DIR, "avatars");
+const avatarStore = createAvatarStore(AVATAR_DIR);
+```
+
+(import as needed: `import { createAvatarStore } from "./data/avatars.js";`)
+
+Pass `avatarStore` through to whatever constructs `BotManager` (and from there to `BotInstance`).
+
+- [ ] **Step 3: In `BotInstance`, after `profileManager` is created, load the avatar from disk if any**
+
+In `src/bot/instance.ts`, after `this.profileManager = new BotProfileManager(...)`:
+
+```ts
+const relPath = this.botDb.getCustomAvatarPath(this.id);
+if (relPath) {
+  const buf = this.avatarStore.read(relPath);
+  if (buf) this.profileManager.setCustomAvatar(buf);
+}
+```
+
+(Add `private botDb: BotDatabase` and `private avatarStore: AvatarStore` constructor params; thread them down from `BotManager.createBot()` / `BotManager` constructor.)
+
+- [ ] **Step 4: Add `getProfileManager()` accessor if not present**
+
+If grep already shows `getProfileManager(): BotProfileManager`, skip. Otherwise add a public method that returns `this.profileManager`.
+
+- [ ] **Step 5: Build and run the existing tests**
+
+Run: `npx tsc --noEmit`
+Expected: no TS errors
+
+Run: `npm test`
+Expected: all green
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add src/index.ts src/bot/instance.ts src/bot/manager.ts
+git commit -m "feat(bot): load custom avatar on instance startup"
+```
+
+---
+
+### Task 5: REST endpoints for avatar upload / fetch / delete
+
+**Files:**
+- Modify: `src/web/server.ts` (json size limit)
+- Modify: `src/web/api/bot.ts`
+
+- [ ] **Step 1: Bump express.json size limit**
+
+In `src/web/server.ts`, find `app.use(express.json())` (~line 46) and change to:
+
+```ts
+app.use(express.json({ limit: "400kb" }));
+```
+
+(Avatar payload is base64-encoded ≤200 KB → ~270 KB on the wire; 400 KB gives margin.)
+
+- [ ] **Step 2: Write a failing API test (use supertest if not present, otherwise inline fetch)**
+
+Run: `grep -E '"supertest"|"vitest"' package.json`
+
+If supertest is not present, write the test using `node:http` raw client or skip API integration test and rely on manual + unit tests on Task 7. Don't add new deps unless approved.
+
+If supertest IS present, add `src/web/api/bot.test.ts`:
+
+```ts
+import { describe, it, expect } from "vitest";
+import request from "supertest";
+import express from "express";
+import { createBotRouter } from "./bot.js";
+// ... build minimal app with mocked manager + DB + avatarStore
+```
+
+If not present: skip Step 2, jump to Step 3 and verify by manual curl in Step 5.
+
+- [ ] **Step 3: Add the three endpoints**
+
+In `src/web/api/bot.ts`, modify the factory signature to accept `avatarStore` and `botDb`:
+
+```ts
+export function createBotRouter(
+  botManager: BotManager,
+  config: BotConfig,
+  configPath: string,
+  logger: Logger,
+  botDb: BotDatabase,
+  avatarStore: AvatarStore,
+): Router {
+```
+
+Inside the router, after the existing `/:id/config` GET, add:
+
+```ts
+  router.get("/:id/avatar", (req, res) => {
+    const path = botDb.getCustomAvatarPath(req.params.id);
+    if (!path) { res.status(404).end(); return; }
+    const buf = avatarStore.read(path);
+    if (!buf) { res.status(404).end(); return; }
+    const ext = path.split(".").pop()!;
+    const mime = ext === "png" ? "image/png" : ext === "webp" ? "image/webp" : "image/jpeg";
+    res.set("Content-Type", mime);
+    res.set("Cache-Control", "no-cache");
+    res.send(buf);
+  });
+
+  router.put("/:id/avatar", (req, res) => {
+    const bot = botManager.getBot(req.params.id);
+    if (!bot && !botDb.getBotInstances().some((b) => b.id === req.params.id)) {
+      res.status(404).json({ error: "Bot not found" });
+      return;
+    }
+    const { dataUrl } = req.body as { dataUrl?: string };
+    if (typeof dataUrl !== "string") {
+      res.status(400).json({ error: "dataUrl required" });
+      return;
+    }
+    const m = /^data:(image\/(png|jpeg|webp));base64,(.+)$/.exec(dataUrl);
+    if (!m) {
+      res.status(400).json({ error: "dataUrl must be image/png|jpeg|webp base64" });
+      return;
+    }
+    const mime = m[1];
+    const buf = Buffer.from(m[3], "base64");
+    if (buf.length > 200 * 1024) {
+      res.status(413).json({ error: "avatar exceeds 200KB limit" });
+      return;
+    }
+    const rel = avatarStore.write(req.params.id, mime, buf);
+    botDb.setCustomAvatarPath(req.params.id, rel);
+    bot?.getProfileManager().setCustomAvatar(buf);
+    res.json({ path: rel });
+  });
+
+  router.delete("/:id/avatar", (req, res) => {
+    const path = botDb.getCustomAvatarPath(req.params.id);
+    if (path) avatarStore.remove(path);
+    botDb.setCustomAvatarPath(req.params.id, null);
+    const bot = botManager.getBot(req.params.id);
+    bot?.getProfileManager().setCustomAvatar(null);
+    res.status(204).end();
+  });
+```
+
+- [ ] **Step 4: Update the call site that constructs the router**
+
+Search: `grep -n 'createBotRouter' src/`
+
+In the call site (likely `src/web/server.ts` or `src/index.ts`), pass the new args. Fix the call signature.
+
+- [ ] **Step 5: Manual smoke test**
+
+Run: `npm run build && npm run start`
+In another terminal:
+
+```bash
+# create a small valid PNG (1x1) base64
+B64=$(node -e "console.log(Buffer.from([137,80,78,71,13,10,26,10,0,0,0,13,73,72,68,82,0,0,0,1,0,0,0,1,8,2,0,0,0,144,119,83,222,0,0,0,12,73,68,65,84,8,153,99,248,255,255,63,0,5,254,2,254,205,250,236,184,0,0,0,0,73,69,78,68,174,66,96,130]).toString('base64'))")
+
+curl -X PUT http://localhost:3000/api/bot/<BOT_ID>/avatar \
+  -H 'Content-Type: application/json' \
+  -d "{\"dataUrl\":\"data:image/png;base64,$B64\"}"
+
+curl http://localhost:3000/api/bot/<BOT_ID>/avatar -o /tmp/x.png
+file /tmp/x.png
+
+curl -X DELETE http://localhost:3000/api/bot/<BOT_ID>/avatar -i
+```
+
+Expected: PUT returns `{"path":"<id>.png"}`, GET returns the bytes, DELETE returns 204.
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add src/web/server.ts src/web/api/bot.ts src/index.ts
+git commit -m "feat(api): /api/bot/:id/avatar GET/PUT/DELETE"
+```
+
+---
+
+### Task 6: Frontend — `AvatarUpload.vue` component
+
+**Files:**
+- Create: `web/src/components/AvatarUpload.vue`
+
+- [ ] **Step 1: Create the component**
+
+```vue
+<template>
+  <div class="avatar-upload">
+    <div class="preview" :class="{ empty: !previewUrl }">
+      <img v-if="previewUrl" :src="previewUrl" alt="avatar" />
+      <Icon v-else icon="mdi:account-circle-outline" />
+    </div>
+    <div class="actions">
+      <input
+        ref="fileInput"
+        type="file"
+        accept="image/png,image/jpeg,image/webp"
+        class="hidden"
+        @change="onFile"
+      />
+      <button type="button" class="btn-sm" @click="fileInput?.click()">
+        {{ previewUrl ? '更换' : '上传' }}
+      </button>
+      <button v-if="previewUrl" type="button" class="btn-sm btn-danger" @click="clear">
+        删除
+      </button>
+    </div>
+    <p v-if="error" class="hint error">{{ error }}</p>
+    <p v-else class="hint">PNG / JPG / WebP，≤200 KB</p>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { ref, watch } from 'vue';
+import { Icon } from '@iconify/vue';
+
+const props = defineProps<{ modelValue: string | null }>();
+const emit = defineEmits<{ 'update:modelValue': [value: string | null] }>();
+
+const previewUrl = ref<string | null>(props.modelValue);
+const error = ref<string | null>(null);
+const fileInput = ref<HTMLInputElement | null>(null);
+
+watch(() => props.modelValue, (v) => { previewUrl.value = v; });
+
+function onFile(ev: Event) {
+  const file = (ev.target as HTMLInputElement).files?.[0];
+  if (!file) return;
+  if (!['image/png', 'image/jpeg', 'image/webp'].includes(file.type)) {
+    error.value = '仅支持 PNG / JPG / WebP';
+    return;
+  }
+  if (file.size > 200 * 1024) {
+    error.value = `图片 ${(file.size / 1024).toFixed(0)} KB 超过 200 KB 上限`;
+    return;
+  }
+  error.value = null;
+  const reader = new FileReader();
+  reader.onload = () => {
+    const dataUrl = reader.result as string;
+    previewUrl.value = dataUrl;
+    emit('update:modelValue', dataUrl);
+  };
+  reader.readAsDataURL(file);
+}
+
+function clear() {
+  previewUrl.value = null;
+  emit('update:modelValue', null);
+  if (fileInput.value) fileInput.value.value = '';
+}
+</script>
+
+<style lang="scss" scoped>
+.avatar-upload { display: flex; flex-direction: column; gap: 8px; align-items: flex-start; }
+.preview {
+  width: 80px; height: 80px; border-radius: 50%;
+  background: var(--bg-card); display: flex; align-items: center; justify-content: center;
+  overflow: hidden;
+  img { width: 100%; height: 100%; object-fit: cover; }
+  &.empty :deep(svg) { font-size: 48px; opacity: 0.4; }
+}
+.actions { display: flex; gap: 8px; }
+.hidden { display: none; }
+.hint { font-size: 12px; opacity: 0.6; margin: 0; }
+.hint.error { color: var(--color-danger, #e85060); opacity: 1; }
+.btn-danger { color: var(--color-danger, #e85060); }
+</style>
+```
+
+- [ ] **Step 2: Verify the component compiles**
+
+Run: `cd web && npx vue-tsc --noEmit`
+Expected: no errors
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add web/src/components/AvatarUpload.vue
+git commit -m "feat(web): AvatarUpload component"
+```
+
+---
+
+### Task 7: Wire AvatarUpload into Settings.vue (create + edit + standalone row)
+
+**Files:**
+- Modify: `web/src/views/Settings.vue`
+
+- [ ] **Step 1: Read the relevant Settings.vue regions**
+
+```bash
+grep -n '同步头像\|openEditBot\|saveEditBot\|createBot\|create-bot\|profile-features\|features.find' web/src/views/Settings.vue | head -20
+```
+
+Identify:
+- Create-bot form template region (`<div class="create-bot">` block)
+- Edit-bot modal/dialog template region
+- The profile features table where `avatarEnabled` row lives
+
+- [ ] **Step 2: Add component import + reactive state for avatar dataUrl on the create-bot form**
+
+In the script setup region, near other `newBot*` refs:
+
+```ts
+import AvatarUpload from '../components/AvatarUpload.vue';
+const newBotAvatar = ref<string | null>(null);
+```
+
+- [ ] **Step 3: Insert `<AvatarUpload v-model="newBotAvatar" />` into the create-bot form template**
+
+In the `<div class="create-bot">` block, right before `<button class="btn-primary" @click="createBot">创建</button>`, add:
+
+```vue
+        <div class="form-row">
+          <label>自定义头像（可选）</label>
+          <AvatarUpload v-model="newBotAvatar" />
+        </div>
+```
+
+- [ ] **Step 4: After successful `createBot()`, PUT the avatar if set**
+
+Find the `createBot` async function. After the POST resolves and the bot id is known (`res.data.id` or similar), append:
+
+```ts
+if (newBotAvatar.value) {
+  await axios.put(`/api/bot/${res.data.id}/avatar`, { dataUrl: newBotAvatar.value });
+}
+newBotAvatar.value = null;
+```
+
+- [ ] **Step 5: Add an "自定义头像" row in the per-bot profile features table**
+
+Find the profile-features table render (look for the `features` array iteration). The cleanest path: add a custom row OUTSIDE the array (since it isn't a boolean toggle). Right before `</template>` of the bot row, add:
+
+```vue
+        <div class="feature-row">
+          <div class="feature-label">自定义头像</div>
+          <div class="feature-control">
+            <CustomAvatarRow :bot-id="bot.id" />
+          </div>
+        </div>
+```
+
+Where `CustomAvatarRow` is an inline-defined component or a small file `web/src/components/CustomAvatarRow.vue` that:
+- Mounts → `axios.get(/api/bot/<id>/avatar, { responseType: 'blob' })` → previews if 200, ignore 404
+- Wraps `<AvatarUpload>` and on `update:modelValue`:
+  - If string → `axios.put(/avatar, { dataUrl })`
+  - If null → `axios.delete(/avatar)`
+
+Create `web/src/components/CustomAvatarRow.vue` with that logic; keep its body small (~50 lines).
+
+- [ ] **Step 6: Build and visually verify**
+
+Run: `cd web && npm run build` → no errors. Then `npm run dev` → open create-instance, upload PNG, create — verify the avatar appears on the bot in TS3 once it connects. Check edit/Settings flow.
+
+- [ ] **Step 7: Commit**
+
+```bash
+git add web/src/views/Settings.vue web/src/components/CustomAvatarRow.vue
+git commit -m "feat(web): custom avatar in create-bot + Settings"
+```
+
+---
+
+### Task 8: Open PR
+
+- [ ] **Step 1: Push the branch**
+
+```bash
+git checkout -b feat/custom-bot-avatar
+git push -u origin feat/custom-bot-avatar
+```
+
+(If commits were already on `main`, instead create the branch from the first relevant commit and reset main: `git branch feat/custom-bot-avatar HEAD && git reset --hard origin/main && git checkout feat/custom-bot-avatar`. The exact sequence depends on the working state when starting.)
+
+- [ ] **Step 2: Create the PR**
+
+```bash
+gh pr create --title "feat(profile): custom bot avatar" --body "Closes part of #51 (avatar half).
+
+## Summary
+- New /api/bot/:id/avatar GET/PUT/DELETE
+- BotProfileManager: custom avatar acts as idle image; cover sync still wins during playback when avatarEnabled=true
+- AvatarUpload component used in create-bot form and Settings per-bot row
+- Bump express.json limit to 400kb to allow base64 payload
+
+## Behavior matrix
+| avatarEnabled | custom set | playing | stopped |
+|---|---|---|---|
+| ✓ | ✓ | cover | restore custom |
+| ✓ | ✗ | cover | clear |
+| ✗ | ✓ | custom | custom |
+| ✗ | ✗ | no-op | no-op |
+
+## Test plan
+- [x] vitest covers DB, avatar store, ProfileManager precedence
+- [x] Manual: upload PNG → bot avatar shows; play song → cover; stop → custom; delete → cleared
+
+🤖 Generated with [Claude Code](https://claude.com/claude-code)"
+```
+
+---
+
+## Self-Review Checklist
+
+- [x] Each spec section has at least one task: precedence matrix → Task 3; storage → Task 2; DB → Task 1; API → Task 5; UI → Task 6+7
+- [x] No "TBD" / "fill in" / "implement later" text in any step
+- [x] Type names consistent: `AvatarStore` / `createAvatarStore` / `getCustomAvatarPath` / `setCustomAvatarPath` / `setCustomAvatar` (singular per call site)
+- [x] All code blocks compile under existing TS/Vue config (express 5, vitest, vue 3 + iconify already in use)

docs/superpowers/specs/2026-04-27-fm-artist-playlist-design.md

@@ -0,0 +1,125 @@
+# Design: FM Bug Fix + Artist Loop + Playlist Fuzzy Search
+
+Date: 2026-04-27
+
+## Overview
+
+Three features for the TeamSpeak Music Bot:
+1. New `!artist <name>` command — loop playback filtered by artist
+2. Fuzzy playlist name search in existing `!playlist` command
+3. Fix `!fm` audio dropout bug (no sound after a few songs but status shows playing)
+
+---
+
+## Feature 1: `!artist` Command
+
+### Behavior
+
+`!artist <歌手名> [-q|-b|-y]` searches for songs by the artist, loads them into the queue, sets the queue mode to `Loop`, and starts playing.
+
+### Flow
+
+1. Parse command with optional platform flags (`-q`, `-b`, `-y`)
+2. Call `provider.search(歌手名, 50)` to get up to 50 results
+3. Filter results: only keep songs where `song.artist` contains the search query (case-insensitive)
+4. If filtered list is empty, fall back to unfiltered search results (up to 20)
+5. Clear current queue, add filtered songs, set mode to `Loop`
+6. Play first song via `resolveAndPlay`
+
+### Key Decisions
+
+- **Why Loop mode?** The user said "循环播放" (loop playback). After the artist's songs are exhausted, they should restart.
+- **Why filter client-side?** The search API doesn't support artist-only filtering. We search broadly then narrow down.
+- **Why 50 results?** The default limit is 20, but for prolific artists we want more coverage. 50 balances API response size with coverage.
+
+### Files Changed
+
+- `src/bot/commands.ts`: Register `artist` in PUBLIC_COMMANDS, update help text
+- `src/bot/instance.ts`: New `cmdArtist()` method
+
+---
+
+## Feature 2: Playlist Fuzzy Search
+
+### Behavior
+
+`!playlist <name or ID>` now accepts both playlist IDs and playlist names. When the input is not a pure numeric ID, it searches for matching playlists and uses the top result.
+
+### Flow
+
+1. Parse input — if it's a pure numeric ID or contains a URL with an ID, use existing logic
+2. Otherwise, call `provider.search(input)` which already returns `playlists[]` in the result
+3. Also call `provider.getUserPlaylists()` if the provider supports it (logged-in state)
+4. Client-side fuzzy match user playlists: `playlist.name` contains input (case-insensitive)
+5. Merge results: public search results first (sorted by API relevance), then user matches
+6. Take the first playlist, load its songs, play
+
+### Key Decisions
+
+- **Why public search first?** It's already sorted by relevance from the API. User playlists are a secondary source.
+- **Why client-side matching for user playlists?** The `getUserPlaylists()` API returns all user playlists without a search parameter, so we must filter locally.
+- **Backward compatibility:** Numeric IDs and URL parsing are unchanged.
+
+### Files Changed
+
+- `src/bot/instance.ts`: Modify `cmdPlaylist()` to add search fallback
+- `src/bot/commands.ts`: Update help text
+
+---
+
+## Feature 3: FM Bug Fix
+
+### Root Cause Analysis
+
+The `!fm` bug manifests as: audio stops after a few songs, but `!now` shows a playing song and the song name keeps changing.
+
+`getPersonalFm()` returns only ~3 songs per API call. After those are consumed:
+- In `Sequential` mode: `queue.next()` returns null → `player.stop()` is called → playback stops entirely. This does NOT match "歌还在轮播" (songs still rotating).
+- In `Loop` mode (if user changed mode): the same 3 songs loop, but URLs may expire, causing silent playback failures.
+
+The most likely scenario for "no audio but status shows playing + song names changing":
+1. FM songs have URLs that resolve but don't produce playable audio (copyright/region restrictions)
+2. ffmpeg spawns, connects to the URL, gets an HTTP error or silent stream
+3. ffmpeg exits quickly (clean exit or error)
+4. The frame loop detects ffmpeg gone + buffer empty → emits `trackEnd`
+5. `playNext()` advances to the next song
+6. This rapid cycle (spawn → fail → advance) makes it appear that songs are "playing and rotating" but with no audio
+7. After 3 consecutive ffmpeg spawn failures, `consecutiveFailures >= MAX_CONSECUTIVE_FAILURES` → player refuses to spawn new ffmpeg processes
+8. After that, `resolveAndPlay` still sets state via `player.play()` which immediately emits "error" → `playNext()` skips to next → cycle continues with no ffmpeg at all
+
+### Fix Strategy
+
+**Fix 1 — FM auto-refill (primary fix):**
+- In `cmdFm()`, set queue mode to `RandomLoop` so the queue never "runs out"
+- Add a `refillFm()` method that fetches more FM songs and appends to queue
+- Hook into the `trackEnd` flow: when queue has ≤ 2 songs remaining and we're in FM mode, trigger a refill
+- Track FM state with a boolean flag `isFmMode` on the instance
+
+**Fix 2 — Reset consecutive failures on successful playback (safety net):**
+- Reset `consecutiveFailures` when a track plays successfully for at least N frames (e.g., 50 frames = 1 second)
+- This prevents transient URL failures from accumulating toward the hard limit
+
+**Fix 3 — FM refill before queue exhaustion:**
+- After `playNext()` successfully starts a song, check if `isFmMode` and `queue.size() - currentIndex <= 2`
+- If so, fire an async refill (don't block playback)
+
+### Files Changed
+
+- `src/bot/instance.ts`: Modify `cmdFm()`, add `refillFm()`, add FM state tracking, modify `playNext()` to check for FM refill
+- `src/audio/player.ts`: Add `framesPlayed` threshold check to reset `consecutiveFailures`
+
+---
+
+## Implementation Order
+
+1. **FM bug fix** first — it's a bug fix affecting current users
+2. **Playlist fuzzy search** — small change, quick win
+3. **Artist loop** — new feature, depends on queue/player being stable
+
+---
+
+## Testing
+
+- FM: Verify songs keep playing beyond the initial 3-song batch, verify auto-refill works
+- Playlist: Test with numeric ID (backward compat), test with playlist name (fuzzy search)
+- Artist: Test with known artist names, test edge case (no results), test with platform flags

docs/superpowers/specs/2026-05-06-music-source-tabs-design.md

@@ -0,0 +1,189 @@
+# Multi-Source Tabs for Recommend / User Playlists / Daily Songs
+
+**Date:** 2026-05-06
+**Status:** Spec — pending implementation
+
+## Problem
+
+Home 和 Library 页面的"推荐歌单 / 每日推荐 / 我的歌单"这三类内容当前硬编码只走网易云。当用户同时登录了网易云和 QQ 音乐时，无法在 Web UI 上看到 QQ 侧的对应内容、也无法切换查看。
+
+## Goal
+
+在以下 4 个 section 上提供"网易云 / QQ"来源切换 tab，桌面端和移动端均可用：
+
+- `Home.vue` — 推荐歌单
+- `Home.vue` — 每日推荐
+- `Home.vue` — 我的歌单
+- `Library.vue` — 我的歌单
+
+切换为纯前端动作（数据已预先 fetch），无加载闪烁。各 section 的选择独立持久化。
+
+## Out of Scope
+
+- 私人 FM（QQ 无对应概念）
+- B 站热门（独立第三来源，不属于网易/QQ 切换语义）
+- 最近播放（bot 维度的播放历史，与音乐源无关）
+- Library 现有的"我的收藏"段落 —— 当前调用的 `/api/music/user/liked` 端点不存在，是死代码，本次顺手移除
+- 登录状态实时同步（用户在 Settings 登录后需手动刷新 Home/Library 才能看到 QQ tab）
+- Tab 排序、隐藏、拖动等高级配置
+
+## Non-functional Constraints
+
+- 桌面端（>768px）和移动端（≤768px）布局均可用，tab 与 section title 同行排布；空间不足时允许 flex-wrap
+- Tab 触控区域有效高度 ≥36px
+- 现有 5 分钟 home data cache 行为保留
+- 不引入新的后端端点（后端已通过 `?platform=` 参数支持多源）
+
+## Architecture
+
+### 数据层（`web/src/stores/player.ts`）
+
+字段从单平台改为按 platform 切分：
+
+```ts
+// 前
+recommendPlaylists: PlaylistItem[]
+userPlaylists:      PlaylistItem[]
+dailySongs:         Song[]
+
+// 后
+recommendPlaylists: { netease: PlaylistItem[]; qq: PlaylistItem[] }
+userPlaylists:      { netease: PlaylistItem[]; qq: PlaylistItem[] }
+dailySongs:         { netease: Song[];         qq: Song[] }
+
+// 新增
+authStatus: { netease: boolean; qq: boolean }
+```
+
+`fetchHomeData()` 改写：
+
+1. 并发调用 `/api/auth/status?platform=netease` 与 `?platform=qq`，写入 `authStatus`
+2. 网易云的三类数据照常 fetch（推荐歌单匿名可访问；每日推荐和我的歌单需登录，未登录时 API 自然返回空或失败，`Promise.allSettled` 已隔离）
+3. QQ 的三类数据**仅在 QQ 登录时** fetch，未登录则为空数组
+4. B 站热门保持原样
+5. 5 分钟缓存 TTL 不变
+
+### UI 组件
+
+新增 `web/src/components/SourceTabs.vue`：
+
+```vue
+<SourceTabs v-model="activeSource" :sources="availableSources" />
+```
+
+Props：
+- `sources: ('netease' | 'qq')[]` — 由父组件根据 auth 状态过滤后传入
+- `modelValue: 'netease' | 'qq'` — v-model 绑定
+
+行为：
+- `sources.length < 2` 时组件**自身不渲染**（返回空），父组件无需 v-if 包装
+- 文字标签：`{ netease: '网易云', qq: 'QQ' }`
+- 视觉：水平排列，激活态用主色（`var(--color-primary)`）下划线 + 加粗，未激活态使用次要文字色
+- 紧贴 section-title 右侧，使用 `display: inline-flex`，移动端 padding/font-size 缩小
+
+### 各 section 接入模板
+
+```vue
+<section v-if="recommendAvailable.length > 0" class="section">
+  <h2 class="section-title">
+    推荐歌单
+    <SourceTabs v-model="recommendSource" :sources="recommendAvailable" />
+  </h2>
+  <div class="playlist-grid">
+    <RouterLink
+      v-for="pl in store.recommendPlaylists[recommendSource]"
+      :key="pl.id"
+      :to="`/playlist/${pl.id}?platform=${pl.platform}`"
+      class="playlist-card hover-scale"
+    >
+      <CoverArt :url="pl.coverUrl" :size="160" :radius="10" :show-shadow="true" />
+      <div class="playlist-name">{{ pl.name }}</div>
+    </RouterLink>
+  </div>
+</section>
+```
+
+每个 section 在 `<script setup>` 维护两个值：
+
+- `recommendSource: Ref<'netease' | 'qq'>` — 当前选中
+- `recommendAvailable: ComputedRef<('netease' | 'qq')[]>` — 该 section 在当前登录状态下有哪些 source 可选
+
+`recommendAvailable` 计算规则：
+
+| Section | netease 加入条件 | qq 加入条件 |
+|---|---|---|
+| Home 推荐歌单 | 总是（公开数据） | `authStatus.qq` |
+| Home 每日推荐 | `authStatus.netease` | `authStatus.qq` |
+| Home 我的歌单 | `authStatus.netease` | `authStatus.qq` |
+| Library 我的歌单 | `authStatus.netease` | `authStatus.qq` |
+
+#### "我的歌单"展开按钮兼容
+
+Home 的"我的歌单"现有 `USER_PLAYLIST_LIMIT = 20` 折叠/展开。改造后：
+
+```ts
+const visibleUserPlaylists = computed(() => {
+  const all = store.userPlaylists[userSource.value] ?? [];
+  return userPlaylistsExpanded.value ? all : all.slice(0, USER_PLAYLIST_LIMIT);
+});
+```
+
+切换 source 时折叠态保留（不需 reset）。
+
+### 持久化
+
+localStorage 键统一为一个 JSON：
+
+```
+key:   "source-tabs"
+value: {
+  "home.recommend": "qq",
+  "home.daily":     "netease",
+  "home.user":      "qq",
+  "library.user":   "netease"
+}
+```
+
+读：组件 mount 时一次性读 + 解析。
+写：在 v-model 的 setter 里 `watch` 一次写回。
+不存在的键 / 解析失败 / 老用户没这个 key —— 默认值 `"netease"`。
+
+### 边界与回退
+
+| 情况 | 行为 |
+|---|---|
+| 选的 source 不在 `available` 里（例：选了 QQ，登出后回到页面） | 渲染时 fallback 到 `available[0]`，不修改 localStorage（保留用户偏好，下次登回来仍生效） |
+| `recommendPlaylists.qq` 为空数组（API 失败 or 无数据） | tab 仍可切，切过去显示空 grid（无错误提示，符合现有"空数据隐藏 section"语义；section 顶层 v-if 检查的是 `available.length > 0`，单 platform 数据为空不影响 section 显隐） |
+| QQ provider 不支持 `getDailyRecommendSongs`（501） | `Promise.allSettled` 已捕获，`dailySongs.qq` 保持 `[]`，等同上一行 |
+| 用户在 Settings 登录 QQ 后切回 Home | 不自动 refetch / 不自动出 tab —— 用户需手动刷新页面（保留 5 分钟缓存语义） |
+| 网易云和 QQ 都没登录 | `available` 为空时 section 隐藏（沿用现有逻辑） |
+| Library "我的收藏" 段落 | 整段移除（含 template、script 中的 `liked` ref、对应 axios 调用） |
+
+## 修改文件清单
+
+新增：
+- `web/src/components/SourceTabs.vue` — 共享 tab 组件
+
+修改：
+- `web/src/stores/player.ts` — 多平台 state、`authStatus`、`fetchHomeData` 重写
+- `web/src/views/Home.vue` — 三个 section 接入 SourceTabs，对应 ref + computed
+- `web/src/views/Library.vue` — 我的歌单接入 SourceTabs；移除我的收藏死代码
+
+不改：
+- 后端（API 已支持 `?platform=`）
+- `Search.vue` / `Playlist.vue` / `Settings.vue` 等其他页面
+
+## 测试方案
+
+- 手动：在两种登录组合下访问 Home 和 Library，验证 tab 显隐、切换、刷新后持久化
+  - 仅网易登录 → 不显示 tab
+  - 两边登录 → 显示 tab，切换后刷新页面来源不变
+  - QQ 登录 → 网易登出 → 网易 tab 消失，若上次选的是网易则 fallback 到 QQ
+- 移动端（DevTools 768px 以下）：tab 与 section-title 同行不溢出，触控区域可点
+- TypeScript 类型检查通过：`npx tsc --noEmit` + `npm run build:web`
+- 单元测试：现有 vitest 套件不应回归（store 改动不破坏其他用法）
+
+## 风险
+
+- store 字段类型变更（数组 → 对象）会影响所有读取这三个字段的地方。需 grep 确认没有遗漏的消费者。
+- localStorage 解析失败的容错必须周全，避免一次脏数据导致整个页面白屏。

docs/superpowers/specs/2026-05-06-prev-history-and-play-next-design.md

@@ -0,0 +1,226 @@
+# History-aware `prev` + "Play Next" Insert
+
+**Date:** 2026-05-06
+**Status:** Spec — pending implementation
+
+## Problem
+
+Two queue/playback gaps surfaced in real use:
+
+1. In `PlayMode.Random` and `PlayMode.RandomLoop`, `!prev` does not play the
+   actually-previously-played song. It just walks `currentIndex - 1` in the
+   underlying array — but in random modes `currentIndex` jumps non-sequentially,
+   so the "previous" array slot has no relationship to play history.
+
+2. `!add` / web "添加到队列" appends to the queue tail. There is no way to
+   say "play this song right after the current one." Users want a "下一首
+   播放" affordance comparable to Spotify "Add to Queue (next up)" or Apple
+   Music "Play Next".
+
+## Goals
+
+- `prev` walks back through the actual play history regardless of mode.
+- A new "Play Next" path inserts a song at `currentIndex + 1`, available
+  via web UI button and TS3 chat command.
+- Both features are usable on desktop and mobile web.
+
+## Out of Scope
+
+- Forward/redo through prev'd songs (user would need to push next manually,
+  which picks a fresh random in random modes — acceptable simplification).
+- Reordering songs already in the queue ("move to next" inside Queue.vue).
+- Persisting play history across bot restarts (in-memory only).
+
+## Non-functional Constraints
+
+- History capped at 50 entries to bound memory.
+- `addNext` must keep `playedIndices` and `history` index references valid
+  after insertion (shift all indices > current by +1).
+- New Toast UX from the previous round still applies (failures surface).
+- TypeScript and existing test suite must not regress.
+
+## Architecture
+
+### A. History-aware `prev`
+
+**`src/audio/queue.ts`** — `PlayQueue` gains a back-stack:
+
+```ts
+private history: number[] = [];
+private static readonly HISTORY_LIMIT = 50;
+
+private pushHistory(idx: number): void {
+  if (idx < 0) return;
+  this.history.push(idx);
+  if (this.history.length > PlayQueue.HISTORY_LIMIT) {
+    this.history.shift();
+  }
+}
+```
+
+Mutators call `pushHistory(this.currentIndex)` **before** changing `currentIndex`:
+
+| Method | History action |
+|---|---|
+| `play()` | `this.history = []` (fresh playback) |
+| `playAt(idx)` | `pushHistory(currentIndex)`, then set `currentIndex = idx` |
+| `next()` | `pushHistory(currentIndex)`, then advance per mode |
+| `prev()` | **Pop** from history → `currentIndex = popped`. If empty, fall back to existing `currentIndex - 1` (which keeps Sequential's wrap behavior; Random returns null). `prev` itself does NOT push to history. |
+| `clear()` | `this.history = []` |
+| `setMode(m)` | `this.history = []` (mode change resets context) |
+| `remove(idx)` | Drop matching entries from history; shift any entry `> idx` by `-1`. Same logic as the existing `playedIndices` rebuild. |
+
+**`prev()` rewrite:**
+
+```ts
+prev(): QueuedSong | null {
+  if (this.songs.length === 0) return null;
+  // History-driven path (preferred when we have one)
+  while (this.history.length > 0) {
+    const idx = this.history.pop()!;
+    if (idx >= 0 && idx < this.songs.length) {
+      this.currentIndex = idx;
+      this.playedIndices.add(idx);
+      return this.songs[idx];
+    }
+    // popped index is stale (song removed) — keep popping
+  }
+  // Fallback: old index-based prev
+  const prevIndex = this.currentIndex - 1;
+  if (prevIndex < 0) {
+    if (this.mode === PlayMode.Sequential) return null;
+    this.currentIndex = this.songs.length - 1;
+  } else {
+    this.currentIndex = prevIndex;
+  }
+  this.playedIndices.add(this.currentIndex);
+  return this.songs[this.currentIndex];
+}
+```
+
+### B. Play Next (insert after current)
+
+**`PlayQueue.addNext(song)`:**
+
+```ts
+addNext(song: QueuedSong): void {
+  if (this.currentIndex < 0 || this.songs.length === 0) {
+    this.songs.push(song);
+    return;
+  }
+  const insertAt = this.currentIndex + 1;
+  this.songs.splice(insertAt, 0, song);
+  // Shift any tracked index > currentIndex by +1
+  const shifted = new Set<number>();
+  for (const i of this.playedIndices) {
+    shifted.add(i > this.currentIndex ? i + 1 : i);
+  }
+  this.playedIndices = shifted;
+  this.history = this.history.map((i) => (i > this.currentIndex ? i + 1 : i));
+}
+```
+
+**Backend endpoint** — `src/web/api/player.ts`:
+
+```
+POST /api/player/:botId/play-next-song
+body: { song: Song }
+```
+
+Behavior:
+- If queue is empty or `currentIndex < 0`: `queue.addNext(song)` (which falls
+  through to plain push), then `queue.play()`, then `resolveAndPlay`. Same
+  semantics as a successful `/play-song` — message: "正在播放：…"
+- Otherwise: `queue.addNext(song)`, no resolveAndPlay. Message: "已加入下一首：…"
+- Returns `{ ok: boolean, message: string }` matching the convention
+  established in the previous round.
+
+**Bot command** — `src/bot/instance.ts`:
+
+Register `!playnext <query>` (alias `!pn`):
+- Mirror of `cmdPlay`'s search step
+- On match: `queue.addNext(song)`. If no current playback, fall through to
+  `resolveAndPlay`.
+- Reply with `已加入下一首：<name>` or `正在播放：<name>` accordingly
+
+**Frontend store action** — `web/src/stores/player.ts`:
+
+```ts
+async playNextSong(song: Song) {
+  if (!this.activeBotId) return;
+  const res = await axios.post(`/api/player/${this.activeBotId}/play-next-song`, { song });
+  if (res.data?.message) {
+    this.notify(res.data.message, res.data.ok === false ? 'error' : 'info');
+  }
+}
+```
+
+**Frontend SongCard** — `web/src/components/SongCard.vue`:
+
+Add a third action button between the existing "play" and "add to queue":
+
+```vue
+<button class="action-btn" @click.stop="$emit('playNext')" title="下一首播放">
+  <Icon icon="mdi:playlist-play" />
+</button>
+```
+
+Add `playNext: []` to `defineEmits`.
+
+**Caller updates** — `Home.vue`, `Library.vue`, `Search.vue`, `History.vue`,
+`Playlist.vue`: each `<SongCard>` usage adds
+`@playNext="store.playNextSong(song)"`.
+
+**Queue.vue** is intentionally **not** updated — clicking "play next" on a
+song already in the queue would create a confusing duplicate.
+
+## Edge Cases
+
+| Case | Behavior |
+|---|---|
+| `prev` with empty history in Sequential mode | Walks `currentIndex - 1`; returns null at index 0 (existing) |
+| `prev` with empty history in Random/RandomLoop | Returns null (no past to recover) |
+| Repeated `prev` past start of history | Pops what's there, then falls back to index walk; eventually null |
+| `addNext` while `currentIndex == -1` (nothing played yet) | Falls through to push; queue.play() will pick it as first |
+| `addNext` while playing and queue size = 1 | Inserts at index 1; current index unchanged; next() will advance to it |
+| `remove` removes a song whose index is in history | Entry dropped; shifted accordingly |
+| Mode switched mid-playback | History cleared (intentional — mode change is a context boundary) |
+| `addNext` then `prev` | Inserted song was never played → not in history; prev pops the previously-played song, NOT the just-inserted one |
+
+## Files Touched
+
+- `src/audio/queue.ts` — history field, `pushHistory`, `addNext`, rewritten `prev`, mutator updates
+- `src/audio/queue.test.ts` (or add if missing) — unit tests for history behavior + addNext shift logic
+- `src/bot/instance.ts` — register `!playnext` / `!pn` command handler
+- `src/web/api/player.ts` — new `/play-next-song` route
+- `web/src/stores/player.ts` — `playNextSong` action
+- `web/src/components/SongCard.vue` — third action button + emit
+- `web/src/views/Home.vue` — wire `@playNext`
+- `web/src/views/Library.vue` — wire `@playNext`
+- `web/src/views/Search.vue` — wire `@playNext`
+- `web/src/views/History.vue` — wire `@playNext`
+- `web/src/views/Playlist.vue` — wire `@playNext`
+
+## Test Plan
+
+**Unit (vitest, `queue.test.ts`):**
+- prev with empty history in Sequential: walks back, null at index 0
+- prev with empty history in Random: returns null
+- next → next → next → prev pops correctly; prev again pops earlier
+- prev after `clear()` returns null (history reset)
+- prev after `setMode()` returns null (history reset)
+- `remove(idx)` drops from history and shifts entries > idx
+- `addNext` while empty: appends
+- `addNext` while playing index 2 in a 5-song queue: ends up at index 3, currentIndex still 2, queue size 6
+- `addNext` then `next()`: plays the inserted song
+- `addNext` shifts existing playedIndices and history correctly
+
+**Integration (manual smoke):**
+- Random mode: play 4 songs, hit `prev` 3 times → walks back through history
+- Click "下一首播放" on a search result → next song after current is the chosen one
+- `!playnext 七里香` → bot replies "已加入下一首：..."; current keeps playing; next song is 七里香
+- `!playnext` while idle → starts playing immediately
+
+**Regression:**
+- Existing 161 source-tree tests still pass.
+- TypeScript `tsc --noEmit` and `npm run build:web` clean.

docs/superpowers/specs/2026-05-07-custom-avatar-and-album-search-design.md

@@ -0,0 +1,149 @@
+# 自定义机器人头像 + 专辑搜索/播放
+
+**Date:** 2026-05-07
+**Status:** Spec — pending implementation
+**Issue:** [#51](https://github.com/ZHANGTIANYAO1/teamspeak-music-bot/issues/51)
+
+## Problem
+
+Issue #51 的两个独立但同源的反馈：
+
+1. **机器人头像无法固定** — 当前 `ProfileConfig.avatarEnabled` 控制是否同步专辑封面，但没有任何"上传一张固定头像"的入口。多 bot 房间里用户依赖头像辨识具体 bot，封面跟着歌变会让识别成本变高。
+2. **网页端搜索不能播放整张专辑** — `SearchResult.albums` 类型字段存在但所有 provider 都返回 `[]`，搜索 API `/search/all` 只聚合 `songs`；Search.vue 里也只渲染 SongCard。Netease 后端 `getAlbumSongs` 已实现，唯独缺把搜索/UI 连起来。
+
+两件事独立，分两个 PR；本 spec 同时覆盖两块以保持 #51 的单一 issue 关系。
+
+## Goal
+
+### 自定义头像
+
+- "创建新实例"弹窗里有一个"自定义头像"上传/预览控件（PNG/JPG/WebP，≤200 KB，与 TS3 头像上限一致）
+- Settings 已有的"同步头像"那行下面增加同等的"自定义头像"卡片，可以在已存在的 bot 上随时改/删
+- 行为矩阵：
+
+  | `avatarEnabled` | 有自定义 | 播放时 | 停播时 |
+  |---|---|---|---|
+  | true  | 是 | 跟当前歌曲封面 | **回到自定义** |
+  | true  | 否 | 跟当前歌曲封面 | 清空（保持现状） |
+  | false | 是 | 一直显示自定义 | 一直显示自定义 |
+  | false | 否 | 不主动改 | 不主动改 |
+
+### 专辑搜索
+
+- 搜索结果里能看到"专辑"分区（先支持 Netease + QQ，bilibili/youtube 仍返回 `[]`）
+- 点专辑卡片进入详情页 → 看到曲目列表 + 顶部"播放全部 / 加入队列"
+
+## Out of Scope
+
+- 头像格式自动转换（用户传 GIF/BMP 不接受，前端校验拒掉）
+- 头像服务端自动 resize（本期保持"上传时校验大小"，后期可加 sharp/jimp 但不在本期）
+- 专辑搜索的多平台聚合排序（按 `netease → qq` 简单拼接，与现有 `songs` 聚合一致）
+- 专辑详情页的"喜欢/收藏"按钮（playlist 详情页本身也没有）
+- 专辑作为推荐位（Home 不出现"推荐专辑"这一栏）
+- bilibili / youtube 的专辑概念（这两个平台无对应 API）
+
+## Architecture
+
+### 自定义头像
+
+#### 存储
+
+- 文件落地 `data/avatars/<botId>.<ext>`（仿 `data/cookies/<platform>.json`，Docker volume 友好）
+- DB schema：`bot_instances` 表新增 `custom_avatar_path` TEXT NULL（存相对路径，如 `avatars/<botId>.png`），通过 `migrateSchema()` 迁移
+- 加载时机：`BotProfileManager` 构造时把文件读到内存 `Buffer`，避免每次 stop 都读盘
+
+#### 后端 API
+
+新增 `src/web/api/bot.ts` 里（如不存在则在 `instance.ts` 同源处）：
+
+- `POST /api/bot/:id/avatar` (multipart) — 校验大小 ≤200 KB、MIME ∈ {png,jpeg,webp}；写盘 + 更新 DB；广播给运行中实例（重新加载 buffer + 立即 `applyIdleAvatar()`）
+- `DELETE /api/bot/:id/avatar` — 删盘 + 清 DB；运行中实例切回原 clear 语义
+- `GET /api/bot/:id/avatar` — 直接 `res.sendFile`（带强 ETag）供前端预览
+
+#### `BotProfileManager` 改动
+
+新增字段 + 方法：
+
+```ts
+private customAvatar: Buffer | null = null;
+
+setCustomAvatar(buf: Buffer | null): void;
+private async applyIdleAvatar(gen: number): Promise<void>;  // 上传 customAvatar
+```
+
+修改：
+
+- `clearAvatar(gen)` → `if (this.customAvatar) { applyIdleAvatar(gen) } else { 当前逻辑 }`
+- `onConnect()` 新增：`if (!avatarEnabled && customAvatar) applyIdleAvatar(gen)`
+- `setCustomAvatar(buf)`：更新内存 buffer，并触发 `applyIdleAvatar` 一次（仅当当前应该显示 idle avatar 时，即没在播放或 avatarEnabled=false）
+
+#### 前端
+
+新组件 `web/src/components/AvatarUpload.vue`：
+
+- props: `botId?` (上传时空表示走临时 base64 缓存)、`v-model:value`
+- 拖拽 / 文件选择 / 预览圆框 / 删除按钮
+- 内部 `axios.post('/api/bot/<id>/avatar', formData)` 或在创建表单里把 base64 与表单一同提交
+
+接入点：
+
+- 创建实例弹窗（搜索 `BotEditor.vue` 或类似）—— 表单提交后用返回的 botId 再 POST 头像；或者表单本身保存 base64 等创建完成后由后端解码落盘
+- Settings.vue：在 features 列表中插入一行"自定义头像"，右侧渲染 `<AvatarUpload :bot-id="botId" />`
+
+### 专辑搜索 / 详情
+
+#### 后端
+
+`src/music/netease.ts` `search()`：
+
+- 多发一个 `cloudsearch?type=10` 请求，把返回的 `result.albums[]` 映射成 `Album[]` 填进 `SearchResult.albums`
+- 字段 `id` / `name` / `coverUrl` (`picUrl`) / `artist` (`artists[].name.join(' / ')`)
+
+`src/music/qq.ts` `search()`：
+
+- 在现有 `req_0` 旁增加 `req_album: { module: "music.search.SearchCgiService", method: "DoSearchForQQMusicDesktop", param: { searchid, query, search_type: 8 } }`，映射 `body.album.list[]`
+
+`src/web/api/music.ts` `/search/all`：
+
+- 在响应里增加 `albums` 和 `playlists`，与 `songs` 一同合并
+
+`/album/:id` 已存在，无需改动。
+
+#### 前端
+
+- `web/src/views/Search.vue`：响应 schema 升级为 `{songs, albums, playlists}`；模板加入两个新分区（"专辑"、"歌单"），各自一个简单的卡片网格（参考 Home.vue 的 `playlist-grid`）
+- 新路由 `/album/:id` → 复用 `Playlist.vue`，把它的 `loadPlaylist()` 重构为根据 `route.path` 决定调 `/playlist/:id` 还是 `/album/:id`，或者新建 `Album.vue` 内部 import 同一个 `<PlaylistDetail />` 子组件
+  - **方案选择**：拆出 `<PlaylistDetail :endpoint="...">` 组件 + `Album.vue` / `Playlist.vue` 两个薄壳。当前 `Playlist.vue` 内部仅 ~60 行模板，单文件改造比新建 PlaylistDetail 子组件更小，先用最小改动：在 `Playlist.vue` 内根据 `route.meta.kind === 'album'` 切换 endpoint
+- 路由：`router/index.ts` 加 `{ path: '/album/:id', component: Playlist, meta: { kind: 'album' } }`
+
+### 拆分
+
+**两个 PR：**
+
+1. `feat(profile): custom bot avatar with idle/playback precedence`
+   - DB migration + ProfileManager 改动 + 上传 API + AvatarUpload.vue + 接入两个表单
+2. `feat(search): album section in search results + album detail playback`
+   - netease/qq search 扩展 + /search/all + Search.vue 分区 + Playlist.vue 复用为 album
+
+## Testing
+
+### 自定义头像
+
+- 单元：DB 迁移加 `custom_avatar_path` 列幂等；上传 API 校验大小/MIME；ProfileManager.applyIdleAvatar 在 onSongChange(null) 后被调用
+- 集成：mock TS3Client 验证 fileTransferInitUpload 收到的 buffer 是 customAvatar
+- 手动：本地起 bot 上传一张 png → 检查头像；播一首歌 → 头像切封面；停止 → 头像回到 png；关掉 avatarEnabled 重启 → 头像直接是 png
+
+### 专辑搜索
+
+- 单元：netease/qq `search()` 测试：响应包含 albums 字段，长度 > 0 (mock fixture 必须含 album 段)
+- 集成：`/search/all` 响应 schema 包含 `albums`/`playlists`
+- 手动：搜"周杰伦" → 看到歌曲 + 专辑 + 歌单三个分区；点专辑 → 详情页 → 播放全部 → 队列加上整张专辑
+
+## Migration
+
+DB 迁移：`bot_instances.custom_avatar_path` TEXT NULL，默认 NULL。已存在 bot 不受影响。
+
+## Open Questions
+
+- TS6 协议路径下 `fileTransferInitUpload` 是否一致？（既有 avatar 流程已经覆盖 TS3 + TS6，本期沿用同一路径，不单独验证）
+- 头像超过 200 KB 时前端用 Canvas 自动 resize 还是直接拒？— **决定：拒，错误提示"请压缩到 200KB 以内"**，简单可控

scripts/docker/docker-compose.yml

@@ -1,14 +1,16 @@
 # TSMusicBot — Docker Compose
-# 一键部署：docker-compose up -d
+# 一键部署：docker-compose pull && docker-compose up -d
 #
-# 所有依赖已内置（Node.js, FFmpeg, Opus 编码器）无需安装任何额外软件
+# 默认从 GitHub Container Registry 拉取预构建镜像（amd64 + arm64），
-# FFmpeg 使用系统包管理器安装，确保容器内兼容性
+# 无需本地编译，无需 Node.js / 构建工具链。
+# 镜像内置：Node.js, FFmpeg, Opus 编码器，原生模块均已交叉编译。
+#
+# 如需指定版本，把 :latest 换成具体 tag（例如 :1.4.0）。
+# 如需本地构建（开发或 fork），见底部注释。
 
 services:
   tsmusicbot:
-    build:
+    image: ghcr.io/zhangtianyao1/teamspeak-music-bot:latest
-      context: ../..
-      dockerfile: scripts/docker/Dockerfile
     container_name: tsmusicbot
     # Use host network so the bot can reach TS3 server on LAN
     # If your TS3 server is on the same machine, this is required
@@ -27,3 +29,12 @@ services:
 volumes:
   tsmusicbot-data:
     driver: local
+
+# ------------------------------------------------------------------
+# 本地构建（仅开发 / fork 场景使用）：
+# 把上面的 `image:` 行删掉，换成下面的 build 块即可。
+#
+#     build:
+#       context: ../..
+#       dockerfile: scripts/docker/Dockerfile
+# ------------------------------------------------------------------

scripts/setup.bat

@@ -1,91 +1,321 @@
 @echo off
+setlocal enabledelayedexpansion
+chcp 65001 >nul
 title TSMusicBot Setup
-echo ============================================
+
-echo   TSMusicBot - First-Time Setup (Windows)
+:: ============================================================
-echo ============================================
+::  TSMusicBot Setup Script (Robust Edition)
-echo.
+::  - Auto-detect China network, switch to npmmirror
+::  - Strict error checking at every step
+::  - Detailed logging to setup.log
+::  - Skip already-completed steps on re-run
+:: ============================================================
+
+set "SCRIPT_VERSION=2.0"
+set "MIN_NODE_MAJOR=20"
+set "LOG_FILE=%~dp0..\setup.log"
+set "FAILED=0"
 
 :: Resolve project root (one level up from scripts/)
-cd /d "%~dp0.."
+cd /d "%~dp0.." || (
+    echo [FATAL] Cannot change to project directory.
+    pause
+    exit /b 1
+)
+
+set "PROJECT_ROOT=%cd%"
+
+:: ---- Initialize log ----
+echo. > "%LOG_FILE%"
+call :log "============================================"
+call :log "  TSMusicBot Setup v%SCRIPT_VERSION%"
+call :log "  Started: %date% %time%"
+call :log "  Project root: %PROJECT_ROOT%"
+call :log "============================================"
+
+echo ============================================
+echo   TSMusicBot - First-Time Setup (Windows)
+echo   Version %SCRIPT_VERSION%
+echo ============================================
+echo.
+echo Log file: %LOG_FILE%
+echo.
+
+:: ============================================================
+:: Step 1: Check Node.js
+:: ============================================================
+call :step "1/6" "Checking Node.js"
 
-:: ---- Step 1: Check / install Node.js ----
 where node >nul 2>&1
-if %errorlevel% neq 0 (
+if errorlevel 1 (
-    echo Node.js not found. Attempting automatic installation...
+    call :error "Node.js not found in PATH."
     echo.
+    echo Please install Node.js %MIN_NODE_MAJOR% LTS or newer from one of:
+    echo   - https://nodejs.org/        ^(official^)
+    echo   - https://nodejs.cn/         ^(China mirror, recommended for CN users^)
+    echo.
+    echo After installation:
+    echo   1. Close this window completely
+    echo   2. Open a NEW Command Prompt
+    echo   3. Run scripts\setup.bat again
+    echo.
+    pause
+    exit /b 1
+)
 
-    :: Try winget first (available on Windows 10 1709+ and Windows 11)
+:: Check Node version >= 20
-    where winget >nul 2>&1
+for /f "tokens=1 delims=v." %%a in ('node --version 2^>nul') do set "NODE_RAW=%%a"
-    if %errorlevel% equ 0 (
+for /f "tokens=1 delims=v." %%a in ('node --version 2^>nul') do (
-        echo Installing Node.js via winget...
+    for /f "tokens=1 delims=." %%b in ("%%a") do set "NODE_MAJOR=%%b"
-        winget install OpenJS.NodeJS.LTS --accept-source-agreements --accept-package-agreements
+)
-        if %errorlevel% neq 0 (
+
-            echo winget installation failed. Please install Node.js manually from https://nodejs.org
+:: Robust version parse
+for /f "delims=" %%v in ('node --version 2^>nul') do set "NODE_VER=%%v"
+set "NODE_VER_NUM=%NODE_VER:v=%"
+for /f "tokens=1 delims=." %%a in ("%NODE_VER_NUM%") do set "NODE_MAJOR=%%a"
+
+call :log "Node.js version: %NODE_VER%"
+echo [OK] Node.js found: %NODE_VER%
+
+if %NODE_MAJOR% LSS %MIN_NODE_MAJOR% (
+    call :error "Node.js version too old. Need %MIN_NODE_MAJOR%+, found %NODE_VER%."
+    echo Please upgrade Node.js to version %MIN_NODE_MAJOR% LTS or newer.
     pause
     exit /b 1
-        )
+)
-        :: Refresh PATH so node is available in this session
+echo.
-        call refreshenv >nul 2>&1
+
-        :: If refreshenv is not available, ask user to restart
+:: ============================================================
-        where node >nul 2>&1
+:: Step 2: Check npm
-        if %errorlevel% neq 0 (
+:: ============================================================
-            echo.
+call :step "2/6" "Checking npm"
-            echo Node.js was installed but is not yet available in this terminal.
+
-            echo Please close this window and run setup.bat again.
+where npm >nul 2>&1
+if errorlevel 1 (
+    call :error "npm not found. This is unusual since Node.js is installed."
+    echo Please reinstall Node.js to fix this.
     pause
-            exit /b 0
+    exit /b 1
-        )
+)
+
+for /f "delims=" %%v in ('npm --version 2^>nul') do set "NPM_VER=%%v"
+call :log "npm version: %NPM_VER%"
+echo [OK] npm found: %NPM_VER%
+echo.
+
+:: ============================================================
+:: Step 3: Detect network and configure mirror
+:: ============================================================
+call :step "3/6" "Checking network"
+
+set "USE_MIRROR=0"
+
+:: Try reaching npm registry with a short timeout
+echo Testing connection to registry.npmjs.org...
+call :log "Testing npm registry connectivity..."
+
+:: Use curl if available (more reliable than ping for HTTPS)
+where curl >nul 2>&1
+if not errorlevel 1 (
+    curl -s -o nul -m 5 -w "%%{http_code}" https://registry.npmjs.org/ > "%TEMP%\npmtest.txt" 2>nul
+    set /p HTTP_CODE=<"%TEMP%\npmtest.txt"
+    del "%TEMP%\npmtest.txt" >nul 2>&1
+    if "!HTTP_CODE!"=="200" (
+        echo [OK] npm registry reachable.
+        call :log "npm registry HTTP 200 OK"
     ) else (
-        echo winget is not available on this system.
+        echo [WARN] npm registry slow or unreachable ^(code: !HTTP_CODE!^).
-        echo Please install Node.js 20 LTS manually from https://nodejs.org
+        call :log "npm registry returned: !HTTP_CODE!"
-        echo After installing, close this window and run setup.bat again.
+        set "USE_MIRROR=1"
-        pause
-        exit /b 1
     )
 ) else (
-    echo [OK] Node.js found.
+    :: Fallback to ping
-    node --version
+    ping -n 1 -w 3000 registry.npmjs.org >nul 2>&1
+    if errorlevel 1 (
+        echo [WARN] Cannot reach npm registry quickly.
+        set "USE_MIRROR=1"
+    ) else (
+        echo [OK] npm registry reachable.
+    )
+)
+
+if "%USE_MIRROR%"=="1" (
+    echo.
+    echo Slow connection detected. Switching to China mirror ^(npmmirror.com^)...
+    call :log "Switching to npmmirror.com"
+    call npm config set registry https://registry.npmmirror.com >>"%LOG_FILE%" 2>&1
+    call npm config set disturl https://registry.npmmirror.com/-/binary/node >>"%LOG_FILE%" 2>&1
+    call npm config set electron_mirror https://registry.npmmirror.com/-/binary/electron/ >>"%LOG_FILE%" 2>&1
+    call npm config set sqlite3_binary_host_mirror https://registry.npmmirror.com/-/binary/better-sqlite3 >>"%LOG_FILE%" 2>&1
+    call npm config set node_sqlite3_binary_host_mirror https://registry.npmmirror.com/-/binary/better-sqlite3 >>"%LOG_FILE%" 2>&1
+    call npm config set sharp_binary_host https://registry.npmmirror.com/-/binary/sharp >>"%LOG_FILE%" 2>&1
+    call npm config set sharp_libvips_binary_host https://registry.npmmirror.com/-/binary/sharp-libvips >>"%LOG_FILE%" 2>&1
+    call npm config set FFMPEG_BINARIES_URL https://registry.npmmirror.com/-/binary/ffmpeg-static >>"%LOG_FILE%" 2>&1
+    call npm config set @discordjs:registry https://registry.npmmirror.com >>"%LOG_FILE%" 2>&1
+    echo [OK] Mirror configured.
 )
 echo.
 
-:: ---- Step 2: Install npm dependencies ----
+:: ============================================================
-echo Installing dependencies (this may take a few minutes)...
+:: Step 4: Install backend dependencies
-call npm install
+:: ============================================================
-if %errorlevel% neq 0 (
+call :step "4/6" "Installing backend dependencies"
+
+if exist "node_modules\.package-lock.json" (
+    echo Found existing node_modules. Checking integrity...
+    call :log "Existing node_modules detected, running npm install to verify"
+)
+
+echo Running: npm install ^(this can take 5-15 minutes on slow networks^)
+echo Press Ctrl+C to abort.
+echo.
+
+call npm install >>"%LOG_FILE%" 2>&1
+if errorlevel 1 (
+    call :error "Backend npm install failed."
+    echo.
+    echo Common causes:
+    echo   - Network timeout ^(retry with VPN or check %LOG_FILE%^)
+    echo   - Native module compile failure ^(missing Python/VS Build Tools^)
+    echo   - Disk space full
+    echo.
+    echo Try manually:
+    echo   cd /d "%PROJECT_ROOT%"
+    echo   npm install --verbose
     echo.
-    echo npm install failed. Check the error messages above.
     pause
     exit /b 1
 )
-echo [OK] Dependencies installed.
+echo [OK] Backend dependencies installed.
 echo.
 
-:: ---- Step 3: Build the project ----
+:: ============================================================
-echo Building TypeScript project...
+:: Step 5: Install frontend dependencies
-call npx tsc
+:: ============================================================
-if %errorlevel% neq 0 (
+call :step "5/6" "Installing frontend dependencies"
+
+if not exist "web\package.json" (
+    call :error "web\package.json not found. Repository may be incomplete."
+    echo Please re-clone the repository:
+    echo   git clone https://github.com/ZHANGTIANYAO1/teamspeak-music-bot.git
+    pause
+    exit /b 1
+)
+
+echo Running: npm install ^(in web/ directory^)
+echo.
+
+pushd web >nul
+call npm install >>"%LOG_FILE%" 2>&1
+set "WEB_INSTALL_RESULT=!errorlevel!"
+popd >nul
+
+if !WEB_INSTALL_RESULT! neq 0 (
+    call :error "Frontend npm install failed ^(exit code !WEB_INSTALL_RESULT!^)."
+    echo.
+    echo Try manually:
+    echo   cd /d "%PROJECT_ROOT%\web"
+    echo   npm install --verbose
+    echo.
+    pause
+    exit /b 1
+)
+echo [OK] Frontend dependencies installed.
+echo.
+
+:: ============================================================
+:: Step 6: Build project (backend + frontend)
+:: ============================================================
+call :step "6/6" "Building project"
+
+echo Running: npm run build
+echo.
+
+call npm run build >>"%LOG_FILE%" 2>&1
+if errorlevel 1 (
+    call :error "Build failed."
+    echo.
+    echo Check the log file for details: %LOG_FILE%
+    echo.
+    echo Try manually:
+    echo   cd /d "%PROJECT_ROOT%"
+    echo   npm run build
     echo.
-    echo Build failed. Check the error messages above.
     pause
     exit /b 1
 )
 echo [OK] Build succeeded.
 echo.
 
-:: ---- Step 4: Create default config if missing ----
+:: ============================================================
+:: Verify build outputs
+:: ============================================================
+echo Verifying build outputs...
+set "BUILD_OK=1"
+
+if not exist "dist" (
+    call :error "dist/ directory missing after build."
+    set "BUILD_OK=0"
+)
+if not exist "web\dist" (
+    call :error "web\dist/ directory missing after build."
+    set "BUILD_OK=0"
+)
+
+if "!BUILD_OK!"=="0" (
+    echo.
+    echo Build completed but expected output is missing.
+    echo Check %LOG_FILE% for details.
+    pause
+    exit /b 1
+)
+echo [OK] Build outputs verified.
+echo.
+
+:: ============================================================
+:: Optional: config.json hint
+:: ============================================================
 if not exist "config.json" (
-    echo Creating default config.json...
+    echo [INFO] config.json will be auto-generated on first launch.
-    echo Please edit config.json with your TeamSpeak server details before starting the bot.
 ) else (
     echo [OK] config.json already exists.
 )
 echo.
 
-:: ---- Done ----
+:: ============================================================
+:: Done
+:: ============================================================
+call :log "Setup completed successfully at %date% %time%"
+
 echo ============================================
-echo   Setup complete!
+echo   Setup Complete!
 echo ============================================
 echo.
-echo To start the bot, run:  scripts\start.bat
+echo Next steps:
+echo   1. Run:  scripts\start.bat
+echo   2. Open: http://localhost:3000
+echo   3. Follow the in-browser setup wizard.
+echo.
+echo Setup log saved to: %LOG_FILE%
 echo.
 pause
+exit /b 0
+
+:: ============================================================
+:: Subroutines
+:: ============================================================
+:step
+echo ---- Step %~1: %~2 ----
+call :log ""
+call :log "---- Step %~1: %~2 ----"
+goto :eof
+
+:error
+echo.
+echo [ERROR] %~1
+call :log "[ERROR] %~1"
+goto :eof
+
+:log
+echo [%time%] %~1 >> "%LOG_FILE%"
+goto :eof

scripts/test_jdymusic_powershell.mjs

@@ -0,0 +1,106 @@
+// Empirically verifies the PowerShell-download workaround for jdymusic CDN
+// blocks Node.js HTTP. Runs A/B against the same fresh /jdymusic/ URL:
+//   A) ffmpeg direct with browser UA (the previous fix in this branch)
+//   B) PowerShell WebClient -> temp file -> ffmpeg from file (the new fix)
+// Reports bytes received + exit code + stderr-tail for each.
+
+import { spawn } from "node:child_process";
+import { mkdtempSync, statSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { buildFfmpegArgs } from "../dist/audio/player.js";
+
+const url = process.argv[2];
+if (!url) {
+  console.error("usage: node scripts/test_jdymusic_powershell.mjs <jdymusic_url>");
+  process.exit(2);
+}
+if (!url.includes("/jdymusic/")) {
+  console.error("warning: this script targets /jdymusic/ URLs specifically");
+}
+
+const FFMPEG = "ffmpeg";
+const BROWSER_UA =
+  "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36";
+const TIMEOUT_MS = 20_000;
+
+function runFfmpeg(label, args, stdinSource) {
+  return new Promise((resolve) => {
+    const proc = spawn(FFMPEG, args, { stdio: [stdinSource ?? "ignore", "pipe", "pipe"] });
+    let bytes = 0;
+    let stderrTail = "";
+    let killed = false;
+    proc.stdout.on("data", (chunk) => { bytes += chunk.length; });
+    proc.stderr.on("data", (chunk) => { stderrTail = (stderrTail + chunk.toString()).slice(-1500); });
+    const timer = setTimeout(() => { killed = true; proc.kill("SIGTERM"); }, TIMEOUT_MS);
+    proc.on("exit", (code, signal) => {
+      clearTimeout(timer);
+      resolve({ label, bytes, code, signal, killed, stderrTail });
+    });
+  });
+}
+
+function downloadViaPowerShell(targetUrl, outFile) {
+  return new Promise((resolve) => {
+    const psScript = [
+      "$ErrorActionPreference = 'Stop'",
+      "$ProgressPreference = 'SilentlyContinue'",
+      "$wc = New-Object System.Net.WebClient",
+      "$wc.Headers.Add('User-Agent', $env:DL_UA)",
+      "$wc.Headers.Add('Referer', $env:DL_REFERER)",
+      "$wc.DownloadFile($env:DL_URL, $env:DL_OUT)",
+    ].join("; ");
+    const ps = spawn(
+      "powershell",
+      ["-NoProfile", "-ExecutionPolicy", "Bypass", "-Command", psScript],
+      {
+        env: {
+          ...process.env,
+          DL_URL: targetUrl,
+          DL_OUT: outFile,
+          DL_UA: BROWSER_UA,
+          DL_REFERER: "https://music.163.com/",
+        },
+        stdio: ["ignore", "pipe", "pipe"],
+      },
+    );
+    let stderr = "";
+    ps.stderr.on("data", (chunk) => { stderr += chunk.toString(); });
+    ps.on("exit", (code) => resolve({ code, stderr }));
+  });
+}
+
+console.log(`URL: ${url}\n`);
+
+console.log("[A] ffmpeg direct (browser UA via -headers)");
+const a = await runFfmpeg("A", buildFfmpegArgs(url, 0));
+console.log(`    code=${a.code} bytes=${a.bytes} killed=${a.killed}`);
+console.log(`    stderr-tail: ${a.stderrTail.split("\n").slice(-3).join(" | ")}\n`);
+
+console.log("[B] PowerShell WebClient -> temp file -> ffmpeg -i tempfile");
+const tempDir = mkdtempSync(join(tmpdir(), "tsbot-jdymusic-test-"));
+const tempFile = join(tempDir, "song.audio");
+const psStart = Date.now();
+const dl = await downloadViaPowerShell(url, tempFile);
+const psMs = Date.now() - psStart;
+if (dl.code !== 0) {
+  console.log(`    PowerShell download FAILED: code=${dl.code}`);
+  console.log(`    stderr: ${dl.stderr.slice(-500)}`);
+  rmSync(tempDir, { recursive: true, force: true });
+  process.exit(1);
+}
+const dlSize = statSync(tempFile).size;
+console.log(`    PowerShell downloaded ${dlSize} bytes in ${psMs}ms`);
+
+const b = await runFfmpeg("B", buildFfmpegArgs(tempFile, 0));
+console.log(`    ffmpeg-from-file: code=${b.code} bytes=${b.bytes} killed=${b.killed}`);
+console.log(`    stderr-tail: ${b.stderrTail.split("\n").slice(-3).join(" | ")}\n`);
+
+rmSync(tempDir, { recursive: true, force: true });
+
+const aBlocked = a.bytes === 0 && !a.killed;
+const bWorked = b.bytes > 100_000;
+console.log(
+  `Verdict: direct ${aBlocked ? "BLOCKED" : "OK"} ; ` +
+  `powershell-then-ffmpeg ${bWorked ? "WORKED" : "FAILED"}`,
+);

scripts/test_netease_ua_fix.mjs

@@ -0,0 +1,73 @@
+// Empirically tests whether the browser UA + Referer headers fix the
+// connection resets we saw in bot.log against m701/m801.music.126.net.
+//
+// Spawns ffmpeg twice against the SAME fresh Netease CDN URL:
+//   A) old args from before the fix (no headers, -reconnect_delay_max 5)
+//   B) new args from after the fix (browser UA + Referer for music.126.net)
+// and reports bytes received + exit code + stderr-tail for each.
+
+import { spawn } from "node:child_process";
+import { buildFfmpegArgs } from "../dist/audio/player.js";
+
+const url = process.argv[2];
+if (!url) {
+  console.error("usage: node scripts/test_netease_ua_fix.mjs <netease_cdn_url>");
+  process.exit(2);
+}
+
+const FFMPEG = "ffmpeg";
+const TIMEOUT_MS = 15_000;
+
+function legacyArgs(u) {
+  return [
+    "-reconnect", "1",
+    "-reconnect_streamed", "1",
+    "-reconnect_delay_max", "5",
+    "-i", u,
+    "-f", "s16le",
+    "-ar", "48000",
+    "-ac", "2",
+    "-acodec", "pcm_s16le",
+    "-",
+  ];
+}
+
+function runFfmpeg(label, args) {
+  return new Promise((resolve) => {
+    const proc = spawn(FFMPEG, args, { stdio: ["ignore", "pipe", "pipe"] });
+    let bytes = 0;
+    let stderrTail = "";
+    let killed = false;
+
+    proc.stdout.on("data", (chunk) => {
+      bytes += chunk.length;
+    });
+    proc.stderr.on("data", (chunk) => {
+      stderrTail = (stderrTail + chunk.toString()).slice(-1500);
+    });
+
+    const timer = setTimeout(() => {
+      killed = true;
+      proc.kill("SIGTERM");
+    }, TIMEOUT_MS);
+
+    proc.on("exit", (code, signal) => {
+      clearTimeout(timer);
+      resolve({ label, bytes, code, signal, killed, stderrTail });
+    });
+  });
+}
+
+console.log(`URL: ${url}\n`);
+
+const a = await runFfmpeg("A) legacy args (no UA)", legacyArgs(url));
+console.log(`[A] code=${a.code} signal=${a.signal} killed=${a.killed} bytes=${a.bytes}`);
+console.log(`    stderr-tail:\n${a.stderrTail.split("\n").slice(-6).map((l) => "    " + l).join("\n")}\n`);
+
+const b = await runFfmpeg("B) fixed args (browser UA + Referer)", buildFfmpegArgs(url, 0));
+console.log(`[B] code=${b.code} signal=${b.signal} killed=${b.killed} bytes=${b.bytes}`);
+console.log(`    stderr-tail:\n${b.stderrTail.split("\n").slice(-6).map((l) => "    " + l).join("\n")}\n`);
+
+const aFailed = a.bytes === 0 && !a.killed && a.code !== 0;
+const bWorked = b.bytes > 100_000; // got real audio bytes
+console.log(`Verdict: legacy ${aFailed ? "FAILED (no bytes, exit code 1)" : "??"} ; fixed ${bWorked ? "WORKED (received audio)" : "??"}`);

src/audio/player.test.ts

@@ -0,0 +1,135 @@
+import { describe, it, expect } from "vitest";
+import { mkdtempSync, writeFileSync, existsSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { buildFfmpegArgs, shouldUsePowerShellDownload, cleanupTempDir } from "./player.js";
+
+function getHeadersArg(args: string[]): string {
+  const idx = args.indexOf("-headers");
+  if (idx === -1) return "";
+  return args[idx + 1] ?? "";
+}
+
+describe("buildFfmpegArgs", () => {
+  it("includes browser User-Agent and Referer for Netease CDN URLs", () => {
+    const url = "http://m701.music.126.net/some/path/song.mp3?vuutv=abc";
+    const args = buildFfmpegArgs(url, 0);
+    const headers = getHeadersArg(args);
+    expect(headers).toContain("User-Agent:");
+    expect(headers).toContain("Mozilla/5.0");
+    expect(headers).toContain("Referer: https://music.163.com/");
+  });
+
+  it("keeps Bilibili Referer + UA for bilibili URLs", () => {
+    const url = "https://upos-sz-mirrorcoso1.bilivideo.com/foo/bar.mp3";
+    const args = buildFfmpegArgs(url, 0);
+    const headers = getHeadersArg(args);
+    expect(headers).toContain("Referer: https://www.bilibili.com");
+    expect(headers).toContain("User-Agent: Mozilla/5.0");
+  });
+
+  it("does not set custom headers for unknown URLs", () => {
+    const url = "https://example.com/song.mp3";
+    const args = buildFfmpegArgs(url, 0);
+    expect(args).not.toContain("-headers");
+  });
+
+  it("includes resilient reconnect flags for all URLs", () => {
+    const args = buildFfmpegArgs("https://example.com/song.mp3", 0);
+    expect(args).toContain("-reconnect");
+    expect(args).toContain("-reconnect_streamed");
+    expect(args).toContain("-reconnect_delay_max");
+    expect(args).toContain("-reconnect_on_network_error");
+    expect(args).toContain("-reconnect_on_http_error");
+    const idx = args.indexOf("-reconnect_delay_max");
+    expect(Number(args[idx + 1])).toBeGreaterThanOrEqual(30);
+  });
+
+  it("inserts -ss before -i when seekSeconds > 0", () => {
+    const args = buildFfmpegArgs("https://example.com/song.mp3", 42);
+    const ssIdx = args.indexOf("-ss");
+    const iIdx = args.indexOf("-i");
+    expect(ssIdx).toBeGreaterThan(-1);
+    expect(args[ssIdx + 1]).toBe("42");
+    expect(ssIdx).toBeLessThan(iIdx);
+  });
+
+  it("does not insert -ss when seekSeconds is 0", () => {
+    const args = buildFfmpegArgs("https://example.com/song.mp3", 0);
+    expect(args).not.toContain("-ss");
+  });
+
+  it("omits HTTP-only flags when input is a local file path", () => {
+    const args = buildFfmpegArgs("C:/temp/song.mp3", 0);
+    expect(args).not.toContain("-reconnect");
+    expect(args).not.toContain("-reconnect_on_network_error");
+    expect(args).not.toContain("-reconnect_on_http_error");
+    expect(args).not.toContain("-headers");
+    expect(args).toContain("-i");
+    expect(args[args.indexOf("-i") + 1]).toBe("C:/temp/song.mp3");
+  });
+
+  it("ends args with the input URL and PCM output spec", () => {
+    const url = "https://example.com/song.mp3";
+    const args = buildFfmpegArgs(url, 0);
+    const iIdx = args.indexOf("-i");
+    expect(args[iIdx + 1]).toBe(url);
+    expect(args).toContain("-f");
+    expect(args).toContain("s16le");
+    expect(args[args.length - 1]).toBe("-");
+  });
+});
+
+describe("shouldUsePowerShellDownload", () => {
+  const jdymusicUrl =
+    "http://m801.music.126.net/20260507/abc/jdymusic/obj/xyz/song.mp3?vuutv=tok";
+  const newCdnUrl =
+    "http://m801.music.126.net/20260507/abc/jd-musicrep-ts/obj/xyz/song.mp3?vuutv=tok";
+  const ymusicUrl =
+    "http://m801.music.126.net/20260507/abc/ymusic/obj/xyz/song.mp3?vuutv=tok";
+
+  it("returns true for /jdymusic/ URL on win32", () => {
+    expect(shouldUsePowerShellDownload(jdymusicUrl, "win32")).toBe(true);
+  });
+
+  it("returns false for /jdymusic/ URL on linux", () => {
+    expect(shouldUsePowerShellDownload(jdymusicUrl, "linux")).toBe(false);
+  });
+
+  it("returns false for /jdymusic/ URL on darwin", () => {
+    expect(shouldUsePowerShellDownload(jdymusicUrl, "darwin")).toBe(false);
+  });
+
+  it("returns false for new-format /jd-musicrep-ts/ URL on win32", () => {
+    expect(shouldUsePowerShellDownload(newCdnUrl, "win32")).toBe(false);
+  });
+
+  it("returns false for /ymusic/ URL on win32", () => {
+    expect(shouldUsePowerShellDownload(ymusicUrl, "win32")).toBe(false);
+  });
+
+  it("returns false for unrelated URLs", () => {
+    expect(shouldUsePowerShellDownload("https://example.com/x.mp3", "win32")).toBe(false);
+  });
+});
+
+describe("cleanupTempDir", () => {
+  it("removes a directory and its contents", () => {
+    const dir = mkdtempSync(join(tmpdir(), "tsbot-test-"));
+    writeFileSync(join(dir, "song.mp3"), "fake-bytes");
+    expect(existsSync(dir)).toBe(true);
+    cleanupTempDir(dir);
+    expect(existsSync(dir)).toBe(false);
+  });
+
+  it("does not throw when directory does not exist", () => {
+    const missing = join(tmpdir(), "tsbot-test-does-not-exist-xyz");
+    expect(() => cleanupTempDir(missing)).not.toThrow();
+  });
+
+  it("does not throw when called twice", () => {
+    const dir = mkdtempSync(join(tmpdir(), "tsbot-test-"));
+    cleanupTempDir(dir);
+    expect(() => cleanupTempDir(dir)).not.toThrow();
+  });
+});

src/audio/player.ts

@@ -1,15 +1,18 @@
 import { spawn, execSync, type ChildProcess } from "node:child_process";
 import { EventEmitter } from "node:events";
 import { createRequire } from "node:module";
-import { accessSync, chmodSync, constants } from "node:fs";
+import { accessSync, chmodSync, constants, mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
 import { createOpusEncoder, PCM_FRAME_BYTES, type Encoder } from "./encoder.js";
 import type { Logger } from "../logger.js";
 
-// ffmpeg-static is a CJS module that exports the path to the bundled ffmpeg binary.
 const require = createRequire(import.meta.url);
 const ffmpegPath: string | null = require("ffmpeg-static");
 
-/** Ensure the given binary has execute permission. */
+/** 全局 PID 追踪器，防止进程在类实例切换时沦为孤儿进程 （ */
+const globalActivePids = new Set<number>();
+
 function isExecutable(binPath: string): boolean {
   try {
     accessSync(binPath, constants.X_OK);
@@ -25,7 +28,6 @@ function isExecutable(binPath: string): boolean {
   }
 }
 
-/** Test if an ffmpeg binary actually works by running -version. */
 function ffmpegWorks(bin: string): boolean {
   try {
     execSync(`"${bin}" -version`, { timeout: 5000, stdio: "pipe" });
@@ -35,43 +37,72 @@ function ffmpegWorks(bin: string): boolean {
   }
 }
 
-/**
- * Resolved once at module load.
- *
- * Priority: system FFmpeg → bundled ffmpeg-static.
- *
- * System-installed FFmpeg is always compatible with the running OS/container,
- * while the pre-compiled binary from ffmpeg-static can SIGSEGV in Docker
- * (passes `ffmpeg -version` but crashes during actual audio processing due to
- * incompatible glibc or missing shared libraries).
- */
 const resolvedFfmpeg: string = (() => {
-  // 1. Prefer system-installed FFmpeg (always compatible with the runtime)
+  if (ffmpegWorks("ffmpeg")) return "ffmpeg";
-  if (ffmpegWorks("ffmpeg")) {
-    return "ffmpeg";
-  }
-
-  // 2. Fall back to bundled ffmpeg-static binary
-  // On Windows, ffmpeg-static may return a path with backslashes; on Linux/macOS
-  // it may return a Windows .exe path if node_modules was copied cross-platform.
   const isWinPath = ffmpegPath ? /\\/.test(ffmpegPath) || ffmpegPath.endsWith(".exe") : false;
   const onWindows = process.platform === "win32";
-
   if (ffmpegPath && (onWindows === isWinPath)) {
-    if (isExecutable(ffmpegPath) && ffmpegWorks(ffmpegPath)) {
+    if (isExecutable(ffmpegPath) && ffmpegWorks(ffmpegPath)) return ffmpegPath;
-      return ffmpegPath;
   }
-  }
-
-  // Last resort: always use "ffmpeg" so spawn error is clear, never use a cross-platform path
   return "ffmpeg";
 })();
 
-/** Resolve ffmpeg binary: prefer system PATH, fall back to bundled ffmpeg-static. */
 function getFfmpegCommand(): string {
   return resolvedFfmpeg;
 }
 
+const BROWSER_UA =
+  "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36";
+
+// Old jdymusic CDN paths (e.g. /jdymusic/obj/...) RST direct Node-stack
+// requests on Windows; same URL works when fetched via WinHTTP. Empirically,
+// /jd-musicrep-ts/ and /ymusic/ paths do not have this restriction.
+export function shouldUsePowerShellDownload(
+  url: string,
+  platform: string = process.platform,
+): boolean {
+  return platform === "win32" && url.includes("/jdymusic/");
+}
+
+export function cleanupTempDir(dir: string): void {
+  try {
+    rmSync(dir, { recursive: true, force: true });
+  } catch {
+    // best-effort
+  }
+}
+
+export function buildFfmpegArgs(url: string, seekSeconds: number): string[] {
+  const args: string[] = [];
+  const isHttp = /^https?:\/\//i.test(url);
+
+  if (isHttp && (url.includes("bilivideo") || url.includes("bilibili"))) {
+    args.push(
+      "-headers",
+      `Referer: https://www.bilibili.com\r\nUser-Agent: ${BROWSER_UA}\r\n`,
+    );
+  } else if (isHttp && (url.includes("music.126.net") || url.includes("music.163.com"))) {
+    args.push(
+      "-headers",
+      `Referer: https://music.163.com/\r\nUser-Agent: ${BROWSER_UA}\r\n`,
+    );
+  }
+
+  if (isHttp) {
+    args.push(
+      "-reconnect", "1",
+      "-reconnect_streamed", "1",
+      "-reconnect_delay_max", "30",
+      "-reconnect_on_network_error", "1",
+      "-reconnect_on_http_error", "4xx,5xx",
+    );
+  }
+  if (seekSeconds > 0) args.push("-ss", String(seekSeconds));
+  args.push("-i", url, "-f", "s16le", "-ar", "48000", "-ac", "2", "-acodec", "pcm_s16le", "-");
+
+  return args;
+}
+
 export interface PlayerEvents {
   frame: (opusFrame: Buffer) => void;
   trackEnd: () => void;
@@ -93,14 +124,18 @@ export class AudioPlayer extends EventEmitter {
   private nextFrameTime = 0;
   private currentUrl = "";
   private seekOffset = 0;
-  private framesPlayed = 0; // ground truth: number of 20ms frames sent
+  private framesPlayed = 0;
   private sessionId = 0;
-  private static readonly BUFFER_HIGH_WATER = 960 * 1024; // ~5s of PCM at 48kHz stereo
+  private static readonly BUFFER_HIGH_WATER = 640 * 1024;
-  private static readonly BUFFER_LOW_WATER = 480 * 1024;  // ~2.5s
+  private static readonly BUFFER_LOW_WATER = 256 * 1024;
   private ffmpegPaused = false;
-  private spawnFailed = false; // true if ffmpeg spawn errored (prevent trackEnd cascade)
+  private spawnFailed = false;
   private consecutiveFailures = 0;
   private static readonly MAX_CONSECUTIVE_FAILURES = 3;
+  private healthyFrames = 0;
+  private static readonly HEALTHY_FRAME_RESET = 50; // ~1 second of audio
+  private downloader: ChildProcess | null = null;
+  private currentTempDir: string | null = null;
 
   constructor(logger: Logger) {
     super();
@@ -109,112 +144,255 @@ export class AudioPlayer extends EventEmitter {
   }
 
   play(url: string, seekSeconds = 0): void {
+    // 1. 停止当前所有播放，自增 sessionId 屏蔽旧回调 （
     this.stop();
-    this.sessionId++;
+
-    const playSessionId = this.sessionId;
+    const currentSessionId = this.sessionId; 
     this.currentUrl = url;
     this.seekOffset = seekSeconds;
     this.framesPlayed = 0;
+    this.healthyFrames = 0;
     this.ffmpegPaused = false;
     this.spawnFailed = false;
 
-    // Prevent rapid-fire spawn attempts when ffmpeg is broken
     if (this.consecutiveFailures >= AudioPlayer.MAX_CONSECUTIVE_FAILURES) {
-      this.logger.error(
+      this.logger.error({ failures: this.consecutiveFailures }, "FFmpeg failures limit reached");
-        { failures: this.consecutiveFailures, ffmpeg: getFfmpegCommand() },
-        "Too many consecutive ffmpeg failures — ffmpeg binary may be missing or broken. Stopping playback."
-      );
       this.state = "idle";
-      this.emit("error", new Error("ffmpeg unavailable after repeated failures"));
+      this.emit("error", new Error("ffmpeg unavailable"));
       return;
     }
 
-    this.logger.info({ url: url.slice(0, 80), seek: seekSeconds }, "Starting playback");
+    if (shouldUsePowerShellDownload(url)) {
-
+      this.playViaPowerShellDownload(url, seekSeconds, currentSessionId);
-    const args: string[] = [];
+      return;
-
-    // BiliBili CDN requires Referer header for audio playback
-    if (url.includes("bilivideo") || url.includes("bilibili")) {
-      args.push(
-        "-headers",
-        "Referer: https://www.bilibili.com\r\nUser-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36\r\n"
-      );
     }
 
-    args.push(
+    const args = buildFfmpegArgs(url, seekSeconds);
-      "-reconnect", "1",
-      "-reconnect_streamed", "1",
-      "-reconnect_delay_max", "5",
-    );
-    if (seekSeconds > 0) {
-      args.push("-ss", String(seekSeconds));
-    }
-    args.push(
-      "-i", url,
-      "-f", "s16le",
-      "-ar", "48000",
-      "-ac", "2",
-      "-acodec", "pcm_s16le",
-      "-",
-    );
 
     const ffmpegBin = getFfmpegCommand();
-    this.logger.info({ ffmpeg: ffmpegBin }, "Using ffmpeg binary");
     this.ffmpeg = spawn(ffmpegBin, args, { stdio: ["ignore", "pipe", "pipe"] });
     
-    // Prevent stream errors from crashing the process
+    const currentPid = this.ffmpeg.pid;
-    this.ffmpeg.stdout!.on("error", (err) => {
+    if (currentPid) {
-      this.logger.warn({ err }, "FFmpeg stdout error");
+      globalActivePids.add(currentPid);
-    });
+      this.logger.debug({ pid: currentPid, sessionId: currentSessionId }, "FFmpeg spawned");
-    this.ffmpeg.stderr!.on("error", (err) => {
-      this.logger.warn({ err }, "FFmpeg stderr error");
-    });
-
-    let gotFirstData = false;
-    this.ffmpeg.stdout!.on("data", (chunk: Buffer) => {
-      if (!gotFirstData) {
-        gotFirstData = true;
-        this.logger.info({ bytes: chunk.length }, "FFmpeg: first PCM data received");
     }
+
+    this.ffmpeg.stdout!.on("data", (chunk: Buffer) => {
+      // 2. 严格校验 sessionId，防止老进程的数据混入新播放请求 （
+      if (this.sessionId !== currentSessionId) {
+        return;
+      }
+
       this.pcmBuffer = Buffer.concat([this.pcmBuffer, chunk]);
-      // Backpressure: pause FFmpeg stdout when buffer is too large
       if (this.pcmBuffer.length > AudioPlayer.BUFFER_HIGH_WATER && !this.ffmpegPaused && this.ffmpeg?.stdout) {
         this.ffmpeg.stdout.pause();
         this.ffmpegPaused = true;
       }
     });
 
-    this.ffmpeg.on("close", (code, signal) => {
+    this.ffmpeg.on("exit", (code, signal) => {
-      this.logger.info({ exitCode: code, signal, gotData: gotFirstData, framesPlayed: this.framesPlayed }, "FFmpeg process closed");
+      if (currentPid) globalActivePids.delete(currentPid);
-      if (this.sessionId === playSessionId) {
+      this.logger.info({ pid: currentPid, code, signal }, "FFmpeg exited");
-        this.ffmpeg = null; // Signal frame loop that no more data is coming
+      
+      // 只有当前会话的进程结束才置空变量
+      if (this.sessionId === currentSessionId) {
+        this.ffmpeg = null;
       }
     });
 
     this.ffmpeg.on("error", (err) => {
-      this.logger.error({ err }, "FFmpeg error");
+      if (this.sessionId === currentSessionId) {
-      if (this.sessionId === playSessionId) {
         this.spawnFailed = true;
         this.consecutiveFailures++;
         this.emit("error", err);
       }
     });
 
-    // Log FFmpeg stderr at info level for debugging playback issues
+    this.state = "playing";
-    this.ffmpeg.stderr!.on("data", (data: Buffer) => {
+    this.startFrameLoop();
-      const msg = data.toString().trimEnd();
-      // Log important FFmpeg messages at info level
-      if (msg.includes("Error") || msg.includes("error") || msg.includes("HTTP") || msg.includes("Opening") || msg.includes("Stream")) {
-        this.logger.info({ ffmpegStderr: msg }, "FFmpeg stderr");
-      } else {
-        this.logger.debug({ stderr: msg }, "FFmpeg stderr");
   }
+
+  private playViaPowerShellDownload(url: string, seekSeconds: number, sessionId: number): void {
+    const tempDir = mkdtempSync(join(tmpdir(), "tsbot-jdymusic-"));
+    const tempFile = join(tempDir, "song.audio");
+    this.currentTempDir = tempDir;
+
+    const psScript = [
+      "$ErrorActionPreference = 'Stop'",
+      "$ProgressPreference = 'SilentlyContinue'",
+      "$wc = New-Object System.Net.WebClient",
+      "$wc.Headers.Add('User-Agent', $env:DL_UA)",
+      "$wc.Headers.Add('Referer', $env:DL_REFERER)",
+      "$wc.DownloadFile($env:DL_URL, $env:DL_OUT)",
+    ].join("; ");
+
+    this.logger.debug({ sessionId, tempFile }, "Downloading via PowerShell (jdymusic CDN)");
+
+    const ps = spawn(
+      "powershell",
+      ["-NoProfile", "-ExecutionPolicy", "Bypass", "-Command", psScript],
+      {
+        env: {
+          ...process.env,
+          DL_URL: url,
+          DL_OUT: tempFile,
+          DL_UA: BROWSER_UA,
+          DL_REFERER: "https://music.163.com/",
+        },
+        stdio: ["ignore", "pipe", "pipe"],
+      },
+    );
+    this.downloader = ps;
+
+    let stderrTail = "";
+    ps.stderr!.on("data", (chunk: Buffer) => {
+      stderrTail = (stderrTail + chunk.toString()).slice(-500);
+    });
+
+    ps.on("exit", (code, signal) => {
+      if (this.sessionId !== sessionId) {
+        cleanupTempDir(tempDir);
+        return;
+      }
+      this.downloader = null;
+      if (code !== 0) {
+        this.logger.warn({ code, signal, stderr: stderrTail }, "PowerShell download failed");
+        this.spawnFailed = true;
+        this.consecutiveFailures++;
+        this.state = "idle";
+        cleanupTempDir(tempDir);
+        this.currentTempDir = null;
+        this.emit("error", new Error(`PowerShell download exited ${code}`));
+        return;
+      }
+      this.spawnFfmpegFromFile(tempFile, seekSeconds, sessionId);
+    });
+
+    ps.on("error", (err) => {
+      if (this.sessionId !== sessionId) return;
+      this.downloader = null;
+      this.spawnFailed = true;
+      this.consecutiveFailures++;
+      cleanupTempDir(tempDir);
+      this.currentTempDir = null;
+      this.emit("error", err);
     });
 
     this.state = "playing";
     this.startFrameLoop();
   }
 
+  private spawnFfmpegFromFile(tempFile: string, seekSeconds: number, sessionId: number): void {
+    if (this.sessionId !== sessionId) {
+      if (this.currentTempDir) {
+        cleanupTempDir(this.currentTempDir);
+        this.currentTempDir = null;
+      }
+      return;
+    }
+
+    const args = buildFfmpegArgs(tempFile, seekSeconds);
+    const ffmpegBin = getFfmpegCommand();
+    this.ffmpeg = spawn(ffmpegBin, args, { stdio: ["ignore", "pipe", "pipe"] });
+
+    const currentPid = this.ffmpeg.pid;
+    if (currentPid) {
+      globalActivePids.add(currentPid);
+      this.logger.debug({ pid: currentPid, sessionId }, "FFmpeg spawned (from temp file)");
+    }
+    const tempDirToCleanup = this.currentTempDir;
+
+    this.ffmpeg.stdout!.on("data", (chunk: Buffer) => {
+      if (this.sessionId !== sessionId) return;
+      this.pcmBuffer = Buffer.concat([this.pcmBuffer, chunk]);
+      if (this.pcmBuffer.length > AudioPlayer.BUFFER_HIGH_WATER && !this.ffmpegPaused && this.ffmpeg?.stdout) {
+        this.ffmpeg.stdout.pause();
+        this.ffmpegPaused = true;
+      }
+    });
+
+    this.ffmpeg.on("exit", (code, signal) => {
+      if (currentPid) globalActivePids.delete(currentPid);
+      this.logger.info({ pid: currentPid, code, signal }, "FFmpeg exited");
+      if (this.sessionId === sessionId) {
+        this.ffmpeg = null;
+        if (this.currentTempDir === tempDirToCleanup) this.currentTempDir = null;
+      }
+      if (tempDirToCleanup) cleanupTempDir(tempDirToCleanup);
+    });
+
+    this.ffmpeg.on("error", (err) => {
+      if (this.sessionId === sessionId) {
+        this.spawnFailed = true;
+        this.consecutiveFailures++;
+        this.emit("error", err);
+      }
+    });
+  }
+
+  stop(): void {
+    // 3. 递增 ID 是最有效的逻辑“隔离墙”
+    this.sessionId++; 
+    this.frameLoopRunning = false;
+    
+    // 立即清空缓冲区，确保切歌瞬间静音 （
+    this.pcmBuffer = Buffer.alloc(0);
+
+    if (this.ffmpeg) {
+      const procToKill = this.ffmpeg;
+      const pidToKill = procToKill.pid;
+      this.ffmpeg = null;
+
+      if (pidToKill) {
+        this.forceCleanup(procToKill, pidToKill);
+      }
+    }
+
+    if (this.downloader) {
+      const ps = this.downloader;
+      this.downloader = null;
+      try { ps.kill("SIGTERM"); } catch { /* already gone */ }
+    }
+
+    if (this.currentTempDir) {
+      cleanupTempDir(this.currentTempDir);
+      this.currentTempDir = null;
+    }
+
+    this.ffmpegPaused = false;
+    this.spawnFailed = false;
+    this.state = "idle";
+    this.currentUrl = "";
+    this.seekOffset = 0;
+    this.framesPlayed = 0;
+    this.healthyFrames = 0;
+  }
+
+  private forceCleanup(proc: ChildProcess, pid: number): void {
+    if (!globalActivePids.has(pid)) return;
+
+    try {
+      proc.kill("SIGTERM");
+    } catch (e) { /* ignore */ }
+
+    const killTimeout = setTimeout(() => {
+      try {
+        process.kill(pid, 0); 
+        process.kill(pid, "SIGKILL");
+      } catch (e) {
+      } finally {
+        globalActivePids.delete(pid);
+      }
+    }, 1500);
+
+    proc.unref();
+    proc.once("exit", () => {
+      clearTimeout(killTimeout);
+      globalActivePids.delete(pid);
+    });
+  }
+
   private startFrameLoop(): void {
     if (this.frameLoopRunning) return;
     this.frameLoopRunning = true;
@@ -224,50 +402,37 @@ export class AudioPlayer extends EventEmitter {
 
   private scheduleNextFrame(): void {
     if (!this.frameLoopRunning) return;
-
     const loopSessionId = this.sessionId;
-
     this.nextFrameTime += FRAME_DURATION_MS;
-    const now = performance.now();
+    const delay = Math.max(0, this.nextFrameTime - performance.now());
-    const delay = Math.max(0, this.nextFrameTime - now);
 
     setTimeout(() => {
-      // Discard callback from a stale play session
+      // 这里的校验能防止旧的定时器回调处理新 Session 的逻辑 （
-      if (loopSessionId !== this.sessionId) return;
+      if (loopSessionId !== this.sessionId || !this.frameLoopRunning) return;
-      if (!this.frameLoopRunning) return;
 
-      if (this.state === "playing") {
+      if (this.state === "playing") this.sendNextFrame();
-        this.sendNextFrame();
+      else if (this.state === "paused") this.nextFrameTime = performance.now();
-      } else if (this.state === "paused") {
-        this.nextFrameTime = performance.now();
-      }
 
       if (!this.ffmpeg && this.pcmBuffer.length < PCM_FRAME_BYTES) {
         this.frameLoopRunning = false;
         if (this.state !== "idle") {
           this.state = "idle";
-          // Don't emit trackEnd if ffmpeg spawn failed — prevents infinite retry cascade
+          if (!this.spawnFailed) {
-          if (this.spawnFailed) {
+            this.consecutiveFailures = 0;
-            this.logger.warn("Suppressing trackEnd due to ffmpeg spawn failure");
-          } else {
-            this.consecutiveFailures = 0; // Reset on successful track completion
             this.emit("trackEnd");
           }
         }
         return;
       }
-
       this.scheduleNextFrame();
     }, delay);
   }
 
   private sendNextFrame(): void {
     if (this.pcmBuffer.length < PCM_FRAME_BYTES) return;
-
     const pcmFrame = this.pcmBuffer.subarray(0, PCM_FRAME_BYTES);
     this.pcmBuffer = this.pcmBuffer.subarray(PCM_FRAME_BYTES);
 
-    // Backpressure: resume FFmpeg stdout when buffer drains below low-water mark
     if (this.ffmpegPaused && this.pcmBuffer.length < AudioPlayer.BUFFER_LOW_WATER && this.ffmpeg?.stdout) {
       this.ffmpeg.stdout.resume();
       this.ffmpegPaused = false;
@@ -278,101 +443,33 @@ export class AudioPlayer extends EventEmitter {
       const opusFrame = this.encoder.encode(adjusted);
       this.emit("frame", opusFrame);
       this.framesPlayed++;
-
+      this.healthyFrames++;
-      if (this.framesPlayed === 1) {
+      if (this.healthyFrames >= AudioPlayer.HEALTHY_FRAME_RESET) {
-        this.logger.info({ opusBytes: opusFrame.length }, "First audio frame encoded and emitted");
+        this.consecutiveFailures = 0;
-      }
+        this.healthyFrames = 0;
-      // Log every ~10 seconds (500 frames * 20ms = 10s)
-      if (this.framesPlayed % 500 === 0) {
-        this.logger.debug({ framesPlayed: this.framesPlayed, elapsed: this.getElapsed() }, "Playback progress");
       }
     } catch (err) {
-      this.logger.error({ err }, "Error encoding/sending audio frame");
       this.emit("error", err as Error);
     }
   }
 
   private applyVolume(pcm: Buffer): Buffer {
     if (this.volume === 100) return Buffer.from(pcm);
-    const factor = this.volume / 100;
+    const factor = (this.volume / 100) * 0.2;
     const out = Buffer.alloc(pcm.length);
     for (let i = 0; i < pcm.length; i += 2) {
-      let sample = pcm.readInt16LE(i);
+      let sample = Math.round(pcm.readInt16LE(i) * factor);
-      sample = Math.round(sample * factor);
+      out.writeInt16LE(Math.max(-32768, Math.min(32767, sample)), i);
-      if (sample > 32767) sample = 32767;
-      else if (sample < -32768) sample = -32768;
-      out.writeInt16LE(sample, i);
     }
     return out;
   }
 
-  /** Actual elapsed time in seconds (ground truth from frame count) */
+  getElapsed(): number { return this.seekOffset + (this.framesPlayed * FRAME_DURATION_MS) / 1000; }
-  getElapsed(): number {
+  seek(seconds: number): void { if (this.currentUrl && Number.isFinite(seconds) && seconds >= 0) this.play(this.currentUrl, seconds); }
-    return this.seekOffset + (this.framesPlayed * FRAME_DURATION_MS) / 1000;
+  pause(): void { if (this.state === "playing") this.state = "paused"; }
-  }
+  resume(): void { if (this.state === "paused") { this.state = "playing"; this.nextFrameTime = performance.now(); } }
-
+  resetFailures(): void { this.consecutiveFailures = 0; }
-  seek(seconds: number): void {
+  setVolume(vol: number): void { this.volume = Math.max(0, Math.min(100, vol)); }
-    if (!this.currentUrl) return;
+  getVolume(): number { return this.volume; }
-    // Reject NaN/Infinity/negative — the HTTP layer validates too, but a
+  getState(): PlayerState { return this.state; }
-    // bad value here would poison seekOffset and leave getElapsed()
-    // returning NaN until the track ends.
-    if (!Number.isFinite(seconds) || seconds < 0) {
-      this.logger.warn({ seek: seconds }, "Ignoring invalid seek position");
-      return;
-    }
-    this.logger.info({ seek: seconds }, "Seeking");
-    this.play(this.currentUrl, seconds);
-  }
-
-  getSeekOffset(): number {
-    return this.seekOffset;
-  }
-
-  pause(): void {
-    if (this.state === "playing") {
-      this.state = "paused";
-      this.logger.debug("Playback paused");
-    }
-  }
-
-  resume(): void {
-    if (this.state === "paused") {
-      this.state = "playing";
-      this.nextFrameTime = performance.now();
-      this.logger.debug("Playback resumed");
-    }
-  }
-
-  stop(): void {
-    this.sessionId++;
-    this.frameLoopRunning = false;
-    if (this.ffmpeg) {
-      this.ffmpeg.kill("SIGTERM");
-      this.ffmpeg = null;
-    }
-    this.pcmBuffer = Buffer.alloc(0);
-    this.ffmpegPaused = false;
-    this.spawnFailed = false;
-    this.state = "idle";
-    this.currentUrl = "";
-    this.seekOffset = 0;
-    this.framesPlayed = 0;
-  }
-
-  /** Reset the consecutive failure counter (e.g. after user action) */
-  resetFailures(): void {
-    this.consecutiveFailures = 0;
-  }
-
-  setVolume(vol: number): void {
-    this.volume = Math.max(0, Math.min(100, vol));
-  }
-
-  getVolume(): number {
-    return this.volume;
-  }
-
-  getState(): PlayerState {
-    return this.state;
-  }
 }

src/audio/queue.test.ts

@@ -261,4 +261,227 @@ describe("PlayQueue", () => {
     queue.playAt(2);
     expect(queue.current()?.id).toBe("3");
   });
+
+  describe("history-aware prev", () => {
+    it("walks back through played indices in random mode", () => {
+      queue.setMode(PlayMode.Random);
+      queue.add(makeSong("a"));
+      queue.add(makeSong("b"));
+      queue.add(makeSong("c"));
+      queue.add(makeSong("d"));
+      queue.add(makeSong("e"));
+
+      // Force a deterministic random sequence: a → c → e
+      queue.playAt(0);
+      queue.playAt(2);
+      queue.playAt(4);
+      expect(queue.current()?.id).toBe("e");
+
+      // prev pops back through history: e → c → a
+      expect(queue.prev()?.id).toBe("c");
+      expect(queue.prev()?.id).toBe("a");
+    });
+
+    it("returns null when history is empty in random mode", () => {
+      queue.setMode(PlayMode.Random);
+      queue.add(makeSong("a"));
+      queue.add(makeSong("b"));
+      queue.playAt(0);
+      // No further moves → history is empty (only 'a' is current, never pushed)
+      expect(queue.prev()).toBeNull();
+    });
+
+    it("preserves sequential prev when history is empty", () => {
+      queue.setMode(PlayMode.Sequential);
+      queue.add(makeSong("a"));
+      queue.add(makeSong("b"));
+      queue.add(makeSong("c"));
+      queue.play();
+      queue.next(); // currentIndex = 1
+      // Sequential next() pushed 0 to history → prev pops back to 0
+      expect(queue.prev()?.id).toBe("a");
+    });
+
+    it("clears history on play()", () => {
+      queue.setMode(PlayMode.Random);
+      queue.add(makeSong("a"));
+      queue.add(makeSong("b"));
+      queue.playAt(0);
+      queue.playAt(1);
+      queue.play(); // resets to index 0 and clears history
+      expect(queue.prev()).toBeNull();
+    });
+
+    it("clears history on clear()", () => {
+      queue.add(makeSong("a"));
+      queue.add(makeSong("b"));
+      queue.play();
+      queue.next();
+      queue.clear();
+      queue.add(makeSong("c"));
+      queue.play();
+      // History was wiped — no prev path available beyond index 0
+      expect(queue.prev()).toBeNull();
+    });
+
+    it("clears history on setMode()", () => {
+      queue.setMode(PlayMode.Sequential);
+      queue.add(makeSong("a"));
+      queue.add(makeSong("b"));
+      queue.play();
+      queue.next();
+      // Mode change resets context
+      queue.setMode(PlayMode.Random);
+      expect(queue.prev()).toBeNull();
+    });
+
+    it("drops history entries pointing at a removed song", () => {
+      queue.setMode(PlayMode.Random);
+      queue.add(makeSong("a"));
+      queue.add(makeSong("b"));
+      queue.add(makeSong("c"));
+      queue.playAt(0);
+      queue.playAt(1); // history: [0]
+      queue.playAt(2); // history: [0, 1]
+      // Remove song at index 1 → history entry 1 dropped
+      queue.remove(1);
+      // queue is now [a, c], history should be [0]
+      // current was at 2 → after remove shifts to 1 → song "c"
+      expect(queue.current()?.id).toBe("c");
+      expect(queue.prev()?.id).toBe("a");
+    });
+
+    it("does not push to history on prev itself", () => {
+      queue.setMode(PlayMode.Random);
+      queue.add(makeSong("a"));
+      queue.add(makeSong("b"));
+      queue.add(makeSong("c"));
+      queue.playAt(0);
+      queue.playAt(1);
+      queue.playAt(2); // history: [0, 1]
+      queue.prev();    // pops 1, history: [0]
+      queue.prev();    // pops 0, history: []
+      expect(queue.prev()).toBeNull(); // no fallback target in random mode
+    });
+
+    it("caps history at HISTORY_LIMIT (50) entries, dropping oldest", () => {
+      queue.setMode(PlayMode.Random);
+      // Build a queue large enough to overflow HISTORY_LIMIT
+      for (let i = 0; i < 60; i++) queue.add(makeSong(`s${i}`));
+      // Walk through 60 explicit picks → 59 pushes to history
+      // (playAt pushes the previous currentIndex; first call has -1
+      // which pushHistory rejects). After 60 playAts, history holds
+      // the last 50 of those 59 entries.
+      for (let i = 0; i < 60; i++) queue.playAt(i);
+
+      // Walk back through history. The first prev returns whatever the
+      // 50th-most-recent push was (= index 9, since pushes 0..58 happened
+      // and the oldest 9 fell off). We can verify by counting prevs that
+      // succeed before history exhausts and prev returns null in random.
+      let count = 0;
+      while (queue.prev() !== null) {
+        count++;
+        if (count > 100) break; // safety
+      }
+      expect(count).toBe(50);
+    });
+  });
+
+  describe("addNext", () => {
+    it("appends when queue is empty (no current)", () => {
+      queue.addNext(makeSong("a"));
+      expect(queue.size()).toBe(1);
+      expect(queue.list()[0].id).toBe("a");
+    });
+
+    it("appends when nothing is currently playing (currentIndex < 0)", () => {
+      queue.add(makeSong("a"));
+      queue.add(makeSong("b"));
+      // No play() yet → currentIndex still -1
+      queue.addNext(makeSong("c"));
+      expect(queue.list().map((s) => s.id)).toEqual(["a", "b", "c"]);
+    });
+
+    it("inserts at currentIndex+1 mid-queue", () => {
+      queue.add(makeSong("a"));
+      queue.add(makeSong("b"));
+      queue.add(makeSong("c"));
+      queue.add(makeSong("d"));
+      queue.play();      // current = 0 (a)
+      queue.next();      // current = 1 (b)
+      queue.addNext(makeSong("x"));
+      expect(queue.list().map((s) => s.id)).toEqual(["a", "b", "x", "c", "d"]);
+      expect(queue.current()?.id).toBe("b"); // current unchanged
+    });
+
+    it("makes the inserted song play next when next() is called", () => {
+      queue.setMode(PlayMode.Sequential);
+      queue.add(makeSong("a"));
+      queue.add(makeSong("b"));
+      queue.play();      // current = 0 (a)
+      queue.addNext(makeSong("x"));
+      expect(queue.next()?.id).toBe("x");
+    });
+
+    it("shifts playedIndices entries > currentIndex by +1", () => {
+      queue.setMode(PlayMode.Random);
+      queue.add(makeSong("a"));
+      queue.add(makeSong("b"));
+      queue.add(makeSong("c"));
+      queue.add(makeSong("d"));
+      queue.playAt(2); // current = 2 (c), played = {2}
+      queue.playAt(3); // current = 3 (d), played = {2, 3}
+      queue.playAt(2); // current = 2 (c), played = {2, 3}
+      // Now insert after c — d's index 3 should become 4
+      queue.addNext(makeSong("x"));
+      expect(queue.list().map((s) => s.id)).toEqual(["a", "b", "c", "x", "d"]);
+      // After addNext: currentIndex still 2; played should be {2, 4}
+      // (the previously-played 'd' is now at index 4)
+      // Verify by removing 'x' (index 3) — d should remain played at index 3
+      queue.remove(3);
+      expect(queue.list().map((s) => s.id)).toEqual(["a", "b", "c", "d"]);
+    });
+
+    it("shifts history entries > currentIndex by +1", () => {
+      queue.setMode(PlayMode.Random);
+      queue.add(makeSong("a"));
+      queue.add(makeSong("b"));
+      queue.add(makeSong("c"));
+      queue.add(makeSong("d"));
+      queue.playAt(0); // current = 0
+      queue.playAt(3); // current = 3 (d), history = [0]
+      queue.playAt(1); // current = 1 (b), history = [0, 3]
+      queue.addNext(makeSong("x"));
+      // Insert at index 2 → entries > 1 shift +1 → history becomes [0, 4]
+      // queue: [a, b, x, c, d]; d is now at index 4
+      // prev → pop 4 → song at index 4 = d
+      expect(queue.prev()?.id).toBe("d");
+      // prev again → pop 0 → song at index 0 = a
+      expect(queue.prev()?.id).toBe("a");
+    });
+
+    it("idle player + stale currentIndex: insertion target is currentIndex+1, not size-1", () => {
+      // Reproduces the scenario where the player has gone idle but the
+      // queue still has a non-negative currentIndex (e.g., after natural
+      // track end without queue.clear()).
+      queue.add(makeSong("a"));
+      queue.add(makeSong("b"));
+      queue.add(makeSong("c"));
+      queue.add(makeSong("d"));
+      queue.play();      // current = 0 (a)
+      queue.next();      // current = 1 (b)
+      // Simulate idle-with-stale-currentIndex: the player has gone idle
+      // but queue still points at b.
+      // Caller pre-captures insertedAt:
+      const insertedAt = queue.getCurrentIndex() + 1; // = 2
+      queue.addNext(makeSong("x"));
+      // queue is now [a, b, x, c, d]
+      // size-1 would be 4 (d) — WRONG.
+      // insertedAt is 2 (x) — RIGHT.
+      expect(queue.list().map((s) => s.id)).toEqual(["a", "b", "x", "c", "d"]);
+      expect(queue.size() - 1).toBe(4); // proves size-1 strategy would pick d
+      const promoted = queue.playAt(insertedAt);
+      expect(promoted?.id).toBe("x");
+    });
+  });
 });

src/audio/queue.ts

@@ -21,6 +21,16 @@ export class PlayQueue {
   private currentIndex = -1;
   private mode: PlayMode = PlayMode.Sequential;
   private playedIndices = new Set<number>();
+  private history: number[] = [];
+  private static readonly HISTORY_LIMIT = 50;
+
+  private pushHistory(idx: number): void {
+    if (idx < 0 || idx >= this.songs.length) return;
+    this.history.push(idx);
+    if (this.history.length > PlayQueue.HISTORY_LIMIT) {
+      this.history.shift();
+    }
+  }
 
   add(song: QueuedSong): void {
     this.songs.push(song);
@@ -30,6 +40,34 @@ export class PlayQueue {
     this.songs.push(...songs);
   }
 
+  /**
+   * Insert a song to play immediately after the current one. Falls
+   * through to plain push when nothing is playing yet (currentIndex < 0
+   * or queue empty), so the existing "add → idle bot starts playing"
+   * flow continues to work.
+   *
+   * Shifts playedIndices and history entries > currentIndex by +1 so
+   * their references stay valid after the splice.
+   */
+  addNext(song: QueuedSong): void {
+    if (this.currentIndex < 0 || this.songs.length === 0) {
+      this.songs.push(song);
+      return;
+    }
+    const insertAt = this.currentIndex + 1;
+    this.songs.splice(insertAt, 0, song);
+
+    const shifted = new Set<number>();
+    for (const i of this.playedIndices) {
+      shifted.add(i > this.currentIndex ? i + 1 : i);
+    }
+    this.playedIndices = shifted;
+
+    this.history = this.history.map((i) =>
+      i > this.currentIndex ? i + 1 : i,
+    );
+  }
+
   remove(index: number): QueuedSong | null {
     if (index < 0 || index >= this.songs.length) return null;
     const [removed] = this.songs.splice(index, 1);
@@ -48,6 +86,12 @@ export class PlayQueue {
     }
     this.playedIndices = newPlayed;
 
+    // Same shift logic for history — drop entries pointing at the
+    // removed song; shift entries > index down by 1.
+    this.history = this.history
+      .filter((idx) => idx !== index)
+      .map((idx) => (idx > index ? idx - 1 : idx));
+
     return removed;
   }
 
@@ -55,11 +99,13 @@ export class PlayQueue {
     this.songs = [];
     this.currentIndex = -1;
     this.playedIndices.clear();
+    this.history = [];
   }
 
   play(): QueuedSong | null {
     if (this.songs.length === 0) return null;
     this.playedIndices.clear();
+    this.history = [];
     this.currentIndex = 0;
     this.playedIndices.add(0);
     return this.songs[0];
@@ -67,6 +113,10 @@ export class PlayQueue {
 
   playAt(index: number): QueuedSong | null {
     if (index < 0 || index >= this.songs.length) return null;
+    this.pushHistory(this.currentIndex);
+    // Reset the Random-mode "unplayed" pool — explicit picks restart
+    // shuffle from this point. History tracking is independent and
+    // unaffected by this clear.
     this.playedIndices.clear();
     this.currentIndex = index;
     this.playedIndices.add(index);
@@ -80,10 +130,12 @@ export class PlayQueue {
       case PlayMode.Sequential: {
         const nextIndex = this.currentIndex + 1;
         if (nextIndex >= this.songs.length) return null;
+        this.pushHistory(this.currentIndex);
         this.currentIndex = nextIndex;
         return this.songs[nextIndex];
       }
       case PlayMode.Loop: {
+        this.pushHistory(this.currentIndex);
         this.currentIndex = (this.currentIndex + 1) % this.songs.length;
         return this.songs[this.currentIndex];
       }
@@ -95,12 +147,14 @@ export class PlayQueue {
         if (unplayed.length === 0) return null;
         const nextIndex =
           unplayed[Math.floor(Math.random() * unplayed.length)];
+        this.pushHistory(this.currentIndex);
         this.currentIndex = nextIndex;
         this.playedIndices.add(nextIndex);
         return this.songs[nextIndex];
       }
       case PlayMode.RandomLoop: {
         if (this.songs.length === 1) {
+          this.pushHistory(this.currentIndex);
           this.currentIndex = 0;
           return this.songs[0];
         }
@@ -108,6 +162,7 @@ export class PlayQueue {
         do {
           idx = Math.floor(Math.random() * this.songs.length);
         } while (idx === this.currentIndex);
+        this.pushHistory(this.currentIndex);
         this.currentIndex = idx;
         return this.songs[idx];
       }
@@ -116,9 +171,27 @@ export class PlayQueue {
 
   prev(): QueuedSong | null {
     if (this.songs.length === 0) return null;
+
+    // Preferred: pop from the back-stack so prev means "the song I
+    // actually played before this one," not "the previous array slot."
+    while (this.history.length > 0) {
+      const idx = this.history.pop()!;
+      if (idx >= 0 && idx < this.songs.length) {
+        this.currentIndex = idx;
+        this.playedIndices.add(idx);
+        return this.songs[idx];
+      }
+      // Stale entry (song removed) — keep popping.
+    }
+
+    // Fallback: no history to walk back through. In Sequential we
+    // can still meaningfully step the index backward; in random
+    // modes there's nothing useful to return.
+    if (this.mode === PlayMode.Random || this.mode === PlayMode.RandomLoop) {
+      return null;
+    }
     const prevIndex = this.currentIndex - 1;
     if (prevIndex < 0) {
-      // In Sequential mode, don't wrap around
       if (this.mode === PlayMode.Sequential) return null;
       this.currentIndex = this.songs.length - 1;
     } else {
@@ -153,6 +226,7 @@ export class PlayQueue {
   setMode(mode: PlayMode): void {
     this.mode = mode;
     this.playedIndices.clear();
+    this.history = [];
     if (this.currentIndex >= 0) {
       this.playedIndices.add(this.currentIndex);
     }
@@ -161,4 +235,9 @@ export class PlayQueue {
   getCurrentIndex(): number {
     return this.currentIndex;
   }
+
+  /** Number of songs not yet played in Random mode. */
+  unplayedCount(): number {
+    return this.songs.length - this.playedIndices.size;
+  }
 }

src/bot/commands.ts

@@ -8,6 +8,7 @@ export interface ParsedCommand {
 export const PUBLIC_COMMANDS = new Set([
   "play", "add", "queue", "list", "now", "lyrics", "vote", "help",
   "playlist", "album", "fm", "prev", "next", "skip", "pause", "resume",
+  "artist",
 ]);
 
 export const ADMIN_COMMANDS = new Set([

src/bot/instance.ts

@@ -16,6 +16,7 @@ import type { Logger } from "../logger.js";
 import type { BotDatabase, ProfileConfig } from "../data/database.js";
 import type { BotConfig } from "../data/config.js";
 import { BotProfileManager } from "./profile.js";
+import type { AvatarStore } from "../data/avatars.js";
 
 export interface BotInstanceOptions {
   id: string;
@@ -28,6 +29,7 @@ export interface BotInstanceOptions {
   database: BotDatabase;
   config: BotConfig;
   logger: Logger;
+  avatarStore: AvatarStore;
 }
 
 export interface BotStatus {
@@ -57,11 +59,15 @@ export class BotInstance extends EventEmitter {
   private database: BotDatabase;
   private config: BotConfig;
   private logger: Logger;
+  private avatarStore: AvatarStore;
   private connected = false;
   private disconnectEmitted = false;
   private voteSkipUsers = new Set<string>();
   private isAdvancing = false;
+  private idleTimer: ReturnType<typeof setTimeout> | null = null;
+  private channelUserCount = 0;
   private profileManager: BotProfileManager;
+  private isFmMode = false;
 
   constructor(options: BotInstanceOptions) {
     super();
@@ -74,6 +80,7 @@ export class BotInstance extends EventEmitter {
     this.database = options.database;
     this.config = options.config;
     this.logger = options.logger.child({ botId: this.id });
+    this.avatarStore = options.avatarStore;
 
     this.tsClient = new TS3Client(options.tsOptions, this.logger);
     this.player = new AudioPlayer(this.logger);
@@ -87,6 +94,17 @@ export class BotInstance extends EventEmitter {
       options.tsOptions.nickname,
     );
 
+    // Best-effort: a corrupted/locked avatar file must not block bot startup.
+    try {
+      const relPath = this.database.getCustomAvatarPath(this.id);
+      if (relPath) {
+        const buf = this.avatarStore.read(relPath);
+        if (buf) this.profileManager.setCustomAvatar(buf);
+      }
+    } catch (err) {
+      this.logger.warn({ err }, "Failed to load custom avatar — skipping");
+    }
+
     this.setupPlayerEvents();
     this.setupTsEvents();
   }
@@ -131,6 +149,10 @@ export class BotInstance extends EventEmitter {
       this.disconnectEmitted = true;
       this.emit("disconnected");
     });
+
+    this.tsClient.on("connected", () => {
+      this._startIdlePoller();
+    });
   }
 
   async connect(): Promise<void> {
@@ -149,6 +171,7 @@ export class BotInstance extends EventEmitter {
   }
 
   disconnect(): void {
+    this._cancelIdleTimer();
     this.player.stop();
     this.connected = false;
     if (!this.disconnectEmitted) {
@@ -158,6 +181,48 @@ export class BotInstance extends EventEmitter {
     this.tsClient.disconnect();
   }
 
+  /** 外部更新 idleTimeoutMinutes（由 API 保存时调用） */
+  updateIdleTimeout(minutes: number): void {
+    this.config.idleTimeoutMinutes = minutes;
+    if (minutes === 0) this._cancelIdleTimer();
+  }
+
+  private _startIdlePoller(): void {
+    // 每 30 秒检查一次频道人数
+    const poll = async () => {
+      if (!this.connected) return;
+      try {
+        const clients = await this.tsClient.getClientsInChannel();
+        const userCount = clients.length - 1; // 排除 bot 自身
+        if (userCount <= 0) {
+          this._scheduleIdleCheck();
+        } else {
+          this._cancelIdleTimer();
+        }
+      } catch { /* ignore */ }
+      setTimeout(poll, 30_000);
+    };
+    setTimeout(poll, 30_000);
+  }
+
+  private _scheduleIdleCheck(): void {
+    if (this.idleTimer !== null) return; // 已经在倒计时，不重复创建
+    const minutes = this.config.idleTimeoutMinutes ?? 0;
+    if (!this.connected || minutes <= 0) return;
+    this.idleTimer = setTimeout(() => {
+      if (!this.connected) return;
+      this.logger.info({ idleMinutes: minutes }, "Channel empty, disconnecting due to idle timeout");
+      this.disconnect();
+    }, minutes * 60 * 1000);
+  }
+
+  private _cancelIdleTimer(): void {
+    if (this.idleTimer) {
+      clearTimeout(this.idleTimer);
+      this.idleTimer = null;
+    }
+  }
+
   private async handleTextMessage(msg: TS3TextMessage): Promise<void> {
     const parsed = parseCommand(
       msg.message,
@@ -204,12 +269,15 @@ export class BotInstance extends EventEmitter {
     const AUDIO_COMMANDS = new Set([
       "play",
       "add",
+      "playnext",
+      "pn",
       "next",
       "skip",
       "prev",
       "playlist",
       "album",
       "fm",
+      "artist",
     ]);
     if (!this.connected && AUDIO_COMMANDS.has(cmd.name)) {
       throw new Error("Bot is not connected to TeamSpeak");
@@ -219,6 +287,9 @@ export class BotInstance extends EventEmitter {
         return this.cmdPlay(cmd);
       case "add":
         return this.cmdAdd(cmd);
+      case "playnext":
+      case "pn":
+        return this.cmdPlayNext(cmd);
       case "pause":
         return this.cmdPause();
       case "resume":
@@ -249,6 +320,8 @@ export class BotInstance extends EventEmitter {
         return this.cmdAlbum(cmd);
       case "fm":
         return this.cmdFm();
+      case "artist":
+        return this.cmdArtist(cmd);
       case "vote":
         return this.cmdVote(msg);
       case "lyrics":
@@ -338,6 +411,7 @@ export class BotInstance extends EventEmitter {
 
     const song = result.songs[0];
     this.queue.clear();
+    this.isFmMode = false;
     this.queue.add({ ...song, platform: provider.platform });
     this.queue.play();
 
@@ -374,6 +448,39 @@ export class BotInstance extends EventEmitter {
     return `Added to queue: ${song.name} - ${song.artist} (position ${this.queue.size()})`;
   }
 
+  private async cmdPlayNext(cmd: ParsedCommand): Promise<string> {
+    if (!cmd.args) return "Usage: !playnext <song name>";
+    const provider = this.getProvider(cmd.flags);
+    const result = await provider.search(cmd.args, 1);
+    if (result.songs.length === 0)
+      return `No results found for: ${cmd.args}`;
+
+    const song = result.songs[0];
+    const wasIdle = this.player.getState() === "idle";
+    // Capture the slot addNext WILL insert at, before mutating the queue.
+    // addNext pushes when currentIndex<0 (slot = size); otherwise splices
+    // at currentIndex+1. Using size-1 after addNext was wrong when the
+    // queue had stale currentIndex>=0 while the player was idle (e.g.,
+    // after natural track end without queue.clear()).
+    const insertedAt =
+      this.queue.getCurrentIndex() < 0
+        ? this.queue.size()
+        : this.queue.getCurrentIndex() + 1;
+    this.queue.addNext({ ...song, platform: provider.platform });
+
+    if (wasIdle) {
+      this.queue.playAt(insertedAt);
+      this.player.resetFailures();
+      const ok = await this.resolveAndPlay(this.queue.current()!);
+      this.emit("stateChange");
+      if (!ok) return `Cannot play: ${song.name}`;
+      return `Now playing: ${song.name} - ${song.artist}`;
+    }
+
+    this.emit("stateChange");
+    return `Up next: ${song.name} - ${song.artist}`;
+  }
+
   private cmdPause(): string {
     this.player.pause();
     this.emit("stateChange");
@@ -389,6 +496,7 @@ export class BotInstance extends EventEmitter {
   private cmdStop(): string {
     this.player.stop();
     this.queue.clear();
+    this.isFmMode = false;
     this.profileManager.onSongChange(null).catch((err) => {
       this.logger.warn({ err }, "Profile restore failed on stop");
     });
@@ -405,13 +513,17 @@ export class BotInstance extends EventEmitter {
   }
 
   private async cmdPrev(): Promise<string> {
+    // Retry-skip up to 4 attempts: history can include failed songs
+    // that playNext's auto-advance retry-skipped past, so a single
+    // prev would otherwise land on an unplayable song and leave the
+    // queue's currentIndex stuck mid-failure.
+    for (let i = 0; i < 4; i++) {
       const prev = this.queue.prev();
-    if (prev) {
+      if (!prev) return "No previous song";
       const ok = await this.resolveAndPlay(prev);
-      if (!ok) return "Cannot play previous song";
+      if (ok) return `Now playing: ${prev.name} - ${prev.artist}`;
-      return `Now playing: ${prev.name} - ${prev.artist}`;
     }
-    return "No previous song";
+    return "Cannot play any previous songs (all failed to resolve)";
   }
 
   private cmdVol(cmd: ParsedCommand): string {
@@ -442,6 +554,7 @@ export class BotInstance extends EventEmitter {
   private cmdClear(): string {
     this.player.stop();
     this.queue.clear();
+    this.isFmMode = false;
     this.profileManager.onSongChange(null).catch((err) => {
       this.logger.warn({ err }, "Profile restore failed on clear");
     });
@@ -473,13 +586,48 @@ export class BotInstance extends EventEmitter {
   }
 
   private async cmdPlaylist(cmd: ParsedCommand): Promise<string> {
-    if (!cmd.args) return "Usage: !playlist <playlist ID or URL>";
+    if (!cmd.args) return "Usage: !playlist <playlist name or ID>";
     const provider = this.getProvider(cmd.flags);
+
+    // Determine if input is a numeric ID or a name search
     const id = this.extractId(cmd.args);
-    const songs = await provider.getPlaylistSongs(id);
+    const isNumericId = /^\d+$/.test(cmd.args.trim());
+
+    let playlistId: string;
+
+    if (isNumericId || id !== cmd.args) {
+      // Input is a numeric ID or URL containing an ID — use existing logic
+      playlistId = id;
+    } else {
+      // Name-based search
+      const result = await provider.search(cmd.args);
+      let playlists = result.playlists ?? [];
+
+      // Also search user's personal playlists if logged in
+      if (provider.getUserPlaylists) {
+        try {
+          const userPlaylists = await provider.getUserPlaylists();
+          const query = cmd.args.toLowerCase();
+          const matched = userPlaylists.filter(
+            p => p.name.toLowerCase().includes(query)
+          );
+          // Merge: public results first (API-ranked), then user matches
+          playlists = [...playlists, ...matched];
+        } catch {
+          // User playlists unavailable — continue with public results
+        }
+      }
+
+      if (playlists.length === 0)
+        return `No playlists found for: ${cmd.args}`;
+      playlistId = playlists[0].id;
+    }
+
+    const songs = await provider.getPlaylistSongs(playlistId);
     if (songs.length === 0) return "Playlist is empty or not found";
 
     this.queue.clear();
+    this.isFmMode = false;
     for (const song of songs) {
       this.queue.add({ ...song, platform: provider.platform });
     }
@@ -496,6 +644,7 @@ export class BotInstance extends EventEmitter {
     if (songs.length === 0) return "Album is empty or not found";
 
     this.queue.clear();
+    this.isFmMode = false;
     for (const song of songs) {
       this.queue.add({ ...song, platform: provider.platform });
     }
@@ -517,12 +666,61 @@ export class BotInstance extends EventEmitter {
     for (const song of songs) {
       this.queue.add({ ...song, platform: "netease" });
     }
+    this.queue.setMode(PlayMode.Random);
+    this.isFmMode = true;
+    this.player.resetFailures();
+
     const first = this.queue.play();
     if (first) await this.resolveAndPlay(first);
     this.emit("stateChange");
     return `Personal FM started: ${first?.name ?? "unknown"} - ${first?.artist ?? ""}`;
   }
 
+  private async cmdArtist(cmd: ParsedCommand): Promise<string> {
+    if (!cmd.args) return "Usage: !artist <artist name>";
+    const provider = this.getProvider(cmd.flags);
+    const result = await provider.search(cmd.args, 50);
+    if (result.songs.length === 0)
+      return `No results found for artist: ${cmd.args}`;
+
+    const query = cmd.args.toLowerCase();
+    let filtered = result.songs.filter(
+      s => s.artist.toLowerCase().includes(query)
+    );
+
+    // Fallback to unfiltered results if filtering drops everything
+    if (filtered.length === 0) {
+      filtered = result.songs.slice(0, 20);
+    }
+
+    this.queue.clear();
+    this.isFmMode = false;
+    for (const song of filtered) {
+      this.queue.add({ ...song, platform: provider.platform });
+    }
+    this.queue.setMode(PlayMode.Loop);
+    this.player.resetFailures();
+
+    const first = this.queue.play();
+    if (first) await this.resolveAndPlay(first);
+    this.emit("stateChange");
+    return `Artist mode: ${cmd.args} — ${filtered.length} songs loaded. Now playing: ${first?.name ?? "unknown"}`;
+  }
+
+  private async refillFm(): Promise<void> {
+    if (!this.isFmMode || !this.neteaseProvider.getPersonalFm) return;
+    try {
+      const songs = await this.neteaseProvider.getPersonalFm();
+      if (songs.length === 0) return;
+      for (const song of songs) {
+        this.queue.add({ ...song, platform: "netease" });
+      }
+      this.logger.debug({ count: songs.length }, "FM queue refilled");
+    } catch (err) {
+      this.logger.error({ err }, "Failed to refill FM queue");
+    }
+  }
+
   private async cmdVote(msg?: TS3TextMessage): Promise<string> {
     if (!msg) return "Vote can only be used in TeamSpeak";
     this.voteSkipUsers.add(msg.invokerUid);
@@ -574,15 +772,19 @@ export class BotInstance extends EventEmitter {
       `${p}play -b <song> — Search from BiliBili`,
       `${p}play -y <song> — Search from YouTube (yt-dlp)`,
       `${p}add <song>   — Add to queue`,
+      `${p}playnext <song> — Insert as next song (alias: ${p}pn)`,
       `${p}pause/resume — Pause/resume`,
       `${p}next/prev    — Next/previous`,
       `${p}stop         — Stop and clear queue`,
       `${p}vol <0-100>  — Set volume`,
       `${p}queue        — Show queue`,
       `${p}mode <seq|loop|random|rloop> — Play mode`,
-      `${p}playlist <id> — Load playlist`,
+      `${p}playlist <name or id> — Load playlist by name or ID`,
+      `${p}playlist -q <name or id> — Load playlist from QQ Music`,
       `${p}album <id>   — Load album`,
       `${p}fm           — Personal FM (NetEase)`,
+      `${p}artist <name> — Play songs by artist (loop)`,
+      `${p}artist -q <name> — Artist loop from QQ Music`,
       `${p}vote         — Vote to skip`,
       `${p}lyrics       — Show lyrics`,
       `${p}now          — Current song info`,
@@ -590,17 +792,25 @@ export class BotInstance extends EventEmitter {
     ].join("\n");
   }
 
-  private async playNext(): Promise<void> {
+  /**
-    if (this.isAdvancing || !this.connected) return;
+   * Advance the queue and play the next song. If the resolved URL fails
+   * (e.g., copyright/region restrictions for QQ), skips up to `maxRetries`
+   * more songs looking for a playable one. Public so REST endpoints that
+   * seed the queue can fall back to this retry-skip behavior.
+   *
+   * Returns true if a song actually started playing, false otherwise.
+   */
+  async playNext(maxRetries = 3): Promise<boolean> {
+    if (this.isAdvancing || !this.connected) return false;
     this.isAdvancing = true;
     try {
       this.voteSkipUsers.clear();
       const next = this.queue.next();
+      let started = false;
       if (next) {
-        let started = await this.resolveAndPlay(next);
+        started = await this.resolveAndPlay(next);
         if (!started) {
-          // Skip to next if URL resolve fails (up to 3 retries)
+          for (let i = 0; i < maxRetries && this.connected; i++) {
-          for (let i = 0; i < 3 && this.connected; i++) {
             const retry = this.queue.next();
             if (!retry) break;
             if (await this.resolveAndPlay(retry)) {
@@ -609,6 +819,21 @@ export class BotInstance extends EventEmitter {
             }
           }
         }
+        if (!started) {
+          this.player.stop();
+          this.profileManager.onSongChange(null).catch(() => {});
+        } else if (this.isFmMode && this.queue.unplayedCount() <= 3) {
+          // Proactive refill: when queue is running low, fetch more FM songs
+          this.refillFm().catch(err => this.logger.error({ err }, "Proactive FM refill failed"));
+        }
+      } else {
+        // Queue exhausted — in FM Random mode, refill and continue
+        if (this.isFmMode) {
+          await this.refillFm();
+          const refillNext = this.queue.next();
+          if (refillNext) {
+            started = await this.resolveAndPlay(refillNext);
+          }
           if (!started) {
             this.player.stop();
             this.profileManager.onSongChange(null).catch(() => {});
@@ -617,7 +842,9 @@ export class BotInstance extends EventEmitter {
           this.player.stop();
           this.profileManager.onSongChange(null).catch(() => {});
         }
+      }
       this.emit("stateChange");
+      return started;
     } finally {
       this.isAdvancing = false;
     }

src/bot/manager.ts

@@ -11,6 +11,7 @@ import type { BotConfig } from "../data/config.js";
 import type { Logger } from "../logger.js";
 
 import type { ServerProtocol } from "../ts-protocol/client.js";
+import type { AvatarStore } from "../data/avatars.js";
 
 /**
  * Run bot.connect() with a hard deadline. If the handshake hangs (e.g. the
@@ -74,6 +75,7 @@ export class BotManager extends EventEmitter {
   private database: BotDatabase;
   private config: BotConfig;
   private logger: Logger;
+  private avatarStore: AvatarStore;
 
   constructor(
     neteaseProvider: MusicProvider,
@@ -81,7 +83,8 @@ export class BotManager extends EventEmitter {
     bilibiliProvider: MusicProvider,
     database: BotDatabase,
     config: BotConfig,
-    logger: Logger
+    logger: Logger,
+    avatarStore: AvatarStore
   ) {
     super();
     this.neteaseProvider = neteaseProvider;
@@ -91,6 +94,7 @@ export class BotManager extends EventEmitter {
     this.database = database;
     this.config = config;
     this.logger = logger;
+    this.avatarStore = avatarStore;
   }
 
   async createBot(params: CreateBotParams): Promise<BotInstance> {
@@ -117,6 +121,7 @@ export class BotManager extends EventEmitter {
       database: this.database,
       config: this.config,
       logger: this.logger,
+      avatarStore: this.avatarStore,
     });
 
     this.bots.set(id, bot);
@@ -233,6 +238,7 @@ export class BotManager extends EventEmitter {
         database: this.database,
         config: this.config,
         logger: this.logger,
+        avatarStore: this.avatarStore,
       });
       this.bots.set(id, bot);
       this.emit("botInstance", bot);
@@ -283,6 +289,7 @@ export class BotManager extends EventEmitter {
         database: this.database,
         config: this.config,
         logger: this.logger,
+        avatarStore: this.avatarStore,
       });
 
       this.bots.set(saved.id, bot);

src/bot/profile.test.ts

@@ -0,0 +1,147 @@
+import { describe, it, expect, beforeEach, vi } from "vitest";
+import { BotProfileManager } from "./profile.js";
+import type { TS3Client } from "../ts-protocol/client.js";
+import type { QueuedSong } from "../audio/queue.js";
+
+function makeMockTs(): TS3Client & {
+  uploadCalls: Buffer[];
+  clearCalls: number;
+} {
+  const calls: Buffer[] = [];
+  let clears = 0;
+  const ts: any = {
+    uploadCalls: calls,
+    get clearCalls() { return clears; },
+    getHost: () => "127.0.0.1",
+    getHttpQuery: () => null,
+    fileTransferInitUpload: vi.fn().mockResolvedValue({}),
+    uploadFileData: vi.fn().mockImplementation(async (_h: any, _i: any, stream: any) => {
+      const chunks: Buffer[] = [];
+      for await (const c of stream) chunks.push(c as Buffer);
+      calls.push(Buffer.concat(chunks));
+    }),
+    fileTransferDeleteFile: vi.fn().mockResolvedValue(undefined),
+    sendCommandNoWait: vi.fn().mockImplementation(async (cmd: string) => {
+      if (/client_flag_avatar=$/.test(cmd)) clears++;
+    }),
+  };
+  return ts;
+}
+
+const noopLogger: any = { child: () => noopLogger, info: () => {}, debug: () => {}, warn: () => {}, error: () => {} };
+
+const cfgOn = { avatarEnabled: true, descriptionEnabled: false, nicknameEnabled: false, awayStatusEnabled: false, channelDescEnabled: false, nowPlayingMsgEnabled: false };
+const cfgOff = { ...cfgOn, avatarEnabled: false };
+
+const fakeSong: QueuedSong = {
+  id: "1",
+  name: "X",
+  artist: "Y",
+  album: "Z",
+  platform: "netease",
+  url: "u",
+  coverUrl: "c",
+  duration: 100,
+};
+
+const flush = () => new Promise((r) => setImmediate(r));
+
+describe("BotProfileManager custom avatar precedence", () => {
+  let ts: ReturnType<typeof makeMockTs>;
+  beforeEach(() => { ts = makeMockTs(); });
+
+  it("setCustomAvatar uploads immediately on a fresh idle bot (sync on)", async () => {
+    const pm = new BotProfileManager(ts as any, noopLogger, cfgOn, "Bot");
+    pm.setCustomAvatar(Buffer.from([1, 2, 3]));
+    await flush();
+    expect(ts.uploadCalls.length).toBe(1);
+    expect(ts.uploadCalls[0].equals(Buffer.from([1, 2, 3]))).toBe(true);
+  });
+
+  it("setCustomAvatar uploads immediately when sync is off (always idle)", async () => {
+    const pm = new BotProfileManager(ts as any, noopLogger, cfgOff, "Bot");
+    pm.setCustomAvatar(Buffer.from([7]));
+    await flush();
+    expect(ts.uploadCalls.length).toBe(1);
+  });
+
+  it("setCustomAvatar while playing + sync on does NOT push (cover wins)", async () => {
+    const pm = new BotProfileManager(ts as any, noopLogger, cfgOn, "Bot");
+    // Simulate the bot playing a song. We can't actually run updateAvatar's
+    // full HTTP fetch path, but onSongChange records currentSong before
+    // updateAvatar runs, which is enough for this assertion.
+    void pm.onSongChange(fakeSong);
+    await flush();
+    const uploadsBefore = ts.uploadCalls.length;
+    pm.setCustomAvatar(Buffer.from([42]));
+    await flush();
+    expect(ts.uploadCalls.length).toBe(uploadsBefore); // no new upload
+  });
+
+  it("setCustomAvatar while playing + sync off DOES push (sync-off is idle)", async () => {
+    const pm = new BotProfileManager(ts as any, noopLogger, cfgOff, "Bot");
+    void pm.onSongChange(fakeSong);
+    await flush();
+    const uploadsBefore = ts.uploadCalls.length;
+    pm.setCustomAvatar(Buffer.from([42]));
+    await flush();
+    expect(ts.uploadCalls.length).toBe(uploadsBefore + 1);
+  });
+
+  it("setCustomAvatar(null) while idle clears the TS3 avatar", async () => {
+    const pm = new BotProfileManager(ts as any, noopLogger, cfgOn, "Bot");
+    pm.setCustomAvatar(Buffer.from([1]));
+    await flush();
+    const clearsBefore = ts.clearCalls;
+    pm.setCustomAvatar(null);
+    await flush();
+    expect(ts.clearCalls).toBe(clearsBefore + 1);
+  });
+
+  it("on stop with custom avatar set + sync on, restores custom (does not clear)", async () => {
+    const pm = new BotProfileManager(ts as any, noopLogger, cfgOn, "Bot");
+    pm.setCustomAvatar(Buffer.from([1, 2, 3, 4]));
+    await flush();
+    const clearsBefore = ts.clearCalls;
+    await pm.onSongChange(null);
+    expect(ts.uploadCalls.at(-1)?.equals(Buffer.from([1, 2, 3, 4]))).toBe(true);
+    expect(ts.clearCalls).toBe(clearsBefore); // no extra clear
+  });
+
+  it("on stop with no custom avatar, falls back to clear", async () => {
+    const pm = new BotProfileManager(ts as any, noopLogger, cfgOn, "Bot");
+    await pm.onSongChange(null);
+    expect(ts.clearCalls).toBe(1);
+    expect(ts.uploadCalls.length).toBe(0);
+  });
+
+  it("on connect with custom avatar set + sync ON, applies custom (spec matrix row 1)", async () => {
+    const pm = new BotProfileManager(ts as any, noopLogger, cfgOn, "Bot");
+    pm.setCustomAvatar(Buffer.from([5, 5]));
+    await flush();
+    ts.uploadCalls.length = 0; // reset
+    pm.onConnect();
+    await flush();
+    expect(ts.uploadCalls.length).toBe(1);
+    expect(ts.uploadCalls[0].equals(Buffer.from([5, 5]))).toBe(true);
+  });
+
+  it("on connect with custom avatar set + sync OFF, applies custom", async () => {
+    const pm = new BotProfileManager(ts as any, noopLogger, cfgOff, "Bot");
+    pm.setCustomAvatar(Buffer.from([9, 9]));
+    await flush();
+    ts.uploadCalls.length = 0;
+    pm.onConnect();
+    await flush();
+    expect(ts.uploadCalls.length).toBe(1);
+    expect(ts.uploadCalls[0].equals(Buffer.from([9, 9]))).toBe(true);
+  });
+
+  it("on connect with no custom avatar, does not touch avatar", async () => {
+    const pm = new BotProfileManager(ts as any, noopLogger, cfgOff, "Bot");
+    pm.onConnect();
+    await flush();
+    expect(ts.uploadCalls.length).toBe(0);
+    expect(ts.clearCalls).toBe(0);
+  });
+});

src/bot/profile.ts

@@ -2,6 +2,7 @@ import { createHash } from "node:crypto";
 import { Readable } from "node:stream";
 import axios from "axios";
 import { TS3Client, escapeTS3 } from "../ts-protocol/client.js";
+import { HttpQueryError } from "../ts-protocol/http-query.js";
 import type { ProfileConfig } from "../data/database.js";
 import type { QueuedSong } from "../audio/queue.js";
 import type { Logger } from "../logger.js";
@@ -24,6 +25,13 @@ export class BotProfileManager {
   private logger: Logger;
   private config: ProfileConfig;
   private defaultNickname: string;
+  private customAvatar: Buffer | null = null;
+  /**
+   * Tracks the last song handed to onSongChange. null means stopped/idle.
+   * Used by setCustomAvatar to decide whether the new buffer should be
+   * pushed immediately (idle) or wait for the next stop event (playing).
+   */
+  private currentSong: QueuedSong | null = null;
 
   /** Per-feature permission-denied flags. Reset on reconnect. */
   private permDenied = {
@@ -57,6 +65,26 @@ export class BotProfileManager {
 
   // --- Public API ---
 
+  /**
+   * Set/clear the persistent idle avatar. Pass null to remove.
+   *
+   * If the bot is currently in an idle state (no song playing OR
+   * avatarEnabled is off), the new buffer is pushed to TS3 right away;
+   * otherwise the cover-art sync is in charge until the next stop event,
+   * at which point clearAvatar restores from this.customAvatar.
+   */
+  setCustomAvatar(buffer: Buffer | null): void {
+    this.customAvatar = buffer;
+    const idle = this.currentSong === null || !this.config.avatarEnabled;
+    if (!idle) return;
+    const gen = ++this.generation;
+    if (buffer && buffer.length > 0) {
+      void this.applyIdleAvatar(gen);
+    } else {
+      void this.clearAvatar(gen);
+    }
+  }
+
   /**
    * Called when a new song starts playing (song != null) or playback
    * stops (song == null).
@@ -70,6 +98,7 @@ export class BotProfileManager {
    */
   async onSongChange(song: QueuedSong | null): Promise<void> {
     const gen = ++this.generation;
+    this.currentSong = song;
 
     // 1. Avatar first — file transfer uses its own response tracker and
     //    must run before sendCommandNoWait calls whose orphaned responses
@@ -90,6 +119,7 @@ export class BotProfileManager {
   /** Reset permission-denied flags and bump generation on new connection. */
   onConnect(): void {
     this.generation++;
+    this.currentSong = null;
     this.permDenied = {
       avatar: false,
       description: false,
@@ -98,6 +128,12 @@ export class BotProfileManager {
       channelDesc: false,
       nowPlayingMsg: false,
     };
+    // No song is playing on a fresh connect, so the matrix says the
+    // custom avatar should be visible regardless of avatarEnabled.
+    if (this.customAvatar) {
+      const gen = this.generation;
+      void this.applyIdleAvatar(gen);
+    }
   }
 
   getConfig(): ProfileConfig {
@@ -135,24 +171,45 @@ export class BotProfileManager {
 
       // Wrap the file-transfer sequence with a timeout — the TS3
       // full-client file transfer can silently hang.
+      const start = Date.now();
       await this.withTimeout(this.doAvatarUpload(imageBuffer), FILE_TRANSFER_TIMEOUT_MS);
-      this.logger.info("Avatar updated");
+      this.logger.info(
+        { bytes: imageBuffer.length, elapsedMs: Date.now() - start },
+        "Avatar updated",
+      );
     } catch (err) {
       this.handleFeatureError("avatar", err);
     }
   }
 
+  /**
+   * Three-step upload. Each step is logged so the log can tell us whether
+   * a broken/loading avatar on the client is from:
+   *   (a) init failing (no permission)
+   *   (b) file transfer hanging on TCP 30033
+   *   (c) client_flag_avatar not applying
+   * If (b) happens, the avatar MD5 would still be set in the past — leaving
+   * clients showing a placeholder. The flag is now only set after the TCP
+   * transfer resolves.
+   */
   private async doAvatarUpload(imageBuffer: Buffer): Promise<void> {
     const host = this.tsClient.getHost();
+    this.logger.debug({ bytes: imageBuffer.length, host }, "Avatar: init file transfer");
     const info = await this.tsClient.fileTransferInitUpload(
       0n, "/avatar", "", BigInt(imageBuffer.length), true,
     );
+    this.logger.debug({ bytes: imageBuffer.length }, "Avatar: uploading file data");
     await this.tsClient.uploadFileData(host, info, Readable.from(imageBuffer));
     const md5 = createHash("md5").update(imageBuffer).digest("hex");
+    this.logger.debug({ md5 }, "Avatar: setting client_flag_avatar");
     await this.tsClient.sendCommandNoWait(`clientupdate client_flag_avatar=${escapeTS3(md5)}`);
   }
 
   private async clearAvatar(gen: number): Promise<void> {
+    if (this.customAvatar && this.customAvatar.length > 0) {
+      await this.applyIdleAvatar(gen);
+      return;
+    }
     try {
       await this.withTimeout(
         this.tsClient.fileTransferDeleteFile(0n, ["/avatar"]),
@@ -161,7 +218,6 @@ export class BotProfileManager {
     } catch {
       // File may not exist or transfer timed out — that's fine
     }
-    // Bail if a newer song started while we were deleting
     if (this.generation !== gen) return;
     try {
       await this.tsClient.sendCommandNoWait("clientupdate client_flag_avatar=");
@@ -170,6 +226,18 @@ export class BotProfileManager {
     }
   }
 
+  private async applyIdleAvatar(gen: number): Promise<void> {
+    if (!this.customAvatar || this.customAvatar.length === 0) return;
+    if (this.permDenied.avatar) return;
+    try {
+      await this.withTimeout(this.doAvatarUpload(this.customAvatar), FILE_TRANSFER_TIMEOUT_MS);
+      if (this.generation !== gen) return;
+      this.logger.info({ bytes: this.customAvatar.length }, "Idle (custom) avatar applied");
+    } catch (err) {
+      this.handleFeatureError("avatar", err);
+    }
+  }
+
   private async updateDescription(song: QueuedSong | null): Promise<void> {
     if (!this.config.descriptionEnabled || this.permDenied.description) return;
     try {
@@ -178,7 +246,11 @@ export class BotProfileManager {
         : "";
       const httpQuery = this.tsClient.getHttpQuery();
       if (httpQuery) {
-        await httpQuery.clientUpdate({ client_description: text });
+        // TS6 HTTP API: send the raw (unescaped) text. clientUpdate
+        // throws HttpQueryError on non-2xx so a silent 400/403 cannot
+        // be misreported as success.
+        const result = await httpQuery.clientUpdate({ client_description: text });
+        this.logger.info({ status: result.status }, "Description updated");
       } else {
         // clientupdate rejects client_description (error 1538).
         // Use clientedit on our own clid instead — this is what
@@ -193,8 +265,8 @@ export class BotProfileManager {
           ),
           5000,
         );
-      }
         this.logger.info("Description updated");
+      }
     } catch (err) {
       this.handleFeatureError("description", err);
     }
@@ -204,18 +276,25 @@ export class BotProfileManager {
    * Build and send a single `clientupdate` command that sets nickname
    * and away status together, avoiding multiple round-trips that can
    * cause command-queue timeouts on the TS3 protocol.
+   *
+   * Values are collected as raw strings/numbers. The TS6 HTTP path
+   * forwards them as JSON (the server expects real spaces, not `\s`);
+   * the TS3 wire path escapes them on the fly. Previously the code
+   * escaped upfront and then split the escaped string to build the
+   * JSON body, so TS6 received literal backslashes and silently
+   * rejected the update.
    */
   private async updateClientProperties(song: QueuedSong | null): Promise<void> {
-    const parts: string[] = [];
+    const rawProps: Record<string, string | number> = {};
 
     // --- Nickname ---
     if (this.config.nicknameEnabled && !this.permDenied.nickname) {
       if (!song) {
-        parts.push(`client_nickname=${escapeTS3(this.defaultNickname)}`);
+        rawProps.client_nickname = this.defaultNickname;
       } else {
         const nickname = this.buildNickname(song);
         if (nickname) {
-          parts.push(`client_nickname=${escapeTS3(nickname)}`);
+          rawProps.client_nickname = nickname;
         }
       }
     }
@@ -223,31 +302,38 @@ export class BotProfileManager {
     // --- Away status ---
     if (this.config.awayStatusEnabled && !this.permDenied.awayStatus) {
       if (song) {
-        parts.push("client_away=0");
+        rawProps.client_away = 0;
       } else {
-        parts.push(`client_away=1 client_away_message=${escapeTS3("\u7B49\u5F85\u64AD\u653E")}`);
+        rawProps.client_away = 1;
+        rawProps.client_away_message = "\u7B49\u5F85\u64AD\u653E";
       }
     }
 
-    if (parts.length === 0) return;
+    if (Object.keys(rawProps).length === 0) return;
 
     try {
       const httpQuery = this.tsClient.getHttpQuery();
       if (httpQuery) {
-        // TS6: build a properties object
+        // TS6: send raw values as JSON. Throws HttpQueryError on 4xx/5xx.
-        const props: Record<string, string | number> = {};
+        const result = await httpQuery.clientUpdate(rawProps);
-        for (const part of parts) {
+        this.logger.info(
-          const eq = part.indexOf("=");
+          { status: result.status, props: Object.keys(rawProps) },
-          if (eq > 0) props[part.slice(0, eq)] = part.slice(eq + 1);
+          "Client properties updated (nickname + away)",
-        }
+        );
-        await httpQuery.clientUpdate(props);
       } else {
-        // Use sendCommandNoWait: the TS3 full-client protocol often
+        // TS3 wire protocol: escape string values inline.
+        // sendCommandNoWait: the TS3 full-client protocol often
         // doesn't return a timely error response for clientupdate,
         // causing execCommand to time out after 10s.
+        const parts = Object.entries(rawProps).map(([k, v]) =>
+          typeof v === "string" ? `${k}=${escapeTS3(v)}` : `${k}=${v}`,
+        );
         await this.tsClient.sendCommandNoWait(`clientupdate ${parts.join(" ")}`);
+        this.logger.info(
+          { props: Object.keys(rawProps) },
+          "Client properties updated (nickname + away)",
+        );
       }
-      this.logger.info("Client properties updated (nickname + away)");
     } catch (err) {
       // Flag both features on permission error
       this.handleFeatureError("nickname", err);
@@ -387,21 +473,28 @@ export class BotProfileManager {
     err: unknown,
   ): void {
     const msg = err instanceof Error ? err.message.toLowerCase() : String(err).toLowerCase();
+    const status = err instanceof HttpQueryError ? err.status : undefined;
+    const body = err instanceof HttpQueryError ? err.body : undefined;
     // Disable the feature for this session on unrecoverable errors:
     // - permission / insufficient → server denies the action
     // - invalid parameter → command not supported by this protocol
-    if (
+    // - HTTP 401/403 → TS6 server rejects the API key/role
+    // - HTTP 400 → bad parameter; retrying on every song change is wasteful
+    const isUnrecoverable =
       msg.includes("permission") ||
       msg.includes("insufficient") ||
-      msg.includes("invalid parameter")
+      msg.includes("invalid parameter") ||
-    ) {
+      status === 400 ||
+      status === 401 ||
+      status === 403;
+    if (isUnrecoverable) {
       this.permDenied[feature] = true;
       this.logger.info(
-        { feature, reason: msg },
+        { feature, status, body, reason: msg },
         "Feature disabled for this session (will retry after reconnect)",
       );
     } else {
-      this.logger.warn({ feature, err }, "Profile update failed");
+      this.logger.warn({ feature, status, body, err }, "Profile update failed");
     }
   }
 }

src/data/avatars.test.ts

@@ -0,0 +1,61 @@
+import { describe, it, expect, beforeEach } from "vitest";
+import { mkdtempSync, rmSync, existsSync, readFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { createAvatarStore } from "./avatars.js";
+
+let dir: string;
+
+beforeEach(() => {
+  dir = mkdtempSync(join(tmpdir(), "avatar-test-"));
+});
+
+describe("createAvatarStore", () => {
+  it("write returns a relative path under the store dir", () => {
+    const store = createAvatarStore(dir);
+    const buf = Buffer.from("fake-png");
+    const rel = store.write("bot-1", "image/png", buf);
+    expect(rel).toBe("bot-1.png");
+    expect(readFileSync(join(dir, "bot-1.png")).equals(buf)).toBe(true);
+  });
+
+  it("write picks correct extension for jpeg / webp", () => {
+    const store = createAvatarStore(dir);
+    expect(store.write("a", "image/jpeg", Buffer.from(""))).toBe("a.jpg");
+    expect(store.write("b", "image/webp", Buffer.from(""))).toBe("b.webp");
+  });
+
+  it("write rejects unsupported MIME types", () => {
+    const store = createAvatarStore(dir);
+    expect(() => store.write("c", "image/gif", Buffer.from(""))).toThrow(/unsupported/i);
+  });
+
+  it("read returns the bytes for an existing file", () => {
+    const store = createAvatarStore(dir);
+    store.write("bot-1", "image/png", Buffer.from("hello"));
+    const buf = store.read("bot-1.png");
+    expect(buf?.equals(Buffer.from("hello"))).toBe(true);
+  });
+
+  it("read returns null when path is missing", () => {
+    const store = createAvatarStore(dir);
+    expect(store.read("missing.png")).toBeNull();
+  });
+
+  it("remove deletes the file (idempotent)", () => {
+    const store = createAvatarStore(dir);
+    store.write("bot-1", "image/png", Buffer.from("x"));
+    store.remove("bot-1.png");
+    expect(existsSync(join(dir, "bot-1.png"))).toBe(false);
+    expect(() => store.remove("bot-1.png")).not.toThrow();
+  });
+
+  it("write replaces any existing file for the same botId regardless of old extension", () => {
+    const store = createAvatarStore(dir);
+    store.write("bot-1", "image/png", Buffer.from("old"));
+    const rel = store.write("bot-1", "image/jpeg", Buffer.from("new"));
+    expect(rel).toBe("bot-1.jpg");
+    expect(existsSync(join(dir, "bot-1.png"))).toBe(false);
+    expect(existsSync(join(dir, "bot-1.jpg"))).toBe(true);
+  });
+});

src/data/avatars.ts

@@ -0,0 +1,43 @@
+import { mkdirSync, writeFileSync, readFileSync, rmSync, readdirSync, existsSync } from "node:fs";
+import { join } from "node:path";
+
+const MIME_TO_EXT: Record<string, string> = {
+  "image/png": "png",
+  "image/jpeg": "jpg",
+  "image/webp": "webp",
+};
+
+export interface AvatarStore {
+  /** Returns the relative path written (e.g. "bot-1.png"). */
+  write(botId: string, mime: string, buffer: Buffer): string;
+  read(relPath: string): Buffer | null;
+  remove(relPath: string): void;
+  getDir(): string;
+}
+
+export function createAvatarStore(dir: string): AvatarStore {
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+  return {
+    write(botId, mime, buffer) {
+      const ext = MIME_TO_EXT[mime];
+      if (!ext) throw new Error(`unsupported avatar MIME: ${mime}`);
+      for (const name of readdirSync(dir)) {
+        if (name.startsWith(`${botId}.`)) rmSync(join(dir, name), { force: true });
+      }
+      const rel = `${botId}.${ext}`;
+      writeFileSync(join(dir, rel), buffer);
+      return rel;
+    },
+    read(relPath) {
+      const full = join(dir, relPath);
+      if (!existsSync(full)) return null;
+      return readFileSync(full);
+    },
+    remove(relPath) {
+      rmSync(join(dir, relPath), { force: true });
+    },
+    getDir() {
+      return dir;
+    },
+  };
+}

src/data/config.ts

@@ -13,6 +13,15 @@ export interface BotConfig {
   adminGroups: number[];
   autoReturnDelay: number;
   autoPauseOnEmpty: boolean;
+  idleTimeoutMinutes: number;
+  // Public base URL used when generating share links (e.g. the bot专属链接).
+  // Leave empty to use the browser's current origin. Example:
+  //   "https://music.example.com" or "http://1.2.3.4:3000"
+  publicUrl: string;
+  // When true, Express trusts X-Forwarded-* headers from a reverse proxy
+  // (nginx/Caddy/Cloudflare). Required for correct protocol/host detection
+  // behind HTTPS-terminating proxies.
+  trustProxy: boolean;
 }
 
 export function getDefaultConfig(): BotConfig {
@@ -28,6 +37,9 @@ export function getDefaultConfig(): BotConfig {
     adminGroups: [],
     autoReturnDelay: 300,
     autoPauseOnEmpty: true,
+    idleTimeoutMinutes: 0,
+    publicUrl: "",
+    trustProxy: false,
   };
 }
 

src/data/database.test.ts

@@ -68,7 +68,7 @@ describe("database", () => {
     botDb.saveBotInstance(instance);
     const instances = botDb.getBotInstances();
     expect(instances).toHaveLength(1);
-    expect(instances[0]).toEqual(instance);
+    expect(instances[0]).toMatchObject(instance);
     expect(instances[0].autoStart).toBe(true);
 
     // Test upsert
@@ -98,4 +98,26 @@ describe("database", () => {
     expect(botDb.getBotInstances()).toHaveLength(0);
     expect(botDb.deleteBotInstance("nonexistent")).toBe(false);
   });
+
+  it("persists and clears customAvatarPath on a bot instance", () => {
+    const inst = {
+      id: "bot-1",
+      name: "B",
+      serverAddress: "x",
+      serverPort: 9987,
+      nickname: "n",
+      defaultChannel: "",
+      channelPassword: "",
+      autoStart: false,
+      serverProtocol: "",
+      ts6ApiKey: "",
+      serverPassword: "",
+    };
+    botDb.saveBotInstance(inst);
+    expect(botDb.getCustomAvatarPath("bot-1")).toBeNull();
+    botDb.setCustomAvatarPath("bot-1", "avatars/bot-1.png");
+    expect(botDb.getCustomAvatarPath("bot-1")).toBe("avatars/bot-1.png");
+    botDb.setCustomAvatarPath("bot-1", null);
+    expect(botDb.getCustomAvatarPath("bot-1")).toBeNull();
+  });
 });

src/data/database.ts

@@ -60,6 +60,8 @@ export interface BotDatabase {
   deleteBotInstance(id: string): boolean;
   getProfileConfig(botId: string): ProfileConfig;
   saveProfileConfig(botId: string, config: ProfileConfig): void;
+  getCustomAvatarPath(botId: string): string | null;
+  setCustomAvatarPath(botId: string, path: string | null): void;
   close(): void;
 }
 
@@ -92,6 +94,9 @@ function migrateSchema(db: Database.Database): void {
       db.exec(`ALTER TABLE bot_instances ADD COLUMN ${col} INTEGER NOT NULL DEFAULT 1`);
     }
   }
+  if (!names.includes("custom_avatar_path")) {
+    db.exec("ALTER TABLE bot_instances ADD COLUMN custom_avatar_path TEXT");
+  }
 }
 
 function initTables(db: Database.Database): void {
@@ -179,6 +184,9 @@ export function createDatabase(dbPath: string): BotDatabase {
     WHERE id = @id
   `);
 
+  const selectCustomAvatar = db.prepare(`SELECT custom_avatar_path FROM bot_instances WHERE id = ?`);
+  const updateCustomAvatar = db.prepare(`UPDATE bot_instances SET custom_avatar_path = ? WHERE id = ?`);
+
   return {
     db,
 
@@ -242,6 +250,14 @@ export function createDatabase(dbPath: string): BotDatabase {
       });
     },
 
+    getCustomAvatarPath(botId) {
+      const row = selectCustomAvatar.get(botId) as { custom_avatar_path: string | null } | undefined;
+      return row?.custom_avatar_path ?? null;
+    },
+    setCustomAvatarPath(botId, path) {
+      updateCustomAvatar.run(path, botId);
+    },
+
     close() {
       db.close();
     },

src/index.ts

@@ -8,6 +8,7 @@ import { NeteaseProvider } from "./music/netease.js";
 import { QQMusicProvider } from "./music/qq.js";
 import { BiliBiliProvider } from "./music/bilibili.js";
 import { createCookieStore } from "./music/auth.js";
+import { createAvatarStore } from "./data/avatars.js";
 import { BotManager } from "./bot/manager.js";
 import { createWebServer } from "./web/server.js";
 
@@ -18,6 +19,7 @@ const CONFIG_PATH = path.join(ROOT_DIR, "config.json");
 const DB_PATH = path.join(DATA_DIR, "tsmusicbot.db");
 const LOG_DIR = path.join(DATA_DIR, "logs");
 const COOKIE_DIR = path.join(DATA_DIR, "cookies");
+const AVATAR_DIR = path.join(DATA_DIR, "avatars");
 const STATIC_DIR = path.join(ROOT_DIR, "web", "dist");
 
 async function main() {
@@ -46,6 +48,7 @@ async function main() {
   const bilibiliProvider = new BiliBiliProvider();
 
   const cookieStore = createCookieStore(COOKIE_DIR);
+  const avatarStore = createAvatarStore(AVATAR_DIR);
   const neteaseCookie = cookieStore.load("netease");
   if (neteaseCookie) neteaseProvider.setCookie(neteaseCookie);
   const qqCookie = cookieStore.load("qq");
@@ -59,7 +62,8 @@ async function main() {
     bilibiliProvider,
     db,
     config,
-    logger
+    logger,
+    avatarStore
   );
   await botManager.loadSavedBots();
 
@@ -70,7 +74,9 @@ async function main() {
     qqProvider,
     bilibiliProvider,
     database: db,
+    avatarStore,
     config,
+    configPath: CONFIG_PATH,
     logger,
     cookieStore,
     staticDir: STATIC_DIR,
@@ -78,7 +84,10 @@ async function main() {
   await webServer.start();
 
   logger.info({ webPort: config.webPort }, "TSMusicBot started");
-  logger.info(`WebUI: http://localhost:${config.webPort}`);
+  const publicUrl = (config.publicUrl ?? "").trim().replace(/\/+$/, "");
+  logger.info(
+    `WebUI: ${publicUrl || `http://localhost:${config.webPort}`}`
+  );
 
   const shutdown = () => {
     logger.info("Shutting down...");

src/music/api-server.ts

@@ -76,7 +76,14 @@ export function createApiServerManager(
           );
         } else {
           const qqModule = (await import("@sansenjian/qq-music-api")) as any;
-          const koaApp = qqModule.default ?? qqModule;
+          // The module's export structure varies between versions:
+          //   2.2.11+: default → Koa app (has .listen)
+          //   2.2.10:  default → wrapper object whose .default is the Koa app
+          //   older:   module itself may be the Koa app
+          const candidate = qqModule.default ?? qqModule;
+          const koaApp = typeof candidate.listen === "function"
+            ? candidate
+            : candidate.default ?? null;
           if (koaApp && typeof koaApp.listen === "function") {
             qqMusicServer = await new Promise<Server>((resolve, reject) => {
               const srv = koaApp.listen(options.qqMusicPort, "127.0.0.1", () =>

src/music/netease.ts

@@ -3,6 +3,7 @@ import type {
   MusicProvider,
   Song,
   Playlist,
+  PlaylistDetail,
   LyricLine,
   SearchResult,
   QrCodeResult,
@@ -319,6 +320,21 @@ export class NeteaseProvider implements MusicProvider {
     }));
   }
 
+  async getPlaylistDetail(playlistId: string): Promise<PlaylistDetail | null> {
+    const res = await this.api.get("/playlist/detail", {
+      params: { id: playlistId, ...this.cookieParams },
+    });
+    const p = res.data?.playlist;
+    if (!p) return null;
+    return {
+      id: String(p.id),
+      name: p.name ?? "",
+      description: p.description ?? "",
+      coverUrl: p.coverImgUrl ?? "",
+      songCount: p.trackCount ?? 0,
+    };
+  }
+
   async getUserPlaylists(): Promise<Playlist[]> {
     // First get user ID from login status
     const statusRes = await this.api.get("/login/status", {

src/music/provider.ts

@@ -20,6 +20,14 @@ export interface Playlist {
   platform: "netease" | "qq" | "bilibili" | "youtube";
 }
 
+export interface PlaylistDetail {
+  id: string;
+  name: string;
+  description: string;
+  coverUrl: string;
+  songCount: number;
+}
+
 export interface Album {
   id: string;
   name: string;
@@ -77,4 +85,5 @@ export interface MusicProvider {
   getPersonalFm?(): Promise<Song[]>;
   getDailyRecommendSongs?(): Promise<Song[]>;
   getUserPlaylists?(): Promise<Playlist[]>;
+  getPlaylistDetail?(playlistId: string): Promise<PlaylistDetail | null>;
 }

src/music/qq.ts

@@ -3,6 +3,7 @@ import type {
   MusicProvider,
   Song,
   Playlist,
+  PlaylistDetail,
   LyricLine,
   SearchResult,
   QrCodeResult,
@@ -10,6 +11,30 @@ import type {
 } from "./provider.js";
 import { parseLyrics } from "./netease.js";
 
+// Direct QQ Music API client — bypasses the local API server for search
+// because @sansenjian/qq-music-api still uses the broken c.y.qq.com endpoint.
+const qqDirectApi = axios.create({
+  baseURL: "https://u.y.qq.com",
+  timeout: 10000,
+  headers: { referer: "https://y.qq.com" },
+});
+
+// Direct client for c.y.qq.com endpoints (collected playlists / favorites).
+// The bundled qq-music-api wrapper doesn't expose these endpoints.
+const qqFavApi = axios.create({
+  baseURL: "https://c.y.qq.com",
+  timeout: 10000,
+  headers: { referer: "https://y.qq.com/" },
+});
+
+function computeGtk(pSkey: string): number {
+  let hash = 5381;
+  for (let i = 0; i < pSkey.length; i++) {
+    hash = (hash + (hash << 5) + pSkey.charCodeAt(i)) | 0;
+  }
+  return hash & 0x7fffffff;
+}
+
 export class QQMusicProvider implements MusicProvider {
   readonly platform = "qq" as const;
   private api: AxiosInstance;
@@ -36,33 +61,102 @@ export class QQMusicProvider implements MusicProvider {
   }
 
   async search(query: string, limit = 20): Promise<SearchResult> {
-    const res = await this.api.get("/getSearchByKey", {
+    const reqData = JSON.stringify({
-      params: { key: query, pageSize: limit, ...this.cookieParams },
+      req_0: {
+        module: "music.search.SearchCgiService",
+        method: "DoSearchForQQMusicDesktop",
+        param: {
+          searchid: "1",
+          query,
+          num_per_page: Math.min(limit, 50),
+        },
+      },
     });
+    const res = await qqDirectApi.get("/cgi-bin/musicu.fcg", {
+      params: { format: "json", data: reqData },
+    });
+    const list: any[] =
+      res.data?.req_0?.data?.body?.song?.list ?? [];
 
-    const songs: Song[] = (res.data?.response?.data?.song?.list ?? []).map(
+    const songs: Song[] = list.map((s: any) => ({
-      (s: any) => ({
+      id: String(s.mid ?? s.id),
-        id: String(s.songmid ?? s.songid),
+      name: s.title ?? s.name ?? "",
-        name: s.songname ?? "",
       artist: (s.singer ?? []).map((a: any) => a.name).join(" / "),
-        album: s.albumname ?? "",
+      album: s.album?.name ?? s.album?.title ?? "",
       duration: s.interval ?? 0,
-        coverUrl: s.albummid
+      coverUrl: s.album?.mid
-          ? `https://y.gtimg.cn/music/photo_new/T002R300x300M000${s.albummid}.jpg`
+        ? `https://y.gtimg.cn/music/photo_new/T002R300x300M000${s.album.mid}.jpg`
         : "",
       platform: "qq",
-      })
+    }));
-    );
 
     return { songs, playlists: [], albums: [] };
   }
 
-  async getSongUrl(songId: string, _quality?: string): Promise<string | null> {
+  async getSongUrl(songId: string, quality?: string): Promise<string | null> {
+    try {
       const res = await this.api.get("/getMusicPlay", {
-      params: { songmid: songId, ...this.cookieParams },
+        params: { songmid: songId, quality: quality ?? this.quality, ...this.cookieParams },
       });
       const playUrl = res.data?.data?.playUrl?.[songId];
-    return playUrl?.url || null;
+      if (playUrl?.url) return playUrl.url;
+    } catch {
+      // try with songid
+      try {
+        const res = await this.api.get("/getMusicPlay", {
+          params: { songid: songId, quality: quality ?? this.quality, ...this.cookieParams },
+        });
+        const playUrl = res.data?.data?.playUrl?.[songId];
+        if (playUrl?.url) return playUrl.url;
+      } catch {
+        // ignore
+      }
+    }
+    return null;
+  }
+
+  /**
+   * Batch-check which song mids are actually streamable. QQ playlists
+   * (especially collected ones) frequently contain a majority of songs
+   * that return result=104003 ("no copyright/region restricted") for the
+   * current user — a sequential retry loop wastes time guessing.
+   *
+   * The wrapper's /getMusicPlay accepts a comma-separated songmid list
+   * and resolves all of them in a single upstream call. We chunk to keep
+   * the URL well under typical 8KB query-string limits and to keep per-
+   * request latency bounded (~2-3s per 100 mids).
+   *
+   * Returns:
+   *   - non-null Set: authoritative result. Empty Set means all songs are
+   *     unplayable; non-empty means filter to those mids.
+   *   - null: every chunk failed. Caller should fall back to sequential
+   *     retry rather than treating as "all unplayable".
+   */
+  async getPlayableSongIds(songIds: string[]): Promise<Set<string> | null> {
+    if (songIds.length === 0) return new Set();
+
+    const CHUNK = 100;          // ~14 chars/mid * 100 + commas ≈ 1.5KB
+    const playable = new Set<string>();
+    let allChunksFailed = true;
+    for (let i = 0; i < songIds.length; i += CHUNK) {
+      const slice = songIds.slice(i, i + CHUNK);
+      try {
+        const res = await this.api.get("/getMusicPlay", {
+          params: { songmid: slice.join(","), quality: this.quality, ...this.cookieParams },
+        });
+        const playUrlMap: Record<string, { url?: string }> | undefined =
+          res.data?.data?.playUrl;
+        if (!playUrlMap) continue; // chunk-level failure, try next
+        allChunksFailed = false;
+        for (const [mid, info] of Object.entries(playUrlMap)) {
+          if (info?.url) playable.add(mid);
+        }
+      } catch {
+        // chunk-level failure — keep going so a transient error on one
+        // chunk doesn't poison the whole batch.
+      }
+    }
+    return allChunksFailed ? null : playable;
   }
 
   async getSongDetail(songId: string): Promise<Song | null> {
@@ -115,18 +209,35 @@ export class QQMusicProvider implements MusicProvider {
     const cdlist = res.data?.response?.cdlist ?? [];
     if (cdlist.length === 0) return [];
     return (cdlist[0].songlist ?? []).map((s: any) => ({
-      id: String(s.songmid ?? s.songid),
+      id: String(s.mid ?? s.songmid ?? s.songid),
       name: s.songname ?? s.name ?? "",
       artist: (s.singer ?? []).map((a: any) => a.name).join(" / "),
       album: s.albumname ?? "",
       duration: s.interval ?? 0,
-      coverUrl: s.albummid
+      coverUrl: s.album?.mid
+        ? `https://y.gtimg.cn/music/photo_new/T002R300x300M000${s.album.mid}.jpg`
+        : s.albummid
         ? `https://y.gtimg.cn/music/photo_new/T002R300x300M000${s.albummid}.jpg`
         : "",
       platform: "qq",
     }));
   }
 
+  async getPlaylistDetail(playlistId: string): Promise<PlaylistDetail | null> {
+    const res = await this.api.get("/getSongListDetail", {
+      params: { disstid: playlistId, ...this.cookieParams },
+    });
+    const cd = res.data?.response?.cdlist?.[0];
+    if (!cd) return null;
+    return {
+      id: String(cd.disstid ?? cd.dissid ?? ""),
+      name: cd.dissname ?? "",
+      description: cd.desc ?? "",
+      coverUrl: cd.logo ?? "",
+      songCount: cd.songnum ?? cd.total_song_num ?? 0,
+    };
+  }
+
   async getRecommendPlaylists(): Promise<Playlist[]> {
     const res = await this.api.get("/getSongLists", {
       params: { categoryId: 10000000, pageSize: 10, ...this.cookieParams },
@@ -255,4 +366,117 @@ export class QQMusicProvider implements MusicProvider {
       return { loggedIn: false };
     }
   }
+
+  async getDailyRecommendSongs(): Promise<Song[]> {
+    // QQ has no per-user daily list; use newsong.NewSongServer (新歌速递)
+    // as the closest analogue. Returns ~20 newly-released songs.
+    try {
+      const res = await this.api.get("/getNewSongs", {
+        params: { ...this.cookieParams },
+      });
+      const list: any[] = res.data?.response?.new_song?.data?.songlist ?? [];
+      return list.map((s: any) => ({
+        id: String(s.mid ?? s.id),
+        name: s.title ?? s.name ?? "",
+        artist: (s.singer ?? []).map((a: any) => a.name).join(" / "),
+        album: s.album?.name ?? s.album?.title ?? "",
+        duration: s.interval ?? 0,
+        coverUrl: s.album?.mid
+          ? `https://y.gtimg.cn/music/photo_new/T002R300x300M000${s.album.mid}.jpg`
+          : "",
+        platform: "qq",
+      }));
+    } catch {
+      return [];
+    }
+  }
+
+  async getUserPlaylists(): Promise<Playlist[]> {
+    if (!this.cookie) return [];
+    const uinMatch = /(?:^|; )uin=o?0?(\d+)/.exec(this.cookie);
+    const uin = uinMatch ? uinMatch[1] : "";
+    if (!uin) return [];
+
+    // Created and collected playlists come from two separate QQ endpoints.
+    // Run them in parallel and concatenate (created first, then collected),
+    // matching the order shown in the QQ Music desktop app.
+    const [created, collected] = await Promise.all([
+      this.fetchCreatedPlaylists(uin),
+      this.fetchCollectedPlaylists(uin),
+    ]);
+    return [...created, ...collected];
+  }
+
+  private async fetchCreatedPlaylists(uin: string): Promise<Playlist[]> {
+    try {
+      const res = await this.api.get("/user/getUserPlaylists", {
+        params: { uin, ...this.cookieParams },
+      });
+      if (res.data?.response?.code !== 0) return [];
+      return (res.data?.response?.data?.playlists ?? []).map((p: any) => {
+        // fcg_get_profile_homepage returns title/picurl/subtitle ("X首  Y次播放").
+        const subtitle: string = p.subtitle ?? "";
+        const songCountFromSubtitle = parseInt(subtitle.match(/(\d+)\s*首/)?.[1] ?? "0", 10);
+        return {
+          id: String(p.dissid ?? p.id ?? ""),
+          name: p.title ?? p.dissname ?? p.name ?? "",
+          coverUrl: p.picurl ?? p.imgurl ?? p.coverUrl ?? "",
+          songCount: p.song_count ?? p.listennum ?? songCountFromSubtitle,
+          platform: "qq",
+        };
+      });
+    } catch {
+      return [];
+    }
+  }
+
+  private async fetchCollectedPlaylists(uin: string): Promise<Playlist[]> {
+    // c.y.qq.com fav endpoint: reqtype=3 returns collected playlists (cdlist).
+    // Requires g_tk derived from the p_skey cookie.
+    const pSkeyMatch = /(?:^|; )p_skey=([^;]+)/.exec(this.cookie);
+    if (!pSkeyMatch) return [];
+    const gtk = computeGtk(pSkeyMatch[1]);
+
+    const PAGE_SIZE = 30;
+    const MAX_PAGES = 10;       // 300-playlist hard cap; should cover any sane user
+    const all: Playlist[] = [];
+    try {
+      for (let page = 0; page < MAX_PAGES; page++) {
+        const sin = page * PAGE_SIZE;
+        const ein = sin + PAGE_SIZE - 1;
+        const res = await qqFavApi.get("/fav/fcgi-bin/fcg_get_profile_order_asset.fcg", {
+          params: {
+            ct: 20,
+            cid: 205360956,
+            userid: uin,
+            reqtype: 3,
+            sin,
+            ein,
+            g_tk: gtk,
+            format: "json",
+          },
+          headers: { Cookie: this.cookie },
+        });
+        if (res.data?.code !== 0) break;
+        const list: any[] = res.data?.data?.cdlist ?? [];
+        for (const p of list) {
+          all.push({
+            id: String(p.dissid ?? ""),
+            name: p.dissname ?? "",
+            coverUrl: p.logo ?? "",
+            songCount: p.songnum ?? 0,
+            platform: "qq",
+          });
+        }
+        // Stop when upstream signals no more pages, or when this page is
+        // short (also indicates end). has_more is the canonical signal.
+        const hasMore = res.data?.data?.has_more === 1 || res.data?.data?.has_more === true;
+        if (!hasMore || list.length < PAGE_SIZE) break;
+      }
+    } catch {
+      // Return whatever we got so far on partial failure rather than dropping
+      // earlier pages.
+    }
+    return all;
+  }
 }

src/ts-protocol/client.ts

@@ -188,6 +188,9 @@ export class TS3Client extends EventEmitter {
     };
 
     this.client = new TS3FullClient(this.identity, addr, this.options.nickname, {
+      // Forward server password to the protocol library so it can be
+      // included in clientinit for password-protected servers
+      serverPassword: this.options.serverPassword,
       logger: {
         debug: (msg) => this.logger.debug(msg),
         info: (msg) => this.logger.info(msg),

src/ts-protocol/http-query.ts

@@ -14,6 +14,38 @@ export interface HttpQueryResult {
   body: unknown;
 }
 
+/**
+ * Thrown when the TS6 HTTP Query returns a non-2xx status.
+ *
+ * The previous implementation silently ignored the status code, so a 400
+ * (bad parameter) or 403 (insufficient permission) looked identical to
+ * success in logs. Callers that rely on the response being applied —
+ * nickname / description / away-status updates — should catch this and
+ * surface it rather than log "updated" for a request that was rejected.
+ */
+export class HttpQueryError extends Error {
+  readonly status: number;
+  readonly body: unknown;
+  readonly path: string;
+
+  constructor(path: string, status: number, body: unknown) {
+    const bodySnippet = (() => {
+      if (body == null) return "";
+      const s = typeof body === "string" ? body : JSON.stringify(body);
+      return s.length > 200 ? s.slice(0, 200) + "\u2026" : s;
+    })();
+    super(
+      `TS6 HTTP Query ${path} failed: status=${status}${
+        bodySnippet ? ` body=${bodySnippet}` : ""
+      }`,
+    );
+    this.name = "HttpQueryError";
+    this.status = status;
+    this.body = body;
+    this.path = path;
+  }
+}
+
 /**
  * TS6 HTTP Query client.
  *
@@ -157,12 +189,24 @@ export class TS6HttpQuery {
     });
   }
 
-  /** Update client properties (e.g., description) */
+  /**
+   * Update client properties (e.g., description, nickname, away).
+   *
+   * Throws HttpQueryError on non-2xx responses. The TS6 server returns
+   * 400 for invalid parameters and 403 for insufficient permissions;
+   * prior to this check the errors were silently dropped and callers
+   * logged a false "updated" success.
+   */
   async clientUpdate(
     properties: Record<string, string | number>,
     sid = 1,
   ): Promise<HttpQueryResult> {
-    return this.request("POST", `/1/clientupdate?sid=${sid}`, properties);
+    const path = `/1/clientupdate?sid=${sid}`;
+    const result = await this.request("POST", path, properties);
+    if (result.status < 200 || result.status >= 300) {
+      throw new HttpQueryError(path, result.status, result.body);
+    }
+    return result;
   }
 
   /** Move a client to a channel */

src/web/api/bot.ts

@@ -1,12 +1,18 @@
 import { Router } from "express";
 import type { BotManager } from "../../bot/manager.js";
 import type { BotConfig } from "../../data/config.js";
+import { saveConfig } from "../../data/config.js";
 import type { Logger } from "../../logger.js";
+import type { BotDatabase } from "../../data/database.js";
+import type { AvatarStore } from "../../data/avatars.js";
 
 export function createBotRouter(
   botManager: BotManager,
   config: BotConfig,
-  logger: Logger
+  configPath: string,
+  logger: Logger,
+  botDb: BotDatabase,
+  avatarStore: AvatarStore,
 ): Router {
   const router = Router();
 
@@ -34,6 +40,70 @@ export function createBotRouter(
     res.json(saved);
   });
 
+  router.get("/:id/avatar", (req, res) => {
+    const path = botDb.getCustomAvatarPath(req.params.id);
+    if (!path) {
+      res.status(404).end();
+      return;
+    }
+    const buf = avatarStore.read(path);
+    if (!buf) {
+      res.status(404).end();
+      return;
+    }
+    const ext = path.split(".").pop() ?? "";
+    const mime = ext === "png"
+      ? "image/png"
+      : ext === "webp"
+        ? "image/webp"
+        : "image/jpeg";
+    res.set("Content-Type", mime);
+    res.set("Cache-Control", "no-cache");
+    res.send(buf);
+  });
+
+  router.put("/:id/avatar", (req, res) => {
+    const exists =
+      botManager.getBot(req.params.id) ||
+      botDb.getBotInstances().some((b) => b.id === req.params.id);
+    if (!exists) {
+      res.status(404).json({ error: "Bot not found" });
+      return;
+    }
+    const { dataUrl } = req.body as { dataUrl?: string };
+    if (typeof dataUrl !== "string") {
+      res.status(400).json({ error: "dataUrl required" });
+      return;
+    }
+    const m = /^data:(image\/(?:png|jpeg|webp));base64,(.+)$/.exec(dataUrl);
+    if (!m) {
+      res.status(400).json({ error: "dataUrl must be image/png|jpeg|webp base64" });
+      return;
+    }
+    const mime = m[1] as string;
+    const buf = Buffer.from(m[2] ?? "", "base64");
+    if (buf.length === 0) {
+      res.status(400).json({ error: "empty image" });
+      return;
+    }
+    if (buf.length > 200 * 1024) {
+      res.status(413).json({ error: "avatar exceeds 200KB limit" });
+      return;
+    }
+    const rel = avatarStore.write(req.params.id, mime, buf);
+    botDb.setCustomAvatarPath(req.params.id, rel);
+    botManager.getBot(req.params.id)?.getProfileManager().setCustomAvatar(buf);
+    res.json({ path: rel });
+  });
+
+  router.delete("/:id/avatar", (req, res) => {
+    const path = botDb.getCustomAvatarPath(req.params.id);
+    if (path) avatarStore.remove(path);
+    botDb.setCustomAvatarPath(req.params.id, null);
+    botManager.getBot(req.params.id)?.getProfileManager().setCustomAvatar(null);
+    res.status(204).end();
+  });
+
   router.post("/", async (req, res) => {
     try {
       const {
@@ -116,5 +186,26 @@ export function createBotRouter(
     }
   });
   
+  // GET /api/bot/settings — 读取全局 bot 行为设置
+  router.get("/settings", (_req, res) => {
+    res.json({ idleTimeoutMinutes: config.idleTimeoutMinutes ?? 0 });
+  });
+
+  // POST /api/bot/settings — 保存全局 bot 行为设置
+  router.post("/settings", (req, res) => {
+    const { idleTimeoutMinutes } = req.body;
+    if (typeof idleTimeoutMinutes !== "number" || idleTimeoutMinutes < 0) {
+      res.status(400).json({ error: "idleTimeoutMinutes must be a non-negative number" });
+      return;
+    }
+    config.idleTimeoutMinutes = idleTimeoutMinutes;
+    saveConfig(configPath, config);
+    // 通知所有 bot 实例更新定时器
+    for (const bot of botManager.getAllBots()) {
+      bot.updateIdleTimeout(idleTimeoutMinutes);
+    }
+    res.json({ ok: true });
+  });
+
   return router;
 }

src/web/api/music.ts

@@ -168,32 +168,16 @@ export function createMusicRouter(
   router.get("/playlist/:id/detail", async (req, res) => {
     try {
       const provider = getProvider(req.query.platform as string);
-      // Use the playlist songs endpoint to get basic info,
+      if (!provider.getPlaylistDetail) {
-      // but we also need detail info (name, cover, description).
+        res.status(501).json({ error: "Not supported by this provider" });
-      // For netease, we access the underlying API directly.
-      const nProvider = provider as any;
-      if (nProvider.api) {
-        const cookieParams = nProvider.cookie
-          ? { cookie: nProvider.cookie }
-          : {};
-        const detailRes = await nProvider.api.get("/playlist/detail", {
-          params: { id: req.params.id, ...cookieParams },
-        });
-        const p = detailRes.data?.playlist;
-        if (p) {
-          res.json({
-            playlist: {
-              id: String(p.id),
-              name: p.name,
-              description: p.description ?? "",
-              coverUrl: p.coverImgUrl ?? "",
-              songCount: p.trackCount ?? 0,
-            },
-          });
         return;
       }
-      }
+      const detail = await provider.getPlaylistDetail(req.params.id);
+      if (!detail) {
         res.status(404).json({ error: "Playlist not found" });
+        return;
+      }
+      res.json({ playlist: detail });
     } catch (err) {
       logger.error({ err }, "Get playlist detail failed");
       res.status(500).json({ error: (err as Error).message });

src/web/api/player.ts

@@ -249,9 +249,32 @@ export function createPlayerRouter(
         return;
       }
 
+      // QQ-specific optimization: many users' QQ playlists contain a
+      // large fraction of songs that return result=104003 (region/copyright
+      // restricted). Batch-resolve URLs once and only queue the playable
+      // ones, otherwise the playback retry loop wastes time guessing.
+      let queueable: { id: string }[] = songs;
+      const totalCount = songs.length;
+      const qqLike = provider as { getPlayableSongIds?: (ids: string[]) => Promise<Set<string> | null> };
+      if (typeof qqLike.getPlayableSongIds === "function") {
+        const playable = await qqLike.getPlayableSongIds(songs.map((s: { id: string }) => s.id));
+        if (playable !== null) {
+          // Authoritative answer from upstream — even an empty set means
+          // "we know none are playable", short-circuit immediately rather
+          // than wasting 20+ retries.
+          queueable = songs.filter((s: { id: string }) => playable.has(s.id));
+        }
+        // If null, the batch endpoint itself errored — fall through to
+        // the sequential retry path, which still has a chance.
+      }
+      if (queueable.length === 0) {
+        res.json({ ok: false, message: `歌单 ${totalCount} 首歌曲均无版权可播放（区域/版权限制）` });
+        return;
+      }
+
       const queue = bot.getQueueManager();
       queue.clear();
-      for (const song of songs) {
+      for (const song of queueable) {
         queue.add({ ...song, platform: provider.platform });
       }
 
@@ -265,11 +288,25 @@ export function createPlayerRouter(
         first = queue.play();
       }
 
-      if (first) {
+      // If the first picked song can't resolve (e.g., QQ song with no
-        await bot.resolveAndPlay(first);
+      // streaming entitlement → result 104003), fall back to playNext's
+      // retry-skip behavior. Use a higher retry budget than the default
+      // trackEnd auto-advance because user-initiated playlist plays
+      // commonly have long contiguous runs of unplayable songs.
+      let started = first ? await bot.resolveAndPlay(first) : false;
+      if (first && !started) {
+        started = await bot.playNext(20);
       }
 
-      res.json({ message: `Loaded ${songs.length} songs. Now playing: ${first?.name ?? "unknown"}` });
+      const playing = queue.current();
+      const loadedMsg = queueable.length < totalCount
+        ? `已加载 ${queueable.length}/${totalCount} 首（其余区域/版权限制）`
+        : `已加载 ${queueable.length} 首`;
+      if (started && playing) {
+        res.json({ ok: true, message: `${loadedMsg}，正在播放：${playing.name}` });
+      } else {
+        res.json({ ok: false, message: `${loadedMsg}，但无法开始播放。` });
+      }
     } catch (err) {
       logger.error({ err }, "Play playlist failed");
       res.status(500).json({ error: (err as Error).message });
@@ -277,35 +314,94 @@ export function createPlayerRouter(
   });
 
   // Play a single song by ID — resolves URL on demand
-  router.post("/:botId/play-by-id", async (req, res) => {
+  router.post("/:botId/play-song", async (req, res) => {
     try {
       const bot = (req as any).bot;
-      const { songId, platform } = req.body;
+      const { song } = req.body;
-      const provider = bot.getProviderFor(
+      if (!song || !song.id || !song.platform) {
-        platform === "bilibili" || platform === "qq" || platform === "youtube"
+        res.status(400).json({ error: "song object with id and platform is required" });
-          ? platform
-          : "netease"
-      );
-
-      const song = await provider.getSongDetail(songId);
-      if (!song) {
-        res.json({ message: "Song not found" });
         return;
       }
-
       const queue = bot.getQueueManager();
       queue.clear();
-      queue.add({ ...song, platform: provider.platform });
+      queue.add(song);
       queue.play();
 
       bot.getPlayer().resetFailures();
       const ok = await bot.resolveAndPlay(queue.current()!);
       if (!ok) {
-        res.json({ message: `Cannot play: ${song.name}` });
+        res.json({ ok: false, message: `无法播放「${song.name || song.id}」（区域/版权限制）` });
         return;
       }
 
-      res.json({ message: `Now playing: ${song.name} - ${song.artist}` });
+      res.json({ ok: true, message: `正在播放：${song.name || 'Unknown'} - ${song.artist || 'Unknown'}` });
+    } catch (err) {
+      res.status(500).json({ error: (err as Error).message });
+    }
+  });
+
+  // Insert a single song to play right after the current one.
+  // If nothing is playing, behaves like /play-song (start immediately).
+  router.post("/:botId/play-next-song", async (req, res) => {
+    try {
+      const bot = (req as any).bot;
+      const { song } = req.body;
+      if (!song || !song.id || !song.platform) {
+        res.status(400).json({ error: "song object with id and platform is required" });
+        return;
+      }
+      const queue = bot.getQueueManager();
+      const wasIdle = bot.getPlayer().getState() === "idle";
+      // Capture the slot addNext WILL insert at, before mutating the queue.
+      // addNext pushes when currentIndex<0 (slot = size); otherwise splices
+      // at currentIndex+1. Using size-1 after addNext was wrong when the
+      // queue had stale currentIndex>=0 while the player was idle (e.g.,
+      // after natural track end without queue.clear()).
+      const insertedAt =
+        queue.getCurrentIndex() < 0 ? queue.size() : queue.getCurrentIndex() + 1;
+      queue.addNext(song);
+
+      if (wasIdle) {
+        // Promote the just-added song to current and start it.
+        queue.playAt(insertedAt);
+        bot.getPlayer().resetFailures();
+        const ok = await bot.resolveAndPlay(queue.current()!);
+        if (!ok) {
+          res.json({ ok: false, message: `无法播放「${song.name || song.id}」（区域/版权限制）` });
+          return;
+        }
+        res.json({ ok: true, message: `正在播放：${song.name || 'Unknown'} - ${song.artist || 'Unknown'}` });
+        return;
+      }
+
+      res.json({ ok: true, message: `已加入下一首：${song.name || 'Unknown'} - ${song.artist || 'Unknown'}` });
+    } catch (err) {
+      res.status(500).json({ error: (err as Error).message });
+    }
+  });
+
+  router.post("/:botId/add-song", async (req, res) => {
+    try {
+      const bot = (req as any).bot;
+      const { song } = req.body;
+      if (!song || !song.id || !song.platform) {
+        res.status(400).json({ error: "song object with id and platform is required" });
+        return;
+      }
+      const queue = bot.getQueueManager();
+      const wasIdle = bot.getPlayer().getState() === "idle";
+      queue.add(song);
+
+      // If nothing was playing, start this newly-added song immediately.
+      if (wasIdle) {
+        queue.playAt(queue.size() - 1);
+        bot.getPlayer().resetFailures();
+        await bot.resolveAndPlay(queue.current()!);
+        res.json({ message: `Now playing: ${song.name || 'Unknown'} - ${song.artist || 'Unknown'}` });
+        return;
+      }
+
+      res.json({ message: `Added to queue: ${song.name || 'Unknown'} - ${song.artist || 'Unknown'} (position ${queue.size()})` });
     } catch (err) {
       res.status(500).json({ error: (err as Error).message });
     }

src/web/server.ts

@@ -8,6 +8,7 @@ import type { BotDatabase } from "../data/database.js";
 import type { BotConfig } from "../data/config.js";
 import type { Logger } from "../logger.js";
 import type { CookieStore } from "../music/auth.js";
+import type { AvatarStore } from "../data/avatars.js";
 import { createBotRouter } from "./api/bot.js";
 import { createMusicRouter } from "./api/music.js";
 import { createPlayerRouter } from "./api/player.js";
@@ -22,8 +23,10 @@ export interface WebServerOptions {
   bilibiliProvider: MusicProvider;
   database: BotDatabase;
   config: BotConfig;
+  configPath: string;
   logger: Logger;
   cookieStore?: CookieStore;
+  avatarStore: AvatarStore;
   staticDir?: string;
 }
 
@@ -37,11 +40,28 @@ export function createWebServer(options: WebServerOptions): WebServer {
   const server = http.createServer(app);
   const logger = options.logger.child({ component: "web" });
 
-  app.use(express.json());
+  if (options.config.trustProxy) {
+    // Honor X-Forwarded-* from a reverse proxy (nginx/Caddy/Cloudflare).
+    app.set("trust proxy", true);
+  }
+
+  app.use(express.json({ limit: "400kb" }));
+
+  app.get("/api/config/public-url", (_req, res) => {
+    const raw = (options.config.publicUrl ?? "").trim();
+    res.json({ publicUrl: raw ? raw.replace(/\/+$/, "") : null });
+  });
 
   app.use(
     "/api/bot",
-    createBotRouter(options.botManager, options.config, logger)
+    createBotRouter(
+      options.botManager,
+      options.config,
+      options.configPath,
+      logger,
+      options.database,
+      options.avatarStore,
+    )
   );
   app.use(
     "/api/music",

web/package-lock.json

@@ -797,9 +797,6 @@
         "arm"
       ],
       "dev": true,
-      "libc": [
-        "glibc"
-      ],
       "license": "MIT",
       "optional": true,
       "os": [
@@ -821,9 +818,6 @@
         "arm"
       ],
       "dev": true,
-      "libc": [
-        "musl"
-      ],
       "license": "MIT",
       "optional": true,
       "os": [
@@ -845,9 +839,6 @@
         "arm64"
       ],
       "dev": true,
-      "libc": [
-        "glibc"
-      ],
       "license": "MIT",
       "optional": true,
       "os": [
@@ -869,9 +860,6 @@
         "arm64"
       ],
       "dev": true,
-      "libc": [
-        "musl"
-      ],
       "license": "MIT",
       "optional": true,
       "os": [
@@ -893,9 +881,6 @@
         "x64"
       ],
       "dev": true,
-      "libc": [
-        "glibc"
-      ],
       "license": "MIT",
       "optional": true,
       "os": [
@@ -917,9 +902,6 @@
         "x64"
       ],
       "dev": true,
-      "libc": [
-        "musl"
-      ],
       "license": "MIT",
       "optional": true,
       "os": [
@@ -1088,9 +1070,6 @@
         "arm"
       ],
       "dev": true,
-      "libc": [
-        "glibc"
-      ],
       "license": "MIT",
       "optional": true,
       "os": [
@@ -1105,9 +1084,6 @@
         "arm"
       ],
       "dev": true,
-      "libc": [
-        "musl"
-      ],
       "license": "MIT",
       "optional": true,
       "os": [
@@ -1122,9 +1098,6 @@
         "arm64"
       ],
       "dev": true,
-      "libc": [
-        "glibc"
-      ],
       "license": "MIT",
       "optional": true,
       "os": [
@@ -1139,9 +1112,6 @@
         "arm64"
       ],
       "dev": true,
-      "libc": [
-        "musl"
-      ],
       "license": "MIT",
       "optional": true,
       "os": [
@@ -1156,9 +1126,6 @@
         "loong64"
       ],
       "dev": true,
-      "libc": [
-        "glibc"
-      ],
       "license": "MIT",
       "optional": true,
       "os": [
@@ -1173,9 +1140,6 @@
         "loong64"
       ],
       "dev": true,
-      "libc": [
-        "musl"
-      ],
       "license": "MIT",
       "optional": true,
       "os": [
@@ -1190,9 +1154,6 @@
         "ppc64"
       ],
       "dev": true,
-      "libc": [
-        "glibc"
-      ],
       "license": "MIT",
       "optional": true,
       "os": [
@@ -1207,9 +1168,6 @@
         "ppc64"
       ],
       "dev": true,
-      "libc": [
-        "musl"
-      ],
       "license": "MIT",
       "optional": true,
       "os": [
@@ -1224,9 +1182,6 @@
         "riscv64"
       ],
       "dev": true,
-      "libc": [
-        "glibc"
-      ],
       "license": "MIT",
       "optional": true,
       "os": [
@@ -1241,9 +1196,6 @@
         "riscv64"
       ],
       "dev": true,
-      "libc": [
-        "musl"
-      ],
       "license": "MIT",
       "optional": true,
       "os": [
@@ -1258,9 +1210,6 @@
         "s390x"
       ],
       "dev": true,
-      "libc": [
-        "glibc"
-      ],
       "license": "MIT",
       "optional": true,
       "os": [
@@ -1275,9 +1224,6 @@
         "x64"
       ],
       "dev": true,
-      "libc": [
-        "glibc"
-      ],
       "license": "MIT",
       "optional": true,
       "os": [
@@ -1292,9 +1238,6 @@
         "x64"
       ],
       "dev": true,
-      "libc": [
-        "musl"
-      ],
       "license": "MIT",
       "optional": true,
       "os": [

web/src/App.vue

@@ -5,32 +5,152 @@
       <RouterView />
     </main>
     <Player />
+    <Toast />
+    <Queue class="mobile-queue" :open="mobileQueueOpen" @close="mobileQueueOpen = false" />
+
+    <!-- Mobile mini player -->
+    <div v-if="currentSong" class="m-player" @click="router.push('/lyrics')">
+      <div class="m-player-progress">
+        <div class="m-player-progress-fill" :style="{ width: mobileProgressPct + '%' }" />
+      </div>
+      <CoverArt :url="currentSong.coverUrl" :size="40" :radius="8" />
+      <div class="m-player-info">
+        <div class="m-player-name">{{ currentSong.name }}</div>
+        <div class="m-player-artist">{{ currentSong.artist }}</div>
+      </div>
+      <div class="m-player-controls" @click.stop>
+        <button class="m-player-btn" @click="playerStore.prev()">
+          <Icon icon="mdi:skip-previous" />
+        </button>
+        <button class="m-player-btn" @click="playerStore.isPlaying ? playerStore.pause() : playerStore.resume()">
+          <Icon :icon="playerStore.isPlaying ? 'mdi:pause' : 'mdi:play'" />
+        </button>
+        <button class="m-player-btn" @click="playerStore.next()">
+          <Icon icon="mdi:skip-next" />
+        </button>
+        <button class="m-player-btn" @click="cycleMobileMode">
+          <Icon :icon="mobileModeIcon" />
+        </button>
+        <button class="m-player-btn" @click="toggleMobileQueue">
+          <Icon icon="mdi:playlist-music" />
+        </button>
+        <button class="m-player-btn" @click="toggleMobileVolume">
+          <Icon icon="mdi:volume-high" />
+        </button>
+      </div>
+      <div v-if="mobileVolumeOpen" class="m-volume-popover" @click.stop>
+        <Icon icon="mdi:volume-high" class="m-volume-icon" />
+        <input
+          type="range"
+          min="0"
+          max="100"
+          :value="mobileVolume"
+          class="m-volume-slider"
+          @input="onMobileVolumeChange"
+        />
+        <span class="m-volume-value">{{ mobileVolume }}</span>
+      </div>
+    </div>
+
+    <!-- Mobile bottom tab bar -->
+    <nav class="m-tabbar">
+      <RouterLink to="/" class="m-tab" :class="{ active: route.path === '/' }">
+        <Icon icon="mdi:home" class="tab-icon" />
+        <span class="tab-label">发现</span>
+      </RouterLink>
+      <RouterLink to="/search" class="m-tab" :class="{ active: route.path === '/search' }">
+        <Icon icon="mdi:magnify" class="tab-icon" />
+        <span class="tab-label">搜索</span>
+      </RouterLink>
+      <RouterLink to="/library" class="m-tab" :class="{ active: route.path === '/library' }">
+        <Icon icon="mdi:music-box-multiple" class="tab-icon" />
+        <span class="tab-label">音乐库</span>
+      </RouterLink>
+      <RouterLink to="/settings" class="m-tab" :class="{ active: route.path.startsWith('/settings') }">
+        <Icon icon="mdi:cog" class="tab-icon" />
+        <span class="tab-label">设置</span>
+      </RouterLink>
+    </nav>
   </div>
 </template>
 
 <script setup lang="ts">
-import { computed, onMounted, onUnmounted } from 'vue';
+import { computed, onMounted, onUnmounted, ref } from 'vue';
+import { useRoute, useRouter } from 'vue-router';
+import { Icon } from '@iconify/vue';
 import { usePlayerStore } from './stores/player.js';
 import { useWebSocket } from './composables/useWebSocket.js';
 import Navbar from './components/Navbar.vue';
 import Player from './components/Player.vue';
+import CoverArt from './components/CoverArt.vue';
+import Toast from './components/Toast.vue';
+import Queue from './components/Queue.vue';
 
 const playerStore = usePlayerStore();
 const theme = computed(() => playerStore.theme);
+const route = useRoute();
+const router = useRouter();
 const { connect } = useWebSocket();
+const currentSong = computed(() => playerStore.currentSong);
+const mobileVolume = computed(() => playerStore.activeBot?.volume ?? 75);
+const mobileMode = computed(() => playerStore.activeBot?.playMode ?? 'seq');
+const mobileModeOrder = ['seq', 'loop', 'random', 'rloop'];
+const mobileModeIcons: Record<string, string> = {
+  seq: 'mdi:arrow-right',
+  loop: 'mdi:repeat',
+  random: 'mdi:shuffle',
+  rloop: 'mdi:repeat-once',
+};
+const mobileModeIcon = computed(() => mobileModeIcons[mobileMode.value] ?? mobileModeIcons.seq);
+const mobileVolumeOpen = ref(false);
+const mobileQueueOpen = ref(false);
 
+const mobileProgressPct = ref(0);
 let syncTimer: ReturnType<typeof setInterval> | null = null;
+let mobileRaf: number | null = null;
+
+function updateMobileProgress() {
+  const duration = currentSong.value?.duration ?? 0;
+  mobileProgressPct.value = duration > 0
+    ? Math.min((playerStore.elapsed / duration) * 100, 100)
+    : 0;
+  mobileRaf = requestAnimationFrame(updateMobileProgress);
+}
+
+function onMobileVolumeChange(e: Event) {
+  const volume = Number((e.target as HTMLInputElement).value);
+  playerStore.setVolume(volume);
+}
+
+function toggleMobileVolume() {
+  mobileVolumeOpen.value = !mobileVolumeOpen.value;
+  if (mobileVolumeOpen.value) mobileQueueOpen.value = false;
+}
+
+function toggleMobileQueue() {
+  mobileQueueOpen.value = !mobileQueueOpen.value;
+  if (mobileQueueOpen.value) mobileVolumeOpen.value = false;
+}
+
+function cycleMobileMode() {
+  const currentIndex = mobileModeOrder.indexOf(mobileMode.value);
+  const nextMode = mobileModeOrder[(currentIndex + 1) % mobileModeOrder.length] ?? mobileModeOrder[0];
+  mobileVolumeOpen.value = false;
+  mobileQueueOpen.value = false;
+  playerStore.setMode(nextMode);
+}
 
 onMounted(() => {
   playerStore.loadTheme();
   connect();
   playerStore.fetchBots();
-  // Periodically sync elapsed time from server (ground truth)
   syncTimer = setInterval(() => playerStore.syncElapsed(), 3000);
+  mobileRaf = requestAnimationFrame(updateMobileProgress);
 });
 
 onUnmounted(() => {
   if (syncTimer) clearInterval(syncTimer);
+  if (mobileRaf !== null) cancelAnimationFrame(mobileRaf);
 });
 </script>
 
@@ -47,5 +167,186 @@ onUnmounted(() => {
   @media (max-width: 1336px) {
     padding: 80px 5vw 80px;
   }
+
+  @media (max-width: 768px) {
+    padding: 72px 16px 200px;
+  }
+}
+
+// Mobile mini player
+.m-player {
+  position: fixed;
+  left: 8px;
+  right: 8px;
+  bottom: 68px;
+  height: 58px;
+  padding: 8px 10px;
+  display: flex;
+  align-items: center;
+  gap: 10px;
+  background: var(--bg-secondary);
+  border-radius: var(--radius-md);
+  box-shadow: 0 6px 20px rgba(0, 0, 0, 0.35);
+  z-index: 95;
+  cursor: pointer;
+
+  @media (min-width: 769px) {
+    display: none;
+  }
+}
+
+.mobile-queue {
+  display: none;
+
+  @media (max-width: 768px) {
+    display: flex;
+  }
+}
+
+.m-player-progress {
+  position: absolute;
+  top: 0;
+  left: 10px;
+  right: 10px;
+  height: 2px;
+}
+
+.m-player-progress-fill {
+  height: 2px;
+  background: var(--color-primary);
+  border-radius: 1px;
+}
+
+.m-player-info {
+  flex: 1;
+  min-width: 0;
+}
+
+.m-player-controls {
+  display: flex;
+  align-items: center;
+  gap: 4px;
+  flex: 0 0 auto;
+}
+
+.m-player-name {
+  font-size: 13px;
+  font-weight: 500;
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+
+.m-player-artist {
+  font-size: 11px;
+  color: var(--text-secondary);
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+
+.m-player-btn {
+  width: 28px;
+  height: 32px;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  font-size: 20px;
+  opacity: 0.85;
+  flex-shrink: 0;
+}
+
+.m-volume-popover {
+  position: absolute;
+  right: 8px;
+  bottom: calc(100% + 8px);
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  width: min(260px, calc(100vw - 32px));
+  padding: 10px 12px;
+  background: var(--bg-secondary);
+  border: 1px solid var(--border-color);
+  border-radius: var(--radius-md);
+  box-shadow: var(--shadow-dropdown);
+  cursor: default;
+}
+
+.m-volume-icon {
+  flex: 0 0 auto;
+  font-size: 18px;
+  color: var(--text-secondary);
+}
+
+.m-volume-slider {
+  flex: 1 1 auto;
+  min-width: 0;
+  height: 4px;
+  appearance: none;
+  background: var(--border-color);
+  border-radius: 2px;
+  outline: none;
+
+  &::-webkit-slider-thumb {
+    appearance: none;
+    width: 16px;
+    height: 16px;
+    background: var(--color-primary);
+    border-radius: 50%;
+  }
+}
+
+.m-volume-value {
+  flex: 0 0 30px;
+  font-size: 12px;
+  color: var(--text-secondary);
+  text-align: right;
+  font-variant-numeric: tabular-nums;
+}
+
+// Mobile bottom tab bar
+.m-tabbar {
+  position: fixed;
+  left: 0;
+  right: 0;
+  bottom: 0;
+  height: 60px;
+  display: flex;
+  align-items: center;
+  justify-content: space-around;
+  padding-bottom: env(safe-area-inset-bottom, 0);
+  background: var(--bg-navbar);
+  backdrop-filter: saturate(180%) blur(20px);
+  -webkit-backdrop-filter: saturate(180%) blur(20px);
+  border-top: 1px solid var(--border-color);
+  z-index: 100;
+
+  @media (min-width: 769px) {
+    display: none;
+  }
+}
+
+.m-tab {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: 2px;
+  padding: 6px 14px;
+  color: var(--text-tertiary);
+  text-decoration: none;
+  font-family: inherit;
+
+  &.active {
+    color: var(--color-primary);
+  }
+
+  .tab-icon {
+    font-size: 22px;
+  }
+
+  .tab-label {
+    font-size: 10px;
+    font-weight: 500;
+  }
 }
 </style>

web/src/components/AvatarUpload.vue

@@ -0,0 +1,99 @@
+<template>
+  <div class="avatar-upload">
+    <div class="preview" :class="{ empty: !previewUrl }">
+      <img v-if="previewUrl" :src="previewUrl" alt="avatar" />
+      <Icon v-else icon="mdi:account-circle-outline" />
+    </div>
+    <div class="actions">
+      <input
+        ref="fileInput"
+        type="file"
+        accept="image/png,image/jpeg,image/webp"
+        class="hidden"
+        @change="onFile"
+      />
+      <button type="button" class="btn-sm" @click="fileInput?.click()">
+        {{ previewUrl ? '更换' : '上传' }}
+      </button>
+      <button v-if="previewUrl" type="button" class="btn-sm btn-danger" @click="clear">
+        删除
+      </button>
+    </div>
+    <p v-if="error" class="hint error">{{ error }}</p>
+    <p v-else class="hint">PNG / JPG / WebP，≤200 KB</p>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { ref, watch } from 'vue';
+import { Icon } from '@iconify/vue';
+
+const props = defineProps<{ modelValue: string | null }>();
+const emit = defineEmits<{ 'update:modelValue': [value: string | null] }>();
+
+const previewUrl = ref<string | null>(props.modelValue);
+const error = ref<string | null>(null);
+const fileInput = ref<HTMLInputElement | null>(null);
+
+watch(() => props.modelValue, (v) => { previewUrl.value = v; });
+
+function onFile(ev: Event) {
+  const file = (ev.target as HTMLInputElement).files?.[0];
+  if (!file) return;
+  if (!['image/png', 'image/jpeg', 'image/webp'].includes(file.type)) {
+    error.value = '仅支持 PNG / JPG / WebP';
+    return;
+  }
+  if (file.size > 200 * 1024) {
+    error.value = `图片 ${(file.size / 1024).toFixed(0)} KB 超过 200 KB 上限`;
+    return;
+  }
+  error.value = null;
+  const reader = new FileReader();
+  reader.onload = () => {
+    const dataUrl = reader.result as string;
+    previewUrl.value = dataUrl;
+    emit('update:modelValue', dataUrl);
+  };
+  reader.readAsDataURL(file);
+}
+
+function clear() {
+  previewUrl.value = null;
+  emit('update:modelValue', null);
+  if (fileInput.value) fileInput.value.value = '';
+}
+</script>
+
+<style lang="scss" scoped>
+.avatar-upload { display: flex; flex-direction: column; gap: 8px; align-items: flex-start; }
+
+.preview {
+  width: 80px; height: 80px; border-radius: 50%;
+  background: var(--bg-card); display: flex; align-items: center; justify-content: center;
+  overflow: hidden;
+
+  img { width: 100%; height: 100%; object-fit: cover; }
+  &.empty :deep(svg) { font-size: 48px; opacity: 0.4; }
+}
+
+.actions { display: flex; gap: 8px; }
+.hidden { display: none; }
+
+.btn-sm {
+  padding: 6px 14px;
+  background: var(--hover-bg);
+  border-radius: var(--radius-sm);
+  font-size: 12px;
+  font-weight: 600;
+  transition: all var(--transition-fast);
+  &:hover { background: var(--color-primary); color: white; }
+}
+
+.btn-danger {
+  &:hover { background: #f44336; color: white; }
+}
+
+.hint { font-size: 12px; opacity: 0.6; margin: 0; }
+.hint.error { color: #f44336; opacity: 1; }
+</style>

web/src/components/CustomAvatarRow.vue

@@ -0,0 +1,59 @@
+<template>
+  <AvatarUpload v-model="avatarDataUrl" />
+</template>
+
+<script setup lang="ts">
+import { ref, onMounted, watch, nextTick } from 'vue';
+import axios from 'axios';
+import AvatarUpload from './AvatarUpload.vue';
+
+const props = defineProps<{ botId: string }>();
+const avatarDataUrl = ref<string | null>(null);
+// Stays true until the watcher queued by the load-time assignment has run,
+// so the initial null → loaded-data-url transition does not fire a redundant
+// PUT echoing the just-fetched bytes back to the server.
+let initializing = true;
+
+async function loadCurrent() {
+  try {
+    const res = await axios.get(`/api/bot/${props.botId}/avatar`, { responseType: 'blob' });
+    const blob = res.data as Blob;
+    avatarDataUrl.value = await blobToDataUrl(blob);
+  } catch (err: any) {
+    if (err?.response?.status !== 404) {
+      console.warn('failed to load avatar', err);
+    }
+    avatarDataUrl.value = null;
+  } finally {
+    // Wait for the watcher's flush queue to drain (it'll see initializing=true
+    // and bail), then release for real user-driven changes.
+    await nextTick();
+    initializing = false;
+  }
+}
+
+function blobToDataUrl(blob: Blob): Promise<string> {
+  return new Promise((resolve, reject) => {
+    const reader = new FileReader();
+    reader.onload = () => resolve(reader.result as string);
+    reader.onerror = () => reject(reader.error);
+    reader.readAsDataURL(blob);
+  });
+}
+
+watch(avatarDataUrl, async (newVal, oldVal) => {
+  if (initializing) return;
+  if (newVal === oldVal) return;
+  try {
+    if (newVal && newVal.startsWith('data:')) {
+      await axios.put(`/api/bot/${props.botId}/avatar`, { dataUrl: newVal });
+    } else if (newVal === null) {
+      await axios.delete(`/api/bot/${props.botId}/avatar`);
+    }
+  } catch (err) {
+    console.warn('avatar update failed', err);
+  }
+});
+
+onMounted(loadCurrent);
+</script>

web/src/components/Navbar.vue

@@ -5,6 +5,7 @@
     <div class="nav-links">
       <RouterLink to="/" class="nav-link" active-class="active">发现</RouterLink>
       <RouterLink to="/search" class="nav-link" active-class="active">搜索</RouterLink>
+      <RouterLink to="/library" class="nav-link" active-class="active">音乐库</RouterLink>
       <RouterLink to="/history" class="nav-link" active-class="active">播放历史</RouterLink>
     </div>
 
@@ -19,38 +20,68 @@
           <Icon icon="mdi:chevron-down" class="bot-chevron" :class="{ rotated: dropdownOpen }" />
         </button>
         <div v-if="dropdownOpen" class="bot-dropdown">
+          <div class="bot-dropdown-header">机器人</div>
           <div
             v-for="bot in store.bots"
             :key="bot.id"
-            class="bot-dropdown-row"
+            class="bot-card"
-          >
-            <button
-              class="bot-dropdown-item"
             :class="{ active: bot.id === store.activeBotId }"
-              @click="selectBot(bot.id)"
           >
+            <div class="bot-card-head" @click="bot.connected ? selectBot(bot.id) : undefined">
               <span class="bot-dot" :class="{ online: bot.connected }" />
-              <span class="bot-dropdown-name">{{ bot.name }}</span>
+              <span class="bot-card-name">{{ bot.name }}</span>
+              <span v-if="bot.id === store.activeBotId" class="bot-current-badge">当前</span>
               <span v-if="bot.playing && !bot.paused" class="bot-playing-badge">播放中</span>
               <span v-else-if="bot.paused" class="bot-paused-badge">已暂停</span>
               <span v-else-if="bot.connected" class="bot-idle-badge">空闲</span>
               <span v-else class="bot-offline-badge">离线</span>
-            </button>
+            </div>
+            <div class="bot-card-controls">
               <button
-              class="bot-power-btn"
+                v-if="bot.connected"
-              :class="{ online: bot.connected }"
+                class="bot-ctrl-btn danger"
-              :title="bot.connected ? `停止 ${bot.name}` : `启动 ${bot.name}`"
                 :disabled="togglingBots[bot.id]"
                 @click.stop="togglePower(bot)"
               >
-              <Icon :icon="bot.connected ? 'mdi:power' : 'mdi:power-off'" />
+                <Icon icon="mdi:link-off" /> 断开
               </button>
-            <button class="bot-link-btn" :title="`复制 ${bot.name} 的专属链接`" @click.stop="copyBotLink(bot.id)">
+              <button
+                v-else
+                class="bot-ctrl-btn primary"
+                :disabled="togglingBots[bot.id]"
+                @click.stop="togglePower(bot)"
+              >
+                <Icon icon="mdi:link-variant" /> 连接
+              </button>
+              <button
+                v-if="bot.playing || bot.paused"
+                class="bot-ctrl-btn"
+                :disabled="!bot.connected"
+                @click.stop="store.pause()"
+              >
+                <Icon icon="mdi:stop" /> 停止
+              </button>
+              <button
+                v-else
+                class="bot-ctrl-btn"
+                :disabled="!bot.connected"
+                @click.stop="store.resume()"
+              >
+                <Icon icon="mdi:play" /> 播放
+              </button>
+              <button
+                class="bot-ctrl-btn"
+                :disabled="!bot.connected || (!bot.playing && !bot.paused)"
+                @click.stop="store.next()"
+                title="下一首"
+              >
+                <Icon icon="mdi:skip-next" />
+              </button>
+              <button class="bot-ctrl-btn" @click.stop="copyBotLink(bot.id)" title="复制链接">
                 <Icon icon="mdi:link-variant" />
               </button>
             </div>
-          <div class="bot-dropdown-divider" />
+          </div>
-          <div class="bot-dropdown-hint">点击切换 · 🔗 复制专属链接</div>
         </div>
       </div>
 
@@ -59,10 +90,30 @@
       </RouterLink>
     </div>
   </nav>
+
+  <div v-if="linkDialog.open" class="link-dialog-backdrop" @click="closeLinkDialog">
+    <div class="link-dialog" @click.stop>
+      <div class="link-dialog-title">{{ linkDialog.name }} 的专属链接</div>
+      <div class="link-dialog-hint">选中文本并按 Ctrl/Cmd+C 复制，或点击下方按钮</div>
+      <input
+        ref="linkInputRef"
+        class="link-dialog-input"
+        :value="linkDialog.url"
+        readonly
+        @focus="($event.target as HTMLInputElement).select()"
+      />
+      <div class="link-dialog-actions">
+        <button class="link-dialog-btn primary" @click="copyLinkFromDialog">
+          {{ linkDialog.copied ? '已复制' : '复制链接' }}
+        </button>
+        <button class="link-dialog-btn" @click="closeLinkDialog">关闭</button>
+      </div>
+    </div>
+  </div>
 </template>
 
 <script setup lang="ts">
-import { computed, ref, onMounted, onUnmounted } from 'vue';
+import { computed, ref, onMounted, onUnmounted, nextTick, reactive } from 'vue';
 import { Icon } from '@iconify/vue';
 import { usePlayerStore } from '../stores/player.js';
 
@@ -71,17 +122,92 @@ const activeBot = computed(() => store.activeBot);
 const dropdownOpen = ref(false);
 const selectorRef = ref<HTMLElement | null>(null);
 const togglingBots = ref<Record<string, boolean>>({});
+const linkInputRef = ref<HTMLInputElement | null>(null);
+const publicBaseUrl = ref<string | null>(null);
+
+const linkDialog = reactive({
+  open: false,
+  url: '',
+  name: '',
+  copied: false,
+});
 
 function selectBot(id: string) {
   store.setActiveBotId(id);
   dropdownOpen.value = false;
 }
 
-function copyBotLink(id: string) {
+function resolveBaseUrl(): string {
-  const url = `${window.location.origin}/bot/${id}`;
+  const base = publicBaseUrl.value;
-  navigator.clipboard.writeText(url).then(() => {
+  if (base && /^https?:\/\//i.test(base)) return base.replace(/\/+$/, '');
+  return window.location.origin;
+}
+
+async function tryClipboardWrite(text: string): Promise<boolean> {
+  try {
+    if (navigator.clipboard && window.isSecureContext) {
+      await navigator.clipboard.writeText(text);
+      return true;
+    }
+  } catch {
+    // fall through
+  }
+  try {
+    const ta = document.createElement('textarea');
+    ta.value = text;
+    ta.style.position = 'fixed';
+    ta.style.opacity = '0';
+    ta.style.pointerEvents = 'none';
+    document.body.appendChild(ta);
+    ta.focus();
+    ta.select();
+    const ok = document.execCommand('copy');
+    document.body.removeChild(ta);
+    return ok;
+  } catch {
+    return false;
+  }
+}
+
+async function copyBotLink(id: string) {
+  const bot = store.bots.find((b) => b.id === id);
+  const url = `${resolveBaseUrl()}/bot/${id}`;
+  linkDialog.url = url;
+  linkDialog.name = bot?.name ?? '机器人';
+  linkDialog.copied = false;
+  linkDialog.open = true;
   dropdownOpen.value = false;
-  });
+  // Try to copy silently; user can still manually select if it fails.
+  const ok = await tryClipboardWrite(url);
+  if (ok) linkDialog.copied = true;
+  await nextTick();
+  linkInputRef.value?.focus();
+  linkInputRef.value?.select();
+}
+
+async function copyLinkFromDialog() {
+  const ok = await tryClipboardWrite(linkDialog.url);
+  if (ok) {
+    linkDialog.copied = true;
+  } else {
+    linkInputRef.value?.focus();
+    linkInputRef.value?.select();
+  }
+}
+
+function closeLinkDialog() {
+  linkDialog.open = false;
+}
+
+async function loadPublicBaseUrl() {
+  try {
+    const res = await fetch('/api/config/public-url');
+    if (!res.ok) return;
+    const data = (await res.json()) as { publicUrl?: string | null };
+    if (data.publicUrl) publicBaseUrl.value = data.publicUrl;
+  } catch {
+    // ignore — fall back to window.location.origin
+  }
 }
 
 async function togglePower(bot: { id: string; connected: boolean; name: string }) {
@@ -108,6 +234,7 @@ function onClickOutside(e: MouseEvent) {
 
 onMounted(() => {
   document.addEventListener('click', onClickOutside);
+  loadPublicBaseUrl();
 });
 
 onUnmounted(() => {
@@ -131,6 +258,11 @@ onUnmounted(() => {
   @media (max-width: 1336px) {
     padding: 0 5vw;
   }
+
+  @media (max-width: 768px) {
+    padding: 0 16px;
+    height: 52px;
+  }
 }
 
 .logo {
@@ -138,11 +270,20 @@ onUnmounted(() => {
   font-weight: 700;
   color: var(--color-primary);
   margin-right: 40px;
+
+  @media (max-width: 768px) {
+    font-size: 17px;
+    margin-right: 0;
+  }
 }
 
 .nav-links {
   display: flex;
   gap: 24px;
+
+  @media (max-width: 768px) {
+    display: none;
+  }
 }
 
 .nav-link {
@@ -170,7 +311,7 @@ onUnmounted(() => {
   opacity: 0.6;
 
   &.online {
-    background: rgba(51, 94, 234, 0.15);
+    background: var(--color-primary-15);
     color: var(--color-primary);
     opacity: 1;
   }
@@ -199,12 +340,25 @@ onUnmounted(() => {
     background: var(--bg-card);
     border-color: var(--color-primary);
   }
+
+  @media (max-width: 768px) {
+    padding: 6px 10px;
+    font-size: 12px;
+    font-weight: 600;
+    min-height: 32px;
+    gap: 6px;
+    border-radius: var(--radius-full);
+  }
 }
 
 .bot-state-mini {
   font-size: 14px;
-  &.playing { color: #22c55e; }
+  &.playing { color: var(--color-online); }
-  &.paused { color: #eab308; }
+  &.paused { color: var(--color-paused); }
+
+  @media (max-width: 768px) {
+    display: none;
+  }
 }
 
 .bot-chevron {
@@ -215,6 +369,10 @@ onUnmounted(() => {
   &.rotated {
     transform: rotate(180deg);
   }
+
+  @media (max-width: 768px) {
+    display: none;
+  }
 }
 
 .bot-dot {
@@ -225,7 +383,12 @@ onUnmounted(() => {
   flex-shrink: 0;
 
   &.online {
-    background: #22c55e;
+    background: var(--color-online);
+  }
+
+  @media (max-width: 768px) {
+    width: 8px;
+    height: 8px;
   }
 }
 
@@ -234,96 +397,83 @@ onUnmounted(() => {
   overflow: hidden;
   text-overflow: ellipsis;
   white-space: nowrap;
+
+  @media (max-width: 768px) {
+    max-width: 80px;
+  }
 }
 
 .bot-dropdown {
   position: absolute;
   top: calc(100% + 6px);
   right: 0;
-  min-width: 200px;
+  min-width: 320px;
   background: var(--bg-secondary);
   border: 1px solid var(--border-color);
   border-radius: var(--radius-md);
-  padding: 4px;
+  padding: 6px;
-  box-shadow: 0 8px 24px rgba(0, 0, 0, 0.2);
+  box-shadow: var(--shadow-dropdown);
   z-index: 200;
+
+  @media (max-width: 768px) {
+    position: fixed;
+    top: 52px;
+    left: 8px;
+    right: 8px;
+    min-width: auto;
+  }
 }
 
-.bot-dropdown-item {
+.bot-dropdown-header {
+  font-size: 11px;
+  font-weight: 600;
+  color: var(--text-tertiary);
+  padding: 6px 10px 4px;
+  text-transform: uppercase;
+  letter-spacing: 0.5px;
+}
+
+.bot-card {
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
+  padding: 10px;
+  border-radius: var(--radius-sm);
+  margin-bottom: 4px;
+  border: 1px solid transparent;
+  transition: background var(--transition-fast);
+
+  &.active {
+    background: var(--color-primary-12);
+    border-color: rgba(99, 102, 241, 0.25);
+  }
+}
+
+.bot-card-head {
   display: flex;
   align-items: center;
   gap: 8px;
-  flex: 1;
-  min-width: 0;
-  padding: 8px 12px;
-  border-radius: var(--radius-sm);
-  font-size: 13px;
   cursor: pointer;
-  transition: background var(--transition-fast);
-
-  &:hover {
-    background: var(--hover-bg);
-  }
-
-  &.active {
-    background: rgba(51, 94, 234, 0.12);
-    color: var(--color-primary);
-  }
 }
 
-.bot-dropdown-row {
+.bot-card-name {
-  display: flex;
-  align-items: center;
-  gap: 2px;
-}
-
-.bot-dropdown-name {
   flex: 1;
+  font-size: 13px;
+  font-weight: 600;
   min-width: 0;
   overflow: hidden;
   text-overflow: ellipsis;
   white-space: nowrap;
 }
 
-.bot-link-btn {
+.bot-current-badge {
+  font-size: 10px;
+  font-weight: 700;
+  color: var(--color-primary);
+  padding: 2px 6px;
+  border-radius: 4px;
+  background: var(--color-primary-15);
   flex-shrink: 0;
-  padding: 6px 8px;
-  border-radius: var(--radius-sm);
-  font-size: 15px;
-  opacity: 0.4;
-  transition: opacity var(--transition-fast), background var(--transition-fast);
-  cursor: pointer;
-
-  &:hover {
-    opacity: 1;
-    background: var(--hover-bg);
-  }
-}
-
-.bot-power-btn {
-  flex-shrink: 0;
-  padding: 6px 8px;
-  border-radius: var(--radius-sm);
-  font-size: 16px;
-  opacity: 0.5;
-  color: var(--text-tertiary);
-  transition: opacity var(--transition-fast), background var(--transition-fast), color var(--transition-fast);
-  cursor: pointer;
-
-  &:hover:not(:disabled) {
-    opacity: 1;
-    background: var(--hover-bg);
-  }
-
-  &:disabled {
-    opacity: 0.25;
-    cursor: wait;
-  }
-
-  &.online {
-    color: #22c55e;
-    opacity: 0.9;
-  }
 }
 
 .bot-playing-badge,
@@ -331,25 +481,25 @@ onUnmounted(() => {
 .bot-idle-badge,
 .bot-offline-badge {
   font-size: 11px;
-  padding: 1px 6px;
+  padding: 2px 6px;
   border-radius: 4px;
   font-weight: 500;
   flex-shrink: 0;
 }
 
 .bot-playing-badge {
-  background: rgba(34, 197, 94, 0.15);
+  background: var(--color-online-15);
-  color: #22c55e;
+  color: var(--color-online);
 }
 
 .bot-paused-badge {
-  background: rgba(234, 179, 8, 0.15);
+  background: var(--color-paused-15);
-  color: #eab308;
+  color: var(--color-paused);
 }
 
 .bot-idle-badge {
-  background: rgba(51, 94, 234, 0.12);
+  background: var(--hover-bg);
-  color: var(--color-primary);
+  color: var(--text-secondary);
 }
 
 .bot-offline-badge {
@@ -357,17 +507,47 @@ onUnmounted(() => {
   color: var(--text-tertiary);
 }
 
-.bot-dropdown-divider {
+.bot-card-controls {
-  height: 1px;
+  display: flex;
-  background: var(--border-color);
+  gap: 6px;
-  margin: 4px 0;
 }
 
-.bot-dropdown-hint {
+.bot-ctrl-btn {
-  padding: 4px 12px 6px;
+  flex: 1;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  gap: 4px;
+  padding: 6px 8px;
+  border-radius: var(--radius-sm);
+  background: var(--hover-bg);
+  border: 1px solid var(--border-color);
+  color: var(--text-primary);
   font-size: 11px;
-  color: var(--text-tertiary);
+  font-weight: 500;
-  text-align: center;
+  cursor: pointer;
+  white-space: nowrap;
+  transition: all var(--transition-fast);
+
+  &:hover:not(:disabled) {
+    background: var(--bg-card);
+    border-color: var(--color-primary);
+  }
+
+  &:disabled {
+    opacity: 0.4;
+    cursor: not-allowed;
+  }
+
+  &.primary {
+    background: var(--color-primary);
+    color: #fff;
+    border-color: var(--color-primary);
+  }
+
+  &.danger {
+    color: #ef4444;
+  }
 }
 
 .settings-btn {
@@ -375,5 +555,92 @@ onUnmounted(() => {
   opacity: 0.6;
   transition: opacity var(--transition-fast);
   &:hover { opacity: 1; }
+
+  @media (max-width: 768px) {
+    display: none;
+  }
+}
+
+.link-dialog-backdrop {
+  position: fixed;
+  inset: 0;
+  background: var(--bg-modal-scrim);
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  z-index: 1000;
+}
+
+.link-dialog {
+  background: var(--bg-secondary);
+  border: 1px solid var(--border-color);
+  border-radius: var(--radius-md);
+  padding: 20px;
+  min-width: 360px;
+  max-width: 90vw;
+  box-shadow: var(--shadow-modal);
+}
+
+.link-dialog-title {
+  font-size: 15px;
+  font-weight: 600;
+  margin-bottom: 6px;
+}
+
+.link-dialog-hint {
+  font-size: 12px;
+  color: var(--text-tertiary);
+  margin-bottom: 12px;
+}
+
+.link-dialog-input {
+  width: 100%;
+  padding: 10px 12px;
+  font-size: 13px;
+  font-family: ui-monospace, SFMono-Regular, Menlo, monospace;
+  background: var(--hover-bg);
+  border: 1px solid var(--border-color);
+  border-radius: var(--radius-sm);
+  color: inherit;
+  user-select: all;
+  -webkit-user-select: all;
+
+  &:focus {
+    outline: none;
+    border-color: var(--color-primary);
+  }
+}
+
+.link-dialog-actions {
+  display: flex;
+  justify-content: flex-end;
+  gap: 8px;
+  margin-top: 14px;
+}
+
+.link-dialog-btn {
+  padding: 8px 16px;
+  font-size: 13px;
+  font-weight: 500;
+  border-radius: var(--radius-sm);
+  border: 1px solid var(--border-color);
+  background: var(--hover-bg);
+  color: inherit;
+  cursor: pointer;
+  transition: background var(--transition-fast), border-color var(--transition-fast);
+
+  &:hover {
+    background: var(--bg-card);
+  }
+
+  &.primary {
+    background: var(--color-primary);
+    border-color: var(--color-primary);
+    color: #fff;
+
+    &:hover {
+      filter: brightness(1.08);
+    }
+  }
 }
 </style>

web/src/components/Player.vue

@@ -206,6 +206,10 @@ function cycleMode() {
   left: 0;
   right: 0;
   z-index: 100;
+
+  @media (max-width: 768px) {
+    display: none;
+  }
 }
 
 .player-bar {
@@ -326,12 +330,12 @@ function cycleMode() {
 
 .bot-badge {
   display: inline-block;
-  font-size: 10px;
+  font-size: var(--fs-micro);
-  font-weight: 600;
+  font-weight: var(--fw-semi);
   padding: 0 5px;
-  background: rgba(51, 94, 234, 0.15);
+  background: var(--color-primary-15);
   color: var(--color-primary);
-  border-radius: 3px;
+  border-radius: var(--radius-xs);
   line-height: 16px;
   white-space: nowrap;
   flex-shrink: 0;

web/src/components/Queue.vue

@@ -3,6 +3,14 @@
     <div class="queue-header">
       <h3 class="queue-title">播放队列</h3>
       <span class="queue-count">{{ botQueue.length }} 首</span>
+      <button 
+        v-if="botQueue.length > 0"
+        class="clear-btn" 
+        @click="clearAndStop" 
+        title="清空队列并停止播放"
+      >
+        <Icon icon="mdi:stop-circle-outline" />
+      </button>
       <button class="close-btn" @click="$emit('close')">
         <Icon icon="mdi:close" />
       </button>
@@ -70,6 +78,15 @@ async function removeSong(index: number) {
     // Ignore
   }
 }
+
+async function clearAndStop() {
+  try {
+    await store.stop();
+    await store.fetchQueue();
+  } catch {
+    // Ignore
+  }
+}
 </script>
 
 <style lang="scss" scoped>
@@ -117,6 +134,14 @@ async function removeSong(index: number) {
   &:hover { opacity: 1; }
 }
 
+.clear-btn {
+  font-size: 18px;
+  opacity: 0.6;
+  transition: opacity var(--transition-fast);
+  color: var(--text-primary);
+  &:hover { opacity: 1; }
+}
+
 .queue-empty {
   padding: 40px 20px;
   text-align: center;
@@ -146,7 +171,7 @@ async function removeSong(index: number) {
   }
 
   &.active {
-    background: rgba(51, 94, 234, 0.1);
+    background: var(--color-primary-10);
   }
 }
 

web/src/components/SongCard.vue

@@ -18,6 +18,9 @@
       <button class="action-btn" @click.stop="$emit('play')" title="播放">
         <Icon icon="mdi:play" />
       </button>
+      <button class="action-btn" @click.stop="$emit('playNext')" title="下一首播放">
+        <Icon icon="mdi:playlist-play" />
+      </button>
       <button class="action-btn" @click.stop="$emit('add')" title="添加到队列">
         <Icon icon="mdi:playlist-plus" />
       </button>
@@ -28,15 +31,17 @@
 <script setup lang="ts">
 import { Icon } from '@iconify/vue';
 import CoverArt from './CoverArt.vue';
+import { Song } from '../stores/player.js';
 
 defineProps<{
-  song: { id: string; name: string; artist: string; album: string; duration: number; coverUrl: string; platform: string };
+  song: Song;
   index: number;
   active?: boolean;
 }>();
 
 defineEmits<{
   play: [];
+  playNext: [];
   add: [];
 }>();
 
@@ -63,7 +68,7 @@ function formatDuration(seconds: number): string {
   }
 
   &.active {
-    background: rgba(51, 94, 234, 0.1);
+    background: var(--color-primary-10);
   }
 }
 
@@ -96,31 +101,31 @@ function formatDuration(seconds: number): string {
 
 .platform-badge {
   flex-shrink: 0;
-  font-size: 10px;
+  font-size: var(--fs-micro);
-  font-weight: 600;
+  font-weight: var(--fw-semi);
   padding: 1px 5px;
-  border-radius: 3px;
+  border-radius: var(--radius-xs);
   line-height: 1.4;
 }
 
 .badge-netease {
-  background: rgba(232, 17, 35, 0.15);
+  background: var(--brand-netease-15);
-  color: #e81123;
+  color: var(--brand-netease);
 }
 
 .badge-qq {
-  background: rgba(18, 183, 106, 0.15);
+  background: var(--brand-qq-15);
-  color: #12b76a;
+  color: var(--brand-qq);
 }
 
 .badge-bilibili {
-  background: rgba(0, 161, 214, 0.15);
+  background: var(--brand-bilibili-15);
-  color: #00a1d6;
+  color: var(--brand-bilibili);
 }
 
 .badge-youtube {
-  background: rgba(255, 0, 0, 0.12);
+  background: var(--brand-youtube-12);
-  color: #ff0000;
+  color: var(--brand-youtube);
 }
 
 .song-artist {
@@ -151,6 +156,15 @@ function formatDuration(seconds: number): string {
   transition: opacity var(--transition-fast);
 }
 
+// Touch devices have no :hover, so the parent-hover-reveals-actions
+// pattern leaves all action buttons invisible. Always show on coarse-
+// pointer (touch) inputs — this is also where bigger tap targets matter.
+@media (pointer: coarse) {
+  .song-actions {
+    opacity: 1;
+  }
+}
+
 .action-btn {
   font-size: 18px;
   padding: 4px;

web/src/components/SourceTabs.vue

@@ -0,0 +1,94 @@
+<template>
+  <div v-if="sources.length > 0" class="source-tabs">
+    <template v-if="sources.length >= 2">
+      <button
+        v-for="src in sources"
+        :key="src"
+        type="button"
+        class="source-tab"
+        :class="{ active: src === modelValue }"
+        @click="$emit('update:modelValue', src)"
+      >
+        {{ LABELS[src] }}
+      </button>
+    </template>
+    <span v-else class="source-tab-label" :title="`数据来自${LABELS[sources[0]]}`">
+      {{ LABELS[sources[0]] }}
+    </span>
+  </div>
+</template>
+
+<script setup lang="ts">
+import type { Source } from '../stores/player.js';
+
+const LABELS: Record<Source, string> = {
+  netease: '网易云',
+  qq: 'QQ',
+};
+
+defineProps<{
+  modelValue: Source;
+  sources: Source[];
+}>();
+
+defineEmits<{
+  'update:modelValue': [value: Source];
+}>();
+</script>
+
+<style lang="scss" scoped>
+.source-tabs {
+  display: inline-flex;
+  gap: 4px;
+  margin-left: 12px;
+  align-items: center;
+}
+
+.source-tab {
+  padding: 4px 10px;
+  min-height: 28px;
+  font-size: var(--fs-sm);
+  font-weight: var(--fw-medium);
+  color: var(--text-secondary);
+  background: transparent;
+  border: none;
+  border-radius: var(--radius-sm);
+  cursor: pointer;
+  transition: color var(--transition-fast), background var(--transition-fast);
+
+  &:hover {
+    color: var(--text-primary);
+    background: var(--hover-bg);
+  }
+
+  &.active {
+    color: var(--color-primary);
+    background: var(--color-primary-12);
+    font-weight: var(--fw-semi);
+  }
+}
+
+// Single-source mode: not interactive, but tells the user which platform
+// they're looking at instead of leaving them guessing.
+.source-tab-label {
+  padding: 4px 10px;
+  font-size: var(--fs-xs);
+  font-weight: var(--fw-medium);
+  color: var(--text-tertiary);
+  background: var(--hover-bg);
+  border-radius: var(--radius-sm);
+}
+
+@media (max-width: 768px) {
+  .source-tabs {
+    margin-left: 8px;
+    gap: 2px;
+  }
+
+  .source-tab {
+    padding: 6px 10px;
+    min-height: 36px; // larger touch target on mobile
+    font-size: var(--fs-xs);
+  }
+}
+</style>

web/src/components/Toast.vue

@@ -0,0 +1,106 @@
+<template>
+  <Transition name="toast">
+    <div v-if="visible && current" class="toast" :class="`toast--${current.type}`">
+      <Icon :icon="current.type === 'error' ? 'mdi:alert-circle' : 'mdi:information'" class="toast-icon" />
+      <span class="toast-msg">{{ current.message }}</span>
+      <button class="toast-close" @click="visible = false" aria-label="关闭">
+        <Icon icon="mdi:close" />
+      </button>
+    </div>
+  </Transition>
+</template>
+
+<script setup lang="ts">
+import { ref, watch, onUnmounted } from 'vue';
+import { Icon } from '@iconify/vue';
+import { usePlayerStore } from '../stores/player.js';
+
+const store = usePlayerStore();
+const visible = ref(false);
+const current = ref<{ id: number; message: string; type: 'error' | 'info' } | null>(null);
+let timer: ReturnType<typeof setTimeout> | null = null;
+
+watch(
+  () => store.notification?.id,
+  () => {
+    if (!store.notification) return;
+    current.value = store.notification;
+    visible.value = true;
+    if (timer) clearTimeout(timer);
+    timer = setTimeout(() => {
+      visible.value = false;
+    }, current.value.type === 'error' ? 5000 : 3000);
+  }
+);
+
+onUnmounted(() => {
+  if (timer) clearTimeout(timer);
+});
+</script>
+
+<style lang="scss" scoped>
+.toast {
+  position: fixed;
+  left: 50%;
+  bottom: calc(var(--player-height) + 24px);
+  transform: translateX(-50%);
+  display: flex;
+  align-items: center;
+  gap: 10px;
+  padding: 10px 14px;
+  max-width: min(90vw, 480px);
+  background: var(--bg-card);
+  backdrop-filter: blur(20px);
+  border: 1px solid var(--border-color);
+  border-radius: var(--radius-md);
+  box-shadow: var(--shadow-dropdown);
+  font-size: var(--fs-body);
+  color: var(--text-primary);
+  z-index: 1000;
+
+  @media (max-width: 768px) {
+    bottom: calc(var(--player-height) + 60px);  // sit above mobile tabbar
+  }
+}
+
+.toast--error {
+  border-color: var(--brand-netease);
+  .toast-icon { color: var(--brand-netease); }
+}
+
+.toast--info {
+  border-color: var(--color-primary);
+  .toast-icon { color: var(--color-primary); }
+}
+
+.toast-icon {
+  font-size: 18px;
+  flex-shrink: 0;
+}
+
+.toast-msg {
+  flex: 1;
+  line-height: 1.4;
+}
+
+.toast-close {
+  flex-shrink: 0;
+  font-size: 18px;
+  color: var(--text-tertiary);
+  background: transparent;
+  border: none;
+  cursor: pointer;
+  &:hover { color: var(--text-primary); }
+}
+
+.toast-enter-active,
+.toast-leave-active {
+  transition: opacity var(--transition-fast), transform var(--transition-fast);
+}
+
+.toast-enter-from,
+.toast-leave-to {
+  opacity: 0;
+  transform: translateX(-50%) translateY(8px);
+}
+</style>

web/src/main.ts

@@ -3,6 +3,7 @@ import { createPinia } from 'pinia';
 import App from './App.vue';
 import router from './router/index.js';
 import './styles/global.scss';
+import './styles/mobile.scss';
 
 const app = createApp(App);
 app.use(createPinia());

web/src/router/index.ts

@@ -13,6 +13,11 @@ const router = createRouter({
       name: 'search',
       component: () => import('../views/Search.vue'),
     },
+    {
+      path: '/library',
+      name: 'library',
+      component: () => import('../views/Library.vue'),
+    },
     {
       path: '/playlist/:id',
       name: 'playlist',

web/src/stores/player.ts

@@ -8,9 +8,11 @@ export interface Song {
   album: string;
   duration: number;
   coverUrl: string;
-  platform: 'netease' | 'qq';
+  platform: 'netease' | 'qq' | 'bilibili' | 'youtube';
 }
 
+export type Source = 'netease' | 'qq';
+
 export interface BotStatus {
   id: string;
   name: string;
@@ -54,12 +56,17 @@ export const usePlayerStore = defineStore('player', {
     timings: {} as Record<string, TimingState>,
     theme: 'dark' as 'dark' | 'light',
 
-    // Home page cache
+    // Home page cache, split by source
-    recommendPlaylists: [] as PlaylistItem[],
+    recommendPlaylists: { netease: [] as PlaylistItem[], qq: [] as PlaylistItem[] },
-    dailySongs: [] as Song[],
+    dailySongs:         { netease: [] as Song[],         qq: [] as Song[] },
-    userPlaylists: [] as PlaylistItem[],
+    userPlaylists:      { netease: [] as PlaylistItem[], qq: [] as PlaylistItem[] },
     bilibiliPopular: [] as Song[],
+    authStatus: { netease: false, qq: false },
     lastFetchTime: 0,
+
+    // Transient notification for surfacing failures (e.g., "song not playable")
+    // to a global Toast. Bumped `id` triggers re-render of the same message.
+    notification: null as { id: number; message: string; type: 'error' | 'info' } | null,
   }),
 
   getters: {
@@ -91,6 +98,13 @@ export const usePlayerStore = defineStore('player', {
       if (this.isPaused) return Math.min(timing.serverElapsed, maxDuration);
       return Math.min(timing.serverElapsed + (Date.now() - timing.serverSyncTime) / 1000, maxDuration);
     },
+    /** Sources that are currently logged in. Order: netease before qq. */
+    availableSources(): Source[] {
+      const s: Source[] = [];
+      if (this.authStatus.netease) s.push('netease');
+      if (this.authStatus.qq) s.push('qq');
+      return s;
+    },
   },
 
   actions: {
@@ -259,6 +273,30 @@ export const usePlayerStore = defineStore('player', {
       this._syncAfterAction();
     },
 
+    notify(message: string, type: 'error' | 'info' = 'info') {
+      this.notification = { id: Date.now(), message, type };
+    },
+
+    async playSong(song: Song) {
+      if (!this.activeBotId) return;
+      const res = await axios.post(`/api/player/${this.activeBotId}/play-song`, { song });
+      if (res.data?.ok === false && res.data?.message) {
+        this.notify(res.data.message, 'error');
+      }
+      this._setTiming(this.activeBotId, { serverElapsed: 0 });
+      this._syncAfterAction();
+    },
+
+    async playNextSong(song: Song) {
+      if (!this.activeBotId) return;
+      const res = await axios.post(`/api/player/${this.activeBotId}/play-next-song`, { song });
+      if (res.data?.message) {
+        this.notify(res.data.message, res.data.ok === false ? 'error' : 'info');
+      }
+      // Refresh queue so the inserted item shows up in the side panel
+      this.fetchQueue();
+    },
+
     async addToQueue(query: string, platform = 'netease') {
       if (!this.activeBotId) return;
       await axios.post(`/api/player/${this.activeBotId}/add`, { query, platform });
@@ -269,9 +307,17 @@ export const usePlayerStore = defineStore('player', {
       await axios.post(`/api/player/${this.activeBotId}/add-by-id`, { songId, platform });
     },
 
+    async addSong(song: Song) {
+      if (!this.activeBotId) return;
+      await axios.post(`/api/player/${this.activeBotId}/add-song`, { song });
+    },
+
     async playPlaylist(playlistId: string, platform = 'netease') {
       if (!this.activeBotId) return;
-      await axios.post(`/api/player/${this.activeBotId}/play-playlist`, { playlistId, platform });
+      const res = await axios.post(`/api/player/${this.activeBotId}/play-playlist`, { playlistId, platform });
+      if (res.data?.message) {
+        this.notify(res.data.message, res.data.ok === false ? 'error' : 'info');
+      }
       this._setTiming(this.activeBotId, { serverElapsed: 0 });
       this._syncAfterAction();
     },
@@ -330,39 +376,104 @@ export const usePlayerStore = defineStore('player', {
     async setVolume(volume: number) {
       if (!this.activeBotId) return;
       await axios.post(`/api/player/${this.activeBotId}/volume`, { volume });
+      const bot = this.bots.find((b) => b.id === this.activeBotId);
+      if (bot) bot.volume = volume;
     },
 
     async setMode(mode: string) {
       if (!this.activeBotId) return;
       await axios.post(`/api/player/${this.activeBotId}/mode`, { mode });
+      const bot = this.bots.find((b) => b.id === this.activeBotId);
+      if (bot) bot.playMode = mode;
     },
 
     async fetchHomeData() {
-      if (this.lastFetchTime > 0 && Date.now() - this.lastFetchTime < HOME_CACHE_TTL) {
+      // Always check auth status first — if it changed since the cached
+      // fetch (e.g., user logged in/out as a different account), the
+      // cached playlists belong to a different user and we MUST refetch.
+      const [neAuthRes, qqAuthRes] = await Promise.allSettled([
+        axios.get('/api/auth/status', { params: { platform: 'netease' } }),
+        axios.get('/api/auth/status', { params: { platform: 'qq' } }),
+      ]);
+      const newAuth = {
+        netease: neAuthRes.status === 'fulfilled' && !!neAuthRes.value.data?.loggedIn,
+        qq:      qqAuthRes.status === 'fulfilled' && !!qqAuthRes.value.data?.loggedIn,
+      };
+      const authChanged =
+        newAuth.netease !== this.authStatus.netease || newAuth.qq !== this.authStatus.qq;
+      this.authStatus.netease = newAuth.netease;
+      this.authStatus.qq = newAuth.qq;
+
+      // Cache hit only if auth is unchanged AND within TTL.
+      if (
+        !authChanged &&
+        this.lastFetchTime > 0 &&
+        Date.now() - this.lastFetchTime < HOME_CACHE_TTL
+      ) {
         return;
       }
 
-      const [playlistRes, dailyRes, userRes, biliRes] = await Promise.allSettled([
+      // 2. NetEase data: recommend playlists work anonymously; daily/user
-        axios.get('/api/music/recommend/playlists'),
+      // playlists need login but Promise.allSettled isolates failures.
-        axios.get('/api/music/recommend/songs'),
+      const neteasePromises = [
-        axios.get('/api/music/user/playlists'),
+        axios.get('/api/music/recommend/playlists', { params: { platform: 'netease' } }),
-        axios.get('/api/music/bilibili/popular?limit=12'),
+        axios.get('/api/music/recommend/songs',     { params: { platform: 'netease' } }),
+        axios.get('/api/music/user/playlists',      { params: { platform: 'netease' } }),
+      ];
+
+      // 3. QQ data: only fetch when QQ is logged in. When not logged in,
+      // resolve to empty payloads so the same indexed handling works.
+      const emptyPlaylists = { data: { playlists: [] } };
+      const emptySongs     = { data: { songs: [] } };
+      const qqPromises = this.authStatus.qq
+        ? [
+            axios.get('/api/music/recommend/playlists', { params: { platform: 'qq' } }),
+            axios.get('/api/music/recommend/songs',     { params: { platform: 'qq' } }),
+            axios.get('/api/music/user/playlists',      { params: { platform: 'qq' } }),
+          ]
+        : [
+            Promise.resolve(emptyPlaylists),
+            Promise.resolve(emptySongs),
+            Promise.resolve(emptyPlaylists),
+          ];
+
+      const biliPromise = axios.get('/api/music/bilibili/popular?limit=12');
+
+      const results = await Promise.allSettled([
+        ...neteasePromises,
+        ...qqPromises,
+        biliPromise,
       ]);
 
-      if (playlistRes.status === 'fulfilled') {
+      const [neRecPL, neDaily, neUserPL, qqRecPL, qqDaily, qqUserPL, bili] = results;
-        this.recommendPlaylists = playlistRes.value.data.playlists;
+
-      }
+      this.recommendPlaylists.netease =
-      if (dailyRes.status === 'fulfilled') {
+        neRecPL.status === 'fulfilled' ? (neRecPL.value.data.playlists ?? []) : [];
-        this.dailySongs = dailyRes.value.data.songs;
+      this.dailySongs.netease =
-      }
+        neDaily.status === 'fulfilled' ? (neDaily.value.data.songs ?? []) : [];
-      if (userRes.status === 'fulfilled') {
+      this.userPlaylists.netease =
-        this.userPlaylists = userRes.value.data.playlists;
+        neUserPL.status === 'fulfilled' ? (neUserPL.value.data.playlists ?? []) : [];
-      }
+      this.recommendPlaylists.qq =
-      if (biliRes.status === 'fulfilled') {
+        qqRecPL.status === 'fulfilled' ? (qqRecPL.value.data.playlists ?? []) : [];
-        this.bilibiliPopular = biliRes.value.data.songs;
+      this.dailySongs.qq =
+        qqDaily.status === 'fulfilled' ? (qqDaily.value.data.songs ?? []) : [];
+      this.userPlaylists.qq =
+        qqUserPL.status === 'fulfilled' ? (qqUserPL.value.data.playlists ?? []) : [];
+      // bilibili popular: keep previous value on failure (it's an anonymous endpoint
+      // unrelated to user auth state, and stale popular results are harmless)
+      if (bili.status === 'fulfilled') {
+        this.bilibiliPopular = bili.value.data.songs ?? [];
       }
 
+      // Only mark as fetched if at least the auth-status calls succeeded —
+      // a fully failed fetch (network blip / server down) should NOT be
+      // cached for 5 minutes, otherwise the user has to hard-reload to
+      // recover when connectivity returns.
+      const authOk =
+        neAuthRes.status === 'fulfilled' || qqAuthRes.status === 'fulfilled';
+      if (authOk) {
         this.lastFetchTime = Date.now();
+      }
     },
   },
 });

web/src/stores/sourceTabs.ts

@@ -0,0 +1,42 @@
+import type { Source } from './player.js';
+
+const STORAGE_KEY = 'source-tabs';
+
+export type TabKey =
+  | 'home.recommend'
+  | 'home.daily'
+  | 'home.user'
+  | 'library.user';
+
+function readAll(): Partial<Record<TabKey, Source>> {
+  try {
+    const raw = localStorage.getItem(STORAGE_KEY);
+    if (!raw) return {};
+    const parsed = JSON.parse(raw);
+    // typeof null === 'object' and typeof [] === 'object' — both pass a
+    // naive check but neither is a valid record. Reject explicitly so a
+    // corrupted / manipulated value can't smuggle wrong shapes through.
+    if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+      return {};
+    }
+    return parsed as Partial<Record<TabKey, Source>>;
+  } catch {
+    return {};
+  }
+}
+
+export function loadTabSource(key: TabKey, fallback: Source = 'netease'): Source {
+  const all = readAll();
+  const v = all[key];
+  return v === 'netease' || v === 'qq' ? v : fallback;
+}
+
+export function saveTabSource(key: TabKey, value: Source): void {
+  try {
+    const all = readAll();
+    all[key] = value;
+    localStorage.setItem(STORAGE_KEY, JSON.stringify(all));
+  } catch {
+    // localStorage may be unavailable (private browsing); silently no-op
+  }
+}

web/src/styles/variables.scss

@@ -1,33 +1,95 @@
-// YesPlayMusic-inspired design tokens
+// TSMusicBot Design System — canonical tokens
 
 :root {
-  // Fonts
+  // Typography
   --font-primary: 'Barlow', -apple-system, 'PingFang SC', 'Microsoft YaHei', sans-serif;
+  --font-mono: ui-monospace, SFMono-Regular, Menlo, 'Cascadia Code', monospace;
+
+  --fs-hero:  22px;
+  --fs-h1:    20px;
+  --fs-h2:    17px;
+  --fs-h3:    16px;
+  --fs-body:  14px;
+  --fs-sm:    13px;
+  --fs-xs:    12px;
+  --fs-2xs:   11px;
+  --fs-micro: 10px;
+
+  --fw-regular: 400;
+  --fw-medium:  500;
+  --fw-semi:    600;
+  --fw-bold:    700;
+  --fw-black:   800;
+
+  --lh-tight:  1.2;
+  --lh-normal: 1.4;
+  --lh-body:   1.5;
 
   // Spacing
+  --space-1:  4px;
+  --space-2:  8px;
+  --space-3:  12px;
+  --space-4:  16px;
+  --space-5:  20px;
+  --space-6:  24px;
+  --space-8:  36px;
+  --space-10: 80px;
+
+  // Layout
   --navbar-height: 56px;
   --player-height: 56px;
+  --page-gutter: 10vw;
 
   // Radius
+  --radius-xs: 3px;
   --radius-sm: 6px;
   --radius-md: 10px;
   --radius-lg: 14px;
   --radius-xl: 20px;
+  --radius-full: 9999px;
 
   // Transitions
   --transition-fast: 0.2s ease;
   --transition-normal: 0.3s ease;
+  --ease-cinematic: cubic-bezier(0.25, 0.1, 0.25, 1);
+
+  // Shadows
+  --shadow-dropdown: 0 8px 24px rgba(0, 0, 0, 0.2);
+  --shadow-modal: 0 12px 40px rgba(0, 0, 0, 0.35);
 
   // Accent
   --color-primary: #335eea;
   --color-primary-bg: #eaeffd;
+  --color-primary-15: rgba(51, 94, 234, 0.15);
+  --color-primary-10: rgba(51, 94, 234, 0.10);
+  --color-primary-12: rgba(51, 94, 234, 0.12);
+  --gradient-fm: linear-gradient(135deg, #335eea, #6366f1);
+
+  // Semantic (theme-invariant)
+  --color-online: #22c55e;
+  --color-online-15: rgba(34, 197, 94, 0.15);
+  --color-paused: #eab308;
+  --color-paused-15: rgba(234, 179, 8, 0.15);
+
+  // Platform brand
+  --brand-netease: #e81123;
+  --brand-netease-15: rgba(232, 17, 35, 0.15);
+  --brand-qq: #12b76a;
+  --brand-qq-15: rgba(18, 183, 106, 0.15);
+  --brand-bilibili: #00a1d6;
+  --brand-bilibili-15: rgba(0, 161, 214, 0.15);
+  --brand-youtube: #ff0000;
+  --brand-youtube-12: rgba(255, 0, 0, 0.12);
 }
 
+// Dark theme (default)
+:root,
 [data-theme='dark'] {
   --bg-primary: #222222;
   --bg-secondary: #323232;
   --bg-card: rgba(255, 255, 255, 0.04);
   --bg-navbar: rgba(34, 34, 34, 0.86);
+  --bg-modal-scrim: rgba(0, 0, 0, 0.55);
   --text-primary: #ffffff;
   --text-secondary: rgba(255, 255, 255, 0.58);
   --text-tertiary: rgba(255, 255, 255, 0.38);
@@ -40,6 +102,7 @@
   --bg-secondary: #f5f5f7;
   --bg-card: rgba(0, 0, 0, 0.02);
   --bg-navbar: rgba(255, 255, 255, 0.86);
+  --bg-modal-scrim: rgba(0, 0, 0, 0.35);
   --text-primary: #000000;
   --text-secondary: rgba(0, 0, 0, 0.58);
   --text-tertiary: rgba(0, 0, 0, 0.38);

web/src/views/History.vue

@@ -19,8 +19,9 @@
         :song="song"
         :index="i + 1"
         :active="store.currentSong?.id === song.id"
-        @play="store.play(song.name, song.platform)"
+        @play="store.playSong(song)"
-        @add="store.addToQueue(song.name, song.platform)"
+        @playNext="store.playNextSong(song)"
+        @add="store.addSong(song)"
       />
     </div>
   </div>
@@ -35,7 +36,9 @@ import SongCard from '../components/SongCard.vue';
 
 const store = usePlayerStore();
 
-const history = ref<Array<{ id: string; name: string; artist: string; album: string; duration: number; coverUrl: string; platform: string }>>([]);
+import { Song } from '../stores/player.js';
+
+const history = ref<Song[]>([]);
 const loading = ref(true);
 
 onMounted(async () => {

web/src/views/Home.vue

@@ -34,14 +34,17 @@
     </section>
 
     <!-- 每日推荐 -->
-    <section class="section" v-if="store.dailySongs.length > 0">
+    <section class="section" v-if="dailyAvailable.length > 0">
-      <h2 class="section-title">每日推荐</h2>
+      <h2 class="section-title">
+        每日推荐
+        <SourceTabs v-model="dailySource" :sources="dailyAvailable" />
+      </h2>
       <div class="daily-grid">
         <div
-          v-for="song in store.dailySongs.slice(0, 12)"
+          v-for="song in (store.dailySongs[dailySourceSafe] ?? []).slice(0, 12)"
           :key="song.id"
           class="daily-card hover-scale"
-          @click="store.playById(song.id, song.platform)"
+          @click="store.playSong(song)"
         >
           <CoverArt :url="song.coverUrl" :size="120" :radius="10" :show-shadow="true" />
           <div class="daily-name">{{ song.name }}</div>
@@ -51,11 +54,14 @@
     </section>
 
     <!-- 推荐歌单 -->
-    <section class="section" v-if="store.recommendPlaylists.length > 0">
+    <section class="section" v-if="recommendAvailable.length > 0">
-      <h2 class="section-title">推荐歌单</h2>
+      <h2 class="section-title">
+        推荐歌单
+        <SourceTabs v-model="recommendSource" :sources="recommendAvailable" />
+      </h2>
       <div class="playlist-grid">
         <RouterLink
-          v-for="playlist in store.recommendPlaylists"
+          v-for="playlist in (store.recommendPlaylists[recommendSourceSafe] ?? [])"
           :key="playlist.id"
           :to="`/playlist/${playlist.id}?platform=${playlist.platform}`"
           class="playlist-card hover-scale"
@@ -67,10 +73,11 @@
     </section>
 
     <!-- 我的歌单 -->
-    <section class="section" v-if="store.userPlaylists.length > 0">
+    <section class="section" v-if="userAvailable.length > 0">
       <h2 class="section-title">
         我的歌单
-        <span class="section-count">{{ store.userPlaylists.length }}</span>
+        <span v-if="currentUserPlaylists.length > 0" class="section-count">{{ currentUserPlaylists.length }}</span>
+        <SourceTabs v-model="userSource" :sources="userAvailable" />
       </h2>
       <div class="playlist-grid">
         <RouterLink
@@ -85,12 +92,12 @@
         </RouterLink>
       </div>
       <button
-        v-if="store.userPlaylists.length > USER_PLAYLIST_LIMIT"
+        v-if="currentUserPlaylists.length > USER_PLAYLIST_LIMIT"
         class="expand-btn"
         @click="userPlaylistsExpanded = !userPlaylistsExpanded"
       >
         <Icon :icon="userPlaylistsExpanded ? 'mdi:chevron-up' : 'mdi:chevron-down'" />
-        {{ userPlaylistsExpanded ? '收起' : `展开全部 ${store.userPlaylists.length} 个歌单` }}
+        {{ userPlaylistsExpanded ? '收起' : `展开全部 ${currentUserPlaylists.length} 个歌单` }}
       </button>
     </section>
 
@@ -105,7 +112,7 @@
           v-for="song in store.bilibiliPopular.slice(0, 12)"
           :key="song.id"
           class="daily-card hover-scale"
-          @click="store.playById(song.id, song.platform)"
+          @click="store.playSong(song)"
         >
           <CoverArt :url="song.coverUrl" :size="120" :radius="10" :show-shadow="true" />
           <div class="daily-name">{{ song.name }}</div>
@@ -117,19 +124,60 @@
 </template>
 
 <script setup lang="ts">
-import { ref, computed, onMounted } from 'vue';
+import { ref, computed, watch, onMounted } from 'vue';
 import { Icon } from '@iconify/vue';
 import axios from 'axios';
-import { usePlayerStore, type Song } from '../stores/player.js';
+import { usePlayerStore, type Song, type Source } from '../stores/player.js';
+import { loadTabSource, saveTabSource } from '../stores/sourceTabs.js';
 import CoverArt from '../components/CoverArt.vue';
+import SourceTabs from '../components/SourceTabs.vue';
 
 const store = usePlayerStore();
 const USER_PLAYLIST_LIMIT = 20;
 const userPlaylistsExpanded = ref(false);
+
+// Available sources per section.
+// Recommend playlists work anonymously on netease, so it's always available;
+// QQ requires login. This intentionally differs from dailyAvailable/userAvailable.
+const recommendAvailable = computed<Source[]>(() => {
+  const s: Source[] = ['netease'];
+  if (store.authStatus.qq) s.push('qq');
+  return s;
+});
+const dailyAvailable = computed<Source[]>(() => store.availableSources);
+const userAvailable = computed<Source[]>(() => store.availableSources);
+
+// Persisted active source per section.
+const recommendSource = ref<Source>(loadTabSource('home.recommend'));
+const dailySource     = ref<Source>(loadTabSource('home.daily'));
+const userSource      = ref<Source>(loadTabSource('home.user'));
+
+watch(recommendSource, (v) => saveTabSource('home.recommend', v));
+watch(dailySource,     (v) => saveTabSource('home.daily',     v));
+watch(userSource,      (v) => saveTabSource('home.user',      v));
+
+// Fallback when persisted source is no longer available.
+const recommendSourceSafe = computed<Source>(() =>
+  recommendAvailable.value.includes(recommendSource.value)
+    ? recommendSource.value
+    : recommendAvailable.value[0] ?? 'netease'
+);
+const dailySourceSafe = computed<Source>(() =>
+  dailyAvailable.value.includes(dailySource.value)
+    ? dailySource.value
+    : dailyAvailable.value[0] ?? 'netease'
+);
+const userSourceSafe = computed<Source>(() =>
+  userAvailable.value.includes(userSource.value)
+    ? userSource.value
+    : userAvailable.value[0] ?? 'netease'
+);
+
+const currentUserPlaylists = computed(() => store.userPlaylists[userSourceSafe.value] ?? []);
 const visibleUserPlaylists = computed(() =>
   userPlaylistsExpanded.value
-    ? store.userPlaylists
+    ? currentUserPlaylists.value
-    : store.userPlaylists.slice(0, USER_PLAYLIST_LIMIT)
+    : currentUserPlaylists.value.slice(0, USER_PLAYLIST_LIMIT)
 );
 
 async function playFm() {
@@ -179,6 +227,10 @@ onMounted(() => {
 
 .section {
   margin-bottom: 36px;
+
+  @media (max-width: 768px) {
+    margin-bottom: 28px;
+  }
 }
 
 .section-title {
@@ -188,6 +240,11 @@ onMounted(() => {
   display: flex;
   align-items: center;
   gap: 8px;
+
+  @media (max-width: 768px) {
+    font-size: 18px;
+    margin-bottom: 12px;
+  }
 }
 
 .section-count {
@@ -223,7 +280,7 @@ onMounted(() => {
   justify-content: center;
   width: 24px;
   height: 24px;
-  background: #00a1d6;
+  background: var(--brand-bilibili);
   color: white;
   border-radius: 4px;
   font-size: 14px;
@@ -317,6 +374,7 @@ onMounted(() => {
 
   @media (max-width: 1200px) { grid-template-columns: repeat(4, 1fr); }
   @media (max-width: 900px) { grid-template-columns: repeat(3, 1fr); }
+  @media (max-width: 768px) { grid-template-columns: repeat(3, 1fr); gap: 14px; }
 }
 
 .daily-card {
@@ -348,6 +406,7 @@ onMounted(() => {
 
   @media (max-width: 1200px) { grid-template-columns: repeat(4, 1fr); }
   @media (max-width: 900px) { grid-template-columns: repeat(3, 1fr); }
+  @media (max-width: 768px) { grid-template-columns: repeat(3, 1fr); gap: 14px; }
 }
 
 .playlist-card {

web/src/views/Library.vue

@@ -0,0 +1,189 @@
+<template>
+  <div class="library-page">
+    <h1 class="page-title">音乐库</h1>
+
+    <!-- 我的歌单 -->
+    <section class="section" v-if="userAvailable.length > 0">
+      <h2 class="section-title">
+        我的歌单
+        <span v-if="currentUserPlaylists.length > 0" class="section-count">{{ currentUserPlaylists.length }}</span>
+        <SourceTabs v-model="userSource" :sources="userAvailable" />
+      </h2>
+      <div class="playlist-grid">
+        <RouterLink
+          v-for="pl in currentUserPlaylists"
+          :key="pl.id"
+          :to="`/playlist/${pl.id}?platform=${pl.platform}`"
+          class="playlist-card hover-scale"
+        >
+          <CoverArt :url="pl.coverUrl" :size="160" :radius="10" :show-shadow="true" />
+          <div class="playlist-name">{{ pl.name }}</div>
+          <div class="playlist-count">{{ pl.songCount }} 首</div>
+        </RouterLink>
+      </div>
+    </section>
+
+    <!-- 最近播放 -->
+    <section class="section">
+      <h2 class="section-title">最近播放</h2>
+      <div v-if="historyLoading" class="loading">加载中...</div>
+      <div v-else-if="history.length === 0" class="empty">暂无播放记录</div>
+      <div v-else class="song-list">
+        <SongCard
+          v-for="(song, i) in history.slice(0, 10)"
+          :key="`hist-${song.id}-${i}`"
+          :song="song"
+          :index="i + 1"
+          :active="store.currentSong?.id === song.id"
+          @play="store.play(song.name, song.platform)"
+          @playNext="store.playNextSong(song)"
+          @add="store.addToQueue(song.name, song.platform)"
+        />
+      </div>
+    </section>
+
+    <div v-if="!historyLoading && userAvailable.length === 0 && history.length === 0" class="empty-state">
+      <Icon icon="mdi:music-box-outline" class="empty-icon" />
+      <div>登录网易云或QQ音乐后，这里将显示你的歌单和播放记录</div>
+    </div>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { ref, computed, watch, onMounted } from 'vue';
+import { Icon } from '@iconify/vue';
+import axios from 'axios';
+import { usePlayerStore, type Song, type Source } from '../stores/player.js';
+import { loadTabSource, saveTabSource } from '../stores/sourceTabs.js';
+import CoverArt from '../components/CoverArt.vue';
+import SongCard from '../components/SongCard.vue';
+import SourceTabs from '../components/SourceTabs.vue';
+
+const store = usePlayerStore();
+
+const history = ref<Song[]>([]);
+const historyLoading = ref(true);
+
+const userAvailable = computed<Source[]>(() => store.availableSources);
+
+const userSource = ref<Source>(loadTabSource('library.user'));
+watch(userSource, (v) => saveTabSource('library.user', v));
+
+const userSourceSafe = computed<Source>(() =>
+  userAvailable.value.includes(userSource.value)
+    ? userSource.value
+    : userAvailable.value[0] ?? 'netease'
+);
+
+const currentUserPlaylists = computed(() => store.userPlaylists[userSourceSafe.value] ?? []);
+
+onMounted(async () => {
+  if (!store.activeBotId) {
+    await store.fetchBots();
+  }
+
+  store.fetchHomeData();
+
+  if (store.activeBotId) {
+    try {
+      const res = await axios.get(`/api/player/${store.activeBotId}/history`);
+      history.value = res.data.history ?? [];
+    } catch {
+      // API may not be ready
+    }
+  }
+
+  historyLoading.value = false;
+});
+</script>
+
+<style lang="scss" scoped>
+.page-title {
+  font-size: var(--fs-hero);
+  font-weight: var(--fw-bold);
+  margin-bottom: 24px;
+}
+
+.section {
+  margin-bottom: 36px;
+}
+
+.section-title {
+  font-size: var(--fs-hero);
+  font-weight: var(--fw-bold);
+  margin-bottom: 16px;
+  display: flex;
+  align-items: center;
+  gap: 8px;
+}
+
+.section-count {
+  font-size: var(--fs-sm);
+  font-weight: var(--fw-medium);
+  color: var(--text-tertiary);
+}
+
+.playlist-grid {
+  display: grid;
+  grid-template-columns: repeat(5, 1fr);
+  gap: 24px;
+
+  @media (max-width: 1200px) { grid-template-columns: repeat(4, 1fr); }
+  @media (max-width: 900px) { grid-template-columns: repeat(3, 1fr); }
+}
+
+.playlist-card {
+  cursor: pointer;
+  display: block;
+  text-decoration: none;
+  color: inherit;
+}
+
+.playlist-name {
+  margin-top: 8px;
+  font-size: var(--fs-sm);
+  font-weight: var(--fw-medium);
+  display: -webkit-box;
+  -webkit-line-clamp: 2;
+  -webkit-box-orient: vertical;
+  overflow: hidden;
+}
+
+.playlist-count {
+  font-size: var(--fs-xs);
+  color: var(--text-tertiary);
+  margin-top: 2px;
+}
+
+.song-list {
+  display: flex;
+  flex-direction: column;
+  gap: 2px;
+}
+
+.loading {
+  text-align: center;
+  padding: 40px;
+  color: var(--text-secondary);
+}
+
+.empty {
+  text-align: center;
+  padding: 40px;
+  color: var(--text-tertiary);
+  font-size: var(--fs-body);
+}
+
+.empty-state {
+  text-align: center;
+  padding: 80px 20px;
+  color: var(--text-tertiary);
+  font-size: var(--fs-body);
+}
+
+.empty-icon {
+  font-size: 48px;
+  opacity: 0.3;
+  margin-bottom: 16px;
+}
+</style>

web/src/views/Playlist.vue

@@ -31,8 +31,9 @@
           :song="song"
           :index="i + 1"
           :active="store.currentSong?.id === song.id"
-          @play="store.playById(song.id, song.platform)"
+          @play="store.playSong(song)"
-          @add="store.addToQueueById(song.id, song.platform)"
+          @playNext="store.playNextSong(song)"
+          @add="store.addSong(song)"
         />
       </div>
     </template>
@@ -53,6 +54,8 @@ import SongCard from '../components/SongCard.vue';
 const store = usePlayerStore();
 const route = useRoute();
 
+import { Song } from '../stores/player.js';
+
 interface PlaylistDetail {
   id: string;
   name: string;
@@ -61,18 +64,8 @@ interface PlaylistDetail {
   songCount: number;
 }
 
-interface SongItem {
-  id: string;
-  name: string;
-  artist: string;
-  album: string;
-  duration: number;
-  coverUrl: string;
-  platform: string;
-}
-
 const playlist = ref<PlaylistDetail | null>(null);
-const songs = ref<SongItem[]>([]);
+const songs = ref<Song[]>([]);
 const loading = ref(true);
 
 async function playAll() {
@@ -85,20 +78,37 @@ onMounted(async () => {
   const id = route.params.id as string;
   const platform = (route.query.platform as string) || 'netease';
 
-  try {
+  // allSettled, not Promise.all — if detail 404s but songs is fine
-    const [detailRes, songsRes] = await Promise.all([
+  // (e.g., a QQ playlist whose detail endpoint flaked but the song
+  // list resolved), we still want to show the songs rather than
+  // the "歌单不存在" empty state.
+  const [detailRes, songsRes] = await Promise.allSettled([
     axios.get(`/api/music/playlist/${id}/detail`, { params: { platform } }),
     axios.get(`/api/music/playlist/${id}`, { params: { platform } }),
   ]);
-    playlist.value = detailRes.data.playlist;
+
-    songs.value = songsRes.data.songs;
+  const detail = detailRes.status === 'fulfilled' ? detailRes.value.data?.playlist : null;
-  } catch (err: any) {
+  const songList = songsRes.status === 'fulfilled' ? (songsRes.value.data?.songs ?? []) : [];
-    console.error('Failed to load playlist:', err?.response?.status, err?.message);
+
+  if (detail) {
+    playlist.value = detail;
+  } else if (songList.length > 0) {
+    // Fall back to a stub built from the route + first song's cover.
+    playlist.value = {
+      id,
+      name: '歌单',
+      description: '',
+      coverUrl: songList[0]?.coverUrl ?? '',
+      songCount: songList.length,
+    };
+  } else {
     playlist.value = null;
-    songs.value = [];
+    if (detailRes.status === 'rejected') {
-  } finally {
+      console.error('Failed to load playlist detail:', (detailRes.reason as any)?.response?.status, (detailRes.reason as any)?.message);
-    loading.value = false;
     }
+  }
+  songs.value = songList;
+  loading.value = false;
 });
 </script>
 

web/src/views/Search.vue

@@ -27,8 +27,9 @@
         :song="song"
         :index="i + 1"
         :active="store.currentSong?.id === song.id"
-        @play="store.playById(song.id, song.platform)"
+        @play="store.playSong(song)"
-        @add="store.addToQueueById(song.id, song.platform)"
+        @playNext="store.playNextSong(song)"
+        @add="store.addSong(song)"
       />
     </div>
 
@@ -50,7 +51,9 @@ const store = usePlayerStore();
 const route = useRoute();
 
 const query = ref((route.query.q as string) || '');
-const results = ref<Array<{ id: string; name: string; artist: string; album: string; duration: number; coverUrl: string; platform: string }>>([]);
+import { Song } from '../stores/player.js';
+
+const results = ref<Song[]>([]);
 const loading = ref(false);
 const searched = ref(false);
 

web/src/views/Settings.vue

@@ -116,6 +116,10 @@
           <label>服务器密码（可选）</label>
           <input v-model="newBotServerPassword" class="input" type="password" placeholder="服务器有密码时填写" />
         </div>
+        <div class="form-group">
+          <label>自定义头像（可选）</label>
+          <AvatarUpload v-model="newBotAvatar" />
+        </div>
         <button class="btn-primary" @click="createBot">创建</button>
       </div>
     </section>
@@ -371,6 +375,85 @@
         </div>
       </div>
     </section>
+    
+    <!-- Idle Timeout -->
+    <section class="settings-section">
+      <h2 class="section-title">行为设置</h2>
+      <div class="setting-row">
+        <div class="setting-label">
+          <Icon icon="mdi:timer-off-outline" class="setting-icon" />
+          <div>
+            <div>闲置自动退出</div>
+            <div style="font-size:12px; opacity:0.6; margin-top:2px">频道无人时，机器人自动断开的等待时间（0 = 不退出）</div>
+          </div>
+        </div>
+        <div class="prefix-input-wrap">
+          <input
+            v-model.number="idleTimeout"
+            type="number"
+            min="0"
+            class="input input-sm"
+            style="max-width:80px"
+            placeholder="0"
+          />
+          <span style="font-size:13px; opacity:0.7">分钟</span>
+          <button class="btn-primary" @click="saveIdleTimeout">保存</button>
+        </div>
+      </div>
+    </section>
+
+    <!-- Bot Profile (TeamSpeak Behavior) -->
+    <section class="settings-section">
+      <h2 class="section-title">机器人 Profile（TeamSpeak 行为）</h2>
+      <p class="profile-section-hint">控制 bot 在 TeamSpeak 上自动同步歌曲信息的方式。⚠️ 标记的项会触发频道里所有人的提示音。</p>
+      <div v-if="store.bots.length === 0" class="empty-hint">还没有机器人，先在上面创建一个。</div>
+      <div v-else class="profile-bot-list">
+        <div v-for="bot in store.bots" :key="bot.id" class="profile-bot">
+          <button
+            class="profile-bot-header"
+            :class="{ expanded: profileExpanded[bot.id] }"
+            @click="toggleProfileExpanded(bot.id)"
+          >
+            <Icon :icon="profileExpanded[bot.id] ? 'mdi:chevron-down' : 'mdi:chevron-right'" />
+            <span class="profile-bot-name">{{ bot.name }}</span>
+          </button>
+          <div v-if="profileExpanded[bot.id]" class="profile-toggles">
+            <div v-if="profileLoadError[bot.id]" class="profile-loading profile-error">
+              {{ profileLoadError[bot.id] }}
+              <button class="btn-link" @click="loadProfileConfig(bot.id)">重试</button>
+            </div>
+            <div v-else-if="!profileConfigs[bot.id]" class="profile-loading">加载中...</div>
+            <label
+              v-else
+              v-for="t in PROFILE_TOGGLES"
+              :key="t.key"
+              class="profile-toggle"
+            >
+              <div class="profile-toggle-text">
+                <div class="profile-toggle-label">
+                  {{ t.label }}
+                  <span v-if="t.warning" class="profile-warn-tag">⚠️ {{ t.warning }}</span>
+                </div>
+                <div class="profile-toggle-hint">{{ t.hint }}</div>
+              </div>
+              <input
+                type="checkbox"
+                class="profile-toggle-switch"
+                :checked="profileConfigs[bot.id][t.key]"
+                @change="updateProfile(bot.id, t.key, ($event.target as HTMLInputElement).checked)"
+              />
+            </label>
+            <div v-if="profileConfigs[bot.id]" class="profile-toggle profile-toggle-static">
+              <div class="profile-toggle-text">
+                <div class="profile-toggle-label">自定义头像</div>
+                <div class="profile-toggle-hint">无论封面同步是否开启，停播时都会回到这张图</div>
+              </div>
+              <CustomAvatarRow :bot-id="bot.id" />
+            </div>
+          </div>
+        </div>
+      </div>
+    </section>
   </div>
 </template>
 
@@ -378,6 +461,8 @@
 import { ref, reactive, onMounted, onUnmounted } from 'vue';
 import { Icon } from '@iconify/vue';
 import axios from 'axios';
+import AvatarUpload from '../components/AvatarUpload.vue';
+import CustomAvatarRow from '../components/CustomAvatarRow.vue';
 import QRCode from 'qrcode';
 import { usePlayerStore } from '../stores/player.js';
 
@@ -403,6 +488,7 @@ const newBotPort = ref(9987);
 const newBotNickname = ref('MusicBot');
 const newBotChannel = ref('');
 const newBotServerPassword = ref('');
+const newBotAvatar = ref<string | null>(null);
 
 // Edit bot
 const editingBot = ref<string | null>(null);
@@ -563,7 +649,7 @@ async function pollQrStatus(platform: string) {
 async function createBot() {
   if (!newBotName.value || !newBotServer.value) return;
   try {
-    await axios.post('/api/bot', {
+    const res = await axios.post('/api/bot', {
       name: newBotName.value,
       serverAddress: newBotServer.value,
       serverPort: newBotPort.value || 9987,
@@ -572,12 +658,20 @@ async function createBot() {
       serverPassword: newBotServerPassword.value || undefined,
       autoStart: false,
     });
+    if (newBotAvatar.value && res.data?.id) {
+      try {
+        await axios.put(`/api/bot/${res.data.id}/avatar`, { dataUrl: newBotAvatar.value });
+      } catch (err) {
+        console.warn('failed to set avatar on new bot', err);
+      }
+    }
     newBotName.value = '';
     newBotServer.value = '';
     newBotPort.value = 9987;
     newBotNickname.value = 'MusicBot';
     newBotChannel.value = '';
     newBotServerPassword.value = '';
+    newBotAvatar.value = null;
     await store.fetchBots();
   } catch {
     // Ignore
@@ -661,10 +755,93 @@ async function savePrefix() {
   // Prefix is saved client-side for now
 }
 
+// Idle timeout
+const idleTimeout = ref(0);
+
+async function loadIdleTimeout() {
+  try {
+    const res = await axios.get('/api/bot/settings');
+    idleTimeout.value = res.data.idleTimeoutMinutes ?? 0;
+  } catch { /* ignore */ }
+}
+
+async function saveIdleTimeout() {
+  try {
+    await axios.post('/api/bot/settings', { idleTimeoutMinutes: idleTimeout.value });
+  } catch { /* ignore */ }
+}
+
+// --- Bot Profile config ---
+interface ProfileConfig {
+  avatarEnabled: boolean;
+  descriptionEnabled: boolean;
+  nicknameEnabled: boolean;
+  awayStatusEnabled: boolean;
+  channelDescEnabled: boolean;
+  nowPlayingMsgEnabled: boolean;
+}
+
+const PROFILE_TOGGLES: ReadonlyArray<{
+  key: keyof ProfileConfig;
+  label: string;
+  hint: string;
+  warning: string | null;
+}> = [
+  { key: 'avatarEnabled',       label: '同步头像',           hint: '使用专辑封面作为 bot 头像',                  warning: null },
+  { key: 'descriptionEnabled',  label: '同步个人描述',       hint: '在 bot 简介里显示当前播放的歌曲',            warning: null },
+  { key: 'nicknameEnabled',     label: '同步昵称',           hint: 'bot 昵称跟着歌名变化',                       warning: null },
+  { key: 'awayStatusEnabled',   label: '走开状态',           hint: '停止播放时把 bot 设为"走开"',               warning: null },
+  { key: 'channelDescEnabled',  label: '更新频道描述',       hint: '把"正在播放"信息写入频道描述',             warning: '频道编辑提示音' },
+  { key: 'nowPlayingMsgEnabled',label: '推送"正在播放"消息', hint: '切歌时在频道里发一条文字消息',               warning: '新消息提示音' },
+];
+
+const profileConfigs = reactive<Record<string, ProfileConfig>>({});
+const profileExpanded = reactive<Record<string, boolean>>({});
+const profileLoadError = reactive<Record<string, string | null>>({});
+
+async function loadProfileConfig(botId: string) {
+  if (profileConfigs[botId]) return;
+  profileLoadError[botId] = null;
+  try {
+    const res = await axios.get(`/api/player/${botId}/profile`);
+    // Defensive: a 200 response with non-object body (empty / proxy
+    // injection / etc.) would otherwise leave the row stuck on
+    // "加载中..." because profileConfigs[botId] would be falsy.
+    if (!res.data || typeof res.data !== 'object' || typeof res.data.avatarEnabled !== 'boolean') {
+      profileLoadError[botId] = '响应格式异常';
+      return;
+    }
+    profileConfigs[botId] = res.data;
+  } catch (err: any) {
+    profileLoadError[botId] = err?.response?.status === 404
+      ? '机器人未加载'
+      : '加载失败，请重试';
+  }
+}
+
+function toggleProfileExpanded(botId: string) {
+  profileExpanded[botId] = !profileExpanded[botId];
+  if (profileExpanded[botId]) loadProfileConfig(botId);
+}
+
+async function updateProfile(botId: string, key: keyof ProfileConfig, value: boolean) {
+  const cfg = profileConfigs[botId];
+  if (!cfg) return;
+  const prev = cfg[key];
+  cfg[key] = value; // optimistic
+  try {
+    const res = await axios.put(`/api/player/${botId}/profile`, { [key]: value });
+    profileConfigs[botId] = res.data;
+  } catch {
+    cfg[key] = prev; // revert
+  }
+}
+
 onMounted(() => {
   store.fetchBots(); // Refresh bot status on page visit
   checkAuthStatus();
   loadQuality();
+  loadIdleTimeout();
 });
 
 onUnmounted(() => {
@@ -777,16 +954,16 @@ onUnmounted(() => {
   background: var(--border-color);
   color: var(--text-tertiary);
   &.online {
-    background: rgba(51, 94, 234, 0.15);
+    background: var(--color-primary-15);
     color: var(--color-primary);
   }
   &.playing {
-    background: rgba(76, 175, 80, 0.15);
+    background: var(--color-online-15);
-    color: #4caf50;
+    color: var(--color-online);
   }
   &.paused {
-    background: rgba(255, 152, 0, 0.15);
+    background: var(--color-paused-15);
-    color: #ff9800;
+    color: var(--color-paused);
   }
 }
 
@@ -810,7 +987,7 @@ onUnmounted(() => {
   color: var(--color-primary);
 
   &.bilibili-icon {
-    color: #00a1d6;
+    color: var(--brand-bilibili);
   }
 }
 
@@ -822,7 +999,7 @@ onUnmounted(() => {
 .account-status {
   font-size: 12px;
   color: var(--text-tertiary);
-  &.logged { color: #4caf50; }
+  &.logged { color: var(--color-online); }
 }
 
 .login-methods {
@@ -845,7 +1022,7 @@ onUnmounted(() => {
 
   &:hover { border-color: var(--color-primary); color: var(--color-primary); }
   &.active {
-    background: rgba(51, 94, 234, 0.1);
+    background: var(--color-primary-10);
     border-color: var(--color-primary);
     color: var(--color-primary);
   }
@@ -969,7 +1146,7 @@ onUnmounted(() => {
   &:hover { border-color: var(--border-color); }
   &.active {
     border-color: var(--color-primary);
-    background: rgba(51, 94, 234, 0.1);
+    background: var(--color-primary-10);
   }
 }
 
@@ -1096,4 +1273,194 @@ onUnmounted(() => {
   from { transform: rotate(0deg); }
   to { transform: rotate(360deg); }
 }
+
+// --- Bot Profile section ---
+.profile-section-hint {
+  font-size: 13px;
+  color: var(--text-secondary);
+  margin: -8px 0 16px;
+  line-height: 1.5;
+}
+
+.empty-hint {
+  font-size: 13px;
+  color: var(--text-tertiary);
+  padding: 12px;
+}
+
+.profile-bot-list {
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
+}
+
+.profile-bot {
+  border: 1px solid var(--border-color);
+  border-radius: var(--radius-md);
+  overflow: hidden;
+}
+
+.profile-bot-header {
+  width: 100%;
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  padding: 12px 16px;
+  background: transparent;
+  font-size: 14px;
+  font-weight: 600;
+  color: var(--text-primary);
+  cursor: pointer;
+  transition: background var(--transition-fast);
+
+  &:hover { background: var(--hover-bg); }
+  &.expanded { background: var(--hover-bg); }
+}
+
+.profile-bot-name {
+  flex: 1;
+  text-align: left;
+}
+
+.profile-toggles {
+  display: flex;
+  flex-direction: column;
+  padding: 0 16px 8px;
+  border-top: 1px solid var(--border-color);
+}
+
+.profile-loading {
+  padding: 16px 0;
+  font-size: 13px;
+  color: var(--text-tertiary);
+  text-align: center;
+}
+
+.profile-error {
+  color: var(--brand-netease); // re-uses red brand color for error state
+
+  .btn-link {
+    margin-left: 8px;
+    font-size: 13px;
+    color: var(--color-primary);
+    text-decoration: underline;
+    background: transparent;
+    cursor: pointer;
+  }
+}
+
+.profile-toggle {
+  display: flex;
+  align-items: center;
+  gap: 16px;
+  padding: 14px 0;
+  border-bottom: 1px solid var(--border-color);
+  cursor: pointer;
+
+  &:last-child { border-bottom: none; }
+}
+
+.profile-toggle-text {
+  flex: 1;
+  min-width: 0;
+}
+
+.profile-toggle-label {
+  font-size: 14px;
+  font-weight: 500;
+  color: var(--text-primary);
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  flex-wrap: wrap;
+  line-height: 1.3;
+}
+
+.profile-warn-tag {
+  font-size: 11px;
+  font-weight: 500;
+  padding: 2px 6px;
+  background: var(--color-paused-15);
+  color: var(--color-paused);
+  border-radius: var(--radius-xs);
+  white-space: nowrap;
+}
+
+.profile-toggle-hint {
+  font-size: 12px;
+  color: var(--text-tertiary);
+  margin-top: 4px;
+  line-height: 1.4;
+}
+
+.profile-toggle-switch {
+  flex-shrink: 0;
+  appearance: none;
+  -webkit-appearance: none;
+  width: 40px;
+  height: 22px;
+  border-radius: 999px;
+  background: var(--bg-secondary);
+  border: 1px solid var(--border-color);
+  position: relative;
+  cursor: pointer;
+  transition: background var(--transition-fast), border-color var(--transition-fast);
+  margin: 0;
+
+  &::before {
+    content: '';
+    position: absolute;
+    top: 2px;
+    left: 2px;
+    width: 16px;
+    height: 16px;
+    border-radius: 50%;
+    background: var(--text-secondary);
+    transition: transform var(--transition-fast), background var(--transition-fast);
+  }
+
+  &:checked {
+    background: var(--color-primary);
+    border-color: var(--color-primary);
+
+    &::before {
+      transform: translateX(18px);
+      background: white;
+    }
+  }
+}
+
+.profile-toggle-static {
+  cursor: default;
+  align-items: flex-start;
+}
+
+@media (max-width: 768px) {
+  .profile-bot-header {
+    padding: 14px 12px;
+    font-size: 15px;
+  }
+
+  .profile-toggles {
+    padding: 0 12px 6px;
+  }
+
+  .profile-toggle {
+    gap: 12px;
+    padding: 14px 0;
+  }
+
+  .profile-toggle-switch {
+    width: 44px;
+    height: 24px;
+
+    &::before {
+      width: 18px;
+      height: 18px;
+    }
+    &:checked::before {
+      transform: translateX(20px);
+    }
+  }
+}
 </style>