Merge remote-tracking branch 'origin/main' into feat/issue-119-saved-playlists

# Conflicts:
#	src/data/config.ts

.claude/settings.json

@@ -1,24 +0,0 @@
-{
-  "permissions": {
-    "allow": [
-      "Read",
-      "Edit",
-      "Write",
-      "Glob",
-      "Grep",
-      "Bash(*)",
-      "WebFetch(*)",
-      "WebSearch(*)",
-      "Agent(*)",
-      "mcp__Claude_Preview__*",
-      "mcp__Claude_in_Chrome__*",
-      "mcp__scheduled-tasks__*"
-    ],
-    "deny": [
-      "Bash(git push * main)",
-      "Bash(git push * master)",
-      "Bash(git push --force *)",
-      "Bash(rm -rf /)"
-    ]
-  }
-}

.claude/settings.local.json

@@ -1,26 +0,0 @@
-{
-  "permissions": {
-    "allow": [
-      "Read",
-      "Edit",
-      "Write",
-      "Glob",
-      "Grep",
-      "Bash(*)",
-      "WebFetch(*)",
-      "WebSearch(*)",
-      "Agent(*)",
-      "mcp__Claude_Preview__*",
-      "mcp__Claude_in_Chrome__*",
-      "mcp__scheduled-tasks__*",
-      "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 --force *)",
-      "Bash(rm -rf /)"
-    ]
-  }
-}

.gitignore

@@ -7,6 +7,7 @@ config.json
 cookies/
 .superpowers/
 .worktrees/
+.claude/
 setup.log
 /bin/
 scripts/navbar_bigger.png

README.md

@@ -5,7 +5,7 @@
 <h1 align="center">TSMusicBot</h1>
 
 <p align="center">
-  <strong>TeamSpeak 音乐机器人</strong> — 自建 <strong>Jellyfin</strong> 音乐库为主音源，网易云 / QQ / 酷狗 / 哔哩哔哩 / YouTube / Spotify 可选启用，YesPlayMusic 风格 WebUI 控制面板
+  <strong>TeamSpeak 音乐机器人</strong> — 网易云音乐 + QQ 音乐 + 酷狗音乐 + 哔哩哔哩 + YouTube（可选），Jellyfin / Spotify 可选启用，YesPlayMusic 风格 WebUI 控制面板
 </p>
 
 <p align="center">
@@ -15,27 +15,28 @@
   <img src="https://img.shields.io/badge/许可证-MIT-green" />
   <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/Jellyfin-主音源-aa5cc3?logo=jellyfin&logoColor=white" />
+  <img src="https://img.shields.io/badge/酷狗音乐-支持-2ca2f9" />
-  <img src="https://img.shields.io/badge/酷狗音乐-可选-2ca2f9" />
+  <img src="https://img.shields.io/badge/BiliBili-支持-00a1d6?logo=bilibili&logoColor=white" />
-  <img src="https://img.shields.io/badge/BiliBili-可选-00a1d6?logo=bilibili&logoColor=white" />
+  <img src="https://img.shields.io/badge/Jellyfin-可选-aa5cc3?logo=jellyfin&logoColor=white" />
   <img src="https://img.shields.io/badge/YouTube-可选-FF0000?logo=youtube&logoColor=white" />
   <img src="https://img.shields.io/badge/Spotify-可选-1DB954?logo=spotify&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>
 
