Merge pull request #50 from ZHANGTIANYAO1/feature/design-implementation

Web UI redesign + per-platform tabs + play-next + audit fixes
fix: cmdPrev retry-skip + show SongCard actions on touch devices
2026-10-02 04:52:50 +08:00 · 2026-05-06 17:09:59 +08:00 · 2026-05-06 17:06:18 +08:00 · 2026-05-06 17:00:05 +08:00 · 2026-05-06 16:43:10 +08:00 · 2026-05-06 16:41:47 +08:00
74 changed files with 11474 additions and 1046 deletions
@@ -13,7 +13,10 @@
      "mcp__Claude_Preview__*",
      "mcp__Claude_in_Chrome__*",
      "mcp__scheduled-tasks__*",
-      "Bash(npx vitest:*)"
+      "Bash(npx vitest:*)",
+      "Bash(cp \"C:\\\\Users\\\\saopig1\\\\.claude\\\\projects\\\\C--Users-saopig1-Music-teamspeak-music-bot\\\\b5a64d6f-051e-4b87-966c-ece97d2b879b\\\\tool-results\\\\webfetch-1776569008470-exv7qe.bin\" /tmp/design.gz)",
+      "Bash(gunzip -f /tmp/design.gz)",
+      "Read(//tmp/**)"
    ],
    "deny": [
      "Bash(git push * main)",
@@ -6,3 +6,6 @@ dist/
 config.json
 cookies/
 .superpowers/
+.worktrees/
+/bin/
+scripts/navbar_bigger.png
@@ -1,11 +1,11 @@
 <p align="center">
-  <img src="https://img.shields.io/badge/TeamSpeak_3-音乐机器人-blue?style=for-the-badge&logo=teamspeak" alt="TSMusicBot" />
+  <img src="https://img.shields.io/badge/TeamSpeak-音乐机器人-blue?style=for-the-badge&logo=teamspeak" alt="TSMusicBot" />
 </p>

 <h1 align="center">TSMusicBot</h1>

 <p align="center">
-  <strong>TeamSpeak 3 音乐机器人</strong> — 网易云音乐 + QQ 音乐 + 哔哩哔哩 三平台，YesPlayMusic 风格 WebUI 控制面板
+  <strong>TeamSpeak 音乐机器人</strong> — 网易云音乐 + QQ 音乐 + 哔哩哔哩 + YouTube（可选），YesPlayMusic 风格 WebUI 控制面板
 </p>

 <p align="center">
@@ -16,14 +16,15 @@
  <img src="https://img.shields.io/badge/FFmpeg-已内置-orange?logo=ffmpeg" />
  <img src="https://img.shields.io/badge/Docker-支持-2496ED?logo=docker&logoColor=white" />
  <img src="https://img.shields.io/badge/BiliBili-支持-00a1d6?logo=bilibili&logoColor=white" />
+  <img src="https://img.shields.io/badge/YouTube-可选-FF0000?logo=youtube&logoColor=white" />
+  <img src="https://img.shields.io/badge/TS3-支持-2580C3?logo=teamspeak&logoColor=white" />
+  <img src="https://img.shields.io/badge/TS6-支持-2580C3?logo=teamspeak&logoColor=white" />
 </p>

---
-
 ## 功能特性

- **三平台音源** — 网易云音乐 + QQ 音乐 + 哔哩哔哩，统一搜索，结果标注来源
- **真实 TS3 客户端协议** — 机器人在 TeamSpeak 中可见（非 ServerQuery 隐身模式），兼容 TS3/TS5/TS6 服务器
+- **多平台音源** — 网易云音乐 + QQ 音乐 + 哔哩哔哩（默认内置），YouTube 可选启用（通过 yt-dlp），统一搜索，结果标注来源
+- **真实客户端协议 (TS3/TS6 双协议)** — 机器人在 TeamSpeak 中可见（非 ServerQuery 隐身模式），自动检测并适配 TS3 和 TS6 服务器，支持 TS6 HTTP Query API
 - **YesPlayMusic 风格 WebUI** — 精美界面，支持深色/浅色主题切换
 - **完整播放控制** — 播放/暂停/上一首/下一首/进度跳转/音量调节
 - **四种播放模式** — 顺序播放/循环播放/随机播放/随机循环
@@ -33,6 +34,7 @@
 - **B站视频音频提取** — 搜索B站视频，自动提取DASH最高码率音频流播放
 - **B站热门推荐** — 首页展示B站热门视频和个性化推荐（登录后更准确）
 - **QR码登录** — 扫码登录网易云/QQ音乐/哔哩哔哩账号，Cookie 自动持久化
+- **机器人形象自动更新** — 播放时自动更新头像（专辑封面）、昵称（当前歌曲）、描述、Away 状态、频道描述，停止时恢复默认值。每项功能独立可配置，权限不足时自动降级
 - **多机器人独立播放** — 多个机器人同时在不同服务器或频道播放不同音乐，每个机器人独立的播放队列、进度和音量，WebUI 一键切换控制
 - **播放历史** — 自动记录所有播放过的歌曲
 - **懒加载机制** — 歌单只存储元数据，播放时才获取链接（避免链接过期）
@@ -40,7 +42,8 @@

 ## 截图

-> *截图即将添加*
+> <img width="2568" height="1408" alt="musicbot1" src="https://github.com/user-attachments/assets/47ba4f62-fae3-4c17-a7f7-b53f00885672" />
+> <img width="2568" height="1408" alt="musicbot2" src="https://github.com/user-attachments/assets/42f4bef7-d41b-49e3-8c13-b4ce6c822dba" />

 ## 快速开始

@@ -64,8 +67,8 @@ FFmpeg **已自动内置**，无需手动安装。

 ```bash
 # 下载项目
-git clone https://github.com/ZHANGTIANYAO1/tsmusicbot.git
-cd tsmusicbot
+git clone https://github.com/ZHANGTIANYAO1/teamspeak-music-bot.git
+cd teamspeak-music-bot

 # 安装依赖
 npm install
@@ -85,8 +88,8 @@ npm start
 所有依赖已内置（Node.js、FFmpeg、Opus 编码器），无需安装任何额外软件。

 ```bash
-git clone https://github.com/ZHANGTIANYAO1/tsmusicbot.git
-cd tsmusicbot/scripts/docker
+git clone https://github.com/ZHANGTIANYAO1/teamspeak-music-bot.git
+cd teamspeak-music-bot/scripts/docker
 docker-compose up -d
 ```

@@ -124,6 +127,96 @@ sudo ./scripts/install.sh

 自动安装 Node.js 和依赖，配置 systemd 服务，支持开机自启。

+## 更新升级
+
+> **⚠️ 从使用 `@honeybbq/teamspeak-client 0.1.x` 的旧版本升级时的重要变更**
+>
+> 本项目已将底层 TeamSpeak 协议库升级到 `0.2.x` 并移除了内置的 TS6 兼容层，改用库自带的通用 `clientinit` 协议。这涉及一次**数据库迁移**：
+>
+> **旧的身份（identity）不兼容新的加密握手路径。** `0.1.0` 版本的库在生成 TS 客户端身份时存在 P-256 公钥 DER 编码错误，该 bug 在 `0.1.1` 中由本项目维护者 [ZHANGTIANYAO1](https://github.com/HoneyBBQ/teamspeak-js/pull/5) 修复并合并到上游。`0.1.0` 生成的身份与 `0.2.x` 修复后的握手路径**不兼容**：升级后用旧身份连接会卡在 `received initivexpand2` 直到 15 秒超时。
+>
+> **解决办法**：升级后清空受影响机器人的 `identity` 字段，下次启动时程序会自动生成新身份并持久化。
+>
+> ```bash
+> # 对每个需要迁移的机器人执行（替换 <bot-id> 为实际 UUID）：
+> python -c "import sqlite3; db=sqlite3.connect('data/tsmusicbot.db'); \
+>   db.execute(\"UPDATE bot_instances SET identity=NULL WHERE id='<bot-id>'\"); \
+>   db.commit()"
+>
+> # 或者清空所有机器人的身份：
+> python -c "import sqlite3; db=sqlite3.connect('data/tsmusicbot.db'); \
+>   db.execute('UPDATE bot_instances SET identity=NULL'); db.commit()"
+> ```
+>
+> **影响范围**：
+> - ✅ TS3 服务器 + 旧身份：在多数情况下仍可正常工作（TS3 对 legacy 编码更宽容），可选择不清空
+> - ❌ TS6 服务器 + 旧身份：**必须**清空身份才能连接
+> - ⚠️ 清空身份后，TS 服务器会把机器人识别为**全新的客户端**。之前手动赋予机器人的**服务器组需要用新 UID 重新授予一次**，之后每次重启都会自动保留
+>
+> **如何判断是否需要迁移**：如果你是全新安装，或者你的机器人数据库中 `identity` 字段已经是空的，则**无需任何操作**。完成上述步骤后，按下面对应的系统升级步骤执行即可。
+
+### Windows 用户
+
+```
+1. 双击 scripts\stop.bat 停止运行中的机器人（或手动关闭窗口）
+2. 在项目目录打开命令行，执行 git pull
+3. 双击 scripts\setup.bat 重新安装依赖并构建
+4. 双击 scripts\start.bat 启动
+```
+
+### 手动安装用户（所有系统）
+
+```bash
+# 停止当前运行的机器人（Ctrl+C 或 kill 进程）
+
+# 拉取最新代码
+git pull
+
+# 重新安装依赖（如有新增依赖）
+npm install
+cd web && npm install && cd ..
+
+# 重新构建
+npm run build
+
+# 启动
+npm start
+```
+
+### Docker 用户
+
+```bash
+cd scripts/docker
+
+# 拉取最新代码
+git pull
+
+# 重新构建并启动（数据自动保留）
+docker-compose up -d --build
+```
+
+> 数据（数据库、Cookie、日志）保存在 Docker 命名卷 `tsmusicbot-data` 中，更新不会丢失。
+
+### Linux systemd 用户
+
+```bash
+# 停止服务
+sudo systemctl stop tsmusicbot
+
+# 拉取最新代码
+git pull
+
+# 重新安装依赖并构建
+npm install
+cd web && npm install && cd ..
+npm run build
+
+# 重新启动服务
+sudo systemctl start tsmusicbot
+```
+
+> **提示：** 更新不会影响你的 `config.json` 配置文件、数据库和登录 Cookie，所有数据会自动保留。但请注意本节开头关于 **身份迁移** 的警告——从 0.1.x 版本升级时需要手动清空旧身份。
+
 ## 使用说明

 ### 首次配置
@@ -153,6 +246,7 @@ sudo ./scripts/install.sh
 | `!play <歌名>` | 搜索并播放 |
 | `!play -q <歌名>` | 从 QQ 音乐搜索 |
 | `!play -b <关键词>` | 从哔哩哔哩搜索视频并播放音频 |
+| `!play -y <关键词>` | 从 YouTube 搜索并播放（需要安装 [yt-dlp](#可选youtube-音源)）|
 | `!add <歌名>` | 添加到播放队列 |
 | `!pause` / `!resume` | 暂停 / 恢复播放 |
 | `!next` / `!prev` | 下一首 / 上一首 |
@@ -160,9 +254,11 @@ sudo ./scripts/install.sh
 | `!vol <0-100>` | 设置音量 |
 | `!queue` | 查看播放队列 |
 | `!mode <seq\|loop\|random\|rloop>` | 切换播放模式 |
-| `!playlist <ID>` | 加载歌单 |
+| `!playlist <歌单名或ID>` | 加载歌单（支持名称模糊搜索和 ID） |
+| `!playlist -q <歌单名>` | 从 QQ 音乐搜索并加载歌单 |
 | `!album <ID>` | 加载专辑 |
-| `!fm` | 私人 FM（网易云） |
+| `!artist <歌手名>` | 按歌手循环播放（支持 `-q`/`-b`/`-y`） |
+| `!fm` | 私人 FM（网易云，自动续播） |
 | `!lyrics` | 显示当前歌词 |
 | `!now` | 当前播放信息 |
 | `!vote` | 投票跳过当前歌曲 |
@@ -187,7 +283,7 @@ sudo ./scripts/install.sh
 ## 项目架构

 ```
-tsmusicbot/
+teamspeak-music-bot/
 ├── src/                        # 后端源码 (TypeScript)
 │   ├── audio/                  # 音频管线：FFmpeg → PCM → Opus → 20ms 帧
 │   │   ├── encoder.ts          # Opus 编码器 (@discordjs/opus)
@@ -196,7 +292,8 @@ tsmusicbot/
 │   ├── bot/                    # 机器人核心
 │   │   ├── commands.ts         # 文字命令解析器（前缀、别名、权限）
 │   │   ├── instance.ts         # Bot 实例（绑定 TS3 + 播放器 + 音源）
-│   │   └── manager.ts          # 多实例生命周期管理
+│   │   ├── manager.ts          # 多实例生命周期管理
+│   │   └── profile.ts          # 机器人形象管理（头像/昵称/描述/Away/频道描述）
 │   ├── data/                   # 数据层
 │   │   ├── config.ts           # JSON 配置文件
 │   │   └── database.ts         # SQLite 数据库（播放历史、实例持久化）
@@ -205,10 +302,14 @@ tsmusicbot/
 │   │   ├── netease.ts          # 网易云音乐适配器
 │   │   ├── qq.ts               # QQ 音乐适配器
 │   │   ├── bilibili.ts         # 哔哩哔哩适配器（视频音频提取）
+│   │   ├── youtube.ts          # YouTube 适配器（可选，依赖 yt-dlp）
 │   │   ├── auth.ts             # Cookie 持久化存储
 │   │   └── api-server.ts       # 嵌入式 API 服务（自动启动）
-│   ├── ts-protocol/            # TS3 客户端协议
-│   │   └── client.ts           # 完整客户端（ECDH + AES-EAX 加密协议）
+│   ├── ts-protocol/            # TeamSpeak 客户端协议（TS3/TS6 双协议）
+│   │   ├── client.ts           # 完整客户端（ECDH + AES-EAX 加密协议）
+│   │   ├── protocol-detect.ts  # 服务器协议自动检测（TS3 vs TS6）
+│   │   ├── http-query.ts       # TS6 HTTP Query 客户端（替代 TS3 ServerQuery）
+│   │   └── ts6-compat.ts       # TS6 兼容中间件（版本升级 + 签名）
 │   ├── web/                    # Web 后端
 │   │   ├── server.ts           # Express + WebSocket 服务
 │   │   ├── websocket.ts        # 实时状态广播
@@ -246,7 +347,7 @@ tsmusicbot/
 | **后端框架** | Express 4, WebSocket (ws) |
 | **数据库** | better-sqlite3 (SQLite) |
 | **音频处理** | FFmpeg (ffmpeg-static 内置), @discordjs/opus |
-| **TS 协议** | @honeybbq/teamspeak-client（完整客户端协议，兼容 TS3/TS5/TS6） |
+| **TS 协议** | @honeybbq/teamspeak-client（完整客户端协议）+ 自研 TS6 协议适配层 |
 | **网易云 API** | NeteaseCloudMusicApi |
 | **QQ 音乐 API** | @sansenjian/qq-music-api |
 | **哔哩哔哩** | BiliBili Web API（搜索、DASH 音频流、QR 登录） |
@@ -255,6 +356,55 @@ tsmusicbot/
 | **图标** | @iconify/vue |
 | **日志** | pino |

+## 可选：YouTube 音源
+
+YouTube 是**可选**的音源，默认**未启用**，需要安装 [yt-dlp](https://github.com/yt-dlp/yt-dlp) 才能使用。启用后可通过聊天命令 `!play -y <关键词>` 或 WebUI 的 YouTube 平台选项搜索/播放 YouTube 视频的音频流。
+
+### 启用方式（任选其一）
+
+**方式一：项目本地 `bin/` 目录（推荐）**
+
+将 `yt-dlp` 可执行文件放到项目根目录下的 `bin/` 文件夹，程序会优先使用此路径。该目录已被 `.gitignore` 忽略，不会影响代码更新。
+
+```bash
+# Windows（PowerShell 或 Git Bash）
+mkdir bin
+curl -L -o bin/yt-dlp.exe https://github.com/yt-dlp/yt-dlp/releases/latest/download/yt-dlp.exe
+
+# Linux / macOS
+mkdir -p bin
+curl -L -o bin/yt-dlp https://github.com/yt-dlp/yt-dlp/releases/latest/download/yt-dlp
+chmod +x bin/yt-dlp
+```
+
+**方式二：系统级安装（让 `yt-dlp` 在 `PATH` 中可用）**
+
+```bash
+# Windows
+winget install yt-dlp
+
+# macOS
+brew install yt-dlp
+
+# Debian/Ubuntu
+sudo apt install yt-dlp
+
+# 通用（Python 环境下）
+pip install -U yt-dlp
+```
+
+### 验证是否可用
+
+重启机器人程序，在 WebUI 或 `!play -y lofi` 测试搜索。若 `bin/` 和 `PATH` 中都找不到 `yt-dlp`，YouTube 搜索会静默返回空结果（不会影响其他音源），其余功能正常。
+
+### 注意事项
+
+- YouTube 音源通过 `yt-dlp` 本地调用实现，不依赖 API Key，也无需登录
+- 播放的是视频的最佳音频流（`bestaudio[ext=webm]/bestaudio[ext=m4a]/bestaudio`），由 FFmpeg 解码
+- 音质由源视频决定，不受音质设置影响
+- 受 YouTube 风控/地域限制，部分视频可能无法播放
+- `yt-dlp` 更新较频繁，如果播放失败，先尝试升级 `yt-dlp` 到最新版本
+
 ## 配置文件

 `config.json` 在首次运行时自动生成，可手动编辑：
@@ -277,6 +427,9 @@ tsmusicbot/

 ## 常见问题

+**Q：支持 TeamSpeak 6 Server 吗？**
+A：支持。本项目内置 TS3/TS6 双协议支持，连接时会自动检测服务器类型。如果自动检测失败（例如 Query 端口被防火墙屏蔽），可以在创建机器人时手动指定 `serverProtocol: "ts6"`。TS6 Server 的 HTTP Query API（端口 10080）也已适配，需要时可配置 `ts6ApiKey`。
+
 **Q：机器人连接了但 TeamSpeak 中听不到音乐？**
 A：确保机器人和你在同一个频道。检查音量（`!vol 75`）。部分 VIP 歌曲需要先登录账号。

@@ -305,6 +458,9 @@ A：原生模块（opus、sqlite3）需要编译工具，Dockerfile 已包含。
 **Q：B站视频搜索不到结果？**
 A：B站搜索需要 buvid3 匿名 Cookie（程序启动时自动获取）。如果失败，重启程序即可。登录B站账号后搜索效果更好。

+**Q：YouTube 平台搜索返回空结果？**
+A：YouTube 是可选音源，需要手动安装 `yt-dlp`。详见 [可选：YouTube 音源](#可选youtube-音源) 章节。快速验证：在项目根目录执行 `bin/yt-dlp --version`（或系统 `yt-dlp --version`），能打印版本号即可。若 yt-dlp 已安装但仍搜索失败，通常是网络/地域问题或 yt-dlp 版本过旧（执行 `yt-dlp -U` 升级）。
+
 **Q：如何更新到新版本？**
 A：`git pull` 拉取最新代码，然后 `npm install && npm run build && npm start` 重新构建启动。Docker 用户执行 `docker-compose up -d --build`。

@@ -316,12 +472,89 @@ A：`git pull` 拉取最新代码，然后 `npm install && npm run build && npm
 4. 推送分支 (`git push origin feature/新功能`)
 5. 提交 Pull Request

+## 更新日志
+
+> 完整历史请查看 [git log](https://github.com/ZHANGTIANYAO1/teamspeak-music-bot/commits/main) 或 [Releases](https://github.com/ZHANGTIANYAO1/teamspeak-music-bot/releases)。这里只列出重要变更和面向用户的破坏性改动。
+
+### 最新版本
+
+**机器人形象自动更新（Bot Profile）**
+
+- **播放时自动更新 TS 形象**：头像（专辑封面缩略图）、昵称（`♪ 歌名 - 歌手 - 原昵称`）、描述（歌曲信息）、Away 状态、频道描述、"正在播放"频道消息，全部随歌曲切换自动更新。
+- **停止播放时恢复默认**：头像清除、昵称恢复、Away 显示"等待播放"、描述和频道描述清空。
+- **权限安全**：每项功能独立检测权限，权限不足时自动禁用该功能（不影响其他功能和播放），重连后重试。
+- **独立可配置**：6 项功能可通过 REST API（`GET/PUT /api/player/:botId/profile`）独立开关，配置持久化到数据库。
+- **竞争条件防护**：generation 计数器防止快速切歌时旧头像覆盖新头像；UTF-8 字节长度截断中文昵称；文件传输操作带超时保护。
+- **TS3 适配**：描述通过 `clientedit`（非 `clientupdate`）设置，需要 `b_client_modify_description` 权限；昵称和 Away 通过合并的单条 `clientupdate` 避免命令队列超时。
+
+**新命令 & FM 修复**
+
+- **新增 `!artist <歌手名>` 命令**：搜索指定歌手的歌曲并循环播放，支持 `-q`（QQ 音乐）/ `-b`（B站）/ `-y`（YouTube）平台切换。一次加载最多 50 首，自动按歌手名过滤并设为 Loop 模式。
+- **歌单模糊搜索**：`!playlist` 现在支持歌单名称模糊搜索（如 `!playlist 华语经典`），自动匹配公开歌单 + 个人歌单（网易云 + QQ）。纯数字 ID 和 URL 解析保持兼容。
+- **修复 `!fm` 播放中断**：私人 FM 几首歌后静音的 bug 已修复。新增自动续播机制（队列低位自动拉取新歌），播放器健康帧追踪防止临时 URL 失败导致永久静音。
+- **QQ 音乐个人歌单**：QQ Music provider 新增 `getUserPlaylists` 支持，登录后可通过 `!playlist -q <名称>` 模糊搜索个人歌单。
+
+**协议层 & 稳定性**
+
+- **升级 `@honeybbq/teamspeak-client` 到 `0.2.1`**，移除内置 TS6 兼容层（`ts6-compat.ts`），改用库自带的通用 `clientinit` 协议（`3.?.? [Build: 5680278000]`），TS3/TS6 单一代码路径。
+  - ⚠️ **破坏性**：`0.1.0` 生成的旧身份与新握手路径不兼容，升级时需要迁移。详见 [更新升级](#更新升级) 章节顶部的警告。
+- **修复 `startBot` 与 `stopBot` 之间的竞态**：mid-handshake 被替换的 BotInstance 不再泄漏 TS 会话，`disconnect()` 被 `connect()` 的 await 插队时不再错误地把 `connected` 翻回 `true`。
+- **修复播放条自动刷新 bug**：BotManager 现在在创建新 BotInstance 时 emit `botInstance` 事件，WebSocket 监听器会立即重新挂接到新实例，播放状态变化无需手动刷新页面。
+- **`connect()` 增加 15 秒超时**：握手卡住时会清理掉挂起的实例并返回 500，不再无限阻塞 HTTP 请求和 UI。
+- **识别持久化修复**：`startBot` 现在会从数据库读取 `identity` 传给新 BotInstance，服务器组在机器人重启后能保留。
+
+**HTTP API 加固**
+
+- 新增输入校验，拒绝无效值并返回 **400**（之前会返回 200 包装 usage-text 字符串）：
+  - `/volume`：非数字、`NaN`/`Infinity`、超出 `[0,100]`
+  - `/mode`：不在 `{seq, loop, random, rloop}` 中的值
+  - `/seek`：`NaN`/`Infinity`、负数、字符串
+  - `/play-at`：索引越界（**先**校验再停止当前播放，避免误杀正在播的歌）
+- **修复 YouTube 平台路由**：`/play`、`/add`、`/playlist`、`/play-by-id`、`/add-by-id`、`/play-playlist` 现在都正确处理 `platform=youtube`（之前会静默回退到网易云）。
+- **修复 `/auth/status?platform=youtube` 数据泄漏**：之前会回退到网易云并返回网易云用户的昵称 + 头像 URL，现在正确路由到 YouTube provider 并报告 `yt-dlp` 的实际可用状态。
+- **`/auth/cookie` 拒绝 `platform=youtube`**，防止意外覆盖网易云 cookie。
+
+**连接状态一致性**
+
+- 断开连接时，音频命令（`play`/`add`/`next`/`prev`/`playlist`/`album`/`fm`）返回 **400 "Bot is not connected to TeamSpeak"**；配置类命令（`volume`/`mode`/`clear`/`stop`/`queue`/`now`/`lyrics`）仍可正常工作，保持 UI 可用。
+- `resolveAndPlay` 在网络请求（URL 解析）前后都会检查 `this.connected`，防止在解析期间被 `stop()` 中断后仍然启动 ffmpeg。
+- `tsClient` 的 `disconnected` 事件处理器现在总是清理播放器状态，不再因为 `connect()` 从未完成而遗留 `playing=true` 的僵尸状态。
+
+**功能改进**
+
+- **YouTube 音源（可选）**：新增基于 `yt-dlp` 的 YouTube provider，通过 `!play -y <关键词>` 或 WebUI 平台选项使用。未安装 `yt-dlp` 时静默降级、返回空结果，不影响其他音源。详见 [可选：YouTube 音源](#可选youtube-音源)。
+- **Bot Selector UI**：
+  - 始终可见（不再只有 ≥2 个机器人时才显示）
+  - 尺寸放大（更大的按钮、字体、状态图标）
+  - 每行增加 **电源按键**（一键启动/停止对应机器人，带禁用态与播放状态高亮）
+  - 每行增加 **链接按钮**（复制机器人专属 URL）
+  - 新路由 `/bot/:id`，打开后自动切换到对应机器人
+- **服务器密码登录**：`serverPassword` 字段已加入数据库与 Settings UI，支持加入需要密码的 TS 服务器。
+- **`!add` 一键开播**：在连接状态下向空队列 `!add` 歌曲时自动开始播放（之前只会入队，需要再 `!play` 或 `!next`）。
+- **WebSocket 新增 `botRemoved` 事件**：删除机器人后 UI 会立即从列表中移除（之前需要手动刷新页面）。
+
+**内部修复**
+
+- **`PlayQueue.remove()` 当前歌曲移除 bug**：移除正在播放的歌曲时，`next()` 不再跳过紧跟其后的那首歌。
+- **投票跳过**：需要的票数现在至少为 1（避免 `needed=0` 时单人"全票通过"的边界情况）；投票计数会在每首新歌开始时自动清零，不再跨歌曲泄漏。
+- 多处输入边界修复：`seek` 防止 `NaN` 毒化 `seekOffset` 导致 `getElapsed()` 永久返回 `NaN`；`play-at` 越界时不再误杀当前播放。
+
+### 历史重要变更
+
+更早的变更请查阅 git log。主要里程碑：
+
+- **初始 TS3/TS6 双协议支持**：自动协议检测（TS3 port 10011 vs TS6 port 10080）、TS6 HTTP Query 客户端、数据库持久化 `serverProtocol` / `ts6ApiKey`。
+- **多机器人架构**：支持同一进程中运行多个机器人实例，独立队列、进度、音量；WebUI 一键切换。
+- **网易云 / QQ 音乐 / 哔哩哔哩**：三平台原生音源，QR 码登录，Cookie 持久化。
+- **Docker & systemd 部署**：一键部署脚本，数据卷持久化，自动重启支持。
+
 ## 致谢

 感谢以下项目和开发者：

 | 项目 | 说明 |
 |------|------|
+| [yichen11818/NeteaseTSBot](https://github.com/yichen11818/NeteaseTSBot) | TS6 协议兼容参考（vendored tsproto 补丁） |
 | [Splamy/TS3AudioBot](https://github.com/Splamy/TS3AudioBot) | 优秀的 TeamSpeak 音频机器人框架 |
 | [TS3AudioBot-BiliBiliPlugin](https://github.com/xxmod/TS3AudioBot-BiliBiliPlugin) | 提供插件开发参考 |
 | [TS3AudioBot-NetEaseCloudmusic-plugin](https://github.com/ZHANGTIANYAO1/TS3AudioBot-NetEaseCloudmusic-plugin) | 提供插件开发参考和懒加载设计参考 |
@@ -0,0 +1,517 @@
+# FM Bug Fix + Artist Loop + Playlist Fuzzy Search — Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Fix FM audio dropout bug, add `!artist` command for artist-based loop playback, and support playlist name fuzzy search in `!playlist`.
+
+**Architecture:** All changes stay within existing files. The FM fix adds auto-refill logic and a success-tracking mechanism in the player. Playlist search reuses the existing `provider.search()` API that already returns playlists. The `!artist` command is a new command method following the same pattern as `cmdPlay`/`cmdFm`.
+
+**Tech Stack:** TypeScript, Node.js, ffmpeg-static, @honeybbq/teamspeak-client
+
+---
+
+## File Map
+
+| File | Change | Purpose |
+|------|--------|---------|
+| `src/bot/instance.ts` | Modify | Add `isFmMode`, `refillFm()`, fix `cmdFm()`, modify `cmdPlaylist()`, add `cmdArtist()`, modify `playNext()` to trigger FM refill |
+| `src/bot/commands.ts` | Modify | Register `artist` in PUBLIC_COMMANDS, update help text |
+| `src/audio/player.ts` | Modify | Track healthy frame count, reset `consecutiveFailures` after sustained successful playback |
+
+---
+
+### Task 1: Fix FM — Track healthy playback in AudioPlayer
+
+**Files:**
+- Modify: `src/audio/player.ts:62-82` (add field)
+- Modify: `src/audio/player.ts:243-261` (sendNextFrame — track healthy frames)
+
+- [ ] **Step 1: Add healthy frame counter field**
+
+In `src/audio/player.ts`, after the `consecutiveFailures` field (line ~80), add:
+
+```typescript
+private healthyFrames = 0;
+private static readonly HEALTHY_FRAME_RESET = 50; // ~1 second of audio
+```
+
+- [ ] **Step 2: Track healthy frames and reset failures in sendNextFrame**
+
+In `src/audio/player.ts`, in the `sendNextFrame()` method, after line 257 (`this.framesPlayed++;`), add:
+
+```typescript
+this.healthyFrames++;
+if (this.healthyFrames >= AudioPlayer.HEALTHY_FRAME_RESET) {
+  this.consecutiveFailures = 0;
+  this.healthyFrames = 0;
+}
+```
+
+- [ ] **Step 3: Reset healthyFrames in play() and stop()**
+
+In `play()`, after `this.framesPlayed = 0;` (line ~95), add:
+
+```typescript
+this.healthyFrames = 0;
+```
+
+In `stop()`, after `this.framesPlayed = 0;` (line ~181), add:
+
+```typescript
+this.healthyFrames = 0;
+```
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add src/audio/player.ts
+git commit -m "fix(player): reset consecutiveFailures after sustained healthy playback"
+```
+
+---
+
+### Task 2: Fix FM — Add auto-refill logic in BotInstance
+
+**Files:**
+- Modify: `src/bot/instance.ts:62-66` (add fields)
+- Modify: `src/bot/instance.ts:557-573` (cmdFm)
+- Modify: `src/bot/instance.ts:642-673` (playNext — add refill trigger)
+
+- [ ] **Step 1: Add isFmMode field**
+
+In `src/bot/instance.ts`, after `private profileManager: BotProfileManager;` (line ~66), add:
+
+```typescript
+private isFmMode = false;
+```
+
+- [ ] **Step 2: Add refillFm method**
+
+In `src/bot/instance.ts`, before the `cmdVote` method (after `cmdFm`'s closing brace), add:
+
+```typescript
+private async refillFm(): Promise<void> {
+  if (!this.isFmMode || !this.neteaseProvider.getPersonalFm) return;
+  try {
+    const songs = await this.neteaseProvider.getPersonalFm();
+    if (songs.length === 0) return;
+    for (const song of songs) {
+      this.queue.add({ ...song, platform: "netease" });
+    }
+    this.logger.debug({ count: songs.length }, "FM queue refilled");
+  } catch (err) {
+    this.logger.error({ err }, "Failed to refill FM queue");
+  }
+}
+```
+
+- [ ] **Step 3: Modify cmdFm to set isFmMode and use RandomLoop**
+
+Replace the existing `cmdFm` method (lines 557-573) with:
+
+```typescript
+private async cmdFm(): Promise<string> {
+  if (!this.neteaseProvider.getPersonalFm) {
+    return "Personal FM is only available for NetEase Cloud Music";
+  }
+  const songs = await this.neteaseProvider.getPersonalFm();
+  if (songs.length === 0)
+    return "No FM songs available (need to login first)";
+
+  this.queue.clear();
+  for (const song of songs) {
+    this.queue.add({ ...song, platform: "netease" });
+  }
+  this.queue.setMode(PlayMode.RandomLoop);
+  this.isFmMode = true;
+  this.player.resetFailures();
+
+  const first = this.queue.play();
+  if (first) await this.resolveAndPlay(first);
+  this.emit("stateChange");
+  return `Personal FM started: ${first?.name ?? "unknown"} - ${first?.artist ?? ""}`;
+}
+```
+
+- [ ] **Step 4: Modify playNext to trigger FM refill and check isFmMode**
+
+In `playNext()`, replace the `else` branch (lines 665-668) that handles `queue.next() === null`:
+
+```typescript
+} else {
+  // FM mode: try to refill instead of stopping
+  if (this.isFmMode) {
+    await this.refillFm();
+    const refillNext = this.queue.next();
+    if (refillNext) {
+      const started = await this.resolveAndPlay(refillNext);
+      if (!started) {
+        this.player.stop();
+        this.profileManager.onSongChange(null).catch(() => {});
+      }
+      this.emit("stateChange");
+    } else {
+      this.player.stop();
+      this.profileManager.onSongChange(null).catch(() => {});
+    }
+  } else {
+    this.player.stop();
+    this.profileManager.onSongChange(null).catch(() => {});
+  }
+}
+```
+
+Also add a proactive refill after successful advance. At the end of the `if (next)` block, after `this.emit("stateChange");` is handled outside the if/else, add this right after `resolveAndPlay` succeeds (inside the `if (next)` block, after the retry loop):
+
+After the `if (!started)` block and before the closing `}` of `if (next)`, insert:
+
+```typescript
+// Proactive FM refill when running low
+if (this.isFmMode && this.queue.size() - (this.queue.getCurrentIndex()) <= 3) {
+  this.refillFm().catch(err => this.logger.error({ err }, "Proactive FM refill failed"));
+}
+```
+
+Wait — `this.emit("stateChange")` is outside the `if (next)` block. Let me re-read the original code structure...
+
+The original `playNext()` structure is:
+```
+if (next) {
+    let started = await resolveAndPlay(next)
+    if (!started) { retry loop... }
+    if (!started) { stop }
+} else {
+    stop
+}
+emit("stateChange")
+```
+
+So I need to add the proactive refill inside the `if (next)` block, right after `resolveAndPlay` succeeds. Let me write this more carefully:
+
+```typescript
+private async playNext(): Promise<void> {
+    if (this.isAdvancing || !this.connected) return;
+    this.isAdvancing = true;
+    try {
+      this.voteSkipUsers.clear();
+      const next = this.queue.next();
+      if (next) {
+        let started = await this.resolveAndPlay(next);
+        if (!started) {
+          for (let i = 0; i < 3 && this.connected; i++) {
+            const retry = this.queue.next();
+            if (!retry) break;
+            if (await this.resolveAndPlay(retry)) {
+              started = true;
+              break;
+            }
+          }
+        }
+        if (!started) {
+          this.player.stop();
+          this.profileManager.onSongChange(null).catch(() => {});
+        } else if (this.isFmMode && this.queue.size() - this.queue.getCurrentIndex() <= 3) {
+          // Proactive refill: when queue is running low, fetch more FM songs
+          this.refillFm().catch(err => this.logger.error({ err }, "Proactive FM refill failed"));
+        }
+      } else {
+        // Queue exhausted — in FM mode, refill instead of stopping
+        if (this.isFmMode) {
+          await this.refillFm();
+          const refillNext = this.queue.next();
+          if (refillNext) {
+            await this.resolveAndPlay(refillNext);
+          } else {
+            this.player.stop();
+            this.profileManager.onSongChange(null).catch(() => {});
+          }
+        } else {
+          this.player.stop();
+          this.profileManager.onSongChange(null).catch(() => {});
+        }
+      }
+      this.emit("stateChange");
+    } finally {
+      this.isAdvancing = false;
+    }
+  }
+```
+
+OK this is getting complex. Let me simplify the plan — I'll structure it more clearly.
+
+Also I need to clear `isFmMode` when user issues stop/clear or manually plays something else.
+
+- [ ] **Step 5: Clear isFmMode in stop/clear/play commands**
+
+In `cmdStop()`, after `this.queue.clear();`, add:
+
+```typescript
+this.isFmMode = false;
+```
+
+In `cmdClear()` (same line), add:
+
+```typescript
+this.isFmMode = false;
+```
+
+In `cmdPlay()`, after `this.queue.clear();`, add:
+
+```typescript
+this.isFmMode = false;
+```
+
+In `cmdPlaylist()`, after `this.queue.clear();`, add:
+
+```typescript
+this.isFmMode = false;
+```
+
+In `cmdAlbum()`, after `this.queue.clear();`, add:
+
+```typescript
+this.isFmMode = false;
+```
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add src/bot/instance.ts
+git commit -m "fix: FM auto-refill to prevent audio dropout after initial batch"
+```
+
+---
+
+### Task 3: Playlist Fuzzy Search
+
+**Files:**
+- Modify: `src/bot/instance.ts:524-539` (cmdPlaylist)
+
+- [ ] **Step 1: Modify cmdPlaylist to support name search**
+
+Replace the `cmdPlaylist` method (lines 524-539) with:
+
+```typescript
+private async cmdPlaylist(cmd: ParsedCommand): Promise<string> {
+  if (!cmd.args) return "Usage: !playlist <playlist name or ID>";
+  const provider = this.getProvider(cmd.flags);
+
+  // Determine if input is a numeric ID or a name search
+  const id = this.extractId(cmd.args);
+  const isNumericId = /^\d+$/.test(cmd.args.trim());
+
+  let playlistId: string;
+
+  if (isNumericId || id !== cmd.args) {
+    // Input is a numeric ID or URL containing an ID — use existing logic
+    playlistId = id;
+  } else {
+    // Name-based search
+    const result = await provider.search(cmd.args);
+    let playlists = result.playlists ?? [];
+
+    // Also search user's personal playlists if logged in
+    if (provider.getUserPlaylists) {
+      try {
+        const userPlaylists = await provider.getUserPlaylists();
+        const query = cmd.args.toLowerCase();
+        const matched = userPlaylists.filter(
+          p => p.name.toLowerCase().includes(query)
+        );
+        // Merge: public results first (API-ranked), then user matches
+        playlists = [...playlists, ...matched];
+      } catch {
+        // User playlists unavailable — continue with public results
+      }
+    }
+
+    if (playlists.length === 0)
+      return `No playlists found for: ${cmd.args}`;
+    playlistId = playlists[0].id;
+  }
+
+  const songs = await provider.getPlaylistSongs(playlistId);
+  if (songs.length === 0) return "Playlist is empty or not found";
+
+  this.queue.clear();
+  this.isFmMode = false;
+  for (const song of songs) {
+    this.queue.add({ ...song, platform: provider.platform });
+  }
+  const first = this.queue.play();
+  if (first) await this.resolveAndPlay(first);
+  this.emit("stateChange");
+  return `Loaded ${songs.length} songs. Now playing: ${first?.name ?? "unknown"}`;
+}
+```
+
+- [ ] **Step 2: Update help text to reflect new usage**
+
+In `cmdHelp()` (line ~633), change the playlist line from:
+
+```
+`${p}playlist <id> — Load playlist`
+```
+
+to:
+
+```
+`${p}playlist <name or id> — Load playlist by name or ID`
+```
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add src/bot/instance.ts
+git commit -m "feat: support playlist name fuzzy search in !playlist command"
+```
+
+---
+
+### Task 4: Artist Loop Command
+
+**Files:**
+- Modify: `src/bot/commands.ts:8-11` (PUBLIC_COMMANDS)
+- Modify: `src/bot/commands.ts:248-260` (AUDIO_COMMANDS in instance.ts — actually in instance.ts)
+- Modify: `src/bot/instance.ts:244-314` (executeCommand switch + add cmdArtist)
+
+Wait, AUDIO_COMMANDS is in instance.ts executeCommand. Let me check...
+
+Actually looking back at instance.ts, the AUDIO_COMMANDS set is local to executeCommand. I don't need to add artist there since it will be handled in the switch.
+
+- [ ] **Step 1: Register `artist` in PUBLIC_COMMANDS**
+
+In `src/bot/commands.ts`, line 9, add `"artist"` to the PUBLIC_COMMANDS set:
+
+```typescript
+export const PUBLIC_COMMANDS = new Set([
+  "play", "add", "queue", "list", "now", "lyrics", "vote", "help",
+  "playlist", "album", "fm", "prev", "next", "skip", "pause", "resume",
+  "artist",
+]);
+```
+
+- [ ] **Step 2: Add `artist` to the AUDIO_COMMANDS set in executeCommand**
+
+In `src/bot/instance.ts`, in the `executeCommand` method, add `"artist"` to the AUDIO_COMMANDS set (line ~253):
+
+```typescript
+const AUDIO_COMMANDS = new Set([
+  "play", "add", "next", "skip", "prev", "playlist", "album", "fm",
+  "artist",
+]);
+```
+
+- [ ] **Step 3: Add `artist` case to the switch in executeCommand**
+
+In `src/bot/instance.ts`, after the `case "fm":` block (line ~300), add:
+
+```typescript
+case "artist":
+  return this.cmdArtist(cmd);
+```
+
+- [ ] **Step 4: Implement cmdArtist method**
+
+Add the `cmdArtist` method in `src/bot/instance.ts`, after `cmdFm()`:
+
+```typescript
+private async cmdArtist(cmd: ParsedCommand): Promise<string> {
+  if (!cmd.args) return "Usage: !artist <artist name>";
+  const provider = this.getProvider(cmd.flags);
+  const result = await provider.search(cmd.args, 50);
+  if (result.songs.length === 0)
+    return `No results found for artist: ${cmd.args}`;
+
+  const query = cmd.args.toLowerCase();
+  let filtered = result.songs.filter(
+    s => s.artist.toLowerCase().includes(query)
+  );
+
+  // Fallback to unfiltered results if filtering drops everything
+  if (filtered.length === 0) {
+    filtered = result.songs.slice(0, 20);
+  }
+
+  this.queue.clear();
+  this.isFmMode = false;
+  for (const song of filtered) {
+    this.queue.add({ ...song, platform: provider.platform });
+  }
+  this.queue.setMode(PlayMode.Loop);
+  this.player.resetFailures();
+
+  const first = this.queue.play();
+  if (first) await this.resolveAndPlay(first);
+  this.emit("stateChange");
+  return `Artist mode: ${cmd.args} — ${filtered.length} songs loaded. Now playing: ${first?.name ?? "unknown"}`;
+}
+```
+
+- [ ] **Step 5: Update help text**
+
+In `cmdHelp()`, add the artist help line after the fm line:
+
+```
+`${p}artist <name> — Play songs by artist (loop)`
+```
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add src/bot/commands.ts src/bot/instance.ts
+git commit -m "feat: add !artist command for artist-based loop playback"
+```
+
+---
+
+### Task 5: Type-check and verify
+
+**Files:**
+- All modified files
+
+- [ ] **Step 1: Run type check**
+
+```bash
+cd /home/proxxy/project/teamspeak-music-bot && npm run typecheck
+```
+
+Expected: No errors.
+
+- [ ] **Step 2: Verify command parsing**
+
+```bash
+cd /home/proxxy/project/teamspeak-music-bot && node --loader ts-node/esm -e "
+const { parseCommand } = await import('./src/bot/commands.ts');
+console.log(parseCommand('!artist 周杰伦', '!'));
+console.log(parseCommand('!artist 周杰伦 -q', '!'));
+console.log(parseCommand('!playlist 华语经典', '!'));
+console.log(parseCommand('!playlist 123456', '!'));
+"
+```
+
+Expected: All parse correctly; `artist` with args "周杰伦", `playlist` with args "华语经典" and "123456".
+
+- [ ] **Step 3: Commit any fixes from type check**
+
+```bash
+git add -A && git commit -m "chore: type fixes from final verification"
+```
+(Only if there were issues)
+
+---
+
+### Self-Review Checklist
+
+1. **Spec coverage:**
+   - FM bug fix → Tasks 1, 2 (healthy frame tracking + auto-refill)
+   - Playlist fuzzy search → Task 3
+   - Artist loop → Task 4
+   - Verification → Task 5
+
+2. **No placeholders** — all steps have exact code.
+
+3. **Type consistency:**
+   - `isFmMode: boolean` — used in cmdFm, cmdStop, cmdClear, cmdPlay, cmdPlaylist, cmdAlbum, playNext, refillFm ✓
+   - `refillFm(): Promise<void>` — called from cmdFm (indirectly via playNext trigger), playNext ✓
+   - `healthyFrames: number`, `HEALTHY_FRAME_RESET: 50` — used in play(), stop(), sendNextFrame() ✓
@@ -0,0 +1,911 @@
+# Music Source Tabs Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Add NetEase / QQ source-switcher tabs to Home (推荐歌单 / 每日推荐 / 我的歌单) and Library (我的歌单), with per-section persistence and graceful degradation when only one source is logged in.
+
+**Architecture:** A single shared `<SourceTabs>` Vue component handles the tab UI and self-hides when fewer than 2 sources are available. The Pinia store splits the affected fields into `{ netease, qq }` objects, fetches from both platforms in `fetchHomeData()` based on `authStatus`, and consumers select with a reactive `activeSource` ref persisted to localStorage.
+
+**Tech Stack:** Vue 3 (Composition API + `<script setup>`), Pinia, TypeScript, SCSS (CSS variables from `web/src/styles/variables.scss`).
+
+**Spec:** `docs/superpowers/specs/2026-05-06-music-source-tabs-design.md`
+
+---
+
+## File Structure
+
+**New:**
+- `web/src/components/SourceTabs.vue` — shared tab UI (presentational, no store deps)
+
+**Modified:**
+- `web/src/stores/player.ts` — state shape change + `authStatus` + `fetchHomeData` rewrite
+- `web/src/views/Home.vue` — 3 sections wired to SourceTabs
+- `web/src/views/Library.vue` — 1 section wired; remove dead `liked` block
+
+**Unchanged:**
+- Backend (already supports `?platform=qq`)
+- All other web pages
+
+---
+
+## Task 1: Build the SourceTabs component
+
+**Files:**
+- Create: `web/src/components/SourceTabs.vue`
+
+This task is fully independent of store changes — the component is presentational, takes typed props, and emits an update event. It can land and be committed alone (build will pass; component is just unused until later tasks).
+
+- [ ] **Step 1.1: Create the component file**
+
+Write `web/src/components/SourceTabs.vue`:
+
+```vue
+<template>
+  <div v-if="sources.length >= 2" class="source-tabs">
+    <button
+      v-for="src in sources"
+      :key="src"
+      type="button"
+      class="source-tab"
+      :class="{ active: src === modelValue }"
+      @click="$emit('update:modelValue', src)"
+    >
+      {{ LABELS[src] }}
+    </button>
+  </div>
+</template>
+
+<script setup lang="ts">
+type Source = 'netease' | 'qq';
+
+const LABELS: Record<Source, string> = {
+  netease: '网易云',
+  qq: 'QQ',
+};
+
+defineProps<{
+  modelValue: Source;
+  sources: Source[];
+}>();
+
+defineEmits<{
+  'update:modelValue': [value: Source];
+}>();
+</script>
+
+<style lang="scss" scoped>
+.source-tabs {
+  display: inline-flex;
+  gap: 4px;
+  margin-left: 12px;
+  align-items: center;
+}
+
+.source-tab {
+  padding: 4px 10px;
+  min-height: 28px;
+  font-size: var(--fs-sm);
+  font-weight: var(--fw-medium);
+  color: var(--text-secondary);
+  background: transparent;
+  border: none;
+  border-radius: var(--radius-sm);
+  cursor: pointer;
+  transition: color var(--transition-fast), background var(--transition-fast);
+
+  &:hover {
+    color: var(--text-primary);
+    background: var(--hover-bg);
+  }
+
+  &.active {
+    color: var(--color-primary);
+    background: var(--color-primary-12);
+    font-weight: var(--fw-semi);
+  }
+}
+
+@media (max-width: 768px) {
+  .source-tabs {
+    margin-left: 8px;
+    gap: 2px;
+  }
+
+  .source-tab {
+    padding: 6px 10px;
+    min-height: 36px; // larger touch target on mobile
+    font-size: var(--fs-xs);
+  }
+}
+</style>
+```
+
+Why these choices:
+- `v-if="sources.length >= 2"` — auto-hide when only one source available; parent doesn't need wrapper logic
+- Min-height 28px desktop / 36px mobile — comfortable touch on phones
+- `--color-primary-12` (12% primary tint) — matches existing active-state pattern in the codebase
+- No `--brand-netease/qq` in active state — keeps tab visually consistent regardless of which platform; brand colors are reserved for SongCard platform badges where they identify content origin
+
+- [ ] **Step 1.2: Verify it imports cleanly via type check**
+
+Run from project root:
+
+```
+npx tsc --noEmit
+```
+
+Expected: exit code 0, no output.
+
+Then verify the web project also type-checks:
+
+```
+cd web && npx vue-tsc --noEmit && cd ..
+```
+
+Expected: exit code 0, no output.
+
+- [ ] **Step 1.3: Commit**
+
+```
+git add web/src/components/SourceTabs.vue
+git commit -m "feat(web): add SourceTabs component for platform switcher
+
+Presentational component for switching between netease and qq music
+sources. Auto-hides when fewer than 2 sources are passed in. Mobile
+breakpoint enlarges touch target to 36px.
+
+Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>"
+```
+
+---
+
+## Task 2: Refactor the store (state + fetchHomeData)
+
+**Files:**
+- Modify: `web/src/stores/player.ts`
+
+This task changes types, which will break Home.vue and Library.vue at compile time. **Do not run tsc/build between Task 2 and Task 4** — they are migrated in a single coherent commit. After Task 4, type-check confirms the whole change.
+
+- [ ] **Step 2.1: Add the `Source` type alias and update state shape**
+
+In `web/src/stores/player.ts`, locate the `state: () => ({ ... })` block (around line 47-63).
+
+**Find:**
+
+```ts
+    // Home page cache
+    recommendPlaylists: [] as PlaylistItem[],
+    dailySongs: [] as Song[],
+    userPlaylists: [] as PlaylistItem[],
+    bilibiliPopular: [] as Song[],
+    lastFetchTime: 0,
+```
+
+**Replace with:**
+
+```ts
+    // Home page cache, split by source
+    recommendPlaylists: { netease: [] as PlaylistItem[], qq: [] as PlaylistItem[] },
+    dailySongs:         { netease: [] as Song[],         qq: [] as Song[] },
+    userPlaylists:      { netease: [] as PlaylistItem[], qq: [] as PlaylistItem[] },
+    bilibiliPopular: [] as Song[],
+    authStatus: { netease: false, qq: false },
+    lastFetchTime: 0,
+```
+
+Also add this exported type at the top of the file, right after the existing `Song` interface (around line 12):
+
+```ts
+export type Source = 'netease' | 'qq';
+```
+
+- [ ] **Step 2.2: Rewrite `fetchHomeData()`**
+
+In the same file, find the `fetchHomeData` action (around line 352-378).
+
+**Replace the entire action body with:**
+
+```ts
+    async fetchHomeData() {
+      if (this.lastFetchTime > 0 && Date.now() - this.lastFetchTime < HOME_CACHE_TTL) {
+        return;
+      }
+
+      // 1. Fetch auth status for both platforms first.
+      const [neAuthRes, qqAuthRes] = await Promise.allSettled([
+        axios.get('/api/auth/status', { params: { platform: 'netease' } }),
+        axios.get('/api/auth/status', { params: { platform: 'qq' } }),
+      ]);
+      this.authStatus.netease =
+        neAuthRes.status === 'fulfilled' && !!neAuthRes.value.data?.loggedIn;
+      this.authStatus.qq =
+        qqAuthRes.status === 'fulfilled' && !!qqAuthRes.value.data?.loggedIn;
+
+      // 2. NetEase data: recommend playlists work anonymously; daily/user
+      // playlists need login but Promise.allSettled isolates failures.
+      const neteasePromises = [
+        axios.get('/api/music/recommend/playlists', { params: { platform: 'netease' } }),
+        axios.get('/api/music/recommend/songs',     { params: { platform: 'netease' } }),
+        axios.get('/api/music/user/playlists',      { params: { platform: 'netease' } }),
+      ];
+
+      // 3. QQ data: only fetch when QQ is logged in. When not logged in,
+      // resolve to empty payloads so the same indexed handling works.
+      const emptyPlaylists = { data: { playlists: [] } };
+      const emptySongs     = { data: { songs: [] } };
+      const qqPromises = this.authStatus.qq
+        ? [
+            axios.get('/api/music/recommend/playlists', { params: { platform: 'qq' } }),
+            axios.get('/api/music/recommend/songs',     { params: { platform: 'qq' } }),
+            axios.get('/api/music/user/playlists',      { params: { platform: 'qq' } }),
+          ]
+        : [
+            Promise.resolve(emptyPlaylists),
+            Promise.resolve(emptySongs),
+            Promise.resolve(emptyPlaylists),
+          ];
+
+      const biliPromise = axios.get('/api/music/bilibili/popular?limit=12');
+
+      const results = await Promise.allSettled([
+        ...neteasePromises,
+        ...qqPromises,
+        biliPromise,
+      ]);
+
+      const [neRecPL, neDaily, neUserPL, qqRecPL, qqDaily, qqUserPL, bili] = results;
+
+      if (neRecPL.status === 'fulfilled') {
+        this.recommendPlaylists.netease = neRecPL.value.data.playlists ?? [];
+      }
+      if (neDaily.status === 'fulfilled') {
+        this.dailySongs.netease = neDaily.value.data.songs ?? [];
+      }
+      if (neUserPL.status === 'fulfilled') {
+        this.userPlaylists.netease = neUserPL.value.data.playlists ?? [];
+      }
+      if (qqRecPL.status === 'fulfilled') {
+        this.recommendPlaylists.qq = qqRecPL.value.data.playlists ?? [];
+      }
+      if (qqDaily.status === 'fulfilled') {
+        this.dailySongs.qq = qqDaily.value.data.songs ?? [];
+      }
+      if (qqUserPL.status === 'fulfilled') {
+        this.userPlaylists.qq = qqUserPL.value.data.playlists ?? [];
+      }
+      if (bili.status === 'fulfilled') {
+        this.bilibiliPopular = bili.value.data.songs ?? [];
+      }
+
+      this.lastFetchTime = Date.now();
+    },
+```
+
+**Do NOT type-check yet** — Home/Library still reference the old shape. They'll be migrated in Tasks 3 and 4.
+
+---
+
+## Task 3: Migrate Home.vue to multi-source tabs
+
+**Files:**
+- Modify: `web/src/views/Home.vue`
+
+- [ ] **Step 3.1: Add a localStorage helper module**
+
+Create `web/src/stores/sourceTabs.ts`:
+
+```ts
+import type { Source } from './player.js';
+
+const STORAGE_KEY = 'source-tabs';
+
+export type TabKey =
+  | 'home.recommend'
+  | 'home.daily'
+  | 'home.user'
+  | 'library.user';
+
+function readAll(): Partial<Record<TabKey, Source>> {
+  try {
+    const raw = localStorage.getItem(STORAGE_KEY);
+    if (!raw) return {};
+    const parsed = JSON.parse(raw);
+    return typeof parsed === 'object' && parsed !== null ? parsed : {};
+  } catch {
+    return {};
+  }
+}
+
+export function loadTabSource(key: TabKey, fallback: Source = 'netease'): Source {
+  const all = readAll();
+  const v = all[key];
+  return v === 'netease' || v === 'qq' ? v : fallback;
+}
+
+export function saveTabSource(key: TabKey, value: Source): void {
+  try {
+    const all = readAll();
+    all[key] = value;
+    localStorage.setItem(STORAGE_KEY, JSON.stringify(all));
+  } catch {
+    // localStorage may be unavailable (private browsing); silently no-op
+  }
+}
+```
+
+This is a separate file rather than inline so Library can reuse it without duplication.
+
+- [ ] **Step 3.2: Update Home.vue template**
+
+Replace the three `<section>` blocks (推荐歌单 / 每日推荐 / 我的歌单) and the `<script setup>` block.
+
+**Find** the entire `<template>` 推荐歌单 section (currently around lines 53-67):
+
+```vue
+    <!-- 推荐歌单 -->
+    <section class="section" v-if="store.recommendPlaylists.length > 0">
+      <h2 class="section-title">推荐歌单</h2>
+      <div class="playlist-grid">
+        <RouterLink
+          v-for="playlist in store.recommendPlaylists"
+          :key="playlist.id"
+          :to="`/playlist/${playlist.id}?platform=${playlist.platform}`"
+          class="playlist-card hover-scale"
+        >
+          <CoverArt :url="playlist.coverUrl" :size="160" :radius="10" :show-shadow="true" />
+          <div class="playlist-name">{{ playlist.name }}</div>
+        </RouterLink>
+      </div>
+    </section>
+```
+
+**Replace with:**
+
+```vue
+    <!-- 推荐歌单 -->
+    <section class="section" v-if="recommendAvailable.length > 0">
+      <h2 class="section-title">
+        推荐歌单
+        <SourceTabs v-model="recommendSource" :sources="recommendAvailable" />
+      </h2>
+      <div class="playlist-grid">
+        <RouterLink
+          v-for="playlist in (store.recommendPlaylists[recommendSourceSafe] ?? [])"
+          :key="playlist.id"
+          :to="`/playlist/${playlist.id}?platform=${playlist.platform}`"
+          class="playlist-card hover-scale"
+        >
+          <CoverArt :url="playlist.coverUrl" :size="160" :radius="10" :show-shadow="true" />
+          <div class="playlist-name">{{ playlist.name }}</div>
+        </RouterLink>
+      </div>
+    </section>
+```
+
+**Find** the 每日推荐 section (currently around lines 36-51):
+
+```vue
+    <!-- 每日推荐 -->
+    <section class="section" v-if="store.dailySongs.length > 0">
+      <h2 class="section-title">每日推荐</h2>
+      <div class="daily-grid">
+        <div
+          v-for="song in store.dailySongs.slice(0, 12)"
+          :key="song.id"
+          class="daily-card hover-scale"
+          @click="store.playSong(song)"
+        >
+          <CoverArt :url="song.coverUrl" :size="120" :radius="10" :show-shadow="true" />
+          <div class="daily-name">{{ song.name }}</div>
+          <div class="daily-artist">{{ song.artist }}</div>
+        </div>
+      </div>
+    </section>
+```
+
+**Replace with:**
+
+```vue
+    <!-- 每日推荐 -->
+    <section class="section" v-if="dailyAvailable.length > 0">
+      <h2 class="section-title">
+        每日推荐
+        <SourceTabs v-model="dailySource" :sources="dailyAvailable" />
+      </h2>
+      <div class="daily-grid">
+        <div
+          v-for="song in (store.dailySongs[dailySourceSafe] ?? []).slice(0, 12)"
+          :key="song.id"
+          class="daily-card hover-scale"
+          @click="store.playSong(song)"
+        >
+          <CoverArt :url="song.coverUrl" :size="120" :radius="10" :show-shadow="true" />
+          <div class="daily-name">{{ song.name }}</div>
+          <div class="daily-artist">{{ song.artist }}</div>
+        </div>
+      </div>
+    </section>
+```
+
+**Find** the 我的歌单 section (currently around lines 69-95):
+
+```vue
+    <!-- 我的歌单 -->
+    <section class="section" v-if="store.userPlaylists.length > 0">
+      <h2 class="section-title">
+        我的歌单
+        <span class="section-count">{{ store.userPlaylists.length }}</span>
+      </h2>
+      <div class="playlist-grid">
+        <RouterLink
+          v-for="pl in visibleUserPlaylists"
+          :key="pl.id"
+          :to="`/playlist/${pl.id}?platform=${pl.platform}`"
+          class="playlist-card hover-scale"
+        >
+          <CoverArt :url="pl.coverUrl" :size="160" :radius="10" :show-shadow="true" />
+          <div class="playlist-name">{{ pl.name }}</div>
+          <div class="playlist-count">{{ pl.songCount }} 首</div>
+        </RouterLink>
+      </div>
+      <button
+        v-if="store.userPlaylists.length > USER_PLAYLIST_LIMIT"
+        class="expand-btn"
+        @click="userPlaylistsExpanded = !userPlaylistsExpanded"
+      >
+        <Icon :icon="userPlaylistsExpanded ? 'mdi:chevron-up' : 'mdi:chevron-down'" />
+        {{ userPlaylistsExpanded ? '收起' : `展开全部 ${store.userPlaylists.length} 个歌单` }}
+      </button>
+    </section>
+```
+
+**Replace with:**
+
+```vue
+    <!-- 我的歌单 -->
+    <section class="section" v-if="userAvailable.length > 0">
+      <h2 class="section-title">
+        我的歌单
+        <span class="section-count">{{ currentUserPlaylists.length }}</span>
+        <SourceTabs v-model="userSource" :sources="userAvailable" />
+      </h2>
+      <div class="playlist-grid">
+        <RouterLink
+          v-for="pl in visibleUserPlaylists"
+          :key="pl.id"
+          :to="`/playlist/${pl.id}?platform=${pl.platform}`"
+          class="playlist-card hover-scale"
+        >
+          <CoverArt :url="pl.coverUrl" :size="160" :radius="10" :show-shadow="true" />
+          <div class="playlist-name">{{ pl.name }}</div>
+          <div class="playlist-count">{{ pl.songCount }} 首</div>
+        </RouterLink>
+      </div>
+      <button
+        v-if="currentUserPlaylists.length > USER_PLAYLIST_LIMIT"
+        class="expand-btn"
+        @click="userPlaylistsExpanded = !userPlaylistsExpanded"
+      >
+        <Icon :icon="userPlaylistsExpanded ? 'mdi:chevron-up' : 'mdi:chevron-down'" />
+        {{ userPlaylistsExpanded ? '收起' : `展开全部 ${currentUserPlaylists.length} 个歌单` }}
+      </button>
+    </section>
+```
+
+- [ ] **Step 3.3: Update Home.vue `<script setup>`**
+
+**Find** the `<script setup lang="ts">` block (currently around lines 119-153):
+
+```ts
+<script setup lang="ts">
+import { ref, computed, onMounted } from 'vue';
+import { Icon } from '@iconify/vue';
+import axios from 'axios';
+import { usePlayerStore, type Song } from '../stores/player.js';
+import CoverArt from '../components/CoverArt.vue';
+
+const store = usePlayerStore();
+const USER_PLAYLIST_LIMIT = 20;
+const userPlaylistsExpanded = ref(false);
+const visibleUserPlaylists = computed(() =>
+  userPlaylistsExpanded.value
+    ? store.userPlaylists
+    : store.userPlaylists.slice(0, USER_PLAYLIST_LIMIT)
+);
+
+async function playFm() {
+  try {
+    const res = await axios.get('/api/music/personal/fm');
+    const songs: Song[] = res.data.songs;
+    if (songs.length > 0) {
+      await store.play(songs[0].name, songs[0].platform);
+      for (let i = 1; i < songs.length; i++) {
+        await store.addToQueue(songs[i].name, songs[i].platform);
+      }
+    }
+  } catch {
+    // Ignore
+  }
+}
+
+onMounted(() => {
+  store.fetchHomeData();
+});
+</script>
+```
+
+**Replace with:**
+
+```ts
+<script setup lang="ts">
+import { ref, computed, watch, onMounted } from 'vue';
+import { Icon } from '@iconify/vue';
+import axios from 'axios';
+import { usePlayerStore, type Song, type Source } from '../stores/player.js';
+import { loadTabSource, saveTabSource } from '../stores/sourceTabs.js';
+import CoverArt from '../components/CoverArt.vue';
+import SourceTabs from '../components/SourceTabs.vue';
+
+const store = usePlayerStore();
+const USER_PLAYLIST_LIMIT = 20;
+const userPlaylistsExpanded = ref(false);
+
+// Available sources per section. Recommend playlists are public for both
+// platforms — netease always; qq only when logged in. Daily and user
+// playlists need login on both sides.
+const recommendAvailable = computed<Source[]>(() => {
+  const s: Source[] = ['netease'];
+  if (store.authStatus.qq) s.push('qq');
+  return s;
+});
+const dailyAvailable = computed<Source[]>(() => {
+  const s: Source[] = [];
+  if (store.authStatus.netease) s.push('netease');
+  if (store.authStatus.qq) s.push('qq');
+  return s;
+});
+const userAvailable = computed<Source[]>(() => {
+  const s: Source[] = [];
+  if (store.authStatus.netease) s.push('netease');
+  if (store.authStatus.qq) s.push('qq');
+  return s;
+});
+
+// Persisted active source per section.
+const recommendSource = ref<Source>(loadTabSource('home.recommend'));
+const dailySource     = ref<Source>(loadTabSource('home.daily'));
+const userSource      = ref<Source>(loadTabSource('home.user'));
+
+watch(recommendSource, (v) => saveTabSource('home.recommend', v));
+watch(dailySource,     (v) => saveTabSource('home.daily',     v));
+watch(userSource,      (v) => saveTabSource('home.user',      v));
+
+// Fallback when persisted source is no longer available (e.g. user logged
+// out of QQ since last visit). We render against `*Safe` but never write
+// back, so the user's preference is preserved for when they log in again.
+const recommendSourceSafe = computed<Source>(() =>
+  recommendAvailable.value.includes(recommendSource.value)
+    ? recommendSource.value
+    : recommendAvailable.value[0] ?? 'netease'
+);
+const dailySourceSafe = computed<Source>(() =>
+  dailyAvailable.value.includes(dailySource.value)
+    ? dailySource.value
+    : dailyAvailable.value[0] ?? 'netease'
+);
+const userSourceSafe = computed<Source>(() =>
+  userAvailable.value.includes(userSource.value)
+    ? userSource.value
+    : userAvailable.value[0] ?? 'netease'
+);
+
+const currentUserPlaylists = computed(() => store.userPlaylists[userSourceSafe.value] ?? []);
+const visibleUserPlaylists = computed(() =>
+  userPlaylistsExpanded.value
+    ? currentUserPlaylists.value
+    : currentUserPlaylists.value.slice(0, USER_PLAYLIST_LIMIT)
+);
+
+async function playFm() {
+  try {
+    const res = await axios.get('/api/music/personal/fm');
+    const songs: Song[] = res.data.songs;
+    if (songs.length > 0) {
+      await store.play(songs[0].name, songs[0].platform);
+      for (let i = 1; i < songs.length; i++) {
+        await store.addToQueue(songs[i].name, songs[i].platform);
+      }
+    }
+  } catch {
+    // Ignore
+  }
+}
+
+onMounted(() => {
+  store.fetchHomeData();
+});
+</script>
+```
+
+Note: The 我的歌单 template uses `userSource` (not `userSourceSafe`) on the `<SourceTabs>` v-model so the user's click maps directly to the persisted ref. The grid below the tabs uses `currentUserPlaylists` which derives from `userSourceSafe`, so even if `userSource` points at an unavailable platform momentarily, the grid still renders something sensible. Same pattern for 推荐歌单 / 每日推荐.
+
+---
+
+## Task 4: Migrate Library.vue and remove dead code
+
+**Files:**
+- Modify: `web/src/views/Library.vue`
+
+- [ ] **Step 4.1: Replace the template**
+
+**Find** the `<template>` block (currently lines 1-64) and **replace the entire template with:**
+
+```vue
+<template>
+  <div class="library-page">
+    <h1 class="page-title">音乐库</h1>
+
+    <!-- 我的歌单 -->
+    <section class="section" v-if="userAvailable.length > 0">
+      <h2 class="section-title">
+        我的歌单
+        <span class="section-count">{{ currentUserPlaylists.length }}</span>
+        <SourceTabs v-model="userSource" :sources="userAvailable" />
+      </h2>
+      <div class="playlist-grid">
+        <RouterLink
+          v-for="pl in currentUserPlaylists"
+          :key="pl.id"
+          :to="`/playlist/${pl.id}?platform=${pl.platform}`"
+          class="playlist-card hover-scale"
+        >
+          <CoverArt :url="pl.coverUrl" :size="160" :radius="10" :show-shadow="true" />
+          <div class="playlist-name">{{ pl.name }}</div>
+          <div class="playlist-count">{{ pl.songCount }} 首</div>
+        </RouterLink>
+      </div>
+    </section>
+
+    <!-- 最近播放 -->
+    <section class="section">
+      <h2 class="section-title">最近播放</h2>
+      <div v-if="historyLoading" class="loading">加载中...</div>
+      <div v-else-if="history.length === 0" class="empty">暂无播放记录</div>
+      <div v-else class="song-list">
+        <SongCard
+          v-for="(song, i) in history.slice(0, 10)"
+          :key="`hist-${song.id}-${i}`"
+          :song="song"
+          :index="i + 1"
+          :active="store.currentSong?.id === song.id"
+          @play="store.play(song.name, song.platform)"
+          @add="store.addToQueue(song.name, song.platform)"
+        />
+      </div>
+    </section>
+
+    <div v-if="!historyLoading && userAvailable.length === 0 && history.length === 0" class="empty-state">
+      <Icon icon="mdi:music-box-outline" class="empty-icon" />
+      <div>登录网易云或QQ音乐后，这里将显示你的歌单和播放记录</div>
+    </div>
+  </div>
+</template>
+```
+
+Changes from the previous version:
+- "我的歌单" section: same data binding pattern as Home (`userAvailable`, `currentUserPlaylists`, `<SourceTabs>`)
+- "我的收藏" section: removed entirely (the `/api/music/user/liked` endpoint never existed)
+- Empty state condition: replaced `liked.length === 0` with `userAvailable.length === 0`
+
+- [ ] **Step 4.2: Replace the script block**
+
+**Find** the `<script setup lang="ts">` block (currently lines 66-105) and **replace with:**
+
+```ts
+<script setup lang="ts">
+import { ref, computed, watch, onMounted } from 'vue';
+import { Icon } from '@iconify/vue';
+import axios from 'axios';
+import { usePlayerStore, type Song, type Source } from '../stores/player.js';
+import { loadTabSource, saveTabSource } from '../stores/sourceTabs.js';
+import CoverArt from '../components/CoverArt.vue';
+import SongCard from '../components/SongCard.vue';
+import SourceTabs from '../components/SourceTabs.vue';
+
+const store = usePlayerStore();
+
+const history = ref<Song[]>([]);
+const historyLoading = ref(true);
+
+const userAvailable = computed<Source[]>(() => {
+  const s: Source[] = [];
+  if (store.authStatus.netease) s.push('netease');
+  if (store.authStatus.qq) s.push('qq');
+  return s;
+});
+
+const userSource = ref<Source>(loadTabSource('library.user'));
+watch(userSource, (v) => saveTabSource('library.user', v));
+
+const userSourceSafe = computed<Source>(() =>
+  userAvailable.value.includes(userSource.value)
+    ? userSource.value
+    : userAvailable.value[0] ?? 'netease'
+);
+
+const currentUserPlaylists = computed(() => store.userPlaylists[userSourceSafe.value] ?? []);
+
+onMounted(async () => {
+  if (!store.activeBotId) {
+    await store.fetchBots();
+  }
+
+  store.fetchHomeData();
+
+  if (store.activeBotId) {
+    try {
+      const res = await axios.get(`/api/player/${store.activeBotId}/history`);
+      history.value = res.data.history ?? [];
+    } catch {
+      // API may not be ready
+    }
+  }
+
+  historyLoading.value = false;
+});
+</script>
+```
+
+Changes:
+- Removed `liked` ref and the `/api/music/user/liked` axios call
+- Added auth-driven `userAvailable`, persisted `userSource`, and `currentUserPlaylists` computed
+- Imports `Source` type and `SourceTabs` component
+
+- [ ] **Step 4.3: Style — `.section-title` already supports inline children**
+
+The existing `.section-title` style (Library.vue and Home.vue both) already uses `display: flex; align-items: center; gap: 8px;`. SourceTabs uses `display: inline-flex` with its own `margin-left`, so it sits inline with the title and count. **No style changes are required in either Home.vue or Library.vue.**
+
+---
+
+## Task 5: Verify the build and types
+
+- [ ] **Step 5.1: Run TypeScript backend type check**
+
+```
+npx tsc --noEmit
+```
+
+Expected: exit code 0, no output. (No backend files were touched.)
+
+- [ ] **Step 5.2: Run web type check + production build**
+
+```
+npm run build:web
+```
+
+Expected: build completes with `✓ built in N.NNs` and no TypeScript errors. The script runs `vue-tsc --noEmit && vite build`, so failures here mean a type or template error in our changes.
+
+- [ ] **Step 5.3: Run the existing test suite to confirm no regression**
+
+```
+npm test
+```
+
+Expected: same baseline as before this feature (`Test Files 2 failed | 26 passed (28)`, `Tests 2 failed | 161 passed (163)`). The 2 pre-existing failures are in `dist/` and `.claude/worktrees/` and are unrelated to our changes — they should remain at exactly 2.
+
+If any **source-tree** test fails (anything not in `dist/` or `.claude/worktrees/`), stop and investigate.
+
+---
+
+## Task 6: Manual smoke test on the dev server
+
+This task verifies behavior the type system can't catch.
+
+- [ ] **Step 6.1: Start the dev server**
+
+```
+npm run dev
+```
+
+Wait for `Web server started` and `WebUI: http://localhost:3000` log lines.
+
+- [ ] **Step 6.2: Test scenario A — only NetEase logged in**
+
+Open http://localhost:3000 in a browser. Confirm:
+
+- 推荐歌单 section displays NetEase playlists, **no tab bar visible** (single source, SourceTabs auto-hidden)
+- 每日推荐 section: visible only if NetEase login provides daily songs; **no tab bar**
+- 我的歌单 section: visible if NetEase has user playlists; **no tab bar**
+- Navigate to `/library`: 我的歌单 section: same — no tab bar, NetEase playlists shown
+
+Open DevTools → Application → Local Storage → `localhost:3000` → `source-tabs` should be absent or `{}` (no clicks happened).
+
+- [ ] **Step 6.3: Test scenario B — both NetEase and QQ logged in**
+
+If QQ is not logged in, log in via Settings → QQ Music → 扫码登录.
+
+Hard reload the browser (Cmd/Ctrl+Shift+R) to bypass the 5-min `lastFetchTime` cache.
+
+Confirm:
+
+- 推荐歌单: tab bar shows `[网易云] [QQ]`, NetEase active by default
+- Click `QQ` — playlist grid switches to QQ data, no flicker (data already in store)
+- Click `网易云` — back to NetEase
+- Same for 每日推荐 and 我的歌单
+- Navigate to `/library`, confirm 我的歌单 has its own tab bar with independent state
+- Reload the page — Home tabs and Library tab persist their last-selected source independently
+
+Check `localStorage['source-tabs']`: should contain JSON with up to 4 keys (`home.recommend`, `home.daily`, `home.user`, `library.user`).
+
+- [ ] **Step 6.4: Test scenario C — fallback when persisted source becomes unavailable**
+
+While logged into both:
+1. On Home, switch 推荐歌单 to `QQ`. Confirm `localStorage['source-tabs']['home.recommend'] === 'qq'`.
+2. Go to Settings → log out of QQ.
+3. Hard-reload Home.
+
+Confirm:
+- 推荐歌单 tab bar disappears (only NetEase available)
+- Grid shows NetEase playlists (graceful fallback via `recommendSourceSafe`)
+- `localStorage['source-tabs']['home.recommend']` is **still `'qq'`** (preference preserved)
+4. Log back into QQ → reload → 推荐歌单 grid is QQ again (preference restored)
+
+- [ ] **Step 6.5: Test mobile layout**
+
+Open DevTools → Toggle device toolbar → set width to 375px (iPhone SE).
+
+Confirm on Home and Library:
+- Section title + tab bar fit on the same line without overflow
+- Tab buttons are at least 36px tall (use Inspect → check computed `min-height`)
+- Tabs are tappable (clicking still switches sources)
+
+- [ ] **Step 6.6: Stop the dev server**
+
+Kill the `npm run dev` process.
+
+---
+
+## Task 7: Final commit
+
+- [ ] **Step 7.1: Stage and commit Task 2 + 3 + 4 changes**
+
+```
+git add web/src/stores/player.ts web/src/stores/sourceTabs.ts web/src/views/Home.vue web/src/views/Library.vue
+git status
+```
+
+Expected `git status` output: 4 modified/new files staged, working tree otherwise clean (apart from pre-existing `.claude/worktrees/` and `test-ts6-version.cjs` untracked).
+
+```
+git commit -m "feat(web): per-platform source tabs on Home and Library
+
+Recommend playlists, daily songs, and user playlists on Home now show
+a [网易云][QQ] tab when both platforms are logged in. Library 我的歌单
+gets the same tab. Selection persists per-section in localStorage and
+falls back gracefully when the persisted source becomes unavailable
+(e.g., user logged out). Removes dead 我的收藏 block from Library that
+referenced a non-existent /api/music/user/liked endpoint.
+
+Spec: docs/superpowers/specs/2026-05-06-music-source-tabs-design.md
+
+Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>"
+```
+
+- [ ] **Step 7.2: Verify commit landed**
+
+```
+git log --oneline -3
+```
+
+Expected:
+```
+<sha> feat(web): per-platform source tabs on Home and Library
+<sha> feat(web): add SourceTabs component for platform switcher
+<sha> docs: spec for multi-source tabs on Home and Library
+```
+
+---
+
+## Done
+
+The branch should now have 3 new commits on top of the merge commit, all green builds and tests, and the feature working in dev mode.
@@ -0,0 +1,124 @@
+# Bot Profile Manager — Design Spec
+
+## Goal
+
+When the bot plays a song, automatically update its TeamSpeak presence (avatar, description, nickname, away status, channel description) and send a "now playing" chat message. When playback stops, restore all values to defaults. Each feature is independently configurable and permission-safe — if the bot lacks a required server permission, that feature silently disables itself until the next reconnect.
+
+## Features
+
+| # | Feature | Update on song | Restore on stop | TS3 mechanism | TS6 mechanism |
+|---|---------|---------------|-----------------|---------------|---------------|
+| 1 | Avatar | Album cover art | Delete avatar | File transfer upload + `clientupdate client_flag_avatar=<md5>` | Same (file transfer is protocol-level) |
+| 2 | Description | `歌名 - 歌手 [专辑]` | Clear (empty string) | `clientupdate client_description=...` | `httpQuery.clientUpdate(...)` |
+| 3 | Nickname | `♪ 歌名 - 歌手 \| 原昵称` (max 30 chars) | Restore `defaultNickname` | `clientupdate client_nickname=...` | `httpQuery.clientUpdate(...)` |
+| 4 | Away status | `client_away=1`, message = `正在播放: 歌名 - 歌手` | `client_away=0` | `clientupdate client_away=...` | `httpQuery.clientUpdate(...)` |
+| 5 | Channel description | `正在播放: 歌名 - 歌手\n专辑: xxx\n平台: xxx` | Clear | `channeledit cid=... channel_description=...` | `httpQuery.request("POST", "/1/channeledit", ...)` |
+| 6 | Now-playing message | `♪ 正在播放: 歌名 - 歌手 [专辑]` | (not sent on stop) | `sendTextMessage` (existing) | `sendTextMessage` (existing) |
+
+## Architecture
+
+```
+resolveAndPlay() success / stop / clear / playNext exhausted
+    ↓
+BotInstance → BotProfileManager.onSongChange(song | null)
+                 ├─ updateAvatar(coverUrl | null)       [fire-and-forget]
+                 ├─ updateDescription(song | null)
+                 ├─ updateNickname(song | null)
+                 ├─ updateAwayStatus(song | null)
+                 ├─ updateChannelDescription(song | null)
+                 └─ sendNowPlayingMessage(song)          [only when song != null]
+
+BotInstance.connect()  → profileManager.onConnect()   // reset perm flags, restore defaults
+BotInstance.disconnect() → (no action needed, server cleans up)
+```
+
+## File Changes
+
+| File | Change |
+|------|--------|
+| `src/bot/profile.ts` | **New** — `BotProfileManager` class |
+| `src/ts-protocol/client.ts` | Add `execCommand`, `execCommandWithResponse`, file transfer methods, `escapeTS3()` |
+| `src/bot/instance.ts` | Create & hold `BotProfileManager`, call at lifecycle points |
+| `src/data/database.ts` | Add 6 profile config columns via ALTER TABLE migration |
+| `src/web/api/player.ts` | Add `GET/PUT /api/player/:botId/profile` endpoints |
+
+## TS3Client Layer Extensions
+
+New methods on `TS3Client` (all delegate to underlying `@honeybbq/teamspeak-client` Client):
+
+```typescript
+execCommand(cmd: string): Promise<void>
+execCommandWithResponse(cmd: string): Promise<Record<string, string>[]>
+fileTransferInitUpload(channelID: bigint, path: string, password: string,
+                       size: bigint, overwrite?: boolean): Promise<FileUploadInfo>
+uploadFileData(host: string, info: FileUploadInfo, data: Readable): Promise<void>
+fileTransferDeleteFile(channelID: bigint, paths: string[]): Promise<void>
+```
+
+Utility: `escapeTS3(str: string): string` — escapes spaces (`\s`), backslashes (`\\`), pipes (`\p`), slashes (`\/`).
+
+## BotProfileManager Detail
+
+```typescript
+interface ProfileConfig {
+  avatarEnabled: boolean;        // default true
+  descriptionEnabled: boolean;   // default true
+  nicknameEnabled: boolean;      // default true
+  awayStatusEnabled: boolean;    // default true
+  channelDescEnabled: boolean;   // default true
+  nowPlayingMsgEnabled: boolean; // default true
+}
+```
+
+### Permission Handling
+
+- Each feature has an independent `permDenied: boolean` flag.
+- On first failure where error message contains "permission" or "insufficient" → set flag, skip subsequent calls.
+- On `onConnect()` → reset all flags (new connection may have different permissions).
+- Non-permission errors (network timeout, etc.) do NOT set the flag — next song change will retry.
+
+### Nickname Truncation
+
+- Format: `♪ {songInfo} | {defaultNickname}`
+- TS3 max nickname: 30 characters
+- If total > 30: truncate songInfo, keep defaultNickname
+- If `♪  | {defaultNickname}` alone > 30: skip nickname update entirely
+
+### Avatar Upload Flow (TS3)
+
+1. Download cover image via axios (HTTP GET coverUrl) → Buffer
+2. `fileTransferInitUpload(0n, "/avatar", "", BigInt(buffer.length), true)`
+3. `uploadFileData(host, info, Readable.from(buffer))`
+4. Compute MD5: `crypto.createHash('md5').update(buffer).digest('hex')`
+5. `execCommand("clientupdate client_flag_avatar=" + md5)`
+
+To clear: `fileTransferDeleteFile(0n, ["/avatar"])` + `execCommand("clientupdate client_flag_avatar=")`
+
+### Fire-and-Forget
+
+Avatar download/upload is slow. `onSongChange()` launches all updates concurrently via `Promise.allSettled()` — failures are logged but never block playback.
+
+## Database Migration
+
+```sql
+ALTER TABLE bot_instances ADD COLUMN profile_avatar_enabled INTEGER DEFAULT 1;
+ALTER TABLE bot_instances ADD COLUMN profile_description_enabled INTEGER DEFAULT 1;
+ALTER TABLE bot_instances ADD COLUMN profile_nickname_enabled INTEGER DEFAULT 1;
+ALTER TABLE bot_instances ADD COLUMN profile_away_enabled INTEGER DEFAULT 1;
+ALTER TABLE bot_instances ADD COLUMN profile_channel_desc_enabled INTEGER DEFAULT 1;
+ALTER TABLE bot_instances ADD COLUMN profile_now_playing_enabled INTEGER DEFAULT 1;
+```
+
+## Web API
+
+```
+GET  /api/player/:botId/profile  → { avatarEnabled, descriptionEnabled, ... }
+PUT  /api/player/:botId/profile  → body: Partial<ProfileConfig> → 200 OK
+```
+
+## Constraints
+
+- All profile operations are async, never block playback
+- Uses existing `axios` dependency for image download
+- MD5 via Node.js built-in `crypto`
+- No new npm dependencies required
@@ -0,0 +1,125 @@
+# Design: FM Bug Fix + Artist Loop + Playlist Fuzzy Search
+
+Date: 2026-04-27
+
+## Overview
+
+Three features for the TeamSpeak Music Bot:
+1. New `!artist <name>` command — loop playback filtered by artist
+2. Fuzzy playlist name search in existing `!playlist` command
+3. Fix `!fm` audio dropout bug (no sound after a few songs but status shows playing)
+
+---
+
+## Feature 1: `!artist` Command
+
+### Behavior
+
+`!artist <歌手名> [-q|-b|-y]` searches for songs by the artist, loads them into the queue, sets the queue mode to `Loop`, and starts playing.
+
+### Flow
+
+1. Parse command with optional platform flags (`-q`, `-b`, `-y`)
+2. Call `provider.search(歌手名, 50)` to get up to 50 results
+3. Filter results: only keep songs where `song.artist` contains the search query (case-insensitive)
+4. If filtered list is empty, fall back to unfiltered search results (up to 20)
+5. Clear current queue, add filtered songs, set mode to `Loop`
+6. Play first song via `resolveAndPlay`
+
+### Key Decisions
+
+- **Why Loop mode?** The user said "循环播放" (loop playback). After the artist's songs are exhausted, they should restart.
+- **Why filter client-side?** The search API doesn't support artist-only filtering. We search broadly then narrow down.
+- **Why 50 results?** The default limit is 20, but for prolific artists we want more coverage. 50 balances API response size with coverage.
+
+### Files Changed
+
+- `src/bot/commands.ts`: Register `artist` in PUBLIC_COMMANDS, update help text
+- `src/bot/instance.ts`: New `cmdArtist()` method
+
+---
+
+## Feature 2: Playlist Fuzzy Search
+
+### Behavior
+
+`!playlist <name or ID>` now accepts both playlist IDs and playlist names. When the input is not a pure numeric ID, it searches for matching playlists and uses the top result.
+
+### Flow
+
+1. Parse input — if it's a pure numeric ID or contains a URL with an ID, use existing logic
+2. Otherwise, call `provider.search(input)` which already returns `playlists[]` in the result
+3. Also call `provider.getUserPlaylists()` if the provider supports it (logged-in state)
+4. Client-side fuzzy match user playlists: `playlist.name` contains input (case-insensitive)
+5. Merge results: public search results first (sorted by API relevance), then user matches
+6. Take the first playlist, load its songs, play
+
+### Key Decisions
+
+- **Why public search first?** It's already sorted by relevance from the API. User playlists are a secondary source.
+- **Why client-side matching for user playlists?** The `getUserPlaylists()` API returns all user playlists without a search parameter, so we must filter locally.
+- **Backward compatibility:** Numeric IDs and URL parsing are unchanged.
+
+### Files Changed
+
+- `src/bot/instance.ts`: Modify `cmdPlaylist()` to add search fallback
+- `src/bot/commands.ts`: Update help text
+
+---
+
+## Feature 3: FM Bug Fix
+
+### Root Cause Analysis
+
+The `!fm` bug manifests as: audio stops after a few songs, but `!now` shows a playing song and the song name keeps changing.
+
+`getPersonalFm()` returns only ~3 songs per API call. After those are consumed:
+- In `Sequential` mode: `queue.next()` returns null → `player.stop()` is called → playback stops entirely. This does NOT match "歌还在轮播" (songs still rotating).
+- In `Loop` mode (if user changed mode): the same 3 songs loop, but URLs may expire, causing silent playback failures.
+
+The most likely scenario for "no audio but status shows playing + song names changing":
+1. FM songs have URLs that resolve but don't produce playable audio (copyright/region restrictions)
+2. ffmpeg spawns, connects to the URL, gets an HTTP error or silent stream
+3. ffmpeg exits quickly (clean exit or error)
+4. The frame loop detects ffmpeg gone + buffer empty → emits `trackEnd`
+5. `playNext()` advances to the next song
+6. This rapid cycle (spawn → fail → advance) makes it appear that songs are "playing and rotating" but with no audio
+7. After 3 consecutive ffmpeg spawn failures, `consecutiveFailures >= MAX_CONSECUTIVE_FAILURES` → player refuses to spawn new ffmpeg processes
+8. After that, `resolveAndPlay` still sets state via `player.play()` which immediately emits "error" → `playNext()` skips to next → cycle continues with no ffmpeg at all
+
+### Fix Strategy
+
+**Fix 1 — FM auto-refill (primary fix):**
+- In `cmdFm()`, set queue mode to `RandomLoop` so the queue never "runs out"
+- Add a `refillFm()` method that fetches more FM songs and appends to queue
+- Hook into the `trackEnd` flow: when queue has ≤ 2 songs remaining and we're in FM mode, trigger a refill
+- Track FM state with a boolean flag `isFmMode` on the instance
+
+**Fix 2 — Reset consecutive failures on successful playback (safety net):**
+- Reset `consecutiveFailures` when a track plays successfully for at least N frames (e.g., 50 frames = 1 second)
+- This prevents transient URL failures from accumulating toward the hard limit
+
+**Fix 3 — FM refill before queue exhaustion:**
+- After `playNext()` successfully starts a song, check if `isFmMode` and `queue.size() - currentIndex <= 2`
+- If so, fire an async refill (don't block playback)
+
+### Files Changed
+
+- `src/bot/instance.ts`: Modify `cmdFm()`, add `refillFm()`, add FM state tracking, modify `playNext()` to check for FM refill
+- `src/audio/player.ts`: Add `framesPlayed` threshold check to reset `consecutiveFailures`
+
+---
+
+## Implementation Order
+
+1. **FM bug fix** first — it's a bug fix affecting current users
+2. **Playlist fuzzy search** — small change, quick win
+3. **Artist loop** — new feature, depends on queue/player being stable
+
+---
+
+## Testing
+
+- FM: Verify songs keep playing beyond the initial 3-song batch, verify auto-refill works
+- Playlist: Test with numeric ID (backward compat), test with playlist name (fuzzy search)
+- Artist: Test with known artist names, test edge case (no results), test with platform flags
@@ -0,0 +1,189 @@
+# Multi-Source Tabs for Recommend / User Playlists / Daily Songs
+
+**Date:** 2026-05-06
+**Status:** Spec — pending implementation
+
+## Problem
+
+Home 和 Library 页面的"推荐歌单 / 每日推荐 / 我的歌单"这三类内容当前硬编码只走网易云。当用户同时登录了网易云和 QQ 音乐时，无法在 Web UI 上看到 QQ 侧的对应内容、也无法切换查看。
+
+## Goal
+
+在以下 4 个 section 上提供"网易云 / QQ"来源切换 tab，桌面端和移动端均可用：
+
+- `Home.vue` — 推荐歌单
+- `Home.vue` — 每日推荐
+- `Home.vue` — 我的歌单
+- `Library.vue` — 我的歌单
+
+切换为纯前端动作（数据已预先 fetch），无加载闪烁。各 section 的选择独立持久化。
+
+## Out of Scope
+
+- 私人 FM（QQ 无对应概念）
+- B 站热门（独立第三来源，不属于网易/QQ 切换语义）
+- 最近播放（bot 维度的播放历史，与音乐源无关）
+- Library 现有的"我的收藏"段落 —— 当前调用的 `/api/music/user/liked` 端点不存在，是死代码，本次顺手移除
+- 登录状态实时同步（用户在 Settings 登录后需手动刷新 Home/Library 才能看到 QQ tab）
+- Tab 排序、隐藏、拖动等高级配置
+
+## Non-functional Constraints
+
+- 桌面端（>768px）和移动端（≤768px）布局均可用，tab 与 section title 同行排布；空间不足时允许 flex-wrap
+- Tab 触控区域有效高度 ≥36px
+- 现有 5 分钟 home data cache 行为保留
+- 不引入新的后端端点（后端已通过 `?platform=` 参数支持多源）
+
+## Architecture
+
+### 数据层（`web/src/stores/player.ts`）
+
+字段从单平台改为按 platform 切分：
+
+```ts
+// 前
+recommendPlaylists: PlaylistItem[]
+userPlaylists:      PlaylistItem[]
+dailySongs:         Song[]
+
+// 后
+recommendPlaylists: { netease: PlaylistItem[]; qq: PlaylistItem[] }
+userPlaylists:      { netease: PlaylistItem[]; qq: PlaylistItem[] }
+dailySongs:         { netease: Song[];         qq: Song[] }
+
+// 新增
+authStatus: { netease: boolean; qq: boolean }
+```
+
+`fetchHomeData()` 改写：
+
+1. 并发调用 `/api/auth/status?platform=netease` 与 `?platform=qq`，写入 `authStatus`
+2. 网易云的三类数据照常 fetch（推荐歌单匿名可访问；每日推荐和我的歌单需登录，未登录时 API 自然返回空或失败，`Promise.allSettled` 已隔离）
+3. QQ 的三类数据**仅在 QQ 登录时** fetch，未登录则为空数组
+4. B 站热门保持原样
+5. 5 分钟缓存 TTL 不变
+
+### UI 组件
+
+新增 `web/src/components/SourceTabs.vue`：
+
+```vue
+<SourceTabs v-model="activeSource" :sources="availableSources" />
+```
+
+Props：
+- `sources: ('netease' | 'qq')[]` — 由父组件根据 auth 状态过滤后传入
+- `modelValue: 'netease' | 'qq'` — v-model 绑定
+
+行为：
+- `sources.length < 2` 时组件**自身不渲染**（返回空），父组件无需 v-if 包装
+- 文字标签：`{ netease: '网易云', qq: 'QQ' }`
+- 视觉：水平排列，激活态用主色（`var(--color-primary)`）下划线 + 加粗，未激活态使用次要文字色
+- 紧贴 section-title 右侧，使用 `display: inline-flex`，移动端 padding/font-size 缩小
+
+### 各 section 接入模板
+
+```vue
+<section v-if="recommendAvailable.length > 0" class="section">
+  <h2 class="section-title">
+    推荐歌单
+    <SourceTabs v-model="recommendSource" :sources="recommendAvailable" />
+  </h2>
+  <div class="playlist-grid">
+    <RouterLink
+      v-for="pl in store.recommendPlaylists[recommendSource]"
+      :key="pl.id"
+      :to="`/playlist/${pl.id}?platform=${pl.platform}`"
+      class="playlist-card hover-scale"
+    >
+      <CoverArt :url="pl.coverUrl" :size="160" :radius="10" :show-shadow="true" />
+      <div class="playlist-name">{{ pl.name }}</div>
+    </RouterLink>
+  </div>
+</section>
+```
+
+每个 section 在 `<script setup>` 维护两个值：
+
+- `recommendSource: Ref<'netease' | 'qq'>` — 当前选中
+- `recommendAvailable: ComputedRef<('netease' | 'qq')[]>` — 该 section 在当前登录状态下有哪些 source 可选
+
+`recommendAvailable` 计算规则：
+
+| Section | netease 加入条件 | qq 加入条件 |
+|---|---|---|
+| Home 推荐歌单 | 总是（公开数据） | `authStatus.qq` |
+| Home 每日推荐 | `authStatus.netease` | `authStatus.qq` |
+| Home 我的歌单 | `authStatus.netease` | `authStatus.qq` |
+| Library 我的歌单 | `authStatus.netease` | `authStatus.qq` |
+
+#### "我的歌单"展开按钮兼容
+
+Home 的"我的歌单"现有 `USER_PLAYLIST_LIMIT = 20` 折叠/展开。改造后：
+
+```ts
+const visibleUserPlaylists = computed(() => {
+  const all = store.userPlaylists[userSource.value] ?? [];
+  return userPlaylistsExpanded.value ? all : all.slice(0, USER_PLAYLIST_LIMIT);
+});
+```
+
+切换 source 时折叠态保留（不需 reset）。
+
+### 持久化
+
+localStorage 键统一为一个 JSON：
+
+```
+key:   "source-tabs"
+value: {
+  "home.recommend": "qq",
+  "home.daily":     "netease",
+  "home.user":      "qq",
+  "library.user":   "netease"
+}
+```
+
+读：组件 mount 时一次性读 + 解析。
+写：在 v-model 的 setter 里 `watch` 一次写回。
+不存在的键 / 解析失败 / 老用户没这个 key —— 默认值 `"netease"`。
+
+### 边界与回退
+
+| 情况 | 行为 |
+|---|---|
+| 选的 source 不在 `available` 里（例：选了 QQ，登出后回到页面） | 渲染时 fallback 到 `available[0]`，不修改 localStorage（保留用户偏好，下次登回来仍生效） |
+| `recommendPlaylists.qq` 为空数组（API 失败 or 无数据） | tab 仍可切，切过去显示空 grid（无错误提示，符合现有"空数据隐藏 section"语义；section 顶层 v-if 检查的是 `available.length > 0`，单 platform 数据为空不影响 section 显隐） |
+| QQ provider 不支持 `getDailyRecommendSongs`（501） | `Promise.allSettled` 已捕获，`dailySongs.qq` 保持 `[]`，等同上一行 |
+| 用户在 Settings 登录 QQ 后切回 Home | 不自动 refetch / 不自动出 tab —— 用户需手动刷新页面（保留 5 分钟缓存语义） |
+| 网易云和 QQ 都没登录 | `available` 为空时 section 隐藏（沿用现有逻辑） |
+| Library "我的收藏" 段落 | 整段移除（含 template、script 中的 `liked` ref、对应 axios 调用） |
+
+## 修改文件清单
+
+新增：
+- `web/src/components/SourceTabs.vue` — 共享 tab 组件
+
+修改：
+- `web/src/stores/player.ts` — 多平台 state、`authStatus`、`fetchHomeData` 重写
+- `web/src/views/Home.vue` — 三个 section 接入 SourceTabs，对应 ref + computed
+- `web/src/views/Library.vue` — 我的歌单接入 SourceTabs；移除我的收藏死代码
+
+不改：
+- 后端（API 已支持 `?platform=`）
+- `Search.vue` / `Playlist.vue` / `Settings.vue` 等其他页面
+
+## 测试方案
+
+- 手动：在两种登录组合下访问 Home 和 Library，验证 tab 显隐、切换、刷新后持久化
+  - 仅网易登录 → 不显示 tab
+  - 两边登录 → 显示 tab，切换后刷新页面来源不变
+  - QQ 登录 → 网易登出 → 网易 tab 消失，若上次选的是网易则 fallback 到 QQ
+- 移动端（DevTools 768px 以下）：tab 与 section-title 同行不溢出，触控区域可点
+- TypeScript 类型检查通过：`npx tsc --noEmit` + `npm run build:web`
+- 单元测试：现有 vitest 套件不应回归（store 改动不破坏其他用法）
+
+## 风险
+
+- store 字段类型变更（数组 → 对象）会影响所有读取这三个字段的地方。需 grep 确认没有遗漏的消费者。
+- localStorage 解析失败的容错必须周全，避免一次脏数据导致整个页面白屏。
@@ -0,0 +1,226 @@
+# History-aware `prev` + "Play Next" Insert
+
+**Date:** 2026-05-06
+**Status:** Spec — pending implementation
+
+## Problem
+
+Two queue/playback gaps surfaced in real use:
+
+1. In `PlayMode.Random` and `PlayMode.RandomLoop`, `!prev` does not play the
+   actually-previously-played song. It just walks `currentIndex - 1` in the
+   underlying array — but in random modes `currentIndex` jumps non-sequentially,
+   so the "previous" array slot has no relationship to play history.
+
+2. `!add` / web "添加到队列" appends to the queue tail. There is no way to
+   say "play this song right after the current one." Users want a "下一首
+   播放" affordance comparable to Spotify "Add to Queue (next up)" or Apple
+   Music "Play Next".
+
+## Goals
+
+- `prev` walks back through the actual play history regardless of mode.
+- A new "Play Next" path inserts a song at `currentIndex + 1`, available
+  via web UI button and TS3 chat command.
+- Both features are usable on desktop and mobile web.
+
+## Out of Scope
+
+- Forward/redo through prev'd songs (user would need to push next manually,
+  which picks a fresh random in random modes — acceptable simplification).
+- Reordering songs already in the queue ("move to next" inside Queue.vue).
+- Persisting play history across bot restarts (in-memory only).
+
+## Non-functional Constraints
+
+- History capped at 50 entries to bound memory.
+- `addNext` must keep `playedIndices` and `history` index references valid
+  after insertion (shift all indices > current by +1).
+- New Toast UX from the previous round still applies (failures surface).
+- TypeScript and existing test suite must not regress.
+
+## Architecture
+
+### A. History-aware `prev`
+
+**`src/audio/queue.ts`** — `PlayQueue` gains a back-stack:
+
+```ts
+private history: number[] = [];
+private static readonly HISTORY_LIMIT = 50;
+
+private pushHistory(idx: number): void {
+  if (idx < 0) return;
+  this.history.push(idx);
+  if (this.history.length > PlayQueue.HISTORY_LIMIT) {
+    this.history.shift();
+  }
+}
+```
+
+Mutators call `pushHistory(this.currentIndex)` **before** changing `currentIndex`:
+
+| Method | History action |
+|---|---|
+| `play()` | `this.history = []` (fresh playback) |
+| `playAt(idx)` | `pushHistory(currentIndex)`, then set `currentIndex = idx` |
+| `next()` | `pushHistory(currentIndex)`, then advance per mode |
+| `prev()` | **Pop** from history → `currentIndex = popped`. If empty, fall back to existing `currentIndex - 1` (which keeps Sequential's wrap behavior; Random returns null). `prev` itself does NOT push to history. |
+| `clear()` | `this.history = []` |
+| `setMode(m)` | `this.history = []` (mode change resets context) |
+| `remove(idx)` | Drop matching entries from history; shift any entry `> idx` by `-1`. Same logic as the existing `playedIndices` rebuild. |
+
+**`prev()` rewrite:**
+
+```ts
+prev(): QueuedSong | null {
+  if (this.songs.length === 0) return null;
+  // History-driven path (preferred when we have one)
+  while (this.history.length > 0) {
+    const idx = this.history.pop()!;
+    if (idx >= 0 && idx < this.songs.length) {
+      this.currentIndex = idx;
+      this.playedIndices.add(idx);
+      return this.songs[idx];
+    }
+    // popped index is stale (song removed) — keep popping
+  }
+  // Fallback: old index-based prev
+  const prevIndex = this.currentIndex - 1;
+  if (prevIndex < 0) {
+    if (this.mode === PlayMode.Sequential) return null;
+    this.currentIndex = this.songs.length - 1;
+  } else {
+    this.currentIndex = prevIndex;
+  }
+  this.playedIndices.add(this.currentIndex);
+  return this.songs[this.currentIndex];
+}
+```
+
+### B. Play Next (insert after current)
+
+**`PlayQueue.addNext(song)`:**
+
+```ts
+addNext(song: QueuedSong): void {
+  if (this.currentIndex < 0 || this.songs.length === 0) {
+    this.songs.push(song);
+    return;
+  }
+  const insertAt = this.currentIndex + 1;
+  this.songs.splice(insertAt, 0, song);
+  // Shift any tracked index > currentIndex by +1
+  const shifted = new Set<number>();
+  for (const i of this.playedIndices) {
+    shifted.add(i > this.currentIndex ? i + 1 : i);
+  }
+  this.playedIndices = shifted;
+  this.history = this.history.map((i) => (i > this.currentIndex ? i + 1 : i));
+}
+```
+
+**Backend endpoint** — `src/web/api/player.ts`:
+
+```
+POST /api/player/:botId/play-next-song
+body: { song: Song }
+```
+
+Behavior:
+- If queue is empty or `currentIndex < 0`: `queue.addNext(song)` (which falls
+  through to plain push), then `queue.play()`, then `resolveAndPlay`. Same
+  semantics as a successful `/play-song` — message: "正在播放：…"
+- Otherwise: `queue.addNext(song)`, no resolveAndPlay. Message: "已加入下一首：…"
+- Returns `{ ok: boolean, message: string }` matching the convention
+  established in the previous round.
+
+**Bot command** — `src/bot/instance.ts`:
+
+Register `!playnext <query>` (alias `!pn`):
+- Mirror of `cmdPlay`'s search step
+- On match: `queue.addNext(song)`. If no current playback, fall through to
+  `resolveAndPlay`.
+- Reply with `已加入下一首：<name>` or `正在播放：<name>` accordingly
+
+**Frontend store action** — `web/src/stores/player.ts`:
+
+```ts
+async playNextSong(song: Song) {
+  if (!this.activeBotId) return;
+  const res = await axios.post(`/api/player/${this.activeBotId}/play-next-song`, { song });
+  if (res.data?.message) {
+    this.notify(res.data.message, res.data.ok === false ? 'error' : 'info');
+  }
+}
+```
+
+**Frontend SongCard** — `web/src/components/SongCard.vue`:
+
+Add a third action button between the existing "play" and "add to queue":
+
+```vue
+<button class="action-btn" @click.stop="$emit('playNext')" title="下一首播放">
+  <Icon icon="mdi:playlist-play" />
+</button>
+```
+
+Add `playNext: []` to `defineEmits`.
+
+**Caller updates** — `Home.vue`, `Library.vue`, `Search.vue`, `History.vue`,
+`Playlist.vue`: each `<SongCard>` usage adds
+`@playNext="store.playNextSong(song)"`.
+
+**Queue.vue** is intentionally **not** updated — clicking "play next" on a
+song already in the queue would create a confusing duplicate.
+
+## Edge Cases
+
+| Case | Behavior |
+|---|---|
+| `prev` with empty history in Sequential mode | Walks `currentIndex - 1`; returns null at index 0 (existing) |
+| `prev` with empty history in Random/RandomLoop | Returns null (no past to recover) |
+| Repeated `prev` past start of history | Pops what's there, then falls back to index walk; eventually null |
+| `addNext` while `currentIndex == -1` (nothing played yet) | Falls through to push; queue.play() will pick it as first |
+| `addNext` while playing and queue size = 1 | Inserts at index 1; current index unchanged; next() will advance to it |
+| `remove` removes a song whose index is in history | Entry dropped; shifted accordingly |
+| Mode switched mid-playback | History cleared (intentional — mode change is a context boundary) |
+| `addNext` then `prev` | Inserted song was never played → not in history; prev pops the previously-played song, NOT the just-inserted one |
+
+## Files Touched
+
+- `src/audio/queue.ts` — history field, `pushHistory`, `addNext`, rewritten `prev`, mutator updates
+- `src/audio/queue.test.ts` (or add if missing) — unit tests for history behavior + addNext shift logic
+- `src/bot/instance.ts` — register `!playnext` / `!pn` command handler
+- `src/web/api/player.ts` — new `/play-next-song` route
+- `web/src/stores/player.ts` — `playNextSong` action
+- `web/src/components/SongCard.vue` — third action button + emit
+- `web/src/views/Home.vue` — wire `@playNext`
+- `web/src/views/Library.vue` — wire `@playNext`
+- `web/src/views/Search.vue` — wire `@playNext`
+- `web/src/views/History.vue` — wire `@playNext`
+- `web/src/views/Playlist.vue` — wire `@playNext`
+
+## Test Plan
+
+**Unit (vitest, `queue.test.ts`):**
+- prev with empty history in Sequential: walks back, null at index 0
+- prev with empty history in Random: returns null
+- next → next → next → prev pops correctly; prev again pops earlier
+- prev after `clear()` returns null (history reset)
+- prev after `setMode()` returns null (history reset)
+- `remove(idx)` drops from history and shifts entries > idx
+- `addNext` while empty: appends
+- `addNext` while playing index 2 in a 5-song queue: ends up at index 3, currentIndex still 2, queue size 6
+- `addNext` then `next()`: plays the inserted song
+- `addNext` shifts existing playedIndices and history correctly
+
+**Integration (manual smoke):**
+- Random mode: play 4 songs, hit `prev` 3 times → walks back through history
+- Click "下一首播放" on a search result → next song after current is the chosen one
+- `!playnext 七里香` → bot replies "已加入下一首：..."; current keeps playing; next song is 七里香
+- `!playnext` while idle → starts playing immediately
+
+**Regression:**
+- Existing 161 source-tree tests still pass.
+- TypeScript `tsc --noEmit` and `npm run build:web` clean.
@@ -8,15 +8,16 @@
    "build": "tsc && npm run build:web",
    "build:web": "cd web && npm run build",
    "start": "node dist/index.js",
+    "play": "node dist/index.js",
    "test": "vitest run",
    "test:watch": "vitest"
  },
  "license": "MIT",
  "dependencies": {
    "@discordjs/opus": "^0.10.0",
-    "@honeybbq/teamspeak-client": "^0.1.0",
+    "@honeybbq/teamspeak-client": "^0.2.1",
    "@koa/router": "^15.4.0",
-    "@sansenjian/qq-music-api": "^2.2.9",
+    "@sansenjian/qq-music-api": "^2.2.10",
    "axios": "^1.14.0",
    "better-sqlite3": "^12.8.0",
    "chalk": "^5.6.2",
@@ -29,7 +30,8 @@
    "pino": "^10.3.1",
    "ts3-nodejs-library": "^3.5.1",
    "tweetnacl": "^1.0.3",
-    "ws": "^8.20.0"
+    "ws": "^8.20.0",
+    "yt-dlp-wrap": "^2.3.12"
  },
  "devDependencies": {
    "@types/better-sqlite3": "^7.6.13",
@@ -25,30 +25,27 @@ RUN cd web && npm ci
 COPY . .
 RUN npm run build

+# Install production dependencies (with native addons compiled) in the builder
+# so we don't need build tools in the production image.
+RUN rm -rf node_modules && npm ci --production && npm cache clean --force
+
 # --- Stage 2: Production image ---
 FROM node:20-slim

-# Install only runtime native build tools (needed for native module rebuild)
+# Install system FFmpeg — the ffmpeg-static npm package bundles a pre-compiled
+# binary that can SIGSEGV inside Docker (incompatible glibc / missing libs).
+# System-installed FFmpeg is always compatible with the container runtime.
 RUN apt-get update && apt-get install -y --no-install-recommends \
-    python3 make g++ && \
+    ffmpeg && \
    rm -rf /var/lib/apt/lists/*

 WORKDIR /app

-# Copy built output
+# Copy built output and pre-compiled production node_modules from builder
 COPY --from=builder /app/dist ./dist
 COPY --from=builder /app/web/dist ./web/dist
 COPY --from=builder /app/package*.json ./
-
-# Install production dependencies (includes ffmpeg-static, opus, sqlite3)
-# These need to compile native addons inside the container
-RUN npm ci --production && npm cache clean --force
-
-# Remove build tools to reduce image size
-RUN apt-get purge -y python3 make g++ && apt-get autoremove -y && \
-    rm -rf /var/lib/apt/lists/*
-
-# FFmpeg is bundled via ffmpeg-static — no system ffmpeg needed
+COPY --from=builder /app/node_modules ./node_modules

 # Data directory for database, cookies, logs
 RUN mkdir -p /app/data
@@ -1,8 +1,8 @@
 # TSMusicBot — Docker Compose
 # 一键部署：docker-compose up -d
 #
-# 所有依赖已内置（Node.js, FFmpeg, Opus 编码器）
-# 无需安装任何额外软件
+# 所有依赖已内置（Node.js, FFmpeg, Opus 编码器）无需安装任何额外软件
+# FFmpeg 使用系统包管理器安装，确保容器内兼容性

 services:
  tsmusicbot:
@@ -6,9 +6,19 @@ echo "║       TSMusicBot Installer           ║"
 echo "╚══════════════════════════════════════╝"
 echo ""

+# Resolve script location → project root
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_DIR="$(cd "$SCRIPT_DIR/.." && pwd)"
 INSTALL_DIR="/opt/tsmusicbot"
 SERVICE_NAME="tsmusicbot"

+# Verify we're in a valid project directory
+if [ ! -f "$PROJECT_DIR/package.json" ]; then
+    echo "Error: Cannot find package.json in $PROJECT_DIR"
+    echo "Please run this script from the TSMusicBot project directory."
+    exit 1
+fi
+
 # Detect OS
 if [ -f /etc/os-release ]; then
    . /etc/os-release
@@ -18,44 +28,57 @@ else
    exit 1
 fi

-echo "[1/5] Installing system dependencies..."
+echo "[1/6] Installing system dependencies..."
 case $OS in
    ubuntu|debian)
        sudo apt-get update -qq
-        sudo apt-get install -y -qq curl ffmpeg
+        sudo apt-get install -y -qq curl build-essential python3
        ;;
    centos|rhel|fedora)
-        sudo yum install -y curl ffmpeg
+        sudo yum install -y curl gcc gcc-c++ make python3
        ;;
    arch|manjaro)
-        sudo pacman -S --noconfirm curl ffmpeg
+        sudo pacman -S --noconfirm curl base-devel python
        ;;
    *)
-        echo "Unsupported OS: $OS. Please install Node.js 20 and FFmpeg manually."
+        echo "Unsupported OS: $OS. Please install Node.js 20, build tools, and FFmpeg manually."
        ;;
 esac

-echo "[2/5] Installing Node.js 20 LTS..."
+echo "[2/6] Installing Node.js 20 LTS..."
 if ! command -v node &> /dev/null || [[ $(node -v | cut -d. -f1 | tr -d 'v') -lt 20 ]]; then
    curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
    sudo apt-get install -y -qq nodejs 2>/dev/null || sudo yum install -y nodejs 2>/dev/null
 fi
 echo "Node.js $(node -v) installed"

-echo "[3/5] Downloading TSMusicBot..."
-sudo mkdir -p "$INSTALL_DIR"
-if [ -d "$(pwd)/dist" ]; then
-    sudo cp -r "$(pwd)"/* "$INSTALL_DIR/"
-else
-    echo "Please run this script from the TSMusicBot source directory after building."
-    exit 1
+echo "[3/6] Installing dependencies..."
+cd "$PROJECT_DIR"
+npm install
+if [ -d "$PROJECT_DIR/web/package.json" ] || [ -f "$PROJECT_DIR/web/package.json" ]; then
+    (cd "$PROJECT_DIR/web" && npm install)
 fi

-echo "[4/5] Installing npm dependencies..."
-cd "$INSTALL_DIR"
-sudo npm install --production
+echo "[4/6] Building project..."
+npm run build

-echo "[5/5] Creating systemd service..."
+echo "[5/6] Copying to $INSTALL_DIR..."
+sudo mkdir -p "$INSTALL_DIR"
+sudo cp -r "$PROJECT_DIR/dist" "$INSTALL_DIR/"
+sudo cp -r "$PROJECT_DIR/node_modules" "$INSTALL_DIR/"
+sudo cp "$PROJECT_DIR/package.json" "$INSTALL_DIR/"
+# Copy web frontend if built
+if [ -d "$PROJECT_DIR/web/dist" ]; then
+    sudo mkdir -p "$INSTALL_DIR/web"
+    sudo cp -r "$PROJECT_DIR/web/dist" "$INSTALL_DIR/web/"
+fi
+# Copy scripts for future use
+sudo mkdir -p "$INSTALL_DIR/scripts"
+sudo cp -r "$PROJECT_DIR/scripts/"* "$INSTALL_DIR/scripts/" 2>/dev/null || true
+# Create data directory
+sudo mkdir -p "$INSTALL_DIR/data"
+
+echo "[6/6] Creating systemd service..."
 sudo tee /etc/systemd/system/${SERVICE_NAME}.service > /dev/null <<EOL
 [Unit]
 Description=TSMusicBot - TeamSpeak Music Bot
@@ -88,4 +111,5 @@ echo "║    Commands:                          ║"
 echo "║    systemctl status tsmusicbot       ║"
 echo "║    systemctl restart tsmusicbot      ║"
 echo "║    systemctl stop tsmusicbot         ║"
+echo "║    journalctl -u tsmusicbot -f       ║"
 echo "╚══════════════════════════════════════╝"
@@ -0,0 +1,212 @@
+"""Open a real Chromium browser at y.qq.com, let the user log in via any
+method (password / QR / QQ connect), then extract the resulting cookie
+set and save it to data/cookies/qq.json. Also tests whether the cookie
+actually unlocks a known VIP track (Jay Chou 稻香) against the local
+QQ Music API before declaring success.
+
+Usage:
+    "C:/Users/saopig1/miniforge3/python.exe" scripts/qq_browser_login.py
+
+Steps:
+    1. A visible Chromium window opens at y.qq.com/n/ryqq/player
+    2. Click the login button in the top right and log in with your
+       real QQ Music account (the one that has VIP)
+    3. The script POLLS cookies in the background and auto-detects
+       successful login by watching for the `uin` cookie to appear
+    4. Once detected, cookies are captured, tested against
+       /getMusicPlay for 稻香, and saved on success
+    5. If VIP still fails, cookies are NOT saved — your existing bot
+       cookie stays untouched
+
+No terminal input required — the script exits on its own when login
+is detected (or after the configured timeout).
+"""
+from __future__ import annotations
+
+import json
+import re
+import time
+from pathlib import Path
+
+import requests
+from playwright.sync_api import sync_playwright
+
+BOT_ROOT = Path(r"C:\Users\saopig1\Music\teamspeak music bot")
+COOKIE_FILE = BOT_ROOT / "data" / "cookies" / "qq.json"
+QQ_API = "http://localhost:3200"
+VIP_TEST_SONGMID = "003aAYrm3GE0Ac"  # 稻香 周杰伦
+
+# How long to wait for the user to finish logging in
+LOGIN_TIMEOUT_S = 300  # 5 minutes
+POLL_INTERVAL_S = 1.0
+# After detecting login, wait a bit for extra cookies (e.g. qqmusic_key)
+SETTLE_DELAY_S = 4.0
+
+
+def qq_cookies(ctx) -> list[dict]:
+    wanted_suffixes = (".qq.com", "y.qq.com", ".music.qq.com")
+    return [
+        c for c in ctx.cookies()
+        if any(c.get("domain", "").endswith(s) or c.get("domain", "") == s.lstrip(".")
+               for s in wanted_suffixes)
+    ]
+
+
+def cookies_to_header(cookies: list[dict]) -> str:
+    return "; ".join(f"{c['name']}={c['value']}" for c in cookies)
+
+
+def cookie_has_uin(cookies: list[dict]) -> str | None:
+    for c in cookies:
+        if c["name"] == "uin" and c["value"]:
+            return c["value"]
+    return None
+
+
+def test_vip_unlock(cookie_header: str) -> tuple[bool, dict]:
+    try:
+        r = requests.get(
+            f"{QQ_API}/getMusicPlay",
+            params={"songmid": VIP_TEST_SONGMID, "cookie": cookie_header},
+            timeout=10,
+            proxies={"http": None, "https": None},
+        )
+        body = r.json()
+        play = body.get("data", {}).get("playUrl", {}).get(VIP_TEST_SONGMID, {})
+        url = play.get("url", "")
+        return (
+            bool(url),
+            {
+                "url_length": len(url),
+                "url_prefix": url[:120] if url else "",
+                "error": play.get("error", ""),
+            },
+        )
+    except Exception as e:
+        return False, {"error": f"request failed: {e}"}
+
+
+def main() -> int:
+    print("[setup] launching visible Chromium — look for the window on your desktop")
+    print("[setup] goto https://y.qq.com/n/ryqq/player")
+    print()
+    print("action required:")
+    print("  1. Click the 登录 button (top-right) in the browser window")
+    print("  2. Log in with your VIP QQ Music account (QR / password / WeChat)")
+    print("  3. Do NOTHING in this terminal — the script detects login itself")
+    print()
+
+    with sync_playwright() as p:
+        browser = p.chromium.launch(headless=False)
+        ctx = browser.new_context(
+            viewport={"width": 1280, "height": 820},
+            user_agent=(
+                "Mozilla/5.0 (Windows NT 10.0; Win64; x64) "
+                "AppleWebKit/537.36 (KHTML, like Gecko) "
+                "Chrome/132.0.0.0 Safari/537.36"
+            ),
+        )
+        page = ctx.new_page()
+        try:
+            page.goto("https://y.qq.com/n/ryqq/player", wait_until="domcontentloaded", timeout=30_000)
+        except Exception as e:
+            print(f"[warn] initial navigation slow: {e}")
+
+        print(f"[wait] polling every {POLL_INTERVAL_S}s for login (timeout {LOGIN_TIMEOUT_S}s)")
+        deadline = time.time() + LOGIN_TIMEOUT_S
+        uin_detected: str | None = None
+        last_report = 0.0
+        while time.time() < deadline:
+            cks = qq_cookies(ctx)
+            uin = cookie_has_uin(cks)
+            if uin:
+                uin_detected = uin
+                print(f"[detect] uin cookie appeared: {uin}")
+                break
+            now = time.time()
+            if now - last_report >= 15:
+                remaining = int(deadline - now)
+                n = len(cks)
+                print(f"[wait] still waiting... {n} qq.com cookies so far, {remaining}s left")
+                last_report = now
+            time.sleep(POLL_INTERVAL_S)
+
+        if not uin_detected:
+            print("[abort] login not detected within timeout")
+            browser.close()
+            return 1
+
+        print(f"[settle] waiting {SETTLE_DELAY_S}s for session cookies to populate")
+        time.sleep(SETTLE_DELAY_S)
+
+        cks = qq_cookies(ctx)
+        cookie_header = cookies_to_header(cks)
+        print(f"[capture] {len(cks)} cookies, {len(cookie_header)} char header")
+
+        qm_key = next((c["value"] for c in cks if c["name"] == "qqmusic_key"), "")
+        qm_keyst = next((c["value"] for c in cks if c["name"] == "qm_keyst"), "")
+        p_skey = next((c["value"] for c in cks if c["name"] == "p_skey"), "")
+        print(f"[capture] qqmusic_key: {'present (' + qm_key[:20] + '...)' if qm_key else '(absent)'}")
+        print(f"[capture] qm_keyst   : {'present (' + qm_keyst[:20] + '...)' if qm_keyst else '(absent)'}")
+        print(f"[capture] p_skey     : {'present' if p_skey else '(absent)'}")
+
+        print("\n[test] calling /getMusicPlay for 稻香 with captured cookie...")
+        unlocked, details = test_vip_unlock(cookie_header)
+        print(f"[test] unlocked: {unlocked}")
+        print(f"[test] details: {details}")
+
+        if not unlocked:
+            print(
+                "\n[result] VIP did NOT unlock even with browser-extracted cookies.\n"
+                "         Existing cookie file is UNTOUCHED.\n"
+                "         Diagnosis: the login flow is not the bottleneck — the\n"
+                "         account likely lacks entitlement for this specific track,\n"
+                "         OR QQ requires additional session setup (gateway handshake)\n"
+                "         beyond what's in the cookie itself.\n"
+            )
+            # Dump the full cookie set for inspection
+            dump_path = BOT_ROOT / "data" / "cookies" / "qq.browser-capture.json"
+            dump_path.write_text(
+                json.dumps(
+                    {"cookie": cookie_header, "cookieList": cks, "capturedAt": time.strftime("%Y-%m-%dT%H:%M:%SZ")},
+                    ensure_ascii=False,
+                    indent=2,
+                ),
+                encoding="utf-8",
+            )
+            print(f"[dump] full browser cookies written to {dump_path}")
+            print("       (for side-by-side comparison with OAuth-derived cookies)")
+            browser.close()
+            return 2
+
+        print("\n[save] VIP unlocked. Writing cookie to bot...")
+        COOKIE_FILE.write_text(
+            json.dumps(
+                {"cookie": cookie_header, "updatedAt": time.strftime("%Y-%m-%dT%H:%M:%SZ")},
+                ensure_ascii=False,
+            ),
+            encoding="utf-8",
+        )
+        print(f"[save] wrote {COOKIE_FILE}")
+
+        try:
+            r = requests.post(
+                "http://localhost:3000/api/auth/cookie",
+                json={"platform": "qq", "cookie": cookie_header},
+                timeout=5,
+                proxies={"http": None, "https": None},
+            )
+            print(f"[notify] /api/auth/cookie POST: {r.status_code}")
+        except Exception as e:
+            print(f"[notify] failed to push cookie to bot: {e}")
+            print("         Restart the bot to pick up the new cookie from disk.")
+
+        print("\n[done] VIP should now work through the bot. Try playing 稻香!")
+        browser.close()
+        return 0
+
+
+if __name__ == "__main__":
+    import sys
+
+    sys.exit(main())
@@ -0,0 +1,119 @@
+"""Open a visible browser at y.qq.com so the user can manually verify
+whether their VIP account can play 稻香 (Jay Chou) in the real QQ Music
+web player.
+
+If the browser plays the song → entitlement exists and our 104003 is a
+request-signing issue.
+If the browser refuses / shows a VIP modal / silently fails → the
+account doesn't have entitlement OR QQ's web player hits the same wall.
+"""
+import sys
+import time
+from playwright.sync_api import sync_playwright
+
+# Force line-buffered stdout so logs actually reach the output file
+sys.stdout.reconfigure(line_buffering=True)
+
+START_URL = "https://y.qq.com/n/ryqq/player"
+SONG_URL = "https://y.qq.com/n/ryqq/songDetail/003aAYrm3GE0Ac"
+
+
+def log(msg: str) -> None:
+    print(msg, flush=True)
+
+
+def main() -> int:
+    log("[setup] launching visible Chromium")
+    log(f"[setup] start URL: {START_URL}")
+    log(f"[setup] song URL:  {SONG_URL}")
+    log("")
+    log("action required:")
+    log("  1. The browser opens at the player page")
+    log("  2. Make sure your VIP account is logged in (top-right avatar)")
+    log("     — if not, log in now, the script will wait")
+    log("  3. Once logged in, the browser will auto-navigate to 稻香")
+    log("  4. Click the PLAY button and report what happens:")
+    log("     (a) song plays → account has entitlement, issue is request signing")
+    log("     (b) VIP modal → account needs higher tier / digital album purchase")
+    log("     (c) silent failure → QQ web player has same 104003 wall")
+    log("")
+    log("[wait] browser stays open for 5 minutes")
+    log("")
+
+    with sync_playwright() as p:
+        try:
+            browser = p.chromium.launch(headless=False)
+        except Exception as e:
+            log(f"[fatal] failed to launch Chromium: {e}")
+            return 1
+
+        ctx = browser.new_context(
+            viewport={"width": 1400, "height": 900},
+            user_agent=(
+                "Mozilla/5.0 (Windows NT 10.0; Win64; x64) "
+                "AppleWebKit/537.36 (KHTML, like Gecko) "
+                "Chrome/132.0.0.0 Safari/537.36"
+            ),
+        )
+        page = ctx.new_page()
+
+        # Log every navigation so we can see if pages fail
+        page.on("framenavigated", lambda f: log(f"[nav] {f.url[:120]}") if f == page.main_frame else None)
+        page.on("pageerror", lambda e: log(f"[js-error] {str(e)[:200]}"))
+
+        # Step 1: open the player page (known working)
+        log(f"[goto] {START_URL}")
+        try:
+            page.goto(START_URL, wait_until="domcontentloaded", timeout=30_000)
+            log(f"[ok] loaded: {page.url}")
+        except Exception as e:
+            log(f"[warn] initial goto failed: {e}")
+            log("[warn] browser stays open, try manual navigation")
+
+        # Wait briefly for auth state to settle
+        time.sleep(3)
+
+        # Check if the user is logged in via the uin cookie
+        cookies = ctx.cookies()
+        uin = next((c["value"] for c in cookies if c["name"] == "uin" and c["value"]), None)
+        if uin:
+            log(f"[auth] logged in as uin={uin}")
+        else:
+            log("[auth] not logged in yet — please log in via the top-right avatar")
+            log("[auth] waiting up to 2 minutes for login...")
+            end = time.time() + 120
+            while time.time() < end:
+                time.sleep(1)
+                cookies = ctx.cookies()
+                uin = next((c["value"] for c in cookies if c["name"] == "uin" and c["value"]), None)
+                if uin:
+                    log(f"[auth] detected login: uin={uin}")
+                    break
+            if not uin:
+                log("[abort] no login detected within 2 minutes")
+                time.sleep(30)  # keep browser visible
+                browser.close()
+                return 2
+
+        # Step 2: navigate to the song page
+        log(f"[goto] {SONG_URL}")
+        try:
+            page.goto(SONG_URL, wait_until="domcontentloaded", timeout=30_000)
+            log(f"[ok] loaded: {page.url}")
+        except Exception as e:
+            log(f"[warn] song navigation failed: {e}")
+            log(f"[info] current page: {page.url}")
+
+        log("")
+        log("===========================================================")
+        log("browser is open on the song page — click PLAY and observe.")
+        log("keeping browser open for 5 more minutes")
+        log("===========================================================")
+
+        time.sleep(300)
+        browser.close()
+        return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())
@@ -0,0 +1,12 @@
+from playwright.sync_api import sync_playwright
+
+with sync_playwright() as p:
+    browser = p.chromium.launch(headless=True)
+    page = browser.new_page(viewport={"width": 1440, "height": 900})
+    page.goto("http://localhost:3000")
+    page.wait_for_load_state("networkidle")
+    page.wait_for_timeout(800)
+    page.locator(".navbar").screenshot(path="scripts/navbar_bigger.png")
+    rect = page.locator(".bot-selector-btn").bounding_box()
+    print("bot-selector-btn bbox:", rect)
+    browser.close()
@@ -1,91 +1,321 @@
@echo off
+setlocal enabledelayedexpansion
+chcp 65001 >nul
 title TSMusicBot Setup
-echo ============================================
-echo   TSMusicBot - First-Time Setup (Windows)
-echo ============================================
-echo.
+
+:: ============================================================
+::  TSMusicBot Setup Script (Robust Edition)
+::  - Auto-detect China network, switch to npmmirror
+::  - Strict error checking at every step
+::  - Detailed logging to setup.log
+::  - Skip already-completed steps on re-run
+:: ============================================================
+
+set "SCRIPT_VERSION=2.0"
+set "MIN_NODE_MAJOR=20"
+set "LOG_FILE=%~dp0..\setup.log"
+set "FAILED=0"

 :: Resolve project root (one level up from scripts/)
-cd /d "%~dp0.."
-
-:: ---- Step 1: Check / install Node.js ----
-where node >nul 2>&1
-if %errorlevel% neq 0 (
-    echo Node.js not found. Attempting automatic installation...
-    echo.
-
-    :: Try winget first (available on Windows 10 1709+ and Windows 11)
-    where winget >nul 2>&1
-    if %errorlevel% equ 0 (
-        echo Installing Node.js via winget...
-        winget install OpenJS.NodeJS.LTS --accept-source-agreements --accept-package-agreements
-        if %errorlevel% neq 0 (
-            echo winget installation failed. Please install Node.js manually from https://nodejs.org
-            pause
-            exit /b 1
-        )
-        :: Refresh PATH so node is available in this session
-        call refreshenv >nul 2>&1
-        :: If refreshenv is not available, ask user to restart
-        where node >nul 2>&1
-        if %errorlevel% neq 0 (
-            echo.
-            echo Node.js was installed but is not yet available in this terminal.
-            echo Please close this window and run setup.bat again.
-            pause
-            exit /b 0
-        )
-    ) else (
-        echo winget is not available on this system.
-        echo Please install Node.js 20 LTS manually from https://nodejs.org
-        echo After installing, close this window and run setup.bat again.
-        pause
-        exit /b 1
-    )
-) else (
-    echo [OK] Node.js found.
-    node --version
-)
-echo.
-
-:: ---- Step 2: Install npm dependencies ----
-echo Installing dependencies (this may take a few minutes)...
-call npm install
-if %errorlevel% neq 0 (
-    echo.
-    echo npm install failed. Check the error messages above.
+cd /d "%~dp0.." || (
+    echo [FATAL] Cannot change to project directory.
    pause
    exit /b 1
 )
-echo [OK] Dependencies installed.
+
+set "PROJECT_ROOT=%cd%"
+
+:: ---- Initialize log ----
+echo. > "%LOG_FILE%"
+call :log "============================================"
+call :log "  TSMusicBot Setup v%SCRIPT_VERSION%"
+call :log "  Started: %date% %time%"
+call :log "  Project root: %PROJECT_ROOT%"
+call :log "============================================"
+
+echo ============================================
+echo   TSMusicBot - First-Time Setup (Windows)
+echo   Version %SCRIPT_VERSION%
+echo ============================================
+echo.
+echo Log file: %LOG_FILE%
 echo.

-:: ---- Step 3: Build the project ----
-echo Building TypeScript project...
-call npx tsc
-if %errorlevel% neq 0 (
+:: ============================================================
+:: Step 1: Check Node.js
+:: ============================================================
+call :step "1/6" "Checking Node.js"
+
+where node >nul 2>&1
+if errorlevel 1 (
+    call :error "Node.js not found in PATH."
+    echo.
+    echo Please install Node.js %MIN_NODE_MAJOR% LTS or newer from one of:
+    echo   - https://nodejs.org/        ^(official^)
+    echo   - https://nodejs.cn/         ^(China mirror, recommended for CN users^)
+    echo.
+    echo After installation:
+    echo   1. Close this window completely
+    echo   2. Open a NEW Command Prompt
+    echo   3. Run scripts\setup.bat again
+    echo.
+    pause
+    exit /b 1
+)
+
+:: Check Node version >= 20
+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=." %%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
+)
+echo.
+
+:: ============================================================
+:: Step 2: Check npm
+:: ============================================================
+call :step "2/6" "Checking npm"
+
+where npm >nul 2>&1
+if errorlevel 1 (
+    call :error "npm not found. This is unusual since Node.js is installed."
+    echo Please reinstall Node.js to fix this.
+    pause
+    exit /b 1
+)
+
+for /f "delims=" %%v in ('npm --version 2^>nul') do set "NPM_VER=%%v"
+call :log "npm version: %NPM_VER%"
+echo [OK] npm found: %NPM_VER%
+echo.
+
+:: ============================================================
+:: Step 3: Detect network and configure mirror
+:: ============================================================
+call :step "3/6" "Checking network"
+
+set "USE_MIRROR=0"
+
+:: Try reaching npm registry with a short timeout
+echo Testing connection to registry.npmjs.org...
+call :log "Testing npm registry connectivity..."
+
+:: Use curl if available (more reliable than ping for HTTPS)
+where curl >nul 2>&1
+if not errorlevel 1 (
+    curl -s -o nul -m 5 -w "%%{http_code}" https://registry.npmjs.org/ > "%TEMP%\npmtest.txt" 2>nul
+    set /p HTTP_CODE=<"%TEMP%\npmtest.txt"
+    del "%TEMP%\npmtest.txt" >nul 2>&1
+    if "!HTTP_CODE!"=="200" (
+        echo [OK] npm registry reachable.
+        call :log "npm registry HTTP 200 OK"
+    ) else (
+        echo [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.
+        set "USE_MIRROR=1"
+    ) else (
+        echo [OK] npm registry reachable.
+    )
+)
+
+if "%USE_MIRROR%"=="1" (
+    echo.
+    echo Slow connection detected. Switching to China mirror ^(npmmirror.com^)...
+    call :log "Switching to npmmirror.com"
+    call npm config set registry https://registry.npmmirror.com >>"%LOG_FILE%" 2>&1
+    call npm config set disturl https://registry.npmmirror.com/-/binary/node >>"%LOG_FILE%" 2>&1
+    call npm config set electron_mirror https://registry.npmmirror.com/-/binary/electron/ >>"%LOG_FILE%" 2>&1
+    call npm config set sqlite3_binary_host_mirror https://registry.npmmirror.com/-/binary/better-sqlite3 >>"%LOG_FILE%" 2>&1
+    call npm config set node_sqlite3_binary_host_mirror https://registry.npmmirror.com/-/binary/better-sqlite3 >>"%LOG_FILE%" 2>&1
+    call npm config set sharp_binary_host https://registry.npmmirror.com/-/binary/sharp >>"%LOG_FILE%" 2>&1
+    call npm config set sharp_libvips_binary_host https://registry.npmmirror.com/-/binary/sharp-libvips >>"%LOG_FILE%" 2>&1
+    call npm config set FFMPEG_BINARIES_URL https://registry.npmmirror.com/-/binary/ffmpeg-static >>"%LOG_FILE%" 2>&1
+    call npm config set @discordjs:registry https://registry.npmmirror.com >>"%LOG_FILE%" 2>&1
+    echo [OK] Mirror configured.
+)
+echo.
+
+:: ============================================================
+:: Step 4: Install backend dependencies
+:: ============================================================
+call :step "4/6" "Installing backend dependencies"
+
+if exist "node_modules\.package-lock.json" (
+    echo Found existing node_modules. Checking integrity...
+    call :log "Existing node_modules detected, running npm install to verify"
+)
+
+echo Running: npm install ^(this can take 5-15 minutes on slow networks^)
+echo Press Ctrl+C to abort.
+echo.
+
+call npm install >>"%LOG_FILE%" 2>&1
+if errorlevel 1 (
+    call :error "Backend npm install failed."
+    echo.
+    echo Common causes:
+    echo   - Network timeout ^(retry with VPN or check %LOG_FILE%^)
+    echo   - Native module compile failure ^(missing Python/VS Build Tools^)
+    echo   - Disk space full
+    echo.
+    echo Try manually:
+    echo   cd /d "%PROJECT_ROOT%"
+    echo   npm install --verbose
+    echo.
+    pause
+    exit /b 1
+)
+echo [OK] Backend dependencies installed.
+echo.
+
+:: ============================================================
+:: Step 5: Install frontend dependencies
+:: ============================================================
+call :step "5/6" "Installing frontend dependencies"
+
+if not exist "web\package.json" (
+    call :error "web\package.json not found. Repository may be incomplete."
+    echo Please re-clone the repository:
+    echo   git clone https://github.com/ZHANGTIANYAO1/teamspeak-music-bot.git
+    pause
+    exit /b 1
+)
+
+echo Running: npm install ^(in web/ directory^)
+echo.
+
+pushd web >nul
+call npm install >>"%LOG_FILE%" 2>&1
+set "WEB_INSTALL_RESULT=!errorlevel!"
+popd >nul
+
+if !WEB_INSTALL_RESULT! neq 0 (
+    call :error "Frontend npm install failed ^(exit code !WEB_INSTALL_RESULT!^)."
+    echo.
+    echo Try manually:
+    echo   cd /d "%PROJECT_ROOT%\web"
+    echo   npm install --verbose
+    echo.
+    pause
+    exit /b 1
+)
+echo [OK] Frontend dependencies installed.
+echo.
+
+:: ============================================================
+:: Step 6: Build project (backend + frontend)
+:: ============================================================
+call :step "6/6" "Building project"
+
+echo Running: npm run build
+echo.
+
+call npm run build >>"%LOG_FILE%" 2>&1
+if errorlevel 1 (
+    call :error "Build failed."
+    echo.
+    echo Check the log file for details: %LOG_FILE%
+    echo.
+    echo Try manually:
+    echo   cd /d "%PROJECT_ROOT%"
+    echo   npm run build
    echo.
-    echo Build failed. Check the error messages above.
    pause
    exit /b 1
 )
 echo [OK] Build succeeded.
 echo.

-:: ---- Step 4: Create default config if missing ----
+:: ============================================================
+:: Verify build outputs
+:: ============================================================
+echo Verifying build outputs...
+set "BUILD_OK=1"
+
+if not exist "dist" (
+    call :error "dist/ directory missing after build."
+    set "BUILD_OK=0"
+)
+if not exist "web\dist" (
+    call :error "web\dist/ directory missing after build."
+    set "BUILD_OK=0"
+)
+
+if "!BUILD_OK!"=="0" (
+    echo.
+    echo Build completed but expected output is missing.
+    echo Check %LOG_FILE% for details.
+    pause
+    exit /b 1
+)
+echo [OK] Build outputs verified.
+echo.
+
+:: ============================================================
+:: Optional: config.json hint
+:: ============================================================
 if not exist "config.json" (
-    echo Creating default config.json...
-    echo Please edit config.json with your TeamSpeak server details before starting the bot.
+    echo [INFO] config.json will be auto-generated on first launch.
 ) else (
    echo [OK] config.json already exists.
 )
 echo.

-:: ---- Done ----
+:: ============================================================
+:: Done
+:: ============================================================
+call :log "Setup completed successfully at %date% %time%"
+
 echo ============================================
-echo   Setup complete!
+echo   Setup Complete!
 echo ============================================
 echo.
-echo To start the bot, run:  scripts\start.bat
+echo Next steps:
+echo   1. Run:  scripts\start.bat
+echo   2. Open: http://localhost:3000
+echo   3. Follow the in-browser setup wizard.
+echo.
+echo Setup log saved to: %LOG_FILE%
 echo.
 pause
+exit /b 0
+
+:: ============================================================
+:: Subroutines
+:: ============================================================
+:step
+echo ---- Step %~1: %~2 ----
+call :log ""
+call :log "---- Step %~1: %~2 ----"
+goto :eof
+
+:error
+echo.
+echo [ERROR] %~1
+call :log "[ERROR] %~1"
+goto :eof
+
+:log
+echo [%time%] %~1 >> "%LOG_FILE%"
+goto :eof
@@ -0,0 +1,99 @@
+"""Regression: DELETE /api/bot/:id must broadcast botRemoved so the UI drops the row.
+
+Creates an ephemeral bot, opens the dropdown, deletes the bot via API, and
+asserts the row disappears without any page reload. Does not touch any
+existing user bot.
+"""
+import time
+import requests
+from playwright.sync_api import sync_playwright
+
+BASE = "http://localhost:3000"
+EPHEMERAL_NAME = "rmbot_test"
+EPHEMERAL_NICK = "RmBotTest"
+
+
+def api(path, method="GET", **kw):
+    r = getattr(requests, method.lower())(f"{BASE}{path}", timeout=10, **kw)
+    r.raise_for_status()
+    return r.json() if r.text else None
+
+
+def cleanup():
+    for b in api("/api/bot/")["bots"]:
+        if b["name"] == EPHEMERAL_NAME:
+            try:
+                api(f"/api/bot/{b['id']}", method="DELETE")
+            except Exception:
+                pass
+
+
+def main():
+    cleanup()
+    new = api(
+        "/api/bot/",
+        method="POST",
+        json={
+            "name": EPHEMERAL_NAME,
+            "serverAddress": "127.0.0.1",
+            "serverPort": 9987,
+            "nickname": EPHEMERAL_NICK,
+            "autoStart": False,
+        },
+    )
+    bot_id = new["id"]
+    print(f"[setup] created ephemeral bot {bot_id[:8]}")
+
+    try:
+        with sync_playwright() as p:
+            browser = p.chromium.launch(headless=True)
+            try:
+                page = browser.new_page(viewport={"width": 1440, "height": 900})
+                page.goto(BASE)
+                page.wait_for_load_state("networkidle")
+                time.sleep(0.8)
+
+                # Open dropdown and confirm the new bot row is present
+                page.locator(".bot-selector-btn").click()
+                page.wait_for_selector(".bot-dropdown")
+                rows_before = page.locator(".bot-dropdown-row").count()
+                print(f"[ui] dropdown rows before remove: {rows_before}")
+
+                # Match the ephemeral row by its name text
+                present = (
+                    page.locator(".bot-dropdown-row", has_text=EPHEMERAL_NAME).count()
+                )
+                assert present == 1, f"ephemeral row not found (got {present})"
+
+                # Delete via API
+                api(f"/api/bot/{bot_id}", method="DELETE")
+                print("[api] deleted bot")
+
+                # Wait up to 4s for UI to drop the row
+                removed = False
+                for _ in range(40):
+                    if (
+                        page.locator(
+                            ".bot-dropdown-row", has_text=EPHEMERAL_NAME
+                        ).count()
+                        == 0
+                    ):
+                        removed = True
+                        break
+                    time.sleep(0.1)
+
+                rows_after = page.locator(".bot-dropdown-row").count()
+                print(f"[ui] dropdown rows after remove: {rows_after}")
+                assert removed, "ephemeral row did not disappear from UI after DELETE"
+                assert rows_after == rows_before - 1, (
+                    f"row count mismatch: before={rows_before} after={rows_after}"
+                )
+                print("[PASS] bot removal propagates to UI via WS")
+            finally:
+                browser.close()
+    finally:
+        cleanup()
+
+
+if __name__ == "__main__":
+    main()
@@ -0,0 +1,171 @@
+"""Corner case regressions that go beyond Bugs A/B/C.
+
+A. Race — disconnect() called during connect()'s awaited handshake must
+   NOT leave the bot reporting connected=true afterwards.
+
+B. Config-only commands (vol, mode, clear) must work even when the bot is
+   disconnected (UI should stay usable while the bot is offline).
+
+C. After a disconnect mid-playback, the player must not be able to
+   auto-advance to the next queued song (trackEnd → resolveAndPlay).
+"""
+import time
+import threading
+import requests
+
+BASE = "http://localhost:3000"
+
+
+def api(path, method="GET", **kw):
+    return getattr(requests, method.lower())(f"{BASE}{path}", timeout=30, **kw)
+
+
+def get_bot(bot_id):
+    return next(b for b in api("/api/bot/").json()["bots"] if b["id"] == bot_id)
+
+
+def wait_connected(bot_id, want, timeout=15):
+    end = time.time() + timeout
+    while time.time() < end:
+        if get_bot(bot_id)["connected"] is want:
+            return True
+        time.sleep(0.1)
+    return False
+
+
+def test_config_commands_when_disconnected(bot_id):
+    """B. vol/mode/clear should succeed while bot is disconnected."""
+    api(f"/api/bot/{bot_id}/stop", method="POST")
+    wait_connected(bot_id, False)
+
+    # volume is the simplest config-only command
+    r = api(
+        f"/api/player/{bot_id}/volume",
+        method="POST",
+        json={"volume": 60},
+    )
+    assert r.status_code == 200, f"volume failed while disconnected: {r.status_code} {r.text[:100]}"
+
+    r = api(
+        f"/api/player/{bot_id}/mode",
+        method="POST",
+        json={"mode": "seq"},
+    )
+    assert r.status_code == 200, f"mode failed while disconnected: {r.status_code} {r.text[:100]}"
+
+    r = api(f"/api/player/{bot_id}/clear", method="POST")
+    assert r.status_code == 200, f"clear failed while disconnected: {r.status_code} {r.text[:100]}"
+
+    print("[PASS] config commands (vol/mode/clear) work when disconnected")
+
+
+def test_play_rejected_when_disconnected(bot_id):
+    """B (negative). play/add/next/prev should still be rejected."""
+    r = api(
+        f"/api/player/{bot_id}/play",
+        method="POST",
+        json={"query": "test", "platform": "netease"},
+    )
+    assert r.status_code >= 400, f"play should fail while disconnected"
+
+    r = api(
+        f"/api/player/{bot_id}/add",
+        method="POST",
+        json={"query": "test", "platform": "netease"},
+    )
+    assert r.status_code >= 400, f"add should fail while disconnected"
+
+    r = api(f"/api/player/{bot_id}/next", method="POST")
+    assert r.status_code >= 400, f"next should fail while disconnected"
+
+    print("[PASS] audio commands (play/add/next) rejected when disconnected")
+
+
+def test_disconnect_during_connect_race(bot_id):
+    """A. disconnect() called while connect() is awaiting must win the race.
+
+    Fires a stop 200ms into a start call; after things settle the bot's
+    connected state must be stable (either cleanly disconnected, or cleanly
+    connected if the stop happened after connect completed). It must NOT
+    end up in a weird state where connected=true but a subsequent query
+    shows inconsistent data.
+    """
+    # Ensure disconnected first
+    api(f"/api/bot/{bot_id}/stop", method="POST")
+    wait_connected(bot_id, False)
+    time.sleep(1)  # give TS server a moment to forget us
+
+    def delayed_stop():
+        time.sleep(0.2)
+        try:
+            api(f"/api/bot/{bot_id}/stop", method="POST")
+        except Exception:
+            pass
+
+    threading.Thread(target=delayed_stop, daemon=True).start()
+    try:
+        r = api(f"/api/bot/{bot_id}/start", method="POST")
+    except Exception as e:
+        r = None
+        print(f"[info] start threw: {e}")
+
+    # Wait for all state transitions to settle
+    time.sleep(2)
+
+    b = get_bot(bot_id)
+    # The key invariant: if connected is false, playing must also be false;
+    # if connected is true, the transport is actually up (we can issue
+    # another command without error).
+    assert not (b["connected"] is False and b["playing"] is True), (
+        f"inconsistent state: connected={b['connected']} playing={b['playing']}"
+    )
+    print(
+        f"[PASS] disconnect-during-connect race — final state consistent "
+        f"(connected={b['connected']} playing={b['playing']})"
+    )
+
+
+def test_resolve_guard(bot_id):
+    """C. resolveAndPlay on a disconnected bot is a no-op.
+
+    We can't directly invoke resolveAndPlay from the API, but we can
+    verify by checking that after a stop, the bot stays idle even if we
+    wait for a trackEnd-like event to fire.
+    """
+    api(f"/api/bot/{bot_id}/stop", method="POST")
+    wait_connected(bot_id, False)
+    time.sleep(1.5)  # more than a frame cycle
+    b = get_bot(bot_id)
+    assert not b["playing"], (
+        f"player should stay stopped after disconnect: {b}"
+    )
+    print("[PASS] player stays idle after disconnect (no ghost autoplay)")
+
+
+def main():
+    bots = api("/api/bot/").json()["bots"]
+    if not bots:
+        print("[skip] no bots")
+        return
+    bot_id = bots[0]["id"]
+    initial = bots[0]["connected"]
+    print(f"[init] bot={bot_id[:8]} initial connected={initial}")
+
+    try:
+        test_config_commands_when_disconnected(bot_id)
+        test_play_rejected_when_disconnected(bot_id)
+        test_resolve_guard(bot_id)
+        test_disconnect_during_connect_race(bot_id)
+        print("ALL GREEN")
+    finally:
+        if initial:
+            api(f"/api/bot/{bot_id}/start", method="POST")
+            wait_connected(bot_id, True)
+        else:
+            api(f"/api/bot/{bot_id}/stop", method="POST")
+            wait_connected(bot_id, False)
+        print(f"[restore] connected={get_bot(bot_id)['connected']}")
+
+
+if __name__ == "__main__":
+    main()
@@ -0,0 +1,852 @@
+"""Comprehensive feature + corner-case test for TSMusicBot against a
+local TeamSpeak 3 server.
+
+Exercises every major HTTP endpoint, the WebSocket state-broadcast path,
+all music providers, bot lifecycle transitions, and a handful of races
+that have burned us in the past. Designed to be safe to run against a
+real installation: captures the target bot's initial connected/volume/
+mode settings and restores them in `finally`.
+
+Usage:
+    "C:/Users/saopig1/miniforge3/python.exe" scripts/test_full_feature.py
+
+Exit code: 0 if every non-skipped test passed, 1 otherwise.
+"""
+from __future__ import annotations
+
+import json
+import threading
+import time
+from dataclasses import dataclass
+from typing import Any
+
+import requests
+
+BASE = "http://localhost:3000"
+POLL_INTERVAL = 0.15
+CONNECT_TIMEOUT = 20        # tolerate occasional TS3 anti-flood grace
+ANTIFLOOD_BREATHER = 1.5    # gap between rapid cycles so TS3 stays happy
+
+
+# ----------------------------- HTTP helpers ---------------------------------
+
+
+def api(path: str, method: str = "GET", json_body: Any = None):
+    """Return (status_code, body). Never raises."""
+    try:
+        fn = getattr(requests, method.lower())
+        r = fn(f"{BASE}{path}", json=json_body, timeout=30)
+        try:
+            return r.status_code, r.json()
+        except Exception:
+            return r.status_code, r.text
+    except Exception as e:
+        return None, f"<{type(e).__name__}: {e}>"
+
+
+def get_bot(bot_id: str) -> dict | None:
+    _, data = api("/api/bot/")
+    if not isinstance(data, dict):
+        return None
+    return next((b for b in data.get("bots", []) if b["id"] == bot_id), None)
+
+
+def wait_connected(bot_id: str, want: bool, timeout: float = CONNECT_TIMEOUT) -> bool:
+    end = time.time() + timeout
+    while time.time() < end:
+        b = get_bot(bot_id)
+        if b is not None and b["connected"] is want:
+            return True
+        time.sleep(POLL_INTERVAL)
+    return False
+
+
+def start_and_wait(bot_id: str, retries: int = 2) -> bool:
+    """Start the bot, tolerating transient TS3 anti-flood by retrying with
+    exponential backoff. Returns True only when the bot reports connected."""
+    for attempt in range(retries + 1):
+        s, _ = api(f"/api/bot/{bot_id}/start", method="POST")
+        if s == 200 and wait_connected(bot_id, True):
+            return True
+        # If /start returned an error (e.g. connect timeout from our 15s
+        # deadline), back off and retry — TS3 server-side anti-flood
+        # usually clears in a few seconds.
+        if attempt < retries:
+            time.sleep(3.0 * (attempt + 1))
+            # Make sure we're fully stopped before the next attempt so
+            # oldBot.disconnect() doesn't double-fire
+            api(f"/api/bot/{bot_id}/stop", method="POST")
+            wait_connected(bot_id, False, timeout=5)
+    return False
+
+
+def stop_and_wait(bot_id: str) -> bool:
+    api(f"/api/bot/{bot_id}/stop", method="POST")
+    return wait_connected(bot_id, False)
+
+
+def assert_started(bot_id: str):
+    """Helper that raises with a clear message when start fails so test
+    output points at 'could not connect' rather than an empty assertion."""
+    if not start_and_wait(bot_id):
+        raise AssertionError(
+            "could not bring bot online (TS3 server may be anti-flooding "
+            "or unreachable)"
+        )
+
+
+# ----------------------------- test runner ----------------------------------
+
+
+@dataclass
+class TestResult:
+    name: str
+    status: str  # PASS / FAIL / ERROR / SKIP
+    detail: str = ""
+
+
+passed = 0
+failed = 0
+skipped = 0
+results: list[TestResult] = []
+
+
+def run(name: str, fn):
+    global passed, failed
+    try:
+        fn()
+        print(f"  [PASS] {name}")
+        passed += 1
+        results.append(TestResult(name, "PASS"))
+    except AssertionError as e:
+        print(f"  [FAIL] {name}: {e}")
+        failed += 1
+        results.append(TestResult(name, "FAIL", str(e)))
+    except Exception as e:
+        print(f"  [ERROR] {name}: {type(e).__name__}: {e}")
+        failed += 1
+        results.append(TestResult(name, "ERROR", f"{type(e).__name__}: {e}"))
+
+
+def skip(name: str, reason: str):
+    global skipped
+    print(f"  [SKIP] {name}  ({reason})")
+    skipped += 1
+    results.append(TestResult(name, "SKIP", reason))
+
+
+# ----------------------------- test groups ----------------------------------
+
+
+def group_infrastructure(bot_id: str):
+    print("\n== infrastructure ==")
+
+    def t_health():
+        s, d = api("/api/health")
+        assert s == 200, f"health returned {s}"
+        assert d.get("status") == "ok"
+    run("GET /api/health", t_health)
+
+    def t_list_bots():
+        s, d = api("/api/bot/")
+        assert s == 200
+        assert isinstance(d.get("bots"), list)
+        assert any(b["id"] == bot_id for b in d["bots"])
+    run("GET /api/bot/ lists target bot", t_list_bots)
+
+    def t_bot_config():
+        s, d = api(f"/api/bot/{bot_id}/config")
+        assert s == 200
+        assert d["id"] == bot_id
+        assert "identity" in d
+        assert "serverAddress" in d and "nickname" in d
+        assert "serverPassword" in d, "serverPassword field missing"
+    run("GET /api/bot/:id/config returns all fields", t_bot_config)
+
+    def t_404_on_unknown_bot():
+        s, _ = api("/api/bot/does-not-exist/config")
+        assert s == 404
+    run("404 on unknown bot id", t_404_on_unknown_bot)
+
+    def t_quality_shape():
+        s, d = api("/api/music/quality")
+        assert s == 200
+        for p in ("netease", "qq", "bilibili"):
+            assert p in d, f"{p} missing from quality response"
+    run("GET /api/music/quality shape", t_quality_shape)
+
+
+def group_auth_status():
+    print("\n== auth status per platform ==")
+
+    def t_netease_ok():
+        s, d = api("/api/auth/status?platform=netease")
+        assert s == 200
+        assert d.get("platform") == "netease"
+        assert "loggedIn" in d
+    run("auth status netease", t_netease_ok)
+
+    def t_qq_ok():
+        s, d = api("/api/auth/status?platform=qq")
+        assert s == 200
+        assert d.get("platform") == "qq"
+    run("auth status qq", t_qq_ok)
+
+    def t_bilibili_ok():
+        s, d = api("/api/auth/status?platform=bilibili")
+        assert s == 200
+        assert d.get("platform") == "bilibili"
+    run("auth status bilibili", t_bilibili_ok)
+
+    def t_youtube_routed():
+        # Regression: /auth/status?platform=youtube used to fall through
+        # to NetEase and leak the NetEase user's nickname/avatar.
+        s, d = api("/api/auth/status?platform=youtube")
+        assert s == 200
+        assert d.get("platform") == "youtube", (
+            f"youtube auth status leaked to {d.get('platform')}"
+        )
+    run("auth status youtube routes correctly", t_youtube_routed)
+
+    def t_youtube_cookie_rejected():
+        s, d = api(
+            "/api/auth/cookie",
+            method="POST",
+            json_body={"platform": "youtube", "cookie": "fake"},
+        )
+        assert s == 400, f"youtube cookie should be rejected, got {s}: {d}"
+    run("POST /auth/cookie rejects youtube", t_youtube_cookie_rejected)
+
+
+def group_search():
+    print("\n== multi-platform search ==")
+
+    def search(platform: str, query: str = "test"):
+        return api(f"/api/music/search?q={query}&platform={platform}&limit=1")
+
+    def t_netease():
+        s, d = search("netease")
+        assert s == 200
+        assert isinstance(d.get("songs"), list)
+    run("netease search", t_netease)
+
+    def t_qq():
+        s, d = search("qq")
+        assert s == 200
+        # QQ may return 0 results if no cookie, but shouldn't error
+        assert isinstance(d.get("songs"), list)
+    run("qq search (empty ok)", t_qq)
+
+    def t_bilibili():
+        s, d = search("bilibili")
+        assert s == 200
+        assert isinstance(d.get("songs"), list)
+    run("bilibili search", t_bilibili)
+
+    def t_missing_query():
+        s, _ = api("/api/music/search?platform=netease")
+        assert s == 400, "missing q should 400"
+    run("400 on missing query", t_missing_query)
+
+    _, auth = api("/api/auth/status?platform=youtube")
+    youtube_available = isinstance(auth, dict) and auth.get("loggedIn") is True
+
+    if youtube_available:
+        def t_youtube():
+            s, d = search("youtube", "lofi")
+            assert s == 200
+            songs = d.get("songs", [])
+            assert len(songs) >= 1, "expected at least 1 YouTube result"
+            assert songs[0]["platform"] == "youtube"
+        run("youtube search (yt-dlp installed)", t_youtube)
+    else:
+        skip("youtube search", "yt-dlp not installed")
+
+
+def group_lifecycle(bot_id: str):
+    print("\n== connection lifecycle ==")
+
+    def t_stop_from_any_state():
+        api(f"/api/bot/{bot_id}/stop", method="POST")
+        assert wait_connected(bot_id, False), "bot did not stop"
+        b = get_bot(bot_id)
+        assert not b["playing"], "playing should be false after stop"
+    run("stop from any state \u2192 disconnected+idle", t_stop_from_any_state)
+
+    def t_start_completes_quickly():
+        t0 = time.time()
+        s, d = api(f"/api/bot/{bot_id}/start", method="POST")
+        elapsed = time.time() - t0
+        assert s == 200, f"start failed: {d}"
+        assert elapsed < 10, f"start took {elapsed:.1f}s (expected <10s)"
+        assert wait_connected(bot_id, True)
+    run("start completes well under 15s deadline", t_start_completes_quickly)
+
+    def t_identity_persists():
+        assert_started(bot_id)
+        _, cfg1 = api(f"/api/bot/{bot_id}/config")
+        id1 = cfg1["identity"]
+        assert id1, "identity empty after first start"
+        assert stop_and_wait(bot_id)
+        time.sleep(ANTIFLOOD_BREATHER)
+        assert_started(bot_id)
+        _, cfg2 = api(f"/api/bot/{bot_id}/config")
+        assert cfg2["identity"] == id1, (
+            f"identity changed across restart: {id1} \u2192 {cfg2['identity']}"
+        )
+    run("identity preserved across stop/start", t_identity_persists)
+
+
+def group_playback(bot_id: str):
+    print("\n== playback ==")
+
+    # Bring the bot online ONCE for the whole playback group, then only
+    # toggle player state (play/pause/stop) between tests. This keeps the
+    # TS3 reconnect count for this group at exactly 1.
+    assert_started(bot_id)
+
+    def t_play_song():
+        s, d = api(
+            f"/api/player/{bot_id}/play",
+            method="POST",
+            json_body={"query": "the mass", "platform": "netease"},
+        )
+        assert s == 200, f"play failed: {d}"
+        time.sleep(1.2)
+        b = get_bot(bot_id)
+        assert b["playing"] is True, f"not playing after /play: {b}"
+        assert b["currentSong"] is not None
+    run("play netease song \u2192 playing=true", t_play_song)
+
+    def t_pause_resume():
+        # Previous test left a song playing
+        api(f"/api/player/{bot_id}/pause", method="POST")
+        time.sleep(0.4)
+        b = get_bot(bot_id)
+        assert b["paused"] is True, f"pause failed: {b}"
+        api(f"/api/player/{bot_id}/resume", method="POST")
+        time.sleep(0.4)
+        b = get_bot(bot_id)
+        assert b["paused"] is False and b["playing"] is True, f"resume failed: {b}"
+    run("pause \u2192 paused, resume \u2192 playing", t_pause_resume)
+
+    def t_volume_change():
+        s, _ = api(
+            f"/api/player/{bot_id}/volume",
+            method="POST",
+            json_body={"volume": 42},
+        )
+        assert s == 200
+        time.sleep(0.2)
+        b = get_bot(bot_id)
+        assert b["volume"] == 42, f"volume not applied: {b['volume']}"
+    run("volume change", t_volume_change)
+
+    def t_mode_cycle():
+        for m in ("seq", "loop", "random", "rloop"):
+            s, _ = api(
+                f"/api/player/{bot_id}/mode", method="POST", json_body={"mode": m}
+            )
+            assert s == 200
+            b = get_bot(bot_id)
+            assert b["playMode"] == m, f"mode {m} not applied: {b['playMode']}"
+    run("all four play modes apply", t_mode_cycle)
+
+    def t_queue_endpoint():
+        s, d = api(f"/api/player/{bot_id}/queue")
+        assert s == 200
+        assert isinstance(d.get("queue"), list)
+        assert "status" in d
+    run("GET /player/:id/queue returns queue+status", t_queue_endpoint)
+
+    def t_elapsed_endpoint():
+        s, d = api(f"/api/player/{bot_id}/elapsed")
+        assert s == 200
+        elapsed = d.get("elapsed")
+        assert isinstance(elapsed, (int, float)) and elapsed >= 0, (
+            f"elapsed should be non-negative number: {elapsed}"
+        )
+    run("GET /player/:id/elapsed returns finite number", t_elapsed_endpoint)
+
+    def t_add_autoplay_on_idle():
+        # This specific test needs an IDLE bot — stop first (but keep
+        # connected), then add and confirm auto-play.
+        api(f"/api/player/{bot_id}/stop", method="POST")
+        time.sleep(0.4)
+        b = get_bot(bot_id)
+        assert not b["playing"] and b["queueSize"] == 0, f"setup failed: {b}"
+        s, d = api(
+            f"/api/player/{bot_id}/add",
+            method="POST",
+            json_body={"query": "the mass", "platform": "netease"},
+        )
+        assert s == 200
+        msg = d.get("message", "") if isinstance(d, dict) else ""
+        assert "Now playing" in msg, (
+            f"add on idle bot should auto-play, got: {msg!r}"
+        )
+        time.sleep(0.8)
+        b = get_bot(bot_id)
+        assert b["playing"] is True, f"not playing after add: {b}"
+    run("add on idle bot auto-plays", t_add_autoplay_on_idle)
+
+    # Leave the bot in a clean state for the next group
+    api(f"/api/player/{bot_id}/stop", method="POST")
+
+
+def group_queue_ops(bot_id: str):
+    print("\n== queue operations ==")
+    assert_started(bot_id)
+
+    def t_clear():
+        api(
+            f"/api/player/{bot_id}/play",
+            method="POST",
+            json_body={"query": "the mass", "platform": "netease"},
+        )
+        time.sleep(0.8)
+        api(
+            f"/api/player/{bot_id}/add",
+            method="POST",
+            json_body={"query": "lemon tree", "platform": "netease"},
+        )
+        time.sleep(0.6)
+        b_before = get_bot(bot_id)
+        assert b_before["queueSize"] >= 2, f"expected \u22652 songs: {b_before}"
+        api(f"/api/player/{bot_id}/clear", method="POST")
+        time.sleep(0.4)
+        b_after = get_bot(bot_id)
+        assert b_after["queueSize"] == 0
+    run("clear queue empties it", t_clear)
+
+    def t_play_at_invalid_preserves_playback():
+        api(
+            f"/api/player/{bot_id}/play",
+            method="POST",
+            json_body={"query": "the mass", "platform": "netease"},
+        )
+        time.sleep(1.2)
+        assert get_bot(bot_id)["playing"]
+        s, _ = api(
+            f"/api/player/{bot_id}/play-at",
+            method="POST",
+            json_body={"index": 9999},
+        )
+        assert s == 400, f"invalid index should 400, got {s}"
+        time.sleep(0.4)
+        b = get_bot(bot_id)
+        assert b["playing"], "invalid play-at killed the current song"
+    run("invalid play-at preserves current playback", t_play_at_invalid_preserves_playback)
+
+    def t_play_at_negative_rejected():
+        s, _ = api(
+            f"/api/player/{bot_id}/play-at",
+            method="POST",
+            json_body={"index": -1},
+        )
+        assert s == 400
+    run("play-at with negative index rejected", t_play_at_negative_rejected)
+
+    api(f"/api/player/{bot_id}/stop", method="POST")
+
+
+def group_input_validation(bot_id: str):
+    print("\n== HTTP input validation ==")
+
+    def t_volume_out_of_range():
+        for bad in (150, -10, 1000, -1):
+            s, _ = api(
+                f"/api/player/{bot_id}/volume",
+                method="POST",
+                json_body={"volume": bad},
+            )
+            assert s == 400, f"volume={bad} should 400, got {s}"
+    run("volume out-of-range rejected (400)", t_volume_out_of_range)
+
+    def t_volume_wrong_type():
+        for bad in ("50", None, [50], {"v": 50}):
+            s, _ = api(
+                f"/api/player/{bot_id}/volume",
+                method="POST",
+                json_body={"volume": bad},
+            )
+            assert s == 400, f"volume={bad!r} should 400, got {s}"
+    run("volume wrong-type rejected (400)", t_volume_wrong_type)
+
+    def t_volume_missing():
+        s, _ = api(
+            f"/api/player/{bot_id}/volume", method="POST", json_body={}
+        )
+        assert s == 400
+    run("volume missing rejected (400)", t_volume_missing)
+
+    def t_volume_valid():
+        for good in (0, 1, 50, 100):
+            s, _ = api(
+                f"/api/player/{bot_id}/volume",
+                method="POST",
+                json_body={"volume": good},
+            )
+            assert s == 200, f"volume={good} should succeed, got {s}"
+            b = get_bot(bot_id)
+            assert b["volume"] == good, f"volume not applied: {b['volume']}"
+    run("valid volumes apply", t_volume_valid)
+
+    def t_mode_invalid():
+        for bad in ("bogus", "", None, 1, "SEQ"):
+            s, _ = api(
+                f"/api/player/{bot_id}/mode",
+                method="POST",
+                json_body={"mode": bad},
+            )
+            assert s == 400, f"mode={bad!r} should 400, got {s}"
+    run("mode invalid rejected (400)", t_mode_invalid)
+
+    def t_mode_missing():
+        s, _ = api(f"/api/player/{bot_id}/mode", method="POST", json_body={})
+        assert s == 400
+    run("mode missing rejected (400)", t_mode_missing)
+
+
+def group_disconnect_corners(bot_id: str):
+    print("\n== disconnected-bot corners ==")
+
+    def t_play_rejected():
+        assert stop_and_wait(bot_id)
+        s, d = api(
+            f"/api/player/{bot_id}/play",
+            method="POST",
+            json_body={"query": "x", "platform": "netease"},
+        )
+        assert s >= 400
+        err = (d.get("error") or "") if isinstance(d, dict) else ""
+        assert "not connected" in err.lower(), f"expected 'not connected' error: {d}"
+    run("play rejected while disconnected", t_play_rejected)
+
+    def t_add_rejected():
+        s, _ = api(
+            f"/api/player/{bot_id}/add",
+            method="POST",
+            json_body={"query": "x", "platform": "netease"},
+        )
+        assert s >= 400
+    run("add rejected while disconnected", t_add_rejected)
+
+    def t_next_rejected():
+        s, _ = api(f"/api/player/{bot_id}/next", method="POST")
+        assert s >= 400
+    run("next rejected while disconnected", t_next_rejected)
+
+    def t_volume_allowed():
+        s, _ = api(
+            f"/api/player/{bot_id}/volume",
+            method="POST",
+            json_body={"volume": 60},
+        )
+        assert s == 200, "volume should work while disconnected"
+    run("volume allowed while disconnected", t_volume_allowed)
+
+    def t_mode_allowed():
+        s, _ = api(
+            f"/api/player/{bot_id}/mode", method="POST", json_body={"mode": "random"}
+        )
+        assert s == 200, "mode should work while disconnected"
+    run("mode allowed while disconnected", t_mode_allowed)
+
+    def t_clear_allowed():
+        s, _ = api(f"/api/player/{bot_id}/clear", method="POST")
+        assert s == 200, "clear should work while disconnected"
+    run("clear allowed while disconnected", t_clear_allowed)
+
+    def t_player_state_clean():
+        b = get_bot(bot_id)
+        assert not b["playing"] and not b["paused"], f"state leak: {b}"
+    run("no player state leak while disconnected", t_player_state_clean)
+
+
+def group_seek(bot_id: str):
+    print("\n== seek validation ==")
+
+    def t_negative():
+        s, _ = api(
+            f"/api/player/{bot_id}/seek", method="POST", json_body={"position": -5}
+        )
+        assert s == 400
+    run("negative seek rejected", t_negative)
+
+    def t_string():
+        s, _ = api(
+            f"/api/player/{bot_id}/seek",
+            method="POST",
+            json_body={"position": "abc"},
+        )
+        assert s == 400
+    run("string seek rejected", t_string)
+
+    def t_nan_literal():
+        r = requests.post(
+            f"{BASE}/api/player/{bot_id}/seek",
+            data='{"position": NaN}',
+            headers={"Content-Type": "application/json"},
+            timeout=10,
+        )
+        assert r.status_code >= 400, f"NaN literal accepted: {r.status_code}"
+    run("NaN literal seek rejected", t_nan_literal)
+
+    def t_valid_seek():
+        # Seek needs a live connection + playing song. The disconnect-
+        # corners group right before this one left the bot disconnected.
+        assert_started(bot_id)
+        api(
+            f"/api/player/{bot_id}/play",
+            method="POST",
+            json_body={"query": "the mass", "platform": "netease"},
+        )
+        time.sleep(1.5)
+        s, _ = api(
+            f"/api/player/{bot_id}/seek",
+            method="POST",
+            json_body={"position": 25},
+        )
+        assert s == 200
+        time.sleep(0.5)
+        _, d = api(f"/api/player/{bot_id}/elapsed")
+        elapsed = d.get("elapsed")
+        assert isinstance(elapsed, (int, float)) and 24 <= elapsed < 40, (
+            f"elapsed after seek(25) wrong: {elapsed}"
+        )
+        api(f"/api/player/{bot_id}/stop", method="POST")
+    run("valid seek produces finite elapsed", t_valid_seek)
+
+
+def group_races(bot_id: str):
+    print("\n== race conditions ==")
+
+    def t_disconnect_during_connect():
+        assert stop_and_wait(bot_id)
+        time.sleep(ANTIFLOOD_BREATHER)
+
+        def delayed_stop():
+            time.sleep(0.2)
+            api(f"/api/bot/{bot_id}/stop", method="POST")
+
+        threading.Thread(target=delayed_stop, daemon=True).start()
+        api(f"/api/bot/{bot_id}/start", method="POST")
+        time.sleep(2)
+        b = get_bot(bot_id)
+        assert not (b["connected"] is False and b["playing"] is True), (
+            f"inconsistent state: {b}"
+        )
+    run("disconnect during connect", t_disconnect_during_connect)
+
+    def t_stop_during_url_resolve():
+        assert stop_and_wait(bot_id)
+        time.sleep(ANTIFLOOD_BREATHER)
+        assert_started(bot_id)
+
+        def delayed_stop():
+            time.sleep(0.15)
+            api(f"/api/bot/{bot_id}/stop", method="POST")
+
+        threading.Thread(target=delayed_stop, daemon=True).start()
+        api(
+            f"/api/player/{bot_id}/play",
+            method="POST",
+            json_body={"query": "the mass", "platform": "netease"},
+        )
+        time.sleep(3)
+        b = get_bot(bot_id)
+        assert not (b["connected"] is False and b["playing"] is True), (
+            f"inconsistent state: {b}"
+        )
+    run("stop during URL resolve", t_stop_during_url_resolve)
+
+    def t_rapid_volume_change():
+        # Volume is a config-only command and works while disconnected,
+        # so this test deliberately doesn't call assert_started — we're
+        # validating the API's last-write-wins behavior, not the TS
+        # transport. That also spares the TS3 anti-flood budget.
+        for v in (10, 25, 50, 75, 100, 1):
+            s, _ = api(
+                f"/api/player/{bot_id}/volume",
+                method="POST",
+                json_body={"volume": v},
+            )
+            assert s == 200, f"volume POST failed: {s}"
+        time.sleep(0.3)
+        b = get_bot(bot_id)
+        assert b["volume"] == 1, f"final volume wrong: {b['volume']}"
+    run("rapid volume changes converge", t_rapid_volume_change)
+
+
+def group_websocket(bot_id: str):
+    print("\n== websocket broadcasts ==")
+    try:
+        from websocket import create_connection
+    except Exception as e:
+        skip("websocket state broadcasts", f"websocket lib unavailable: {e}")
+        return
+
+    try:
+        ws = create_connection("ws://localhost:3000/ws", timeout=5)
+    except Exception as e:
+        skip("websocket state broadcasts", f"connect failed: {e}")
+        return
+
+    ws.settimeout(0.3)
+    messages: list[dict] = []
+    stop_reader = threading.Event()
+
+    def reader():
+        while not stop_reader.is_set():
+            try:
+                raw = ws.recv()
+                if not raw:
+                    break
+                try:
+                    messages.append(json.loads(raw))
+                except Exception:
+                    pass
+            except Exception:
+                # recv() timeout or closed — keep trying until stop_reader
+                if stop_reader.is_set():
+                    break
+                continue
+
+    reader_thread = threading.Thread(target=reader, daemon=True)
+    reader_thread.start()
+
+    try:
+        def t_init():
+            time.sleep(0.6)
+            types = [m.get("type") for m in messages]
+            assert "init" in types, f"no init message; got: {types}"
+        run("init message on connect", t_init)
+
+        def t_state_change_on_play():
+            assert_started(bot_id)
+            messages.clear()
+            api(
+                f"/api/player/{bot_id}/play",
+                method="POST",
+                json_body={"query": "the mass", "platform": "netease"},
+            )
+            time.sleep(1.5)
+            types = [m.get("type") for m in messages]
+            assert "stateChange" in types, (
+                f"no stateChange after play; got types: {types}"
+            )
+            api(f"/api/player/{bot_id}/stop", method="POST")
+        run("stateChange broadcast on play", t_state_change_on_play)
+
+        def t_bot_disconnected_event():
+            assert_started(bot_id)
+            messages.clear()
+            api(f"/api/bot/{bot_id}/stop", method="POST")
+            time.sleep(1.5)
+            types = [m.get("type") for m in messages]
+            assert "botDisconnected" in types or "stateChange" in types, (
+                f"no disconnect event; got: {types}"
+            )
+        run("botDisconnected event on stop", t_bot_disconnected_event)
+    finally:
+        stop_reader.set()
+        try:
+            ws.close()
+        except Exception:
+            pass
+
+
+# ----------------------------- main ----------------------------------------
+
+
+def main() -> int:
+    _, data = api("/api/bot/")
+    if not isinstance(data, dict) or not data.get("bots"):
+        print("[fatal] no bots registered — create one via the WebUI first")
+        return 2
+
+    target = data["bots"][0]
+    bot_id = target["id"]
+    initial_connected = target["connected"]
+    initial_volume = target["volume"]
+    initial_mode = target["playMode"]
+
+    print(f"[init] target bot  = {bot_id[:8]}  ({target['name']})")
+    print(
+        f"[init] initial state: connected={initial_connected} "
+        f"volume={initial_volume} mode={initial_mode}"
+    )
+
+    try:
+        # Read-only / no-lifecycle groups first — they don't consume TS3
+        # anti-flood budget.
+        group_infrastructure(bot_id)
+        group_auth_status()
+        group_search()
+
+        # Lifecycle-heavy groups — interleave with small breathers so the
+        # TS3 server's per-IP reconnect limit doesn't start throttling us.
+        group_lifecycle(bot_id)
+        time.sleep(ANTIFLOOD_BREATHER)
+
+        group_playback(bot_id)
+        time.sleep(ANTIFLOOD_BREATHER)
+
+        group_queue_ops(bot_id)
+        time.sleep(ANTIFLOOD_BREATHER)
+
+        group_input_validation(bot_id)
+        group_disconnect_corners(bot_id)
+        group_seek(bot_id)
+        time.sleep(ANTIFLOOD_BREATHER)
+
+        group_races(bot_id)
+        # Extra breather before websocket group — races is the heaviest
+        # consumer of TS3 reconnect budget (disconnect-during-connect and
+        # stop-during-url-resolve each burn one cycle), and the websocket
+        # group needs a clean reconnect to observe live state broadcasts.
+        time.sleep(ANTIFLOOD_BREATHER * 3)
+
+        group_websocket(bot_id)
+    finally:
+        # Restore initial state — this runs even if a test raised
+        try:
+            api(
+                f"/api/player/{bot_id}/volume",
+                method="POST",
+                json_body={"volume": initial_volume},
+            )
+            api(
+                f"/api/player/{bot_id}/mode",
+                method="POST",
+                json_body={"mode": initial_mode},
+            )
+            api(f"/api/player/{bot_id}/stop", method="POST")
+            if initial_connected:
+                start_and_wait(bot_id)
+            else:
+                stop_and_wait(bot_id)
+        except Exception as e:
+            print(f"[warn] restore failed: {e}")
+
+    print()
+    print("=" * 60)
+    print(f"  PASSED:  {passed}")
+    print(f"  FAILED:  {failed}")
+    print(f"  SKIPPED: {skipped}")
+    print("=" * 60)
+
+    if failed > 0:
+        print("\nFailed tests:")
+        for r in results:
+            if r.status in ("FAIL", "ERROR"):
+                print(f"  [{r.status}] {r.name}: {r.detail}")
+
+    return 0 if failed == 0 else 1
+
+
+if __name__ == "__main__":
+    import sys
+
+    sys.exit(main())
@@ -0,0 +1,166 @@
+"""More corner-case regressions.
+
+A. resolveAndPlay disconnect-during-URL-resolve race
+   The bot checks !this.connected at the top of resolveAndPlay, but the
+   URL-resolve await can take several seconds. If stop is called during
+   that window, playback would previously start on a disconnected bot.
+
+B. /seek NaN/Infinity rejection
+   typeof NaN === "number" and NaN < 0 is false, so a plain range check
+   leaks NaN through and corrupts seekOffset / getElapsed.
+"""
+import threading
+import time
+import requests
+
+BASE = "http://localhost:3000"
+
+
+def api(path, method="GET", **kw):
+    return getattr(requests, method.lower())(f"{BASE}{path}", timeout=30, **kw)
+
+
+def get_bot(bot_id):
+    return next(b for b in api("/api/bot/").json()["bots"] if b["id"] == bot_id)
+
+
+def wait_connected(bot_id, want, timeout=15):
+    end = time.time() + timeout
+    while time.time() < end:
+        if get_bot(bot_id)["connected"] is want:
+            return True
+        time.sleep(0.15)
+    return False
+
+
+def test_resolve_play_stop_race(bot_id):
+    """Fire stopBot during the /play call's URL resolve window."""
+    api(f"/api/bot/{bot_id}/stop", method="POST")
+    wait_connected(bot_id, False)
+    time.sleep(1)
+    api(f"/api/bot/{bot_id}/start", method="POST")
+    wait_connected(bot_id, True)
+
+    # Schedule a stop 150ms into the play call — that lands inside the
+    # provider.getSongUrl await, which is where the race lives.
+    def delayed_stop():
+        time.sleep(0.15)
+        try:
+            api(f"/api/bot/{bot_id}/stop", method="POST")
+        except Exception:
+            pass
+
+    threading.Thread(target=delayed_stop, daemon=True).start()
+
+    try:
+        api(
+            f"/api/player/{bot_id}/play",
+            method="POST",
+            json={"query": "the mass", "platform": "netease"},
+        )
+    except Exception:
+        pass
+
+    # Give both calls time to settle fully
+    time.sleep(3)
+    b = get_bot(bot_id)
+    # Key invariant: we never want connected=false AND playing=true. That
+    # pair is the exact Bug C symptom and would indicate the resolveAndPlay
+    # post-await check didn't fire.
+    assert not (b["connected"] is False and b["playing"] is True), (
+        f"inconsistent state after race: {b}"
+    )
+    print(
+        f"[PASS] resolveAndPlay stop-race — final state consistent "
+        f"(connected={b['connected']} playing={b['playing']})"
+    )
+
+
+def test_seek_nan_rejected(bot_id):
+    """Verify that NaN and Infinity seek positions are rejected at the API
+    layer (instead of poisoning seekOffset)."""
+    api(f"/api/bot/{bot_id}/stop", method="POST")
+    wait_connected(bot_id, False)
+    api(f"/api/bot/{bot_id}/start", method="POST")
+    wait_connected(bot_id, True)
+
+    # Start a real song so there is an active playback to seek against
+    api(
+        f"/api/player/{bot_id}/play",
+        method="POST",
+        json={"query": "the mass", "platform": "netease"},
+    )
+    time.sleep(1.2)
+
+    # JSON spec doesn't allow NaN/Infinity literals, but Python's json
+    # encoder emits them as bare tokens when allow_nan=True (the default).
+    # Express's body-parser rejects them as invalid JSON, which itself is
+    # a form of rejection. We additionally verify that sending a string
+    # "NaN" or a negative value is also rejected with a clean 400.
+    r = api(
+        f"/api/player/{bot_id}/seek",
+        method="POST",
+        json={"position": -5},
+    )
+    assert r.status_code == 400, f"negative seek should be rejected, got {r.status_code}"
+
+    r = api(
+        f"/api/player/{bot_id}/seek",
+        method="POST",
+        json={"position": "fifty"},
+    )
+    assert r.status_code == 400, f"string seek should be rejected, got {r.status_code}"
+
+    # Directly send NaN in raw body (body-parser will likely 400 it)
+    r = requests.post(
+        f"{BASE}/api/player/{bot_id}/seek",
+        data='{"position": NaN}',
+        headers={"Content-Type": "application/json"},
+        timeout=10,
+    )
+    assert r.status_code >= 400, f"NaN seek should be rejected, got {r.status_code}"
+
+    # After the junk attempts, a valid seek still works and the elapsed
+    # time is a finite number (not NaN).
+    r = api(
+        f"/api/player/{bot_id}/seek",
+        method="POST",
+        json={"position": 30},
+    )
+    assert r.status_code == 200, f"valid seek failed: {r.text[:120]}"
+
+    elapsed_resp = api(f"/api/player/{bot_id}/elapsed")
+    elapsed = elapsed_resp.json().get("elapsed")
+    assert elapsed is not None and isinstance(elapsed, (int, float)), (
+        f"elapsed should be a number, got {elapsed}"
+    )
+    # Could be exactly 30 or a tiny bit more if a frame has advanced
+    assert 29 <= elapsed < 40, f"elapsed after seek(30) out of range: {elapsed}"
+    print(f"[PASS] seek NaN/Infinity rejected; valid seek produces finite elapsed={elapsed:.2f}")
+
+
+def main():
+    bots = api("/api/bot/").json()["bots"]
+    if not bots:
+        print("[skip] no bots")
+        return
+    bot_id = bots[0]["id"]
+    initial = bots[0]["connected"]
+    print(f"[init] bot={bot_id[:8]} initial connected={initial}")
+
+    try:
+        test_resolve_play_stop_race(bot_id)
+        test_seek_nan_rejected(bot_id)
+        print("ALL GREEN")
+    finally:
+        if initial:
+            api(f"/api/bot/{bot_id}/start", method="POST")
+            wait_connected(bot_id, True)
+        else:
+            api(f"/api/bot/{bot_id}/stop", method="POST")
+            wait_connected(bot_id, False)
+        print(f"[restore] connected={get_bot(bot_id)['connected']}")
+
+
+if __name__ == "__main__":
+    main()
@@ -0,0 +1,212 @@
+"""Stress-test two bots playing music concurrently on the same TS server.
+
+Creates two temporary bots (or reuses existing named ones), starts them,
+plays music on both, and polls /api/bot/ every 2 seconds to detect when
+(if) either bot disconnects or stops playing. Cleans up on exit.
+
+Usage:
+    python scripts/test_multibot.py --minutes 3
+    python scripts/test_multibot.py --minutes 10 --host 127.0.0.1 --port 9987
+"""
+import argparse
+import sys
+import time
+from dataclasses import dataclass
+
+import requests
+
+API = "http://localhost:3000"
+POLL_INTERVAL = 2.0
+TEST_BOT_NAMES = ("mbtest1", "mbtest2")
+TEST_BOT_NICKS = ("MBTest1", "MBTest2")
+QUERIES = ("the mass", "lofi")  # one different song per bot
+
+
+@dataclass
+class BotSnapshot:
+    t: float
+    connected: bool
+    playing: bool
+    song: str | None
+
+
+def api_get(path: str):
+    r = requests.get(f"{API}{path}", timeout=5)
+    r.raise_for_status()
+    return r.json()
+
+
+def api_post(path: str, json=None):
+    r = requests.post(f"{API}{path}", json=json, timeout=15)
+    r.raise_for_status()
+    return r.json()
+
+
+def api_delete(path: str):
+    r = requests.delete(f"{API}{path}", timeout=10)
+    r.raise_for_status()
+    return r.json()
+
+
+def cleanup_existing(names: tuple[str, ...]) -> None:
+    bots = api_get("/api/bot/")["bots"]
+    for b in bots:
+        if b["name"] in names:
+            try:
+                api_post(f"/api/player/{b['id']}/stop")
+            except Exception:
+                pass
+            try:
+                api_delete(f"/api/bot/{b['id']}")
+                print(f"[cleanup] removed existing bot {b['name']} ({b['id']})")
+            except Exception as e:
+                print(f"[cleanup] failed to remove {b['name']}: {e}")
+
+
+def create_bot(name: str, nickname: str, host: str, port: int) -> str:
+    res = api_post(
+        "/api/bot/",
+        json={
+            "name": name,
+            "serverAddress": host,
+            "serverPort": port,
+            "nickname": nickname,
+            "autoStart": False,
+        },
+    )
+    bot_id = res["id"]
+    print(f"[create] {name} -> {bot_id}")
+    return bot_id
+
+
+def start_bot(bot_id: str) -> None:
+    api_post(f"/api/bot/{bot_id}/start")
+
+
+def play(bot_id: str, query: str) -> None:
+    api_post(f"/api/player/{bot_id}/play", json={"query": query, "platform": "netease"})
+
+
+def snapshot(bot_id: str, t0: float) -> BotSnapshot:
+    bots = api_get("/api/bot/")["bots"]
+    b = next((x for x in bots if x["id"] == bot_id), None)
+    if not b:
+        return BotSnapshot(time.time() - t0, False, False, None)
+    song = b["currentSong"]["name"] if b.get("currentSong") else None
+    return BotSnapshot(time.time() - t0, b["connected"], b["playing"], song)
+
+
+def run(minutes: float, host: str, port: int) -> int:
+    print(f"[setup] duration={minutes}min host={host}:{port}")
+
+    cleanup_existing(TEST_BOT_NAMES)
+
+    bot_ids = [
+        create_bot(TEST_BOT_NAMES[0], TEST_BOT_NICKS[0], host, port),
+        create_bot(TEST_BOT_NAMES[1], TEST_BOT_NICKS[1], host, port),
+    ]
+
+    # Start both, allowing a small stagger to avoid handshake collision
+    for i, bid in enumerate(bot_ids):
+        start_bot(bid)
+        print(f"[start] bot{i+1} started")
+        time.sleep(1.5)
+
+    # Wait until both are connected (or bail after 15s)
+    deadline = time.time() + 15
+    while time.time() < deadline:
+        bots = {b["id"]: b for b in api_get("/api/bot/")["bots"]}
+        if all(bots[b]["connected"] for b in bot_ids):
+            print("[start] both bots connected")
+            break
+        time.sleep(0.5)
+    else:
+        print("[fatal] bots did not both come online in 15s")
+        cleanup_existing(TEST_BOT_NAMES)
+        return 2
+
+    # Kick off playback on both
+    for i, bid in enumerate(bot_ids):
+        play(bid, QUERIES[i])
+        print(f"[play] bot{i+1} -> {QUERIES[i]!r}")
+
+    t0 = time.time()
+    end = t0 + minutes * 60
+    first_drop: dict[str, float] = {}
+    last_state: dict[str, BotSnapshot] = {}
+
+    print(f"[monitor] polling every {POLL_INTERVAL}s for {minutes} min...")
+    print(f"{'time':>7}  {'bot1':<40}  {'bot2':<40}")
+
+    def fmt(snap: BotSnapshot) -> str:
+        flag = ("C" if snap.connected else "-") + ("P" if snap.playing else "-")
+        song = (snap.song or "").replace("\n", " ")[:30]
+        return f"{flag} {song}"
+
+    try:
+        while time.time() < end:
+            snaps = [snapshot(bid, t0) for bid in bot_ids]
+            elapsed = int(time.time() - t0)
+            row = f"{elapsed:>6}s  {fmt(snaps[0]):<40}  {fmt(snaps[1]):<40}"
+            # Only print when state changes or every 10s
+            changed = False
+            for bid, s in zip(bot_ids, snaps):
+                prev = last_state.get(bid)
+                if (prev is None
+                        or prev.connected != s.connected
+                        or prev.playing != s.playing
+                        or prev.song != s.song):
+                    changed = True
+                last_state[bid] = s
+                if not s.connected and bid not in first_drop:
+                    first_drop[bid] = s.t
+            if changed or elapsed % 10 == 0:
+                print(row)
+
+            # If both stopped playing but are still connected, re-queue the same song
+            for i, (bid, s) in enumerate(zip(bot_ids, snaps)):
+                if s.connected and not s.playing:
+                    try:
+                        play(bid, QUERIES[i])
+                    except Exception as e:
+                        print(f"[warn] re-play bot{i+1} failed: {e}")
+
+            time.sleep(POLL_INTERVAL)
+    except KeyboardInterrupt:
+        print("\n[abort] interrupted")
+
+    # Summary
+    total = time.time() - t0
+    print()
+    print("=" * 60)
+    print(f"Total observed time: {total:.1f}s")
+    for i, bid in enumerate(bot_ids):
+        drop = first_drop.get(bid)
+        if drop is None:
+            print(f"  bot{i+1} ({TEST_BOT_NICKS[i]}): stayed connected the whole run")
+        else:
+            print(f"  bot{i+1} ({TEST_BOT_NICKS[i]}): FIRST DISCONNECT at t+{drop:.1f}s")
+    print("=" * 60)
+
+    # Cleanup
+    cleanup_existing(TEST_BOT_NAMES)
+    print("[cleanup] done")
+
+    return 0 if not first_drop else 1
+
+
+def main() -> int:
+    p = argparse.ArgumentParser()
+    p.add_argument("--minutes", type=float, default=3.0)
+    p.add_argument("--host", default="127.0.0.1")
+    p.add_argument("--port", type=int, default=9987)
+    args = p.parse_args()
+    try:
+        return run(args.minutes, args.host, args.port)
+    except requests.HTTPError as e:
+        print(f"[http-error] {e} body={e.response.text[:200] if e.response else ''}")
+        return 3
+
+
+if __name__ == "__main__":
+    sys.exit(main())
@@ -0,0 +1,119 @@
+"""Reproduce / regression-check the player-bar-not-appearing bug.
+
+Captures the bot's initial playback state and restores it on exit so the
+test never leaves the user with surprise music or a cleared queue.
+"""
+import time
+import requests
+from playwright.sync_api import sync_playwright
+
+BASE = "http://localhost:3000"
+
+
+def api(path, method="GET", **kw):
+    fn = getattr(requests, method.lower())
+    r = fn(f"{BASE}{path}", timeout=10, **kw)
+    r.raise_for_status()
+    return r.json() if r.text else None
+
+
+def get_bot(bot_id):
+    return next(b for b in api("/api/bot/")["bots"] if b["id"] == bot_id)
+
+
+def capture_state(bot_id):
+    b = get_bot(bot_id)
+    return {
+        "playing": b["playing"],
+        "paused": b["paused"],
+        "song": (b["currentSong"] or {}).get("name"),
+    }
+
+
+def main():
+    bots = api("/api/bot/")["bots"]
+    if not bots:
+        print("[skip] no bots")
+        return
+    bot_id = bots[0]["id"]
+    initial = capture_state(bot_id)
+    print(f"[init] initial state: {initial}")
+
+    try:
+        # Clear slate
+        api(f"/api/player/{bot_id}/stop", method="POST")
+        time.sleep(0.6)
+
+        with sync_playwright() as p:
+            browser = p.chromium.launch(headless=True)
+            try:
+                ctx = browser.new_context()
+                ctx.add_init_script(
+                    """
+                    (() => {
+                      const OrigWS = window.WebSocket;
+                      window.__wsMessages = [];
+                      window.WebSocket = function(...args) {
+                        const ws = new OrigWS(...args);
+                        ws.addEventListener('message', (ev) => {
+                          try {
+                            const d = JSON.parse(ev.data);
+                            window.__wsMessages.push({type: d.type, botId: d.botId});
+                          } catch(e) {}
+                        });
+                        return ws;
+                      };
+                      Object.assign(window.WebSocket, OrigWS);
+                    })();
+                    """
+                )
+                page = ctx.new_page()
+                page.goto(BASE)
+                page.wait_for_load_state("networkidle")
+                time.sleep(0.8)
+
+                assert page.locator(".player-wrapper").count() == 0, (
+                    "player bar should be hidden before playback"
+                )
+
+                # Trigger play via API (simulates any play trigger)
+                api(
+                    f"/api/player/{bot_id}/play",
+                    method="POST",
+                    json={"query": "the mass", "platform": "netease"},
+                )
+
+                # Poll for up to 6s to see if player bar appears automatically
+                appeared_at = None
+                for i in range(60):
+                    if page.locator(".player-wrapper").count() > 0:
+                        appeared_at = i * 0.1
+                        break
+                    page.wait_for_timeout(100)
+
+                if appeared_at is None:
+                    msgs = page.evaluate("() => window.__wsMessages")
+                    print(f"[FAIL] player bar never appeared; WS msgs: {msgs}")
+                    raise AssertionError("player bar did not auto-show on stateChange")
+                print(f"[PASS] player bar appeared after {appeared_at:.1f}s")
+            finally:
+                browser.close()
+    finally:
+        # Restore: stop the "test" song we triggered, then re-apply initial
+        # state as best we can. We can't re-queue the user's previous song,
+        # but we can at least stop ours and leave the bot idle if it was idle.
+        try:
+            api(f"/api/player/{bot_id}/stop", method="POST")
+        except Exception as e:
+            print(f"[warn] failed to stop test song on cleanup: {e}")
+        post = capture_state(bot_id)
+        print(f"[restore] bot now idle (was playing={initial['playing']} song={initial['song']!r})")
+        if initial["playing"] and initial["song"]:
+            print(
+                f"[note] initial bot was playing {initial['song']!r}; "
+                "this test cannot resume arbitrary tracks — you may need to restart playback"
+            )
+
+
+if __name__ == "__main__":
+    main()
@@ -0,0 +1,100 @@
+"""E2E: the new power button in the Bot Selector dropdown toggles bot connected state.
+
+Captures the target bot's initial connected state and restores it on exit
+(including on assertion failure), so running this test never pollutes the
+user's current bot setup.
+"""
+import time
+import requests
+from playwright.sync_api import sync_playwright
+
+BASE = "http://localhost:3000"
+
+
+def get_bot(bot_id):
+    return next(b for b in requests.get(f"{BASE}/api/bot/").json()["bots"] if b["id"] == bot_id)
+
+
+def wait_for_connected(bot_id, want: bool, timeout_s: float = 12.0) -> bool:
+    deadline = time.time() + timeout_s
+    while time.time() < deadline:
+        if get_bot(bot_id)["connected"] is want:
+            return True
+        time.sleep(0.2)
+    return False
+
+
+def set_connected(bot_id, want: bool) -> None:
+    """Force the bot into the given connected state via API."""
+    current = get_bot(bot_id)["connected"]
+    if current == want:
+        return
+    endpoint = "start" if want else "stop"
+    requests.post(f"{BASE}/api/bot/{bot_id}/{endpoint}")
+    wait_for_connected(bot_id, want)
+
+
+def main():
+    bots = requests.get(f"{BASE}/api/bot/").json()["bots"]
+    if not bots:
+        print("[skip] no bots registered, nothing to test")
+        return
+    target = bots[0]
+    bot_id = target["id"]
+    initial_connected = target["connected"]
+    print(f"[init] target bot {target['name']} ({bot_id[:8]}), initial connected={initial_connected}")
+
+    try:
+        # Force bot disconnected before the test
+        set_connected(bot_id, False)
+        assert not get_bot(bot_id)["connected"], "bot should be disconnected at start"
+
+        with sync_playwright() as p:
+            browser = p.chromium.launch(headless=True)
+            try:
+                page = browser.new_page(viewport={"width": 1440, "height": 900})
+                page.goto(BASE)
+                page.wait_for_load_state("networkidle")
+                time.sleep(0.6)
+
+                # Open dropdown
+                page.locator(".bot-selector-btn").click()
+                page.wait_for_selector(".bot-power-btn")
+
+                # Click the power button to start
+                page.locator(".bot-power-btn").first.click()
+                print("[ui] clicked power (start)")
+
+                assert wait_for_connected(bot_id, True), "bot should be connected after clicking start"
+                print("[api] bot connected = True")
+
+                # Let UI catch up via WS then re-open the dropdown to re-check class
+                time.sleep(1.0)
+                page.locator(".bot-selector-btn").click()  # close
+                time.sleep(0.2)
+                page.locator(".bot-selector-btn").click()  # reopen
+                page.wait_for_selector(".bot-power-btn.online", timeout=3000)
+                print("[ui] power button now shows .online class")
+
+                # Click again to stop
+                page.locator(".bot-power-btn.online").first.click()
+                print("[ui] clicked power (stop)")
+
+                assert wait_for_connected(bot_id, False), "bot should be disconnected after clicking stop"
+                print("[api] bot connected = False")
+
+                print("[PASS] power button toggles bot connection")
+            finally:
+                browser.close()
+    finally:
+        # Always restore the initial state so the test never leaves the bot
+        # in an unexpected place
+        set_connected(bot_id, initial_connected)
+        final = get_bot(bot_id)["connected"]
+        print(f"[restore] bot connected={final} (initial was {initial_connected})")
+        if final != initial_connected:
+            print("[warn] failed to restore initial connected state")
+
+
+if __name__ == "__main__":
+    main()
@@ -0,0 +1,130 @@
+"""Regression for the 'connected=False but playing=True' stuck-state bug.
+
+After rapid disconnect/reconnect, the library could drop the connection
+(TS3 server anti-flood or a hung handshake). The bot then ended up in an
+inconsistent state: player.state='playing' but tsClient disconnected.
+
+This test verifies three fixes:
+  Bug A — startBot() has a 15s timeout instead of hanging forever on a
+          stalled handshake. /start returns a clean 500 instead of blocking.
+  Bug B — play/add/etc commands are rejected when the bot is not connected.
+  Bug C — the tsClient 'disconnected' handler always clears player state,
+          even when connect() never completed (so !this.connected).
+
+We also sanity-check that the bot recovers (can start a fresh cycle) after
+a transient failure.
+"""
+import time
+import requests
+
+BASE = "http://localhost:3000"
+
+
+def api(path, method="GET", **kw):
+    return getattr(requests, method.lower())(f"{BASE}{path}", timeout=30, **kw)
+
+
+def get_bot(bot_id):
+    return next(b for b in api("/api/bot/").json()["bots"] if b["id"] == bot_id)
+
+
+def wait_connected(bot_id, want, timeout=15):
+    end = time.time() + timeout
+    while time.time() < end:
+        if get_bot(bot_id)["connected"] is want:
+            return True
+        time.sleep(0.15)
+    return False
+
+
+def main():
+    bots = api("/api/bot/").json()["bots"]
+    if not bots:
+        print("[skip] no bots")
+        return
+    bot_id = bots[0]["id"]
+    initial_connected = bots[0]["connected"]
+    print(f"[init] bot={bot_id[:8]} initial connected={initial_connected}")
+
+    try:
+        # Start from a clean slate
+        api(f"/api/bot/{bot_id}/stop", method="POST")
+        wait_connected(bot_id, False)
+
+        # --- Bug B: play while disconnected must be rejected ---
+        r = api(
+            f"/api/player/{bot_id}/play",
+            method="POST",
+            json={"query": "rejection test", "platform": "netease"},
+        )
+        assert r.status_code >= 400, (
+            f"play while disconnected should fail, got {r.status_code} {r.text[:120]}"
+        )
+        assert "not connected" in r.text.lower(), (
+            f"expected 'not connected' error, got: {r.text[:200]}"
+        )
+        b = get_bot(bot_id)
+        assert not b["playing"], f"player shouldn't be playing after rejected /play: {b}"
+        print("[PASS] Bug B — /play rejected while bot disconnected; state untouched")
+
+        # --- Bug C: normal start→play→stop leaves player state clean ---
+        r = api(f"/api/bot/{bot_id}/start", method="POST")
+        assert r.status_code == 200, f"start failed {r.text[:120]}"
+        assert wait_connected(bot_id, True), "bot did not connect within 15s"
+
+        r = api(
+            f"/api/player/{bot_id}/play",
+            method="POST",
+            json={"query": "the mass", "platform": "netease"},
+        )
+        assert r.status_code == 200, f"play failed {r.text[:120]}"
+        time.sleep(1.2)
+        b = get_bot(bot_id)
+        assert b["connected"] and b["playing"], f"should be connected+playing: {b}"
+
+        api(f"/api/bot/{bot_id}/stop", method="POST")
+        assert wait_connected(bot_id, False, timeout=5), "bot did not disconnect"
+        b = get_bot(bot_id)
+        assert not b["playing"], (
+            f"player should have stopped after bot disconnect (Bug C): {b}"
+        )
+        print("[PASS] Bug C — stop clears both connected and playing state")
+
+        # --- Bug A: startBot has a deadline and returns a clean error if connect hangs ---
+        # We can't easily force a hang in-process, but we can sanity-check that
+        # startBot returns promptly (well under the 15s cap) on a normal run.
+        t0 = time.time()
+        r = api(f"/api/bot/{bot_id}/start", method="POST")
+        elapsed = time.time() - t0
+        assert r.status_code == 200, f"start failed {r.text[:120]}"
+        assert elapsed < 10, f"start should be prompt, took {elapsed:.1f}s"
+        assert wait_connected(bot_id, True), "bot did not connect"
+        print(
+            f"[PASS] Bug A — startBot completed in {elapsed:.2f}s "
+            "(deadline is 15s, would throw on hang)"
+        )
+
+        # --- Recovery: after any failure, another start should work ---
+        api(f"/api/bot/{bot_id}/stop", method="POST")
+        wait_connected(bot_id, False)
+        # Give TS3 server a moment to forget us (anti-flood grace)
+        time.sleep(2)
+        r = api(f"/api/bot/{bot_id}/start", method="POST")
+        assert r.status_code == 200, f"recovery start failed {r.text[:120]}"
+        assert wait_connected(bot_id, True), "bot did not recover"
+        print("[PASS] recovery — bot reconnects cleanly after a cycle")
+
+        print("ALL GREEN")
+
+    finally:
+        if initial_connected:
+            api(f"/api/bot/{bot_id}/start", method="POST")
+            wait_connected(bot_id, True)
+        else:
+            api(f"/api/bot/{bot_id}/stop", method="POST")
+            wait_connected(bot_id, False)
+        print(f"[restore] bot connected={get_bot(bot_id)['connected']} (was {initial_connected})")
+
+
+if __name__ == "__main__":
+    main()
@@ -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,20 +35,16 @@ function ffmpegWorks(bin: string): boolean {
  }
 }

-/** Resolved once at module load — prefer bundled ffmpeg-static, fall back to system. */
 const resolvedFfmpeg: string = (() => {
-  if (ffmpegPath && isExecutable(ffmpegPath) && ffmpegWorks(ffmpegPath)) {
-    return ffmpegPath;
+  if (ffmpegWorks("ffmpeg")) return "ffmpeg";
+  const isWinPath = ffmpegPath ? /\\/.test(ffmpegPath) || ffmpegPath.endsWith(".exe") : false;
+  const onWindows = process.platform === "win32";
+  if (ffmpegPath && (onWindows === isWinPath)) {
+    if (isExecutable(ffmpegPath) && ffmpegWorks(ffmpegPath)) return ffmpegPath;
  }
-  // Fall back to system ffmpeg
-  if (ffmpegWorks("ffmpeg")) {
-    return "ffmpeg";
-  }
-  // Last resort: return whatever we have, will fail at runtime with clear error
-  return ffmpegPath ?? "ffmpeg";
+  return "ffmpeg";
 })();

-/** Resolve ffmpeg binary: prefer bundled ffmpeg-static, fall back to system PATH. */
 function getFfmpegCommand(): string {
  return resolvedFfmpeg;
 }
@@ -74,11 +70,16 @@ 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_LOW_WATER = 480 * 1024;  // ~2.5s
+  private static readonly BUFFER_HIGH_WATER = 640 * 1024;
+  private static readonly BUFFER_LOW_WATER = 256 * 1024;
  private ffmpegPaused = false;
+  private spawnFailed = false;
+  private consecutiveFailures = 0;
+  private static readonly MAX_CONSECUTIVE_FAILURES = 3;
+  private healthyFrames = 0;
+  private static readonly HEALTHY_FRAME_RESET = 50; // ~1 second of audio

  constructor(logger: Logger) {
    super();
@@ -87,90 +88,127 @@ export class AudioPlayer extends EventEmitter {
  }

  play(url: string, seekSeconds = 0): void {
+    // 1. 停止当前所有播放，自增 sessionId 屏蔽旧回调 （
    this.stop();
-    this.sessionId++;
-    const playSessionId = this.sessionId;
+
+    const currentSessionId = this.sessionId; 
    this.currentUrl = url;
    this.seekOffset = seekSeconds;
    this.framesPlayed = 0;
+    this.healthyFrames = 0;
    this.ffmpegPaused = false;
+    this.spawnFailed = false;

-    this.logger.info({ url: url.slice(0, 80), seek: seekSeconds }, "Starting playback");
+    if (this.consecutiveFailures >= AudioPlayer.MAX_CONSECUTIVE_FAILURES) {
+      this.logger.error({ failures: this.consecutiveFailures }, "FFmpeg failures limit reached");
+      this.state = "idle";
+      this.emit("error", new Error("ffmpeg unavailable"));
+      return;
+    }

    const args: string[] = [];
-
-    // BiliBili CDN requires Referer header for audio playback
    if (url.includes("bilivideo") || url.includes("bilibili")) {
-      args.push(
-        "-headers",
-        "Referer: https://www.bilibili.com\r\nUser-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36\r\n"
-      );
+      args.push("-headers", "Referer: https://www.bilibili.com\r\nUser-Agent: Mozilla/5.0...\r\n");
    }
-
-    args.push(
-      "-reconnect", "1",
-      "-reconnect_streamed", "1",
-      "-reconnect_delay_max", "5",
-    );
-    if (seekSeconds > 0) {
-      args.push("-ss", String(seekSeconds));
-    }
-    args.push(
-      "-i", url,
-      "-f", "s16le",
-      "-ar", "48000",
-      "-ac", "2",
-      "-acodec", "pcm_s16le",
-      "-",
-    );
+    args.push("-reconnect", "1", "-reconnect_streamed", "1", "-reconnect_delay_max", "5");
+    if (seekSeconds > 0) args.push("-ss", String(seekSeconds));
+    args.push("-i", url, "-f", "s16le", "-ar", "48000", "-ac", "2", "-acodec", "pcm_s16le", "-");

    const ffmpegBin = getFfmpegCommand();
-    this.logger.info({ ffmpeg: ffmpegBin }, "Using ffmpeg binary");
    this.ffmpeg = spawn(ffmpegBin, args, { stdio: ["ignore", "pipe", "pipe"] });
+    
+    const currentPid = this.ffmpeg.pid;
+    if (currentPid) {
+      globalActivePids.add(currentPid);
+      this.logger.debug({ pid: currentPid, sessionId: currentSessionId }, "FFmpeg spawned");
+    }

-    let gotFirstData = false;
    this.ffmpeg.stdout!.on("data", (chunk: Buffer) => {
-      if (!gotFirstData) {
-        gotFirstData = true;
-        this.logger.info({ bytes: chunk.length }, "FFmpeg: first PCM data received");
+      // 2. 严格校验 sessionId，防止老进程的数据混入新播放请求 （
+      if (this.sessionId !== currentSessionId) {
+        return;
      }
+
      this.pcmBuffer = Buffer.concat([this.pcmBuffer, chunk]);
-      // Backpressure: pause FFmpeg stdout when buffer is too large
      if (this.pcmBuffer.length > AudioPlayer.BUFFER_HIGH_WATER && !this.ffmpegPaused && this.ffmpeg?.stdout) {
        this.ffmpeg.stdout.pause();
        this.ffmpegPaused = true;
      }
    });

-    this.ffmpeg.on("close", (code, signal) => {
-      this.logger.info({ exitCode: code, signal, gotData: gotFirstData, framesPlayed: this.framesPlayed }, "FFmpeg process closed");
-      if (this.sessionId === playSessionId) {
-        this.ffmpeg = null; // Signal frame loop that no more data is coming
+    this.ffmpeg.on("exit", (code, signal) => {
+      if (currentPid) globalActivePids.delete(currentPid);
+      this.logger.info({ pid: currentPid, code, signal }, "FFmpeg exited");
+      
+      // 只有当前会话的进程结束才置空变量
+      if (this.sessionId === currentSessionId) {
+        this.ffmpeg = null;
      }
    });

    this.ffmpeg.on("error", (err) => {
-      this.logger.error({ err }, "FFmpeg error");
-      if (this.sessionId === playSessionId) {
+      if (this.sessionId === currentSessionId) {
+        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;
+    this.healthyFrames = 0;
+  }
+
+  private forceCleanup(proc: ChildProcess, pid: number): void {
+    if (!globalActivePids.has(pid)) return;
+
+    try {
+      proc.kill("SIGTERM");
+    } catch (e) { /* ignore */ }
+
+    const killTimeout = setTimeout(() => {
+      try {
+        process.kill(pid, 0); 
+        process.kill(pid, "SIGKILL");
+      } catch (e) {
+      } finally {
+        globalActivePids.delete(pid);
+      }
+    }, 1500);
+
+    proc.unref();
+    proc.once("exit", () => {
+      clearTimeout(killTimeout);
+      globalActivePids.delete(pid);
+    });
+  }
+
  private startFrameLoop(): void {
    if (this.frameLoopRunning) return;
    this.frameLoopRunning = true;
@@ -180,44 +218,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 - now);
+    const delay = Math.max(0, this.nextFrameTime - performance.now());

    setTimeout(() => {
-      // Discard callback from a stale play session
-      if (loopSessionId !== this.sessionId) return;
-      if (!this.frameLoopRunning) return;
+      // 这里的校验能防止旧的定时器回调处理新 Session 的逻辑 （
+      if (loopSessionId !== this.sessionId || !this.frameLoopRunning) return;

-      if (this.state === "playing") {
-        this.sendNextFrame();
-      } else if (this.state === "paused") {
-        this.nextFrameTime = performance.now();
-      }
+      if (this.state === "playing") this.sendNextFrame();
+      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";
-          this.emit("trackEnd");
+          if (!this.spawnFailed) {
+            this.consecutiveFailures = 0;
+            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;
@@ -228,88 +259,33 @@ 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");
+      this.healthyFrames++;
+      if (this.healthyFrames >= AudioPlayer.HEALTHY_FRAME_RESET) {
+        this.consecutiveFailures = 0;
+        this.healthyFrames = 0;
      }
    } 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);
-      sample = Math.round(sample * factor);
-      if (sample > 32767) sample = 32767;
-      else if (sample < -32768) sample = -32768;
-      out.writeInt16LE(sample, i);
+      let sample = Math.round(pcm.readInt16LE(i) * factor);
+      out.writeInt16LE(Math.max(-32768, Math.min(32767, 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;
-  }
-
-  seek(seconds: number): void {
-    if (!this.currentUrl) 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.state = "idle";
-    this.currentUrl = "";
-    this.seekOffset = 0;
-    this.framesPlayed = 0;
-  }
-
-  setVolume(vol: number): void {
-    this.volume = Math.max(0, Math.min(100, vol));
-  }
-
-  getVolume(): number {
-    return this.volume;
-  }
-
-  getState(): PlayerState {
-    return this.state;
-  }
-}
+  getElapsed(): number { return this.seekOffset + (this.framesPlayed * FRAME_DURATION_MS) / 1000; }
+  seek(seconds: number): void { if (this.currentUrl && Number.isFinite(seconds) && seconds >= 0) this.play(this.currentUrl, seconds); }
+  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; }
+  setVolume(vol: number): void { this.volume = Math.max(0, Math.min(100, vol)); }
+  getVolume(): number { return this.volume; }
+  getState(): PlayerState { return this.state; }
+}
@@ -89,6 +89,49 @@ describe("PlayQueue", () => {
    expect(queue.list()[1].id).toBe("3");
  });

+  it("removing a song before current shifts current index", () => {
+    queue.setMode(PlayMode.Sequential);
+    queue.add(makeSong("A"));
+    queue.add(makeSong("B"));
+    queue.add(makeSong("C"));
+    queue.playAt(2); // playing C at index 2
+    queue.remove(0); // remove A (before current)
+    expect(queue.current()?.id).toBe("C"); // still on C
+    expect(queue.getCurrentIndex()).toBe(1);
+  });
+
+  it("removing the currently-playing song lets next() advance to the shifted song", () => {
+    queue.setMode(PlayMode.Sequential);
+    queue.add(makeSong("A"));
+    queue.add(makeSong("B"));
+    queue.add(makeSong("C"));
+    queue.add(makeSong("D"));
+    queue.playAt(2); // playing C
+    queue.remove(2); // remove C — D shifts into slot 2
+    // Before the fix this returned null (D was silently skipped)
+    expect(queue.next()?.id).toBe("D");
+  });
+
+  it("removing the only song clears the queue", () => {
+    queue.add(makeSong("only"));
+    queue.playAt(0);
+    queue.remove(0);
+    expect(queue.size()).toBe(0);
+    expect(queue.current()).toBeNull();
+    expect(queue.next()).toBeNull();
+  });
+
+  it("removing the last song while playing it advances to null in sequential mode", () => {
+    queue.setMode(PlayMode.Sequential);
+    queue.add(makeSong("A"));
+    queue.add(makeSong("B"));
+    queue.playAt(1); // playing B (last)
+    queue.remove(1);
+    expect(queue.size()).toBe(1);
+    // currentIndex moved to 0, so next() should try to advance past the end
+    expect(queue.next()).toBeNull();
+  });
+
  it("clears all songs", () => {
    queue.add(makeSong("1"));
    queue.add(makeSong("2"));
@@ -107,6 +150,101 @@ describe("PlayQueue", () => {
    expect(next).not.toBeNull();
  });

+  it("random mode with single song returns null on next", () => {
+    queue.setMode(PlayMode.Random);
+    queue.add(makeSong("1"));
+    queue.play();
+    expect(queue.next()).toBeNull();
+  });
+
+  it("random mode plays each song exactly once then stops", () => {
+    queue.setMode(PlayMode.Random);
+    queue.add(makeSong("A"));
+    queue.add(makeSong("B"));
+    queue.add(makeSong("C"));
+    queue.play();
+    const played = new Set<string>();
+    played.add(queue.current()!.id);
+    for (let i = 0; i < 3; i++) {
+      const song = queue.next();
+      if (!song) break;
+      played.add(song.id);
+    }
+    // All 3 songs should have been played
+    expect(played).toEqual(new Set(["A", "B", "C"]));
+    // next() after all played should return null
+    expect(queue.next()).toBeNull();
+  });
+
+  it("random mode: removing currently-playing song does not skip others", () => {
+    queue.setMode(PlayMode.Random);
+    queue.add(makeSong("A"));
+    queue.add(makeSong("B"));
+    queue.add(makeSong("C"));
+    queue.add(makeSong("D"));
+    queue.play(); // plays A (index 0)
+    const second = queue.next()!; // plays some song
+    // Remove the currently-playing song
+    const curIdx = queue.getCurrentIndex();
+    queue.remove(curIdx);
+    // Remaining songs (excluding A and the removed song) should all be reachable
+    const played = new Set<string>();
+    played.add("A"); // already played via play()
+    played.add(second.id); // played and then removed
+    let song = queue.next();
+    while (song) {
+      played.add(song.id);
+      song = queue.next();
+    }
+    // All 4 original songs should have been played or accounted for
+    expect(played).toEqual(new Set(["A", "B", "C", "D"]));
+  });
+
+  it("random mode: prev does not cause duplicate plays", () => {
+    queue.setMode(PlayMode.Random);
+    queue.add(makeSong("A"));
+    queue.add(makeSong("B"));
+    queue.add(makeSong("C"));
+    queue.play(); // plays A
+    queue.next(); // plays B or C
+    queue.prev(); // go back — this song is now marked as played
+    // Exhaust remaining songs
+    const ids: string[] = [];
+    let song = queue.next();
+    while (song) {
+      ids.push(song.id);
+      song = queue.next();
+    }
+    // No song ID should appear more than once across the entire session
+    expect(new Set(ids).size).toBe(ids.length);
+  });
+
+  it("random mode: adding song mid-playback includes the new song", () => {
+    queue.setMode(PlayMode.Random);
+    queue.add(makeSong("A"));
+    queue.add(makeSong("B"));
+    queue.play(); // plays A
+    queue.next(); // plays B
+    // Add a new song while all existing songs have been played
+    queue.add(makeSong("C"));
+    const song = queue.next();
+    expect(song).not.toBeNull();
+    expect(song!.id).toBe("C");
+    // After C, should stop
+    expect(queue.next()).toBeNull();
+  });
+
+  it("random mode: setMode preserves current song as played", () => {
+    queue.add(makeSong("A"));
+    queue.add(makeSong("B"));
+    queue.play(); // plays A in sequential mode
+    queue.setMode(PlayMode.Random); // switch to random — A should be marked played
+    // next() should only return B, never A again
+    const song = queue.next();
+    expect(song?.id).toBe("B");
+    expect(queue.next()).toBeNull();
+  });
+
  it("random-loop mode never returns null", () => {
    queue.setMode(PlayMode.RandomLoop);
    queue.add(makeSong("1"));
@@ -123,4 +261,227 @@ describe("PlayQueue", () => {
    queue.playAt(2);
    expect(queue.current()?.id).toBe("3");
  });
+
+  describe("history-aware prev", () => {
+    it("walks back through played indices in random mode", () => {
+      queue.setMode(PlayMode.Random);
+      queue.add(makeSong("a"));
+      queue.add(makeSong("b"));
+      queue.add(makeSong("c"));
+      queue.add(makeSong("d"));
+      queue.add(makeSong("e"));
+
+      // Force a deterministic random sequence: a → c → e
+      queue.playAt(0);
+      queue.playAt(2);
+      queue.playAt(4);
+      expect(queue.current()?.id).toBe("e");
+
+      // prev pops back through history: e → c → a
+      expect(queue.prev()?.id).toBe("c");
+      expect(queue.prev()?.id).toBe("a");
+    });
+
+    it("returns null when history is empty in random mode", () => {
+      queue.setMode(PlayMode.Random);
+      queue.add(makeSong("a"));
+      queue.add(makeSong("b"));
+      queue.playAt(0);
+      // No further moves → history is empty (only 'a' is current, never pushed)
+      expect(queue.prev()).toBeNull();
+    });
+
+    it("preserves sequential prev when history is empty", () => {
+      queue.setMode(PlayMode.Sequential);
+      queue.add(makeSong("a"));
+      queue.add(makeSong("b"));
+      queue.add(makeSong("c"));
+      queue.play();
+      queue.next(); // currentIndex = 1
+      // Sequential next() pushed 0 to history → prev pops back to 0
+      expect(queue.prev()?.id).toBe("a");
+    });
+
+    it("clears history on play()", () => {
+      queue.setMode(PlayMode.Random);
+      queue.add(makeSong("a"));
+      queue.add(makeSong("b"));
+      queue.playAt(0);
+      queue.playAt(1);
+      queue.play(); // resets to index 0 and clears history
+      expect(queue.prev()).toBeNull();
+    });
+
+    it("clears history on clear()", () => {
+      queue.add(makeSong("a"));
+      queue.add(makeSong("b"));
+      queue.play();
+      queue.next();
+      queue.clear();
+      queue.add(makeSong("c"));
+      queue.play();
+      // History was wiped — no prev path available beyond index 0
+      expect(queue.prev()).toBeNull();
+    });
+
+    it("clears history on setMode()", () => {
+      queue.setMode(PlayMode.Sequential);
+      queue.add(makeSong("a"));
+      queue.add(makeSong("b"));
+      queue.play();
+      queue.next();
+      // Mode change resets context
+      queue.setMode(PlayMode.Random);
+      expect(queue.prev()).toBeNull();
+    });
+
+    it("drops history entries pointing at a removed song", () => {
+      queue.setMode(PlayMode.Random);
+      queue.add(makeSong("a"));
+      queue.add(makeSong("b"));
+      queue.add(makeSong("c"));
+      queue.playAt(0);
+      queue.playAt(1); // history: [0]
+      queue.playAt(2); // history: [0, 1]
+      // Remove song at index 1 → history entry 1 dropped
+      queue.remove(1);
+      // queue is now [a, c], history should be [0]
+      // current was at 2 → after remove shifts to 1 → song "c"
+      expect(queue.current()?.id).toBe("c");
+      expect(queue.prev()?.id).toBe("a");
+    });
+
+    it("does not push to history on prev itself", () => {
+      queue.setMode(PlayMode.Random);
+      queue.add(makeSong("a"));
+      queue.add(makeSong("b"));
+      queue.add(makeSong("c"));
+      queue.playAt(0);
+      queue.playAt(1);
+      queue.playAt(2); // history: [0, 1]
+      queue.prev();    // pops 1, history: [0]
+      queue.prev();    // pops 0, history: []
+      expect(queue.prev()).toBeNull(); // no fallback target in random mode
+    });
+
+    it("caps history at HISTORY_LIMIT (50) entries, dropping oldest", () => {
+      queue.setMode(PlayMode.Random);
+      // Build a queue large enough to overflow HISTORY_LIMIT
+      for (let i = 0; i < 60; i++) queue.add(makeSong(`s${i}`));
+      // Walk through 60 explicit picks → 59 pushes to history
+      // (playAt pushes the previous currentIndex; first call has -1
+      // which pushHistory rejects). After 60 playAts, history holds
+      // the last 50 of those 59 entries.
+      for (let i = 0; i < 60; i++) queue.playAt(i);
+
+      // Walk back through history. The first prev returns whatever the
+      // 50th-most-recent push was (= index 9, since pushes 0..58 happened
+      // and the oldest 9 fell off). We can verify by counting prevs that
+      // succeed before history exhausts and prev returns null in random.
+      let count = 0;
+      while (queue.prev() !== null) {
+        count++;
+        if (count > 100) break; // safety
+      }
+      expect(count).toBe(50);
+    });
+  });
+
+  describe("addNext", () => {
+    it("appends when queue is empty (no current)", () => {
+      queue.addNext(makeSong("a"));
+      expect(queue.size()).toBe(1);
+      expect(queue.list()[0].id).toBe("a");
+    });
+
+    it("appends when nothing is currently playing (currentIndex < 0)", () => {
+      queue.add(makeSong("a"));
+      queue.add(makeSong("b"));
+      // No play() yet → currentIndex still -1
+      queue.addNext(makeSong("c"));
+      expect(queue.list().map((s) => s.id)).toEqual(["a", "b", "c"]);
+    });
+
+    it("inserts at currentIndex+1 mid-queue", () => {
+      queue.add(makeSong("a"));
+      queue.add(makeSong("b"));
+      queue.add(makeSong("c"));
+      queue.add(makeSong("d"));
+      queue.play();      // current = 0 (a)
+      queue.next();      // current = 1 (b)
+      queue.addNext(makeSong("x"));
+      expect(queue.list().map((s) => s.id)).toEqual(["a", "b", "x", "c", "d"]);
+      expect(queue.current()?.id).toBe("b"); // current unchanged
+    });
+
+    it("makes the inserted song play next when next() is called", () => {
+      queue.setMode(PlayMode.Sequential);
+      queue.add(makeSong("a"));
+      queue.add(makeSong("b"));
+      queue.play();      // current = 0 (a)
+      queue.addNext(makeSong("x"));
+      expect(queue.next()?.id).toBe("x");
+    });
+
+    it("shifts playedIndices entries > currentIndex by +1", () => {
+      queue.setMode(PlayMode.Random);
+      queue.add(makeSong("a"));
+      queue.add(makeSong("b"));
+      queue.add(makeSong("c"));
+      queue.add(makeSong("d"));
+      queue.playAt(2); // current = 2 (c), played = {2}
+      queue.playAt(3); // current = 3 (d), played = {2, 3}
+      queue.playAt(2); // current = 2 (c), played = {2, 3}
+      // Now insert after c — d's index 3 should become 4
+      queue.addNext(makeSong("x"));
+      expect(queue.list().map((s) => s.id)).toEqual(["a", "b", "c", "x", "d"]);
+      // After addNext: currentIndex still 2; played should be {2, 4}
+      // (the previously-played 'd' is now at index 4)
+      // Verify by removing 'x' (index 3) — d should remain played at index 3
+      queue.remove(3);
+      expect(queue.list().map((s) => s.id)).toEqual(["a", "b", "c", "d"]);
+    });
+
+    it("shifts history entries > currentIndex by +1", () => {
+      queue.setMode(PlayMode.Random);
+      queue.add(makeSong("a"));
+      queue.add(makeSong("b"));
+      queue.add(makeSong("c"));
+      queue.add(makeSong("d"));
+      queue.playAt(0); // current = 0
+      queue.playAt(3); // current = 3 (d), history = [0]
+      queue.playAt(1); // current = 1 (b), history = [0, 3]
+      queue.addNext(makeSong("x"));
+      // Insert at index 2 → entries > 1 shift +1 → history becomes [0, 4]
+      // queue: [a, b, x, c, d]; d is now at index 4
+      // prev → pop 4 → song at index 4 = d
+      expect(queue.prev()?.id).toBe("d");
+      // prev again → pop 0 → song at index 0 = a
+      expect(queue.prev()?.id).toBe("a");
+    });
+
+    it("idle player + stale currentIndex: insertion target is currentIndex+1, not size-1", () => {
+      // Reproduces the scenario where the player has gone idle but the
+      // queue still has a non-negative currentIndex (e.g., after natural
+      // track end without queue.clear()).
+      queue.add(makeSong("a"));
+      queue.add(makeSong("b"));
+      queue.add(makeSong("c"));
+      queue.add(makeSong("d"));
+      queue.play();      // current = 0 (a)
+      queue.next();      // current = 1 (b)
+      // Simulate idle-with-stale-currentIndex: the player has gone idle
+      // but queue still points at b.
+      // Caller pre-captures insertedAt:
+      const insertedAt = queue.getCurrentIndex() + 1; // = 2
+      queue.addNext(makeSong("x"));
+      // queue is now [a, b, x, c, d]
+      // size-1 would be 4 (d) — WRONG.
+      // insertedAt is 2 (x) — RIGHT.
+      expect(queue.list().map((s) => s.id)).toEqual(["a", "b", "x", "c", "d"]);
+      expect(queue.size() - 1).toBe(4); // proves size-1 strategy would pick d
+      const promoted = queue.playAt(insertedAt);
+      expect(promoted?.id).toBe("x");
+    });
+  });
 });
@@ -10,7 +10,7 @@ export interface QueuedSong {
  name: string;
  artist: string;
  album: string;
-  platform: "netease" | "qq" | "bilibili";
+  platform: "netease" | "qq" | "bilibili" | "youtube";
  url?: string; // resolved lazily at play time
  coverUrl: string;
  duration: number; // seconds
@@ -20,6 +20,17 @@ export class PlayQueue {
  private songs: QueuedSong[] = [];
  private currentIndex = -1;
  private mode: PlayMode = PlayMode.Sequential;
+  private playedIndices = new Set<number>();
+  private history: number[] = [];
+  private static readonly HISTORY_LIMIT = 50;
+
+  private pushHistory(idx: number): void {
+    if (idx < 0 || idx >= this.songs.length) return;
+    this.history.push(idx);
+    if (this.history.length > PlayQueue.HISTORY_LIMIT) {
+      this.history.shift();
+    }
+  }

  add(song: QueuedSong): void {
    this.songs.push(song);
@@ -29,6 +40,34 @@ export class PlayQueue {
    this.songs.push(...songs);
  }

+  /**
+   * Insert a song to play immediately after the current one. Falls
+   * through to plain push when nothing is playing yet (currentIndex < 0
+   * or queue empty), so the existing "add → idle bot starts playing"
+   * flow continues to work.
+   *
+   * Shifts playedIndices and history entries > currentIndex by +1 so
+   * their references stay valid after the splice.
+   */
+  addNext(song: QueuedSong): void {
+    if (this.currentIndex < 0 || this.songs.length === 0) {
+      this.songs.push(song);
+      return;
+    }
+    const insertAt = this.currentIndex + 1;
+    this.songs.splice(insertAt, 0, song);
+
+    const shifted = new Set<number>();
+    for (const i of this.playedIndices) {
+      shifted.add(i > this.currentIndex ? i + 1 : i);
+    }
+    this.playedIndices = shifted;
+
+    this.history = this.history.map((i) =>
+      i > this.currentIndex ? i + 1 : i,
+    );
+  }
+
  remove(index: number): QueuedSong | null {
    if (index < 0 || index >= this.songs.length) return null;
    const [removed] = this.songs.splice(index, 1);
@@ -36,28 +75,51 @@ export class PlayQueue {
    if (index < this.currentIndex) {
      this.currentIndex--;
    } else if (index === this.currentIndex) {
-      if (this.currentIndex >= this.songs.length) {
-        this.currentIndex = this.songs.length - 1;
-      }
+      this.currentIndex--;
    }

+    // Rebuild playedIndices to account for shifted indices
+    const newPlayed = new Set<number>();
+    for (const idx of this.playedIndices) {
+      if (idx === index) continue;
+      newPlayed.add(idx > index ? idx - 1 : idx);
+    }
+    this.playedIndices = newPlayed;
+
+    // Same shift logic for history — drop entries pointing at the
+    // removed song; shift entries > index down by 1.
+    this.history = this.history
+      .filter((idx) => idx !== index)
+      .map((idx) => (idx > index ? idx - 1 : idx));
+
    return removed;
  }

  clear(): void {
    this.songs = [];
    this.currentIndex = -1;
+    this.playedIndices.clear();
+    this.history = [];
  }

  play(): QueuedSong | null {
    if (this.songs.length === 0) return null;
+    this.playedIndices.clear();
+    this.history = [];
    this.currentIndex = 0;
+    this.playedIndices.add(0);
    return this.songs[0];
  }

  playAt(index: number): QueuedSong | null {
    if (index < 0 || index >= this.songs.length) return null;
+    this.pushHistory(this.currentIndex);
+    // Reset the Random-mode "unplayed" pool — explicit picks restart
+    // shuffle from this point. History tracking is independent and
+    // unaffected by this clear.
+    this.playedIndices.clear();
    this.currentIndex = index;
+    this.playedIndices.add(index);
    return this.songs[index];
  }

@@ -68,24 +130,31 @@ export class PlayQueue {
      case PlayMode.Sequential: {
        const nextIndex = this.currentIndex + 1;
        if (nextIndex >= this.songs.length) return null;
+        this.pushHistory(this.currentIndex);
        this.currentIndex = nextIndex;
        return this.songs[nextIndex];
      }
      case PlayMode.Loop: {
+        this.pushHistory(this.currentIndex);
        this.currentIndex = (this.currentIndex + 1) % this.songs.length;
        return this.songs[this.currentIndex];
      }
      case PlayMode.Random: {
-        if (this.songs.length === 1) return this.songs[0];
-        let nextIndex: number;
-        do {
-          nextIndex = Math.floor(Math.random() * this.songs.length);
-        } while (nextIndex === this.currentIndex && this.songs.length > 1);
+        const unplayed: number[] = [];
+        for (let i = 0; i < this.songs.length; i++) {
+          if (!this.playedIndices.has(i)) unplayed.push(i);
+        }
+        if (unplayed.length === 0) return null;
+        const nextIndex =
+          unplayed[Math.floor(Math.random() * unplayed.length)];
+        this.pushHistory(this.currentIndex);
        this.currentIndex = nextIndex;
+        this.playedIndices.add(nextIndex);
        return this.songs[nextIndex];
      }
      case PlayMode.RandomLoop: {
        if (this.songs.length === 1) {
+          this.pushHistory(this.currentIndex);
          this.currentIndex = 0;
          return this.songs[0];
        }
@@ -93,6 +162,7 @@ export class PlayQueue {
        do {
          idx = Math.floor(Math.random() * this.songs.length);
        } while (idx === this.currentIndex);
+        this.pushHistory(this.currentIndex);
        this.currentIndex = idx;
        return this.songs[idx];
      }
@@ -101,14 +171,33 @@ export class PlayQueue {

  prev(): QueuedSong | null {
    if (this.songs.length === 0) return null;
+
+    // Preferred: pop from the back-stack so prev means "the song I
+    // actually played before this one," not "the previous array slot."
+    while (this.history.length > 0) {
+      const idx = this.history.pop()!;
+      if (idx >= 0 && idx < this.songs.length) {
+        this.currentIndex = idx;
+        this.playedIndices.add(idx);
+        return this.songs[idx];
+      }
+      // Stale entry (song removed) — keep popping.
+    }
+
+    // Fallback: no history to walk back through. In Sequential we
+    // can still meaningfully step the index backward; in random
+    // modes there's nothing useful to return.
+    if (this.mode === PlayMode.Random || this.mode === PlayMode.RandomLoop) {
+      return null;
+    }
    const prevIndex = this.currentIndex - 1;
    if (prevIndex < 0) {
-      // In Sequential mode, don't wrap around
      if (this.mode === PlayMode.Sequential) return null;
      this.currentIndex = this.songs.length - 1;
    } else {
      this.currentIndex = prevIndex;
    }
+    this.playedIndices.add(this.currentIndex);
    return this.songs[this.currentIndex];
  }

@@ -136,9 +225,19 @@ export class PlayQueue {

  setMode(mode: PlayMode): void {
    this.mode = mode;
+    this.playedIndices.clear();
+    this.history = [];
+    if (this.currentIndex >= 0) {
+      this.playedIndices.add(this.currentIndex);
+    }
  }

  getCurrentIndex(): number {
    return this.currentIndex;
  }
+
+  /** Number of songs not yet played in Random mode. */
+  unplayedCount(): number {
+    return this.songs.length - this.playedIndices.size;
+  }
 }
@@ -8,6 +8,7 @@ export interface ParsedCommand {
 export const PUBLIC_COMMANDS = new Set([
  "play", "add", "queue", "list", "now", "lyrics", "vote", "help",
  "playlist", "album", "fm", "prev", "next", "skip", "pause", "resume",
+  "artist",
 ]);

 export const ADMIN_COMMANDS = new Set([
@@ -13,8 +13,9 @@ import {
  type ParsedCommand,
 } from "./commands.js";
 import type { Logger } from "../logger.js";
-import type { BotDatabase } from "../data/database.js";
+import type { BotDatabase, ProfileConfig } from "../data/database.js";
 import type { BotConfig } from "../data/config.js";
+import { BotProfileManager } from "./profile.js";

 export interface BotInstanceOptions {
  id: string;
@@ -23,6 +24,7 @@ export interface BotInstanceOptions {
  neteaseProvider: MusicProvider;
  qqProvider: MusicProvider;
  bilibiliProvider: MusicProvider;
+  youtubeProvider: MusicProvider;
  database: BotDatabase;
  config: BotConfig;
  logger: Logger;
@@ -51,12 +53,18 @@ export class BotInstance extends EventEmitter {
  private neteaseProvider: MusicProvider;
  private qqProvider: MusicProvider;
  private bilibiliProvider: MusicProvider;
+  private youtubeProvider: MusicProvider;
  private database: BotDatabase;
  private config: BotConfig;
  private logger: Logger;
  private connected = false;
+  private disconnectEmitted = false;
  private voteSkipUsers = new Set<string>();
  private isAdvancing = false;
+  private idleTimer: ReturnType<typeof setTimeout> | null = null;
+  private channelUserCount = 0;
+  private profileManager: BotProfileManager;
+  private isFmMode = false;

  constructor(options: BotInstanceOptions) {
    super();
@@ -65,6 +73,7 @@ export class BotInstance extends EventEmitter {
    this.neteaseProvider = options.neteaseProvider;
    this.qqProvider = options.qqProvider;
    this.bilibiliProvider = options.bilibiliProvider;
+    this.youtubeProvider = options.youtubeProvider;
    this.database = options.database;
    this.config = options.config;
    this.logger = options.logger.child({ botId: this.id });
@@ -73,6 +82,14 @@ export class BotInstance extends EventEmitter {
    this.player = new AudioPlayer(this.logger);
    this.queue = new PlayQueue();

+    const profileConfig = this.database.getProfileConfig(this.id);
+    this.profileManager = new BotProfileManager(
+      this.tsClient,
+      this.logger,
+      profileConfig,
+      options.tsOptions.nickname,
+    );
+
    this.setupPlayerEvents();
    this.setupTsEvents();
  }
@@ -99,27 +116,96 @@ export class BotInstance extends EventEmitter {

  private setupTsEvents(): void {
    this.tsClient.on("textMessage", (msg: TS3TextMessage) => {
-      this.handleTextMessage(msg);
+      this.handleTextMessage(msg).catch((err) => {
+        this.logger.error({ err }, "Unhandled error in text message handler");
+      });
    });

    this.tsClient.on("disconnected", () => {
+      // Always reset local state — covers the case where connect() never
+      // completed (hanging handshake → 60s library idle timeout) and
+      // this.connected was never flipped to true. Previously this handler
+      // short-circuited on !this.connected, leaving player stuck as "playing".
      this.connected = false;
      this.player.stop();
+      // Only emit externally once per lifecycle so clients don't see a
+      // duplicate "disconnected" after an explicit disconnect() call.
+      if (this.disconnectEmitted) return;
+      this.disconnectEmitted = true;
      this.emit("disconnected");
    });
+
+    this.tsClient.on("connected", () => {
+      this._startIdlePoller();
+    });
  }

  async connect(): Promise<void> {
+    this.disconnectEmitted = false;
    await this.tsClient.connect();
+    // Race guard: if disconnect() was called while the handshake was
+    // awaiting, don't flip connected back to true — that would leave the
+    // bot in an inconsistent state (externally "connected" but the tsClient
+    // has already been torn down).
+    if (this.disconnectEmitted) {
+      throw new Error("Connect aborted by concurrent disconnect");
+    }
    this.connected = true;
+    this.profileManager.onConnect();
    this.emit("connected");
  }

  disconnect(): void {
+    this._cancelIdleTimer();
    this.player.stop();
-    this.tsClient.disconnect();
    this.connected = false;
-    this.emit("disconnected");
+    if (!this.disconnectEmitted) {
+      this.disconnectEmitted = true;
+      this.emit("disconnected");
+    }
+    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> {
@@ -160,11 +246,35 @@ export class BotInstance extends EventEmitter {
    cmd: ParsedCommand,
    msg?: TS3TextMessage
  ): Promise<string | null> {
+    // Reject commands that would push audio when the bot isn't connected:
+    // otherwise ffmpeg spawns and voice goes to a half-initialized or
+    // torn-down TS client, leaving player.state="playing" on a disconnected
+    // bot. Config-only commands (vol, mode, clear, stop, queue, now) are
+    // still allowed so the UI stays usable while the bot is offline.
+    const AUDIO_COMMANDS = new Set([
+      "play",
+      "add",
+      "playnext",
+      "pn",
+      "next",
+      "skip",
+      "prev",
+      "playlist",
+      "album",
+      "fm",
+      "artist",
+    ]);
+    if (!this.connected && AUDIO_COMMANDS.has(cmd.name)) {
+      throw new Error("Bot is not connected to TeamSpeak");
+    }
    switch (cmd.name) {
      case "play":
        return this.cmdPlay(cmd);
      case "add":
        return this.cmdAdd(cmd);
+      case "playnext":
+      case "pn":
+        return this.cmdPlayNext(cmd);
      case "pause":
        return this.cmdPause();
      case "resume":
@@ -195,6 +305,8 @@ export class BotInstance extends EventEmitter {
        return this.cmdAlbum(cmd);
      case "fm":
        return this.cmdFm();
+      case "artist":
+        return this.cmdArtist(cmd);
      case "vote":
        return this.cmdVote(msg);
      case "lyrics":
@@ -210,19 +322,29 @@ export class BotInstance extends EventEmitter {
    }
  }

-  getProviderFor(platform: "netease" | "qq" | "bilibili"): MusicProvider {
+  getProviderFor(platform: "netease" | "qq" | "bilibili" | "youtube"): MusicProvider {
    if (platform === "bilibili") return this.bilibiliProvider;
+    if (platform === "youtube") return this.youtubeProvider;
    return platform === "qq" ? this.qqProvider : this.neteaseProvider;
  }

  private getProvider(flags: Set<string>): MusicProvider {
    if (flags.has("b")) return this.bilibiliProvider;
    if (flags.has("q")) return this.qqProvider;
+    if (flags.has("y")) return this.youtubeProvider;
    return this.neteaseProvider;
  }

  /** Resolve URL for a song and start playing it. Skips to next if URL fails. */
  async resolveAndPlay(song: QueuedSong): Promise<boolean> {
+    if (!this.connected) {
+      this.logger.warn({ songId: song.id, name: song.name }, "resolveAndPlay called on disconnected bot — skipping");
+      return false;
+    }
+    // Clear any accumulated skip votes — every fresh track starts with a
+    // clean slate, regardless of which code path loaded it (cmdPlay,
+    // cmdPlaylist, cmdAlbum, cmdFm, trackEnd auto-advance, etc.).
+    this.voteSkipUsers.clear();
    const provider = this.getProviderFor(song.platform);
    try {
      const url = await provider.getSongUrl(song.id);
@@ -230,6 +352,18 @@ export class BotInstance extends EventEmitter {
        this.logger.warn({ songId: song.id, name: song.name }, "No URL available, skipping");
        return false;
      }
+      // Re-check connection state AFTER the network round-trip — the URL
+      // resolve can take multiple seconds and the user may have called stop
+      // during that window. Without this, we'd spawn ffmpeg on a
+      // disconnected bot and land back in the same "connected=false but
+      // playing=true" inconsistency that Bug C was about.
+      if (!this.connected) {
+        this.logger.warn(
+          { songId: song.id, name: song.name },
+          "bot disconnected during URL resolve — aborting playback",
+        );
+        return false;
+      }
      song.url = url;
      this.player.play(url);
      this.database.addPlayHistory({
@@ -241,6 +375,10 @@ export class BotInstance extends EventEmitter {
        platform: song.platform,
        coverUrl: song.coverUrl,
      });
+      // Update bot presence (fire-and-forget — never blocks playback)
+      this.profileManager.onSongChange(song).catch((err) => {
+        this.logger.warn({ err }, "Profile update failed after song change");
+      });
      this.emit("stateChange");
      return true;
    } catch (err) {
@@ -258,9 +396,12 @@ export class BotInstance extends EventEmitter {

    const song = result.songs[0];
    this.queue.clear();
+    this.isFmMode = false;
    this.queue.add({ ...song, platform: provider.platform });
    this.queue.play();

+    // Reset failure counter on user-initiated play
+    this.player.resetFailures();
    const ok = await this.resolveAndPlay(this.queue.current()!);
    if (!ok) return `Cannot play: ${song.name}`;
    return `Now playing: ${song.name} - ${song.artist}`;
@@ -274,11 +415,57 @@ export class BotInstance extends EventEmitter {
      return `No results found for: ${cmd.args}`;

    const song = result.songs[0];
+    const wasIdle = this.player.getState() === "idle";
    this.queue.add({ ...song, platform: provider.platform });
+
+    // If nothing was playing, start this newly-added song immediately.
+    // Matches /api/player/:id/add-by-id behavior so both add paths feel
+    // the same to the user (add to idle bot → plays now).
+    if (wasIdle) {
+      this.queue.playAt(this.queue.size() - 1);
+      this.player.resetFailures();
+      await this.resolveAndPlay(this.queue.current()!);
+      this.emit("stateChange");
+      return `Now playing: ${song.name} - ${song.artist}`;
+    }
+
    this.emit("stateChange");
    return `Added to queue: ${song.name} - ${song.artist} (position ${this.queue.size()})`;
  }

+  private async cmdPlayNext(cmd: ParsedCommand): Promise<string> {
+    if (!cmd.args) return "Usage: !playnext <song name>";
+    const provider = this.getProvider(cmd.flags);
+    const result = await provider.search(cmd.args, 1);
+    if (result.songs.length === 0)
+      return `No results found for: ${cmd.args}`;
+
+    const song = result.songs[0];
+    const wasIdle = this.player.getState() === "idle";
+    // Capture the slot addNext WILL insert at, before mutating the queue.
+    // addNext pushes when currentIndex<0 (slot = size); otherwise splices
+    // at currentIndex+1. Using size-1 after addNext was wrong when the
+    // queue had stale currentIndex>=0 while the player was idle (e.g.,
+    // after natural track end without queue.clear()).
+    const insertedAt =
+      this.queue.getCurrentIndex() < 0
+        ? this.queue.size()
+        : this.queue.getCurrentIndex() + 1;
+    this.queue.addNext({ ...song, platform: provider.platform });
+
+    if (wasIdle) {
+      this.queue.playAt(insertedAt);
+      this.player.resetFailures();
+      const ok = await this.resolveAndPlay(this.queue.current()!);
+      this.emit("stateChange");
+      if (!ok) return `Cannot play: ${song.name}`;
+      return `Now playing: ${song.name} - ${song.artist}`;
+    }
+
+    this.emit("stateChange");
+    return `Up next: ${song.name} - ${song.artist}`;
+  }
+
  private cmdPause(): string {
    this.player.pause();
    this.emit("stateChange");
@@ -294,6 +481,10 @@ export class BotInstance extends EventEmitter {
  private cmdStop(): string {
    this.player.stop();
    this.queue.clear();
+    this.isFmMode = false;
+    this.profileManager.onSongChange(null).catch((err) => {
+      this.logger.warn({ err }, "Profile restore failed on stop");
+    });
    this.emit("stateChange");
    return "Stopped and queue cleared";
  }
@@ -307,13 +498,17 @@ export class BotInstance extends EventEmitter {
  }

  private async cmdPrev(): Promise<string> {
-    const prev = this.queue.prev();
-    if (prev) {
+    // Retry-skip up to 4 attempts: history can include failed songs
+    // that playNext's auto-advance retry-skipped past, so a single
+    // prev would otherwise land on an unplayable song and leave the
+    // queue's currentIndex stuck mid-failure.
+    for (let i = 0; i < 4; i++) {
+      const prev = this.queue.prev();
+      if (!prev) return "No previous song";
      const ok = await this.resolveAndPlay(prev);
-      if (!ok) return "Cannot play previous song";
-      return `Now playing: ${prev.name} - ${prev.artist}`;
+      if (ok) return `Now playing: ${prev.name} - ${prev.artist}`;
    }
-    return "No previous song";
+    return "Cannot play any previous songs (all failed to resolve)";
  }

  private cmdVol(cmd: ParsedCommand): string {
@@ -344,6 +539,10 @@ export class BotInstance extends EventEmitter {
  private cmdClear(): string {
    this.player.stop();
    this.queue.clear();
+    this.isFmMode = false;
+    this.profileManager.onSongChange(null).catch((err) => {
+      this.logger.warn({ err }, "Profile restore failed on clear");
+    });
    this.emit("stateChange");
    return "Queue cleared";
  }
@@ -372,13 +571,48 @@ export class BotInstance extends EventEmitter {
  }

  private async cmdPlaylist(cmd: ParsedCommand): Promise<string> {
-    if (!cmd.args) return "Usage: !playlist <playlist ID or URL>";
+    if (!cmd.args) return "Usage: !playlist <playlist name or ID>";
    const provider = this.getProvider(cmd.flags);
+
+    // Determine if input is a numeric ID or a name search
    const id = this.extractId(cmd.args);
-    const songs = await provider.getPlaylistSongs(id);
+    const isNumericId = /^\d+$/.test(cmd.args.trim());
+
+    let playlistId: string;
+
+    if (isNumericId || id !== cmd.args) {
+      // Input is a numeric ID or URL containing an ID — use existing logic
+      playlistId = id;
+    } else {
+      // Name-based search
+      const result = await provider.search(cmd.args);
+      let playlists = result.playlists ?? [];
+
+      // Also search user's personal playlists if logged in
+      if (provider.getUserPlaylists) {
+        try {
+          const userPlaylists = await provider.getUserPlaylists();
+          const query = cmd.args.toLowerCase();
+          const matched = userPlaylists.filter(
+            p => p.name.toLowerCase().includes(query)
+          );
+          // Merge: public results first (API-ranked), then user matches
+          playlists = [...playlists, ...matched];
+        } catch {
+          // User playlists unavailable — continue with public results
+        }
+      }
+
+      if (playlists.length === 0)
+        return `No playlists found for: ${cmd.args}`;
+      playlistId = playlists[0].id;
+    }
+
+    const songs = await provider.getPlaylistSongs(playlistId);
    if (songs.length === 0) return "Playlist is empty or not found";

    this.queue.clear();
+    this.isFmMode = false;
    for (const song of songs) {
      this.queue.add({ ...song, platform: provider.platform });
    }
@@ -395,6 +629,7 @@ export class BotInstance extends EventEmitter {
    if (songs.length === 0) return "Album is empty or not found";

    this.queue.clear();
+    this.isFmMode = false;
    for (const song of songs) {
      this.queue.add({ ...song, platform: provider.platform });
    }
@@ -416,18 +651,70 @@ export class BotInstance extends EventEmitter {
    for (const song of songs) {
      this.queue.add({ ...song, platform: "netease" });
    }
+    this.queue.setMode(PlayMode.Random);
+    this.isFmMode = true;
+    this.player.resetFailures();
+
    const first = this.queue.play();
    if (first) await this.resolveAndPlay(first);
    this.emit("stateChange");
    return `Personal FM started: ${first?.name ?? "unknown"} - ${first?.artist ?? ""}`;
  }

+  private async cmdArtist(cmd: ParsedCommand): Promise<string> {
+    if (!cmd.args) return "Usage: !artist <artist name>";
+    const provider = this.getProvider(cmd.flags);
+    const result = await provider.search(cmd.args, 50);
+    if (result.songs.length === 0)
+      return `No results found for artist: ${cmd.args}`;
+
+    const query = cmd.args.toLowerCase();
+    let filtered = result.songs.filter(
+      s => s.artist.toLowerCase().includes(query)
+    );
+
+    // Fallback to unfiltered results if filtering drops everything
+    if (filtered.length === 0) {
+      filtered = result.songs.slice(0, 20);
+    }
+
+    this.queue.clear();
+    this.isFmMode = false;
+    for (const song of filtered) {
+      this.queue.add({ ...song, platform: provider.platform });
+    }
+    this.queue.setMode(PlayMode.Loop);
+    this.player.resetFailures();
+
+    const first = this.queue.play();
+    if (first) await this.resolveAndPlay(first);
+    this.emit("stateChange");
+    return `Artist mode: ${cmd.args} — ${filtered.length} songs loaded. Now playing: ${first?.name ?? "unknown"}`;
+  }
+
+  private async refillFm(): Promise<void> {
+    if (!this.isFmMode || !this.neteaseProvider.getPersonalFm) return;
+    try {
+      const songs = await this.neteaseProvider.getPersonalFm();
+      if (songs.length === 0) return;
+      for (const song of songs) {
+        this.queue.add({ ...song, platform: "netease" });
+      }
+      this.logger.debug({ count: songs.length }, "FM queue refilled");
+    } catch (err) {
+      this.logger.error({ err }, "Failed to refill FM queue");
+    }
+  }
+
  private async cmdVote(msg?: TS3TextMessage): Promise<string> {
    if (!msg) return "Vote can only be used in TeamSpeak";
    this.voteSkipUsers.add(msg.invokerUid);
    const clients = await this.tsClient.getClientsInChannel();
-    const totalUsers = clients.length - 1;
-    const needed = Math.ceil(totalUsers / 2);
+    const totalUsers = clients.length - 1; // exclude the bot itself
+    // At least 1 vote is always required — otherwise a single voter in an
+    // otherwise empty channel (or a transient clients.length=1 race) could
+    // unanimously "win" with needed=0.
+    const needed = Math.max(1, Math.ceil(totalUsers / 2));
    const votes = this.voteSkipUsers.size;

    if (votes >= needed) {
@@ -468,16 +755,21 @@ export class BotInstance extends EventEmitter {
      `${p}play <song>  — Search and play`,
      `${p}play -q <song> — Search from QQ Music`,
      `${p}play -b <song> — Search from BiliBili`,
+      `${p}play -y <song> — Search from YouTube (yt-dlp)`,
      `${p}add <song>   — Add to queue`,
+      `${p}playnext <song> — Insert as next song (alias: ${p}pn)`,
      `${p}pause/resume — Pause/resume`,
      `${p}next/prev    — Next/previous`,
      `${p}stop         — Stop and clear queue`,
      `${p}vol <0-100>  — Set volume`,
      `${p}queue        — Show queue`,
      `${p}mode <seq|loop|random|rloop> — Play mode`,
-      `${p}playlist <id> — Load playlist`,
+      `${p}playlist <name or id> — Load playlist by name or ID`,
+      `${p}playlist -q <name or id> — Load playlist from QQ Music`,
      `${p}album <id>   — Load album`,
      `${p}fm           — Personal FM (NetEase)`,
+      `${p}artist <name> — Play songs by artist (loop)`,
+      `${p}artist -q <name> — Artist loop from QQ Music`,
      `${p}vote         — Vote to skip`,
      `${p}lyrics       — Show lyrics`,
      `${p}now          — Current song info`,
@@ -485,27 +777,59 @@ export class BotInstance extends EventEmitter {
    ].join("\n");
  }

-  private async playNext(): Promise<void> {
-    if (this.isAdvancing) return;
+  /**
+   * Advance the queue and play the next song. If the resolved URL fails
+   * (e.g., copyright/region restrictions for QQ), skips up to `maxRetries`
+   * more songs looking for a playable one. Public so REST endpoints that
+   * seed the queue can fall back to this retry-skip behavior.
+   *
+   * Returns true if a song actually started playing, false otherwise.
+   */
+  async playNext(maxRetries = 3): Promise<boolean> {
+    if (this.isAdvancing || !this.connected) return false;
    this.isAdvancing = true;
    try {
      this.voteSkipUsers.clear();
      const next = this.queue.next();
+      let started = false;
      if (next) {
-        const ok = await this.resolveAndPlay(next);
-        if (!ok) {
-          // Skip to next if URL resolve fails (up to 3 retries)
-          for (let i = 0; i < 3; i++) {
+        started = await this.resolveAndPlay(next);
+        if (!started) {
+          for (let i = 0; i < maxRetries && this.connected; i++) {
            const retry = this.queue.next();
            if (!retry) break;
-            if (await this.resolveAndPlay(retry)) break;
+            if (await this.resolveAndPlay(retry)) {
+              started = true;
+              break;
+            }
          }
+        }
+        if (!started) {
          this.player.stop();
+          this.profileManager.onSongChange(null).catch(() => {});
+        } else if (this.isFmMode && this.queue.unplayedCount() <= 3) {
+          // Proactive refill: when queue is running low, fetch more FM songs
+          this.refillFm().catch(err => this.logger.error({ err }, "Proactive FM refill failed"));
        }
      } else {
-        this.player.stop();
+        // Queue exhausted — in FM Random mode, refill and continue
+        if (this.isFmMode) {
+          await this.refillFm();
+          const refillNext = this.queue.next();
+          if (refillNext) {
+            started = await this.resolveAndPlay(refillNext);
+          }
+          if (!started) {
+            this.player.stop();
+            this.profileManager.onSongChange(null).catch(() => {});
+          }
+        } else {
+          this.player.stop();
+          this.profileManager.onSongChange(null).catch(() => {});
+        }
      }
      this.emit("stateChange");
+      return started;
    } finally {
      this.isAdvancing = false;
    }
@@ -549,4 +873,12 @@ export class BotInstance extends EventEmitter {
  isConnected(): boolean {
    return this.connected;
  }
+
+  getProfileManager(): BotProfileManager {
+    return this.profileManager;
+  }
+
+  getIdentityExport(): string | undefined {
+    return this.tsClient.getIdentityExport();
+  }
 }
@@ -1,13 +1,53 @@
 import crypto from "node:crypto";
+import { EventEmitter } from "node:events";
 import {
  BotInstance,
  type BotInstanceOptions,
 } from "./instance.js";
 import type { MusicProvider } from "../music/provider.js";
+import { YouTubeProvider } from "../music/youtube.js";
 import type { BotDatabase } from "../data/database.js";
 import type { BotConfig } from "../data/config.js";
 import type { Logger } from "../logger.js";

+import type { ServerProtocol } from "../ts-protocol/client.js";
+
+/**
+ * Run bot.connect() with a hard deadline. If the handshake hangs (e.g. the
+ * server silently drops the connection after initivexpand2), we tear the
+ * instance down instead of waiting for the library's 60s idle timeout, so
+ * the HTTP /start call returns promptly and the UI doesn't lock up.
+ */
+async function connectWithTimeout(
+  bot: BotInstance,
+  ms: number,
+  logger: Logger
+): Promise<void> {
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const timeout = new Promise<never>((_, reject) => {
+    timer = setTimeout(
+      () => reject(new Error(`connect timeout after ${ms}ms`)),
+      ms
+    );
+  });
+  try {
+    await Promise.race([bot.connect(), timeout]);
+  } catch (err) {
+    logger.warn(
+      { err, botId: bot.id },
+      "Connect failed or timed out — tearing down instance"
+    );
+    try {
+      bot.disconnect();
+    } catch {
+      // ignore teardown errors
+    }
+    throw err;
+  } finally {
+    if (timer) clearTimeout(timer);
+  }
+}
+
 export interface CreateBotParams {
  name: string;
  serverAddress: string;
@@ -17,13 +57,20 @@ export interface CreateBotParams {
  defaultChannel?: string;
  channelPassword?: string;
  autoStart?: boolean;
+  /** Force TS3 or TS6 protocol; omit or "unknown" for auto-detect. */
+  serverProtocol?: ServerProtocol;
+  /** API key for TS6 HTTP Query (port 10080/10443). */
+  ts6ApiKey?: string;
+  /** Password required to join the TS server. */
+  serverPassword?: string;
 }

-export class BotManager {
+export class BotManager extends EventEmitter {
  private bots = new Map<string, BotInstance>();
  private neteaseProvider: MusicProvider;
  private qqProvider: MusicProvider;
  private bilibiliProvider: MusicProvider;
+  private youtubeProvider: MusicProvider;
  private database: BotDatabase;
  private config: BotConfig;
  private logger: Logger;
@@ -36,9 +83,11 @@ export class BotManager {
    config: BotConfig,
    logger: Logger
  ) {
+    super();
    this.neteaseProvider = neteaseProvider;
    this.qqProvider = qqProvider;
    this.bilibiliProvider = bilibiliProvider;
+    this.youtubeProvider = new YouTubeProvider();
    this.database = database;
    this.config = config;
    this.logger = logger;
@@ -57,16 +106,21 @@ export class BotManager {
        nickname: params.nickname,
        defaultChannel: params.defaultChannel,
        channelPassword: params.channelPassword,
+        serverPassword: params.serverPassword,
+        serverProtocol: params.serverProtocol,
+        ts6ApiKey: params.ts6ApiKey,
      },
      neteaseProvider: this.neteaseProvider,
      qqProvider: this.qqProvider,
      bilibiliProvider: this.bilibiliProvider,
+      youtubeProvider: this.youtubeProvider,
      database: this.database,
      config: this.config,
      logger: this.logger,
    });

    this.bots.set(id, bot);
+    this.emit("botInstance", bot);

    this.database.saveBotInstance({
      id,
@@ -77,6 +131,9 @@ export class BotManager {
      defaultChannel: params.defaultChannel ?? "",
      channelPassword: params.channelPassword ?? "",
      autoStart: params.autoStart ?? false,
+      serverProtocol: params.serverProtocol ?? "",
+      ts6ApiKey: params.ts6ApiKey ?? "",
+      serverPassword: params.serverPassword ?? "",
    });

    this.logger.info({ botId: id, name: params.name }, "Bot instance created");
@@ -90,6 +147,7 @@ export class BotManager {
      this.bots.delete(id);
    }
    this.database.deleteBotInstance(id);
+    this.emit("botInstanceRemoved", id);
    this.logger.info({ botId: id }, "Bot instance removed");
  }

@@ -106,6 +164,9 @@ export class BotManager {
      nickname: params.nickname ?? existing.nickname,
      defaultChannel: params.defaultChannel ?? existing.defaultChannel,
      channelPassword: params.channelPassword ?? existing.channelPassword,
+      serverProtocol: params.serverProtocol ?? existing.serverProtocol,
+      ts6ApiKey: params.ts6ApiKey ?? existing.ts6ApiKey,
+      serverPassword: params.serverPassword ?? existing.serverPassword,
    });
    // Update in-memory name immediately (other fields need reconnect)
    const bot = this.bots.get(id);
@@ -128,53 +189,129 @@ export class BotManager {
  }

  async startBot(id: string): Promise<void> {
-    const bot = this.bots.get(id);
-    if (!bot) throw new Error(`Bot ${id} not found`);
-    await bot.connect();
-  }
+    const oldBot = this.bots.get(id);
+    if (!oldBot) throw new Error(`Bot ${id} not found`);

-  stopBot(id: string): void {
-    const bot = this.bots.get(id);
-    if (!bot) throw new Error(`Bot ${id} not found`);
-    bot.disconnect();
-  }
+    // Always tear down the outgoing instance before creating a replacement.
+    // Covers three cases:
+    //   1. oldBot is fully connected (manual restart)
+    //   2. oldBot is mid-handshake from a prior rapid start (isConnected()
+    //      still returns false but the library client is live and will leak
+    //      a TS session if we abandon it)
+    //   3. oldBot was just created by createBot but never connected — the
+    //      disconnect call is a cheap no-op here.
+    // Calling disconnect() is idempotent (disconnectEmitted guards event
+    // emission), so this is safe in all states.
+    oldBot.disconnect();

-  async loadSavedBots(): Promise<void> {
-    const savedInstances = this.database.getBotInstances();
-    for (const saved of savedInstances) {
+    // Reload config from database so updated settings (channel, nickname, etc.) take effect
+    const saved = this.database.getBotInstances().find((i) => i.id === id);
+    if (saved) {
+      const proto = saved.serverProtocol as "ts3" | "ts6" | "" | undefined;
      const bot = new BotInstance({
        id: saved.id,
        name: saved.name,
        tsOptions: {
          host: saved.serverAddress,
          port: saved.serverPort,
-          queryPort: 10011,
+          queryPort: proto === "ts6" ? 10080 : 10011,
          nickname: saved.nickname,
+          // Reuse the stored identity so server groups assigned to this bot
+          // survive restarts — without this the TS server sees a new UID
+          // each connect and strips all previously granted groups.
+          identity: saved.identity || undefined,
          defaultChannel: saved.defaultChannel || undefined,
          channelPassword: saved.channelPassword || undefined,
+          serverPassword: saved.serverPassword || undefined,
+          serverProtocol: proto === "ts3" || proto === "ts6" ? proto : undefined,
+          ts6ApiKey: saved.ts6ApiKey || undefined,
        },
        neteaseProvider: this.neteaseProvider,
        qqProvider: this.qqProvider,
        bilibiliProvider: this.bilibiliProvider,
+      youtubeProvider: this.youtubeProvider,
+        database: this.database,
+        config: this.config,
+        logger: this.logger,
+      });
+      this.bots.set(id, bot);
+      this.emit("botInstance", bot);
+      await connectWithTimeout(bot, 15_000, this.logger);
+      // Mark as autoStart so it reconnects on Docker restart, and persist identity
+      this.database.saveBotInstance({ ...saved, autoStart: true });
+      this.persistBotIdentity(saved, bot);
+    } else {
+      await connectWithTimeout(oldBot, 15_000, this.logger);
+    }
+  }
+
+  stopBot(id: string): void {
+    const bot = this.bots.get(id);
+    if (!bot) throw new Error(`Bot ${id} not found`);
+    bot.disconnect();
+
+    // Mark as not autoStart so it stays stopped on Docker restart
+    const saved = this.database.getBotInstances().find((i) => i.id === id);
+    if (saved) {
+      this.database.saveBotInstance({ ...saved, autoStart: false });
+    }
+  }
+
+  async loadSavedBots(): Promise<void> {
+    const savedInstances = this.database.getBotInstances();
+    for (const saved of savedInstances) {
+      const proto = saved.serverProtocol as "ts3" | "ts6" | "" | undefined;
+      const bot = new BotInstance({
+        id: saved.id,
+        name: saved.name,
+        tsOptions: {
+          host: saved.serverAddress,
+          port: saved.serverPort,
+          queryPort: proto === "ts6" ? 10080 : 10011,
+          nickname: saved.nickname,
+          identity: saved.identity || undefined,
+          defaultChannel: saved.defaultChannel || undefined,
+          channelPassword: saved.channelPassword || undefined,
+          serverPassword: saved.serverPassword || undefined,
+          serverProtocol: proto === "ts3" || proto === "ts6" ? proto : undefined,
+          ts6ApiKey: saved.ts6ApiKey || undefined,
+        },
+        neteaseProvider: this.neteaseProvider,
+        qqProvider: this.qqProvider,
+        bilibiliProvider: this.bilibiliProvider,
+      youtubeProvider: this.youtubeProvider,
        database: this.database,
        config: this.config,
        logger: this.logger,
      });

      this.bots.set(saved.id, bot);
+      this.emit("botInstance", bot);

-      // Auto-connect in background (non-blocking, won't affect other bots)
-      bot.connect().then(() => {
+      // Only auto-connect bots that have autoStart enabled
+      if (saved.autoStart) {
+        bot.connect().then(() => {
+          // Persist identity after successful connection for future restarts
+          this.persistBotIdentity(saved, bot);
+          this.logger.info(
+            { botId: saved.id, name: saved.name },
+            "Auto-connected saved bot"
+          );
+        }).catch((err) => {
+          this.logger.error(
+            { err, botId: saved.id, name: saved.name },
+            "Failed to auto-connect bot (start manually from Settings)"
+          );
+        });
+
+        // Stagger connections to avoid overwhelming the TS server
+        await new Promise((resolve) => setTimeout(resolve, 1000));
+      } else {
        this.logger.info(
          { botId: saved.id, name: saved.name },
-          "Auto-connected saved bot"
+          "Loaded bot (autoStart disabled, not connecting)"
        );
-      }).catch((err) => {
-        this.logger.error(
-          { err, botId: saved.id, name: saved.name },
-          "Failed to auto-connect bot (start manually from Settings)"
-        );
-      });
+      }
    }

    this.logger.info(
@@ -183,6 +320,13 @@ export class BotManager {
    );
  }

+  private persistBotIdentity(saved: import("../data/database.js").BotInstance, bot: BotInstance): void {
+    const identity = bot.getIdentityExport();
+    if (identity && identity !== saved.identity) {
+      this.database.saveBotInstance({ ...saved, identity });
+    }
+  }
+
  shutdown(): void {
    for (const bot of this.bots.values()) {
      bot.disconnect();
@@ -0,0 +1,450 @@
+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";
+
+const TS3_NICKNAME_MAX = 30;
+/** TS3 avatar max size — server default is ~300 KB. Use 200 KB to be safe. */
+const AVATAR_MAX_BYTES = 200 * 1024;
+/** Timeout for file-transfer operations (upload / delete). */
+const FILE_TRANSFER_TIMEOUT_MS = 6000;
+
+/**
+ * Manages the bot's TeamSpeak presence (avatar, description, nickname,
+ * away status, channel description, now-playing messages).
+ *
+ * Every update is permission-safe: if a feature fails due to insufficient
+ * server permissions, it silently disables itself until the next reconnect.
+ */
+export class BotProfileManager {
+  private tsClient: TS3Client;
+  private logger: Logger;
+  private config: ProfileConfig;
+  private defaultNickname: string;
+
+  /** Per-feature permission-denied flags. Reset on reconnect. */
+  private permDenied = {
+    avatar: false,
+    description: false,
+    nickname: false,
+    awayStatus: false,
+    channelDesc: false,
+    nowPlayingMsg: false,
+  };
+
+  /**
+   * Monotonically increasing generation counter. Incremented on every
+   * onSongChange / onConnect call. Long-running operations (avatar
+   * download/upload) check this before committing their result — if
+   * the generation changed, a newer update has superseded them.
+   */
+  private generation = 0;
+
+  constructor(
+    tsClient: TS3Client,
+    logger: Logger,
+    config: ProfileConfig,
+    defaultNickname: string,
+  ) {
+    this.tsClient = tsClient;
+    this.logger = logger.child({ component: "profile" });
+    this.config = { ...config };
+    this.defaultNickname = defaultNickname;
+  }
+
+  // --- Public API ---
+
+  /**
+   * Called when a new song starts playing (song != null) or playback
+   * stops (song == null).
+   *
+   * Commands are serialized to avoid overwhelming the TS3 command queue.
+   * Nickname + away status are merged into a single `clientupdate` call.
+   *
+   * A generation counter guards against stale updates: if a newer
+   * onSongChange fires while the avatar is still downloading, the old
+   * update is discarded.
+   */
+  async onSongChange(song: QueuedSong | null): Promise<void> {
+    const gen = ++this.generation;
+
+    // 1. Avatar first — file transfer uses its own response tracker and
+    //    must run before sendCommandNoWait calls whose orphaned responses
+    //    could confuse the command matcher.
+    await this.updateAvatar(song?.coverUrl ?? null, gen);
+    if (this.generation !== gen) return; // superseded
+
+    // 2. Combined clientupdate (nickname + away in one fire-and-forget)
+    await this.updateClientProperties(song);
+    // 3. Description (clientedit on TS3, httpQuery on TS6)
+    await this.updateDescription(song);
+    // 4. Channel description (fire-and-forget channeledit)
+    await this.updateChannelDescription(song);
+    // 5. Now-playing chat message
+    if (song) await this.sendNowPlayingMessage(song);
+  }
+
+  /** Reset permission-denied flags and bump generation on new connection. */
+  onConnect(): void {
+    this.generation++;
+    this.permDenied = {
+      avatar: false,
+      description: false,
+      nickname: false,
+      awayStatus: false,
+      channelDesc: false,
+      nowPlayingMsg: false,
+    };
+  }
+
+  getConfig(): ProfileConfig {
+    return { ...this.config };
+  }
+
+  updateConfig(partial: Partial<ProfileConfig>): void {
+    Object.assign(this.config, partial);
+  }
+
+  // --- Internal update methods ---
+
+  private async updateAvatar(coverUrl: string | null, gen: number): Promise<void> {
+    if (!this.config.avatarEnabled || this.permDenied.avatar) return;
+    try {
+      if (!coverUrl) {
+        await this.clearAvatar(gen);
+        return;
+      }
+      // Request a thumbnail from the CDN to stay within TS3's avatar size limit.
+      const thumbUrl = this.thumbnailUrl(coverUrl);
+      const imageBuffer = await this.downloadImage(thumbUrl);
+
+      // Check generation after the slow download — bail if superseded.
+      if (this.generation !== gen) return;
+
+      if (!imageBuffer || imageBuffer.length === 0) return;
+      if (imageBuffer.length > AVATAR_MAX_BYTES) {
+        this.logger.warn(
+          { bytes: imageBuffer.length, max: AVATAR_MAX_BYTES },
+          "Cover image still too large after resize — skipping avatar update",
+        );
+        return;
+      }
+
+      // 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(
+        { bytes: imageBuffer.length, elapsedMs: Date.now() - start },
+        "Avatar updated",
+      );
+    } catch (err) {
+      this.handleFeatureError("avatar", err);
+    }
+  }
+
+  /**
+   * Three-step upload. Each step is logged so the log can tell us whether
+   * a broken/loading avatar on the client is from:
+   *   (a) init failing (no permission)
+   *   (b) file transfer hanging on TCP 30033
+   *   (c) client_flag_avatar not applying
+   * If (b) happens, the avatar MD5 would still be set in the past — leaving
+   * clients showing a placeholder. The flag is now only set after the TCP
+   * transfer resolves.
+   */
+  private async doAvatarUpload(imageBuffer: Buffer): Promise<void> {
+    const host = this.tsClient.getHost();
+    this.logger.debug({ bytes: imageBuffer.length, host }, "Avatar: init file transfer");
+    const info = await this.tsClient.fileTransferInitUpload(
+      0n, "/avatar", "", BigInt(imageBuffer.length), true,
+    );
+    this.logger.debug({ bytes: imageBuffer.length }, "Avatar: uploading file data");
+    await this.tsClient.uploadFileData(host, info, Readable.from(imageBuffer));
+    const md5 = createHash("md5").update(imageBuffer).digest("hex");
+    this.logger.debug({ md5 }, "Avatar: setting client_flag_avatar");
+    await this.tsClient.sendCommandNoWait(`clientupdate client_flag_avatar=${escapeTS3(md5)}`);
+  }
+
+  private async clearAvatar(gen: number): Promise<void> {
+    try {
+      await this.withTimeout(
+        this.tsClient.fileTransferDeleteFile(0n, ["/avatar"]),
+        FILE_TRANSFER_TIMEOUT_MS,
+      );
+    } catch {
+      // File may not exist or transfer timed out — that's fine
+    }
+    // Bail if a newer song started while we were deleting
+    if (this.generation !== gen) return;
+    try {
+      await this.tsClient.sendCommandNoWait("clientupdate client_flag_avatar=");
+    } catch (err) {
+      this.handleFeatureError("avatar", err);
+    }
+  }
+
+  private async updateDescription(song: QueuedSong | null): Promise<void> {
+    if (!this.config.descriptionEnabled || this.permDenied.description) return;
+    try {
+      const text = song
+        ? `${song.name} - ${song.artist} [${song.album}]`
+        : "";
+      const httpQuery = this.tsClient.getHttpQuery();
+      if (httpQuery) {
+        // 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
+        // TS3AudioBot does via TSLib's ChangeDescription().
+        const clid = this.tsClient.getClientId();
+        if (clid <= 0) return;
+        // Use a 5s timeout — if clientedit hangs, don't block the
+        // remaining profile updates (channeledit, now-playing msg).
+        await this.withTimeout(
+          this.tsClient.execCommand(
+            `clientedit clid=${clid} client_description=${escapeTS3(text)}`,
+          ),
+          5000,
+        );
+        this.logger.info("Description updated");
+      }
+    } catch (err) {
+      this.handleFeatureError("description", err);
+    }
+  }
+
+  /**
+   * 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 rawProps: Record<string, string | number> = {};
+
+    // --- Nickname ---
+    if (this.config.nicknameEnabled && !this.permDenied.nickname) {
+      if (!song) {
+        rawProps.client_nickname = this.defaultNickname;
+      } else {
+        const nickname = this.buildNickname(song);
+        if (nickname) {
+          rawProps.client_nickname = nickname;
+        }
+      }
+    }
+
+    // --- Away status ---
+    if (this.config.awayStatusEnabled && !this.permDenied.awayStatus) {
+      if (song) {
+        rawProps.client_away = 0;
+      } else {
+        rawProps.client_away = 1;
+        rawProps.client_away_message = "\u7B49\u5F85\u64AD\u653E";
+      }
+    }
+
+    if (Object.keys(rawProps).length === 0) return;
+
+    try {
+      const httpQuery = this.tsClient.getHttpQuery();
+      if (httpQuery) {
+        // TS6: send raw values as JSON. Throws HttpQueryError on 4xx/5xx.
+        const result = await httpQuery.clientUpdate(rawProps);
+        this.logger.info(
+          { status: result.status, props: Object.keys(rawProps) },
+          "Client properties updated (nickname + away)",
+        );
+      } else {
+        // 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)",
+        );
+      }
+    } catch (err) {
+      // Flag both features on permission error
+      this.handleFeatureError("nickname", err);
+      this.handleFeatureError("awayStatus", err);
+    }
+  }
+
+  /**
+   * Build a nickname string that fits within TS3_NICKNAME_MAX.
+   * Uses UTF-8 byte length for the limit since TS3 counts bytes,
+   * not characters.
+   */
+  private buildNickname(song: QueuedSong): string | null {
+    const songInfo = `${song.name} - ${song.artist}`;
+    const prefix = "\u266A "; // ♪
+    const sep = " - ";
+    const suffix = `${sep}${this.defaultNickname}`;
+
+    const overheadBytes = Buffer.byteLength(prefix, "utf8") + Buffer.byteLength(suffix, "utf8");
+    if (overheadBytes >= TS3_NICKNAME_MAX) {
+      // Default nickname alone is too long with decoration — skip
+      return null;
+    }
+
+    const maxSongBytes = TS3_NICKNAME_MAX - overheadBytes;
+    const truncated = this.truncateUtf8(songInfo, maxSongBytes);
+    return `${prefix}${truncated}${suffix}`;
+  }
+
+  /**
+   * Truncate a string so its UTF-8 byte length does not exceed maxBytes.
+   * Appends an ellipsis if truncation occurred, taking its byte cost
+   * into account. Never splits a multi-byte character.
+   */
+  private truncateUtf8(str: string, maxBytes: number): string {
+    if (Buffer.byteLength(str, "utf8") <= maxBytes) return str;
+    const ellipsis = "\u2026"; // …
+    const ellipsisBytes = Buffer.byteLength(ellipsis, "utf8"); // 3
+    const target = maxBytes - ellipsisBytes;
+    if (target <= 0) return ellipsis;
+    // Walk characters, accumulating byte length
+    let byteLen = 0;
+    let end = 0;
+    for (const ch of str) {
+      const chBytes = Buffer.byteLength(ch, "utf8");
+      if (byteLen + chBytes > target) break;
+      byteLen += chBytes;
+      end += ch.length; // ch.length handles surrogate pairs
+    }
+    return str.slice(0, end) + ellipsis;
+  }
+
+  private async updateChannelDescription(song: QueuedSong | null): Promise<void> {
+    if (!this.config.channelDescEnabled || this.permDenied.channelDesc) return;
+    try {
+      const channelId = this.tsClient.getChannelId();
+      if (channelId === 0n) return; // unknown channel
+
+      if (!song) {
+        await this.tsClient.sendCommandNoWait(
+          `channeledit cid=${channelId} channel_description=`,
+        );
+        return;
+      }
+
+      const lines = [
+        `\u266A \u6B63\u5728\u64AD\u653E: ${song.name} - ${song.artist}`, // ♪ 正在播放:
+        `\u4E13\u8F91: ${song.album}`, // 专辑:
+        `\u5E73\u53F0: ${song.platform}`, // 平台:
+      ];
+      const desc = lines.join("\\n");
+      await this.tsClient.sendCommandNoWait(
+        `channeledit cid=${channelId} channel_description=${escapeTS3(desc)}`,
+      );
+    } catch (err) {
+      this.handleFeatureError("channelDesc", err);
+    }
+  }
+
+  private async sendNowPlayingMessage(song: QueuedSong): Promise<void> {
+    if (!this.config.nowPlayingMsgEnabled || this.permDenied.nowPlayingMsg) return;
+    try {
+      const text = `\u266A \u6B63\u5728\u64AD\u653E: ${song.name} - ${song.artist} [${song.album}]`;
+      await this.tsClient.sendTextMessage(text);
+    } catch (err) {
+      this.handleFeatureError("nowPlayingMsg", err);
+    }
+  }
+
+  // --- Helpers ---
+
+  /**
+   * Append CDN resize parameters to get a thumbnail suitable for TS3 avatars.
+   * NetEase and QQ Music CDNs support URL-based image resizing.
+   * BiliBili and YouTube covers fall through to the size-check guard.
+   */
+  private thumbnailUrl(url: string): string {
+    if (url.includes("music.126.net") || url.includes("netease")) {
+      return url.includes("?") ? url : `${url}?param=200y200`;
+    }
+    if (url.includes("qqmusic") || url.includes("qq.com")) {
+      return url.replace(/\/\d+$/, "/200");
+    }
+    if (url.includes("bilivideo") || url.includes("hdslb")) {
+      // BiliBili CDN supports @<w>w_<h>h suffix
+      return url.includes("@") ? url : `${url}@200w_200h`;
+    }
+    return url;
+  }
+
+  private async downloadImage(url: string): Promise<Buffer | null> {
+    try {
+      const resp = await axios.get(url, {
+        responseType: "arraybuffer",
+        timeout: 8000,
+        maxContentLength: 2 * 1024 * 1024, // 2 MB cap
+      });
+      return Buffer.from(resp.data);
+    } catch (err) {
+      this.logger.warn({ err, url }, "Failed to download cover image");
+      return null;
+    }
+  }
+
+  /** Race a promise against a timeout. */
+  private withTimeout<T>(promise: Promise<T>, ms: number): Promise<T> {
+    return Promise.race([
+      promise,
+      new Promise<never>((_, reject) =>
+        setTimeout(() => reject(new Error(`Timed out after ${ms}ms`)), ms),
+      ),
+    ]);
+  }
+
+  private handleFeatureError(
+    feature: keyof typeof this.permDenied,
+    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
+    // - 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") ||
+      status === 400 ||
+      status === 401 ||
+      status === 403;
+    if (isUnrecoverable) {
+      this.permDenied[feature] = true;
+      this.logger.info(
+        { feature, status, body, reason: msg },
+        "Feature disabled for this session (will retry after reconnect)",
+      );
+    } else {
+      this.logger.warn({ feature, status, body, err }, "Profile update failed");
+    }
+  }
+}
@@ -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,
  };
 }

@@ -60,12 +60,15 @@ describe("database", () => {
      defaultChannel: "Music",
      channelPassword: "",
      autoStart: true,
+      serverProtocol: "",
+      ts6ApiKey: "",
+      serverPassword: "",
    };

    botDb.saveBotInstance(instance);
    const instances = botDb.getBotInstances();
    expect(instances).toHaveLength(1);
-    expect(instances[0]).toEqual(instance);
+    expect(instances[0]).toMatchObject(instance);
    expect(instances[0].autoStart).toBe(true);

    // Test upsert
@@ -86,6 +89,9 @@ describe("database", () => {
      defaultChannel: "Music",
      channelPassword: "",
      autoStart: false,
+      serverProtocol: "",
+      ts6ApiKey: "",
+      serverPassword: "",
    });

    expect(botDb.deleteBotInstance("bot1")).toBe(true);
@@ -6,7 +6,7 @@ export interface PlayHistoryEntry {
  songName: string;
  artist: string;
  album: string;
-  platform: "netease" | "qq" | "bilibili";
+  platform: "netease" | "qq" | "bilibili" | "youtube";
  coverUrl: string;
 }

@@ -24,8 +24,33 @@ export interface BotInstance {
  defaultChannel: string;
  channelPassword: string;
  autoStart: boolean;
+  /** "ts3" | "ts6" | "" (empty = auto-detect) */
+  serverProtocol: string;
+  /** API key for TS6 HTTP Query */
+  ts6ApiKey: string;
+  /** Password to join the TS server (server password) */
+  serverPassword: string;
+  identity?: string;
 }

+export interface ProfileConfig {
+  avatarEnabled: boolean;
+  descriptionEnabled: boolean;
+  nicknameEnabled: boolean;
+  awayStatusEnabled: boolean;
+  channelDescEnabled: boolean;
+  nowPlayingMsgEnabled: boolean;
+}
+
+export const DEFAULT_PROFILE_CONFIG: ProfileConfig = {
+  avatarEnabled: true,
+  descriptionEnabled: true,
+  nicknameEnabled: true,
+  awayStatusEnabled: true,
+  channelDescEnabled: true,
+  nowPlayingMsgEnabled: true,
+};
+
 export interface BotDatabase {
  db: Database.Database;
  addPlayHistory(entry: PlayHistoryEntry): void;
@@ -33,9 +58,42 @@ export interface BotDatabase {
  saveBotInstance(instance: BotInstance): void;
  getBotInstances(): BotInstance[];
  deleteBotInstance(id: string): boolean;
+  getProfileConfig(botId: string): ProfileConfig;
+  saveProfileConfig(botId: string, config: ProfileConfig): void;
  close(): void;
 }

+function migrateSchema(db: Database.Database): void {
+  const columns = db.prepare("PRAGMA table_info(bot_instances)").all() as Array<{ name: string }>;
+  const names = columns.map((c) => c.name);
+  if (!names.includes("identity")) {
+    db.exec("ALTER TABLE bot_instances ADD COLUMN identity TEXT");
+  }
+  if (!names.includes("serverProtocol")) {
+    db.exec("ALTER TABLE bot_instances ADD COLUMN serverProtocol TEXT NOT NULL DEFAULT ''");
+  }
+  if (!names.includes("ts6ApiKey")) {
+    db.exec("ALTER TABLE bot_instances ADD COLUMN ts6ApiKey TEXT NOT NULL DEFAULT ''");
+  }
+  if (!names.includes("serverPassword")) {
+    db.exec("ALTER TABLE bot_instances ADD COLUMN serverPassword TEXT NOT NULL DEFAULT ''");
+  }
+  // Profile feature flags
+  const profileCols = [
+    "profile_avatar_enabled",
+    "profile_description_enabled",
+    "profile_nickname_enabled",
+    "profile_away_enabled",
+    "profile_channel_desc_enabled",
+    "profile_now_playing_enabled",
+  ];
+  for (const col of profileCols) {
+    if (!names.includes(col)) {
+      db.exec(`ALTER TABLE bot_instances ADD COLUMN ${col} INTEGER NOT NULL DEFAULT 1`);
+    }
+  }
+}
+
 function initTables(db: Database.Database): void {
  db.exec(`
    CREATE TABLE IF NOT EXISTS play_history (
@@ -58,7 +116,11 @@ function initTables(db: Database.Database): void {
      nickname TEXT NOT NULL,
      defaultChannel TEXT NOT NULL,
      channelPassword TEXT NOT NULL,
-      autoStart INTEGER NOT NULL DEFAULT 0
+      autoStart INTEGER NOT NULL DEFAULT 0,
+      serverProtocol TEXT NOT NULL DEFAULT '',
+      ts6ApiKey TEXT NOT NULL DEFAULT '',
+      serverPassword TEXT NOT NULL DEFAULT '',
+      identity TEXT
    );
  `);
 }
@@ -67,6 +129,7 @@ export function createDatabase(dbPath: string): BotDatabase {
  const db = new Database(dbPath);
  db.pragma("journal_mode = WAL");
  initTables(db);
+  migrateSchema(db);

  const insertHistory = db.prepare(`
    INSERT INTO play_history (botId, songId, songName, artist, album, platform, coverUrl)
@@ -78,8 +141,8 @@ export function createDatabase(dbPath: string): BotDatabase {
  `);

  const upsertInstance = db.prepare(`
-    INSERT INTO bot_instances (id, name, serverAddress, serverPort, nickname, defaultChannel, channelPassword, autoStart)
-    VALUES (@id, @name, @serverAddress, @serverPort, @nickname, @defaultChannel, @channelPassword, @autoStart)
+    INSERT INTO bot_instances (id, name, serverAddress, serverPort, nickname, defaultChannel, channelPassword, autoStart, serverProtocol, ts6ApiKey, serverPassword, identity)
+    VALUES (@id, @name, @serverAddress, @serverPort, @nickname, @defaultChannel, @channelPassword, @autoStart, @serverProtocol, @ts6ApiKey, @serverPassword, @identity)
    ON CONFLICT(id) DO UPDATE SET
      name = excluded.name,
      serverAddress = excluded.serverAddress,
@@ -87,13 +150,35 @@ export function createDatabase(dbPath: string): BotDatabase {
      nickname = excluded.nickname,
      defaultChannel = excluded.defaultChannel,
      channelPassword = excluded.channelPassword,
-      autoStart = excluded.autoStart
+      autoStart = excluded.autoStart,
+      serverProtocol = excluded.serverProtocol,
+      ts6ApiKey = excluded.ts6ApiKey,
+      serverPassword = excluded.serverPassword,
+      identity = excluded.identity
  `);

  const selectInstances = db.prepare(`SELECT * FROM bot_instances`);

  const deleteInstance = db.prepare(`DELETE FROM bot_instances WHERE id = ?`);

+  const selectProfileConfig = db.prepare(`
+    SELECT profile_avatar_enabled, profile_description_enabled,
+           profile_nickname_enabled, profile_away_enabled,
+           profile_channel_desc_enabled, profile_now_playing_enabled
+    FROM bot_instances WHERE id = ?
+  `);
+
+  const updateProfileConfig = db.prepare(`
+    UPDATE bot_instances SET
+      profile_avatar_enabled = @avatar,
+      profile_description_enabled = @description,
+      profile_nickname_enabled = @nickname,
+      profile_away_enabled = @away,
+      profile_channel_desc_enabled = @channelDesc,
+      profile_now_playing_enabled = @nowPlaying
+    WHERE id = @id
+  `);
+
  return {
    db,

@@ -109,14 +194,22 @@ export function createDatabase(dbPath: string): BotDatabase {
      upsertInstance.run({
        ...instance,
        autoStart: instance.autoStart ? 1 : 0,
+        identity: instance.identity ?? null,
      });
    },

    getBotInstances() {
      const rows = selectInstances.all() as Array<
-        Omit<BotInstance, "autoStart"> & { autoStart: number }
+        Omit<BotInstance, "autoStart" | "identity"> & { autoStart: number; identity: string | null }
      >;
-      return rows.map((r) => ({ ...r, autoStart: r.autoStart === 1 }));
+      return rows.map((r) => ({
+        ...r,
+        autoStart: r.autoStart === 1,
+        serverProtocol: r.serverProtocol ?? "",
+        ts6ApiKey: r.ts6ApiKey ?? "",
+        serverPassword: r.serverPassword ?? "",
+        identity: r.identity ?? undefined,
+      }));
    },

    deleteBotInstance(id) {
@@ -124,6 +217,31 @@ export function createDatabase(dbPath: string): BotDatabase {
      return result.changes > 0;
    },

+    getProfileConfig(botId) {
+      const row = selectProfileConfig.get(botId) as Record<string, number> | undefined;
+      if (!row) return { ...DEFAULT_PROFILE_CONFIG };
+      return {
+        avatarEnabled: row.profile_avatar_enabled === 1,
+        descriptionEnabled: row.profile_description_enabled === 1,
+        nicknameEnabled: row.profile_nickname_enabled === 1,
+        awayStatusEnabled: row.profile_away_enabled === 1,
+        channelDescEnabled: row.profile_channel_desc_enabled === 1,
+        nowPlayingMsgEnabled: row.profile_now_playing_enabled === 1,
+      };
+    },
+
+    saveProfileConfig(botId, config) {
+      updateProfileConfig.run({
+        id: botId,
+        avatar: config.avatarEnabled ? 1 : 0,
+        description: config.descriptionEnabled ? 1 : 0,
+        nickname: config.nicknameEnabled ? 1 : 0,
+        away: config.awayStatusEnabled ? 1 : 0,
+        channelDesc: config.channelDescEnabled ? 1 : 0,
+        nowPlaying: config.nowPlayingMsgEnabled ? 1 : 0,
+      });
+    },
+
    close() {
      db.close();
    },
@@ -25,6 +25,14 @@ async function main() {
  saveConfig(CONFIG_PATH, config);

  const logger = createLogger(LOG_DIR);
+
+  // Prevent unhandled errors from crashing the process
+  process.on("uncaughtException", (err) => {
+    logger.error({ err }, "Uncaught exception");
+  });
+  process.on("unhandledRejection", (reason) => {
+    logger.error({ reason }, "Unhandled promise rejection");
+  });
  const db = createDatabase(DB_PATH);

  const apiServer = createApiServerManager(
@@ -63,6 +71,7 @@ async function main() {
    bilibiliProvider,
    database: db,
    config,
+    configPath: CONFIG_PATH,
    logger,
    cookieStore,
    staticDir: STATIC_DIR,
@@ -70,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...");
@@ -17,7 +17,9 @@ export interface ApiServerManager {
 function isPortFree(port: number): Promise<boolean> {
  return new Promise((resolve) => {
    const server = net.createServer();
-    server.once("error", () => resolve(false));
+    server.once("error", () => {
+      server.close(() => resolve(false));
+    });
    server.once("listening", () => {
      server.close(() => resolve(true));
    });
@@ -30,6 +32,7 @@ export function createApiServerManager(
  logger: Logger
 ): ApiServerManager {
  let neteaseServer: Server | null = null;
+  let qqMusicServer: Server | null = null;

  const neteaseBaseUrl = `http://127.0.0.1:${options.neteasePort}`;
  const qqMusicBaseUrl = `http://127.0.0.1:${options.qqMusicPort}`;
@@ -60,7 +63,10 @@ export function createApiServerManager(
        logger.error({ err }, "Failed to start NetEase Cloud Music API");
      }

-      // Start QQ Music API (auto-starts on import)
+      // Start QQ Music API. Older versions auto-started on import; the
+      // current fork (2.2.11+) only listens when run as `require.main`,
+      // so we explicitly call .listen() on the imported Koa app and keep
+      // the server handle for clean shutdown.
      try {
        const portFree = await isPortFree(options.qqMusicPort);
        if (!portFree) {
@@ -69,11 +75,29 @@ export function createApiServerManager(
            "QQ Music API port already in use — reusing existing instance"
          );
        } else {
-          await import("@sansenjian/qq-music-api");
-          logger.info(
-            { port: options.qqMusicPort },
-            "QQ Music API started"
-          );
+          const qqModule = (await import("@sansenjian/qq-music-api")) as any;
+          // 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", () =>
+                resolve(srv)
+              );
+              srv.on("error", reject);
+            });
+            logger.info(
+              { port: options.qqMusicPort },
+              "QQ Music API started"
+            );
+          } else {
+            logger.warn("QQ Music API module does not expose a Koa app");
+          }
        }
      } catch (err) {
        logger.warn(
@@ -89,6 +113,10 @@ export function createApiServerManager(
        (neteaseServer as any).close();
      }
      neteaseServer = null;
+      if (qqMusicServer && typeof (qqMusicServer as any).close === "function") {
+        (qqMusicServer as any).close();
+      }
+      qqMusicServer = null;
    },

    getNeteaseBaseUrl(): string {
@@ -3,6 +3,7 @@ import type {
  MusicProvider,
  Song,
  Playlist,
+  PlaylistDetail,
  LyricLine,
  SearchResult,
  QrCodeResult,
@@ -319,6 +320,21 @@ export class NeteaseProvider implements MusicProvider {
    }));
  }

+  async getPlaylistDetail(playlistId: string): Promise<PlaylistDetail | null> {
+    const res = await this.api.get("/playlist/detail", {
+      params: { id: playlistId, ...this.cookieParams },
+    });
+    const p = res.data?.playlist;
+    if (!p) return null;
+    return {
+      id: String(p.id),
+      name: p.name ?? "",
+      description: p.description ?? "",
+      coverUrl: p.coverImgUrl ?? "",
+      songCount: p.trackCount ?? 0,
+    };
+  }
+
  async getUserPlaylists(): Promise<Playlist[]> {
    // First get user ID from login status
    const statusRes = await this.api.get("/login/status", {
@@ -5,7 +5,7 @@ export interface Song {
  album: string;
  duration: number; // seconds
  coverUrl: string;
-  platform: "netease" | "qq" | "bilibili";
+  platform: "netease" | "qq" | "bilibili" | "youtube";
 }

 export interface SongWithUrl extends Song {
@@ -17,7 +17,15 @@ export interface Playlist {
  name: string;
  coverUrl: string;
  songCount: number;
-  platform: "netease" | "qq" | "bilibili";
+  platform: "netease" | "qq" | "bilibili" | "youtube";
+}
+
+export interface PlaylistDetail {
+  id: string;
+  name: string;
+  description: string;
+  coverUrl: string;
+  songCount: number;
 }

 export interface Album {
@@ -26,7 +34,7 @@ export interface Album {
  artist: string;
  coverUrl: string;
  songCount: number;
-  platform: "netease" | "qq" | "bilibili";
+  platform: "netease" | "qq" | "bilibili" | "youtube";
 }

 export interface LyricLine {
@@ -54,7 +62,7 @@ export interface AuthStatus {
 }

 export interface MusicProvider {
-  readonly platform: "netease" | "qq" | "bilibili";
+  readonly platform: "netease" | "qq" | "bilibili" | "youtube";

  search(query: string, limit?: number): Promise<SearchResult>;
  getSongUrl(songId: string, quality?: string): Promise<string | null>;
@@ -77,4 +85,5 @@ export interface MusicProvider {
  getPersonalFm?(): Promise<Song[]>;
  getDailyRecommendSongs?(): Promise<Song[]>;
  getUserPlaylists?(): Promise<Playlist[]>;
+  getPlaylistDetail?(playlistId: string): Promise<PlaylistDetail | null>;
 }
@@ -3,6 +3,7 @@ import type {
  MusicProvider,
  Song,
  Playlist,
+  PlaylistDetail,
  LyricLine,
  SearchResult,
  QrCodeResult,
@@ -10,6 +11,30 @@ import type {
 } from "./provider.js";
 import { parseLyrics } from "./netease.js";

+// Direct QQ Music API client — bypasses the local API server for search
+// because @sansenjian/qq-music-api still uses the broken c.y.qq.com endpoint.
+const qqDirectApi = axios.create({
+  baseURL: "https://u.y.qq.com",
+  timeout: 10000,
+  headers: { referer: "https://y.qq.com" },
+});
+
+// Direct client for c.y.qq.com endpoints (collected playlists / favorites).
+// The bundled qq-music-api wrapper doesn't expose these endpoints.
+const qqFavApi = axios.create({
+  baseURL: "https://c.y.qq.com",
+  timeout: 10000,
+  headers: { referer: "https://y.qq.com/" },
+});
+
+function computeGtk(pSkey: string): number {
+  let hash = 5381;
+  for (let i = 0; i < pSkey.length; i++) {
+    hash = (hash + (hash << 5) + pSkey.charCodeAt(i)) | 0;
+  }
+  return hash & 0x7fffffff;
+}
+
 export class QQMusicProvider implements MusicProvider {
  readonly platform = "qq" as const;
  private api: AxiosInstance;
@@ -36,37 +61,111 @@ export class QQMusicProvider implements MusicProvider {
  }

  async search(query: string, limit = 20): Promise<SearchResult> {
-    const res = await this.api.get("/getSearchByKey", {
-      params: { key: query, pageSize: limit, ...this.cookieParams },
+    const reqData = JSON.stringify({
+      req_0: {
+        module: "music.search.SearchCgiService",
+        method: "DoSearchForQQMusicDesktop",
+        param: {
+          searchid: "1",
+          query,
+          num_per_page: Math.min(limit, 50),
+        },
+      },
    });
+    const res = await qqDirectApi.get("/cgi-bin/musicu.fcg", {
+      params: { format: "json", data: reqData },
+    });
+    const list: any[] =
+      res.data?.req_0?.data?.body?.song?.list ?? [];

-    const songs: Song[] = (res.data?.response?.data?.song?.list ?? []).map(
-      (s: any) => ({
-        id: String(s.songmid ?? s.songid),
-        name: s.songname ?? "",
-        artist: (s.singer ?? []).map((a: any) => a.name).join(" / "),
-        album: s.albumname ?? "",
-        duration: s.interval ?? 0,
-        coverUrl: s.albummid
-          ? `https://y.gtimg.cn/music/photo_new/T002R300x300M000${s.albummid}.jpg`
-          : "",
-        platform: "qq",
-      })
-    );
+    const songs: Song[] = list.map((s: any) => ({
+      id: String(s.mid ?? s.id),
+      name: s.title ?? s.name ?? "",
+      artist: (s.singer ?? []).map((a: any) => a.name).join(" / "),
+      album: s.album?.name ?? s.album?.title ?? "",
+      duration: s.interval ?? 0,
+      coverUrl: s.album?.mid
+        ? `https://y.gtimg.cn/music/photo_new/T002R300x300M000${s.album.mid}.jpg`
+        : "",
+      platform: "qq",
+    }));

    return { songs, playlists: [], albums: [] };
  }

-  async getSongUrl(songId: string, _quality?: string): Promise<string | null> {
-    const res = await this.api.get("/getMusicPlay", {
-      params: { songmid: songId, ...this.cookieParams },
-    });
-    const playUrl = res.data?.data?.playUrl?.[songId];
-    return playUrl?.url || null;
+  async getSongUrl(songId: string, quality?: string): Promise<string | null> {
+    try {
+      const res = await this.api.get("/getMusicPlay", {
+        params: { songmid: songId, quality: quality ?? this.quality, ...this.cookieParams },
+      });
+      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;
+  }
+
+  /**
+   * Batch-check which song mids are actually streamable. QQ playlists
+   * (especially collected ones) frequently contain a majority of songs
+   * that return result=104003 ("no copyright/region restricted") for the
+   * current user — a sequential retry loop wastes time guessing.
+   *
+   * The wrapper's /getMusicPlay accepts a comma-separated songmid list
+   * and resolves all of them in a single upstream call. We chunk to keep
+   * the URL well under typical 8KB query-string limits and to keep per-
+   * request latency bounded (~2-3s per 100 mids).
+   *
+   * Returns:
+   *   - non-null Set: authoritative result. Empty Set means all songs are
+   *     unplayable; non-empty means filter to those mids.
+   *   - null: every chunk failed. Caller should fall back to sequential
+   *     retry rather than treating as "all unplayable".
+   */
+  async getPlayableSongIds(songIds: string[]): Promise<Set<string> | null> {
+    if (songIds.length === 0) return new Set();
+
+    const CHUNK = 100;          // ~14 chars/mid * 100 + commas ≈ 1.5KB
+    const playable = new Set<string>();
+    let allChunksFailed = true;
+    for (let i = 0; i < songIds.length; i += CHUNK) {
+      const slice = songIds.slice(i, i + CHUNK);
+      try {
+        const res = await this.api.get("/getMusicPlay", {
+          params: { songmid: slice.join(","), quality: this.quality, ...this.cookieParams },
+        });
+        const playUrlMap: Record<string, { url?: string }> | undefined =
+          res.data?.data?.playUrl;
+        if (!playUrlMap) continue; // chunk-level failure, try next
+        allChunksFailed = false;
+        for (const [mid, info] of Object.entries(playUrlMap)) {
+          if (info?.url) playable.add(mid);
+        }
+      } catch {
+        // chunk-level failure — keep going so a transient error on one
+        // chunk doesn't poison the whole batch.
+      }
+    }
+    return allChunksFailed ? null : playable;
  }

  async getSongDetail(songId: string): Promise<Song | null> {
-    // getSongInfo requires cookie; use search as fallback
+    // Try /getSongInfo for full metadata, but fall through to a minimal
+    // stub if the library endpoint fails (current @sansenjian/qq-music-api
+    // returns upstream code 500001 for this route — the param format it
+    // sends doesn't match QQ's current API). The bot's resolveAndPlay path
+    // only needs `id` and `platform` to fetch a play URL, and the fallback
+    // stub is sufficient to let /play-by-id and /add-by-id flows succeed.
    try {
      const res = await this.api.get("/getSongInfo", {
        params: { songmid: songId, ...this.cookieParams },
@@ -87,9 +186,20 @@ export class QQMusicProvider implements MusicProvider {
        };
      }
    } catch {
-      // fallback: search by songmid (less reliable)
+      // fall through to stub
    }
-    return null;
+    // Minimal stub — resolveAndPlay only needs id + platform to fetch a
+    // play URL. Name/artist/album will be empty in play history, but the
+    // song will actually play, which is the important part.
+    return {
+      id: songId,
+      name: "",
+      artist: "",
+      album: "",
+      duration: 0,
+      coverUrl: "",
+      platform: "qq",
+    };
  }

  async getPlaylistSongs(playlistId: string): Promise<Song[]> {
@@ -99,18 +209,35 @@ export class QQMusicProvider implements MusicProvider {
    const cdlist = res.data?.response?.cdlist ?? [];
    if (cdlist.length === 0) return [];
    return (cdlist[0].songlist ?? []).map((s: any) => ({
-      id: String(s.songmid ?? s.songid),
+      id: String(s.mid ?? s.songmid ?? s.songid),
      name: s.songname ?? s.name ?? "",
      artist: (s.singer ?? []).map((a: any) => a.name).join(" / "),
      album: s.albumname ?? "",
      duration: s.interval ?? 0,
-      coverUrl: s.albummid
+      coverUrl: s.album?.mid
+        ? `https://y.gtimg.cn/music/photo_new/T002R300x300M000${s.album.mid}.jpg`
+        : s.albummid
        ? `https://y.gtimg.cn/music/photo_new/T002R300x300M000${s.albummid}.jpg`
        : "",
      platform: "qq",
    }));
  }

+  async getPlaylistDetail(playlistId: string): Promise<PlaylistDetail | null> {
+    const res = await this.api.get("/getSongListDetail", {
+      params: { disstid: playlistId, ...this.cookieParams },
+    });
+    const cd = res.data?.response?.cdlist?.[0];
+    if (!cd) return null;
+    return {
+      id: String(cd.disstid ?? cd.dissid ?? ""),
+      name: cd.dissname ?? "",
+      description: cd.desc ?? "",
+      coverUrl: cd.logo ?? "",
+      songCount: cd.songnum ?? cd.total_song_num ?? 0,
+    };
+  }
+
  async getRecommendPlaylists(): Promise<Playlist[]> {
    const res = await this.api.get("/getSongLists", {
      params: { categoryId: 10000000, pageSize: 10, ...this.cookieParams },
@@ -152,30 +279,53 @@ export class QQMusicProvider implements MusicProvider {
  }

  async getQrCode(): Promise<QrCodeResult> {
+    // @sansenjian/qq-music-api 2.x returns { img, qrsig, ptqrtoken } via
+    // customResponse (no { response: ... } wrapping). /checkQQLoginQr
+    // requires BOTH qrsig AND ptqrtoken — passing only one gives a 400
+    // "参数错误". Pack both into the opaque `key` field so the polling
+    // endpoint can split them back out. Separator "|" is safe: QQ tokens
+    // are alphanumeric.
    const res = await this.api.get("/getQQLoginQr");
+    const qrsig: string = res.data?.qrsig ?? "";
+    const ptqrtoken: string = String(res.data?.ptqrtoken ?? "");
    return {
      qrUrl: "",
      qrImg: res.data?.img ?? "",
-      key: res.data?.qrsig ?? res.data?.ptqrtoken ?? "",
+      key: `${qrsig}|${ptqrtoken}`,
    };
  }

  async checkQrCodeStatus(
    key: string
  ): Promise<"waiting" | "scanned" | "confirmed" | "expired"> {
-    const res = await this.api.get("/checkQQLoginQr", {
-      params: { qrsig: key },
-    });
-    const code = res.data?.code ?? res.data?.response?.code;
-    if (code === 0) {
-      if (res.data?.cookie) {
-        this.cookie = res.data.cookie;
-      }
+    const [qrsig, ptqrtoken] = key.split("|");
+    if (!qrsig || !ptqrtoken) return "expired";
+
+    // NOTE: /checkQQLoginQr is registered as POST only in
+    // @sansenjian/qq-music-api 2.x. GET returns 405 Method Not Allowed.
+    let res;
+    try {
+      res = await this.api.post("/checkQQLoginQr", null, {
+        params: { qrsig, ptqrtoken },
+      });
+    } catch {
+      return "expired";
+    }
+
+    // customResponse shape:
+    //   success:  { isOk: true, message: '登录成功', session: { cookie, ... } }
+    //   scanning: { isOk: false, refresh: false, message: '未扫描二维码' }
+    //   expired:  { isOk: false, refresh: true,  message: '二维码已失效' }
+    const body = res.data;
+    if (body?.isOk === true) {
+      const cookie: string = body.session?.cookie ?? "";
+      if (cookie) this.cookie = cookie;
      return "confirmed";
    }
-    if (code === 1) return "scanned";
-    if (code === 2) return "waiting";
-    return "expired";
+    if (body?.refresh === true) return "expired";
+    if (typeof body?.message === "string" && body.message.includes("未扫描"))
+      return "waiting";
+    return "waiting";
  }

  setCookie(cookie: string): void {
@@ -188,20 +338,145 @@ export class QQMusicProvider implements MusicProvider {

  async getAuthStatus(): Promise<AuthStatus> {
    if (!this.cookie) return { loggedIn: false };
+    // /getUserAvatar in @sansenjian/qq-music-api 2.x is NOT registered on
+    // the main router; the real endpoint is /user/getUserAvatar, and even
+    // that just builds a static URL from a uin without validating the
+    // cookie against QQ. Round-trip through /user/getUserPlaylists which
+    // actually hits QQ Music with the cookie; if the upstream returns
+    // code=0, the cookie is valid.
+    //
+    // IMPORTANT: /user/getUserPlaylists requires `uin` as a query param —
+    // the library 400s with "缺少 uin 参数" otherwise. Parse it out of the
+    // cookie (uin=<qq>; comes after the various *uin prefixed names, which
+    // is why the regex anchors on a word boundary).
+    const uinMatch = /(?:^|; )uin=o?0?(\d+)/.exec(this.cookie);
+    const uin = uinMatch ? uinMatch[1] : "";
+    if (!uin) return { loggedIn: false };
    try {
-      const res = await this.api.get("/getUserAvatar", {
+      const res = await this.api.get("/user/getUserPlaylists", {
+        params: { uin, ...this.cookieParams },
+      });
+      if (res.data?.response?.code !== 0) return { loggedIn: false };
+      return {
+        loggedIn: true,
+        nickname: `QQ ${uin}`,
+        avatarUrl: `https://q.qlogo.cn/headimg_dl?dst_uin=${uin}&spec=100`,
+      };
+    } catch {
+      return { loggedIn: false };
+    }
+  }
+
+  async getDailyRecommendSongs(): Promise<Song[]> {
+    // QQ has no per-user daily list; use newsong.NewSongServer (新歌速递)
+    // as the closest analogue. Returns ~20 newly-released songs.
+    try {
+      const res = await this.api.get("/getNewSongs", {
        params: { ...this.cookieParams },
      });
-      if (res.data?.response?.data) {
+      const list: any[] = res.data?.response?.new_song?.data?.songlist ?? [];
+      return list.map((s: any) => ({
+        id: String(s.mid ?? s.id),
+        name: s.title ?? s.name ?? "",
+        artist: (s.singer ?? []).map((a: any) => a.name).join(" / "),
+        album: s.album?.name ?? s.album?.title ?? "",
+        duration: s.interval ?? 0,
+        coverUrl: s.album?.mid
+          ? `https://y.gtimg.cn/music/photo_new/T002R300x300M000${s.album.mid}.jpg`
+          : "",
+        platform: "qq",
+      }));
+    } catch {
+      return [];
+    }
+  }
+
+  async getUserPlaylists(): Promise<Playlist[]> {
+    if (!this.cookie) return [];
+    const uinMatch = /(?:^|; )uin=o?0?(\d+)/.exec(this.cookie);
+    const uin = uinMatch ? uinMatch[1] : "";
+    if (!uin) return [];
+
+    // Created and collected playlists come from two separate QQ endpoints.
+    // Run them in parallel and concatenate (created first, then collected),
+    // matching the order shown in the QQ Music desktop app.
+    const [created, collected] = await Promise.all([
+      this.fetchCreatedPlaylists(uin),
+      this.fetchCollectedPlaylists(uin),
+    ]);
+    return [...created, ...collected];
+  }
+
+  private async fetchCreatedPlaylists(uin: string): Promise<Playlist[]> {
+    try {
+      const res = await this.api.get("/user/getUserPlaylists", {
+        params: { uin, ...this.cookieParams },
+      });
+      if (res.data?.response?.code !== 0) return [];
+      return (res.data?.response?.data?.playlists ?? []).map((p: any) => {
+        // fcg_get_profile_homepage returns title/picurl/subtitle ("X首  Y次播放").
+        const subtitle: string = p.subtitle ?? "";
+        const songCountFromSubtitle = parseInt(subtitle.match(/(\d+)\s*首/)?.[1] ?? "0", 10);
        return {
-          loggedIn: true,
-          nickname: res.data.response.data.nickname,
-          avatarUrl: res.data.response.data.headpic,
+          id: String(p.dissid ?? p.id ?? ""),
+          name: p.title ?? p.dissname ?? p.name ?? "",
+          coverUrl: p.picurl ?? p.imgurl ?? p.coverUrl ?? "",
+          songCount: p.song_count ?? p.listennum ?? songCountFromSubtitle,
+          platform: "qq",
        };
+      });
+    } catch {
+      return [];
+    }
+  }
+
+  private async fetchCollectedPlaylists(uin: string): Promise<Playlist[]> {
+    // c.y.qq.com fav endpoint: reqtype=3 returns collected playlists (cdlist).
+    // Requires g_tk derived from the p_skey cookie.
+    const pSkeyMatch = /(?:^|; )p_skey=([^;]+)/.exec(this.cookie);
+    if (!pSkeyMatch) return [];
+    const gtk = computeGtk(pSkeyMatch[1]);
+
+    const PAGE_SIZE = 30;
+    const MAX_PAGES = 10;       // 300-playlist hard cap; should cover any sane user
+    const all: Playlist[] = [];
+    try {
+      for (let page = 0; page < MAX_PAGES; page++) {
+        const sin = page * PAGE_SIZE;
+        const ein = sin + PAGE_SIZE - 1;
+        const res = await qqFavApi.get("/fav/fcgi-bin/fcg_get_profile_order_asset.fcg", {
+          params: {
+            ct: 20,
+            cid: 205360956,
+            userid: uin,
+            reqtype: 3,
+            sin,
+            ein,
+            g_tk: gtk,
+            format: "json",
+          },
+          headers: { Cookie: this.cookie },
+        });
+        if (res.data?.code !== 0) break;
+        const list: any[] = res.data?.data?.cdlist ?? [];
+        for (const p of list) {
+          all.push({
+            id: String(p.dissid ?? ""),
+            name: p.dissname ?? "",
+            coverUrl: p.logo ?? "",
+            songCount: p.songnum ?? 0,
+            platform: "qq",
+          });
+        }
+        // Stop when upstream signals no more pages, or when this page is
+        // short (also indicates end). has_more is the canonical signal.
+        const hasMore = res.data?.data?.has_more === 1 || res.data?.data?.has_more === true;
+        if (!hasMore || list.length < PAGE_SIZE) break;
      }
    } catch {
-      // ignore
+      // Return whatever we got so far on partial failure rather than dropping
+      // earlier pages.
    }
-    return { loggedIn: false };
+    return all;
  }
 }
@@ -0,0 +1,232 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { existsSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+import type {
+  MusicProvider,
+  Song,
+  SongWithUrl,
+  Playlist,
+  Album,
+  SearchResult,
+  LyricLine,
+  QrCodeResult,
+  AuthStatus,
+} from "./provider.js";
+
+const execFileAsync = promisify(execFile);
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+/** Resolve the yt-dlp binary path. Checks the project bin/ dir first, then PATH. */
+function findYtDlp(): string {
+  const exe = process.platform === "win32" ? "yt-dlp.exe" : "yt-dlp";
+  const candidates = [
+    join(__dirname, "..", "..", "bin", exe),
+    join(__dirname, "..", "..", "bin", "yt-dlp"),
+    exe,
+  ];
+  for (const c of candidates) {
+    // Absolute/relative paths: only return if the file exists.
+    // Bare names: return and let execFile resolve via PATH.
+    const isBinPath = c.includes(join("bin", "yt-dlp"));
+    if (!isBinPath || existsSync(c)) return c;
+  }
+  return exe;
+}
+
+/**
+ * Availability check for yt-dlp. Runs `yt-dlp --version` and caches only
+ * the positive result — if the binary is missing, subsequent calls retry
+ * so the user can install yt-dlp while the server is running and pick it
+ * up without a restart. Used by getAuthStatus() so the UI can reflect
+ * whether YouTube is actually usable.
+ */
+let cachedAvailable = false;
+let pendingCheck: Promise<boolean> | null = null;
+async function checkYtDlpAvailable(): Promise<boolean> {
+  if (cachedAvailable) return true;
+  if (pendingCheck) return pendingCheck;
+  pendingCheck = (async () => {
+    try {
+      await execFileAsync(findYtDlp(), ["--version"], {
+        timeout: 5_000,
+        maxBuffer: 1024,
+      });
+      cachedAvailable = true;
+      return true;
+    } catch {
+      return false;
+    } finally {
+      pendingCheck = null;
+    }
+  })();
+  return pendingCheck;
+}
+
+/** Force re-detection on the next call (for tests). */
+export function resetYtDlpAvailabilityCache(): void {
+  cachedAvailable = false;
+  pendingCheck = null;
+}
+
+async function runYtDlp(args: string[], timeoutMs = 30_000): Promise<string> {
+  const binary = findYtDlp();
+  const env = { ...process.env };
+  if (process.env.HTTPS_PROXY || process.env.HTTP_PROXY) {
+    // yt-dlp respects these env vars natively
+  }
+  const { stdout } = await execFileAsync(binary, args, {
+    timeout: timeoutMs,
+    env,
+    maxBuffer: 10 * 1024 * 1024,
+  });
+  return stdout;
+}
+
+interface YtDlpEntry {
+  id: string;
+  title: string;
+  uploader?: string;
+  channel?: string;
+  duration?: number;
+  thumbnail?: string;
+  webpage_url?: string;
+  url?: string;
+  entries?: YtDlpEntry[];
+  _type?: string;
+}
+
+function entryToSong(entry: YtDlpEntry): Song {
+  return {
+    id: entry.id ?? "",
+    name: entry.title ?? "Unknown",
+    artist: entry.uploader ?? entry.channel ?? "YouTube",
+    album: "YouTube",
+    duration: Math.round(entry.duration ?? 0),
+    coverUrl: entry.thumbnail ?? "",
+    platform: "youtube",
+  };
+}
+
+export class YouTubeProvider implements MusicProvider {
+  readonly platform = "youtube" as const;
+  private quality = "bestaudio";
+
+  async search(query: string, limit = 5): Promise<SearchResult> {
+    try {
+      const raw = await runYtDlp([
+        `ytsearch${limit}:${query}`,
+        "--dump-json",
+        "--flat-playlist",
+        "--no-warnings",
+        "--quiet",
+      ]);
+      const lines = raw.trim().split("\n").filter(Boolean);
+      const songs: Song[] = lines.map((line) => {
+        const entry = JSON.parse(line) as YtDlpEntry;
+        return entryToSong(entry);
+      });
+      return { songs, playlists: [], albums: [] };
+    } catch {
+      return { songs: [], playlists: [], albums: [] };
+    }
+  }
+
+  async getSongUrl(songId: string): Promise<string | null> {
+    try {
+      const url = `https://www.youtube.com/watch?v=${songId}`;
+      const raw = await runYtDlp([
+        url,
+        "--get-url",
+        "-f",
+        "bestaudio[ext=webm]/bestaudio[ext=m4a]/bestaudio",
+        "--no-warnings",
+        "--quiet",
+      ], 45_000);
+      const audioUrl = raw.trim().split("\n")[0];
+      return audioUrl || null;
+    } catch {
+      return null;
+    }
+  }
+
+  setQuality(quality: string): void {
+    this.quality = quality;
+  }
+
+  getQuality(): string {
+    return this.quality;
+  }
+
+  async getSongDetail(songId: string): Promise<Song | null> {
+    try {
+      const url = `https://www.youtube.com/watch?v=${songId}`;
+      const raw = await runYtDlp([url, "--dump-json", "--no-warnings", "--quiet"]);
+      const entry = JSON.parse(raw.trim()) as YtDlpEntry;
+      return entryToSong(entry);
+    } catch {
+      return null;
+    }
+  }
+
+  async getPlaylistSongs(playlistId: string): Promise<Song[]> {
+    try {
+      const url = playlistId.startsWith("http")
+        ? playlistId
+        : `https://www.youtube.com/playlist?list=${playlistId}`;
+      const raw = await runYtDlp([
+        url,
+        "--dump-json",
+        "--flat-playlist",
+        "--no-warnings",
+        "--quiet",
+      ], 60_000);
+      const lines = raw.trim().split("\n").filter(Boolean);
+      return lines.map((line) => entryToSong(JSON.parse(line) as YtDlpEntry));
+    } catch {
+      return [];
+    }
+  }
+
+  async getRecommendPlaylists(): Promise<Playlist[]> {
+    return [];
+  }
+
+  async getAlbumSongs(_albumId: string): Promise<Song[]> {
+    return [];
+  }
+
+  async getLyrics(_songId: string): Promise<LyricLine[]> {
+    return [];
+  }
+
+  async getQrCode(): Promise<QrCodeResult> {
+    return { qrUrl: "", key: "" };
+  }
+
+  async checkQrCodeStatus(
+    _key: string
+  ): Promise<"waiting" | "scanned" | "confirmed" | "expired"> {
+    return "expired";
+  }
+
+  setCookie(_cookie: string): void {}
+  getCookie(): string { return ""; }
+
+  async getAuthStatus(): Promise<AuthStatus> {
+    // YouTube has no login concept via yt-dlp, so "loggedIn" here means
+    // "yt-dlp binary is reachable and responds to --version". The UI can
+    // use this flag to grey out YouTube when the optional dependency is
+    // missing, instead of silently returning empty search results.
+    const available = await checkYtDlpAvailable();
+    if (available) {
+      return { loggedIn: true, nickname: "YouTube (yt-dlp)" };
+    }
+    return {
+      loggedIn: false,
+      nickname: "YouTube (yt-dlp not installed)",
+    };
+  }
+}
@@ -1,4 +1,5 @@
 import { EventEmitter } from "node:events";
+import { Readable } from "node:stream";
 import {
  Client as TS3FullClient,
  generateIdentity as genTS3Identity,
@@ -7,23 +8,48 @@ import {
  listChannels,
  listClients,
  clientMove,
+  fileTransferDeleteFile,
  type Identity,
  type TextMessage,
  type ClientInfo,
+  type FileUploadInfo,
 } from "@honeybbq/teamspeak-client";
 import type { Logger } from "../logger.js";
+import {
+  detectServerProtocol,
+  type ServerProtocol,
+} from "./protocol-detect.js";
+import { TS6HttpQuery } from "./http-query.js";

 export { CODEC_OPUS_MUSIC } from "./voice.js";
+export type { ServerProtocol } from "./protocol-detect.js";
+export type { FileUploadInfo } from "@honeybbq/teamspeak-client";
+
+/** Escape a string for use in TS3 ServerQuery-style commands. */
+export function escapeTS3(str: string): string {
+  return str
+    .replace(/\\/g, "\\\\")
+    .replace(/ /g, "\\s")
+    .replace(/\//g, "\\/")
+    .replace(/\|/g, "\\p")
+    .replace(/\t/g, "\\t")
+    .replace(/\n/g, "\\n")
+    .replace(/\r/g, "\\r");
+}

 export interface TS3ClientOptions {
  host: string;
  port: number; // Voice/virtual server port (default 9987)
-  queryPort: number; // ServerQuery port (default 10011) — unused now, kept for compat
+  queryPort: number; // ServerQuery port (10011 for TS3, 10080 for TS6 HTTP)
  nickname: string;
  identity?: string; // Exported identity string, or undefined to generate new
  defaultChannel?: string;
  channelPassword?: string;
  serverPassword?: string;
+  /** Force a specific protocol instead of auto-detecting. */
+  serverProtocol?: ServerProtocol;
+  /** API key for TS6 HTTP Query authentication. */
+  ts6ApiKey?: string;
 }

 export interface TS3TextMessage {
@@ -40,6 +66,9 @@ export class TS3Client extends EventEmitter {
  private clientId = 0;
  private logger: Logger;
  private disconnecting = false;
+  private detectedProtocol: ServerProtocol = "unknown";
+  private httpQuery: TS6HttpQuery | null = null;
+  private udpErrorTimer: ReturnType<typeof setTimeout> | null = null;

  constructor(private options: TS3ClientOptions, logger: Logger) {
    super();
@@ -52,25 +81,105 @@ export class TS3Client extends EventEmitter {
    }
  }

+  /** The detected (or forced) server protocol after connect(). */
+  getServerProtocol(): ServerProtocol {
+    return this.detectedProtocol;
+  }
+
+  /** TS6 HTTP Query client (available after connecting to a TS6 server). */
+  getHttpQuery(): TS6HttpQuery | null {
+    return this.httpQuery;
+  }
+
  async connect(): Promise<void> {
+    // Clean up any existing connection before creating a new one
+    if (this.client) {
+      this.logger.info("Cleaning up previous connection before reconnecting");
+      try {
+        await this.client.disconnect();
+      } catch {
+        // Ignore errors during cleanup
+      }
+      this.client = null;
+      this.clientId = 0;
+    }
+
    const addr = `${this.options.host}:${this.options.port}`;
-    this.logger.info({ addr }, "Connecting to TeamSpeak server (full client protocol)");
+
+    // Detect or use forced protocol
+    if (this.options.serverProtocol && this.options.serverProtocol !== "unknown") {
+      this.detectedProtocol = this.options.serverProtocol;
+      this.logger.info(
+        { addr, protocol: this.detectedProtocol },
+        "Using forced server protocol",
+      );
+    } else {
+      this.logger.info({ addr }, "Detecting server protocol (TS3/TS6)...");
+      const detection = await detectServerProtocol(
+        this.options.host,
+        this.options.port,
+        3000,
+        { ts3QueryPort: 10011, ts6HttpPort: 10080 },
+      );
+      this.detectedProtocol = detection.protocol;
+      if (this.detectedProtocol === "unknown") {
+        this.logger.warn(
+          { addr },
+          "Could not detect server protocol (query ports 10011/10080 unreachable). " +
+            "Will attempt voice connection anyway. Use serverProtocol option to force TS3 or TS6.",
+        );
+      } else {
+        this.logger.info(
+          { addr, protocol: this.detectedProtocol, queryPort: detection.queryPort },
+          `Server protocol detected: ${this.detectedProtocol.toUpperCase()}`,
+        );
+      }
+    }
+
+    // Set up TS6 HTTP Query if applicable
+    if (this.detectedProtocol === "ts6") {
+      const queryPort = this.options.queryPort !== 10011 ? this.options.queryPort : 10080;
+      this.httpQuery = new TS6HttpQuery({
+        host: this.options.host,
+        port: queryPort,
+        apiKey: this.options.ts6ApiKey,
+      });
+    }
+
+    // Guard against calling connect() while already connected.
+    // Save detectedProtocol first because disconnect() resets it.
+    if (this.client) {
+      this.logger.warn("connect() called while already connected, disconnecting first");
+      const savedProtocol = this.detectedProtocol;
+      const savedHttpQuery = this.httpQuery;
+      this.disconnect();
+      this.detectedProtocol = savedProtocol;
+      this.httpQuery = savedHttpQuery;
+      // Give the old client a moment to tear down
+      await new Promise((r) => setTimeout(r, 100));
+    }
+
+    this.logger.info(
+      { addr, protocol: this.detectedProtocol },
+      "Connecting to TeamSpeak server (full client protocol)",
+    );

    // Throttle repeated "udp send error" warnings (fires every 20ms during playback if UDP breaks)
    let udpErrorCount = 0;
-    let udpErrorTimer: ReturnType<typeof setTimeout> | null = null;
    const throttledWarn = (msg: string, ...args: unknown[]) => {
      if (typeof msg === "string" && msg.includes("udp send error")) {
        udpErrorCount++;
        if (udpErrorCount === 1) {
          this.logger.warn(msg);
-          // After 2 seconds, log a summary and reset
-          udpErrorTimer = setTimeout(() => {
+          // After 2 seconds, log a summary and reset.
+          // Clear any previous timer to avoid leaking it.
+          if (this.udpErrorTimer) clearTimeout(this.udpErrorTimer);
+          this.udpErrorTimer = setTimeout(() => {
            if (udpErrorCount > 1) {
              this.logger.warn(`udp send error (repeated ${udpErrorCount} times, connection may be lost)`);
            }
            udpErrorCount = 0;
-            udpErrorTimer = null;
+            this.udpErrorTimer = null;
          }, 2000);
        }
        return;
@@ -79,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),
@@ -112,9 +224,19 @@ export class TS3Client extends EventEmitter {
    });

    await this.client.connect();
+    // Note: @honeybbq/teamspeak-client 0.2.x ships a universal clientinit
+    // (client_version "3.?.? [Build: 5680278000]" + matching signature)
+    // that works against both TS3 and TS6 servers. The old 3.6.2 monkey-
+    // patch on handler.sendPacket was removed when we bumped to 0.2.1 — it
+    // would have replaced the library's new correct version with a stale
+    // signature and made TS6 handshakes fail.
    await this.client.waitConnected();
    this.clientId = this.client.clientID();
-    this.logger.info({ clientId: this.clientId }, "Logged in (visible client)");
+    this.voiceFramesSent = 0;
+    this.logger.info(
+      { clientId: this.clientId, protocol: this.detectedProtocol },
+      `Logged in (visible client, ${this.detectedProtocol.toUpperCase()} server)`,
+    );

    // Join default channel if specified
    if (this.options.defaultChannel) {
@@ -175,6 +297,56 @@ export class TS3Client extends EventEmitter {
    }
  }

+  // --- Raw command & file transfer pass-through ---
+
+  async execCommand(cmd: string): Promise<void> {
+    if (!this.client) throw new Error("Not connected");
+    await this.client.execCommand(cmd);
+  }
+
+  /** Fire a command without waiting for the server's response. */
+  async sendCommandNoWait(cmd: string): Promise<void> {
+    if (!this.client) throw new Error("Not connected");
+    await this.client.sendCommandNoWait(cmd);
+  }
+
+  async execCommandWithResponse(cmd: string): Promise<Record<string, string>[]> {
+    if (!this.client) throw new Error("Not connected");
+    return this.client.execCommandWithResponse(cmd);
+  }
+
+  async fileTransferInitUpload(
+    channelID: bigint,
+    path: string,
+    password: string,
+    size: bigint,
+    overwrite = true,
+  ): Promise<FileUploadInfo> {
+    if (!this.client) throw new Error("Not connected");
+    return this.client.fileTransferInitUpload(channelID, path, password, size, overwrite);
+  }
+
+  async uploadFileData(host: string, info: FileUploadInfo, data: Readable): Promise<void> {
+    if (!this.client) throw new Error("Not connected");
+    await this.client.uploadFileData(host, info, data);
+  }
+
+  async fileTransferDeleteFile(channelID: bigint, paths: string[]): Promise<void> {
+    if (!this.client) throw new Error("Not connected");
+    await fileTransferDeleteFile(this.client, channelID, paths);
+  }
+
+  /** The server host (needed for file transfer TCP connections). */
+  getHost(): string {
+    return this.options.host;
+  }
+
+  /** The current channel ID of this client. */
+  getChannelId(): bigint {
+    if (!this.client) return 0n;
+    return this.client.channelID();
+  }
+
  private voiceFramesSent = 0;

  sendVoiceData(opusFrame: Buffer): void {
@@ -212,6 +384,12 @@ export class TS3Client extends EventEmitter {
      });
    }
    this.clientId = 0;
+    this.httpQuery = null;
+    this.detectedProtocol = "unknown";
+    if (this.udpErrorTimer) {
+      clearTimeout(this.udpErrorTimer);
+      this.udpErrorTimer = null;
+    }
    this.logger.info("Disconnected from TeamSpeak server");
  }
 }
@@ -1,10 +1,17 @@
+/**
+ * TS3 raw-TCP ServerQuery connection (port 10011).
+ *
+ * @deprecated This module only works with TS3 servers. TS6 servers replaced
+ * the raw-TCP ServerQuery with HTTP/HTTPS (port 10080/10443) and SSH (10022).
+ * For TS6 servers, use {@link ../http-query.js TS6HttpQuery} instead.
+ */
 import net from "node:net";
 import { EventEmitter } from "node:events";
 import { encodeCommand, decodeResponse, parseErrorLine } from "./commands.js";

 export interface ConnectionOptions {
  host: string;
-  port: number; // ServerQuery port, typically 10011
+  port: number; // ServerQuery port: 10011 (TS3) — not available on TS6
 }

 export interface CommandResult {
@@ -0,0 +1,223 @@
+import http from "node:http";
+import https from "node:https";
+
+export interface HttpQueryOptions {
+  host: string;
+  port: number; // 10080 (HTTP) or 10443 (HTTPS)
+  useTls?: boolean;
+  apiKey?: string;
+  timeoutMs?: number;
+}
+
+export interface HttpQueryResult {
+  status: number;
+  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.
+ *
+ * TeamSpeak 6 Server replaces the TS3 raw-TCP ServerQuery (port 10011)
+ * with an HTTP/HTTPS API on ports 10080/10443.
+ *
+ * Common endpoints (TS6 HTTP Query):
+ *   GET  /                         → server info / health check
+ *   POST /api-key                  → create API key
+ *   GET  /1/serverlist             → list virtual servers
+ *   GET  /1/clientlist?sid={sid}   → list clients
+ *   POST /1/sendtextmessage        → send text message
+ *   POST /1/clientmove             → move a client
+ *   GET  /1/channellist?sid={sid}  → list channels
+ *   POST /1/clientupdate           → update client properties
+ */
+export class TS6HttpQuery {
+  private options: Required<HttpQueryOptions>;
+
+  constructor(options: HttpQueryOptions) {
+    this.options = {
+      host: options.host,
+      port: options.port,
+      useTls: options.useTls ?? options.port === 10443,
+      apiKey: options.apiKey ?? "",
+      timeoutMs: options.timeoutMs ?? 5000,
+    };
+  }
+
+  async request(
+    method: "GET" | "POST" | "PUT" | "DELETE",
+    path: string,
+    body?: Record<string, unknown>,
+  ): Promise<HttpQueryResult> {
+    const { host, port, useTls, apiKey, timeoutMs } = this.options;
+    const transport = useTls ? https : http;
+
+    const headers: Record<string, string> = {
+      Accept: "application/json",
+    };
+    if (apiKey) {
+      headers["x-api-key"] = apiKey;
+    }
+
+    let bodyStr: string | undefined;
+    if (body) {
+      bodyStr = JSON.stringify(body);
+      headers["Content-Type"] = "application/json";
+      headers["Content-Length"] = String(Buffer.byteLength(bodyStr));
+    }
+
+    return new Promise((resolve, reject) => {
+      let settled = false;
+      const fail = (err: Error) => {
+        if (settled) return;
+        settled = true;
+        reject(err);
+      };
+
+      const req = transport.request(
+        {
+          hostname: host,
+          port,
+          path,
+          method,
+          timeout: timeoutMs,
+          headers,
+          rejectUnauthorized: false, // self-signed certs common on self-hosted
+        },
+        (res) => {
+          let data = "";
+          res.setEncoding("utf-8");
+          res.on("data", (chunk: string) => (data += chunk));
+          res.on("error", fail);
+          res.on("end", () => {
+            if (settled) return;
+            settled = true;
+            let parsed: unknown;
+            try {
+              parsed = JSON.parse(data);
+            } catch {
+              parsed = data;
+            }
+            resolve({
+              status: res.statusCode ?? 0,
+              body: parsed,
+            });
+          });
+        },
+      );
+
+      req.on("error", fail);
+      req.on("timeout", () => {
+        req.destroy();
+        fail(new Error("TS6 HTTP Query timeout"));
+      });
+
+      if (bodyStr) {
+        req.write(bodyStr);
+      }
+      req.end();
+    });
+  }
+
+  /** Check if the TS6 HTTP Query is reachable */
+  async healthCheck(): Promise<boolean> {
+    try {
+      const result = await this.request("GET", "/");
+      return result.status >= 200 && result.status < 500;
+    } catch {
+      return false;
+    }
+  }
+
+  /** List virtual servers */
+  async serverList(): Promise<HttpQueryResult> {
+    return this.request("GET", "/1/serverlist");
+  }
+
+  /** List clients on a virtual server */
+  async clientList(sid = 1): Promise<HttpQueryResult> {
+    return this.request("GET", `/1/clientlist?sid=${sid}`);
+  }
+
+  /** List channels on a virtual server */
+  async channelList(sid = 1): Promise<HttpQueryResult> {
+    return this.request("GET", `/1/channellist?sid=${sid}`);
+  }
+
+  /** Send a text message */
+  async sendTextMessage(
+    targetMode: number,
+    target: number,
+    msg: string,
+    sid = 1,
+  ): Promise<HttpQueryResult> {
+    return this.request("POST", `/1/sendtextmessage?sid=${sid}`, {
+      targetmode: targetMode,
+      target,
+      msg,
+    });
+  }
+
+  /**
+   * 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> {
+    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 */
+  async clientMove(
+    clid: number,
+    cid: number,
+    cpw?: string,
+    sid = 1,
+  ): Promise<HttpQueryResult> {
+    const body: Record<string, unknown> = { clid, cid };
+    if (cpw) body.cpw = cpw;
+    return this.request("POST", `/1/clientmove?sid=${sid}`, body);
+  }
+}
@@ -0,0 +1,23 @@
+import { describe, it, expect } from "vitest";
+import {
+  detectServerProtocol,
+  type ServerProtocol,
+  type ProtocolDetectResult,
+} from "./protocol-detect.js";
+
+describe("protocol-detect", () => {
+  it("returns unknown for unreachable hosts", async () => {
+    const result = await detectServerProtocol("192.0.2.1", 9987, 1000);
+    expect(result.protocol).toBe("unknown");
+    expect(result.queryPort).toBeNull();
+    expect(result.voicePort).toBe(9987);
+  });
+
+  it("result shape matches ProtocolDetectResult interface", async () => {
+    const result = await detectServerProtocol("127.0.0.1", 9987, 500);
+    expect(result).toHaveProperty("protocol");
+    expect(result).toHaveProperty("queryPort");
+    expect(result).toHaveProperty("voicePort");
+    expect(["ts3", "ts6", "unknown"]).toContain(result.protocol);
+  });
+});
@@ -0,0 +1,128 @@
+import net from "node:net";
+import http from "node:http";
+
+export type ServerProtocol = "ts3" | "ts6" | "unknown";
+
+export interface ProtocolDetectResult {
+  protocol: ServerProtocol;
+  /** The query port that responded (10011 for TS3, 10080 for TS6 HTTP) */
+  queryPort: number | null;
+  /** Whether the voice port (UDP 9987) is the same for both */
+  voicePort: number;
+}
+
+export interface DetectOptions {
+  /** TS3 ServerQuery probe port (default: 10011) */
+  ts3QueryPort?: number;
+  /** TS6 HTTP Query probe port (default: 10080) */
+  ts6HttpPort?: number;
+}
+
+/**
+ * Probe a TeamSpeak server to determine if it's running TS3 or TS6.
+ *
+ * Detection strategy:
+ *  1. Try TCP connect to port 10011 (TS3 ServerQuery) — if banner starts with "TS3", it's TS3.
+ *  2. Try HTTP GET to port 10080 (TS6 HTTP Query) — if we get a valid HTTP response, it's TS6.
+ *  3. If neither responds, return "unknown" (voice-only connection may still work).
+ */
+export async function detectServerProtocol(
+  host: string,
+  voicePort = 9987,
+  timeoutMs = 3000,
+  options?: DetectOptions,
+): Promise<ProtocolDetectResult> {
+  const ts3Port = options?.ts3QueryPort ?? 10011;
+  const ts6Port = options?.ts6HttpPort ?? 10080;
+
+  const [ts3, ts6] = await Promise.allSettled([
+    probeTS3Query(host, ts3Port, timeoutMs),
+    probeTS6HttpQuery(host, ts6Port, timeoutMs),
+  ]);
+
+  // Prefer TS3 if both somehow respond (shouldn't happen in practice)
+  if (ts3.status === "fulfilled" && ts3.value) {
+    return { protocol: "ts3", queryPort: ts3Port, voicePort };
+  }
+  if (ts6.status === "fulfilled" && ts6.value) {
+    return { protocol: "ts6", queryPort: ts6Port, voicePort };
+  }
+
+  return { protocol: "unknown", queryPort: null, voicePort };
+}
+
+/**
+ * Probe TS3 ServerQuery by connecting to raw TCP and checking for "TS3" banner.
+ */
+function probeTS3Query(host: string, port: number, timeoutMs: number): Promise<boolean> {
+  return new Promise((resolve) => {
+    let resolved = false;
+    const done = (value: boolean) => {
+      if (resolved) return;
+      resolved = true;
+      socket.removeAllListeners();
+      socket.destroy();
+      resolve(value);
+    };
+
+    const socket = net.createConnection({ host, port, timeout: timeoutMs });
+    let banner = "";
+    const MAX_BANNER = 256; // TS3 banner is ~50 bytes; cap to avoid memory abuse
+
+    socket.setTimeout(timeoutMs);
+
+    socket.on("data", (data: Buffer) => {
+      banner += data.toString("utf-8");
+      if (banner.length > MAX_BANNER) banner = banner.slice(0, MAX_BANNER);
+      if (banner.includes("TS3")) {
+        done(true);
+      }
+    });
+
+    socket.on("connect", () => {
+      // Wait briefly for banner after TCP connect
+      setTimeout(() => done(banner.includes("TS3")), 500);
+    });
+
+    socket.on("error", () => done(false));
+    socket.on("timeout", () => done(false));
+  });
+}
+
+/**
+ * Probe TS6 HTTP Query by sending GET / and checking for a valid response.
+ * Any HTTP status (including 401/403) confirms the TS6 HTTP Query exists.
+ */
+function probeTS6HttpQuery(host: string, port: number, timeoutMs: number): Promise<boolean> {
+  return new Promise((resolve) => {
+    let resolved = false;
+    const done = (value: boolean) => {
+      if (resolved) return;
+      resolved = true;
+      resolve(value);
+    };
+
+    const req = http.request(
+      {
+        hostname: host,
+        port,
+        path: "/",
+        method: "GET",
+        timeout: timeoutMs,
+        headers: { Accept: "application/json" },
+      },
+      (res) => {
+        res.resume();
+        done(res.statusCode !== undefined);
+      },
+    );
+
+    req.on("error", () => done(false));
+    req.on("timeout", () => {
+      req.destroy();
+      done(false);
+    });
+
+    req.end();
+  });
+}
@@ -1,5 +1,6 @@
 import { Router } from "express";
 import type { MusicProvider } from "../../music/provider.js";
+import { YouTubeProvider } from "../../music/youtube.js";
 import type { CookieStore } from "../../music/auth.js";
 import type { Logger } from "../../logger.js";

@@ -11,9 +12,13 @@ export function createAuthRouter(
  cookieStore?: CookieStore
 ): Router {
  const router = Router();
+  // YouTube is auth-less; we only use this instance so /auth/status can
+  // report whether yt-dlp is actually installed (loggedIn=false otherwise).
+  const youtubeProvider: MusicProvider = new YouTubeProvider();

  function getProvider(platform?: string): MusicProvider {
    if (platform === "bilibili") return bilibiliProvider;
+    if (platform === "youtube") return youtubeProvider;
    return platform === "qq" ? qqProvider : neteaseProvider;
  }

@@ -119,6 +124,14 @@ export function createAuthRouter(
      res.status(400).json({ error: "cookie is required" });
      return;
    }
+    // YouTube has no cookie concept — reject instead of falling through and
+    // clobbering the NetEase cookie entry.
+    if (platform === "youtube") {
+      res
+        .status(400)
+        .json({ error: "YouTube does not use cookies (uses yt-dlp binary)" });
+      return;
+    }
    const provider = getProvider(platform);
    provider.setCookie(cookie);
    const plat = platform === "bilibili" ? "bilibili" as const
@@ -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();
@@ -43,6 +45,7 @@ export function createBotRouter(
        nickname,
        defaultChannel,
        channelPassword,
+        serverPassword,
        autoStart,
      } = req.body;
      if (!name || !serverAddress || !nickname) {
@@ -58,6 +61,7 @@ export function createBotRouter(
        nickname,
        defaultChannel,
        channelPassword,
+        serverPassword,
        autoStart: autoStart ?? false,
      });
      res.status(201).json(bot.getStatus());
@@ -75,10 +79,10 @@ export function createBotRouter(
        res.status(404).json({ error: "Bot not found" });
        return;
      }
-      const { name, serverAddress, serverPort, nickname, defaultChannel, channelPassword } = req.body;
+      const { name, serverAddress, serverPort, nickname, defaultChannel, channelPassword, serverPassword } = req.body;
      // Update in database
      botManager.updateBot(req.params.id, {
-        name, serverAddress, serverPort, nickname, defaultChannel, channelPassword,
+        name, serverAddress, serverPort, nickname, defaultChannel, channelPassword, serverPassword,
      });
      res.json({ success: true });
    } catch (err) {
@@ -113,6 +117,27 @@ export function createBotRouter(
      res.status(500).json({ error: (err as Error).message });
    }
  });
+  
+  // 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;
 }
@@ -1,5 +1,6 @@
 import { Router } from "express";
 import type { MusicProvider } from "../../music/provider.js";
+import { YouTubeProvider } from "../../music/youtube.js";
 import type { Logger } from "../../logger.js";

 export function createMusicRouter(
@@ -9,9 +10,11 @@ export function createMusicRouter(
  logger: Logger
 ): Router {
  const router = Router();
+  const youtubeProvider: MusicProvider = new YouTubeProvider();

  function getProvider(platform?: string): MusicProvider {
    if (platform === "bilibili") return bilibiliProvider;
+    if (platform === "youtube") return youtubeProvider;
    return platform === "qq" ? qqProvider : neteaseProvider;
  }

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

+  /** Map API platform string to the corresponding command flag. */
+  const platformFlag = (platform: unknown): string => {
+    if (platform === "bilibili") return "-b";
+    if (platform === "qq") return "-q";
+    if (platform === "youtube") return "-y";
+    return "";
+  };
+
  router.post("/:botId/play", async (req, res) => {
    try {
      const bot = (req as any).bot;
@@ -33,8 +41,7 @@ export function createPlayerRouter(
        res.status(400).json({ error: "query is required" });
        return;
      }
-      const flags = platform === "bilibili" ? "-b" : platform === "qq" ? "-q" : "";
-      const cmd = parseCommand(`!play ${flags} ${query}`.trim(), "!");
+      const cmd = parseCommand(`!play ${platformFlag(platform)} ${query}`.trim(), "!");
      if (!cmd) {
        res.status(400).json({ error: "Invalid command" });
        return;
@@ -50,8 +57,7 @@ export function createPlayerRouter(
    try {
      const bot = (req as any).bot;
      const { query, platform } = req.body;
-      const flags = platform === "bilibili" ? "-b" : platform === "qq" ? "-q" : "";
-      const cmd = parseCommand(`!add ${flags} ${query}`.trim(), "!");
+      const cmd = parseCommand(`!add ${platformFlag(platform)} ${query}`.trim(), "!");
      if (!cmd) {
        res.status(400).json({ error: "Invalid command" });
        return;
@@ -85,7 +91,21 @@ export function createPlayerRouter(
    try {
      const bot = (req as any).bot;
      const { volume } = req.body;
-      const cmd = parseCommand(`!vol ${volume}`, "!")!;
+      // Reject bad input with a proper 4xx instead of letting cmdVol
+      // return a "Usage:" string inside a 200 body — API clients can't
+      // detect that failure mode, and the UI would silently swallow it.
+      if (
+        typeof volume !== "number" ||
+        !Number.isFinite(volume) ||
+        volume < 0 ||
+        volume > 100
+      ) {
+        res
+          .status(400)
+          .json({ error: "volume must be a number between 0 and 100" });
+        return;
+      }
+      const cmd = parseCommand(`!vol ${Math.round(volume)}`, "!")!;
      const response = await bot.executeCommand(cmd);
      res.json({ message: response });
    } catch (err) {
@@ -93,10 +113,18 @@ export function createPlayerRouter(
    }
  });

+  const VALID_MODES = new Set(["seq", "loop", "random", "rloop"]);
+
  router.post("/:botId/mode", async (req, res) => {
    try {
      const bot = (req as any).bot;
      const { mode } = req.body;
+      if (typeof mode !== "string" || !VALID_MODES.has(mode)) {
+        res
+          .status(400)
+          .json({ error: "mode must be one of: seq, loop, random, rloop" });
+        return;
+      }
      const cmd = parseCommand(`!mode ${mode}`, "!")!;
      const response = await bot.executeCommand(cmd);
      res.json({ message: response });
@@ -116,8 +144,12 @@ export function createPlayerRouter(
    try {
      const bot = (req as any).bot;
      const { position } = req.body; // seconds
-      if (typeof position !== "number" || position < 0) {
-        res.status(400).json({ error: "position (seconds) is required" });
+      // typeof NaN === "number" and NaN < 0 is false, so a plain range
+      // check lets NaN/Infinity through and later corrupts seekOffset.
+      if (typeof position !== "number" || !Number.isFinite(position) || position < 0) {
+        res
+          .status(400)
+          .json({ error: "position must be a finite non-negative number" });
        return;
      }
      bot.getPlayer().seek(position);
@@ -153,7 +185,15 @@ export function createPlayerRouter(
        return;
      }
      const queue = bot.getQueueManager();
-      bot.getPlayer().stop(); // Stop current playback first
+      // Validate the index BEFORE stopping current playback — otherwise an
+      // invalid index silently kills the user's current song and leaves the
+      // queue idle.
+      if (index >= queue.size()) {
+        res.status(400).json({ error: "Invalid queue index" });
+        return;
+      }
+      bot.getPlayer().stop();
+      bot.getPlayer().resetFailures();
      const song = queue.playAt(index);
      if (!song) {
        res.status(400).json({ error: "Invalid queue index" });
@@ -174,9 +214,8 @@ export function createPlayerRouter(
    try {
      const bot = (req as any).bot;
      const { playlistId, platform } = req.body;
-      const flags = platform === "bilibili" ? "-b" : platform === "qq" ? "-q" : "";
      const cmd = parseCommand(
-        `!playlist ${flags} ${playlistId}`.trim(),
+        `!playlist ${platformFlag(platform)} ${playlistId}`.trim(),
        "!"
      )!;
      const response = await bot.executeCommand(cmd);
@@ -192,14 +231,17 @@ export function createPlayerRouter(
    try {
      const bot = (req as any).bot;
      const { playlistId, platform } = req.body;
-      const provider = platform === "bilibili" ? bilibiliProvider : platform === "qq" ? qqProvider : neteaseProvider;
-      if (!provider) {
-        res.status(500).json({ error: "Provider not available" });
-        return;
-      }
+      // Use the bot's own provider lookup — it already knows about youtube,
+      // which the router's constructor params did not.
+      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.getPlaylistSongs(playlistId);
      if (songs.length === 0) {
@@ -207,9 +249,32 @@ export function createPlayerRouter(
        return;
      }

+      // QQ-specific optimization: many users' QQ playlists contain a
+      // large fraction of songs that return result=104003 (region/copyright
+      // restricted). Batch-resolve URLs once and only queue the playable
+      // ones, otherwise the playback retry loop wastes time guessing.
+      let queueable: { id: string }[] = songs;
+      const totalCount = songs.length;
+      const qqLike = provider as { getPlayableSongIds?: (ids: string[]) => Promise<Set<string> | null> };
+      if (typeof qqLike.getPlayableSongIds === "function") {
+        const playable = await qqLike.getPlayableSongIds(songs.map((s: { id: string }) => s.id));
+        if (playable !== null) {
+          // Authoritative answer from upstream — even an empty set means
+          // "we know none are playable", short-circuit immediately rather
+          // than wasting 20+ retries.
+          queueable = songs.filter((s: { id: string }) => playable.has(s.id));
+        }
+        // If null, the batch endpoint itself errored — fall through to
+        // the sequential retry path, which still has a chance.
+      }
+      if (queueable.length === 0) {
+        res.json({ ok: false, message: `歌单 ${totalCount} 首歌曲均无版权可播放（区域/版权限制）` });
+        return;
+      }
+
      const queue = bot.getQueueManager();
      queue.clear();
-      for (const song of songs) {
+      for (const song of queueable) {
        queue.add({ ...song, platform: provider.platform });
      }

@@ -223,11 +288,25 @@ export function createPlayerRouter(
        first = queue.play();
      }

-      if (first) {
-        await bot.resolveAndPlay(first);
+      // If the first picked song can't resolve (e.g., QQ song with no
+      // streaming entitlement → result 104003), fall back to playNext's
+      // retry-skip behavior. Use a higher retry budget than the default
+      // trackEnd auto-advance because user-initiated playlist plays
+      // commonly have long contiguous runs of unplayable songs.
+      let started = first ? await bot.resolveAndPlay(first) : false;
+      if (first && !started) {
+        started = await bot.playNext(20);
      }

-      res.json({ message: `Loaded ${songs.length} songs. Now playing: ${first?.name ?? "unknown"}` });
+      const playing = queue.current();
+      const loadedMsg = queueable.length < totalCount
+        ? `已加载 ${queueable.length}/${totalCount} 首（其余区域/版权限制）`
+        : `已加载 ${queueable.length} 首`;
+      if (started && playing) {
+        res.json({ ok: true, message: `${loadedMsg}，正在播放：${playing.name}` });
+      } else {
+        res.json({ ok: false, message: `${loadedMsg}，但无法开始播放。` });
+      }
    } catch (err) {
      logger.error({ err }, "Play playlist failed");
      res.status(500).json({ error: (err as Error).message });
@@ -235,34 +314,94 @@ export function createPlayerRouter(
  });

  // Play a single song by ID — resolves URL on demand
-  router.post("/:botId/play-by-id", async (req, res) => {
+  router.post("/:botId/play-song", async (req, res) => {
    try {
      const bot = (req as any).bot;
-      const { songId, platform } = req.body;
-      const provider = platform === "bilibili" ? bilibiliProvider : platform === "qq" ? qqProvider : neteaseProvider;
-      if (!provider) {
-        res.status(500).json({ error: "Provider not available" });
+      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 song = await provider.getSongDetail(songId);
-      if (!song) {
-        res.json({ message: "Song not found" });
-        return;
-      }
-
      const queue = bot.getQueueManager();
      queue.clear();
-      queue.add({ ...song, platform: provider.platform });
+      queue.add(song);
      queue.play();

+      bot.getPlayer().resetFailures();
      const ok = await bot.resolveAndPlay(queue.current()!);
      if (!ok) {
-        res.json({ message: `Cannot play: ${song.name}` });
+        res.json({ ok: false, message: `无法播放「${song.name || song.id}」（区域/版权限制）` });
        return;
      }

-      res.json({ message: `Now playing: ${song.name} - ${song.artist}` });
+      res.json({ ok: true, message: `正在播放：${song.name || 'Unknown'} - ${song.artist || 'Unknown'}` });
+    } catch (err) {
+      res.status(500).json({ error: (err as Error).message });
+    }
+  });
+
+  // Insert a single song to play right after the current one.
+  // If nothing is playing, behaves like /play-song (start immediately).
+  router.post("/:botId/play-next-song", async (req, res) => {
+    try {
+      const bot = (req as any).bot;
+      const { song } = req.body;
+      if (!song || !song.id || !song.platform) {
+        res.status(400).json({ error: "song object with id and platform is required" });
+        return;
+      }
+      const queue = bot.getQueueManager();
+      const wasIdle = bot.getPlayer().getState() === "idle";
+      // Capture the slot addNext WILL insert at, before mutating the queue.
+      // addNext pushes when currentIndex<0 (slot = size); otherwise splices
+      // at currentIndex+1. Using size-1 after addNext was wrong when the
+      // queue had stale currentIndex>=0 while the player was idle (e.g.,
+      // after natural track end without queue.clear()).
+      const insertedAt =
+        queue.getCurrentIndex() < 0 ? queue.size() : queue.getCurrentIndex() + 1;
+      queue.addNext(song);
+
+      if (wasIdle) {
+        // Promote the just-added song to current and start it.
+        queue.playAt(insertedAt);
+        bot.getPlayer().resetFailures();
+        const ok = await bot.resolveAndPlay(queue.current()!);
+        if (!ok) {
+          res.json({ ok: false, message: `无法播放「${song.name || song.id}」（区域/版权限制）` });
+          return;
+        }
+        res.json({ ok: true, message: `正在播放：${song.name || 'Unknown'} - ${song.artist || 'Unknown'}` });
+        return;
+      }
+
+      res.json({ ok: true, message: `已加入下一首：${song.name || 'Unknown'} - ${song.artist || 'Unknown'}` });
+    } catch (err) {
+      res.status(500).json({ error: (err as Error).message });
+    }
+  });
+
+  router.post("/:botId/add-song", async (req, res) => {
+    try {
+      const bot = (req as any).bot;
+      const { song } = req.body;
+      if (!song || !song.id || !song.platform) {
+        res.status(400).json({ error: "song object with id and platform is required" });
+        return;
+      }
+      const queue = bot.getQueueManager();
+      const wasIdle = bot.getPlayer().getState() === "idle";
+      queue.add(song);
+
+      // If nothing was playing, start this newly-added song immediately.
+      if (wasIdle) {
+        queue.playAt(queue.size() - 1);
+        bot.getPlayer().resetFailures();
+        await bot.resolveAndPlay(queue.current()!);
+        res.json({ message: `Now playing: ${song.name || 'Unknown'} - ${song.artist || 'Unknown'}` });
+        return;
+      }
+
+      res.json({ message: `Added to queue: ${song.name || 'Unknown'} - ${song.artist || 'Unknown'} (position ${queue.size()})` });
    } catch (err) {
      res.status(500).json({ error: (err as Error).message });
    }
@@ -273,11 +412,11 @@ export function createPlayerRouter(
    try {
      const bot = (req as any).bot;
      const { songId, platform } = req.body;
-      const provider = platform === "bilibili" ? bilibiliProvider : platform === "qq" ? qqProvider : neteaseProvider;
-      if (!provider) {
-        res.status(500).json({ error: "Provider not available" });
-        return;
-      }
+      const provider = bot.getProviderFor(
+        platform === "bilibili" || platform === "qq" || platform === "youtube"
+          ? platform
+          : "netease"
+      );

      const song = await provider.getSongDetail(songId);
      if (!song) {
@@ -300,6 +439,27 @@ export function createPlayerRouter(
    }
  });

+  // --- Profile config endpoints ---
+
+  router.get("/:botId/profile", (req, res) => {
+    const bot = (req as any).bot;
+    res.json(bot.getProfileManager().getConfig());
+  });
+
+  router.put("/:botId/profile", (req, res) => {
+    try {
+      const bot = (req as any).bot;
+      const pm = bot.getProfileManager();
+      pm.updateConfig(req.body);
+      if (database) {
+        database.saveProfileConfig(bot.id, pm.getConfig());
+      }
+      res.json(pm.getConfig());
+    } catch (err) {
+      res.status(500).json({ error: (err as Error).message });
+    }
+  });
+
  router.get("/:botId/history", (req, res) => {
    if (!database) {
      res.json({ history: [] });
@@ -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",
@@ -67,7 +78,14 @@ export function createWebServer(options: WebServerOptions): WebServer {
    });
  }

+  server.on("error", (err) => {
+    logger.error({ err }, "HTTP server error");
+  });
+
  const wss = new WebSocketServer({ server, path: "/ws" });
+  wss.on("error", (err) => {
+    logger.error({ err }, "WebSocket server error");
+  });
  const cleanupWs = setupWebSocket(wss, options.botManager, logger);

  return {
@@ -10,8 +10,9 @@ export function setupWebSocket(
 ): () => void {
  const clients = new Set<WebSocket>();

-  /** Track which bots already have listeners attached */
+  /** Track which bot instances have listeners attached (keyed by id, storing ref) */
  const attachedBots = new Map<string, {
+    bot: BotInstance;
    stateChange: () => void;
    connected: () => void;
    disconnected: () => void;
@@ -39,13 +40,31 @@ export function setupWebSocket(
    const message = JSON.stringify(data);
    for (const client of clients) {
      if (client.readyState === WebSocket.OPEN) {
-        client.send(message);
+        try {
+          client.send(message);
+        } catch {
+          clients.delete(client);
+        }
      }
    }
  };

+  function detachBotListener(id: string): void {
+    const existing = attachedBots.get(id);
+    if (!existing) return;
+    existing.bot.removeListener("stateChange", existing.stateChange);
+    existing.bot.removeListener("connected", existing.connected);
+    existing.bot.removeListener("disconnected", existing.disconnected);
+    attachedBots.delete(id);
+  }
+
  function attachBotListener(bot: BotInstance): void {
-    if (attachedBots.has(bot.id)) return;
+    const existing = attachedBots.get(bot.id);
+    if (existing) {
+      if (existing.bot === bot) return; // already attached to this instance
+      // Bot instance was replaced (e.g. startBot re-created it) — re-attach
+      detachBotListener(bot.id);
+    }

    const onStateChange = () => {
      broadcast({
@@ -77,6 +96,7 @@ export function setupWebSocket(
    bot.on("disconnected", onDisconnected);

    attachedBots.set(bot.id, {
+      bot,
      stateChange: onStateChange,
      connected: onConnected,
      disconnected: onDisconnected,
@@ -90,21 +110,39 @@ export function setupWebSocket(
    }
  }

-  // Check for newly added bots periodically
-  const intervalId = setInterval(ensureAllBotsAttached, 5000);
+  // React immediately when a bot instance is created or replaced
+  const onBotInstance = (bot: BotInstance) => attachBotListener(bot);
+  botManager.on("botInstance", onBotInstance);
+
+  // React when a bot is removed: detach its listener and tell clients to drop it
+  const onBotInstanceRemoved = (id: string) => {
+    detachBotListener(id);
+    broadcast({ type: "botRemoved", botId: id });
+  };
+  botManager.on("botInstanceRemoved", onBotInstanceRemoved);
+
+  /** Drop attached listeners whose bot is no longer in the manager. */
+  function reconcileAttachedBots(): void {
+    const liveIds = new Set(botManager.getAllBots().map((b) => b.id));
+    for (const id of Array.from(attachedBots.keys())) {
+      if (!liveIds.has(id)) detachBotListener(id);
+    }
+  }
+
+  // Safety net: periodically re-check in case any bot was missed
+  const intervalId = setInterval(() => {
+    reconcileAttachedBots();
+    ensureAllBotsAttached();
+  }, 5000);
  ensureAllBotsAttached();

  return () => {
    clearInterval(intervalId);
-    // Clean up named listeners
-    for (const bot of botManager.getAllBots()) {
-      const listeners = attachedBots.get(bot.id);
-      if (listeners) {
-        bot.removeListener("stateChange", listeners.stateChange);
-        bot.removeListener("connected", listeners.connected);
-        bot.removeListener("disconnected", listeners.disconnected);
-      }
+    botManager.removeListener("botInstance", onBotInstance);
+    botManager.removeListener("botInstanceRemoved", onBotInstanceRemoved);
+    // Clean up all attached listeners (detach from stored bot refs, not live map)
+    for (const id of Array.from(attachedBots.keys())) {
+      detachBotListener(id);
    }
-    attachedBots.clear();
  };
 }
@@ -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": [
@@ -5,32 +5,89 @@
      <RouterView />
    </main>
    <Player />
+    <Toast />
+
+    <!-- Mobile mini player -->
+    <div v-if="currentSong" class="m-player" @click="router.push('/lyrics')">
+      <div class="m-player-progress">
+        <div class="m-player-progress-fill" :style="{ width: mobileProgressPct + '%' }" />
+      </div>
+      <CoverArt :url="currentSong.coverUrl" :size="40" :radius="8" />
+      <div class="m-player-info">
+        <div class="m-player-name">{{ currentSong.name }}</div>
+        <div class="m-player-artist">{{ currentSong.artist }}</div>
+      </div>
+      <button class="m-player-btn" @click.stop="playerStore.isPlaying ? playerStore.pause() : playerStore.resume()">
+        <Icon :icon="playerStore.isPlaying ? 'mdi:pause' : 'mdi:play'" />
+      </button>
+      <button class="m-player-btn" @click.stop="playerStore.next()">
+        <Icon icon="mdi:skip-next" />
+      </button>
+    </div>
+
+    <!-- Mobile bottom tab bar -->
+    <nav class="m-tabbar">
+      <RouterLink to="/" class="m-tab" :class="{ active: route.path === '/' }">
+        <Icon icon="mdi:home" class="tab-icon" />
+        <span class="tab-label">发现</span>
+      </RouterLink>
+      <RouterLink to="/search" class="m-tab" :class="{ active: route.path === '/search' }">
+        <Icon icon="mdi:magnify" class="tab-icon" />
+        <span class="tab-label">搜索</span>
+      </RouterLink>
+      <RouterLink to="/library" class="m-tab" :class="{ active: route.path === '/library' }">
+        <Icon icon="mdi:music-box-multiple" class="tab-icon" />
+        <span class="tab-label">音乐库</span>
+      </RouterLink>
+      <RouterLink to="/settings" class="m-tab" :class="{ active: route.path.startsWith('/settings') }">
+        <Icon icon="mdi:cog" class="tab-icon" />
+        <span class="tab-label">设置</span>
+      </RouterLink>
+    </nav>
  </div>
 </template>

 <script setup lang="ts">
-import { computed, onMounted, onUnmounted } from 'vue';
+import { computed, onMounted, onUnmounted, ref } from 'vue';
+import { useRoute, useRouter } from 'vue-router';
+import { Icon } from '@iconify/vue';
 import { usePlayerStore } from './stores/player.js';
 import { useWebSocket } from './composables/useWebSocket.js';
 import Navbar from './components/Navbar.vue';
 import Player from './components/Player.vue';
+import CoverArt from './components/CoverArt.vue';
+import Toast from './components/Toast.vue';

 const playerStore = usePlayerStore();
 const theme = computed(() => playerStore.theme);
+const route = useRoute();
+const router = useRouter();
 const { connect } = useWebSocket();
+const currentSong = computed(() => playerStore.currentSong);

+const mobileProgressPct = ref(0);
 let syncTimer: ReturnType<typeof setInterval> | null = null;
+let mobileRaf: number | null = null;
+
+function updateMobileProgress() {
+  const duration = currentSong.value?.duration ?? 0;
+  mobileProgressPct.value = duration > 0
+    ? Math.min((playerStore.elapsed / duration) * 100, 100)
+    : 0;
+  mobileRaf = requestAnimationFrame(updateMobileProgress);
+}

 onMounted(() => {
  playerStore.loadTheme();
  connect();
  playerStore.fetchBots();
-  // Periodically sync elapsed time from server (ground truth)
  syncTimer = setInterval(() => playerStore.syncElapsed(), 3000);
+  mobileRaf = requestAnimationFrame(updateMobileProgress);
 });

 onUnmounted(() => {
  if (syncTimer) clearInterval(syncTimer);
+  if (mobileRaf !== null) cancelAnimationFrame(mobileRaf);
 });
 </script>

@@ -47,5 +104,123 @@ onUnmounted(() => {
  @media (max-width: 1336px) {
    padding: 80px 5vw 80px;
  }
+
+  @media (max-width: 768px) {
+    padding: 72px 16px 200px;
+  }
+}
+
+// Mobile mini player
+.m-player {
+  position: fixed;
+  left: 8px;
+  right: 8px;
+  bottom: 68px;
+  height: 58px;
+  padding: 8px 10px;
+  display: flex;
+  align-items: center;
+  gap: 10px;
+  background: var(--bg-secondary);
+  border-radius: var(--radius-md);
+  box-shadow: 0 6px 20px rgba(0, 0, 0, 0.35);
+  z-index: 95;
+  cursor: pointer;
+
+  @media (min-width: 769px) {
+    display: none;
+  }
+}
+
+.m-player-progress {
+  position: absolute;
+  top: 0;
+  left: 10px;
+  right: 10px;
+  height: 2px;
+}
+
+.m-player-progress-fill {
+  height: 2px;
+  background: var(--color-primary);
+  border-radius: 1px;
+}
+
+.m-player-info {
+  flex: 1;
+  min-width: 0;
+}
+
+.m-player-name {
+  font-size: 13px;
+  font-weight: 500;
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+
+.m-player-artist {
+  font-size: 11px;
+  color: var(--text-secondary);
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+
+.m-player-btn {
+  width: 32px;
+  height: 32px;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  font-size: 22px;
+  opacity: 0.85;
+  flex-shrink: 0;
+}
+
+// Mobile bottom tab bar
+.m-tabbar {
+  position: fixed;
+  left: 0;
+  right: 0;
+  bottom: 0;
+  height: 60px;
+  display: flex;
+  align-items: center;
+  justify-content: space-around;
+  padding-bottom: env(safe-area-inset-bottom, 0);
+  background: var(--bg-navbar);
+  backdrop-filter: saturate(180%) blur(20px);
+  -webkit-backdrop-filter: saturate(180%) blur(20px);
+  border-top: 1px solid var(--border-color);
+  z-index: 100;
+
+  @media (min-width: 769px) {
+    display: none;
+  }
+}
+
+.m-tab {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: 2px;
+  padding: 6px 14px;
+  color: var(--text-tertiary);
+  text-decoration: none;
+  font-family: inherit;
+
+  &.active {
+    color: var(--color-primary);
+  }
+
+  .tab-icon {
+    font-size: 22px;
+  }
+
+  .tab-label {
+    font-size: 10px;
+    font-weight: 500;
+  }
 }
 </style>
@@ -5,49 +5,115 @@
    <div class="nav-links">
      <RouterLink to="/" class="nav-link" active-class="active">发现</RouterLink>
      <RouterLink to="/search" class="nav-link" active-class="active">搜索</RouterLink>
+      <RouterLink to="/library" class="nav-link" active-class="active">音乐库</RouterLink>
      <RouterLink to="/history" class="nav-link" active-class="active">播放历史</RouterLink>
    </div>

    <div class="nav-right">
-      <!-- Multi-bot selector -->
-      <div v-if="store.bots.length > 1" class="bot-selector" ref="selectorRef">
+      <!-- Bot selector (always shown when at least one bot exists) -->
+      <div v-if="store.bots.length > 0" class="bot-selector" ref="selectorRef">
        <button class="bot-selector-btn" @click="dropdownOpen = !dropdownOpen">
          <span class="bot-dot" :class="{ online: activeBot?.connected }" />
          <span class="bot-selector-name">{{ activeBot?.name ?? '选择机器人' }}</span>
+          <span v-if="activeBot?.playing && !activeBot?.paused" class="bot-state-mini playing">▶</span>
+          <span v-else-if="activeBot?.paused" class="bot-state-mini paused">⏸</span>
          <Icon icon="mdi:chevron-down" class="bot-chevron" :class="{ rotated: dropdownOpen }" />
        </button>
        <div v-if="dropdownOpen" class="bot-dropdown">
-          <button
+          <div class="bot-dropdown-header">机器人</div>
+          <div
            v-for="bot in store.bots"
            :key="bot.id"
-            class="bot-dropdown-item"
+            class="bot-card"
            :class="{ active: bot.id === store.activeBotId }"
-            @click="selectBot(bot.id)"
          >
-            <span class="bot-dot" :class="{ online: bot.connected }" />
-            <span class="bot-dropdown-name">{{ bot.name }}</span>
-            <span v-if="bot.playing && !bot.paused" class="bot-playing-badge">播放中</span>
-            <span v-else-if="bot.paused" class="bot-paused-badge">已暂停</span>
-            <span v-else-if="bot.connected" class="bot-idle-badge">空闲</span>
-            <span v-else class="bot-offline-badge">离线</span>
-          </button>
+            <div class="bot-card-head" @click="bot.connected ? selectBot(bot.id) : undefined">
+              <span class="bot-dot" :class="{ online: bot.connected }" />
+              <span class="bot-card-name">{{ bot.name }}</span>
+              <span v-if="bot.id === store.activeBotId" class="bot-current-badge">当前</span>
+              <span v-if="bot.playing && !bot.paused" class="bot-playing-badge">播放中</span>
+              <span v-else-if="bot.paused" class="bot-paused-badge">已暂停</span>
+              <span v-else-if="bot.connected" class="bot-idle-badge">空闲</span>
+              <span v-else class="bot-offline-badge">离线</span>
+            </div>
+            <div class="bot-card-controls">
+              <button
+                v-if="bot.connected"
+                class="bot-ctrl-btn danger"
+                :disabled="togglingBots[bot.id]"
+                @click.stop="togglePower(bot)"
+              >
+                <Icon icon="mdi:link-off" /> 断开
+              </button>
+              <button
+                v-else
+                class="bot-ctrl-btn primary"
+                :disabled="togglingBots[bot.id]"
+                @click.stop="togglePower(bot)"
+              >
+                <Icon icon="mdi:link-variant" /> 连接
+              </button>
+              <button
+                v-if="bot.playing || bot.paused"
+                class="bot-ctrl-btn"
+                :disabled="!bot.connected"
+                @click.stop="store.pause()"
+              >
+                <Icon icon="mdi:stop" /> 停止
+              </button>
+              <button
+                v-else
+                class="bot-ctrl-btn"
+                :disabled="!bot.connected"
+                @click.stop="store.resume()"
+              >
+                <Icon icon="mdi:play" /> 播放
+              </button>
+              <button
+                class="bot-ctrl-btn"
+                :disabled="!bot.connected || (!bot.playing && !bot.paused)"
+                @click.stop="store.next()"
+                title="下一首"
+              >
+                <Icon icon="mdi:skip-next" />
+              </button>
+              <button class="bot-ctrl-btn" @click.stop="copyBotLink(bot.id)" title="复制链接">
+                <Icon icon="mdi:link-variant" />
+              </button>
+            </div>
+          </div>
        </div>
      </div>

-      <!-- Single bot status (original behavior) -->
-      <div v-else-if="activeBot" class="bot-status" :class="{ online: activeBot.connected }">
-        {{ activeBot.name }} {{ activeBot.connected ? '在线' : '离线' }}
-      </div>
-
      <RouterLink to="/settings" class="settings-btn">
        <Icon icon="mdi:cog" />
      </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';

@@ -55,12 +121,111 @@ const store = usePlayerStore();
 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 resolveBaseUrl(): string {
+  const base = publicBaseUrl.value;
+  if (base && /^https?:\/\//i.test(base)) return base.replace(/\/+$/, '');
+  return window.location.origin;
+}
+
+async function tryClipboardWrite(text: string): Promise<boolean> {
+  try {
+    if (navigator.clipboard && window.isSecureContext) {
+      await navigator.clipboard.writeText(text);
+      return true;
+    }
+  } catch {
+    // fall through
+  }
+  try {
+    const ta = document.createElement('textarea');
+    ta.value = text;
+    ta.style.position = 'fixed';
+    ta.style.opacity = '0';
+    ta.style.pointerEvents = 'none';
+    document.body.appendChild(ta);
+    ta.focus();
+    ta.select();
+    const ok = document.execCommand('copy');
+    document.body.removeChild(ta);
+    return ok;
+  } catch {
+    return false;
+  }
+}
+
+async function copyBotLink(id: string) {
+  const bot = store.bots.find((b) => b.id === id);
+  const url = `${resolveBaseUrl()}/bot/${id}`;
+  linkDialog.url = url;
+  linkDialog.name = bot?.name ?? '机器人';
+  linkDialog.copied = false;
+  linkDialog.open = true;
+  dropdownOpen.value = false;
+  // Try to copy silently; user can still manually select if it fails.
+  const ok = await tryClipboardWrite(url);
+  if (ok) linkDialog.copied = true;
+  await nextTick();
+  linkInputRef.value?.focus();
+  linkInputRef.value?.select();
+}
+
+async function copyLinkFromDialog() {
+  const ok = await tryClipboardWrite(linkDialog.url);
+  if (ok) {
+    linkDialog.copied = true;
+  } else {
+    linkInputRef.value?.focus();
+    linkInputRef.value?.select();
+  }
+}
+
+function closeLinkDialog() {
+  linkDialog.open = false;
+}
+
+async function loadPublicBaseUrl() {
+  try {
+    const res = await fetch('/api/config/public-url');
+    if (!res.ok) return;
+    const data = (await res.json()) as { publicUrl?: string | null };
+    if (data.publicUrl) publicBaseUrl.value = data.publicUrl;
+  } catch {
+    // ignore — fall back to window.location.origin
+  }
+}
+
+async function togglePower(bot: { id: string; connected: boolean; name: string }) {
+  if (togglingBots.value[bot.id]) return;
+  togglingBots.value[bot.id] = true;
+  try {
+    if (bot.connected) {
+      await store.stopBotInstance(bot.id);
+    } else {
+      await store.startBotInstance(bot.id);
+    }
+  } catch (err) {
+    console.error(`Failed to toggle bot ${bot.name}`, err);
+  } finally {
+    togglingBots.value[bot.id] = false;
+  }
+}
+
 function onClickOutside(e: MouseEvent) {
  if (selectorRef.value && !selectorRef.value.contains(e.target as Node)) {
    dropdownOpen.value = false;
@@ -69,6 +234,7 @@ function onClickOutside(e: MouseEvent) {

 onMounted(() => {
  document.addEventListener('click', onClickOutside);
+  loadPublicBaseUrl();
 });

 onUnmounted(() => {
@@ -92,6 +258,11 @@ onUnmounted(() => {
  @media (max-width: 1336px) {
    padding: 0 5vw;
  }
+
+  @media (max-width: 768px) {
+    padding: 0 16px;
+    height: 52px;
+  }
 }

 .logo {
@@ -99,11 +270,20 @@ onUnmounted(() => {
  font-weight: 700;
  color: var(--color-primary);
  margin-right: 40px;
+
+  @media (max-width: 768px) {
+    font-size: 17px;
+    margin-right: 0;
+  }
 }

 .nav-links {
  display: flex;
  gap: 24px;
+
+  @media (max-width: 768px) {
+    display: none;
+  }
 }

 .nav-link {
@@ -131,7 +311,7 @@ onUnmounted(() => {
  opacity: 0.6;

  &.online {
-    background: rgba(51, 94, 234, 0.15);
+    background: var(--color-primary-15);
    color: var(--color-primary);
    opacity: 1;
  }
@@ -145,115 +325,181 @@ onUnmounted(() => {
 .bot-selector-btn {
  display: flex;
  align-items: center;
-  gap: 8px;
-  padding: 6px 14px;
+  gap: 10px;
+  padding: 10px 20px;
  background: var(--hover-bg);
-  border-radius: var(--radius-sm);
-  font-size: 13px;
-  font-weight: 500;
-  transition: background var(--transition-fast);
+  border-radius: var(--radius-md);
+  font-size: 16px;
+  font-weight: 600;
+  min-height: 44px;
+  border: 1px solid var(--border-color);
+  transition: background var(--transition-fast), border-color var(--transition-fast);
  cursor: pointer;

  &:hover {
    background: var(--bg-card);
+    border-color: var(--color-primary);
+  }
+
+  @media (max-width: 768px) {
+    padding: 6px 10px;
+    font-size: 12px;
+    font-weight: 600;
+    min-height: 32px;
+    gap: 6px;
+    border-radius: var(--radius-full);
+  }
+}
+
+.bot-state-mini {
+  font-size: 14px;
+  &.playing { color: var(--color-online); }
+  &.paused { color: var(--color-paused); }
+
+  @media (max-width: 768px) {
+    display: none;
  }
 }

 .bot-chevron {
-  font-size: 16px;
+  font-size: 20px;
  opacity: 0.5;
  transition: transform 0.2s ease;

  &.rotated {
    transform: rotate(180deg);
  }
+
+  @media (max-width: 768px) {
+    display: none;
+  }
 }

 .bot-dot {
-  width: 8px;
-  height: 8px;
+  width: 10px;
+  height: 10px;
  border-radius: 50%;
  background: var(--text-tertiary);
  flex-shrink: 0;

  &.online {
-    background: #22c55e;
+    background: var(--color-online);
+  }
+
+  @media (max-width: 768px) {
+    width: 8px;
+    height: 8px;
  }
 }

 .bot-selector-name {
-  max-width: 120px;
+  max-width: 160px;
  overflow: hidden;
  text-overflow: ellipsis;
  white-space: nowrap;
+
+  @media (max-width: 768px) {
+    max-width: 80px;
+  }
 }

 .bot-dropdown {
  position: absolute;
  top: calc(100% + 6px);
  right: 0;
-  min-width: 200px;
+  min-width: 320px;
  background: var(--bg-secondary);
  border: 1px solid var(--border-color);
  border-radius: var(--radius-md);
-  padding: 4px;
-  box-shadow: 0 8px 24px rgba(0, 0, 0, 0.2);
+  padding: 6px;
+  box-shadow: var(--shadow-dropdown);
  z-index: 200;
+
+  @media (max-width: 768px) {
+    position: fixed;
+    top: 52px;
+    left: 8px;
+    right: 8px;
+    min-width: auto;
+  }
 }

-.bot-dropdown-item {
+.bot-dropdown-header {
+  font-size: 11px;
+  font-weight: 600;
+  color: var(--text-tertiary);
+  padding: 6px 10px 4px;
+  text-transform: uppercase;
+  letter-spacing: 0.5px;
+}
+
+.bot-card {
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
+  padding: 10px;
+  border-radius: var(--radius-sm);
+  margin-bottom: 4px;
+  border: 1px solid transparent;
+  transition: background var(--transition-fast);
+
+  &.active {
+    background: var(--color-primary-12);
+    border-color: rgba(99, 102, 241, 0.25);
+  }
+}
+
+.bot-card-head {
  display: flex;
  align-items: center;
  gap: 8px;
-  width: 100%;
-  padding: 8px 12px;
-  border-radius: var(--radius-sm);
-  font-size: 13px;
  cursor: pointer;
-  transition: background var(--transition-fast);
-
-  &:hover {
-    background: var(--hover-bg);
-  }
-
-  &.active {
-    background: rgba(51, 94, 234, 0.12);
-    color: var(--color-primary);
-  }
 }

-.bot-dropdown-name {
+.bot-card-name {
  flex: 1;
+  font-size: 13px;
+  font-weight: 600;
  min-width: 0;
  overflow: hidden;
  text-overflow: ellipsis;
  white-space: nowrap;
 }

+.bot-current-badge {
+  font-size: 10px;
+  font-weight: 700;
+  color: var(--color-primary);
+  padding: 2px 6px;
+  border-radius: 4px;
+  background: var(--color-primary-15);
+  flex-shrink: 0;
+}
+
 .bot-playing-badge,
 .bot-paused-badge,
 .bot-idle-badge,
 .bot-offline-badge {
  font-size: 11px;
-  padding: 1px 6px;
+  padding: 2px 6px;
  border-radius: 4px;
  font-weight: 500;
  flex-shrink: 0;
 }

 .bot-playing-badge {
-  background: rgba(34, 197, 94, 0.15);
-  color: #22c55e;
+  background: var(--color-online-15);
+  color: var(--color-online);
 }

 .bot-paused-badge {
-  background: rgba(234, 179, 8, 0.15);
-  color: #eab308;
+  background: var(--color-paused-15);
+  color: var(--color-paused);
 }

 .bot-idle-badge {
-  background: rgba(51, 94, 234, 0.12);
-  color: var(--color-primary);
+  background: var(--hover-bg);
+  color: var(--text-secondary);
 }

 .bot-offline-badge {
@@ -261,10 +507,140 @@ onUnmounted(() => {
  color: var(--text-tertiary);
 }

+.bot-card-controls {
+  display: flex;
+  gap: 6px;
+}
+
+.bot-ctrl-btn {
+  flex: 1;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  gap: 4px;
+  padding: 6px 8px;
+  border-radius: var(--radius-sm);
+  background: var(--hover-bg);
+  border: 1px solid var(--border-color);
+  color: var(--text-primary);
+  font-size: 11px;
+  font-weight: 500;
+  cursor: pointer;
+  white-space: nowrap;
+  transition: all var(--transition-fast);
+
+  &:hover:not(:disabled) {
+    background: var(--bg-card);
+    border-color: var(--color-primary);
+  }
+
+  &:disabled {
+    opacity: 0.4;
+    cursor: not-allowed;
+  }
+
+  &.primary {
+    background: var(--color-primary);
+    color: #fff;
+    border-color: var(--color-primary);
+  }
+
+  &.danger {
+    color: #ef4444;
+  }
+}
+
 .settings-btn {
-  font-size: 20px;
+  font-size: 22px;
  opacity: 0.6;
  transition: opacity var(--transition-fast);
  &:hover { opacity: 1; }
+
+  @media (max-width: 768px) {
+    display: none;
+  }
+}
+
+.link-dialog-backdrop {
+  position: fixed;
+  inset: 0;
+  background: var(--bg-modal-scrim);
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  z-index: 1000;
+}
+
+.link-dialog {
+  background: var(--bg-secondary);
+  border: 1px solid var(--border-color);
+  border-radius: var(--radius-md);
+  padding: 20px;
+  min-width: 360px;
+  max-width: 90vw;
+  box-shadow: var(--shadow-modal);
+}
+
+.link-dialog-title {
+  font-size: 15px;
+  font-weight: 600;
+  margin-bottom: 6px;
+}
+
+.link-dialog-hint {
+  font-size: 12px;
+  color: var(--text-tertiary);
+  margin-bottom: 12px;
+}
+
+.link-dialog-input {
+  width: 100%;
+  padding: 10px 12px;
+  font-size: 13px;
+  font-family: ui-monospace, SFMono-Regular, Menlo, monospace;
+  background: var(--hover-bg);
+  border: 1px solid var(--border-color);
+  border-radius: var(--radius-sm);
+  color: inherit;
+  user-select: all;
+  -webkit-user-select: all;
+
+  &:focus {
+    outline: none;
+    border-color: var(--color-primary);
+  }
+}
+
+.link-dialog-actions {
+  display: flex;
+  justify-content: flex-end;
+  gap: 8px;
+  margin-top: 14px;
+}
+
+.link-dialog-btn {
+  padding: 8px 16px;
+  font-size: 13px;
+  font-weight: 500;
+  border-radius: var(--radius-sm);
+  border: 1px solid var(--border-color);
+  background: var(--hover-bg);
+  color: inherit;
+  cursor: pointer;
+  transition: background var(--transition-fast), border-color var(--transition-fast);
+
+  &:hover {
+    background: var(--bg-card);
+  }
+
+  &.primary {
+    background: var(--color-primary);
+    border-color: var(--color-primary);
+    color: #fff;
+
+    &:hover {
+      filter: brightness(1.08);
+    }
+  }
 }
 </style>
@@ -206,6 +206,10 @@ function cycleMode() {
  left: 0;
  right: 0;
  z-index: 100;
+
+  @media (max-width: 768px) {
+    display: none;
+  }
 }

 .player-bar {
@@ -326,12 +330,12 @@ function cycleMode() {

 .bot-badge {
  display: inline-block;
-  font-size: 10px;
-  font-weight: 600;
+  font-size: var(--fs-micro);
+  font-weight: var(--fw-semi);
  padding: 0 5px;
-  background: rgba(51, 94, 234, 0.15);
+  background: var(--color-primary-15);
  color: var(--color-primary);
-  border-radius: 3px;
+  border-radius: var(--radius-xs);
  line-height: 16px;
  white-space: nowrap;
  flex-shrink: 0;
@@ -3,6 +3,14 @@
    <div class="queue-header">
      <h3 class="queue-title">播放队列</h3>
      <span class="queue-count">{{ botQueue.length }} 首</span>
+      <button 
+        v-if="botQueue.length > 0"
+        class="clear-btn" 
+        @click="clearAndStop" 
+        title="清空队列并停止播放"
+      >
+        <Icon icon="mdi:stop-circle-outline" />
+      </button>
      <button class="close-btn" @click="$emit('close')">
        <Icon icon="mdi:close" />
      </button>
@@ -70,6 +78,15 @@ async function removeSong(index: number) {
    // Ignore
  }
 }
+
+async function clearAndStop() {
+  try {
+    await store.stop();
+    await store.fetchQueue();
+  } catch {
+    // Ignore
+  }
+}
 </script>

 <style lang="scss" scoped>
@@ -117,6 +134,14 @@ async function removeSong(index: number) {
  &:hover { opacity: 1; }
 }

+.clear-btn {
+  font-size: 18px;
+  opacity: 0.6;
+  transition: opacity var(--transition-fast);
+  color: var(--text-primary);
+  &:hover { opacity: 1; }
+}
+
 .queue-empty {
  padding: 40px 20px;
  text-align: center;
@@ -146,7 +171,7 @@ async function removeSong(index: number) {
  }

  &.active {
-    background: rgba(51, 94, 234, 0.1);
+    background: var(--color-primary-10);
  }
 }

@@ -7,8 +7,8 @@
        <span class="song-name">{{ song.name }}</span>
        <span
          class="platform-badge"
-          :class="song.platform === 'bilibili' ? 'badge-bilibili' : song.platform === 'qq' ? 'badge-qq' : 'badge-netease'"
-        >{{ song.platform === 'bilibili' ? 'B站' : song.platform === 'qq' ? 'QQ' : '网易云' }}</span>
+          :class="song.platform === 'bilibili' ? 'badge-bilibili' : song.platform === 'qq' ? 'badge-qq' : song.platform === 'youtube' ? 'badge-youtube' : 'badge-netease'"
+        >{{ song.platform === 'bilibili' ? 'B站' : song.platform === 'qq' ? 'QQ' : song.platform === 'youtube' ? 'YouTube' : '网易云' }}</span>
      </div>
      <div class="song-artist">{{ song.artist }}</div>
    </div>
@@ -18,6 +18,9 @@
      <button class="action-btn" @click.stop="$emit('play')" title="播放">
        <Icon icon="mdi:play" />
      </button>
+      <button class="action-btn" @click.stop="$emit('playNext')" title="下一首播放">
+        <Icon icon="mdi:playlist-play" />
+      </button>
      <button class="action-btn" @click.stop="$emit('add')" title="添加到队列">
        <Icon icon="mdi:playlist-plus" />
      </button>
@@ -28,15 +31,17 @@
 <script setup lang="ts">
 import { Icon } from '@iconify/vue';
 import CoverArt from './CoverArt.vue';
+import { Song } from '../stores/player.js';

 defineProps<{
-  song: { id: string; name: string; artist: string; album: string; duration: number; coverUrl: string; platform: string };
+  song: Song;
  index: number;
  active?: boolean;
 }>();

 defineEmits<{
  play: [];
+  playNext: [];
  add: [];
 }>();

@@ -63,7 +68,7 @@ function formatDuration(seconds: number): string {
  }

  &.active {
-    background: rgba(51, 94, 234, 0.1);
+    background: var(--color-primary-10);
  }
 }

@@ -96,26 +101,31 @@ function formatDuration(seconds: number): string {

 .platform-badge {
  flex-shrink: 0;
-  font-size: 10px;
-  font-weight: 600;
+  font-size: var(--fs-micro);
+  font-weight: var(--fw-semi);
  padding: 1px 5px;
-  border-radius: 3px;
+  border-radius: var(--radius-xs);
  line-height: 1.4;
 }

 .badge-netease {
-  background: rgba(232, 17, 35, 0.15);
-  color: #e81123;
+  background: var(--brand-netease-15);
+  color: var(--brand-netease);
 }

 .badge-qq {
-  background: rgba(18, 183, 106, 0.15);
-  color: #12b76a;
+  background: var(--brand-qq-15);
+  color: var(--brand-qq);
 }

 .badge-bilibili {
-  background: rgba(0, 161, 214, 0.15);
-  color: #00a1d6;
+  background: var(--brand-bilibili-15);
+  color: var(--brand-bilibili);
+}
+
+.badge-youtube {
+  background: var(--brand-youtube-12);
+  color: var(--brand-youtube);
 }

 .song-artist {
@@ -146,6 +156,15 @@ function formatDuration(seconds: number): string {
  transition: opacity var(--transition-fast);
 }

+// Touch devices have no :hover, so the parent-hover-reveals-actions
+// pattern leaves all action buttons invisible. Always show on coarse-
+// pointer (touch) inputs — this is also where bigger tap targets matter.
+@media (pointer: coarse) {
+  .song-actions {
+    opacity: 1;
+  }
+}
+
 .action-btn {
  font-size: 18px;
  padding: 4px;
@@ -0,0 +1,94 @@
+<template>
+  <div v-if="sources.length > 0" class="source-tabs">
+    <template v-if="sources.length >= 2">
+      <button
+        v-for="src in sources"
+        :key="src"
+        type="button"
+        class="source-tab"
+        :class="{ active: src === modelValue }"
+        @click="$emit('update:modelValue', src)"
+      >
+        {{ LABELS[src] }}
+      </button>
+    </template>
+    <span v-else class="source-tab-label" :title="`数据来自${LABELS[sources[0]]}`">
+      {{ LABELS[sources[0]] }}
+    </span>
+  </div>
+</template>
+
+<script setup lang="ts">
+import type { Source } from '../stores/player.js';
+
+const LABELS: Record<Source, string> = {
+  netease: '网易云',
+  qq: 'QQ',
+};
+
+defineProps<{
+  modelValue: Source;
+  sources: Source[];
+}>();
+
+defineEmits<{
+  'update:modelValue': [value: Source];
+}>();
+</script>
+
+<style lang="scss" scoped>
+.source-tabs {
+  display: inline-flex;
+  gap: 4px;
+  margin-left: 12px;
+  align-items: center;
+}
+
+.source-tab {
+  padding: 4px 10px;
+  min-height: 28px;
+  font-size: var(--fs-sm);
+  font-weight: var(--fw-medium);
+  color: var(--text-secondary);
+  background: transparent;
+  border: none;
+  border-radius: var(--radius-sm);
+  cursor: pointer;
+  transition: color var(--transition-fast), background var(--transition-fast);
+
+  &:hover {
+    color: var(--text-primary);
+    background: var(--hover-bg);
+  }
+
+  &.active {
+    color: var(--color-primary);
+    background: var(--color-primary-12);
+    font-weight: var(--fw-semi);
+  }
+}
+
+// Single-source mode: not interactive, but tells the user which platform
+// they're looking at instead of leaving them guessing.
+.source-tab-label {
+  padding: 4px 10px;
+  font-size: var(--fs-xs);
+  font-weight: var(--fw-medium);
+  color: var(--text-tertiary);
+  background: var(--hover-bg);
+  border-radius: var(--radius-sm);
+}
+
+@media (max-width: 768px) {
+  .source-tabs {
+    margin-left: 8px;
+    gap: 2px;
+  }
+
+  .source-tab {
+    padding: 6px 10px;
+    min-height: 36px; // larger touch target on mobile
+    font-size: var(--fs-xs);
+  }
+}
+</style>
@@ -0,0 +1,106 @@
+<template>
+  <Transition name="toast">
+    <div v-if="visible && current" class="toast" :class="`toast--${current.type}`">
+      <Icon :icon="current.type === 'error' ? 'mdi:alert-circle' : 'mdi:information'" class="toast-icon" />
+      <span class="toast-msg">{{ current.message }}</span>
+      <button class="toast-close" @click="visible = false" aria-label="关闭">
+        <Icon icon="mdi:close" />
+      </button>
+    </div>
+  </Transition>
+</template>
+
+<script setup lang="ts">
+import { ref, watch, onUnmounted } from 'vue';
+import { Icon } from '@iconify/vue';
+import { usePlayerStore } from '../stores/player.js';
+
+const store = usePlayerStore();
+const visible = ref(false);
+const current = ref<{ id: number; message: string; type: 'error' | 'info' } | null>(null);
+let timer: ReturnType<typeof setTimeout> | null = null;
+
+watch(
+  () => store.notification?.id,
+  () => {
+    if (!store.notification) return;
+    current.value = store.notification;
+    visible.value = true;
+    if (timer) clearTimeout(timer);
+    timer = setTimeout(() => {
+      visible.value = false;
+    }, current.value.type === 'error' ? 5000 : 3000);
+  }
+);
+
+onUnmounted(() => {
+  if (timer) clearTimeout(timer);
+});
+</script>
+
+<style lang="scss" scoped>
+.toast {
+  position: fixed;
+  left: 50%;
+  bottom: calc(var(--player-height) + 24px);
+  transform: translateX(-50%);
+  display: flex;
+  align-items: center;
+  gap: 10px;
+  padding: 10px 14px;
+  max-width: min(90vw, 480px);
+  background: var(--bg-card);
+  backdrop-filter: blur(20px);
+  border: 1px solid var(--border-color);
+  border-radius: var(--radius-md);
+  box-shadow: var(--shadow-dropdown);
+  font-size: var(--fs-body);
+  color: var(--text-primary);
+  z-index: 1000;
+
+  @media (max-width: 768px) {
+    bottom: calc(var(--player-height) + 60px);  // sit above mobile tabbar
+  }
+}
+
+.toast--error {
+  border-color: var(--brand-netease);
+  .toast-icon { color: var(--brand-netease); }
+}
+
+.toast--info {
+  border-color: var(--color-primary);
+  .toast-icon { color: var(--color-primary); }
+}
+
+.toast-icon {
+  font-size: 18px;
+  flex-shrink: 0;
+}
+
+.toast-msg {
+  flex: 1;
+  line-height: 1.4;
+}
+
+.toast-close {
+  flex-shrink: 0;
+  font-size: 18px;
+  color: var(--text-tertiary);
+  background: transparent;
+  border: none;
+  cursor: pointer;
+  &:hover { color: var(--text-primary); }
+}
+
+.toast-enter-active,
+.toast-leave-active {
+  transition: opacity var(--transition-fast), transform var(--transition-fast);
+}
+
+.toast-enter-from,
+.toast-leave-to {
+  opacity: 0;
+  transform: translateX(-50%) translateY(8px);
+}
+</style>
@@ -56,6 +56,13 @@ export function useWebSocket() {
            }
          }
          break;
+        case 'botRemoved':
+          // Bot was deleted from the server — drop from local state entirely
+          store.removeBotStatus(data.botId);
+          if (store.activeBotId === data.botId) {
+            store.activeBotId = store.bots[0]?.id ?? null;
+          }
+          break;
      }
    };

@@ -13,6 +13,11 @@ const router = createRouter({
      name: 'search',
      component: () => import('../views/Search.vue'),
    },
+    {
+      path: '/library',
+      name: 'library',
+      component: () => import('../views/Library.vue'),
+    },
    {
      path: '/playlist/:id',
      name: 'playlist',
@@ -38,6 +43,12 @@ const router = createRouter({
      name: 'setup',
      component: () => import('../views/Setup.vue'),
    },
+    {
+      // Per-bot URL: /bot/:id — sets active bot then redirects to home
+      path: '/bot/:id',
+      name: 'bot',
+      component: () => import('../views/BotRedirect.vue'),
+    },
  ],
 });

@@ -8,9 +8,11 @@ export interface Song {
  album: string;
  duration: number;
  coverUrl: string;
-  platform: 'netease' | 'qq';
+  platform: 'netease' | 'qq' | 'bilibili' | 'youtube';
 }

+export type Source = 'netease' | 'qq';
+
 export interface BotStatus {
  id: string;
  name: string;
@@ -54,12 +56,17 @@ export const usePlayerStore = defineStore('player', {
    timings: {} as Record<string, TimingState>,
    theme: 'dark' as 'dark' | 'light',

-    // Home page cache
-    recommendPlaylists: [] as PlaylistItem[],
-    dailySongs: [] as Song[],
-    userPlaylists: [] as PlaylistItem[],
+    // Home page cache, split by source
+    recommendPlaylists: { netease: [] as PlaylistItem[], qq: [] as PlaylistItem[] },
+    dailySongs:         { netease: [] as Song[],         qq: [] as Song[] },
+    userPlaylists:      { netease: [] as PlaylistItem[], qq: [] as PlaylistItem[] },
    bilibiliPopular: [] as Song[],
+    authStatus: { netease: false, qq: false },
    lastFetchTime: 0,
+
+    // Transient notification for surfacing failures (e.g., "song not playable")
+    // to a global Toast. Bumped `id` triggers re-render of the same message.
+    notification: null as { id: number; message: string; type: 'error' | 'info' } | null,
  }),

  getters: {
@@ -91,6 +98,13 @@ export const usePlayerStore = defineStore('player', {
      if (this.isPaused) return Math.min(timing.serverElapsed, maxDuration);
      return Math.min(timing.serverElapsed + (Date.now() - timing.serverSyncTime) / 1000, maxDuration);
    },
+    /** Sources that are currently logged in. Order: netease before qq. */
+    availableSources(): Source[] {
+      const s: Source[] = [];
+      if (this.authStatus.netease) s.push('netease');
+      if (this.authStatus.qq) s.push('qq');
+      return s;
+    },
  },

  actions: {
@@ -168,6 +182,14 @@ export const usePlayerStore = defineStore('player', {
      if (saved) this.theme = saved;
    },

+    async startBotInstance(id: string) {
+      await axios.post(`/api/bot/${id}/start`);
+    },
+
+    async stopBotInstance(id: string) {
+      await axios.post(`/api/bot/${id}/stop`);
+    },
+
    async fetchBots() {
      const res = await axios.get('/api/bot');
      this.bots = res.data.bots;
@@ -251,6 +273,30 @@ export const usePlayerStore = defineStore('player', {
      this._syncAfterAction();
    },

+    notify(message: string, type: 'error' | 'info' = 'info') {
+      this.notification = { id: Date.now(), message, type };
+    },
+
+    async playSong(song: Song) {
+      if (!this.activeBotId) return;
+      const res = await axios.post(`/api/player/${this.activeBotId}/play-song`, { song });
+      if (res.data?.ok === false && res.data?.message) {
+        this.notify(res.data.message, 'error');
+      }
+      this._setTiming(this.activeBotId, { serverElapsed: 0 });
+      this._syncAfterAction();
+    },
+
+    async playNextSong(song: Song) {
+      if (!this.activeBotId) return;
+      const res = await axios.post(`/api/player/${this.activeBotId}/play-next-song`, { song });
+      if (res.data?.message) {
+        this.notify(res.data.message, res.data.ok === false ? 'error' : 'info');
+      }
+      // Refresh queue so the inserted item shows up in the side panel
+      this.fetchQueue();
+    },
+
    async addToQueue(query: string, platform = 'netease') {
      if (!this.activeBotId) return;
      await axios.post(`/api/player/${this.activeBotId}/add`, { query, platform });
@@ -261,9 +307,17 @@ export const usePlayerStore = defineStore('player', {
      await axios.post(`/api/player/${this.activeBotId}/add-by-id`, { songId, platform });
    },

+    async addSong(song: Song) {
+      if (!this.activeBotId) return;
+      await axios.post(`/api/player/${this.activeBotId}/add-song`, { song });
+    },
+
    async playPlaylist(playlistId: string, platform = 'netease') {
      if (!this.activeBotId) return;
-      await axios.post(`/api/player/${this.activeBotId}/play-playlist`, { playlistId, platform });
+      const res = await axios.post(`/api/player/${this.activeBotId}/play-playlist`, { playlistId, platform });
+      if (res.data?.message) {
+        this.notify(res.data.message, res.data.ok === false ? 'error' : 'info');
+      }
      this._setTiming(this.activeBotId, { serverElapsed: 0 });
      this._syncAfterAction();
    },
@@ -330,31 +384,92 @@ export const usePlayerStore = defineStore('player', {
    },

    async fetchHomeData() {
-      if (this.lastFetchTime > 0 && Date.now() - this.lastFetchTime < HOME_CACHE_TTL) {
+      // Always check auth status first — if it changed since the cached
+      // fetch (e.g., user logged in/out as a different account), the
+      // cached playlists belong to a different user and we MUST refetch.
+      const [neAuthRes, qqAuthRes] = await Promise.allSettled([
+        axios.get('/api/auth/status', { params: { platform: 'netease' } }),
+        axios.get('/api/auth/status', { params: { platform: 'qq' } }),
+      ]);
+      const newAuth = {
+        netease: neAuthRes.status === 'fulfilled' && !!neAuthRes.value.data?.loggedIn,
+        qq:      qqAuthRes.status === 'fulfilled' && !!qqAuthRes.value.data?.loggedIn,
+      };
+      const authChanged =
+        newAuth.netease !== this.authStatus.netease || newAuth.qq !== this.authStatus.qq;
+      this.authStatus.netease = newAuth.netease;
+      this.authStatus.qq = newAuth.qq;
+
+      // Cache hit only if auth is unchanged AND within TTL.
+      if (
+        !authChanged &&
+        this.lastFetchTime > 0 &&
+        Date.now() - this.lastFetchTime < HOME_CACHE_TTL
+      ) {
        return;
      }

-      const [playlistRes, dailyRes, userRes, biliRes] = await Promise.allSettled([
-        axios.get('/api/music/recommend/playlists'),
-        axios.get('/api/music/recommend/songs'),
-        axios.get('/api/music/user/playlists'),
-        axios.get('/api/music/bilibili/popular?limit=12'),
+      // 2. NetEase data: recommend playlists work anonymously; daily/user
+      // playlists need login but Promise.allSettled isolates failures.
+      const neteasePromises = [
+        axios.get('/api/music/recommend/playlists', { params: { platform: 'netease' } }),
+        axios.get('/api/music/recommend/songs',     { params: { platform: 'netease' } }),
+        axios.get('/api/music/user/playlists',      { params: { platform: 'netease' } }),
+      ];
+
+      // 3. QQ data: only fetch when QQ is logged in. When not logged in,
+      // resolve to empty payloads so the same indexed handling works.
+      const emptyPlaylists = { data: { playlists: [] } };
+      const emptySongs     = { data: { songs: [] } };
+      const qqPromises = this.authStatus.qq
+        ? [
+            axios.get('/api/music/recommend/playlists', { params: { platform: 'qq' } }),
+            axios.get('/api/music/recommend/songs',     { params: { platform: 'qq' } }),
+            axios.get('/api/music/user/playlists',      { params: { platform: 'qq' } }),
+          ]
+        : [
+            Promise.resolve(emptyPlaylists),
+            Promise.resolve(emptySongs),
+            Promise.resolve(emptyPlaylists),
+          ];
+
+      const biliPromise = axios.get('/api/music/bilibili/popular?limit=12');
+
+      const results = await Promise.allSettled([
+        ...neteasePromises,
+        ...qqPromises,
+        biliPromise,
      ]);

-      if (playlistRes.status === 'fulfilled') {
-        this.recommendPlaylists = playlistRes.value.data.playlists;
-      }
-      if (dailyRes.status === 'fulfilled') {
-        this.dailySongs = dailyRes.value.data.songs;
-      }
-      if (userRes.status === 'fulfilled') {
-        this.userPlaylists = userRes.value.data.playlists;
-      }
-      if (biliRes.status === 'fulfilled') {
-        this.bilibiliPopular = biliRes.value.data.songs;
+      const [neRecPL, neDaily, neUserPL, qqRecPL, qqDaily, qqUserPL, bili] = results;
+
+      this.recommendPlaylists.netease =
+        neRecPL.status === 'fulfilled' ? (neRecPL.value.data.playlists ?? []) : [];
+      this.dailySongs.netease =
+        neDaily.status === 'fulfilled' ? (neDaily.value.data.songs ?? []) : [];
+      this.userPlaylists.netease =
+        neUserPL.status === 'fulfilled' ? (neUserPL.value.data.playlists ?? []) : [];
+      this.recommendPlaylists.qq =
+        qqRecPL.status === 'fulfilled' ? (qqRecPL.value.data.playlists ?? []) : [];
+      this.dailySongs.qq =
+        qqDaily.status === 'fulfilled' ? (qqDaily.value.data.songs ?? []) : [];
+      this.userPlaylists.qq =
+        qqUserPL.status === 'fulfilled' ? (qqUserPL.value.data.playlists ?? []) : [];
+      // bilibili popular: keep previous value on failure (it's an anonymous endpoint
+      // unrelated to user auth state, and stale popular results are harmless)
+      if (bili.status === 'fulfilled') {
+        this.bilibiliPopular = bili.value.data.songs ?? [];
      }

-      this.lastFetchTime = Date.now();
+      // Only mark as fetched if at least the auth-status calls succeeded —
+      // a fully failed fetch (network blip / server down) should NOT be
+      // cached for 5 minutes, otherwise the user has to hard-reload to
+      // recover when connectivity returns.
+      const authOk =
+        neAuthRes.status === 'fulfilled' || qqAuthRes.status === 'fulfilled';
+      if (authOk) {
+        this.lastFetchTime = Date.now();
+      }
    },
  },
 });
@@ -0,0 +1,42 @@
+import type { Source } from './player.js';
+
+const STORAGE_KEY = 'source-tabs';
+
+export type TabKey =
+  | 'home.recommend'
+  | 'home.daily'
+  | 'home.user'
+  | 'library.user';
+
+function readAll(): Partial<Record<TabKey, Source>> {
+  try {
+    const raw = localStorage.getItem(STORAGE_KEY);
+    if (!raw) return {};
+    const parsed = JSON.parse(raw);
+    // typeof null === 'object' and typeof [] === 'object' — both pass a
+    // naive check but neither is a valid record. Reject explicitly so a
+    // corrupted / manipulated value can't smuggle wrong shapes through.
+    if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+      return {};
+    }
+    return parsed as Partial<Record<TabKey, Source>>;
+  } catch {
+    return {};
+  }
+}
+
+export function loadTabSource(key: TabKey, fallback: Source = 'netease'): Source {
+  const all = readAll();
+  const v = all[key];
+  return v === 'netease' || v === 'qq' ? v : fallback;
+}
+
+export function saveTabSource(key: TabKey, value: Source): void {
+  try {
+    const all = readAll();
+    all[key] = value;
+    localStorage.setItem(STORAGE_KEY, JSON.stringify(all));
+  } catch {
+    // localStorage may be unavailable (private browsing); silently no-op
+  }
+}
@@ -1,33 +1,95 @@
-// YesPlayMusic-inspired design tokens
+// TSMusicBot Design System — canonical tokens

 :root {
-  // Fonts
+  // Typography
  --font-primary: 'Barlow', -apple-system, 'PingFang SC', 'Microsoft YaHei', sans-serif;
+  --font-mono: ui-monospace, SFMono-Regular, Menlo, 'Cascadia Code', monospace;
+
+  --fs-hero:  22px;
+  --fs-h1:    20px;
+  --fs-h2:    17px;
+  --fs-h3:    16px;
+  --fs-body:  14px;
+  --fs-sm:    13px;
+  --fs-xs:    12px;
+  --fs-2xs:   11px;
+  --fs-micro: 10px;
+
+  --fw-regular: 400;
+  --fw-medium:  500;
+  --fw-semi:    600;
+  --fw-bold:    700;
+  --fw-black:   800;
+
+  --lh-tight:  1.2;
+  --lh-normal: 1.4;
+  --lh-body:   1.5;

  // Spacing
+  --space-1:  4px;
+  --space-2:  8px;
+  --space-3:  12px;
+  --space-4:  16px;
+  --space-5:  20px;
+  --space-6:  24px;
+  --space-8:  36px;
+  --space-10: 80px;
+
+  // Layout
  --navbar-height: 56px;
  --player-height: 56px;
+  --page-gutter: 10vw;

  // Radius
+  --radius-xs: 3px;
  --radius-sm: 6px;
  --radius-md: 10px;
  --radius-lg: 14px;
  --radius-xl: 20px;
+  --radius-full: 9999px;

  // Transitions
  --transition-fast: 0.2s ease;
  --transition-normal: 0.3s ease;
+  --ease-cinematic: cubic-bezier(0.25, 0.1, 0.25, 1);
+
+  // Shadows
+  --shadow-dropdown: 0 8px 24px rgba(0, 0, 0, 0.2);
+  --shadow-modal: 0 12px 40px rgba(0, 0, 0, 0.35);

  // Accent
  --color-primary: #335eea;
  --color-primary-bg: #eaeffd;
+  --color-primary-15: rgba(51, 94, 234, 0.15);
+  --color-primary-10: rgba(51, 94, 234, 0.10);
+  --color-primary-12: rgba(51, 94, 234, 0.12);
+  --gradient-fm: linear-gradient(135deg, #335eea, #6366f1);
+
+  // Semantic (theme-invariant)
+  --color-online: #22c55e;
+  --color-online-15: rgba(34, 197, 94, 0.15);
+  --color-paused: #eab308;
+  --color-paused-15: rgba(234, 179, 8, 0.15);
+
+  // Platform brand
+  --brand-netease: #e81123;
+  --brand-netease-15: rgba(232, 17, 35, 0.15);
+  --brand-qq: #12b76a;
+  --brand-qq-15: rgba(18, 183, 106, 0.15);
+  --brand-bilibili: #00a1d6;
+  --brand-bilibili-15: rgba(0, 161, 214, 0.15);
+  --brand-youtube: #ff0000;
+  --brand-youtube-12: rgba(255, 0, 0, 0.12);
 }

+// Dark theme (default)
+:root,
 [data-theme='dark'] {
  --bg-primary: #222222;
  --bg-secondary: #323232;
  --bg-card: rgba(255, 255, 255, 0.04);
  --bg-navbar: rgba(34, 34, 34, 0.86);
+  --bg-modal-scrim: rgba(0, 0, 0, 0.55);
  --text-primary: #ffffff;
  --text-secondary: rgba(255, 255, 255, 0.58);
  --text-tertiary: rgba(255, 255, 255, 0.38);
@@ -40,6 +102,7 @@
  --bg-secondary: #f5f5f7;
  --bg-card: rgba(0, 0, 0, 0.02);
  --bg-navbar: rgba(255, 255, 255, 0.86);
+  --bg-modal-scrim: rgba(0, 0, 0, 0.35);
  --text-primary: #000000;
  --text-secondary: rgba(0, 0, 0, 0.58);
  --text-tertiary: rgba(0, 0, 0, 0.38);
@@ -0,0 +1,42 @@
+<template>
+  <div class="redirect-page">
+    <span v-if="notFound">机器人不存在或未加载</span>
+    <span v-else>正在跳转...</span>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { onMounted, ref } from 'vue';
+import { useRoute, useRouter } from 'vue-router';
+import { usePlayerStore } from '../stores/player.js';
+
+const route = useRoute();
+const router = useRouter();
+const store = usePlayerStore();
+const notFound = ref(false);
+
+onMounted(async () => {
+  const botId = route.params.id as string;
+  if (!store.bots.length) {
+    await store.fetchBots();
+  }
+  const bot = store.bots.find((b) => b.id === botId);
+  if (bot) {
+    store.setActiveBotId(botId);
+    router.replace('/');
+  } else {
+    notFound.value = true;
+  }
+});
+</script>
+
+<style scoped>
+.redirect-page {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  height: 60vh;
+  font-size: 16px;
+  color: var(--text-secondary);
+}
+</style>
@@ -19,8 +19,9 @@
        :song="song"
        :index="i + 1"
        :active="store.currentSong?.id === song.id"
-        @play="store.play(song.name, song.platform)"
-        @add="store.addToQueue(song.name, song.platform)"
+        @play="store.playSong(song)"
+        @playNext="store.playNextSong(song)"
+        @add="store.addSong(song)"
      />
    </div>
  </div>
@@ -35,7 +36,9 @@ import SongCard from '../components/SongCard.vue';

 const store = usePlayerStore();

-const history = ref<Array<{ id: string; name: string; artist: string; album: string; duration: number; coverUrl: string; platform: string }>>([]);
+import { Song } from '../stores/player.js';
+
+const history = ref<Song[]>([]);
 const loading = ref(true);

 onMounted(async () => {
@@ -34,14 +34,17 @@
    </section>

    <!-- 每日推荐 -->
-    <section class="section" v-if="store.dailySongs.length > 0">
-      <h2 class="section-title">每日推荐</h2>
+    <section class="section" v-if="dailyAvailable.length > 0">
+      <h2 class="section-title">
+        每日推荐
+        <SourceTabs v-model="dailySource" :sources="dailyAvailable" />
+      </h2>
      <div class="daily-grid">
        <div
-          v-for="song in store.dailySongs.slice(0, 12)"
+          v-for="song in (store.dailySongs[dailySourceSafe] ?? []).slice(0, 12)"
          :key="song.id"
          class="daily-card hover-scale"
-          @click="store.playById(song.id, song.platform)"
+          @click="store.playSong(song)"
        >
          <CoverArt :url="song.coverUrl" :size="120" :radius="10" :show-shadow="true" />
          <div class="daily-name">{{ song.name }}</div>
@@ -51,11 +54,14 @@
    </section>

    <!-- 推荐歌单 -->
-    <section class="section" v-if="store.recommendPlaylists.length > 0">
-      <h2 class="section-title">推荐歌单</h2>
+    <section class="section" v-if="recommendAvailable.length > 0">
+      <h2 class="section-title">
+        推荐歌单
+        <SourceTabs v-model="recommendSource" :sources="recommendAvailable" />
+      </h2>
      <div class="playlist-grid">
        <RouterLink
-          v-for="playlist in store.recommendPlaylists"
+          v-for="playlist in (store.recommendPlaylists[recommendSourceSafe] ?? [])"
          :key="playlist.id"
          :to="`/playlist/${playlist.id}?platform=${playlist.platform}`"
          class="playlist-card hover-scale"
@@ -67,10 +73,11 @@
    </section>

    <!-- 我的歌单 -->
-    <section class="section" v-if="store.userPlaylists.length > 0">
+    <section class="section" v-if="userAvailable.length > 0">
      <h2 class="section-title">
        我的歌单
-        <span class="section-count">{{ store.userPlaylists.length }}</span>
+        <span v-if="currentUserPlaylists.length > 0" class="section-count">{{ currentUserPlaylists.length }}</span>
+        <SourceTabs v-model="userSource" :sources="userAvailable" />
      </h2>
      <div class="playlist-grid">
        <RouterLink
@@ -85,12 +92,12 @@
        </RouterLink>
      </div>
      <button
-        v-if="store.userPlaylists.length > USER_PLAYLIST_LIMIT"
+        v-if="currentUserPlaylists.length > USER_PLAYLIST_LIMIT"
        class="expand-btn"
        @click="userPlaylistsExpanded = !userPlaylistsExpanded"
      >
        <Icon :icon="userPlaylistsExpanded ? 'mdi:chevron-up' : 'mdi:chevron-down'" />
-        {{ userPlaylistsExpanded ? '收起' : `展开全部 ${store.userPlaylists.length} 个歌单` }}
+        {{ userPlaylistsExpanded ? '收起' : `展开全部 ${currentUserPlaylists.length} 个歌单` }}
      </button>
    </section>

@@ -105,7 +112,7 @@
          v-for="song in store.bilibiliPopular.slice(0, 12)"
          :key="song.id"
          class="daily-card hover-scale"
-          @click="store.playById(song.id, song.platform)"
+          @click="store.playSong(song)"
        >
          <CoverArt :url="song.coverUrl" :size="120" :radius="10" :show-shadow="true" />
          <div class="daily-name">{{ song.name }}</div>
@@ -117,19 +124,60 @@
 </template>

 <script setup lang="ts">
-import { ref, computed, onMounted } from 'vue';
+import { ref, computed, watch, onMounted } from 'vue';
 import { Icon } from '@iconify/vue';
 import axios from 'axios';
-import { usePlayerStore, type Song } from '../stores/player.js';
+import { usePlayerStore, type Song, type Source } from '../stores/player.js';
+import { loadTabSource, saveTabSource } from '../stores/sourceTabs.js';
 import CoverArt from '../components/CoverArt.vue';
+import SourceTabs from '../components/SourceTabs.vue';

 const store = usePlayerStore();
 const USER_PLAYLIST_LIMIT = 20;
 const userPlaylistsExpanded = ref(false);
+
+// Available sources per section.
+// Recommend playlists work anonymously on netease, so it's always available;
+// QQ requires login. This intentionally differs from dailyAvailable/userAvailable.
+const recommendAvailable = computed<Source[]>(() => {
+  const s: Source[] = ['netease'];
+  if (store.authStatus.qq) s.push('qq');
+  return s;
+});
+const dailyAvailable = computed<Source[]>(() => store.availableSources);
+const userAvailable = computed<Source[]>(() => store.availableSources);
+
+// Persisted active source per section.
+const recommendSource = ref<Source>(loadTabSource('home.recommend'));
+const dailySource     = ref<Source>(loadTabSource('home.daily'));
+const userSource      = ref<Source>(loadTabSource('home.user'));
+
+watch(recommendSource, (v) => saveTabSource('home.recommend', v));
+watch(dailySource,     (v) => saveTabSource('home.daily',     v));
+watch(userSource,      (v) => saveTabSource('home.user',      v));
+
+// Fallback when persisted source is no longer available.
+const recommendSourceSafe = computed<Source>(() =>
+  recommendAvailable.value.includes(recommendSource.value)
+    ? recommendSource.value
+    : recommendAvailable.value[0] ?? 'netease'
+);
+const dailySourceSafe = computed<Source>(() =>
+  dailyAvailable.value.includes(dailySource.value)
+    ? dailySource.value
+    : dailyAvailable.value[0] ?? 'netease'
+);
+const userSourceSafe = computed<Source>(() =>
+  userAvailable.value.includes(userSource.value)
+    ? userSource.value
+    : userAvailable.value[0] ?? 'netease'
+);
+
+const currentUserPlaylists = computed(() => store.userPlaylists[userSourceSafe.value] ?? []);
 const visibleUserPlaylists = computed(() =>
  userPlaylistsExpanded.value
-    ? store.userPlaylists
-    : store.userPlaylists.slice(0, USER_PLAYLIST_LIMIT)
+    ? currentUserPlaylists.value
+    : currentUserPlaylists.value.slice(0, USER_PLAYLIST_LIMIT)
 );

 async function playFm() {
@@ -179,6 +227,10 @@ onMounted(() => {

 .section {
  margin-bottom: 36px;
+
+  @media (max-width: 768px) {
+    margin-bottom: 28px;
+  }
 }

 .section-title {
@@ -188,6 +240,11 @@ onMounted(() => {
  display: flex;
  align-items: center;
  gap: 8px;
+
+  @media (max-width: 768px) {
+    font-size: 18px;
+    margin-bottom: 12px;
+  }
 }

 .section-count {
@@ -223,7 +280,7 @@ onMounted(() => {
  justify-content: center;
  width: 24px;
  height: 24px;
-  background: #00a1d6;
+  background: var(--brand-bilibili);
  color: white;
  border-radius: 4px;
  font-size: 14px;
@@ -317,6 +374,7 @@ onMounted(() => {

  @media (max-width: 1200px) { grid-template-columns: repeat(4, 1fr); }
  @media (max-width: 900px) { grid-template-columns: repeat(3, 1fr); }
+  @media (max-width: 768px) { grid-template-columns: repeat(3, 1fr); gap: 14px; }
 }

 .daily-card {
@@ -348,6 +406,7 @@ onMounted(() => {

  @media (max-width: 1200px) { grid-template-columns: repeat(4, 1fr); }
  @media (max-width: 900px) { grid-template-columns: repeat(3, 1fr); }
+  @media (max-width: 768px) { grid-template-columns: repeat(3, 1fr); gap: 14px; }
 }

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

+import { Song } from '../stores/player.js';
+
 interface PlaylistDetail {
  id: string;
  name: string;
@@ -61,18 +64,8 @@ interface PlaylistDetail {
  songCount: number;
 }

-interface SongItem {
-  id: string;
-  name: string;
-  artist: string;
-  album: string;
-  duration: number;
-  coverUrl: string;
-  platform: string;
-}
-
 const playlist = ref<PlaylistDetail | null>(null);
-const songs = ref<SongItem[]>([]);
+const songs = ref<Song[]>([]);
 const loading = ref(true);

 async function playAll() {
@@ -85,20 +78,37 @@ onMounted(async () => {
  const id = route.params.id as string;
  const platform = (route.query.platform as string) || 'netease';

-  try {
-    const [detailRes, songsRes] = await Promise.all([
-      axios.get(`/api/music/playlist/${id}/detail`, { params: { platform } }),
-      axios.get(`/api/music/playlist/${id}`, { params: { platform } }),
-    ]);
-    playlist.value = detailRes.data.playlist;
-    songs.value = songsRes.data.songs;
-  } catch (err: any) {
-    console.error('Failed to load playlist:', err?.response?.status, err?.message);
+  // 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.
+  const [detailRes, songsRes] = await Promise.allSettled([
+    axios.get(`/api/music/playlist/${id}/detail`, { params: { platform } }),
+    axios.get(`/api/music/playlist/${id}`, { params: { platform } }),
+  ]);
+
+  const detail = detailRes.status === 'fulfilled' ? detailRes.value.data?.playlist : null;
+  const songList = songsRes.status === 'fulfilled' ? (songsRes.value.data?.songs ?? []) : [];
+
+  if (detail) {
+    playlist.value = detail;
+  } else if (songList.length > 0) {
+    // Fall back to a stub built from the route + first song's cover.
+    playlist.value = {
+      id,
+      name: '歌单',
+      description: '',
+      coverUrl: songList[0]?.coverUrl ?? '',
+      songCount: songList.length,
+    };
+  } else {
    playlist.value = null;
-    songs.value = [];
-  } finally {
-    loading.value = false;
+    if (detailRes.status === 'rejected') {
+      console.error('Failed to load playlist detail:', (detailRes.reason as any)?.response?.status, (detailRes.reason as any)?.message);
+    }
  }
+  songs.value = songList;
+  loading.value = false;
 });
 </script>

@@ -27,8 +27,9 @@
        :song="song"
        :index="i + 1"
        :active="store.currentSong?.id === song.id"
-        @play="store.playById(song.id, song.platform)"
-        @add="store.addToQueueById(song.id, song.platform)"
+        @play="store.playSong(song)"
+        @playNext="store.playNextSong(song)"
+        @add="store.addSong(song)"
      />
    </div>

@@ -50,7 +51,9 @@ const store = usePlayerStore();
 const route = useRoute();

 const query = ref((route.query.q as string) || '');
-const results = ref<Array<{ id: string; name: string; artist: string; album: string; duration: number; coverUrl: string; platform: string }>>([]);
+import { Song } from '../stores/player.js';
+
+const results = ref<Song[]>([]);
 const loading = ref(false);
 const searched = ref(false);

@@ -76,6 +76,10 @@
            <label>频道密码（可选）</label>
            <input v-model="editForm.channelPassword" class="input" type="password" />
          </div>
+          <div class="form-group">
+            <label>服务器密码（可选）</label>
+            <input v-model="editForm.serverPassword" class="input" type="password" placeholder="服务器有密码时填写" />
+          </div>
          <div class="modal-actions">
            <button class="btn-secondary" @click="editingBot = null">取消</button>
            <button class="btn-primary" @click="saveEditBot">保存（需重启机器人生效）</button>
@@ -108,6 +112,10 @@
          <label>默认频道（可选）</label>
          <input v-model="newBotChannel" class="input" placeholder="音乐频道" />
        </div>
+        <div class="form-group">
+          <label>服务器密码（可选）</label>
+          <input v-model="newBotServerPassword" class="input" type="password" placeholder="服务器有密码时填写" />
+        </div>
        <button class="btn-primary" @click="createBot">创建</button>
      </div>
    </section>
@@ -363,6 +371,78 @@
        </div>
      </div>
    </section>
+    
+    <!-- Idle Timeout -->
+    <section class="settings-section">
+      <h2 class="section-title">行为设置</h2>
+      <div class="setting-row">
+        <div class="setting-label">
+          <Icon icon="mdi:timer-off-outline" class="setting-icon" />
+          <div>
+            <div>闲置自动退出</div>
+            <div style="font-size:12px; opacity:0.6; margin-top:2px">频道无人时，机器人自动断开的等待时间（0 = 不退出）</div>
+          </div>
+        </div>
+        <div class="prefix-input-wrap">
+          <input
+            v-model.number="idleTimeout"
+            type="number"
+            min="0"
+            class="input input-sm"
+            style="max-width:80px"
+            placeholder="0"
+          />
+          <span style="font-size:13px; opacity:0.7">分钟</span>
+          <button class="btn-primary" @click="saveIdleTimeout">保存</button>
+        </div>
+      </div>
+    </section>
+
+    <!-- Bot Profile (TeamSpeak Behavior) -->
+    <section class="settings-section">
+      <h2 class="section-title">机器人 Profile（TeamSpeak 行为）</h2>
+      <p class="profile-section-hint">控制 bot 在 TeamSpeak 上自动同步歌曲信息的方式。⚠️ 标记的项会触发频道里所有人的提示音。</p>
+      <div v-if="store.bots.length === 0" class="empty-hint">还没有机器人，先在上面创建一个。</div>
+      <div v-else class="profile-bot-list">
+        <div v-for="bot in store.bots" :key="bot.id" class="profile-bot">
+          <button
+            class="profile-bot-header"
+            :class="{ expanded: profileExpanded[bot.id] }"
+            @click="toggleProfileExpanded(bot.id)"
+          >
+            <Icon :icon="profileExpanded[bot.id] ? 'mdi:chevron-down' : 'mdi:chevron-right'" />
+            <span class="profile-bot-name">{{ bot.name }}</span>
+          </button>
+          <div v-if="profileExpanded[bot.id]" class="profile-toggles">
+            <div v-if="profileLoadError[bot.id]" class="profile-loading profile-error">
+              {{ profileLoadError[bot.id] }}
+              <button class="btn-link" @click="loadProfileConfig(bot.id)">重试</button>
+            </div>
+            <div v-else-if="!profileConfigs[bot.id]" class="profile-loading">加载中...</div>
+            <label
+              v-else
+              v-for="t in PROFILE_TOGGLES"
+              :key="t.key"
+              class="profile-toggle"
+            >
+              <div class="profile-toggle-text">
+                <div class="profile-toggle-label">
+                  {{ t.label }}
+                  <span v-if="t.warning" class="profile-warn-tag">⚠️ {{ t.warning }}</span>
+                </div>
+                <div class="profile-toggle-hint">{{ t.hint }}</div>
+              </div>
+              <input
+                type="checkbox"
+                class="profile-toggle-switch"
+                :checked="profileConfigs[bot.id][t.key]"
+                @change="updateProfile(bot.id, t.key, ($event.target as HTMLInputElement).checked)"
+              />
+            </label>
+          </div>
+        </div>
+      </div>
+    </section>
  </div>
 </template>

@@ -394,6 +474,7 @@ const newBotServer = ref('');
 const newBotPort = ref(9987);
 const newBotNickname = ref('MusicBot');
 const newBotChannel = ref('');
+const newBotServerPassword = ref('');

 // Edit bot
 const editingBot = ref<string | null>(null);
@@ -404,6 +485,7 @@ const editForm = reactive({
  nickname: '',
  defaultChannel: '',
  channelPassword: '',
+  serverPassword: '',
 });

 const neteaseCookie = ref('');
@@ -559,6 +641,7 @@ async function createBot() {
      serverPort: newBotPort.value || 9987,
      nickname: newBotNickname.value || newBotName.value,
      defaultChannel: newBotChannel.value || undefined,
+      serverPassword: newBotServerPassword.value || undefined,
      autoStart: false,
    });
    newBotName.value = '';
@@ -566,6 +649,7 @@ async function createBot() {
    newBotPort.value = 9987;
    newBotNickname.value = 'MusicBot';
    newBotChannel.value = '';
+    newBotServerPassword.value = '';
    await store.fetchBots();
  } catch {
    // Ignore
@@ -598,6 +682,7 @@ async function openEditBot(bot: any) {
    editForm.nickname = res.data.nickname ?? '';
    editForm.defaultChannel = res.data.defaultChannel ?? '';
    editForm.channelPassword = res.data.channelPassword ?? '';
+    editForm.serverPassword = res.data.serverPassword ?? '';
  } catch {
    // Config not found — use defaults
    editForm.serverAddress = '';
@@ -605,6 +690,7 @@ async function openEditBot(bot: any) {
    editForm.nickname = bot.name;
    editForm.defaultChannel = '';
    editForm.channelPassword = '';
+    editForm.serverPassword = '';
  }
 }

@@ -647,10 +733,93 @@ async function savePrefix() {
  // Prefix is saved client-side for now
 }

+// Idle timeout
+const idleTimeout = ref(0);
+
+async function loadIdleTimeout() {
+  try {
+    const res = await axios.get('/api/bot/settings');
+    idleTimeout.value = res.data.idleTimeoutMinutes ?? 0;
+  } catch { /* ignore */ }
+}
+
+async function saveIdleTimeout() {
+  try {
+    await axios.post('/api/bot/settings', { idleTimeoutMinutes: idleTimeout.value });
+  } catch { /* ignore */ }
+}
+
+// --- Bot Profile config ---
+interface ProfileConfig {
+  avatarEnabled: boolean;
+  descriptionEnabled: boolean;
+  nicknameEnabled: boolean;
+  awayStatusEnabled: boolean;
+  channelDescEnabled: boolean;
+  nowPlayingMsgEnabled: boolean;
+}
+
+const PROFILE_TOGGLES: ReadonlyArray<{
+  key: keyof ProfileConfig;
+  label: string;
+  hint: string;
+  warning: string | null;
+}> = [
+  { key: 'avatarEnabled',       label: '同步头像',           hint: '使用专辑封面作为 bot 头像',                  warning: null },
+  { key: 'descriptionEnabled',  label: '同步个人描述',       hint: '在 bot 简介里显示当前播放的歌曲',            warning: null },
+  { key: 'nicknameEnabled',     label: '同步昵称',           hint: 'bot 昵称跟着歌名变化',                       warning: null },
+  { key: 'awayStatusEnabled',   label: '走开状态',           hint: '停止播放时把 bot 设为"走开"',               warning: null },
+  { key: 'channelDescEnabled',  label: '更新频道描述',       hint: '把"正在播放"信息写入频道描述',             warning: '频道编辑提示音' },
+  { key: 'nowPlayingMsgEnabled',label: '推送"正在播放"消息', hint: '切歌时在频道里发一条文字消息',               warning: '新消息提示音' },
+];
+
+const profileConfigs = reactive<Record<string, ProfileConfig>>({});
+const profileExpanded = reactive<Record<string, boolean>>({});
+const profileLoadError = reactive<Record<string, string | null>>({});
+
+async function loadProfileConfig(botId: string) {
+  if (profileConfigs[botId]) return;
+  profileLoadError[botId] = null;
+  try {
+    const res = await axios.get(`/api/player/${botId}/profile`);
+    // Defensive: a 200 response with non-object body (empty / proxy
+    // injection / etc.) would otherwise leave the row stuck on
+    // "加载中..." because profileConfigs[botId] would be falsy.
+    if (!res.data || typeof res.data !== 'object' || typeof res.data.avatarEnabled !== 'boolean') {
+      profileLoadError[botId] = '响应格式异常';
+      return;
+    }
+    profileConfigs[botId] = res.data;
+  } catch (err: any) {
+    profileLoadError[botId] = err?.response?.status === 404
+      ? '机器人未加载'
+      : '加载失败，请重试';
+  }
+}
+
+function toggleProfileExpanded(botId: string) {
+  profileExpanded[botId] = !profileExpanded[botId];
+  if (profileExpanded[botId]) loadProfileConfig(botId);
+}
+
+async function updateProfile(botId: string, key: keyof ProfileConfig, value: boolean) {
+  const cfg = profileConfigs[botId];
+  if (!cfg) return;
+  const prev = cfg[key];
+  cfg[key] = value; // optimistic
+  try {
+    const res = await axios.put(`/api/player/${botId}/profile`, { [key]: value });
+    profileConfigs[botId] = res.data;
+  } catch {
+    cfg[key] = prev; // revert
+  }
+}
+
 onMounted(() => {
  store.fetchBots(); // Refresh bot status on page visit
  checkAuthStatus();
  loadQuality();
+  loadIdleTimeout();
 });

 onUnmounted(() => {
@@ -763,16 +932,16 @@ onUnmounted(() => {
  background: var(--border-color);
  color: var(--text-tertiary);
  &.online {
-    background: rgba(51, 94, 234, 0.15);
+    background: var(--color-primary-15);
    color: var(--color-primary);
  }
  &.playing {
-    background: rgba(76, 175, 80, 0.15);
-    color: #4caf50;
+    background: var(--color-online-15);
+    color: var(--color-online);
  }
  &.paused {
-    background: rgba(255, 152, 0, 0.15);
-    color: #ff9800;
+    background: var(--color-paused-15);
+    color: var(--color-paused);
  }
 }

@@ -796,7 +965,7 @@ onUnmounted(() => {
  color: var(--color-primary);

  &.bilibili-icon {
-    color: #00a1d6;
+    color: var(--brand-bilibili);
  }
 }

@@ -808,7 +977,7 @@ onUnmounted(() => {
 .account-status {
  font-size: 12px;
  color: var(--text-tertiary);
-  &.logged { color: #4caf50; }
+  &.logged { color: var(--color-online); }
 }

 .login-methods {
@@ -831,7 +1000,7 @@ onUnmounted(() => {

  &:hover { border-color: var(--color-primary); color: var(--color-primary); }
  &.active {
-    background: rgba(51, 94, 234, 0.1);
+    background: var(--color-primary-10);
    border-color: var(--color-primary);
    color: var(--color-primary);
  }
@@ -955,7 +1124,7 @@ onUnmounted(() => {
  &:hover { border-color: var(--border-color); }
  &.active {
    border-color: var(--color-primary);
-    background: rgba(51, 94, 234, 0.1);
+    background: var(--color-primary-10);
  }
 }

@@ -1082,4 +1251,189 @@ onUnmounted(() => {
  from { transform: rotate(0deg); }
  to { transform: rotate(360deg); }
 }
+
+// --- Bot Profile section ---
+.profile-section-hint {
+  font-size: 13px;
+  color: var(--text-secondary);
+  margin: -8px 0 16px;
+  line-height: 1.5;
+}
+
+.empty-hint {
+  font-size: 13px;
+  color: var(--text-tertiary);
+  padding: 12px;
+}
+
+.profile-bot-list {
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
+}
+
+.profile-bot {
+  border: 1px solid var(--border-color);
+  border-radius: var(--radius-md);
+  overflow: hidden;
+}
+
+.profile-bot-header {
+  width: 100%;
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  padding: 12px 16px;
+  background: transparent;
+  font-size: 14px;
+  font-weight: 600;
+  color: var(--text-primary);
+  cursor: pointer;
+  transition: background var(--transition-fast);
+
+  &:hover { background: var(--hover-bg); }
+  &.expanded { background: var(--hover-bg); }
+}
+
+.profile-bot-name {
+  flex: 1;
+  text-align: left;
+}
+
+.profile-toggles {
+  display: flex;
+  flex-direction: column;
+  padding: 0 16px 8px;
+  border-top: 1px solid var(--border-color);
+}
+
+.profile-loading {
+  padding: 16px 0;
+  font-size: 13px;
+  color: var(--text-tertiary);
+  text-align: center;
+}
+
+.profile-error {
+  color: var(--brand-netease); // re-uses red brand color for error state
+
+  .btn-link {
+    margin-left: 8px;
+    font-size: 13px;
+    color: var(--color-primary);
+    text-decoration: underline;
+    background: transparent;
+    cursor: pointer;
+  }
+}
+
+.profile-toggle {
+  display: flex;
+  align-items: center;
+  gap: 16px;
+  padding: 14px 0;
+  border-bottom: 1px solid var(--border-color);
+  cursor: pointer;
+
+  &:last-child { border-bottom: none; }
+}
+
+.profile-toggle-text {
+  flex: 1;
+  min-width: 0;
+}
+
+.profile-toggle-label {
+  font-size: 14px;
+  font-weight: 500;
+  color: var(--text-primary);
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  flex-wrap: wrap;
+  line-height: 1.3;
+}
+
+.profile-warn-tag {
+  font-size: 11px;
+  font-weight: 500;
+  padding: 2px 6px;
+  background: var(--color-paused-15);
+  color: var(--color-paused);
+  border-radius: var(--radius-xs);
+  white-space: nowrap;
+}
+
+.profile-toggle-hint {
+  font-size: 12px;
+  color: var(--text-tertiary);
+  margin-top: 4px;
+  line-height: 1.4;
+}
+
+.profile-toggle-switch {
+  flex-shrink: 0;
+  appearance: none;
+  -webkit-appearance: none;
+  width: 40px;
+  height: 22px;
+  border-radius: 999px;
+  background: var(--bg-secondary);
+  border: 1px solid var(--border-color);
+  position: relative;
+  cursor: pointer;
+  transition: background var(--transition-fast), border-color var(--transition-fast);
+  margin: 0;
+
+  &::before {
+    content: '';
+    position: absolute;
+    top: 2px;
+    left: 2px;
+    width: 16px;
+    height: 16px;
+    border-radius: 50%;
+    background: var(--text-secondary);
+    transition: transform var(--transition-fast), background var(--transition-fast);
+  }
+
+  &:checked {
+    background: var(--color-primary);
+    border-color: var(--color-primary);
+
+    &::before {
+      transform: translateX(18px);
+      background: white;
+    }
+  }
+}
+
+@media (max-width: 768px) {
+  .profile-bot-header {
+    padding: 14px 12px;
+    font-size: 15px;
+  }
+
+  .profile-toggles {
+    padding: 0 12px 6px;
+  }
+
+  .profile-toggle {
+    gap: 12px;
+    padding: 14px 0;
+  }
+
+  .profile-toggle-switch {
+    width: 44px;
+    height: 24px;
+
+    &::before {
+      width: 18px;
+      height: 18px;
+    }
+    &:checked::before {
+      transform: translateX(20px);
+    }
+  }
+}
 </style>