Merge pull request #109 from ZHANGTIANYAO1/fix/player-elapsed-reactivity

fix(web): 播放器时间每帧更新、歌词同步 (closes #107)

README.md

@@ -24,9 +24,11 @@
 ## 功能特性
 
 - **WebUI 鉴权与细粒度权限（必选）** — 用户名 + 密码登录，多用户、两种角色（管理员 / 成员）；成员可进一步配置**细粒度能力**（播放控制 / 队列管理 / 机器人管理 / 平台登录 / 音质）和**按机器人授权白名单**，所有变更操作由后端逐请求强制校验。bcrypt 加密、HttpOnly 会话 Cookie，CSRF 防护，WebSocket 同样鉴权。首次访问引导创建管理员。从无鉴权旧版本升级时请参阅 [更新升级](#更新升级) 章节
+- **游客模式（免登录点歌，默认关闭）** — 管理员可选择允许访客**无需账号密码**进入 WebUI 点歌，并逐项配置游客权限（8 个开关，默认仅「添加到队列末尾」开启）与可控机器人白名单；游客无法查看 / 修改任何设置、管理机器人或访问用户管理。开启后登录页出现 **「以游客身份进入」**。详见下文 **「游客模式 / Guest mode」** 小节
 - **本地收藏歌单** — 在首页 / 搜索 / 歌单页一键收藏，收藏内容按用户存储，登录后跨设备同步
+- **本地音频上传播放** — 在搜索页拖拽或选择本地音频上传，上传后可直接播放 / 下一首播放 / 加入队列；管理员可在 设置 → 行为设置 开关此功能，播放结束或停止/清空/替换队列时会清理服务端接收的本地文件
 - **专属链接（单机器人锁定）** — 通过 `/bot/<id>` 专属链接打开 WebUI 时锁定到单个机器人，刷新后保持，适合把某台机器人的控制页分享给特定用户
-- **频道无人时自动暂停** — 机器人所在频道没有其他人时自动暂停播放，有人加入后自动恢复（可在设置中关闭）
+- **频道无人时自动暂停** — 机器人所在频道没有其他人时自动暂停播放，有人加入后自动恢复（**默认关闭**，可在设置中开启）
 - **多平台音源** — 网易云音乐 + QQ 音乐 + 哔哩哔哩（默认内置），YouTube 可选启用（通过 yt-dlp），统一搜索，结果标注来源
 - **真实客户端协议 (TS3/TS6 双协议)** — 机器人在 TeamSpeak 中可见（非 ServerQuery 隐身模式），自动检测并适配 TS3 和 TS6 服务器，支持 TS6 HTTP Query API
 - **YesPlayMusic 风格 WebUI** — 精美界面，支持深色/浅色主题切换
@@ -182,6 +184,28 @@ sudo ./scripts/install.sh
 - 在 **设置 → 用户管理**（仅管理员）中添加 / 删除 / 重置密码 / 切换角色。
 - 至少保留一个管理员：系统会阻止删除或降级最后一位管理员。
 
+**游客模式 / Guest mode**：
+
+让访客**无需账号密码**即可进入 WebUI 点歌，同时严格限制其可用能力。该功能**默认关闭**，只有管理员能开启。
+
+- **开启方式**：管理员在 **设置 → 游客模式** 打开「允许游客访问」（仅管理员可见此区块）。开启后登录页会出现 **「以游客身份进入」** 按钮，访客点击即可创建游客会话，无需任何凭据。游客共享同一匿名身份、会话有效期较短（约 1 天）。关闭游客模式（或缩小机器人作用域）后立即生效，所有在线游客会话——包括正在连接的实时 WebSocket——会被立刻断开 / 重新限制。
+- **逐项权限（8 个开关，管理员配置）**：除「添加到队列末尾」外**全部默认关闭**，按需逐项放开。
+
+  | 开关 | 字段 | 默认 |
+  |------|------|------|
+  | 添加到队列末尾 | `addToQueue` | **开** |
+  | 添加到下一首 | `playNext` | 关 |
+  | 立即播放（不清空队列） | `playNow` | 关 |
+  | 跳过当前歌曲 | `skip` | 关 |
+  | 暂停/继续/进度/音量 | `transport` | 关 |
+  | 移除/清空队列 | `removeClear` | 关 |
+  | 切换播放模式 / FM | `playMode` | 关 |
+  | 播放整个歌单/专辑 | `playCollection` | 关 |
+
+- **按机器人授权（游客作用域）**：可选择「全部机器人」或指定一份机器人白名单。作用域之外的机器人对游客**不可见、不可控**。
+- **游客始终被禁止**：查看或修改任何设置、管理机器人、设置音乐平台账号 / 凭据、修改音质、收藏歌单、修改密码、访问用户管理与操作审计，以及读取机器人主人的私人歌单 / 私人 FM / 每日推荐等平台账号数据。这些限制不受上面 8 个开关影响，**永远锁死**。
+- **复现 issue #83 的「下一首 only」需求**：在 **设置 → 游客模式** 中关闭「添加到队列末尾」并打开「添加到下一首」，游客便只能把歌曲加到下一首播放。
+
 **如何重置忘记的管理员密码**：
 
 如果你忘记了管理员密码，可以直接编辑 SQLite 数据库 `data/tsmusicbot.db`：
@@ -200,7 +224,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 用户
 
@@ -325,6 +349,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 填入上面的设置即可。
+
 ### 音质等级
 
 | 等级 | 码率 | 格式 | 说明 |
@@ -484,7 +529,7 @@ pip install -U yt-dlp
   "adminPassword": "",
   "adminGroups": [],
   "autoReturnDelay": 300,
-  "autoPauseOnEmpty": true,
+  "autoPauseOnEmpty": false,
   "idleTimeoutMinutes": 0,
   "publicUrl": "",
   "trustProxy": false
@@ -493,7 +538,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` 中设置密码。
 
 ### 反向代理部署注意事项
 
@@ -560,7 +605,7 @@ A：收藏按用户存储在本地 SQLite 数据库（`favorite_playlists` 表
 A：通过 `/bot/<机器人ID>` 打开 WebUI 会把界面锁定到该机器人（顶部显示"专属模式"，刷新后保持），适合把单台机器人的控制页分享给特定用户。点击"退出"可返回多机器人视图。注意：专属链接只是 UI 层的锁定，真正的访问控制由成员权限（机器人白名单）在后端强制。
 
 **Q：机器人播放时突然自动暂停了？**
-A：这是"频道无人时自动暂停"功能：当机器人所在频道没有其他人时会自动暂停，有人加入后自动恢复，避免空播。可在 **设置 → 行为设置** 关闭"频道无人时自动暂停"。
+A：这是"频道无人时自动暂停"功能：当机器人所在频道没有其他人时会自动暂停，有人加入后自动恢复，避免空播。该功能**默认关闭**，仅在你于 **设置 → 行为设置** 开启后生效；如需停用，在同一页面关闭即可。（占用检测依赖 TeamSpeak 的 `clientlist` 命令，部分服务器在频道有其他人时可能查询失败——此时机器人会按"占用情况未知"处理，不会误暂停。）
 
 **Q：如何把某个用户从成员升级为管理员？**
 A：管理员登录后进入 **设置 → 用户管理**，点击对应用户的"提升管理员"按钮即可。降级同理（"降为成员"按钮）。系统会阻止降级最后一位管理员。
@@ -585,12 +630,13 @@ 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 自动续播现支持任意平台。
 
 **Bug 修复**
@@ -609,7 +655,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 自动更新与协议层升级
 

docs/superpowers/plans/2026-06-25-ts-command-permissions.md

@@ -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).

docs/superpowers/specs/2026-05-30-autopause-empty-channel-design.md

@@ -99,3 +99,40 @@ track *we* auto-paused gets auto-resumed; a user-paused track stays paused when
 - No per-bot toggle (global only). No change to idle-disconnect behavior. No new dependency.
 - Reaction relies on events the bot can already see (same-channel members are always in view);
   no extra channel subscription needed.
+
+---
+
+## Update (2026-06): occupancy is event-driven & server-wide, not channel-filtered
+
+Live testing against a real TS3 server (with `@honeybbq/teamspeak-client` 0.2.2)
+invalidated two assumptions above. Recording the corrected model here so nobody
+reintroduces the old design:
+
+- **Default is OFF**, not on. See `getDefaultConfig()` in `src/data/config.ts`
+  and the rationale comment there.
+- **Query commands are unusable when others are present.** `clientlist`,
+  `channellist`, and `channelclientlist` ALL time out (~5–10s) whenever ≥2
+  clients are connected to the **server** (verified even when the two clients
+  are in *different* channels). They succeed only when the bot is the sole
+  client on the whole server. So `getClientsInChannel()` returns `[]` exactly
+  when occupancy matters, and `occupancyFromClientList(0)` returns `null`
+  ("unknown") so callers skip the decision rather than mis-reading it as empty.
+- **PAUSE** therefore only ever fires when the bot becomes alone on the server
+  (the one state where the query works). This is reliable and stays on the
+  query path (`refreshOccupancy()` + the 30s idle poller).
+- **RESUME** is armed directly from the `clientEnter` push event
+  (`shouldResumeOnReturn()` + `_resumeIfReturning()` in `instance.ts`), NOT from
+  a query. Because the bot only auto-pauses while alone, the sole way occupancy
+  can return while `autoPaused` is set is a fresh connection — delivered as
+  `clientEnter`. The resume branch never pauses (userCount is always > 0).
+- **Net semantics:** "pause when the server is empty (bot alone), resume when
+  someone connects." Channel granularity is **impossible** with this library:
+  `clientEnter`'s channel field is always `0` (library reads notify param `cid`
+  but enter-view carries `ctid`), and `clientMoved` delivery is flaky. Do NOT
+  attempt to layer `clientMoved.targetChannelID` channel-accuracy on top — it is
+  systematically wrong for direct-connect clients and reintroduces unreliability.
+  The correct path to true channel scoping is an upstream library fix.
+- **Knock-on:** idle-disconnect shares the same signal and is likewise
+  server-wide. UI copy in `web/src/views/Settings.vue` was updated to say
+  "服务器" rather than "频道" to match. `cmdVote` was intentionally left on the
+  query path (out of scope; switching it would inherit the same timeout).

docs/superpowers/specs/2026-06-24-guest-mode-design.md

@@ -0,0 +1,317 @@
+# Guest mode (login-less WebUI access) — design
+
+**Issue:** [#83](https://github.com/ZHANGTIANYAO1/teamspeak-music-bot/issues/83) — "请求增加 WebUI 鉴权 guest 登录功能"
+**Date:** 2026-06-24
+**Status:** Approved (brainstorm), pending implementation plan
+
+## Scope
+
+Add an optional, **default-OFF** guest mode. When an admin enables it, anyone who can
+reach the WebUI can enter **without logging in** ("以游客身份进入 / Continue as guest")
+and use a restricted subset of playback/queue features. The admin chooses, per
+deployment, exactly what guests may do (a set of toggles) and which bot(s) guests may
+control. Guests can **never** view or change settings, manage bots, set platform
+credentials, change audio quality, or see the user/audit admin panels.
+
+This builds directly on the existing `admin | member` role + capability system
+(`src/data/permissions.ts`, `requirePermission`, `useSession().can()`) and the existing
+append-vs-play-next queue split (`PlayQueue.add` vs `addNext`). It does **not** rebuild
+auth.
+
+The original issue asked specifically that guest song requests go to "下一首" only.
+That exact behavior is reproducible in this design by the admin turning the
+"add to end" toggle **off** and the "play next" toggle **on** — it is one configuration
+of a more general per-ability toggle model (chosen in brainstorm).
+
+## Problem
+
+Today every `/api/*` route past the session router requires a real account
+(`requireAuth`). There is no anonymous/guest path: to let a friend queue a song, an
+admin must create them a `member` account. The maintainer wants a low-friction,
+admin-gated way to let untrusted visitors request music without an account, while
+keeping all administration locked down.
+
+## Decisions (from brainstorm)
+
+1. **Guest = no-login.** A guest is an **anonymous, config-driven synthetic principal**
+   (`role: "guest"`), not a database user with a password. No favorites, no
+   change-password, short-lived session.
+2. **Default OFF**, enforced **server-side** (the guest-session endpoint rejects when
+   the flag is off — never rely on hiding the button).
+3. **Per-ability toggles**, not a single "mode". Every song action and control action is
+   its own admin switch. Default state when guest mode is first enabled: only
+   "add to end of queue" is ON; everything else OFF.
+4. **Per-bot guest scope** (`"all"` or an explicit bot list), mirroring the existing
+   member bot allow-list. Guests cannot see or control out-of-scope bots — including
+   over WebSocket.
+5. **Settings are always hidden AND server-blocked for guests** (view + change), closing
+   the two currently-ungated reads (`GET /api/bot/settings`, `GET /api/music/quality`).
+6. **"Play now" for guests is non-destructive**: insert-next + skip to it, **never** the
+   existing clear-the-whole-queue `/play-song` behavior.
+7. **One unified authorization gate** encapsulates admin/member/guest logic so the
+   existing member/admin capability system is left behavior-unchanged.
+
+## Guest ability model
+
+### Always allowed (baseline read-only — the point of the feature)
+- Browse/search library, playlists, history, song detail, lyrics, cover art.
+- See now-playing and the live queue (REST + WebSocket), **scoped to allowed bots**.
+
+### Always denied (hard locks — not toggles)
+- View **or** change any settings (idle timeout, auto-pause, theme persistence server-side, command prefix, etc.).
+- Bot management (create/edit/delete/start/stop, bot config, avatar, profile).
+- Music-platform login (`/api/auth/*`), audio quality (`/api/music/quality`).
+- User management (`/api/users`), audit log (`/api/audit`), change-password.
+
+### Admin-configurable toggles (`guestMode.permissions.*`, all default `false` except `addToQueue`)
+
+| Flag | 中文 | Default | Backend route(s) gated |
+|---|---|---|---|
+| `addToQueue` | 添加到队列末尾 | **true** | `POST /:botId/add`, `/add-song`, `/add-by-id` |
+| `playNext` | 添加到下一首 | false | `POST /:botId/play-next-song` |
+| `playNow` | 立即播放（不清空队列） | false | new guest-safe play-now (insert-next + skip) |
+| `skip` | 跳过当前歌曲 | false | `POST /:botId/next` |
+| `transport` | 暂停/继续/进度/音量 | false | `POST /:botId/pause`, `/resume`, `/seek`, `/volume` |
+| `removeClear` | 移除/清空队列 | false | `DELETE /:botId/queue/:index`, `POST /:botId/clear` |
+| `playMode` | 切换播放模式 / FM | false | `POST /:botId/mode`, `/fm` |
+
+Notes:
+- Routes with **no** guest flag (e.g. `/prev`, `/stop`, `/play-song`, `/play-playlist`,
+  `/play-album`, `/play-at`, all of `/api/bot/*`, `/api/auth/*`, settings, users, audit)
+  are **never** reachable by guests — the gate denies any guest without an explicit flag.
+  This is the safe default: new routes are guest-denied unless deliberately opted in.
+- `/play-song`, `/play-playlist`, `/play-album` call `queue.clear()` and must stay
+  guest-denied regardless of toggles (they would wipe everyone's queue).
+
+## Config schema (`src/data/config.ts`)
+
+```ts
+export interface GuestPermissions {
+  addToQueue: boolean;   // append to end
+  playNext: boolean;     // 下一首 (insert after current)
+  playNow: boolean;      // 立即播放: insert-next + skip-to-it (non-destructive)
+  skip: boolean;         // skip current track
+  transport: boolean;    // pause/resume/seek/volume
+  removeClear: boolean;  // remove a queue item / clear the queue
+  playMode: boolean;     // play mode (shuffle/repeat) + FM
+}
+
+export interface GuestModeConfig {
+  enabled: boolean;          // master switch, default false
+  bots: "all" | string[];    // per-bot scope (botIds); default "all"
+  permissions: GuestPermissions;
+}
+
+// added to BotConfig:
+guestMode: GuestModeConfig;
+```
+
+`getDefaultConfig()` returns:
+```ts
+guestMode: {
+  enabled: false,
+  bots: "all",
+  permissions: {
+    addToQueue: true, playNext: false, playNow: false,
+    skip: false, transport: false, removeClear: false, playMode: false,
+  },
+}
+```
+
+**Merge hardening:** `loadConfig` currently does a shallow `{...defaults, ...partial}`,
+which would drop `guestMode` sub-keys if a saved config only contains a partial
+`guestMode`. `loadConfig` must **deep-merge `guestMode`** (and its `permissions`) over
+the defaults so missing sub-keys are back-filled. Covered by a `config.test.ts` case.
+
+**Bot deletion:** when a bot is removed, prune its id from `guestMode.bots` (if it's an
+array) and persist — mirrors `PermissionStore.pruneBot(botId)` for members. Done in the
+same `BotManager.removeBot` path that already prunes member access.
+
+## Backend design
+
+### Synthetic guest principal & session entry
+- **Role union widened** to `"admin" | "member" | "guest"` (`UserRole` in
+  `src/data/users.ts`, the `req.user` augmentation in `requireAuth.ts`, the frontend
+  `User` type, and the role badge in Navbar).
+- **Reserved guest user row.** A single fixed row (e.g. id `"__guest__"`, role `"guest"`,
+  an unusable password hash, username e.g. `"guest"`) is created idempotently by
+  migration. It exists only to satisfy the `sessions.userId` FK and the
+  `validateAndTouch` JOIN; it is excluded from user-management listings and the
+  last-admin guards (those count `role = 'admin'` only, so guests don't interfere).
+- **Guest login endpoint:** `POST /api/session/guest`, mounted in the **public** block
+  (before `csrfOriginCheck`/`requireAuth`, like `/login` and `/setup`), rate-limited.
+  - If `config.guestMode.enabled` is false → `403 guest mode disabled`.
+  - Else `sessions.createSession("__guest__")` and set the same `tsmb_session` httpOnly
+    cookie. **Guest sessions use a short TTL** (e.g. `GUEST_SESSION_TTL_MS`, ~24h) and
+    **bypass `MAX_SESSIONS_PER_USER`** for the guest principal (otherwise guest #11
+    would evict guest #1). Expired guest sessions are already deleted on validation; an
+    optional periodic sweep can prune stale ones.
+- **Disable = logout.** In `createRequireAuth`/`validateSession`, if a validated session
+  has `role === "guest"` but `config.guestMode.enabled` is now false, treat it as
+  unauthenticated (401). So flipping guest mode off immediately ends guest access.
+- **Expose availability:** extend `GET /api/session/needs-setup` (or add a sibling
+  `GET /api/session/guest-config`) to return `guestAllowed: boolean` so the **public**
+  Login page can decide whether to show the guest button. This must not leak any other
+  config.
+
+### Permission resolution
+`resolvePermissionContext` gains a `guest` branch. Signature extended to receive the
+live guest config:
+```ts
+resolvePermissionContext(role, userId, store, guestConfig?) => {
+  admin  → { capabilities: all CAPABILITIES, bots: "all" }
+  member → stored caps + stored bots            // unchanged
+  guest  → {
+    capabilities: new Set(),                     // holds NO member capabilities
+    bots: guestConfig.bots === "all" ? "all" : new Set(guestConfig.bots),
+    guest: guestConfig.permissions,              // resolved per-request from live config
+  }
+}
+```
+`PermissionContext` and `req.user` gain an optional `guest?: GuestPermissions`. Because
+`req.user` is rebuilt per request, toggling a permission or the bot scope takes effect on
+the guest's next request (no re-login).
+
+### Unified authorization gate (`src/web/middleware/authorize.ts`, new)
+Replaces `requirePermission('x')` on **guest-reachable** routes:
+```ts
+authorize({ capability?: Capability, guestFlag?: keyof GuestPermissions })
+  // 401 if no req.user
+  // admin  → next()
+  // guest  → (req.user.guest?.[guestFlag] === true) ? next() : 403   // also 403 if no guestFlag
+  // member → (capability && req.user.capabilities.has(capability)) ? next() : 403
+```
+- Member/admin semantics are **identical** to today's `requirePermission`.
+- A route with no `guestFlag` is automatically guest-denied (safe default).
+- `requireBotAccess` is unchanged and already enforces the guest `bots` scope (guests
+  flow through `req.user.bots`).
+- `requireAdmin` is unchanged (guests are non-admin → 403), so `/api/users` and
+  `/api/audit` stay locked.
+
+### Route changes (`src/web/api/player.ts`, `bot.ts`, `music.ts`)
+- Re-express guest-reachable player routes via `authorize({ capability, guestFlag })`:
+  - `/add`, `/add-song`, `/add-by-id` → `{ capability: "player.queue", guestFlag: "addToQueue" }`
+  - `/play-next-song` → `{ capability: "player.control", guestFlag: "playNext" }`
+    (members keep `player.control`; guests pass only via `playNext`)
+  - new guest-safe **play-now** → `{ capability: "player.control", guestFlag: "playNow" }`
+  - `/next` → `{ capability: "player.control", guestFlag: "skip" }`
+  - `/pause`,`/resume`,`/seek`,`/volume` → `{ capability: "player.control", guestFlag: "transport" }`
+  - `DELETE /queue/:index`, `/clear` → `{ capability: "player.queue", guestFlag: "removeClear" }`
+  - `/mode`, `/fm` → `{ capability: "player.control", guestFlag: "playMode" }`
+  - everything else stays `authorize({ capability })` (no guest flag) → guest-denied.
+- **Guest-safe play-now**: a new behavior (own route, e.g. `POST /:botId/play-now`, or a
+  `mode:"now"` branch) that does `queue.addNext(song)` then advances to it (skip into the
+  inserted track) — **no `queue.clear()`**. Members/admins may also use it; the existing
+  destructive `/play-song` stays for the normal ▶ in non-guest UI. Exact wiring decided
+  in the plan.
+- **Close ungated reads against guests:** `GET /api/bot/settings` and
+  `GET /api/music/quality` currently have no guard, so a guest could read config. Add a
+  small `requireNotGuest` guard (allow `admin` + `member`, deny `guest` → 403). This
+  **does not change member/admin behavior** — members keep their current read access; only
+  guests are newly denied. (Deliberately not a new member capability, to avoid touching
+  member semantics.)
+
+### WebSocket (`src/web/websocket.ts`, `src/web/server.ts`)
+- Guests authenticate over the WS upgrade unchanged (session cookie). 
+- **Add per-client bot-scope filtering** for guests: the upgrade handler already stamps
+  `ws.userId`; also resolve and stamp the client's bot scope (`"all"` or a Set). In
+  `setupWebSocket`, when sending `init` and broadcasting `stateChange` /
+  `botConnected/Disconnected/Removed`, **filter to bots the client may see**. For guests
+  with a scoped `bots` list, out-of-scope bots are omitted. Admin/member payloads are
+  unchanged (they resolve to `"all"` or their existing member scope — to avoid changing
+  member behavior, filtering may be applied **only when the client is a guest**; decided
+  in the plan).
+
+### Settings write (`POST /api/bot/settings`)
+Extend the existing settings writer (today only idle-timeout + auto-pause) to also accept
+and persist the `guestMode` block (admin-only via `bot.manage`/`requireAdmin`), calling
+`saveConfig`. Live effect: subsequent guest requests read the updated in-memory config.
+
+## Frontend design
+
+- **`useSession.ts`**: extend `User` with `role:'guest'` and a `guest?: GuestPermissions`
+  field (from `/api/session/me`). Add `isGuest` computed and `guestCan(flag)`; make `can`
+  guest-aware where it maps cleanly, but UI gating for guest-specific actions uses
+  `guestCan('addToQueue' | 'playNext' | ...)`. `canControlBot` already enforces the bot
+  scope and works for guests via the `bots` field.
+- **Login page (`Login.vue`)**: when `guestAllowed`, show a prominent
+  "以游客身份进入 / Continue as guest" button calling a new `session.continueAsGuest()`
+  → `POST /api/session/guest` → refresh → redirect to `?next` or home.
+- **Router (`web/src/router/index.ts`)**: in the global `beforeEach`, block guests from
+  `/settings` and `/setup` (redirect to home). Default-off ⇒ when not a guest, behavior
+  is unchanged.
+- **Navbar (`Navbar.vue`)**: hide the settings cog for guests; add a `游客` role badge
+  branch; the bot selector already filters via `canControlBot`, so scoped guests only see
+  allowed bots.
+- **App shell (`App.vue`)**: hide the mobile `/settings` tab for guests; the mini-player
+  transport reduces to the guest's allowed actions.
+- **SongCard / Queue / Player**: gate each action button by the matching `guestCan(flag)`
+  (e.g. show ▶/下一首/添加 per `playNow`/`playNext`/`addToQueue`; show skip/transport/
+  remove/clear/mode per their flags). Buttons a guest lacks are hidden, mirroring how
+  `Queue.vue` already gates on `can('player.queue')` / `can('player.control')`.
+- **Settings → Guest mode admin section (`Settings.vue`)**: new admin-only panel: a
+  master enable switch, the 7 permission checkboxes (with 中文 labels), and a bot scope
+  control (an "全部机器人 / all bots" toggle + per-bot checkboxes) reusing the existing
+  member permission-editor bot allow-list UI. Saving calls `POST /api/bot/settings` with
+  the `guestMode` block.
+
+## Defaults, migration & backward-compat
+
+- `getDefaultConfig().guestMode.enabled = false` ⇒ **no behavior change** on upgrade;
+  existing installs see nothing until an admin opts in.
+- Migration adds the reserved `__guest__` user row idempotently (guarded like the
+  existing `backfillMemberPermissions` `schema_meta` marker) and does **not** grant it
+  any `user_permissions` (guest authorization is config-driven, not row-driven).
+- `loadConfig` deep-merges `guestMode` so older config files gain the new block with
+  defaults.
+- Member/admin flows, capabilities, and the backfill are untouched.
+
+## Testing (TDD)
+
+- **Config**: `getDefaultConfig` includes `guestMode` default-off; `loadConfig`
+  deep-merges a partial `guestMode` (missing sub-keys back-filled); round-trips through
+  `saveConfig`.
+- **`resolvePermissionContext` guest branch**: empty member capabilities; `bots` `"all"`
+  vs scoped Set; `guest` permissions object passthrough.
+- **`authorize` gate**: admin bypass; member has/lacks capability → 200/403 (regression
+  parity with `requirePermission`); guest allowed only when the specific flag is true;
+  guest with no flag on a route → 403; guest on settings reads → 403.
+- **Enforcement (mirror `permissions-enforcement.test.ts`)**: each toggle independently
+  opens exactly its route(s) for a guest and nothing else; `/play-song`/`/play-playlist`/
+  `/play-album` always 403 for guests; per-bot scope: guest 403 on out-of-scope `:botId`.
+- **Session entry**: `POST /api/session/guest` → 403 when disabled, mints guest session
+  when enabled; guest session bypasses `MAX_SESSIONS_PER_USER`; disabling guest mode
+  invalidates existing guest sessions (401); guest TTL shorter than member TTL.
+- **WS scope**: guest receives only in-scope bots' `init`/`stateChange`; reject upgrade
+  unchanged for no cookie.
+- **Frontend** (where covered): `guestCan` gating; router blocks `/settings` for guests.
+
+## Non-goals (YAGNI)
+
+- No guest accounts/usernames, passwords, favorites, or persistence per guest.
+- No per-guest individual identity or rate-limiting beyond the existing IP rate limits
+  (a basic abuse guard on `/api/session/guest` is in; richer abuse controls are future).
+- No change to the `admin | member` capability semantics; guest is an additive,
+  config-driven third principal.
+- No chat-command (TeamSpeak `!add`/`!playnext`) changes — guest mode is **WebUI-only**
+  (the issue is explicitly about WebUI 鉴权).
+- Per-guest bot scoping beyond a single shared guest scope is out of scope (one guest
+  scope applies to all guests).
+
+## Key files touched
+
+Backend: `src/data/config.ts` (+test), `src/data/permissions.ts` (+test),
+`src/data/users.ts` (role union, reserved guest row), `src/data/database.ts` (migration),
+`src/data/sessions.ts` (guest TTL + cap bypass), `src/web/middleware/authorize.ts` (new,
++test), `src/web/middleware/requireNotGuest.ts` (new, small — for the config reads),
+`src/web/api/session.ts` (guest endpoint, `/me`, `needs-setup`),
+`src/web/api/player.ts` (re-gate + guest play-now), `src/web/api/bot.ts` (settings
+read-lock + guestMode write), `src/web/api/music.ts` (quality read-lock),
+`src/web/server.ts` + `src/web/websocket.ts` (WS scope), `src/web/auth/validateSession.ts`
+(guest disable→401), enforcement tests.
+
+Frontend: `web/src/composables/useSession.ts`, `web/src/views/Login.vue`,
+`web/src/router/index.ts`, `web/src/components/Navbar.vue`, `web/src/App.vue`,
+`web/src/components/SongCard.vue`, `web/src/components/Queue.vue`,
+`web/src/components/Player.vue`, `web/src/views/Settings.vue`,
+`web/src/stores/player.ts`.

docs/superpowers/specs/2026-06-25-ts-command-permissions-design.md

@@ -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).

src/audio/queue.ts

@@ -10,7 +10,7 @@ export interface QueuedSong {
   name: string;
   artist: string;
   album: string;
-  platform: "netease" | "qq" | "bilibili" | "youtube";
+  platform: "netease" | "qq" | "bilibili" | "youtube" | "local";
   url?: string; // resolved lazily at play time
   coverUrl: string;
   duration: number; // seconds

src/bot/auto-pause.test.ts

@@ -1,5 +1,9 @@
 import { describe, it, expect } from "vitest";
-import { decideOccupancyAction } from "./auto-pause.js";
+import {
+  decideOccupancyAction,
+  occupancyFromClientList,
+  shouldResumeOnReturn,
+} from "./auto-pause.js";
 
 describe("decideOccupancyAction", () => {
   it("pauses when empty while playing and enabled", () => {
@@ -27,3 +31,43 @@ describe("decideOccupancyAction", () => {
     expect(decideOccupancyAction("paused", true, false, 1)).toBe("resume");
   });
 });
+
+describe("occupancyFromClientList", () => {
+  it("returns null when the query failed (0 clients — bot itself is always present)", () => {
+    // This is the bug fix: a clientlist timeout makes getClientsInChannel()
+    // return [], which must be treated as "unknown", NOT as an empty channel.
+    expect(occupancyFromClientList(0)).toBeNull();
+  });
+  it("returns 0 other users when only the bot is in the channel", () => {
+    expect(occupancyFromClientList(1)).toBe(0);
+  });
+  it("excludes the bot itself from the count", () => {
+    expect(occupancyFromClientList(2)).toBe(1);
+    expect(occupancyFromClientList(5)).toBe(4);
+  });
+  it("never yields a negative count (guards the -1 that caused false pauses)", () => {
+    expect(occupancyFromClientList(-3)).toBeNull();
+  });
+});
+
+describe("shouldResumeOnReturn (event-driven auto-resume)", () => {
+  it("resumes when we auto-paused and are still paused", () => {
+    // The reported gap: someone returns after an auto-pause. clientlist can't
+    // confirm it (it times out while they're present), so we resume from the
+    // clientEnter event alone.
+    expect(shouldResumeOnReturn(true, "paused")).toBe(true);
+  });
+  it("does NOT resume a track the user paused by hand", () => {
+    expect(shouldResumeOnReturn(false, "paused")).toBe(false);
+  });
+  it("does nothing if already playing (e.g. the bot's own enter at connect)", () => {
+    // autoPaused is cleared to false on connect, so the bot's own clientEnter
+    // is a no-op; this also covers the playing/auto-paused-flag-stale case.
+    expect(shouldResumeOnReturn(false, "playing")).toBe(false);
+    expect(shouldResumeOnReturn(true, "playing")).toBe(false);
+  });
+  it("does nothing when idle (nothing to resume)", () => {
+    expect(shouldResumeOnReturn(true, "idle")).toBe(false);
+    expect(shouldResumeOnReturn(false, "idle")).toBe(false);
+  });
+});

src/bot/auto-pause.ts

@@ -1,6 +1,25 @@
 export type PlayerStateName = "idle" | "playing" | "paused";
 export type OccupancyAction = "pause" | "resume" | "none";
 
+/**
+ * Convert a channel client-list length into the number of *other* users, or
+ * `null` when occupancy can't be determined.
+ *
+ * A connected bot is always a member of its own channel, so a valid query
+ * returns at least 1 (the bot itself). A length of 0 therefore does NOT mean
+ * "empty channel" — it means the underlying `clientlist` query failed (e.g. the
+ * full-client `clientlist` command times out when other clients are present,
+ * and `getClientsInChannel()` returns `[]` on error). Treating that failure as
+ * "empty" is what caused playback to auto-pause within seconds whenever a
+ * listener was actually in the channel. When the result is indeterminate we
+ * return `null` so callers skip the auto-pause/idle decision entirely rather
+ * than mis-reading an unknown state as empty.
+ */
+export function occupancyFromClientList(clientCount: number): number | null {
+  if (clientCount <= 0) return null; // query failed → occupancy unknown
+  return clientCount - 1; // exclude the bot itself
+}
+
 /**
  * Decide what auto-pause should do given channel occupancy.
  * - empty (userCount <= 0): pause iff enabled and currently playing.
@@ -21,3 +40,28 @@ export function decideOccupancyAction(
   if (autoPaused && playerState === "paused") return "resume";
   return "none";
 }
+
+/**
+ * Whether a client-presence push event (a `clientEnter`) should trigger an
+ * auto-resume, WITHOUT consulting a clientlist query.
+ *
+ * Why event-driven: the full-client `clientlist`/`channellist` commands time
+ * out whenever ≥2 clients are connected to the server (a library limitation) —
+ * which is exactly the moment a listener returns. So occupancy cannot be
+ * re-queried to confirm the return; we must act on the push event itself.
+ * This is sound because the bot only ever auto-pauses while it is alone on the
+ * server (the sole state in which the occupancy query succeeds and pause
+ * fires). Therefore, while `autoPaused` is true, the only way occupancy can
+ * return is a fresh connection — delivered reliably as `clientEnter`.
+ *
+ * Gating on `autoPaused` (not merely "paused") guarantees we never revive a
+ * track the user paused by hand, and makes the bot's own `clientEnter` at
+ * connect a no-op (autoPaused is cleared to false on connect). This predicate
+ * NEVER pauses — pause stays on the authoritative clientlist path.
+ */
+export function shouldResumeOnReturn(
+  autoPaused: boolean,
+  playerState: PlayerStateName,
+): boolean {
+  return autoPaused && playerState === "paused";
+}

src/bot/commands.test.ts

@@ -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);
+  });
+});

