Merge pull request #65 from ZHANGTIANYAO1/fix/bilibili-wbi-search

fix(bilibili): wbi-sign search params — legacy /search/type now anti-bot blocked

.claude/settings.local.json

@@ -19,8 +19,6 @@
       "Read(//tmp/**)"
     ],
     "deny": [
-      "Bash(git push * main)",
-      "Bash(git push * master)",
       "Bash(git push --force *)",
       "Bash(rm -rf /)"
     ]

README.md

@@ -253,6 +253,7 @@ sudo systemctl start tsmusicbot
 | `!stop` | 停止播放并清空队列 |
 | `!vol <0-100>` | 设置音量 |
 | `!queue` | 查看播放队列 |
+| `!remove <位置>` | 从队列中删除指定位置的歌曲（位置从 1 开始，见 `!queue`） |
 | `!mode <seq\|loop\|random\|rloop>` | 切换播放模式 |
 | `!playlist <歌单名或ID>` | 加载歌单（支持名称模糊搜索和 ID） |
 | `!playlist -q <歌单名>` | 从 QQ 音乐搜索并加载歌单 |

scripts/download-binaries.mjs

@@ -0,0 +1,161 @@
+#!/usr/bin/env node
+
+/**
+ * Download native binaries (ffmpeg + @discordjs/opus) from npmmirror CDN.
+ * Called by setup.bat after npm install --ignore-scripts.
+ *
+ * Usage: node scripts/download-binaries.mjs [cdn_base_url]
+ */
+
+import { existsSync, mkdirSync, writeFileSync, statSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, dirname } from "node:path";
+import { createGunzip } from "node:zlib";
+import { pipeline } from "node:stream/promises";
+import { createWriteStream } from "node:fs";
+import { get } from "node:https";
+import { Readable } from "node:stream";
+import { execSync } from "node:child_process";
+import { createRequire } from "node:module";
+import { fileURLToPath } from "node:url";
+
+const ROOT = join(dirname(fileURLToPath(import.meta.url)), "..");
+const CDN = process.argv[2] || "https://cdn.npmmirror.com/binaries";
+const PLATFORM = process.platform;
+const ARCH = process.arch;
+const NODE_ABI = process.versions.modules;
+
+function download(url) {
+  return new Promise((resolve, reject) => {
+    const req = get(url, { timeout: 120000 }, (res) => {
+      if (res.statusCode < 200 || res.statusCode >= 400) {
+        reject(new Error(`HTTP ${res.statusCode}: ${url}`));
+        return;
+      }
+      const chunks = [];
+      res.on("data", (c) => chunks.push(c));
+      res.on("end", () => resolve(Buffer.concat(chunks)));
+    });
+    req.on("error", reject);
+    req.on("timeout", () => { req.destroy(); reject(new Error("timeout")); });
+  });
+}
+
+function log(msg) {
+  console.log(`  [binary] ${msg}`);
+}
+
+function isValidSize(filePath, minBytes) {
+  try { return statSync(filePath).size >= minBytes; } catch { return false; }
+}
+
+async function downloadFfmpeg() {
+  const ffDir = join(ROOT, "node_modules", "ffmpeg-static");
+  const ffName = PLATFORM === "win32" ? "ffmpeg.exe" : "ffmpeg";
+  const ffDest = join(ffDir, ffName);
+
+  if (!existsSync(ffDir)) { log("ffmpeg-static not installed, skipping"); return false; }
+  if (existsSync(ffDest)) {
+    if (isValidSize(ffDest, 50 * 1024 * 1024)) {
+      log("ffmpeg already exists, skipping");
+      return true;
+    }
+    log("ffmpeg exists but seems corrupted (too small), re-downloading...");
+  }
+
+  const url = `${CDN}/ffmpeg-static/b6.1.1/ffmpeg-${PLATFORM}-${ARCH}.gz`;
+  log("Downloading ffmpeg...");
+  const buf = await download(url);
+  await pipeline(Readable.from(buf), createGunzip(), createWriteStream(ffDest));
+  try { execSync(`chmod +x "${ffDest}"`); } catch {}
+  const size = ((await statSync(ffDest)).size / 1024 / 1024).toFixed(1);
+  log(`ffmpeg OK (${size} MB)`);
+  return true;
+}
+
+async function downloadOpus() {
+  const opusDir = join(ROOT, "node_modules", "@discordjs", "opus");
+  const prebuildName = `node-v${NODE_ABI}-napi-v3-${PLATFORM}-${ARCH}-unknown-unknown`;
+  const opusDest = join(opusDir, "prebuild", prebuildName, "opus.node");
+
+  if (!existsSync(opusDir)) { log("@discordjs/opus not installed, skipping"); return false; }
+  if (existsSync(opusDest)) {
+    if (isValidSize(opusDest, 100 * 1024)) {
+      log("@discordjs/opus already exists, skipping");
+      return true;
+    }
+    log("@discordjs/opus exists but seems corrupted (too small), re-downloading...");
+  }
+
+  const url = `${CDN}/@discordjs/opus/v0.10.0/opus-v0.10.0-node-v${NODE_ABI}-napi-v3-${PLATFORM}-${ARCH}-unknown-unknown.tar.gz`;
+  log("Downloading @discordjs/opus...");
+  try {
+    const buf = await download(url);
+    mkdirSync(dirname(opusDest), { recursive: true });
+    const require = createRequire(import.meta.url);
+    const tar = require("tar");
+    const tmpFile = join(tmpdir(), `discordjs-opus-${Date.now()}.tar.gz`);
+    writeFileSync(tmpFile, buf);
+    await tar.extract({ cwd: join(opusDir, "prebuild"), file: tmpFile });
+    log("@discordjs/opus OK");
+    return true;
+  } catch (err) {
+    log(`CDN download failed (${err.message}), trying to build from source...`);
+    try {
+      execSync("npm rebuild @discordjs/opus", { cwd: ROOT, stdio: "inherit" });
+      if (existsSync(opusDest) && isValidSize(opusDest, 100 * 1024)) {
+        log("@discordjs/opus built from source OK");
+        return true;
+      }
+      log("Source build completed but .node file not found");
+      return false;
+    } catch (buildErr) {
+      log(`Source build failed: ${buildErr.message}`);
+      log("Install build tools: sudo apt install build-essential (Ubuntu/Debian)");
+      log("                    sudo yum groupinstall 'Development Tools' (CentOS/RHEL)");
+      return false;
+    }
+  }
+}
+
+async function downloadBetterSqlite3() {
+  const pkgDir = join(ROOT, "node_modules", "better-sqlite3");
+  const dest = join(pkgDir, "build", "Release", "better_sqlite3.node");
+
+  if (!existsSync(pkgDir)) { log("better-sqlite3 not installed, skipping"); return false; }
+  if (existsSync(dest)) {
+    if (isValidSize(dest, 500 * 1024)) {
+      log("better-sqlite3 already exists, skipping");
+      return true;
+    }
+    log("better-sqlite3 exists but seems corrupted (too small), re-downloading...");
+  }
+
+  const version = "12.8.0";
+  const url = `${CDN}/better-sqlite3/v${version}/better-sqlite3-v${version}-node-v${NODE_ABI}-${PLATFORM}-${ARCH}.tar.gz`;
+  log("Downloading better-sqlite3...");
+  const buf = await download(url);
+  const require = createRequire(import.meta.url);
+  const tar = require("tar");
+  const tmpFile = join(tmpdir(), `better-sqlite3-${Date.now()}.tar.gz`);
+  writeFileSync(tmpFile, buf);
+  mkdirSync(dirname(dest), { recursive: true });
+  await tar.extract({ cwd: pkgDir, file: tmpFile });
+  if (existsSync(dest)) {
+    log(`better-sqlite3 OK (${((await statSync(dest)).size / 1024).toFixed(0)} KB)`);
+    return true;
+  }
+  log("better-sqlite3 extracted but .node file not found at expected path");
+  return false;
+}
+
+try {
+  const results = await Promise.all([downloadFfmpeg(), downloadOpus(), downloadBetterSqlite3()]);
+  if (results.some(Boolean)) {
+    console.log("  [binary] All downloads complete");
+  }
+} catch (e) {
+  console.error(`  [binary] ERROR: ${e.message}`);
+  process.exit(1);
+}
+

