Merge pull request #38 from NoSetViolin/main

fix #37

src/audio/player.ts

@@ -5,11 +5,12 @@ import { accessSync, chmodSync, constants } from "node:fs";
 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 +26,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,39 +35,16 @@ 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;
 }
@@ -93,12 +70,12 @@ 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;
 
@@ -109,112 +86,125 @@ 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.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");
-
     const args: string[] = [];
-
-    // BiliBili CDN requires Referer header for audio playback
     if (url.includes("bilivideo") || url.includes("bilibili")) {
-      args.push(
+      args.push("-headers", "Referer: https://www.bilibili.com\r\nUser-Agent: Mozilla/5.0...\r\n");
-        "-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("-reconnect", "1", "-reconnect_streamed", "1", "-reconnect_delay_max", "5");
-    args.push(
+    if (seekSeconds > 0) args.push("-ss", String(seekSeconds));
-      "-reconnect", "1",
+    args.push("-i", url, "-f", "s16le", "-ar", "48000", "-ac", "2", "-acodec", "pcm_s16le", "-");
-      "-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) {
+      // 2. 严格校验 sessionId，防止老进程的数据混入新播放请求 （
-        gotFirstData = true;
+      if (this.sessionId !== currentSessionId) {
-        this.logger.info({ bytes: chunk.length }, "FFmpeg: first PCM data received");
+        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.ffmpeg.stderr!.on("data", (data: Buffer) => {
-      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");
-      }
-    });
-
     this.state = "playing";
     this.startFrameLoop();
   }
 
+  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);
+      }
+    }
+
+    this.ffmpegPaused = false;
+    this.spawnFailed = false;
+    this.state = "idle";
+    this.currentUrl = "";
+    this.seekOffset = 0;
+    this.framesPlayed = 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 +214,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 +255,28 @@ export class AudioPlayer extends EventEmitter {
       const opusFrame = this.encoder.encode(adjusted);
       this.emit("frame", opusFrame);
       this.framesPlayed++;
-
-      if (this.framesPlayed === 1) {
-        this.logger.info({ opusBytes: opusFrame.length }, "First audio frame encoded and emitted");
-      }
-      // 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/bot/instance.ts

@@ -61,6 +61,8 @@ export class BotInstance extends EventEmitter {
   private disconnectEmitted = false;
   private voteSkipUsers = new Set<string>();
   private isAdvancing = false;
+  private idleTimer: ReturnType<typeof setTimeout> | null = null;
+  private channelUserCount = 0;
   private profileManager: BotProfileManager;
 
   constructor(options: BotInstanceOptions) {
@@ -131,6 +133,10 @@ export class BotInstance extends EventEmitter {
       this.disconnectEmitted = true;
       this.emit("disconnected");
     });
+
+    this.tsClient.on("connected", () => {
+      this._startIdlePoller();
+    });
   }
 
   async connect(): Promise<void> {
@@ -149,6 +155,7 @@ export class BotInstance extends EventEmitter {
   }
 
   disconnect(): void {
+    this._cancelIdleTimer();
     this.player.stop();
     this.connected = false;
     if (!this.disconnectEmitted) {
@@ -158,6 +165,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,

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";
@@ -135,20 +136,37 @@ 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)}`);
   }
 
@@ -178,7 +196,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 +215,8 @@ export class BotProfileManager {
           ),
           5000,
         );
+        this.logger.info("Description updated");
       }
-      this.logger.info("Description updated");
     } catch (err) {
       this.handleFeatureError("description", err);
     }
@@ -204,18 +226,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 +252,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 +423,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/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/index.ts

@@ -71,6 +71,7 @@ async function main() {
     bilibiliProvider,
     database: db,
     config,
+    configPath: CONFIG_PATH,
     logger,
     cookieStore,
     staticDir: STATIC_DIR,
@@ -78,7 +79,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/qq.ts

@@ -42,7 +42,7 @@ export class QQMusicProvider implements MusicProvider {
 
     const songs: Song[] = (res.data?.response?.data?.song?.list ?? []).map(
       (s: any) => ({
-        id: String(s.songmid ?? s.songid),
+        id: String(s.mid ?? s.songmid ?? s.songid),
         name: s.songname ?? "",
         artist: (s.singer ?? []).map((a: any) => a.name).join(" / "),
         album: s.albumname ?? "",
@@ -57,12 +57,26 @@ export class QQMusicProvider implements MusicProvider {
     return { songs, playlists: [], albums: [] };
   }
 
-  async getSongUrl(songId: string, _quality?: string): Promise<string | null> {
+  async getSongUrl(songId: string, quality?: string): Promise<string | null> {
-    const res = await this.api.get("/getMusicPlay", {
+    try {
-      params: { songmid: songId, ...this.cookieParams },
+      const res = await this.api.get("/getMusicPlay", {
-    });
+        params: { songmid: songId, quality: quality ?? this.quality, ...this.cookieParams },
-    const playUrl = res.data?.data?.playUrl?.[songId];
+      });
-    return playUrl?.url || null;
+      const playUrl = res.data?.data?.playUrl?.[songId];
+      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;
   }
 
   async getSongDetail(songId: string): Promise<Song | null> {
@@ -115,12 +129,14 @@ 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",

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,11 +1,13 @@
 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";
 
 export function createBotRouter(
   botManager: BotManager,
   config: BotConfig,
+  configPath: string,
   logger: Logger
 ): Router {
   const router = Router();
@@ -116,5 +118,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/player.ts

@@ -277,35 +277,54 @@ 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({ message: `Cannot play: ${song.name || song.id}` });
         return;
       }
 
-      res.json({ message: `Now playing: ${song.name} - ${song.artist}` });
+      res.json({ message: `Now playing: ${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

@@ -22,6 +22,7 @@ export interface WebServerOptions {
   bilibiliProvider: MusicProvider;
   database: BotDatabase;
   config: BotConfig;
+  configPath: string;
   logger: Logger;
   cookieStore?: CookieStore;
   staticDir?: string;
@@ -37,11 +38,21 @@ export function createWebServer(options: WebServerOptions): WebServer {
   const server = http.createServer(app);
   const logger = options.logger.child({ component: "web" });
 
+  if (options.config.trustProxy) {
+    // Honor X-Forwarded-* from a reverse proxy (nginx/Caddy/Cloudflare).
+    app.set("trust proxy", true);
+  }
+
   app.use(express.json());
 
+  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)
   );
   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/components/Navbar.vue

@@ -59,10 +59,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 +91,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(/\/+$/, '');
-    dropdownOpen.value = false;
+  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 +203,7 @@ function onClickOutside(e: MouseEvent) {
 
 onMounted(() => {
   document.addEventListener('click', onClickOutside);
+  loadPublicBaseUrl();
 });
 
 onUnmounted(() => {
@@ -376,4 +472,87 @@ onUnmounted(() => {
   transition: opacity var(--transition-fast);
   &:hover { opacity: 1; }
 }
+
+.link-dialog-backdrop {
+  position: fixed;
+  inset: 0;
+  background: rgba(0, 0, 0, 0.55);
+  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: 0 12px 40px rgba(0, 0, 0, 0.35);
+}
+
+.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/SongCard.vue

@@ -28,9 +28,10 @@
 <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;
 }>();

web/src/stores/player.ts

@@ -8,7 +8,7 @@ export interface Song {
   album: string;
   duration: number;
   coverUrl: string;
-  platform: 'netease' | 'qq';
+  platform: 'netease' | 'qq' | 'bilibili' | 'youtube';
 }
 
 export interface BotStatus {
@@ -259,6 +259,13 @@ export const usePlayerStore = defineStore('player', {
       this._syncAfterAction();
     },
 
+    async playSong(song: Song) {
+      if (!this.activeBotId) return;
+      await axios.post(`/api/player/${this.activeBotId}/play-song`, { song });
+      this._setTiming(this.activeBotId, { serverElapsed: 0 });
+      this._syncAfterAction();
+    },
+
     async addToQueue(query: string, platform = 'netease') {
       if (!this.activeBotId) return;
       await axios.post(`/api/player/${this.activeBotId}/add`, { query, platform });
@@ -269,6 +276,11 @@ 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 });

web/src/views/History.vue

@@ -19,8 +19,8 @@
         :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)"
+        @add="store.addSong(song)"
       />
     </div>
   </div>
@@ -35,7 +35,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

@@ -41,7 +41,7 @@
           v-for="song in store.dailySongs.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>
@@ -105,7 +105,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>

web/src/views/Playlist.vue

@@ -31,8 +31,8 @@
           :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)"
+          @add="store.addSong(song)"
         />
       </div>
     </template>
@@ -53,6 +53,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 +63,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() {

web/src/views/Search.vue

@@ -27,8 +27,8 @@
         :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)"
+        @add="store.addSong(song)"
       />
     </div>
 
@@ -50,7 +50,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

@@ -371,6 +371,32 @@
         </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>
   </div>
 </template>
 
@@ -661,10 +687,27 @@ 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 */ }
+}
+
 onMounted(() => {
   store.fetchBots(); // Refresh bot status on page visit
   checkAuthStatus();
   loadQuality();
+  loadIdleTimeout();
 });
 
 onUnmounted(() => {