src/bot/commands.ts

@@ -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)));
+}

src/bot/instance.test.ts

@@ -0,0 +1,212 @@
+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
+// (`playGate`). So we exercise the ACTUAL shipped method via its prototype,
+// bound to a minimal object carrying just that field. This proves the real
+// serializer logic without standing up a full bot.
+type Gate = { playGate: Promise<unknown> };
+const runExclusive = BotInstance.prototype.runExclusive as <T>(
+  this: Gate,
+  fn: () => Promise<T>,
+) => Promise<T>;
+
+function makeGate(): Gate {
+  return { playGate: Promise.resolve() };
+}
+
+/** An explicit, timer-free deferred so ordering is deterministic. */
+function deferred<T = void>() {
+  let resolve!: (value: T) => void;
+  let reject!: (reason?: unknown) => void;
+  const promise = new Promise<T>((res, rej) => {
+    resolve = res;
+    reject = rej;
+  });
+  return { promise, resolve, reject };
+}
+
+describe("BotInstance.runExclusive — serialization", () => {
+  it("does not start fnB until fnA settles", async () => {
+    const gate = makeGate();
+    const order: string[] = [];
+    const gateA = deferred();
+
+    const pA = runExclusive.call(gate, async () => {
+      order.push("A-start");
+      await gateA.promise; // suspend A until we explicitly release it
+      order.push("A-end");
+    });
+
+    const pB = runExclusive.call(gate, async () => {
+      order.push("B-start");
+      order.push("B-end");
+    });
+
+    // Give the microtask queue a chance: B must NOT have started while A is
+    // still suspended on gateA.
+    await Promise.resolve();
+    await Promise.resolve();
+    expect(order).toEqual(["A-start"]);
+
+    gateA.resolve();
+    await pA;
+    await pB;
+
+    expect(order).toEqual(["A-start", "A-end", "B-start", "B-end"]);
+  });
+
+  it("runs fnB even if fnA rejects (chain survives rejection)", async () => {
+    const gate = makeGate();
+    const order: string[] = [];
+    const gateA = deferred();
+
+    const pA = runExclusive.call(gate, async () => {
+      order.push("A-start");
+      await gateA.promise;
+      throw new Error("A blew up");
+    });
+
+    const pB = runExclusive.call(gate, async () => {
+      order.push("B-start");
+      order.push("B-end");
+      return "B-result";
+    });
+
+    await Promise.resolve();
+    await Promise.resolve();
+    expect(order).toEqual(["A-start"]);
+
+    gateA.reject(new Error("A blew up"));
+    await expect(pA).rejects.toThrow("A blew up");
+
+    // B still runs, only after A has fully settled.
+    await expect(pB).resolves.toBe("B-result");
+    expect(order).toEqual(["A-start", "B-start", "B-end"]);
+  });
+
+  it("preserves call order across three serialized tasks", async () => {
+    const gate = makeGate();
+    const order: string[] = [];
+    const tasks = ["X", "Y", "Z"];
+    const promises = tasks.map((t) =>
+      runExclusive.call(gate, async () => {
+        order.push(`${t}-start`);
+        await Promise.resolve();
+        order.push(`${t}-end`);
+      }),
+    );
+
+    await Promise.all(promises);
+
+    expect(order).toEqual([
+      "X-start",
+      "X-end",
+      "Y-start",
+      "Y-end",
+      "Z-start",
+      "Z-end",
+    ]);
+  });
+});
+
+/** 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);
+  });
+});

src/bot/instance.ts

@@ -9,7 +9,7 @@ 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";
@@ -18,7 +18,14 @@ import type { BotDatabase, ProfileConfig } from "../data/database.js";
 import type { BotConfig } from "../data/config.js";
 import { BotProfileManager } from "./profile.js";
 import type { AvatarStore } from "../data/avatars.js";
-import { decideOccupancyAction } from "./auto-pause.js";
+import {
+  decideOccupancyAction,
+  occupancyFromClientList,
+  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;
@@ -28,6 +35,7 @@ export interface BotInstanceOptions {
   qqProvider: MusicProvider;
   bilibiliProvider: MusicProvider;
   youtubeProvider: MusicProvider;
+  localProvider?: MusicProvider;
   database: BotDatabase;
   config: BotConfig;
   logger: Logger;
@@ -45,6 +53,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 {
@@ -58,6 +68,7 @@ export class BotInstance extends EventEmitter {
   private qqProvider: MusicProvider;
   private bilibiliProvider: MusicProvider;
   private youtubeProvider: MusicProvider;
+  private localProvider: MusicProvider;
   private database: BotDatabase;
   private config: BotConfig;
   private logger: Logger;
@@ -74,6 +85,9 @@ 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) {
     super();
@@ -83,6 +97,7 @@ export class BotInstance extends EventEmitter {
     this.qqProvider = options.qqProvider;
     this.bilibiliProvider = options.bilibiliProvider;
     this.youtubeProvider = options.youtubeProvider;
+    this.localProvider = options.localProvider ?? options.neteaseProvider;
     this.database = options.database;
     this.config = options.config;
     this.logger = options.logger.child({ botId: this.id });
@@ -135,6 +150,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) => {
@@ -149,6 +199,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
@@ -166,16 +218,47 @@ export class BotInstance extends EventEmitter {
 
     // React near-instantly to channel membership changes. The 30s idle
     // poller remains the fallback if any of these events are missed.
-    this.tsClient.on("clientEnter", () => void this.refreshOccupancy());
+    //
+    // clientEnter additionally arms auto-RESUME directly from the event,
+    // because the occupancy query (clientlist) times out whenever another
+    // client is present — i.e. exactly when a listener returns — so it cannot
+    // be used to confirm the return. See _resumeIfReturning().
+    this.tsClient.on("clientEnter", () => {
+      this._resumeIfReturning();
+      void this.refreshOccupancy();
+    });
     this.tsClient.on("clientLeave", () => void this.refreshOccupancy());
     this.tsClient.on("clientMoved", () => void this.refreshOccupancy());
   }
 
+  /**
+   * Resume playback when a listener returns after an auto-pause, driven by the
+   * clientEnter push event rather than a (timing-out) occupancy query.
+   *
+   * We only auto-pause while alone on the server, so `autoPaused` is a reliable
+   * "paused because empty" flag; any client appearing while it's set means a
+   * listener returned. Delegating to handleOccupancy(1) routes through
+   * decideOccupancyAction (resume iff autoPaused && paused) and also cancels the
+   * idle-disconnect timer. This path NEVER pauses — userCount is always > 0 —
+   * so a spurious or unrelated enter can only (harmlessly) resume, never stop
+   * playback. Pause remains exclusively on the authoritative clientlist path.
+   */
+  private _resumeIfReturning(): void {
+    if (!this.connected) return;
+    if (shouldResumeOnReturn(this.autoPaused, this.player.getState())) {
+      this.handleOccupancy(1);
+    }
+  }
+
   private async refreshOccupancy(): Promise<void> {
     if (!this.connected) return;
     try {
       const clients = await this.tsClient.getClientsInChannel();
-      this.handleOccupancy(clients.length - 1);
+      // A 0-length result means the clientlist query failed (the bot is always
+      // in its own channel) — occupancy is unknown, so don't act. Acting on it
+      // would mis-read it as "empty" and falsely auto-pause / idle-disconnect.
+      const userCount = occupancyFromClientList(clients.length);
+      if (userCount !== null) this.handleOccupancy(userCount);
     } catch {
       // ignore — the 30s poll is the fallback
     }
@@ -199,6 +282,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;
@@ -229,8 +314,9 @@ export class BotInstance extends EventEmitter {
       if (!this.connected) return;
       try {
         const clients = await this.tsClient.getClientsInChannel();
-        const userCount = clients.length - 1; // 排除 bot 自身
-        this.handleOccupancy(userCount);
+        // null = clientlist query failed (occupancy unknown) → don't act.
+        const userCount = occupancyFromClientList(clients.length);
+        if (userCount !== null) this.handleOccupancy(userCount);
       } catch { /* ignore */ }
       setTimeout(poll, 30_000);
     };
@@ -285,8 +371,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(
@@ -311,6 +406,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
@@ -394,9 +524,10 @@ export class BotInstance extends EventEmitter {
     }
   }
 
-  getProviderFor(platform: "netease" | "qq" | "bilibili" | "youtube"): MusicProvider {
+  getProviderFor(platform: "netease" | "qq" | "bilibili" | "youtube" | "local"): MusicProvider {
     if (platform === "bilibili") return this.bilibiliProvider;
     if (platform === "youtube") return this.youtubeProvider;
+    if (platform === "local") return this.localProvider;
     return platform === "qq" ? this.qqProvider : this.neteaseProvider;
   }
 
@@ -418,14 +549,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;
       }
@@ -441,8 +576,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;
@@ -531,6 +668,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 });
@@ -539,6 +680,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}`;
   }
@@ -618,6 +763,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");
@@ -676,6 +822,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");
@@ -689,6 +836,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}`;
   }
@@ -748,6 +898,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) {
@@ -755,6 +906,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"}`;
   }
@@ -783,6 +935,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) {
@@ -790,6 +943,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"}`;
   }
@@ -812,6 +966,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 });
@@ -823,6 +978,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 ?? ""}`;
@@ -845,6 +1001,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) {
@@ -855,6 +1012,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"}`;
   }
@@ -960,10 +1118,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) {
@@ -1003,6 +1161,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;
     }
   }
@@ -1015,6 +1177,14 @@ export class BotInstance extends EventEmitter {
     return input;
   }
 