scripts/setup.bat

@@ -4,14 +4,13 @@ chcp 65001 >nul
 title TSMusicBot Setup
 
 :: ============================================================
-::  TSMusicBot Setup Script (Robust Edition)
+::  TSMusicBot Setup Script (Windows)
 ::  - Auto-detect China network, switch to npmmirror
-::  - Strict error checking at every step
+::  - Download native binaries from CDN (避开 GitHub)
-::  - Detailed logging to setup.log
+::  - 自动修复 PowerShell 环境变量
-::  - Skip already-completed steps on re-run
 :: ============================================================
 
-set "SCRIPT_VERSION=2.0"
+set "SCRIPT_VERSION=2.1"
 set "MIN_NODE_MAJOR=20"
 set "LOG_FILE=%~dp0..\setup.log"
 set "FAILED=0"
@@ -44,42 +43,29 @@ echo.
 :: ============================================================
 :: Step 1: Check Node.js
 :: ============================================================
-call :step "1/6" "Checking Node.js"
+call :step "1/7" "Checking Node.js"
 
 where node >nul 2>&1
-if errorlevel 1 (
+if not errorlevel 1 goto :check_node_version
+
 call :error "Node.js not found in PATH."
 echo.
-    echo Please install Node.js %MIN_NODE_MAJOR% LTS or newer from one of:
+echo Please install Node.js %MIN_NODE_MAJOR% LTS or newer from:
-    echo   - https://nodejs.org/        ^(official^)
+echo   https://nodejs.org/  (official)
-    echo   - https://nodejs.cn/         ^(China mirror, recommended for CN users^)
+echo   https://nodejs.cn/   (China mirror, recommended)
-    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
-)
 
-:: Check Node version >= 20
+:check_node_version
-for /f "tokens=1 delims=v." %%a in ('node --version 2^>nul') do set "NODE_RAW=%%a"
-for /f "tokens=1 delims=v." %%a in ('node --version 2^>nul') do (
-    for /f "tokens=1 delims=." %%b in ("%%a") do set "NODE_MAJOR=%%b"
-)
-
-:: 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=v." %%a in ("%NODE_VER%") do set "NODE_MAJOR=%%a"
-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
 )
@@ -88,12 +74,11 @@ echo.
 :: ============================================================
 :: Step 2: Check npm
 :: ============================================================
-call :step "2/6" "Checking npm"
+call :step "2/7" "Checking npm"
 
 where npm >nul 2>&1
 if errorlevel 1 (
-    call :error "npm not found. This is unusual since Node.js is installed."
+    call :error "npm not found."
-    echo Please reinstall Node.js to fix this.
     pause
     exit /b 1
 )
@@ -106,117 +91,91 @@ echo.
 :: ============================================================
 :: Step 3: Detect network and configure mirror
 :: ============================================================
-call :step "3/6" "Checking network"
+call :step "3/7" "Checking network"
 
 set "USE_MIRROR=0"
+set "MIRROR_REGISTRY=https://registry.npmjs.org"
 
-:: Try reaching npm registry with a short timeout
+echo Testing connection to npm registry...
-echo Testing connection to registry.npmjs.org...
 call :log "Testing npm registry connectivity..."
 