-> 本项目 fork 自 [ZHANGTIANYAO1/teamspeak-music-bot](https://github.com/ZHANGTIANYAO1/teamspeak-music-bot)（MIT 许可），在其基础上将自建 Jellyfin 服务器改造为默认主音源；原有在线音源全部保留，可按需在配置中重新启用。
+> v1.10.0 新增**可选**的 [Jellyfin](https://jellyfin.org/) 音源（由 [@ItsEricRao](https://github.com/ItsEricRao) 在 [PR #123](https://github.com/ZHANGTIANYAO1/teamspeak-music-bot/pull/123) 中贡献）：连接自建 Jellyfin 服务器直接播放你自己的音乐库。默认关闭，在 **设置 → Jellyfin 音乐库** 一键开启；原有在线音源保持默认启用，行为不变。
 
 ## 功能特性
 
 - **WebUI 鉴权与细粒度权限（必选）** — 用户名 + 密码登录，多用户、两种角色（管理员 / 成员）；成员可进一步配置**细粒度能力**（播放控制 / 队列管理 / 机器人管理 / 平台登录 / 音质）和**按机器人授权白名单**，所有变更操作由后端逐请求强制校验。bcrypt 加密、HttpOnly 会话 Cookie，CSRF 防护，WebSocket 同样鉴权。首次访问引导创建管理员。从无鉴权旧版本升级时请参阅 [更新升级](#更新升级) 章节
 - **游客模式（免登录点歌，默认关闭）** — 管理员可选择允许访客**无需账号密码**进入 WebUI 点歌，并逐项配置游客权限（8 个开关，默认仅「添加到队列末尾」开启）与可控机器人白名单；游客无法查看 / 修改任何设置、管理机器人或访问用户管理。开启后登录页出现 **「以游客身份进入」**。详见下文 **「游客模式 / Guest mode」** 小节
 - **本地收藏歌单** — 在首页 / 搜索 / 歌单页一键收藏，收藏内容按用户存储，登录后跨设备同步
+- **保存/加载播放清单 + 重启后自动恢复队列（可选，默认关闭）** — 管理员在 设置 → 行为设置 开启后，可在网页「已存队列」页或聊天命令（`!save` / `!load` / `!queues`）把当前队列保存为清单，随时**替换**加载或**追加**到队列末尾；同时机器人重启后会自动恢复并继续播放上次的队列。网页保存可选「共享」，聊天保存进入共享清单。**说明**：重启只能从当前曲目的开头恢复（不记忆播放进度）；Spotify 自动恢复为尽力而为（依赖 sidecar 可用）。详见 [使用说明](#使用说明)
 - **本地音频上传播放** — 在搜索页拖拽或选择本地音频上传，上传后可直接播放 / 下一首播放 / 加入队列；管理员可在 设置 → 行为设置 开关此功能，播放结束或停止/清空/替换队列时会清理服务端接收的本地文件
 - **专属链接（单机器人锁定）** — 通过 `/bot/<id>` 专属链接打开 WebUI 时锁定到单个机器人，刷新后保持，适合把某台机器人的控制页分享给特定用户
 - **频道无人时自动暂停** — 机器人所在频道没有其他人时自动暂停播放，有人加入后自动恢复（**默认关闭**，可在设置中开启）
-- **Jellyfin 主音源** — 连接自建 [Jellyfin](https://jellyfin.org/) 服务器作为默认音源：搜索（歌曲 / 专辑 / 歌单）、懒解析直传播放、同步歌词、收藏 Instant Mix 电台（`!fm`）、首页「最近添加 / 播放最多 / 收藏 / 流派」，并把播放进度回报给 Jellyfin（PlayCount / 播放状态）。详见 [Jellyfin 音源（主音源）](#jellyfin-音源主音源)
+- **Jellyfin 音源（可选）** — 连接自建 [Jellyfin](https://jellyfin.org/) 服务器作为额外音源：搜索（歌曲 / 专辑 / 歌单）、懒解析直传播放、同步歌词、收藏 Instant Mix 电台（`!fm -j`）、首页「最近添加 / 播放最多 / 收藏 / 流派」，并把播放进度回报给 Jellyfin（PlayCount / 播放状态）。**默认关闭**，在 设置 → Jellyfin 音乐库 一键开启。详见 [可选：Jellyfin 音源](#可选jellyfin-音源)
-- **多平台音源（enabledProviders 门控）** — 网易云音乐 / QQ 音乐 / 酷狗音乐 / 哔哩哔哩 / YouTube（yt-dlp）代码全部保留但**默认停用**，在 `config.json` 的 `enabledProviders` 中列出即可重新启用；**Spotify（实验性）** 由独立开关控制（需 Premium + 自建开发者应用，默认关闭，详见 [Spotify 音源（实验性）](#spotify-音源实验性)）。统一搜索（歌曲 / 歌单 / 专辑均支持翻页「加载更多」），结果标注来源，禁用音源不出现在搜索栏
+- **多平台音源（enabledProviders 门控）** — 网易云音乐 / QQ 音乐 / 酷狗音乐 / 哔哩哔哩 / YouTube（yt-dlp，需安装）**默认启用**，可在 `config.json` 的 `enabledProviders` 中逐个停用；Jellyfin 为可选音源（见上），**Spotify（实验性）** 由独立开关控制（需 Premium + 自建开发者应用，默认关闭，详见 [Spotify 音源（实验性）](#spotify-音源实验性)）。统一搜索（歌曲 / 歌单 / 专辑均支持翻页「加载更多」），结果标注来源，禁用音源不出现在搜索栏
 - **真实客户端协议 (TS3/TS6 双协议)** — 机器人在 TeamSpeak 中可见（非 ServerQuery 隐身模式），自动检测并适配 TS3 和 TS6 服务器，支持 TS6 HTTP Query API
 - **YesPlayMusic 风格 WebUI** — 精美界面，支持深色/浅色主题切换
 - **完整播放控制** — 播放/暂停/上一首/下一首/进度跳转/音量调节
@@ -167,6 +168,16 @@ sudo ./scripts/install.sh
 >
 > **如何判断是否需要迁移**：如果你是全新安装，或者你的机器人数据库中 `identity` 字段已经是空的，则**无需任何操作**。完成上述步骤后，按下面对应的系统升级步骤执行即可。
 
+### 关于 enabledProviders 音源开关（v1.10.0 起）
+
+v1.10.0（[PR #123](https://github.com/ZHANGTIANYAO1/teamspeak-music-bot/pull/123)）引入 `enabledProviders` 音源开关与可选的 Jellyfin 音源。当前默认值为 `["netease", "qq", "bilibili", "youtube", "kugou"]`——**与旧版行为一致**，从更早版本升级**无需任何操作**，在线音源照常可用；Jellyfin 需要手动开启（详见 [可选：Jellyfin 音源](#可选jellyfin-音源)）。
+
+> ⚠️ **仅影响短暂运行过 v1.10.0 初版的用户**：该版本曾把默认音源设为 Jellyfin-only。如果你在那段时间保存过设置，`data/config.json` 中可能被写入了 `"enabledProviders": ["jellyfin"]`，升级后在线音源会保持停用。修复方法：把在线音源加回列表（或直接删除该字段以使用默认值），重启机器人（网易云 / QQ 的内嵌 API 服务需要重启才会启动）：
+>
+> ```json
+> "enabledProviders": ["netease", "qq", "bilibili", "youtube", "kugou", "jellyfin"]
+> ```
+
 ### 从 WebUI 无鉴权版本升级（重要）
 
 本次更新引入了**强制 WebUI 鉴权**。从无鉴权旧版本升级后，**WebUI 必须先创建管理员账号才能使用**。所有 `/api/*` 端点（除少量公共白名单）和 `/ws` 现在都需要登录。
@@ -307,18 +318,20 @@ sudo systemctl start tsmusicbot
    - 机器人昵称
    - 可选：服务器密码、默认频道
 3. 在 **设置 → 音乐账号** 扫码登录网易云 / QQ 音乐 / 酷狗音乐 / B 站账号（可选，登录后可播放 VIP 歌曲、获取每日推荐 / 我的歌单等）
-4. 在 **设置 → 用户管理**（仅管理员可见）按需添加成员。成员默认可控制播放但无法管理其他用户；管理员还可为每个成员单独配置**能力**（播放控制 / 队列 / 机器人管理 / 平台登录 / 音质）和**可操作的机器人白名单**，未授权的机器人对该成员不可见、不可控
+4. （可选）在 **设置 → Jellyfin 音乐库** 连接自建 Jellyfin 服务器并打开「启用 Jellyfin 音源」（安装向导第 3 步保存连接时会自动启用；详见 [可选：Jellyfin 音源](#可选jellyfin-音源)）
+5. 在 **设置 → 用户管理**（仅管理员可见）按需添加成员。成员默认可控制播放但无法管理其他用户；管理员还可为每个成员单独配置**能力**（播放控制 / 队列 / 机器人管理 / 平台登录 / 音质）和**可操作的机器人白名单**，未授权的机器人对该成员不可见、不可控
 
 ### WebUI 页面说明
 
 | 页面 | 功能 |
 |------|------|
-| **首页** | 推荐歌单、每日推荐、私人FM（网易云 / QQ 雷达 / 酷狗电台）、我的歌单、收藏的歌单（各源带标签切换） |
+| **首页** | 推荐歌单、每日推荐、私人FM（网易云 / QQ 雷达 / 酷狗电台）、我的歌单、收藏的歌单（各源带标签切换）；启用 Jellyfin 后另有「Jellyfin 电台 / 最近添加 / 播放最多 / 收藏 / 流派」区块 |
-| **搜索** | 四平台统一搜索，结果标注网易云/QQ/酷狗/B站来源，可一键收藏歌单 |
+| **搜索** | 跨音源统一搜索（仅显示已启用的音源；启用 Jellyfin 后其结果排最前），结果标注来源，可一键收藏歌单 |
 | **歌单** | 查看歌单详情，播放全部（根据当前播放模式选择首歌），一键收藏 |
 | **歌词** | 全屏歌词页，实时同步滚动，模糊专辑封面背景 |
 | **历史** | 播放历史记录 |
-| **设置** | 账户（修改自己密码） / 主题切换 / 机器人管理 / 行为设置（空闲超时、频道无人自动暂停） / 多平台账号登录（网易云 / QQ / 酷狗 / B站） / 音质选择 / 命令前缀 / 用户管理（仅管理员，含成员能力与机器人白名单）/ 操作审计（仅管理员） |
+| **已存队列** | 保存当前队列为清单、加载（替换）/ 追加 / 删除已保存清单（仅在管理员开启「保存/加载播放清单」后出现） |
+| **设置** | 账户（修改自己密码） / 主题切换 / 机器人管理 / 行为设置（空闲超时、频道无人自动暂停、保存/加载播放清单、单曲直接播放不清空队列） / 多平台账号登录（网易云 / QQ / 酷狗 / B站） / 音质选择 / 命令前缀 / 用户管理（仅管理员，含成员能力与机器人白名单）/ 操作审计（仅管理员） |
 
 ### TeamSpeak 文字命令
 
@@ -326,9 +339,9 @@ sudo systemctl start tsmusicbot
 
 | 命令 | 说明 |
 |------|------|
-| `!play <歌名>` | 搜索并播放（取最热门的匹配项；默认音源为 Jellyfin，除非已停用） |
+| `!play <歌名>` | 搜索并播放（取最热门的匹配项；默认音源为网易云） |
-| `!play -j <歌名>` | 显式从 Jellyfin 搜索 |
+| `!play -n <歌名>` | 显式从网易云音乐搜索（默认音源即网易云，通常可省略） |
-| `!play -n <歌名>` | 从网易云音乐搜索（默认音源不再是网易云，需显式 `-n`） |
+| `!play -j <歌名>` | 从 Jellyfin 搜索（需先启用 Jellyfin 音源） |
 | `!play -q <歌名>` | 从 QQ 音乐搜索 |
 | `!play -k <歌名>` | 从酷狗音乐搜索 |
 | `!play -b <关键词>` | 从哔哩哔哩搜索视频并播放音频 |
@@ -348,17 +361,22 @@ sudo systemctl start tsmusicbot
 | `!playlist -q <歌单名>` | 从 QQ 音乐搜索并加载歌单 |
 | `!album <专辑名或ID>` | 加载专辑（支持名称搜索 / 数字 ID / Jellyfin GUID） |
 | `!artist <歌手名>` | 按歌手循环播放（支持 `-j`/`-n`/`-q`/`-k`/`-b`/`-y`） |
-| `!fm` | 私人 FM（默认 Jellyfin：从收藏出发的 Instant Mix 电台，自动续播） |
+| `!fm` | 私人 FM（默认网易云，自动续播） |
-| `!fm -n` | 网易云私人 FM（自动续播） |
+| `!fm -j` | Jellyfin 电台：从收藏出发的 Instant Mix（需启用 Jellyfin，自动续播） |
 | `!fm -q` | QQ 音乐雷达 / 猜你喜欢 FM（自动续播） |
 | `!fm -k` | 酷狗私人电台 / 个性化推荐 FM（自动续播） |
 | `!lyrics` | 显示当前完整歌词（自动分多条消息发送，不再只显示开头几行） |
 | `!now` | 当前播放信息 |
 | `!vote` | 投票跳过当前歌曲 |
 | `!move <频道名>` | 移动到指定频道 |
+| `!save <名称>` | 保存当前队列为一份已保存清单（需启用「保存/加载播放清单」，聊天保存进入共享清单） |
+| `!load [-a] <名称>` | 加载已保存清单（默认替换当前队列并播放；加 `-a` 追加到队列末尾） |
+| `!queues` | 列出已保存（共享）清单 |
 | `!help` | 显示帮助信息 |
 
 > 命令前缀默认为 `!`，可在设置页面修改。支持别名：`!p` = `!play`，`!s` = `!skip`，`!n` = `!next`
+>
+> `!save` / `!load` / `!queues` 仅在管理员开启「保存/加载播放清单」后可用（默认关闭），未启用时回复「此功能未启用」。
 
 ### TeamSpeak 命令权限（管理类命令限制）
 
@@ -383,14 +401,7 @@ sudo systemctl start tsmusicbot
 
 ### 音质等级
 
-**Jellyfin（主音源）**
+**在线音源（网易云等）**
-
-| 等级 | 说明 |
-|------|------|
-| **原始直传（direct）** | **默认**：原始文件不转码直传（机器人本地统一转 Opus，此档即最高音质） |
-| 320kbps / 192kbps / 128kbps | 由 Jellyfin 服务器转码后传输，适合公网带宽有限的自建服务器 |
-
-**在线音源（网易云等，启用后可选）**
 
 | 等级 | 码率 | 格式 | 说明 |
 |------|------|------|------|
@@ -401,8 +412,29 @@ sudo systemctl start tsmusicbot
 | Hi-Res | ~1500kbps | FLAC | 需要 VIP |
 | 超清母带 | ~4000kbps | FLAC | 需要黑胶 VIP |
 
+**Jellyfin（启用后）**
+
+| 等级 | 说明 |
+|------|------|
+| **原始直传（direct）** | **默认**：原始文件不转码直传（机器人本地统一转 Opus，此档即最高音质） |
+| 320kbps / 192kbps / 128kbps | 由 Jellyfin 服务器转码后传输，适合公网带宽有限的自建服务器 |
+
 在设置页面选择音质，立即生效（影响后续播放的歌曲）。
 
+> **重启后保留（#125）**：音质选择会持久化到 `data/config.json`（每个平台各自记录），重启机器人后自动恢复，无需每次手动重设。
+
+### 重启后保留的播放设置
+
+以下运行时设置在改动时自动落盘，重启机器人后自动恢复，不再回到默认值：
+
+| 设置 | 作用范围 | 存储位置 |
+|------|----------|----------|
+| **播放音量**（`!vol` / WebUI 音量条 / REST `/volume`） | 每个机器人独立 | 数据库 `bot_instances.volume` |
+| **播放模式**（`!mode` / WebUI / REST `/mode`：顺序 / 列表循环 / 随机 / 随机循环） | 每个机器人独立 | 数据库 `bot_instances.play_mode` |
+| **音质**（各平台，WebUI 设置页 / REST `/quality`） | 全局（各平台各自记录） | `data/config.json` 的 `audioQuality` |
+
+聊天命令、WebUI、REST API 三种入口的改动都会被持久化。播放队列、当前歌曲、进度、`!fm` / `!artist` 等临时播放状态仍为一次性状态，重启后不保留（`!fm` / `!artist` 内部临时切换的随机 / 循环也**不会**覆盖你用 `!mode` 显式保存的偏好）。
+
 ## 项目架构
 
 ```
@@ -424,6 +456,7 @@ teamspeak-music-bot/
 │   │   └── database.ts         # SQLite 数据库（播放历史、实例、收藏、权限持久化）
 │   ├── music/                  # 音源服务
 │   │   ├── provider.ts         # 统一 MusicProvider 接口
+│   │   ├── jellyfin.ts         # Jellyfin 适配器（可选音源，直连 REST API）
 │   │   ├── netease.ts          # 网易云音乐适配器
 │   │   ├── qq.ts               # QQ 音乐适配器
 │   │   ├── bilibili.ts         # 哔哩哔哩适配器（视频音频提取）
@@ -477,6 +510,7 @@ teamspeak-music-bot/
 | **数据库** | better-sqlite3 (SQLite) |
 | **音频处理** | FFmpeg (ffmpeg-static 内置), @discordjs/opus |
 | **TS 协议** | @honeybbq/teamspeak-client（完整客户端协议）+ 自研 TS6 协议适配层 |
+| **Jellyfin** | Jellyfin REST API（可选音源，直连，无额外 npm 依赖） |
 | **网易云 API** | NeteaseCloudMusicApi |
 | **QQ 音乐 API** | @sansenjian/qq-music-api（锁定 `~2.4.0`，需 Node ≥ 20.17） |
 | **哔哩哔哩** | BiliBili Web API（搜索、DASH 音频流、QR 登录） |
@@ -486,17 +520,17 @@ teamspeak-music-bot/
 | **图标** | @iconify/vue |
 | **日志** | pino |
 
-## Jellyfin 音源（主音源）
+## 可选：Jellyfin 音源
 
-本 fork 把自建 [Jellyfin](https://jellyfin.org/) 媒体服务器作为**默认且主要的音源**：机器人直接播放你自己音乐库里的文件，不依赖任何在线平台的可用性 / 版权 / 登录状态。
+本项目可将自建 [Jellyfin](https://jellyfin.org/) 媒体服务器作为**额外音源**：机器人直接播放你自己音乐库里的文件，不依赖任何在线平台的可用性 / 版权 / 登录状态。该音源**默认关闭**，需要手动启用。
 
-### 连接配置
+### 启用与连接配置
 
 三种方式任选：
 
-1. **首次安装向导** — 第 3 步即 Jellyfin 连接卡（可跳过，稍后配置）。
+1. **首次安装向导** — 第 3 步即 Jellyfin 连接卡（可跳过，稍后配置）；填写并「保存并继续」会**自动启用**该音源。
-2. **WebUI** — 设置 → Jellyfin 音乐库：填写服务器地址、选择认证方式、「测试连接」验证后保存，**保存即时生效，无需重启**。
+2. **WebUI** — 设置 → Jellyfin 音乐库（可选）：打开「**启用 Jellyfin 音源**」开关，填写服务器地址、选择认证方式、「测试连接」验证后保存，**保存即时生效，无需重启**。
-3. **config.json** — 手动编辑 `jellyfin` 配置块后重启。
+3. **config.json** — 手动编辑 `jellyfin` 配置块，并把 `"jellyfin"` 加入 `enabledProviders`，然后重启。
 
 两种认证方式：
 
@@ -516,7 +550,7 @@ teamspeak-music-bot/
     "apiKey": "",               // apikey 模式填写
     "userId": ""                // apikey 模式填写
   },
-  "enabledProviders": ["jellyfin"]
+  "enabledProviders": ["netease", "qq", "bilibili", "youtube", "kugou", "jellyfin"]
 }
 ```
 
@@ -527,20 +561,22 @@ teamspeak-music-bot/
 - **搜索** — 歌曲 / 专辑 / 歌单，支持翻页「加载更多」；WebUI 统一搜索中 Jellyfin 结果排最前
 - **播放** — 懒解析播放地址；默认**原始直传**（不经 Jellyfin 转码），也可选 320/192/128kbps 服务器转码档（设置 → 音质设置）
 - **歌词** — 读取 Jellyfin 的歌词接口（内嵌或 .lrc），时间轴同步滚动，`!lyrics` 可用
-- **电台 / FM**（`!fm` 或首页「Jellyfin 电台」卡片）— 随机取一首**收藏**做种子生成 Instant Mix 歌曲流；没有收藏则回退到最近播放、再回退随机曲目
+- **电台 / FM**（`!fm -j` 或首页「Jellyfin 电台」卡片）— 随机取一首**收藏**做种子生成 Instant Mix 歌曲流；没有收藏则回退到最近播放、再回退随机曲目
 - **首页区块** — 最近添加（专辑）/ 播放最多 / Jellyfin 收藏 / 我的歌单 / 流派（点流派芯片即播放该流派）
 - **播放上报** — 播放开始 / 进度（约 10s 一次）/ 停止会回报给 Jellyfin（`Sessions/Playing` 系列接口），你的 Jellyfin 播放统计（PlayCount、最近播放）保持准确；上报失败不影响播放
-- **聊天命令** — 默认音源即 Jellyfin：`!play <歌名>`、`!playlist <歌单名或GUID>`、`!album <专辑名或GUID>`、`!artist <歌手>`、`!fm` 开箱即用
+- **聊天命令** — 启用后用 `-j` 标志：`!play -j <歌名>`、`!fm -j`、`!artist -j <歌手>`；`!playlist` / `!album` / `!play id:` 可直接粘贴 Jellyfin GUID。若把在线音源全部停用、只保留 Jellyfin，不带标志的命令会自动以 Jellyfin 为默认音源
 
 ### enabledProviders：音源开关
 
-`config.json` 的 `enabledProviders` 数组决定哪些音源可用（默认 `["jellyfin"]`）：
+`config.json` 的 `enabledProviders` 数组决定哪些音源可用（默认 `["netease", "qq", "bilibili", "youtube", "kugou"]`，即在线音源全开、Jellyfin 关闭）：
 
 - 可选值：`jellyfin`、`netease`、`qq`、`bilibili`、`youtube`、`kugou`（`local` 由 `localAudioEnabled` 控制，`spotify` 由 `spotify.enabled` 控制）
 - 未列出的音源：聊天命令返回「音源未启用」、REST 返回 400、WebUI 搜索栏 / 登录卡 / FM 卡片自动隐藏
+- 不带平台标志的命令默认走**固定优先级中第一个已启用的音源**：网易云 → QQ → 酷狗 → Jellyfin → B站 → YouTube（默认配置下即网易云）
+- **自定义默认音源（`defaultPlatform`）** — 想让不带标志的 `!play 歌名` 直接用某个音源（例如常听哔哩哔哩，免去每次加 `-b`），可在 设置 → 默认音源 里选择，或在 `config.json` 中设置 `"defaultPlatform": "bilibili"`。取值须是 `enabledProviders` 里已启用的音源，否则被忽略（回退到上面的固定优先级）；留空 / `null` / 删除该字段即恢复固定优先级。WebUI 保存后即时生效，无需重启
 - 网易云 / QQ 停用时，其内嵌 API 服务（端口 3001 / 3200）**不会启动**
-- 示例（Jellyfin 为主 + 保留网易云备用）：`"enabledProviders": ["jellyfin", "netease"]`
+- 示例（Jellyfin 为主、只留网易云备用）：`"enabledProviders": ["jellyfin", "netease"]`（默认音源仍为网易云，点歌用 `-j`、停用网易云，或直接把 `defaultPlatform` 设为 `"jellyfin"`）；示例（纯 Jellyfin）：`"enabledProviders": ["jellyfin"]`
-- 注意：重新启用网易云 / QQ 的内嵌 API 服务需要重启机器人；其余音源改动即时生效
+- 注意：重新启用网易云 / QQ 的内嵌 API 服务需要重启机器人；其余音源改动即时生效（WebUI 的 Jellyfin 开关即改此列表）
 
 ## 可选：YouTube 音源
 
@@ -774,10 +810,13 @@ A：使用 `!move <频道名>` 命令，或在设置页面创建机器人时指
 A：可以。在设置页面创建多个实例，分别连接不同的 TS 服务器或频道。
 
 **Q：端口 3200 被占用？**
-A：QQ 音乐 API 启动时自动监听 3200 端口。如果之前的进程还在运行，程序会自动复用。如需重启可手动结束 `node` 进程。
+A：QQ 音乐 API 启动时会监听 `config.json` 里的 `qqMusicApiPort`（默认 **3200**），客户端也用同一个端口发请求，二者始终一致。如果之前的进程还在运行，程序会自动复用。如需改端口，改 `qqMusicApiPort` 后重启即可；如需重启可手动结束 `node` 进程。
+
+**Q：日志里 `baseURL` 是 3200，但 QQ API 实际监听在 3300？（二维码不弹）**
+A：这是**旧版本**（或过期的 `latest` Docker 镜像）才有的问题：早期实现用的上游包默认端口是 3300，而客户端 `baseURL` 已经是 3200，两边对不上，取二维码时就 `ECONNREFUSED 127.0.0.1:3200`。当前版本已把内嵌 QQ 音乐 API **强制绑定到 `qqMusicApiPort`（默认 3200）**，并在启动前把上游包读取的 `PORT` 环境变量对齐到该端口，二者不可能再错位。修复方法：**拉取最新镜像并重启**（`docker compose pull && docker compose up -d`），或用 `npm ci && npm run build` 更新到最新代码。启动后可在日志里确认那行 `QQ Music API started`，其 `port` 字段就是实际监听端口。
 
 **Q：QQ 音乐二维码不弹 / 扫码登录失败 / cookie 无法使用？**
-A：通常是内置的 QQ 音乐 API 服务没起来——它一旦没监听 3200 端口，机器人去取二维码就会拿到 `ECONNREFUSED 127.0.0.1:3200`，于是二维码不显示，登录和 cookie 也全失效。先看日志里 QQ API 的启动报错：
+A：通常是内置的 QQ 音乐 API 服务没起来——它一旦没监听 `qqMusicApiPort`（默认 3200）端口，机器人去取二维码就会拿到 `ECONNREFUSED 127.0.0.1:3200`，于是二维码不显示，登录和 cookie 也全失效。先看日志里 QQ API 的启动报错：
 - 报 `ERR_REQUIRE_ESM`：装到了不兼容的 `@sansenjian/qq-music-api` 版本。本项目把它锁在 **`~2.4.0`**（需要 **Node ≥ 20.17 / 22.9**）；务必用 `npm ci` 或 `npm install` 让版本与锁文件一致，**不要**手动 `npm update` 把它升级或降级到不兼容的中间版本（2.3.0/2.3.1 是纯 ESM、会触发此错）。
 - 报 Node 版本不满足：升级 Node 到 ≥ 20.17，或将该依赖降到 `~2.2.10`（无此 Node 要求）后重装。
 修好版本后重新 `npm install && npm run build` 并重启即可。
@@ -837,7 +876,26 @@ A：本项目内置 `/login` 限流（每 IP 每分钟 5 次），但生产部
 
 > 完整历史请查看 [git log](https://github.com/ZHANGTIANYAO1/teamspeak-music-bot/commits/main) 或 [Releases](https://github.com/ZHANGTIANYAO1/teamspeak-music-bot/releases)。这里只列出重要变更和面向用户的破坏性改动。
 
-### 最新版本
+### 最新版本 — 保存/加载播放清单 + 重启恢复队列
+
+**保存/加载播放清单 + 队列持久化（[#119](https://github.com/ZHANGTIANYAO1/teamspeak-music-bot/issues/119)）——三项开关均默认关闭，升级无行为变化**
+
+- **保存/加载播放清单（`savedQueuesEnabled`，默认关闭，管理员开关）**：开启后，可在网页「已存队列」页或聊天命令保存当前队列为清单、随时**替换**加载或**追加**到队列末尾。网页保存可选「共享」（否则私有到当前用户）；聊天命令始终进入共享清单。新增聊天命令 `!save <名称>` / `!load [-a] <名称>` / `!queues`（未启用时回复「此功能未启用」）。上限：每个所有者 ≤ 50 份清单，每份 ≤ 1000 首。
+- **重启后自动恢复并继续播放队列**（同由 `savedQueuesEnabled` 门控）：机器人连接后会恢复上次的队列并继续播放。**说明**：只能从当前曲目的**开头**恢复（不记忆播放进度，链接重新解析）；**Spotify 恢复为尽力而为**（依赖 sidecar 重新可用），其他音源可靠。
+- **单曲直接播放不清空队列（`playKeepsQueue`，默认关闭，独立开关）**：开启后，直接播放单曲会插入到当前歌曲之后并立即播放、播完继续原队列，而不是清空整个队列。仅影响单曲的「直接播放」；歌单 / 专辑 / 电台仍会替换队列。
+- 三项均在 设置 → 行为设置 中开关，保存即时生效，无需重启。
+
+### Jellyfin 可选音源
+
+**Jellyfin 集成（[PR #123](https://github.com/ZHANGTIANYAO1/teamspeak-music-bot/pull/123)，由 [@ItsEricRao](https://github.com/ItsEricRao) 贡献；随后调整为可选音源）**
+
+- **Jellyfin 音源（可选，默认关闭）**：连接自建 [Jellyfin](https://jellyfin.org/) 服务器作为额外音源——搜索（歌曲 / 专辑 / 歌单，支持翻页）、懒解析直传播放、同步歌词、收藏 Instant Mix 电台（`!fm -j`）、首页「最近添加 / 播放最多 / 收藏 / 流派」区块、播放进度回报（PlayCount / 播放状态）。账号密码或 API Key 两种认证，在 设置 → Jellyfin 音乐库 打开「启用 Jellyfin 音源」即可，保存即时生效。详见 [可选：Jellyfin 音源](#可选jellyfin-音源)。
+- **enabledProviders 音源开关**：`config.json` 新增 `enabledProviders` 字段，默认 `["netease", "qq", "bilibili", "youtube", "kugou"]`——在线音源保持默认启用，**从旧版本升级无行为变化**；列表外的音源在聊天命令 / REST / WebUI 中一律不可用，网易云 / QQ 停用时其内嵌 API 服务（端口 3001 / 3200）不再启动。
+- **新增 `-j`（Jellyfin）与 `-n`（网易云）平台标志**；不带标志的 `!play` / `!search` / `!fm` 等走固定优先级中第一个已启用的音源（默认配置下即网易云，行为与旧版一致）。
+- ⚠️ **v1.10.0 初版曾短暂把默认音源设为 Jellyfin-only，现已回退**。若你在该版本保存过设置导致 `config.json` 中为 `"enabledProviders": ["jellyfin"]`，请手动把在线音源加回（详见 [更新升级](#关于-enabledproviders-音源开关v1100-起)）。
+- **QQ 按 ID 播放空歌名修复**（[PR #124](https://github.com/ZHANGTIANYAO1/teamspeak-music-bot/pull/124)，感谢 [@Slldyd2077](https://github.com/Slldyd2077)）：按 ID 播放 QQ 歌曲时回填歌曲元数据，TS 端不再显示空歌名。
+
+### v1.9.0 及更早
 
 **功能增强：Spotify 音源（实验性）/ 搜索结果翻页 / 细粒度权限 / 本地收藏 / 本地音频上传 / 专属链接 / 自动暂停 / QQ 雷达 FM**
 
@@ -867,6 +925,7 @@ A：本项目内置 `/login` 限流（每 IP 每分钟 5 次），但生产部
 - **会话存储**：服务端 SQLite 表 `sessions`，存储 sha256(token)；浏览器只持有原始 token cookie。7 天 TTL，每小时滚动续期。同账号最多 10 个并发会话（超出剔除最旧）。
 - **登录限流**：每 IP 每分钟 5 次 `/login` + 3 次 `/setup`，命中返回 429 + `Retry-After`。
 - **CSRF & 安全头**：所有 mutating 请求强制 `Origin`/`Referer` 同源；响应携带 `X-Frame-Options: DENY` 和 `Content-Security-Policy: frame-ancestors 'none'`（防点击劫持）。
+- **搜索引擎隐身（防止实例被收录，issue #128）**：为避免部署实例的 WebUI 被搜索引擎收录、被陌生人搜到控制页，采用纵深防御——所有响应携带 `X-Robots-Tag: noindex, nofollow`，`/robots.txt` 返回 `User-agent: * / Disallow: /`，`index.html` 内置 `<meta name="robots" content="noindex, nofollow">`（专属链接 `/bot/<id>` 等所有页面同样覆盖）。这些只阻止「被索引」，不是访问控制——**请不要把自己的 WebUI 链接发到公开网页 / 论坛 / 聊天群**，真正的防护来自登录鉴权与反向代理。
 - **配置变更**：反向代理部署务必 `"trustProxy": true`（详见 [反向代理部署注意事项](#反向代理部署注意事项)）。`config.adminGroups` 现已启用，用于限制管理类聊天命令只能由指定 TeamSpeak 服务器组运行（为空 = 不限制，详见 [TeamSpeak 命令权限](#teamspeak-命令权限管理类命令限制)）；`config.adminPassword` 仍为旧版预留字段，保留以兼容旧 `config.json`，当前未使用。
 
 ### v0.x — Bot Profile 自动更新与协议层升级
@@ -948,8 +1007,8 @@ A：本项目内置 `/login` 限流（每 IP 每分钟 5 次），但生产部
 
 | 项目 | 说明 |
 |------|------|
-| [ZHANGTIANYAO1/teamspeak-music-bot](https://github.com/ZHANGTIANYAO1/teamspeak-music-bot) | **本项目的上游**（MIT 许可）——完整的机器人框架、在线音源与 WebUI 均来自该项目，本 fork 在其之上加入 Jellyfin 主音源 |
+| [Jellyfin](https://github.com/jellyfin/jellyfin) | 自由软件媒体服务器（本项目的可选自建音源） |
-| [Jellyfin](https://github.com/jellyfin/jellyfin) | 自由软件媒体服务器（本 fork 的主音源） |
+| [ItsEricRao](https://github.com/ItsEricRao) | Jellyfin 音源集成贡献者（[PR #123](https://github.com/ZHANGTIANYAO1/teamspeak-music-bot/pull/123)） |
 | [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) | 提供插件开发参考 |
@@ -967,5 +1026,3 @@ A：本项目内置 `/login` 限流（每 IP 每分钟 5 次），但生产部
 ## 开源许可
 
 [MIT](LICENSE)
-
-本项目 fork 自 [ZHANGTIANYAO1/teamspeak-music-bot](https://github.com/ZHANGTIANYAO1/teamspeak-music-bot)，上游同样以 MIT 许可发布，版权归其原作者所有；本 fork 的修改部分亦以 MIT 许可发布。

docs/superpowers/specs/2026-07-06-save-load-playlist-design.md

@@ -0,0 +1,227 @@
+# Save/Load Playlists + Queue Persistence — Design
+
+**Issue:** [#119](https://github.com/ZHANGTIANYAO1/teamspeak-music-bot/issues/119) — 加入保存和加载播放清单功能
+**Date:** 2026-07-06
+**Status:** Approved (design), pending implementation plan
+
+## Problem
+
+The play queue lives only in memory (`PlayQueue` inside each `BotInstance`). It is lost in two situations the user calls out:
+
+1. **On restart** — the process stops, the in-memory queue is gone.
+2. **On "直接播放"** — `!play <song>` (and the WebUI "play now" path) call `queue.clear()`, wiping the queue to play one song.
+
+The user wants to stop losing the queue. Two related-but-separate capabilities were agreed:
+
+- **Named save/load** of queues (manual), plus **auto-restore** of the live queue across restarts.
+- An **independent** option to make single-song immediate-play *not* clear the queue.
+
+Everything ships **behind admin/independent toggles that default OFF**, so existing behavior is unchanged until an operator opts in.
+
+## Scope & agreed decisions
+
+| Decision | Choice |
+| --- | --- |
+| Core behavior | **Both** — named save/load **and** auto-restore live queue across restart |
+| Saved-queue ownership | **Per-user** (like `favorite_playlists`), plus a reserved `__shared__` owner for chat + opt-in sharing |
+| Trigger surface | **Web + chat** commands |
+| Auto-restore on restart | **Restore and resume playing** (gated by `savedQueuesEnabled`) |
+| Load semantics | **Replace (default) + append option** (`-a` flag / WebUI Append button) |
+| Feature gate | `savedQueuesEnabled` — **default false, admin-controlled** |
+| Single-play clear | Independent `playKeepsQueue` toggle — **default false** |
+
+### Out of scope (YAGNI)
+
+- Renaming a saved queue (delete + re-save instead).
+- Mid-track resume on restart (resume from the current track's **start**; URLs are re-resolved).
+- Normalized per-song storage (songs stored as a JSON blob).
+- Sharing granularity beyond "private to me" vs "shared" (one boolean).
+
+## Storage approach
+
+A saved queue is an ordered list of songs that is only ever saved and loaded **whole** — never queried song-by-song. So songs are stored as a **JSON `TEXT` blob**, not a normalized child table. Each stored song is a `QueuedSong` **without `url`** (URLs are resolved lazily at play time, exactly as today). This mirrors how `QueuedSong` already flows and keeps the schema to a single row per saved queue.
+
+---
+
+## Feature 1 — Named save/load (`savedQueuesEnabled`)
+
+### Data model
+
+New table:
+
+```sql
+CREATE TABLE IF NOT EXISTS saved_queues (
+  id        INTEGER PRIMARY KEY AUTOINCREMENT,
+  ownerId   TEXT NOT NULL,          -- WebUI user id, or the reserved SHARED owner
+  name      TEXT NOT NULL,
+  songs     TEXT NOT NULL,          -- JSON array of stored songs (QueuedSong minus url)
+  songCount INTEGER NOT NULL DEFAULT 0,
+  createdAt TEXT NOT NULL DEFAULT (datetime('now')),
+  updatedAt TEXT NOT NULL DEFAULT (datetime('now')),
+  UNIQUE(ownerId, name)
+);
+CREATE INDEX IF NOT EXISTS idx_saved_queues_ownerId ON saved_queues(ownerId);
+```
+
+- **`ownerId`** is either a real user id **or** a reserved constant `SHARED_QUEUE_OWNER = "__shared__"` (a value that can never collide with a real user id).
+- **Ownership rule (reconciles per-user with chat):**
+  - **WebUI save** has a **"共享 (shared)" checkbox.** Off → `ownerId = req.user.id` (private to you). On → `ownerId = SHARED_QUEUE_OWNER`.
+  - **Chat `!save`** always writes `ownerId = SHARED_QUEUE_OWNER` (TeamSpeak users have no WebUI account).
+  - **WebUI list** shows **your own + shared** (labeled). **Chat `!queues`/`!load`** see **shared only**.
+- **Overwrite:** `UNIQUE(ownerId, name)` → save is an **upsert** (same owner+name replaces `songs`, `songCount`, `updatedAt`).
+- **Caps** (reject with a clear message): ≤ **50** saved queues per owner; ≤ **1000** songs per saved queue.
+
+### DB methods (added to `BotDatabase`)
+
+```ts
+saveQueue(ownerId: string, name: string, songs: StoredSong[]): SavedQueue;   // upsert
+listSavedQueues(ownerId: string, includeShared: boolean): SavedQueueMeta[];  // meta only (no songs blob)
+getSavedQueue(id: number): SavedQueue | null;                                // full, with songs
+deleteSavedQueue(id: number): boolean;
+```
+
+- `StoredSong` = `Omit<QueuedSong, "url">`.
+- `SavedQueueMeta` = row without the `songs` blob (id, ownerId, name, songCount, timestamps) — keeps list responses light.
+- JSON (de)serialize at the DB boundary; parse failures on a corrupt blob degrade to an empty song list (never throw into a route).
+
+### Web API — `src/web/api/saved-queues.ts`
+
+All routes require auth + `player.queue` capability, and **404/403 when `savedQueuesEnabled` is false** (feature inert).
+
+| Method / path | Behavior |
+| --- | --- |
+| `GET /api/saved-queues` | list current user's own + shared (meta only) |
+| `POST /api/saved-queues` | body `{ botId, name, shared? }` → snapshot that bot's **current queue** songs, upsert |
+| `POST /api/saved-queues/:id/load` | body `{ botId, mode: "replace"\|"append" }` → load into that bot |
+| `DELETE /api/saved-queues/:id` | delete (only own or shared; not another user's private) |
+
+Ownership check on load/delete: allow if `ownerId === req.user.id` or `ownerId === SHARED_QUEUE_OWNER`; else 404 (no existence leak, matching the favorites pattern).
+
+### Chat commands (new, in `BotInstance.executeCommand`)
+
+- `!save <名称>` — save current queue → shared bucket.
+- `!load <名称>` — replace queue with a saved (shared) queue and play.
+- `!load -a <名称>` — append a saved (shared) queue to the end.
+- `!queues` — list shared saved queues (names + counts).
+
+All four reply **"此功能未启用"** when `savedQueuesEnabled` is false. Added to help text and the command table.
+
+### Load semantics (shared by web + chat)
+
+- **replace** — `queue.clear()`, add all stored songs, `queue.play()` + `resolveAndPlay(first)` (same shape as `cmdPlaylist`). Exits FM mode.
+- **append** — add all stored songs to the end; if idle, start the first newly-added one; never interrupts a playing track.
+- Loaded songs are re-tagged with a `requestedBy` of the loader (WebUI username / `游客` / chat `invokerName`) so play-history attribution stays correct (integrates with #121).
+
+### WebUI
+
+A new **"已保存队列 / Saved Queues"** page (nav entry visible only when `savedQueuesEnabled`):
+
+- **Save current queue**: name input + **共享** checkbox → `POST`.
+- Per entry (reusing `SongCard`/list styles): **Load** (replace), **Append**, **Delete**, showing name / song count / shared badge / owner.
+- Store/composable follows the existing `favorites` pattern.
+
+---
+
+## Feature 2 — Auto-restore live queue across restart (`savedQueuesEnabled`)
+
+Gated by the **same** `savedQueuesEnabled` flag (part of the "saved queues" feature).
+
+### Data model
+
+One row per bot (the live snapshot, continuously overwritten):
+
+```sql
+CREATE TABLE IF NOT EXISTS queue_state (
+  botId        TEXT PRIMARY KEY,
+  songs        TEXT NOT NULL,       -- JSON array of StoredSong
+  currentIndex INTEGER NOT NULL,
+  mode         TEXT NOT NULL,       -- PlayMode value
+  isFmMode     INTEGER NOT NULL DEFAULT 0,
+  fmPlatform   TEXT NOT NULL DEFAULT '',
+  updatedAt    TEXT NOT NULL DEFAULT (datetime('now'))
+);
+```
+
+DB methods: `saveQueueState(state)` (upsert), `getQueueState(botId)`, `clearQueueState(botId)`.
+
+### Snapshot (write path)
+
+- Add `PlayQueue.snapshot(): QueueSnapshot` and `PlayQueue.restore(snapshot)`.
+  - `snapshot` captures `songs` (minus url), `currentIndex`, `mode`.
+  - `restore` rebuilds `songs`, `currentIndex`, `mode`, and resets the derived `playedIndices`/`history`/`forwardStack` to a clean, consistent state for the restored index.
+- `BotInstance` writes the snapshot **debounced (~1 s)** on `stateChange` (queue mutations, track changes, and mode changes already emit `stateChange`). FM mode + fm platform captured alongside.
+- When the queue becomes empty (`clear()` with nothing re-added), the row is cleared via `clearQueueState`.
+
+### Restore (read path — "resume and play")
+
+When a bot reaches **connected/ready** (the same lifecycle point `autoStart` uses):
+
+1. If `savedQueuesEnabled` and a `queue_state` row exists → `PlayQueue.restore(...)`, restore FM mode/provider.
+2. If there was a current track → `resolveAndPlay(current)` (re-resolves URL, plays **from the track's start**).
+
+**Honest caveats (documented in README + spec):**
+
+- Resumes the **current track from its start**, not the exact millisecond (URLs are re-resolved; no persisted elapsed/seek).
+- **Spotify** auto-resume is **best-effort** — it depends on the sidecar/controller being back up; non-Spotify sources are reliable.
+- Resume only happens for bots that reach the connected state (auto-started, or on next manual start).
+
+---
+
+## Feature 3 — `playKeepsQueue` (independent single-play toggle)
+
+**Independent** config flag, **not** gated by `savedQueuesEnabled`. Default false → today's behavior.
+
+Affects **single-song immediate play only**: chat `!play <song | #N | id:<id> | URL>` and the WebUI play-now / play-by-id path.
+
+| `playKeepsQueue` | `!play <song>` behavior |
+| --- | --- |
+| `false` (default) | `queue.clear()` → play only that song (today) |
+| `true` | `addNext(song)` (insert after current) → `playAt(insertedAt)` (jump & play now) → `resolveAndPlay`; queue **kept**; on track-end, `next()` continues the queue |
+
+- Reuses existing `PlayQueue.addNext` + `playAt` — **no new queue logic.**
+- **Not** applied to collection loads — `!playlist` / `!album` / `!artist` / `!fm` still replace the queue (loading a collection is meant to replace; the request is about 单曲/single songs).
+- **Empty queue** → equivalent to a normal play (nothing to preserve).
+- **FM mode** → `!play` still exits FM (manual takeover), but existing queued songs are preserved and continue after the single song (auto-refill stops because FM is off). Documented.
+
+---
+
+## Config
+
+Add to `BotConfig` (in `src/data/config.ts`), both **default false**, both sanitized on load exactly like `localAudioEnabled` / `autoPauseOnEmpty` (so a hand-edited / legacy / corrupt `config.json` can never silently enable them):
+
+```ts
+savedQueuesEnabled: boolean;  // default false — gates Features 1 & 2 (admin-controlled)
+playKeepsQueue: boolean;      // default false — independent (Feature 3)
+```
+
+- Set via **Settings → 行为设置** (the existing admin behavior-settings surface, written through `POST /api/bot/settings`).
+- When `savedQueuesEnabled` is false: chat save/load/queues reply "此功能未启用"; `/api/saved-queues/*` return 403/404; the WebUI page/nav is hidden; no snapshotting; no auto-restore.
+
+## Error handling & edge cases
+
+- Corrupt `songs` JSON blob → treated as empty list; never throws into a route or the restore path.
+- Save with a duplicate name → upsert (overwrite), not an error.
+- Load/delete of a non-owned private queue → 404.
+- Caps exceeded → 4xx with a clear message (web) / friendly reply (chat).
+- Snapshot writes are best-effort and debounced; a DB write failure logs and never interrupts playback.
+- Restore of a Spotify-containing queue → best-effort per source; failures skip to next (existing `resolveAndPlay` skip behavior).
+
+## Testing (TDD)
+
+- **DB:** `saveQueue` upsert + caps; `listSavedQueues` own vs shared; `getSavedQueue`/`deleteSavedQueue`; ownership; `queue_state` upsert/get/clear; JSON round-trip + corrupt-blob degradation.
+- **PlayQueue:** `snapshot`/`restore` round-trip (songs, index, mode; derived state consistent).
+- **BotInstance:** `!save`/`!load`/`!load -a`/`!queues`; feature-disabled replies; snapshot-on-stateChange (debounced); resume-on-ready; `playKeepsQueue` insert-and-jump vs clear; collections still replace; FM interaction.
+- **Web API:** auth + capability + feature-gate (403/404); save (own/shared); load replace/append; delete ownership; caps.
+- **Config:** defaults false; load sanitization (legacy/corrupt/non-boolean → false).
+- **Frontend:** Saved Queues page (save w/ shared toggle, load, append, delete, hidden when disabled); store/composable.
+- Then: full suite (`npx vitest run --no-file-parallelism`) + `npx tsc --noEmit` + `cd web && npm run build`.
+
+## Rollout / staging
+
+Implement in stages (each independently valuable, all default-off):
+
+1. **Config + gates** — `savedQueuesEnabled`, `playKeepsQueue`, sanitization, Settings UI.
+2. **Feature 3** — `playKeepsQueue` single-play behavior (small, self-contained).
+3. **Feature 1** — named save/load (DB → API → chat → WebUI page).
+4. **Feature 2** — live-queue snapshot + resume-on-restart.
+5. **Docs** — README (commands, toggles, caveats).

src/audio/queue.test.ts

@@ -564,4 +564,45 @@ describe("PlayQueue", () => {
       }
     });
   });
+
+  describe("snapshot / restore (#119)", () => {
+    it("round-trips songs, index, and mode; strips url", () => {
+      const q = new PlayQueue();
+      q.add(makeSong("A"));
+      q.add(makeSong("B"));
+      q.setMode(PlayMode.Loop);
+      q.play();
+      q.next(); // current = index 1
+      const snap = q.snapshot();
+      expect(snap.currentIndex).toBe(1);
+      expect(snap.mode).toBe(PlayMode.Loop);
+      expect((snap.songs[0] as QueuedSong).url).toBeUndefined();
+      expect(snap.songs.map((s) => s.id)).toEqual(["A", "B"]);
+
+      const q2 = new PlayQueue();
+      q2.restore(snap);
+      expect(q2.list().map((s) => s.id)).toEqual(["A", "B"]);
+      expect(q2.getCurrentIndex()).toBe(1);
+      expect(q2.getMode()).toBe(PlayMode.Loop);
+      expect(q2.current()?.id).toBe("B");
+    });
+
+    it("preserves requestedBy through a snapshot", () => {
+      const q = new PlayQueue();
+      q.add({ ...makeSong("A"), requestedBy: "alice" });
+      q.play();
+      const q2 = new PlayQueue();
+      q2.restore(q.snapshot());
+      expect(q2.current()?.requestedBy).toBe("alice");
+    });
+
+    it("degrades an out-of-range index to -1 (nothing current)", () => {
+      const q = new PlayQueue();
+      const { url: _url, ...noUrl } = makeSong("A");
+      q.restore({ songs: [noUrl], currentIndex: 5, mode: PlayMode.Sequential });
+      expect(q.getCurrentIndex()).toBe(-1);
+      expect(q.current()).toBeNull();
+      expect(q.list().map((s) => s.id)).toEqual(["A"]);
+    });
+  });
 });

src/audio/queue.ts

@@ -17,6 +17,18 @@ export interface QueuedSong {
   requestedBy?: string;
 }
 
+/**
+ * A persistable view of a queue: its songs (minus the lazily-resolved `url`),
+ * the current index, and the play mode. Used to snapshot/restore the live queue
+ * across restarts (issue #119). Derived state (playedIndices/history/forward
+ * stack) is intentionally NOT captured — restore() rebuilds it consistently.
+ */
+export interface QueueSnapshot {
+  songs: Omit<QueuedSong, "url">[];
+  currentIndex: number;
+  mode: PlayMode;
+}
+
 export class PlayQueue {
   private songs: QueuedSong[] = [];
   private currentIndex = -1;
@@ -273,4 +285,32 @@ export class PlayQueue {
   unplayedCount(): number {
     return this.songs.length - this.playedIndices.size;
   }
+
+  /**
+   * Capture the queue as a persistable snapshot (songs minus `url`, current
+   * index, mode). Songs keep their `requestedBy` so restored play-history
+   * attribution stays correct. See restore().
+   */
+  snapshot(): QueueSnapshot {
+    return {
+      songs: this.songs.map(({ url: _url, ...s }) => s),
+      currentIndex: this.currentIndex,
+      mode: this.mode,
+    };
+  }
+
+  /**
+   * Replace the queue contents from a snapshot. Rebuilds the derived
+   * playedIndices/history/forwardStack to a clean, consistent state for the
+   * restored index (an out-of-range index degrades to -1 = "nothing current").
+   */
+  restore(s: QueueSnapshot): void {
+    this.songs = s.songs.map((song) => ({ ...song }));
+    this.mode = s.mode;
+    this.currentIndex =
+      s.currentIndex >= 0 && s.currentIndex < this.songs.length ? s.currentIndex : -1;
+    this.playedIndices = new Set(this.currentIndex >= 0 ? [this.currentIndex] : []);
+    this.history = [];
+    this.forwardStack = [];
+  }
 }

src/bot/instance.test.ts

@@ -1,6 +1,9 @@
 import { describe, it, expect, vi } from "vitest";
 import { BotInstance, COMMAND_DENIED_MESSAGE, spotifyPortsForBotId } from "./instance.js";
 import type { BotInstanceOptions } from "./instance.js";
+import { PlayQueue, PlayMode } from "../audio/queue.js";
+import { createDatabase, SHARED_QUEUE_OWNER } from "../data/database.js";
+import { parseCommand } from "./commands.js";
 import type { TS3TextMessage } from "../ts-protocol/client.js";
 import type { SpotifyController } from "../music/spotify/controller.js";
 import type { SpotifyOAuth } from "../music/spotify/spotify-oauth.js";
@@ -832,6 +835,9 @@ describe("BotInstance — spotifyOAuth threading to the controller factory (C3.1
     const database = {
       getProfileConfig: () => ({}),
       getCustomAvatarPath: () => null,
+      getPlayerSettings: () => ({ volume: 75, playMode: "seq" }),
+      saveVolume: () => {},
+      savePlayMode: () => {},
     } as unknown as BotDatabase;
     const options: BotInstanceOptions = {
       id: "bot-oauth-test",
@@ -912,6 +918,136 @@ describe("spotifyPortsForBotId — per-bot go-librespot ports (Fix 3)", () => {
   });
 });
 
+// --- Persisting volume + play mode across restarts (#125) ------------------
+const cmdVol = (BotInstance.prototype as any).cmdVol as (this: unknown, cmd: any) => string;
+const cmdMode = (BotInstance.prototype as any).cmdMode as (this: unknown, cmd: any) => string;
+
+describe("BotInstance.cmdVol — persistence (#125)", () => {
+  function makeVolCtx() {
+    let stored = 75;
+    return {
+      id: "bot1",
+      player: {
+        setVolume: vi.fn((v: number) => { stored = v; }),
+        getVolume: vi.fn(() => stored),
+      },
+      database: { saveVolume: vi.fn() },
+      logger: { warn: vi.fn() },
+      emit: vi.fn(),
+      // The real private persist helper lives on the prototype; wire it so the
+      // test exercises the shipped persistence path end-to-end.
+      persistVolume: (BotInstance.prototype as any).persistVolume,
+    } as any;
+  }
+
+  it("saves the new volume via database.saveVolume (covers chat !vol AND the REST endpoint)", () => {
+    const ctx = makeVolCtx();
+    const res = cmdVol.call(ctx, { args: "40" });
+    expect(res).toBe("Volume set to 40%");
+    expect(ctx.player.setVolume).toHaveBeenCalledWith(40);
+    expect(ctx.database.saveVolume).toHaveBeenCalledWith("bot1", 40);
+    expect(ctx.emit).toHaveBeenCalledWith("stateChange");
+  });
+
+  it("does not persist an out-of-range volume", () => {
+    const ctx = makeVolCtx();
+    const res = cmdVol.call(ctx, { args: "999" });
+    expect(res).toBe("Usage: !vol <0-100>");
+    expect(ctx.player.setVolume).not.toHaveBeenCalled();
+    expect(ctx.database.saveVolume).not.toHaveBeenCalled();
+  });
+
+  it("swallows a database error so the volume change still succeeds", () => {
+    const ctx = makeVolCtx();
+    ctx.database.saveVolume = vi.fn(() => { throw new Error("disk full"); });
+    const res = cmdVol.call(ctx, { args: "50" });
+    expect(res).toBe("Volume set to 50%");
+    expect(ctx.player.setVolume).toHaveBeenCalledWith(50);
+    expect(ctx.logger.warn).toHaveBeenCalled();
+  });
+});
+
+describe("BotInstance.cmdMode — persistence (#125)", () => {
+  function makeModeCtx() {
+    let mode = "seq";
+    return {
+      id: "bot1",
+      queue: {
+        setMode: vi.fn((m: string) => { mode = m; }),
+        getMode: vi.fn(() => mode),
+      },
+      database: { savePlayMode: vi.fn() },
+      logger: { warn: vi.fn() },
+      emit: vi.fn(),
+      persistPlayMode: (BotInstance.prototype as any).persistPlayMode,
+    } as any;
+  }
+
+  it("saves the new play mode via database.savePlayMode", () => {
+    const ctx = makeModeCtx();
+    const res = cmdMode.call(ctx, { args: "rloop" });
+    expect(res).toBe("Play mode set to: rloop");
+    expect(ctx.queue.setMode).toHaveBeenCalledWith("rloop");
+    expect(ctx.database.savePlayMode).toHaveBeenCalledWith("bot1", "rloop");
+    expect(ctx.emit).toHaveBeenCalledWith("stateChange");
+  });
+
+  it("does not persist an unknown mode", () => {
+    const ctx = makeModeCtx();
+    const res = cmdMode.call(ctx, { args: "bogus" });
+    expect(res).toBe("Usage: !mode <seq|loop|random|rloop>");
+    expect(ctx.queue.setMode).not.toHaveBeenCalled();
+    expect(ctx.database.savePlayMode).not.toHaveBeenCalled();
+  });
+});
+
+describe("BotInstance — restores persisted player settings on construction (#125)", () => {
+  const provider = { platform: "netease" } as unknown as MusicProvider;
+  function makeOptions(id: string, database: BotDatabase): BotInstanceOptions {
+    const logger: any = { info() {}, warn() {}, error() {}, debug() {}, child() { return logger; } };
+    return {
+      id,
+      name: "RestoreBot",
+      tsOptions: { host: "localhost", port: 9987, queryPort: 10011, nickname: "RestoreBot" } as any,
+      neteaseProvider: provider,
+      qqProvider: provider,
+      bilibiliProvider: provider,
+      youtubeProvider: provider,
+      database,
+      config: { spotify: {} } as unknown as BotConfig,
+      logger,
+      avatarStore: { read: () => null } as unknown as AvatarStore,
+      spotifyControllerFactory: () => ({ on: () => {} } as unknown as SpotifyController),
+    };
+  }
+
+  it("applies the saved volume + play mode from the database", () => {
+    const db = createDatabase(":memory:");
+    db.saveBotInstance({
+      id: "bot-restore", name: "B", serverAddress: "x", serverPort: 9987, nickname: "n",
+      defaultChannel: "", channelId: "", channelPassword: "", autoStart: false,
+      serverProtocol: "", ts6ApiKey: "", serverPassword: "",
+    });
+    db.saveVolume("bot-restore", 33);
+    db.savePlayMode("bot-restore", "loop");
+
+    const bot = new BotInstance(makeOptions("bot-restore", db));
+    const status = bot.getStatus();
+    expect(status.volume).toBe(33);
+    expect(status.playMode).toBe("loop");
+    db.close();
+  });
+
+  it("falls back to defaults for a bot with no saved settings", () => {
+    const db = createDatabase(":memory:");
+    const bot = new BotInstance(makeOptions("brand-new", db));
+    const status = bot.getStatus();
+    expect(status.volume).toBe(75);
+    expect(status.playMode).toBe("seq");
+    db.close();
+  });
+});
+
 describe("BotInstance.handleTextMessage — response chunking (#116)", () => {
   it("splits a long command response into multiple sends, each under the byte cap", async () => {
     const ctx = makeGateCtx({ adminGroups: [] });
@@ -972,3 +1108,282 @@ describe("BotInstance.cmdLyrics — full lyrics (#116)", () => {
     expect(await cmdLyrics.call(ctx)).toBe("No lyrics available");
   });
 });
+
+// ─── Saved queues + live-queue persistence + playKeepsQueue (#119) ─────────
+// All exercise the ACTUAL shipped methods via their prototype, bound to a
+// minimal ctx — the same lightweight pattern as the cmd* tests above.
+const playSingleSong = BotInstance.prototype.playSingleSong as (
+  this: unknown,
+  song: unknown,
+  requesterName?: string,
+) => Promise<boolean>;
+const loadSavedQueue = BotInstance.prototype.loadSavedQueue as (
+  this: unknown,
+  songs: unknown[],
+  mode: "replace" | "append",
+  requesterName?: string,
+) => Promise<void>;
+const cmdSaveQueue = (BotInstance.prototype as any).cmdSaveQueue as (this: unknown, cmd: any) => string;
+const cmdLoadQueue = (BotInstance.prototype as any).cmdLoadQueue as (this: unknown, cmd: any) => Promise<string>;
+const cmdListQueues = (BotInstance.prototype as any).cmdListQueues as (this: unknown) => string;
+const persistQueueSnapshot = (BotInstance.prototype as any).persistQueueSnapshot as (this: unknown) => void;
+const scheduleQueueSnapshot = (BotInstance.prototype as any).scheduleQueueSnapshot as (this: unknown) => void;
+const restoreQueueFromSnapshot = (BotInstance.prototype as any).restoreQueueFromSnapshot as (this: unknown) => Promise<void>;
+
+const withRequester = (BotInstance.prototype as any).withRequester;
+const isSameSong = (BotInstance.prototype as any).isSameSong;
+const savedQueuesGuard = (BotInstance.prototype as any).savedQueuesGuard;
+
+function song119(id: string) {
+  return { id, name: id, artist: "", album: "", platform: "netease" as const, coverUrl: "", duration: 1 };
+}
+function makePlayer119() {
+  let state: "idle" | "playing" | "paused" = "idle";
+  return {
+    stop: vi.fn(() => { state = "idle"; }),
+    resetFailures: vi.fn(),
+    getState: vi.fn(() => state),
+    _play: () => { state = "playing"; },
+  };
+}
+
+describe("BotInstance.playSingleSong / playKeepsQueue (#119)", () => {
+  function makeCtx(playKeepsQueue: boolean) {
+    const queue = new PlayQueue();
+    return {
+      config: { playKeepsQueue },
+      queue,
+      player: makePlayer119(),
+      withRequester,
+      isSameSong,
+      disableFmMode: vi.fn(),
+      sweepLocalAudio: vi.fn(),
+      resolveAndPlay: vi.fn(async () => true),
+    } as any;
+  }
+
+  it("clears the queue when playKeepsQueue is false (default)", async () => {
+    const ctx = makeCtx(false);
+    ctx.queue.add(song119("a"));
+    ctx.queue.play();
+    const ok = await playSingleSong.call(ctx, song119("b"), "alice");
+    expect(ok).toBe(true);
+    expect(ctx.queue.list().map((s: any) => s.id)).toEqual(["b"]);
+    expect(ctx.queue.current()?.id).toBe("b");
+    expect(ctx.sweepLocalAudio).toHaveBeenCalled();
+  });
+
+  it("inserts-after-current and keeps the queue when playKeepsQueue is true", async () => {
+    const ctx = makeCtx(true);
+    ctx.queue.add(song119("a"));
+    ctx.queue.add(song119("c"));
+    ctx.queue.play(); // current = a (index 0)
+    await playSingleSong.call(ctx, song119("b"), "alice");
+    expect(ctx.queue.list().map((s: any) => s.id)).toEqual(["a", "b", "c"]);
+    expect(ctx.queue.current()?.id).toBe("b");
+    expect(ctx.queue.current()?.requestedBy).toBe("alice");
+    // Keep-queue mode must not sweep local uploads (nothing was released).
+    expect(ctx.sweepLocalAudio).not.toHaveBeenCalled();
+  });
+
+  it("falls back to clear-and-play when playKeepsQueue is true but the queue is empty", async () => {
+    const ctx = makeCtx(true);
+    await playSingleSong.call(ctx, song119("b"), "alice");
+    expect(ctx.queue.list().map((s: any) => s.id)).toEqual(["b"]);
+    expect(ctx.queue.current()?.id).toBe("b");
+  });
+});
+
+describe("BotInstance.loadSavedQueue (#119)", () => {
+  function makeCtx() {
+    const player = makePlayer119();
+    return {
+      queue: new PlayQueue(),
+      player,
+      withRequester,
+      disableFmMode: vi.fn(),
+      sweepLocalAudio: vi.fn(),
+      resolveAndPlay: vi.fn(async () => { player._play(); return true; }),
+      emit: vi.fn(),
+    } as any;
+  }
+
+  it("replace clears + plays from the first track", async () => {
+    const ctx = makeCtx();
+    ctx.queue.add(song119("old"));
+    ctx.queue.play();
+    await loadSavedQueue.call(ctx, [song119("a"), song119("b")], "replace", "bob");
+    expect(ctx.queue.list().map((s: any) => s.id)).toEqual(["a", "b"]);
+    expect(ctx.queue.current()?.id).toBe("a");
+    expect(ctx.queue.current()?.requestedBy).toBe("bob");
+    expect(ctx.disableFmMode).toHaveBeenCalled();
+    expect(ctx.resolveAndPlay).toHaveBeenCalled();
+    expect(ctx.emit).toHaveBeenCalledWith("stateChange");
+  });
+
+  it("append adds to the end and starts playing only when idle", async () => {
+    const ctx = makeCtx();
+    // Idle bot with an existing (not playing) queue entry.
+    ctx.queue.add(song119("x"));
+    await loadSavedQueue.call(ctx, [song119("a"), song119("b")], "append");
+    expect(ctx.queue.list().map((s: any) => s.id)).toEqual(["x", "a", "b"]);
+    // wasIdle → start the first appended song (index 1).
+    expect(ctx.queue.current()?.id).toBe("a");
+    expect(ctx.resolveAndPlay).toHaveBeenCalledTimes(1);
+  });
+
+  it("append does not interrupt a playing track", async () => {
+    const ctx = makeCtx();
+    ctx.player._play(); // player is 'playing'
+    ctx.queue.add(song119("x"));
+    ctx.queue.play(); // current = x
+    await loadSavedQueue.call(ctx, [song119("a")], "append");
+    expect(ctx.queue.list().map((s: any) => s.id)).toEqual(["x", "a"]);
+    expect(ctx.queue.current()?.id).toBe("x");
+    expect(ctx.resolveAndPlay).not.toHaveBeenCalled();
+  });
+});
+
+describe("BotInstance chat save/load/queues (#119)", () => {
+  function makeCtx(enabled: boolean, db = createDatabase(":memory:")) {
+    const queue = new PlayQueue();
+    return {
+      config: { savedQueuesEnabled: enabled, commandPrefix: "!" },
+      queue,
+      database: db,
+      savedQueuesGuard,
+      loadSavedQueue: vi.fn(async () => {}),
+    } as any;
+  }
+
+  it("replies 此功能未启用 when the feature is disabled", () => {
+    const ctx = makeCtx(false);
+    expect(cmdSaveQueue.call(ctx, parseCommand("!save night", "!")!)).toBe("此功能未启用");
+    expect(cmdListQueues.call(ctx)).toBe("此功能未启用");
+  });
+
+  it("refuses saving an empty queue", () => {
+    const ctx = makeCtx(true);
+    expect(cmdSaveQueue.call(ctx, parseCommand("!save night", "!")!)).toBe("队列为空，无法保存");
+  });
+
+  it("saves the current queue to the shared bucket and lists it", () => {
+    const ctx = makeCtx(true);
+    ctx.queue.add(song119("a"));
+    ctx.queue.add(song119("b"));
+    const reply = cmdSaveQueue.call(ctx, parseCommand("!save night", "!")!);
+    expect(reply).toContain("已保存队列");
+    expect(ctx.database.listSavedQueues(SHARED_QUEUE_OWNER, false).map((x: any) => x.name)).toContain("night");
+    expect(cmdListQueues.call(ctx)).toContain("night");
+  });
+
+  it("loads a saved queue by name (replace by default, -a appends)", async () => {
+    const db = createDatabase(":memory:");
+    const ctx = makeCtx(true, db);
+    db.saveQueue(SHARED_QUEUE_OWNER, "night", [song119("a")]);
+    const rep = await cmdLoadQueue.call(ctx, parseCommand("!load night", "!")!);
+    expect(rep).toContain("已加载");
+    expect(ctx.loadSavedQueue).toHaveBeenCalledWith(expect.any(Array), "replace");
+
+    const repA = await cmdLoadQueue.call(ctx, parseCommand("!load -a night", "!")!);
+    expect(repA).toContain("已追加");
+    expect(ctx.loadSavedQueue).toHaveBeenLastCalledWith(expect.any(Array), "append");
+  });
+
+  it("reports a missing saved queue", async () => {
+    const ctx = makeCtx(true);
+    expect(await cmdLoadQueue.call(ctx, parseCommand("!load nope", "!")!)).toContain("找不到");
+  });
+});
+
+describe("BotInstance live-queue persistence (#119)", () => {
+  function makeCtx(enabled: boolean, db = createDatabase(":memory:")) {
+    return {
+      id: "bot1",
+      config: { savedQueuesEnabled: enabled },
+      queue: new PlayQueue(),
+      database: db,
+      isFmMode: false,
+      fmProvider: null,
+      logger: { info: vi.fn(), warn: vi.fn(), error: vi.fn(), debug: vi.fn() },
+      player: makePlayer119(),
+      resolveAndPlay: vi.fn(async () => true),
+      getProviderFor: vi.fn(() => ({ platform: "netease" })),
+    } as any;
+  }
+
+  it("persists a snapshot when enabled", () => {
+    const ctx = makeCtx(true);
+    ctx.queue.add(song119("a"));
+    ctx.queue.play();
+    persistQueueSnapshot.call(ctx);
+    const st = ctx.database.getQueueState("bot1")!;
+    expect(st.songs.map((s: any) => s.id)).toEqual(["a"]);
+    expect(st.currentIndex).toBe(0);
+  });
+
+  it("does NOT persist when the feature is disabled", () => {
+    const ctx = makeCtx(false);
+    ctx.queue.add(song119("a"));
+    ctx.queue.play();
+    persistQueueSnapshot.call(ctx);
+    expect(ctx.database.getQueueState("bot1")).toBeNull();
+  });
+
+  it("clears the persisted row when the queue is empty", () => {
+    const db = createDatabase(":memory:");
+    db.saveQueueState({ botId: "bot1", songs: [song119("a")], currentIndex: 0, mode: "seq", isFmMode: false, fmPlatform: "" });
+    const ctx = makeCtx(true, db);
+    persistQueueSnapshot.call(ctx); // queue is empty
+    expect(db.getQueueState("bot1")).toBeNull();
+  });
+
+  it("restores and resumes the current track on restore", async () => {
+    const db = createDatabase(":memory:");
+    db.saveQueueState({ botId: "bot1", songs: [song119("a"), song119("b")], currentIndex: 1, mode: "loop", isFmMode: false, fmPlatform: "" });
+    const ctx = makeCtx(true, db);
+    await restoreQueueFromSnapshot.call(ctx);
+    expect(ctx.queue.list().map((s: any) => s.id)).toEqual(["a", "b"]);
+    expect(ctx.queue.getCurrentIndex()).toBe(1);
+    expect(ctx.queue.getMode()).toBe(PlayMode.Loop);
+    expect(ctx.resolveAndPlay).toHaveBeenCalledTimes(1);
+  });
+
+  it("restores FM mode + provider from the snapshot", async () => {
+    const db = createDatabase(":memory:");
+    db.saveQueueState({ botId: "bot1", songs: [song119("a")], currentIndex: 0, mode: "random", isFmMode: true, fmPlatform: "qq" });
+    const ctx = makeCtx(true, db);
+    await restoreQueueFromSnapshot.call(ctx);
+    expect(ctx.isFmMode).toBe(true);
+    expect(ctx.getProviderFor).toHaveBeenCalledWith("qq");
+  });
+
+  it("does nothing when the feature is disabled", async () => {
+    const db = createDatabase(":memory:");
+    db.saveQueueState({ botId: "bot1", songs: [song119("a")], currentIndex: 0, mode: "seq", isFmMode: false, fmPlatform: "" });
+    const ctx = makeCtx(false, db);
+    await restoreQueueFromSnapshot.call(ctx);
+    expect(ctx.queue.list()).toEqual([]);
+    expect(ctx.resolveAndPlay).not.toHaveBeenCalled();
+  });
+
+  it("a cancelled snapshot timer does not wipe persisted state (disconnect race)", () => {
+    vi.useFakeTimers();
+    try {
+      const db = createDatabase(":memory:");
+      db.saveQueueState({ botId: "bot1", songs: [song119("a")], currentIndex: 0, mode: "seq", isFmMode: false, fmPlatform: "" });
+      const ctx = makeCtx(true, db);
+      ctx.queue.add(song119("a"));
+      ctx.queue.play();
+      // Debounced snapshot scheduled, then a disconnect clears the queue and
+      // cancels the pending timer — the persisted row must survive for restore.
+      scheduleQueueSnapshot.call(ctx);
+      ctx.queue.clear();
+      if (ctx.snapshotTimer) clearTimeout(ctx.snapshotTimer);
+      vi.advanceTimersByTime(3000);
+      expect(db.getQueueState("bot1")).not.toBeNull();
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+});

src/bot/instance.ts

@@ -15,7 +15,7 @@ import {
 import { parseSongRef, parseSelectionIndex } from "./song-ref.js";
 import { splitTextIntoChunks } from "./text-chunk.js";
 import type { Logger } from "../logger.js";
-import type { BotDatabase, ProfileConfig } from "../data/database.js";
+import { SHARED_QUEUE_OWNER, type BotDatabase, type ProfileConfig, type StoredSong } from "../data/database.js";
 import {
   isProviderEnabled,
   defaultPlatform,
@@ -39,6 +39,15 @@ import type { SpotifyOAuth } from "../music/spotify/spotify-oauth.js";
 /** Reply sent when a non-admin invokes an admin-only chat command. */
 export const COMMAND_DENIED_MESSAGE = "⛔ 需要管理员权限（该命令仅限管理员服务器组）";
 
+/** Maps the persisted / command-line play-mode string to the PlayMode enum.
+ *  Shared by the !mode command and the restart-restore path (#125). */
+const PLAY_MODE_BY_VALUE: Record<string, PlayMode> = {
+  seq: PlayMode.Sequential,
+  loop: PlayMode.Loop,
+  random: PlayMode.Random,
+  rloop: PlayMode.RandomLoop,
+};
+
 /** Fallback message when Spotify audio can't be served (backend unavailable
  *  OR a per-track playTrack failure against a dead/failed sidecar). */
 const SPOTIFY_UNAVAILABLE_MESSAGE =
@@ -166,6 +175,8 @@ export class BotInstance extends EventEmitter {
   /** Per-bot Jellyfin playback-report session (start / ~10s progress / stop).
    *  null when the wired provider has no reporting capability. */
   private jellyfinReporter: JellyfinPlaybackReporter | null = null;
+  /** Debounce handle for the live-queue snapshot writer (Feature 2, #119). */
+  private snapshotTimer: ReturnType<typeof setTimeout> | null = null;
 
   constructor(options: BotInstanceOptions) {
     super();
@@ -188,6 +199,19 @@ export class BotInstance extends EventEmitter {
     this.player = new AudioPlayer(this.logger);
     this.queue = new PlayQueue();
 
+    // Restore persisted per-bot player settings (#125): volume + play mode
+    // survive restarts. getPlayerSettings returns validated values (the in-memory
+    // defaults when the row/column is absent), so this is a harmless no-op for a
+    // brand-new bot and reproduces the saved state for an existing one.
+    try {
+      const settings = this.database.getPlayerSettings(this.id);
+      this.player.setVolume(settings.volume);
+      const restoredMode = PLAY_MODE_BY_VALUE[settings.playMode];
+      if (restoredMode) this.queue.setMode(restoredMode);
+    } catch (err) {
+      this.logger.warn({ err }, "Failed to restore player settings — using defaults");
+    }
+
     // Structural typing (like localProvider.sweepUnreferenced): only the real
     // JellyfinProvider exposes createPlaybackReporter, so the netease fallback
     // provider simply leaves reporting off.
@@ -246,6 +270,11 @@ export class BotInstance extends EventEmitter {
 
     this.setupPlayerEvents();
     this.setupTsEvents();
+
+    // Feature 2 (#119): persist a debounced snapshot of the live queue whenever
+    // it changes, so it can be restored + resumed after a restart. Inert unless
+    // config.savedQueuesEnabled is on (checked inside the scheduler).
+    this.on("stateChange", () => this.scheduleQueueSnapshot());
   }
 
   private setupPlayerEvents(): void {
@@ -329,6 +358,15 @@ export class BotInstance extends EventEmitter {
       // this.connected was never flipped to true. Previously this handler
       // short-circuited on !this.connected, leaving player stuck as "playing".
       this.connected = false;
+      // Cancel any pending live-queue snapshot BEFORE clearing the queue: a
+      // debounced snapshot firing after clear() would persist an empty queue
+      // (clearQueueState), wiping the state we want to restore on reconnect —
+      // and since a manual stop→start reuses the same botId, that would clobber
+      // the new instance's restored row (#119).
+      if (this.snapshotTimer) {
+        clearTimeout(this.snapshotTimer);
+        this.snapshotTimer = null;
+      }
       this.spotifyController.stop();
       this.currentSourceIsSpotify = false;
       this.player.stop();
@@ -412,10 +450,22 @@ export class BotInstance extends EventEmitter {
     this.connected = true;
     this.profileManager.onConnect();
     this.emit("connected");
+    // Feature 2 (#119): restore + resume the live queue persisted before the
+    // last shutdown. Best-effort and gated on savedQueuesEnabled; runs after
+    // the bot is fully connected so resolveAndPlay can actually push audio.
+    void this.restoreQueueFromSnapshot();
   }
 
   disconnect(): void {
     this._cancelIdleTimer();
+    // Cancel any pending live-queue snapshot before clearing so it can't fire
+    // afterwards and persist an empty queue over the state we keep for restore
+    // (#119). The disconnected handler cancels too, but do it here as well for
+    // the path where tsClient.disconnect() doesn't re-emit "disconnected".
+    if (this.snapshotTimer) {
+      clearTimeout(this.snapshotTimer);
+      this.snapshotTimer = null;
+    }
     this.spotifyController.stop();
     this.currentSourceIsSpotify = false;
     this.player.stop();
@@ -698,6 +748,12 @@ export class BotInstance extends EventEmitter {
         return this.cmdMove(cmd);
       case "follow":
         return this.cmdFollow(msg);
+      case "save":
+        return this.cmdSaveQueue(cmd);
+      case "load":
+        return this.cmdLoadQueue(cmd);
+      case "queues":
+        return this.cmdListQueues();
       case "help":
         return this.cmdHelp();
       default:
@@ -731,8 +787,8 @@ export class BotInstance extends EventEmitter {
   }
 
   /** Chat-command source flags. No flag → the configured default platform
-   *  (jellyfin unless disabled). Netease is no longer the implicit default,
+   *  (netease in the default config; otherwise the first enabled source by
-   *  so it gets an explicit -n flag. */
+   *  fixed priority — see defaultPlatform()). */
   private static readonly FLAG_PLATFORMS: ReadonlyArray<[string, Platform]> = [
     ["b", "bilibili"],
     ["q", "qq"],
@@ -991,24 +1047,93 @@ export class BotInstance extends EventEmitter {
     const { song, error } = await this.resolvePlayQuery(cmd);
     if (error) return error;
     const song0 = song!;
+    const ok = await this.playSingleSong(song0, requesterName);
+    if (!ok) return `Cannot play: ${song0.name}`;
+    return `Now playing: ${song0.name} - ${song0.artist}`;
+  }
+
+  /**
+   * Play a single resolved song immediately, honoring config.playKeepsQueue:
+   *  - false (default): clear the queue and play only this song — today's
+   *    behavior. The prior track is stopped and released local uploads swept.
+   *  - true (and the queue is non-empty): insert the song after the current
+   *    track and jump to it (reusing addNext + playAt — no new queue logic), so
+   *    the rest of the queue survives and continues after it. FM auto-refill is
+   *    stopped (manual takeover), but existing queued songs are preserved.
+   *
+   * Shared by chat !play and the web /play-song route so the toggle decision
+   * lives in exactly one place (#119). Returns true if a track started playing.
+   */
+  async playSingleSong(song: QueuedSong, requesterName?: string): Promise<boolean> {
+    const s = this.withRequester(song, requesterName);
+    if (this.config.playKeepsQueue && !this.queue.isEmpty()) {
+      const insertedAt =
+        this.queue.getCurrentIndex() < 0
+          ? this.queue.size()
+          : this.queue.getCurrentIndex() + 1;
+      this.player.stop();
+      this.disableFmMode();
+      this.queue.addNext(s);
+      this.queue.playAt(insertedAt);
+      this.player.resetFailures();
+      // No sweep here: the queue is kept, so no local uploads were released.
+      return this.resolveAndPlay(this.queue.current()!);
+    }
+    // Legacy replace behavior (default).
     const previous = this.queue.current();
-    if (previous && !this.isSameSong(previous, song0)) {
+    if (previous && !this.isSameSong(previous, s)) {
       this.player.stop();
     }
     this.queue.clear();
     this.disableFmMode();
-    this.queue.add(this.withRequester(song0, requesterName));
+    this.queue.add(s);
     this.queue.play();
 
     // Reset failure counter on user-initiated play
     this.player.resetFailures();
     const ok = await this.resolveAndPlay(this.queue.current()!);
     // Sweep AFTER the new song is queued+resolved: the replaced songs are no
-    // longer referenced (and get deleted), but song0 — if it is the same local
+    // longer referenced (and get deleted), but the song — if it is the same
-    // upload that was already playing — stays referenced and is preserved.
+    // local upload that was already playing — stays referenced and is preserved.
     this.sweepLocalAudio("replaced");
-    if (!ok) return `Cannot play: ${song0.name}`;
+    return ok;
-    return `Now playing: ${song0.name} - ${song0.artist}`;
+  }
+
+  /**
+   * Load a saved song list into this bot's queue (#119). `replace` clears +
+   * plays from the first track (exits FM, like a fresh collection load);
+   * `append` adds to the end and only starts playing if the bot was idle
+   * (never interrupts a playing track). Loaded songs are re-tagged with the
+   * loader's name so play-history attribution stays correct.
+   */
+  async loadSavedQueue(
+    songs: StoredSong[],
+    mode: "replace" | "append",
+    requesterName?: string,
+  ): Promise<void> {
+    const tagged = songs.map((s) =>
+      this.withRequester({ ...(s as QueuedSong) }, requesterName),
+    );
+    if (mode === "replace") {
+      this.player.stop();
+      this.queue.clear();
+      this.disableFmMode();
+      for (const s of tagged) this.queue.add(s);
+      this.sweepLocalAudio("queue_replaced");
+      const first = this.queue.play();
+      this.player.resetFailures();
+      if (first) await this.resolveAndPlay(first);
+    } else {
+      const wasIdle = this.player.getState() === "idle";
+      const startAt = this.queue.size();
+      for (const s of tagged) this.queue.add(s);
+      if (wasIdle && this.queue.size() > startAt) {
+        this.queue.playAt(startAt);
+        this.player.resetFailures();
+        await this.resolveAndPlay(this.queue.current()!);
+      }
+    }
+    this.emit("stateChange");
   }
 
   private async cmdAdd(cmd: ParsedCommand, requesterName?: string): Promise<string> {
@@ -1136,10 +1261,36 @@ export class BotInstance extends EventEmitter {
     const vol = parseInt(cmd.args, 10);
     if (isNaN(vol) || vol < 0 || vol > 100) return "Usage: !vol <0-100>";
     this.player.setVolume(vol);
+    // Persist so the volume survives a restart (#125). Both the chat !vol command
+    // and the WebUI/REST volume endpoint funnel through here, so one write covers
+    // every entry point. Only volume is written — play mode is saved independently.
+    this.persistVolume();
     this.emit("stateChange");
     return `Volume set to ${vol}%`;
   }
 
+  /** Persist the current volume (#125). Best-effort: a DB error must never break
+   *  the volume change itself. */
+  private persistVolume(): void {
+    try {
+      this.database.saveVolume(this.id, this.player.getVolume());
+    } catch (err) {
+      this.logger.warn({ err }, "Failed to persist volume");
+    }
+  }
+
+  /** Persist the current play mode (#125). Best-effort, mirrors persistVolume.
+   *  Called ONLY from the explicit !mode command — NOT from FM/artist mode, whose
+   *  Random/Loop switch is a transient side effect that must not overwrite the
+   *  user's saved preference. */
+  private persistPlayMode(): void {
+    try {
+      this.database.savePlayMode(this.id, this.queue.getMode());
+    } catch (err) {
+      this.logger.warn({ err }, "Failed to persist play mode");
+    }
+  }
+
   private cmdNow(): string {
     const song = this.queue.current();
     if (!song) return "Nothing is playing";
@@ -1205,15 +1356,12 @@ export class BotInstance extends EventEmitter {
   }
 
   private cmdMode(cmd: ParsedCommand): string {
-    const modeMap: Record<string, PlayMode> = {
+    const mode = PLAY_MODE_BY_VALUE[cmd.args];
-      seq: PlayMode.Sequential,
-      loop: PlayMode.Loop,
-      random: PlayMode.Random,
-      rloop: PlayMode.RandomLoop,
-    };
-    const mode = modeMap[cmd.args];
     if (mode === undefined) return "Usage: !mode <seq|loop|random|rloop>";
     this.queue.setMode(mode);
+    // Persist so the play mode survives a restart (#125). The chat !mode command
+    // and the WebUI/REST mode endpoint both funnel through here.
+    this.persistPlayMode();
     this.emit("stateChange");
     return `Play mode set to: ${cmd.args}`;
   }
@@ -1439,6 +1587,122 @@ export class BotInstance extends EventEmitter {
     return "Following you to your channel";
   }
 
+  // ─── Saved queues (chat side, #119) ──────────────────────────────────────
+  // TeamSpeak users have no WebUI account, so chat save/load always uses the
+  // reserved SHARED_QUEUE_OWNER bucket. All three commands are inert (reply
+  // "此功能未启用") unless the admin enabled savedQueuesEnabled.
+
+  private savedQueuesGuard(): string | null {
+    return this.config.savedQueuesEnabled ? null : "此功能未启用";
+  }
+
+  private cmdSaveQueue(cmd: ParsedCommand): string {
+    const off = this.savedQueuesGuard();
+    if (off) return off;
+    const name = cmd.args.trim();
+    if (!name) return `Usage: ${this.config.commandPrefix}save <名称>`;
+    const songs = this.queue.list();
+    if (songs.length === 0) return "队列为空，无法保存";
+    try {
+      const saved = this.database.saveQueue(SHARED_QUEUE_OWNER, name, songs);
+      return `已保存队列「${name}」（${saved.songCount} 首）`;
+    } catch (err) {
+      return `保存失败：${(err as Error).message}`;
+    }
+  }
+
+  private async cmdLoadQueue(cmd: ParsedCommand): Promise<string> {
+    const off = this.savedQueuesGuard();
+    if (off) return off;
+    const name = cmd.args.trim();
+    if (!name) return `Usage: ${this.config.commandPrefix}load [-a] <名称>`;
+    const meta = this.database
+      .listSavedQueues(SHARED_QUEUE_OWNER, false)
+      .find((q) => q.name === name);
+    const full = meta ? this.database.getSavedQueue(meta.id) : null;
+    if (!full) return `找不到已保存队列「${name}」`;
+    const mode = cmd.flags.has("a") ? "append" : "replace";
+    await this.loadSavedQueue(full.songs, mode);
+    return mode === "append"
+      ? `已追加「${name}」（${full.songs.length} 首）到队列`
+      : `已加载「${name}」（${full.songs.length} 首）`;
+  }
+
+  private cmdListQueues(): string {
+    const off = this.savedQueuesGuard();
+    if (off) return off;
+    const list = this.database.listSavedQueues(SHARED_QUEUE_OWNER, false);
+    if (list.length === 0) return "还没有已保存的队列";
+    return ["已保存队列：", ...list.map((q) => `• ${q.name}（${q.songCount} 首）`)].join("\n");
+  }
+
+  // ─── Live-queue persistence (Feature 2, #119) ────────────────────────────
+
+  /** Synchronous snapshot writer. Persists the live queue (or clears the row
+   *  when empty). Best-effort — a DB failure logs and never interrupts play. */
+  private persistQueueSnapshot(): void {
+    if (!this.config.savedQueuesEnabled) return;
+    try {
+      const snap = this.queue.snapshot();
+      if (snap.songs.length === 0) {
+        this.database.clearQueueState(this.id);
+        return;
+      }
+      this.database.saveQueueState({
+        botId: this.id,
+        songs: snap.songs,
+        currentIndex: snap.currentIndex,
+        mode: snap.mode,
+        isFmMode: this.isFmMode,
+        fmPlatform: this.isFmMode && this.fmProvider ? this.fmProvider.platform : "",
+      });
+    } catch (err) {
+      this.logger.warn({ err }, "queue snapshot persist failed");
+    }
+  }
+
+  /** Debounce the snapshot writer (~1s) off the stateChange firehose. */
+  private scheduleQueueSnapshot(): void {
+    if (!this.config.savedQueuesEnabled) return;
+    if (this.snapshotTimer) clearTimeout(this.snapshotTimer);
+    this.snapshotTimer = setTimeout(() => this.persistQueueSnapshot(), 1000);
+    // Don't keep the event loop alive just for a pending snapshot.
+    this.snapshotTimer.unref?.();
+  }
+
+  /** Restore + resume the live queue after (re)connect. Best-effort: resumes
+   *  the current track from its START (URLs are re-resolved; no persisted
+   *  elapsed). Spotify resume depends on the sidecar being available. */
+  private async restoreQueueFromSnapshot(): Promise<void> {
+    if (!this.config.savedQueuesEnabled) return;
+    let st;
+    try {
+      st = this.database.getQueueState(this.id);
+    } catch (err) {
+      this.logger.warn({ err }, "queue snapshot restore failed to read state");
+      return;
+    }
+    if (!st || st.songs.length === 0) return;
+    this.queue.restore({
+      songs: st.songs,
+      currentIndex: st.currentIndex,
+      mode: st.mode as PlayMode,
+    });
+    if (st.isFmMode && st.fmPlatform) {
+      this.isFmMode = true;
+      this.fmProvider = this.getProviderFor(st.fmPlatform as Platform);
+    }
+    const current = this.queue.current();
+    if (current) {
+      this.player.resetFailures();
+      await this.resolveAndPlay(current);
+    }
+    this.logger.info(
+      { count: st.songs.length, index: st.currentIndex },
+      "Restored live queue from snapshot",
+    );
+  }
+
   private cmdHelp(): string {
     const p = this.config.commandPrefix;
     const def = defaultPlatform(this.config);
@@ -1451,7 +1715,6 @@ export class BotInstance extends EventEmitter {
     return [
       "TSMusicBot Commands:",
       `${p}play <song>  — Search and play (default source: ${def})`,
-      `${p}play -j <song> — Search from Jellyfin`,
       ...(flagHelp ? [`  Source flags: ${flagHelp}`] : []),
       `${p}search <name> — List top matches to pick a specific (same-name) song`,
       `${p}play #N       — Play the Nth result of the last ${p}search`,
@@ -1467,8 +1730,15 @@ export class BotInstance extends EventEmitter {
       `${p}mode <seq|loop|random|rloop> — Play mode`,
       `${p}playlist <name or id> — Load playlist by name or ID`,
       `${p}album <name or id> — Load album`,
-      `${p}fm           — Personal FM (Jellyfin: 收藏电台 Instant Mix)`,
+      `${p}fm           — Personal FM (default source: ${def}; source flags work too)`,
       `${p}artist <name> — Play songs by artist (loop)`,
+      ...(this.config.savedQueuesEnabled
+        ? [
+            `${p}save <名称>  — Save current queue`,
+            `${p}load [-a] <名称> — Load a saved queue (-a appends)`,
+            `${p}queues       — List saved queues`,
+          ]
+        : []),
       `${p}vote         — Vote to skip`,
       `${p}lyrics       — Show lyrics`,
       `${p}now          — Current song info`,

src/data/config.test.ts

@@ -10,7 +10,7 @@ import {
   renameSync,
 } from "node:fs";
 import { tmpdir } from "node:os";
-import { getDefaultConfig, loadConfig, saveConfig, migrateLegacyConfig } from "./config.js";
+import { getDefaultConfig, loadConfig, saveConfig, migrateLegacyConfig, defaultPlatform } from "./config.js";
 
 // Wrap the fs functions config.ts uses in call-through spies so the atomic-write
 // and transient-read-error paths can be observed/forced. Everything else (mkdtemp,
@@ -48,6 +48,159 @@ describe("config", () => {
     expect(config).toEqual(getDefaultConfig());
   });
 
+  it("defaults to the online sources with jellyfin as opt-in (disabled)", () => {
+    const config = getDefaultConfig();
+    expect(config.enabledProviders).toEqual(["netease", "qq", "bilibili", "youtube", "kugou"]);
+    expect(config.enabledProviders).not.toContain("jellyfin");
+  });
+
+  it("keeps pre-gating behavior for legacy configs without enabledProviders", () => {
+    const dir = makeTmpDir();
+    const path = join(dir, "config.json");
+    // A config written before enabledProviders existed: no such field.
+    writeFileSync(path, JSON.stringify({ webPort: 4000 }));
+    const config = loadConfig(path);
+    expect(config.enabledProviders).toEqual(["netease", "qq", "bilibili", "youtube", "kugou"]);
+    expect(defaultPlatform(config)).toBe("netease");
+  });
+
+  it("defaultPlatform follows the fixed priority order", () => {
+    const config = getDefaultConfig();
+    expect(defaultPlatform(config)).toBe("netease");
+
+    // Jellyfin ranks after the online music platforms…
+    config.enabledProviders = ["netease", "jellyfin"];
+    expect(defaultPlatform(config)).toBe("netease");
+    // …but ahead of the video sites…
+    config.enabledProviders = ["bilibili", "jellyfin", "youtube"];
+    expect(defaultPlatform(config)).toBe("jellyfin");
+    // …and is the default when it is the only enabled source.
+    config.enabledProviders = ["jellyfin"];
+    expect(defaultPlatform(config)).toBe("jellyfin");
+    // Nothing enabled → netease fallback (the gate then reports it disabled).
+    config.enabledProviders = [];
+    expect(defaultPlatform(config)).toBe("netease");
+  });
+
+  // --- #126: an explicit operator default source ---
+
+  it("defaultPlatform is null by default (follow the priority order)", () => {
+    expect(getDefaultConfig().defaultPlatform).toBeNull();
+  });
+
+  it("defaultPlatform() honors an explicit, enabled preference over the priority order", () => {
+    const config = getDefaultConfig();
+    // Priority would pick netease; a Bilibili-loving server sets B站 instead (#126).
+    config.defaultPlatform = "bilibili";
+    expect(defaultPlatform(config)).toBe("bilibili");
+  });
+
+  it("defaultPlatform() ignores a preference whose source is not enabled", () => {
+    const config = getDefaultConfig();
+    config.defaultPlatform = "jellyfin"; // opt-in, not enabled in the default config
+    // Falls back to the fixed priority order (netease)…
+    expect(defaultPlatform(config)).toBe("netease");
+    // …until the preferred source is actually enabled.
+    config.enabledProviders = [...config.enabledProviders, "jellyfin"];
+    expect(defaultPlatform(config)).toBe("jellyfin");
+  });
+
+  it("loadConfig keeps a valid, enabled defaultPlatform", () => {
+    const dir = makeTmpDir();
+    const path = join(dir, "config.json");
+    writeFileSync(path, JSON.stringify({ defaultPlatform: "bilibili" }));
+    const config = loadConfig(path);
+    expect(config.defaultPlatform).toBe("bilibili");
+    expect(defaultPlatform(config)).toBe("bilibili");
+  });
+
+  it("loadConfig nulls a defaultPlatform that is unknown, disabled, or the wrong type", () => {
+    const dir = makeTmpDir();
+    // Unknown provider name.
+    const p1 = join(dir, "c1.json");
+    writeFileSync(p1, JSON.stringify({ defaultPlatform: "bogus" }));
+    expect(loadConfig(p1).defaultPlatform).toBeNull();
+    // Known provider, but not in enabledProviders.
+    const p2 = join(dir, "c2.json");
+    writeFileSync(p2, JSON.stringify({ enabledProviders: ["netease"], defaultPlatform: "bilibili" }));
+    expect(loadConfig(p2).defaultPlatform).toBeNull();
+    // Wrong type.
+    const p3 = join(dir, "c3.json");
+    writeFileSync(p3, JSON.stringify({ defaultPlatform: 42 }));
+    expect(loadConfig(p3).defaultPlatform).toBeNull();
+  });
+
+  it("round-trips defaultPlatform through save/load", () => {
+    const dir = makeTmpDir();
+    const path = join(dir, "config.json");
+    saveConfig(path, { ...getDefaultConfig(), defaultPlatform: "qq" });
+    expect(loadConfig(path).defaultPlatform).toBe("qq");
+  });
+
+  it("respects an explicit jellyfin-only enabledProviders from disk", () => {
+    const dir = makeTmpDir();
+    const path = join(dir, "config.json");
+    // e.g. a config persisted by the short-lived jellyfin-by-default builds.
+    writeFileSync(path, JSON.stringify({ enabledProviders: ["jellyfin"] }));
+    const config = loadConfig(path);
+    expect(config.enabledProviders).toEqual(["jellyfin"]);
+    expect(defaultPlatform(config)).toBe("jellyfin");
+  });
+
+  // ── audioQuality persistence (#125) ─────────────────────────────────────
+  it("defaults audioQuality to each provider's in-memory default", () => {
+    const config = getDefaultConfig();
+    expect(config.audioQuality).toEqual({
+      netease: "exhigh",
+      qq: "exhigh",
+      bilibili: "high",
+      kugou: "128",
+      jellyfin: "direct",
+    });
+  });
+
+  it("fills audioQuality defaults for a legacy config without the field", () => {
+    const dir = makeTmpDir();
+    const path = join(dir, "config.json");
+    writeFileSync(path, JSON.stringify({ webPort: 4000 }));
+    const config = loadConfig(path);
+    expect(config.audioQuality).toEqual(getDefaultConfig().audioQuality);
+  });
+
+  it("round-trips a saved audioQuality through save/load", () => {
+    const dir = makeTmpDir();
+    const path = join(dir, "config.json");
+    const config = getDefaultConfig();
+    config.audioQuality = {
+      netease: "lossless",
+      qq: "flac",
+      bilibili: "high",
+      kugou: "flac",
+      jellyfin: "320",
+    };
+    saveConfig(path, config);
+    const loaded = loadConfig(path);
+    expect(loaded.audioQuality).toEqual(config.audioQuality);
+  });
+
+  it("coerces missing / non-string audioQuality fields to defaults", () => {
+    const dir = makeTmpDir();
+    const path = join(dir, "config.json");
+    // netease valid, qq blank, bilibili wrong type, kugou missing, jellyfin valid.
+    writeFileSync(
+      path,
+      JSON.stringify({ audioQuality: { netease: "lossless", qq: "  ", bilibili: 320, jellyfin: "192" } }),
+    );
+    const config = loadConfig(path);
+    expect(config.audioQuality).toEqual({
+      netease: "lossless",
+      qq: "exhigh", // blank → default
+      bilibili: "high", // non-string → default
+      kugou: "128", // missing → default
+      jellyfin: "192",
+    });
+  });
+
   it("creates config file on save", () => {
     const dir = makeTmpDir();
     const path = join(dir, "sub", "config.json");
@@ -450,4 +603,28 @@ describe("loadConfig error handling", () => {
       expect(readFileSync(join(dir, backups[0]), "utf-8")).toBe(content);
     }
   });
+
+  it("defaults savedQueuesEnabled and playKeepsQueue to false", () => {
+    const c = getDefaultConfig();
+    expect(c.savedQueuesEnabled).toBe(false);
+    expect(c.playKeepsQueue).toBe(false);
+  });
+
+  it("coerces non-boolean savedQueues/playKeepsQueue values to false on load", () => {
+    const dir = makeTmpDir();
+    const path = join(dir, "config.json");
+    writeFileSync(path, JSON.stringify({ savedQueuesEnabled: "yes", playKeepsQueue: 1 }));
+    const c = loadConfig(path);
+    expect(c.savedQueuesEnabled).toBe(false);
+    expect(c.playKeepsQueue).toBe(false);
+  });
+
+  it("preserves savedQueues/playKeepsQueue true when explicitly enabled", () => {
+    const dir = makeTmpDir();
+    const path = join(dir, "config.json");
+    writeFileSync(path, JSON.stringify({ savedQueuesEnabled: true, playKeepsQueue: true }));
+    const c = loadConfig(path);
+    expect(c.savedQueuesEnabled).toBe(true);
+    expect(c.playKeepsQueue).toBe(true);
+  });
 });

src/data/config.ts

@@ -38,6 +38,22 @@ export interface JellyfinConfig {
   userId: string;
 }
 
+/**
+ * Per-provider audio quality (音质), persisted so a restart keeps the user's
+ * choice instead of resetting each provider to its in-memory default (#125).
+ * The values are the same strings the WebUI/REST `POST /api/music/quality`
+ * endpoint sends and each provider's setQuality() accepts; on startup they are
+ * replayed onto the (shared, process-wide) providers. Providers ignore/normalize
+ * unknown values, so a stale/hand-edited entry can never break playback.
+ */
+export interface AudioQualityConfig {
+  netease: string;
+  qq: string;
+  bilibili: string;
+  kugou: string;
+  jellyfin: string;
+}
+
 /**
  * Providers gated by `enabledProviders`. Not listed here:
  *  - "local"   → governed by the existing `localAudioEnabled` flag
@@ -61,14 +77,25 @@ export function isProviderEnabled(config: BotConfig, platform: string): boolean
 }
 
 /**
- * The default platform for !play/!add/!playlist/!album and all REST/WebUI calls:
+ * The default platform for !play/!add/!playlist/!album and all REST/WebUI calls.
- * jellyfin when enabled, otherwise the first enabled provider in a fixed
+ *
- * priority order. Falls back to "netease" when nothing is enabled so callers
+ * An explicit user preference (`config.defaultPlatform`) wins whenever it points
- * always get a provider — the enabled-gate then produces the friendly error.
+ * at a source that is currently enabled — this lets e.g. a Bilibili-loving server
+ * set B站 as the default so `!play <歌名>` needs no `-b` flag (issue #126). The
+ * enabled-guard here matters at runtime too: if the operator later disables the
+ * preferred source, we must fall through instead of returning a dead default.
+ *
+ * With no (usable) preference we fall back to the first enabled provider in a
+ * fixed priority order (netease with the default config; jellyfin ranks after
+ * the online music platforms because it is an opt-in source, but ahead of the
+ * video sites for users who run it as their only music library). Falls back to
+ * "netease" when nothing is enabled so callers always get a provider — the
+ * enabled-gate then produces the friendly error.
  */
 export function defaultPlatform(config: BotConfig): GateableProvider {
-  if (config.enabledProviders.includes("jellyfin")) return "jellyfin";
+  const pref = config.defaultPlatform;
-  for (const p of ["netease", "qq", "kugou", "bilibili", "youtube"] as const) {
+  if (pref && config.enabledProviders.includes(pref)) return pref;
+  for (const p of ["netease", "qq", "kugou", "jellyfin", "bilibili", "youtube"] as const) {
     if (config.enabledProviders.includes(p)) return p;
   }
   return "netease";
@@ -89,6 +116,19 @@ export interface BotConfig {
   idleTimeoutMinutes: number;
   /** Enable uploading and playback of server-stored local audio files. */
   localAudioEnabled: boolean;
+  /**
+   * Enable named save/load of queues (chat + web) AND auto-restore of the live
+   * queue across a restart. Admin-controlled; default false so nothing is
+   * persisted/restored until an operator opts in.
+   */
+  savedQueuesEnabled: boolean;
+  /**
+   * When true, a single-song immediate !play (chat) / play-song (web) inserts
+   * after the current track and jumps to it instead of clearing the queue, so
+   * the rest of the queue survives and continues afterwards. Default false
+   * keeps today's clear-and-play behavior.
+   */
+  playKeepsQueue: boolean;
   // 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"
@@ -100,13 +140,24 @@ export interface BotConfig {
   guestMode: GuestModeConfig;
   spotify: SpotifyConfig;
   jellyfin: JellyfinConfig;
+  /** Persisted per-provider audio quality (音质), restored on startup (#125). */
+  audioQuality: AudioQualityConfig;
   /**
    * Which gateable providers are active (see GATEABLE_PROVIDERS). Default is
-   * jellyfin-only: the legacy NetEase/QQ/Bilibili/YouTube/Kugou sources keep
+   * the online sources (NetEase/QQ/Bilibili/YouTube/Kugou); jellyfin is an
-   * compiling but stay disabled — their embedded sidecar API servers must not
+   * opt-in extra that must be listed here (Settings → Jellyfin 音乐库 toggles
-   * start (or bind ports 3001/3200) unless listed here.
+   * it). Sources not listed stay disabled — the NetEase/QQ embedded sidecar
+   * API servers must not start (or bind ports 3001/3200) unless enabled.
    */
   enabledProviders: GateableProvider[];
+  /**
+   * Optional operator-chosen default source for commands/REST/WebUI calls that
+   * omit a platform (issue #126). When set to an enabled gateable provider it
+   * overrides the fixed priority order in defaultPlatform(); `null` (the default)
+   * keeps that priority order. loadConfig cleans stale/unknown/disabled values
+   * back to null.
+   */
+  defaultPlatform: GateableProvider | null;
 }
 
 export function getDefaultConfig(): BotConfig {
@@ -127,6 +178,8 @@ export function getDefaultConfig(): BotConfig {
     autoPauseOnEmpty: false,
     idleTimeoutMinutes: 0,
     localAudioEnabled: true,
+    savedQueuesEnabled: false,
+    playKeepsQueue: false,
     publicUrl: "",
     trustProxy: false,
     guestMode: {
@@ -159,7 +212,17 @@ export function getDefaultConfig(): BotConfig {
       apiKey: "",
       userId: "",
     },
-    enabledProviders: ["jellyfin"],
+    // Mirrors each provider's own in-memory default quality; overwritten on
+    // startup once the user has changed a quality (persisted via #125).
+    audioQuality: {
+      netease: "exhigh",
+      qq: "exhigh",
+      bilibili: "high",
+      kugou: "128",
+      jellyfin: "direct",
+    },
+    enabledProviders: ["netease", "qq", "bilibili", "youtube", "kugou"],
+    defaultPlatform: null,
   };
 }
 
@@ -306,14 +369,46 @@ export function loadConfig(path: string): BotConfig {
     };
 
     // enabledProviders → known providers only; a non-array falls back to the
-    // default (["jellyfin"]). An explicitly-empty array is respected (operator
+    // default (online sources, jellyfin off). An explicitly-empty array is
-    // chose to disable every gateable source).
+    // respected (operator chose to disable every gateable source).
     const enabledProviders = Array.isArray(partial.enabledProviders)
       ? partial.enabledProviders.filter((p): p is GateableProvider =>
           (GATEABLE_PROVIDERS as readonly string[]).includes(p as string),
         )
       : defaults.enabledProviders;
 
+    // Strict-coerce the two feature flags exactly like spotify.enabled so a
+    // hand-edited / legacy / corrupt config.json can never silently enable
+    // them (`"yes"`, `1`, `null` → false; only a literal `true` enables).
+    const savedQueuesEnabled = partial.savedQueuesEnabled === true;
+    const playKeepsQueue = partial.playKeepsQueue === true;
+
+    // defaultPlatform → an explicit operator default (issue #126). Keep it only
+    // when it names a KNOWN gateable provider that is ALSO currently enabled;
+    // anything else (unknown value, disabled source, wrong type, missing) becomes
+    // null so defaultPlatform() falls back to the fixed priority order.
+    const rawDefault = partial.defaultPlatform;
+    const defaultPlatformPref: GateableProvider | null =
+      typeof rawDefault === "string" &&
+      (GATEABLE_PROVIDERS as readonly string[]).includes(rawDefault) &&
+      enabledProviders.includes(rawDefault as GateableProvider)
+        ? (rawDefault as GateableProvider)
+        : null;
+
+    // audioQuality → per-provider strings; each field falls back to its default
+    // when missing/blank/non-string (a hand-edited/legacy config must never smuggle
+    // a non-string past the gate — the value is fed straight to provider.setQuality).
+    const partialAq = (partial.audioQuality ?? {}) as Partial<AudioQualityConfig>;
+    const coerceQuality = (v: unknown, fallback: string): string =>
+      typeof v === "string" && v.trim() ? v : fallback;
+    const audioQuality: AudioQualityConfig = {
+      netease: coerceQuality(partialAq.netease, defaults.audioQuality.netease),
+      qq: coerceQuality(partialAq.qq, defaults.audioQuality.qq),
+      bilibili: coerceQuality(partialAq.bilibili, defaults.audioQuality.bilibili),
+      kugou: coerceQuality(partialAq.kugou, defaults.audioQuality.kugou),
+      jellyfin: coerceQuality(partialAq.jellyfin, defaults.audioQuality.jellyfin),
+    };
+
     return {
       ...defaults,
       ...partial,
@@ -321,7 +416,11 @@ export function loadConfig(path: string): BotConfig {
       guestMode: gm,
       spotify,
       jellyfin,
+      audioQuality,
       enabledProviders,
+      savedQueuesEnabled,
+      playKeepsQueue,
+      defaultPlatform: defaultPlatformPref,
     };
   }
 }

src/data/database.test.ts

@@ -2,7 +2,7 @@ import { mkdtempSync, rmSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { describe, it, expect, beforeEach, afterEach } from "vitest";
-import { createDatabase, type BotDatabase, type BotInstance, type PlayHistoryEntry } from "./database.js";
+import { createDatabase, SHARED_QUEUE_OWNER, type BotDatabase, type BotInstance, type PlayHistoryEntry } from "./database.js";
 import { createUserStore, GUEST_USER_ID } from "./users.js";
 
 describe("database", () => {
@@ -131,6 +131,92 @@ describe("database", () => {
     expect(botDb.deleteBotInstance("nonexistent")).toBe(false);
   });
 
+  it("persists and restores per-bot player settings (volume + play mode) (#125)", () => {
+    const inst = {
+      id: "bot-ps",
+      name: "B",
+      serverAddress: "x",
+      serverPort: 9987,
+      nickname: "n",
+      defaultChannel: "",
+      channelId: "",
+      channelPassword: "",
+      autoStart: false,
+      serverProtocol: "",
+      ts6ApiKey: "",
+      serverPassword: "",
+    };
+    botDb.saveBotInstance(inst);
+
+    // Fresh row → in-memory defaults.
+    expect(botDb.getPlayerSettings("bot-ps")).toEqual({ volume: 75, playMode: "seq" });
+
+    // Volume and play mode persist independently.
+    botDb.saveVolume("bot-ps", 42);
+    expect(botDb.getPlayerSettings("bot-ps")).toEqual({ volume: 42, playMode: "seq" });
+    botDb.savePlayMode("bot-ps", "rloop");
+    expect(botDb.getPlayerSettings("bot-ps")).toEqual({ volume: 42, playMode: "rloop" });
+
+    // A later saveBotInstance upsert (e.g. autoStart toggle) must NOT reset them.
+    botDb.saveBotInstance({ ...inst, autoStart: true });
+    expect(botDb.getPlayerSettings("bot-ps")).toEqual({ volume: 42, playMode: "rloop" });
+  });
+
+  it("defaults player settings for an unknown bot and validates inputs (#125)", () => {
+    // No row → defaults.
+    expect(botDb.getPlayerSettings("does-not-exist")).toEqual({ volume: 75, playMode: "seq" });
+
+    botDb.saveBotInstance({
+      id: "bot-v",
+      name: "B",
+      serverAddress: "x",
+      serverPort: 9987,
+      nickname: "n",
+      defaultChannel: "",
+      channelId: "",
+      channelPassword: "",
+      autoStart: false,
+      serverProtocol: "",
+      ts6ApiKey: "",
+      serverPassword: "",
+    });
+    // Out-of-range volume is clamped; an unknown play mode is ignored (not stored).
+    botDb.saveVolume("bot-v", 250);
+    expect(botDb.getPlayerSettings("bot-v").volume).toBe(100);
+    botDb.saveVolume("bot-v", -10);
+    expect(botDb.getPlayerSettings("bot-v").volume).toBe(0);
+    botDb.savePlayMode("bot-v", "bogus");
+    expect(botDb.getPlayerSettings("bot-v").playMode).toBe("seq");
+  });
+
+  it("migrates volume + play_mode columns onto a legacy bot_instances table (#125)", () => {
+    const dir = mkdtempSync(join(tmpdir(), "tsmb-mig-"));
+    const p = join(dir, "legacy.db");
+    // Build a minimal pre-#125 bot_instances table (no volume/play_mode columns).
+    const legacy = createDatabase(p);
+    legacy.db.exec("DROP TABLE bot_instances");
+    legacy.db.exec(`CREATE TABLE bot_instances (
+      id TEXT PRIMARY KEY, name TEXT NOT NULL, serverAddress TEXT NOT NULL,
+      serverPort INTEGER NOT NULL, nickname TEXT NOT NULL, defaultChannel TEXT NOT NULL,
+      channelId TEXT NOT NULL DEFAULT '', channelPassword TEXT NOT NULL,
+      autoStart INTEGER NOT NULL DEFAULT 0, serverProtocol TEXT NOT NULL DEFAULT '',
+      ts6ApiKey TEXT NOT NULL DEFAULT '', serverPassword TEXT NOT NULL DEFAULT '', identity TEXT
+    )`);
+    legacy.db
+      .prepare("INSERT INTO bot_instances (id, name, serverAddress, serverPort, nickname, defaultChannel, channelPassword) VALUES (?, 'B', 'x', 9987, 'n', '', '')")
+      .run("legacy-bot");
+    legacy.close();
+
+    // Reopen → migrateSchema adds the columns; the old row gets the defaults.
+    const reopened = createDatabase(p);
+    const cols = (reopened.db.prepare("PRAGMA table_info(bot_instances)").all() as Array<{ name: string }>).map((c) => c.name);
+    expect(cols).toContain("volume");
+    expect(cols).toContain("play_mode");
+    expect(reopened.getPlayerSettings("legacy-bot")).toEqual({ volume: 75, playMode: "seq" });
+    reopened.close();
+    rmSync(dir, { recursive: true, force: true });
+  });
+
   it("persists and clears customAvatarPath on a bot instance", () => {
     const inst = {
       id: "bot-1",
@@ -153,6 +239,86 @@ describe("database", () => {
     botDb.setCustomAvatarPath("bot-1", null);
     expect(botDb.getCustomAvatarPath("bot-1")).toBeNull();
   });
+
+  const sq = (id: string) => ({
+    id,
+    name: id,
+    artist: "",
+    album: "",
+    platform: "netease" as const,
+    coverUrl: "",
+    duration: 1,
+  });
+
+  describe("saved_queues", () => {
+    it("upserts by (ownerId, name) and returns songs", () => {
+      botDb.saveQueue("u1", "night", [sq("a"), sq("b")]);
+      const again = botDb.saveQueue("u1", "night", [sq("c")]); // overwrite
+      expect(again.songCount).toBe(1);
+      expect(botDb.listSavedQueues("u1", false)).toHaveLength(1);
+      const full = botDb.getSavedQueue(again.id)!;
+      expect(full.songs.map((s) => s.id)).toEqual(["c"]);
+    });
+
+    it("strips url before persisting", () => {
+      const saved = botDb.saveQueue("u1", "x", [
+        { ...sq("a"), url: "http://example.com/a.mp3" } as never,
+      ]);
+      const full = botDb.getSavedQueue(saved.id)!;
+      expect((full.songs[0] as { url?: string }).url).toBeUndefined();
+    });
+
+    it("lists own + shared when includeShared, own-only otherwise", () => {
+      botDb.saveQueue("u1", "mine", [sq("a")]);
+      botDb.saveQueue(SHARED_QUEUE_OWNER, "party", [sq("b")]);
+      expect(botDb.listSavedQueues("u1", false).map((q) => q.name)).toEqual(["mine"]);
+      expect(
+        botDb.listSavedQueues("u1", true).map((q) => q.name).sort(),
+      ).toEqual(["mine", "party"]);
+    });
+
+    it("caps songs at 1000 and queues at 50", () => {
+      expect(() =>
+        botDb.saveQueue("u1", "big", Array.from({ length: 1001 }, (_, i) => sq("s" + i))),
+      ).toThrow(/1000/);
+      for (let i = 0; i < 50; i++) botDb.saveQueue("u1", "q" + i, [sq("a")]);
+      expect(() => botDb.saveQueue("u1", "q50", [sq("a")])).toThrow(/50/);
+      // Overwriting an existing name is always allowed despite the cap.
+      expect(() => botDb.saveQueue("u1", "q0", [sq("z")])).not.toThrow();
+    });
+
+    it("deletes and degrades a corrupt blob to empty", () => {
+      const q = botDb.saveQueue("u1", "x", [sq("a")]);
+      botDb.db.prepare("UPDATE saved_queues SET songs='not json' WHERE id=?").run(q.id);
+      expect(botDb.getSavedQueue(q.id)!.songs).toEqual([]);
+      expect(botDb.deleteSavedQueue(q.id)).toBe(true);
+      expect(botDb.getSavedQueue(q.id)).toBeNull();
+      expect(botDb.deleteSavedQueue(q.id)).toBe(false); // already gone
+    });
+  });
+
+  describe("queue_state", () => {
+    it("upserts, reads back, and clears per bot", () => {
+      botDb.saveQueueState({ botId: "b1", songs: [sq("a")], currentIndex: 0, mode: "loop", isFmMode: true, fmPlatform: "netease" });
+      botDb.saveQueueState({ botId: "b1", songs: [sq("a"), sq("b")], currentIndex: 1, mode: "seq", isFmMode: false, fmPlatform: "" });
+      const st = botDb.getQueueState("b1")!;
+      expect(st.songs.map((s) => s.id)).toEqual(["a", "b"]);
+      expect(st.currentIndex).toBe(1);
+      expect(st.mode).toBe("seq");
+      expect(st.isFmMode).toBe(false);
+      botDb.clearQueueState("b1");
+      expect(botDb.getQueueState("b1")).toBeNull();
+    });
+
+    it("round-trips FM flags and degrades a corrupt blob", () => {
+      botDb.saveQueueState({ botId: "b2", songs: [sq("a")], currentIndex: 0, mode: "random", isFmMode: true, fmPlatform: "qq" });
+      const st = botDb.getQueueState("b2")!;
+      expect(st.isFmMode).toBe(true);
+      expect(st.fmPlatform).toBe("qq");
+      botDb.db.prepare("UPDATE queue_state SET songs='{' WHERE botId=?").run("b2");
+      expect(botDb.getQueueState("b2")!.songs).toEqual([]);
+    });
+  });
 });
 
 describe("guest principal migration", () => {

src/data/database.ts

@@ -1,6 +1,46 @@
 import Database from "better-sqlite3";
 import { CAPABILITIES, BOTS_ALL } from "./permissions.js";
 import { GUEST_USER_ID, GUEST_USERNAME } from "./users.js";
+import type { QueuedSong } from "../audio/queue.js";
+
+/**
+ * Reserved owner id for chat-saved / opt-in-shared queues. A `__`-bracketed
+ * literal can never collide with a real WebUI user id (UUIDs), so it cleanly
+ * partitions "shared" saved queues from per-user private ones (issue #119).
+ */
+export const SHARED_QUEUE_OWNER = "__shared__";
+/** Cap per owner (private user OR the shared bucket). */
+export const MAX_SAVED_QUEUES = 50;
+/** Cap per saved queue / persisted live-queue snapshot. */
+export const MAX_QUEUE_SONGS = 1000;
+
+/** A stored song is a QueuedSong minus the lazily-resolved `url`. */
+export type StoredSong = Omit<QueuedSong, "url">;
+
+/** Saved-queue row without the (potentially large) songs blob — for list views. */
+export interface SavedQueueMeta {
+  id: number;
+  ownerId: string;
+  name: string;
+  songCount: number;
+  createdAt: string;
+  updatedAt: string;
+}
+
+/** Full saved queue, including its songs. */
+export interface SavedQueue extends SavedQueueMeta {
+  songs: StoredSong[];
+}
+
+/** One-row-per-bot persisted live-queue state (Feature 2, auto-restore). */
+export interface QueueStateRow {
+  botId: string;
+  songs: StoredSong[];
+  currentIndex: number;
+  mode: string;
+  isFmMode: boolean;
+  fmPlatform: string;
+}
 
 export interface PlayHistoryEntry {
   botId: string;
@@ -55,6 +95,26 @@ export const DEFAULT_PROFILE_CONFIG: ProfileConfig = {
   nowPlayingMsgEnabled: true,
 };
 
+/**
+ * Per-bot player settings persisted across restarts (#125): the playback volume
+ * and play mode. These reset to defaults on process restart when kept only in
+ * memory (AudioPlayer/PlayQueue), so they are stored on the bot_instances row —
+ * exactly like the per-bot profile flags — and restored when the bot is (re)built.
+ */
+export interface PlayerSettings {
+  /** 0-100. */
+  volume: number;
+  /** PlayMode string: "seq" | "loop" | "random" | "rloop". */
+  playMode: string;
+}
+
+const PLAY_MODES = new Set(["seq", "loop", "random", "rloop"]);
+
+export const DEFAULT_PLAYER_SETTINGS: PlayerSettings = {
+  volume: 75,
+  playMode: "seq",
+};
+
 export interface FavoritePlaylist {
   id: number;
   userId: string;
@@ -75,12 +135,24 @@ export interface BotDatabase {
   deleteBotInstance(id: string): boolean;
   getProfileConfig(botId: string): ProfileConfig;
   saveProfileConfig(botId: string, config: ProfileConfig): void;
+  getPlayerSettings(botId: string): PlayerSettings;
+  saveVolume(botId: string, volume: number): void;
+  savePlayMode(botId: string, playMode: string): void;
   getCustomAvatarPath(botId: string): string | null;
   setCustomAvatarPath(botId: string, path: string | null): void;
   addFavorite(userId: string, playlist: { platform: string; playlistId: string; name: string; coverUrl: string; songCount: number }): void;
   removeFavorite(userId: string, playlistId: string, platform: string): boolean;
   getFavorites(userId: string): FavoritePlaylist[];
   isFavorited(userId: string, playlistId: string, platform: string): boolean;
+  // Saved queues (Feature 1) — upsert by (ownerId, name), capped.
+  saveQueue(ownerId: string, name: string, songs: StoredSong[]): SavedQueue;
+  listSavedQueues(ownerId: string, includeShared: boolean): SavedQueueMeta[];
+  getSavedQueue(id: number): SavedQueue | null;
+  deleteSavedQueue(id: number): boolean;
+  // Live-queue persistence (Feature 2) — one row per bot.
+  saveQueueState(state: QueueStateRow): void;
+  getQueueState(botId: string): QueueStateRow | null;
+  clearQueueState(botId: string): void;
   close(): void;
 }
 
@@ -119,6 +191,15 @@ function migrateSchema(db: Database.Database): void {
   if (!names.includes("custom_avatar_path")) {
     db.exec("ALTER TABLE bot_instances ADD COLUMN custom_avatar_path TEXT");
   }
+  // Per-bot persisted player settings (#125): volume + play mode. Defaults match
+  // AudioPlayer/PlayQueue's in-memory defaults so pre-existing rows keep behaving
+  // exactly as before until the user changes them.
+  if (!names.includes("volume")) {
+    db.exec("ALTER TABLE bot_instances ADD COLUMN volume INTEGER NOT NULL DEFAULT 75");
+  }
+  if (!names.includes("play_mode")) {
+    db.exec("ALTER TABLE bot_instances ADD COLUMN play_mode TEXT NOT NULL DEFAULT 'seq'");
+  }
 
   const userColumns = db.prepare("PRAGMA table_info(users)").all() as Array<{ name: string }>;
   const userColNames = userColumns.map((c) => c.name);
@@ -161,6 +242,8 @@ function initTables(db: Database.Database): void {
       serverProtocol TEXT NOT NULL DEFAULT '',
       ts6ApiKey TEXT NOT NULL DEFAULT '',
       serverPassword TEXT NOT NULL DEFAULT '',
+      volume INTEGER NOT NULL DEFAULT 75,
+      play_mode TEXT NOT NULL DEFAULT 'seq',
       identity TEXT
     );
 
@@ -223,6 +306,28 @@ function initTables(db: Database.Database): void {
       FOREIGN KEY (userId) REFERENCES users(id) ON DELETE CASCADE
     );
     CREATE INDEX IF NOT EXISTS idx_user_bot_access_userId ON user_bot_access(userId);
+
+    CREATE TABLE IF NOT EXISTS saved_queues (
+      id        INTEGER PRIMARY KEY AUTOINCREMENT,
+      ownerId   TEXT NOT NULL,
+      name      TEXT NOT NULL,
+      songs     TEXT NOT NULL,
+      songCount INTEGER NOT NULL DEFAULT 0,
+      createdAt TEXT NOT NULL DEFAULT (datetime('now')),
+      updatedAt TEXT NOT NULL DEFAULT (datetime('now')),
+      UNIQUE(ownerId, name)
+    );
+    CREATE INDEX IF NOT EXISTS idx_saved_queues_ownerId ON saved_queues(ownerId);
+
+    CREATE TABLE IF NOT EXISTS queue_state (
+      botId        TEXT PRIMARY KEY,
+      songs        TEXT NOT NULL,
+      currentIndex INTEGER NOT NULL,
+      mode         TEXT NOT NULL,
+      isFmMode     INTEGER NOT NULL DEFAULT 0,
+      fmPlatform   TEXT NOT NULL DEFAULT '',
+      updatedAt    TEXT NOT NULL DEFAULT (datetime('now'))
+    );
   `);
 }
 
@@ -321,6 +426,12 @@ export function createDatabase(dbPath: string): BotDatabase {
     WHERE id = @id
   `);
 
+  const selectPlayerSettings = db.prepare(
+    `SELECT volume, play_mode FROM bot_instances WHERE id = ?`,
+  );
+  const updateVolume = db.prepare(`UPDATE bot_instances SET volume = ? WHERE id = ?`);
+  const updatePlayMode = db.prepare(`UPDATE bot_instances SET play_mode = ? WHERE id = ?`);
+
   const selectCustomAvatar = db.prepare(`SELECT custom_avatar_path FROM bot_instances WHERE id = ?`);
   const updateCustomAvatar = db.prepare(`UPDATE bot_instances SET custom_avatar_path = ? WHERE id = ?`);
 
@@ -342,6 +453,67 @@ export function createDatabase(dbPath: string): BotDatabase {
     SELECT 1 FROM favorite_playlists WHERE userId = ? AND playlistId = ? AND platform = ?
   `);
 
+  // A corrupt/hand-edited songs blob must never throw into a route or the
+  // restore path — degrade to an empty list instead.
+  const parseSongs = (raw: string): StoredSong[] => {
+    try {
+      const v = JSON.parse(raw);
+      return Array.isArray(v) ? (v as StoredSong[]) : [];
+    } catch {
+      return [];
+    }
+  };
+  const rowToSavedMeta = (r: {
+    id: number; ownerId: string; name: string; songCount: number; createdAt: string; updatedAt: string;
+  }): SavedQueueMeta => ({
+    id: r.id,
+    ownerId: r.ownerId,
+    name: r.name,
+    songCount: r.songCount,
+    createdAt: r.createdAt,
+    updatedAt: r.updatedAt,
+  });
+
+  const upsertSavedQueue = db.prepare(`
+    INSERT INTO saved_queues (ownerId, name, songs, songCount)
+    VALUES (@ownerId, @name, @songs, @songCount)
+    ON CONFLICT(ownerId, name) DO UPDATE SET
+      songs = excluded.songs,
+      songCount = excluded.songCount,
+      updatedAt = datetime('now')
+  `);
+  const selectSavedQueueByOwnerName = db.prepare(
+    "SELECT * FROM saved_queues WHERE ownerId = ? AND name = ?",
+  );
+  const selectSavedQueueIdByOwnerName = db.prepare(
+    "SELECT id FROM saved_queues WHERE ownerId = ? AND name = ?",
+  );
+  const countSavedQueues = db.prepare(
+    "SELECT COUNT(*) AS c FROM saved_queues WHERE ownerId = ?",
+  );
+  const listSavedQueuesOwn = db.prepare(
+    "SELECT id, ownerId, name, songCount, createdAt, updatedAt FROM saved_queues WHERE ownerId = ? ORDER BY updatedAt DESC",
+  );
+  const listSavedQueuesShared = db.prepare(
+    "SELECT id, ownerId, name, songCount, createdAt, updatedAt FROM saved_queues WHERE ownerId = ? OR ownerId = ? ORDER BY updatedAt DESC",
+  );
+  const selectSavedQueueById = db.prepare("SELECT * FROM saved_queues WHERE id = ?");
+  const deleteSavedQueueById = db.prepare("DELETE FROM saved_queues WHERE id = ?");
+
+  const upsertQueueState = db.prepare(`
+    INSERT INTO queue_state (botId, songs, currentIndex, mode, isFmMode, fmPlatform, updatedAt)
+    VALUES (@botId, @songs, @currentIndex, @mode, @isFmMode, @fmPlatform, datetime('now'))
+    ON CONFLICT(botId) DO UPDATE SET
+      songs = excluded.songs,
+      currentIndex = excluded.currentIndex,
+      mode = excluded.mode,
+      isFmMode = excluded.isFmMode,
+      fmPlatform = excluded.fmPlatform,
+      updatedAt = datetime('now')
+  `);
+  const selectQueueState = db.prepare("SELECT * FROM queue_state WHERE botId = ?");
+  const deleteQueueState = db.prepare("DELETE FROM queue_state WHERE botId = ?");
+
   return {
     db,
 
@@ -406,6 +578,36 @@ export function createDatabase(dbPath: string): BotDatabase {
       });
     },
 
+    getPlayerSettings(botId) {
+      const row = selectPlayerSettings.get(botId) as
+        | { volume: number | null; play_mode: string | null }
+        | undefined;
+      if (!row) return { ...DEFAULT_PLAYER_SETTINGS };
+      // Coerce/validate: clamp volume to 0-100 and fall back to defaults for any
+      // NULL / out-of-range / unknown value (a hand-edited DB must never feed a
+      // bad value into AudioPlayer.setVolume / PlayQueue.setMode).
+      const rawVol = typeof row.volume === "number" ? row.volume : DEFAULT_PLAYER_SETTINGS.volume;
+      const volume = Number.isFinite(rawVol)
+        ? Math.max(0, Math.min(100, Math.round(rawVol)))
+        : DEFAULT_PLAYER_SETTINGS.volume;
+      const playMode =
+        typeof row.play_mode === "string" && PLAY_MODES.has(row.play_mode)
+          ? row.play_mode
+          : DEFAULT_PLAYER_SETTINGS.playMode;
+      return { volume, playMode };
+    },
+
+    saveVolume(botId, volume) {
+      const clamped = Math.max(0, Math.min(100, Math.round(volume)));
+      updateVolume.run(clamped, botId);
+    },
+
+    savePlayMode(botId, playMode) {
+      // Persist only recognized modes so a bad value can never poison the row.
+      if (!PLAY_MODES.has(playMode)) return;
+      updatePlayMode.run(playMode, botId);
+    },
+
     getCustomAvatarPath(botId) {
       const row = selectCustomAvatar.get(botId) as { custom_avatar_path: string | null } | undefined;
       return row?.custom_avatar_path ?? null;
@@ -432,6 +634,85 @@ export function createDatabase(dbPath: string): BotDatabase {
       return row !== undefined;
     },
 
+    saveQueue(ownerId, name, songs) {
+      if (songs.length > MAX_QUEUE_SONGS) {
+        throw new Error(`保存失败：歌曲数量超过上限 ${MAX_QUEUE_SONGS}`);
+      }
+      // Strip any lazily-resolved url before persisting.
+      const stripped: StoredSong[] = songs.map((s) => {
+        const { url: _url, ...rest } = s as QueuedSong;
+        return rest;
+      });
+      // Enforce the per-owner cap only for a NEW name (an overwrite of an
+      // existing saved queue must always be allowed).
+      const existing = selectSavedQueueIdByOwnerName.get(ownerId, name) as
+        | { id: number }
+        | undefined;
+      if (!existing) {
+        const { c } = countSavedQueues.get(ownerId) as { c: number };
+        if (c >= MAX_SAVED_QUEUES) {
+          throw new Error(`保存失败：已保存队列数量超过上限 ${MAX_SAVED_QUEUES}`);
+        }
+      }
+      upsertSavedQueue.run({
+        ownerId,
+        name,
+        songs: JSON.stringify(stripped),
+        songCount: stripped.length,
+      });
+      const row = selectSavedQueueByOwnerName.get(ownerId, name) as SavedQueueMeta;
+      return { ...rowToSavedMeta(row), songs: stripped };
+    },
+
+    listSavedQueues(ownerId, includeShared) {
+      const rows = includeShared
+        ? (listSavedQueuesShared.all(ownerId, SHARED_QUEUE_OWNER) as SavedQueueMeta[])
+        : (listSavedQueuesOwn.all(ownerId) as SavedQueueMeta[]);
+      return rows.map(rowToSavedMeta);
+    },
+
+    getSavedQueue(id) {
+      const row = selectSavedQueueById.get(id) as
+        | (SavedQueueMeta & { songs: string })
+        | undefined;
+      if (!row) return null;
+      return { ...rowToSavedMeta(row), songs: parseSongs(row.songs) };
+    },
+
+    deleteSavedQueue(id) {
+      return deleteSavedQueueById.run(id).changes > 0;
+    },
+
+    saveQueueState(state) {
+      upsertQueueState.run({
+        botId: state.botId,
+        songs: JSON.stringify(state.songs),
+        currentIndex: state.currentIndex,
+        mode: state.mode,
+        isFmMode: state.isFmMode ? 1 : 0,
+        fmPlatform: state.fmPlatform,
+      });
+    },
+
+    getQueueState(botId) {
+      const r = selectQueueState.get(botId) as
+        | { botId: string; songs: string; currentIndex: number; mode: string; isFmMode: number; fmPlatform: string }
+        | undefined;
+      if (!r) return null;
+      return {
+        botId: r.botId,
+        songs: parseSongs(r.songs),
+        currentIndex: r.currentIndex,
+        mode: r.mode,
+        isFmMode: r.isFmMode === 1,
+        fmPlatform: r.fmPlatform,
+      };
+    },
+
+    clearQueueState(botId) {
+      deleteQueueState.run(botId);
+    },
+
     close() {
       db.close();
     },

src/index.ts

@@ -56,8 +56,8 @@ async function main() {
     {
       neteasePort: config.neteaseApiPort,
       qqMusicPort: config.qqMusicApiPort,
-      // Provider gating: with the default (jellyfin-only) config, neither
+      // Provider gating: a sidecar only starts (and binds 3001/3200) when its
-      // sidecar starts and ports 3001/3200 are never bound.
+      // source is listed in enabledProviders — both are on in the default config.
       neteaseEnabled: isProviderEnabled(config, "netease"),
       qqEnabled: isProviderEnabled(config, "qq"),
     },
@@ -100,6 +100,15 @@ async function main() {
   if (jellyfinAuth) jellyfinProvider.setCookie(jellyfinAuth);
   jellyfinProvider.setPersist((serialized) => cookieStore.save("jellyfin", serialized));
 
+  // Restore the persisted per-provider audio quality (#125) onto the shared,
+  // process-wide providers so a restart keeps the user's choice. setQuality()
+  // normalizes/ignores unknown values, so a stale entry can never break playback.
+  neteaseProvider.setQuality(config.audioQuality.netease);
+  qqProvider.setQuality(config.audioQuality.qq);
+  bilibiliProvider.setQuality(config.audioQuality.bilibili);
+  kugouProvider.setQuality(config.audioQuality.kugou);
+  jellyfinProvider.setQuality(config.audioQuality.jellyfin);
+
   const permissions = createPermissionStore(db.db);
 
   // Single process-wide Spotify authorization (one Premium account for Stage 3).

src/music/api-server.test.ts

@@ -1,5 +1,34 @@
-import { describe, it, expect } from "vitest";
+import { describe, it, expect, vi, beforeEach } from "vitest";
-import { describeQqApiStartupError } from "./api-server.js";
+import { createApiServerManager, describeQqApiStartupError } from "./api-server.js";
+import type { Logger } from "../logger.js";
+
+// Record every listen() the QQ sidecar makes so we can assert it is always
+// pinned to the configured port (regression coverage for issue #122).
+const mockState = vi.hoisted(() => ({
+  listenCalls: [] as Array<{ port: number; host: string }>,
+}));
+
+vi.mock("@sansenjian/qq-music-api", () => {
+  const app = {
+    listen(port: number, host: string, cb?: () => void) {
+      mockState.listenCalls.push({ port, host });
+      const server = {
+        address: () => ({ port, address: host, family: "IPv4" as const }),
+        on() {
+          return server;
+        },
+        close(done?: () => void) {
+          done?.();
+        },
+      };
+      // Real net/Koa fire the listening callback on a later tick, after the
+      // caller has captured the returned server handle.
+      if (cb) setImmediate(cb);
+      return server;
+    },
+  };
+  return { default: app };
+});
 
 describe("describeQqApiStartupError", () => {
   it("flags ERR_REQUIRE_ESM by error code with version-pin guidance", () => {
@@ -28,3 +57,77 @@ describe("describeQqApiStartupError", () => {
     expect(describeQqApiStartupError(null)).toBeNull();
   });
 });
+
+// Regression coverage for issue #122: the QQ Music API sidecar must listen on
+// the same port the client base URL targets (config.qqMusicApiPort). A stale
+// build once bound 3300 while the client requested 3200, silently breaking the
+// QQ login QR / search flow with ECONNREFUSED on 127.0.0.1:3200.
+describe("createApiServerManager — QQ sidecar port binding", () => {
+  const noopLogger = {
+    info() {},
+    warn() {},
+    error() {},
+    debug() {},
+    trace() {},
+    fatal() {},
+  } as unknown as Logger;
+
+  beforeEach(() => {
+    mockState.listenCalls = [];
+  });
+
+  it("listens on the configured qqMusicPort and exposes a matching base URL", async () => {
+    const port = 39217; // uncommon port to avoid clashing with a real instance
+    const manager = createApiServerManager(
+      { neteasePort: 39218, qqMusicPort: port, neteaseEnabled: false, qqEnabled: true },
+      noopLogger
+    );
+    await manager.start();
+    manager.stop();
+
+    expect(manager.getQQMusicBaseUrl()).toBe(`http://127.0.0.1:${port}`);
+    expect(mockState.listenCalls).toEqual([{ port, host: "127.0.0.1" }]);
+  });
+
+  it("follows qqMusicPort — not an injected PORT — and restores PORT afterwards", async () => {
+    const port = 39219;
+    const previous = process.env.PORT;
+    // Simulate a hosting platform / compose file injecting a stray PORT that
+    // must NOT leak into the QQ sidecar's chosen port.
+    process.env.PORT = "39999";
+    const manager = createApiServerManager(
+      { neteasePort: 39220, qqMusicPort: port, neteaseEnabled: false, qqEnabled: true },
+      noopLogger
+    );
+    try {
+      await manager.start();
+      // The sidecar follows qqMusicPort, never the injected PORT.
+      expect(mockState.listenCalls).toEqual([{ port, host: "127.0.0.1" }]);
+      // The injected PORT is restored so nothing else in the process is affected.
+      expect(process.env.PORT).toBe("39999");
+    } finally {
+      manager.stop();
+      if (previous === undefined) delete process.env.PORT;
+      else process.env.PORT = previous;
+    }
+  });
+
+  it("leaves an absent PORT env unset after importing the sidecar", async () => {
+    const port = 39221;
+    const previous = process.env.PORT;
+    delete process.env.PORT;
+    const manager = createApiServerManager(
+      { neteasePort: 39222, qqMusicPort: port, neteaseEnabled: false, qqEnabled: true },
+      noopLogger
+    );
+    try {
+      await manager.start();
+      // Was unset before importing — must be unset again, no leaked override.
+      expect(process.env.PORT).toBeUndefined();
+    } finally {
+      manager.stop();
+      if (previous === undefined) delete process.env.PORT;
+      else process.env.PORT = previous;
+    }
+  });
+});

src/music/api-server.ts

@@ -114,7 +114,25 @@ export function createApiServerManager(
             "QQ Music API port already in use — reusing existing instance"
           );
         } else {
-          const qqModule = (await import("@sansenjian/qq-music-api")) as any;
+          // Pin the upstream server to the configured port before importing.
+          // The package derives its default port from process.env.PORT (falling
+          // back to 3200) and, in some historical versions, auto-started that
+          // server as an import side effect. Aligning PORT with qqMusicApiPort
+          // guarantees the sidecar can never bind a different port than the one
+          // the client base URL (getQQMusicBaseUrl) targets — the root cause of
+          // issue #122, where an old build listened on 3300 while the client
+          // requested 3200. Restore the previous value right after import so we
+          // never leak the override into the rest of the process (e.g. the web
+          // server or the NetEase sidecar, which also read PORT as a fallback).
+          const prevPortEnv = process.env.PORT;
+          process.env.PORT = String(options.qqMusicPort);
+          let qqModule: any;
+          try {
+            qqModule = (await import("@sansenjian/qq-music-api")) as any;
+          } finally {
+            if (prevPortEnv === undefined) delete process.env.PORT;
+            else process.env.PORT = prevPortEnv;
+          }
           // 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
@@ -124,16 +142,34 @@ export function createApiServerManager(
             ? candidate
             : candidate.default ?? null;
           if (koaApp && typeof koaApp.listen === "function") {
+            // A version that auto-started on import has already bound the
+            // configured port (thanks to the PORT alignment above); reuse it
+            // rather than racing a second listen that would fail EADDRINUSE.
+            const stillFree = await isPortFree(options.qqMusicPort);
+            if (!stillFree) {
+              logger.info(
+                { port: options.qqMusicPort },
+                "QQ Music API already listening on the configured port (auto-started on import) — reusing embedded instance"
+              );
+            } else {
               qqMusicServer = await new Promise<Server>((resolve, reject) => {
                 const srv = koaApp.listen(options.qqMusicPort, "127.0.0.1", () =>
                   resolve(srv)
                 );
                 srv.on("error", reject);
               });
+              // Log the port actually bound (read from the socket) rather than
+              // the requested one, so operators can spot a mismatch in the logs.
+              const addr = qqMusicServer.address();
+              const boundPort =
+                addr && typeof addr === "object" && addr !== null
+                  ? addr.port
+                  : options.qqMusicPort;
               logger.info(
-              { port: options.qqMusicPort },
+                { port: boundPort },
                 "QQ Music API started"
               );
+            }
           } else {
             logger.warn("QQ Music API module does not expose a Koa app");
           }

src/web/api/bot.test.ts

@@ -325,6 +325,38 @@ describe("bot router /settings", () => {
     expect(res.status).toBe(200);
     expect(config.spotify).toEqual(before);
   });
+
+  it("GET /settings echoes savedQueuesEnabled + playKeepsQueue (default false)", async () => {
+    const res = await request(app).get("/api/bot/settings").set("Cookie", cookie);
+    expect(res.status).toBe(200);
+    expect(res.body.savedQueuesEnabled).toBe(false);
+    expect(res.body.playKeepsQueue).toBe(false);
+  });
+
+  it("POST /settings persists savedQueuesEnabled and playKeepsQueue", async () => {
+    const res = await request(app)
+      .post("/api/bot/settings")
+      .set("Cookie", cookie)
+      .send({ savedQueuesEnabled: true, playKeepsQueue: true });
+    expect(res.status).toBe(200);
+    expect(res.body.savedQueuesEnabled).toBe(true);
+    expect(res.body.playKeepsQueue).toBe(true);
+    expect(config.savedQueuesEnabled).toBe(true);
+    expect(config.playKeepsQueue).toBe(true);
+
+    const get = await request(app).get("/api/bot/settings").set("Cookie", cookie);
+    expect(get.body.savedQueuesEnabled).toBe(true);
+    expect(get.body.playKeepsQueue).toBe(true);
+  });
+
+  it("POST /settings ignores non-boolean savedQueuesEnabled without 400", async () => {
+    const res = await request(app)
+      .post("/api/bot/settings")
+      .set("Cookie", cookie)
+      .send({ savedQueuesEnabled: "nope" });
+    expect(res.status).toBe(200);
+    expect(config.savedQueuesEnabled).toBe(false); // unchanged from default
+  });
 });
 
 // Whole-branch I2: saving a Client ID in Settings must re-configure the single
@@ -612,7 +644,8 @@ describe("bot router /settings jellyfin block + enabledProviders", () => {
       hasPassword: true,
       hasApiKey: false,
     });
-    expect(res.body.enabledProviders).toEqual(["jellyfin"]);
+    // Default: online sources on, jellyfin opt-in (not listed).
+    expect(res.body.enabledProviders).toEqual(["netease", "qq", "bilibili", "youtube", "kugou"]);
   });
 
   it("POST /settings merges jellyfin, keeps stored secrets on blank, hot-configures", async () => {
@@ -646,4 +679,54 @@ describe("bot router /settings jellyfin block + enabledProviders", () => {
     // No jellyfin block in the request → no reconfigure call.
     expect(configureCalls).toHaveLength(0);
   });
+
+  // --- #126: operator-chosen default source ---
+
+  it("GET /settings exposes defaultPlatform (null by default)", async () => {
+    const res = await request(mountBot()).get("/api/bot/settings");
+    expect(res.status).toBe(200);
+    expect(res.body.defaultPlatform).toBeNull();
+  });
+
+  it("POST /settings sets an enabled defaultPlatform and persists it", async () => {
+    const res = await request(mountBot()).post("/api/bot/settings").send({
+      defaultPlatform: "bilibili",
+    });
+    expect(res.status).toBe(200);
+    expect(res.body.defaultPlatform).toBe("bilibili");
+    expect(config.defaultPlatform).toBe("bilibili");
+    const onDisk = JSON.parse(readFileSync(configPath, "utf-8"));
+    expect(onDisk.defaultPlatform).toBe("bilibili");
+  });
+
+  it("POST /settings ignores an unknown or disabled defaultPlatform", async () => {
+    const app = mountBot();
+    // jellyfin is opt-in and not enabled in the default config → rejected.
+    await request(app).post("/api/bot/settings").send({ defaultPlatform: "jellyfin" });
+    expect(config.defaultPlatform).toBeNull();
+    // Unknown value → rejected.
+    await request(app).post("/api/bot/settings").send({ defaultPlatform: "bogus" });
+    expect(config.defaultPlatform).toBeNull();
+  });
+
+  it("POST /settings clears defaultPlatform with null", async () => {
+    const app = mountBot();
+    await request(app).post("/api/bot/settings").send({ defaultPlatform: "qq" });
+    expect(config.defaultPlatform).toBe("qq");
+    const res = await request(app).post("/api/bot/settings").send({ defaultPlatform: null });
+    expect(res.body.defaultPlatform).toBeNull();
+    expect(config.defaultPlatform).toBeNull();
+  });
+
+  it("POST /settings drops a default whose source gets disabled in the same request", async () => {
+    const app = mountBot();
+    await request(app).post("/api/bot/settings").send({ defaultPlatform: "qq" });
+    expect(config.defaultPlatform).toBe("qq");
+    // Disabling qq via enabledProviders clears the now-invalid default.
+    const res = await request(app).post("/api/bot/settings").send({
+      enabledProviders: ["netease", "bilibili"],
+    });
+    expect(res.body.defaultPlatform).toBeNull();
+    expect(config.defaultPlatform).toBeNull();
+  });
 });

src/web/api/bot.ts

@@ -72,11 +72,14 @@ export function createBotRouter(
       idleTimeoutMinutes: config.idleTimeoutMinutes ?? 0,
       autoPauseOnEmpty: config.autoPauseOnEmpty,
       localAudioEnabled: config.localAudioEnabled,
+      savedQueuesEnabled: config.savedQueuesEnabled,
+      playKeepsQueue: config.playKeepsQueue,
       adminGroups: config.adminGroups ?? [],
       guestMode: config.guestMode,
       spotify: maskedSpotify(),
       jellyfin: maskedJellyfin(),
       enabledProviders: config.enabledProviders,
+      defaultPlatform: config.defaultPlatform,
     });
   });
 
@@ -98,6 +101,16 @@ export function createBotRouter(
     if (hasAutoPause) config.autoPauseOnEmpty = autoPauseOnEmpty;
     if (hasLocalAudioEnabled) config.localAudioEnabled = localAudioEnabled;
 
+    // Saved-queues + play-keeps-queue toggles (default off). Both read live from
+    // config by BotInstance / the saved-queues router, so no per-bot push needed;
+    // only a literal boolean mutates the stored value (junk is ignored).
+    if (typeof req.body.savedQueuesEnabled === "boolean") {
+      config.savedQueuesEnabled = req.body.savedQueuesEnabled;
+    }
+    if (typeof req.body.playKeepsQueue === "boolean") {
+      config.playKeepsQueue = req.body.playKeepsQueue;
+    }
+
     const hasGuestMode = guestMode !== undefined && guestMode !== null && typeof guestMode === "object";
     if (hasGuestMode) {
       const gm = config.guestMode;
@@ -175,6 +188,29 @@ export function createBotRouter(
       );
     }
 
+    // defaultPlatform (issue #126): the operator-chosen default source for
+    // platform-less commands/REST/WebUI calls. Reconciled AFTER enabledProviders
+    // so both are validated against the same (possibly updated) enabled list:
+    //   1) Drop a stored default that the new enabledProviders no longer allows,
+    //      keeping the persisted config consistent with loadConfig's invariant.
+    //   2) Apply an explicit change — `null`/`""` clears it (back to priority
+    //      order); a known+enabled provider sets it; anything else is ignored.
+    if (config.defaultPlatform && !config.enabledProviders.includes(config.defaultPlatform)) {
+      config.defaultPlatform = null;
+    }
+    if ("defaultPlatform" in req.body) {
+      const dp = req.body.defaultPlatform;
+      if (dp === null || dp === "") {
+        config.defaultPlatform = null;
+      } else if (
+        typeof dp === "string" &&
+        (GATEABLE_PROVIDERS as readonly string[]).includes(dp) &&
+        config.enabledProviders.includes(dp as GateableProvider)
+      ) {
+        config.defaultPlatform = dp as GateableProvider;
+      }
+    }
+
     saveConfig(configPath, config);
 
     // Hot-apply the (possibly re-pointed) Jellyfin connection to the live
@@ -214,11 +250,14 @@ export function createBotRouter(
       idleTimeoutMinutes: config.idleTimeoutMinutes ?? 0,
       autoPauseOnEmpty: config.autoPauseOnEmpty,
       localAudioEnabled: config.localAudioEnabled,
+      savedQueuesEnabled: config.savedQueuesEnabled,
+      playKeepsQueue: config.playKeepsQueue,
       adminGroups: config.adminGroups ?? [],
       guestMode: config.guestMode,
       spotify: maskedSpotify(),
       jellyfin: maskedJellyfin(),
       enabledProviders: config.enabledProviders,
+      defaultPlatform: config.defaultPlatform,
     });
   });
 

src/web/api/music.test.ts

@@ -1,9 +1,19 @@
-import { describe, it, expect, vi, beforeEach } from "vitest";
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
 import express from "express";
+import cookieParser from "cookie-parser";
 import request from "supertest";
 import pino from "pino";
+import { mkdtempSync, rmSync, readFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
 import type { MusicProvider, SearchResult } from "../../music/provider.js";
-import { getDefaultConfig, type BotConfig } from "../../data/config.js";
+import { getDefaultConfig, loadConfig, type BotConfig } from "../../data/config.js";
+import { createDatabase, type BotDatabase } from "../../data/database.js";
+import { createUserStore } from "../../data/users.js";
+import { createSessionStore } from "../../data/sessions.js";
+import { createPermissionStore } from "../../data/permissions.js";
+import { createRequireAuth } from "../middleware/requireAuth.js";
+import { SESSION_COOKIE_NAME } from "../auth/validateSession.js";
 import { createMusicRouter } from "./music.js";
 
 const empty: SearchResult = { songs: [], albums: [], playlists: [] };
@@ -82,44 +92,70 @@ describe("music router provider gating (enabledProviders) + jellyfin endpoints",
     return { app, netease, jellyfin };
   }
 
-  it("routes a platform-less /search to the default platform (jellyfin)", async () => {
+  it("routes a platform-less /search to the default platform (netease)", async () => {
     const { app, netease, jellyfin } = mount(getDefaultConfig());
     const res = await request(app).get("/api/music/search?q=hello");
     expect(res.status).toBe(200);
-    expect(jellyfin.search).toHaveBeenCalledWith("hello", 20, 0);
+    expect(netease.search).toHaveBeenCalledWith("hello", 20, 0);
-    expect(netease.search).not.toHaveBeenCalled();
+    expect(jellyfin.search).not.toHaveBeenCalled();
   });
 
   it("rejects a disabled platform with 400 without calling its provider", async () => {
-    // Default config enables jellyfin only.
+    // Default config leaves jellyfin (opt-in) disabled.
-    const { app, netease } = mount(getDefaultConfig());
+    const { app, jellyfin } = mount(getDefaultConfig());
-    const res = await request(app).get("/api/music/search?q=hello&platform=netease");
+    const res = await request(app).get("/api/music/search?q=hello&platform=jellyfin");
     expect(res.status).toBe(400);
-    expect(netease.search).not.toHaveBeenCalled();
+    expect(jellyfin.search).not.toHaveBeenCalled();
   });
 
-  it("allows an explicitly re-enabled legacy platform", async () => {
+  it("allows an explicitly enabled jellyfin platform", async () => {
     const config = getDefaultConfig();
-    config.enabledProviders = ["jellyfin", "netease"];
+    config.enabledProviders = [...config.enabledProviders, "jellyfin"];
-    const { app, netease } = mount(config);
+    const { app, jellyfin } = mount(config);
-    const res = await request(app).get("/api/music/search?q=hello&platform=netease");
+    const res = await request(app).get("/api/music/search?q=hello&platform=jellyfin");
     expect(res.status).toBe(200);
-    expect(netease.search).toHaveBeenCalledWith("hello", 20, 0);
+    expect(jellyfin.search).toHaveBeenCalledWith("hello", 20, 0);
   });
 
   it("GET /providers reports enabled sources and the default platform", async () => {
     const { app } = mount(getDefaultConfig());
     const res = await request(app).get("/api/music/providers");
     expect(res.status).toBe(200);
-    expect(res.body.default).toBe("jellyfin");
+    expect(res.body.default).toBe("netease");
-    expect(res.body.enabled).toContain("jellyfin");
+    expect(res.body.enabled).toContain("netease");
     expect(res.body.enabled).toContain("local"); // localAudioEnabled defaults on
-    expect(res.body.enabled).not.toContain("netease");
+    expect(res.body.enabled).not.toContain("jellyfin"); // opt-in, off by default
     expect(res.body.enabled).not.toContain("spotify"); // spotify.enabled defaults off
   });
 
+  it("GET /providers reports a configured defaultPlatform override (#126)", async () => {
+    const config = getDefaultConfig();
+    config.defaultPlatform = "qq"; // operator prefers QQ over the priority order
+    const { app } = mount(config);
+    const res = await request(app).get("/api/music/providers");
+    expect(res.status).toBe(200);
+    expect(res.body.default).toBe("qq");
+  });
+
+  it("routes a platform-less /search to the configured defaultPlatform (#126)", async () => {
+    const config = getDefaultConfig();
+    config.defaultPlatform = "bilibili";
+    const { app, netease } = mount(config);
+    const res = await request(app).get("/api/music/search?q=hello");
+    expect(res.status).toBe(200);
+    // Default is now bilibili, so the netease provider must NOT be hit.
+    expect(netease.search).not.toHaveBeenCalled();
+  });
+
+  /** Default config plus the opt-in jellyfin source enabled. */
+  function configWithJellyfin() {
+    const config = getDefaultConfig();
+    config.enabledProviders = [...config.enabledProviders, "jellyfin"];
+    return config;
+  }
+
   it("GET /jellyfin/latest-albums returns provider data", async () => {
-    const { app, jellyfin } = mount(getDefaultConfig());
+    const { app, jellyfin } = mount(configWithJellyfin());
     const res = await request(app).get("/api/music/jellyfin/latest-albums?limit=5");
     expect(res.status).toBe(200);
     expect(
@@ -128,17 +164,134 @@ describe("music router provider gating (enabledProviders) + jellyfin endpoints",
     expect(res.body.albums).toHaveLength(1);
   });
 
-  it("GET /jellyfin/latest-albums is 400 when jellyfin is disabled", async () => {
+  it("GET /jellyfin/latest-albums is 400 when jellyfin is disabled (the default)", async () => {
-    const config = getDefaultConfig();
+    const { app } = mount(getDefaultConfig());
-    config.enabledProviders = ["netease"];
-    const { app } = mount(config);
     const res = await request(app).get("/api/music/jellyfin/latest-albums");
     expect(res.status).toBe(400);
   });
 
   it("GET /jellyfin/favorites denies unauthenticated/guest access", async () => {
-    const { app } = mount(getDefaultConfig());
+    const { app } = mount(configWithJellyfin());
     const res = await request(app).get("/api/music/jellyfin/favorites");
     expect(res.status).toBe(401);
   });
 });
+
+describe("music router POST /quality — persistence (#125)", () => {
+  let tmpDir: string;
+  let configPath: string;
+  let config: BotConfig;
+  let botDb: BotDatabase;
+  let app: express.Express;
+  let cookie: string;
+  let providers: Record<string, MusicProvider>;
+
+  /** A provider whose in-memory quality is settable and readable, like the real
+   *  ones. */
+  function qualityProvider(platform: MusicProvider["platform"], initial: string): MusicProvider {
+    let q = initial;
+    return {
+      platform,
+      search: vi.fn().mockResolvedValue(empty),
+      getQuality: vi.fn(() => q),
+      setQuality: vi.fn((v: string) => { q = v; }),
+    } as unknown as MusicProvider;
+  }
+
+  /** Jellyfin only accepts its own tiers (mirrors the real provider), so a
+   *  broadcast of a foreign value is ignored — proving the snapshot captures each
+   *  provider's ACTUAL post-apply state, not just the request value. */
+  function jellyfinQualityProvider(): MusicProvider {
+    let q = "direct";
+    const tiers = new Set(["direct", "320", "192", "128"]);
+    return {
+      platform: "jellyfin",
+      search: vi.fn().mockResolvedValue(empty),
+      getQuality: vi.fn(() => q),
+      setQuality: vi.fn((v: string) => { if (tiers.has(v)) q = v; }),
+    } as unknown as MusicProvider;
+  }
+
+  beforeEach(async () => {
+    botDb = createDatabase(":memory:");
+    const users = createUserStore(botDb.db);
+    const sessions = createSessionStore(botDb.db);
+    const admin = await users.createUser("admin", "pw-admin", "admin");
+    cookie = `${SESSION_COOKIE_NAME}=${sessions.createSession(admin.id).token}`;
+
+    tmpDir = mkdtempSync(join(tmpdir(), "musicquality-"));
+    configPath = join(tmpDir, "config.json");
+    config = getDefaultConfig();
+
+    providers = {
+      netease: qualityProvider("netease", "exhigh"),
+      qq: qualityProvider("qq", "exhigh"),
+      bilibili: qualityProvider("bilibili", "high"),
+      kugou: qualityProvider("kugou", "128"),
+      jellyfin: jellyfinQualityProvider(),
+    };
+
+    app = express();
+    app.use(express.json());
+    app.use(cookieParser());
+    app.use("/api", createRequireAuth(sessions, createPermissionStore(botDb.db), () => getDefaultConfig().guestMode));
+    app.use(
+      "/api/music",
+      createMusicRouter(
+        providers.netease, providers.qq, providers.bilibili, pino({ level: "silent" }),
+        undefined, config, providers.kugou, undefined, providers.jellyfin, configPath,
+      ),
+    );
+  });
+
+  afterEach(() => {
+    botDb.close();
+    rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  it("persists a platform-specific quality change to config.json", async () => {
+    const res = await request(app)
+      .post("/api/music/quality")
+      .set("Cookie", cookie)
+      .send({ platform: "netease", quality: "lossless" });
+    expect(res.status).toBe(200);
+    expect(providers.netease.setQuality).toHaveBeenCalledWith("lossless");
+    // in-memory config mutated
+    expect(config.audioQuality.netease).toBe("lossless");
+    // written to disk + reload reflects it (survives a restart)
+    const onDisk = JSON.parse(readFileSync(configPath, "utf-8"));
+    expect(onDisk.audioQuality.netease).toBe("lossless");
+    expect(loadConfig(configPath).audioQuality.netease).toBe("lossless");
+  });
+
+  it("snapshots each provider's post-apply quality on a broadcast change", async () => {
+    const res = await request(app)
+      .post("/api/music/quality")
+      .set("Cookie", cookie)
+      .send({ quality: "320" });
+    expect(res.status).toBe(200);
+    // Broadcast reached every provider…
+    expect(providers.netease.setQuality).toHaveBeenCalledWith("320");
+    expect(providers.jellyfin.setQuality).toHaveBeenCalledWith("320");
+    // …and the snapshot reflects what each one actually accepted. Jellyfin's
+    // "320" is a valid tier here, so it takes; a foreign value would be ignored.
+    expect(config.audioQuality).toEqual({
+      netease: "320",
+      qq: "320",
+      bilibili: "320",
+      kugou: "320",
+      jellyfin: "320",
+    });
+  });
+
+  it("ignores foreign broadcast values that a provider rejects (jellyfin)", async () => {
+    const res = await request(app)
+      .post("/api/music/quality")
+      .set("Cookie", cookie)
+      .send({ quality: "lossless" });
+    expect(res.status).toBe(200);
+    // jellyfin rejects the NetEase-style value → stays at its default tier.
+    expect(config.audioQuality.jellyfin).toBe("direct");
+    expect(config.audioQuality.netease).toBe("lossless");
+  });
+});

src/web/api/music.ts

@@ -2,7 +2,7 @@ import express, { Router, type Response } from "express";
 import type { MusicProvider, Song, Album } from "../../music/provider.js";
 import { YouTubeProvider } from "../../music/youtube.js";
 import type { Logger } from "../../logger.js";
-import { isProviderEnabled, defaultPlatform, type BotConfig } from "../../data/config.js";
+import { isProviderEnabled, defaultPlatform, saveConfig, type BotConfig } from "../../data/config.js";
 import { requirePermission } from "../middleware/requirePermission.js";
 import { requireNotGuest } from "../middleware/requireNotGuest.js";
 import { authorize } from "../middleware/authorize.js";
@@ -16,7 +16,10 @@ export function createMusicRouter(
   config?: BotConfig,
   kugouProvider?: MusicProvider,
   spotifyProvider?: MusicProvider,
-  jellyfinProvider?: MusicProvider
+  jellyfinProvider?: MusicProvider,
+  // When set (alongside config), a quality change is persisted to config.json so
+  // it survives a restart (#125). Omitted by unit-test routers → no persistence.
+  configPath?: string,
 ): Router {
   const router = Router();
   const youtubeProvider: MusicProvider = new YouTubeProvider();
@@ -37,9 +40,10 @@ export function createMusicRouter(
 
   /**
    * Provider gating for user-supplied platform params. No platform → the
-   * configured default (jellyfin unless disabled). A disabled platform gets a
+   * configured default (see defaultPlatform(); netease in the default config).
-   * friendly 400 and null back — the handler must return immediately.
+   * A disabled platform gets a friendly 400 and null back — the handler must
-   * Without a config (unit-test routers), everything stays enabled.
+   * return immediately. Without a config (unit-test routers), everything
+   * stays enabled.
    */
   function resolveProvider(platform: unknown, res: Response): MusicProvider | null {
     const requested = typeof platform === "string" && platform ? platform : undefined;
@@ -144,7 +148,8 @@ export function createMusicRouter(
       // view would only yield results that get skipped. Spotify search remains
       // available from its own tab via /search?platform=spotify.
       // Provider gating (#enabledProviders): disabled sources are skipped, not
-      // searched. Jellyfin — the primary source — leads the merged results.
+      // searched. Jellyfin (an opt-in source) leads the merged results when
+      // enabled — a self-hosted library match is almost always the wanted one.
       const enabled = (p: string) => !config || isProviderEnabled(config, p);
       const none = { songs: [], albums: [], playlists: [] };
       const [jellyfinResult, neteaseResult, qqResult, bilibiliResult, localResult, kugouResult] = await Promise.allSettled([
@@ -478,6 +483,26 @@ export function createMusicRouter(
     if ((!platform || platform === "jellyfin") && jellyfinProvider) {
       jellyfinProvider.setQuality(quality);
     }
+
+    // Persist the (post-apply) per-provider quality so it survives a restart
+    // (#125). Snapshotting each provider's getQuality() AFTER setQuality captures
+    // exactly what each one accepted (jellyfin ignores foreign tiers, kugou maps
+    // aliases), so replaying these on startup reproduces this state faithfully.
+    if (config && configPath) {
+      config.audioQuality = {
+        netease: neteaseProvider.getQuality(),
+        qq: qqProvider.getQuality(),
+        bilibili: bilibiliProvider.getQuality(),
+        kugou: kugouProvider?.getQuality() ?? config.audioQuality.kugou,
+        jellyfin: jellyfinProvider?.getQuality() ?? config.audioQuality.jellyfin,
+      };
+      try {
+        saveConfig(configPath, config);
+      } catch (err) {
+        logger.warn({ err }, "Failed to persist audio quality");
+      }
+    }
+
     logger.info({ quality, platform }, "Audio quality changed");
     res.json({ success: true, quality });
   });

src/web/api/player.ts

@@ -461,7 +461,11 @@ export function createPlayerRouter(
     }
   });
 
-  // Play a single song by ID — resolves URL on demand
+  // Play a single song by ID — resolves URL on demand. Funnels through
+  // bot.playSingleSong so the config.playKeepsQueue decision (clear-and-play vs
+  // insert-and-jump, keeping the queue) lives in one place shared with chat
+  // !play. Serialized via runExclusive like /play-now-song so concurrent
+  // requests can't interleave the queue mutation + playback (#119).
   router.post("/:botId/play-song", authorize({ capability: "player.control" }), async (req, res) => {
     try {
       const bot = (req as any).bot;
@@ -474,23 +478,16 @@ export function createPlayerRouter(
         rejectDisabledLocalAudio(res);
         return;
       }
-      const queue = bot.getQueueManager();
+      // The cleanupQueuedLocalSongs sweep now lives inside playSingleSong's
-      bot.getPlayer().stop();
+      // clear branch — do NOT also call it here, or it would delete retained
-      queue.clear();
+      // local uploads in keep-queue mode.
-      queue.add({ ...song, requestedBy: requesterName(req) });
+      const body = await bot.runExclusive(async () => {
-      queue.play();
+        const ok = await bot.playSingleSong({ ...song }, requesterName(req));
-
+        return ok
-      bot.getPlayer().resetFailures();
+          ? { ok: true, message: `正在播放：${song.name || 'Unknown'} - ${song.artist || 'Unknown'}` }
-      const ok = await bot.resolveAndPlay(queue.current()!);
+          : { ok: false, message: `无法播放「${song.name || song.id}」（区域/版权限制）` };
-      // Sweep AFTER the new song is queued+resolved, so replaying a local song
+      });
-      // that was still in the queue doesn't delete the file we're about to play.
+      res.json(body);
-      bot.cleanupQueuedLocalSongs?.("queue_replaced");
-      if (!ok) {
-        res.json({ ok: false, message: `无法播放「${song.name || song.id}」（区域/版权限制）` });
-        return;
-      }
-
-      res.json({ ok: true, message: `正在播放：${song.name || 'Unknown'} - ${song.artist || 'Unknown'}` });
     } catch (err) {
       res.status(500).json({ error: (err as Error).message });
     }

src/web/api/saved-queues.test.ts

@@ -0,0 +1,119 @@
+import { describe, it, expect } from "vitest";
+import express from "express";
+import request from "supertest";
+import pino from "pino";
+import { createDatabase, SHARED_QUEUE_OWNER, type BotDatabase } from "../../data/database.js";
+import type { BotManager } from "../../bot/manager.js";
+import { createSavedQueuesRouter } from "./saved-queues.js";
+
+const song = (id: string) => ({
+  id,
+  name: id,
+  artist: "",
+  album: "",
+  platform: "netease" as const,
+  coverUrl: "",
+  duration: 1,
+});
+
+function mount(enabled: boolean, opts: { queue?: unknown[] } = {}) {
+  const db = createDatabase(":memory:");
+  const loads: Array<{ songs: unknown[]; mode: string; by?: string }> = [];
+  const bot = {
+    getQueueManager: () => ({ list: () => opts.queue ?? [song("a"), song("b")] }),
+    loadSavedQueue: async (songs: unknown[], mode: string, by?: string) => {
+      loads.push({ songs, mode, by });
+    },
+  };
+  const botManager = { getBot: (_id: string) => bot } as unknown as BotManager;
+  const app = express();
+  app.use(express.json());
+  app.use((req, _res, next) => {
+    (req as unknown as { user: unknown }).user = { id: "u1", username: "alice", role: "member" };
+    next();
+  });
+  app.use(
+    "/api/saved-queues",
+    createSavedQueuesRouter(db, botManager, () => enabled, pino({ level: "silent" })),
+  );
+  return { app, db, loads };
+}
+
+describe("saved-queues router", () => {
+  it("403s every route when the feature is disabled", async () => {
+    const { app } = mount(false);
+    expect((await request(app).get("/api/saved-queues")).status).toBe(403);
+    expect((await request(app).post("/api/saved-queues").send({ botId: "b", name: "x" })).status).toBe(403);
+    expect((await request(app).post("/api/saved-queues/1/load").send({ botId: "b" })).status).toBe(403);
+    expect((await request(app).delete("/api/saved-queues/1")).status).toBe(403);
+  });
+
+  it("saves the current queue (private) and lists it back", async () => {
+    const { app } = mount(true);
+    const save = await request(app).post("/api/saved-queues").send({ botId: "b", name: "night" });
+    expect(save.status).toBe(200);
+    expect(save.body.queue.name).toBe("night");
+    expect(save.body.queue.songCount).toBe(2);
+    expect(save.body.queue.ownerId).toBe("u1");
+
+    const list = await request(app).get("/api/saved-queues");
+    expect(list.status).toBe(200);
+    expect(list.body.queues.map((q: { name: string }) => q.name)).toContain("night");
+  });
+
+  it("saves to the shared bucket when shared:true", async () => {
+    const { app, db } = mount(true);
+    const save = await request(app).post("/api/saved-queues").send({ botId: "b", name: "party", shared: true });
+    expect(save.status).toBe(200);
+    expect(save.body.queue.ownerId).toBe(SHARED_QUEUE_OWNER);
+    expect(db.listSavedQueues(SHARED_QUEUE_OWNER, false).map((q) => q.name)).toEqual(["party"]);
+  });
+
+  it("rejects saving an empty queue", async () => {
+    const { app } = mount(true, { queue: [] });
+    const save = await request(app).post("/api/saved-queues").send({ botId: "b", name: "empty" });
+    expect(save.status).toBe(400);
+  });
+
+  it("requires botId and name", async () => {
+    const { app } = mount(true);
+    expect((await request(app).post("/api/saved-queues").send({ name: "x" })).status).toBe(400);
+    expect((await request(app).post("/api/saved-queues").send({ botId: "b" })).status).toBe(400);
+  });
+
+  it("loads a shared queue (replace by default) into the bot", async () => {
+    const { app, db, loads } = mount(true);
+    const saved = db.saveQueue(SHARED_QUEUE_OWNER, "party", [song("a"), song("b")]);
+    const load = await request(app).post(`/api/saved-queues/${saved.id}/load`).send({ botId: "b" });
+    expect(load.status).toBe(200);
+    expect(load.body).toMatchObject({ ok: true, loaded: 2, mode: "replace" });
+    expect(loads).toHaveLength(1);
+    expect(loads[0].mode).toBe("replace");
+    expect(loads[0].by).toBe("alice");
+  });
+
+  it("loads in append mode when requested", async () => {
+    const { app, db, loads } = mount(true);
+    const saved = db.saveQueue("u1", "mine", [song("a")]);
+    const load = await request(app).post(`/api/saved-queues/${saved.id}/load`).send({ botId: "b", mode: "append" });
+    expect(load.status).toBe(200);
+    expect(loads[0].mode).toBe("append");
+  });
+
+  it("404s loading another user's private queue (no existence leak)", async () => {
+    const { app, db } = mount(true);
+    db.saveQueue("someoneElse", "private", [song("z")]);
+    const other = db.listSavedQueues("someoneElse", false)[0];
+    const load = await request(app).post(`/api/saved-queues/${other.id}/load`).send({ botId: "b", mode: "replace" });
+    expect(load.status).toBe(404);
+  });
+
+  it("deletes an own queue but 404s another user's private one", async () => {
+    const { app, db } = mount(true);
+    const mine = db.saveQueue("u1", "mine", [song("a")]);
+    const theirs = db.saveQueue("someoneElse", "private", [song("z")]);
+    expect((await request(app).delete(`/api/saved-queues/${theirs.id}`)).status).toBe(404);
+    expect((await request(app).delete(`/api/saved-queues/${mine.id}`)).status).toBe(200);
+    expect(db.getSavedQueue(mine.id)).toBeNull();
+  });
+});

src/web/api/saved-queues.ts

@@ -0,0 +1,122 @@
+import { Router } from "express";
+import type { BotDatabase } from "../../data/database.js";
+import { SHARED_QUEUE_OWNER } from "../../data/database.js";
+import type { BotManager } from "../../bot/manager.js";
+import type { Logger } from "../../logger.js";
+
+/**
+ * The /api/saved-queues router (Feature 1, #119). Named save/load of queues,
+ * per-user with a reserved shared bucket. Every route is inert (403) unless
+ * savedQueuesEnabled is on, so the feature is fully gated behind the admin flag.
+ *
+ * Ownership model:
+ *  - WebUI save with `shared:true` → SHARED_QUEUE_OWNER; otherwise the caller's
+ *    own user id (private to them).
+ *  - list returns the caller's own queues + shared ones.
+ *  - load/delete are allowed only for the caller's own queues or shared ones;
+ *    another user's private queue 404s (no existence leak, matching favorites).
+ */
+export function createSavedQueuesRouter(
+  database: BotDatabase,
+  botManager: BotManager,
+  isEnabled: () => boolean,
+  logger: Logger,
+): Router {
+  const router = Router();
+
+  // Feature gate — inert (403) when savedQueuesEnabled is false.
+  router.use((_req, res, next) => {
+    if (!isEnabled()) {
+      res.status(403).json({ error: "此功能未启用" });
+      return;
+    }
+    next();
+  });
+
+  // GET / — the caller's own + shared saved queues (meta only, no songs blob).
+  router.get("/", (req, res) => {
+    const userId = req.user!.id;
+    res.json({ queues: database.listSavedQueues(userId, true) });
+  });
+
+  // POST / — snapshot a bot's CURRENT queue and upsert it.
+  // body: { botId, name, shared? }
+  router.post("/", (req, res) => {
+    const userId = req.user!.id;
+    const { botId, name, shared } = req.body ?? {};
+    if (typeof name !== "string" || !name.trim() || typeof botId !== "string" || !botId) {
+      res.status(400).json({ error: "botId and name are required" });
+      return;
+    }
+    const bot = botManager.getBot(botId);
+    if (!bot) {
+      res.status(404).json({ error: "bot not found" });
+      return;
+    }
+    const songs = bot.getQueueManager().list();
+    if (songs.length === 0) {
+      res.status(400).json({ error: "队列为空，无法保存" });
+      return;
+    }
+    const ownerId = shared === true ? SHARED_QUEUE_OWNER : userId;
+    try {
+      const saved = database.saveQueue(ownerId, name.trim(), songs);
+      logger.info({ userId, ownerId, name: saved.name, count: saved.songCount }, "saved queue upserted");
+      res.json({
+        queue: {
+          id: saved.id,
+          ownerId: saved.ownerId,
+          name: saved.name,
+          songCount: saved.songCount,
+        },
+      });
+    } catch (err) {
+      res.status(400).json({ error: (err as Error).message });
+    }
+  });
+
+  // POST /:id/load — load a saved queue into a bot. body: { botId, mode }
+  router.post("/:id/load", async (req, res) => {
+    const userId = req.user!.id;
+    const username = req.user!.username;
+    const id = parseInt(req.params.id, 10);
+    const { botId, mode } = req.body ?? {};
+    if (Number.isNaN(id) || typeof botId !== "string" || !botId) {
+      res.status(400).json({ error: "invalid id/botId" });
+      return;
+    }
+    const sq = database.getSavedQueue(id);
+    if (!sq || (sq.ownerId !== userId && sq.ownerId !== SHARED_QUEUE_OWNER)) {
+      res.status(404).json({ error: "not found" });
+      return;
+    }
+    const bot = botManager.getBot(botId);
+    if (!bot) {
+      res.status(404).json({ error: "bot not found" });
+      return;
+    }
+    const loadMode = mode === "append" ? "append" : "replace";
+    await bot.loadSavedQueue(sq.songs, loadMode, username || "游客");
+    res.json({ ok: true, loaded: sq.songs.length, mode: loadMode });
+  });
+
+  // DELETE /:id — delete a saved queue (own or shared only).
+  router.delete("/:id", (req, res) => {
+    const userId = req.user!.id;
+    const id = parseInt(req.params.id, 10);
+    if (Number.isNaN(id)) {
+      res.status(400).json({ error: "invalid id" });
+      return;
+    }
+    const sq = database.getSavedQueue(id);
+    if (!sq || (sq.ownerId !== userId && sq.ownerId !== SHARED_QUEUE_OWNER)) {
+      res.status(404).json({ error: "not found" });
+      return;
+    }
+    database.deleteSavedQueue(id);
+    logger.info({ userId, id }, "saved queue deleted");
+    res.json({ ok: true });
+  });
+
+  return router;
+}

src/web/robots.test.ts

@@ -0,0 +1,86 @@
+import { describe, it, expect } from "vitest";
+import express from "express";
+import request from "supertest";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+/**
+ * Search-engine hardening for issue #128: searching "TsmusicBot" surfaced a
+ * large number of deployed instances' WebUI URLs, letting strangers walk into
+ * other people's control pages. The fix is defence in depth — none of these
+ * layers is authentication (that's handled elsewhere), they just keep the
+ * public URL out of crawler indexes:
+ *
+ *   1. `X-Robots-Tag: noindex, nofollow` on EVERY response;
+ *   2. `GET /robots.txt` → `User-agent: * / Disallow: /`;
+ *   3. `<meta name="robots" content="noindex, nofollow">` in web/index.html.
+ *
+ * The header middleware and the /robots.txt route both live at the top of
+ * `createWebServer` in `server.ts`; this test asserts the exact behaviour we
+ * expect from them in isolation (the wiring inside server.ts is verified by
+ * code review / git diff, matching security-headers.test.ts).
+ */
+describe("search-engine hardening (issue #128 noindex)", () => {
+  function buildApp() {
+    const app = express();
+    // Mirrors the security-headers middleware in server.ts.
+    app.use((_req, res, next) => {
+      res.setHeader("X-Frame-Options", "DENY");
+      res.setHeader("Content-Security-Policy", "frame-ancestors 'none'");
+      res.setHeader("X-Robots-Tag", "noindex, nofollow");
+      next();
+    });
+    // Mirrors the public /robots.txt route in server.ts.
+    app.get("/robots.txt", (_req, res) => {
+      res.type("text/plain").send("User-agent: *\nDisallow: /\n");
+    });
+    app.get("/", (_req, res) => res.json({ ok: true }));
+    app.post("/api/session/login", (_req, res) => res.json({ ok: true }));
+    return app;
+  }
+
+  it("sets X-Robots-Tag: noindex, nofollow on GET responses", async () => {
+    const res = await request(buildApp()).get("/");
+    expect(res.status).toBe(200);
+    expect(res.headers["x-robots-tag"]).toBe("noindex, nofollow");
+  });
+
+  it("sets X-Robots-Tag on POST (API) responses too", async () => {
+    const res = await request(buildApp()).post("/api/session/login");
+    expect(res.headers["x-robots-tag"]).toBe("noindex, nofollow");
+  });
+
+  it("serves /robots.txt disallowing all crawlers", async () => {
+    const res = await request(buildApp()).get("/robots.txt");
+    expect(res.status).toBe(200);
+    expect(res.headers["content-type"]).toMatch(/text\/plain/);
+    expect(res.text).toContain("User-agent: *");
+    expect(res.text).toContain("Disallow: /");
+  });
+
+  it("still tags the /robots.txt response itself as noindex", async () => {
+    const res = await request(buildApp()).get("/robots.txt");
+    expect(res.headers["x-robots-tag"]).toBe("noindex, nofollow");
+  });
+});
+
+describe("frontend robots meta tag (issue #128 noindex)", () => {
+  const indexHtmlPath = path.resolve(
+    path.dirname(fileURLToPath(import.meta.url)),
+    "../../web/index.html"
+  );
+  const html = fs.readFileSync(indexHtmlPath, "utf-8");
+
+  const robotsMeta = html.match(
+    /<meta\s+name=["']robots["']\s+content=["']([^"']+)["']\s*\/?>/i
+  );
+
+  it("declares a robots meta tag", () => {
+    expect(robotsMeta).not.toBeNull();
+  });
+
+  it("marks the SPA shell noindex, nofollow (covers /bot/<id> dedicated links)", () => {
+    expect(robotsMeta?.[1]).toBe("noindex, nofollow");
+  });
+});

src/web/server.ts

@@ -19,6 +19,7 @@ import { createUsersRouter } from "./api/users.js";
 import { createAuditStore } from "../data/audit.js";
 import { createAuditRouter } from "./api/audit.js";
 import { createFavoritesRouter } from "./api/favorites.js";
+import { createSavedQueuesRouter } from "./api/saved-queues.js";
 import { createSpotifyRouter } from "./api/spotify.js";
 import type { SpotifyOAuth } from "../music/spotify/spotify-oauth.js";
 import type { SpotifyProvider } from "../music/spotify/provider.js";
@@ -77,12 +78,19 @@ export function createWebServer(options: WebServerOptions): WebServer {
     app.set("trust proxy", true);
   }
 
-  // Security headers: prevent the WebUI from being embedded in a third-party
+  // Security headers:
-  // iframe (clickjacking defence). CSP frame-ancestors is the modern equivalent
+  //  • X-Frame-Options / CSP frame-ancestors — prevent the WebUI from being
-  // of X-Frame-Options; both are set for compatibility across browsers.
+  //    embedded in a third-party iframe (clickjacking defence). CSP
+  //    frame-ancestors is the modern equivalent of X-Frame-Options; both are
+  //    set for compatibility across browsers.
+  //  • X-Robots-Tag — keep deployed instances out of search-engine indexes
+  //    (issue #128: searching "TsmusicBot" surfaced strangers' WebUI URLs).
+  //    Set on EVERY response so JSON/API responses and the SPA shell are all
+  //    covered; complements /robots.txt and the <meta name="robots"> tag.
   app.use((_req, res, next) => {
     res.setHeader("X-Frame-Options", "DENY");
     res.setHeader("Content-Security-Policy", "frame-ancestors 'none'");
+    res.setHeader("X-Robots-Tag", "noindex, nofollow");
     next();
   });
 
@@ -95,6 +103,13 @@ export function createWebServer(options: WebServerOptions): WebServer {
   const permissions = createPermissionStore(options.database.db);
 
   // ─── Public routes (no auth, no CSRF) ───────────────────────────────────
+  // Disallow every crawler (issue #128). Declared before the static SPA
+  // fallback so this wins over index.html for /robots.txt. Belt-and-braces
+  // with the X-Robots-Tag header above and the <meta name="robots"> tag.
+  app.get("/robots.txt", (_req, res) => {
+    res.type("text/plain").send("User-agent: *\nDisallow: /\n");
+  });
+
   app.get("/api/health", (_req, res) => {
     res.json({ status: "ok", version: "0.1.0" });
   });
@@ -151,7 +166,7 @@ export function createWebServer(options: WebServerOptions): WebServer {
   );
   app.use(
     "/api/music",
-    createMusicRouter(options.neteaseProvider, options.qqProvider, options.bilibiliProvider, logger, options.localProvider, options.config, options.kugouProvider, options.spotifyProvider, options.jellyfinProvider)
+    createMusicRouter(options.neteaseProvider, options.qqProvider, options.bilibiliProvider, logger, options.localProvider, options.config, options.kugouProvider, options.spotifyProvider, options.jellyfinProvider, options.configPath)
   );
   app.use("/api/player", createPlayerRouter(
     options.botManager, logger, options.database,
@@ -188,6 +203,18 @@ export function createWebServer(options: WebServerOptions): WebServer {
     );
   }
   app.use("/api/favorites", requireNotGuest, createFavoritesRouter(options.database, logger));
+  // Saved queues (Feature 1, #119). Members + admins only (requireNotGuest);
+  // the router itself 403s every route unless savedQueuesEnabled is on.
+  app.use(
+    "/api/saved-queues",
+    requireNotGuest,
+    createSavedQueuesRouter(
+      options.database,
+      options.botManager,
+      () => options.config.savedQueuesEnabled,
+      logger,
+    ),
+  );
 
   // admin-only routes
   app.use("/api/users", requireAdmin, createUsersRouter(users, sessions, audit, logger, permissions));

web/index.html

@@ -3,6 +3,12 @@
 <head>
   <meta charset="UTF-8">
   <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <!-- Keep deployed instances out of search-engine indexes (issue #128:
+       searching "TsmusicBot" surfaced strangers' WebUI URLs). Defence in depth
+       alongside the server's X-Robots-Tag header and /robots.txt. Applies to
+       the SPA shell and every in-app route (incl. /bot/<id> dedicated links),
+       since they all share this single index.html. -->
+  <meta name="robots" content="noindex, nofollow">
   <!-- Bilibili / NetEase / QQ image CDNs reject requests whose Referer is not on
        their whitelist, so we must not leak a Referer cross-origin. "same-origin"
        does exactly that: full Referer for our own requests, none for cross-origin

web/src/App.vue

@@ -166,6 +166,9 @@ onMounted(async () => {
   // Search or Playlist render hearts correctly without first visiting Home.
   // (fire-and-forget; fetchFavorites swallows the 401 when not yet logged in.)
   playerStore.fetchFavorites();
+  // Non-critical: reads savedQueuesEnabled so the nav entry can show/hide.
+  // Guests get a 403 (swallowed) → the entry stays hidden for them.
+  if (!session.isGuest.value) playerStore.fetchBotSettings();
   syncTimer = setInterval(() => playerStore.syncElapsed(), 3000);
   mobileRaf = requestAnimationFrame(updateMobileProgress);
   // Reconcile the dedicated-link scope only after the bot list is known: the

web/src/components/Navbar.vue

@@ -7,6 +7,12 @@
       <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>
+      <RouterLink
+        v-if="store.savedQueuesEnabled && !session.isGuest.value"
+        to="/saved-queues"
+        class="nav-link"
+        active-class="active"
+      >已存队列</RouterLink>
     </div>
 
     <div class="nav-right">

web/src/composables/savedQueues.test.ts

@@ -0,0 +1,34 @@
+import { describe, it, expect } from 'vitest';
+import { isShared, sortQueues, SHARED_OWNER, type SavedQueueMeta } from './savedQueues';
+
+const meta = (over: Partial<SavedQueueMeta>): SavedQueueMeta => ({
+  id: 1,
+  ownerId: 'u1',
+  name: 'q',
+  songCount: 0,
+  createdAt: '2026-01-01',
+  updatedAt: '2026-01-01',
+  ...over,
+});
+
+describe('savedQueues helper', () => {
+  it('flags the shared owner', () => {
+    expect(isShared({ ownerId: SHARED_OWNER })).toBe(true);
+    expect(isShared({ ownerId: 'u1' })).toBe(false);
+  });
+
+  it('sorts by updatedAt descending (newest first)', () => {
+    const out = sortQueues([
+      meta({ id: 1, updatedAt: '2026-01-01' }),
+      meta({ id: 2, updatedAt: '2026-02-01' }),
+      meta({ id: 3, updatedAt: '2026-01-15' }),
+    ]);
+    expect(out.map((q) => q.id)).toEqual([2, 3, 1]);
+  });
+
+  it('does not mutate the input array', () => {
+    const input = [meta({ id: 1, updatedAt: '2026-01-01' }), meta({ id: 2, updatedAt: '2026-02-01' })];
+    sortQueues(input);
+    expect(input.map((q) => q.id)).toEqual([1, 2]);
+  });
+});

web/src/composables/savedQueues.ts

@@ -0,0 +1,27 @@
+// Pure, framework-free helpers for the Saved Queues feature (#119). Kept
+// separate from the API composable so the list/ownership logic is unit-testable
+// without a DOM or axios.
+
+export interface SavedQueueMeta {
+  id: number;
+  ownerId: string;
+  name: string;
+  songCount: number;
+  createdAt: string;
+  updatedAt: string;
+}
+
+/** Must match SHARED_QUEUE_OWNER in src/data/database.ts. */
+export const SHARED_OWNER = '__shared__';
+
+/** Whether a saved queue lives in the shared bucket (vs. private to a user). */
+export function isShared(q: Pick<SavedQueueMeta, 'ownerId'>): boolean {
+  return q.ownerId === SHARED_OWNER;
+}
+
+/** Newest-updated first; stable for equal timestamps. */
+export function sortQueues<T extends { updatedAt: string }>(qs: T[]): T[] {
+  return [...qs].sort((a, b) =>
+    a.updatedAt < b.updatedAt ? 1 : a.updatedAt > b.updatedAt ? -1 : 0,
+  );
+}

web/src/composables/useSavedQueues.ts

@@ -0,0 +1,52 @@
+import { ref } from 'vue';
+import axios from 'axios';
+import { sortQueues, type SavedQueueMeta } from './savedQueues.js';
+
+/**
+ * API composable for the Saved Queues feature (#119). Wraps /api/saved-queues.
+ * `disabled` becomes true when the server returns 403 (savedQueuesEnabled off),
+ * so the page can render a "feature disabled" state instead of an error.
+ */
+export function useSavedQueues() {
+  const queues = ref<SavedQueueMeta[]>([]);
+  const loading = ref(false);
+  const disabled = ref(false);
+  const error = ref<string | null>(null);
+
+  async function list(): Promise<void> {
+    loading.value = true;
+    error.value = null;
+    try {
+      const res = await axios.get('/api/saved-queues');
+      queues.value = sortQueues((res.data?.queues ?? []) as SavedQueueMeta[]);
+      disabled.value = false;
+    } catch (e: unknown) {
+      const status = (e as { response?: { status?: number } })?.response?.status;
+      if (status === 403) {
+        disabled.value = true;
+        queues.value = [];
+      } else {
+        error.value = '加载已保存队列失败';
+      }
+    } finally {
+      loading.value = false;
+    }
+  }
+
+  async function save(botId: string, name: string, shared: boolean): Promise<void> {
+    await axios.post('/api/saved-queues', { botId, name, shared });
+    await list();
+  }
+
+  async function load(id: number, botId: string, mode: 'replace' | 'append'): Promise<{ loaded: number; mode: string }> {
+    const res = await axios.post(`/api/saved-queues/${id}/load`, { botId, mode });
+    return res.data;
+  }
+
+  async function remove(id: number): Promise<void> {
+    await axios.delete(`/api/saved-queues/${id}`);
+    await list();
+  }
+
+  return { queues, loading, disabled, error, list, save, load, remove };
+}

web/src/router/index.ts

@@ -22,6 +22,7 @@ const router = createRouter({
     },
     { path: '/lyrics', name: 'lyrics', component: () => import('../views/Lyrics.vue') },
     { path: '/history', name: 'history', component: () => import('../views/History.vue') },
+    { path: '/saved-queues', name: 'saved-queues', component: () => import('../views/SavedQueues.vue') },
     { path: '/settings', name: 'settings', component: () => import('../views/Settings.vue') },
     { path: '/setup', name: 'setup', component: () => import('../views/Setup.vue') },
     { path: '/bot/:id', name: 'bot', component: () => import('../views/BotRedirect.vue') },

web/src/stores/player.ts

@@ -113,14 +113,18 @@ export const usePlayerStore = defineStore('player', {
     // Which sources the server has enabled (GET /api/music/providers) and the
     // configured default. Empty until fetched — sections stay hidden briefly.
     enabledProviders: [] as string[],
-    defaultSource: 'jellyfin' as string,
+    defaultSource: 'netease' as string,
+
+    // Whether the admin enabled save/load queues (#119). Gates the nav entry
+    // and the /saved-queues page. Fetched from /api/bot/settings (non-guest).
+    savedQueuesEnabled: false,
 
     // Home page cache, split by source
     recommendPlaylists: { netease: [] as PlaylistItem[], qq: [] as PlaylistItem[], kugou: [] as PlaylistItem[], spotify: [] as PlaylistItem[] },
     dailySongs:         { netease: [] as Song[],         qq: [] as Song[],         kugou: [] as Song[], spotify: [] as Song[] },
     userPlaylists:      { jellyfin: [] as PlaylistItem[], netease: [] as PlaylistItem[], qq: [] as PlaylistItem[], kugou: [] as PlaylistItem[], spotify: [] as PlaylistItem[] },
     bilibiliPopular: [] as Song[],
-    // Jellyfin home sections (primary source)
+    // Jellyfin home sections (shown only when the optional source is enabled)
     jellyfinLatestAlbums: [] as AlbumItem[],
     jellyfinMostPlayed: [] as Song[],
     jellyfinFavorites: [] as Song[],
@@ -173,7 +177,7 @@ export const usePlayerStore = defineStore('player', {
       const maxDuration = this.activeBot.currentSong.duration || Infinity;
       return interpolateElapsed(timing, this.isPaused, maxDuration);
     },
-    /** Sources that are currently logged in. Jellyfin (the primary source) leads. */
+    /** Sources that are currently logged in. Jellyfin (when enabled) leads. */
     availableSources(): Source[] {
       const s: Source[] = [];
       if (this.authStatus.jellyfin) s.push('jellyfin');
@@ -595,6 +599,18 @@ export const usePlayerStore = defineStore('player', {
       return this.favoritedPlaylists.some((f) => f.playlistId === playlistId && f.platform === platform);
     },
 
+    /** Load global bot settings we care about client-side (currently just the
+     *  saved-queues gate). Guests get a 403 here, which we swallow so the nav
+     *  entry simply stays hidden for them. */
+    async fetchBotSettings() {
+      try {
+        const res = await axios.get('/api/bot/settings');
+        this.savedQueuesEnabled = res.data?.savedQueuesEnabled === true;
+      } catch {
+        // not critical (guests 403; keep previous value otherwise)
+      }
+    },
+
     /** Load the server-side source gate (enabledProviders + default). */
     async fetchProviders() {
       try {

web/src/views/SavedQueues.vue

@@ -0,0 +1,301 @@
+<template>
+  <div class="saved-queues-page">
+    <button class="back-btn" @click="$router.back()">
+      <Icon icon="mdi:arrow-left" />
+      返回
+    </button>
+    <h1 class="page-title">已保存队列</h1>
+
+    <div v-if="disabled" class="empty">
+      此功能未启用。请在「设置 → 行为设置」中开启「保存/加载播放清单」。
+    </div>
+
+    <template v-else>
+      <!-- Save current queue -->
+      <section class="save-card">
+        <div class="save-title">保存当前队列</div>
+        <div class="save-hint">
+          将机器人 <strong>{{ activeBotName }}</strong> 当前的播放队列保存为一份清单，稍后可加载或追加。
+        </div>
+        <div class="save-row">
+          <input
+            v-model="newName"
+            class="input"
+            type="text"
+            placeholder="清单名称"
+            maxlength="80"
+            @keyup.enter="onSave"
+          />
+          <label class="shared-check">
+            <input v-model="newShared" type="checkbox" />
+            共享
+          </label>
+          <button class="btn-primary" :disabled="!canSave || saving" @click="onSave">
+            {{ saving ? '保存中…' : '保存' }}
+          </button>
+        </div>
+      </section>
+
+      <div v-if="loading" class="loading">加载中...</div>
+      <div v-else-if="queues.length === 0" class="empty">还没有已保存的队列</div>
+
+      <div v-else class="queue-list">
+        <div v-for="q in queues" :key="q.id" class="queue-row">
+          <div class="queue-info">
+            <span class="queue-name">{{ q.name }}</span>
+            <span v-if="isShared(q)" class="badge shared">共享</span>
+            <span v-else class="badge private">私有</span>
+            <span class="queue-count">{{ q.songCount }} 首</span>
+          </div>
+          <div class="queue-actions">
+            <button class="btn-sm primary" :disabled="!activeBotId || busyId === q.id" @click="onLoad(q, 'replace')">
+              加载
+            </button>
+            <button class="btn-sm" :disabled="!activeBotId || busyId === q.id" @click="onLoad(q, 'append')">
+              追加
+            </button>
+            <button class="btn-sm danger" :disabled="busyId === q.id" @click="onDelete(q)">
+              删除
+            </button>
+          </div>
+        </div>
+      </div>
+    </template>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { ref, computed, onMounted } from 'vue';
+import { Icon } from '@iconify/vue';
+import { usePlayerStore } from '../stores/player.js';
+import { useSavedQueues } from '../composables/useSavedQueues.js';
+import { isShared, type SavedQueueMeta } from '../composables/savedQueues.js';
+
+const store = usePlayerStore();
+const { queues, loading, disabled, list, save, load, remove } = useSavedQueues();
+
+const newName = ref('');
+const newShared = ref(false);
+const saving = ref(false);
+const busyId = ref<number | null>(null);
+
+const activeBotId = computed(() => store.activeBotId);
+const activeBotName = computed(() => store.activeBot?.name ?? '（未选择）');
+const canSave = computed(() => !!activeBotId.value && newName.value.trim().length > 0);
+
+async function onSave() {
+  if (!canSave.value || saving.value) return;
+  saving.value = true;
+  try {
+    await save(activeBotId.value!, newName.value.trim(), newShared.value);
+    store.notify(`已保存「${newName.value.trim()}」`, 'info');
+    newName.value = '';
+    newShared.value = false;
+  } catch (e: unknown) {
+    const msg = (e as { response?: { data?: { error?: string } } })?.response?.data?.error;
+    store.notify(msg || '保存失败', 'error');
+  } finally {
+    saving.value = false;
+  }
+}
+
+async function onLoad(q: SavedQueueMeta, mode: 'replace' | 'append') {
+  if (!activeBotId.value) return;
+  busyId.value = q.id;
+  try {
+    const res = await load(q.id, activeBotId.value, mode);
+    store.notify(
+      mode === 'append' ? `已追加「${q.name}」（${res.loaded} 首）` : `已加载「${q.name}」（${res.loaded} 首）`,
+      'info',
+    );
+    store.fetchQueue();
+  } catch {
+    store.notify('加载失败', 'error');
+  } finally {
+    busyId.value = null;
+  }
+}
+
+async function onDelete(q: SavedQueueMeta) {
+  busyId.value = q.id;
+  try {
+    await remove(q.id);
+    store.notify(`已删除「${q.name}」`, 'info');
+  } catch {
+    store.notify('删除失败', 'error');
+  } finally {
+    busyId.value = null;
+  }
+}
+
+onMounted(async () => {
+  if (!store.activeBotId) {
+    await store.fetchBots();
+  }
+  await list();
+});
+</script>
+
+<style lang="scss" scoped>
+.back-btn {
+  display: flex;
+  align-items: center;
+  gap: 6px;
+  font-size: 14px;
+  opacity: 0.7;
+  margin-bottom: 16px;
+  transition: opacity var(--transition-fast);
+  &:hover { opacity: 1; }
+}
+
+.page-title {
+  font-size: 28px;
+  font-weight: 800;
+  margin-bottom: 24px;
+}
+
+.save-card {
+  background: var(--bg-card);
+  border: 1px solid var(--border-color);
+  border-radius: var(--radius-md);
+  padding: 18px;
+  margin-bottom: 24px;
+}
+
+.save-title {
+  font-size: 16px;
+  font-weight: 700;
+  margin-bottom: 6px;
+}
+
+.save-hint {
+  font-size: 13px;
+  color: var(--text-secondary);
+  margin-bottom: 14px;
+}
+
+.save-row {
+  display: flex;
+  align-items: center;
+  gap: 12px;
+  flex-wrap: wrap;
+}
+
+.input {
+  flex: 1;
+  min-width: 180px;
+  padding: 10px 12px;
+  font-size: 14px;
+  background: var(--hover-bg);
+  border: 1px solid var(--border-color);
+  border-radius: var(--radius-sm);
+  color: inherit;
+  &:focus { outline: none; border-color: var(--color-primary); }
+}
+
+.shared-check {
+  display: flex;
+  align-items: center;
+  gap: 6px;
+  font-size: 13px;
+  color: var(--text-secondary);
+  white-space: nowrap;
+  cursor: pointer;
+}
+
+.btn-primary {
+  padding: 10px 18px;
+  font-size: 14px;
+  font-weight: 600;
+  border-radius: var(--radius-sm);
+  background: var(--color-primary);
+  color: #fff;
+  border: 1px solid var(--color-primary);
+  cursor: pointer;
+  transition: filter var(--transition-fast);
+  &:hover:not(:disabled) { filter: brightness(1.08); }
+  &:disabled { opacity: 0.5; cursor: not-allowed; }
+}
+
+.queue-list {
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
+}
+
+.queue-row {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 12px;
+  padding: 12px 14px;
+  background: var(--bg-card);
+  border: 1px solid var(--border-color);
+  border-radius: var(--radius-sm);
+  flex-wrap: wrap;
+}
+
+.queue-info {
+  display: flex;
+  align-items: center;
+  gap: 10px;
+  min-width: 0;
+}
+
+.queue-name {
+  font-size: 15px;
+  font-weight: 600;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.queue-count {
+  font-size: 12px;
+  color: var(--text-tertiary);
+}
+
+.badge {
+  font-size: 10px;
+  font-weight: 700;
+  padding: 2px 6px;
+  border-radius: 4px;
+  flex-shrink: 0;
+  &.shared { background: var(--color-primary-15); color: var(--color-primary); }
+  &.private { background: var(--hover-bg); color: var(--text-secondary); }
+}
+
+.queue-actions {
+  display: flex;
+  gap: 6px;
+}
+
+.btn-sm {
+  padding: 6px 12px;
+  font-size: 12px;
+  font-weight: 600;
+  border-radius: var(--radius-sm);
+  background: var(--hover-bg);
+  border: 1px solid var(--border-color);
+  color: var(--text-primary);
+  cursor: pointer;
+  transition: all var(--transition-fast);
+  &:hover:not(:disabled) { background: var(--bg-secondary); border-color: var(--color-primary); }
+  &:disabled { opacity: 0.5; cursor: not-allowed; }
+  &.primary { background: var(--color-primary); border-color: var(--color-primary); color: #fff; }
+  &.danger { color: #ef4444; }
+}
+
+.loading {
+  text-align: center;
+  padding: 60px;
+  color: var(--text-secondary);
+}
+
+.empty {
+  text-align: center;
+  padding: 60px 20px;
+  color: var(--text-tertiary);
+  font-size: 14px;
+}
+</style>

web/src/views/Search.vue

@@ -57,7 +57,7 @@
 
     <template v-else-if="allSongs.length || allAlbums.length || allPlaylists.length">
       <!-- Only enabled sources are offered (enabledProviders gate); Jellyfin
-           — the primary source — comes first. -->
+           (opt-in) comes first when enabled. -->
       <div class="source-bar">
         <button
           v-if="sourceEnabled('jellyfin')"
@@ -218,7 +218,7 @@ function loadSource(): SearchSource {
     const stored = localStorage.getItem(SOURCE_STORAGE_KEY);
     if (SEARCH_SOURCES.includes(stored as SearchSource)) return stored as SearchSource;
   } catch { /* localStorage blocked */ }
-  return 'jellyfin';
+  return 'netease';
 }
 
 type TabType = 'songs' | 'albums' | 'playlists';
@@ -272,7 +272,7 @@ function fixupSelectedSource() {
   const def = store.defaultSource as SearchSource;
   selectedSource.value = SEARCH_SOURCES.includes(def) && sourceEnabled(def)
     ? def
-    : SEARCH_SOURCES.find((s) => s !== 'local' && sourceEnabled(s)) ?? 'jellyfin';
+    : SEARCH_SOURCES.find((s) => s !== 'local' && sourceEnabled(s)) ?? 'netease';
 }
 
 // ---- 分页 / 加载更多 ----

web/src/views/Settings.vue

@@ -165,10 +165,13 @@
       </div>
     </section>
 
-    <!-- Jellyfin — the primary music source. Admin-configured connection
+    <!-- Jellyfin — optional self-hosted music source. Admin-configured
-         (server URL + credentials), no QR flow. -->
+         connection (server URL + credentials), no QR flow. The card stays
-    <section v-if="can('platform.auth') && providerOn('jellyfin')" class="settings-section">
+         visible even while the source is disabled: the enable toggle below is
-      <h2 class="section-title">Jellyfin 音乐库</h2>
+         the only UI that flips its enabledProviders membership, so hiding the
+         card would leave no way to turn Jellyfin on. -->
+    <section v-if="can('platform.auth')" class="settings-section">
+      <h2 class="section-title">Jellyfin 音乐库（可选）</h2>
 
       <div class="account-card">
         <div class="account-header">
@@ -181,6 +184,15 @@
           </div>
         </div>
 
+        <!-- Enable (opt-in source: presence in enabledProviders) -->
+        <label class="profile-toggle behavior-toggle spotify-toggle">
+          <div class="profile-toggle-text">
+            <div class="profile-toggle-label">启用 Jellyfin 音源</div>
+            <div class="profile-toggle-hint">开启后 Jellyfin 出现在搜索、首页与聊天命令（!play -j）的音源列表中。默认关闭，点击下方「保存」后生效。</div>
+          </div>
+          <input v-model="jellyfinEnabledForm" type="checkbox" class="profile-toggle-switch" />
+        </label>
+
         <div class="form-group">
           <label>服务器地址</label>
           <input v-model="jellyfinForm.serverUrl" class="input" autocomplete="off" placeholder="https://jellyfin.example.com" />
@@ -543,6 +555,36 @@
       </div>
     </section>
 
+    <!-- Default music source (issue #126): the source used by chat commands
+         (!play/!add …) and the WebUI when no platform flag is given. Saving is a
+         global bot setting, so gate on bot.manage like the other behavior rows. -->
+    <section v-if="can('bot.manage')" class="settings-section">
+      <h2 class="section-title">默认音源</h2>
+      <p class="profile-section-hint">
+        设置不带音源参数时（如聊天里的 <code>!play 歌名</code> 或网页搜索）默认使用的音源。
+        例如把默认音源设为「哔哩哔哩」后，点播 B 站音乐就不用每次都加 <code>-b</code>。
+        选择「自动」则按内置优先级挑选第一个已启用的音源（网易云 → QQ → 酷狗 → Jellyfin → 哔哩哔哩 → YouTube）。
+      </p>
+      <div class="setting-row">
+        <div class="setting-label">
+          <Icon icon="mdi:music-box-multiple-outline" class="setting-icon" />
+          默认音源
+        </div>
+        <div class="prefix-input-wrap">
+          <select v-model="defaultPlatformForm" class="input input-sm default-source-select">
+            <option value="">自动（按优先级）</option>
+            <option v-for="opt in defaultSourceOptions" :key="opt.value" :value="opt.value">
+              {{ opt.label }}
+            </option>
+          </select>
+          <button class="btn-primary" :disabled="defaultSourceSaving" @click="saveDefaultSource">
+            {{ defaultSourceSaving ? '保存中…' : '保存' }}
+          </button>
+        </div>
+      </div>
+      <p v-if="defaultSourceMessage" class="spotify-message" :class="`tone-${defaultSourceMessageTone}`">{{ defaultSourceMessage }}</p>
+    </section>
+
     <!-- Spotify (Connect) playback via librespot — requires platform.auth -->
     <section v-if="can('platform.auth')" class="settings-section">
       <h2 class="section-title">Spotify 播放（实验性）</h2>
@@ -748,6 +790,32 @@
           @change="saveLocalAudioEnabled"
         />
       </label>
+
+      <label class="profile-toggle behavior-toggle">
+        <div class="profile-toggle-text">
+          <div class="profile-toggle-label">保存/加载播放清单（含重启后自动恢复队列）</div>
+          <div class="profile-toggle-hint">开启后可在网页与聊天命令（!save / !load / !queues）保存和加载播放清单，并在机器人重启后自动恢复并继续播放上次的队列。重启只能从当前曲目的开头恢复（不记忆进度）；Spotify 恢复为尽力而为。默认关闭。</div>
+        </div>
+        <input
+          v-model="savedQueuesEnabled"
+          type="checkbox"
+          class="profile-toggle-switch"
+          @change="saveSavedQueuesEnabled"
+        />
+      </label>
+
+      <label class="profile-toggle behavior-toggle">
+        <div class="profile-toggle-text">
+          <div class="profile-toggle-label">直接播放单曲时不清空队列</div>
+          <div class="profile-toggle-hint">开启后，直接播放单曲会插入到当前歌曲之后并立即播放，播完继续原队列，而不是清空整个队列。仅影响单曲的「直接播放」；歌单/专辑/电台仍会替换队列。默认关闭。</div>
+        </div>
+        <input
+          v-model="playKeepsQueue"
+          type="checkbox"
+          class="profile-toggle-switch"
+          @change="savePlayKeepsQueue"
+        />
+      </label>
     </section>
 
     <!-- Guest Mode (admin only) -->
@@ -1149,6 +1217,51 @@ function providerOn(p: string): boolean {
   return enabledProviders.value.length === 0 || enabledProviders.value.includes(p);
 }
 
+// --- Default music source (issue #126) ---
+// Chinese labels for the gateable providers, shown in the default-source select.
+const PROVIDER_LABELS: Record<string, string> = {
+  netease: '网易云音乐',
+  qq: 'QQ音乐',
+  kugou: '酷狗音乐',
+  bilibili: '哔哩哔哩',
+  youtube: 'YouTube',
+  jellyfin: 'Jellyfin',
+};
+// Empty string = "auto" (follow the fixed priority order); persisted as null.
+const defaultPlatformForm = ref('');
+const defaultSourceSaving = ref(false);
+const defaultSourceMessage = ref('');
+const defaultSourceMessageTone = ref<'ok' | 'warn'>('ok');
+// Only currently-enabled sources can be picked as the default.
+const defaultSourceOptions = computed(() =>
+  enabledProviders.value
+    .filter((p) => p in PROVIDER_LABELS)
+    .map((p) => ({ value: p, label: PROVIDER_LABELS[p] })),
+);
+
+async function saveDefaultSource() {
+  defaultSourceSaving.value = true;
+  defaultSourceMessage.value = '';
+  try {
+    const res = await axios.post('/api/bot/settings', {
+      defaultPlatform: defaultPlatformForm.value || null,
+    });
+    defaultPlatformForm.value = res.data?.defaultPlatform ?? '';
+    // Push the new default across the app immediately (search bar / play calls
+    // read store.defaultSource, refreshed via GET /api/music/providers).
+    await store.fetchProviders();
+    defaultSourceMessageTone.value = 'ok';
+    defaultSourceMessage.value = '已保存';
+  } catch (err: any) {
+    defaultSourceMessageTone.value = 'warn';
+    defaultSourceMessage.value = err?.response?.status === 403
+      ? '没有权限修改设置（需要 bot.manage）'
+      : '保存失败，请稍后重试';
+  } finally {
+    defaultSourceSaving.value = false;
+  }
+}
+
 // --- Jellyfin connection (admin-configured; password/apiKey are write-only) ---
 const jellyfinForm = reactive({
   serverUrl: '',
@@ -1164,6 +1277,12 @@ const jellyfinSaving = ref(false);
 const jellyfinTesting = ref(false);
 const jellyfinMessage = ref('');
 const jellyfinMessageTone = ref<'ok' | 'warn'>('ok');
+// Jellyfin is opt-in: its "enabled" bit is membership in enabledProviders
+// (unlike Spotify's dedicated spotify.enabled flag). Only trust the toggle
+// once the real list has loaded, so an early save can't clobber the other
+// providers with the empty placeholder list.
+const jellyfinEnabledForm = ref(false);
+const enabledProvidersLoaded = ref(false);
 
 // Populate from the masked GET /api/bot/settings response — secrets never
 // round-trip, only hasPassword/hasApiKey.
@@ -1183,8 +1302,27 @@ async function saveJellyfin() {
   jellyfinSaving.value = true;
   jellyfinMessage.value = '';
   try {
-    const res = await axios.post('/api/bot/settings', { jellyfin: { ...jellyfinForm } });
+    // enabledProviders is a full-replace field, so only send it when the
+    // current list is known — otherwise we'd wipe the other sources.
+    const payload: Record<string, unknown> = { jellyfin: { ...jellyfinForm } };
+    if (enabledProvidersLoaded.value) {
+      const others = enabledProviders.value.filter((p) => p !== 'jellyfin');
+      payload.enabledProviders = jellyfinEnabledForm.value ? [...others, 'jellyfin'] : others;
+    }
+    const res = await axios.post('/api/bot/settings', payload);
     applyJellyfinConfig(res.data?.jellyfin);
+    if (Array.isArray(res.data?.enabledProviders)) {
+      enabledProviders.value = res.data.enabledProviders;
+      jellyfinEnabledForm.value = res.data.enabledProviders.includes('jellyfin');
+      enabledProvidersLoaded.value = true;
+      // Search bar / home sections / FM cards react without a reload.
+      store.fetchProviders();
+    }
+    // Disabling a source can clear a default that pointed at it (backend
+    // reconciles enabledProviders → defaultPlatform); keep the select in sync.
+    if (res.data && 'defaultPlatform' in res.data) {
+      defaultPlatformForm.value = res.data.defaultPlatform ?? '';
+    }
     jellyfinMessageTone.value = 'ok';
     jellyfinMessage.value = '已保存';
     await checkAuthStatus();
@@ -1458,6 +1596,9 @@ const idleTimeout = ref(0);
 // Defaults OFF to match the backend default (config.ts getDefaultConfig).
 const autoPauseOnEmpty = ref(false);
 const localAudioEnabled = ref(true);
+// Saved-queues + play-keeps-queue toggles (#119), both default OFF.
+const savedQueuesEnabled = ref(false);
+const playKeepsQueue = ref(false);
 
 async function loadIdleTimeout() {
   try {
@@ -1465,13 +1606,20 @@ async function loadIdleTimeout() {
     idleTimeout.value = res.data.idleTimeoutMinutes ?? 0;
     autoPauseOnEmpty.value = res.data.autoPauseOnEmpty ?? false;
     localAudioEnabled.value = res.data.localAudioEnabled ?? true;
+    savedQueuesEnabled.value = res.data.savedQueuesEnabled ?? false;
+    playKeepsQueue.value = res.data.playKeepsQueue ?? false;
+    store.savedQueuesEnabled = savedQueuesEnabled.value;
     applyGuestModeFromServer(res.data.guestMode);
     applyAdminGroupsFromServer(res.data.adminGroups);
     applySpotifyConfig(res.data.spotify);
     applyJellyfinConfig(res.data.jellyfin);
     if (Array.isArray(res.data.enabledProviders)) {
       enabledProviders.value = res.data.enabledProviders;
+      jellyfinEnabledForm.value = res.data.enabledProviders.includes('jellyfin');
+      enabledProvidersLoaded.value = true;
     }
+    // null (unset) → "" so the select shows "自动（按优先级）".
+    defaultPlatformForm.value = res.data.defaultPlatform ?? '';
   } catch { /* ignore */ }
 }
 
@@ -1494,6 +1642,22 @@ async function saveLocalAudioEnabled() {
   } catch { /* ignore */ }
 }
 
+async function saveSavedQueuesEnabled() {
+  try {
+    const res = await axios.post('/api/bot/settings', { savedQueuesEnabled: savedQueuesEnabled.value });
+    savedQueuesEnabled.value = res.data.savedQueuesEnabled ?? savedQueuesEnabled.value;
+    // Keep the shared store flag (nav gate) in sync without a reload.
+    store.savedQueuesEnabled = savedQueuesEnabled.value;
+  } catch { /* ignore */ }
+}
+
+async function savePlayKeepsQueue() {
+  try {
+    const res = await axios.post('/api/bot/settings', { playKeepsQueue: playKeepsQueue.value });
+    playKeepsQueue.value = res.data.playKeepsQueue ?? playKeepsQueue.value;
+  } catch { /* ignore */ }
+}
+
 // --- Spotify (Connect) settings (§8) ---
 // NOTE: This card's status comes ONLY from /api/spotify/status (playback OAuth
 // `authorized`). It is deliberately NOT wired to the player store's
@@ -2414,6 +2578,13 @@ onUnmounted(() => {
 
 .input-sm { max-width: 80px; }
 
+// The default-source picker holds full source names ("网易云音乐"), so it needs
+// more room than the 80px .input-sm cap.
+.default-source-select {
+  max-width: none;
+  flex: 0 0 160px;
+}
+
 .textarea {
   width: 100%;
   padding: 10px 14px;

web/src/views/Setup.vue

@@ -61,7 +61,7 @@
 
     <div v-if="currentStep === 2" class="step-content">
       <h2>连接 Jellyfin (可选)</h2>
-      <p class="subtitle">连接自建 Jellyfin 服务器作为主音源；也可稍后在「设置」中配置</p>
+      <p class="subtitle">连接自建 Jellyfin 服务器作为额外音源；保存后自动启用，也可稍后在「设置」中配置</p>
       <div class="form-group">
         <label>服务器地址</label>
         <input v-model="jellyfin.serverUrl" placeholder="https://jellyfin.example.com" class="input" />
@@ -130,8 +130,8 @@ const nickname = ref('MusicBot');
 const defaultChannel = ref('');
 const channelId = ref('');
 
-// Jellyfin — the primary music source. Optional: skipping leaves it
+// Jellyfin — optional self-hosted music source. Skipping leaves it
-// configurable later in Settings.
+// configurable later in Settings; saving here also enables it.
 const jellyfin = reactive({
   serverUrl: '',
   authMode: 'userpass' as 'userpass' | 'apikey',
@@ -182,7 +182,19 @@ async function testJellyfin() {
 async function saveJellyfinAndNext() {
   jellyfinSaving.value = true;
   try {
-    await axios.post('/api/bot/settings', { jellyfin: { ...jellyfin } });
+    // Jellyfin is opt-in (not in the default enabledProviders), so completing
+    // this step also enables the source — a configured-but-dark Jellyfin would
+    // be baffling. enabledProviders is full-replace: fetch the current list
+    // and append. Only do this when a server URL was actually entered.
+    const payload: Record<string, unknown> = { jellyfin: { ...jellyfin } };
+    if (jellyfin.serverUrl.trim()) {
+      const cur = await axios.get('/api/bot/settings');
+      const ep: unknown = cur.data?.enabledProviders;
+      if (Array.isArray(ep) && !ep.includes('jellyfin')) {
+        payload.enabledProviders = [...ep, 'jellyfin'];
+      }
+    }
+    await axios.post('/api/bot/settings', payload);
     currentStep.value = 3;
   } catch {
     jellyfinTestOk.value = false;