+  /** Serialize queue-mutation + play sequences so concurrent requests can't
+   *  interleave (audible track must match queue.currentIndex). */
+  runExclusive<T>(fn: () => Promise<T>): Promise<T> {
+    const next = this.playGate.then(fn, fn);
+    this.playGate = next.catch(() => {});
+    return next;
+  }
+
   getStatus(): BotStatus {
     return {
       id: this.id,
@@ -1027,6 +1197,7 @@ export class BotInstance extends EventEmitter {
       volume: this.player.getVolume(),
       playMode: this.queue.getMode(),
       elapsed: this.player.getElapsed(),
+      effectiveDuration: this.effectiveDuration,
     };
   }
 

src/bot/manager.test.ts

@@ -0,0 +1,87 @@
+import { describe, it, expect, afterEach } from "vitest";
+import { join } from "node:path";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { BotManager } from "./manager.js";
+import { createDatabase, type BotDatabase } from "../data/database.js";
+import { createPermissionStore } from "../data/permissions.js";
+import { getDefaultConfig, loadConfig, saveConfig, type BotConfig } from "../data/config.js";
+import type { Logger } from "../logger.js";
+import type { MusicProvider } from "../music/provider.js";
+import type { AvatarStore } from "../data/avatars.js";
+
+// removeBot only calls logger.info; provide the full shape it could touch.
+const stubLogger = {
+  info() {},
+  warn() {},
+  error() {},
+  debug() {},
+  child() {
+    return stubLogger;
+  },
+} as unknown as Logger;
+
+describe("BotManager.removeBot — guest scope pruning", () => {
+  const dirs: string[] = [];
+  let db: BotDatabase;
+
+  function makeTmpConfigPath(): string {
+    const dir = mkdtempSync(join(tmpdir(), "tsmusicbot-manager-test-"));
+    dirs.push(dir);
+    return join(dir, "config.json");
+  }
+
+  function makeManager(config: BotConfig, configPath: string): BotManager {
+    db = createDatabase(":memory:");
+    const permissions = createPermissionStore(db.db);
+    saveConfig(configPath, config);
+    return new BotManager(
+      {} as unknown as MusicProvider,
+      {} as unknown as MusicProvider,
+      {} as unknown as MusicProvider,
+      db,
+      config,
+      stubLogger,
+      {} as unknown as AvatarStore,
+      permissions,
+      configPath
+    );
+  }
+
+  afterEach(() => {
+    try {
+      db?.close();
+    } catch {
+      /* ignore */
+    }
+    for (const d of dirs) {
+      rmSync(d, { recursive: true, force: true });
+    }
+    dirs.length = 0;
+  });
+
+  it("prunes a deleted bot from guestMode.bots (array) and persists", async () => {
+    const configPath = makeTmpConfigPath();
+    const config = getDefaultConfig();
+    config.guestMode.bots = ["botA", "botB"];
+    const manager = makeManager(config, configPath);
+
+    await manager.removeBot("botA");
+
+    expect(config.guestMode.bots).toEqual(["botB"]);
+    // Persisted file must also reflect the prune.
+    expect(loadConfig(configPath).guestMode.bots).toEqual(["botB"]);
+  });
+
+  it('leaves guestMode.bots === "all" unchanged (no crash, no change)', async () => {
+    const configPath = makeTmpConfigPath();
+    const config = getDefaultConfig();
+    config.guestMode.bots = "all";
+    const manager = makeManager(config, configPath);
+
+    await manager.removeBot("botA");
+
+    expect(config.guestMode.bots).toBe("all");
+    expect(loadConfig(configPath).guestMode.bots).toBe("all");
+  });
+});

src/bot/manager.ts

@@ -7,7 +7,7 @@ import {
 import type { MusicProvider } from "../music/provider.js";
 import { YouTubeProvider } from "../music/youtube.js";
 import type { BotDatabase } from "../data/database.js";
-import type { BotConfig } from "../data/config.js";
+import { saveConfig, type BotConfig } from "../data/config.js";
 import type { Logger } from "../logger.js";
 
 import type { ServerProtocol } from "../ts-protocol/client.js";
@@ -57,6 +57,7 @@ export interface CreateBotParams {
   queryPort?: number;
   nickname: string;
   defaultChannel?: string;
+  channelId?: string;
   channelPassword?: string;
   autoStart?: boolean;
   /** Force TS3 or TS6 protocol; omit or "unknown" for auto-detect. */
@@ -73,11 +74,13 @@ export class BotManager extends EventEmitter {
   private qqProvider: MusicProvider;
   private bilibiliProvider: MusicProvider;
   private youtubeProvider: MusicProvider;
+  private localProvider: MusicProvider;
   private database: BotDatabase;
   private config: BotConfig;
   private logger: Logger;
   private avatarStore: AvatarStore;
   private permissions: PermissionStore;
+  private configPath: string;
 
   constructor(
     neteaseProvider: MusicProvider,
@@ -87,18 +90,28 @@ export class BotManager extends EventEmitter {
     config: BotConfig,
     logger: Logger,
     avatarStore: AvatarStore,
-    permissions: PermissionStore
+    permissions: PermissionStore,
+    configPath: string,
+    localProvider?: MusicProvider
   ) {
     super();
     this.neteaseProvider = neteaseProvider;
     this.qqProvider = qqProvider;
     this.bilibiliProvider = bilibiliProvider;
     this.youtubeProvider = new YouTubeProvider();
+    this.localProvider = localProvider ?? 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;
     this.avatarStore = avatarStore;
     this.permissions = permissions;
+    this.configPath = configPath;
   }
 
   async createBot(params: CreateBotParams): Promise<BotInstance> {
@@ -113,6 +126,7 @@ export class BotManager extends EventEmitter {
         queryPort: params.queryPort ?? 10011,
         nickname: params.nickname,
         defaultChannel: params.defaultChannel,
+        channelId: params.channelId,
         channelPassword: params.channelPassword,
         serverPassword: params.serverPassword,
         serverProtocol: params.serverProtocol,
@@ -122,6 +136,7 @@ export class BotManager extends EventEmitter {
       qqProvider: this.qqProvider,
       bilibiliProvider: this.bilibiliProvider,
       youtubeProvider: this.youtubeProvider,
+      localProvider: this.localProvider,
       database: this.database,
       config: this.config,
       logger: this.logger,
@@ -138,6 +153,7 @@ export class BotManager extends EventEmitter {
       serverPort: params.serverPort,
       nickname: params.nickname,
       defaultChannel: params.defaultChannel ?? "",
+      channelId: params.channelId ?? "",
       channelPassword: params.channelPassword ?? "",
       autoStart: params.autoStart ?? false,
       serverProtocol: params.serverProtocol ?? "",
@@ -157,6 +173,11 @@ export class BotManager extends EventEmitter {
     }
     this.database.deleteBotInstance(id);
     this.permissions.pruneBot(id);
+    // Prune the deleted bot from the guest scope allow-list (mirrors permissions.pruneBot).
+    if (Array.isArray(this.config.guestMode.bots) && this.config.guestMode.bots.includes(id)) {
+      this.config.guestMode.bots = this.config.guestMode.bots.filter((b) => b !== id);
+      saveConfig(this.configPath, this.config);
+    }
     this.emit("botInstanceRemoved", id);
     this.logger.info({ botId: id }, "Bot instance removed");
   }
@@ -173,6 +194,7 @@ export class BotManager extends EventEmitter {
       serverPort: params.serverPort ?? existing.serverPort,
       nickname: params.nickname ?? existing.nickname,
       defaultChannel: params.defaultChannel ?? existing.defaultChannel,
+      channelId: params.channelId ?? existing.channelId,
       channelPassword: params.channelPassword ?? existing.channelPassword,
       serverProtocol: params.serverProtocol ?? existing.serverProtocol,
       ts6ApiKey: params.ts6ApiKey ?? existing.ts6ApiKey,
@@ -198,6 +220,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`);
@@ -231,6 +265,7 @@ export class BotManager extends EventEmitter {
           // each connect and strips all previously granted groups.
           identity: saved.identity || undefined,
           defaultChannel: saved.defaultChannel || undefined,
+          channelId: saved.channelId || undefined,
           channelPassword: saved.channelPassword || undefined,
           serverPassword: saved.serverPassword || undefined,
           serverProtocol: proto === "ts3" || proto === "ts6" ? proto : undefined,
@@ -240,6 +275,7 @@ export class BotManager extends EventEmitter {
         qqProvider: this.qqProvider,
         bilibiliProvider: this.bilibiliProvider,
         youtubeProvider: this.youtubeProvider,
+        localProvider: this.localProvider,
         database: this.database,
         config: this.config,
         logger: this.logger,
@@ -282,6 +318,7 @@ export class BotManager extends EventEmitter {
           nickname: saved.nickname,
           identity: saved.identity || undefined,
           defaultChannel: saved.defaultChannel || undefined,
+          channelId: saved.channelId || undefined,
           channelPassword: saved.channelPassword || undefined,
           serverPassword: saved.serverPassword || undefined,
           serverProtocol: proto === "ts3" || proto === "ts6" ? proto : undefined,
@@ -291,6 +328,7 @@ export class BotManager extends EventEmitter {
         qqProvider: this.qqProvider,
         bilibiliProvider: this.bilibiliProvider,
         youtubeProvider: this.youtubeProvider,
+        localProvider: this.localProvider,
         database: this.database,
         config: this.config,
         logger: this.logger,

src/data/config.test.ts

@@ -49,7 +49,8 @@ describe("config", () => {
     // defaults should fill in the rest
     expect(loaded.theme).toBe("dark");
     expect(loaded.commandPrefix).toBe("!");
-    expect(loaded.autoPauseOnEmpty).toBe(true);
+    // auto-pause defaults OFF (occupancy detection is unreliable on some servers)
+    expect(loaded.autoPauseOnEmpty).toBe(false);
   });
 
   // --- #86: config.json must live under (and be created in) the persisted data dir ---
@@ -105,3 +106,102 @@ describe("config", () => {
     expect(migrated).toBe(false);
   });
 });
+
+describe("guestMode config", () => {
+  it("defaults to disabled, all-bots, append-only", () => {
+    const c = getDefaultConfig();
+    expect(c.guestMode.enabled).toBe(false);
+    expect(c.guestMode.bots).toBe("all");
+    expect(c.guestMode.permissions).toEqual({
+      addToQueue: true, playNext: false, playNow: false,
+      skip: false, transport: false, removeClear: false, playMode: false,
+      playCollection: false,
+    });
+  });
+
+  it("deep-merges a partial guestMode so missing sub-keys are back-filled", () => {
+    const dir = mkdtempSync(join(tmpdir(), "tsmb-cfg-"));
+    const p = join(dir, "config.json");
+    writeFileSync(p, JSON.stringify({ guestMode: { enabled: true, permissions: { playNext: true } } }));
+    const c = loadConfig(p);
+    expect(c.guestMode.enabled).toBe(true);
+    expect(c.guestMode.bots).toBe("all"); // back-filled
+    expect(c.guestMode.permissions.playNext).toBe(true);
+    expect(c.guestMode.permissions.addToQueue).toBe(true); // back-filled default
+    expect(c.guestMode.permissions.skip).toBe(false); // back-filled default
+    rmSync(dir, { recursive: true, force: true });
+  });
+
+  // --- B1: loadConfig must sanitize a hand-edited/legacy/corrupt guestMode ---
+
+  function loadGuestMode(raw: unknown) {
+    const dir = mkdtempSync(join(tmpdir(), "tsmb-cfg-"));
+    const p = join(dir, "config.json");
+    writeFileSync(p, JSON.stringify(raw));
+    try {
+      return loadConfig(p).guestMode;
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  }
+
+  describe("bots normalization", () => {
+    it("a numeric bots value falls back to the default \"all\" (no crash)", () => {
+      const gm = loadGuestMode({ guestMode: { bots: 5 } });
+      expect(gm.bots).toBe("all");
+    });
+    it("an array bots value is filtered to strings only", () => {
+      const gm = loadGuestMode({ guestMode: { bots: ["a", 2, "b"] } });
+      expect(gm.bots).toEqual(["a", "b"]);
+    });
+    it("the literal \"all\" is preserved", () => {
+      const gm = loadGuestMode({ guestMode: { bots: "all" } });
+      expect(gm.bots).toBe("all");
+    });
+  });
+
+  describe("permissions coercion", () => {
+    it("a non-boolean truthy flag is coerced to false; a real true stays true", () => {
+      const gm = loadGuestMode({ guestMode: { permissions: { skip: 1, playNext: true } } });
+      expect(gm.permissions.skip).toBe(false);
+      expect(gm.permissions.playNext).toBe(true);
+    });
+    it("a string permissions value yields defaults with no numeric index keys", () => {
+      const gm = loadGuestMode({ guestMode: { permissions: "hacked" } });
+      // 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([]);
+  });
+});

src/data/config.ts

@@ -1,5 +1,13 @@
 import { readFileSync, writeFileSync, mkdirSync, existsSync, copyFileSync, rmSync } from "node:fs";
 import { dirname } from "node:path";
+import type { BotAccess, GuestPermissions } from "./permissions.js";
+import { GUEST_PERMISSION_FLAGS } from "./permissions.js";
+
+export interface GuestModeConfig {
+  enabled: boolean;
+  bots: BotAccess; // "all" | string[]
+  permissions: GuestPermissions;
+}
 
 export interface BotConfig {
   webPort: number;
@@ -14,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"
@@ -22,6 +32,7 @@ export interface BotConfig {
   // (nginx/Caddy/Cloudflare). Required for correct protocol/host detection
   // behind HTTPS-terminating proxies.
   trustProxy: boolean;
+  guestMode: GuestModeConfig;
 }
 
 export function getDefaultConfig(): BotConfig {
@@ -36,10 +47,28 @@ export function getDefaultConfig(): BotConfig {
     adminPassword: "",
     adminGroups: [],
     autoReturnDelay: 300,
-    autoPauseOnEmpty: true,
+    // Default OFF: occupancy detection relies on the full-client `clientlist`
+    // command, which is unreliable on some servers (it can time out when other
+    // clients are present). Users can opt in from the web UI.
+    autoPauseOnEmpty: false,
     idleTimeoutMinutes: 0,
+    localAudioEnabled: true,
     publicUrl: "",
     trustProxy: false,
+    guestMode: {
+      enabled: false,
+      bots: "all",
+      permissions: {
+        addToQueue: true,
+        playNext: false,
+        playNow: false,
+        skip: false,
+        transport: false,
+        removeClear: false,
+        playMode: false,
+        playCollection: false,
+      },
+    },
   };
 }
 
@@ -48,7 +77,53 @@ export function loadConfig(path: string): BotConfig {
   try {
     const raw = readFileSync(path, "utf-8");
     const partial = JSON.parse(raw) as Partial<BotConfig>;
-    return { ...defaults, ...partial };
+
+    // Normalize/sanitize guestMode on load. The WRITE path (POST /api/bot/settings)
+    // sanitizes too, but a hand-edited/legacy/corrupt config.json reaches the gate
+    // directly — so coerce it here as well, mirroring that write-path logic.
+    const partialGm = (partial.guestMode ?? {}) as Partial<GuestModeConfig>;
+    const gm: GuestModeConfig = {
+      ...defaults.guestMode,
+      ...partialGm,
+      // bots → "all" | string[]; anything else falls back to the default ("all").
+      bots:
+        partialGm.bots === "all"
+          ? "all"
+          : Array.isArray(partialGm.bots)
+            ? partialGm.bots.filter((id): id is string => typeof id === "string")
+            : defaults.guestMode.bots,
+      // permissions → defaults, then spread ONLY a plain object, then strict-coerce
+      // each known flag to a boolean (drops index keys + non-boolean values).
+      permissions: { ...defaults.guestMode.permissions },
+    };
+    const partialPerms = partialGm.permissions;
+    if (
+      partialPerms !== null &&
+      typeof partialPerms === "object" &&
+      !Array.isArray(partialPerms)
+    ) {
+      Object.assign(gm.permissions, partialPerms);
+    }
+    for (const f of GUEST_PERMISSION_FLAGS) {
+      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 {
     return defaults;
   }

src/data/database.test.ts

@@ -1,5 +1,9 @@
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
 import { describe, it, expect, beforeEach, afterEach } from "vitest";
 import { createDatabase, type BotDatabase, type BotInstance, type PlayHistoryEntry } from "./database.js";
+import { createUserStore, GUEST_USER_ID } from "./users.js";
 
 describe("database", () => {
   let botDb: BotDatabase;
@@ -82,6 +86,7 @@ describe("database", () => {
       serverPort: 9987,
       nickname: "MusicBot",
       defaultChannel: "Music",
+      channelId: "",
       channelPassword: "",
       autoStart: true,
       serverProtocol: "",
@@ -111,6 +116,7 @@ describe("database", () => {
       serverPort: 9987,
       nickname: "MusicBot",
       defaultChannel: "Music",
+      channelId: "",
       channelPassword: "",
       autoStart: false,
       serverProtocol: "",
@@ -131,6 +137,7 @@ describe("database", () => {
       serverPort: 9987,
       nickname: "n",
       defaultChannel: "",
+      channelId: "",
       channelPassword: "",
       autoStart: false,
       serverProtocol: "",
@@ -145,3 +152,28 @@ describe("database", () => {
     expect(botDb.getCustomAvatarPath("bot-1")).toBeNull();
   });
 });
+
+describe("guest principal migration", () => {
+  it("creates exactly one reserved guest row, idempotently", () => {
+    const dir = mkdtempSync(join(tmpdir(), "tsmb-db-"));
+    const p = join(dir, "t.db");
+    const a = createDatabase(p); a.db.close();
+    const b = createDatabase(p); // run again — must not duplicate
+    const row = b.db.prepare("SELECT id, role FROM users WHERE id = ?").get(GUEST_USER_ID) as { id: string; role: string } | undefined;
+    expect(row?.role).toBe("guest");
+    const n = (b.db.prepare("SELECT COUNT(*) AS n FROM users WHERE role='guest'").get() as { n: number }).n;
+    expect(n).toBe(1);
+    b.db.close();
+    rmSync(dir, { recursive: true, force: true });
+  });
+
+  it("guest row does not break first-run detection (countUsers excludes it)", () => {
+    const dir = mkdtempSync(join(tmpdir(), "tsmb-db2-"));
+    const p = join(dir, "t.db");
+    const d = createDatabase(p);
+    const users = createUserStore(d.db);
+    expect(users.countUsers()).toBe(0); // guest excluded → still needs setup
+    d.db.close();
+    rmSync(dir, { recursive: true, force: true });
+  });
+});

src/data/database.ts

@@ -1,5 +1,6 @@
 import Database from "better-sqlite3";
 import { CAPABILITIES, BOTS_ALL } from "./permissions.js";
+import { GUEST_USER_ID, GUEST_USERNAME } from "./users.js";
 
 export interface PlayHistoryEntry {
   botId: string;
@@ -7,7 +8,7 @@ export interface PlayHistoryEntry {
   songName: string;
   artist: string;
   album: string;
-  platform: "netease" | "qq" | "bilibili" | "youtube";
+  platform: "netease" | "qq" | "bilibili" | "youtube" | "local";
   coverUrl: string;
 }
 
@@ -23,6 +24,7 @@ export interface BotInstance {
   serverPort: number;
   nickname: string;
   defaultChannel: string;
+  channelId: string;
   channelPassword: string;
   autoStart: boolean;
   /** "ts3" | "ts6" | "" (empty = auto-detect) */
@@ -96,6 +98,9 @@ function migrateSchema(db: Database.Database): void {
   if (!names.includes("serverPassword")) {
     db.exec("ALTER TABLE bot_instances ADD COLUMN serverPassword TEXT NOT NULL DEFAULT ''");
   }
+  if (!names.includes("channelId")) {
+    db.exec("ALTER TABLE bot_instances ADD COLUMN channelId TEXT NOT NULL DEFAULT ''");
+  }
   // Profile feature flags
   const profileCols = [
     "profile_avatar_enabled",
@@ -142,6 +147,7 @@ function initTables(db: Database.Database): void {
       serverPort INTEGER NOT NULL,
       nickname TEXT NOT NULL,
       defaultChannel TEXT NOT NULL,
+      channelId TEXT NOT NULL DEFAULT '',
       channelPassword TEXT NOT NULL,
       autoStart INTEGER NOT NULL DEFAULT 0,
       serverProtocol TEXT NOT NULL DEFAULT '',
@@ -236,6 +242,19 @@ export function backfillMemberPermissions(db: Database.Database): void {
   tx();
 }
 
+/**
+ * Ensure the reserved guest principal exists. Idempotent via the PK on
+ * `users.id`. This row only backs login-less guest sessions; it is excluded
+ * from countUsers()/listUsers() so it never interferes with first-run setup
+ * or the user-management UI, and holds an unusable password hash.
+ */
+export function ensureGuestUser(db: Database.Database): void {
+  const now = Date.now();
+  db.prepare(
+    "INSERT OR IGNORE INTO users (id, username, passwordHash, createdAt, updatedAt, role) VALUES (?, ?, '!', ?, ?, 'guest')"
+  ).run(GUEST_USER_ID, GUEST_USERNAME, now, now);
+}
+
 export function createDatabase(dbPath: string): BotDatabase {
   const db = new Database(dbPath);
   db.pragma("journal_mode = WAL");
@@ -243,6 +262,7 @@ export function createDatabase(dbPath: string): BotDatabase {
   initTables(db);
   migrateSchema(db);
   backfillMemberPermissions(db);
+  ensureGuestUser(db);
 
   const insertHistory = db.prepare(`
     INSERT INTO play_history (botId, songId, songName, artist, album, platform, coverUrl)
@@ -254,14 +274,15 @@ export function createDatabase(dbPath: string): BotDatabase {
   `);
 
   const upsertInstance = db.prepare(`
-    INSERT INTO bot_instances (id, name, serverAddress, serverPort, nickname, defaultChannel, channelPassword, autoStart, serverProtocol, ts6ApiKey, serverPassword, identity)
-    VALUES (@id, @name, @serverAddress, @serverPort, @nickname, @defaultChannel, @channelPassword, @autoStart, @serverProtocol, @ts6ApiKey, @serverPassword, @identity)
+    INSERT INTO bot_instances (id, name, serverAddress, serverPort, nickname, defaultChannel, channelId, channelPassword, autoStart, serverProtocol, ts6ApiKey, serverPassword, identity)
+    VALUES (@id, @name, @serverAddress, @serverPort, @nickname, @defaultChannel, @channelId, @channelPassword, @autoStart, @serverProtocol, @ts6ApiKey, @serverPassword, @identity)
     ON CONFLICT(id) DO UPDATE SET
       name = excluded.name,
       serverAddress = excluded.serverAddress,
       serverPort = excluded.serverPort,
       nickname = excluded.nickname,
       defaultChannel = excluded.defaultChannel,
+      channelId = excluded.channelId,
       channelPassword = excluded.channelPassword,
       autoStart = excluded.autoStart,
       serverProtocol = excluded.serverProtocol,
@@ -342,6 +363,7 @@ export function createDatabase(dbPath: string): BotDatabase {
         serverProtocol: r.serverProtocol ?? "",
         ts6ApiKey: r.ts6ApiKey ?? "",
         serverPassword: r.serverPassword ?? "",
+        channelId: r.channelId ?? "",
         identity: r.identity ?? undefined,
       }));
     },

src/data/permissions.test.ts

@@ -88,3 +88,48 @@ describe("PermissionStore", () => {
     });
   });
 });
+
+import { GUEST_PERMISSION_FLAGS } from "./permissions.js";
+
+describe("resolvePermissionContext guest branch", () => {
+  const noStore = {
+    getCapabilities: () => [],
+    getBotAccess: () => [] as string[],
+    setPermissions: () => {},
+    pruneBot: () => {},
+  };
+
+  it("guest has no member capabilities and exposes the guest permissions + bots", () => {
+    const ctx = resolvePermissionContext("guest", "__guest__", noStore, {
+      bots: ["bot1"],
+      permissions: {
+        addToQueue: true, playNext: false, playNow: false,
+        skip: true, transport: false, removeClear: false, playMode: false,
+        playCollection: false,
+      },
+    });
+    expect([...ctx.capabilities]).toEqual([]);
+    expect(ctx.bots).toBeInstanceOf(Set);
+    expect((ctx.bots as Set<string>).has("bot1")).toBe(true);
+    expect(ctx.guest?.addToQueue).toBe(true);
+    expect(ctx.guest?.skip).toBe(true);
+  });
+
+  it("guest with bots:'all' resolves to 'all'", () => {
+    const ctx = resolvePermissionContext("guest", "__guest__", noStore, {
+      bots: "all",
+      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 8 canonical flags", () => {
+    expect([...GUEST_PERMISSION_FLAGS].sort()).toEqual(
+      ["addToQueue", "playCollection", "playMode", "playNext", "playNow", "removeClear", "skip", "transport"].sort()
+    );
+  });
+});

src/data/permissions.ts

@@ -21,6 +21,30 @@ export function isCapability(x: string): x is Capability {
 
 export type BotAccess = "all" | string[];
 
+export interface GuestPermissions {
+  addToQueue: boolean;
+  playNext: boolean;
+  playNow: boolean;
+  skip: boolean;
+  transport: boolean;
+  removeClear: boolean;
+  playMode: boolean;
+  /** Load + play an entire playlist/album (clears the queue). Issue #103. */
+  playCollection: boolean;
+}
+
+export const GUEST_PERMISSION_FLAGS = [
+  "addToQueue",
+  "playNext",
+  "playNow",
+  "skip",
+  "transport",
+  "removeClear",
+  "playMode",
+  "playCollection",
+] as const;
+export type GuestFlag = (typeof GUEST_PERMISSION_FLAGS)[number];
+
 export interface PermissionStore {
   getCapabilities(userId: string): Capability[];
   getBotAccess(userId: string): BotAccess;
@@ -71,16 +95,26 @@ export function createPermissionStore(db: Database.Database): PermissionStore {
 export interface PermissionContext {
   capabilities: Set<string>;
   bots: "all" | Set<string>;
+  guest?: GuestPermissions;
 }
 
 export function resolvePermissionContext(
-  role: "admin" | "member",
+  role: "admin" | "member" | "guest",
   userId: string,
-  store: PermissionStore
+  store: PermissionStore,
+  guest?: { bots: BotAccess; permissions: GuestPermissions }
 ): PermissionContext {
   if (role === "admin") {
     return { capabilities: new Set(CAPABILITIES), bots: "all" };
   }
+  if (role === "guest") {
+    const bots = guest?.bots ?? [];
+    return {
+      capabilities: new Set<string>(),
+      bots: bots === "all" ? "all" : new Set(bots),
+      guest: guest?.permissions,
+    };
+  }
   const access = store.getBotAccess(userId);
   return {
     capabilities: new Set(store.getCapabilities(userId)),

src/data/sessions.test.ts

@@ -2,7 +2,7 @@ import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
 import { createHash } from "node:crypto";
 import { createDatabase, type BotDatabase } from "./database.js";
 import { createUserStore, type UserStore } from "./users.js";
-import { createSessionStore, type SessionStore, SESSION_TTL_MS, SESSION_TOUCH_INTERVAL_MS, MAX_SESSIONS_PER_USER } from "./sessions.js";
+import { createSessionStore, type SessionStore, SESSION_TTL_MS, SESSION_TOUCH_INTERVAL_MS, MAX_SESSIONS_PER_USER, GUEST_SESSION_TTL_MS } from "./sessions.js";
 
 function sha256(token: string) {
   return createHash("sha256").update(token).digest("hex");
@@ -126,3 +126,74 @@ describe("SessionStore", () => {
     expect(count).toBe(MAX_SESSIONS_PER_USER);
   });
 });
+
+describe("guest sessions", () => {
+  let botDb: BotDatabase;
+  let sessions: SessionStore;
+
+  beforeEach(() => {
+    botDb = createDatabase(":memory:");
+    sessions = createSessionStore(botDb.db);
+    // Create the synthetic guest user row to satisfy the sessions FK.
+    botDb.db
+      .prepare("INSERT OR IGNORE INTO users (id, username, passwordHash, createdAt, updatedAt, role) VALUES ('__guest__','游客','!',?,?, 'guest')")
+      .run(Date.now(), Date.now());
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+    botDb.close();
+  });
+
+  it("skipCap lets more than MAX_SESSIONS_PER_USER coexist for one principal", () => {
+    const tokens: string[] = [];
+    for (let i = 0; i < MAX_SESSIONS_PER_USER + 3; i++) {
+      tokens.push(sessions.createSession("__guest__", { ttlMs: GUEST_SESSION_TTL_MS, skipCap: true }).token);
+    }
+    // The first token must STILL validate (not evicted).
+    expect(sessions.validateAndTouch(tokens[0])?.role).toBe("guest");
+    const n = (botDb.db.prepare("SELECT COUNT(*) AS n FROM sessions WHERE userId='__guest__'").get() as { n: number }).n;
+    expect(n).toBe(MAX_SESSIONS_PER_USER + 3);
+  });
+
+  it("ttlMs sets a shorter expiry than the default", () => {
+    const { expiresAt } = sessions.createSession("__guest__", { ttlMs: GUEST_SESSION_TTL_MS, skipCap: true });
+    expect(expiresAt).toBeLessThanOrEqual(Date.now() + GUEST_SESSION_TTL_MS + 50);
+  });
+
+  it("validateAndTouch refreshes a guest session to GUEST_SESSION_TTL_MS (1d), not SESSION_TTL_MS (7d)", () => {
+    const { token } = sessions.createSession("__guest__", { ttlMs: GUEST_SESSION_TTL_MS, skipCap: true });
+    // Force the touch branch: backdate lastSeenAt past the touch interval.
+    botDb.db
+      .prepare("UPDATE sessions SET lastSeenAt = ? WHERE userId = '__guest__'")
+      .run(Date.now() - (SESSION_TOUCH_INTERVAL_MS + 1000));
+    const result = sessions.validateAndTouch(token);
+    expect(result?.role).toBe("guest");
+    const row = botDb.db
+      .prepare("SELECT expiresAt FROM sessions WHERE userId = '__guest__'")
+      .get() as { expiresAt: number };
+    // Should refresh to ~now + 1 day, NOT now + 7 days.
+    expect(row.expiresAt).toBeGreaterThan(Date.now() + GUEST_SESSION_TTL_MS - 5000);
+    expect(row.expiresAt).toBeLessThanOrEqual(Date.now() + GUEST_SESSION_TTL_MS + 5000);
+    // Sanity: well below the 7d window.
+    expect(row.expiresAt).toBeLessThan(Date.now() + SESSION_TTL_MS);
+  });
+
+  it("validateAndTouch still refreshes a non-guest (admin) session to SESSION_TTL_MS (7d) on touch", () => {
+    botDb.db
+      .prepare("INSERT INTO users (id, username, passwordHash, createdAt, updatedAt, role) VALUES ('admin1','adminuser','!',?,?, 'admin')")
+      .run(Date.now(), Date.now());
+    const { token } = sessions.createSession("admin1");
+    botDb.db
+      .prepare("UPDATE sessions SET lastSeenAt = ? WHERE userId = 'admin1'")
+      .run(Date.now() - (SESSION_TOUCH_INTERVAL_MS + 1000));
+    const result = sessions.validateAndTouch(token);
+    expect(result?.role).toBe("admin");
+    const row = botDb.db
+      .prepare("SELECT expiresAt FROM sessions WHERE userId = 'admin1'")
+      .get() as { expiresAt: number };
+    // Refreshes to ~now + 7 days, NOT the 1d guest window.
+    expect(row.expiresAt).toBeGreaterThan(Date.now() + SESSION_TTL_MS - 5000);
+    expect(row.expiresAt).toBeLessThanOrEqual(Date.now() + SESSION_TTL_MS + 5000);
+  });
+});

src/data/sessions.ts

@@ -2,17 +2,18 @@ import { createHash, randomBytes } from "node:crypto";
 import type Database from "better-sqlite3";
 
 export const SESSION_TTL_MS = 7 * 24 * 60 * 60 * 1000; // 7 days
+export const GUEST_SESSION_TTL_MS = 24 * 60 * 60 * 1000; // 1 day — guests are short-lived
 export const SESSION_TOUCH_INTERVAL_MS = 60 * 60 * 1000; // 1 hour
 export const MAX_SESSIONS_PER_USER = 10;
 
 export interface SessionValidation {
   userId: string;
   username: string;
-  role: "admin" | "member";
+  role: "admin" | "member" | "guest";
 }
 
 export interface SessionStore {
-  createSession(userId: string): { token: string; expiresAt: number };
+  createSession(userId: string, opts?: { ttlMs?: number; skipCap?: boolean }): { token: string; expiresAt: number };
   validateAndTouch(rawToken: string): SessionValidation | null;
   deleteSession(rawToken: string): void;
   deleteAllForUser(userId: string, exceptToken?: string): void;
@@ -47,7 +48,7 @@ export function createSessionStore(db: Database.Database): SessionStore {
   );
 
   return {
-    createSession(userId) {
+    createSession(userId, opts) {
       // Cap concurrent sessions per user — oldest gets evicted on overflow.
       // Wrap the count → delete → insert in a transaction so concurrent logins
       // for the same user can't both pass the cap check and both insert,
@@ -55,11 +56,13 @@ export function createSessionStore(db: Database.Database): SessionStore {
       const token = randomBytes(32).toString("base64url");
       const id = hashToken(token);
       const now = Date.now();
-      const expiresAt = now + SESSION_TTL_MS;
+      const expiresAt = now + (opts?.ttlMs ?? SESSION_TTL_MS);
       const tx = db.transaction(() => {
-        const existing = (countForUserStmt.get(userId) as { n: number }).n;
-        if (existing >= MAX_SESSIONS_PER_USER) {
-          deleteOldestForUserStmt.run(userId, existing - MAX_SESSIONS_PER_USER + 1);
+        if (!opts?.skipCap) {
+          const existing = (countForUserStmt.get(userId) as { n: number }).n;
+          if (existing >= MAX_SESSIONS_PER_USER) {
+            deleteOldestForUserStmt.run(userId, existing - MAX_SESSIONS_PER_USER + 1);
+          }
         }
         insertStmt.run(id, userId, now, expiresAt, now);
       });
@@ -80,9 +83,12 @@ export function createSessionStore(db: Database.Database): SessionStore {
         return null;
       }
       if (now - row.lastSeenAt > SESSION_TOUCH_INTERVAL_MS) {
-        touchStmt.run(now, now + SESSION_TTL_MS, id);
+        // Refresh against the role's own TTL — guests are short-lived (1d) and
+        // must NOT be bumped to the member/admin 7d window on touch.
+        const ttl = row.role === "guest" ? GUEST_SESSION_TTL_MS : SESSION_TTL_MS;
+        touchStmt.run(now, now + ttl, id);
       }
-      return { userId: row.userId, username: row.username, role: row.role as "admin" | "member" };
+      return { userId: row.userId, username: row.username, role: row.role as "admin" | "member" | "guest" };
     },
 
     deleteSession(rawToken) {

src/data/users.test.ts

@@ -1,6 +1,6 @@
 import { describe, it, expect, beforeEach, afterEach } from "vitest";
 import { createDatabase, type BotDatabase } from "./database.js";
-import { createUserStore, UsernameTakenError, type UserStore } from "./users.js";
+import { createUserStore, UsernameTakenError, GUEST_USER_ID, GUEST_USERNAME, type UserStore } from "./users.js";
 
 describe("UserStore", () => {
   let botDb: BotDatabase;
@@ -184,3 +184,43 @@ describe("UserStore", () => {
     expect(users.countAdmins()).toBe(1);
   });
 });
+
+describe("guest row exclusion", () => {
+  let botDb: BotDatabase;
+  let users: UserStore;
+
+  beforeEach(() => {
+    botDb = createDatabase(":memory:");
+    users = createUserStore(botDb.db);
+  });
+
+  afterEach(() => {
+    botDb.close();
+  });
+
+  it("countUsers and listUsers ignore the reserved guest row", async () => {
+    await users.createUser("alice", "password123", "member");
+    // Insert the reserved guest row directly (mirrors the migration).
+    botDb.db.prepare(
+      "INSERT OR IGNORE INTO users (id, username, passwordHash, createdAt, updatedAt, role) VALUES (?, ?, ?, ?, ?, 'guest')"
+    ).run(GUEST_USER_ID, GUEST_USERNAME, "!", Date.now(), Date.now());
+
+    expect(users.countUsers()).toBe(1); // alice only
+    expect(users.listUsers().some((u) => u.id === GUEST_USER_ID)).toBe(false);
+  });
+
+  it("setRoleIfNotLastAdmin refuses to re-role the reserved guest principal", () => {
+    // The guest row is seeded by createDatabase via ensureGuestUser.
+    expect(users.findById(GUEST_USER_ID)!.role).toBe("guest"); // sanity
+    expect(users.setRoleIfNotLastAdmin(GUEST_USER_ID, "admin")).toBe("not_found");
+    // The guest row's role is unchanged.
+    expect(users.findById(GUEST_USER_ID)!.role).toBe("guest");
+  });
+
+  it("deleteUserIfNotLastAdmin refuses to delete the reserved guest principal", () => {
+    expect(users.findById(GUEST_USER_ID)).not.toBeNull(); // sanity
+    expect(users.deleteUserIfNotLastAdmin(GUEST_USER_ID)).toBe("not_found");
+    // The guest row still exists.
+    expect(users.findById(GUEST_USER_ID)).not.toBeNull();
+  });
+});

src/data/users.ts

@@ -4,7 +4,13 @@ import bcrypt from "bcryptjs";
 
 const BCRYPT_ROUNDS = 12;
 
-export type UserRole = "admin" | "member";
+export type UserRole = "admin" | "member" | "guest";
+
+/** Reserved synthetic principal for login-less guest sessions. The username is
+ *  non-ASCII so it can never collide with an API-created account (which is
+ *  validated against ^[A-Za-z0-9_\-.]{3,32}$). */
+export const GUEST_USER_ID = "__guest__";
+export const GUEST_USERNAME = "游客";
 
 export interface UserRow {
   id: string;
@@ -39,7 +45,7 @@ export class UsernameTakenError extends Error {
 }
 
 export function createUserStore(db: Database.Database): UserStore {
-  const countStmt = db.prepare("SELECT COUNT(*) AS n FROM users");
+  const countStmt = db.prepare("SELECT COUNT(*) AS n FROM users WHERE role != 'guest'");
   const countAdminsStmt = db.prepare("SELECT COUNT(*) AS n FROM users WHERE role = 'admin'");
   const insertStmt = db.prepare(
     "INSERT INTO users (id, username, passwordHash, createdAt, updatedAt, role) VALUES (?, ?, ?, ?, ?, ?)"
@@ -57,7 +63,7 @@ export function createUserStore(db: Database.Database): UserStore {
     "UPDATE users SET role = ?, updatedAt = ? WHERE id = ?"
   );
   const listUsersStmt = db.prepare(
-    "SELECT id, username, createdAt, role FROM users ORDER BY createdAt ASC"
+    "SELECT id, username, createdAt, role FROM users WHERE role != 'guest' ORDER BY createdAt ASC"
   );
   const deleteUserStmt = db.prepare("DELETE FROM users WHERE id = ?");
 
@@ -131,6 +137,7 @@ export function createUserStore(db: Database.Database): UserStore {
       const tx = db.transaction(() => {
         const row = findByIdStmt.get(id) as UserRow | undefined;
         if (!row) return "not_found" as const;
+        if (row.role === "guest") return "not_found" as const; // reserved synthetic principal
         if (row.role === newRole) return "ok" as const; // no-op
         if (row.role === "admin" && newRole === "member") {
           const adminCount = (countAdminsStmt.get() as { n: number }).n;
@@ -155,6 +162,7 @@ export function createUserStore(db: Database.Database): UserStore {
       const tx = db.transaction(() => {
         const row = findByIdStmt.get(id) as UserRow | undefined;
         if (!row) return "not_found" as const;
+        if (row.role === "guest") return "not_found" as const; // reserved synthetic principal
         if (row.role === "admin") {
           const adminCount = (countAdminsStmt.get() as { n: number }).n;
           if (adminCount <= 1) return "would_orphan" as const;

src/index.ts

@@ -7,6 +7,7 @@ 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 { createCookieStore } from "./music/auth.js";
 import { createAvatarStore } from "./data/avatars.js";
 import { createPermissionStore } from "./data/permissions.js";
@@ -25,6 +26,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 +56,7 @@ 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 cookieStore = createCookieStore(COOKIE_DIR);
   const avatarStore = createAvatarStore(AVATAR_DIR);
@@ -74,7 +77,9 @@ async function main() {
     config,
     logger,
     avatarStore,
-    permissions
+    permissions,
+    CONFIG_PATH,
+    localProvider
   );
   await botManager.loadSavedBots();
 
@@ -84,6 +89,7 @@ async function main() {
     neteaseProvider,
     qqProvider,
     bilibiliProvider,
+    localProvider,
     database: db,
     avatarStore,
     config,

src/music/bilibili.ts

@@ -3,6 +3,7 @@ import axios, { type AxiosInstance } from "axios";
 import type {
   MusicProvider,
   Song,
+  SongUrlResult,
   Playlist,
   LyricLine,
   SearchResult,
@@ -231,7 +232,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 +254,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;
     }

src/music/local.test.ts

@@ -0,0 +1,221 @@
+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 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();
+  });
+});

src/music/local.ts

@@ -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): 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(0, 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;
+  }
+}

src/music/netease.test.ts

@@ -1,5 +1,5 @@
 import { describe, it, expect } from "vitest";
-import { parseLyrics, mapNeteaseAlbums } from "./netease.js";
+import { parseLyrics, mapNeteaseAlbums, mapNeteaseSongs, parseNeteaseTrial } from "./netease.js";
 
 describe("NetEase adapter", () => {
   it("parses LRC format lyrics", () => {
@@ -56,4 +56,40 @@ 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();
+  });
 });

src/music/netease.ts

@@ -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 },
@@ -121,17 +149,7 @@ export class NeteaseProvider implements MusicProvider {
       }),
     ]);
 
-    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 +166,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 +208,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 +307,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> {

src/music/provider.ts

@@ -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";
+  /** 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";
 }
 
 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";
 }
 
 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";
 
   search(query: string, limit?: number): Promise<SearchResult>;
-  getSongUrl(songId: string, quality?: string): Promise<string | null>;
+  getSongUrl(songId: string, quality?: string): Promise<SongUrlResult | null>;
   setQuality(quality: string): void;
   getQuality(): string;
   getSongDetail(songId: string): Promise<Song | null>;

src/music/qq.test.ts

@@ -1,5 +1,5 @@
 import { describe, it, expect } from "vitest";
-import { mapQqAlbums, mapQqSongs } from "./qq.js";
+import { mapQqAlbums, mapQqSongs, parseQqTrial } from "./qq.js";
 
 describe("QQ adapter", () => {
   it("mapQqSongs maps QQMusicApi-style song entries", () => {
@@ -22,10 +22,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 = [
       {

src/music/qq.ts

@@ -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) => {
@@ -247,13 +261,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 +275,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 +534,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 [];

src/music/youtube.ts

@@ -7,6 +7,7 @@ import type {
   MusicProvider,
   Song,
   SongWithUrl,
+  SongUrlResult,
   Playlist,
   Album,
   SearchResult,
@@ -134,7 +135,7 @@ export class YouTubeProvider implements MusicProvider {
     }
   }
 
-  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 +147,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;
     }

src/ts-protocol/client-groups.test.ts

@@ -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([]);
+  });
+});

src/ts-protocol/client.ts

@@ -8,6 +8,7 @@ import {
   listChannels,
   listClients,
   clientMove,
+  getClientInfo,
   fileTransferDeleteFile,
   type Identity,
   type TextMessage,
@@ -46,6 +47,7 @@ export interface TS3ClientOptions {
   nickname: string;
   identity?: string; // Exported identity string, or undefined to generate new
   defaultChannel?: string;
+  channelId?: string; // Numeric channel ID (takes precedence over defaultChannel)
   channelPassword?: string;
   serverPassword?: string;
   /** Force a specific protocol instead of auto-detecting. */
@@ -60,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 {
@@ -202,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) => {
@@ -254,8 +267,10 @@ export class TS3Client extends EventEmitter {
       `Logged in (visible client, ${this.detectedProtocol.toUpperCase()} server)`,
     );
 
-    // Join default channel if specified
-    if (this.options.defaultChannel) {
+    // Join channel by numeric ID (takes precedence) or by name
+    if (this.options.channelId) {
+      await this.joinChannel(this.options.channelId, this.options.channelPassword);
+    } else if (this.options.defaultChannel) {
       await this.joinChannel(
         this.options.defaultChannel,
         this.options.channelPassword
@@ -268,6 +283,17 @@ export class TS3Client extends EventEmitter {
   async joinChannel(channelName: string, password?: string): Promise<void> {
     if (!this.client) return;
 
+    const isNumeric = /^\d+$/.test(channelName);
+    if (isNumeric) {
+      try {
+        await clientMove(this.client, this.clientId, BigInt(channelName), password);
+        this.logger.info({ channelName }, "Joined channel");
+      } catch (err) {
+        this.logger.error({ err, channelName }, "Failed to join channel");
+      }
+      return;
+    }
+
     try {
       const channels = await listChannels(this.client);
       const channel = channels.find((ch) => ch.name === channelName);
@@ -277,12 +303,7 @@ export class TS3Client extends EventEmitter {
         return;
       }
 
-      await clientMove(
-        this.client,
-        this.clientId,
-        channel.id,
-        password
-      );
+      await clientMove(this.client, this.clientId, channel.id, password);
       this.logger.info(
         { channelName, cid: channel.id.toString() },
         "Joined channel"
@@ -313,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> {

src/ts-protocol/text-message.test.ts

@@ -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([]);
+  });
+});

src/web/api/audit.test.ts

@@ -7,6 +7,7 @@ import { createUserStore } from "../../data/users.js";
 import { createSessionStore } from "../../data/sessions.js";
 import { createAuditStore } from "../../data/audit.js";
 import { createPermissionStore } from "../../data/permissions.js";
+import { getDefaultConfig } from "../../data/config.js";
 import { createRequireAuth } from "../middleware/requireAuth.js";
 import { createAuditRouter } from "./audit.js";
 import { SESSION_COOKIE_NAME } from "../auth/validateSession.js";
@@ -34,7 +35,7 @@ describe("audit router", () => {
     app = express();
     app.use(express.json());
     app.use(cookieParser());
-    app.use("/api", createRequireAuth(sessions, permissions));
+    app.use("/api", createRequireAuth(sessions, permissions, () => getDefaultConfig().guestMode));
     app.use("/api/audit", createAuditRouter(audit));
   });
 

src/web/api/auth.ts

@@ -4,6 +4,7 @@ import { YouTubeProvider } from "../../music/youtube.js";
 import type { CookieStore } from "../../music/auth.js";
 import type { Logger } from "../../logger.js";
 import { requirePermission } from "../middleware/requirePermission.js";
+import { requireNotGuest } from "../middleware/requireNotGuest.js";
 
 export function createAuthRouter(
   neteaseProvider: MusicProvider,
@@ -23,7 +24,7 @@ export function createAuthRouter(
     return platform === "qq" ? qqProvider : neteaseProvider;
   }
 
-  router.get("/status", async (req, res) => {
+  router.get("/status", requireNotGuest, async (req, res) => {
     try {
       const platform = req.query.platform as string;
       const provider = getProvider(platform);
@@ -49,7 +50,7 @@ export function createAuthRouter(
     }
   });
 
-  router.get("/qrcode/status", async (req, res) => {
+  router.get("/qrcode/status", requireNotGuest, async (req, res) => {
     try {
       const { key, platform } = req.query;
       if (!key) {

src/web/api/bot.test.ts

@@ -60,7 +60,7 @@ describe("bot router /settings", () => {
     app = express();
     app.use(express.json());
     app.use(cookieParser());
-    app.use("/api", createRequireAuth(sessions, createPermissionStore(botDb.db)));
+    app.use("/api", createRequireAuth(sessions, createPermissionStore(botDb.db), () => getDefaultConfig().guestMode));
     app.use(
       "/api/bot",
       createBotRouter(fakeManager, config, configPath, pino({ level: "silent" }), botDb, avatarStore),
@@ -158,4 +158,97 @@ 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", () => {
+  let tmpDir: string;
+  let configPath: string;
+  let config: BotConfig;
+  let botDb: BotDatabase;
+
+  beforeEach(() => {
+    botDb = createDatabase(":memory:");
+    tmpDir = mkdtempSync(join(tmpdir(), "botsettings-gm-"));
+    configPath = join(tmpDir, "config.json");
+    config = getDefaultConfig();
+  });
+
+  afterEach(() => {
+    botDb.close();
+    rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  /** Mounts createBotRouter with an injected req.user (no session/cookie). */
+  function mountBot(injectUser: () => unknown): express.Express {
+    const fakeManager = { getAllBots: () => [] } as unknown as BotManager;
+    const avatarStore = createAvatarStore(tmpDir);
+    const app = express();
+    app.use(express.json());
+    app.use((req, _res, next) => { (req as { user?: unknown }).user = injectUser(); next(); });
+    app.use(
+      "/api/bot",
+      createBotRouter(fakeManager, config, configPath, pino({ level: "silent" }), botDb, avatarStore),
+    );
+    return app;
+  }
+
+  it("GET /settings is 403 for guests and includes guestMode for admins", async () => {
+    const guestApp = mountBot(() => ({ role: "guest", guest: {} }));
+    expect((await request(guestApp).get("/api/bot/settings")).status).toBe(403);
+    const adminApp = mountBot(() => ({ role: "admin" }));
+    const res = await request(adminApp).get("/api/bot/settings");
+    expect(res.status).toBe(200);
+    expect(res.body.guestMode).toBeDefined();
+    expect(res.body.guestMode.enabled).toBe(false);
+  });
+
+  it("POST /settings persists a guestMode block", async () => {
+    const adminApp = mountBot(() => ({ role: "admin" }));
+    const res = await request(adminApp).post("/api/bot/settings").send({
+      guestMode: { enabled: true, bots: ["bot1"], permissions: { playNext: true } },
+    });
+    expect(res.status).toBe(200);
+    expect(res.body.guestMode.enabled).toBe(true);
+    expect(res.body.guestMode.bots).toEqual(["bot1"]);
+    expect(res.body.guestMode.permissions.playNext).toBe(true);
+    expect(res.body.guestMode.permissions.addToQueue).toBe(true); // untouched default
+  });
 });

src/web/api/bot.ts

@@ -1,11 +1,13 @@
 import { Router } from "express";
 import type { BotManager } from "../../bot/manager.js";
-import type { BotConfig } from "../../data/config.js";
+import type { BotConfig, GuestModeConfig } from "../../data/config.js";
 import { saveConfig } from "../../data/config.js";
 import type { Logger } from "../../logger.js";
 import type { BotDatabase } from "../../data/database.js";
 import type { AvatarStore } from "../../data/avatars.js";
 import { requirePermission, requireBotAccess } from "../middleware/requirePermission.js";
+import { requireNotGuest } from "../middleware/requireNotGuest.js";
+import { GUEST_PERMISSION_FLAGS } from "../../data/permissions.js";
 
 export function createBotRouter(
   botManager: BotManager,
@@ -14,6 +16,7 @@ export function createBotRouter(
   logger: Logger,
   botDb: BotDatabase,
   avatarStore: AvatarStore,
+  onGuestPolicyChanged?: (cfg: GuestModeConfig) => void,
 ): Router {
   const router = Router();
 
@@ -29,17 +32,20 @@ export function createBotRouter(
 
   // GET /api/bot/settings — 读取全局 bot 行为设置
   // NOTE: must be registered before "/:id" so it isn't shadowed by the param route.
-  router.get("/settings", (_req, res) => {
+  router.get("/settings", requireNotGuest, (_req, res) => {
     res.json({
       idleTimeoutMinutes: config.idleTimeoutMinutes ?? 0,
       autoPauseOnEmpty: config.autoPauseOnEmpty,
+      localAudioEnabled: config.localAudioEnabled,
+      adminGroups: config.adminGroups ?? [],
+      guestMode: config.guestMode,
     });
   });
 
   // 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 } = req.body;
+    const { idleTimeoutMinutes, autoPauseOnEmpty, localAudioEnabled, guestMode, adminGroups } = req.body;
 
     const hasIdle = idleTimeoutMinutes !== undefined;
     if (hasIdle && (typeof idleTimeoutMinutes !== "number" || idleTimeoutMinutes < 0)) {
@@ -48,11 +54,46 @@ 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) {
+      const gm = config.guestMode;
+      if (typeof guestMode.enabled === "boolean") gm.enabled = guestMode.enabled;
+      if (guestMode.bots === "all") {
+        gm.bots = "all";
+      } else if (Array.isArray(guestMode.bots)) {
+        gm.bots = guestMode.bots.filter((id: unknown): id is string => typeof id === "string");
+      }
+      if (guestMode.permissions && typeof guestMode.permissions === "object") {
+        for (const f of GUEST_PERMISSION_FLAGS) {
+          if (typeof guestMode.permissions[f] === "boolean") {
+            gm.permissions[f] = guestMode.permissions[f];
+          }
+        }
+      }
+    }
+
+    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
+    // disabled or narrowed scope takes effect immediately (matches requireAuth's
+    // "disabling immediately invalidates in-flight guest sessions" invariant).
+    if (hasGuestMode) {
+      onGuestPolicyChanged?.(config.guestMode);
+    }
+
     // 通知所有 bot 实例更新
     for (const bot of botManager.getAllBots()) {
       if (hasIdle) bot.updateIdleTimeout(config.idleTimeoutMinutes);
@@ -62,6 +103,9 @@ export function createBotRouter(
     res.json({
       idleTimeoutMinutes: config.idleTimeoutMinutes ?? 0,
       autoPauseOnEmpty: config.autoPauseOnEmpty,
+      localAudioEnabled: config.localAudioEnabled,
+      adminGroups: config.adminGroups ?? [],
+      guestMode: config.guestMode,
     });
   });
 
@@ -159,6 +203,7 @@ export function createBotRouter(
         serverPort,
         nickname,
         defaultChannel,
+        channelId,
         channelPassword,
         serverPassword,
         autoStart,
@@ -175,6 +220,7 @@ export function createBotRouter(
         serverPort: serverPort ?? 9987,
         nickname,
         defaultChannel,
+        channelId,
         channelPassword,
         serverPassword,
         autoStart: autoStart ?? false,
@@ -194,10 +240,10 @@ export function createBotRouter(
         res.status(404).json({ error: "Bot not found" });
         return;
       }
-      const { name, serverAddress, serverPort, nickname, defaultChannel, channelPassword, serverPassword } = req.body;
+      const { name, serverAddress, serverPort, nickname, defaultChannel, channelId, channelPassword, serverPassword } = req.body;
       // Update in database
       botManager.updateBot(req.params.id, {
-        name, serverAddress, serverPort, nickname, defaultChannel, channelPassword, serverPassword,
+        name, serverAddress, serverPort, nickname, defaultChannel, channelId, channelPassword, serverPassword,
       });
       res.json({ success: true });
     } catch (err) {

src/web/api/music.ts

@@ -1,24 +1,85 @@
-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
 ): 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;
     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;
@@ -26,6 +87,10 @@ export function createMusicRouter(
         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);
       const result = await provider.search(
         q as string,
@@ -46,16 +111,18 @@ export function createMusicRouter(
         return;
       }
       const parsedLimit = parseInt(limit as string) || 20;
-      const [neteaseResult, qqResult, bilibiliResult] = await Promise.allSettled([
+      const [neteaseResult, qqResult, bilibiliResult, localResult] = 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: [] }),
       ]);
 
       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 : []),
       ];
       const albums = [
         ...(neteaseResult.status === "fulfilled" ? neteaseResult.value.albums : []),
@@ -75,6 +142,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) {
@@ -127,7 +198,7 @@ export function createMusicRouter(
     }
   });
 
-  router.get("/recommend/songs", async (req, res) => {
+  router.get("/recommend/songs", requireNotGuest, async (req, res) => {
     try {
       const provider = getProvider(req.query.platform as string);
       if (!provider.getDailyRecommendSongs) {
@@ -142,7 +213,7 @@ export function createMusicRouter(
     }
   });
 
-  router.get("/personal/fm", async (req, res) => {
+  router.get("/personal/fm", requireNotGuest, async (req, res) => {
     try {
       const provider = getProvider(req.query.platform as string);
       if (!provider.getPersonalFm) {
@@ -157,7 +228,7 @@ export function createMusicRouter(
     }
   });
 
-  router.get("/user/playlists", async (req, res) => {
+  router.get("/user/playlists", requireNotGuest, async (req, res) => {
     try {
       const provider = getProvider(req.query.platform as string);
       if (!provider.getUserPlaylists) {
@@ -209,11 +280,12 @@ export function createMusicRouter(
   });
 
   // Get current quality
-  router.get("/quality", (_req, res) => {
+  router.get("/quality", requireNotGuest, (_req, res) => {
     res.json({
       netease: neteaseProvider.getQuality(),
       qq: qqProvider.getQuality(),
       bilibili: bilibiliProvider.getQuality(),
+      local: localProvider?.getQuality() ?? "original",
     });
   });
 

src/web/api/permissions-enforcement.test.ts

@@ -6,6 +6,8 @@ import { createPlayerRouter } from "./player.js";
 import { createBotRouter } from "./bot.js";
 import { createAuthRouter } from "./auth.js";
 import { createMusicRouter } from "./music.js";
+import { createFavoritesRouter } from "./favorites.js";
+import { requireNotGuest } from "../middleware/requireNotGuest.js";
 
 const logger = pino({ level: "silent" });
 
@@ -188,6 +190,36 @@ describe("permission enforcement on action routes", () => {
       const res = await request(app).post("/api/music/quality").send({ quality: "high" });
       expect(res.status).not.toBe(403);
     });
+
+    it("GET /api/music/quality is 403 for guests, allowed for members", async () => {
+      const guestApp = makeApp(guest());
+      expect((await request(guestApp).get("/api/music/quality")).status).toBe(403);
+      const memberApp = makeApp(member([], "all"));
+      expect((await request(memberApp).get("/api/music/quality")).status).toBe(200);
+    });
+  });
+
+  // The operator's personal-account reads (their recommendations, FM, and
+  // playlists) must never leak to login-less guests. These routes are gated
+  // with requireNotGuest; generic search/browse stays open.
+  describe("operator personal-data reads are denied to guests", () => {
+    const personalRoutes = [
+      "/api/music/recommend/songs",
+      "/api/music/personal/fm",
+      "/api/music/user/playlists",
+    ];
+
+    for (const route of personalRoutes) {
+      it(`GET ${route} is 403 for a guest`, async () => {
+        const app = makeApp(guest());
+        expect((await request(app).get(route)).status).toBe(403);
+      });
+
+      it(`GET ${route} is NOT 403 for a member`, async () => {
+        const app = makeApp(member([], "all"));
+        expect((await request(app).get(route)).status).not.toBe(403);
+      });
+    }
   });
 
   describe("read-only routes stay open", () => {
@@ -197,7 +229,7 @@ describe("permission enforcement on action routes", () => {
       expect(res.status).not.toBe(403);
     });
 
-    it("GET /api/music/quality not gated", async () => {
+    it("GET /api/music/quality readable by members, denied to guests", async () => {
       const app = makeApp(member([], "all"));
       const res = await request(app).get("/api/music/quality");
       expect(res.status).not.toBe(403);
@@ -208,6 +240,12 @@ describe("permission enforcement on action routes", () => {
       const res = await request(app).get("/api/bot");
       expect(res.status).not.toBe(403);
     });
+
+    it("GET /api/auth/status and /api/auth/qrcode/status are 403 for guests", async () => {
+      const app = makeApp(guest());
+      expect((await request(app).get("/api/auth/status")).status).toBe(403);
+      expect((await request(app).get("/api/auth/qrcode/status?key=k")).status).toBe(403);
+    });
   });
 
   describe("admin bypasses every gate", () => {
@@ -235,3 +273,186 @@ describe("permission enforcement on action routes", () => {
     });
   });
 });
+
+// --------------------------------------------------------------------------
+// Guest enforcement on the player routes. Guests carry per-flag permissions
+// (req.user.guest) instead of capabilities; authorize() opens a route only
+// when its guestFlag is set AND enabled. Routes with no guestFlag are denied
+// to guests no matter which flags are on. We reuse makeApp() (it injects
+// req.user and mounts the real player router over the fake bot manager) and
+// assert purely on 403-vs-not-403 — a 200/500 from the fake bot both prove
+// the gate let the request through.
+// --------------------------------------------------------------------------
+
+const SONG = { id: "1", platform: "netease", name: "x", artist: "y" };
+
+// Build a guest user with all flags off, then override the ones passed in.
+const guest = (perms: Partial<Record<string, boolean>> = {}) => ({
+  id: "__guest__",
+  username: "游客",
+  role: "guest" as const,
+  capabilities: new Set<string>(),
+  bots: "all" as const,
+  guest: {
+    addToQueue: false,
+    playNext: false,
+    playNow: false,
+    skip: false,
+    transport: false,
+    removeClear: false,
+    playMode: false,
+    playCollection: false,
+    ...perms,
+  },
+});
+
+const mountGuest = (perms: Partial<Record<string, boolean>> = {}) => makeApp(guest(perms));
+
+describe("guest enforcement on player routes", () => {
+  it("addToQueue flag gates POST /add, /add-song, /add-by-id", async () => {
+    const allow = mountGuest({ addToQueue: true });
+    const deny = mountGuest({ addToQueue: false });
+    for (const path of ["add", "add-song", "add-by-id"]) {
+      expect((await request(allow).post(`/api/player/${ALLOWED_BOT}/${path}`).send({ song: SONG, songId: "1", query: "x" })).status).not.toBe(403);
+      expect((await request(deny).post(`/api/player/${ALLOWED_BOT}/${path}`).send({ song: SONG, songId: "1", query: "x" })).status).toBe(403);
+    }
+  });
+
+  it("playNext flag gates /play-next-song", async () => {
+    expect((await request(mountGuest({ playNext: true })).post(`/api/player/${ALLOWED_BOT}/play-next-song`).send({ song: SONG })).status).not.toBe(403);
+    expect((await request(mountGuest({})).post(`/api/player/${ALLOWED_BOT}/play-next-song`).send({ song: SONG })).status).toBe(403);
+  });
+
+  it("playNow flag gates the new /play-now-song", async () => {
+    expect((await request(mountGuest({ playNow: true })).post(`/api/player/${ALLOWED_BOT}/play-now-song`).send({ song: SONG })).status).not.toBe(403);
+    expect((await request(mountGuest({})).post(`/api/player/${ALLOWED_BOT}/play-now-song`).send({ song: SONG })).status).toBe(403);
+    // playNext does NOT open play-now-song, and playNow does NOT open play-next-song.
+    expect((await request(mountGuest({ playNext: true })).post(`/api/player/${ALLOWED_BOT}/play-now-song`).send({ song: SONG })).status).toBe(403);
+    expect((await request(mountGuest({ playNow: true })).post(`/api/player/${ALLOWED_BOT}/play-next-song`).send({ song: SONG })).status).toBe(403);
+  });
+
+  it("skip flag gates /next", async () => {
+    expect((await request(mountGuest({ skip: true })).post(`/api/player/${ALLOWED_BOT}/next`)).status).not.toBe(403);
+    expect((await request(mountGuest({})).post(`/api/player/${ALLOWED_BOT}/next`)).status).toBe(403);
+  });
+
+  it("transport flag gates /pause, /resume, /seek, /volume", async () => {
+    const allow = mountGuest({ transport: true });
+    const deny = mountGuest({ transport: false });
+    expect((await request(allow).post(`/api/player/${ALLOWED_BOT}/pause`)).status).not.toBe(403);
+    expect((await request(allow).post(`/api/player/${ALLOWED_BOT}/resume`)).status).not.toBe(403);
+    expect((await request(allow).post(`/api/player/${ALLOWED_BOT}/seek`).send({ position: 0 })).status).not.toBe(403);
+    expect((await request(allow).post(`/api/player/${ALLOWED_BOT}/volume`).send({ volume: 50 })).status).not.toBe(403);
+    expect((await request(deny).post(`/api/player/${ALLOWED_BOT}/pause`)).status).toBe(403);
+    expect((await request(deny).post(`/api/player/${ALLOWED_BOT}/resume`)).status).toBe(403);
+    expect((await request(deny).post(`/api/player/${ALLOWED_BOT}/seek`).send({ position: 0 })).status).toBe(403);
+    expect((await request(deny).post(`/api/player/${ALLOWED_BOT}/volume`).send({ volume: 50 })).status).toBe(403);
+  });
+
+  it("playMode flag gates /mode, /fm", async () => {
+    const allow = mountGuest({ playMode: true });
+    const deny = mountGuest({ playMode: false });
+    expect((await request(allow).post(`/api/player/${ALLOWED_BOT}/mode`).send({ mode: "seq" })).status).not.toBe(403);
+    expect((await request(allow).post(`/api/player/${ALLOWED_BOT}/fm`).send({})).status).not.toBe(403);
+    expect((await request(deny).post(`/api/player/${ALLOWED_BOT}/mode`).send({ mode: "seq" })).status).toBe(403);
+    expect((await request(deny).post(`/api/player/${ALLOWED_BOT}/fm`).send({})).status).toBe(403);
+  });
+
+  it("removeClear flag gates /clear and DELETE /queue/:index", async () => {
+    const allow = mountGuest({ removeClear: true });
+    const deny = mountGuest({ removeClear: false });
+    expect((await request(allow).post(`/api/player/${ALLOWED_BOT}/clear`)).status).not.toBe(403);
+    expect((await request(allow).delete(`/api/player/${ALLOWED_BOT}/queue/0`)).status).not.toBe(403);
+    expect((await request(deny).post(`/api/player/${ALLOWED_BOT}/clear`)).status).toBe(403);
+    expect((await request(deny).delete(`/api/player/${ALLOWED_BOT}/queue/0`)).status).toBe(403);
+  });
+
+  it("each guest flag opens exactly its own route(s) — a single flag does not leak", async () => {
+    // With only addToQueue on, a transport route stays denied.
+    expect((await request(mountGuest({ addToQueue: true })).post(`/api/player/${ALLOWED_BOT}/pause`)).status).toBe(403);
+    // With only transport on, an add route stays denied.
+    expect((await request(mountGuest({ transport: true })).post(`/api/player/${ALLOWED_BOT}/add-song`).send({ song: SONG })).status).toBe(403);
+  });
+
+  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,
+      playNow: true,
+      skip: true,
+      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}/playlist`).send({ playlistId: "1" })).status).toBe(403);
+    expect((await request(all).put(`/api/player/${ALLOWED_BOT}/profile`).send({})).status).toBe(403);
+  });
+
+  it("members are unaffected — player.queue still reaches /add-song", async () => {
+    const m = makeApp(member(["player.queue"], [ALLOWED_BOT]));
+    expect((await request(m).post(`/api/player/${ALLOWED_BOT}/add-song`).send({ song: SONG })).status).not.toBe(403);
+  });
+});
+
+// --------------------------------------------------------------------------
+// Favorites are member-only: the router keys everything off req.user.id and
+// all guests share the __guest__ principal, so a guest must never reach it.
+// server.ts gates the mount with requireNotGuest; we mirror that mount here
+// and assert a guest gets 403 (the requireNotGuest guard runs before any
+// handler, so the fake database is never touched).
+// --------------------------------------------------------------------------
+
+function makeFavoritesApp(user: any) {
+  const app = express();
+  app.use(express.json());
+  app.use((req, _res, next) => { (req as any).user = user; next(); });
+  const fakeDb = {
+    getFavorites: () => [],
+    addFavorite: () => {},
+    removeFavorite: () => {},
+    isFavorited: () => false,
+  } as any;
+  app.use("/api/favorites", requireNotGuest, createFavoritesRouter(fakeDb, logger));
+  return app;
+}
+
+describe("favorites are denied to guests", () => {
+  it("403 for a guest on GET /api/favorites", async () => {
+    const app = makeFavoritesApp(guest());
+    expect((await request(app).get("/api/favorites")).status).toBe(403);
+  });
+
+  it("403 for a guest on GET /api/favorites/check", async () => {
+    const app = makeFavoritesApp(guest());
+    expect((await request(app).get("/api/favorites/check?platform=netease&playlistId=x")).status).toBe(403);
+  });
+
+  it("403 for a guest on POST /api/favorites", async () => {
+    const app = makeFavoritesApp(guest());
+    const res = await request(app).post("/api/favorites").send({ platform: "netease", playlistId: "x", name: "n" });
+    expect(res.status).toBe(403);
+  });
+
+  it("NOT 403 for a member on GET /api/favorites", async () => {
+    const app = makeFavoritesApp(member([], "all"));
+    expect((await request(app).get("/api/favorites")).status).not.toBe(403);
+  });
+});

src/web/api/player.ts

@@ -4,7 +4,8 @@ import type { BotDatabase } from "../../data/database.js";
 import type { MusicProvider } from "../../music/provider.js";
 import type { Logger } from "../../logger.js";
 import { parseCommand } from "../../bot/commands.js";
-import { requirePermission, requireBotAccess } from "../middleware/requirePermission.js";
+import { requireBotAccess } from "../middleware/requirePermission.js";
+import { authorize } from "../middleware/authorize.js";
 
 export function createPlayerRouter(
   botManager: BotManager,
@@ -41,7 +42,17 @@ export function createPlayerRouter(
     return "";
   };
 
-  router.post("/:botId/play", requirePermission("player.control"), async (req, res) => {
+  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;
       const { query, platform } = req.body;
@@ -61,7 +72,7 @@ export function createPlayerRouter(
     }
   });
 
-  router.post("/:botId/add", requirePermission("player.queue"), async (req, res) => {
+  router.post("/:botId/add", authorize({ capability: "player.queue", guestFlag: "addToQueue" }), async (req, res) => {
     try {
       const bot = (req as any).bot;
       const { query, platform } = req.body;
@@ -88,19 +99,23 @@ export function createPlayerRouter(
     }
   };
 
-  router.post("/:botId/pause", requirePermission("player.control"), simpleCommand("!pause"));
-  router.post("/:botId/resume", requirePermission("player.control"), simpleCommand("!resume"));
-  router.post("/:botId/next", requirePermission("player.control"), simpleCommand("!next"));
-  router.post("/:botId/prev", requirePermission("player.control"), simpleCommand("!prev"));
-  router.post("/:botId/stop", requirePermission("player.control"), simpleCommand("!stop"));
-  router.post("/:botId/clear", requirePermission("player.queue"), simpleCommand("!clear"));
+  router.post("/:botId/pause", authorize({ capability: "player.control", guestFlag: "transport" }), simpleCommand("!pause"));
+  router.post("/:botId/resume", authorize({ capability: "player.control", guestFlag: "transport" }), simpleCommand("!resume"));
+  router.post("/:botId/next", authorize({ capability: "player.control", guestFlag: "skip" }), simpleCommand("!next"));
+  router.post("/:botId/prev", authorize({ capability: "player.control" }), simpleCommand("!prev"));
+  router.post("/:botId/stop", authorize({ capability: "player.control" }), simpleCommand("!stop"));
+  router.post("/:botId/clear", authorize({ capability: "player.queue", guestFlag: "removeClear" }), simpleCommand("!clear"));
 
-  router.post("/:botId/fm", requirePermission("player.control"), async (req, res) => {
+  router.post("/:botId/fm", authorize({ capability: "player.control", guestFlag: "playMode" }), async (req, res) => {
     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
           : "netease"
       );
@@ -117,7 +132,7 @@ export function createPlayerRouter(
     }
   });
 
-  router.post("/:botId/volume", requirePermission("player.control"), async (req, res) => {
+  router.post("/:botId/volume", authorize({ capability: "player.control", guestFlag: "transport" }), async (req, res) => {
     try {
       const bot = (req as any).bot;
       const { volume } = req.body;
@@ -145,7 +160,7 @@ export function createPlayerRouter(
 
   const VALID_MODES = new Set(["seq", "loop", "random", "rloop"]);
 
-  router.post("/:botId/mode", requirePermission("player.control"), async (req, res) => {
+  router.post("/:botId/mode", authorize({ capability: "player.control", guestFlag: "playMode" }), async (req, res) => {
     try {
       const bot = (req as any).bot;
       const { mode } = req.body;
@@ -170,7 +185,7 @@ export function createPlayerRouter(
   });
 
   // Seek to position
-  router.post("/:botId/seek", requirePermission("player.control"), async (req, res) => {
+  router.post("/:botId/seek", authorize({ capability: "player.control", guestFlag: "transport" }), async (req, res) => {
     try {
       const bot = (req as any).bot;
       const { position } = req.body; // seconds
@@ -194,7 +209,7 @@ export function createPlayerRouter(
     res.json({ queue: bot.getQueue(), status: bot.getStatus() });
   });
 
-  router.delete("/:botId/queue/:index", requirePermission("player.queue"), async (req, res) => {
+  router.delete("/:botId/queue/:index", authorize({ capability: "player.queue", guestFlag: "removeClear" }), async (req, res) => {
     try {
       const bot = (req as any).bot;
       const cmd = parseCommand(`!remove ${req.params.index}`, "!")!;
@@ -206,7 +221,7 @@ export function createPlayerRouter(
   });
 
   // Jump to a specific index in the queue (without clearing it)
-  router.post("/:botId/play-at", requirePermission("player.control"), async (req, res) => {
+  router.post("/:botId/play-at", authorize({ capability: "player.control" }), async (req, res) => {
     try {
       const bot = (req as any).bot;
       const { index } = req.body;
@@ -214,33 +229,40 @@ export function createPlayerRouter(
         res.status(400).json({ error: "index is required" });
         return;
       }
-      const queue = bot.getQueueManager();
-      // Validate the index BEFORE stopping current playback — otherwise an
-      // invalid index silently kills the user's current song and leaves the
-      // queue idle.
-      if (index >= queue.size()) {
-        res.status(400).json({ error: "Invalid queue index" });
+      // Serialize the index-validation + stop/reset/playAt/resolveAndPlay so a
+      // concurrent request can't interleave between mutating the queue and
+      // starting playback (audible track must match queue.currentIndex).
+      const result = await bot.runExclusive(async () => {
+        const queue = bot.getQueueManager();
+        // Validate the index BEFORE stopping current playback — otherwise an
+        // invalid index silently kills the user's current song and leaves the
+        // queue idle.
+        if (index >= queue.size()) {
+          return { status: 400 as const, body: { error: "Invalid queue index" } };
+        }
+        bot.getPlayer().stop();
+        bot.getPlayer().resetFailures();
+        const song = queue.playAt(index);
+        if (!song) {
+          return { status: 400 as const, body: { error: "Invalid queue index" } };
+        }
+        const ok = await bot.resolveAndPlay(song);
+        if (!ok) {
+          return { body: { message: `Cannot play: ${song.name}` } };
+        }
+        return { body: { message: `Now playing: ${song.name} - ${song.artist}` } };
+      });
+      if (result.status) {
+        res.status(result.status).json(result.body);
         return;
       }
-      bot.getPlayer().stop();
-      bot.getPlayer().resetFailures();
-      const song = queue.playAt(index);
-      if (!song) {
-        res.status(400).json({ error: "Invalid queue index" });
-        return;
-      }
-      const ok = await bot.resolveAndPlay(song);
-      if (!ok) {
-        res.json({ message: `Cannot play: ${song.name}` });
-        return;
-      }
-      res.json({ message: `Now playing: ${song.name} - ${song.artist}` });
+      res.json(result.body);
     } catch (err) {
       res.status(500).json({ error: (err as Error).message });
     }
   });
 
-  router.post("/:botId/playlist", requirePermission("player.queue"), async (req, res) => {
+  router.post("/:botId/playlist", authorize({ capability: "player.queue" }), async (req, res) => {
     try {
       const bot = (req as any).bot;
       const { playlistId, platform } = req.body;
@@ -257,14 +279,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", requirePermission("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
           : "netease"
       );
@@ -307,6 +333,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();
@@ -344,12 +374,16 @@ export function createPlayerRouter(
   });
 
   // Play an album by ID — mirrors play-playlist but calls getAlbumSongs
-  router.post("/:botId/play-album", requirePermission("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
           : "netease"
       );
@@ -385,6 +419,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;
@@ -416,7 +452,7 @@ export function createPlayerRouter(
   });
 
   // Play a single song by ID — resolves URL on demand
-  router.post("/:botId/play-song", requirePermission("player.control"), async (req, res) => {
+  router.post("/:botId/play-song", authorize({ capability: "player.control" }), async (req, res) => {
     try {
       const bot = (req as any).bot;
       const { song } = req.body;
@@ -424,13 +460,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;
@@ -444,7 +488,7 @@ export function createPlayerRouter(
 
   // Insert a single song to play right after the current one.
   // If nothing is playing, behaves like /play-song (start immediately).
-  router.post("/:botId/play-next-song", requirePermission("player.control"), async (req, res) => {
+  router.post("/:botId/play-next-song", authorize({ capability: "player.control", guestFlag: "playNext" }), async (req, res) => {
     try {
       const bot = (req as any).bot;
       const { song } = req.body;
@@ -452,37 +496,47 @@ export function createPlayerRouter(
         res.status(400).json({ error: "song object with id and platform is required" });
         return;
       }
-      const queue = bot.getQueueManager();
-      const wasIdle = bot.getPlayer().getState() === "idle";
-      // Capture the slot addNext WILL insert at, before mutating the queue.
-      // addNext pushes when currentIndex<0 (slot = size); otherwise splices
-      // at currentIndex+1. Using size-1 after addNext was wrong when the
-      // queue had stale currentIndex>=0 while the player was idle (e.g.,
-      // after natural track end without queue.clear()).
-      const insertedAt =
-        queue.getCurrentIndex() < 0 ? queue.size() : queue.getCurrentIndex() + 1;
-      queue.addNext(song);
-
-      if (wasIdle) {
-        // Promote the just-added song to current and start it.
-        queue.playAt(insertedAt);
-        bot.getPlayer().resetFailures();
-        const ok = await bot.resolveAndPlay(queue.current()!);
-        if (!ok) {
-          res.json({ ok: false, message: `无法播放「${song.name || song.id}」（区域/版权限制）` });
-          return;
-        }
-        res.json({ ok: true, message: `正在播放：${song.name || 'Unknown'} - ${song.artist || 'Unknown'}` });
+      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 () => {
+        const queue = bot.getQueueManager();
+        const wasIdle = bot.getPlayer().getState() === "idle";
+        // Capture the slot addNext WILL insert at, before mutating the queue.
+        // addNext pushes when currentIndex<0 (slot = size); otherwise splices
+        // at currentIndex+1. Using size-1 after addNext was wrong when the
+        // queue had stale currentIndex>=0 while the player was idle (e.g.,
+        // after natural track end without queue.clear()).
+        const insertedAt =
+          queue.getCurrentIndex() < 0 ? queue.size() : queue.getCurrentIndex() + 1;
+        queue.addNext(song);
 
-      res.json({ ok: true, message: `已加入下一首：${song.name || 'Unknown'} - ${song.artist || 'Unknown'}` });
+        if (wasIdle) {
+          // Promote the just-added song to current and start it.
+          queue.playAt(insertedAt);
+          bot.getPlayer().resetFailures();
+          const ok = await bot.resolveAndPlay(queue.current()!);
+          if (!ok) {
+            return { ok: false, message: `无法播放「${song.name || song.id}」（区域/版权限制）` };
+          }
+          return { ok: true, message: `正在播放：${song.name || 'Unknown'} - ${song.artist || 'Unknown'}` };
+        }
+
+        return { ok: true, message: `已加入下一首：${song.name || 'Unknown'} - ${song.artist || 'Unknown'}` };
+      });
+      res.json(body);
     } catch (err) {
       res.status(500).json({ error: (err as Error).message });
     }
   });
 
-  router.post("/:botId/add-song", requirePermission("player.queue"), async (req, res) => {
+  // Play a song "now" without clearing the queue: insert after current, then
+  // promote to current and start it. Non-destructive (unlike /play-song which
+  // clears the whole queue) — this is the guest-safe "play now".
+  router.post("/:botId/play-now-song", authorize({ capability: "player.control", guestFlag: "playNow" }), async (req, res) => {
     try {
       const bot = (req as any).bot;
       const { song } = req.body;
@@ -490,32 +544,77 @@ export function createPlayerRouter(
         res.status(400).json({ error: "song object with id and platform is required" });
         return;
       }
-      const queue = bot.getQueueManager();
-      const wasIdle = bot.getPlayer().getState() === "idle";
-      queue.add(song);
-
-      // If nothing was playing, start this newly-added song immediately.
-      if (wasIdle) {
-        queue.playAt(queue.size() - 1);
-        bot.getPlayer().resetFailures();
-        await bot.resolveAndPlay(queue.current()!);
-        res.json({ message: `Now playing: ${song.name || 'Unknown'} - ${song.artist || 'Unknown'}` });
+      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 () => {
+        const queue = bot.getQueueManager();
+        const insertedAt =
+          queue.getCurrentIndex() < 0 ? queue.size() : queue.getCurrentIndex() + 1;
+        queue.addNext(song);
+        queue.playAt(insertedAt);
+        bot.getPlayer().resetFailures();
+        const ok = await bot.resolveAndPlay(queue.current()!);
+        if (!ok) {
+          return { ok: false, message: `无法播放「${song.name || song.id}」（区域/版权限制）` };
+        }
+        return { ok: true, message: `正在播放：${song.name || "Unknown"} - ${song.artist || "Unknown"}` };
+      });
+      res.json(body);
+    } catch (err) {
+      res.status(500).json({ error: (err as Error).message });
+    }
+  });
 
-      res.json({ message: `Added to queue: ${song.name || 'Unknown'} - ${song.artist || 'Unknown'} (position ${queue.size()})` });
+  router.post("/:botId/add-song", authorize({ capability: "player.queue", guestFlag: "addToQueue" }), async (req, res) => {
+    try {
+      const bot = (req as any).bot;
+      const { song } = req.body;
+      if (!song || !song.id || !song.platform) {
+        res.status(400).json({ error: "song object with id and platform is required" });
+        return;
+      }
+      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 () => {
+        const queue = bot.getQueueManager();
+        const wasIdle = bot.getPlayer().getState() === "idle";
+        queue.add(song);
+
+        // If nothing was playing, start this newly-added song immediately.
+        if (wasIdle) {
+          queue.playAt(queue.size() - 1);
+          bot.getPlayer().resetFailures();
+          await bot.resolveAndPlay(queue.current()!);
+          return { message: `Now playing: ${song.name || 'Unknown'} - ${song.artist || 'Unknown'}` };
+        }
+
+        return { message: `Added to queue: ${song.name || 'Unknown'} - ${song.artist || 'Unknown'} (position ${queue.size()})` };
+      });
+      res.json(body);
     } catch (err) {
       res.status(500).json({ error: (err as Error).message });
     }
   });
 
   // Add a song to queue by ID — metadata only
-  router.post("/:botId/add-by-id", requirePermission("player.queue"), async (req, res) => {
+  router.post("/:botId/add-by-id", authorize({ capability: "player.queue", guestFlag: "addToQueue" }), async (req, res) => {
     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
           : "netease"
       );
@@ -548,7 +647,7 @@ export function createPlayerRouter(
     res.json(bot.getProfileManager().getConfig());
   });
 
-  router.put("/:botId/profile", requirePermission("bot.manage"), (req, res) => {
+  router.put("/:botId/profile", authorize({ capability: "bot.manage" }), (req, res) => {
     try {
       const bot = (req as any).bot;
       const pm = bot.getProfileManager();

src/web/api/session.test.ts

@@ -8,6 +8,8 @@ import { createUserStore, type UserStore } from "../../data/users.js";
 import { createSessionStore, type SessionStore } from "../../data/sessions.js";
 import { createAuditStore } from "../../data/audit.js";
 import { createPermissionStore } from "../../data/permissions.js";
+import { getDefaultConfig, type GuestModeConfig } from "../../data/config.js";
+import type { GuestPermissions, BotAccess } from "../../data/permissions.js";
 import { createSessionRouter } from "./session.js";
 import { SESSION_COOKIE_NAME } from "../auth/validateSession.js";
 
@@ -17,7 +19,17 @@ function makeApp(botDb: BotDatabase, users: UserStore, sessions: SessionStore) {
   app.use(cookieParser());
   const audit = createAuditStore(botDb.db);
   const permissions = createPermissionStore(botDb.db);
-  app.use("/api/session", createSessionRouter(users, sessions, audit, pino({ level: "silent" }), permissions));
+  app.use(
+    "/api/session",
+    createSessionRouter(
+      users,
+      sessions,
+      audit,
+      pino({ level: "silent" }),
+      permissions,
+      () => getDefaultConfig().guestMode
+    )
+  );
   return app;
 }
 
@@ -47,7 +59,7 @@ describe("session router", () => {
   it("GET /needs-setup returns true on an empty db", async () => {
     const res = await request(app).get("/api/session/needs-setup");
     expect(res.status).toBe(200);
-    expect(res.body).toEqual({ needsSetup: true });
+    expect(res.body).toEqual({ needsSetup: true, guestAllowed: false });
   });
 
   it("POST /setup creates the first admin, logs them in, and returns false from /needs-setup afterwards", async () => {
@@ -59,7 +71,7 @@ describe("session router", () => {
     extractCookie(setupRes);
 
     const needs = await request(app).get("/api/session/needs-setup");
-    expect(needs.body).toEqual({ needsSetup: false });
+    expect(needs.body).toEqual({ needsSetup: false, guestAllowed: false });
   });
 
   it("POST /setup returns 409 once a user already exists", async () => {
@@ -157,3 +169,105 @@ describe("session router", () => {
     expect(u.id).toBe(meA.body.id);
   });
 });
+
+describe("session router — guest mode", () => {
+  let botDb: BotDatabase;
+
+  afterEach(() => botDb.close());
+
+  function makeApp(opts: {
+    guestEnabled: boolean;
+    guestPermissions?: GuestPermissions;
+    guestBots?: BotAccess;
+  }) {
+    botDb = createDatabase(":memory:");
+    const users = createUserStore(botDb.db);
+    const sessions = createSessionStore(botDb.db);
+    const audit = createAuditStore(botDb.db);
+    const permissions = createPermissionStore(botDb.db);
+    const guestCfg: GuestModeConfig = {
+      enabled: opts.guestEnabled,
+      bots: opts.guestBots ?? getDefaultConfig().guestMode.bots,
+      permissions: opts.guestPermissions ?? getDefaultConfig().guestMode.permissions,
+    };
+    const app = express();
+    app.use(express.json());
+    app.use(cookieParser());
+    app.use(
+      "/api/session",
+      createSessionRouter(users, sessions, audit, pino({ level: "silent" }), permissions, () => guestCfg)
+    );
+    return { app, users, sessions };
+  }
+
+  it("POST /guest is 403 when guest mode disabled", async () => {
+    const { app } = makeApp({ guestEnabled: false });
+    const res = await request(app).post("/api/session/guest");
+    expect(res.status).toBe(403);
+  });
+
+  it("POST /guest mints a guest session when enabled, and /me reports role guest + flags", async () => {
+    const { app } = makeApp({
+      guestEnabled: true,
+      guestPermissions: {
+        addToQueue: true,
+        playNext: true,
+        playNow: false,
+        skip: false,
+        transport: false,
+        removeClear: false,
+        playMode: false,
+        playCollection: false,
+      },
+      guestBots: "all",
+    });
+    const login = await request(app).post("/api/session/guest");
+    expect(login.status).toBe(200);
+    expect(login.body.role).toBe("guest");
+    const cookie = login.headers["set-cookie"];
+    const me = await request(app).get("/api/session/me").set("Cookie", cookie);
+    expect(me.body.role).toBe("guest");
+    expect(me.body.guest.addToQueue).toBe(true);
+    expect(me.body.guest.playNext).toBe(true);
+    expect(me.body.capabilities).toEqual([]);
+  });
+
+  it("GET /needs-setup exposes guestAllowed", async () => {
+    const { app } = makeApp({ guestEnabled: true });
+    const res = await request(app).get("/api/session/needs-setup");
+    expect(res.body.guestAllowed).toBe(true);
+  });
+
+  it("GET /me returns 401 for a guest session once guest mode is disabled", async () => {
+    // Build an app whose guest config can be toggled at runtime, mirroring an
+    // admin flipping the setting mid-session (requireAuthInline must reject).
+    botDb = createDatabase(":memory:");
+    const users = createUserStore(botDb.db);
+    const sessions = createSessionStore(botDb.db);
+    const audit = createAuditStore(botDb.db);
+    const permissions = createPermissionStore(botDb.db);
+    const guestCfg: GuestModeConfig = {
+      enabled: true,
+      bots: getDefaultConfig().guestMode.bots,
+      permissions: getDefaultConfig().guestMode.permissions,
+    };
+    const app = express();
+    app.use(express.json());
+    app.use(cookieParser());
+    app.use(
+      "/api/session",
+      createSessionRouter(users, sessions, audit, pino({ level: "silent" }), permissions, () => guestCfg)
+    );
+
+    const login = await request(app).post("/api/session/guest");
+    expect(login.status).toBe(200);
+    const cookie = login.headers["set-cookie"];
+
+    // While enabled, /me works for the guest.
+    expect((await request(app).get("/api/session/me").set("Cookie", cookie)).status).toBe(200);
+
+    // Admin disables guest mode → the in-flight guest session is now invalid.
+    guestCfg.enabled = false;
+    expect((await request(app).get("/api/session/me").set("Cookie", cookie)).status).toBe(401);
+  });
+});

src/web/api/session.ts

@@ -5,7 +5,9 @@ import type { UserStore } from "../../data/users.js";
 import type { SessionStore } from "../../data/sessions.js";
 import type { AuditStore } from "../../data/audit.js";
 import { resolvePermissionContext, type PermissionStore } from "../../data/permissions.js";
-import { SESSION_TTL_MS } from "../../data/sessions.js";
+import { SESSION_TTL_MS, GUEST_SESSION_TTL_MS } from "../../data/sessions.js";
+import { GUEST_USER_ID, GUEST_USERNAME } from "../../data/users.js";
+import type { GuestModeConfig } from "../../data/config.js";
 import { SESSION_COOKIE_NAME, validateSessionFromHeaders, extractSessionToken } from "../auth/validateSession.js";
 
 const FAILED_LOGIN_DELAY_MS = 250;
@@ -51,7 +53,8 @@ export function createSessionRouter(
   sessions: SessionStore,
   audit: AuditStore,
   logger: Logger,
-  permissions: PermissionStore
+  permissions: PermissionStore,
+  getGuestConfig: () => GuestModeConfig
 ): Router {
   const router = Router();
 
@@ -62,6 +65,13 @@ export function createSessionRouter(
       res.status(401).json({ error: "unauthenticated" });
       return;
     }
+    // A guest session is only valid while guest mode is enabled. Disabling it
+    // immediately invalidates any in-flight guest sessions (mirrors createRequireAuth).
+    if (result.role === "guest" && !getGuestConfig().enabled) {
+      clearSessionCookie(res);
+      res.status(401).json({ error: "unauthenticated" });
+      return;
+    }
     req.user = { id: result.userId, username: result.username, role: result.role };
     const token = extractSessionToken(req.headers.cookie);
     if (token) setSessionCookie(res, token);
@@ -69,7 +79,7 @@ export function createSessionRouter(
   };
 
   router.get("/needs-setup", (_req, res) => {
-    res.json({ needsSetup: users.countUsers() === 0 });
+    res.json({ needsSetup: users.countUsers() === 0, guestAllowed: getGuestConfig().enabled });
   });
 
   router.post("/setup", async (req, res) => {
@@ -125,6 +135,26 @@ export function createSessionRouter(
     res.json({ id: user.id, username: user.username, role: user.role });
   });
 
+  router.post("/guest", (_req, res) => {
+    const cfg = getGuestConfig();
+    if (!cfg.enabled) {
+      res.status(403).json({ error: "guest mode disabled" });
+      return;
+    }
+    let token: string;
+    try {
+      // If the reserved guest row is somehow missing, the session FK would
+      // throw; surface a clean 503 rather than letting it become a 500.
+      ({ token } = sessions.createSession(GUEST_USER_ID, { ttlMs: GUEST_SESSION_TTL_MS, skipCap: true }));
+    } catch (err) {
+      logger.error({ err }, "guest session creation failed");
+      res.status(503).json({ error: "guest unavailable" });
+      return;
+    }
+    setSessionCookie(res, token);
+    res.json({ id: GUEST_USER_ID, username: GUEST_USERNAME, role: "guest" });
+  });
+
   router.post("/logout", (req, res) => {
     const token = parseTokenFromCookie(req.headers.cookie);
     if (token) {
@@ -136,13 +166,20 @@ export function createSessionRouter(
 
   router.get("/me", requireAuthInline, (req, res) => {
     const user = req.user!;
-    const ctx = resolvePermissionContext(user.role, user.id, permissions);
+    const cfg = getGuestConfig();
+    const ctx = resolvePermissionContext(
+      user.role,
+      user.id,
+      permissions,
+      user.role === "guest" ? { bots: cfg.bots, permissions: cfg.permissions } : undefined
+    );
     res.json({
       id: user.id,
       username: user.username,
       role: user.role,
       capabilities: [...ctx.capabilities],
       bots: ctx.bots === "all" ? "all" : [...ctx.bots],
+      guest: ctx.guest ?? null,
     });
   });
 

src/web/api/users.test.ts

@@ -4,10 +4,11 @@ import cookieParser from "cookie-parser";
 import request from "supertest";
 import pino from "pino";
 import { createDatabase, type BotDatabase } from "../../data/database.js";
-import { createUserStore, type UserStore } from "../../data/users.js";
+import { createUserStore, GUEST_USER_ID, type UserStore } from "../../data/users.js";
 import { createSessionStore, type SessionStore } from "../../data/sessions.js";
 import { createAuditStore, type AuditStore } from "../../data/audit.js";
 import { createPermissionStore, type PermissionStore } from "../../data/permissions.js";
+import { getDefaultConfig } from "../../data/config.js";
 import { createRequireAuth } from "../middleware/requireAuth.js";
 import { createUsersRouter } from "./users.js";
 import { SESSION_COOKIE_NAME } from "../auth/validateSession.js";
@@ -17,7 +18,7 @@ function makeApp(botDb: BotDatabase, users: UserStore, sessions: SessionStore) {
   app.use(express.json());
   app.use(cookieParser());
   const permissions = createPermissionStore(botDb.db);
-  const requireAuth = createRequireAuth(sessions, permissions);
+  const requireAuth = createRequireAuth(sessions, permissions, () => getDefaultConfig().guestMode);
   const audit = createAuditStore(botDb.db);
   app.use("/api", requireAuth);
   app.use("/api/users", createUsersRouter(users, sessions, audit, pino({ level: "silent" }), permissions));
@@ -152,7 +153,7 @@ describe("users router", () => {
     const localApp = express();
     localApp.use(express.json());
     localApp.use(cookieParser());
-    localApp.use("/api", createRequireAuth(sessions, createPermissionStore(botDb.db)));
+    localApp.use("/api", createRequireAuth(sessions, createPermissionStore(botDb.db), () => getDefaultConfig().guestMode));
     localApp.use(
       "/api/users",
       createUsersRouter(users, sessions, brokenAudit, pino({ level: "silent" }), createPermissionStore(botDb.db))
@@ -341,4 +342,49 @@ describe("users router", () => {
     expect(perms.status).toBe(200);
     expect(perms.body).toEqual({ capabilities: [], bots: [] });
   });
+
+  // --- reserved guest principal is never mutable/visible via user mgmt -------
+  // The synthetic __guest__ row is seeded by createDatabase. findById has no
+  // role filter, so without the 404-guard these by-id handlers would operate
+  // on it (privilege-escalation / DoS / cred-login holes).
+  describe("reserved __guest__ principal is 404 on every by-id handler", () => {
+    it("DELETE /:id → 404 and the guest row survives", async () => {
+      const res = await request(app).delete(`/api/users/${GUEST_USER_ID}`).set("Cookie", aliceCookie);
+      expect(res.status).toBe(404);
+      expect(users.findById(GUEST_USER_ID)).not.toBeNull();
+      expect(users.findById(GUEST_USER_ID)!.role).toBe("guest");
+    });
+
+    it("PATCH /:id/role {role:'admin'} → 404 and the guest role is unchanged", async () => {
+      const res = await request(app)
+        .patch(`/api/users/${GUEST_USER_ID}/role`)
+        .set("Cookie", aliceCookie)
+        .send({ role: "admin" });
+      expect(res.status).toBe(404);
+      expect(users.findById(GUEST_USER_ID)!.role).toBe("guest");
+    });
+
+    it("POST /:id/reset-password → 404 (cannot give the guest a login)", async () => {
+      const res = await request(app)
+        .post(`/api/users/${GUEST_USER_ID}/reset-password`)
+        .set("Cookie", aliceCookie)
+        .send({ newPassword: "guest-new-pw" });
+      expect(res.status).toBe(404);
+    });
+
+    it("GET /:id/permissions → 404", async () => {
+      const res = await request(app)
+        .get(`/api/users/${GUEST_USER_ID}/permissions`)
+        .set("Cookie", aliceCookie);
+      expect(res.status).toBe(404);
+    });
+
+    it("PUT /:id/permissions → 404", async () => {
+      const res = await request(app)
+        .put(`/api/users/${GUEST_USER_ID}/permissions`)
+        .set("Cookie", aliceCookie)
+        .send({ capabilities: ["player.control"], bots: "all" });
+      expect(res.status).toBe(404);
+    });
+  });
 });

src/web/api/users.ts

@@ -1,7 +1,7 @@
 import { Router } from "express";
 import type { Logger } from "../../logger.js";
 import type { UserStore } from "../../data/users.js";
-import { UsernameTakenError } from "../../data/users.js";
+import { UsernameTakenError, GUEST_USER_ID } from "../../data/users.js";
 import type { SessionStore } from "../../data/sessions.js";
 import type { AuditStore } from "../../data/audit.js";
 import { isCapability, BASIC_TIER_CAPABILITIES, type PermissionStore } from "../../data/permissions.js";
@@ -63,6 +63,7 @@ export function createUsersRouter(
 
   router.delete("/:id", (req, res) => {
     const targetId = req.params.id;
+    if (targetId === GUEST_USER_ID) { res.status(404).json({ error: "not found" }); return; }
     // Snapshot target's username BEFORE deletion for audit
     const target = users.findById(targetId);
     if (!target) {
@@ -104,6 +105,7 @@ export function createUsersRouter(
       return;
     }
     const targetId = req.params.id;
+    if (targetId === GUEST_USER_ID) { res.status(404).json({ error: "not found" }); return; }
     const target = users.findById(targetId);
     if (!target) {
       res.status(404).json({ error: "not found" });
@@ -130,6 +132,7 @@ export function createUsersRouter(
 
   router.patch("/:id/role", (req, res) => {
     const targetId = req.params.id;
+    if (targetId === GUEST_USER_ID) { res.status(404).json({ error: "not found" }); return; }
     const { role: newRole } = req.body ?? {};
     if (newRole !== "admin" && newRole !== "member") {
       res.status(400).json({ error: "invalid role" });
@@ -168,6 +171,7 @@ export function createUsersRouter(
   });
 
   router.get("/:id/permissions", (req, res) => {
+    if (req.params.id === GUEST_USER_ID) { res.status(404).json({ error: "not found" }); return; }
     const user = users.findById(req.params.id);
     if (!user) {
       res.status(404).json({ error: "not_found" });
@@ -180,6 +184,7 @@ export function createUsersRouter(
   });
 
   router.put("/:id/permissions", (req, res) => {
+    if (req.params.id === GUEST_USER_ID) { res.status(404).json({ error: "not found" }); return; }
     const user = users.findById(req.params.id);
     if (!user) {
       res.status(404).json({ error: "not_found" });

src/web/middleware/authorize.test.ts

@@ -0,0 +1,37 @@
+import { describe, it, expect, vi } from "vitest";
+import { authorize } from "./authorize.js";
+
+function run(user: any, opts: any) {
+  const req: any = { user };
+  const res: any = { statusCode: 0, body: null, status(c: number) { this.statusCode = c; return this; }, json(b: any) { this.body = b; return this; } };
+  const next = vi.fn();
+  authorize(opts)(req, res, next);
+  return { res, next };
+}
+
+describe("authorize", () => {
+  it("401 when unauthenticated", () => {
+    const { res, next } = run(undefined, { capability: "player.queue" });
+    expect(res.statusCode).toBe(401);
+    expect(next).not.toHaveBeenCalled();
+  });
+  it("admin always passes", () => {
+    const { next } = run({ role: "admin" }, { capability: "bot.manage" });
+    expect(next).toHaveBeenCalled();
+  });
+  it("member passes only with the capability", () => {
+    expect(run({ role: "member", capabilities: new Set(["player.queue"]) }, { capability: "player.queue" }).next).toHaveBeenCalled();
+    expect(run({ role: "member", capabilities: new Set() }, { capability: "player.queue" }).res.statusCode).toBe(403);
+  });
+  it("guest passes only when its flag is enabled", () => {
+    expect(run({ role: "guest", guest: { playNext: true } }, { capability: "player.control", guestFlag: "playNext" }).next).toHaveBeenCalled();
+    expect(run({ role: "guest", guest: { playNext: false } }, { capability: "player.control", guestFlag: "playNext" }).res.statusCode).toBe(403);
+  });
+  it("guest is denied on routes with no guestFlag (e.g. play-song)", () => {
+    expect(run({ role: "guest", guest: { addToQueue: true } }, { capability: "player.control" }).res.statusCode).toBe(403);
+  });
+  it("guest with a non-boolean truthy flag value (1) is denied (strict-boolean gate)", () => {
+    expect(run({ role: "guest", guest: { playNext: 1 } as any }, { guestFlag: "playNext" }).res.statusCode).toBe(403);
+    expect(run({ role: "guest", guest: { playNext: true } }, { guestFlag: "playNext" }).next).toHaveBeenCalled();
+  });
+});

src/web/middleware/authorize.ts

@@ -0,0 +1,29 @@
+import type { Request, Response, NextFunction, RequestHandler } from "express";
+import type { GuestFlag } from "../../data/permissions.js";
+
+/**
+ * Unified authorization gate.
+ * - admin  → always allowed (unchanged from requirePermission)
+ * - member → allowed iff it holds `capability` (unchanged from requirePermission)
+ * - guest  → allowed iff `guestFlag` is set AND that flag is enabled in the
+ *            guest's resolved permissions; a route with no `guestFlag` is
+ *            denied to guests by default.
+ * Generic over the route-param shape `P` for the same reason requirePermission is.
+ */
+export function authorize<P = Record<string, string>>(opts: {
+  capability?: string;
+  guestFlag?: GuestFlag;
+}): RequestHandler<P> {
+  return (req: Request<P>, res: Response, next: NextFunction) => {
+    const user = req.user;
+    if (!user) { res.status(401).json({ error: "unauthenticated" }); return; }
+    if (user.role === "admin") { next(); return; }
+    if (user.role === "guest") {
+      if (opts.guestFlag && user.guest?.[opts.guestFlag] === true) { next(); return; }
+      res.status(403).json({ error: "forbidden" });
+      return;
+    }
+    if (opts.capability && user.capabilities?.has(opts.capability)) { next(); return; }
+    res.status(403).json({ error: "forbidden" });
+  };
+}

src/web/middleware/requireAdmin.test.ts

@@ -6,6 +6,7 @@ import { createDatabase, type BotDatabase } from "../../data/database.js";
 import { createUserStore } from "../../data/users.js";
 import { createSessionStore } from "../../data/sessions.js";
 import { createPermissionStore } from "../../data/permissions.js";
+import { getDefaultConfig } from "../../data/config.js";
 import { createRequireAuth } from "./requireAuth.js";
 import { requireAdmin } from "./requireAdmin.js";
 import { SESSION_COOKIE_NAME } from "../auth/validateSession.js";
@@ -27,7 +28,7 @@ describe("requireAdmin middleware", () => {
     memberCookie = `${SESSION_COOKIE_NAME}=${sessions.createSession(member.id).token}`;
     app = express();
     app.use(cookieParser());
-    app.use(createRequireAuth(sessions, permissions));
+    app.use(createRequireAuth(sessions, permissions, () => getDefaultConfig().guestMode));
     app.use(requireAdmin);
     app.get("/admin-only", (_req, res) => res.json({ ok: true }));
   });

src/web/middleware/requireAuth.test.ts

@@ -1,4 +1,4 @@
-import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
 import express from "express";
 import cookieParser from "cookie-parser";
 import request from "supertest";
@@ -24,7 +24,22 @@ describe("requireAuth middleware", () => {
 
     app = express();
     app.use(cookieParser());
-    app.use(createRequireAuth(sessions, permissions));
+    app.use(
+      createRequireAuth(sessions, permissions, () => ({
+        enabled: true,
+        bots: "all",
+        permissions: {
+          addToQueue: true,
+          playNext: true,
+          playNow: true,
+          skip: true,
+          transport: true,
+          removeClear: true,
+          playMode: true,
+          playCollection: true,
+        },
+      }))
+    );
     app.get("/protected", (req, res) => {
       res.json({ ok: true, user: (req as any).user });
     });
@@ -68,4 +83,34 @@ describe("requireAuth middleware", () => {
     expect(refreshed).toBeDefined();
     expect(refreshed!).toMatch(/Max-Age=\d+/);
   });
+
+  // A guest session is rejected (401) when guest mode is disabled.
+  it("rejects a guest session when guest mode is disabled", () => {
+    const sessions: any = { validateAndTouch: () => ({ userId: "__guest__", username: "游客", role: "guest" }) };
+    const permissions: any = { getCapabilities: () => [], getBotAccess: () => [] };
+    const getGuestConfig = () => ({ enabled: false, bots: "all" as const, permissions: {} as any });
+    const mw = createRequireAuth(sessions, permissions, getGuestConfig);
+    const req: any = { headers: { cookie: "tsmb_session=x" } };
+    const res: any = { statusCode: 0, cleared: false, clearCookie() { this.cleared = true; }, status(c: number) { this.statusCode = c; return this; }, json() { return this; }, cookie() {} };
+    const next = vi.fn();
+    mw(req, res, next);
+    expect(res.statusCode).toBe(401);
+    expect(next).not.toHaveBeenCalled();
+  });
+
+  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, 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 };
+    const res: any = { status() { return this; }, json() { return this; }, cookie() {}, clearCookie() {} };
+    const next = vi.fn();
+    mw(req, res, next);
+    expect(next).toHaveBeenCalled();
+    expect(req.user.role).toBe("guest");
+    expect(req.user.guest.addToQueue).toBe(true);
+    expect(req.user.bots instanceof Set && req.user.bots.has("bot1")).toBe(true);
+  });
 });

src/web/middleware/requireAuth.ts

@@ -1,7 +1,8 @@
 import type { Request, Response, NextFunction, RequestHandler } from "express";
 import type { SessionStore } from "../../data/sessions.js";
 import { SESSION_TTL_MS } from "../../data/sessions.js";
-import { resolvePermissionContext, type PermissionStore } from "../../data/permissions.js";
+import { resolvePermissionContext, type PermissionStore, type GuestPermissions } from "../../data/permissions.js";
+import type { GuestModeConfig } from "../../data/config.js";
 import {
   validateSessionFromHeaders,
   extractSessionToken,
@@ -13,14 +14,19 @@ declare module "express-serve-static-core" {
     user?: {
       id: string;
       username: string;
-      role: "admin" | "member";
+      role: "admin" | "member" | "guest";
       capabilities?: Set<string>;
       bots?: "all" | Set<string>;
+      guest?: GuestPermissions;
     };
   }
 }
 
-export function createRequireAuth(sessions: SessionStore, permissions: PermissionStore): RequestHandler {
+export function createRequireAuth(
+  sessions: SessionStore,
+  permissions: PermissionStore,
+  getGuestConfig: () => GuestModeConfig
+): RequestHandler {
   return function requireAuth(req: Request, res: Response, next: NextFunction) {
     const result = validateSessionFromHeaders(req.headers.cookie, sessions);
     if (!result) {
@@ -28,13 +34,27 @@ export function createRequireAuth(sessions: SessionStore, permissions: Permissio
       res.status(401).json({ error: "unauthenticated" });
       return;
     }
-    const ctx = resolvePermissionContext(result.role, result.userId, permissions);
+    // A guest session is only valid while guest mode is enabled. Disabling it
+    // immediately invalidates any in-flight guest sessions.
+    const guestCfg = getGuestConfig();
+    if (result.role === "guest" && !guestCfg.enabled) {
+      res.clearCookie(SESSION_COOKIE_NAME, { path: "/" });
+      res.status(401).json({ error: "unauthenticated" });
+      return;
+    }
+    const ctx = resolvePermissionContext(
+      result.role,
+      result.userId,
+      permissions,
+      result.role === "guest" ? { bots: guestCfg.bots, permissions: guestCfg.permissions } : undefined
+    );
     req.user = {
       id: result.userId,
       username: result.username,
       role: result.role,
       capabilities: ctx.capabilities,
       bots: ctx.bots,
+      guest: ctx.guest,
     };
     const token = extractSessionToken(req.headers.cookie);
     if (token) {

src/web/middleware/requireNotGuest.test.ts

@@ -0,0 +1,19 @@
+import { describe, it, expect, vi } from "vitest";
+import { requireNotGuest } from "./requireNotGuest.js";
+
+function run(user: any) {
+  const req: any = { user };
+  const res: any = { statusCode: 0, status(c: number) { this.statusCode = c; return this; }, json() { return this; } };
+  const next = vi.fn();
+  requireNotGuest(req, res, next);
+  return { res, next };
+}
+
+describe("requireNotGuest", () => {
+  it("401 when no user", () => { expect(run(undefined).res.statusCode).toBe(401); });
+  it("403 for guests", () => { expect(run({ role: "guest" }).res.statusCode).toBe(403); });
+  it("passes admins and members", () => {
+    expect(run({ role: "admin" }).next).toHaveBeenCalled();
+    expect(run({ role: "member" }).next).toHaveBeenCalled();
+  });
+});

src/web/middleware/requireNotGuest.ts

@@ -0,0 +1,9 @@
+import type { Request, Response, NextFunction } from "express";
+
+/** Allow admins and members; deny login-less guests (used for config reads
+ *  that must never leak to guests, e.g. GET /api/bot/settings, GET /api/music/quality). */
+export function requireNotGuest(req: Request, res: Response, next: NextFunction): void {
+  if (!req.user) { res.status(401).json({ error: "unauthenticated" }); return; }
+  if (req.user.role === "guest") { res.status(403).json({ error: "forbidden" }); return; }
+  next();
+}

src/web/server.ts

@@ -6,7 +6,7 @@ import { WebSocketServer } from "ws";
 import type { BotManager } from "../bot/manager.js";
 import type { MusicProvider } from "../music/provider.js";
 import type { BotDatabase } from "../data/database.js";
-import type { BotConfig } from "../data/config.js";
+import type { BotConfig, GuestModeConfig } from "../data/config.js";
 import type { Logger } from "../logger.js";
 import type { CookieStore } from "../music/auth.js";
 import type { AvatarStore } from "../data/avatars.js";
@@ -25,6 +25,7 @@ import { createSessionStore } from "../data/sessions.js";
 import { createPermissionStore } from "../data/permissions.js";
 import { createRequireAuth } from "./middleware/requireAuth.js";
 import { requireAdmin } from "./middleware/requireAdmin.js";
+import { requireNotGuest } from "./middleware/requireNotGuest.js";
 import { csrfOriginCheck } from "./middleware/csrf.js";
 import { createRateLimit } from "./middleware/rateLimit.js";
 import { validateSessionFromHeaders } from "./auth/validateSession.js";
@@ -37,6 +38,7 @@ export interface WebServerOptions {
   neteaseProvider: MusicProvider;
   qqProvider: MusicProvider;
   bilibiliProvider: MusicProvider;
+  localProvider: MusicProvider;
   database: BotDatabase;
   config: BotConfig;
   configPath: string;
@@ -95,14 +97,19 @@ export function createWebServer(options: WebServerOptions): WebServer {
   app.use("/api/session/login", loginLimit);
   app.use("/api/session/setup", setupLimit);
 
-  app.use("/api/session", createSessionRouter(users, sessions, audit, logger, permissions));
+  app.use("/api/session", createSessionRouter(users, sessions, audit, logger, permissions, () => options.config.guestMode));
 
   // ─── Gates for everything else under /api ───────────────────────────────
-  const requireAuth = createRequireAuth(sessions, permissions);
+  const requireAuth = createRequireAuth(sessions, permissions, () => options.config.guestMode);
   app.use("/api", csrfOriginCheck);
   app.use("/api", requireAuth);
 
   // ─── Protected routes ───────────────────────────────────────────────────
+  // The bot router is mounted BEFORE setupWebSocket runs, but its /settings
+  // handler needs to trigger a guest-policy refresh on the (later-created) WS
+  // controller. Bridge the two with a mutable indirection that starts as a
+  // no-op and is wired to the real refreshGuestPolicy once the WS is set up.
+  let onGuestPolicyChanged: (cfg: GuestModeConfig) => void = () => {};
   app.use(
     "/api/bot",
     createBotRouter(
@@ -112,11 +119,12 @@ export function createWebServer(options: WebServerOptions): WebServer {
       logger,
       options.database,
       options.avatarStore,
+      (cfg) => onGuestPolicyChanged(cfg),
     )
   );
   app.use(
     "/api/music",
-    createMusicRouter(options.neteaseProvider, options.qqProvider, options.bilibiliProvider, logger)
+    createMusicRouter(options.neteaseProvider, options.qqProvider, options.bilibiliProvider, logger, options.localProvider, options.config)
   );
   app.use("/api/player", createPlayerRouter(
     options.botManager, logger, options.database,
@@ -126,7 +134,7 @@ export function createWebServer(options: WebServerOptions): WebServer {
     "/api/auth",
     createAuthRouter(options.neteaseProvider, options.qqProvider, options.bilibiliProvider, logger, options.cookieStore)
   );
-  app.use("/api/favorites", createFavoritesRouter(options.database, logger));
+  app.use("/api/favorites", requireNotGuest, createFavoritesRouter(options.database, logger));
 
   // admin-only routes
   app.use("/api/users", requireAdmin, createUsersRouter(users, sessions, audit, logger, permissions));
@@ -175,12 +183,27 @@ export function createWebServer(options: WebServerOptions): WebServer {
       socket.destroy();
       return;
     }
+    // Guest sessions are only valid while guest mode is enabled.
+    if (result.role === "guest" && !options.config.guestMode.enabled) {
+      socket.write("HTTP/1.1 401 Unauthorized\r\nConnection: close\r\n\r\n");
+      socket.destroy();
+      return;
+    }
+    const guestBots = options.config.guestMode.bots;
+    const botScope: "all" | Set<string> =
+      result.role === "guest"
+        ? guestBots === "all" ? "all" : new Set(guestBots)
+        : "all";
     wss.handleUpgrade(req, socket, head, (ws) => {
-      (ws as unknown as { userId: string }).userId = result.userId;
+      const w = ws as unknown as { userId: string; isGuest: boolean; botScope: "all" | Set<string> };
+      w.userId = result.userId;
+      w.isGuest = result.role === "guest";
+      w.botScope = botScope;
       wss.emit("connection", ws, req);
     });
   });
-  const cleanupWs = setupWebSocket(wss, options.botManager, logger);
+  const controller = setupWebSocket(wss, options.botManager, logger);
+  onGuestPolicyChanged = controller.refreshGuestPolicy;
 
   // ─── Session cleanup interval ──────────────────────────────────────────
   let cleanupTimer: ReturnType<typeof setInterval> | null = null;
@@ -206,7 +229,7 @@ export function createWebServer(options: WebServerOptions): WebServer {
         clearInterval(cleanupTimer);
         cleanupTimer = null;
       }
-      cleanupWs();
+      controller.cleanup();
       wss.close();
       server.close();
     },

src/web/websocket-auth.test.ts

@@ -7,6 +7,7 @@ import { createDatabase, type BotDatabase } from "../data/database.js";
 import { createUserStore } from "../data/users.js";
 import { createSessionStore } from "../data/sessions.js";
 import { validateSessionFromHeaders, SESSION_COOKIE_NAME } from "./auth/validateSession.js";
+import { setupWebSocket } from "./websocket.js";
 
 function buildServer(sessions: ReturnType<typeof createSessionStore>) {
   const app = express();
@@ -72,3 +73,109 @@ describe("WebSocket auth at upgrade", () => {
     ws.close();
   });
 });
+
+describe("WebSocket guest bot scope", () => {
+  it("guest init is filtered to the guest bot scope", () => {
+    const sent: any[] = [];
+    const fakeWs: any = {
+      readyState: 1,
+      isGuest: true,
+      botScope: new Set(["bot1"]),
+      send: (m: string) => sent.push(JSON.parse(m)),
+      on: () => {},
+    };
+    const fakeWss: any = {
+      on: (ev: string, cb: any) => {
+        if (ev === "connection") fakeWss._conn = cb;
+      },
+    };
+    const makeBot = (id: string) => ({
+      id,
+      getStatus: () => ({ id }),
+      getQueue: () => [],
+      on: () => {},
+      removeListener: () => {},
+    });
+    const botManager: any = {
+      getAllBots: () => [makeBot("bot1"), makeBot("bot2")],
+      on: () => {},
+      off: () => {},
+      removeListener: () => {},
+    };
+    const { cleanup } = setupWebSocket(fakeWss, botManager, {
+      debug() {},
+      error() {},
+      info() {},
+      warn() {},
+    } as any);
+    fakeWss._conn(fakeWs);
+    const init = sent.find((m) => m.type === "init");
+    expect(init.bots.map((b: any) => b.id)).toEqual(["bot1"]);
+    cleanup();
+  });
+});
+
+describe("WebSocket refreshGuestPolicy", () => {
+  function makeHarness() {
+    const clients: any[] = [];
+    const fakeWss: any = {
+      on: (ev: string, cb: any) => {
+        if (ev === "connection") fakeWss._conn = cb;
+      },
+    };
+    const botManager: any = {
+      getAllBots: () => [],
+      on: () => {},
+      off: () => {},
+      removeListener: () => {},
+    };
+    const logger = { debug() {}, error() {}, info() {}, warn() {} } as any;
+    const controller = setupWebSocket(fakeWss, botManager, logger);
+    // Connect fake sockets via the connection handler so they land in `clients`.
+    const connect = (ws: any) => {
+      clients.push(ws);
+      fakeWss._conn(ws);
+    };
+    return { controller, connect };
+  }
+
+  function makeFakeWs(opts: { isGuest: boolean; botScope?: "all" | Set<string> }) {
+    const closeCalls: Array<{ code?: number; reason?: string }> = [];
+    const ws: any = {
+      readyState: 1,
+      isGuest: opts.isGuest,
+      botScope: opts.botScope,
+      send: () => {},
+      on: () => {},
+      close: (code?: number, reason?: string) => closeCalls.push({ code, reason }),
+    };
+    return { ws, closeCalls };
+  }
+
+  it("disabling guest mode closes guest sockets but leaves non-guest sockets open", () => {
+    const { controller, connect } = makeHarness();
+    const guest = makeFakeWs({ isGuest: true, botScope: new Set(["bot1"]) });
+    const member = makeFakeWs({ isGuest: false, botScope: "all" });
+    connect(guest.ws);
+    connect(member.ws);
+
+    controller.refreshGuestPolicy({ enabled: false, bots: "all" });
+
+    expect(guest.closeCalls.length).toBe(1);
+    expect(guest.closeCalls[0].code).toBe(1008);
+    expect(member.closeCalls.length).toBe(0);
+  });
+
+  it("narrowing the guest scope live re-scopes open guest sockets", () => {
+    const { controller, connect } = makeHarness();
+    const guest = makeFakeWs({ isGuest: true, botScope: new Set(["bot1"]) });
+    connect(guest.ws);
+
+    controller.refreshGuestPolicy({ enabled: true, bots: ["bot2"] });
+
+    expect(guest.closeCalls.length).toBe(0);
+    expect(guest.ws.botScope instanceof Set).toBe(true);
+    expect(guest.ws.botScope.has("bot2")).toBe(true);
+    expect(guest.ws.botScope.has("bot1")).toBe(false);
+  });
+});

src/web/websocket.ts

@@ -3,13 +3,34 @@ import type { BotManager } from "../bot/manager.js";
 import type { BotInstance } from "../bot/instance.js";
 import type { Logger } from "../logger.js";
 
+export interface WebSocketController {
+  cleanup: () => void;
+  /**
+   * Re-apply the current guest-mode policy to every already-open guest socket.
+   * If guest mode is disabled, in-flight guest sockets are force-closed; otherwise
+   * each guest socket is live re-scoped so out-of-scope bots stop streaming.
+   */
+  refreshGuestPolicy: (cfg: { enabled: boolean; bots: "all" | string[] }) => void;
+}
+
 export function setupWebSocket(
   wss: WebSocketServer,
   botManager: BotManager,
   logger: Logger
-): () => void {
+): WebSocketController {
   const clients = new Set<WebSocket>();
 
+  /**
+   * Whether a given bot is visible to a WebSocket client. Member/admin clients
+   * (non-guest) and guests with full scope see everything; scoped guests only
+   * see bots in their allowed set.
+   */
+  function visibleToClient(ws: WebSocket, botId: string): boolean {
+    const w = ws as unknown as { isGuest?: boolean; botScope?: "all" | Set<string> };
+    if (!w.isGuest || w.botScope === "all" || !w.botScope) return true;
+    return w.botScope.has(botId);
+  }
+
   /** Track which bot instances have listeners attached (keyed by id, storing ref) */
   const attachedBots = new Map<string, {
     bot: BotInstance;
@@ -22,7 +43,10 @@ export function setupWebSocket(
     clients.add(ws);
     logger.debug("WebSocket client connected");
 
-    const bots = botManager.getAllBots().map((b) => b.getStatus());
+    const bots = botManager
+      .getAllBots()
+      .filter((b) => visibleToClient(ws, b.id))
+      .map((b) => b.getStatus());
     ws.send(JSON.stringify({ type: "init", bots }));
 
     ws.on("close", () => {
@@ -36,15 +60,15 @@ export function setupWebSocket(
     });
   });
 
-  const broadcast = (data: object) => {
+  const broadcast = (data: object, botId?: string) => {
     const message = JSON.stringify(data);
     for (const client of clients) {
-      if (client.readyState === WebSocket.OPEN) {
-        try {
-          client.send(message);
-        } catch {
-          clients.delete(client);
-        }
+      if (client.readyState !== WebSocket.OPEN) continue;
+      if (botId !== undefined && !visibleToClient(client, botId)) continue;
+      try {
+        client.send(message);
+      } catch {
+        clients.delete(client);
       }
     }
   };
@@ -72,7 +96,7 @@ export function setupWebSocket(
         botId: bot.id,
         status: bot.getStatus(),
         queue: bot.getQueue(),
-      });
+      }, bot.id);
     };
 
     const onConnected = () => {
@@ -80,7 +104,7 @@ export function setupWebSocket(
         type: "botConnected",
         botId: bot.id,
         status: bot.getStatus(),
-      });
+      }, bot.id);
     };
 
     const onDisconnected = () => {
@@ -88,7 +112,7 @@ export function setupWebSocket(
         type: "botDisconnected",
         botId: bot.id,
         status: bot.getStatus(),
-      });
+      }, bot.id);
     };
 
     bot.on("stateChange", onStateChange);
@@ -117,7 +141,7 @@ export function setupWebSocket(
   // React when a bot is removed: detach its listener and tell clients to drop it
   const onBotInstanceRemoved = (id: string) => {
     detachBotListener(id);
-    broadcast({ type: "botRemoved", botId: id });
+    broadcast({ type: "botRemoved", botId: id }, id);
   };
   botManager.on("botInstanceRemoved", onBotInstanceRemoved);
 
@@ -136,7 +160,7 @@ export function setupWebSocket(
   }, 5000);
   ensureAllBotsAttached();
 
-  return () => {
+  const cleanup = () => {
     clearInterval(intervalId);
     botManager.removeListener("botInstance", onBotInstance);
     botManager.removeListener("botInstanceRemoved", onBotInstanceRemoved);
@@ -145,4 +169,25 @@ export function setupWebSocket(
       detachBotListener(id);
     }
   };
+
+  // When the admin changes guestMode (disable / narrow scope), already-open guest
+  // sockets must stop streaming immediately — their isGuest/botScope were stamped
+  // once at upgrade and would otherwise keep receiving bot state.
+  const refreshGuestPolicy = (cfg: { enabled: boolean; bots: "all" | string[] }) => {
+    for (const ws of clients) {
+      const w = ws as unknown as { isGuest?: boolean; botScope?: "all" | Set<string> };
+      if (!w.isGuest) continue;
+      if (!cfg.enabled) {
+        try {
+          ws.close(1008, "guest mode disabled");
+        } catch {
+          // socket may already be closing; ignore
+        }
+      } else {
+        w.botScope = cfg.bots === "all" ? "all" : new Set(cfg.bots);
+      }
+    }
+  };
+
+  return { cleanup, refreshGuestPolicy };
 }

web/src/App.vue

@@ -19,22 +19,22 @@
         <div class="m-player-artist">{{ currentSong.artist }}</div>
       </div>
       <div class="m-player-controls" @click.stop>
-        <button class="m-player-btn" @click="playerStore.prev()">
+        <button v-if="can('player.control')" class="m-player-btn" @click="playerStore.prev()">
           <Icon icon="mdi:skip-previous" />
         </button>
-        <button class="m-player-btn" @click="playerStore.isPlaying ? playerStore.pause() : playerStore.resume()">
+        <button v-if="canTransport" class="m-player-btn" @click="playerStore.isPlaying ? playerStore.pause() : playerStore.resume()">
           <Icon :icon="playerStore.isPlaying ? 'mdi:pause' : 'mdi:play'" />
         </button>
-        <button class="m-player-btn" @click="playerStore.next()">
+        <button v-if="canSkip" class="m-player-btn" @click="playerStore.next()">
           <Icon icon="mdi:skip-next" />
         </button>
-        <button class="m-player-btn" @click="cycleMobileMode">
+        <button v-if="canModeCtl" class="m-player-btn" @click="cycleMobileMode">
           <Icon :icon="mobileModeIcon" />
         </button>
         <button class="m-player-btn" @click="toggleMobileQueue">
           <Icon icon="mdi:playlist-music" />
         </button>
-        <button class="m-player-btn" @click="toggleMobileVolume">
+        <button v-if="canTransport" class="m-player-btn" @click="toggleMobileVolume">
           <Icon icon="mdi:volume-high" />
         </button>
       </div>
@@ -66,7 +66,7 @@
         <Icon icon="mdi:music-box-multiple" class="tab-icon" />
         <span class="tab-label">音乐库</span>
       </RouterLink>
-      <RouterLink to="/settings" class="m-tab" :class="{ active: route.path.startsWith('/settings') }">
+      <RouterLink v-if="!session.isGuest.value" to="/settings" class="m-tab" :class="{ active: route.path.startsWith('/settings') }">
         <Icon icon="mdi:cog" class="tab-icon" />
         <span class="tab-label">设置</span>
       </RouterLink>
@@ -80,6 +80,7 @@ import { useRoute, useRouter } from 'vue-router';
 import { Icon } from '@iconify/vue';
 import { usePlayerStore } from './stores/player.js';
 import { useWebSocket } from './composables/useWebSocket.js';
+import { useSession } from './composables/useSession.js';
 import Navbar from './components/Navbar.vue';
 import Player from './components/Player.vue';
 import CoverArt from './components/CoverArt.vue';
@@ -87,6 +88,12 @@ import Toast from './components/Toast.vue';
 import Queue from './components/Queue.vue';
 
 const playerStore = usePlayerStore();
+const session = useSession();
+const { can, guestCan } = session;
+// Mobile mini-player transport gating — mirrors components/Player.vue.
+const canTransport = computed(() => can('player.control') || guestCan('transport'));
+const canSkip = computed(() => can('player.control') || guestCan('skip'));
+const canModeCtl = computed(() => can('player.control') || guestCan('playMode'));
 const theme = computed(() => playerStore.theme);
 const route = useRoute();
 const router = useRouter();
@@ -111,8 +118,10 @@ 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);
 }

web/src/components/Navbar.vue

@@ -98,14 +98,14 @@
         </div>
       </div>
 
-      <RouterLink to="/settings" class="settings-btn">
+      <RouterLink v-if="!session.isGuest.value" to="/settings" class="settings-btn">
         <Icon icon="mdi:cog" />
       </RouterLink>
 
       <div v-if="session.currentUser.value" class="nav-user">
         <span class="nav-user-name">{{ session.currentUser.value.username }}</span>
         <span class="nav-user-role" :class="`role-${session.currentUser.value.role}`">
-          {{ session.currentUser.value.role === 'admin' ? '管理员' : '成员' }}
+          {{ session.currentUser.value.role === 'admin' ? '管理员' : session.currentUser.value.role === 'guest' ? '游客' : '成员' }}
         </span>
         <button class="nav-user-logout" @click="onLogout" title="退出">
           <Icon icon="mdi:logout" />
@@ -769,4 +769,5 @@ onUnmounted(() => {
 }
 .role-admin { background: rgba(99, 145, 226, 0.18); color: #6391e2; }
 .role-member { background: rgba(150, 150, 150, 0.18); color: var(--text-secondary); }
+.role-guest { background: rgba(150, 150, 150, 0.18); color: var(--text-secondary); }
 </style>

web/src/components/Player.vue

@@ -3,10 +3,10 @@
     <Queue :open="showQueue" @close="showQueue = false" />
 
     <div class="player-bar frosted-glass">
-      <!-- Progress bar (read-only display; seek interaction gated on player.control) -->
+      <!-- Progress bar (read-only display; seek interaction gated on transport / canTransport) -->
       <div
         class="progress-bar-container"
-        :class="{ 'no-seek': !canControl }"
+        :class="{ 'no-seek': !canTransport }"
         ref="progressBarRef"
         @click="onProgressClick"
         @mousemove="onProgressHover"
@@ -38,18 +38,18 @@
 
       <div class="player-center">
         <span class="time-display time-current">{{ formatTime(currentElapsed) }}</span>
-        <!-- Transport controls require player.control -->
-        <template v-if="canControl">
-          <button class="control-btn" @click="store.prev()">
+        <!-- Transport controls: per-button gating honoring guest flags -->
+        <template v-if="canControl || canTransport || canSkip || canModeCtl">
+          <button v-if="canControl" class="control-btn" @click="store.prev()">
             <Icon icon="mdi:skip-previous" />
           </button>
-          <button class="play-btn" @click="togglePlay">
+          <button v-if="canTransport" class="play-btn" @click="togglePlay">
             <Icon :icon="store.isPlaying ? 'mdi:pause' : 'mdi:play'" />
           </button>
-          <button class="control-btn" @click="store.next()">
+          <button v-if="canSkip" class="control-btn" @click="store.next()">
             <Icon icon="mdi:skip-next" />
           </button>
-          <button class="control-btn mode-btn" @click="cycleMode" :title="modeLabel">
+          <button v-if="canModeCtl" class="control-btn mode-btn" @click="cycleMode" :title="modeLabel">
             <Icon :icon="modeIcon" />
             <span class="mode-label">{{ modeLabel }}</span>
           </button>
@@ -58,8 +58,8 @@
       </div>
 
       <div class="player-right">
-        <!-- Volume requires player.control -->
-        <template v-if="canControl">
+        <!-- Volume gated on transport -->
+        <template v-if="canTransport">
           <Icon icon="mdi:volume-high" class="volume-icon" />
           <input
             type="range"
@@ -94,8 +94,11 @@ const route = useRoute();
 const router = useRouter();
 const showQueue = ref(false);
 
-const { can } = useSession();
+const { can, guestCan } = useSession();
 const canControl = computed(() => can('player.control'));
+const canTransport = computed(() => can('player.control') || guestCan('transport'));
+const canSkip = computed(() => can('player.control') || guestCan('skip'));
+const canModeCtl = computed(() => can('player.control') || guestCan('playMode'));
 
 const store = usePlayerStore();
 const activeBot = computed(() => store.activeBot);
@@ -132,8 +135,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
@@ -144,7 +148,7 @@ function updateProgress() {
 }
 
 async function onProgressClick(e: MouseEvent) {
-  if (!canControl.value) return; // seek requires player.control
+  if (!canTransport.value) return; // seek gated on transport (canTransport)
   const bar = progressBarRef.value;
   if (!bar) return;
   const rect = bar.getBoundingClientRect();

web/src/components/Queue.vue

@@ -4,7 +4,7 @@
       <h3 class="queue-title">播放队列</h3>
       <span class="queue-count">{{ botQueue.length }} 首</span>
       <button
-        v-if="botQueue.length > 0 && can('player.control')"
+        v-if="botQueue.length > 0 && (can('player.control') || guestCan('removeClear'))"
         class="clear-btn"
         @click="clearAndStop"
         title="清空队列并停止播放"
@@ -33,7 +33,7 @@
           <div class="queue-song-name">{{ song.name }}</div>
           <div class="queue-song-artist">{{ song.artist }}</div>
         </div>
-        <button v-if="can('player.queue')" class="remove-btn" @click="removeSong(i)" title="移除">
+        <button v-if="can('player.queue') || guestCan('removeClear')" class="remove-btn" @click="removeSong(i)" title="移除">
           <Icon icon="mdi:close" />
         </button>
       </div>
@@ -58,7 +58,7 @@ defineEmits<{
 }>();
 
 const store = usePlayerStore();
-const { can } = useSession();
+const { can, guestCan } = useSession();
 const botQueue = computed(() => store.queue);
 
 // Fetch queue when panel opens

web/src/components/SongCard.vue

@@ -1,5 +1,5 @@
 <template>
-  <div class="song-card" :class="{ active }" @dblclick="$emit('play')">
+  <div class="song-card" :class="{ active }" @dblclick="showPlay && $emit('play')">
     <div class="song-index">{{ index }}</div>
     <CoverArt :url="song.coverUrl" :size="36" :radius="6" />
     <div class="song-info">
@@ -7,21 +7,21 @@
         <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' : 'badge-netease'"
+        >{{ song.platform === 'bilibili' ? 'B站' : song.platform === 'qq' ? 'QQ' : song.platform === 'youtube' ? 'YouTube' : song.platform === 'local' ? '本地' : '网易云' }}</span>
       </div>
       <div class="song-artist">{{ song.artist }}</div>
     </div>
     <div class="song-album">{{ song.album }}</div>
     <div class="song-duration">{{ formatDuration(song.duration) }}</div>
     <div class="song-actions">
-      <button class="action-btn" @click.stop="$emit('play')" title="播放">
+      <button v-if="showPlay" class="action-btn" @click.stop="$emit('play')" title="播放">
         <Icon icon="mdi:play" />
       </button>
-      <button class="action-btn" @click.stop="$emit('playNext')" title="下一首播放">
+      <button v-if="showPlayNext" class="action-btn" @click.stop="$emit('playNext')" title="下一首播放">
         <Icon icon="mdi:playlist-play" />
       </button>
-      <button class="action-btn" @click.stop="$emit('add')" title="添加到队列">
+      <button v-if="showAdd" class="action-btn" @click.stop="$emit('add')" title="添加到队列">
         <Icon icon="mdi:playlist-plus" />
       </button>
     </div>
@@ -29,9 +29,11 @@
 </template>
 
 <script setup lang="ts">
+import { computed } from 'vue';
 import { Icon } from '@iconify/vue';
 import CoverArt from './CoverArt.vue';
 import { Song } from '../stores/player.js';
+import { useSession } from '../composables/useSession.js';
 
 defineProps<{
   song: Song;
@@ -39,6 +41,11 @@ defineProps<{
   active?: boolean;
 }>();
 
+const { can, guestCan } = useSession();
+const showPlay = computed(() => can('player.control') || guestCan('playNow'));
+const showPlayNext = computed(() => can('player.control') || guestCan('playNext'));
+const showAdd = computed(() => can('player.queue') || guestCan('addToQueue'));
+
 defineEmits<{
   play: [];
   playNext: [];
@@ -128,6 +135,11 @@ function formatDuration(seconds: number): string {
   color: var(--brand-youtube);
 }
 
+.badge-local {
+  background: var(--color-primary-10);
+  color: var(--color-primary);
+}
+
 .song-artist {
   font-size: 12px;
   color: var(--text-secondary);

web/src/composables/useSession.ts

@@ -3,13 +3,15 @@ import { ref, computed, readonly } from "vue";
 interface User {
   id: string;
   username: string;
-  role: 'admin' | 'member';
+  role: 'admin' | 'member' | 'guest';
   capabilities?: string[];
   bots?: "all" | string[];
+  guest?: Record<string, boolean> | null;
 }
 
 const currentUser = ref<User | null>(null);
 const needsSetup = ref<boolean | null>(null); // null = unknown / not fetched yet
+const guestAllowed = ref(false);
 const ready = ref(false);
 
 let pollTimer: ReturnType<typeof setInterval> | null = null;
@@ -37,6 +39,7 @@ async function refreshNeedsSetup(): Promise<void> {
   if (res.ok) {
     const body = await res.json();
     needsSetup.value = Boolean(body.needsSetup);
+    guestAllowed.value = Boolean(body.guestAllowed);
   }
 }
 
@@ -76,6 +79,16 @@ async function login(username: string, password: string): Promise<void> {
   await refreshMe();
 }
 
+async function continueAsGuest(): Promise<void> {
+  const res = await fetch("/api/session/guest", { method: "POST", credentials: "same-origin" });
+  if (!res.ok) {
+    const body = await res.json().catch(() => ({}));
+    throw new Error(body.error ?? `guest entry failed (${res.status})`);
+  }
+  currentUser.value = (await res.json()) as User;
+  await refreshMe(); // authoritative role + guest flags + bots
+}
+
 async function setup(username: string, password: string): Promise<void> {
   const res = await fetch("/api/session/setup", {
     method: "POST",
@@ -104,6 +117,11 @@ function can(cap: string): boolean {
   return !!u && (u.role === "admin" || (u.capabilities ?? []).includes(cap));
 }
 
+function guestCan(flag: string): boolean {
+  const u = currentUser.value;
+  return !!u && u.role === "guest" && !!u.guest && u.guest[flag] === true;
+}
+
 function canControlBot(botId: string): boolean {
   const u = currentUser.value;
   if (!u) return false;
@@ -115,14 +133,18 @@ export function useSession() {
   return {
     currentUser: readonly(currentUser),
     needsSetup: readonly(needsSetup),
+    guestAllowed: readonly(guestAllowed),
     isAuthenticated: computed(() => currentUser.value !== null),
     isAdmin: computed(() => currentUser.value?.role === 'admin'),
+    isGuest: computed(() => currentUser.value?.role === 'guest'),
     ready: readonly(ready),
     refresh,
     login,
     logout,
     setup,
+    continueAsGuest,
     can,
+    guestCan,
     canControlBot,
   };
 }

web/src/router/index.ts

@@ -58,6 +58,12 @@ router.beforeEach(async (to) => {
     return { name: 'login', query: { next: to.fullPath } };
   }
 
+  // Guests may never reach settings/setup, even by typing the URL.
+  const GUEST_BLOCKED = new Set(['settings', 'setup']);
+  if (session.isGuest.value && GUEST_BLOCKED.has(to.name as string)) {
+    return { name: 'home' };
+  }
+
   // Navigation is allowed to proceed to `to` past here (auth/setup redirects above take precedence).
   // Sync + preserve the dedicated-link scope carried by ?bot.
   const store = usePlayerStore();

web/src/stores/elapsed.test.ts

@@ -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);
+  });
+});

web/src/stores/player.ts

@@ -1,6 +1,7 @@
 import { defineStore } from 'pinia';
 import axios from 'axios';
 import { resolveScopedBot } from './scope.js';
+import { useSession } from '../composables/useSession.js';
 
 export interface Song {
   id: string;
@@ -9,7 +10,7 @@ export interface Song {
   album: string;
   duration: number;
   coverUrl: string;
-  platform: 'netease' | 'qq' | 'bilibili' | 'youtube';
+  platform: 'netease' | 'qq' | 'bilibili' | 'youtube' | 'local';
 }
 
 export type Source = 'netease' | 'qq';
@@ -46,7 +47,7 @@ export interface FavoritePlaylist {
   createdAt: string;
 }
 
-interface TimingState {
+export interface TimingState {
   serverElapsed: number;
   serverSyncTime: number;
   wasPlaying: boolean;
@@ -58,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[],
@@ -110,15 +138,19 @@ 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[] {
@@ -130,6 +162,21 @@ export const usePlayerStore = defineStore('player', {
   },
 
   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();
@@ -334,7 +381,10 @@ export const usePlayerStore = defineStore('player', {
 
     async playSong(song: Song) {
       if (!this.activeBotId) return;
-      const res = await axios.post(`/api/player/${this.activeBotId}/play-song`, { song });
+      // Guests use the non-destructive "play now" (insert-next + skip) so they
+      // can't wipe everyone else's queue; members/admins keep the normal behavior.
+      const endpoint = useSession().isGuest.value ? 'play-now-song' : 'play-song';
+      const res = await axios.post(`/api/player/${this.activeBotId}/${endpoint}`, { song });
       if (res.data?.ok === false && res.data?.message) {
         this.notify(res.data.message, 'error');
       }
@@ -369,29 +419,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`);

web/src/views/Login.vue

@@ -13,6 +13,15 @@
       <p v-if="error" class="auth-error">{{ error }}</p>
       <button type="submit" :disabled="loading">{{ loading ? '登录中…' : '登录' }}</button>
     </form>
+    <button
+      v-if="session.guestAllowed.value"
+      type="button"
+      class="guest-btn"
+      :disabled="loading"
+      @click="enterAsGuest"
+    >
+      以游客身份进入
+    </button>
   </div>
 </template>
 
@@ -43,12 +52,28 @@ async function submit() {
     loading.value = false;
   }
 }
+
+async function enterAsGuest() {
+  error.value = '';
+  loading.value = true;
+  try {
+    await session.continueAsGuest();
+    const rawNext = typeof route.query.next === 'string' ? route.query.next : '/';
+    const next = rawNext.startsWith('/') && !rawNext.startsWith('//') ? rawNext : '/';
+    router.replace(next);
+  } catch (e) {
+    error.value = (e as Error).message;
+  } finally {
+    loading.value = false;
+  }
+}
 </script>
 
 <style scoped lang="scss">
 .auth-page {
   min-height: 100vh;
   display: flex;
+  flex-direction: column;
   align-items: center;
   justify-content: center;
   background: var(--bg-primary);
@@ -75,4 +100,11 @@ async function submit() {
 }
 .auth-card button:disabled { opacity: 0.6; cursor: progress; }
 .auth-error { color: #e26a6a; font-size: 13px; margin: 0; }
+.guest-btn {
+  width: 360px; height: 38px; margin-top: 4px; border-radius: var(--radius-sm);
+  background: transparent; color: var(--text-secondary);
+  border: 1px solid var(--border-color); cursor: pointer;
+}
+.guest-btn:hover { color: var(--text-primary); }
+.guest-btn:disabled { opacity: 0.6; cursor: progress; }
 </style>

web/src/views/Lyrics.vue

@@ -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) {

web/src/views/Playlist.vue

@@ -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';
 

web/src/views/Search.vue

@@ -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,12 @@
           :class="{ active: selectedSource === 'bilibili' }"
           @click="selectedSource = 'bilibili'"
         >B站</button>
+        <button
+          v-if="hasLocalSongs"
+          class="source-btn"
+          :class="{ active: selectedSource === 'local' }"
+          @click="selectedSource = 'local'"
+        >本地</button>
       </div>
 
       <div class="tab-bar">
@@ -48,7 +89,7 @@
           单曲<span class="tab-count">{{ filteredSongs.length }}</span>
         </button>
         <button
-          v-if="selectedSource !== 'bilibili'"
+          v-if="selectedSource !== 'bilibili' && selectedSource !== 'local'"
           class="tab"
           :class="{ active: activeTab === 'albums' }"
           @click="activeTab = 'albums'"
@@ -56,7 +97,7 @@
           专辑<span class="tab-count">{{ filteredAlbums.length }}</span>
         </button>
         <button
-          v-if="selectedSource !== 'bilibili'"
+          v-if="selectedSource !== 'bilibili' && selectedSource !== 'local'"
           class="tab"
           :class="{ active: activeTab === 'playlists' }"
           @click="activeTab = 'playlists'"
@@ -141,17 +182,19 @@ const router = useRouter();
 
 const SOURCE_STORAGE_KEY = 'search-source';
 
-function loadSource(): 'netease' | 'qq' | 'bilibili' {
+type SearchSource = 'netease' | 'qq' | 'bilibili' | 'local';
+
+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') return stored;
   } catch { /* localStorage blocked */ }
   return 'netease';
 }
 
 const query = ref((route.query.q as string) || '');
 const activeTab = ref<'songs' | 'albums' | 'playlists'>('songs');
-const selectedSource = ref<'netease' | 'qq' | 'bilibili'>(loadSource());
+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; }
@@ -161,6 +204,12 @@ const allAlbums = ref<Album[]>([]);
 const allPlaylists = ref<Playlist[]>([]);
 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 +223,16 @@ const filteredPlaylists = computed(() =>
   allPlaylists.value.filter((p) => p.platform === selectedSource.value)
 );
 
+const hasLocalSongs = computed(() => localAudioEnabled.value && allSongs.value.some((s) => s.platform === 'local'));
+
 // 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') && activeTab.value !== 'songs') {
     activeTab.value = 'songs';
   }
 });
@@ -223,10 +274,83 @@ 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 '本地';
   return '网易云';
 }
 
@@ -234,10 +358,24 @@ 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';
   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 +396,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;
@@ -422,6 +640,11 @@ onMounted(() => {
   color: var(--brand-youtube);
 }
 
+.badge-local {
+  background: var(--color-primary-10);
+  color: var(--color-primary);
+}
+
 .fav-badge {
   position: absolute;
   top: 8px;

web/src/views/Settings.vue

@@ -98,8 +98,12 @@
             </div>
           </div>
           <div class="form-group">
-            <label>默认频道（可选）</label>
-            <input v-model="editForm.defaultChannel" class="input" placeholder="音乐频道" />
+            <label>默认频道名称（可选）</label>
+            <input v-model="editForm.defaultChannel" :disabled="!!editForm.channelId" class="input" :class="{ disabled: !!editForm.channelId }" placeholder="音乐频道" />
+          </div>
+          <div class="form-group">
+            <label>默认频道ID（可选）</label>
+            <input v-model="editForm.channelId" :disabled="!!editForm.defaultChannel" class="input" :class="{ disabled: !!editForm.defaultChannel }" placeholder="如 12" />
           </div>
           <div class="form-group">
             <label>频道密码（可选）</label>
@@ -142,8 +146,12 @@
           <input v-model="newBotNickname" class="input" placeholder="MusicBot" />
         </div>
         <div class="form-group">
-          <label>默认频道（可选）</label>
-          <input v-model="newBotChannel" class="input" placeholder="音乐频道" />
+          <label>默认频道名称（可选）</label>
+          <input v-model="newBotChannel" :disabled="!!newBotChannelId" class="input" :class="{ disabled: !!newBotChannelId }" placeholder="音乐频道" />
+        </div>
+        <div class="form-group">
+          <label>默认频道ID（可选）</label>
+          <input v-model="newBotChannelId" :disabled="!!newBotChannel" class="input" :class="{ disabled: !!newBotChannel }" placeholder="如 12" />
         </div>
         <div class="form-group">
           <label>服务器密码（可选）</label>
@@ -417,7 +425,7 @@
           <Icon icon="mdi:timer-off-outline" class="setting-icon" />
           <div>
             <div>闲置自动退出</div>
-            <div style="font-size:12px; opacity:0.6; margin-top:2px">频道无人时，机器人自动断开的等待时间（0 = 不退出）</div>
+            <div style="font-size:12px; opacity:0.6; margin-top:2px">服务器上没有其他人时，机器人自动断开的等待时间（0 = 不退出）</div>
           </div>
         </div>
         <div class="prefix-input-wrap">
@@ -435,8 +443,8 @@
       </div>
       <label class="profile-toggle behavior-toggle">
         <div class="profile-toggle-text">
-          <div class="profile-toggle-label">频道无人时自动暂停播放</div>
-          <div class="profile-toggle-hint">机器人所在频道没有其他人时自动暂停，有人加入后可继续播放</div>
+          <div class="profile-toggle-label">无人时自动暂停播放</div>
+          <div class="profile-toggle-hint">服务器上只剩机器人自己时自动暂停，有人连接后自动继续播放（受协议限制，占用判断以整个服务器为准，无法精确到单个频道）</div>
         </div>
         <input
           v-model="autoPauseOnEmpty"
@@ -445,6 +453,85 @@
           @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) -->
+    <section v-if="session.isAdmin.value" class="settings-section">
+      <h2 class="section-title">游客模式</h2>
+      <p class="profile-section-hint">开启后，访客无需登录即可进入并点歌（默认关闭）。游客永远无法查看或修改设置。下面逐项决定游客可用的能力。</p>
+
+      <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="guestMode.enabled" type="checkbox" class="profile-toggle-switch" />
+      </label>
+
+      <div v-if="guestMode.enabled" class="perm-group">
+        <div class="perm-group-title">游客权限</div>
+        <div class="perm-checks">
+          <label v-for="f in GUEST_FLAGS" :key="f.token" class="perm-check">
+            <input type="checkbox" v-model="guestMode.permissions[f.token]" />
+            {{ f.label }}
+          </label>
+        </div>
+      </div>
+
+      <div v-if="guestMode.enabled" class="perm-group">
+        <div class="perm-group-title">可控制的机器人</div>
+        <label class="perm-check">
+          <input type="checkbox" v-model="guestMode.botsAll" />
+          全部机器人
+        </label>
+        <div v-if="!guestMode.botsAll" class="perm-checks perm-bots">
+          <label v-for="bot in store.bots" :key="bot.id" class="perm-check">
+            <input
+              type="checkbox"
+              :checked="guestMode.selectedBotIds.includes(bot.id)"
+              @change="toggleGuestBot(bot.id, ($event.target as HTMLInputElement).checked)"
+            />
+            {{ bot.name }}
+          </label>
+          <span v-if="store.bots.length === 0" class="user-empty">还没有机器人。</span>
+        </div>
+      </div>
+
+      <div class="form-actions">
+        <button class="btn-primary" :disabled="guestSaving" @click="saveGuestMode">
+          {{ guestSaving ? '保存中…' : '保存' }}
+        </button>
+      </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) -->
@@ -685,6 +772,7 @@ const newBotServer = ref('');
 const newBotPort = ref(9987);
 const newBotNickname = ref('MusicBot');
 const newBotChannel = ref('');
+const newBotChannelId = ref('');
 const newBotServerPassword = ref('');
 const newBotAvatar = ref<string | null>(null);
 
@@ -696,6 +784,7 @@ const editForm = reactive({
   serverPort: 9987,
   nickname: '',
   defaultChannel: '',
+  channelId: '',
   channelPassword: '',
   serverPassword: '',
 });
@@ -853,6 +942,7 @@ async function createBot() {
       serverPort: newBotPort.value || 9987,
       nickname: newBotNickname.value || newBotName.value,
       defaultChannel: newBotChannel.value || undefined,
+      channelId: newBotChannelId.value || undefined,
       serverPassword: newBotServerPassword.value || undefined,
       autoStart: false,
     });
@@ -868,6 +958,7 @@ async function createBot() {
     newBotPort.value = 9987;
     newBotNickname.value = 'MusicBot';
     newBotChannel.value = '';
+    newBotChannelId.value = '';
     newBotServerPassword.value = '';
     newBotAvatar.value = null;
     await store.fetchBots();
@@ -901,6 +992,7 @@ async function openEditBot(bot: any) {
     editForm.serverPort = res.data.serverPort ?? 9987;
     editForm.nickname = res.data.nickname ?? '';
     editForm.defaultChannel = res.data.defaultChannel ?? '';
+    editForm.channelId = res.data.channelId ?? '';
     editForm.channelPassword = res.data.channelPassword ?? '';
     editForm.serverPassword = res.data.serverPassword ?? '';
   } catch {
@@ -909,6 +1001,7 @@ async function openEditBot(bot: any) {
     editForm.serverPort = 9987;
     editForm.nickname = bot.name;
     editForm.defaultChannel = '';
+    editForm.channelId = '';
     editForm.channelPassword = '';
     editForm.serverPassword = '';
   }
@@ -955,13 +1048,18 @@ async function savePrefix() {
 
 // Idle timeout
 const idleTimeout = ref(0);
-const autoPauseOnEmpty = ref(true);
+// 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 ?? true;
+    autoPauseOnEmpty.value = res.data.autoPauseOnEmpty ?? false;
+    localAudioEnabled.value = res.data.localAudioEnabled ?? true;
+    applyGuestModeFromServer(res.data.guestMode);
+    applyAdminGroupsFromServer(res.data.adminGroups);
   } catch { /* ignore */ }
 }
 
@@ -977,6 +1075,93 @@ 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: '添加到队列末尾' },
+  { token: 'playNext', label: '添加到下一首' },
+  { token: 'playNow', label: '立即播放（不清空队列）' },
+  { token: 'skip', label: '跳过当前歌曲' },
+  { 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, playCollection: false },
+});
+const guestSaving = ref(false);
+
+function applyGuestModeFromServer(gm: any) {
+  if (!gm) return;
+  guestMode.enabled = Boolean(gm.enabled);
+  guestMode.botsAll = gm.bots === 'all';
+  guestMode.selectedBotIds = Array.isArray(gm.bots) ? [...gm.bots] : [];
+  for (const f of GUEST_FLAGS) {
+    guestMode.permissions[f.token] = Boolean(gm.permissions?.[f.token]);
+  }
+}
+
+function toggleGuestBot(id: string, checked: boolean) {
+  const has = guestMode.selectedBotIds.includes(id);
+  if (checked && !has) guestMode.selectedBotIds.push(id);
+  else if (!checked && has) guestMode.selectedBotIds = guestMode.selectedBotIds.filter((b) => b !== id);
+}
+
+async function saveGuestMode() {
+  guestSaving.value = true;
+  try {
+    const res = await axios.post('/api/bot/settings', {
+      guestMode: {
+        enabled: guestMode.enabled,
+        bots: guestMode.botsAll ? 'all' : [...guestMode.selectedBotIds],
+        permissions: { ...guestMode.permissions },
+      },
+    });
+    applyGuestModeFromServer(res.data?.guestMode);
+  } catch { /* ignore */ } finally {
+    guestSaving.value = false;
+  }
+}
+
+// --- 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;
@@ -1634,6 +1819,10 @@ onUnmounted(() => {
   font-size: 13px;
   outline: none;
   &:focus { border-color: var(--color-primary); }
+  &.disabled {
+    opacity: 0.4;
+    cursor: not-allowed;
+  }
 }
 
 .input-sm { max-width: 80px; }

web/src/views/Setup.vue

@@ -46,8 +46,12 @@
         <input v-model="nickname" placeholder="MusicBot" class="input" />
       </div>
       <div class="form-group">
-        <label>默认频道 (可选)</label>
-        <input v-model="defaultChannel" placeholder="音乐频道" class="input" />
+        <label>默认频道名称（可选）</label>
+        <input v-model="defaultChannel" :disabled="!!channelId" placeholder="音乐频道" class="input" :class="{ disabled: !!channelId }" />
+      </div>
+      <div class="form-group">
+        <label>默认频道ID（可选）</label>
+        <input v-model="channelId" :disabled="!!defaultChannel" placeholder="如 12" class="input" :class="{ disabled: !!defaultChannel }" />
       </div>
       <div class="btn-row">
         <button class="btn-secondary" @click="currentStep = 0">上一步</button>
@@ -87,6 +91,7 @@ const serverAddress = ref('');
 const serverPort = ref(9987);
 const nickname = ref('MusicBot');
 const defaultChannel = ref('');
+const channelId = ref('');
 
 async function createBotAndNext() {
   try {
@@ -96,6 +101,7 @@ async function createBotAndNext() {
       serverPort: serverPort.value,
       nickname: nickname.value,
       defaultChannel: defaultChannel.value,
+      channelId: channelId.value || undefined,
       autoStart: true,
     });
     currentStep.value = 2;
@@ -193,6 +199,10 @@ async function createBotAndNext() {
   &:focus {
     border-color: var(--color-primary);
   }
+  &.disabled {
+    opacity: 0.4;
+    cursor: not-allowed;
+  }
 }
 
 .btn-primary {