-:: Use curl if available (more reliable than ping for HTTPS)
+ping -n 1 -w 4000 registry.npmjs.org >nul 2>&1
-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 [WARN] npm registry slow or unreachable ^(code: !HTTP_CODE!^).
-        call :log "npm registry returned: !HTTP_CODE!"
-        set "USE_MIRROR=1"
-    )
-) else (
-    :: Fallback to ping
-    ping -n 1 -w 3000 registry.npmjs.org >nul 2>&1
 if errorlevel 1 (
-        echo [WARN] Cannot reach npm registry quickly.
+    echo [WARN] Cannot reach npm registry quickly, using China mirror.
+    call :log "npm registry unreachable via ping"
     set "USE_MIRROR=1"
 ) else (
     echo [OK] npm registry reachable.
-    )
+    call :log "npm registry reachable"
 )
 
 if "%USE_MIRROR%"=="1" (
     echo.
-    echo Slow connection detected. Switching to China mirror ^(npmmirror.com^)...
+    echo [INFO] Using China mirror (npmmirror.com)
     call :log "Switching to npmmirror.com"
-    call npm config set registry https://registry.npmmirror.com >>"%LOG_FILE%" 2>&1
+    set "MIRROR_REGISTRY=https://registry.npmmirror.com"
-    call npm config set disturl https://registry.npmmirror.com/-/binary/node >>"%LOG_FILE%" 2>&1
+    set "CDN_MIRROR=https://cdn.npmmirror.com/binaries"
-    call npm config set electron_mirror https://registry.npmmirror.com/-/binary/electron/ >>"%LOG_FILE%" 2>&1
+) else (
-    call npm config set sqlite3_binary_host_mirror https://registry.npmmirror.com/-/binary/better-sqlite3 >>"%LOG_FILE%" 2>&1
+    set "CDN_MIRROR="
-    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 4: Install backend dependencies
+:: Step 4: Install backend dependencies (跳过二进制)
 :: ============================================================
-call :step "4/6" "Installing backend dependencies"
+call :step "4/7" "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 Running: npm install --ignore-scripts (跳过 GitHub 二进制下载)
-echo Press Ctrl+C to abort.
 echo.
 
-call npm install >>"%LOG_FILE%" 2>&1
+call npm install --registry=%MIRROR_REGISTRY% --ignore-scripts >>"%LOG_FILE%" 2>&1
 if errorlevel 1 (
     call :error "Backend npm install failed."
-    echo.
+    echo Check the log: %LOG_FILE%
-    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.
     pause
     exit /b 1
 )
 echo [OK] Backend dependencies installed.
 echo.
 
+:: ============================================================
+:: Step 4b: Download native binaries from CDN
+:: ============================================================
+call :step "4b/7" "Downloading native binaries"
+
+node scripts/download-binaries.mjs %CDN_MIRROR% >>"%LOG_FILE%" 2>&1
+if errorlevel 1 (
+    echo [WARN] Binary download had issues. Check %LOG_FILE% for details.
+) else (
+    echo [OK] Native binaries installed.
+)
+echo.
+
 :: ============================================================
 :: Step 5: Install frontend dependencies
 :: ============================================================
-call :step "5/6" "Installing frontend dependencies"
+call :step "5/7" "Installing frontend dependencies"
 
 if not exist "web\package.json" (
-    call :error "web\package.json not found. Repository may be incomplete."
+    call :error "web\package.json not found."
-    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 Running: npm install (in web/)
 echo.
 
 pushd web >nul
-call npm install >>"%LOG_FILE%" 2>&1
+call npm install --registry=%MIRROR_REGISTRY% >>"%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!^)."
+    call :error "Frontend npm install failed."
-    echo.
-    echo Try manually:
-    echo   cd /d "%PROJECT_ROOT%\web"
-    echo   npm install --verbose
-    echo.
     pause
     exit /b 1
 )
@@ -224,29 +183,48 @@ echo [OK] Frontend dependencies installed.
 echo.
 
 :: ============================================================
-:: Step 6: Build project (backend + frontend)
+:: Step 6: Build project
 :: ============================================================
-call :step "6/6" "Building project"
+call :step "6/7" "Building project"
 
 echo Running: npm run build
 echo.
 
 call npm run build >>"%LOG_FILE%" 2>&1
 if errorlevel 1 (
-    call :error "Build failed."
+    call :error "Build failed. Check: %LOG_FILE%"
-    echo.
-    echo Check the log file for details: %LOG_FILE%
-    echo.
-    echo Try manually:
-    echo   cd /d "%PROJECT_ROOT%"
-    echo   npm run build
-    echo.
     pause
     exit /b 1
 )
 echo [OK] Build succeeded.
 echo.
 
+:: ============================================================
+:: Step 7: Ensure PowerShell in PATH (修复 jdymusic CDN 播放)
+:: ============================================================
+call :step "7/7" "Checking PowerShell PATH"
+
+where powershell >nul 2>&1
+if errorlevel 1 (
+    echo [WARN] PowerShell not found in PATH.
+    echo Attempting to fix...
+    set "POWERSHELL_PATH=C:\Windows\System32\WindowsPowerShell\v1.0"
+    if exist "!POWERSHELL_PATH!\powershell.exe" (
+        :: 为用户添加永久 PATH 环境变量
+        echo [INFO] Adding PowerShell to user PATH...
+        call setx PATH "!POWERSHELL_PATH!;%PATH%" >nul 2>&1
+        echo [OK] PowerShell added to PATH. Please restart your terminal.
+    ) else (
+        echo [WARN] Could not find powershell.exe on this system.
+        echo        If you encounter playback issues with some NetEase songs,
+        echo        run: set PATH=%%PATH%%;C:\Windows\System32\WindowsPowerShell\v1.0\
+        echo        before running scripts\start.bat
+    )
+) else (
+    echo [OK] PowerShell found in PATH.
+)
+echo.
+
 :: ============================================================
 :: Verify build outputs
 :: ============================================================
@@ -263,18 +241,13 @@ if not exist "web\dist" (
 )
 
 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 [INFO] config.json will be auto-generated on first launch.
 ) else (
@@ -294,9 +267,8 @@ echo.
 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 Setup log: %LOG_FILE%
 echo.
 pause
 exit /b 0
@@ -319,3 +291,4 @@ goto :eof
 :log
 echo [%time%] %~1 >> "%LOG_FILE%"
 goto :eof
+

scripts/setup.sh

@@ -0,0 +1,145 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+#
+# TSMusicBot Setup Script (Linux/macOS)
+# - Auto-detect China network, switch to npmmirror
+# - Download native binaries from CDN (避开 GitHub)
+# - One-click setup, same as setup.bat for Windows
+#
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_DIR="$(cd "$SCRIPT_DIR/.." && pwd)"
+LOG_FILE="$PROJECT_DIR/setup.log"
+
+echo "============================================"
+echo "  TSMusicBot - First-Time Setup (Linux)"
+echo "============================================"
+echo ""
+echo "Log file: $LOG_FILE"
+echo ""
+
+# ---- Check Node.js ----
+if ! command -v node &>/dev/null; then
+    echo "[ERROR] Node.js not found. Please install Node.js 20+ from https://nodejs.org"
+    echo "        or https://nodejs.cn/ (China mirror)."
+    exit 1
+fi
+echo "[OK] Node.js $(node -v)"
+
+if ! command -v npm &>/dev/null; then
+    echo "[ERROR] npm not found."
+    exit 1
+fi
+echo "[OK] npm v$(npm -v)"
+echo ""
+
+# ---- Detect China network ----
+USE_MIRROR=0
+MIRROR_REGISTRY="https://registry.npmjs.org"
+CDN_MIRROR=""
+
+echo "Testing connection to npm registry..."
+if ping -c 1 -W 4 registry.npmjs.org &>/dev/null; then
+    echo "[OK] npm registry reachable."
+else
+    echo "[WARN] Cannot reach npm registry, using China mirror."
+    USE_MIRROR=1
+fi
+
+if [ "$USE_MIRROR" = "1" ]; then
+    echo "[INFO] Using China mirror (npmmirror.com)"
+    MIRROR_REGISTRY="https://registry.npmmirror.com"
+    CDN_MIRROR="https://cdn.npmmirror.com/binaries"
+    export npm_config_registry="$MIRROR_REGISTRY"
+fi
+echo ""
+
+# ---- Check build tools (needed for native module fallback) ----
+if ! command -v gcc &>/dev/null && ! command -v clang &>/dev/null; then
+    echo "[INFO] No C compiler found. If CDN binaries are unavailable,"
+    echo "       native modules may fail. Install build tools:"
+    echo "       sudo apt install build-essential  (Ubuntu/Debian)"
+    echo "       sudo yum groupinstall 'Development Tools'  (CentOS/RHEL)"
+    echo ""
+fi
+
+# ---- Step 1: Install dependencies (skip GitHub binaries) ----
+echo "---- 1/5: Installing Node.js dependencies ----"
+echo ""
+
+cd "$PROJECT_DIR"
+npm install --registry="$MIRROR_REGISTRY" --ignore-scripts 2>&1 | tee -a "$LOG_FILE"
+echo "[OK] Dependencies installed."
+echo ""
+
+# ---- Step 2: Download native binaries from CDN ----
+echo "---- 2/5: Downloading native binaries ----"
+echo ""
+
+if node scripts/download-binaries.mjs $CDN_MIRROR 2>&1 | tee -a "$LOG_FILE"; then
+    echo "[OK] Native binaries installed."
+else
+    echo "[WARN] Some native binaries had issues (will try source build as fallback)."
+fi
+echo ""
+
+# ---- Step 3: Install web panel dependencies ----
+echo "---- 3/5: Installing web panel dependencies ----"
+echo ""
+
+if [ -f "web/package.json" ]; then
+    cd "$PROJECT_DIR/web"
+    npm install --registry="$MIRROR_REGISTRY" 2>&1 | tee -a "$LOG_FILE"
+    cd "$PROJECT_DIR"
+    echo "[OK] Web panel dependencies installed."
+else
+    echo "[SKIP] web/package.json not found."
+fi
+echo ""
+
+# ---- Step 4: Build project ----
+echo "---- 4/5: Building project ----"
+echo ""
+
+npm run build 2>&1 | tee -a "$LOG_FILE"
+echo "[OK] Build succeeded."
+echo ""
+
+# ---- Step 5: Verify ----
+echo "---- 5/5: Verifying build ----"
+echo ""
+
+BUILD_OK=1
+if [ ! -d "dist" ]; then
+    echo "[ERROR] dist/ directory missing."
+    BUILD_OK=0
+fi
+if [ -d "web" ] && [ ! -d "web/dist" ]; then
+    echo "[ERROR] web/dist/ directory missing."
+    BUILD_OK=0
+fi
+
+if [ "$BUILD_OK" = "0" ]; then
+    echo "Build completed but expected output is missing."
+    exit 1
+fi
+echo "[OK] Build outputs verified."
+echo ""
+
+if [ ! -f "config.json" ]; then
+    echo "[INFO] config.json will be auto-generated on first launch."
+fi
+echo ""
+
+echo "============================================"
+echo "  Setup Complete!"
+echo "============================================"
+echo ""
+echo "Next steps:"
+echo "  1. Run:  npm start"
+echo "  2. Open: http://localhost:3000"
+echo ""
+echo "Setup log: $LOG_FILE"
+echo ""
+

scripts/start.bat

@@ -7,7 +7,7 @@ echo.
 where node >nul 2>&1
 if %errorlevel% neq 0 (
     echo Node.js is not installed.
-    echo Run scripts\setup.bat for automatic installation, or install Node.js 20+ from https://nodejs.org
+    echo Run scripts\setup.bat first.
     pause
     exit /b 1
 )
@@ -15,33 +15,30 @@ if %errorlevel% neq 0 (
 :: Resolve project root (one level up from scripts/)
 cd /d "%~dp0.."
 
-:: Install dependencies if needed
+:: Check if dependencies are installed
 if not exist "node_modules" (
-    echo Installing dependencies...
+    echo Dependencies not found. Please run scripts\setup.bat first.
-    call npm install --production
-    if %errorlevel% neq 0 (
-        echo Failed to install dependencies.
     pause
     exit /b 1
 )
-)
 
-:: Build if dist/ doesn't exist
+:: Check if build output exists
 if not exist "dist" (
-    echo Building project...
+    echo Build not found. Please run scripts\setup.bat first.
-    call npx tsc
-    if %errorlevel% neq 0 (
-        echo Build failed.
     pause
     exit /b 1
 )
-)
 
-:: FFmpeg is bundled via ffmpeg-static — no PATH check needed.
+:: Ensure PowerShell is in PATH (fix for jdymusic CDN playback on some systems)
-echo FFmpeg is bundled via node_modules (ffmpeg-static).
+where powershell >nul 2>&1
-echo.
+if errorlevel 1 (
+    if exist "C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe" (
+        set "PATH=%PATH%;C:\Windows\System32\WindowsPowerShell\v1.0\"
+    )
+)
 
 :: Start the application
 node dist/index.js
 
 pause
+

src/audio/player.ts

@@ -279,8 +279,12 @@ export class AudioPlayer extends EventEmitter {
       this.emit("error", err);
     });
 
+    // Mark playing but DO NOT start the frame loop here — the loop's
+    // "no ffmpeg + empty buffer → trackEnd" branch would fire on the very
+    // first tick, before the PowerShell download even completes. The
+    // frame loop is started inside spawnFfmpegFromFile() once ffmpeg is
+    // alive and producing PCM.
     this.state = "playing";
-    this.startFrameLoop();
   }
 
   private spawnFfmpegFromFile(tempFile: string, seekSeconds: number, sessionId: number): void {
@@ -329,6 +333,9 @@ export class AudioPlayer extends EventEmitter {
         this.emit("error", err);
       }
     });
