feat(search): per-source load-more pagination in Search.vue (#115 frontend)

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
feat(search): server-side offset pagination through providers + /search route (#115 backend)
2026-10-02 04:52:50 +08:00 · 2026-07-04 14:42:07 +08:00 · 2026-07-04 14:36:54 +08:00 · 2026-07-04 14:26:51 +08:00 · 2026-06-30 23:26:28 +08:00 · 2026-06-30 23:16:25 +08:00
65 changed files with 5798 additions and 603 deletions
@@ -5,7 +5,7 @@
 <h1 align="center">TSMusicBot</h1>

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

 <p align="center">
@@ -15,6 +15,7 @@
  <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/酷狗音乐-支持-2ca2f9" />
  <img src="https://img.shields.io/badge/BiliBili-支持-00a1d6?logo=bilibili&logoColor=white" />
  <img src="https://img.shields.io/badge/YouTube-可选-FF0000?logo=youtube&logoColor=white" />
  <img src="https://img.shields.io/badge/TS3-支持-2580C3?logo=teamspeak&logoColor=white" />
@@ -24,20 +25,22 @@
 ## 功能特性

 - **WebUI 鉴权与细粒度权限（必选）** — 用户名 + 密码登录，多用户、两种角色（管理员 / 成员）；成员可进一步配置**细粒度能力**（播放控制 / 队列管理 / 机器人管理 / 平台登录 / 音质）和**按机器人授权白名单**，所有变更操作由后端逐请求强制校验。bcrypt 加密、HttpOnly 会话 Cookie，CSRF 防护，WebSocket 同样鉴权。首次访问引导创建管理员。从无鉴权旧版本升级时请参阅 [更新升级](#更新升级) 章节
+- **游客模式（免登录点歌，默认关闭）** — 管理员可选择允许访客**无需账号密码**进入 WebUI 点歌，并逐项配置游客权限（8 个开关，默认仅「添加到队列末尾」开启）与可控机器人白名单；游客无法查看 / 修改任何设置、管理机器人或访问用户管理。开启后登录页出现 **「以游客身份进入」**。详见下文 **「游客模式 / Guest mode」** 小节
 - **本地收藏歌单** — 在首页 / 搜索 / 歌单页一键收藏，收藏内容按用户存储，登录后跨设备同步
+- **本地音频上传播放** — 在搜索页拖拽或选择本地音频上传，上传后可直接播放 / 下一首播放 / 加入队列；管理员可在 设置 → 行为设置 开关此功能，播放结束或停止/清空/替换队列时会清理服务端接收的本地文件
 - **专属链接（单机器人锁定）** — 通过 `/bot/<id>` 专属链接打开 WebUI 时锁定到单个机器人，刷新后保持，适合把某台机器人的控制页分享给特定用户
 - **频道无人时自动暂停** — 机器人所在频道没有其他人时自动暂停播放，有人加入后自动恢复（**默认关闭**，可在设置中开启）
- **多平台音源** — 网易云音乐 + QQ 音乐 + 哔哩哔哩（默认内置），YouTube 可选启用（通过 yt-dlp），统一搜索，结果标注来源
+- **多平台音源** — 网易云音乐 + QQ 音乐 + 酷狗音乐 + 哔哩哔哩（默认内置），YouTube 可选启用（通过 yt-dlp），统一搜索，结果标注来源
 - **真实客户端协议 (TS3/TS6 双协议)** — 机器人在 TeamSpeak 中可见（非 ServerQuery 隐身模式），自动检测并适配 TS3 和 TS6 服务器，支持 TS6 HTTP Query API
 - **YesPlayMusic 风格 WebUI** — 精美界面，支持深色/浅色主题切换
 - **完整播放控制** — 播放/暂停/上一首/下一首/进度跳转/音量调节
 - **四种播放模式** — 顺序播放/循环播放/随机播放/随机循环
 - **实时歌词同步** — 歌词滚动显示，支持翻译歌词，服务端帧计数精确同步
- **歌单管理** — 推荐歌单/我的歌单/每日推荐/私人FM，点击播放全部；私人 FM 支持网易云与 **QQ 音乐雷达推荐**（`!fm -q`）
+- **歌单管理** — 推荐歌单/我的歌单/每日推荐/私人FM，点击播放全部；私人 FM 支持网易云、**QQ 音乐雷达推荐**（`!fm -q`）与**酷狗私人电台**（`!fm -k`）。网易云、QQ、酷狗均提供登录后的推荐歌单 / 每日推荐 / 我的歌单
 - **音质选择** — 标准(128k) / 较高(192k) / 极高(320k) / 无损(FLAC) / Hi-Res / 超清母带
 - **B站视频音频提取** — 搜索B站视频，自动提取DASH最高码率音频流播放
 - **B站热门推荐** — 首页展示B站热门视频和个性化推荐（登录后更准确）
- **QR码登录** — 扫码登录网易云/QQ音乐/哔哩哔哩账号，Cookie 自动持久化
+- **QR码登录** — 扫码登录网易云/QQ音乐/酷狗音乐/哔哩哔哩账号，Cookie 自动持久化
 - **机器人形象自动更新** — 播放时自动更新头像（专辑封面）、昵称（当前歌曲）、描述、Away 状态、频道描述，停止时恢复默认值。每项功能独立可配置，权限不足时自动降级
 - **多机器人独立播放** — 多个机器人同时在不同服务器或频道播放不同音乐，每个机器人独立的播放队列、进度和音量，WebUI 一键切换控制
 - **播放历史** — 自动记录所有播放过的歌曲
@@ -186,8 +189,8 @@ sudo ./scripts/install.sh

 让访客**无需账号密码**即可进入 WebUI 点歌，同时严格限制其可用能力。该功能**默认关闭**，只有管理员能开启。

- **开启方式**：管理员在 **设置 → 游客模式** 打开「允许游客访问」（仅管理员可见此区块）。开启后登录页会出现 **「以游客身份进入」** 按钮，访客点击即可创建游客会话，无需任何凭据。关闭游客模式后，所有游客会话立即失效。
- **逐项权限（7 个开关，管理员配置）**：除「添加到队列末尾」外**全部默认关闭**，按需逐项放开。
+- **开启方式**：管理员在 **设置 → 游客模式** 打开「允许游客访问」（仅管理员可见此区块）。开启后登录页会出现 **「以游客身份进入」** 按钮，访客点击即可创建游客会话，无需任何凭据。游客共享同一匿名身份、会话有效期较短（约 1 天）。关闭游客模式（或缩小机器人作用域）后立即生效，所有在线游客会话——包括正在连接的实时 WebSocket——会被立刻断开 / 重新限制。
+- **逐项权限（8 个开关，管理员配置）**：除「添加到队列末尾」外**全部默认关闭**，按需逐项放开。

  | 开关 | 字段 | 默认 |
  |------|------|------|
@@ -198,9 +201,10 @@ sudo ./scripts/install.sh
  | 暂停/继续/进度/音量 | `transport` | 关 |
  | 移除/清空队列 | `removeClear` | 关 |
  | 切换播放模式 / FM | `playMode` | 关 |
+  | 播放整个歌单/专辑 | `playCollection` | 关 |

 - **按机器人授权（游客作用域）**：可选择「全部机器人」或指定一份机器人白名单。作用域之外的机器人对游客**不可见、不可控**。
- **游客始终被禁止**：查看或修改任何设置、管理机器人、设置音乐平台账号 / 凭据、修改音质，以及访问用户管理与操作审计。这些限制不受上面 7 个开关影响，**永远锁死**。
+- **游客始终被禁止**：查看或修改任何设置、管理机器人、设置音乐平台账号 / 凭据、修改音质、收藏歌单、修改密码、访问用户管理与操作审计，以及读取机器人主人的私人歌单 / 私人 FM / 每日推荐等平台账号数据。这些限制不受上面 8 个开关影响，**永远锁死**。
 - **复现 issue #83 的「下一首 only」需求**：在 **设置 → 游客模式** 中关闭「添加到队列末尾」并打开「添加到下一首」，游客便只能把歌曲加到下一首播放。

 **如何重置忘记的管理员密码**：
@@ -221,7 +225,7 @@ sqlite3 data/tsmusicbot.db "UPDATE users SET passwordHash='<paste-hash-here>' WH

 **反向代理用户特别注意**：如果通过 nginx / Caddy / Cloudflare 暴露 WebUI，**必须**在 `config.json` 中设置 `"trustProxy": true`，否则 Cookie 不会带 `Secure` 标志，且登录限流会把所有用户合并到同一个桶。详见下方 [反向代理部署注意事项](#反向代理部署注意事项)。

-**旧版 `config.adminPassword` / `adminGroups`**：这两个配置项在旧版本中预留但从未实际启用（TS-side admin 命令权限的占位字段）。保留以避免破坏旧 `config.json`，但不再影响任何行为。可以放心忽略。
+**`config.adminGroups`（现已启用）**：用于限制管理类聊天命令（`stop`/`clear`/`remove`/`move`/`vol`/`mode`）只能由指定 TeamSpeak 服务器组的成员运行；为空时不做任何限制（向后兼容）。详见 [TeamSpeak 命令权限](#teamspeak-命令权限管理类命令限制)。`config.adminPassword` 则是旧版预留字段，当前版本未使用，保留以兼容旧 `config.json`，可以放心忽略。

 ### Windows 用户

@@ -297,19 +301,19 @@ sudo systemctl start tsmusicbot
   - 端口（默认 9987，自托管或非标准端口请填写实际值）
   - 机器人昵称
   - 可选：服务器密码、默认频道
-3. 在 **设置 → 音乐账号** 扫码登录网易云 / QQ 音乐 / B 站账号（可选，登录后可播放 VIP 歌曲）
+3. 在 **设置 → 音乐账号** 扫码登录网易云 / QQ 音乐 / 酷狗音乐 / B 站账号（可选，登录后可播放 VIP 歌曲、获取每日推荐 / 我的歌单等）
 4. 在 **设置 → 用户管理**（仅管理员可见）按需添加成员。成员默认可控制播放但无法管理其他用户；管理员还可为每个成员单独配置**能力**（播放控制 / 队列 / 机器人管理 / 平台登录 / 音质）和**可操作的机器人白名单**，未授权的机器人对该成员不可见、不可控

 ### WebUI 页面说明

 | 页面 | 功能 |
 |------|------|
-| **首页** | 推荐歌单、每日推荐、私人FM（网易云 / QQ 雷达）、我的歌单、收藏的歌单 |
-| **搜索** | 三平台统一搜索，结果标注网易云/QQ/B站来源，可一键收藏歌单 |
+| **首页** | 推荐歌单、每日推荐、私人FM（网易云 / QQ 雷达 / 酷狗电台）、我的歌单、收藏的歌单（各源带标签切换） |
+| **搜索** | 四平台统一搜索，结果标注网易云/QQ/酷狗/B站来源，可一键收藏歌单 |
 | **歌单** | 查看歌单详情，播放全部（根据当前播放模式选择首歌），一键收藏 |
 | **歌词** | 全屏歌词页，实时同步滚动，模糊专辑封面背景 |
 | **历史** | 播放历史记录 |
-| **设置** | 账户（修改自己密码） / 主题切换 / 机器人管理 / 行为设置（空闲超时、频道无人自动暂停） / 三平台账号登录 / 音质选择 / 命令前缀 / 用户管理（仅管理员，含成员能力与机器人白名单）/ 操作审计（仅管理员） |
+| **设置** | 账户（修改自己密码） / 主题切换 / 机器人管理 / 行为设置（空闲超时、频道无人自动暂停） / 多平台账号登录（网易云 / QQ / 酷狗 / B站） / 音质选择 / 命令前缀 / 用户管理（仅管理员，含成员能力与机器人白名单）/ 操作审计（仅管理员） |

 ### TeamSpeak 文字命令

@@ -319,9 +323,10 @@ sudo systemctl start tsmusicbot
 |------|------|
 | `!play <歌名>` | 搜索并播放（取最热门的匹配项） |
 | `!play -q <歌名>` | 从 QQ 音乐搜索 |
+| `!play -k <歌名>` | 从酷狗音乐搜索 |
 | `!play -b <关键词>` | 从哔哩哔哩搜索视频并播放音频 |
 | `!play -y <关键词>` | 从 YouTube 搜索并播放（需要安装 [yt-dlp](#可选youtube-音源)）|
-| `!search <歌名>` | 列出前若干个匹配结果（含序号与 id），用于挑选同名歌曲 |
+| `!search <歌名> [-q\|-k\|-b\|-y]` | 列出前若干个匹配结果（含序号与 id），用于挑选同名歌曲；可加平台标志切换音源 |
 | `!play #<序号>` | 播放上一次 `!search` 结果中的第 N 项（区分同名歌曲） |
 | `!play id:<id>` | 按歌曲 id 播放精确的某首歌（也支持直接粘贴网易云 / QQ / B站 歌曲链接） |
 | `!add <歌名>` | 添加到播放队列（同样支持 `#序号` / `id:<id>` / 链接） |
@@ -335,9 +340,10 @@ sudo systemctl start tsmusicbot
 | `!playlist <歌单名或ID>` | 加载歌单（支持名称模糊搜索和 ID） |
 | `!playlist -q <歌单名>` | 从 QQ 音乐搜索并加载歌单 |
 | `!album <ID>` | 加载专辑 |
-| `!artist <歌手名>` | 按歌手循环播放（支持 `-q`/`-b`/`-y`） |
+| `!artist <歌手名>` | 按歌手循环播放（支持 `-q`/`-k`/`-b`/`-y`） |
 | `!fm` | 私人 FM（网易云，自动续播） |
 | `!fm -q` | QQ 音乐雷达 / 猜你喜欢 FM（自动续播） |
+| `!fm -k` | 酷狗私人电台 / 个性化推荐 FM（自动续播） |
 | `!lyrics` | 显示当前歌词 |
 | `!now` | 当前播放信息 |
 | `!vote` | 投票跳过当前歌曲 |
@@ -346,6 +352,27 @@ sudo systemctl start tsmusicbot

 > 命令前缀默认为 `!`，可在设置页面修改。支持别名：`!p` = `!play`，`!s` = `!skip`，`!n` = `!next`

+### TeamSpeak 命令权限（管理类命令限制）
+
+默认情况下，频道里任何人都能运行所有聊天命令。你可以把一组「管理类」命令限制为只有特定 TeamSpeak 服务器组的成员才能运行：
+
+- 受限命令：`stop`、`clear`、`remove`、`move`、`vol`、`mode`
+- 其余命令（点歌、队列、跳过、歌词等）始终对所有人开放
+- **默认不限制**：管理服务器组列表为空时，所有命令对所有人开放（向后兼容）
+
+**配置方式**
+
+- 网页端：设置 → 命令权限，填写允许的服务器组 ID（逗号分隔），保存即时生效。
+- 或编辑 `config.json` 的 `adminGroups`（数字数组），例如 `"adminGroups": [6, 8]`。
+
+填入任意服务器组 ID 后，限制立即开启：只有属于这些组之一的用户才能运行受限命令，其他人会收到「⛔ 需要管理员权限（该命令仅限管理员服务器组）」的提示。
+
+> 提示（fail-closed）：当受限命令来自一个机器人当前看不到其服务器组的发送者（例如不在机器人所在频道的私聊），机器人会尝试查询其分组；若仍无法确定，则拒绝执行。
+
+**如何查看服务器组 ID**
+
+在 TeamSpeak 客户端中打开「权限 → 服务器组」（Permissions → Server Groups）对话框，选中某个组后，其 ID 会显示在标题栏/状态栏；或在服务器组管理界面中查看每个组对应的数字 ID。把需要授权的组 ID 填入上面的设置即可。
+
 ### 音质等级

 | 等级 | 码率 | 格式 | 说明 |
@@ -383,6 +410,7 @@ teamspeak-music-bot/
 │   │   ├── netease.ts          # 网易云音乐适配器
 │   │   ├── qq.ts               # QQ 音乐适配器
 │   │   ├── bilibili.ts         # 哔哩哔哩适配器（视频音频提取）
+│   │   ├── kugou.ts            # 酷狗音乐适配器（直连 API，无 npm 依赖 / 无内嵌服务）
 │   │   ├── youtube.ts          # YouTube 适配器（可选，依赖 yt-dlp）
 │   │   ├── auth.ts             # Cookie 持久化存储
 │   │   └── api-server.ts       # 嵌入式 API 服务（自动启动）
@@ -433,8 +461,9 @@ teamspeak-music-bot/
 | **音频处理** | FFmpeg (ffmpeg-static 内置), @discordjs/opus |
 | **TS 协议** | @honeybbq/teamspeak-client（完整客户端协议）+ 自研 TS6 协议适配层 |
 | **网易云 API** | NeteaseCloudMusicApi |
-| **QQ 音乐 API** | @sansenjian/qq-music-api |
+| **QQ 音乐 API** | @sansenjian/qq-music-api（锁定 `~2.4.0`，需 Node ≥ 20.17） |
 | **哔哩哔哩** | BiliBili Web API（搜索、DASH 音频流、QR 登录） |
+| **酷狗音乐** | 酷狗公开 API（直连，无 npm 依赖 / 无内嵌服务；请求签名 / KRC 歌词解码 / 设备注册移植自 MIT 的 MakcRe/KuGouMusicApi，改用 Node 内置 crypto + zlib） |
 | **前端框架** | Vue 3, Vite 5, Pinia, Vue Router 4 |
 | **界面样式** | SCSS（YesPlayMusic 设计风格） |
 | **图标** | @iconify/vue |
@@ -514,7 +543,7 @@ pip install -U yt-dlp

 > **配置文件位置变更**：旧版本把 `config.json` 写在项目根目录（不在 Docker 挂载卷内，导致重启丢失、手动编辑不生效）。现在统一放在 `data/config.json`。升级时若检测到根目录存在旧的 `config.json`，会在首次启动时自动迁移到 `data/` 并保留你的设置，无需手动操作。

-> **关于 `adminPassword` 和 `adminGroups`**：这两个字段保留是为了兼容旧 `config.json`，但当前版本未使用。WebUI 鉴权改为基于数据库的用户账号系统（见 [首次配置](#首次配置)），无需在 `config.json` 中设置密码。
+> **关于 `adminPassword` 和 `adminGroups`**：`adminGroups` 现已启用，用于限制管理类聊天命令只能由指定 TeamSpeak 服务器组运行（为空 = 不限制），详见 [TeamSpeak 命令权限](#teamspeak-命令权限管理类命令限制)。`adminPassword` 仍为旧版预留字段、当前版本未使用——WebUI 鉴权改为基于数据库的用户账号系统（见 [首次配置](#首次配置)），无需在 `config.json` 中设置密码。

 ### 反向代理部署注意事项

@@ -549,6 +578,12 @@ A：可以。在设置页面创建多个实例，分别连接不同的 TS 服务
 **Q：端口 3200 被占用？**
 A：QQ 音乐 API 启动时自动监听 3200 端口。如果之前的进程还在运行，程序会自动复用。如需重启可手动结束 `node` 进程。

+**Q：QQ 音乐二维码不弹 / 扫码登录失败 / cookie 无法使用？**
+A：通常是内置的 QQ 音乐 API 服务没起来——它一旦没监听 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` 并重启即可。
+
 **Q：播放歌曲时报 FFmpeg EACCES 错误？**
 A：`ffmpeg-static` 内置的 FFmpeg 二进制文件缺少执行权限。程序已自动尝试修复，如果仍然失败，请手动执行：
 ```bash
@@ -606,10 +641,11 @@ A：本项目内置 `/login` 限流（每 IP 每分钟 5 次），但生产部

 ### 最新版本

-**功能增强：细粒度权限 / 本地收藏 / 专属链接 / 自动暂停 / QQ 雷达 FM**
+**功能增强：细粒度权限 / 本地收藏 / 本地音频上传 / 专属链接 / 自动暂停 / QQ 雷达 FM**

 - **细粒度账号权限**（叠加在 admin / member 之上）：管理员可为每个成员勾选 5 项能力（`player.control` / `player.queue` / `bot.manage` / `platform.auth` / `quality`）和按机器人授权白名单；所有变更路由由后端 `requirePermission` / `requireBotAccess` 中间件逐请求强制校验，未授权返回 403，未授权的机器人对成员不可见（列表过滤，无 403-vs-404 枚举泄漏）。已有成员经一次性迁移获得全部能力，新成员默认基础能力。
 - **本地收藏歌单**：按用户存储的收藏（`favorite_playlists` 表 + `/api/favorites`），首页 / 搜索 / 歌单页一键收藏，跨设备同步。
+- **本地音频上传播放**：搜索页支持拖拽 / 选择本地音频上传（保存到 `data/local-audio`），上传后可像普通歌曲一样播放、下一首播放或加入队列；设置 → 行为设置 中新增「本地音频播放」开关，关闭后拒绝新的本地上传和本地歌曲播放请求。播放结束或停止 / 清空 / 替换队列时会从服务端删除已接收文件并更新索引。
 - **专属链接（单机器人锁定）**：`/bot/<id>` 打开时锁定到单台机器人，`?bot=<id>` 随刷新保持；与权限白名单组合，机器人下拉只显示"作用域 ∩ 可控"的机器人。
 - **频道无人时自动暂停**：机器人所在频道清空时暂停、有人加入时恢复（区分用户手动暂停，不会误恢复）；可在 设置 → 行为设置 开关（默认关闭）。占用检测在 `clientlist` 查询失败时按"未知"处理而非"无人"，避免有人在听时被误暂停。
 - **QQ 音乐雷达 / 私人 FM**：`!fm -q` 或 WebUI 启动 QQ 雷达推荐流（失败回退"猜你喜欢"），FM 自动续播现支持任意平台。
@@ -630,7 +666,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'`（防点击劫持）。
- **配置变更**：反向代理部署务必 `"trustProxy": true`（详见 [反向代理部署注意事项](#反向代理部署注意事项)）。`config.adminPassword` / `adminGroups` 字段保留以兼容旧 `config.json`，但不再影响任何行为。
+- **配置变更**：反向代理部署务必 `"trustProxy": true`（详见 [反向代理部署注意事项](#反向代理部署注意事项)）。`config.adminGroups` 现已启用，用于限制管理类聊天命令只能由指定 TeamSpeak 服务器组运行（为空 = 不限制，详见 [TeamSpeak 命令权限](#teamspeak-命令权限管理类命令限制)）；`config.adminPassword` 仍为旧版预留字段，保留以兼容旧 `config.json`，当前未使用。

 ### v0.x — Bot Profile 自动更新与协议层升级

@@ -702,6 +738,7 @@ A：本项目内置 `/login` 限流（每 IP 每分钟 5 次），但生产部
 - **初始 TS3/TS6 双协议支持**：自动协议检测（TS3 port 10011 vs TS6 port 10080）、TS6 HTTP Query 客户端、数据库持久化 `serverProtocol` / `ts6ApiKey`。
 - **多机器人架构**：支持同一进程中运行多个机器人实例，独立队列、进度、音量；WebUI 一键切换。
 - **网易云 / QQ 音乐 / 哔哩哔哩**：三平台原生音源，QR 码登录，Cookie 持久化。
+- **酷狗音乐音源**：第四个原生音源（直连 API，无 npm 依赖 / 无内嵌服务），覆盖搜索 / 播放 / KRC 歌词 / 专辑 / QR 登录，登录后支持每日推荐 / 推荐歌单 / 我的歌单 / 私人电台与歌曲封面。
 - **Docker & systemd 部署**：一键部署脚本，数据卷持久化，自动重启支持。

 ## 致谢
@@ -722,6 +759,7 @@ A：本项目内置 `/login` 限流（每 IP 每分钟 5 次），但生产部
 | [@sansenjian/qq-music-api](https://github.com/sansenjian/qq-music-api) | QQ 音乐 API 活跃维护版本 |
 | [@honeybbq/teamspeak-client](https://www.npmjs.com/package/@honeybbq/teamspeak-client) | TS3 完整客户端协议实现 |
 | [bilibili-API-collect](https://github.com/SocialSisterYi/bilibili-API-collect) | 哔哩哔哩 API 文档 |
+| [MakcRe/KuGouMusicApi](https://github.com/MakcRe/KuGouMusicApi) | 酷狗音乐 API 参考（请求签名 / KRC 歌词解码 / 设备注册移植来源，MIT 许可） |

 ## 开源许可

@@ -0,0 +1,840 @@
+# TeamSpeak chat-command permission control — Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Gate a fixed set of "admin" TeamSpeak chat commands (`stop`, `clear`, `remove`, `move`, `vol`, `mode`) behind configured TS server-group IDs, opt-in and backward-compatible, configurable from the WebUI and `config.json`.
+
+**Architecture:** A pure helper `canRunCommand(name, invokerGroups, adminGroups)` decides allow/deny. The chat handler `handleTextMessage` (NOT the WebUI-shared `executeCommand`) consults it before executing, performs a best-effort group lookup when the sender's groups weren't delivered with the event, fails closed, and replies on deny. The privileged groups live in the already-declared `config.adminGroups`, surfaced through the existing `GET/POST /api/bot/settings` endpoints and an admin-only Settings.vue section.
+
+**Tech Stack:** Node 20, TypeScript (ESM), Express 5, Vitest + supertest (backend), Vue 3 + `vue-tsc` (frontend), `@honeybbq/teamspeak-client`.
+
+## Global Constraints
+
+- **ESM import specifiers:** every relative import ends in `.js` even in `.ts` files (e.g. `import { canRunCommand } from "./commands.js"`).
+- **Admin command set (exact, single source of truth):** `stop`, `clear`, `remove`, `move`, `vol`, `mode`. Everything else is public. (Note: `follow` is intentionally NOT admin — it becomes public.)
+- **Enforcement is opt-in / backward-compatible:** `config.adminGroups === []` (the default) ⇒ no enforcement; admin commands stay open to everyone exactly as today.
+- **Fail closed:** an admin command, with enforcement on, whose sender groups cannot be determined (even after fallback) is **denied**.
+- **Group-id normalization:** `invokerGroups` are strings, `adminGroups` are numbers — compare as the same type so `"6"` matches `6`.
+- **Denial reply text (exact):** `⛔ 需要管理员权限（该命令仅限管理员服务器组）`.
+- **`adminGroups` validation:** array of non-negative integers; filter out everything else; ignore a non-array value entirely.
+- **Live config:** `BotInstance` shares the same `config` object the router mutates; the gate reads `this.config.adminGroups` live (no restart, no propagation call).
+- **Per-task tests:** run `npx vitest run <file>` (targets `.ts` directly). Before any full `npm test`, run `rm -rf dist` first — a stale untracked `dist/` makes vitest double-run compiled `.test.js` copies (known environment quirk). The repo path contains spaces (`/c/Users/saopig1/Music/teamspeak music bot`) — quote it.
+- **Frontend type-check:** `cd web && npx vue-tsc --noEmit` (must be clean).
+- **TDD + frequent commits:** every task is red→green→commit. Keep project `tsc`/`vitest` green after each task.
+
+---
+
+### Task 1: `canRunCommand` helper + admin-set as single source of truth
+
+**Files:**
+- Modify: `src/bot/commands.ts` (lines 8-16 sets; line 59-61 `isAdminCommand`)
+- Test: `src/bot/commands.test.ts` (append a new `describe` block)
+
+**Interfaces:**
+- Consumes: nothing from other tasks.
+- Produces:
+  - `export const ADMIN_COMMANDS: Set<string>` = `{stop, clear, remove, move, vol, mode}`
+  - `export function isAdminCommand(commandName: string): boolean` (unchanged signature)
+  - `export function canRunCommand(commandName: string, invokerGroups: readonly (string | number)[], adminGroups: readonly number[]): boolean` — consumed by Task 3.
+
+- [ ] **Step 1: Write the failing tests**
+
+Append to `src/bot/commands.test.ts`:
+
+```ts
+import { canRunCommand, isAdminCommand } from "./commands.js";
+
+describe("isAdminCommand classification", () => {
+  it("treats stop/clear/remove/move/vol/mode as admin", () => {
+    for (const c of ["stop", "clear", "remove", "move", "vol", "mode"]) {
+      expect(isAdminCommand(c)).toBe(true);
+    }
+  });
+  it("treats follow and play as NOT admin", () => {
+    expect(isAdminCommand("follow")).toBe(false);
+    expect(isAdminCommand("play")).toBe(false);
+  });
+});
+
+describe("canRunCommand", () => {
+  it("allows any public command regardless of groups", () => {
+    expect(canRunCommand("play", [], [6])).toBe(true);
+    expect(canRunCommand("follow", [], [6])).toBe(true);
+  });
+  it("allows admin command when enforcement is off (empty adminGroups)", () => {
+    expect(canRunCommand("stop", [], [])).toBe(true);
+  });
+  it("allows admin command when an invoker group matches (string vs number)", () => {
+    expect(canRunCommand("stop", ["6"], [6])).toBe(true);
+    expect(canRunCommand("stop", [6], [6])).toBe(true);
+    expect(canRunCommand("vol", ["8", "6"], [6])).toBe(true);
+  });
+  it("denies admin command when no invoker group matches", () => {
+    expect(canRunCommand("stop", ["8"], [6])).toBe(false);
+  });
+  it("denies admin command when invoker has no groups and enforcement is on", () => {
+    expect(canRunCommand("clear", [], [6])).toBe(false);
+  });
+});
+```
+
+- [ ] **Step 2: Run the tests to verify they fail**
+
+Run: `npx vitest run "src/bot/commands.test.ts"`
+Expected: FAIL — `canRunCommand` is not exported / not a function.
+
+- [ ] **Step 3: Implement the helper and tighten the admin set**
+
+In `src/bot/commands.ts`, delete the dead `PUBLIC_COMMANDS` export (nothing imports it; the admin set is the sole source of truth), set `ADMIN_COMMANDS` to the exact spec set (drop `follow`), and add `canRunCommand`. The file becomes:
+
+```ts
+export interface ParsedCommand {
+  name: string;
+  args: string;
+  rawArgs: string[];
+  flags: Set<string>;
+}
+
+/**
+ * The fixed set of "admin" chat commands. This is the SINGLE source of truth
+ * for which commands the permission gate restricts; reclassifying a command is
+ * a one-line edit here. Everything not in this set is public.
+ */
+export const ADMIN_COMMANDS = new Set([
+  "stop", "clear", "remove", "move", "vol", "mode",
+]);
+
+export function parseCommand(
+  message: string,
+  prefix: string,
+  aliases: Record<string, string> = {},
+): ParsedCommand | null {
+  const trimmed = message.trim();
+  if (!trimmed.startsWith(prefix)) return null;
+
+  const withoutPrefix = trimmed.slice(prefix.length);
+  if (!withoutPrefix) return null;
+
+  const parts = withoutPrefix.split(/\s+/);
+  let name = parts[0].toLowerCase();
+
+  if (aliases[name]) {
+    name = aliases[name];
+  }
+
+  const flags = new Set<string>();
+  const argParts: string[] = [];
+
+  for (let i = 1; i < parts.length; i++) {
+    if (
+      parts[i].startsWith("-") &&
+      parts[i].length === 2 &&
+      /[a-zA-Z]/.test(parts[i][1])
+    ) {
+      flags.add(parts[i][1].toLowerCase());
+    } else {
+      argParts.push(parts[i]);
+    }
+  }
+
+  return {
+    name,
+    args: argParts.join(" "),
+    rawArgs: argParts,
+    flags,
+  };
+}
+
+export function isAdminCommand(commandName: string): boolean {
+  return ADMIN_COMMANDS.has(commandName);
+}
+
+/**
+ * Decide whether a chat command may run, given the invoker's TS server groups
+ * and the configured admin groups. Pure + synchronous so it is trivially unit
+ * tested and reused by the async gate in BotInstance.
+ *
+ * Allowed iff: (1) it is a public command, OR (2) enforcement is off
+ * (adminGroups empty), OR (3) some invoker group is in adminGroups.
+ * invokerGroups (strings from TS) and adminGroups (numbers) are normalized to
+ * strings before comparison so "6" matches 6.
+ */
+export function canRunCommand(
+  commandName: string,
+  invokerGroups: readonly (string | number)[],
+  adminGroups: readonly number[],
+): boolean {
+  if (!isAdminCommand(commandName)) return true;
+  if (adminGroups.length === 0) return true;
+  const admin = new Set(adminGroups.map((g) => String(g)));
+  return invokerGroups.some((g) => admin.has(String(g)));
+}
+```
+
+- [ ] **Step 4: Run the tests to verify they pass**
+
+Run: `npx vitest run "src/bot/commands.test.ts"`
+Expected: PASS (parser tests + the new classification/canRunCommand tests).
+
+- [ ] **Step 5: Verify nothing else imported the deleted symbol**
+
+Run: `grep -rn "PUBLIC_COMMANDS" src/`
+Expected: no matches (confirms the deletion is safe).
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add "src/bot/commands.ts" "src/bot/commands.test.ts"
+git commit -m "feat(commands): add canRunCommand gate helper + admin-set source of truth"
+```
+
+---
+
+### Task 2: Surface `invokerGroups` on `TS3TextMessage`
+
+**Files:**
+- Modify: `src/ts-protocol/client.ts` (interface lines 58-64; mapping lines 205-214)
+- Test: `src/ts-protocol/text-message.test.ts` (new)
+
+**Interfaces:**
+- Consumes: nothing from other tasks.
+- Produces:
+  - `TS3TextMessage` gains `invokerGroups: string[]`.
+  - `export function toTS3TextMessage(msg: TextMessage): TS3TextMessage` — a pure mapper, used by the `textMessage` event handler and unit-testable. Consumed (the field) by Task 3.
+
+- [ ] **Step 1: Write the failing test**
+
+Create `src/ts-protocol/text-message.test.ts`:
+
+```ts
+import { describe, it, expect } from "vitest";
+import { toTS3TextMessage } from "./client.js";
+import type { TextMessage } from "@honeybbq/teamspeak-client";
+
+function makeMsg(over: Partial<TextMessage> = {}): TextMessage {
+  return {
+    invokerName: "Alice",
+    invokerUID: "uid-abc",
+    message: "!stop",
+    invokerGroups: ["6", "8"],
+    targetMode: 2,
+    targetID: 0n,
+    invokerID: 5,
+    ...over,
+  };
+}
+
+describe("toTS3TextMessage", () => {
+  it("maps core fields and stringifies invokerID", () => {
+    const r = toTS3TextMessage(makeMsg());
+    expect(r.invokerName).toBe("Alice");
+    expect(r.invokerId).toBe("5");
+    expect(r.invokerUid).toBe("uid-abc");
+    expect(r.message).toBe("!stop");
+    expect(r.targetMode).toBe(2);
+  });
+
+  it("preserves the sender's server groups", () => {
+    expect(toTS3TextMessage(makeMsg({ invokerGroups: ["6"] })).invokerGroups).toEqual(["6"]);
+  });
+
+  it("defaults missing invokerGroups to an empty array", () => {
+    const partial = {
+      invokerName: "Bob",
+      invokerUID: "u",
+      message: "!stop",
+      targetMode: 1,
+      targetID: 0n,
+      invokerID: 7,
+    } as unknown as TextMessage;
+    expect(toTS3TextMessage(partial).invokerGroups).toEqual([]);
+  });
+});
+```
+
+- [ ] **Step 2: Run the test to verify it fails**
+
+Run: `npx vitest run "src/ts-protocol/text-message.test.ts"`
+Expected: FAIL — `toTS3TextMessage` is not exported.
+
+- [ ] **Step 3: Add the field and the pure mapper, and use it in the handler**
+
+In `src/ts-protocol/client.ts`, extend the interface (add `invokerGroups`):
+
+```ts
+export interface TS3TextMessage {
+  invokerName: string;
+  invokerId: string;
+  invokerUid: string;
+  message: string;
+  targetMode: number; // 1=private, 2=channel, 3=server
+  invokerGroups: string[]; // sender's TS server-group ids; [] when not in view cache
+}
+```
+
+Add the pure mapper just below the interface (still above the `TS3Client` class):
+
+```ts
+/**
+ * Map the library's TextMessage to our wrapper. Preserves invokerGroups (the
+ * sender's TS server groups), which the library populates only when the sender
+ * is in the bot's client-view cache; otherwise it is []. Used by the chat
+ * command permission gate.
+ */
+export function toTS3TextMessage(msg: TextMessage): TS3TextMessage {
+  return {
+    invokerName: msg.invokerName,
+    invokerId: String(msg.invokerID),
+    invokerUid: msg.invokerUID,
+    message: msg.message,
+    targetMode: msg.targetMode,
+    invokerGroups: msg.invokerGroups ?? [],
+  };
+}
+```
+
+Replace the inline mapping inside `this.client.on("textMessage", ...)` (currently lines 205-214) with a call to the mapper:
+
+```ts
+    this.client.on("textMessage", (msg: TextMessage) => {
+      this.emit("textMessage", toTS3TextMessage(msg));
+    });
+```
+
+(`TextMessage` is already imported at the top of the file.)
+
+- [ ] **Step 4: Run the test to verify it passes**
+
+Run: `npx vitest run "src/ts-protocol/text-message.test.ts"`
+Expected: PASS (3 tests).
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add "src/ts-protocol/client.ts" "src/ts-protocol/text-message.test.ts"
+git commit -m "feat(ts-protocol): surface invokerGroups on TS3TextMessage via pure mapper"
+```
+
+---
+
+### Task 3: Permission gate in `handleTextMessage` (fallback lookup + fail-closed + denial reply)
+
+**Files:**
+- Modify: `src/bot/instance.ts` (imports lines 10-14; add a module constant; `handleTextMessage` lines 317-349; add two private methods)
+- Test: `src/bot/instance.test.ts` (append a new `describe` block)
+
+**Interfaces:**
+- Consumes:
+  - `canRunCommand(commandName, invokerGroups, adminGroups)` from `./commands.js` (Task 1).
+  - `TS3TextMessage.invokerGroups: string[]` (Task 2).
+  - Existing `this.tsClient.getClientsInChannel(): Promise<ClientInfo[]>` where each `ClientInfo` has `id: number` and `serverGroups: string[]` (library already parses these).
+  - Existing `this.tsClient.sendTextMessage(message: string, targetMode?: number): Promise<void>`.
+- Produces:
+  - `export const COMMAND_DENIED_MESSAGE: string` (exported so the test can assert it).
+  - Private `isCommandAllowed(commandName, msg)` and `lookupInvokerGroups(invokerId)` (exercised via prototype in the test).
+
+- [ ] **Step 1: Write the failing tests**
+
+Append to `src/bot/instance.test.ts`:
+
+```ts
+import { vi } from "vitest";
+import { COMMAND_DENIED_MESSAGE } from "./instance.js";
+import type { TS3TextMessage } from "../ts-protocol/client.js";
+
+/** Minimal `this` carrying only what handleTextMessage's gate path touches.
+ *  The gate methods live on the prototype and are attached here so calls like
+ *  `this.isCommandAllowed(...)` resolve against this same object. */
+function makeGateCtx(opts: {
+  adminGroups?: number[];
+  clients?: Array<{ id: number; serverGroups: string[] }>;
+}) {
+  const ctx: any = {
+    config: { commandPrefix: "!", commandAliases: {}, adminGroups: opts.adminGroups ?? [] },
+    logger: { info: vi.fn(), error: vi.fn() },
+    tsClient: {
+      sendTextMessage: vi.fn(async () => {}),
+      getClientsInChannel: vi.fn(async () => opts.clients ?? []),
+    },
+    executeCommand: vi.fn(async () => null),
+    isCommandAllowed: (BotInstance.prototype as any).isCommandAllowed,
+    lookupInvokerGroups: (BotInstance.prototype as any).lookupInvokerGroups,
+  };
+  return ctx;
+}
+
+function makeMsg(message: string, invokerGroups: string[] = [], invokerId = "5"): TS3TextMessage {
+  return { invokerName: "Tester", invokerId, invokerUid: "uid", message, targetMode: 2, invokerGroups };
+}
+
+const handleTextMessage = (BotInstance.prototype as any).handleTextMessage as (
+  this: unknown,
+  msg: TS3TextMessage,
+) => Promise<void>;
+
+describe("BotInstance.handleTextMessage — command permission gate", () => {
+  it("runs a public command even with enforcement on", async () => {
+    const ctx = makeGateCtx({ adminGroups: [6] });
+    await handleTextMessage.call(ctx, makeMsg("!play 晴天"));
+    expect(ctx.executeCommand).toHaveBeenCalledTimes(1);
+    expect(ctx.tsClient.sendTextMessage).not.toHaveBeenCalledWith(COMMAND_DENIED_MESSAGE);
+  });
+
+  it("runs an admin command when enforcement is off (empty adminGroups)", async () => {
+    const ctx = makeGateCtx({ adminGroups: [] });
+    await handleTextMessage.call(ctx, makeMsg("!stop"));
+    expect(ctx.executeCommand).toHaveBeenCalledTimes(1);
+  });
+
+  it("runs an admin command when the event carried a matching group", async () => {
+    const ctx = makeGateCtx({ adminGroups: [6] });
+    await handleTextMessage.call(ctx, makeMsg("!stop", ["6"]));
+    expect(ctx.executeCommand).toHaveBeenCalledTimes(1);
+    expect(ctx.tsClient.getClientsInChannel).not.toHaveBeenCalled(); // no fallback needed
+  });
+
+  it("denies an admin command when known groups do not match (no fallback, with reply)", async () => {
+    const ctx = makeGateCtx({ adminGroups: [6] });
+    await handleTextMessage.call(ctx, makeMsg("!stop", ["8"]));
+    expect(ctx.executeCommand).not.toHaveBeenCalled();
+    expect(ctx.tsClient.getClientsInChannel).not.toHaveBeenCalled();
+    expect(ctx.tsClient.sendTextMessage).toHaveBeenCalledWith(COMMAND_DENIED_MESSAGE);
+  });
+
+  it("falls back to a group lookup when the event carried no groups, and allows on match", async () => {
+    const ctx = makeGateCtx({ adminGroups: [6], clients: [{ id: 5, serverGroups: ["6"] }] });
+    await handleTextMessage.call(ctx, makeMsg("!stop", [], "5"));
+    expect(ctx.tsClient.getClientsInChannel).toHaveBeenCalledTimes(1);
+    expect(ctx.executeCommand).toHaveBeenCalledTimes(1);
+  });
+
+  it("fails closed when the fallback finds the client but no matching group", async () => {
+    const ctx = makeGateCtx({ adminGroups: [6], clients: [{ id: 5, serverGroups: ["8"] }] });
+    await handleTextMessage.call(ctx, makeMsg("!stop", [], "5"));
+    expect(ctx.executeCommand).not.toHaveBeenCalled();
+    expect(ctx.tsClient.sendTextMessage).toHaveBeenCalledWith(COMMAND_DENIED_MESSAGE);
+  });
+
+  it("fails closed when the fallback cannot find the client at all", async () => {
+    const ctx = makeGateCtx({ adminGroups: [6], clients: [] });
+    await handleTextMessage.call(ctx, makeMsg("!stop", [], "5"));
+    expect(ctx.executeCommand).not.toHaveBeenCalled();
+    expect(ctx.tsClient.sendTextMessage).toHaveBeenCalledWith(COMMAND_DENIED_MESSAGE);
+  });
+});
+```
+
+- [ ] **Step 2: Run the tests to verify they fail**
+
+Run: `npx vitest run "src/bot/instance.test.ts"`
+Expected: FAIL — `COMMAND_DENIED_MESSAGE` is not exported; `isCommandAllowed`/`lookupInvokerGroups` are undefined.
+
+- [ ] **Step 3: Implement the gate**
+
+In `src/bot/instance.ts`, change the commands import (lines 10-14) from `isAdminCommand` to `canRunCommand`:
+
+```ts
+import {
+  parseCommand,
+  canRunCommand,
+  type ParsedCommand,
+} from "./commands.js";
+```
+
+Add a module-level constant just after the imports (above `export interface BotInstanceOptions`):
+
+```ts
+/** Reply sent when a non-admin invokes an admin-only chat command. */
+export const COMMAND_DENIED_MESSAGE = "⛔ 需要管理员权限（该命令仅限管理员服务器组）";
+```
+
+Replace `handleTextMessage` (lines 317-349) so the dead stub becomes the real gate:
+
+```ts
+  private async handleTextMessage(msg: TS3TextMessage): Promise<void> {
+    const parsed = parseCommand(
+      msg.message,
+      this.config.commandPrefix,
+      this.config.commandAliases
+    );
+    if (!parsed) return;
+
+    if (!(await this.isCommandAllowed(parsed.name, msg))) {
+      this.logger.info(
+        { command: parsed.name, invoker: msg.invokerName },
+        "Command denied: invoker not in adminGroups"
+      );
+      try {
+        await this.tsClient.sendTextMessage(COMMAND_DENIED_MESSAGE);
+      } catch (sendErr) {
+        this.logger.error({ err: sendErr }, "Failed to send permission-denied message to chat");
+      }
+      return;
+    }
+
+    this.logger.info(
+      { command: parsed.name, args: parsed.args, invoker: msg.invokerName },
+      "Command received"
+    );
+
+    try {
+      const response = await this.executeCommand(parsed, msg);
+      if (response) {
+        await this.tsClient.sendTextMessage(response);
+      }
+    } catch (err) {
+      this.logger.error({ err, command: parsed.name }, "Command execution error");
+      try {
+        await this.tsClient.sendTextMessage(
+          `Error: ${(err as Error).message}`
+        );
+      } catch (sendErr) {
+        this.logger.error({ err: sendErr }, "Failed to send error message to chat");
+      }
+    }
+  }
+
+  /**
+   * Decide whether a chat command may run for this sender. Reads adminGroups
+   * live from this.config (the router mutates the same object). Only performs
+   * the async group lookup when the synchronous decision is "deny because the
+   * event carried no groups" — i.e. an admin command, enforcement on, and
+   * empty invokerGroups. Fails closed if groups remain undeterminable.
+   */
+  private async isCommandAllowed(commandName: string, msg: TS3TextMessage): Promise<boolean> {
+    const adminGroups = this.config.adminGroups;
+    if (canRunCommand(commandName, msg.invokerGroups, adminGroups)) return true;
+    // Here: admin command, enforcement on, and the provided groups did not match.
+    // If the event actually carried groups, this is a genuine deny — no lookup.
+    if (msg.invokerGroups.length > 0) return false;
+    // Groups unknown (sender not in the view cache): one targeted lookup, then
+    // re-decide. canRunCommand([], …) is false ⇒ fail-closed when still unknown.
+    const groups = await this.lookupInvokerGroups(msg.invokerId);
+    return canRunCommand(commandName, groups, adminGroups);
+  }
+
+  /**
+   * Best-effort lookup of a sender's server groups by client id, via the
+   * channel client list (whose entries already carry parsed serverGroups).
+   * Returns [] when the client can't be found or the query fails (→ deny).
+   */
+  private async lookupInvokerGroups(invokerId: string): Promise<string[]> {
+    const clid = Number(invokerId);
+    if (!Number.isFinite(clid) || clid <= 0) return [];
+    try {
+      const clients = await this.tsClient.getClientsInChannel();
+      const match = clients.find((c) => c.id === clid);
+      return match?.serverGroups ?? [];
+    } catch {
+      return [];
+    }
+  }
+```
+
+- [ ] **Step 4: Run the gate tests to verify they pass**
+
+Run: `npx vitest run "src/bot/instance.test.ts"`
+Expected: PASS (existing `runExclusive` tests + the 7 new gate tests).
+
+- [ ] **Step 5: Confirm the live-config invariant**
+
+Confirm `BotInstance` reads `adminGroups` from the shared, mutable config — not a copy. The constructor stores `this.config = options.config` (line 91 region) and the router (`src/web/api/bot.ts`) mutates that same object; no propagation call is needed. Quick check:
+
+Run: `grep -n "this.config = options.config\|this.config.adminGroups" "src/bot/instance.ts"`
+Expected: shows the assignment and the gate read (proves the gate uses the live reference).
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add "src/bot/instance.ts" "src/bot/instance.test.ts"
+git commit -m "feat(bot): gate admin chat commands on adminGroups with fallback + deny reply"
+```
+
+---
+
+### Task 4: Read/write `adminGroups` in the settings endpoints
+
+**Files:**
+- Modify: `src/web/api/bot.ts` (GET `/settings` lines 35-41; POST `/settings` lines 45-97)
+- Test: `src/web/api/bot.test.ts` (append `it` cases to the first `describe("bot router /settings", …)` block)
+
+**Interfaces:**
+- Consumes: existing `config.adminGroups: number[]` (already declared in `src/data/config.ts`, default `[]`).
+- Produces: `GET /api/bot/settings` returns `adminGroups: number[]`; `POST /api/bot/settings` accepts, validates, persists, and echoes `adminGroups`.
+
+- [ ] **Step 1: Write the failing tests**
+
+Append these `it` cases inside the existing first `describe("bot router /settings", …)` block in `src/web/api/bot.test.ts` (it already wires `app`, `config`, and an admin `cookie`):
+
+```ts
+  it("GET /settings includes adminGroups reflecting config", async () => {
+    config.adminGroups = [6, 8];
+    const res = await request(app).get("/api/bot/settings").set("Cookie", cookie);
+    expect(res.status).toBe(200);
+    expect(res.body.adminGroups).toEqual([6, 8]);
+  });
+
+  it("POST /settings persists a validated adminGroups and GET returns it", async () => {
+    const res = await request(app)
+      .post("/api/bot/settings")
+      .set("Cookie", cookie)
+      .send({ adminGroups: [6, 8] });
+    expect(res.status).toBe(200);
+    expect(res.body.adminGroups).toEqual([6, 8]);
+    expect(config.adminGroups).toEqual([6, 8]);
+    const followUp = await request(app).get("/api/bot/settings").set("Cookie", cookie);
+    expect(followUp.body.adminGroups).toEqual([6, 8]);
+  });
+
+  it("POST /settings filters invalid adminGroups entries (negative, non-integer, non-number)", async () => {
+    const res = await request(app)
+      .post("/api/bot/settings")
+      .set("Cookie", cookie)
+      .send({ adminGroups: [6, -1, 2.5, "x", 8] });
+    expect(res.status).toBe(200);
+    expect(config.adminGroups).toEqual([6, 8]);
+  });
+
+  it("POST /settings ignores a non-array adminGroups (leaves config unchanged)", async () => {
+    config.adminGroups = [6];
+    const res = await request(app)
+      .post("/api/bot/settings")
+      .set("Cookie", cookie)
+      .send({ adminGroups: "6" });
+    expect(res.status).toBe(200);
+    expect(config.adminGroups).toEqual([6]);
+  });
+```
+
+- [ ] **Step 2: Run the tests to verify they fail**
+
+Run: `npx vitest run "src/web/api/bot.test.ts"`
+Expected: FAIL — `res.body.adminGroups` is `undefined`; the POST does not persist `adminGroups`.
+
+- [ ] **Step 3: Extend the GET handler**
+
+In `src/web/api/bot.ts`, add `adminGroups` to the GET `/settings` response (the handler at lines 35-41):
+
+```ts
+  router.get("/settings", requireNotGuest, (_req, res) => {
+    res.json({
+      idleTimeoutMinutes: config.idleTimeoutMinutes ?? 0,
+      autoPauseOnEmpty: config.autoPauseOnEmpty,
+      adminGroups: config.adminGroups ?? [],
+      guestMode: config.guestMode,
+    });
+  });
+```
+
+- [ ] **Step 4: Extend the POST handler**
+
+In the POST `/settings` handler: (a) pull `adminGroups` out of `req.body`; (b) validate + assign before `saveConfig`; (c) echo it in the response. Change the destructuring line (46):
+
+```ts
+    const { idleTimeoutMinutes, autoPauseOnEmpty, guestMode, adminGroups } = req.body;
+```
+
+Add this block just before `saveConfig(configPath, config);` (line 77):
+
+```ts
+    if (Array.isArray(adminGroups)) {
+      config.adminGroups = adminGroups.filter(
+        (g: unknown): g is number =>
+          typeof g === "number" && Number.isInteger(g) && g >= 0,
+      );
+    }
+```
+
+Add `adminGroups` to BOTH `res.json({ … })` bodies in this handler (the success response near line 92, and — if present — keep them consistent):
+
+```ts
+    res.json({
+      idleTimeoutMinutes: config.idleTimeoutMinutes ?? 0,
+      autoPauseOnEmpty: config.autoPauseOnEmpty,
+      adminGroups: config.adminGroups ?? [],
+      guestMode: config.guestMode,
+    });
+```
+
+- [ ] **Step 5: Run the tests to verify they pass**
+
+Run: `npx vitest run "src/web/api/bot.test.ts"`
+Expected: PASS (existing settings/guest-mode tests + the 4 new adminGroups tests).
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add "src/web/api/bot.ts" "src/web/api/bot.test.ts"
+git commit -m "feat(api): read/write adminGroups in bot settings endpoints"
+```
+
+---
+
+### Task 5: Admin-only "命令权限" section in Settings.vue
+
+**Files:**
+- Modify: `web/src/views/Settings.vue` (template: add a section after the Guest Mode section, before the Bot Profile section ~line 506; script: add state + handlers near the guest-mode block ~line 1093; hydrate in `loadIdleTimeout` ~line 1024)
+
+**Interfaces:**
+- Consumes: `GET /api/bot/settings` → `adminGroups: number[]`; `POST /api/bot/settings` with `{ adminGroups: number[] }` (Task 4). Existing `session.isAdmin.value`.
+- Produces: UI only.
+
+- [ ] **Step 1: Add the template section**
+
+In `web/src/views/Settings.vue`, insert this `<section>` immediately AFTER the closing `</section>` of the Guest Mode block (the one whose title is `游客模式`, ends ~line 505) and BEFORE the `<!-- Bot Profile … -->` section:
+
+```html
+    <!-- Command Permissions (admin only) -->
+    <section v-if="session.isAdmin.value" class="settings-section">
+      <h2 class="section-title">命令权限</h2>
+      <p class="profile-section-hint">
+        限制谁能在 TeamSpeak 聊天里运行管理类命令（stop / clear / remove / move / vol / mode）。
+        填写允许的服务器组 ID（逗号分隔）。留空 = 不限制，所有人可用。如何查看服务器组 ID 见 README。
+      </p>
+      <div class="setting-row">
+        <div class="prefix-input-wrap">
+          <input v-model="adminGroupsText" class="input input-sm" placeholder="如 6, 8" />
+          <button class="btn-primary" :disabled="adminGroupsSaving" @click="saveAdminGroups">
+            {{ adminGroupsSaving ? '保存中…' : '保存' }}
+          </button>
+        </div>
+      </div>
+    </section>
+```
+
+- [ ] **Step 2: Add the script state + handlers**
+
+In the `<script setup>` block, add this just after the guest-mode block (after `saveGuestMode` closes, ~line 1093):
+
+```ts
+// --- Command permissions (admin only) ---
+const adminGroupsText = ref('');
+const adminGroupsSaving = ref(false);
+
+function applyAdminGroupsFromServer(groups: unknown) {
+  if (Array.isArray(groups)) {
+    adminGroupsText.value = groups.filter((g) => typeof g === 'number').join(', ');
+  }
+}
+
+function parseAdminGroups(text: string): number[] {
+  return text
+    .split(',')
+    .map((s) => s.trim())
+    .filter((s) => s.length > 0)
+    .map((s) => Number(s))
+    .filter((n) => Number.isInteger(n) && n >= 0);
+}
+
+async function saveAdminGroups() {
+  adminGroupsSaving.value = true;
+  try {
+    const res = await axios.post('/api/bot/settings', { adminGroups: parseAdminGroups(adminGroupsText.value) });
+    applyAdminGroupsFromServer(res.data?.adminGroups);
+  } catch { /* ignore */ } finally {
+    adminGroupsSaving.value = false;
+  }
+}
+```
+
+- [ ] **Step 3: Hydrate on load**
+
+In `loadIdleTimeout` (the existing function ~lines 1024-1031), add the hydrate call alongside `applyGuestModeFromServer`:
+
+```ts
+async function loadIdleTimeout() {
+  try {
+    const res = await axios.get('/api/bot/settings');
+    idleTimeout.value = res.data.idleTimeoutMinutes ?? 0;
+    autoPauseOnEmpty.value = res.data.autoPauseOnEmpty ?? false;
+    applyGuestModeFromServer(res.data.guestMode);
+    applyAdminGroupsFromServer(res.data.adminGroups);
+  } catch { /* ignore */ }
+}
+```
+
+- [ ] **Step 4: Type-check the frontend**
+
+Run: `cd "web" && npx vue-tsc --noEmit`
+Expected: no errors.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add "web/src/views/Settings.vue"
+git commit -m "feat(web): admin-only command-permission (adminGroups) settings section"
+```
+
+---
+
+### Task 6: Document the feature in the README
+
+**Files:**
+- Modify: `README.md`
+
+**Interfaces:**
+- Consumes: nothing (docs).
+- Produces: user-facing documentation of the feature + how to find TS server-group IDs.
+
+- [ ] **Step 1: Locate the insertion point**
+
+Run: `grep -n "游客模式\|Guest\|权限\|adminGroups" "README.md"`
+Expected: shows the guest-mode / permissions area. Insert the new subsection immediately after the guest-mode documentation block (or, if there is a dedicated permissions/features section, at its end).
+
+- [ ] **Step 2: Add the documentation block**
+
+Insert this markdown at the chosen point:
+
+```markdown
+### TeamSpeak 命令权限（管理类命令限制）
+
+默认情况下，频道里任何人都能运行所有聊天命令。你可以把一组「管理类」命令限制为只有特定 TeamSpeak 服务器组的成员才能运行：
+
+- 受限命令：`stop`、`clear`、`remove`、`move`、`vol`、`mode`
+- 其余命令（点歌、队列、跳过、歌词等）始终对所有人开放
+- **默认不限制**：管理服务器组列表为空时，所有命令对所有人开放（向后兼容）
+
+**配置方式**
+
+- 网页端：设置 → 命令权限，填写允许的服务器组 ID（逗号分隔），保存即时生效。
+- 或编辑 `config.json` 的 `adminGroups`（数字数组），例如 `"adminGroups": [6, 8]`。
+
+填入任意服务器组 ID 后，限制立即开启：只有属于这些组之一的用户才能运行受限命令，其他人会收到「⛔ 需要管理员权限」的提示。
+
+> 提示（fail-closed）：当受限命令来自一个机器人当前看不到其服务器组的发送者（例如不在机器人所在频道的私聊），机器人会尝试查询其分组；若仍无法确定，则拒绝执行。
+
+**如何查看服务器组 ID**
+
+在 TeamSpeak 客户端中打开「权限 → 服务器组」（Permissions → Server Groups）对话框，选中某个组后，其 ID 会显示在标题栏/状态栏；或在服务器组管理界面中查看每个组对应的数字 ID。把需要授权的组 ID 填入上面的设置即可。
+```
+
+- [ ] **Step 3: Sanity-check the docs render**
+
+Run: `grep -n "命令权限\|adminGroups" "README.md"`
+Expected: shows the newly added section.
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add "README.md"
+git commit -m "docs: document TeamSpeak chat-command permission control"
+```
+
+---
+
+## Final verification (after all tasks)
+
+- [ ] Remove stale compiled output, then run the full suite:
+
+```bash
+rm -rf dist
+npm test
+```
+Expected: all tests pass (the new `canRunCommand`, `toTS3TextMessage`, gate, and `adminGroups` settings tests included).
+
+- [ ] Full build (backend `tsc` + frontend `vue-tsc` + vite):
+
+```bash
+npm run build
+```
+Expected: SUCCESS (no type errors).
@@ -0,0 +1,116 @@
+# TeamSpeak chat-command permission control — design
+
+**Origin:** User request — "给 ts 命令也加上权限控制" (give the TS chat commands permission control too, like the WebUI already has). Completes the unused `adminGroups` scaffold the original authors left behind.
+**Date:** 2026-06-25
+**Status:** Approved (brainstorm), pending implementation plan
+
+## Scope
+
+Add permission control to **TeamSpeak chat commands** (`!play`, `!add`, `!stop`, …). Today any client in a channel with the bot can run any command; only the WebUI path is permission-gated. This adds a **binary admin gate** keyed on the sender's **TS server groups**: a fixed set of "admin" commands may be restricted to members of configured admin server-groups, while all other commands stay public. Enforcement is **opt-in and backward-compatible** — it activates only once an admin lists their server-group ID(s).
+
+The privileged server-groups are configured in `config.adminGroups` (already declared, currently unused) and become editable from the WebUI.
+
+## Problem
+
+`src/bot/commands.ts` already declares `PUBLIC_COMMANDS` / `ADMIN_COMMANDS` sets and an `isAdminCommand()` helper, and `src/bot/instance.ts:325` has the stub `// TODO: Check if invoker is in adminGroups` — but none of it gates anything. `config.adminGroups: number[]` (`src/data/config.ts:21,46`) is documented as a legacy placeholder and read nowhere. So chat commands are unauthenticated: anyone can `!stop`, `!clear`, `!remove`, move the bot, change volume/mode. The WebUI, by contrast, gates everything via `authorize()` at the HTTP layer.
+
+`executeCommand` (`instance.ts:351`) is **shared** by the chat handler and the WebUI player router; the WebUI gates at the HTTP layer, so the chat gate must live in the **chat handler**, never inside `executeCommand` (else the already-gated WebUI would be double-gated).
+
+## Decisions (from brainstorm)
+
+1. **Binary admin gate**, not per-group capabilities and not a whole-bot allowlist. Reuses the existing `adminGroups` scaffold.
+2. **Admin command set (fixed, one source of truth):** `stop`, `clear`, `remove`, `move`, `vol`, `mode`. Everything else is public. The set lives in one constant so reclassifying a command is a one-line change.
+3. **Default = open / opt-in (backward-compatible):** when `config.adminGroups` is empty (the default), there is **no enforcement** — admin commands stay open to everyone, exactly as today. Enforcement turns on only when `adminGroups` is non-empty.
+4. **Identity key = TS server groups**, matched against `adminGroups`.
+5. **Fail-closed on undeterminable groups:** if an admin command arrives, enforcement is on, and the sender's groups cannot be determined (even after a fallback lookup), **deny**.
+6. **Reply on deny:** the bot sends the sender a brief permission-denied message (silent denial is confusing; the bot already replies to commands).
+7. **Config surface:** `adminGroups` becomes editable from an admin-only WebUI Settings section, live-applied via the existing `/api/bot/settings` endpoint; `config.json` continues to work.
+
+## Permission model
+
+Tier definitions live in `src/bot/commands.ts` (repurpose the existing dead sets; the admin set is the source of truth):
+- **Admin commands:** `stop`, `clear`, `remove`, `move`, `vol`, `mode`.
+- **Public commands:** all others (`play`, `add`, `playnext`/`pn`, `skip`/`next`, `prev`, `pause`, `resume`, `now`, `queue`/`list`, `lyrics`, `vote`, `help`, `search`/`find`, `playlist`, `album`, `artist`, `fm`).
+
+**Enforcement rule** — a command is **allowed** iff:
+1. it is a public command, **OR**
+2. `config.adminGroups` is empty (enforcement off), **OR**
+3. the sender's server groups ∩ `config.adminGroups` ≠ ∅.
+
+Otherwise it is **denied** (no execution; a denial reply is sent).
+
+Expressed as a pure, unit-testable helper (no TS/async dependency):
+```ts
+// returns true = allowed, false = denied
+function canRunCommand(
+  commandName: string,
+  invokerGroups: readonly (string | number)[],
+  adminGroups: readonly number[]
+): boolean
+```
+- not an admin command → `true`.
+- admin command, `adminGroups.length === 0` → `true` (enforcement off).
+- admin command, non-empty `adminGroups` → `true` iff any `invokerGroups` value (normalized to number/string consistently) is in `adminGroups`, else `false`.
+
+> Note: `invokerGroups` from TS are strings; `adminGroups` are numbers. Normalize both sides (compare as the same type) to avoid `"6" !== 6` bugs.
+
+## Identity resolution
+
+The TS library already delivers the sender's server groups on each chat event (`TextMessage.invokerGroups: string[]` in `@honeybbq/teamspeak-client`), but the wrapper type `TS3TextMessage` (`src/ts-protocol/client.ts:58-64`) and its mapping (`client.ts:205-214`) **drop** it.
+
+Changes:
+1. Add `invokerGroups: string[]` to `TS3TextMessage` and populate it from `msg.invokerGroups` in the mapping.
+2. **Availability caveat:** `invokerGroups` is populated only when the sender's client is in the bot's local cache (typically same channel / in view). For a private message from an unseen client, it is `[]`.
+3. **Fallback lookup (only when needed):** in the gate, if the command is admin-gated **and** enforcement is on **and** `invokerGroups` is empty, perform a targeted lookup of the sender's groups keyed on `invokerId` (clid) — reuse the already-wrapped `getClientsInChannel()` (`client.ts:314-323`, whose `ClientInfo` carries `serverGroups`), or add a thin wrapper around the library's `getClientInfo(client, clid)` for a precise `clientinfo` query. This query is skipped entirely for public commands, when enforcement is off, and when the event already carried groups (the common "listener in the channel types `!stop`" case).
+4. **Fail-closed:** if after the fallback the groups are still unknown, deny the admin command.
+
+## Enforcement seam
+
+In `handleTextMessage` (`src/bot/instance.ts:317`), replace the dead stub at `instance.ts:325-327` with the real check, placed after `parseCommand` succeeds and **before** `executeCommand` (`instance.ts:335`):
+- compute `allowed` via `canRunCommand(parsed.name, msg.invokerGroups, this.config.adminGroups)`, performing the async fallback lookup only when the synchronous check is "deny due to empty groups on an admin command with enforcement on";
+- if denied → send the denial reply to `msg` (respecting its `targetMode`/sender) and return without executing;
+- if allowed → `executeCommand(parsed, msg)` as today.
+
+`executeCommand` stays permission-agnostic, so the WebUI path is unaffected.
+
+**Live config:** `BotInstance` already holds the shared `config` object by reference (passed through `BotInstanceOptions`); `POST /api/bot/settings` mutates that same object in place, so reading `this.config.adminGroups` in the gate reflects edits immediately — no restart, no re-wiring. (Implementation must confirm the instance reads `adminGroups` from the live `config` reference, not a copied-at-construction value.)
+
+## Denied UX
+
+The bot replies to the sender with a short bilingual-ish message, e.g. `⛔ 需要管理员权限（该命令仅限管理员服务器组）`, via the same reply mechanism the command handlers already use, honoring the message's `targetMode` (private vs channel). No execution occurs.
+
+## Config surface
+
+**Backend** (`src/web/api/bot.ts`): extend the existing settings endpoints (already admin-gated: `GET` behind `requireNotGuest`, `POST` behind `requirePermission("bot.manage")`):
+- `GET /api/bot/settings` → also return `adminGroups: number[]`.
+- `POST /api/bot/settings` → also accept `adminGroups`; validate it is an array of non-negative integers (filter/reject otherwise), assign to `config.adminGroups`, `saveConfig`. Reuses the in-place-mutation + `saveConfig` pattern already used for idle-timeout/auto-pause/guestMode, so it is live-applied.
+
+**Frontend** (`web/src/views/Settings.vue`): a new admin-only section **"命令权限 / Command permissions"** (`v-if="session.isAdmin.value"`), mirroring the idle-timeout/guest-mode sections:
+- a text input for comma-separated server-group IDs (parsed to `number[]`, ignoring blanks/non-numbers), a Save button calling `POST /api/bot/settings`, hydrated by the existing `loadIdleTimeout()` GET;
+- hint: "仅这些组可运行 stop/clear/remove/move/vol/mode；留空 = 不限制（所有人可用）。如何查看服务器组 ID 见 README。"
+
+**`config.json`**: `adminGroups` continues to work for file-based config.
+
+## Testing
+
+- **`canRunCommand` unit tests** (`src/bot/commands.test.ts` or a new file): public command always allowed; admin command with empty `adminGroups` allowed; admin command with a matching group allowed; admin command with no matching group denied; string-vs-number normalization (`["6"]` matches `[6]`).
+- **Handler gate tests:** a denied admin command does NOT call `executeCommand` and triggers a denial reply; an allowed admin command (matching group) and any public command DO call `executeCommand`. (Use a fake `msg` + a `config` with `adminGroups` set; stub the reply + `executeCommand`.)
+- **Fallback path:** admin command with empty `invokerGroups` + enforcement on triggers the group lookup; if the lookup yields a matching group → allowed; if it yields nothing → denied (fail-closed).
+- **Settings round-trip** (`src/web/api/bot.test.ts`): `POST /api/bot/settings` persists a validated `adminGroups`; `GET` returns it; invalid values (non-array, negative, non-integer) are rejected/filtered.
+- **Frontend:** `vue-tsc --noEmit` clean.
+
+## Non-goals (YAGNI)
+
+- No per-group capability map and no whole-bot allowlist (binary admin gate only).
+- No per-command customization of the admin/public split in the UI (the set is a code constant; reclassifying is a one-line edit).
+- No server-group picker UI (admin types IDs; a picker that lists the bot's visible groups is a possible future enhancement).
+- No new chat *management* commands.
+- No change to the WebUI authorization model or `executeCommand` semantics.
+
+## Key files touched
+
+Backend: `src/bot/commands.ts` (admin-set constant + `canRunCommand` helper, repurpose the dead sets; +test), `src/bot/instance.ts` (gate in `handleTextMessage`, denial reply, live `adminGroups`), `src/ts-protocol/client.ts` (surface `invokerGroups` on `TS3TextMessage`; possibly a `getClientInfo` wrapper for the fallback), `src/web/api/bot.ts` (settings read/write `adminGroups`; +test). Possibly `src/data/config.ts` (no schema change; `adminGroups` already exists).
+
+Frontend: `web/src/views/Settings.vue` (admin-only 命令权限 section).
+
+Docs: `README.md` (document the feature + how to find TS server-group IDs).
@@ -17,7 +17,7 @@
    "@discordjs/opus": "^0.10.0",
    "@honeybbq/teamspeak-client": "^0.2.1",
    "@koa/router": "^15.4.0",
-    "@sansenjian/qq-music-api": "^2.2.10",
+    "@sansenjian/qq-music-api": "~2.4.0",
    "axios": "^1.14.0",
    "bcryptjs": "^2.4.3",
    "better-sqlite3": "^12.8.0",
@@ -28,7 +28,7 @@
    "koa": "^3.2.0",
    "koa-bodyparser": "^4.4.1",
    "koa-static": "^5.0.0",
-    "NeteaseCloudMusicApi": "^4.30.0",
+    "NeteaseCloudMusicApi": "~4.32.0",
    "pino": "^10.3.1",
    "ts3-nodejs-library": "^3.5.1",
    "tweetnacl": "^1.0.3",
@@ -10,7 +10,7 @@ export interface QueuedSong {
  name: string;
  artist: string;
  album: string;
-  platform: "netease" | "qq" | "bilibili" | "youtube";
+  platform: "netease" | "qq" | "bilibili" | "youtube" | "local" | "kugou";
  url?: string; // resolved lazily at play time
  coverUrl: string;
  duration: number; // seconds
@@ -1,5 +1,5 @@
 import { describe, it, expect } from "vitest";
-import { parseCommand } from "./commands.js";
+import { parseCommand, canRunCommand, isAdminCommand } from "./commands.js";

 describe("Command Parser", () => {
  it("parses simple command", () => {
@@ -60,3 +60,36 @@ describe("Command Parser", () => {
    expect(result!.args).toBe("3");
  });
 });
+
+describe("isAdminCommand classification", () => {
+  it("treats stop/clear/remove/move/vol/mode as admin", () => {
+    for (const c of ["stop", "clear", "remove", "move", "vol", "mode"]) {
+      expect(isAdminCommand(c)).toBe(true);
+    }
+  });
+  it("treats follow and play as NOT admin", () => {
+    expect(isAdminCommand("follow")).toBe(false);
+    expect(isAdminCommand("play")).toBe(false);
+  });
+});
+
+describe("canRunCommand", () => {
+  it("allows any public command regardless of groups", () => {
+    expect(canRunCommand("play", [], [6])).toBe(true);
+    expect(canRunCommand("follow", [], [6])).toBe(true);
+  });
+  it("allows admin command when enforcement is off (empty adminGroups)", () => {
+    expect(canRunCommand("stop", [], [])).toBe(true);
+  });
+  it("allows admin command when an invoker group matches (string vs number)", () => {
+    expect(canRunCommand("stop", ["6"], [6])).toBe(true);
+    expect(canRunCommand("stop", [6], [6])).toBe(true);
+    expect(canRunCommand("vol", ["8", "6"], [6])).toBe(true);
+  });
+  it("denies admin command when no invoker group matches", () => {
+    expect(canRunCommand("stop", ["8"], [6])).toBe(false);
+  });
+  it("denies admin command when invoker has no groups and enforcement is on", () => {
+    expect(canRunCommand("clear", [], [6])).toBe(false);
+  });
+});
@@ -5,14 +5,13 @@ export interface ParsedCommand {
  flags: Set<string>;
 }

-export const PUBLIC_COMMANDS = new Set([
-  "play", "add", "queue", "list", "now", "lyrics", "vote", "help",
-  "playlist", "album", "fm", "prev", "next", "skip", "pause", "resume",
-  "artist",
-]);
-
+/**
+ * The fixed set of "admin" chat commands. This is the SINGLE source of truth
+ * for which commands the permission gate restricts; reclassifying a command is
+ * a one-line edit here. Everything not in this set is public.
+ */
 export const ADMIN_COMMANDS = new Set([
-  "stop", "clear", "move", "vol", "mode", "follow", "remove",
+  "stop", "clear", "remove", "move", "vol", "mode",
 ]);

 export function parseCommand(
@@ -59,3 +58,24 @@ export function parseCommand(
 export function isAdminCommand(commandName: string): boolean {
  return ADMIN_COMMANDS.has(commandName);
 }
+
+/**
+ * Decide whether a chat command may run, given the invoker's TS server groups
+ * and the configured admin groups. Pure + synchronous so it is trivially unit
+ * tested and reused by the async gate in BotInstance.
+ *
+ * Allowed iff: (1) it is a public command, OR (2) enforcement is off
+ * (adminGroups empty), OR (3) some invoker group is in adminGroups.
+ * invokerGroups (strings from TS) and adminGroups (numbers) are normalized to
+ * strings before comparison so "6" matches 6.
+ */
+export function canRunCommand(
+  commandName: string,
+  invokerGroups: readonly (string | number)[],
+  adminGroups: readonly number[],
+): boolean {
+  if (!isAdminCommand(commandName)) return true;
+  if (adminGroups.length === 0) return true;
+  const admin = new Set(adminGroups.map((g) => String(g)));
+  return invokerGroups.some((g) => admin.has(String(g)));
+}
@@ -1,5 +1,6 @@
-import { describe, it, expect } from "vitest";
-import { BotInstance } from "./instance.js";
+import { describe, it, expect, vi } from "vitest";
+import { BotInstance, COMMAND_DENIED_MESSAGE } from "./instance.js";
+import type { TS3TextMessage } from "../ts-protocol/client.js";

 // Constructing a real BotInstance is heavy (spawns a TS3Client, AudioPlayer,
 // reads avatars, etc.), and runExclusive only touches a single private field
@@ -110,3 +111,163 @@ describe("BotInstance.runExclusive — serialization", () => {
    ]);
  });
 });
+
+/** Minimal `this` carrying only what handleTextMessage's gate path touches.
+ *  The gate methods live on the prototype and are attached here so calls like
+ *  `this.isCommandAllowed(...)` resolve against this same object. */
+function makeGateCtx(opts: {
+  adminGroups?: number[];
+  lookupGroups?: string[];
+  lookupThrows?: boolean;
+}) {
+  const ctx: any = {
+    config: { commandPrefix: "!", commandAliases: {}, adminGroups: opts.adminGroups ?? [] },
+    logger: { info: vi.fn(), error: vi.fn() },
+    tsClient: {
+      sendTextMessage: vi.fn(async () => {}),
+      getClientServerGroups: vi.fn(async () => {
+        if (opts.lookupThrows) throw new Error("query failed");
+        return opts.lookupGroups ?? [];
+      }),
+    },
+    executeCommand: vi.fn(async () => null),
+    isCommandAllowed: (BotInstance.prototype as any).isCommandAllowed,
+    lookupInvokerGroups: (BotInstance.prototype as any).lookupInvokerGroups,
+  };
+  return ctx;
+}
+
+function makeMsg(message: string, invokerGroups: string[] = [], invokerId = "5"): TS3TextMessage {
+  return { invokerName: "Tester", invokerId, invokerUid: "uid", message, targetMode: 2, invokerGroups };
+}
+
+const handleTextMessage = (BotInstance.prototype as any).handleTextMessage as (
+  this: unknown,
+  msg: TS3TextMessage,
+) => Promise<void>;
+
+describe("BotInstance.handleTextMessage — command permission gate", () => {
+  it("runs a public command with no group lookup, even under enforcement", async () => {
+    const ctx = makeGateCtx({ adminGroups: [6] });
+    await handleTextMessage.call(ctx, makeMsg("!play 晴天", ["6"]));
+    expect(ctx.executeCommand).toHaveBeenCalledTimes(1);
+    expect(ctx.tsClient.getClientServerGroups).not.toHaveBeenCalled();
+    expect(ctx.tsClient.sendTextMessage).not.toHaveBeenCalledWith(COMMAND_DENIED_MESSAGE);
+  });
+
+  it("runs an admin command with no lookup when enforcement is off", async () => {
+    const ctx = makeGateCtx({ adminGroups: [] });
+    await handleTextMessage.call(ctx, makeMsg("!stop"));
+    expect(ctx.executeCommand).toHaveBeenCalledTimes(1);
+    expect(ctx.tsClient.getClientServerGroups).not.toHaveBeenCalled();
+  });
+
+  it("allows an enforced admin command when the live lookup returns a matching group", async () => {
+    const ctx = makeGateCtx({ adminGroups: [6], lookupGroups: ["6"] });
+    await handleTextMessage.call(ctx, makeMsg("!stop"));
+    expect(ctx.tsClient.getClientServerGroups).toHaveBeenCalledTimes(1);
+    expect(ctx.executeCommand).toHaveBeenCalledTimes(1);
+  });
+
+  it("denies an enforced admin command when the live lookup has no matching group", async () => {
+    const ctx = makeGateCtx({ adminGroups: [6], lookupGroups: ["8"] });
+    await handleTextMessage.call(ctx, makeMsg("!stop"));
+    expect(ctx.executeCommand).not.toHaveBeenCalled();
+    expect(ctx.tsClient.sendTextMessage).toHaveBeenCalledWith(COMMAND_DENIED_MESSAGE);
+  });
+
+  it("fails closed when the live lookup returns no groups", async () => {
+    const ctx = makeGateCtx({ adminGroups: [6], lookupGroups: [] });
+    await handleTextMessage.call(ctx, makeMsg("!stop"));
+    expect(ctx.executeCommand).not.toHaveBeenCalled();
+    expect(ctx.tsClient.sendTextMessage).toHaveBeenCalledWith(COMMAND_DENIED_MESSAGE);
+  });
+
+  it("fails closed when the live lookup throws", async () => {
+    const ctx = makeGateCtx({ adminGroups: [6], lookupThrows: true });
+    await handleTextMessage.call(ctx, makeMsg("!stop"));
+    expect(ctx.executeCommand).not.toHaveBeenCalled();
+    expect(ctx.tsClient.sendTextMessage).toHaveBeenCalledWith(COMMAND_DENIED_MESSAGE);
+  });
+
+  it("ignores stale event groups: a demoted sender (cached match) is denied by the live lookup", async () => {
+    const ctx = makeGateCtx({ adminGroups: [6], lookupGroups: ["8"] });
+    await handleTextMessage.call(ctx, makeMsg("!stop", ["6"]));
+    expect(ctx.executeCommand).not.toHaveBeenCalled();
+    expect(ctx.tsClient.sendTextMessage).toHaveBeenCalledWith(COMMAND_DENIED_MESSAGE);
+  });
+
+  it("uses live groups, not stale event groups: a freshly-promoted sender is allowed", async () => {
+    const ctx = makeGateCtx({ adminGroups: [6], lookupGroups: ["6"] });
+    await handleTextMessage.call(ctx, makeMsg("!stop", ["8"]));
+    expect(ctx.executeCommand).toHaveBeenCalledTimes(1);
+  });
+
+  it("resolves out-of-channel senders server-wide: empty event groups but a matching live group → allowed", async () => {
+    const ctx = makeGateCtx({ adminGroups: [6], lookupGroups: ["6"] });
+    await handleTextMessage.call(ctx, makeMsg("!stop", [], "5"));
+    expect(ctx.tsClient.getClientServerGroups).toHaveBeenCalledTimes(1);
+    expect(ctx.executeCommand).toHaveBeenCalledTimes(1);
+  });
+});
+
+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: [] });
+    const longResponse = Array.from(
+      { length: 200 },
+      (_, i) => `歌词 line number ${i} with some content`,
+    ).join("\n");
+    ctx.executeCommand = vi.fn(async () => longResponse);
+
+    await handleTextMessage.call(ctx, makeMsg("!lyrics"));
+
+    const calls = ctx.tsClient.sendTextMessage.mock.calls;
+    expect(calls.length).toBeGreaterThan(1);
+    for (const [chunk] of calls) {
+      expect(Buffer.byteLength(chunk as string, "utf8")).toBeLessThanOrEqual(900);
+    }
+  });
+
+  it("sends a short command response as a single message", async () => {
+    const ctx = makeGateCtx({ adminGroups: [] });
+    ctx.executeCommand = vi.fn(async () => "short reply");
+
+    await handleTextMessage.call(ctx, makeMsg("!lyrics"));
+
+    expect(ctx.tsClient.sendTextMessage).toHaveBeenCalledTimes(1);
+    expect(ctx.tsClient.sendTextMessage).toHaveBeenCalledWith("short reply");
+  });
+});
+
+const cmdLyrics = (BotInstance.prototype as any).cmdLyrics as (
+  this: unknown,
+) => Promise<string>;
+
+describe("BotInstance.cmdLyrics — full lyrics (#116)", () => {
+  it("returns ALL lyric lines, not just the first 10", async () => {
+    const lyricLines = Array.from({ length: 30 }, (_, i) => ({
+      time: i,
+      text: `lyric line ${i}`,
+    }));
+    const ctx: any = {
+      queue: { current: () => ({ id: "s1", name: "Song", platform: "netease" }) },
+      getProviderFor: () => ({ getLyrics: vi.fn(async () => lyricLines) }),
+    };
+
+    const out = await cmdLyrics.call(ctx);
+
+    for (const l of lyricLines) {
+      expect(out).toContain(l.text);
+    }
+    expect(out.startsWith("Lyrics for Song:")).toBe(true);
+  });
+
+  it("returns 'No lyrics available' when the provider has none", async () => {
+    const ctx: any = {
+      queue: { current: () => ({ id: "s1", name: "Song", platform: "netease" }) },
+      getProviderFor: () => ({ getLyrics: vi.fn(async () => []) }),
+    };
+    expect(await cmdLyrics.call(ctx)).toBe("No lyrics available");
+  });
+});
@@ -9,10 +9,11 @@ import { PlayQueue, PlayMode, type QueuedSong } from "../audio/queue.js";
 import type { MusicProvider, Song } from "../music/provider.js";
 import {
  parseCommand,
-  isAdminCommand,
+  canRunCommand,
  type ParsedCommand,
 } from "./commands.js";
 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 type { BotConfig } from "../data/config.js";
@@ -24,6 +25,9 @@ import {
  shouldResumeOnReturn,
 } from "./auto-pause.js";

+/** Reply sent when a non-admin invokes an admin-only chat command. */
+export const COMMAND_DENIED_MESSAGE = "⛔ 需要管理员权限（该命令仅限管理员服务器组）";
+
 export interface BotInstanceOptions {
  id: string;
  name: string;
@@ -32,6 +36,8 @@ export interface BotInstanceOptions {
  qqProvider: MusicProvider;
  bilibiliProvider: MusicProvider;
  youtubeProvider: MusicProvider;
+  localProvider?: MusicProvider;
+  kugouProvider?: MusicProvider;
  database: BotDatabase;
  config: BotConfig;
  logger: Logger;
@@ -49,6 +55,8 @@ export interface BotStatus {
  volume: number;
  playMode: PlayMode;
  elapsed: number; // ground truth elapsed seconds from frame count
+  /** 当前曲实际播放时长（秒）。试听片段=试听秒数；完整曲=duration。缺失时前端回退 currentSong.duration。 */
+  effectiveDuration?: number;
 }

 export class BotInstance extends EventEmitter {
@@ -62,6 +70,8 @@ export class BotInstance extends EventEmitter {
  private qqProvider: MusicProvider;
  private bilibiliProvider: MusicProvider;
  private youtubeProvider: MusicProvider;
+  private localProvider: MusicProvider;
+  private kugouProvider: MusicProvider;
  private database: BotDatabase;
  private config: BotConfig;
  private logger: Logger;
@@ -78,6 +88,8 @@ export class BotInstance extends EventEmitter {
  private fmProvider: MusicProvider | null = null;
  /** Results of the most recent !search, for "#N" selection (issue #90). */
  private lastSearchResults: Song[] = [];
+  /** 当前曲实际播放时长（试听片段秒数或完整 duration）；resolveAndPlay 赋值。 */
+  private effectiveDuration: number | undefined;
  private playGate: Promise<unknown> = Promise.resolve();

  constructor(options: BotInstanceOptions) {
@@ -88,6 +100,8 @@ export class BotInstance extends EventEmitter {
    this.qqProvider = options.qqProvider;
    this.bilibiliProvider = options.bilibiliProvider;
    this.youtubeProvider = options.youtubeProvider;
+    this.localProvider = options.localProvider ?? options.neteaseProvider;
+    this.kugouProvider = options.kugouProvider ?? options.neteaseProvider;
    this.database = options.database;
    this.config = options.config;
    this.logger = options.logger.child({ botId: this.id });
@@ -140,6 +154,41 @@ export class BotInstance extends EventEmitter {
    });
  }

+  isLocalAudioEnabled(): boolean {
+    return this.config.localAudioEnabled !== false;
+  }
+
+  /**
+   * Reference-aware cleanup of uploaded local audio files. Delegates to the
+   * local provider, which deletes a file only when it has been played AND is
+   * no longer referenced by ANY bot's queue — so loop replays, prev, the song
+   * being re-started, and the same upload queued on another bot are all safe.
+   * Call this AFTER the queue mutation, so released songs are unreferenced
+   * (and deleted) while songs that remain queued are preserved.
+   */
+  cleanupQueuedLocalSongs(reason: string): void {
+    this.sweepLocalAudio(reason);
+  }
+
+  private sweepLocalAudio(reason: string): void {
+    const provider = this.localProvider as MusicProvider & {
+      sweepUnreferenced?: () => string[];
+    };
+    if (typeof provider.sweepUnreferenced !== "function") return;
+    try {
+      const deleted = provider.sweepUnreferenced();
+      if (deleted.length) {
+        this.logger.info({ count: deleted.length, reason }, "Cleaned up local audio files");
+      }
+    } catch (err) {
+      this.logger.warn({ err, reason }, "Local audio cleanup failed");
+    }
+  }
+
+  private isSameSong(a: QueuedSong | Song | null | undefined, b: QueuedSong | Song | null | undefined): boolean {
+    return !!a && !!b && a.platform === b.platform && a.id === b.id;
+  }
+
  private setupTsEvents(): void {
    this.tsClient.on("textMessage", (msg: TS3TextMessage) => {
      this.handleTextMessage(msg).catch((err) => {
@@ -154,6 +203,8 @@ export class BotInstance extends EventEmitter {
      // short-circuited on !this.connected, leaving player stuck as "playing".
      this.connected = false;
      this.player.stop();
+      this.queue.clear();
+      this.sweepLocalAudio("disconnected");
      // A lifecycle change must not leave a stale auto-resume armed.
      this.autoPaused = false;
      // Only emit externally once per lifecycle so clients don't see a
@@ -235,6 +286,8 @@ export class BotInstance extends EventEmitter {
  disconnect(): void {
    this._cancelIdleTimer();
    this.player.stop();
+    this.queue.clear();
+    this.sweepLocalAudio("disconnected");
    this.connected = false;
    if (!this.disconnectEmitted) {
      this.disconnectEmitted = true;
@@ -322,8 +375,17 @@ export class BotInstance extends EventEmitter {
    );
    if (!parsed) return;

-    if (isAdminCommand(parsed.name)) {
-      // TODO: Check if invoker is in adminGroups
+    if (!(await this.isCommandAllowed(parsed.name, msg))) {
+      this.logger.info(
+        { command: parsed.name, invoker: msg.invokerName },
+        "Command denied: invoker not in adminGroups"
+      );
+      try {
+        await this.tsClient.sendTextMessage(COMMAND_DENIED_MESSAGE);
+      } catch (sendErr) {
+        this.logger.error({ err: sendErr }, "Failed to send permission-denied message to chat");
+      }
+      return;
    }

    this.logger.info(
@@ -334,7 +396,11 @@ export class BotInstance extends EventEmitter {
    try {
      const response = await this.executeCommand(parsed, msg);
      if (response) {
-        await this.tsClient.sendTextMessage(response);
+        // A single long reply (e.g. full lyrics) would exceed TeamSpeak's
+        // per-message byte cap, so split it and send the chunks in order.
+        for (const chunk of splitTextIntoChunks(response)) {
+          await this.tsClient.sendTextMessage(chunk);
+        }
      }
    } catch (err) {
      this.logger.error({ err, command: parsed.name }, "Command execution error");
@@ -348,6 +414,41 @@ export class BotInstance extends EventEmitter {
    }
  }

+  /**
+   * Decide whether a chat command may run for this sender. Reads adminGroups
+   * live from this.config. Public commands and the enforcement-off case are
+   * allowed with NO query. For an ENFORCED admin command we resolve the
+   * sender's CURRENT server groups with a targeted server-wide lookup rather
+   * than trusting the text event's cached groups — those are empty for
+   * out-of-channel senders and stale after a live promotion/demotion. Fails
+   * closed when the groups can't be determined.
+   */
+  private async isCommandAllowed(commandName: string, msg: TS3TextMessage): Promise<boolean> {
+    const adminGroups = this.config.adminGroups;
+    // Public command, or enforcement off → allow without any lookup.
+    // (canRunCommand with empty groups is true iff the command is public OR
+    // adminGroups is empty.)
+    if (canRunCommand(commandName, [], adminGroups)) return true;
+    // Enforced admin command: authoritative decision uses freshly-resolved,
+    // server-wide groups. Fail closed if they can't be determined.
+    const groups = await this.lookupInvokerGroups(msg.invokerId);
+    return canRunCommand(commandName, groups, adminGroups);
+  }
+
+  /**
+   * Resolve the sender's current server groups by client id, server-wide.
+   * Returns [] on a bad id or query failure (→ fail-closed deny upstream).
+   */
+  private async lookupInvokerGroups(invokerId: string): Promise<string[]> {
+    const clid = Number(invokerId);
+    if (!Number.isFinite(clid) || clid <= 0) return [];
+    try {
+      return await this.tsClient.getClientServerGroups(clid);
+    } catch {
+      return [];
+    }
+  }
+
  async executeCommand(
    cmd: ParsedCommand,
    msg?: TS3TextMessage
@@ -431,9 +532,11 @@ export class BotInstance extends EventEmitter {
    }
  }

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

@@ -446,6 +549,7 @@ export class BotInstance extends EventEmitter {
    if (flags.has("b")) return this.bilibiliProvider;
    if (flags.has("q")) return this.qqProvider;
    if (flags.has("y")) return this.youtubeProvider;
+    if (flags.has("k")) return this.kugouProvider;
    return this.neteaseProvider;
  }

@@ -455,14 +559,18 @@ export class BotInstance extends EventEmitter {
      this.logger.warn({ songId: song.id, name: song.name }, "resolveAndPlay called on disconnected bot — skipping");
      return false;
    }
+    if (song.platform === "local" && !this.isLocalAudioEnabled()) {
+      this.logger.warn({ songId: song.id, name: song.name }, "Local audio playback disabled — refusing track");
+      return false;
+    }
    // Clear any accumulated skip votes — every fresh track starts with a
    // clean slate, regardless of which code path loaded it (cmdPlay,
    // cmdPlaylist, cmdAlbum, cmdFm, trackEnd auto-advance, etc.).
    this.voteSkipUsers.clear();
    const provider = this.getProviderFor(song.platform);
    try {
-      const url = await provider.getSongUrl(song.id);
-      if (!url) {
+      const result = await provider.getSongUrl(song.id);
+      if (!result?.url) {
        this.logger.warn({ songId: song.id, name: song.name }, "No URL available, skipping");
        return false;
      }
@@ -478,8 +586,10 @@ export class BotInstance extends EventEmitter {
        );
        return false;
      }
-      song.url = url;
-      this.player.play(url, 0, song.duration);
+      song.url = result.url;
+      // 试听片段用试听时长（让 player nearEnd 正确触发自动切歌）；完整曲回退 song.duration
+      this.effectiveDuration = result.trialDuration ?? song.duration;
+      this.player.play(result.url, 0, this.effectiveDuration);
      // Fresh playback (re)start — clear auto-pause so a later occupancy
      // change won't try to "resume" a track the user already restarted.
      this.autoPaused = false;
@@ -549,7 +659,7 @@ export class BotInstance extends EventEmitter {

  private async cmdSearch(cmd: ParsedCommand): Promise<string> {
    const p = this.config.commandPrefix;
-    if (!cmd.args) return `Usage: ${p}search <name> [-q|-b|-y]`;
+    if (!cmd.args) return `Usage: ${p}search <name> [-q|-k|-b|-y]`;
    const provider = this.getProvider(cmd.flags);
    const result = await provider.search(cmd.args, 8);
    if (result.songs.length === 0) return `No results found for: ${cmd.args}`;
@@ -568,6 +678,10 @@ export class BotInstance extends EventEmitter {
    const { song, error } = await this.resolvePlayQuery(cmd);
    if (error) return error;
    const song0 = song!;
+    const previous = this.queue.current();
+    if (previous && !this.isSameSong(previous, song0)) {
+      this.player.stop();
+    }
    this.queue.clear();
    this.disableFmMode();
    this.queue.add({ ...song0 });
@@ -576,6 +690,10 @@ export class BotInstance extends EventEmitter {
    // 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
+    // upload that was already playing — stays referenced and is preserved.
+    this.sweepLocalAudio("replaced");
    if (!ok) return `Cannot play: ${song0.name}`;
    return `Now playing: ${song0.name} - ${song0.artist}`;
  }
@@ -655,6 +773,7 @@ export class BotInstance extends EventEmitter {
    this.player.stop();
    this.autoPaused = false;
    this.queue.clear();
+    this.sweepLocalAudio("stopped");
    this.disableFmMode();
    this.profileManager.onSongChange(null).catch((err) => {
      this.logger.warn({ err }, "Profile restore failed on stop");
@@ -713,6 +832,7 @@ export class BotInstance extends EventEmitter {
  private cmdClear(): string {
    this.player.stop();
    this.queue.clear();
+    this.sweepLocalAudio("queue_cleared");
    this.disableFmMode();
    this.profileManager.onSongChange(null).catch((err) => {
      this.logger.warn({ err }, "Profile restore failed on clear");
@@ -726,6 +846,9 @@ export class BotInstance extends EventEmitter {
    if (isNaN(index) || index < 0) return "Usage: !remove <number>";
    const removed = this.queue.remove(index);
    if (!removed) return "Invalid position";
+    // Sweep after the entry is gone — the file is deleted only if no other
+    // queue position (or bot) still references this upload.
+    this.sweepLocalAudio("removed_from_queue");
    this.emit("stateChange");
    return `Removed: ${removed.name}`;
  }
@@ -785,6 +908,7 @@ export class BotInstance extends EventEmitter {
    const songs = await provider.getPlaylistSongs(playlistId);
    if (songs.length === 0) return "Playlist is empty or not found";

+    this.player.stop();
    this.queue.clear();
    this.disableFmMode();
    for (const song of songs) {
@@ -792,6 +916,7 @@ export class BotInstance extends EventEmitter {
    }
    const first = this.queue.play();
    if (first) await this.resolveAndPlay(first);
+    this.sweepLocalAudio("queue_replaced");
    this.emit("stateChange");
    return `Loaded ${songs.length} songs. Now playing: ${first?.name ?? "unknown"}`;
  }
@@ -820,6 +945,7 @@ export class BotInstance extends EventEmitter {
    const songs = await provider.getAlbumSongs(albumId);
    if (songs.length === 0) return "Album is empty or not found";

+    this.player.stop();
    this.queue.clear();
    this.disableFmMode();
    for (const song of songs) {
@@ -827,6 +953,7 @@ export class BotInstance extends EventEmitter {
    }
    const first = this.queue.play();
    if (first) await this.resolveAndPlay(first);
+    this.sweepLocalAudio("queue_replaced");
    this.emit("stateChange");
    return `Loaded ${songs.length} songs. Now playing: ${first?.name ?? "unknown"}`;
  }
@@ -849,6 +976,7 @@ export class BotInstance extends EventEmitter {
    if (songs.length === 0)
      return "No FM songs available (need to login first)";

+    this.player.stop();
    this.queue.clear();
    for (const song of songs) {
      this.queue.add({ ...song, platform: provider.platform });
@@ -860,6 +988,7 @@ export class BotInstance extends EventEmitter {

    const first = this.queue.play();
    if (first) await this.resolveAndPlay(first);
+    this.sweepLocalAudio("queue_replaced");
    this.emit("stateChange");
    const label = provider.platform === "qq" ? "QQ Radar FM" : "Personal FM";
    return `${label} started: ${first?.name ?? "unknown"} - ${first?.artist ?? ""}`;
@@ -882,6 +1011,7 @@ export class BotInstance extends EventEmitter {
      filtered = result.songs.slice(0, 20);
    }

+    this.player.stop();
    this.queue.clear();
    this.disableFmMode();
    for (const song of filtered) {
@@ -892,6 +1022,7 @@ export class BotInstance extends EventEmitter {

    const first = this.queue.play();
    if (first) await this.resolveAndPlay(first);
+    this.sweepLocalAudio("queue_replaced");
    this.emit("stateChange");
    return `Artist mode: ${cmd.args} — ${filtered.length} songs loaded. Now playing: ${first?.name ?? "unknown"}`;
  }
@@ -938,7 +1069,10 @@ export class BotInstance extends EventEmitter {
    const provider = this.getProviderFor(song.platform);
    const lyrics = await provider.getLyrics(song.id);
    if (lyrics.length === 0) return "No lyrics available";
-    const lines = lyrics.slice(0, 10).map((l) => l.text);
+    // Include the FULL lyrics (the send path chunks them under the message
+    // cap). Cap only to avoid pathological spam — far above any normal song.
+    const MAX_LYRIC_LINES = 200;
+    const lines = lyrics.slice(0, MAX_LYRIC_LINES).map((l) => l.text);
    return `Lyrics for ${song.name}:\n${lines.join("\n")}`;
  }

@@ -997,10 +1131,10 @@ export class BotInstance extends EventEmitter {
  async playNext(maxRetries = 3): Promise<boolean> {
    if (this.isAdvancing || !this.connected) return false;
    this.isAdvancing = true;
+    let started = false;
    try {
      this.voteSkipUsers.clear();
      const next = this.queue.next();
-      let started = false;
      if (next) {
        started = await this.resolveAndPlay(next);
        if (!started) {
@@ -1040,6 +1174,10 @@ export class BotInstance extends EventEmitter {
      this.emit("stateChange");
      return started;
    } finally {
+      // Reference-aware sweep: a finished local song that still sits in the
+      // queue (sequential history, loop/repeat, or queued on another bot) is
+      // preserved; only uploads no longer referenced anywhere are deleted.
+      this.sweepLocalAudio("playback_finished");
      this.isAdvancing = false;
    }
  }
@@ -1072,6 +1210,7 @@ export class BotInstance extends EventEmitter {
      volume: this.player.getVolume(),
      playMode: this.queue.getMode(),
      elapsed: this.player.getElapsed(),
+      effectiveDuration: this.effectiveDuration,
    };
  }

@@ -74,6 +74,8 @@ export class BotManager extends EventEmitter {
  private qqProvider: MusicProvider;
  private bilibiliProvider: MusicProvider;
  private youtubeProvider: MusicProvider;
+  private localProvider: MusicProvider;
+  private kugouProvider: MusicProvider;
  private database: BotDatabase;
  private config: BotConfig;
  private logger: Logger;
@@ -90,13 +92,23 @@ export class BotManager extends EventEmitter {
    logger: Logger,
    avatarStore: AvatarStore,
    permissions: PermissionStore,
-    configPath: string
+    configPath: string,
+    localProvider?: MusicProvider,
+    kugouProvider?: MusicProvider
  ) {
    super();
    this.neteaseProvider = neteaseProvider;
    this.qqProvider = qqProvider;
    this.bilibiliProvider = bilibiliProvider;
    this.youtubeProvider = new YouTubeProvider();
+    this.localProvider = localProvider ?? neteaseProvider;
+    this.kugouProvider = kugouProvider ?? neteaseProvider;
+    // Let the local provider see which uploads are still referenced by any
+    // bot's queue, so it never deletes a file another queue/bot still needs.
+    const referenceable = this.localProvider as Partial<{
+      setInUseResolver: (resolver: () => Set<string>) => void;
+    }>;
+    referenceable.setInUseResolver?.(() => this.getReferencedLocalSongIds());
    this.database = database;
    this.config = config;
    this.logger = logger;
@@ -127,6 +139,8 @@ export class BotManager extends EventEmitter {
      qqProvider: this.qqProvider,
      bilibiliProvider: this.bilibiliProvider,
      youtubeProvider: this.youtubeProvider,
+      localProvider: this.localProvider,
+      kugouProvider: this.kugouProvider,
      database: this.database,
      config: this.config,
      logger: this.logger,
@@ -210,6 +224,18 @@ export class BotManager extends EventEmitter {
    return Array.from(this.bots.values());
  }

+  /** Local upload ids still referenced by any bot's queue. The local provider
+   *  uses this to avoid deleting a file another queue/bot is still using. */
+  getReferencedLocalSongIds(): Set<string> {
+    const ids = new Set<string>();
+    for (const bot of this.bots.values()) {
+      for (const song of bot.getQueueManager().list()) {
+        if (song.platform === "local") ids.add(song.id);
+      }
+    }
+    return ids;
+  }
+
  async startBot(id: string): Promise<void> {
    const oldBot = this.bots.get(id);
    if (!oldBot) throw new Error(`Bot ${id} not found`);
@@ -253,6 +279,8 @@ export class BotManager extends EventEmitter {
        qqProvider: this.qqProvider,
        bilibiliProvider: this.bilibiliProvider,
        youtubeProvider: this.youtubeProvider,
+        localProvider: this.localProvider,
+        kugouProvider: this.kugouProvider,
        database: this.database,
        config: this.config,
        logger: this.logger,
@@ -305,6 +333,8 @@ export class BotManager extends EventEmitter {
        qqProvider: this.qqProvider,
        bilibiliProvider: this.bilibiliProvider,
        youtubeProvider: this.youtubeProvider,
+        localProvider: this.localProvider,
+        kugouProvider: this.kugouProvider,
        database: this.database,
        config: this.config,
        logger: this.logger,
@@ -0,0 +1,67 @@
+import { describe, it, expect } from "vitest";
+import { splitTextIntoChunks } from "./text-chunk.js";
+
+const bytes = (s: string) => Buffer.byteLength(s, "utf8");
+
+describe("splitTextIntoChunks", () => {
+  it("returns a single chunk for a short string", () => {
+    const chunks = splitTextIntoChunks("hello world", 900);
+    expect(chunks).toEqual(["hello world"]);
+  });
+
+  it("splits a multi-line string longer than maxBytes into multiple chunks on line boundaries", () => {
+    const lines = Array.from({ length: 50 }, (_, i) => `line number ${i}`);
+    const text = lines.join("\n");
+    const chunks = splitTextIntoChunks(text, 60);
+
+    expect(chunks.length).toBeGreaterThan(1);
+    for (const c of chunks) {
+      expect(bytes(c)).toBeLessThanOrEqual(60);
+    }
+    // No hard-split of any line occurred, so rejoining with "\n" is lossless.
+    expect(chunks.join("\n")).toBe(text);
+  });
+
+  it("bounds by BYTES not chars: multibyte (Chinese) content stays under the cap", () => {
+    // Each Chinese char is 3 bytes in UTF-8. 40 chars/line = 120 bytes/line.
+    const lines = Array.from({ length: 10 }, () => "歌词".repeat(20));
+    const text = lines.join("\n");
+    const chunks = splitTextIntoChunks(text, 150);
+
+    expect(chunks.length).toBeGreaterThan(1);
+    for (const c of chunks) {
+      expect(bytes(c)).toBeLessThanOrEqual(150);
+    }
+    expect(chunks.join("\n")).toBe(text);
+  });
+
+  it("hard-splits a single over-long line so no chunk exceeds the cap", () => {
+    const longLine = "a".repeat(500);
+    const chunks = splitTextIntoChunks(longLine, 100);
+
+    expect(chunks.length).toBeGreaterThan(1);
+    for (const c of chunks) {
+      expect(bytes(c)).toBeLessThanOrEqual(100);
+    }
+    // Content is preserved (hard-split introduces split points, not \n).
+    expect(chunks.join("")).toBe(longLine);
+  });
+
+  it("never splits a multibyte character across a hard-split boundary", () => {
+    // 200 Chinese chars = 600 bytes on ONE line, cap 40 bytes.
+    const longLine = "歌".repeat(200);
+    const chunks = splitTextIntoChunks(longLine, 40);
+
+    for (const c of chunks) {
+      expect(bytes(c)).toBeLessThanOrEqual(40);
+      // A clean re-decode: every chunk is valid UTF-8 with no replacement char.
+      expect(c.includes("�")).toBe(false);
+    }
+    expect(chunks.join("")).toBe(longLine);
+  });
+
+  it("preserves blank lines within a single chunk", () => {
+    const text = "a\n\nb";
+    expect(splitTextIntoChunks(text, 900)).toEqual([text]);
+  });
+});
@@ -0,0 +1,74 @@
+/**
+ * Split `text` into chunks whose UTF-8 byte length never exceeds `maxBytes`.
+ *
+ * TeamSpeak enforces a per-message byte cap (~1024 bytes), and the send path
+ * does no chunking, so a long single reply (e.g. full song lyrics) would be
+ * truncated or rejected. This packs whole lines greedily, breaking BETWEEN
+ * lines. When a single line is itself longer than `maxBytes`, it is hard-split
+ * on UTF-8 character boundaries so no chunk ever exceeds the cap and no
+ * multibyte character is ever cut in half.
+ *
+ * Content is preserved on rejoin, modulo the split points: chunks split only on
+ * newline boundaries rejoin losslessly with `chunks.join("\n")`; a hard-split
+ * long line rejoins with `chunks.join("")`.
+ *
+ * @param text     The full message text.
+ * @param maxBytes Max UTF-8 bytes per chunk (default 900 — under TS's ~1024 cap
+ *                 with headroom for protocol framing/escaping).
+ */
+export function splitTextIntoChunks(text: string, maxBytes = 900): string[] {
+  const chunks: string[] = [];
+  let current = "";
+
+  const flush = (): void => {
+    if (current !== "") {
+      chunks.push(current);
+      current = "";
+    }
+  };
+
+  for (const rawLine of text.split("\n")) {
+    const pieces =
+      Buffer.byteLength(rawLine, "utf8") > maxBytes
+        ? hardSplitByBytes(rawLine, maxBytes)
+        : [rawLine];
+
+    for (const piece of pieces) {
+      const candidate = current === "" ? piece : `${current}\n${piece}`;
+      if (Buffer.byteLength(candidate, "utf8") <= maxBytes) {
+        current = candidate;
+      } else {
+        // current is guaranteed non-empty here: pieces never exceed maxBytes,
+        // so an empty `current` always accepts the next piece above.
+        flush();
+        current = piece;
+      }
+    }
+  }
+
+  flush();
+  return chunks;
+}
+
+/**
+ * Break a single line into pieces each ≤ `maxBytes` UTF-8 bytes, never cutting
+ * a character (iterates code points, so surrogate pairs stay intact).
+ */
+function hardSplitByBytes(line: string, maxBytes: number): string[] {
+  const pieces: string[] = [];
+  let current = "";
+  let currentBytes = 0;
+
+  for (const ch of line) {
+    const chBytes = Buffer.byteLength(ch, "utf8");
+    if (currentBytes + chBytes > maxBytes && current !== "") {
+      pieces.push(current);
+      current = "";
+      currentBytes = 0;
+    }
+    current += ch;
+    currentBytes += chBytes;
+  }
+  if (current !== "") pieces.push(current);
+  return pieces;
+}
@@ -115,6 +115,7 @@ describe("guestMode config", () => {
    expect(c.guestMode.permissions).toEqual({
      addToQueue: true, playNext: false, playNow: false,
      skip: false, transport: false, removeClear: false, playMode: false,
+      playCollection: false,
    });
  });

@@ -167,13 +168,40 @@ describe("guestMode config", () => {
    });
    it("a string permissions value yields defaults with no numeric index keys", () => {
      const gm = loadGuestMode({ guestMode: { permissions: "hacked" } });
-      // 7 known flags present at their defaults
+      // all known flags present at their defaults
      expect(gm.permissions).toEqual({
        addToQueue: true, playNext: false, playNow: false,
        skip: false, transport: false, removeClear: false, playMode: false,
+        playCollection: false,
      });
      // no garbage index keys leaked from spreading a string
      expect((gm.permissions as unknown as Record<string, unknown>)["0"]).toBeUndefined();
    });
  });
 });
+
+describe("adminGroups normalization", () => {
+  function loadAdminGroups(raw: unknown) {
+    const dir = mkdtempSync(join(tmpdir(), "tsmb-cfg-"));
+    const p = join(dir, "config.json");
+    writeFileSync(p, JSON.stringify(raw));
+    try {
+      return loadConfig(p).adminGroups;
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  }
+
+  it("defaults to [] when absent", () => {
+    expect(loadAdminGroups({})).toEqual([]);
+  });
+  it("keeps valid non-negative integers", () => {
+    expect(loadAdminGroups({ adminGroups: [6, 8] })).toEqual([6, 8]);
+  });
+  it("filters out negatives, non-integers and non-numbers", () => {
+    expect(loadAdminGroups({ adminGroups: [6, -1, 2.5, "8", null] })).toEqual([6]);
+  });
+  it("a non-array value falls back to the default [] (no crash)", () => {
+    expect(loadAdminGroups({ adminGroups: "6" })).toEqual([]);
+  });
+});
@@ -22,6 +22,8 @@ export interface BotConfig {
  autoReturnDelay: number;
  autoPauseOnEmpty: boolean;
  idleTimeoutMinutes: number;
+  /** Enable uploading and playback of server-stored local audio files. */
+  localAudioEnabled: 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"
@@ -50,6 +52,7 @@ export function getDefaultConfig(): BotConfig {
    // clients are present). Users can opt in from the web UI.
    autoPauseOnEmpty: false,
    idleTimeoutMinutes: 0,
+    localAudioEnabled: true,
    publicUrl: "",
    trustProxy: false,
    guestMode: {
@@ -63,6 +66,7 @@ export function getDefaultConfig(): BotConfig {
        transport: false,
        removeClear: false,
        playMode: false,
+        playCollection: false,
      },
    },
  };
@@ -104,9 +108,20 @@ export function loadConfig(path: string): BotConfig {
      gm.permissions[f] = gm.permissions[f] === true;
    }

+    // Sanitize adminGroups on load too: the WebUI write path filters it, but a
+    // hand-edited / legacy / corrupt config.json reaches the command gate
+    // directly. Keep only non-negative integers; a non-array falls back to the
+    // default []. Mirrors the guestMode sanitization above.
+    const adminGroups = Array.isArray(partial.adminGroups)
+      ? partial.adminGroups.filter(
+          (g): g is number => typeof g === "number" && Number.isInteger(g) && g >= 0,
+        )
+      : defaults.adminGroups;
+
    return {
      ...defaults,
      ...partial,
+      adminGroups,
      guestMode: gm,
    };
  } catch {
@@ -8,7 +8,7 @@ export interface PlayHistoryEntry {
  songName: string;
  artist: string;
  album: string;
-  platform: "netease" | "qq" | "bilibili" | "youtube";
+  platform: "netease" | "qq" | "bilibili" | "youtube" | "local" | "kugou";
  coverUrl: string;
 }

@@ -105,6 +105,7 @@ describe("resolvePermissionContext guest branch", () => {
      permissions: {
        addToQueue: true, playNext: false, playNow: false,
        skip: true, transport: false, removeClear: false, playMode: false,
+        playCollection: false,
      },
    });
    expect([...ctx.capabilities]).toEqual([]);
@@ -120,14 +121,15 @@ describe("resolvePermissionContext guest branch", () => {
      permissions: {
        addToQueue: true, playNext: false, playNow: false,
        skip: false, transport: false, removeClear: false, playMode: false,
+        playCollection: false,
      },
    });
    expect(ctx.bots).toBe("all");
  });

-  it("exposes the 7 canonical flags", () => {
+  it("exposes the 8 canonical flags", () => {
    expect([...GUEST_PERMISSION_FLAGS].sort()).toEqual(
-      ["addToQueue", "playMode", "playNext", "playNow", "removeClear", "skip", "transport"].sort()
+      ["addToQueue", "playCollection", "playMode", "playNext", "playNow", "removeClear", "skip", "transport"].sort()
    );
  });
 });
@@ -29,6 +29,8 @@ export interface GuestPermissions {
  transport: boolean;
  removeClear: boolean;
  playMode: boolean;
+  /** Load + play an entire playlist/album (clears the queue). Issue #103. */
+  playCollection: boolean;
 }

 export const GUEST_PERMISSION_FLAGS = [
@@ -39,6 +41,7 @@ export const GUEST_PERMISSION_FLAGS = [
  "transport",
  "removeClear",
  "playMode",
+  "playCollection",
 ] as const;
 export type GuestFlag = (typeof GUEST_PERMISSION_FLAGS)[number];

@@ -7,6 +7,8 @@ import { createApiServerManager } from "./music/api-server.js";
 import { NeteaseProvider } from "./music/netease.js";
 import { QQMusicProvider } from "./music/qq.js";
 import { BiliBiliProvider } from "./music/bilibili.js";
+import { LocalMusicProvider } from "./music/local.js";
+import { KugouProvider } from "./music/kugou.js";
 import { createCookieStore } from "./music/auth.js";
 import { createAvatarStore } from "./data/avatars.js";
 import { createPermissionStore } from "./data/permissions.js";
@@ -25,6 +27,7 @@ const DB_PATH = path.join(DATA_DIR, "tsmusicbot.db");
 const LOG_DIR = path.join(DATA_DIR, "logs");
 const COOKIE_DIR = path.join(DATA_DIR, "cookies");
 const AVATAR_DIR = path.join(DATA_DIR, "avatars");
+const LOCAL_AUDIO_DIR = path.join(DATA_DIR, "local-audio");
 const STATIC_DIR = path.join(ROOT_DIR, "web", "dist");

 async function main() {
@@ -54,6 +57,8 @@ async function main() {
  const neteaseProvider = new NeteaseProvider(apiServer.getNeteaseBaseUrl());
  const qqProvider = new QQMusicProvider(apiServer.getQQMusicBaseUrl());
  const bilibiliProvider = new BiliBiliProvider();
+  const localProvider = new LocalMusicProvider(LOCAL_AUDIO_DIR);
+  const kugouProvider = new KugouProvider();

  const cookieStore = createCookieStore(COOKIE_DIR);
  const avatarStore = createAvatarStore(AVATAR_DIR);
@@ -63,6 +68,8 @@ async function main() {
  if (qqCookie) qqProvider.setCookie(qqCookie);
  const bilibiliCookie = cookieStore.load("bilibili");
  if (bilibiliCookie) bilibiliProvider.setCookie(bilibiliCookie);
+  const kugouCookie = cookieStore.load("kugou");
+  if (kugouCookie) kugouProvider.setCookie(kugouCookie);

  const permissions = createPermissionStore(db.db);

@@ -75,7 +82,9 @@ async function main() {
    logger,
    avatarStore,
    permissions,
-    CONFIG_PATH
+    CONFIG_PATH,
+    localProvider,
+    kugouProvider
  );
  await botManager.loadSavedBots();

@@ -85,6 +94,8 @@ async function main() {
    neteaseProvider,
    qqProvider,
    bilibiliProvider,
+    localProvider,
+    kugouProvider,
    database: db,
    avatarStore,
    config,
@@ -0,0 +1,30 @@
+import { describe, it, expect } from "vitest";
+import { describeQqApiStartupError } from "./api-server.js";
+
+describe("describeQqApiStartupError", () => {
+  it("flags ERR_REQUIRE_ESM by error code with version-pin guidance", () => {
+    const hint = describeQqApiStartupError({ code: "ERR_REQUIRE_ESM", message: "..." });
+    expect(hint).toMatch(/ERR_REQUIRE_ESM/);
+    expect(hint).toMatch(/~2\.4\.0/);
+    expect(hint).toMatch(/~2\.2\.10/);
+  });
+
+  it("flags ERR_REQUIRE_ESM by message when the code is absent", () => {
+    const hint = describeQqApiStartupError(
+      new Error("require() of ES Module .../@sansenjian/qq-music-api/dist/index.js not supported")
+    );
+    expect(hint).toMatch(/incompatible @sansenjian\/qq-music-api/);
+  });
+
+  it("flags a Node engine mismatch with a Node-upgrade hint", () => {
+    const hint = describeQqApiStartupError(new Error("Unsupported engine: requires Node >=20.17"));
+    expect(hint).toMatch(/Node >=20\.17/);
+    expect(hint).toMatch(/~2\.2\.10/);
+  });
+
+  it("returns null for an unrelated startup error (falls back to the generic warning)", () => {
+    expect(describeQqApiStartupError(new Error("EADDRINUSE: port in use"))).toBeNull();
+    expect(describeQqApiStartupError(undefined)).toBeNull();
+    expect(describeQqApiStartupError(null)).toBeNull();
+  });
+});
@@ -14,6 +14,32 @@ export interface ApiServerManager {
  getQQMusicBaseUrl(): string;
 }

+/**
+ * Classify a QQ Music API (@sansenjian/qq-music-api) startup failure into
+ * actionable operator guidance, or null when it isn't a recognised
+ * dependency/runtime mismatch. Exported for testing.
+ *
+ * Background: the package became ESM in 2.3.x. A loose `^` range could pull an
+ * ESM-only build (2.3.0/2.3.1) that throws ERR_REQUIRE_ESM, or a 2.4.x build
+ * that needs Node >=20.17 — either way the embedded server never binds, so
+ * every QQ request fails downstream with ECONNREFUSED on the API port.
+ */
+export function describeQqApiStartupError(err: unknown): string | null {
+  const e = (err ?? {}) as { code?: string; message?: string };
+  const code = String(e.code ?? "");
+  const msg = String(e.message ?? "");
+  if (code === "ERR_REQUIRE_ESM" || /ERR_REQUIRE_ESM|require\(\) of ES ?Module/i.test(msg)) {
+    return (
+      "an incompatible @sansenjian/qq-music-api build is installed (ERR_REQUIRE_ESM). " +
+      "Pin it to ~2.4.0 (needs Node >=20.17) or ~2.2.10 in package.json, then reinstall"
+    );
+  }
+  if (/Unsupported engine|EBADENGINE|requires Node|Node\.js version/i.test(msg)) {
+    return "@sansenjian/qq-music-api 2.4.x requires Node >=20.17 (or >=22.9) — upgrade Node, or pin the package to ~2.2.10";
+  }
+  return null;
+}
+
 function isPortFree(port: number): Promise<boolean> {
  return new Promise((resolve) => {
    const server = net.createServer();
@@ -100,10 +126,18 @@ export function createApiServerManager(
          }
        }
      } catch (err) {
-        logger.warn(
-          { err },
-          "QQ Music API not available — QQ Music features may be limited"
-        );
+        const hint = describeQqApiStartupError(err);
+        if (hint) {
+          logger.error(
+            { err },
+            `QQ Music API failed to start — ${hint}. QQ features (search/play/login) will be unavailable until fixed; port ${options.qqMusicPort} is down.`
+          );
+        } else {
+          logger.warn(
+            { err },
+            "QQ Music API not available — QQ Music features may be limited"
+          );
+        }
      }
    },

@@ -2,8 +2,8 @@ import fs from "node:fs";
 import path from "node:path";

 export interface CookieStore {
-  save(platform: "netease" | "qq" | "bilibili", cookie: string): void;
-  load(platform: "netease" | "qq" | "bilibili"): string;
+  save(platform: "netease" | "qq" | "bilibili" | "kugou", cookie: string): void;
+  load(platform: "netease" | "qq" | "bilibili" | "kugou"): string;
 }

 export function createCookieStore(cookieDir: string): CookieStore {
@@ -12,7 +12,7 @@ export function createCookieStore(cookieDir: string): CookieStore {
  }

  return {
-    save(platform: "netease" | "qq" | "bilibili", cookie: string): void {
+    save(platform: "netease" | "qq" | "bilibili" | "kugou", cookie: string): void {
      const filePath = path.join(cookieDir, `${platform}.json`);
      fs.writeFileSync(
        filePath,
@@ -21,7 +21,7 @@ export function createCookieStore(cookieDir: string): CookieStore {
      );
    },

-    load(platform: "netease" | "qq" | "bilibili"): string {
+    load(platform: "netease" | "qq" | "bilibili" | "kugou"): string {
      const filePath = path.join(cookieDir, `${platform}.json`);
      if (!fs.existsSync(filePath)) return "";
      try {
@@ -0,0 +1,39 @@
+import { describe, it, expect, vi } from "vitest";
+import { BiliBiliProvider } from "./bilibili.js";
+
+describe("BiliBiliProvider.search pagination", () => {
+  function mockProvider() {
+    const p = new BiliBiliProvider();
+    const get = vi.fn().mockResolvedValue({ data: { data: { result: [] } } });
+    // Short-circuit the buvid + wbi bootstrap so search only issues the
+    // /search/type request we want to inspect.
+    (p as any).buvidInitialized = true;
+    (p as any).wbiMixinKey = "0".repeat(32);
+    (p as any).wbiKeyFetchedAt = Date.now();
+    (p as any).api = { get };
+    return { p, get };
+  }
+
+  function searchParams(get: ReturnType<typeof vi.fn>) {
+    const call = get.mock.calls.find(
+      (c: any[]) => c[0] === "/x/web-interface/wbi/search/type"
+    );
+    expect(call, "expected a /search/type call").toBeTruthy();
+    // signWbi stringifies every value.
+    return call![1].params as Record<string, string>;
+  }
+
+  it("adds page (offset/limit+1) alongside page_size", async () => {
+    const { p, get } = mockProvider();
+    await p.search("hello", 20, 20); // page 2
+    const params = searchParams(get);
+    expect(params.page).toBe("2");
+    expect(params.page_size).toBe("20");
+  });
+
+  it("defaults offset to 0 → page 1 (backward compatible)", async () => {
+    const { p, get } = mockProvider();
+    await p.search("hello", 20);
+    expect(searchParams(get).page).toBe("1");
+  });
+});
@@ -3,6 +3,7 @@ import axios, { type AxiosInstance } from "axios";
 import type {
  MusicProvider,
  Song,
+  SongUrlResult,
  Playlist,
  LyricLine,
  SearchResult,
@@ -146,12 +147,16 @@ export class BiliBiliProvider implements MusicProvider {
    return fixed;
  }

-  async search(query: string, limit = 20): Promise<SearchResult> {
+  async search(query: string, limit = 20, offset = 0): Promise<SearchResult> {
    await this.ensureBuvidCookie();
    await this.ensureWbiKeys();
+    // /search/type is page-based; the web pages in limit-aligned steps so
+    // offset is a multiple of page_size.
+    const page = Math.floor(offset / limit) + 1;
    const signed = this.signWbi({
      search_type: "video",
      keyword: query,
+      page,
      page_size: limit,
    });
    const res = await this.api.get("/x/web-interface/wbi/search/type", {
@@ -231,7 +236,7 @@ export class BiliBiliProvider implements MusicProvider {
    return this.cidCache.get(bvid) ?? null;
  }

-  async getSongUrl(songId: string, _quality?: string): Promise<string | null> {
+  async getSongUrl(songId: string, _quality?: string): Promise<SongUrlResult | null> {
    const cid = await this.getCid(songId);
    if (!cid) return null;

@@ -253,7 +258,8 @@ export class BiliBiliProvider implements MusicProvider {
        (b.bandwidth ?? 0) > (a.bandwidth ?? 0) ? b : a
      );

-      return best.baseUrl ?? best.base_url ?? null;
+      const biliUrl = best.baseUrl ?? best.base_url;
+      return biliUrl ? { url: biliUrl } : null;
    } catch {
      return null;
    }
@@ -0,0 +1,224 @@
+import { describe, it, expect, vi } from "vitest";
+import { mapKugouSong, mapKugouSongs, mapKugouAlbums, mapKugouPlaylist, mapKugouPlaylists, krcToLrc, KugouProvider } from "./kugou.js";
+import { parseLyrics } from "./netease.js";
+
+describe("mapKugouSongs", () => {
+  it("maps the mobile-search song shape to a Song with platform 'kugou'", () => {
+    // Shape captured live from mobilecdn.kugou.com/api/v3/search/song.
+    const raw = {
+      hash: "B3A52A7A958BF0AED0EBFBA2E9A818B7",
+      album_audio_id: 32100650,
+      album_id: "966846",
+      songname: "晴天",
+      singername: "周杰伦",
+      duration: 269,
+    };
+    const [song] = mapKugouSongs([raw]);
+    expect(song.platform).toBe("kugou");
+    expect(song.name).toBe("晴天");
+    expect(song.artist).toBe("周杰伦");
+    expect(song.duration).toBe(269);
+    // The id must round-trip hash + album_audio_id + album_id so getSongUrl
+    // can resolve a stream from a search result.
+    expect(song.id).toBe("b3a52a7a958bf0aed0ebfba2e9a818b7|32100650|966846");
+  });
+
+  it("treats nested audio_info durations as milliseconds and flat search durations as seconds", () => {
+    // List endpoints: ms under audio_info.
+    expect(mapKugouSong({ audio_info: { hash: "abc", duration: 215000 } }).duration).toBe(215);
+    // Search endpoint: a long-form track's flat `duration` stays seconds (no /1000).
+    expect(mapKugouSong({ hash: "abc", songname: "x", duration: 10800 }).duration).toBe(10800);
+  });
+
+  it("falls back to splitting '歌手 - 歌名' from the filename", () => {
+    const song = mapKugouSong({ FileHash: "deadbeef", filename: "周杰伦 - 稻香", Duration: 200 });
+    expect(song.artist).toBe("周杰伦");
+    expect(song.name).toBe("稻香");
+  });
+
+  it("uses PascalCase fields from the gateway shape and skips entries with no hash", () => {
+    const songs = mapKugouSongs([
+      { FileHash: "aa", SongName: "n", SingerName: "s", MixSongID: 1, AlbumID: 2 },
+      { songname: "no hash" } as any,
+    ]);
+    expect(songs).toHaveLength(1);
+    expect(songs[0].id).toBe("aa|1|2");
+  });
+
+  it("returns [] for non-array input", () => {
+    expect(mapKugouSongs(undefined)).toEqual([]);
+  });
+
+  it("maps the NESTED album/playlist track shape (base + audio_info)", () => {
+    // Shape captured live from /album/songs (叶惠美).
+    const raw = {
+      base: { album_id: 966846, album_audio_id: 32100648, audio_name: "以父之名", author_name: "周杰伦" },
+      audio_info: { hash: "DBC0207490EB51153EF933EF5A7E98E4", duration: 342047 },
+    };
+    const [song] = mapKugouSongs([raw]);
+    expect(song.name).toBe("以父之名");
+    expect(song.artist).toBe("周杰伦");
+    expect(song.duration).toBe(342); // ms → s
+    expect(song.id).toBe("dbc0207490eb51153ef933ef5a7e98e4|32100648|966846");
+  });
+});
+
+describe("krcToLrc", () => {
+  it("converts KRC [startMs,durMs] line timestamps + strips word timings into parseable LRC", () => {
+    // Shape captured live from lyrics.kugou.com (周杰伦 - 晴天).
+    const krc = [
+      "[ti:晴天]",
+      "[ar:周杰伦]",
+      "[0,2250]<0,160,0>晴<160,160,0>天",
+      "[63000,1800]<0,200,0>故<200,200,0>事",
+    ].join("\n");
+    const lrc = krcToLrc(krc);
+    expect(lrc).toContain("[00:00.00]晴天");
+    expect(lrc).toContain("[01:03.00]故事");
+    expect(lrc).not.toMatch(/<\d+,\d+,\d+>/); // word timings stripped
+
+    // And the shared LRC parser must now actually produce timed lines.
+    const lines = parseLyrics(lrc);
+    expect(lines.length).toBe(2);
+    expect(lines[0]).toEqual({ time: 0, text: "晴天" });
+    expect(lines[1].time).toBe(63);
+    expect(lines[1].text).toBe("故事");
+  });
+});
+
+describe("mapKugouAlbums", () => {
+  it("maps album shape and normalises {size} covers to https", () => {
+    const [album] = mapKugouAlbums([
+      { album_id: 966846, album_name: "叶惠美", singername: "周杰伦", sizable_cover: "http://imge.kugou.com/x/{size}/abc.jpg", songcount: 11 },
+    ]);
+    expect(album.platform).toBe("kugou");
+    expect(album.id).toBe("966846");
+    expect(album.name).toBe("叶惠美");
+    expect(album.coverUrl).toBe("https://imge.kugou.com/x/240/abc.jpg");
+    expect(album.songCount).toBe(11);
+  });
+});
+
+describe("mapKugouSong — playlist (get_other_list_file) shape", () => {
+  it("splits the combined `name` and uses `mixsongid` as the audio id", () => {
+    // Shape captured live from /pubsongs/v2/get_other_list_file_nofilt (我喜欢).
+    // The combined "歌手 - 歌名" is in `name`; there is no separate songname.
+    const raw = {
+      name: "KOKIA - ありがとう… (谢谢…)",
+      hash: "E9A08A98614DD992F11A68A5E5F1C79F",
+      album_id: "1491689",
+      mixsongid: 37533796,
+      timelen: 248528, // ms
+      cover: "http://imge.kugou.com/stdmusic/{size}/20210113/x.jpg",
+    };
+    const song = mapKugouSong(raw);
+    expect(song.artist).toBe("KOKIA");
+    expect(song.name).toBe("ありがとう… (谢谢…)");
+    // hash lowercased | mixsongid | album_id — so getSongUrl can resolve it.
+    expect(song.id).toBe("e9a08a98614dd992f11a68a5e5f1c79f|37533796|1491689");
+    expect(song.duration).toBe(249); // timelen ms → s
+    expect(song.coverUrl).toBe("https://imge.kugou.com/stdmusic/240/20210113/x.jpg");
+  });
+});
+
+describe("mapKugouSong — cover art per endpoint", () => {
+  it("reads `sizable_cover` (daily/FM shape) and resolves {size}→240, http→https", () => {
+    const song = mapKugouSong({
+      hash: "abc",
+      songname: "x",
+      duration: 200,
+      sizable_cover: "http://imge.kugou.com/stdmusic/{size}/y.jpg",
+    });
+    expect(song.coverUrl).toBe("https://imge.kugou.com/stdmusic/240/y.jpg");
+  });
+
+  it("falls back to `trans_param.union_cover` (search shape, no top-level cover)", () => {
+    const song = mapKugouSong({
+      hash: "abc",
+      songname: "x",
+      duration: 200,
+      trans_param: { union_cover: "http://imge.kugou.com/stdmusic/{size}/z.jpg" },
+    });
+    expect(song.coverUrl).toBe("https://imge.kugou.com/stdmusic/240/z.jpg");
+  });
+
+  it("returns an empty coverUrl when no cover field is present", () => {
+    expect(mapKugouSong({ hash: "abc", songname: "x", duration: 200 }).coverUrl).toBe("");
+  });
+
+  it("skips an empty-string cover field (Kugou returns '') and uses the next non-empty source", () => {
+    const song = mapKugouSong({
+      hash: "abc",
+      songname: "x",
+      duration: 200,
+      sizable_cover: "", // present but empty — must NOT mask the real cover below
+      trans_param: { union_cover: "http://imge.kugou.com/stdmusic/{size}/z.jpg" },
+    });
+    expect(song.coverUrl).toBe("https://imge.kugou.com/stdmusic/240/z.jpg");
+  });
+});
+
+describe("mapKugouPlaylists", () => {
+  it("maps the user-playlist shape (/v7/get_all_list info), keying id on global_collection_id", () => {
+    // Shape captured live from /v7/get_all_list (我喜欢).
+    const [pl] = mapKugouPlaylists([
+      { name: "我喜欢", count: 7, global_collection_id: "collection_3_2526507197_2_0", listid: 2, type: 0 },
+    ]);
+    expect(pl.platform).toBe("kugou");
+    expect(pl.name).toBe("我喜欢");
+    expect(pl.songCount).toBe(7);
+    // Must be the global_collection_id — the only id getPlaylistSongs can open.
+    expect(pl.id).toBe("collection_3_2526507197_2_0");
+  });
+
+  it("maps the recommend shape (/v2/special_recommend), preferring global_collection_id over specialid", () => {
+    // Shape captured live from /v2/special_recommend special_list.
+    const pl = mapKugouPlaylist({
+      specialname: "米津玄师：蒙着眼睛也能炸翻全场",
+      specialid: 1154672,
+      global_collection_id: "collection_1_1029965246_1154672_0",
+      pic: "http://imge.kugou.com/specialimg/{size}/a.jpg",
+      percount: 0,
+    });
+    expect(pl.id).toBe("collection_1_1029965246_1154672_0");
+    expect(pl.name).toBe("米津玄师：蒙着眼睛也能炸翻全场");
+    expect(pl.coverUrl).toBe("https://imge.kugou.com/specialimg/240/a.jpg");
+  });
+
+  it("drops entries whose only id is a non-openable specialid/listid (not a global_collection_id)", () => {
+    // getPlaylistSongs can only open a global_collection_id, so a numeric
+    // specialid/listid would be a dead id — such entries must be dropped.
+    expect(mapKugouPlaylists([{ specialname: "x", specialid: 1154672, listid: 9 }])).toHaveLength(0);
+    expect(mapKugouPlaylists([{ name: "no id" }])).toHaveLength(0);
+    expect(mapKugouPlaylists(undefined)).toEqual([]);
+  });
+});
+
+describe("KugouProvider.search pagination", () => {
+  function mockProvider() {
+    const p = new KugouProvider();
+    const get = vi.fn().mockResolvedValue({ data: { data: { info: [] } } });
+    (p as any).mobileHttp = { get };
+    return { p, get };
+  }
+
+  function searchParams(get: ReturnType<typeof vi.fn>) {
+    const call = get.mock.calls[0];
+    expect(call, "expected a mobile search call").toBeTruthy();
+    return call[1].params as Record<string, unknown>;
+  }
+
+  it("sets page to offset/limit+1 and keeps pagesize=limit", async () => {
+    const { p, get } = mockProvider();
+    await p.search("hello", 20, 20); // page 2
+    const params = searchParams(get);
+    expect(params.page).toBe(2);
+    expect(params.pagesize).toBe(20);
+  });
+
+  it("defaults offset to 0 → page 1 (backward compatible)", async () => {
+    const { p, get } = mockProvider();
+    await p.search("hello", 20);
+    expect(searchParams(get).page).toBe(1);
+  });
+});
@@ -0,0 +1,235 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { mkdtempSync, rmSync, existsSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { LocalMusicProvider } from "./local.js";
+
+let dir: string;
+
+beforeEach(() => {
+  dir = mkdtempSync(join(tmpdir(), "local-audio-test-"));
+});
+
+afterEach(() => {
+  rmSync(dir, { recursive: true, force: true });
+});
+
+// Seed real files + an index.json so we can exercise the cleanup lifecycle
+// without invoking the ffmpeg duration probe that uploadAudio runs.
+function makeRecord(id: string, bytes = 16) {
+  const filePath = join(dir, `${id}.mp3`);
+  writeFileSync(filePath, Buffer.alloc(bytes, 1));
+  return {
+    id,
+    name: id,
+    artist: "本地上传",
+    album: "本地音乐",
+    duration: 0,
+    coverUrl: "",
+    platform: "local" as const,
+    filePath,
+    originalName: `${id}.mp3`,
+    uploadedAt: "1970-01-01T00:00:00.000Z",
+    size: bytes,
+    mimeType: "audio/mpeg",
+  };
+}
+
+function seed(records: ReturnType<typeof makeRecord>[]) {
+  writeFileSync(join(dir, "index.json"), JSON.stringify(records), "utf8");
+}
+
+describe("LocalMusicProvider cleanup lifecycle", () => {
+  it("sweep keeps referenced and never-played files, deletes only played+unreferenced", async () => {
+    const a = makeRecord("a");
+    const b = makeRecord("b");
+    const c = makeRecord("c");
+    seed([a, b, c]);
+    const p = new LocalMusicProvider(dir);
+    const refs = new Set<string>(["a"]); // "a" still sits in a queue somewhere
+    p.setInUseResolver(() => refs);
+
+    await p.getSongUrl("a"); // played, but referenced
+    await p.getSongUrl("b"); // played and unreferenced
+    // "c" was never played (e.g. uploaded but not queued)
+
+    const deleted = p.sweepUnreferenced();
+
+    expect(deleted).toEqual(["b"]);
+    expect(existsSync(a.filePath)).toBe(true); // referenced → kept
+    expect(existsSync(b.filePath)).toBe(false); // played + unreferenced → deleted
+    expect(existsSync(c.filePath)).toBe(true); // never played → kept
+  });
+
+  it("a played song still in the queue survives the sweep and stays replayable (loop / prev)", async () => {
+    const a = makeRecord("a");
+    seed([a]);
+    const p = new LocalMusicProvider(dir);
+    const refs = new Set<string>(["a"]); // loop queue still references it
+    p.setInUseResolver(() => refs);
+
+    await p.getSongUrl("a"); // first pass plays it
+    p.sweepUnreferenced(); // "playback_finished" sweep
+
+    expect(existsSync(a.filePath)).toBe(true);
+    expect((await p.getSongUrl("a"))?.url).toBe(a.filePath); // next loop pass works
+  });
+
+  it("re-playing a queued local song does not delete it (play-song order)", async () => {
+    const a = makeRecord("a");
+    seed([a]);
+    const p = new LocalMusicProvider(dir);
+    // Mirror the fixed endpoint order: the song is (re)added to the queue
+    // BEFORE the sweep runs, so it is referenced when we sweep.
+    const refs = new Set<string>(["a"]);
+    p.setInUseResolver(() => refs);
+
+    await p.getSongUrl("a"); // played once
+    p.sweepUnreferenced(); // sweep fired after the replay re-queued it
+    expect(existsSync(a.filePath)).toBe(true);
+    expect(await p.getSongUrl("a")).not.toBeNull();
+  });
+
+  it("deletes a played file once it leaves every queue", async () => {
+    const a = makeRecord("a");
+    seed([a]);
+    const p = new LocalMusicProvider(dir);
+    let refs = new Set<string>(["a"]);
+    p.setInUseResolver(() => refs);
+
+    await p.getSongUrl("a");
+    p.sweepUnreferenced();
+    expect(existsSync(a.filePath)).toBe(true); // still queued
+
+    refs = new Set<string>(); // queue cleared
+    p.sweepUnreferenced();
+    expect(existsSync(a.filePath)).toBe(false); // now removed
+    expect(await p.getSongUrl("a")).toBeNull();
+  });
+
+  it("never deletes anything when the reference resolver throws", async () => {
+    const a = makeRecord("a");
+    seed([a]);
+    const p = new LocalMusicProvider(dir);
+    p.setInUseResolver(() => {
+      throw new Error("manager unavailable");
+    });
+    await p.getSongUrl("a");
+    expect(p.sweepUnreferenced()).toEqual([]);
+    expect(existsSync(a.filePath)).toBe(true);
+  });
+});
+
+describe("LocalMusicProvider upload validation", () => {
+  it("rejects a spoofed Content-Type with a non-audio extension", async () => {
+    const p = new LocalMusicProvider(dir);
+    await expect(
+      p.uploadAudio({
+        buffer: Buffer.from("malicious"),
+        originalName: "evil.exe",
+        mimeType: "application/octet-stream",
+      }),
+    ).rejects.toThrow();
+  });
+
+  it("rejects an unknown extension even when the mime claims audio", async () => {
+    const p = new LocalMusicProvider(dir);
+    await expect(
+      p.uploadAudio({
+        buffer: Buffer.from("x"),
+        originalName: "evil.html",
+        mimeType: "audio/mpeg",
+      }),
+    ).rejects.toThrow();
+  });
+
+  it("rejects an empty file", async () => {
+    const p = new LocalMusicProvider(dir);
+    await expect(
+      p.uploadAudio({ buffer: Buffer.alloc(0), originalName: "a.mp3" }),
+    ).rejects.toThrow();
+  });
+});
+
+describe("LocalMusicProvider quota", () => {
+  it("evicts oldest unreferenced uploads beyond maxFiles", async () => {
+    const a = makeRecord("a");
+    const b = makeRecord("b");
+    seed([b, a]); // newest-first: b newer than a
+    const p = new LocalMusicProvider(dir, { maxFiles: 2 });
+    p.setInUseResolver(() => new Set<string>());
+
+    // Upload a third valid file → over the 2-file cap → evict the oldest ("a").
+    await p.uploadAudio({
+      buffer: Buffer.alloc(16, 7),
+      originalName: "c.mp3",
+      mimeType: "audio/mpeg",
+    });
+
+    expect(existsSync(a.filePath)).toBe(false); // oldest evicted
+    expect(existsSync(b.filePath)).toBe(true);
+    const result = await p.search("");
+    expect(result.songs.map((s) => s.id).sort()).not.toContain("a");
+  });
+
+  it("does not evict a referenced upload even when over the cap", async () => {
+    const a = makeRecord("a");
+    const b = makeRecord("b");
+    seed([b, a]);
+    const p = new LocalMusicProvider(dir, { maxFiles: 1 });
+    p.setInUseResolver(() => new Set<string>(["a"])); // "a" is queued
+
+    await p.uploadAudio({
+      buffer: Buffer.alloc(16, 7),
+      originalName: "c.mp3",
+      mimeType: "audio/mpeg",
+    });
+
+    expect(existsSync(a.filePath)).toBe(true); // protected: still queued
+  });
+
+  it("never evicts the just-uploaded file, even when every older file is referenced", async () => {
+    const a = makeRecord("a");
+    seed([a]);
+    const p = new LocalMusicProvider(dir, { maxFiles: 1 });
+    p.setInUseResolver(() => new Set<string>(["a"])); // the only older file is queued
+
+    const song = await p.uploadAudio({
+      buffer: Buffer.alloc(16, 7),
+      originalName: "c.mp3",
+      mimeType: "audio/mpeg",
+    });
+
+    // The returned song must actually exist and be playable — not a phantom.
+    expect(await p.getSongUrl(song.id)).not.toBeNull();
+  });
+});
+
+describe("LocalMusicProvider search pagination", () => {
+  it("slices [offset, offset+limit) instead of the first page", async () => {
+    const recs = ["a", "b", "c", "d"].map((id) => makeRecord(id));
+    seed(recs); // newest-first order preserved: a, b, c, d
+    const p = new LocalMusicProvider(dir);
+
+    const page1 = await p.search("", 2); // offset defaults to 0
+    expect(page1.songs.map((s) => s.id)).toEqual(["a", "b"]);
+
+    const page2 = await p.search("", 2, 2);
+    expect(page2.songs.map((s) => s.id)).toEqual(["c", "d"]);
+  });
+});
+
+describe("LocalMusicProvider filename handling", () => {
+  it("accepts a long filename without dropping its extension", async () => {
+    const p = new LocalMusicProvider(dir);
+    const longName = "x".repeat(300) + ".mp3";
+    // Must not throw the "unsupported format" error — the extension survives.
+    const song = await p.uploadAudio({
+      buffer: Buffer.alloc(16, 1),
+      originalName: longName,
+      mimeType: "audio/mpeg",
+    });
+    expect(song.id).toBeTruthy();
+    expect(await p.getSongUrl(song.id)).not.toBeNull();
+  });
+});
@@ -0,0 +1,391 @@
+import { spawn } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import path from "node:path";
+import crypto from "node:crypto";
+import type {
+  Album,
+  AuthStatus,
+  LyricLine,
+  MusicProvider,
+  Playlist,
+  PlaylistDetail,
+  QrCodeResult,
+  SearchResult,
+  Song,
+  SongUrlResult,
+} from "./provider.js";
+
+const require = createRequire(import.meta.url);
+const ffmpegPath: string | null = require("ffmpeg-static");
+
+const AUDIO_EXTENSIONS = new Set([
+  ".mp3",
+  ".flac",
+  ".wav",
+  ".m4a",
+  ".aac",
+  ".ogg",
+  ".opus",
+  ".webm",
+  ".wma",
+  ".alac",
+  ".aiff",
+  ".ape",
+]);
+
+const DEFAULT_MAX_FILES = 200;
+const DEFAULT_MAX_TOTAL_BYTES = 5 * 1024 * 1024 * 1024; // 5 GiB
+
+export interface LocalMusicProviderOptions {
+  /** Max number of uploaded files kept on disk (oldest unreferenced evicted). */
+  maxFiles?: number;
+  /** Max total bytes of uploaded files kept on disk. */
+  maxTotalBytes?: number;
+}
+
+interface LocalSongRecord extends Song {
+  filePath: string;
+  originalName: string;
+  uploadedAt: string;
+  size: number;
+  mimeType: string;
+}
+
+function safeFileName(name: string): string {
+  const base = path.basename(name || "audio")
+    .replace(/[<>:"/\\|?*\x00-\x1F]/g, "_")
+    .replace(/\s+/g, " ")
+    .trim();
+  if (!base) return "audio";
+  // Cap the total length but ALWAYS preserve the extension — truncating the
+  // whole string would drop a trailing ".mp3" on a long filename and make the
+  // file fail extension validation.
+  const ext = path.extname(base);
+  const stem = ext ? base.slice(0, base.length - ext.length) : base;
+  const safeStem = stem.slice(0, Math.max(1, 160 - ext.length)) || "audio";
+  return `${safeStem}${ext}`;
+}
+
+function titleFromFileName(name: string): string {
+  return safeFileName(name).replace(/\.[^.]+$/, "") || "本地音频";
+}
+
+async function probeDurationSeconds(filePath: string): Promise<number> {
+  return new Promise((resolve) => {
+    const ffmpeg = spawn(ffmpegPath || "ffmpeg", ["-hide_banner", "-i", filePath], {
+      stdio: ["ignore", "ignore", "pipe"],
+    });
+    let stderr = "";
+    const timeout = setTimeout(() => {
+      ffmpeg.kill("SIGKILL");
+      resolve(0);
+    }, 5000);
+    ffmpeg.stderr.on("data", (chunk) => {
+      stderr += chunk.toString("utf8");
+    });
+    ffmpeg.on("error", () => {
+      clearTimeout(timeout);
+      resolve(0);
+    });
+    ffmpeg.on("close", () => {
+      clearTimeout(timeout);
+      const match = stderr.match(/Duration:\s*(\d+):(\d+):(\d+(?:\.\d+)?)/);
+      if (!match) {
+        resolve(0);
+        return;
+      }
+      const hours = Number(match[1]);
+      const minutes = Number(match[2]);
+      const seconds = Number(match[3]);
+      const total = hours * 3600 + minutes * 60 + seconds;
+      resolve(Number.isFinite(total) ? Math.round(total) : 0);
+    });
+  });
+}
+
+export class LocalMusicProvider implements MusicProvider {
+  readonly platform = "local" as const;
+  private readonly uploadDir: string;
+  private readonly indexPath: string;
+  private records: LocalSongRecord[] = [];
+  private readonly maxFiles: number;
+  private readonly maxTotalBytes: number;
+  /** Ids that have been resolved for playback at least once; only these are
+   *  eligible for reference-aware cleanup, so freshly uploaded files that are
+   *  not yet queued/played survive in the search list. */
+  private playedIds = new Set<string>();
+  /** Returns the set of local song ids still referenced by any bot's queue.
+   *  Deletion never removes a file whose id this set contains. */
+  private inUseResolver: () => Set<string> = () => new Set<string>();
+  /** Ids with an in-flight retry-delete scheduled (file briefly locked, e.g.
+   *  ffmpeg on Windows still releasing a just-stopped track). */
+  private retrying = new Set<string>();
+
+  constructor(uploadDir: string, options: LocalMusicProviderOptions = {}) {
+    this.uploadDir = uploadDir;
+    this.indexPath = path.join(uploadDir, "index.json");
+    this.maxFiles = options.maxFiles ?? DEFAULT_MAX_FILES;
+    this.maxTotalBytes = options.maxTotalBytes ?? DEFAULT_MAX_TOTAL_BYTES;
+    mkdirSync(uploadDir, { recursive: true });
+    this.loadIndex();
+  }
+
+  /** Wire the resolver the BotManager uses to report which uploads are still
+   *  queued anywhere. Must be set before any cleanup can delete files. */
+  setInUseResolver(resolver: () => Set<string>): void {
+    this.inUseResolver = resolver;
+  }
+
+  private referencedIds(): Set<string> | null {
+    try {
+      return this.inUseResolver() ?? new Set<string>();
+    } catch {
+      // Resolver failure → references unknown → refuse to delete anything.
+      return null;
+    }
+  }
+
+  private loadIndex(): void {
+    try {
+      const raw = readFileSync(this.indexPath, "utf8");
+      const parsed = JSON.parse(raw) as LocalSongRecord[];
+      this.records = Array.isArray(parsed)
+        ? parsed.filter((r) => r && typeof r.id === "string" && typeof r.filePath === "string")
+        : [];
+    } catch {
+      this.records = [];
+    }
+  }
+
+  private saveIndex(): void {
+    writeFileSync(this.indexPath, JSON.stringify(this.records, null, 2), "utf8");
+  }
+
+  async uploadAudio(input: {
+    buffer: Buffer;
+    originalName: string;
+    mimeType?: string;
+  }): Promise<Song> {
+    const originalName = safeFileName(input.originalName || "audio");
+    const ext = path.extname(originalName).toLowerCase();
+    // Validate by the (sanitised) file extension only — never trust the
+    // client-supplied Content-Type. This also guarantees the STORED extension
+    // is one of the known audio types, so a spoofed header cannot persist an
+    // arbitrary-extension blob on disk.
+    if (!AUDIO_EXTENSIONS.has(ext)) {
+      throw new Error("只支持常见音频文件，如 mp3、flac、wav、m4a、ogg、opus、aac、webm 等");
+    }
+    if (!input.buffer || input.buffer.length === 0) {
+      throw new Error("上传文件为空");
+    }
+
+    const id = crypto.randomUUID();
+    const storedName = `${id}${ext}`;
+    const filePath = path.join(this.uploadDir, storedName);
+    writeFileSync(filePath, input.buffer);
+
+    const duration = await probeDurationSeconds(filePath);
+    const song: LocalSongRecord = {
+      id,
+      name: titleFromFileName(originalName),
+      artist: "本地上传",
+      album: "本地音乐",
+      duration,
+      coverUrl: "",
+      platform: "local",
+      filePath,
+      originalName,
+      uploadedAt: new Date().toISOString(),
+      size: input.buffer.length,
+      mimeType: input.mimeType || "application/octet-stream",
+    };
+
+    this.records.unshift(song);
+    this.saveIndex();
+    // Never evict the file we just accepted, even if every older file is still
+    // queued — returning success for a file we deleted would be a phantom entry.
+    this.enforceQuota(id);
+    return this.toSong(song);
+  }
+
+  private toSong(record: LocalSongRecord): Song {
+    const { filePath: _filePath, originalName: _originalName, uploadedAt: _uploadedAt, size: _size, mimeType: _mimeType, ...song } = record;
+    return song;
+  }
+
+  async search(query: string, limit = 20, offset = 0): Promise<SearchResult> {
+    const q = query.trim().toLowerCase();
+    const songs = this.records
+      .filter((r) => existsSync(r.filePath))
+      .filter((r) => !q || `${r.name} ${r.artist} ${r.album} ${r.originalName}`.toLowerCase().includes(q))
+      .slice(offset, offset + limit)
+      .map((r) => this.toSong(r));
+    return { songs, playlists: [], albums: [] };
+  }
+
+  async getSongUrl(songId: string): Promise<SongUrlResult | null> {
+    const record = this.records.find((r) => r.id === songId);
+    if (!record || !existsSync(record.filePath)) return null;
+    // A song that is actually resolved for playback becomes eligible for
+    // cleanup once it is no longer referenced by any queue.
+    this.playedIds.add(songId);
+    return { url: record.filePath };
+  }
+
+  async getSongDetail(songId: string): Promise<Song | null> {
+    const record = this.records.find((r) => r.id === songId);
+    return record && existsSync(record.filePath) ? this.toSong(record) : null;
+  }
+
+  /**
+   * Reference-aware cleanup: delete only files that have been played at least
+   * once AND are no longer referenced by any bot's queue. Safe to call after
+   * any queue mutation — a file still queued anywhere (loop replay, prev,
+   * the song being re-started, the same upload queued on another bot) is kept.
+   * Returns the ids that were deleted.
+   */
+  sweepUnreferenced(): string[] {
+    const inUse = this.referencedIds();
+    if (!inUse) return [];
+    const deleted: string[] = [];
+    for (let i = this.records.length - 1; i >= 0; i--) {
+      const r = this.records[i];
+      if (!this.playedIds.has(r.id) || inUse.has(r.id)) continue;
+      if (this.unlinkRecordAt(i)) {
+        deleted.push(r.id);
+      } else {
+        // File still locked (e.g. ffmpeg just-stopped on Windows) — keep the
+        // record and retry shortly; never orphan it or abort the rest.
+        this.scheduleRetry(r.id);
+      }
+    }
+    if (deleted.length) this.saveIndex();
+    return deleted;
+  }
+
+  /** Evict oldest, never-referenced uploads until under the file-count and
+   *  total-byte caps. Bounds disk use from uploads that are never played.
+   *  `protectId` is never evicted (the file just uploaded in this same call). */
+  private enforceQuota(protectId?: string): void {
+    if (this.records.length <= this.maxFiles &&
+        this.totalBytes() <= this.maxTotalBytes) {
+      return;
+    }
+    const inUse = this.referencedIds();
+    if (!inUse) return; // can't safely evict without knowing references
+    let count = this.records.length;
+    let bytes = this.totalBytes();
+    let changed = false;
+    for (let i = this.records.length - 1;
+         i >= 0 && (count > this.maxFiles || bytes > this.maxTotalBytes);
+         i--) {
+      const r = this.records[i];
+      if (inUse.has(r.id) || r.id === protectId) continue; // never evict these
+      const size = r.size || 0;
+      if (this.unlinkRecordAt(i)) {
+        count--;
+        bytes -= size;
+        changed = true;
+      }
+    }
+    if (changed) this.saveIndex();
+  }
+
+  /**
+   * Delete the backing file for records[index] and drop the record from memory.
+   * Deletes the FILE FIRST, then mutates state only on success, so a failed
+   * unlink leaves the record intact (file + index stay consistent) instead of
+   * orphaning the file. Returns true if the file is gone (deleted or already
+   * absent), false if it is still present (locked). Never throws; does NOT
+   * persist the index — callers batch saveIndex().
+   */
+  private unlinkRecordAt(index: number): boolean {
+    const r = this.records[index];
+    try {
+      rmSync(r.filePath, { force: true });
+    } catch {
+      // rmSync force:true only swallows ENOENT; EBUSY/EPERM/EACCES throw. If
+      // the file genuinely vanished anyway, fall through and drop the record.
+      if (existsSync(r.filePath)) return false;
+    }
+    this.records.splice(index, 1);
+    this.playedIds.delete(r.id);
+    this.retrying.delete(r.id);
+    return true;
+  }
+
+  /** Schedule a bounded, non-blocking retry to delete a briefly-locked file.
+   *  Uses unref'd timers so it never keeps the process alive. */
+  private scheduleRetry(id: string, attempt = 1): void {
+    if (attempt === 1 && this.retrying.has(id)) return;
+    this.retrying.add(id);
+    const MAX_ATTEMPTS = 6;
+    const timer = setTimeout(() => {
+      const index = this.records.findIndex((r) => r.id === id);
+      if (index < 0) { this.retrying.delete(id); return; } // already removed
+      const inUse = this.referencedIds();
+      if (!inUse || inUse.has(id)) { this.retrying.delete(id); return; } // unknown or re-queued
+      if (this.unlinkRecordAt(index)) {
+        this.saveIndex();
+      } else if (attempt < MAX_ATTEMPTS) {
+        this.scheduleRetry(id, attempt + 1);
+      } else {
+        this.retrying.delete(id); // give up; next sweep/quota will retry
+      }
+    }, 500 * attempt);
+    if (typeof timer.unref === "function") timer.unref();
+  }
+
+  private totalBytes(): number {
+    return this.records.reduce((n, r) => n + (r.size || 0), 0);
+  }
+
+  setQuality(_quality: string): void {
+    // 本地文件按原始音质播放。
+  }
+
+  getQuality(): string {
+    return "original";
+  }
+
+  async getPlaylistSongs(_playlistId: string): Promise<Song[]> {
+    return [];
+  }
+
+  async getRecommendPlaylists(): Promise<Playlist[]> {
+    return [];
+  }
+
+  async getAlbumSongs(_albumId: string): Promise<Song[]> {
+    return [];
+  }
+
+  async getLyrics(_songId: string): Promise<LyricLine[]> {
+    return [];
+  }
+
+  async getQrCode(): Promise<QrCodeResult> {
+    throw new Error("Local music does not require login");
+  }
+
+  async checkQrCodeStatus(_key: string): Promise<"waiting" | "scanned" | "confirmed" | "expired"> {
+    return "expired";
+  }
+
+  setCookie(_cookie: string): void {
+    // no-op
+  }
+
+  getCookie(): string {
+    return "";
+  }
+
+  async getAuthStatus(): Promise<AuthStatus> {
+    return { loggedIn: true, nickname: "本地音乐" };
+  }
+
+  async getPlaylistDetail(_playlistId: string): Promise<PlaylistDetail | null> {
+    return null;
+  }
+}
@@ -1,5 +1,5 @@
-import { describe, it, expect } from "vitest";
-import { parseLyrics, mapNeteaseAlbums } from "./netease.js";
+import { describe, it, expect, vi } from "vitest";
+import { parseLyrics, mapNeteaseAlbums, mapNeteaseSongs, parseNeteaseTrial, NeteaseProvider } from "./netease.js";

 describe("NetEase adapter", () => {
  it("parses LRC format lyrics", () => {
@@ -56,4 +56,86 @@ describe("NetEase adapter", () => {
    expect(mapNeteaseAlbums(null as any)).toEqual([]);
    expect(mapNeteaseAlbums(undefined as any)).toEqual([]);
  });
+
+  it("mapNeteaseSongs maps fee to vip flag (1/4 = vip, 0/8 = free)", () => {
+    const raw = [
+      { id: 1, name: "VIP", ar: [{ name: "A" }], al: { name: "Al", picUrl: "p" }, dt: 180000, fee: 1 },
+      { id: 2, name: "Album-only", ar: [], al: { name: "Al", picUrl: "" }, dt: 0, fee: 4 },
+      { id: 3, name: "Free", ar: [], al: {}, dt: 0, fee: 0 },
+      { id: 4, name: "Free low-quality", ar: [], al: {}, dt: 0, fee: 8 },
+    ];
+    const out = mapNeteaseSongs(raw);
+    expect(out[0].vip).toBe(true);
+    expect(out[1].vip).toBe(true);
+    expect(out[2].vip).toBe(false);
+    expect(out[3].vip).toBe(false); // fee=8 plays in full (low quality), NOT vip
+  });
+
+  it("mapNeteaseSongs accepts artists/album/duration aliases (personal_fm shape)", () => {
+    const out = mapNeteaseSongs([
+      { id: 9, name: "FM", artists: [{ name: "B" }], album: { name: "Al2", picUrl: "p2" }, duration: 200000, fee: 0 },
+    ]);
+    expect(out[0]).toMatchObject({ artist: "B", album: "Al2", coverUrl: "p2", vip: false });
+  });
+
+  it("parseNeteaseTrial maps freeTrialInfo to trial seconds", () => {
+    // 无试听（VIP/免费）
+    expect(parseNeteaseTrial({})).toBeUndefined();
+    expect(parseNeteaseTrial({ freeTrialInfo: null })).toBeUndefined();
+    // 标准秒
+    expect(parseNeteaseTrial({ freeTrialInfo: { start: 0, end: 30 } })).toBe(30);
+    expect(parseNeteaseTrial({ freeTrialInfo: { start: 5, end: 35 } })).toBe(30);
+    // 别名容忍 begin/trialBegin
+    expect(parseNeteaseTrial({ freeTrialInfo: { begin: 0, end: 30 } })).toBe(30);
+    // 毫秒兜底（end>1000）
+    expect(parseNeteaseTrial({ freeTrialInfo: { start: 0, end: 30000 } })).toBe(30);
+    // 异常 end<=start
+    expect(parseNeteaseTrial({ freeTrialInfo: { start: 0, end: 0 } })).toBeUndefined();
+  });
+});
+
+describe("NeteaseProvider.search pagination", () => {
+  function mockProvider() {
+    const p = new NeteaseProvider("http://x");
+    const get = vi.fn().mockResolvedValue({
+      data: { result: { songs: [], playlists: [], albums: [] } },
+    });
+    (p as any).api = { get };
+    return { p, get };
+  }
+
+  /** Find the /cloudsearch call whose params.type matches. */
+  function callByType(get: ReturnType<typeof vi.fn>, type: number) {
+    const call = get.mock.calls.find((c: any[]) => c[1]?.params?.type === type);
+    expect(call, `expected a /cloudsearch call with type=${type}`).toBeTruthy();
+    return call![1].params as Record<string, unknown>;
+  }
+
+  it("forwards offset for songs and uses real limit+offset for playlists/albums", async () => {
+    const { p, get } = mockProvider();
+    await p.search("hello", 20, 20);
+
+    // songs (type 1): offset forwarded, limit unchanged
+    const songs = callByType(get, 1);
+    expect(songs.limit).toBe(20);
+    expect(songs.offset).toBe(20);
+
+    // playlists (type 1000): limit-driven (NOT hardcoded 10) + offset
+    const playlists = callByType(get, 1000);
+    expect(playlists.limit).toBe(20);
+    expect(playlists.offset).toBe(20);
+
+    // albums (type 10): limit-driven (NOT hardcoded 10) + offset
+    const albums = callByType(get, 10);
+    expect(albums.limit).toBe(20);
+    expect(albums.offset).toBe(20);
+  });
+
+  it("defaults offset to 0 (backward compatible)", async () => {
+    const { p, get } = mockProvider();
+    await p.search("hello", 20);
+    expect(callByType(get, 1).offset).toBe(0);
+    expect(callByType(get, 1000).offset).toBe(0);
+    expect(callByType(get, 10).offset).toBe(0);
+  });
 });
@@ -2,6 +2,7 @@ import axios, { type AxiosInstance } from "axios";
 import type {
  MusicProvider,
  Song,
+  SongUrlResult,
  Playlist,
  PlaylistDetail,
  LyricLine,
@@ -68,6 +69,33 @@ export function mapNeteaseAlbums(raw: any[] | null | undefined): Album[] {
  }));
 }

+export function mapNeteaseSongs(raw: any[] | null | undefined): Song[] {
+  if (!Array.isArray(raw)) return [];
+  return raw.map((s: any) => ({
+    id: String(s.id),
+    name: s.name,
+    artist: (s.ar ?? s.artists ?? []).map((a: any) => a.name).join(" / "),
+    album: s.al?.name ?? s.album?.name ?? "",
+    duration: Math.round((s.dt ?? s.duration ?? 0) / 1000),
+    coverUrl: s.al?.picUrl ?? s.album?.picUrl ?? "",
+    platform: "netease",
+    // fee: 0=free, 1=VIP, 4=album-only, 8=free low-quality (plays in full, NOT vip)
+    vip: s.fee === 1 || s.fee === 4,
+  }));
+}
+
+/** 解析网易云 freeTrialInfo → 试听秒数；无片段（VIP/免费）返回 undefined。
+ *  真实字段 {start,end} 单位秒；容忍 begin/trialBegin 别名 + 毫秒兜底（end>1000）。 */
+export function parseNeteaseTrial(item: any): number | undefined {
+  const t = item?.freeTrialInfo;
+  if (!t || typeof t !== "object") return undefined;
+  const start = Number(t.start ?? t.begin ?? t.trialBegin ?? 0);
+  const end = Number(t.end ?? t.trialEnd);
+  if (!Number.isFinite(end) || end <= start) return undefined;
+  const secs = end > 1000 ? (end - start) / 1000 : end - start;
+  return Math.round(secs);
+}
+
 // NetEase quality levels: standard(128k) higher(192k) exhigh(320k) lossless(flac) hires(hi-res) jyeffect jymaster
 export const NETEASE_QUALITY_LEVELS = [
  { value: "standard", label: "标准 (128kbps)", bitrate: 128 },
@@ -103,35 +131,29 @@ export class NeteaseProvider implements MusicProvider {
    return this.cookie ? { cookie: this.cookie } : {};
  }

-  async search(query: string, limit = 20): Promise<SearchResult> {
+  async search(query: string, limit = 20, offset = 0): Promise<SearchResult> {
+    // /cloudsearch supports offset for every type. Songs, playlists (type 1000)
+    // and albums (type 10) are all limit/offset-driven so the web can page past
+    // the first page (playlists/albums were previously hardcoded to limit: 10).
    const [songRes, playlistRes, albumRes] = await Promise.all([
      this.api.get("/cloudsearch", {
-        params: { keywords: query, type: 1, limit, ...this.cookieParams },
+        params: { keywords: query, type: 1, limit, offset, ...this.cookieParams },
      }),
      this.api.get("/cloudsearch", {
        params: {
          keywords: query,
          type: 1000,
-          limit: 10,
+          limit,
+          offset,
          ...this.cookieParams,
        },
      }),
      this.api.get("/cloudsearch", {
-        params: { keywords: query, type: 10, limit: 10, ...this.cookieParams },
+        params: { keywords: query, type: 10, limit, offset, ...this.cookieParams },
      }),
    ]);

-    const songs: Song[] = (songRes.data?.result?.songs ?? []).map(
-      (s: any) => ({
-        id: String(s.id),
-        name: s.name,
-        artist: (s.ar ?? []).map((a: any) => a.name).join(" / "),
-        album: s.al?.name ?? "",
-        duration: Math.round((s.dt ?? 0) / 1000),
-        coverUrl: s.al?.picUrl ?? "",
-        platform: "netease",
-      })
-    );
+    const songs: Song[] = mapNeteaseSongs(songRes.data?.result?.songs);

    const playlists: Playlist[] = (
      playlistRes.data?.result?.playlists ?? []
@@ -148,44 +170,29 @@ export class NeteaseProvider implements MusicProvider {
    return { songs, playlists, albums };
  }

-  async getSongUrl(songId: string, quality?: string): Promise<string | null> {
+  async getSongUrl(songId: string, quality?: string): Promise<SongUrlResult | null> {
    const level = quality ?? this.quality;
    const res = await this.api.get("/song/url/v1", {
      params: { id: songId, level, ...this.cookieParams },
    });
-    return res.data?.data?.[0]?.url ?? null;
+    const item = res.data?.data?.[0];
+    const url = item?.url;
+    if (!url) return null;
+    return { url, trialDuration: parseNeteaseTrial(item) };
  }

  async getSongDetail(songId: string): Promise<Song | null> {
    const res = await this.api.get("/song/detail", {
      params: { ids: songId, ...this.cookieParams },
    });
-    const s = res.data?.songs?.[0];
-    if (!s) return null;
-    return {
-      id: String(s.id),
-      name: s.name,
-      artist: (s.ar ?? []).map((a: any) => a.name).join(" / "),
-      album: s.al?.name ?? "",
-      duration: Math.round((s.dt ?? 0) / 1000),
-      coverUrl: s.al?.picUrl ?? "",
-      platform: "netease",
-    };
+    return mapNeteaseSongs(res.data?.songs)[0] ?? null;
  }

  async getPlaylistSongs(playlistId: string): Promise<Song[]> {
    const res = await this.api.get("/playlist/track/all", {
      params: { id: playlistId, ...this.cookieParams },
    });
-    return (res.data?.songs ?? []).map((s: any) => ({
-      id: String(s.id),
-      name: s.name,
-      artist: (s.ar ?? []).map((a: any) => a.name).join(" / "),
-      album: s.al?.name ?? "",
-      duration: Math.round((s.dt ?? 0) / 1000),
-      coverUrl: s.al?.picUrl ?? "",
-      platform: "netease",
-    }));
+    return mapNeteaseSongs(res.data?.songs);
  }

  async getRecommendPlaylists(): Promise<Playlist[]> {
@@ -205,15 +212,7 @@ export class NeteaseProvider implements MusicProvider {
    const res = await this.api.get("/album", {
      params: { id: albumId, ...this.cookieParams },
    });
-    return (res.data?.songs ?? []).map((s: any) => ({
-      id: String(s.id),
-      name: s.name,
-      artist: (s.ar ?? []).map((a: any) => a.name).join(" / "),
-      album: s.al?.name ?? "",
-      duration: Math.round((s.dt ?? 0) / 1000),
-      coverUrl: s.al?.picUrl ?? "",
-      platform: "netease",
-    }));
+    return mapNeteaseSongs(res.data?.songs);
  }

  async getLyrics(songId: string): Promise<LyricLine[]> {
@@ -312,30 +311,14 @@ export class NeteaseProvider implements MusicProvider {
    const res = await this.api.get("/personal_fm", {
      params: { ...this.cookieParams },
    });
-    return (res.data?.data ?? []).map((s: any) => ({
-      id: String(s.id),
-      name: s.name,
-      artist: (s.artists ?? []).map((a: any) => a.name).join(" / "),
-      album: s.album?.name ?? "",
-      duration: Math.round((s.duration ?? 0) / 1000),
-      coverUrl: s.album?.picUrl ?? "",
-      platform: "netease",
-    }));
+    return mapNeteaseSongs(res.data?.data);
  }

  async getDailyRecommendSongs(): Promise<Song[]> {
    const res = await this.api.get("/recommend/songs", {
      params: { ...this.cookieParams },
    });
-    return (res.data?.data?.dailySongs ?? []).map((s: any) => ({
-      id: String(s.id),
-      name: s.name,
-      artist: (s.ar ?? []).map((a: any) => a.name).join(" / "),
-      album: s.al?.name ?? "",
-      duration: Math.round((s.dt ?? 0) / 1000),
-      coverUrl: s.al?.picUrl ?? "",
-      platform: "netease",
-    }));
+    return mapNeteaseSongs(res.data?.data?.dailySongs);
  }

  async getPlaylistDetail(playlistId: string): Promise<PlaylistDetail | null> {
@@ -5,19 +5,29 @@ export interface Song {
  album: string;
  duration: number; // seconds
  coverUrl: string;
-  platform: "netease" | "qq" | "bilibili" | "youtube";
+  platform: "netease" | "qq" | "bilibili" | "youtube" | "local" | "kugou";
+  /** VIP / copyright-restricted: non-VIP users can only play a trial fragment
+   *  (NetEase fee=1 VIP / fee=4 album-only, or QQ pay.payplay/paytrackprice=1). */
+  vip?: boolean;
 }

 export interface SongWithUrl extends Song {
  url: string;
 }

+/** getSongUrl 解析结果。trialDuration 缺省 = 完整可播放（VIP 账号 / 免费曲）。 */
+export interface SongUrlResult {
+  url: string;
+  /** 试听片段时长（秒）。VIP/免费曲为 undefined → 调用方回退完整 duration。 */
+  trialDuration?: number;
+}
+
 export interface Playlist {
  id: string;
  name: string;
  coverUrl: string;
  songCount: number;
-  platform: "netease" | "qq" | "bilibili" | "youtube";
+  platform: "netease" | "qq" | "bilibili" | "youtube" | "local" | "kugou";
 }

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

 export interface LyricLine {
@@ -62,10 +72,10 @@ export interface AuthStatus {
 }

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

-  search(query: string, limit?: number): Promise<SearchResult>;
-  getSongUrl(songId: string, quality?: string): Promise<string | null>;
+  search(query: string, limit?: number, offset?: number): Promise<SearchResult>;
+  getSongUrl(songId: string, quality?: string): Promise<SongUrlResult | null>;
  setQuality(quality: string): void;
  getQuality(): string;
  getSongDetail(songId: string): Promise<Song | null>;
@@ -1,5 +1,14 @@
-import { describe, it, expect } from "vitest";
-import { mapQqAlbums, mapQqSongs } from "./qq.js";
+import { describe, it, expect, vi, beforeEach } from "vitest";
+
+// All axios.create(...) instances in qq.ts (qqMusicuApi / qqSearchApi / qqFavApi
+// and the per-instance api) share this single mock so the search test can
+// inspect the outgoing params/body regardless of which client issued them.
+const { mockGet, mockPost } = vi.hoisted(() => ({ mockGet: vi.fn(), mockPost: vi.fn() }));
+vi.mock("axios", () => ({
+  default: { create: () => ({ get: mockGet, post: mockPost }) },
+}));
+
+import { mapQqAlbums, mapQqSongs, parseQqTrial, QQMusicProvider } from "./qq.js";

 describe("QQ adapter", () => {
  it("mapQqSongs maps QQMusicApi-style song entries", () => {
@@ -22,10 +31,37 @@ describe("QQ adapter", () => {
        duration: 243,
        coverUrl: "https://y.gtimg.cn/music/photo_new/T002R300x300M000alb001.jpg",
        platform: "qq",
+        vip: false,
      },
    ]);
  });

+  it("mapQqSongs maps pay field to vip flag", () => {
+    const out = mapQqSongs([
+      { mid: "v1", name: "VIP playplay", singer: [], album: {}, interval: 100, pay: { payplay: 1, paytrackprice: 0 } },
+      { mid: "v2", name: "VIP trackprice", singer: [], album: {}, interval: 100, pay: { payplay: 0, paytrackprice: 1 } },
+      { mid: "f1", name: "Free", singer: [], album: {}, interval: 100, pay: { payplay: 0, paytrackprice: 0 } },
+      { mid: "f2", name: "No pay field", singer: [], album: {}, interval: 100 },
+    ]);
+    expect(out[0].vip).toBe(true);
+    expect(out[1].vip).toBe(true);
+    expect(out[2].vip).toBe(false);
+    expect(out[3].vip).toBe(false);
+  });
+
+  it("parseQqTrial maps isTryout/tryout to trial seconds", () => {
+    // 非试听（VIP/免费）
+    expect(parseQqTrial({ isTryout: 0 })).toBeUndefined();
+    expect(parseQqTrial({})).toBeUndefined();
+    // 试听（秒）
+    expect(parseQqTrial({ isTryout: 1, tryBegin: 0, tryEnd: 30 })).toBe(30);
+    expect(parseQqTrial({ tryout: true, begin: 0, end: 45 })).toBe(45);
+    // 毫秒兜底
+    expect(parseQqTrial({ isTryout: 1, tryBegin: 0, tryEnd: 30000 })).toBe(30);
+    // 异常
+    expect(parseQqTrial({ isTryout: 1, tryEnd: 0 })).toBeUndefined();
+  });
+
  it("mapQqAlbums maps albumMID-style raw entries", () => {
    const raw = [
      {
@@ -65,3 +101,74 @@ describe("QQ adapter", () => {
    expect(out[0].id).toBe("");
  });
 });
+
+describe("QQMusicProvider.search pagination", () => {
+  beforeEach(() => {
+    mockGet.mockReset();
+    mockPost.mockReset();
+  });
+
+  /** musicu.fcg returns one song → primary path succeeds. */
+  function musicuOk() {
+    mockGet.mockImplementation(async (url: string) => {
+      if (url === "/cgi-bin/musicu.fcg") {
+        return {
+          data: {
+            req_0: { data: { body: { song: { list: [{ mid: "m1", name: "S", singer: [], album: {}, interval: 100 }] } } } },
+            req_album: { data: { body: { album: { list: [] } } } },
+            req_playlist: { data: { body: { songlist: { list: [] } } } },
+          },
+        };
+      }
+      return { data: {} };
+    });
+  }
+
+  function musicuReqData() {
+    const call = mockGet.mock.calls.find((c: any[]) => c[0] === "/cgi-bin/musicu.fcg");
+    expect(call, "expected a musicu.fcg call").toBeTruthy();
+    return JSON.parse(call![1].params.data);
+  }
+
+  it("adds page_num (offset/limit+1) and limit-driven num_per_page for songs/albums/playlists", async () => {
+    musicuOk();
+    const p = new QQMusicProvider("http://x");
+    await p.search("hello", 20, 20); // page 2
+
+    const d = musicuReqData();
+    expect(d.req_0.param.page_num).toBe(2);
+    expect(d.req_0.param.num_per_page).toBe(20);
+    // Albums/playlists: num_per_page must be limit-driven (NOT hardcoded 10).
+    expect(d.req_album.param.page_num).toBe(2);
+    expect(d.req_album.param.num_per_page).toBe(20);
+    expect(d.req_playlist.param.page_num).toBe(2);
+    expect(d.req_playlist.param.num_per_page).toBe(20);
+  });
+
+  it("defaults offset to 0 → page_num 1 (backward compatible)", async () => {
+    musicuOk();
+    const p = new QQMusicProvider("http://x");
+    await p.search("hello", 20);
+    const d = musicuReqData();
+    expect(d.req_0.param.page_num).toBe(1);
+  });
+
+  it("fallback client_search_cp sets p to the page cursor", async () => {
+    // musicu returns no songs → primary returns null → fallback runs.
+    mockGet.mockImplementation(async (url: string) => {
+      if (url === "/cgi-bin/musicu.fcg") {
+        return { data: { req_0: { data: { body: { song: { list: [] } } } } } };
+      }
+      // client_search_cp
+      return { data: { data: { song: { list: [] }, album: { list: [] } } } };
+    });
+    const p = new QQMusicProvider("http://x");
+    await p.search("hello", 20, 20); // page 2
+
+    const songCall = mockGet.mock.calls.find(
+      (c: any[]) => c[0] === "/soso/fcgi-bin/client_search_cp" && c[1]?.params?.type === 0
+    );
+    expect(songCall, "expected a client_search_cp song call").toBeTruthy();
+    expect(songCall![1].params.p).toBe(2);
+  });
+});
@@ -2,6 +2,7 @@ import axios, { type AxiosInstance } from "axios";
 import type {
  MusicProvider,
  Song,
+  SongUrlResult,
  Playlist,
  PlaylistDetail,
  LyricLine,
@@ -53,10 +54,23 @@ export function mapQqSongs(raw: any[] | null | undefined): Song[] {
        ? `https://y.gtimg.cn/music/photo_new/T002R300x300M000${albumMid}.jpg`
        : "",
      platform: "qq" as const,
+      vip: s.pay?.payplay === 1 || s.pay?.paytrackprice === 1 || false,
    };
  }).filter((s) => s.id);
 }

+/** 解析 QQ 试听标记 → 试听秒数；非试听（VIP/免费）返回 undefined。
+ *  字段 isTryout===1 / tryout===true + tryBegin/tryEnd；容忍 begin/start 别名 + 毫秒兜底。 */
+export function parseQqTrial(playUrl: any): number | undefined {
+  if (!playUrl || typeof playUrl !== "object") return undefined;
+  if (playUrl.isTryout !== 1 && playUrl.tryout !== true) return undefined;
+  const begin = Number(playUrl.tryBegin ?? playUrl.begin ?? playUrl.start ?? 0);
+  const end = Number(playUrl.tryEnd ?? playUrl.end);
+  if (!Number.isFinite(end) || end <= begin) return undefined;
+  const secs = end > 1000 ? (end - begin) / 1000 : end - begin;
+  return Math.round(secs);
+}
+
 export function mapQqAlbums(raw: any[] | null | undefined): Album[] {
  if (!Array.isArray(raw)) return [];
  return raw.map((a) => {
@@ -135,16 +149,16 @@ export class QQMusicProvider implements MusicProvider {
    };
  }

-  async search(query: string, limit = 20): Promise<SearchResult> {
+  async search(query: string, limit = 20, offset = 0): Promise<SearchResult> {
    // Primary: u.y.qq.com/cgi-bin/musicu.fcg — supports songs + albums +
    // playlists. Fixed per https://github.com/ZHANGTIANYAO1/teamspeak-music-bot/issues/61
    // (removed searchid, num_per_page >= 10, corrected search_type values).
-    const primary = await this.searchViaMusicuFcg(query, limit);
+    const primary = await this.searchViaMusicuFcg(query, limit, offset);
    if (primary) return primary;

    // Fallback: c.y.qq.com/soso/fcgi-bin/client_search_cp (song + album,
    // no playlist support). Kept as redundancy.
-    return this.searchViaClientSearchCp(query, limit);
+    return this.searchViaClientSearchCp(query, limit, offset);
  }

  /** Primary search via u.y.qq.com/cgi-bin/musicu.fcg.
@@ -155,25 +169,31 @@ export class QQMusicProvider implements MusicProvider {
   *   3. `search_type: 2` for albums, `3` for playlists (8 was "user"). */
  private async searchViaMusicuFcg(
    query: string,
-    limit: number
+    limit: number,
+    offset = 0
  ): Promise<SearchResult | null> {
    try {
+      // num_per_page must stay >= 10 (lower values return empty). It is now
+      // limit-driven for ALL three lists (albums/playlists were hardcoded to
+      // 10). page_num is the offset cursor; the web always requests in
+      // limit-aligned pages so offset is a multiple of limit.
      const numPerPage = Math.max(10, Math.min(limit, 50));
+      const pageNum = Math.floor(offset / limit) + 1;
      const reqData = JSON.stringify({
        req_0: {
          module: "music.search.SearchCgiService",
          method: "DoSearchForQQMusicDesktop",
-          param: { query, num_per_page: numPerPage, search_type: 0 },
+          param: { query, num_per_page: numPerPage, page_num: pageNum, search_type: 0 },
        },
        req_album: {
          module: "music.search.SearchCgiService",
          method: "DoSearchForQQMusicDesktop",
-          param: { query, num_per_page: 10, search_type: 2 },
+          param: { query, num_per_page: numPerPage, page_num: pageNum, search_type: 2 },
        },
        req_playlist: {
          module: "music.search.SearchCgiService",
          method: "DoSearchForQQMusicDesktop",
-          param: { query, num_per_page: 10, search_type: 3 },
+          param: { query, num_per_page: numPerPage, page_num: pageNum, search_type: 3 },
        },
      });
      const res = await qqMusicuApi.get("/cgi-bin/musicu.fcg", {
@@ -207,12 +227,16 @@ export class QQMusicProvider implements MusicProvider {
  /** Fallback search via c.y.qq.com/soso/fcgi-bin/client_search_cp */
  private async searchViaClientSearchCp(
    query: string,
-    limit: number
+    limit: number,
+    offset = 0
  ): Promise<SearchResult> {
+    // `p` is the 1-based page cursor. The web pages in limit-aligned steps so
+    // offset is a multiple of limit.
+    const page = Math.floor(offset / limit) + 1;
    const songParams = {
      w: query,
      format: "json",
-      p: 1,
+      p: page,
      n: Math.min(limit, 50),
      type: 0,
      cr: 1,
@@ -220,7 +244,7 @@ export class QQMusicProvider implements MusicProvider {
    const albumParams = {
      w: query,
      format: "json",
-      p: 1,
+      p: page,
      n: 5,
      t: 8,
      cr: 1,
@@ -247,13 +271,13 @@ export class QQMusicProvider implements MusicProvider {
    return { songs, playlists: [], albums };
  }

-  async getSongUrl(songId: string, quality?: string): Promise<string | null> {
+  async getSongUrl(songId: string, quality?: string): Promise<SongUrlResult | null> {
    try {
      const res = await this.api.get("/getMusicPlay", {
        params: { songmid: songId, quality: quality ?? this.quality, ...this.cookieParams },
      });
      const playUrl = res.data?.data?.playUrl?.[songId];
-      if (playUrl?.url) return playUrl.url;
+      if (playUrl?.url) return { url: playUrl.url, trialDuration: parseQqTrial(playUrl) };
    } catch {
      // try with songid
      try {
@@ -261,7 +285,7 @@ export class QQMusicProvider implements MusicProvider {
          params: { songid: songId, quality: quality ?? this.quality, ...this.cookieParams },
        });
        const playUrl = res.data?.data?.playUrl?.[songId];
-        if (playUrl?.url) return playUrl.url;
+        if (playUrl?.url) return { url: playUrl.url, trialDuration: parseQqTrial(playUrl) };
      } catch {
        // ignore
      }
@@ -520,6 +544,7 @@ export class QQMusicProvider implements MusicProvider {
          ? `https://y.gtimg.cn/music/photo_new/T002R300x300M000${s.album.mid}.jpg`
          : "",
        platform: "qq",
+        vip: s.pay?.payplay === 1 || s.pay?.paytrackprice === 1 || false,
      }));
    } catch {
      return [];
@@ -7,6 +7,7 @@ import type {
  MusicProvider,
  Song,
  SongWithUrl,
+  SongUrlResult,
  Playlist,
  Album,
  SearchResult,
@@ -114,27 +115,33 @@ export class YouTubeProvider implements MusicProvider {
  readonly platform = "youtube" as const;
  private quality = "bestaudio";

-  async search(query: string, limit = 5): Promise<SearchResult> {
+  async search(query: string, limit = 5, offset = 0): Promise<SearchResult> {
    try {
+      // yt-dlp's `ytsearchN` has no offset cursor — it always returns the first
+      // N results. Best-effort paginate by fetching offset+limit and slicing
+      // locally. (offset 0 → identical to before.)
+      const total = offset + limit;
      const raw = await runYtDlp([
-        `ytsearch${limit}:${query}`,
+        `ytsearch${total}:${query}`,
        "--dump-json",
        "--flat-playlist",
        "--no-warnings",
        "--quiet",
      ]);
      const lines = raw.trim().split("\n").filter(Boolean);
-      const songs: Song[] = lines.map((line) => {
-        const entry = JSON.parse(line) as YtDlpEntry;
-        return entryToSong(entry);
-      });
+      const songs: Song[] = lines
+        .slice(offset, offset + limit)
+        .map((line) => {
+          const entry = JSON.parse(line) as YtDlpEntry;
+          return entryToSong(entry);
+        });
      return { songs, playlists: [], albums: [] };
    } catch {
      return { songs: [], playlists: [], albums: [] };
    }
  }

-  async getSongUrl(songId: string): Promise<string | null> {
+  async getSongUrl(songId: string): Promise<SongUrlResult | null> {
    try {
      const url = `https://www.youtube.com/watch?v=${songId}`;
      const raw = await runYtDlp([
@@ -146,7 +153,7 @@ export class YouTubeProvider implements MusicProvider {
        "--quiet",
      ], 45_000);
      const audioUrl = raw.trim().split("\n")[0];
-      return audioUrl || null;
+      return audioUrl ? { url: audioUrl } : null;
    } catch {
      return null;
    }
@@ -0,0 +1,85 @@
+import { describe, it, expect, vi } from "vitest";
+import pino from "pino";
+import { TS3Client } from "./client.js";
+
+/**
+ * Integration "smoke test" for the admin-command gate's group resolution.
+ *
+ * It drives the REAL TS3Client.getClientServerGroups → library getClientInfo
+ * path against a stubbed underlying client, so it exercises the actual
+ * `clientinfo clid=<id>` query string and the real `client_servergroups`
+ * parsing — the pieces that were previously only verified by reading the code.
+ *
+ * What this CANNOT cover (inherently server-side, needs a live TS server):
+ * whether a real server returns groups for a client in a DIFFERENT channel.
+ * The stub models the server-wide answer (groups returned regardless of
+ * channel); the failure modes below confirm we fail closed when it doesn't.
+ */
+function makeClient(): TS3Client {
+  return new TS3Client(
+    { host: "localhost", port: 9987, queryPort: 10011, nickname: "TestBot" },
+    pino({ level: "silent" }),
+  );
+}
+
+/** Inject a fake low-level client carrying a canned clientinfo response. */
+function withFakeClient(
+  ts: TS3Client,
+  respond: (cmd: string) => Record<string, string>[] | Promise<Record<string, string>[]>,
+): string[] {
+  const calls: string[] = [];
+  const fake = {
+    execCommandWithResponse: vi.fn(async (cmd: string) => {
+      calls.push(cmd);
+      return respond(cmd);
+    }),
+  };
+  (ts as unknown as { client: unknown }).client = fake;
+  return calls;
+}
+
+describe("TS3Client.getClientServerGroups — live query + parse smoke test", () => {
+  it("issues `clientinfo clid=<id>` and parses comma-separated client_servergroups", async () => {
+    const ts = makeClient();
+    const calls = withFakeClient(ts, () => [
+      { client_nickname: "Alice", cid: "99", client_servergroups: "6,8" },
+    ]);
+
+    const groups = await ts.getClientServerGroups(5);
+
+    expect(groups).toEqual(["6", "8"]);
+    // Exact query the bot sends to resolve a sender's groups, by client id.
+    expect(calls[0]).toBe("clientinfo clid=5");
+  });
+
+  it("parses a single-group response", async () => {
+    const ts = makeClient();
+    withFakeClient(ts, () => [{ client_servergroups: "6" }]);
+    expect(await ts.getClientServerGroups(5)).toEqual(["6"]);
+  });
+
+  it("returns [] when the client carries no server groups (empty field)", async () => {
+    const ts = makeClient();
+    withFakeClient(ts, () => [{ client_nickname: "Bob", client_servergroups: "" }]);
+    expect(await ts.getClientServerGroups(7)).toEqual([]);
+  });
+
+  it("returns [] when the server-groups field is absent", async () => {
+    const ts = makeClient();
+    withFakeClient(ts, () => [{ client_nickname: "Carol" }]);
+    expect(await ts.getClientServerGroups(7)).toEqual([]);
+  });
+
+  it("fails closed (returns []) when the query throws / client id is unknown", async () => {
+    const ts = makeClient();
+    withFakeClient(ts, () => {
+      throw new Error("invalid clientID");
+    });
+    expect(await ts.getClientServerGroups(999)).toEqual([]);
+  });
+
+  it("returns [] when not connected (no underlying client)", async () => {
+    const ts = makeClient();
+    expect(await ts.getClientServerGroups(5)).toEqual([]);
+  });
+});
@@ -8,6 +8,7 @@ import {
  listChannels,
  listClients,
  clientMove,
+  getClientInfo,
  fileTransferDeleteFile,
  type Identity,
  type TextMessage,
@@ -61,6 +62,24 @@ export interface TS3TextMessage {
  invokerUid: string;
  message: string;
  targetMode: number; // 1=private, 2=channel, 3=server
+  invokerGroups: string[]; // sender's TS server-group ids; [] when not in view cache
+}
+
+/**
+ * Map the library's TextMessage to our wrapper. Preserves invokerGroups (the
+ * sender's TS server groups), which the library populates only when the sender
+ * is in the bot's client-view cache; otherwise it is []. Used by the chat
+ * command permission gate.
+ */
+export function toTS3TextMessage(msg: TextMessage): TS3TextMessage {
+  return {
+    invokerName: msg.invokerName,
+    invokerId: String(msg.invokerID),
+    invokerUid: msg.invokerUID,
+    message: msg.message,
+    targetMode: msg.targetMode,
+    invokerGroups: msg.invokerGroups ?? [],
+  };
 }

 export class TS3Client extends EventEmitter {
@@ -203,14 +222,7 @@ export class TS3Client extends EventEmitter {
    });

    this.client.on("textMessage", (msg: TextMessage) => {
-      const tsMsg: TS3TextMessage = {
-        invokerName: msg.invokerName,
-        invokerId: String(msg.invokerID),
-        invokerUid: msg.invokerUID,
-        message: msg.message,
-        targetMode: msg.targetMode,
-      };
-      this.emit("textMessage", tsMsg);
+      this.emit("textMessage", toTS3TextMessage(msg));
    });

    this.client.on("disconnected", (err) => {
@@ -322,6 +334,26 @@ export class TS3Client extends EventEmitter {
    }
  }

+  /**
+   * Resolve a client's CURRENT server groups by client id, server-wide (works
+   * regardless of channel/view) via a targeted `clientinfo` query. The raw
+   * `client_servergroups` field is a comma-separated list (same field
+   * `listClients` parses). Returns [] if the client can't be resolved or the
+   * query fails, so callers fail closed.
+   */
+  async getClientServerGroups(clid: number): Promise<string[]> {
+    if (!this.client) return [];
+    try {
+      const info = await getClientInfo(this.client, clid);
+      // `client_servergroups`: comma-separated server-group ids (verified in
+      // @honeybbq/teamspeak-client dist/index.mjs; listClients parses the same).
+      const raw = info.client_servergroups ?? "";
+      return raw ? raw.split(",") : [];
+    } catch {
+      return [];
+    }
+  }
+
  // --- Raw command & file transfer pass-through ---

  async execCommand(cmd: string): Promise<void> {
@@ -0,0 +1,43 @@
+import { describe, it, expect } from "vitest";
+import { toTS3TextMessage } from "./client.js";
+import type { TextMessage } from "@honeybbq/teamspeak-client";
+
+function makeMsg(over: Partial<TextMessage> = {}): TextMessage {
+  return {
+    invokerName: "Alice",
+    invokerUID: "uid-abc",
+    message: "!stop",
+    invokerGroups: ["6", "8"],
+    targetMode: 2,
+    targetID: 0n,
+    invokerID: 5,
+    ...over,
+  };
+}
+
+describe("toTS3TextMessage", () => {
+  it("maps core fields and stringifies invokerID", () => {
+    const r = toTS3TextMessage(makeMsg());
+    expect(r.invokerName).toBe("Alice");
+    expect(r.invokerId).toBe("5");
+    expect(r.invokerUid).toBe("uid-abc");
+    expect(r.message).toBe("!stop");
+    expect(r.targetMode).toBe(2);
+  });
+
+  it("preserves the sender's server groups", () => {
+    expect(toTS3TextMessage(makeMsg({ invokerGroups: ["6"] })).invokerGroups).toEqual(["6"]);
+  });
+
+  it("defaults missing invokerGroups to an empty array", () => {
+    const partial = {
+      invokerName: "Bob",
+      invokerUID: "u",
+      message: "!stop",
+      targetMode: 1,
+      targetID: 0n,
+      invokerID: 7,
+    } as unknown as TextMessage;
+    expect(toTS3TextMessage(partial).invokerGroups).toEqual([]);
+  });
+});
@@ -11,7 +11,8 @@ export function createAuthRouter(
  qqProvider: MusicProvider,
  bilibiliProvider: MusicProvider,
  logger: Logger,
-  cookieStore?: CookieStore
+  cookieStore?: CookieStore,
+  kugouProvider?: MusicProvider
 ): Router {
  const router = Router();
  // YouTube is auth-less; we only use this instance so /auth/status can
@@ -21,6 +22,7 @@ export function createAuthRouter(
  function getProvider(platform?: string): MusicProvider {
    if (platform === "bilibili") return bilibiliProvider;
    if (platform === "youtube") return youtubeProvider;
+    if (platform === "kugou" && kugouProvider) return kugouProvider;
    return platform === "qq" ? qqProvider : neteaseProvider;
  }

@@ -65,6 +67,7 @@ export function createAuthRouter(
      if (status === "confirmed") {
        const cookie = provider.getCookie();
        const plat = (platform as string) === "bilibili" ? "bilibili" as const
+          : (platform as string) === "kugou" ? "kugou" as const
          : (platform as string) === "qq" ? "qq" as const : "netease" as const;
        if (cookie && cookieStore) {
          cookieStore.save(plat, cookie);
@@ -137,6 +140,7 @@ export function createAuthRouter(
    const provider = getProvider(platform);
    provider.setCookie(cookie);
    const plat = platform === "bilibili" ? "bilibili" as const
+      : platform === "kugou" ? "kugou" as const
      : platform === "qq" ? "qq" as const : "netease" as const;
    if (cookieStore) {
      cookieStore.save(plat, cookie);
@@ -158,6 +158,44 @@ describe("bot router /settings", () => {
      expect(bot.autoPauseCalls).toEqual([]);
    }
  });
+
+  it("GET /settings includes adminGroups reflecting config", async () => {
+    config.adminGroups = [6, 8];
+    const res = await request(app).get("/api/bot/settings").set("Cookie", cookie);
+    expect(res.status).toBe(200);
+    expect(res.body.adminGroups).toEqual([6, 8]);
+  });
+
+  it("POST /settings persists a validated adminGroups and GET returns it", async () => {
+    const res = await request(app)
+      .post("/api/bot/settings")
+      .set("Cookie", cookie)
+      .send({ adminGroups: [6, 8] });
+    expect(res.status).toBe(200);
+    expect(res.body.adminGroups).toEqual([6, 8]);
+    expect(config.adminGroups).toEqual([6, 8]);
+    const followUp = await request(app).get("/api/bot/settings").set("Cookie", cookie);
+    expect(followUp.body.adminGroups).toEqual([6, 8]);
+  });
+
+  it("POST /settings filters invalid adminGroups entries (negative, non-integer, non-number)", async () => {
+    const res = await request(app)
+      .post("/api/bot/settings")
+      .set("Cookie", cookie)
+      .send({ adminGroups: [6, -1, 2.5, "x", 8] });
+    expect(res.status).toBe(200);
+    expect(config.adminGroups).toEqual([6, 8]);
+  });
+
+  it("POST /settings ignores a non-array adminGroups (leaves config unchanged)", async () => {
+    config.adminGroups = [6];
+    const res = await request(app)
+      .post("/api/bot/settings")
+      .set("Cookie", cookie)
+      .send({ adminGroups: "6" });
+    expect(res.status).toBe(200);
+    expect(config.adminGroups).toEqual([6]);
+  });
 });

 describe("bot router /settings guest-mode gating + persistence", () => {
@@ -36,6 +36,8 @@ export function createBotRouter(
    res.json({
      idleTimeoutMinutes: config.idleTimeoutMinutes ?? 0,
      autoPauseOnEmpty: config.autoPauseOnEmpty,
+      localAudioEnabled: config.localAudioEnabled,
+      adminGroups: config.adminGroups ?? [],
      guestMode: config.guestMode,
    });
  });
@@ -43,7 +45,7 @@ export function createBotRouter(
  // POST /api/bot/settings — 保存全局 bot 行为设置 (gated: changing global bot
  // behavior is a bot.manage operation, consistent with PR #80's permission model)
  router.post("/settings", requirePermission("bot.manage"), (req, res) => {
-    const { idleTimeoutMinutes, autoPauseOnEmpty, guestMode } = req.body;
+    const { idleTimeoutMinutes, autoPauseOnEmpty, localAudioEnabled, guestMode, adminGroups } = req.body;

    const hasIdle = idleTimeoutMinutes !== undefined;
    if (hasIdle && (typeof idleTimeoutMinutes !== "number" || idleTimeoutMinutes < 0)) {
@@ -52,9 +54,11 @@ export function createBotRouter(
    }

    const hasAutoPause = typeof autoPauseOnEmpty === "boolean";
+    const hasLocalAudioEnabled = typeof localAudioEnabled === "boolean";

    if (hasIdle) config.idleTimeoutMinutes = idleTimeoutMinutes;
    if (hasAutoPause) config.autoPauseOnEmpty = autoPauseOnEmpty;
+    if (hasLocalAudioEnabled) config.localAudioEnabled = localAudioEnabled;

    const hasGuestMode = guestMode !== undefined && guestMode !== null && typeof guestMode === "object";
    if (hasGuestMode) {
@@ -74,6 +78,13 @@ export function createBotRouter(
      }
    }

+    if (Array.isArray(adminGroups)) {
+      config.adminGroups = adminGroups.filter(
+        (g: unknown): g is number =>
+          typeof g === "number" && Number.isInteger(g) && g >= 0,
+      );
+    }
+
    saveConfig(configPath, config);

    // Guest-mode changed: tear down / re-scope in-flight guest WS sockets so a
@@ -92,6 +103,8 @@ export function createBotRouter(
    res.json({
      idleTimeoutMinutes: config.idleTimeoutMinutes ?? 0,
      autoPauseOnEmpty: config.autoPauseOnEmpty,
+      localAudioEnabled: config.localAudioEnabled,
+      adminGroups: config.adminGroups ?? [],
      guestMode: config.guestMode,
    });
  });
@@ -0,0 +1,49 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import express from "express";
+import request from "supertest";
+import pino from "pino";
+import type { MusicProvider, SearchResult } from "../../music/provider.js";
+import { createMusicRouter } from "./music.js";
+
+function fakeProvider(platform: MusicProvider["platform"]): MusicProvider {
+  const empty: SearchResult = { songs: [], albums: [], playlists: [] };
+  return {
+    platform,
+    search: vi.fn().mockResolvedValue(empty),
+  } as unknown as MusicProvider;
+}
+
+describe("music router GET /search offset pagination", () => {
+  let app: express.Express;
+  let netease: MusicProvider;
+
+  beforeEach(() => {
+    netease = fakeProvider("netease");
+    const router = createMusicRouter(
+      netease,
+      fakeProvider("qq"),
+      fakeProvider("bilibili"),
+      pino({ level: "silent" })
+    );
+    app = express();
+    app.use("/api/music", router);
+  });
+
+  it("parses offset and passes it as the 3rd arg to provider.search", async () => {
+    const res = await request(app).get("/api/music/search?q=hello&limit=20&offset=20");
+    expect(res.status).toBe(200);
+    expect(netease.search).toHaveBeenCalledWith("hello", 20, 20);
+  });
+
+  it("defaults a missing offset to 0", async () => {
+    const res = await request(app).get("/api/music/search?q=hello&limit=20");
+    expect(res.status).toBe(200);
+    expect(netease.search).toHaveBeenCalledWith("hello", 20, 0);
+  });
+
+  it("clamps a negative offset to 0", async () => {
+    const res = await request(app).get("/api/music/search?q=hello&limit=20&offset=-5");
+    expect(res.status).toBe(200);
+    expect(netease.search).toHaveBeenCalledWith("hello", 20, 0);
+  });
+});
@@ -1,36 +1,106 @@
-import { Router } from "express";
+import express, { Router } from "express";
 import type { MusicProvider } from "../../music/provider.js";
 import { YouTubeProvider } from "../../music/youtube.js";
 import type { Logger } from "../../logger.js";
+import type { BotConfig } from "../../data/config.js";
 import { requirePermission } from "../middleware/requirePermission.js";
 import { requireNotGuest } from "../middleware/requireNotGuest.js";
+import { authorize } from "../middleware/authorize.js";

 export function createMusicRouter(
  neteaseProvider: MusicProvider,
  qqProvider: MusicProvider,
  bilibiliProvider: MusicProvider,
-  logger: Logger
+  logger: Logger,
+  localProvider?: MusicProvider,
+  config?: BotConfig,
+  kugouProvider?: MusicProvider
 ): Router {
  const router = Router();
  const youtubeProvider: MusicProvider = new YouTubeProvider();

+  function isLocalAudioEnabled(): boolean {
+    return config?.localAudioEnabled !== false;
+  }
+
  function getProvider(platform?: string): MusicProvider {
    if (platform === "bilibili") return bilibiliProvider;
    if (platform === "youtube") return youtubeProvider;
+    if (platform === "local" && localProvider) return localProvider;
+    if (platform === "kugou" && kugouProvider) return kugouProvider;
    return platform === "qq" ? qqProvider : neteaseProvider;
  }

+  router.post(
+    "/local/upload",
+    authorize({ capability: "player.queue", guestFlag: "addToQueue" }),
+    (_req, res, next) => {
+      if (!isLocalAudioEnabled()) {
+        res.status(403).json({ error: "本地音频播放已关闭" });
+        return;
+      }
+      next();
+    },
+    express.raw({
+      type: ["audio/*", "video/webm", "application/octet-stream"],
+      limit: "200mb",
+    }),
+    async (req, res) => {
+      try {
+        if (!localProvider) {
+          res.status(501).json({ error: "Local upload is not configured" });
+          return;
+        }
+        const uploadCapable = localProvider as MusicProvider & {
+          uploadAudio?: (input: { buffer: Buffer; originalName: string; mimeType?: string }) => Promise<unknown>;
+        };
+        if (typeof uploadCapable.uploadAudio !== "function") {
+          res.status(501).json({ error: "Local upload is not supported" });
+          return;
+        }
+        if (!Buffer.isBuffer(req.body)) {
+          res.status(400).json({ error: "raw audio body is required" });
+          return;
+        }
+        const headerName = req.header("x-filename") || req.header("x-file-name") || "audio";
+        let originalName = headerName;
+        try {
+          originalName = decodeURIComponent(headerName);
+        } catch {
+          // Keep the raw header value if it is not URI encoded.
+        }
+        const song = await uploadCapable.uploadAudio({
+          buffer: req.body,
+          originalName,
+          mimeType: req.header("content-type") || undefined,
+        });
+        res.json({ song });
+      } catch (err) {
+        logger.warn({ err }, "Local audio upload failed");
+        res.status(400).json({ error: (err as Error).message });
+      }
+    },
+  );
+
  router.get("/search", async (req, res) => {
    try {
-      const { q, platform, limit } = req.query;
+      const { q, platform, limit, offset } = req.query;
      if (!q) {
        res.status(400).json({ error: "q (query) is required" });
        return;
      }
+      if (platform === "local" && !isLocalAudioEnabled()) {
+        res.json({ songs: [], playlists: [], albums: [] });
+        return;
+      }
      const provider = getProvider(platform as string);
+      // Server-side pagination: offset lets the web load past the first page.
+      // Clamp to >= 0 so a bad/negative value falls back to the first page.
+      const parsedOffset = Math.max(0, parseInt(offset as string) || 0);
      const result = await provider.search(
        q as string,
-        parseInt(limit as string) || 20
+        parseInt(limit as string) || 20,
+        parsedOffset
      );
      res.json(result);
    } catch (err) {
@@ -47,16 +117,20 @@ export function createMusicRouter(
        return;
      }
      const parsedLimit = parseInt(limit as string) || 20;
-      const [neteaseResult, qqResult, bilibiliResult] = await Promise.allSettled([
+      const [neteaseResult, qqResult, bilibiliResult, localResult, kugouResult] = await Promise.allSettled([
        neteaseProvider.search(q as string, parsedLimit),
        qqProvider.search(q as string, parsedLimit),
        bilibiliProvider.search(q as string, parsedLimit),
+        localProvider && isLocalAudioEnabled() ? localProvider.search(q as string, parsedLimit) : Promise.resolve({ songs: [], albums: [], playlists: [] }),
+        kugouProvider ? kugouProvider.search(q as string, parsedLimit) : Promise.resolve({ songs: [], albums: [], playlists: [] }),
      ]);

      const songs = [
        ...(neteaseResult.status === "fulfilled" ? neteaseResult.value.songs : []),
        ...(qqResult.status === "fulfilled" ? qqResult.value.songs : []),
        ...(bilibiliResult.status === "fulfilled" ? bilibiliResult.value.songs : []),
+        ...(localResult.status === "fulfilled" ? localResult.value.songs : []),
+        ...(kugouResult.status === "fulfilled" ? kugouResult.value.songs : []),
      ];
      const albums = [
        ...(neteaseResult.status === "fulfilled" ? neteaseResult.value.albums : []),
@@ -76,6 +150,10 @@ export function createMusicRouter(

  router.get("/song/:id", async (req, res) => {
    try {
+      if (req.query.platform === "local" && !isLocalAudioEnabled()) {
+        res.status(403).json({ error: "本地音频播放已关闭" });
+        return;
+      }
      const provider = getProvider(req.query.platform as string);
      const song = await provider.getSongDetail(req.params.id);
      if (!song) {
@@ -215,6 +293,8 @@ export function createMusicRouter(
      netease: neteaseProvider.getQuality(),
      qq: qqProvider.getQuality(),
      bilibili: bilibiliProvider.getQuality(),
+      local: localProvider?.getQuality() ?? "original",
+      kugou: kugouProvider?.getQuality() ?? "128",
    });
  });

@@ -234,6 +314,9 @@ export function createMusicRouter(
    if (!platform || platform === "bilibili") {
      bilibiliProvider.setQuality(quality);
    }
+    if ((!platform || platform === "kugou") && kugouProvider) {
+      kugouProvider.setQuality(quality);
+    }
    logger.info({ quality, platform }, "Audio quality changed");
    res.json({ success: true, quality });
  });
@@ -301,6 +301,7 @@ const guest = (perms: Partial<Record<string, boolean>> = {}) => ({
    transport: false,
    removeClear: false,
    playMode: false,
+    playCollection: false,
    ...perms,
  },
 });
@@ -373,7 +374,19 @@ describe("guest enforcement on player routes", () => {
    expect((await request(mountGuest({ transport: true })).post(`/api/player/${ALLOWED_BOT}/add-song`).send({ song: SONG })).status).toBe(403);
  });

-  it("guests are always denied /play, /prev, /stop, /play-song, /play-at, /play-playlist, /play-album, /playlist, /profile even with ALL flags on", async () => {
+  it("playCollection flag gates /play-playlist, /play-album (issue #103)", async () => {
+    const allow = mountGuest({ playCollection: true });
+    const deny = mountGuest({ playCollection: false });
+    expect((await request(allow).post(`/api/player/${ALLOWED_BOT}/play-playlist`).send({ playlistId: "1" })).status).not.toBe(403);
+    expect((await request(allow).post(`/api/player/${ALLOWED_BOT}/play-album`).send({ albumId: "1" })).status).not.toBe(403);
+    expect((await request(deny).post(`/api/player/${ALLOWED_BOT}/play-playlist`).send({ playlistId: "1" })).status).toBe(403);
+    expect((await request(deny).post(`/api/player/${ALLOWED_BOT}/play-album`).send({ albumId: "1" })).status).toBe(403);
+    // playCollection does NOT leak into the destructive single-song / queue ops.
+    expect((await request(allow).post(`/api/player/${ALLOWED_BOT}/play`).send({ query: "x" })).status).toBe(403);
+    expect((await request(allow).post(`/api/player/${ALLOWED_BOT}/play-song`).send({ song: SONG })).status).toBe(403);
+  });
+
+  it("guests are always denied /play, /prev, /stop, /play-song, /play-at, /playlist, /profile even with ALL flags on", async () => {
    const all = mountGuest({
      addToQueue: true,
      playNext: true,
@@ -382,14 +395,13 @@ describe("guest enforcement on player routes", () => {
      transport: true,
      removeClear: true,
      playMode: true,
+      playCollection: true,
    });
    expect((await request(all).post(`/api/player/${ALLOWED_BOT}/play`).send({ query: "x" })).status).toBe(403);
    expect((await request(all).post(`/api/player/${ALLOWED_BOT}/prev`)).status).toBe(403);
    expect((await request(all).post(`/api/player/${ALLOWED_BOT}/stop`)).status).toBe(403);
    expect((await request(all).post(`/api/player/${ALLOWED_BOT}/play-song`).send({ song: SONG })).status).toBe(403);
    expect((await request(all).post(`/api/player/${ALLOWED_BOT}/play-at`).send({ index: 0 })).status).toBe(403);
-    expect((await request(all).post(`/api/player/${ALLOWED_BOT}/play-playlist`).send({ playlistId: "1" })).status).toBe(403);
-    expect((await request(all).post(`/api/player/${ALLOWED_BOT}/play-album`).send({ albumId: "1" })).status).toBe(403);
    expect((await request(all).post(`/api/player/${ALLOWED_BOT}/playlist`).send({ playlistId: "1" })).status).toBe(403);
    expect((await request(all).put(`/api/player/${ALLOWED_BOT}/profile`).send({})).status).toBe(403);
  });
@@ -39,9 +39,20 @@ export function createPlayerRouter(
    if (platform === "bilibili") return "-b";
    if (platform === "qq") return "-q";
    if (platform === "youtube") return "-y";
+    if (platform === "kugou") return "-k";
    return "";
  };

+  function isLocalAudioDisabled(bot: any, platform: unknown): boolean {
+    return platform === "local" &&
+      typeof bot.isLocalAudioEnabled === "function" &&
+      !bot.isLocalAudioEnabled();
+  }
+
+  function rejectDisabledLocalAudio(res: any): void {
+    res.status(403).json({ error: "本地音频播放已关闭" });
+  }
+
  router.post("/:botId/play", authorize({ capability: "player.control" }), async (req, res) => {
    try {
      const bot = (req as any).bot;
@@ -100,8 +111,12 @@ export function createPlayerRouter(
    try {
      const bot = (req as any).bot;
      const { platform } = req.body;
+      if (isLocalAudioDisabled(bot, platform)) {
+        rejectDisabledLocalAudio(res);
+        return;
+      }
      const provider = bot.getProviderFor(
-        platform === "bilibili" || platform === "qq" || platform === "youtube"
+        platform === "bilibili" || platform === "qq" || platform === "youtube" || platform === "local" || platform === "kugou"
          ? platform
          : "netease"
      );
@@ -265,14 +280,18 @@ export function createPlayerRouter(

  // Play a playlist by ID — stores metadata only, resolves URL for first song
  // Respects current play mode (random = pick random first song)
-  router.post("/:botId/play-playlist", authorize({ capability: "player.control" }), async (req, res) => {
+  router.post("/:botId/play-playlist", authorize({ capability: "player.control", guestFlag: "playCollection" }), async (req, res) => {
    try {
      const bot = (req as any).bot;
      const { playlistId, platform } = req.body;
+      if (isLocalAudioDisabled(bot, platform)) {
+        rejectDisabledLocalAudio(res);
+        return;
+      }
      // Use the bot's own provider lookup — it already knows about youtube,
      // which the router's constructor params did not.
      const provider = bot.getProviderFor(
-        platform === "bilibili" || platform === "qq" || platform === "youtube"
+        platform === "bilibili" || platform === "qq" || platform === "youtube" || platform === "local" || platform === "kugou"
          ? platform
          : "netease"
      );
@@ -315,6 +334,10 @@ export function createPlayerRouter(
      for (const song of queueable) {
        queue.add({ ...song, platform: provider.platform });
      }
+      // Sweep AFTER the queue is rebuilt: the previous queue's local uploads are
+      // released and deleted, but an empty/failed playlist (early return above)
+      // leaves the previous queue — and its files — intact.
+      bot.cleanupQueuedLocalSongs?.("queue_replaced");

      // Use queue.play() for sequential, or pick random index for random modes
      const mode = queue.getMode();
@@ -352,12 +375,16 @@ export function createPlayerRouter(
  });

  // Play an album by ID — mirrors play-playlist but calls getAlbumSongs
-  router.post("/:botId/play-album", authorize({ capability: "player.control" }), async (req, res) => {
+  router.post("/:botId/play-album", authorize({ capability: "player.control", guestFlag: "playCollection" }), async (req, res) => {
    try {
      const bot = (req as any).bot;
      const { albumId, platform } = req.body;
+      if (isLocalAudioDisabled(bot, platform)) {
+        rejectDisabledLocalAudio(res);
+        return;
+      }
      const provider = bot.getProviderFor(
-        platform === "bilibili" || platform === "qq" || platform === "youtube"
+        platform === "bilibili" || platform === "qq" || platform === "youtube" || platform === "local" || platform === "kugou"
          ? platform
          : "netease"
      );
@@ -393,6 +420,8 @@ export function createPlayerRouter(
      for (const song of queueable) {
        queue.add({ ...song, platform: provider.platform });
      }
+      // Sweep AFTER the queue is rebuilt (see play-playlist).
+      bot.cleanupQueuedLocalSongs?.("queue_replaced");

      const mode = queue.getMode();
      let first;
@@ -432,13 +461,21 @@ export function createPlayerRouter(
        res.status(400).json({ error: "song object with id and platform is required" });
        return;
      }
+      if (isLocalAudioDisabled(bot, song.platform)) {
+        rejectDisabledLocalAudio(res);
+        return;
+      }
      const queue = bot.getQueueManager();
+      bot.getPlayer().stop();
      queue.clear();
      queue.add(song);
      queue.play();

      bot.getPlayer().resetFailures();
      const ok = await bot.resolveAndPlay(queue.current()!);
+      // 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.
+      bot.cleanupQueuedLocalSongs?.("queue_replaced");
      if (!ok) {
        res.json({ ok: false, message: `无法播放「${song.name || song.id}」（区域/版权限制）` });
        return;
@@ -460,6 +497,10 @@ export function createPlayerRouter(
        res.status(400).json({ error: "song object with id and platform is required" });
        return;
      }
+      if (isLocalAudioDisabled(bot, song.platform)) {
+        rejectDisabledLocalAudio(res);
+        return;
+      }
      // Serialize the queue mutation + playback so concurrent requests can't
      // interleave (audible track must match queue.currentIndex).
      const body = await bot.runExclusive(async () => {
@@ -504,6 +545,10 @@ export function createPlayerRouter(
        res.status(400).json({ error: "song object with id and platform is required" });
        return;
      }
+      if (isLocalAudioDisabled(bot, song.platform)) {
+        rejectDisabledLocalAudio(res);
+        return;
+      }
      // Serialize the insert-after-current + promote + playback so concurrent
      // requests can't interleave (audible track must match queue.currentIndex).
      const body = await bot.runExclusive(async () => {
@@ -533,6 +578,10 @@ export function createPlayerRouter(
        res.status(400).json({ error: "song object with id and platform is required" });
        return;
      }
+      if (isLocalAudioDisabled(bot, song.platform)) {
+        rejectDisabledLocalAudio(res);
+        return;
+      }
      // Serialize the queue mutation + (possible) playback so concurrent
      // requests can't interleave (audible track must match queue.currentIndex).
      const body = await bot.runExclusive(async () => {
@@ -561,8 +610,12 @@ export function createPlayerRouter(
    try {
      const bot = (req as any).bot;
      const { songId, platform } = req.body;
+      if (isLocalAudioDisabled(bot, platform)) {
+        rejectDisabledLocalAudio(res);
+        return;
+      }
      const provider = bot.getProviderFor(
-        platform === "bilibili" || platform === "qq" || platform === "youtube"
+        platform === "bilibili" || platform === "qq" || platform === "youtube" || platform === "local" || platform === "kugou"
          ? platform
          : "netease"
      );
@@ -217,6 +217,7 @@ describe("session router — guest mode", () => {
        transport: false,
        removeClear: false,
        playMode: false,
+        playCollection: false,
      },
      guestBots: "all",
    });
@@ -36,6 +36,7 @@ describe("requireAuth middleware", () => {
          transport: true,
          removeClear: true,
          playMode: true,
+          playCollection: true,
        },
      }))
    );
@@ -100,7 +101,7 @@ describe("requireAuth middleware", () => {
  it("attaches guest permissions when guest mode is enabled", () => {
    const sessions: any = { validateAndTouch: () => ({ userId: "__guest__", username: "游客", role: "guest" }) };
    const permissions: any = { getCapabilities: () => [], getBotAccess: () => [] };
-    const perms = { addToQueue: true, playNext: false, playNow: false, skip: false, transport: false, removeClear: false, playMode: false };
+    const perms = { addToQueue: true, playNext: false, playNow: false, skip: false, transport: false, removeClear: false, playMode: false, playCollection: false };
    const getGuestConfig = () => ({ enabled: true, bots: ["bot1"], permissions: perms });
    const mw = createRequireAuth(sessions, permissions, getGuestConfig);
    const req: any = { headers: { cookie: "tsmb_session=x" }, secure: false };
@@ -38,6 +38,8 @@ export interface WebServerOptions {
  neteaseProvider: MusicProvider;
  qqProvider: MusicProvider;
  bilibiliProvider: MusicProvider;
+  localProvider: MusicProvider;
+  kugouProvider: MusicProvider;
  database: BotDatabase;
  config: BotConfig;
  configPath: string;
@@ -123,7 +125,7 @@ export function createWebServer(options: WebServerOptions): WebServer {
  );
  app.use(
    "/api/music",
-    createMusicRouter(options.neteaseProvider, options.qqProvider, options.bilibiliProvider, logger)
+    createMusicRouter(options.neteaseProvider, options.qqProvider, options.bilibiliProvider, logger, options.localProvider, options.config, options.kugouProvider)
  );
  app.use("/api/player", createPlayerRouter(
    options.botManager, logger, options.database,
@@ -131,7 +133,7 @@ export function createWebServer(options: WebServerOptions): WebServer {
  ));
  app.use(
    "/api/auth",
-    createAuthRouter(options.neteaseProvider, options.qqProvider, options.bilibiliProvider, logger, options.cookieStore)
+    createAuthRouter(options.neteaseProvider, options.qqProvider, options.bilibiliProvider, logger, options.cookieStore, options.kugouProvider)
  );
  app.use("/api/favorites", requireNotGuest, createFavoritesRouter(options.database, logger));

@@ -44,11 +44,15 @@
          type="range"
          min="0"
          max="100"
-          :value="mobileVolume"
+          :value="mobileVolumeDisplay"
          class="m-volume-slider"
-          @input="onMobileVolumeChange"
+          @input="onMobileVolumeInput"
+          @change="onMobileVolumeCommit"
+          @pointerup="onMobileVolumeRelease"
+          @pointercancel="onMobileVolumeRelease"
+          @blur="onMobileVolumeRelease"
        />
-        <span class="m-volume-value">{{ mobileVolume }}</span>
+        <span class="m-volume-value">{{ mobileVolumeDisplay }}</span>
      </div>
    </div>

@@ -79,6 +83,7 @@ import { computed, onMounted, onUnmounted, ref } from 'vue';
 import { useRoute, useRouter } from 'vue-router';
 import { Icon } from '@iconify/vue';
 import { usePlayerStore } from './stores/player.js';
+import { useDecoupledSlider } from './composables/useDecoupledSlider.js';
 import { useWebSocket } from './composables/useWebSocket.js';
 import { useSession } from './composables/useSession.js';
 import Navbar from './components/Navbar.vue';
@@ -99,7 +104,17 @@ const route = useRoute();
 const router = useRouter();
 const { connect } = useWebSocket();
 const currentSong = computed(() => playerStore.currentSong);
-const mobileVolume = computed(() => playerStore.activeBot?.volume ?? 75);
+// Volume slider decoupled from the 60fps updateMobileProgress() rAF re-render
+// so it isn't reset mid-drag (#111 — same root cause as the desktop player).
+const {
+  display: mobileVolumeDisplay,
+  onInput: onMobileVolumeInput,
+  onChange: onMobileVolumeCommit,
+  onRelease: onMobileVolumeRelease,
+} = useDecoupledSlider(
+  () => playerStore.activeBot?.volume,
+  (v) => playerStore.setVolume(v)
+);
 const mobileMode = computed(() => playerStore.activeBot?.playMode ?? 'seq');
 const mobileModeOrder = ['seq', 'loop', 'random', 'rloop'];
 const mobileModeIcons: Record<string, string> = {
@@ -118,17 +133,14 @@ let mobileRaf: number | null = null;

 function updateMobileProgress() {
  const duration = currentSong.value?.duration ?? 0;
+  // liveElapsed() recomputes each frame; the cached `elapsed` getter would
+  // leave the mobile bar frozen between server pushes (#107).
  mobileProgressPct.value = duration > 0
-    ? Math.min((playerStore.elapsed / duration) * 100, 100)
+    ? Math.min((playerStore.liveElapsed() / duration) * 100, 100)
    : 0;
  mobileRaf = requestAnimationFrame(updateMobileProgress);
 }

-function onMobileVolumeChange(e: Event) {
-  const volume = Number((e.target as HTMLInputElement).value);
-  playerStore.setVolume(volume);
-}
-
 function toggleMobileVolume() {
  mobileVolumeOpen.value = !mobileVolumeOpen.value;
  if (mobileVolumeOpen.value) mobileQueueOpen.value = false;
@@ -65,8 +65,12 @@
            type="range"
            min="0"
            max="100"
-            :value="activeBot?.volume ?? 75"
+            :value="volumeDisplay"
+            @input="onVolumeInput"
            @change="onVolumeChange"
+            @pointerup="onVolumeRelease"
+            @pointercancel="onVolumeRelease"
+            @blur="onVolumeRelease"
            class="volume-slider"
          />
        </template>
@@ -87,6 +91,7 @@ import { Icon } from '@iconify/vue';
 import { useRoute, useRouter } from 'vue-router';
 import { usePlayerStore } from '../stores/player.js';
 import { useSession } from '../composables/useSession.js';
+import { useDecoupledSlider } from '../composables/useDecoupledSlider.js';
 import CoverArt from './CoverArt.vue';
 import Queue from './Queue.vue';

@@ -135,8 +140,9 @@ function formatTime(seconds: number): string {
 }

 function updateProgress() {
-  // Use store.elapsed which interpolates from server ground truth
-  currentElapsed.value = store.elapsed;
+  // liveElapsed() (an action, not the cached `elapsed` getter) re-interpolates
+  // from the server anchor on every frame so the clock ticks each second (#107).
+  currentElapsed.value = store.liveElapsed();

  const duration = currentSong.value?.duration ?? 0;
  progressPercent.value = duration > 0
@@ -184,10 +190,17 @@ function togglePlay() {
  }
 }

-function onVolumeChange(e: Event) {
-  const target = e.target as HTMLInputElement;
-  store.setVolume(parseInt(target.value));
-}
+// Volume slider is decoupled from the per-frame rAF re-render so dragging the
+// thumb isn't reset every frame (#111). See useDecoupledSlider.
+const {
+  display: volumeDisplay,
+  onInput: onVolumeInput,
+  onChange: onVolumeChange,
+  onRelease: onVolumeRelease,
+} = useDecoupledSlider(
+  () => activeBot.value?.volume,
+  (v) => store.setVolume(v)
+);

 const modeOrder = ['seq', 'loop', 'random', 'rloop'] as const;
 const modeIcons: Record<string, string> = {
@@ -7,8 +7,8 @@
        <span class="song-name">{{ song.name }}</span>
        <span
          class="platform-badge"
-          :class="song.platform === 'bilibili' ? 'badge-bilibili' : song.platform === 'qq' ? 'badge-qq' : song.platform === 'youtube' ? 'badge-youtube' : 'badge-netease'"
-        >{{ song.platform === 'bilibili' ? 'B站' : song.platform === 'qq' ? 'QQ' : song.platform === 'youtube' ? 'YouTube' : '网易云' }}</span>
+          :class="song.platform === 'bilibili' ? 'badge-bilibili' : song.platform === 'qq' ? 'badge-qq' : song.platform === 'youtube' ? 'badge-youtube' : song.platform === 'local' ? 'badge-local' : song.platform === 'kugou' ? 'badge-kugou' : 'badge-netease'"
+        >{{ song.platform === 'bilibili' ? 'B站' : song.platform === 'qq' ? 'QQ' : song.platform === 'youtube' ? 'YouTube' : song.platform === 'local' ? '本地' : song.platform === 'kugou' ? '酷狗' : '网易云' }}</span>
      </div>
      <div class="song-artist">{{ song.artist }}</div>
    </div>
@@ -135,6 +135,16 @@ function formatDuration(seconds: number): string {
  color: var(--brand-youtube);
 }

+.badge-local {
+  background: var(--color-primary-10);
+  color: var(--color-primary);
+}
+
+.badge-kugou {
+  background: var(--brand-kugou-12);
+  color: var(--brand-kugou);
+}
+
 .song-artist {
  font-size: 12px;
  color: var(--text-secondary);
@@ -24,6 +24,7 @@ import type { Source } from '../stores/player.js';
 const LABELS: Record<Source, string> = {
  netease: '网易云',
  qq: 'QQ',
+  kugou: '酷狗',
 };

 defineProps<{
@@ -0,0 +1,84 @@
+import { describe, it, expect, vi } from "vitest";
+import { ref, nextTick } from "vue";
+import { useDecoupledSlider } from "./useDecoupledSlider.js";
+
+/** Minimal stand-in for an <input type="range"> change/input Event. */
+function ev(value: number): Event {
+  return { target: { value: String(value) } } as unknown as Event;
+}
+
+describe("useDecoupledSlider (#111)", () => {
+  it("initialises display from the source, falling back when undefined", () => {
+    const src = ref<number | undefined>(40);
+    const { display } = useDecoupledSlider(() => src.value, () => {});
+    expect(display.value).toBe(40);
+
+    const empty = useDecoupledSlider(() => undefined, () => {}, 75);
+    expect(empty.display.value).toBe(75);
+  });
+
+  it("reflects external source changes into the display when not dragging", async () => {
+    const src = ref<number | undefined>(50);
+    const { display } = useDecoupledSlider(() => src.value, () => {});
+    src.value = 80;
+    await nextTick();
+    expect(display.value).toBe(80);
+  });
+
+  it("tracks @input locally without committing", () => {
+    const commit = vi.fn();
+    const { display, onInput } = useDecoupledSlider(() => 50, commit);
+    onInput(ev(63));
+    expect(display.value).toBe(63);
+    expect(commit).not.toHaveBeenCalled();
+  });
+
+  // THE REGRESSION: this is exactly what the 60fps rAF re-render did — push the
+  // (stale) source value back into the binding mid-drag. The guard must ignore
+  // it so the thumb stays where the user dragged it.
+  it("ignores external source changes WHILE dragging (no snap-back)", async () => {
+    const src = ref<number | undefined>(50);
+    const { display, onInput } = useDecoupledSlider(() => src.value, () => {});
+
+    onInput(ev(70)); // user starts dragging → display 70
+    expect(display.value).toBe(70);
+
+    // Simulate the per-frame re-render re-evaluating the (still-stale) source.
+    src.value = 50;
+    await nextTick();
+    expect(display.value).toBe(70); // stayed put — did NOT snap back to 50
+  });
+
+  // Corner case: a range input skips `change` when released back at its start
+  // value. onRelease (pointerup/pointercancel/blur) must still end the drag so
+  // the slider doesn't freeze against later external updates.
+  it("clears dragging on release even when @change never fires", async () => {
+    const src = ref<number | undefined>(50);
+    const { display, onInput, onRelease } = useDecoupledSlider(() => src.value, () => {});
+
+    onInput(ev(70)); // drag begins
+    onInput(ev(50)); // ...dragged back to the start value
+    onRelease();     // released — browser emits NO change event here
+
+    src.value = 30; // a later external update
+    await nextTick();
+    expect(display.value).toBe(30); // slider resumed following the source
+  });
+
+  it("commits on @change and resumes following the source afterwards", async () => {
+    const commit = vi.fn();
+    const src = ref<number | undefined>(50);
+    const { display, onInput, onChange } = useDecoupledSlider(() => src.value, commit);
+
+    onInput(ev(70));
+    onChange(ev(70)); // release
+    expect(commit).toHaveBeenCalledTimes(1);
+    expect(commit).toHaveBeenCalledWith(70);
+    expect(display.value).toBe(70);
+
+    // After release, external changes flow through again.
+    src.value = 35;
+    await nextTick();
+    expect(display.value).toBe(35);
+  });
+});
@@ -0,0 +1,67 @@
+import { ref, watch, type Ref } from 'vue';
+
+/**
+ * A slider whose displayed value is decoupled from its reactive source.
+ *
+ * Why this exists (#111): the player components run a 60fps requestAnimationFrame
+ * loop (progress clock, #107) that re-renders the whole component every ~16ms.
+ * Binding a range `<input :value>` straight to a reactive source (the store
+ * volume) let Vue re-apply `el.value = source` on every one of those re-renders.
+ * Mid-drag the source is still the *old* value, so the native drag position kept
+ * getting snapped back — the thumb was effectively un-draggable on desktop and
+ * janky on mobile.
+ *
+ * The fix is to bind `:value` to a LOCAL ref that:
+ *  - tracks the native drag synchronously via `@input` (so the bound value always
+ *    equals the element's value → Vue never resets it), and
+ *  - is committed to the real source only on `@change` (release).
+ * External source changes (bot switch, another client) still flow into the
+ * display — except while the user is actively dragging, where they must be
+ * ignored or they'd fight the drag.
+ *
+ * @param source  getter for the authoritative value (e.g. () => bot?.volume)
+ * @param commit  called with the final value on release (e.g. store.setVolume)
+ * @param fallback value to show when the source is undefined (default 75)
+ */
+export function useDecoupledSlider(
+  source: () => number | undefined,
+  commit: (value: number) => void,
+  fallback = 75
+): {
+  display: Ref<number>;
+  dragging: Ref<boolean>;
+  onInput: (e: Event) => void;
+  onChange: (e: Event) => void;
+  onRelease: () => void;
+} {
+  const display = ref<number>(source() ?? fallback);
+  const dragging = ref(false);
+
+  watch(source, (v) => {
+    // Reflect external/store changes — but never while dragging, or the
+    // per-frame re-render would yank the thumb away from the user's finger.
+    if (!dragging.value && typeof v === 'number') display.value = v;
+  });
+
+  function onInput(e: Event): void {
+    dragging.value = true;
+    display.value = Number((e.target as HTMLInputElement).value);
+  }
+
+  function onChange(e: Event): void {
+    dragging.value = false;
+    const v = Number((e.target as HTMLInputElement).value);
+    display.value = v;
+    commit(v);
+  }
+
+  function onRelease(): void {
+    // Safety net for pointerup / pointercancel / blur: a range input does NOT
+    // emit `change` if the value is released back at its starting point, which
+    // would otherwise leave `dragging` stuck true and freeze the slider against
+    // later external updates. Clearing here is idempotent with onChange.
+    dragging.value = false;
+  }
+
+  return { display, dragging, onInput, onChange, onRelease };
+}
@@ -0,0 +1,44 @@
+import { describe, it, expect, vi, afterEach } from "vitest";
+import { interpolateElapsed, type TimingState } from "./player.js";
+
+afterEach(() => {
+  vi.restoreAllMocks();
+});
+
+function timing(partial: Partial<TimingState>): TimingState {
+  return { serverElapsed: 0, serverSyncTime: 0, wasPlaying: false, ...partial };
+}
+
+describe("interpolateElapsed", () => {
+  it("returns serverElapsed before playback has a sync anchor", () => {
+    expect(interpolateElapsed(timing({ serverElapsed: 12, wasPlaying: false }), false, Infinity)).toBe(12);
+    // wasPlaying but no sync time yet
+    expect(interpolateElapsed(timing({ serverElapsed: 5, wasPlaying: true, serverSyncTime: 0 }), false, Infinity)).toBe(5);
+  });
+
+  it("advances with wall-clock time while playing (regression: must not be frozen)", () => {
+    const spy = vi.spyOn(Date, "now");
+    const t = timing({ serverElapsed: 30, serverSyncTime: 10_000, wasPlaying: true });
+
+    spy.mockReturnValue(10_000);
+    expect(interpolateElapsed(t, false, Infinity)).toBeCloseTo(30, 5);
+
+    spy.mockReturnValue(11_000); // +1s
+    expect(interpolateElapsed(t, false, Infinity)).toBeCloseTo(31, 5);
+
+    spy.mockReturnValue(13_500); // +3.5s — distinct from the 1s reading
+    expect(interpolateElapsed(t, false, Infinity)).toBeCloseTo(33.5, 5);
+  });
+
+  it("freezes at serverElapsed while paused", () => {
+    vi.spyOn(Date, "now").mockReturnValue(99_000);
+    const t = timing({ serverElapsed: 42, serverSyncTime: 10_000, wasPlaying: true });
+    expect(interpolateElapsed(t, true, Infinity)).toBe(42);
+  });
+
+  it("clamps to maxDuration", () => {
+    vi.spyOn(Date, "now").mockReturnValue(1_000_000);
+    const t = timing({ serverElapsed: 100, serverSyncTime: 1_000, wasPlaying: true });
+    expect(interpolateElapsed(t, false, 180)).toBe(180);
+  });
+});
@@ -10,10 +10,10 @@ export interface Song {
  album: string;
  duration: number;
  coverUrl: string;
-  platform: 'netease' | 'qq' | 'bilibili' | 'youtube';
+  platform: 'netease' | 'qq' | 'bilibili' | 'youtube' | 'local' | 'kugou';
 }

-export type Source = 'netease' | 'qq';
+export type Source = 'netease' | 'qq' | 'kugou';

 export interface BotStatus {
  id: string;
@@ -47,7 +47,7 @@ export interface FavoritePlaylist {
  createdAt: string;
 }

-interface TimingState {
+export interface TimingState {
  serverElapsed: number;
  serverSyncTime: number;
  wasPlaying: boolean;
@@ -59,6 +59,33 @@ function defaultTiming(): TimingState {
  return { serverElapsed: 0, serverSyncTime: 0, wasPlaying: false };
 }

+/**
+ * Interpolate the live elapsed seconds from the last server anchor.
+ *
+ * This is a PURE function (its only time source is `Date.now()`), deliberately
+ * kept OUT of the Pinia getter so it can be called fresh every animation frame.
+ * The `elapsed` getter is a Vue `computed` and caches its result until a
+ * REACTIVE dependency changes — but `Date.now()` is not reactive, so a getter
+ * only re-runs on a WebSocket push / server poll (every few seconds). Reading
+ * the getter from a requestAnimationFrame loop therefore returns a frozen value
+ * and the clock appears to jump ~3s at a time (issue #107). Per-frame consumers
+ * must call this helper (via the `liveElapsed` action) instead.
+ */
+export function interpolateElapsed(
+  timing: TimingState,
+  isPaused: boolean,
+  maxDuration: number,
+): number {
+  // No live anchor yet, or paused: report the frozen server position.
+  if (!timing.wasPlaying || timing.serverSyncTime === 0 || isPaused) {
+    return Math.min(timing.serverElapsed, maxDuration);
+  }
+  return Math.min(
+    timing.serverElapsed + (Date.now() - timing.serverSyncTime) / 1000,
+    maxDuration,
+  );
+}
+
 export const usePlayerStore = defineStore('player', {
  state: () => ({
    bots: [] as BotStatus[],
@@ -73,11 +100,11 @@ export const usePlayerStore = defineStore('player', {
    theme: 'dark' as 'dark' | 'light',

    // Home page cache, split by source
-    recommendPlaylists: { netease: [] as PlaylistItem[], qq: [] as PlaylistItem[] },
-    dailySongs:         { netease: [] as Song[],         qq: [] as Song[] },
-    userPlaylists:      { netease: [] as PlaylistItem[], qq: [] as PlaylistItem[] },
+    recommendPlaylists: { netease: [] as PlaylistItem[], qq: [] as PlaylistItem[], kugou: [] as PlaylistItem[] },
+    dailySongs:         { netease: [] as Song[],         qq: [] as Song[],         kugou: [] as Song[] },
+    userPlaylists:      { netease: [] as PlaylistItem[], qq: [] as PlaylistItem[], kugou: [] as PlaylistItem[] },
    bilibiliPopular: [] as Song[],
-    authStatus: { netease: false, qq: false },
+    authStatus: { netease: false, qq: false, kugou: false },
    lastFetchTime: 0,

    // Favorited playlists (fetched from server, isolated per WebUI user)
@@ -111,26 +138,46 @@ export const usePlayerStore = defineStore('player', {
      if (!botId) return [];
      return this.queues[botId] ?? [];
    },
-    /** Interpolated elapsed for the active bot */
+    /**
+     * Interpolated elapsed for the active bot. NOTE: as a Pinia getter this is
+     * a Vue `computed` and is CACHED — it only re-runs when a reactive
+     * dependency changes, so it does NOT tick every second on its own. Use it
+     * for one-off reactive reads; per-frame consumers (progress bar, lyrics)
+     * must call the `liveElapsed` action so the clock advances smoothly (#107).
+     */
    elapsed(): number {
      const botId = this.activeBotId ?? this.bots[0]?.id;
      if (!botId || !this.activeBot?.currentSong) return 0;
      const timing = this.timings[botId] ?? defaultTiming();
      const maxDuration = this.activeBot.currentSong.duration || Infinity;
-      if (!timing.wasPlaying || timing.serverSyncTime === 0) return Math.min(timing.serverElapsed, maxDuration);
-      if (this.isPaused) return Math.min(timing.serverElapsed, maxDuration);
-      return Math.min(timing.serverElapsed + (Date.now() - timing.serverSyncTime) / 1000, maxDuration);
+      return interpolateElapsed(timing, this.isPaused, maxDuration);
    },
    /** Sources that are currently logged in. Order: netease before qq. */
    availableSources(): Source[] {
      const s: Source[] = [];
      if (this.authStatus.netease) s.push('netease');
      if (this.authStatus.qq) s.push('qq');
+      if (this.authStatus.kugou) s.push('kugou');
      return s;
    },
  },

  actions: {
+    /**
+     * Live elapsed seconds for the active bot, recomputed on every call. Unlike
+     * the `elapsed` getter (a cached computed), this is an action, so it is NOT
+     * memoised — call it from requestAnimationFrame / interval loops so the
+     * progress bar and lyrics advance every frame instead of jumping on each
+     * server push (#107).
+     */
+    liveElapsed(): number {
+      const botId = this.activeBotId ?? this.bots[0]?.id;
+      if (!botId || !this.activeBot?.currentSong) return 0;
+      const timing = this.timings[botId] ?? defaultTiming();
+      const maxDuration = this.activeBot.currentSong.duration || Infinity;
+      return interpolateElapsed(timing, this.isPaused, maxDuration);
+    },
+
    _getTiming(botId: string): TimingState {
      if (!this.timings[botId]) {
        this.timings[botId] = defaultTiming();
@@ -373,29 +420,40 @@ export const usePlayerStore = defineStore('player', {

    async playPlaylist(playlistId: string, platform = 'netease') {
      if (!this.activeBotId) return;
-      const res = await axios.post(`/api/player/${this.activeBotId}/play-playlist`, { playlistId, platform });
-      if (res.data?.message) {
-        this.notify(res.data.message, res.data.ok === false ? 'error' : 'info');
+      try {
+        const res = await axios.post(`/api/player/${this.activeBotId}/play-playlist`, { playlistId, platform });
+        if (res.data?.message) {
+          this.notify(res.data.message, res.data.ok === false ? 'error' : 'info');
+        }
+        this._setTiming(this.activeBotId, { serverElapsed: 0 });
+        this._syncAfterAction();
+      } catch (e: any) {
+        // A 403 here means a guest lacks the "play entire collection" permission
+        // (issue #103) — surface it instead of failing silently.
+        this.notify(e?.response?.status === 403 ? '没有权限播放整个歌单' : '播放歌单失败', 'error');
      }
-      this._setTiming(this.activeBotId, { serverElapsed: 0 });
-      this._syncAfterAction();
    },

    async playAlbum(albumId: string, platform = 'netease') {
      if (!this.activeBotId) return;
-      const res = await axios.post(`/api/player/${this.activeBotId}/play-album`, { albumId, platform });
-      if (res.data?.message) {
-        this.notify(res.data.message, res.data.ok === false ? 'error' : 'info');
+      try {
+        const res = await axios.post(`/api/player/${this.activeBotId}/play-album`, { albumId, platform });
+        if (res.data?.message) {
+          this.notify(res.data.message, res.data.ok === false ? 'error' : 'info');
+        }
+        this._setTiming(this.activeBotId, { serverElapsed: 0 });
+        this._syncAfterAction();
+      } catch (e: any) {
+        this.notify(e?.response?.status === 403 ? '没有权限播放整个专辑' : '播放专辑失败', 'error');
      }
-      this._setTiming(this.activeBotId, { serverElapsed: 0 });
-      this._syncAfterAction();
    },

    async pause() {
      if (!this.activeBotId) return;
-      // Freeze elapsed at current interpolated value
+      // Freeze elapsed at the current LIVE interpolated value. Using the cached
+      // `elapsed` getter here could snapshot a value up to a few seconds stale.
      this._setTiming(this.activeBotId, {
-        serverElapsed: this.elapsed,
+        serverElapsed: this.liveElapsed(),
        wasPlaying: false,
      });
      await axios.post(`/api/player/${this.activeBotId}/pause`);
@@ -514,18 +572,23 @@ export const usePlayerStore = defineStore('player', {
      // Always check auth status first — if it changed since the cached
      // fetch (e.g., user logged in/out as a different account), the
      // cached playlists belong to a different user and we MUST refetch.
-      const [neAuthRes, qqAuthRes] = await Promise.allSettled([
+      const [neAuthRes, qqAuthRes, kugouAuthRes] = await Promise.allSettled([
        axios.get('/api/auth/status', { params: { platform: 'netease' } }),
        axios.get('/api/auth/status', { params: { platform: 'qq' } }),
+        axios.get('/api/auth/status', { params: { platform: 'kugou' } }),
      ]);
      const newAuth = {
        netease: neAuthRes.status === 'fulfilled' && !!neAuthRes.value.data?.loggedIn,
        qq:      qqAuthRes.status === 'fulfilled' && !!qqAuthRes.value.data?.loggedIn,
+        kugou:   kugouAuthRes.status === 'fulfilled' && !!kugouAuthRes.value.data?.loggedIn,
      };
      const authChanged =
-        newAuth.netease !== this.authStatus.netease || newAuth.qq !== this.authStatus.qq;
+        newAuth.netease !== this.authStatus.netease ||
+        newAuth.qq !== this.authStatus.qq ||
+        newAuth.kugou !== this.authStatus.kugou;
      this.authStatus.netease = newAuth.netease;
      this.authStatus.qq = newAuth.qq;
+      this.authStatus.kugou = newAuth.kugou;

      // Favorites are user-local and cheap; always refresh them, even on a
      // home-data cache hit, so hearts stay correct across tabs/sessions.
@@ -564,15 +627,30 @@ export const usePlayerStore = defineStore('player', {
            Promise.resolve(emptyPlaylists),
          ];

+      // 4. Kugou data: every section (incl. recommend playlists) needs login,
+      // so gate all three on auth like QQ.
+      const kugouPromises = this.authStatus.kugou
+        ? [
+            axios.get('/api/music/recommend/playlists', { params: { platform: 'kugou' } }),
+            axios.get('/api/music/recommend/songs',     { params: { platform: 'kugou' } }),
+            axios.get('/api/music/user/playlists',      { params: { platform: 'kugou' } }),
+          ]
+        : [
+            Promise.resolve(emptyPlaylists),
+            Promise.resolve(emptySongs),
+            Promise.resolve(emptyPlaylists),
+          ];
+
      const biliPromise = axios.get('/api/music/bilibili/popular?limit=12');

      const results = await Promise.allSettled([
        ...neteasePromises,
        ...qqPromises,
+        ...kugouPromises,
        biliPromise,
      ]);

-      const [neRecPL, neDaily, neUserPL, qqRecPL, qqDaily, qqUserPL, bili] = results;
+      const [neRecPL, neDaily, neUserPL, qqRecPL, qqDaily, qqUserPL, kgRecPL, kgDaily, kgUserPL, bili] = results;

      this.recommendPlaylists.netease =
        neRecPL.status === 'fulfilled' ? (neRecPL.value.data.playlists ?? []) : [];
@@ -586,6 +664,12 @@ export const usePlayerStore = defineStore('player', {
        qqDaily.status === 'fulfilled' ? (qqDaily.value.data.songs ?? []) : [];
      this.userPlaylists.qq =
        qqUserPL.status === 'fulfilled' ? (qqUserPL.value.data.playlists ?? []) : [];
+      this.recommendPlaylists.kugou =
+        kgRecPL.status === 'fulfilled' ? (kgRecPL.value.data.playlists ?? []) : [];
+      this.dailySongs.kugou =
+        kgDaily.status === 'fulfilled' ? (kgDaily.value.data.songs ?? []) : [];
+      this.userPlaylists.kugou =
+        kgUserPL.status === 'fulfilled' ? (kgUserPL.value.data.playlists ?? []) : [];
      // bilibili popular: keep previous value on failure (it's an anonymous endpoint
      // unrelated to user auth state, and stale popular results are harmless)
      if (bili.status === 'fulfilled') {
@@ -597,7 +681,9 @@ export const usePlayerStore = defineStore('player', {
      // cached for 5 minutes, otherwise the user has to hard-reload to
      // recover when connectivity returns.
      const authOk =
-        neAuthRes.status === 'fulfilled' || qqAuthRes.status === 'fulfilled';
+        neAuthRes.status === 'fulfilled' ||
+        qqAuthRes.status === 'fulfilled' ||
+        kugouAuthRes.status === 'fulfilled';
      if (authOk) {
        this.lastFetchTime = Date.now();
      }
@@ -28,7 +28,7 @@ function readAll(): Partial<Record<TabKey, Source>> {
 export function loadTabSource(key: TabKey, fallback: Source = 'netease'): Source {
  const all = readAll();
  const v = all[key];
-  return v === 'netease' || v === 'qq' ? v : fallback;
+  return v === 'netease' || v === 'qq' || v === 'kugou' ? v : fallback;
 }

 export function saveTabSource(key: TabKey, value: Source): void {
@@ -80,6 +80,8 @@
  --brand-bilibili-15: rgba(0, 161, 214, 0.15);
  --brand-youtube: #ff0000;
  --brand-youtube-12: rgba(255, 0, 0, 0.12);
+  --brand-kugou: #2ca2f9;
+  --brand-kugou-12: rgba(44, 162, 249, 0.12);
 }

 // Dark theme (default)
@@ -41,13 +41,23 @@
        </div>
        <Icon icon="mdi:play-circle" class="fm-play-icon" />
      </div>
+      <div v-if="store.authStatus.kugou" class="fm-card hover-scale" @click="playFm('kugou')">
+        <div class="fm-icon-wrapper kugou">
+          <Icon icon="mdi:radio-tower" class="fm-icon" />
+        </div>
+        <div class="fm-info">
+          <div class="fm-title">酷狗私人电台</div>
+          <div class="fm-desc">个性化推荐歌曲流</div>
+        </div>
+        <Icon icon="mdi:play-circle" class="fm-play-icon" />
+      </div>
    </section>

    <!-- 每日推荐 -->
    <section class="section" v-if="dailyAvailable.length > 0">
      <h2 class="section-title">
        每日推荐
-        <SourceTabs v-model="dailySource" :sources="dailyAvailable" />
+        <SourceTabs :model-value="dailySourceSafe" @update:model-value="dailySource = $event" :sources="dailyAvailable" />
      </h2>
      <div class="daily-grid">
        <div
@@ -67,7 +77,7 @@
    <section class="section" v-if="recommendAvailable.length > 0">
      <h2 class="section-title">
        推荐歌单
-        <SourceTabs v-model="recommendSource" :sources="recommendAvailable" />
+        <SourceTabs :model-value="recommendSourceSafe" @update:model-value="recommendSource = $event" :sources="recommendAvailable" />
      </h2>
      <div class="playlist-grid">
        <RouterLink
@@ -108,7 +118,7 @@
      <h2 class="section-title">
        我的歌单
        <span v-if="currentUserPlaylists.length > 0" class="section-count">{{ currentUserPlaylists.length }}</span>
-        <SourceTabs v-model="userSource" :sources="userAvailable" />
+        <SourceTabs :model-value="userSourceSafe" @update:model-value="userSource = $event" :sources="userAvailable" />
      </h2>
      <div class="playlist-grid">
        <RouterLink
@@ -173,6 +183,7 @@ const userPlaylistsExpanded = ref(false);
 const recommendAvailable = computed<Source[]>(() => {
  const s: Source[] = ['netease'];
  if (store.authStatus.qq) s.push('qq');
+  if (store.authStatus.kugou) s.push('kugou');
  return s;
 });
 const dailyAvailable = computed<Source[]>(() => store.availableSources);
@@ -358,6 +369,10 @@ onMounted(() => {
  &.qq {
    background: linear-gradient(135deg, var(--brand-qq), #17a2b8);
  }
+
+  &.kugou {
+    background: linear-gradient(135deg, var(--brand-kugou), #1d7fd1);
+  }
 }

 .fm-icon {
@@ -28,7 +28,7 @@
      <h2 class="section-title">
        我的歌单
        <span v-if="currentUserPlaylists.length > 0" class="section-count">{{ currentUserPlaylists.length }}</span>
-        <SourceTabs v-model="userSource" :sources="userAvailable" />
+        <SourceTabs :model-value="userSourceSafe" @update:model-value="userSource = $event" :sources="userAvailable" />
      </h2>
      <div class="playlist-grid">
        <RouterLink
@@ -136,7 +136,9 @@ function scrollToActiveLine(idx: number) {

 function syncLyrics() {
  if (!store.isPlaying || lines.value.length === 0) return;
-  const elapsed = store.elapsed;
+  // liveElapsed() (action) is recomputed now; the cached `elapsed` getter only
+  // refreshed on server pushes, leaving highlights ~half a line behind (#107).
+  const elapsed = store.liveElapsed();
  const idx = findActiveLine(elapsed);
  // Only update when the active line actually changes
  if (idx !== activeLine.value && idx >= 0) {
@@ -17,7 +17,7 @@
            {{ songs.length }} 首歌曲
          </div>
          <div class="playlist-actions">
-            <button class="play-all-btn" @click="playAll">
+            <button v-if="canPlayAll" class="play-all-btn" @click="playAll">
              <Icon icon="mdi:play" />
              播放全部
            </button>
@@ -54,16 +54,22 @@
 </template>

 <script setup lang="ts">
-import { ref, onMounted } from 'vue';
+import { ref, computed, onMounted } from 'vue';
 import { useRoute } from 'vue-router';
 import { Icon } from '@iconify/vue';
 import axios from 'axios';
 import { usePlayerStore } from '../stores/player.js';
+import { useSession } from '../composables/useSession.js';
 import CoverArt from '../components/CoverArt.vue';
 import SongCard from '../components/SongCard.vue';

 const store = usePlayerStore();
 const route = useRoute();
+const { can, guestCan } = useSession();
+
+// "Play all" loads + plays the whole collection (clears the queue). Members
+// need player.control; guests need the playCollection flag (issue #103).
+const canPlayAll = computed(() => can('player.control') || guestCan('playCollection'));

 import { Song } from '../stores/player.js';

@@ -16,6 +16,41 @@
          autofocus
        />
      </div>
+
+      <div
+        v-if="localAudioEnabled"
+        class="local-upload"
+        :class="{ dragging: isDragging, uploading }"
+        @dragenter.prevent="isDragging = true"
+        @dragover.prevent="isDragging = true"
+        @dragleave.prevent="isDragging = false"
+        @drop.prevent="handleDrop"
+      >
+        <Icon icon="mdi:tray-arrow-up" class="upload-icon" />
+        <div class="upload-copy">
+          <div class="upload-title">拖拽本地音频到这里上传</div>
+          <div class="upload-subtitle">支持 mp3、flac、wav、m4a、ogg、opus、aac、webm 等格式，上传后可直接播放或加入队列</div>
+        </div>
+        <button class="upload-btn" :disabled="uploading" @click="fileInput?.click()">
+          {{ uploading ? '上传中...' : '选择音频' }}
+        </button>
+        <input
+          ref="fileInput"
+          class="file-input"
+          type="file"
+          multiple
+          accept="audio/*,.mp3,.flac,.wav,.m4a,.aac,.ogg,.opus,.webm,.wma,.alac,.aiff,.ape"
+          @change="handleFileSelect"
+        />
+      </div>
+      <div v-else class="local-upload disabled">
+        <Icon icon="mdi:music-off" class="upload-icon" />
+        <div class="upload-copy">
+          <div class="upload-title">本地音频播放已关闭</div>
+          <div class="upload-subtitle">管理员可在「设置 → 行为设置 → 本地音频播放」中开启。</div>
+        </div>
+      </div>
+      <div v-if="uploadMessage" class="upload-message" :class="uploadMessageType">{{ uploadMessage }}</div>
    </div>

    <div v-if="loading" class="loading">搜索中...</div>
@@ -37,6 +72,17 @@
          :class="{ active: selectedSource === 'bilibili' }"
          @click="selectedSource = 'bilibili'"
        >B站</button>
+        <button
+          class="source-btn"
+          :class="{ active: selectedSource === 'kugou' }"
+          @click="selectedSource = 'kugou'"
+        >酷狗</button>
+        <button
+          v-if="hasLocalSongs"
+          class="source-btn"
+          :class="{ active: selectedSource === 'local' }"
+          @click="selectedSource = 'local'"
+        >本地</button>
      </div>

      <div class="tab-bar">
@@ -48,7 +94,7 @@
          单曲<span class="tab-count">{{ filteredSongs.length }}</span>
        </button>
        <button
-          v-if="selectedSource !== 'bilibili'"
+          v-if="selectedSource !== 'bilibili' && selectedSource !== 'local' && selectedSource !== 'kugou'"
          class="tab"
          :class="{ active: activeTab === 'albums' }"
          @click="activeTab = 'albums'"
@@ -56,7 +102,7 @@
          专辑<span class="tab-count">{{ filteredAlbums.length }}</span>
        </button>
        <button
-          v-if="selectedSource !== 'bilibili'"
+          v-if="selectedSource !== 'bilibili' && selectedSource !== 'local' && selectedSource !== 'kugou'"
          class="tab"
          :class="{ active: activeTab === 'playlists' }"
          @click="activeTab = 'playlists'"
@@ -119,6 +165,13 @@
          @add="store.addSong(song)"
        />
      </section>
+
+      <div v-if="showLoadMore" class="load-more-wrap">
+        <button class="load-more-btn" :disabled="currentLoadingMore" @click="loadMore">
+          <Icon v-if="currentLoadingMore" icon="mdi:loading" class="spin" />
+          {{ currentLoadingMore ? '加载中...' : '加载更多' }}
+        </button>
+      </div>
    </template>

    <div v-else-if="searched" class="empty">未找到相关结果</div>
@@ -134,6 +187,9 @@ import { usePlayerStore } from '../stores/player.js';
 import type { Song } from '../stores/player.js';
 import SongCard from '../components/SongCard.vue';
 import CoverArt from '../components/CoverArt.vue';
+import { mergeDedup, hasMore, nextOffset } from './searchPagination.js';
+
+const PAGE_SIZE = 20;

 const store = usePlayerStore();
 const route = useRoute();
@@ -141,17 +197,21 @@ const router = useRouter();

 const SOURCE_STORAGE_KEY = 'search-source';

-function loadSource(): 'netease' | 'qq' | 'bilibili' {
+type SearchSource = 'netease' | 'qq' | 'bilibili' | 'local' | 'kugou';
+
+function loadSource(): SearchSource {
  try {
    const stored = localStorage.getItem(SOURCE_STORAGE_KEY);
-    if (stored === 'netease' || stored === 'qq' || stored === 'bilibili') return stored;
+    if (stored === 'netease' || stored === 'qq' || stored === 'bilibili' || stored === 'local' || stored === 'kugou') return stored;
  } catch { /* localStorage blocked */ }
  return 'netease';
 }

+type TabType = 'songs' | 'albums' | 'playlists';
+
 const query = ref((route.query.q as string) || '');
-const activeTab = ref<'songs' | 'albums' | 'playlists'>('songs');
-const selectedSource = ref<'netease' | 'qq' | 'bilibili'>(loadSource());
+const activeTab = ref<TabType>('songs');
+const selectedSource = ref<SearchSource>(loadSource());

 interface Album { id: string; name: string; artist: string; coverUrl: string; songCount?: number; platform: string; }
 interface Playlist { id: string; name: string; coverUrl: string; songCount?: number; platform: string; }
@@ -159,8 +219,17 @@ interface Playlist { id: string; name: string; coverUrl: string; songCount?: num
 const allSongs = ref<Song[]>([]);
 const allAlbums = ref<Album[]>([]);
 const allPlaylists = ref<Playlist[]>([]);
+// "加载更多" 分页状态：hasMore 按 (类型, 音源) 记录，loadingMore 按类型记录。
+const hasMoreMap = ref<Record<string, boolean>>({});
+const loadingMore = ref<Record<TabType, boolean>>({ songs: false, albums: false, playlists: false });
 const loading = ref(false);
 const searched = ref(false);
+const uploading = ref(false);
+const isDragging = ref(false);
+const uploadMessage = ref('');
+const uploadMessageType = ref<'info' | 'error'>('info');
+const fileInput = ref<HTMLInputElement | null>(null);
+const localAudioEnabled = ref(true);

 const filteredSongs = computed(() =>
  allSongs.value.filter((s) => s.platform === selectedSource.value)
@@ -174,14 +243,91 @@ const filteredPlaylists = computed(() =>
  allPlaylists.value.filter((p) => p.platform === selectedSource.value)
 );

+const hasLocalSongs = computed(() => localAudioEnabled.value && allSongs.value.some((s) => s.platform === 'local'));
+
+// ---- 分页 / 加载更多 ----
+function pageKey(type: TabType, source: string): string {
+  return `${type}:${source}`;
+}
+
+const currentItems = computed(() => {
+  if (activeTab.value === 'albums') return filteredAlbums.value;
+  if (activeTab.value === 'playlists') return filteredPlaylists.value;
+  return filteredSongs.value;
+});
+
+const currentLoadingMore = computed(() => loadingMore.value[activeTab.value]);
+
+const currentHasMore = computed(
+  () => hasMoreMap.value[pageKey(activeTab.value, selectedSource.value)] ?? false
+);
+
+// 有结果、还有下一页时才显示按钮；加载中时按钮保留但禁用并显示 spinner。
+const showLoadMore = computed(() => currentItems.value.length > 0 && currentHasMore.value);
+
+function resetPagination() {
+  hasMoreMap.value = {};
+  loadingMore.value = { songs: false, albums: false, playlists: false };
+}
+
+// 记录某个 (类型, 音源) 是否还有更多：返回条数 === PAGE_SIZE 视为还有下一页。
+function setHasMore(type: TabType, source: string, returnedCount: number) {
+  hasMoreMap.value = {
+    ...hasMoreMap.value,
+    [pageKey(type, source)]: hasMore(returnedCount, PAGE_SIZE),
+  };
+}
+
+// 初始 /search/all 返回的是各音源合并的首页，按音源分组统计每种类型的条数。
+function recordInitialHasMore(items: { platform: string }[], type: TabType) {
+  const counts: Record<string, number> = {};
+  for (const it of items) counts[it.platform] = (counts[it.platform] ?? 0) + 1;
+  const next = { ...hasMoreMap.value };
+  for (const [source, count] of Object.entries(counts)) {
+    next[pageKey(type, source)] = hasMore(count, PAGE_SIZE);
+  }
+  hasMoreMap.value = next;
+}
+
+async function loadMore() {
+  const type = activeTab.value;
+  const source = selectedSource.value;
+  if (loadingMore.value[type]) return;
+  if (!currentHasMore.value) return;
+  const offset = nextOffset(currentItems.value.length, PAGE_SIZE);
+  loadingMore.value = { ...loadingMore.value, [type]: true };
+  try {
+    const res = await axios.get('/api/music/search', {
+      params: { q: query.value, platform: source, limit: PAGE_SIZE, offset },
+    });
+    if (type === 'albums') {
+      const incoming = (res.data.albums ?? []) as Album[];
+      allAlbums.value = mergeDedup(allAlbums.value, incoming);
+      setHasMore(type, source, incoming.length);
+    } else if (type === 'playlists') {
+      const incoming = (res.data.playlists ?? []) as Playlist[];
+      allPlaylists.value = mergeDedup(allPlaylists.value, incoming);
+      setHasMore(type, source, incoming.length);
+    } else {
+      const incoming = (res.data.songs ?? []) as Song[];
+      allSongs.value = mergeDedup(allSongs.value, incoming);
+      setHasMore(type, source, incoming.length);
+    }
+  } catch {
+    // 保留 hasMore 现状，允许用户重试。
+  } finally {
+    loadingMore.value = { ...loadingMore.value, [type]: false };
+  }
+}
+
 // Persist source preference
 watch(selectedSource, (src) => {
  try { localStorage.setItem(SOURCE_STORAGE_KEY, src); } catch { /* ignore */ }
 });

-// B站 has no albums/playlists — force songs tab when switching to B站
+// B站 / 本地上传没有专辑和歌单页签，切换时强制回到单曲。
 watch(selectedSource, (src) => {
-  if (src === 'bilibili' && activeTab.value !== 'songs') {
+  if ((src === 'bilibili' || src === 'local' || src === 'kugou') && activeTab.value !== 'songs') {
    activeTab.value = 'songs';
  }
 });
@@ -210,12 +356,16 @@ async function doSearch() {
  loading.value = true;
  searched.value = true;
  activeTab.value = 'songs';
+  resetPagination();
  router.replace({ query: { q: query.value } });
  try {
    const res = await axios.get('/api/music/search/all', { params: { q: query.value } });
    allSongs.value = res.data.songs ?? [];
    allAlbums.value = res.data.albums ?? [];
    allPlaylists.value = res.data.playlists ?? [];
+    recordInitialHasMore(allSongs.value, 'songs');
+    recordInitialHasMore(allAlbums.value, 'albums');
+    recordInitialHasMore(allPlaylists.value, 'playlists');
  } catch {
    allSongs.value = []; allAlbums.value = []; allPlaylists.value = [];
  } finally {
@@ -223,10 +373,84 @@ async function doSearch() {
  }
 }

+
+function isAudioFile(file: File): boolean {
+  return file.type.startsWith('audio/') || /\.(mp3|flac|wav|m4a|aac|ogg|opus|webm|wma|alac|aiff|ape)$/i.test(file.name);
+}
+
+async function uploadLocalFiles(fileList: File[]) {
+  if (!localAudioEnabled.value) {
+    uploadMessageType.value = 'error';
+    uploadMessage.value = '本地音频播放已关闭';
+    return;
+  }
+  const files = fileList.filter(isAudioFile);
+  if (files.length === 0) {
+    uploadMessageType.value = 'error';
+    uploadMessage.value = '没有找到可上传的音频文件';
+    return;
+  }
+
+  uploading.value = true;
+  uploadMessageType.value = 'info';
+  uploadMessage.value = `正在上传 ${files.length} 个文件...`;
+
+  const uploaded: Song[] = [];
+  const failed: string[] = [];
+  for (const file of files) {
+    try {
+      const res = await axios.post('/api/music/local/upload', file, {
+        headers: {
+          'Content-Type': file.type || 'application/octet-stream',
+          'X-Filename': encodeURIComponent(file.name),
+        },
+        maxBodyLength: Infinity,
+      });
+      if (res.data?.song) uploaded.push(res.data.song as Song);
+    } catch (err: any) {
+      failed.push(`${file.name}: ${err?.response?.data?.error || '上传失败'}`);
+    }
+  }
+
+  if (uploaded.length > 0) {
+    const uploadedKeys = new Set(uploaded.map((s) => `${s.platform}-${s.id}`));
+    allSongs.value = [
+      ...uploaded,
+      ...allSongs.value.filter((s) => !uploadedKeys.has(`${s.platform}-${s.id}`)),
+    ];
+    selectedSource.value = 'local';
+    activeTab.value = 'songs';
+    searched.value = true;
+    uploadMessageType.value = failed.length ? 'error' : 'info';
+    uploadMessage.value = failed.length
+      ? `已上传 ${uploaded.length} 个，失败 ${failed.length} 个：${failed[0]}`
+      : `已上传 ${uploaded.length} 个本地音频`;
+  } else {
+    uploadMessageType.value = 'error';
+    uploadMessage.value = failed[0] || '上传失败';
+  }
+
+  uploading.value = false;
+}
+
+function handleDrop(event: DragEvent) {
+  isDragging.value = false;
+  const files = Array.from(event.dataTransfer?.files ?? []);
+  uploadLocalFiles(files);
+}
+
+function handleFileSelect(event: Event) {
+  const input = event.target as HTMLInputElement;
+  uploadLocalFiles(Array.from(input.files ?? []));
+  input.value = '';
+}
+
 function badgeLabel(platform: string): string {
  if (platform === 'qq') return 'QQ';
  if (platform === 'bilibili') return 'B站';
  if (platform === 'youtube') return 'YouTube';
+  if (platform === 'local') return '本地';
+  if (platform === 'kugou') return '酷狗';
  return '网易云';
 }

@@ -234,10 +458,25 @@ function badgeClass(platform: string): string {
  if (platform === 'qq') return 'badge-qq';
  if (platform === 'bilibili') return 'badge-bilibili';
  if (platform === 'youtube') return 'badge-youtube';
+  if (platform === 'local') return 'badge-local';
+  if (platform === 'kugou') return 'badge-kugou';
  return 'badge-netease';
 }

+async function loadLocalAudioSetting() {
+  try {
+    const res = await axios.get('/api/bot/settings');
+    localAudioEnabled.value = res.data.localAudioEnabled ?? true;
+    if (!localAudioEnabled.value && selectedSource.value === 'local') {
+      selectedSource.value = 'netease';
+    }
+  } catch {
+    // Guests may not be allowed to read settings; backend still enforces the switch.
+  }
+}
+
 onMounted(() => {
+  loadLocalAudioSetting();
  if (query.value) doSearch();
 });
 </script>
@@ -258,6 +497,86 @@ onMounted(() => {
  margin-bottom: 24px;
 }

+.local-upload {
+  display: flex;
+  align-items: center;
+  gap: 14px;
+  padding: 14px 16px;
+  border: 1px dashed var(--border-color);
+  border-radius: var(--radius-md);
+  background: var(--bg-card);
+  transition: border-color var(--transition-fast), background var(--transition-fast), transform var(--transition-fast);
+
+  &.dragging {
+    border-color: var(--color-primary);
+    background: var(--color-primary-10);
+    transform: translateY(-1px);
+  }
+
+  &.uploading {
+    opacity: 0.8;
+  }
+}
+
+.upload-icon {
+  flex-shrink: 0;
+  font-size: 28px;
+  color: var(--color-primary);
+}
+
+.upload-copy {
+  flex: 1;
+  min-width: 0;
+}
+
+.upload-title {
+  font-size: 14px;
+  font-weight: var(--fw-semi);
+  color: var(--text-primary);
+}
+
+.upload-subtitle {
+  margin-top: 3px;
+  font-size: 12px;
+  color: var(--text-tertiary);
+  line-height: 1.4;
+}
+
+.upload-btn {
+  flex-shrink: 0;
+  padding: 8px 14px;
+  border-radius: var(--radius-sm);
+  background: var(--color-primary);
+  color: #fff;
+  font-size: 13px;
+  font-weight: var(--fw-semi);
+  cursor: pointer;
+
+  &:disabled {
+    cursor: not-allowed;
+    opacity: 0.65;
+  }
+}
+
+.file-input {
+  display: none;
+}
+
+.local-upload.disabled {
+  opacity: 0.65;
+  border-style: solid;
+}
+
+.upload-message {
+  margin-top: 8px;
+  font-size: 12px;
+  color: var(--text-secondary);
+
+  &.error {
+    color: #e74c3c;
+  }
+}
+
 .search-input-wrap {
  display: flex;
  align-items: center;
@@ -376,6 +695,45 @@ onMounted(() => {
 .result-section {
  margin-bottom: 32px;
 }
+
+.load-more-wrap {
+  display: flex;
+  justify-content: center;
+  margin: 8px 0 32px;
+}
+
+.load-more-btn {
+  display: inline-flex;
+  align-items: center;
+  gap: 6px;
+  padding: 9px 28px;
+  border-radius: var(--radius-md);
+  font-size: 14px;
+  font-family: inherit;
+  font-weight: var(--fw-semi);
+  color: var(--text-secondary);
+  background: var(--bg-card);
+  cursor: pointer;
+  transition: color var(--transition-fast), background var(--transition-fast);
+
+  &:hover:not(:disabled) {
+    color: var(--color-primary);
+    background: rgba(51, 94, 234, 0.12);
+  }
+
+  &:disabled {
+    cursor: not-allowed;
+    opacity: 0.7;
+  }
+
+  .spin {
+    animation: load-more-spin 0.8s linear infinite;
+  }
+}
+
+@keyframes load-more-spin {
+  to { transform: rotate(360deg); }
+}
 .card-grid {
  display: grid;
  grid-template-columns: repeat(auto-fill, minmax(140px, 1fr));
@@ -422,6 +780,16 @@ onMounted(() => {
  color: var(--brand-youtube);
 }

+.badge-local {
+  background: var(--color-primary-10);
+  color: var(--color-primary);
+}
+
+.badge-kugou {
+  background: var(--brand-kugou-12);
+  color: var(--brand-kugou);
+}
+
 .fav-badge {
  position: absolute;
  top: 8px;
@@ -377,6 +377,76 @@
          <button class="btn-primary btn-save" @click="saveCookie('bilibili')">保存Cookie</button>
        </div>
      </div>
+
+      <!-- Kugou -->
+      <div class="account-card">
+        <div class="account-header">
+          <Icon icon="mdi:music-circle-outline" class="account-icon kugou-icon" />
+          <div class="account-info">
+            <div class="account-name">酷狗音乐</div>
+            <div class="account-status" :class="{ logged: kugouAuth.loggedIn }">
+              {{ kugouAuth.loggedIn ? `已登录: ${kugouAuth.nickname}` : '未登录' }}
+            </div>
+          </div>
+        </div>
+
+        <div class="login-methods">
+          <button
+            class="login-btn"
+            :class="{ active: kugouLoginMode === 'qr' }"
+            @click="startQrLogin('kugou')"
+            :disabled="kugouQr.loading"
+          >
+            <Icon icon="mdi:qrcode" />
+            扫码登录
+          </button>
+          <button
+            class="login-btn"
+            :class="{ active: kugouLoginMode === 'cookie' }"
+            @click="kugouLoginMode = 'cookie'"
+          >
+            <Icon icon="mdi:cookie" />
+            Cookie登录
+          </button>
+        </div>
+
+        <!-- QR Code -->
+        <div v-if="kugouLoginMode === 'qr'" class="qr-section">
+          <div v-if="kugouQr.loading" class="qr-loading">
+            <Icon icon="mdi:loading" class="spin" />
+            生成二维码中...
+          </div>
+          <div v-else-if="kugouQr.dataUrl" class="qr-wrap">
+            <img :src="kugouQr.dataUrl" class="qr-image" alt="QR Code" />
+            <div class="qr-status" :class="kugouQr.status">
+              <template v-if="kugouQr.status === 'waiting'">
+                <Icon icon="mdi:cellphone" /> 请使用酷狗音乐APP扫码
+              </template>
+              <template v-else-if="kugouQr.status === 'scanned'">
+                <Icon icon="mdi:check" /> 已扫码，请在手机上确认
+              </template>
+              <template v-else-if="kugouQr.status === 'confirmed'">
+                <Icon icon="mdi:check-circle" /> 登录成功!
+              </template>
+              <template v-else-if="kugouQr.status === 'expired'">
+                <Icon icon="mdi:refresh" /> 二维码已过期
+                <button class="btn-link" @click="startQrLogin('kugou')">重新生成</button>
+              </template>
+            </div>
+          </div>
+        </div>
+
+        <!-- Cookie -->
+        <div v-if="kugouLoginMode === 'cookie'" class="cookie-section">
+          <textarea
+            v-model="kugouCookie"
+            class="textarea"
+            placeholder="粘贴酷狗Cookie (token=...; userid=...)..."
+            rows="3"
+          />
+          <button class="btn-primary btn-save" @click="saveCookie('kugou')">保存Cookie</button>
+        </div>
+      </div>
    </section>

    <!-- Audio Quality requires quality -->
@@ -453,6 +523,19 @@
          @change="saveAutoPause"
        />
      </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="localAudioEnabled"
+          type="checkbox"
+          class="profile-toggle-switch"
+          @change="saveLocalAudioEnabled"
+        />
+      </label>
    </section>

    <!-- Guest Mode (admin only) -->
@@ -504,6 +587,23 @@
      </div>
    </section>

+    <!-- Command Permissions (admin only) -->
+    <section v-if="session.isAdmin.value" class="settings-section">
+      <h2 class="section-title">命令权限</h2>
+      <p class="profile-section-hint">
+        限制谁能在 TeamSpeak 聊天里运行管理类命令（stop / clear / remove / move / vol / mode）。
+        填写允许的服务器组 ID（逗号分隔）。留空 = 不限制，所有人可用。如何查看服务器组 ID 见 README。
+      </p>
+      <div class="setting-row">
+        <div class="prefix-input-wrap">
+          <input v-model="adminGroupsText" class="input input-sm" placeholder="如 6, 8" />
+          <button class="btn-primary" :disabled="adminGroupsSaving" @click="saveAdminGroups">
+            {{ adminGroupsSaving ? '保存中…' : '保存' }}
+          </button>
+        </div>
+      </div>
+    </section>
+
    <!-- Bot Profile (TeamSpeak Behavior) -->
    <section v-if="can('bot.manage')" class="settings-section">
      <h2 class="section-title">机器人 Profile（TeamSpeak 行为）</h2>
@@ -762,6 +862,7 @@ const editForm = reactive({
 const neteaseCookie = ref('');
 const qqCookie = ref('');
 const bilibiliCookie = ref('');
+const kugouCookie = ref('');
 const commandPrefix = ref('!');

 // Audio quality
@@ -793,11 +894,13 @@ async function setQuality(q: string) {
 const neteaseLoginMode = ref<'qr' | 'cookie' | null>(null);
 const qqLoginMode = ref<'qr' | 'cookie' | null>(null);
 const bilibiliLoginMode = ref<'qr' | 'cookie' | null>(null);
+const kugouLoginMode = ref<'qr' | 'cookie' | null>(null);

 // Auth status
 const neteaseAuth = reactive({ loggedIn: false, nickname: '', avatarUrl: '' });
 const qqAuth = reactive({ loggedIn: false, nickname: '', avatarUrl: '' });
 const bilibiliAuth = reactive({ loggedIn: false, nickname: '', avatarUrl: '' });
+const kugouAuth = reactive({ loggedIn: false, nickname: '', avatarUrl: '' });

 // QR state
 interface QrState {
@@ -817,22 +920,28 @@ const qqQr = reactive<QrState>({
 const bilibiliQr = reactive<QrState>({
  loading: false, dataUrl: '', key: '', status: 'waiting', pollTimer: null,
 });
+const kugouQr = reactive<QrState>({
+  loading: false, dataUrl: '', key: '', status: 'waiting', pollTimer: null,
+});

 function getQrState(platform: string): QrState {
  if (platform === 'bilibili') return bilibiliQr;
+  if (platform === 'kugou') return kugouQr;
  return platform === 'netease' ? neteaseQr : qqQr;
 }

 async function checkAuthStatus() {
  try {
-    const [nRes, qRes, bRes] = await Promise.all([
+    const [nRes, qRes, bRes, kRes] = await Promise.all([
      axios.get('/api/auth/status', { params: { platform: 'netease' } }),
      axios.get('/api/auth/status', { params: { platform: 'qq' } }),
      axios.get('/api/auth/status', { params: { platform: 'bilibili' } }),
+      axios.get('/api/auth/status', { params: { platform: 'kugou' } }),
    ]);
    Object.assign(neteaseAuth, nRes.data);
    Object.assign(qqAuth, qRes.data);
    Object.assign(bilibiliAuth, bRes.data);
+    Object.assign(kugouAuth, kRes.data);
  } catch {
    // API not ready
  }
@@ -842,6 +951,7 @@ async function startQrLogin(platform: string) {
  const qr = getQrState(platform);
  if (platform === 'netease') neteaseLoginMode.value = 'qr';
  else if (platform === 'bilibili') bilibiliLoginMode.value = 'qr';
+  else if (platform === 'kugou') kugouLoginMode.value = 'qr';
  else qqLoginMode.value = 'qr';

  // Stop existing poll
@@ -859,13 +969,15 @@ async function startQrLogin(platform: string) {
    if (qrImg) {
      qr.dataUrl = qrImg;
    } else {
+      // QR codes must be dark-on-light to stay scannable. Do NOT invert the
+      // colours for the dark theme: many in-app scanners (notably the Kugou
+      // music app) cannot decode a light-on-dark QR, so a themed code looks
+      // fine on screen but silently fails to scan. The white quiet-zone frames
+      // it cleanly in dark mode anyway.
      qr.dataUrl = await QRCode.toDataURL(qrUrl, {
        width: 200,
        margin: 2,
-        color: {
-          dark: store.theme === 'dark' ? '#ffffff' : '#000000',
-          light: store.theme === 'dark' ? '#2a2a2a' : '#ffffff',
-        },
+        color: { dark: '#000000', light: '#ffffff' },
      });
    }

@@ -1002,7 +1114,9 @@ async function toggleBot(botId: string, connected: boolean) {
 }

 async function saveCookie(platform: string) {
-  const cookie = platform === 'bilibili' ? bilibiliCookie.value : platform === 'netease' ? neteaseCookie.value : qqCookie.value;
+  const cookie = platform === 'bilibili' ? bilibiliCookie.value
+    : platform === 'kugou' ? kugouCookie.value
+    : platform === 'netease' ? neteaseCookie.value : qqCookie.value;
  if (!cookie) return;
  try {
    await axios.post('/api/auth/cookie', { platform, cookie });
@@ -1020,13 +1134,16 @@ async function savePrefix() {
 const idleTimeout = ref(0);
 // Defaults OFF to match the backend default (config.ts getDefaultConfig).
 const autoPauseOnEmpty = ref(false);
+const localAudioEnabled = ref(true);

 async function loadIdleTimeout() {
  try {
    const res = await axios.get('/api/bot/settings');
    idleTimeout.value = res.data.idleTimeoutMinutes ?? 0;
    autoPauseOnEmpty.value = res.data.autoPauseOnEmpty ?? false;
+    localAudioEnabled.value = res.data.localAudioEnabled ?? true;
    applyGuestModeFromServer(res.data.guestMode);
+    applyAdminGroupsFromServer(res.data.adminGroups);
  } catch { /* ignore */ }
 }

@@ -1042,6 +1159,13 @@ async function saveAutoPause() {
  } catch { /* ignore */ }
 }

+async function saveLocalAudioEnabled() {
+  try {
+    const res = await axios.post('/api/bot/settings', { localAudioEnabled: localAudioEnabled.value });
+    localAudioEnabled.value = res.data.localAudioEnabled ?? localAudioEnabled.value;
+  } catch { /* ignore */ }
+}
+
 // --- Guest mode (admin only) ---
 const GUEST_FLAGS: { token: string; label: string }[] = [
  { token: 'addToQueue', label: '添加到队列末尾' },
@@ -1051,12 +1175,13 @@ const GUEST_FLAGS: { token: string; label: string }[] = [
  { token: 'transport', label: '暂停/继续/进度/音量' },
  { token: 'removeClear', label: '移除/清空队列' },
  { token: 'playMode', label: '切换播放模式 / FM' },
+  { token: 'playCollection', label: '播放整个歌单/专辑' },
 ];
 const guestMode = reactive<{ enabled: boolean; botsAll: boolean; selectedBotIds: string[]; permissions: Record<string, boolean> }>({
  enabled: false,
  botsAll: true,
  selectedBotIds: [],
-  permissions: { addToQueue: true, playNext: false, playNow: false, skip: false, transport: false, removeClear: false, playMode: false },
+  permissions: { addToQueue: true, playNext: false, playNow: false, skip: false, transport: false, removeClear: false, playMode: false, playCollection: false },
 });
 const guestSaving = ref(false);

@@ -1092,6 +1217,35 @@ async function saveGuestMode() {
  }
 }

+// --- Command permissions (admin only) ---
+const adminGroupsText = ref('');
+const adminGroupsSaving = ref(false);
+
+function applyAdminGroupsFromServer(groups: unknown) {
+  if (Array.isArray(groups)) {
+    adminGroupsText.value = groups.filter((g) => typeof g === 'number').join(', ');
+  }
+}
+
+function parseAdminGroups(text: string): number[] {
+  return text
+    .split(',')
+    .map((s) => s.trim())
+    .filter((s) => s.length > 0)
+    .map((s) => Number(s))
+    .filter((n) => Number.isInteger(n) && n >= 0);
+}
+
+async function saveAdminGroups() {
+  adminGroupsSaving.value = true;
+  try {
+    const res = await axios.post('/api/bot/settings', { adminGroups: parseAdminGroups(adminGroupsText.value) });
+    applyAdminGroupsFromServer(res.data?.adminGroups);
+  } catch { /* ignore */ } finally {
+    adminGroupsSaving.value = false;
+  }
+}
+
 // --- Bot Profile config ---
 interface ProfileConfig {
  avatarEnabled: boolean;
@@ -1487,6 +1641,7 @@ onUnmounted(() => {
  if (neteaseQr.pollTimer) clearInterval(neteaseQr.pollTimer);
  if (qqQr.pollTimer) clearInterval(qqQr.pollTimer);
  if (bilibiliQr.pollTimer) clearInterval(bilibiliQr.pollTimer);
+  if (kugouQr.pollTimer) clearInterval(kugouQr.pollTimer);
 });
 </script>

@@ -1628,6 +1783,10 @@ onUnmounted(() => {
  &.bilibili-icon {
    color: var(--brand-bilibili);
  }
+
+  &.kugou-icon {
+    color: var(--brand-kugou);
+  }
 }

 .account-name {
@@ -0,0 +1,93 @@
+import { describe, it, expect } from "vitest";
+import { itemKey, mergeDedup, hasMore, nextOffset, type Keyed } from "./searchPagination.js";
+
+const item = (platform: string, id: string): Keyed & { label: string } => ({
+  platform,
+  id,
+  label: `${platform}:${id}`,
+});
+
+describe("searchPagination helpers (#115)", () => {
+  describe("itemKey", () => {
+    it("builds a `${platform}:${id}` key", () => {
+      expect(itemKey({ platform: "netease", id: "42" })).toBe("netease:42");
+    });
+
+    it("distinguishes same id across platforms", () => {
+      expect(itemKey({ platform: "qq", id: "1" })).not.toBe(itemKey({ platform: "netease", id: "1" }));
+    });
+  });
+
+  describe("mergeDedup", () => {
+    it("appends incoming items, existing first, order preserved", () => {
+      const existing = [item("netease", "1"), item("netease", "2")];
+      const incoming = [item("netease", "3"), item("netease", "4")];
+      expect(mergeDedup(existing, incoming).map((x) => x.id)).toEqual(["1", "2", "3", "4"]);
+    });
+
+    it("drops incoming items already present in existing", () => {
+      const existing = [item("netease", "1"), item("netease", "2")];
+      const incoming = [item("netease", "2"), item("netease", "3")];
+      expect(mergeDedup(existing, incoming).map((x) => x.id)).toEqual(["1", "2", "3"]);
+    });
+
+    it("drops duplicates within the incoming batch", () => {
+      const existing = [item("netease", "1")];
+      const incoming = [item("netease", "2"), item("netease", "2"), item("netease", "3")];
+      expect(mergeDedup(existing, incoming).map((x) => x.id)).toEqual(["1", "2", "3"]);
+    });
+
+    it("treats same id on different platforms as distinct", () => {
+      const existing = [item("netease", "1")];
+      const incoming = [item("qq", "1")];
+      const merged = mergeDedup(existing, incoming);
+      expect(merged.map(itemKey)).toEqual(["netease:1", "qq:1"]);
+    });
+
+    it("does not mutate the existing array", () => {
+      const existing = [item("netease", "1")];
+      const before = existing.slice();
+      mergeDedup(existing, [item("netease", "2")]);
+      expect(existing).toEqual(before);
+    });
+
+    it("handles empty incoming", () => {
+      const existing = [item("netease", "1")];
+      expect(mergeDedup(existing, []).map((x) => x.id)).toEqual(["1"]);
+    });
+  });
+
+  describe("hasMore", () => {
+    it("is true when a full page came back", () => {
+      expect(hasMore(20, 20)).toBe(true);
+    });
+
+    it("is false when a short page came back", () => {
+      expect(hasMore(7, 20)).toBe(false);
+    });
+
+    it("is false when nothing came back", () => {
+      expect(hasMore(0, 20)).toBe(false);
+    });
+  });
+
+  describe("nextOffset", () => {
+    it("returns the page-aligned offset for a full first page", () => {
+      expect(nextOffset(20, 20)).toBe(20);
+    });
+
+    it("returns 0 when nothing is shown yet", () => {
+      expect(nextOffset(0, 20)).toBe(0);
+    });
+
+    it("rounds up to the next page boundary after dedup drops items", () => {
+      // page1 (20) + page2 minus 5 dupes -> 35 shown, next page cursor is 40.
+      expect(nextOffset(35, 20)).toBe(40);
+    });
+
+    it("stays aligned across multiple full pages", () => {
+      expect(nextOffset(40, 20)).toBe(40);
+      expect(nextOffset(60, 20)).toBe(60);
+    });
+  });
+});
@@ -0,0 +1,46 @@
+// Pure pagination helpers for Search.vue "加载更多" (load-more) per source + tab.
+// Kept framework-free so root vitest can unit-cover the logic (see searchPagination.test.ts).
+
+/** Minimal shape shared by songs / albums / playlists: needs a stable dedup key. */
+export interface Keyed {
+  id: string;
+  platform: string;
+}
+
+/** Stable dedup key for a result item: `${platform}:${id}`. */
+export function itemKey(item: Keyed): string {
+  return `${item.platform}:${item.id}`;
+}
+
+/**
+ * Merge `incoming` into `existing`, deduped by `${platform}:${id}`.
+ * Order is preserved with existing items first; incoming items already present
+ * (or duplicated within the incoming batch) are dropped.
+ */
+export function mergeDedup<T extends Keyed>(existing: T[], incoming: T[]): T[] {
+  const seen = new Set<string>(existing.map(itemKey));
+  const result = existing.slice();
+  for (const item of incoming) {
+    const key = itemKey(item);
+    if (seen.has(key)) continue;
+    seen.add(key);
+    result.push(item);
+  }
+  return result;
+}
+
+/**
+ * Whether another page might exist: a full page (=== pageSize) means keep the
+ * button; a short/empty page (< pageSize) means the source is exhausted.
+ */
+export function hasMore(returnedCount: number, pageSize: number): boolean {
+  return returnedCount >= pageSize;
+}
+
+/**
+ * Offset for the next page request. Offsets are page-aligned, so this is simply
+ * the number of items already shown for that source+type.
+ */
+export function nextOffset(currentCountForSource: number, pageSize: number): number {
+  return Math.ceil(currentCountForSource / pageSize) * pageSize;
+}
Author	SHA1	Message	Date
saopig1andClaude Opus 4.8	a97e72ef30	feat(search): per-source load-more pagination in Search.vue (#115 frontend) Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>	2026-07-04 14:42:07 +08:00
saopig1andClaude Opus 4.8	a1cc0b8574	feat(search): server-side offset pagination through providers + /search route (#115 backend) Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>	2026-07-04 14:36:54 +08:00
saopig1andClaude Opus 4.8	81b8953d52	fix(lyrics): send full lyrics chunked under TeamSpeak message cap (#116 ) Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>	2026-07-04 14:26:51 +08:00
TIANYAO ZHANG	f8743a904f	Merge pull request #114 from ZHANGTIANYAO1/fix/qq-api-version-pin fix(qq): 锁定 @sansenjian/qq-music-api 到 ~2.4.0 并加固启动报错	2026-06-30 23:26:28 +08:00
saopig1andClaude Opus 4.8	f6e42811a5	chore(deps): update NeteaseCloudMusicApi (pinned) + safe patch/minor bumps Dependency audit follow-up to the QQ pin: - NeteaseCloudMusicApi ^4.30.0 → ~4.32.0. Same rationale as @sansenjian/ qq-music-api: it's an embedded API server loaded via dynamic import, so a loose `^` could drift into a breaking minor and silently kill the netease server (ECONNREFUSED). Tighten to ~4.32.x. Verified at runtime: server starts on 3001 and /banner returns 200. - Lockfile bumps within existing ^ ranges (no API-server risk, so ranges kept): better-sqlite3 12.8.0→12.11.1, koa 3.2.0→3.2.1, ws 8.20.0→8.21.0, typescript 6.0.2→6.0.3, ts3-nodejs-library 3.5.1→3.5.3, vitest 4.1.4→4.1.9, tsx 4.21.0→4.22.4. - Deliberately NOT bumped (major / needs a migration): bcryptjs 2→3 (password hashing), @types/node 25→26, @types/supertest 6→7. tsc clean; full suite 913 passing under vitest 4.1.9. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>	2026-06-30 23:16:25 +08:00
saopig1andClaude Opus 4.8	08260182a9	fix(qq): pin @sansenjian/qq-music-api to ~2.4.0 + guard startup failures A loose `^2.2.10` range let npm pull a newer build of the QQ Music API. The library went ESM in 2.3.x: an ESM-only 2.3.0/2.3.1 throws ERR_REQUIRE_ESM on load, so the embedded server never binds port 3200 and every QQ request (including /getQQLoginQr) fails downstream with ECONNREFUSED — the QR code never appears and cookies look broken. - Pin to `~2.4.0` (verified: loads via the bot's native ESM import, exposes the Koa app, and every endpoint qq.ts calls returns the exact shapes it parses — QR, recommend, lyric, play, playlist detail). Blocks the broken 2.3.0/2.3.1 and any future 2.5 migration. NOTE: 2.4.x requires Node >=20.17 (or >=22.9). - Add describeQqApiStartupError(): on startup failure, log an actionable error (ERR_REQUIRE_ESM → version-pin hint; engine mismatch → Node-upgrade hint) instead of a generic warning, so this is obvious from the logs next time. - README: troubleshooting entry for "QQ 二维码不弹 / 登录失败 / cookie 无法使用" and the version/Node note in the dependency table. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>	2026-06-30 23:05:47 +08:00
TIANYAO ZHANG	de4343cfbb	Merge pull request #113 from ZHANGTIANYAO1/docs/kugou-readme docs: 在 README 中补充酷狗音乐音源与登录功能	2026-06-30 21:36:34 +08:00
saopig1andClaude Opus 4.8	af50d69b00	docs: document Kugou (酷狗音乐) source + login features in README Kugou shipped in #110 but the README still listed only netease/qq/bilibili/ youtube. Add Kugou throughout: - tagline, badge, 多平台音源, QR 登录, 歌单管理 (酷狗私人电台 !fm -k + the login-gated daily/recommend/user playlists) - quick-start account login, WebUI page table (FM sources, 三→四平台 search, multi-platform login), architecture tree (kugou.ts), dependency table, milestones, and a credit to the MIT MakcRe/KuGouMusicApi reference - command table: !play -k / !search [-k] / !artist -k / !fm -k (the flags that actually route to Kugou; not !playlist -k — Kugou search returns no playlists) Also fix the in-bot `!search` usage string to include -k so it matches. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>	2026-06-30 21:36:00 +08:00
TIANYAO ZHANG	e1439a5899	Merge pull request #110 from ZHANGTIANYAO1/feat/kugou-provider feat: 增加酷狗音乐 (Kugou) 音源支持 (closes #69)	2026-06-30 21:15:12 +08:00
saopig1andClaude Opus 4.8	5ae5168b6b	fix(web): keep the volume slider draggable under the per-frame progress loop (#111 ) The 60fps requestAnimationFrame progress clock (#107) re-renders the player every ~16ms, and Vue re-applied `el.value = storeVolume` on a range input each time — snapping the thumb back to the stale store value mid-drag (un-draggable on desktop, janky on mobile). Extract the decoupling into a useDecoupledSlider composable used by both the desktop (Player.vue) and mobile (App.vue) sliders: a local display ref tracks the native drag via @input (so the bound value always matches the element), the store is committed only on @change (release), and an onRelease safety-net (pointerup/pointercancel/blur) clears the dragging guard even when the browser skips `change` (value released at its start point). External/store changes still flow into the display except while dragging. Adds a regression test for the no-snap-back invariant. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>	2026-06-30 21:12:05 +08:00
saopig1andClaude Opus 4.8	4cb1da29d4	fix(web): render login QR codes dark-on-light so scanners can read them The QR images used theme-aware colours, so in the default dark theme they were rendered light-on-dark (inverted). Many in-app scanners — notably the Kugou music app — cannot decode an inverted QR, so the code looked fine on screen but silently failed to scan. Force standard dark-on-light regardless of theme; the white quiet-zone frames it cleanly in dark mode anyway. Affects all platforms' QR login (netease/qq/bilibili/kugou). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>	2026-06-30 21:11:53 +08:00
saopig1andClaude Opus 4.8	f9caea6c79	feat(kugou): add login-gated discovery (daily/recommend/user playlists, FM) + covers Implements the NetEase-parity login features for the Kugou provider now that QR login works: - getDailyRecommendSongs (每日推荐), getUserPlaylists (我的歌单), and a real getRecommendPlaylists (推荐歌单, was a stub) ported from the reference API. - mapKugouSong now extracts cover art per endpoint (sizable_cover / cover / trans_param.union_cover, resolving the {size} template) — Kugou songs had no artwork before. - Fix the playlist-song shape (combined "歌手 - 歌名" in `name`, mixsongid as the audio id) so opened playlists show real titles instead of 未知歌曲. - New defensive playlist mappers keyed on global_collection_id (the only id getPlaylistSongs can open); dedup user playlists in case the list endpoint ignores pagination; firstStr() so an empty-string field can't mask a real one. Frontend wires Kugou as a third home-discovery source (Source type, store caches/auth, availableSources, fetchHomeData, Home FM card + source tabs, SourceTabs label, persisted-tab whitelist). SourceTabs now highlights the fallback-corrected source so the active tab shows when a logged-out source was persisted (newly possible with 3 sources). Adds kugou.test.ts coverage for the new mappers, the cover/empty-string and playlist-shape handling, and id openability. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>	2026-06-30 21:11:45 +08:00
saopig1andClaude Opus 4.8	a12c419dd2	feat(music): add Kugou (酷狗音乐) as a music source (#69 ) Adds a self-contained Kugou provider (bilibili-style: direct API calls, no embedded API server, no new npm dependency) plus full backend + WebUI wiring. Provider (src/music/kugou.ts): search, song-url (with device registration), lyrics (KRC decode), song detail, playlist, album, personal FM, QR login + cookie persistence, and quality. Request signing / crypto / KRC decoding are ported from the MIT-licensed MakcRe/KuGouMusicApi using Node's built-in crypto and zlib (no third-party crypto packages). Wiring: the "kugou" platform is threaded through the provider contract, queue, play-history, bot instance/manager dispatch (getProviderFor + the -k command flag), index/server composition, the music/player/auth routers (unified /search/all, /quality, the platform coercions, QR login), the cookie store, and the WebUI (search source tab + badge, SongCard badge, brand token, and a Kugou QR/cookie login card in Settings). Verified live during development: search, lyrics, and album playback resolve correctly. NOT verifiable in CI (Kugou anti-bot blocks the build host's IP): play-URL resolution, QR login, and VIP audio — these are built faithfully to the reference and need end-to-end testing on a non-flagged IP / a Kugou account. See the header comment in kugou.ts. Includes src/music/kugou.test.ts (mappers + KRC→LRC). An adversarial review pass fixed: pagination truncating on filtered counts, an ms/seconds duration heuristic, dfid soft-fail caching, the /v5/url random-dfid fallback, the FM body identity, and an unguarded nickname decode. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>	2026-06-30 18:55:41 +08:00
TIANYAO ZHANG	af326a37b7	Merge pull request #109 from ZHANGTIANYAO1/fix/player-elapsed-reactivity fix(web): 播放器时间每帧更新、歌词同步 (closes #107)	2026-06-30 17:26:46 +08:00
saopig1andClaude Opus 4.8	45f5d236c1	fix(web): tick player time every frame and keep lyrics in sync (#107 ) `store.elapsed` is a Pinia getter (a cached Vue computed) that interpolates with `Date.now()`. Because `Date.now()` is not a reactive dependency, the computed only re-ran on WebSocket pushes / the 3s server poll, so the bottom progress bar jumped ~3s at a time and lyric highlighting lagged ~half a line — even though the consumers read it from a 60fps requestAnimationFrame loop. Add a pure `interpolateElapsed()` helper and a non-cached `liveElapsed()` store action. The per-frame consumers now call `liveElapsed()` so the value advances every frame instead of returning a frozen cache: - web/src/components/Player.vue (desktop progress bar, rAF) - web/src/App.vue (mobile progress bar, rAF) - web/src/views/Lyrics.vue (lyric highlight, 500ms interval) pause() now freezes at the live value rather than a possibly-stale cached one. The `elapsed` getter is refactored onto the same helper (behaviour unchanged). Adds web/src/stores/elapsed.test.ts covering the time-advancing interpolation, paused freeze, no-anchor, and duration-clamp cases. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>	2026-06-30 16:17:53 +08:00
TIANYAO ZHANG	ea6820204d	Merge pull request #108 from Fa1nttt/feature/local-audio-upload feat: add local audio upload playback 增加本地音频上传播放功能	2026-06-30 16:03:32 +08:00
saopig1andClaude Opus 4.8	e849db2286	fix(local-audio): reference-aware cleanup, upload quota, stricter validation Uploaded local files were deleted whenever a track left the current slot, with no check on whether the file was still needed — causing data loss in several flows. Replace with reference-aware cleanup: a file is deleted only once it has been played AND is no longer referenced by ANY bot's queue (BotManager.getReferencedLocalSongIds wired into the provider via setInUseResolver), with the sweep run AFTER each queue mutation. Fixes: - play-song replay no longer deletes the file it is about to play - loop / repeat-all / prev no longer destroy uploads mid-cycle - a shared upload queued on multiple bots is not deleted while still in use - !play / play-playlist / play-album clean the whole replaced queue, and an empty/failed playlist/album load keeps the previous queue + files intact - bound disk use with an upload quota (evict oldest UNREFERENCED files) - validate uploads by extension against the audio whitelist (never trust the client Content-Type); the stored extension is always a known audio type Deletion now unlinks the file FIRST and drops the record only on success, with a bounded non-blocking retry for briefly-locked files (Windows/ffmpeg), so a failed unlink never orphans a file or diverges index.json. The quota never evicts the just-uploaded file, and long filenames keep their extension. Adds src/music/local.test.ts covering the cleanup lifecycle, quota eviction, and upload validation. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>	2026-06-30 15:58:22 +08:00
Fa1nttt	e12cbf8863	feat: add local audio upload playback	2026-06-30 14:08:42 +08:00
TIANYAO ZHANG	4e148302fc	Merge pull request #106 from ZHANGTIANYAO1/fix/guest-play-collection fix(guest): allow Play All for guests via a dedicated playCollection permission (#103)	2026-06-29 17:39:50 +08:00
saopig1	9c861f487d	docs: add playCollection to the guest-permission table (#103 )	2026-06-29 12:16:17 +08:00
saopig1	70c0273ae7	fix(guest): add playCollection permission so guests can Play All playlist/album (#103 ) - New guest flag playCollection (default OFF), gates play-playlist/play-album - Keeps playNow's non-destructive semantics intact (Play All clears the queue) - Admin-toggleable in Settings → 游客模式; default-off, backward-compatible - Frontend: gate the 播放全部 button on the flag + surface 403 as a toast instead of failing silently (the silent-failure half of the issue)	2026-06-29 12:12:47 +08:00
TIANYAO ZHANG	e2fa288f48	Merge pull request #105 from Slldyd2077/feat/song-vip-flag feat: expose vip flag & trial duration on Song for trial-only playback	2026-06-29 11:59:08 +08:00
TIANYAO ZHANG	59a9e742c8	Merge pull request #104 from ZHANGTIANYAO1/feat/ts-command-permissions feat: TeamSpeak chat-command permission control (adminGroups)	2026-06-28 23:41:34 +08:00
saopig1	31d3830791	test(ts-protocol): smoke-test getClientServerGroups query string + client_servergroups parse	2026-06-28 23:40:30 +08:00
Slldyd2077	d1bd010260	Merge remote-tracking branch 'upstream/main' into feat/song-vip-flag # Conflicts: # src/bot/instance.ts	2026-06-28 21:31:17 +08:00
Slldyd2077	fbb127a86d	feat: resolve trial-only playback via trialDuration/effectiveDuration VIP songs for non-VIP accounts return a ~30s trial fragment. The player used the full duration for isNearEnd, so the trial end didn't trigger auto-advance (~60s stall), and currentSong.duration stayed full, leaving the UI progress stuck. - provider.ts: SongUrlResult {url, trialDuration?}; getSongUrl signature - netease.ts: parseNeteaseTrial (freeTrialInfo start/end in seconds) + getSongUrl - qq.ts: parseQqTrial (isTryout/tryEnd) + getSongUrl - bilibili/youtube: getSongUrl returns {url} - instance.ts: resolveAndPlay uses effectiveDuration = trialDuration ?? duration -> nearEnd at trial end -> native auto-advance; BotStatus.effectiveDuration - VIP account: freeTrialInfo absent -> full duration -> full playback (no toggle) Backward compatible (optional fields; getSongUrl has a single caller, updated). Tests: parseTrial assertions (seconds/alias/ms-fallback). 14 pass.	2026-06-28 21:06:52 +08:00
Slldyd2077	7b2bd0ea6a	feat: expose vip flag on Song for trial-only detection Add optional vip?: boolean to the Song interface so downstream clients (e.g. PowerfulTS) can mark copyright-restricted songs that non-VIP users can only play as a trial fragment, before playback starts. - provider.ts: add optional vip?: boolean (backward compatible) - netease.ts: extract mapNeteaseSongs() pure fn; map fee to vip (1=VIP, 4=album-only). fee=8 (free low-quality) is excluded because it plays in full, just at lower quality. - qq.ts: mapQqSongs() maps pay.payplay/paytrackprice to vip (one fix covers all callers); getDailyRecommendSongs inline mapping too. - tests: vip mapping assertions for netease fee (1/4=vip, 0/8=free) and qq pay fields.	2026-06-28 17:12:57 +08:00
saopig1andClaude Opus 4.8	8e5e9c810e	fix(bot): resolve sender server groups live + server-wide for the admin-command gate Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>	2026-06-27 11:51:06 +08:00
saopig1	e104093614	fix: sanitize adminGroups on config load + final-review cleanups	2026-06-26 21:12:56 +08:00
saopig1	b387d6581e	docs: TS chat-command permission implementation plan	2026-06-26 20:57:39 +08:00
saopig1	17ab477af6	docs: correct stale adminGroups references now that the feature ships	2026-06-26 20:53:56 +08:00
saopig1	10e29476f4	docs: document TeamSpeak chat-command permission control	2026-06-26 20:51:08 +08:00
saopig1	215e328f17	feat(web): admin-only command-permission (adminGroups) settings section	2026-06-26 20:47:34 +08:00
saopig1	3346286ffd	feat(api): read/write adminGroups in bot settings endpoints	2026-06-26 20:44:29 +08:00
saopig1	72ffd44f68	feat(bot): gate admin chat commands on adminGroups with fallback + deny reply	2026-06-26 20:40:01 +08:00
saopig1	b090a8ec21	feat(ts-protocol): surface invokerGroups on TS3TextMessage via pure mapper	2026-06-26 20:35:31 +08:00
saopig1	f98ce47c52	feat(commands): add canRunCommand gate helper + admin-set source of truth	2026-06-26 20:32:45 +08:00
saopig1andClaude Opus 4.8	0c7f7e128b	docs: TS chat-command permission control design spec Binary admin gate keyed on TS server groups (config.adminGroups), opt-in/backward-compatible (empty = no enforcement), gated in the chat handler (executeCommand stays agnostic so WebUI is unaffected), with adminGroups editable from the WebUI settings. Completes the unused adminGroups/ADMIN_COMMANDS scaffold. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>	2026-06-25 23:04:58 +08:00
TIANYAO ZHANG	0cc77fdee0	Merge pull request #102 from ZHANGTIANYAO1/feat/guest-mode docs: surface guest mode in feature list + reflect shipped behavior	2026-06-25 16:25:34 +08:00
saopig1andClaude Opus 4.8	3b2b2185a5	docs: surface guest mode in feature list + reflect shipped behavior - Add a 游客模式 bullet to the top-level 功能特性 list. - Note guests share one short-lived anonymous identity, and that disabling/narrowing takes effect live (incl. open WebSockets). - Expand the always-denied list to include favorites, change-password, and the operator's personal platform-account data. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>	2026-06-25 16:24:25 +08:00