+
+    // Now that ffmpeg is producing PCM, run the frame loop.
+    this.startFrameLoop();
   }
 
   stop(): void {

src/audio/queue.ts

@@ -22,6 +22,7 @@ export class PlayQueue {
   private mode: PlayMode = PlayMode.Sequential;
   private playedIndices = new Set<number>();
   private history: number[] = [];
+  private forwardStack: number[] = [];
   private static readonly HISTORY_LIMIT = 50;
 
   private pushHistory(idx: number): void {
@@ -100,12 +101,14 @@ export class PlayQueue {
     this.currentIndex = -1;
     this.playedIndices.clear();
     this.history = [];
+    this.forwardStack = [];
   }
 
   play(): QueuedSong | null {
     if (this.songs.length === 0) return null;
     this.playedIndices.clear();
     this.history = [];
+    this.forwardStack = [];
     this.currentIndex = 0;
     this.playedIndices.add(0);
     return this.songs[0];
@@ -118,6 +121,7 @@ export class PlayQueue {
     // shuffle from this point. History tracking is independent and
     // unaffected by this clear.
     this.playedIndices.clear();
+    this.forwardStack = [];
     this.currentIndex = index;
     this.playedIndices.add(index);
     return this.songs[index];
@@ -139,7 +143,20 @@ export class PlayQueue {
         this.currentIndex = (this.currentIndex + 1) % this.songs.length;
         return this.songs[this.currentIndex];
       }
-      case PlayMode.Random: {
+      case PlayMode.Random:
+      case PlayMode.RandomLoop: {
+        // 优先回到前进栈记录的位置（prev 退回的歌）
+        if (this.forwardStack.length > 0) {
+          const target = this.forwardStack.pop()!;
+          if (target !== this.currentIndex) {
+            this.pushHistory(this.currentIndex);
+            this.currentIndex = target;
+            this.playedIndices.add(target);
+            return this.songs[target];
+          }
+        }
+        // 前进栈为空，走纯随机逻辑
+        if (this.mode === PlayMode.Random) {
           const unplayed: number[] = [];
           for (let i = 0; i < this.songs.length; i++) {
             if (!this.playedIndices.has(i)) unplayed.push(i);
@@ -151,8 +168,7 @@ export class PlayQueue {
           this.currentIndex = nextIndex;
           this.playedIndices.add(nextIndex);
           return this.songs[nextIndex];
-      }
+        } else {
-      case PlayMode.RandomLoop: {
           if (this.songs.length === 1) {
             this.pushHistory(this.currentIndex);
             this.currentIndex = 0;
@@ -168,17 +184,23 @@ export class PlayQueue {
         }
       }
     }
+  }
 
   prev(): QueuedSong | null {
     if (this.songs.length === 0) return null;
 
+    // 记录当前位置到前进栈，供 next 优先返回
+    if (this.currentIndex >= 0 && this.forwardStack.length < PlayQueue.HISTORY_LIMIT) {
+      this.forwardStack.push(this.currentIndex);
+    }
+
     // 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);
+        this.playedIndices = new Set([...this.history, this.currentIndex]);
         return this.songs[idx];
       }
       // Stale entry (song removed) — keep popping.
@@ -227,6 +249,7 @@ export class PlayQueue {
     this.mode = mode;
     this.playedIndices.clear();
     this.history = [];
+    this.forwardStack = [];
     if (this.currentIndex >= 0) {
       this.playedIndices.add(this.currentIndex);
     }

src/bot/instance.ts

@@ -638,9 +638,27 @@ export class BotInstance extends EventEmitter {
   }
 
   private async cmdAlbum(cmd: ParsedCommand): Promise<string> {
-    if (!cmd.args) return "Usage: !album <album ID>";
+    if (!cmd.args) return "Usage: !album <album name or ID>";
     const provider = this.getProvider(cmd.flags);
-    const songs = await provider.getAlbumSongs(cmd.args);
+
+    const id = this.extractId(cmd.args);
+    const isNumericId = /^\d+$/.test(cmd.args.trim());
+
+    let albumId: string;
+
+    if (isNumericId || id !== cmd.args) {
+      // Input is a numeric ID or URL containing an ID — use directly
+      albumId = id;
+    } else {
+      // Name-based search
+      const result = await provider.search(cmd.args);
+      const albums = result.albums ?? [];
+      if (albums.length === 0)
+        return `No albums found for: ${cmd.args}`;
+      albumId = albums[0].id;
+    }
+
+    const songs = await provider.getAlbumSongs(albumId);
     if (songs.length === 0) return "Album is empty or not found";
 
     this.queue.clear();
@@ -778,6 +796,7 @@ export class BotInstance extends EventEmitter {
       `${p}stop         — Stop and clear queue`,
       `${p}vol <0-100>  — Set volume`,
       `${p}queue        — Show queue`,
+      `${p}remove <pos> — Remove song at position (see ${p}queue)`,
       `${p}mode <seq|loop|random|rloop> — Play mode`,
       `${p}playlist <name or id> — Load playlist by name or ID`,
       `${p}playlist -q <name or id> — Load playlist from QQ Music`,

src/music/bilibili.ts

@@ -1,3 +1,4 @@
+import { createHash } from "node:crypto";
 import axios, { type AxiosInstance } from "axios";
 import type {
   MusicProvider,
@@ -15,6 +16,16 @@ const BILIBILI_HEADERS = {
     "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36",
 };
 
+// Permutation used by B站 to derive the wbi mixin key from img_key+sub_key.
+const WBI_MIXIN_KEY_ENC_TAB = [
+  46, 47, 18, 2, 53, 8, 23, 32, 15, 50, 10, 31, 58, 3, 45, 35, 27, 43, 5, 49,
+  33, 9, 42, 19, 29, 28, 14, 39, 12, 38, 41, 13, 37, 48, 7, 16, 24, 55, 40, 61,
+  26, 17, 0, 1, 60, 51, 30, 4, 22, 25, 54, 21, 56, 59, 6, 63, 57, 62, 11, 36,
+  20, 34, 44, 52,
+];
+
+const WBI_KEY_TTL_MS = 6 * 60 * 60 * 1000; // wbi keys rotate ~daily; refresh every 6h
+
 export class BiliBiliProvider implements MusicProvider {
   readonly platform = "bilibili" as const;
   private api: AxiosInstance;
@@ -24,6 +35,8 @@ export class BiliBiliProvider implements MusicProvider {
   private cidCache = new Map<string, number>();
   private buvidCookie = ""; // anonymous session cookie (buvid3) for anti-412
   private buvidInitialized = false;
+  private wbiMixinKey = "";
+  private wbiKeyFetchedAt = 0;
 
   constructor() {
     this.api = axios.create({
@@ -62,6 +75,50 @@ export class BiliBiliProvider implements MusicProvider {
     return combined ? { Cookie: combined } : {};
   }
 
+  /**
+   * Fetch wbi img_key/sub_key from /x/web-interface/nav and derive the
+   * mixin key used to sign search params. Required since B站 moved the
+   * search endpoint behind wbi signing — unsigned /search/type now
+   * returns an anti-bot HTML page.
+   */
+  private async ensureWbiKeys(): Promise<void> {
+    if (this.wbiMixinKey && Date.now() - this.wbiKeyFetchedAt < WBI_KEY_TTL_MS) {
+      return;
+    }
+    const res = await this.api.get("/x/web-interface/nav", {
+      headers: this.cookieHeaders,
+      validateStatus: () => true, // nav returns -101 when not logged in but still includes wbi_img
+    });
+    const wbi = res.data?.data?.wbi_img;
+    const imgUrl: string = wbi?.img_url ?? "";
+    const subUrl: string = wbi?.sub_url ?? "";
+    const imgKey = imgUrl.split("/").pop()?.split(".")[0] ?? "";
+    const subKey = subUrl.split("/").pop()?.split(".")[0] ?? "";
+    if (!imgKey || !subKey) {
+      throw new Error("Bilibili wbi keys unavailable");
+    }
+    const raw = imgKey + subKey;
+    this.wbiMixinKey = WBI_MIXIN_KEY_ENC_TAB.map((i) => raw[i] ?? "")
+      .join("")
+      .slice(0, 32);
+    this.wbiKeyFetchedAt = Date.now();
+  }
+
+  /** Sign params for wbi-protected endpoints. Returns a new params object including wts and w_rid. */
+  private signWbi(params: Record<string, string | number>): Record<string, string> {
+    const withTs: Record<string, string> = {};
+    for (const [k, v] of Object.entries(params)) withTs[k] = String(v);
+    withTs.wts = String(Math.floor(Date.now() / 1000));
+    const sorted = Object.keys(withTs)
+      .sort()
+      .map((k) => `${encodeURIComponent(k)}=${encodeURIComponent(withTs[k])}`)
+      .join("&");
+    withTs.w_rid = createHash("md5")
+      .update(sorted + this.wbiMixinKey)
+      .digest("hex");
+    return withTs;
+  }
+
   setQuality(quality: string): void {
     this.quality = quality;
   }
@@ -91,12 +148,14 @@ export class BiliBiliProvider implements MusicProvider {
 
   async search(query: string, limit = 20): Promise<SearchResult> {
     await this.ensureBuvidCookie();
-    const res = await this.api.get("/x/web-interface/search/type", {
+    await this.ensureWbiKeys();
-      params: {
+    const signed = this.signWbi({
       search_type: "video",
       keyword: query,
       page_size: limit,
-      },
+    });
+    const res = await this.api.get("/x/web-interface/wbi/search/type", {
+      params: signed,
       headers: this.cookieHeaders,
     });
 

src/music/netease.test.ts

@@ -1,5 +1,5 @@
 import { describe, it, expect } from "vitest";
-import { parseLyrics } from "./netease.js";
+import { parseLyrics, mapNeteaseAlbums } from "./netease.js";
 
 describe("NetEase adapter", () => {
   it("parses LRC format lyrics", () => {
@@ -28,4 +28,32 @@ describe("NetEase adapter", () => {
     expect(lines[0].text).toBe("Hello world");
     expect(lines[0].translation).toBe("你好世界");
   });
+
+  it("mapNeteaseAlbums maps raw cloudsearch albums to Album shape", () => {
+    const raw = [
+      {
+        id: 42,
+        name: "Album A",
+        picUrl: "https://x/p.jpg",
+        artists: [{ name: "Artist X" }, { name: "Featured Y" }],
+        size: 12,
+      },
+      {
+        id: 99,
+        name: "Album B",
+        picUrl: "",
+        artists: [],
+      },
+    ];
+    expect(mapNeteaseAlbums(raw)).toEqual([
+      { id: "42", name: "Album A", artist: "Artist X / Featured Y", coverUrl: "https://x/p.jpg", songCount: 12, platform: "netease" },
+      { id: "99", name: "Album B", artist: "", coverUrl: "", songCount: 0, platform: "netease" },
+    ]);
+  });
+
+  it("mapNeteaseAlbums returns [] for empty/null input", () => {
+    expect(mapNeteaseAlbums([])).toEqual([]);
+    expect(mapNeteaseAlbums(null as any)).toEqual([]);
+    expect(mapNeteaseAlbums(undefined as any)).toEqual([]);
+  });
 });

src/music/netease.ts

@@ -8,6 +8,7 @@ import type {
   SearchResult,
   QrCodeResult,
   AuthStatus,
+  Album,
 } from "./provider.js";
 
 export function parseLyrics(lrc: string, tlyric?: string): LyricLine[] {
@@ -55,6 +56,18 @@ export function parseLyrics(lrc: string, tlyric?: string): LyricLine[] {
   return lines.sort((a, b) => a.time - b.time);
 }
 
+export function mapNeteaseAlbums(raw: any[] | null | undefined): Album[] {
+  if (!Array.isArray(raw)) return [];
+  return raw.map((a) => ({
+    id: String(a.id),
+    name: a.name ?? "",
+    artist: (a.artists ?? []).map((x: any) => x.name).join(" / "),
+    coverUrl: a.picUrl ?? "",
+    songCount: a.size ?? 0,
+    platform: "netease",
+  }));
+}
+
 // NetEase quality levels: standard(128k) higher(192k) exhigh(320k) lossless(flac) hires(hi-res) jyeffect jymaster
 export const NETEASE_QUALITY_LEVELS = [
   { value: "standard", label: "标准 (128kbps)", bitrate: 128 },
@@ -91,7 +104,7 @@ export class NeteaseProvider implements MusicProvider {
   }
 
   async search(query: string, limit = 20): Promise<SearchResult> {
-    const [songRes, playlistRes] = await Promise.all([
+    const [songRes, playlistRes, albumRes] = await Promise.all([
       this.api.get("/cloudsearch", {
         params: { keywords: query, type: 1, limit, ...this.cookieParams },
       }),
@@ -99,10 +112,13 @@ export class NeteaseProvider implements MusicProvider {
         params: {
           keywords: query,
           type: 1000,
-          limit: 5,
+          limit: 10,
           ...this.cookieParams,
         },
       }),
+      this.api.get("/cloudsearch", {
+        params: { keywords: query, type: 10, limit: 10, ...this.cookieParams },
+      }),
     ]);
 
     const songs: Song[] = (songRes.data?.result?.songs ?? []).map(
@@ -127,7 +143,9 @@ export class NeteaseProvider implements MusicProvider {
       platform: "netease",
     }));
 
-    return { songs, playlists, albums: [] };
+    const albums = mapNeteaseAlbums(albumRes.data?.result?.albums);
+
+    return { songs, playlists, albums };
   }
 
   async getSongUrl(songId: string, quality?: string): Promise<string | null> {

src/music/qq.test.ts

@@ -0,0 +1,43 @@
+import { describe, it, expect } from "vitest";
+import { mapQqAlbums } from "./qq.js";
+
+describe("QQ adapter", () => {
+  it("mapQqAlbums maps albumMID-style raw entries", () => {
+    const raw = [
+      {
+        albumMID: "abc",
+        albumName: "Aero",
+        singerName: "Singer A",
+      },
+      {
+        albumMID: "xyz",
+        albumName: "Beta",
+        singer: [{ name: "Singer B" }, { name: "Singer C" }],
+      },
+    ];
+    const out = mapQqAlbums(raw);
+    expect(out).toHaveLength(2);
+    expect(out[0]).toMatchObject({
+      id: "abc",
+      name: "Aero",
+      artist: "Singer A",
+      platform: "qq",
+    });
+    expect(out[0].coverUrl).toContain("T002R300x300M000abc.jpg");
+    expect(out[1].artist).toBe("Singer B / Singer C");
+    expect(out[1].coverUrl).toContain("xyz");
+  });
+
+  it("mapQqAlbums returns [] for empty/null input", () => {
+    expect(mapQqAlbums([])).toEqual([]);
+    expect(mapQqAlbums(null as any)).toEqual([]);
+    expect(mapQqAlbums(undefined as any)).toEqual([]);
+  });
+
+  it("mapQqAlbums falls back to albumPic when no albumMID", () => {
+    const raw = [{ albumName: "C", albumPic: "https://x/p.jpg", singerName: "S" }];
+    const out = mapQqAlbums(raw);
+    expect(out[0].coverUrl).toBe("https://x/p.jpg");
+    expect(out[0].id).toBe("");
+  });
+});

src/music/qq.ts

@@ -8,17 +8,29 @@ import type {
   SearchResult,
   QrCodeResult,
   AuthStatus,
+  Album,
 } from "./provider.js";
 import { parseLyrics } from "./netease.js";
 
-// Direct QQ Music API client — bypasses the local API server for search
+// Primary search client: u.y.qq.com/cgi-bin/musicu.fcg (JSON sub-request
-// because @sansenjian/qq-music-api still uses the broken c.y.qq.com endpoint.
+// batch). Was broken ca. 2026-05 due to two upstream API changes:
-const qqDirectApi = axios.create({
+//   1. searchid param must NOT be present (causes all lists to be empty)
+//   2. num_per_page must be >= 10 (lower values return empty)
+// Both fixes applied per https://github.com/ZHANGTIANYAO1/teamspeak-music-bot/issues/61
+const qqMusicuApi = axios.create({
   baseURL: "https://u.y.qq.com",
   timeout: 10000,
   headers: { referer: "https://y.qq.com" },
 });
 
+// Fallback search client: c.y.qq.com/soso/fcgi-bin/client_search_cp (classic
+// endpoint, song + album only, no playlist support).
+const qqSearchApi = axios.create({
+  baseURL: "https://c.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({
@@ -27,6 +39,26 @@ const qqFavApi = axios.create({
   headers: { referer: "https://y.qq.com/" },
 });
 
+export function mapQqAlbums(raw: any[] | null | undefined): Album[] {
+  if (!Array.isArray(raw)) return [];
+  return raw.map((a) => {
+    const id = String(a.albumMID ?? a.mid ?? a.albumID ?? "");
+    const artist = a.singerName
+      ?? (Array.isArray(a.singer) ? a.singer.map((s: any) => s.name).join(" / ") : "");
+    const coverUrl = id
+      ? `https://y.gtimg.cn/music/photo_new/T002R300x300M000${id}.jpg`
+      : (a.albumPic ?? "");
+    return {
+      id,
+      name: a.albumName ?? a.title ?? "",
+      artist,
+      coverUrl,
+      songCount: a.song_count ?? a.songCount ?? 0,
+      platform: "qq" as const,
+    };
+  });
+}
+
 function computeGtk(pSkey: string): number {
   let hash = 5381;
   for (let i = 0; i < pSkey.length; i++) {
@@ -61,24 +93,55 @@ export class QQMusicProvider implements MusicProvider {
   }
 
   async search(query: string, limit = 20): Promise<SearchResult> {
+    // Primary: u.y.qq.com/cgi-bin/musicu.fcg — supports songs + albums +
+    // playlists. Fixed per https://github.com/ZHANGTIANYAO1/teamspeak-music-bot/issues/61
+    // (removed searchid, num_per_page >= 10, corrected search_type values).
+    const primary = await this.searchViaMusicuFcg(query, limit);
+    if (primary) return primary;
+
+    // Fallback: c.y.qq.com/soso/fcgi-bin/client_search_cp (song + album,
+    // no playlist support). Kept as redundancy.
+    return this.searchViaClientSearchCp(query, limit);
+  }
+
+  /** Primary search via u.y.qq.com/cgi-bin/musicu.fcg.
+   *
+   * Two upstream API changes (2026-05) required fixes:
+   *   1. Omit `searchid` — its presence now causes all lists to be empty.
+   *   2. `num_per_page` >= 10 — lower values return empty.
+   *   3. `search_type: 2` for albums, `3` for playlists (8 was "user"). */
+  private async searchViaMusicuFcg(
+    query: string,
+    limit: number
+  ): Promise<SearchResult | null> {
+    try {
+      const numPerPage = Math.max(10, Math.min(limit, 50));
       const reqData = JSON.stringify({
         req_0: {
           module: "music.search.SearchCgiService",
           method: "DoSearchForQQMusicDesktop",
-        param: {
+          param: { query, num_per_page: numPerPage, search_type: 0 },
-          searchid: "1",
-          query,
-          num_per_page: Math.min(limit, 50),
         },
+        req_album: {
+          module: "music.search.SearchCgiService",
+          method: "DoSearchForQQMusicDesktop",
+          param: { query, num_per_page: 10, search_type: 2 },
+        },
+        req_playlist: {
+          module: "music.search.SearchCgiService",
+          method: "DoSearchForQQMusicDesktop",
+          param: { query, num_per_page: 10, search_type: 3 },
         },
       });
-    const res = await qqDirectApi.get("/cgi-bin/musicu.fcg", {
+      const res = await qqMusicuApi.get("/cgi-bin/musicu.fcg", {
         params: { format: "json", data: reqData },
       });
-    const list: any[] =
-      res.data?.req_0?.data?.body?.song?.list ?? [];
 
-    const songs: Song[] = list.map((s: any) => ({
+      const songList: any[] =
+        res.data?.req_0?.data?.body?.song?.list ?? [];
+      if (songList.length === 0) return null;
+
+      const songs: Song[] = songList.map((s: any) => ({
         id: String(s.mid ?? s.id),
         name: s.title ?? s.name ?? "",
         artist: (s.singer ?? []).map((a: any) => a.name).join(" / "),
@@ -90,7 +153,75 @@ export class QQMusicProvider implements MusicProvider {
         platform: "qq",
       }));
 
-    return { songs, playlists: [], albums: [] };
+      const albumList: any[] = res.data?.req_album?.data?.body?.album?.list ?? [];
+      const albums = mapQqAlbums(albumList);
+
+      const playlistList: any[] = res.data?.req_playlist?.data?.body?.songlist?.list ?? [];
+      const playlists: Playlist[] = playlistList.map((p: any) => ({
+        id: String(p.dissid ?? p.id ?? ""),
+        name: p.dissname ?? p.title ?? "",
+        coverUrl: p.imgurl ?? p.logo ?? "",
+        songCount: p.songnum ?? p.song_count ?? 0,
+        platform: "qq" as const,
+      }));
+
+      return { songs, playlists, albums };
+    } catch {
+      return null;
+    }
+  }
+
+  /** Fallback search via c.y.qq.com/soso/fcgi-bin/client_search_cp */
+  private async searchViaClientSearchCp(
+    query: string,
+    limit: number
+  ): Promise<SearchResult> {
+    const songParams = {
+      w: query,
+      format: "json",
+      p: 1,
+      n: Math.min(limit, 50),
+      type: 0,
+      cr: 1,
+    };
+    const albumParams = {
+      w: query,
+      format: "json",
+      p: 1,
+      n: 5,
+      t: 8,
+      cr: 1,
+    };
+
+    const [songRes, albumRes] = await Promise.allSettled([
+      qqSearchApi.get("/soso/fcgi-bin/client_search_cp", { params: songParams }),
+      qqSearchApi.get("/soso/fcgi-bin/client_search_cp", { params: albumParams }),
+    ]);
+
+    const songList: any[] =
+      songRes.status === "fulfilled"
+        ? (songRes.value.data?.data?.song?.list ?? [])
+        : [];
+
+    const songs: Song[] = songList.map((s: any) => ({
+      id: String(s.songmid ?? s.songid ?? ""),
+      name: s.songname ?? s.name ?? "",
+      artist: (s.singer ?? []).map((a: any) => a.name).join(" / "),
+      album: s.albumname ?? s.album?.name ?? "",
+      duration: s.interval ?? 0,
+      coverUrl: s.albummid
+        ? `https://y.gtimg.cn/music/photo_new/T002R300x300M000${s.albummid}.jpg`
+        : "",
+      platform: "qq",
+    }));
+
+    const albumList: any[] =
+      albumRes.status === "fulfilled"
+        ? (albumRes.value.data?.data?.album?.list ?? [])
+        : [];
+    const albums = mapQqAlbums(albumList);
+
+    return { songs, playlists: [], albums };
   }
 
   async getSongUrl(songId: string, quality?: string): Promise<string | null> {

src/web/api/music.ts

@@ -52,14 +52,20 @@ export function createMusicRouter(
       ]);
 
       const songs = [
-        ...(neteaseResult.status === "fulfilled"
+        ...(neteaseResult.status === "fulfilled" ? neteaseResult.value.songs : []),
-          ? 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 });
+      res.json({ songs, albums, playlists });
     } catch (err) {
       logger.error({ err }, "Unified search failed");
       res.status(500).json({ error: (err as Error).message });

src/web/api/player.ts

@@ -313,6 +313,78 @@ export function createPlayerRouter(
     }
   });
 
+  // Play an album by ID — mirrors play-playlist but calls getAlbumSongs
+  router.post("/:botId/play-album", async (req, res) => {
+    try {
+      const bot = (req as any).bot;
+      const { albumId, platform } = req.body;
+      const provider = bot.getProviderFor(
+        platform === "bilibili" || platform === "qq" || platform === "youtube"
+          ? platform
+          : "netease"
+      );
+
+      // Stop current playback
+      bot.getPlayer().stop();
+      bot.getPlayer().resetFailures();
+
+      const songs = await provider.getAlbumSongs(albumId);
+      if (songs.length === 0) {
+        res.json({ message: "Album is empty" });
+        return;
+      }
+
+      // QQ-specific optimization: batch-resolve playable IDs to avoid
+      // wasting retries on region/copyright-restricted tracks.
+      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) {
+          queueable = songs.filter((s: { id: string }) => playable.has(s.id));
+        }
+      }
+      if (queueable.length === 0) {
+        res.json({ ok: false, message: `专辑 ${totalCount} 首歌曲均无版权可播放（区域/版权限制）` });
+        return;
+      }
+
+      const queue = bot.getQueueManager();
+      queue.clear();
+      for (const song of queueable) {
+        queue.add({ ...song, platform: provider.platform });
+      }
+
+      const mode = queue.getMode();
+      let first;
+      if (mode === "random" || mode === "rloop") {
+        const idx = Math.floor(Math.random() * queue.size());
+        first = queue.playAt(idx);
+      } else {
+        first = queue.play();
+      }
+
+      let started = first ? await bot.resolveAndPlay(first) : false;
+      if (first && !started) {
+        started = await bot.playNext(20);
+      }
+
+      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-album failed");
+      res.status(500).json({ error: (err as Error).message });
+    }
+  });
+
   // Play a single song by ID — resolves URL on demand
   router.post("/:botId/play-song", async (req, res) => {
     try {

web/src/router/index.ts

@@ -22,6 +22,13 @@ const router = createRouter({
       path: '/playlist/:id',
       name: 'playlist',
       component: () => import('../views/Playlist.vue'),
+      meta: { kind: 'playlist' },
+    },
+    {
+      path: '/album/:id',
+      name: 'album',
+      component: () => import('../views/Playlist.vue'),
+      meta: { kind: 'album' },
     },
     {
       path: '/lyrics',

web/src/stores/player.ts

@@ -322,6 +322,16 @@ export const usePlayerStore = defineStore('player', {
       this._syncAfterAction();
     },
 
+    async playAlbum(albumId: string, platform = 'netease') {
+      if (!this.activeBotId) return;
+      const res = await axios.post(`/api/player/${this.activeBotId}/play-album`, { albumId, platform });
+      if (res.data?.message) {
+        this.notify(res.data.message, res.data.ok === false ? 'error' : 'info');
+      }
+      this._setTiming(this.activeBotId, { serverElapsed: 0 });
+      this._syncAfterAction();
+    },
+
     async pause() {
       if (!this.activeBotId) return;
       // Freeze elapsed at current interpolated value

web/src/views/Playlist.vue

@@ -38,7 +38,7 @@
       </div>
     </template>
 
-    <div v-else class="loading">歌单不存在或加载失败</div>
+    <div v-else class="loading">{{ kind === 'album' ? '专辑' : '歌单' }}不存在或加载失败</div>
   </div>
 </template>
 
@@ -64,6 +64,8 @@ interface PlaylistDetail {
   songCount: number;
 }
 
+const kind = (route.meta.kind as string) ?? 'playlist'; // 'playlist' | 'album'
+
 const playlist = ref<PlaylistDetail | null>(null);
 const songs = ref<Song[]>([]);
 const loading = ref(true);
@@ -71,20 +73,32 @@ const loading = ref(true);
 async function playAll() {
   const id = route.params.id as string;
   const platform = (route.query.platform as string) || 'netease';
+  if (kind === 'album') {
+    await store.playAlbum(id, platform);
+  } else {
     await store.playPlaylist(id, platform);
   }
+}
 
 onMounted(async () => {
   const id = route.params.id as string;
   const platform = (route.query.platform as string) || 'netease';
 
+  const detailUrl = kind === 'album'
+    ? `/api/music/album/${id}/detail`
+    : `/api/music/playlist/${id}/detail`;
+  const songsUrl = kind === 'album'
+    ? `/api/music/album/${id}`
+    : `/api/music/playlist/${id}`;
+
   // allSettled, not Promise.all — if detail 404s but songs is fine
   // (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.
+  // the "不存在" empty state. For albums, detail always 404s — that
+  // is intentional; the fallback stub below handles it.
   const [detailRes, songsRes] = await Promise.allSettled([
-    axios.get(`/api/music/playlist/${id}/detail`, { params: { platform } }),
+    axios.get(detailUrl, { params: { platform } }),
-    axios.get(`/api/music/playlist/${id}`, { params: { platform } }),
+    axios.get(songsUrl, { params: { platform } }),
   ]);
 
   const detail = detailRes.status === 'fulfilled' ? detailRes.value.data?.playlist : null;
@@ -93,10 +107,14 @@ onMounted(async () => {
   if (detail) {
     playlist.value = detail;
   } else if (songList.length > 0) {
-    // Fall back to a stub built from the route + first song's cover.
+    // Fall back to a stub built from the route + first song. For albums,
+    // every song's `album` field carries the real album name.
+    const fallbackName = kind === 'album'
+      ? (songList[0]?.album || '专辑')
+      : '歌单';
     playlist.value = {
       id,
-      name: '歌单',
+      name: fallbackName,
       description: '',
       coverUrl: songList[0]?.coverUrl ?? '',
       songCount: songList.length,
@@ -104,7 +122,7 @@ onMounted(async () => {
   } else {
     playlist.value = null;
     if (detailRes.status === 'rejected') {
-      console.error('Failed to load playlist detail:', (detailRes.reason as any)?.response?.status, (detailRes.reason as any)?.message);
+      console.error('Failed to load detail:', (detailRes.reason as any)?.response?.status, (detailRes.reason as any)?.message);
     }
   }
   songs.value = songList;

web/src/views/Search.vue

@@ -20,9 +20,89 @@
 
     <div v-if="loading" class="loading">搜索中...</div>
 
-    <div v-else-if="results.length > 0" class="results">
+    <template v-else-if="allSongs.length || allAlbums.length || allPlaylists.length">
+      <div class="source-bar">
+        <button
+          class="source-btn"
+          :class="{ active: selectedSource === 'netease' }"
+          @click="selectedSource = 'netease'"
+        >网易云</button>
+        <button
+          class="source-btn"
+          :class="{ active: selectedSource === 'qq' }"
+          @click="selectedSource = 'qq'"
+        >QQ</button>
+        <button
+          class="source-btn"
+          :class="{ active: selectedSource === 'bilibili' }"
+          @click="selectedSource = 'bilibili'"
+        >B站</button>
+      </div>
+
+      <div class="tab-bar">
+        <button
+          class="tab"
+          :class="{ active: activeTab === 'songs' }"
+          @click="activeTab = 'songs'"
+        >
+          单曲<span class="tab-count">{{ filteredSongs.length }}</span>
+        </button>
+        <button
+          v-if="selectedSource !== 'bilibili'"
+          class="tab"
+          :class="{ active: activeTab === 'albums' }"
+          @click="activeTab = 'albums'"
+        >
+          专辑<span class="tab-count">{{ filteredAlbums.length }}</span>
+        </button>
+        <button
+          v-if="selectedSource !== 'bilibili'"
+          class="tab"
+          :class="{ active: activeTab === 'playlists' }"
+          @click="activeTab = 'playlists'"
+        >
+          歌单<span class="tab-count">{{ filteredPlaylists.length }}</span>
+        </button>
+      </div>
+
+      <section v-if="activeTab === 'albums' && filteredAlbums.length" class="result-section">
+        <div class="card-grid">
+          <router-link
+            v-for="al in filteredAlbums"
+            :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 }}
+              <span class="platform-badge" :class="badgeClass(al.platform)">{{ badgeLabel(al.platform) }}</span>
+            </div>
+            <div class="card-sub">{{ al.artist }}</div>
+          </router-link>
+        </div>
+      </section>
+
+      <section v-if="activeTab === 'playlists' && filteredPlaylists.length" class="result-section">
+        <div class="card-grid">
+          <router-link
+            v-for="pl in filteredPlaylists"
+            :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 }}
+              <span class="platform-badge" :class="badgeClass(pl.platform)">{{ badgeLabel(pl.platform) }}</span>
+            </div>
+          </router-link>
+        </div>
+      </section>
+
+      <section v-if="activeTab === 'songs' && filteredSongs.length" class="result-section">
         <SongCard
-        v-for="(song, i) in results"
+          v-for="(song, i) in filteredSongs"
           :key="`${song.platform}-${song.id}`"
           :song="song"
           :index="i + 1"
@@ -31,48 +111,106 @@
           @playNext="store.playNextSong(song)"
           @add="store.addSong(song)"
         />
-    </div>
+      </section>
+    </template>
 
-    <div v-else-if="searched" class="empty">
+    <div v-else-if="searched" class="empty">未找到相关结果</div>
-      未找到相关结果
-    </div>
   </div>
 </template>
 
 <script setup lang="ts">
-import { ref, onMounted } from 'vue';
+import { ref, computed, watch, onMounted } from 'vue';
-import { useRoute } from 'vue-router';
+import { useRoute, useRouter } from 'vue-router';
 import { Icon } from '@iconify/vue';
 import axios from 'axios';
 import { usePlayerStore } from '../stores/player.js';
+import type { Song } from '../stores/player.js';
 import SongCard from '../components/SongCard.vue';
+import CoverArt from '../components/CoverArt.vue';
 
 const store = usePlayerStore();
 const route = useRoute();
+const router = useRouter();
+
+const SOURCE_STORAGE_KEY = 'search-source';
+
+function loadSource(): 'netease' | 'qq' | 'bilibili' {
+  try {
+    const stored = localStorage.getItem(SOURCE_STORAGE_KEY);
+    if (stored === 'netease' || stored === 'qq' || stored === 'bilibili') return stored;
+  } catch { /* localStorage blocked */ }
+  return 'netease';
+}
 
 const query = ref((route.query.q as string) || '');
-import { Song } from '../stores/player.js';
+const activeTab = ref<'songs' | 'albums' | 'playlists'>('songs');
+const selectedSource = ref<'netease' | 'qq' | 'bilibili'>(loadSource());
 
-const results = ref<Song[]>([]);
+interface Album { id: string; name: string; artist: string; coverUrl: string; songCount?: number; platform: string; }
+interface Playlist { id: string; name: string; coverUrl: string; songCount?: number; platform: string; }
+
+const allSongs = ref<Song[]>([]);
+const allAlbums = ref<Album[]>([]);
+const allPlaylists = ref<Playlist[]>([]);
 const loading = ref(false);
 const searched = ref(false);
 
+const filteredSongs = computed(() =>
+  allSongs.value.filter((s) => s.platform === selectedSource.value)
+);
+
+const filteredAlbums = computed(() =>
+  allAlbums.value.filter((a) => a.platform === selectedSource.value)
+);
+
+const filteredPlaylists = computed(() =>
+  allPlaylists.value.filter((p) => p.platform === selectedSource.value)
+);
+
+// Persist source preference
+watch(selectedSource, (src) => {
+  try { localStorage.setItem(SOURCE_STORAGE_KEY, src); } catch { /* ignore */ }
+});
+
+// B站 has no albums/playlists — force songs tab when switching to B站
+watch(selectedSource, (src) => {
+  if (src === 'bilibili' && activeTab.value !== 'songs') {
+    activeTab.value = 'songs';
+  }
+});
+
 async function doSearch() {
   if (!query.value.trim()) return;
   loading.value = true;
   searched.value = true;
+  activeTab.value = 'songs';
+  router.replace({ query: { q: query.value } });
   try {
-    const res = await axios.get('/api/music/search/all', {
+    const res = await axios.get('/api/music/search/all', { params: { q: query.value } });
-      params: { q: query.value },
+    allSongs.value = res.data.songs ?? [];
-    });
+    allAlbums.value = res.data.albums ?? [];
-    results.value = res.data.songs;
+    allPlaylists.value = res.data.playlists ?? [];
   } catch {
-    results.value = [];
+    allSongs.value = []; allAlbums.value = []; allPlaylists.value = [];
   } finally {
     loading.value = false;
   }
 }
 
+function badgeLabel(platform: string): string {
+  if (platform === 'qq') return 'QQ';
+  if (platform === 'bilibili') return 'B站';
+  if (platform === 'youtube') return 'YouTube';
+  return '网易云';
+}
+
+function badgeClass(platform: string): string {
+  if (platform === 'qq') return 'badge-qq';
+  if (platform === 'bilibili') return 'badge-bilibili';
+  if (platform === 'youtube') return 'badge-youtube';
+  return 'badge-netease';
+}
+
 onMounted(() => {
   if (query.value) doSearch();
 });
@@ -141,4 +279,119 @@ onMounted(() => {
   flex-direction: column;
   gap: 2px;
 }
+
+.source-bar {
+  display: flex;
+  gap: 8px;
+  margin-bottom: 12px;
+}
+
+.source-btn {
+  padding: 5px 16px;
+  border-radius: var(--radius-sm);
+  font-size: 13px;
+  font-family: inherit;
+  font-weight: var(--fw-semi);
+  color: var(--text-secondary);
+  background: var(--bg-card);
+  cursor: pointer;
+  transition: all var(--transition-fast);
+  white-space: nowrap;
+
+  &:hover { color: var(--text-primary); }
+
+  &.active {
+    color: var(--color-primary);
+    background: rgba(51, 94, 234, 0.12);
+  }
+}
+
+.tab-bar {
+  display: flex;
+  gap: 6px;
+  margin-bottom: 24px;
+  padding: 4px;
+  background: var(--bg-card);
+  border-radius: var(--radius-md);
+  width: fit-content;
+}
+
+.tab {
+  padding: 8px 20px;
+  border-radius: calc(var(--radius-md) - 2px);
+  font-size: 14px;
+  font-family: inherit;
+  font-weight: var(--fw-semi);
+  color: var(--text-secondary);
+  background: transparent;
+  cursor: pointer;
+  transition: all var(--transition-fast);
+  white-space: nowrap;
+
+  &:hover { color: var(--text-primary); }
+
+  &.active {
+    background: var(--color-primary);
+    color: #fff;
+    .tab-count { opacity: 0.85; }
+  }
+}
+
+.tab-count {
+  margin-left: 5px;
+  opacity: 0.55;
+  font-weight: var(--fw-regular);
+  font-size: 13px;
+
+  &::before { content: '('; }
+  &::after  { content: ')'; }
+}
+
+.result-section {
+  margin-bottom: 32px;
+}
+.card-grid {
+  display: grid;
+  grid-template-columns: repeat(auto-fill, minmax(140px, 1fr));
+  gap: 16px 28px;
+}
+.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; }
+}
+
+.platform-badge {
+  vertical-align: middle;
+  flex-shrink: 0;
+  font-size: var(--fs-micro);
+  font-weight: var(--fw-semi);
+  padding: 1px 5px;
+  border-radius: var(--radius-xs);
+  line-height: 1.4;
+}
+
+.badge-netease {
+  background: var(--brand-netease-15);
+  color: var(--brand-netease);
+}
+
+.badge-qq {
+  background: var(--brand-qq-15);
+  color: var(--brand-qq);
+}
+
+.badge-bilibili {
+  background: var(--brand-bilibili-15);
+  color: var(--brand-bilibili);
+}
+
+.badge-youtube {
+  background: var(--brand-youtube-12);
+  color: var(--brand-youtube);
+}
 </style>

web/src/views/Settings.vue

@@ -80,6 +80,10 @@
             <label>服务器密码（可选）</label>
             <input v-model="editForm.serverPassword" class="input" type="password" placeholder="服务器有密码时填写" />
           </div>
+          <div class="form-group">
+            <label>自定义头像</label>
+            <CustomAvatarRow :bot-id="editingBot" />
+          </div>
           <div class="modal-actions">
             <button class="btn-secondary" @click="editingBot = null">取消</button>
             <button class="btn-primary" @click="saveEditBot">保存（需重启机器人生效）</button>