docs: add v1.12.0 changelog entry

也补上此前遗漏的 v1.11.2 条目。

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

README.md

@@ -9,7 +9,7 @@
 </p>
 
 <p align="center">
-  <img src="https://img.shields.io/badge/Node.js-20+-339933?logo=nodedotjs&logoColor=white" />
+  <img src="https://img.shields.io/badge/Node.js-20%20%7C%2022%20LTS-339933?logo=nodedotjs&logoColor=white" />
   <img src="https://img.shields.io/badge/TypeScript-5-3178C6?logo=typescript&logoColor=white" />
   <img src="https://img.shields.io/badge/Vue-3-4FC08D?logo=vuedotjs&logoColor=white" />
   <img src="https://img.shields.io/badge/许可证-MIT-green" />
@@ -62,20 +62,25 @@
 
 ### 方式一：Windows 一键部署（最简单）
 
-只需电脑有网络连接，其他一切自动安装。
+先装好 Node.js，其余依赖（含内置 FFmpeg）全部自动安装。
 
 ```
-1. 下载或 clone 本项目
-2. 双击 scripts\setup.bat      （首次安装，自动安装 Node.js 和所有依赖）
-3. 双击 scripts\start.bat      （启动机器人）
-4. 浏览器打开 http://localhost:3000
+1. 安装 Node.js 20 LTS 或 22 LTS（https://nodejs.org/ 或 https://nodejs.cn/）
+2. 下载或 clone 本项目
+3. 双击 scripts\setup.bat      （安装依赖并构建，不含 Node.js 本身）
+4. 双击 scripts\start.bat      （启动机器人）
+5. 浏览器打开 http://localhost:3000
 ```
 
-> `setup.bat` 会自动通过 winget 安装 Node.js（如果未安装），运行 `npm install` 安装所有依赖（包括内置 FFmpeg），最后构建项目。之后每次只需双击 `start.bat` 启动。
+> **先装 Node.js 20 LTS 或 22 LTS**（[nodejs.org](https://nodejs.org/) / 国内镜像 [nodejs.cn](https://nodejs.cn/)）。`setup.bat` 检测到没装 Node 时会给出下载地址并退出，不会替你安装。
+>
+> 之后 `setup.bat` 会运行 `npm install` 安装所有依赖（包括内置 FFmpeg），按当前 Node 版本准备好原生模块，最后构建项目。之后每次只需双击 `start.bat` 启动。
+>
+> 更新的 Node 大版本（如 24）也能用，但通常没有现成的 opus / better-sqlite3 预编译包，安装脚本会改用源码编译，需要 C/C++ 构建工具且耗时更久——所以推荐 20 / 22 LTS。**装好之后不要再换 Node 大版本**：原生模块只能在编译它的那个版本上加载，换版本后必须重新运行 `setup.bat`（脚本会自动检测并重装，见下方常见问题）。
 
 ### 方式二：手动安装（所有系统）
 
-**前置条件：** [Node.js 20+](https://nodejs.org/) 和一个 TeamSpeak 服务器（TS3/TS5/TS6 均可）。
+**前置条件：** [Node.js 20 LTS 或 22 LTS](https://nodejs.org/)（推荐；更新的大版本可用但需要源码编译原生模块）和一个 TeamSpeak 服务器（TS3/TS5/TS6 均可）。
 FFmpeg **已自动内置**，无需手动安装。
 
 ```bash
@@ -348,8 +353,8 @@ sudo systemctl start tsmusicbot
 | `!play -y <关键词>` | 从 YouTube 搜索并播放（需要安装 [yt-dlp](#可选youtube-音源)）|
 | `!search <歌名> [-j\|-n\|-q\|-k\|-b\|-y]` | 列出前若干个匹配结果（含序号与 id），用于挑选同名歌曲；可加平台标志切换音源 |
 | `!play #<序号>` | 播放上一次 `!search` 结果中的第 N 项（区分同名歌曲） |
-| `!play id:<id>` | 按歌曲 id 播放精确的某首歌（也支持直接粘贴网易云 / QQ / B站 歌曲链接；Jellyfin 曲目用 GUID ItemId） |
-| `!add <歌名>` | 添加到播放队列（同样支持 `#序号` / `id:<id>` / 链接） |
+| `!play id <id>` | 按歌曲 id 播放精确的某首歌（也支持直接粘贴网易云 / QQ / B站 歌曲链接；Jellyfin 曲目用 GUID ItemId）。旧写法 `!play id:<id>` 仍然可用 |
+| `!add <歌名>` | 添加到播放队列（同样支持 `#序号` / `id <id>` / 链接） |
 | `!pause` / `!resume` | 暂停 / 恢复播放 |
 | `!next` / `!prev` | 下一首 / 上一首 |
 | `!stop` | 停止播放并清空队列 |
@@ -505,7 +510,7 @@ teamspeak-music-bot/
 
 | 层级 | 技术 |
 |------|------|
-| **运行时** | Node.js 20+, TypeScript 5 |
+| **运行时** | Node.js 20 / 22 LTS, TypeScript 5 |
 | **后端框架** | Express 4, WebSocket (ws) |
 | **数据库** | better-sqlite3 (SQLite) |
 | **音频处理** | FFmpeg (ffmpeg-static 内置), @discordjs/opus |
@@ -564,7 +569,7 @@ teamspeak-music-bot/
 - **电台 / FM**（`!fm -j` 或首页「Jellyfin 电台」卡片）— 随机取一首**收藏**做种子生成 Instant Mix 歌曲流；没有收藏则回退到最近播放、再回退随机曲目
 - **首页区块** — 最近添加（专辑）/ 播放最多 / Jellyfin 收藏 / 我的歌单 / 流派（点流派芯片即播放该流派）
 - **播放上报** — 播放开始 / 进度（约 10s 一次）/ 停止会回报给 Jellyfin（`Sessions/Playing` 系列接口），你的 Jellyfin 播放统计（PlayCount、最近播放）保持准确；上报失败不影响播放
-- **聊天命令** — 启用后用 `-j` 标志：`!play -j <歌名>`、`!fm -j`、`!artist -j <歌手>`；`!playlist` / `!album` / `!play id:` 可直接粘贴 Jellyfin GUID。若把在线音源全部停用、只保留 Jellyfin，不带标志的命令会自动以 Jellyfin 为默认音源
+- **聊天命令** — 启用后用 `-j` 标志：`!play -j <歌名>`、`!fm -j`、`!artist -j <歌手>`；`!playlist` / `!album` / `!play id <id>` 可直接粘贴 Jellyfin GUID。若把在线音源全部停用、只保留 Jellyfin，不带标志的命令会自动以 Jellyfin 为默认音源
 
 ### enabledProviders：音源开关
 
@@ -797,11 +802,14 @@ A：支持。本项目内置 TS3/TS6 双协议支持，连接时会自动检测
 **Q：机器人连接了但 TeamSpeak 中听不到音乐？**
 A：确保机器人和你在同一个频道。检查音量（`!vol 75`）。部分 VIP 歌曲需要先登录账号。
 
+**Q：启动报 `NODE_MODULE_VERSION 137 ... requires 127`，或提示找不到 `opus.node`？**
+A：换过 Node 大版本了。原生模块（`@discordjs/opus`、`better-sqlite3`）编译时绑定了一个 Node ABI（Node 20 = 115、22 = 127、24 = 137），换版本后旧的 `.node` 就再也加载不了。**重新运行一次 `scripts\setup.bat`（Linux/macOS 是 `bash scripts/setup.sh`）即可**——安装脚本会实际加载一遍每个原生模块，发现和当前 Node 不匹配就自动重新下载/编译，替换过程中失败也会把原来的文件还原回去。`start.bat` 和 `npm start` 在启动前也会先做这个检查，直接告诉你哪个模块对不上、分别是哪个 ABI，而不是抛一串看不懂的堆栈。想彻底重来就删掉 `node_modules` 和 `web\node_modules` 再跑一次 `setup.bat`。
+
 **Q：提示"无法获取播放链接"？**
 A：在设置页面扫码登录音乐账号。许多歌曲需要登录后才能播放。
 
 **Q：同名歌曲 `!play` 只能播到最热门的那首，怎么播放指定的版本？**
-A：`!play <歌名>` 默认取最热门的匹配项。要播放同名的另一首，有三种方式：(1) 先 `!search <歌名>` 列出带序号的结果，再 `!play #序号` 选择；(2) `!play id:<歌曲id>` 按 id 精确播放；(3) 直接粘贴歌曲链接，如 `!play https://music.163.com/song?id=442867526`（也支持 QQ / B站 链接）。在 WebUI 中则可直接在搜索结果列表里点选任意同名歌曲。
+A：`!play <歌名>` 默认取最热门的匹配项。要播放同名的另一首，有三种方式：(1) 先 `!search <歌名>` 列出带序号的结果，再 `!play #序号` 选择；(2) `!play id <歌曲id>` 按 id 精确播放（`!search` 结果里每行末尾的 `[id:...]` 就是它）；(3) 直接粘贴歌曲链接，如 `!play https://music.163.com/song?id=442867526`（也支持 QQ / B站 链接）。在 WebUI 中则可直接在搜索结果列表里点选任意同名歌曲。
 
 **Q：如何更换机器人所在频道？**
 A：使用 `!move <频道名>` 命令，或在设置页面创建机器人时指定默认频道。
@@ -876,7 +884,41 @@ A：本项目内置 `/login` 限流（每 IP 每分钟 5 次），但生产部
 
 > 完整历史请查看 [git log](https://github.com/ZHANGTIANYAO1/teamspeak-music-bot/commits/main) 或 [Releases](https://github.com/ZHANGTIANYAO1/teamspeak-music-bot/releases)。这里只列出重要变更和面向用户的破坏性改动。
 
-### 最新版本 — v1.11.1：修复 `!help` 触发机器人自动点歌
+### 最新版本 — v1.12.0：网站图标 / 移动端交互 / 安装脚本按 ABI 自愈
+
+一次性处理了 6 个社区反馈的 issue。**没有配置变化，升级无需任何操作**；`!play id:<id>` 等旧写法全部继续可用。
+
+**安装脚本按 Node ABI 校验并自动修复（[#140](https://github.com/ZHANGTIANYAO1/teamspeak-music-bot/issues/140)，[PR #147](https://github.com/ZHANGTIANYAO1/teamspeak-music-bot/pull/147)，感谢 [@zbn297427669](https://github.com/zbn297427669)）**
+
+- 换过 Node 大版本后启动报 `NODE_MODULE_VERSION 137 ... requires 127`、或提示找不到 `opus.node` 的问题已修复。原生模块只能在编译它的 Node ABI 上加载，而旧脚本只检查「文件存在且够大」，会把给另一个 Node 版本编译的二进制原样留下。
+- 现在安装脚本会在子进程里真的加载一遍每个原生模块，不匹配就按当前 ABI 重新安装；替换过程先备份再原子替换，任何一步失败都会把原文件逐字节还原，不会让环境变得更糟。被中断留下的备份，下次运行自动认领回来。
+- 必需模块失败会**中止安装并返回非零**，不再出现「setup 显示成功、start 才爆炸」；下载进度实时显示在控制台，不再让人以为卡死。
+- `start.bat` 和 `npm start` 启动前会预检，直接说清楚哪个模块对不上、分别是哪个 ABI、怎么修。
+- 顺带修掉一个会**静默丢掉 ffmpeg** 的问题：源码编译会阻塞事件循环，把同时进行的 80MB ffmpeg 下载误判为超时，而 ffmpeg 是可选模块，于是安装照样报告成功、用户却放不出任何声音。三个模块改为串行处理。
+- Node 版本要求按依赖真实下限判断（20.19+ / 22.12+），推荐 20 或 22 LTS；更新的大版本不阻止，只提示可能需要源码编译。
+
+**随机模式下 `!pn` 真正下一首播放（[#141](https://github.com/ZHANGTIANYAO1/teamspeak-music-bot/issues/141)，[PR #144](https://github.com/ZHANGTIANYAO1/teamspeak-music-bot/pull/144)，感谢 [@XuVIIJay](https://github.com/XuVIIJay)）**
+
+- 随机 / 随机循环下 `!pn`（以及 WebUI 的「下一首播放」）插入的歌只是和其他歌一样等着被随机抽中，机器人却回复「Up next」。现在会真的下一首播放，连续插入多首时的顺序与队列里显示的一致。
+- 同时修掉两个相关问题：插入或删除队列中的歌之后，待播位置可能指向另一首歌；删得多了甚至会让播放**静默停止**。
+
+**WebUI 站点图标与移动端交互（[#142](https://github.com/ZHANGTIANYAO1/teamspeak-music-bot/issues/142) / [#143](https://github.com/ZHANGTIANYAO1/teamspeak-music-bot/issues/143) / [#138](https://github.com/ZHANGTIANYAO1/teamspeak-music-bot/issues/138)，[PR #146](https://github.com/ZHANGTIANYAO1/teamspeak-music-bot/pull/146)，感谢 [@XuVIIJay](https://github.com/XuVIIJay) 与 [@hak5ya](https://github.com/hak5ya)）**
+
+- 新增站点图标：收藏网页、移动端添加到主屏幕都会显示图标（含 iOS 与 Android 适配）。
+- 移动端迷你播放器的进度条现在**可以点按和拖动调节进度**，触摸区域也放大到可用尺寸，拖动时不会被自动跳转到歌词页。
+- 移动端**单击歌曲行即可播放**（桌面端双击行为不变）；队列抽屉里的歌曲行同样支持，其移除按钮在触屏下不再是「看不见但点得到」。
+- QQ 扫码登录的提示改为「请使用手机QQ扫码」——那是 QQ 账号二维码，用 QQ音乐 APP 扫不出来。
+
+**`!play id <id>` 与其他命令语法统一（[#139](https://github.com/ZHANGTIANYAO1/teamspeak-music-bot/issues/139)，[PR #145](https://github.com/ZHANGTIANYAO1/teamspeak-music-bot/pull/145)，感谢 [@hak5ya](https://github.com/hak5ya)）**
+
+- 按 id 播放现在可以写成 `!play id <id>`，和其他命令的 `<命令> <子命令> <参数>` 形式一致；`!add` / `!playnext` 同样适用。
+- **旧写法 `!play id:<id>` 继续支持**。空格写法只在参数确实像 id 时生效，普通搜索和粘贴链接的行为不受影响。
+
+### v1.11.2 — 可配置语音闪避
+
+- 检测频道内其他人说话时平滑降低音乐音量，停止后平滑恢复；默认关闭，可在设置页启用并调节说话时保留的音量比例（[#136](https://github.com/ZHANGTIANYAO1/teamspeak-music-bot/issues/136)，[PR #137](https://github.com/ZHANGTIANYAO1/teamspeak-music-bot/pull/137)）。
+
+### v1.11.1：修复 `!help` 触发机器人自动点歌
 
 **丢弃自回显消息（[PR #135](https://github.com/ZHANGTIANYAO1/teamspeak-music-bot/pull/135)，感谢 [@EvolvedGhost](https://github.com/EvolvedGhost)）**
 

package.json

@@ -3,10 +3,15 @@
   "version": "0.1.0",
   "description": "TeamSpeak music bot with NetEase Cloud Music and QQ Music support",
   "type": "module",
+  "engines": {
+    "node": "^20.19.0 || ^22.12.0 || >=24.0.0"
+  },
   "scripts": {
     "dev": "tsx watch src/index.ts",
     "build": "tsc && npm run build:web",
     "build:web": "cd web && npm run build",
+    "check:native": "node scripts/check-native.mjs",
+    "prestart": "node scripts/check-native.mjs",
     "start": "node dist/index.js",
     "play": "node dist/index.js",
     "test": "vitest run",

scripts/check-native.mjs

@@ -0,0 +1,150 @@
+#!/usr/bin/env node
+
+/**
+ * Preflight: can THIS Node build actually load the native modules that are
+ * sitting in node_modules?
+ *
+ * A compiled addon is tied to one Node ABI (process.versions.modules:
+ * Node 20 = 115, Node 22 = 127, Node 24 = 137). Install under one Node major,
+ * launch under another, and the bot dies deep inside startup with a
+ * `NODE_MODULE_VERSION ...` stack that says nothing about how to fix it.
+ * This script turns that into one actionable sentence, before anything starts.
+ *
+ * Exit code:
+ *   0  every required native module loads (or is simply not installed yet —
+ *      that is npm install's problem, not an ABI problem)
+ *   1  a required native module definitively fails to load; the bot could not
+ *      have started anyway, so there is no false-positive risk here.
+ *
+ * Usage: node scripts/check-native.mjs
+ */
+
+import { execFileSync } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const ROOT = join(dirname(fileURLToPath(import.meta.url)), "..");
+const NODE_MODULES = join(ROOT, "node_modules");
+const STAMP_FILE = join(NODE_MODULES, ".tsmusicbot-abi");
+const NODE_ABI = process.versions.modules;
+
+/** Only the modules the bot cannot start without. ffmpeg-static is optional
+ *  (a system ffmpeg on PATH works too), so it is not checked here. */
+const REQUIRED = ["@discordjs/opus", "better-sqlite3"];
+
+function pkgDirOf(spec) {
+  return join(NODE_MODULES, ...spec.split("/"));
+}
+
+function summarizeError(text) {
+  const lines = String(text || "")
+    .split(/\r?\n/)
+    .map((l) => l.trim())
+    .filter(Boolean);
+  const interesting = lines.find((l) => /NODE_MODULE_VERSION|Error:|error:/.test(l));
+  return (interesting || lines[0] || "unknown error").slice(0, 300);
+}
+
+/**
+ * The snippet that actually forces each package's addon to be dlopen()ed.
+ * NOTE: better-sqlite3 loads its .node lazily, inside the Database constructor,
+ * so a bare `require('better-sqlite3')` succeeds even against a wrong-ABI
+ * binary. Opening an in-memory database is the cheapest way to really load it.
+ */
+const PROBE_EXPR = {
+  "@discordjs/opus": "require('@discordjs/opus')",
+  "better-sqlite3": "new (require('better-sqlite3'))(':memory:').close()",
+};
+
+/**
+ * Load-probe in a throwaway child process. Child process on purpose: requiring
+ * an addon in this process would keep the DLL mapped, and Windows then refuses
+ * to let setup.bat replace the file we just told the user to replace.
+ */
+function probeRequire(spec) {
+  const expr = PROBE_EXPR[spec] || `require(${JSON.stringify(spec)})`;
+  try {
+    execFileSync(process.execPath, ["-e", expr], {
+      cwd: ROOT,
+      stdio: "pipe",
+      timeout: 120000,
+      windowsHide: true,
+    });
+    return { ok: true };
+  } catch (err) {
+    const text = [err.stderr && err.stderr.toString(), err.message].filter(Boolean).join("\n");
+    // "...compiled against ... NODE_MODULE_VERSION 137. This version of Node.js
+    //  requires NODE_MODULE_VERSION 127..." -> first number is the build target.
+    const abis = [...text.matchAll(/NODE_MODULE_VERSION (\d+)/g)].map((m) => m[1]);
+    return {
+      ok: false,
+      abiMismatch: abis.length >= 2,
+      compiledAbi: abis.length >= 2 ? abis[0] : null,
+      error: summarizeError(text),
+    };
+  }
+}
+
+function readStamp() {
+  try {
+    return JSON.parse(readFileSync(STAMP_FILE, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+const setupCmd = process.platform === "win32" ? "scripts\\setup.bat" : "bash scripts/setup.sh";
+
+const broken = [];
+for (const spec of REQUIRED) {
+  if (!existsSync(pkgDirOf(spec))) continue; // not installed yet -> npm install's job
+  const probe = probeRequire(spec);
+  if (!probe.ok) broken.push({ spec, ...probe });
+}
+
+function report() {
+  const stamp = readStamp();
+  const mismatch = broken.find((b) => b.abiMismatch);
+  const out = (line) => process.stderr.write(`${line}\n`);
+
+  out("");
+  out("============================================================");
+  if (mismatch) {
+    out("  [ERROR] 原生模块与当前 Node 版本不匹配");
+    out("          Native modules do not match this Node version");
+  } else {
+    out("  [ERROR] 原生模块无法加载 / native module failed to load");
+  }
+  out("============================================================");
+  out(`  本机 Node / running Node : ${process.version}  (ABI ${NODE_ABI})`);
+  if (stamp && stamp.abi) {
+    out(`  安装时 Node / built with : ${stamp.nodeVersion || "?"}  (ABI ${stamp.abi})`);
+    out(`                             ← node_modules/.tsmusicbot-abi, ${stamp.updatedAt || "?"}`);
+  }
+  out("");
+  for (const b of broken) {
+    if (b.abiMismatch) {
+      out(`  x ${b.spec}: 本机 Node ${process.version} (ABI ${NODE_ABI}),`);
+      out(`      但 node_modules 里的原生模块是给 ABI ${b.compiledAbi} 编译的。`);
+      out(`      built for ABI ${b.compiledAbi}, this Node needs ABI ${NODE_ABI}.`);
+    } else {
+      out(`  x ${b.spec}: ${b.error}`);
+    }
+  }
+  out("");
+  out("  怎么修 / How to fix:");
+  out(`    1) 重新运行安装脚本 / re-run setup:  ${setupCmd}`);
+  out("       (它会自动为当前 Node 版本重新安装原生模块)");
+  out("       (setup now repairs the native modules for whatever Node you run)");
+  out("    2) 或者换回安装时用的 Node 版本 / or switch back to the Node version");
+  out("       you installed with, then start again.");
+  out("============================================================");
+  out("");
+}
+
+if (broken.length > 0) {
+  report();
+  // exitCode rather than exit(): lets the message flush when stderr is piped.
+  process.exitCode = 1;
+}

scripts/docker/Dockerfile

@@ -46,6 +46,11 @@ COPY --from=builder /app/dist ./dist
 COPY --from=builder /app/web/dist ./web/dist
 COPY --from=builder /app/package*.json ./
 COPY --from=builder /app/node_modules ./node_modules
+# package.json declares a `prestart` preflight, so `npm start` inside the
+# container needs this file. The image's own CMD calls node directly and never
+# goes through npm, but an interactive `docker exec ... npm start` would
+# otherwise die on a missing script rather than starting the bot.
+COPY --from=builder /app/scripts/check-native.mjs ./scripts/check-native.mjs
 
 # Data directory for database, cookies, logs
 RUN mkdir -p /app/data

scripts/download-binaries.mjs

@@ -1,161 +1,718 @@
 #!/usr/bin/env node
 
 /**
- * Download native binaries (ffmpeg + @discordjs/opus) from npmmirror CDN.
- * Called by setup.bat after npm install --ignore-scripts.
+ * Verify / download / repair the native binaries used by TSMusicBot
+ * (ffmpeg-static + @discordjs/opus + better-sqlite3), preferring the
+ * npmmirror CDN so China users never have to reach GitHub.
+ *
+ * Called by setup.bat / setup.sh after `npm install --ignore-scripts`.
+ *
+ * WHY THIS IS NOT JUST A DOWNLOADER
+ * ---------------------------------
+ * A compiled addon only loads into the exact Node ABI it was built for
+ * (process.versions.modules: Node 20 = 115, Node 22 = 127, Node 24 = 137).
+ * better-sqlite3 stores its addon at an ABI-agnostic path
+ * (build/Release/better_sqlite3.node), so a "file exists and is big enough"
+ * check happily keeps a binary built for a *different* Node major around and
+ * the bot then dies with `NODE_MODULE_VERSION 137 ... requires 127`.
+ * So we validate by actually LOADING each package — in a short-lived child
+ * process, because on Windows a loaded .node stays mapped and the OS then
+ * refuses to delete or overwrite it.
+ *
+ * Every repair is staged and swapped in atomically: if a download fails we put
+ * the previous file back, so a failed run can never leave the install in a
+ * worse state than it started.
  *
  * Usage: node scripts/download-binaries.mjs [cdn_base_url]
+ * Env:   TSMB_BINARY_LOG_STDOUT=1  also echo progress to stdout
+ *        (setup.bat uses this to show progress live on stderr while stdout
+ *         is redirected into setup.log)
  */
 
-import { existsSync, mkdirSync, writeFileSync, statSync } from "node:fs";
+import {
+  chmodSync,
+  createWriteStream,
+  existsSync,
+  mkdirSync,
+  mkdtempSync,
+  readdirSync,
+  readFileSync,
+  renameSync,
+  rmSync,
+  statSync,
+  writeFileSync,
+} from "node:fs";
 import { tmpdir } from "node:os";
-import { join, dirname } from "node:path";
+import { basename, dirname, join } from "node:path";
 import { createGunzip } from "node:zlib";
 import { pipeline } from "node:stream/promises";
-import { createWriteStream } from "node:fs";
 import { get } from "node:https";
 import { Readable } from "node:stream";
-import { execSync } from "node:child_process";
+import { execFileSync, execSync } from "node:child_process";
 import { createRequire } from "node:module";
 import { fileURLToPath } from "node:url";
 
 const ROOT = join(dirname(fileURLToPath(import.meta.url)), "..");
+const NODE_MODULES = join(ROOT, "node_modules");
+const BACKUP_DIR = join(NODE_MODULES, ".tsmusicbot-backup");
+const STAMP_FILE = join(NODE_MODULES, ".tsmusicbot-abi");
+
 const CDN = process.argv[2] || "https://cdn.npmmirror.com/binaries";
 const PLATFORM = process.platform;
 const ARCH = process.arch;
 const NODE_ABI = process.versions.modules;
 
-function download(url) {
+/** Modules the bot cannot start without. ffmpeg-static is optional: a system
+ *  ffmpeg on PATH is a documented fallback, so it only ever produces a WARN. */
+const REQUIRED = new Set(["@discordjs/opus", "better-sqlite3"]);
+
+/** ffmpeg-static ships ~40-90 MB depending on platform; anything under this is
+ *  certainly a truncated download, not a real build. */
+const FFMPEG_MIN_BYTES = 20 * 1024 * 1024;
+
+// ---------------------------------------------------------------------------
+// logging
+// ---------------------------------------------------------------------------
+
+// Progress goes to stderr so setup.bat can show it live while stdout is being
+// appended to setup.log. TSMB_BINARY_LOG_STDOUT=1 mirrors it into stdout so the
+// log keeps the full transcript too.
+const ECHO_STDOUT = process.env.TSMB_BINARY_LOG_STDOUT === "1";
+
+function log(msg) {
+  const line = msg === "" ? "" : `  [binary] ${msg}`;
+  process.stderr.write(`${line}\n`);
+  if (ECHO_STDOUT) process.stdout.write(`${line}\n`);
+}
+
+// ---------------------------------------------------------------------------
+// small helpers
+// ---------------------------------------------------------------------------
+
+function sizeOf(filePath) {
+  try {
+    return statSync(filePath).size;
+  } catch {
+    return 0;
+  }
+}
+
+function humanSize(filePath) {
+  const bytes = sizeOf(filePath);
+  if (!bytes) return "unknown size";
+  return bytes >= 1024 * 1024
+    ? `${(bytes / 1024 / 1024).toFixed(1)} MB`
+    : `${(bytes / 1024).toFixed(0)} KB`;
+}
+
+function ensureExecutable(filePath) {
+  if (PLATFORM === "win32") return;
+  try {
+    chmodSync(filePath, 0o755);
+  } catch {
+    /* best effort */
+  }
+}
+
+/** Read the version actually present in node_modules (never hardcode it: the
+ *  lockfile can be far ahead of whatever version this script was written for,
+ *  and a wrong version means a 404 on the CDN). */
+function readInstalledVersion(spec) {
+  try {
+    const pkgJson = join(NODE_MODULES, ...spec.split("/"), "package.json");
+    const version = JSON.parse(readFileSync(pkgJson, "utf8")).version;
+    return typeof version === "string" && version ? version : null;
+  } catch {
+    return null;
+  }
+}
+
+function summarizeError(text) {
+  const lines = String(text || "")
+    .split(/\r?\n/)
+    .map((l) => l.trim())
+    .filter(Boolean);
+  const interesting = lines.find((l) => /NODE_MODULE_VERSION|Error:|error:/.test(l));
+  return (interesting || lines[0] || "unknown error").slice(0, 300);
+}
+
+// ---------------------------------------------------------------------------
+// download
+// ---------------------------------------------------------------------------
+
+function download(url, redirects = 0) {
   return new Promise((resolve, reject) => {
     const req = get(url, { timeout: 120000 }, (res) => {
-      if (res.statusCode < 200 || res.statusCode >= 400) {
-        reject(new Error(`HTTP ${res.statusCode}: ${url}`));
+      const { statusCode, headers } = res;
+      if (statusCode >= 300 && statusCode < 400 && headers.location) {
+        res.resume();
+        if (redirects >= 5) {
+          reject(new Error(`too many redirects: ${url}`));
+          return;
+        }
+        resolve(download(new URL(headers.location, url).toString(), redirects + 1));
+        return;
+      }
+      if (statusCode < 200 || statusCode >= 300) {
+        res.resume();
+        reject(new Error(`HTTP ${statusCode}: ${url}`));
         return;
       }
       const chunks = [];
       res.on("data", (c) => chunks.push(c));
+      res.on("error", reject);
       res.on("end", () => resolve(Buffer.concat(chunks)));
     });
     req.on("error", reject);
-    req.on("timeout", () => { req.destroy(); reject(new Error("timeout")); });
+    req.on("timeout", () => {
+      req.destroy();
+      reject(new Error(`timeout: ${url}`));
+    });
   });
 }
 
-function log(msg) {
-  console.log(`  [binary] ${msg}`);
+let tarModule = null;
+
+/** `tar` is not a declared dependency — it only resolves transitively through
+ *  prebuild-install / @discordjs/node-pre-gyp. Fail with a sentence a user can
+ *  act on instead of a raw MODULE_NOT_FOUND stack. */
+function loadTar() {
+  if (tarModule) return tarModule;
+  try {
+    tarModule = createRequire(import.meta.url)("tar");
+  } catch {
+    throw new Error(
+      "'tar' module not available / 找不到 tar 模块 — run `npm install tar` in the project root and retry",
+    );
+  }
+  return tarModule;
 }
 
-function isValidSize(filePath, minBytes) {
-  try { return statSync(filePath).size >= minBytes; } catch { return false; }
+async function extractTarGz(buf, cwd) {
+  const tar = loadTar();
+  const tmpFile = join(tmpdir(), `tsmb-${process.pid}-${Date.now()}.tar.gz`);
+  writeFileSync(tmpFile, buf);
+  try {
+    await tar.extract({ cwd, file: tmpFile });
+  } finally {
+    try {
+      rmSync(tmpFile, { force: true });
+    } catch {
+      /* ignore */
+    }
+  }
 }
 
-async function downloadFfmpeg() {
-  const ffDir = join(ROOT, "node_modules", "ffmpeg-static");
+// ---------------------------------------------------------------------------
+// load probe (the whole point of this rewrite)
+// ---------------------------------------------------------------------------
+
+/**
+ * The snippet that actually forces each package's addon to be dlopen()ed.
+ * NOTE: better-sqlite3 loads its .node lazily, inside the Database constructor
+ * (lib/database.js: `DEFAULT_ADDON || (DEFAULT_ADDON = require('bindings')(...))`),
+ * so a bare `require('better-sqlite3')` succeeds even against a wrong-ABI binary.
+ * Opening an in-memory database is the cheapest way to really load it.
+ */
+const PROBE_EXPR = {
+  "@discordjs/opus": "require('@discordjs/opus')",
+  "better-sqlite3": "new (require('better-sqlite3'))(':memory:').close()",
+};
+
+/**
+ * Try to load a package in a throwaway child process.
+ * Child process on purpose: loading an addon here would keep the DLL mapped and
+ * Windows would then refuse to rename/delete the file we are about to replace.
+ */
+function probeRequire(spec) {
+  const expr = PROBE_EXPR[spec] || `require(${JSON.stringify(spec)})`;
+  try {
+    execFileSync(process.execPath, ["-e", expr], {
+      cwd: ROOT,
+      stdio: "pipe",
+      timeout: 120000,
+      windowsHide: true,
+    });
+    return { ok: true };
+  } catch (err) {
+    const text = [err.stderr && err.stderr.toString(), err.message].filter(Boolean).join("\n");
+    // "...compiled against ... NODE_MODULE_VERSION 137. This version of Node.js
+    //  requires NODE_MODULE_VERSION 127..."  -> first number is what it was built for.
+    const abis = [...text.matchAll(/NODE_MODULE_VERSION (\d+)/g)].map((m) => m[1]);
+    return {
+      ok: false,
+      abiMismatch: abis.length >= 2,
+      compiledAbi: abis.length >= 2 ? abis[0] : null,
+      error: summarizeError(text),
+    };
+  }
+}
+
+function describeProbe(probe) {
+  if (probe.abiMismatch) {
+    return `built for Node ABI ${probe.compiledAbi}, but this Node needs ABI ${NODE_ABI}`;
+  }
+  return probe.error;
+}
+
+function probeFfmpegBinary(bin) {
+  try {
+    const out = execFileSync(bin, ["-version"], {
+      stdio: "pipe",
+      timeout: 30000,
+      windowsHide: true,
+    }).toString();
+    return { ok: true, version: (out.split(/\r?\n/)[0] || "").slice(0, 60) };
+  } catch (err) {
+    const text = [err.stderr && err.stderr.toString(), err.message].filter(Boolean).join("\n");
+    return { ok: false, error: summarizeError(text) };
+  }
+}
+
+// ---------------------------------------------------------------------------
+// atomic swap helpers
+// ---------------------------------------------------------------------------
+
+let stashCounter = 0;
+
+/**
+ * Move `target` (file or directory) out of the way into node_modules/.tsmusicbot-backup.
+ * Same volume as node_modules, so the rename is atomic, and outside the package's
+ * build/ tree so that `npm rebuild` / `node-gyp clean` cannot wipe the backup.
+ * Returns { commit, restore } — call exactly one of them.
+ */
+/** Windows likes to hold a brief lock on a freshly written .node (antivirus,
+ *  indexer), and rmSync does not retry by default. */
+const RM_OPTS = { recursive: true, force: true, maxRetries: 5, retryDelay: 150 };
+
+function stash(target) {
+  if (!existsSync(target)) {
+    return { commit() {}, restore() {} };
+  }
+  mkdirSync(BACKUP_DIR, { recursive: true });
+  const backup = join(BACKUP_DIR, `${basename(target)}.${process.pid}.${stashCounter++}.bak`);
+  rmSync(backup, RM_OPTS);
+  renameSync(target, backup);
+  // The backup filename alone cannot say where the artifact came from, and a
+  // run that is killed (Ctrl+C during a slow download) never reaches commit or
+  // restore. Record the target so the next run can put it back — see
+  // recoverOrphanedBackups().
+  const manifest = `${backup}.json`;
+  try {
+    writeFileSync(manifest, `${JSON.stringify({ target })}\n`);
+  } catch {
+    /* recovery is best-effort; the swap itself still works */
+  }
+
+  let settled = false;
+  const dropManifest = () => {
+    try {
+      rmSync(manifest, RM_OPTS);
+    } catch {
+      /* ignore */
+    }
+  };
+  return {
+    commit() {
+      if (settled) return;
+      settled = true;
+      try {
+        rmSync(backup, RM_OPTS);
+      } catch {
+        /* leftover backup is harmless */
+      }
+      dropManifest();
+    },
+    restore() {
+      if (settled) return;
+      settled = true;
+      try {
+        rmSync(target, RM_OPTS);
+        mkdirSync(dirname(target), { recursive: true });
+        renameSync(backup, target);
+        dropManifest();
+        log(`restored the previous ${basename(target)} — nothing was made worse`);
+      } catch (err) {
+        // Leave the backup AND its manifest in place: recoverOrphanedBackups()
+        // on the next run is the second chance.
+        log(`WARN: could not restore ${target} from ${backup}: ${err.message}`);
+        log(`WARN: the previous file is still at ${backup} — the next run will try again`);
+      }
+    },
+  };
+}
+
+/**
+ * Put back anything a previous run stashed but never restored — a run killed
+ * mid-download, or one whose restore() itself failed. Only acts when the target
+ * is currently absent, so it can never clobber a good binary.
+ */
+function recoverOrphanedBackups() {
+  if (!existsSync(BACKUP_DIR)) return;
+  let entries;
+  try {
+    entries = readdirSync(BACKUP_DIR);
+  } catch {
+    return;
+  }
+  for (const entry of entries) {
+    if (!entry.endsWith(".json")) continue;
+    const manifest = join(BACKUP_DIR, entry);
+    const backup = manifest.slice(0, -".json".length);
+    try {
+      const { target } = JSON.parse(readFileSync(manifest, "utf8"));
+      if (!target || !existsSync(backup)) {
+        rmSync(manifest, RM_OPTS);
+        continue;
+      }
+      if (existsSync(target)) continue; // a good file is already there — leave it alone
+      mkdirSync(dirname(target), { recursive: true });
+      renameSync(backup, target);
+      rmSync(manifest, RM_OPTS);
+      log(`recovered ${basename(target)} left behind by an interrupted run`);
+    } catch (err) {
+      log(`WARN: could not process leftover backup ${entry}: ${err.message}`);
+    }
+  }
+}
+
+function cleanupBackupDir() {
+  try {
+    if (existsSync(BACKUP_DIR) && readdirSync(BACKUP_DIR).length === 0) {
+      rmSync(BACKUP_DIR, { recursive: true, force: true });
+    }
+  } catch {
+    /* ignore */
+  }
+}
+
+// ---------------------------------------------------------------------------
+// per-module results
+// ---------------------------------------------------------------------------
+
+/** status: "ok" | "repaired" | "failed" | "missing" */
+function makeResult(name, status, detail) {
+  return { name, required: REQUIRED.has(name), status, detail };
+}
+
+function buildFromSource(command) {
+  // stdout -> inherited (setup.bat sends it to the log), stderr -> inherited so
+  // compiler progress stays visible; npm's own output is far too noisy to buffer.
+  execSync(command, { cwd: ROOT, stdio: ["ignore", "inherit", "inherit"] });
+}
+
+function buildToolsHint() {
+  log("Install build tools first:");
+  log("  Windows: npm install --global windows-build-tools  (或安装 Visual Studio Build Tools + Python)");
+  log("  Ubuntu/Debian: sudo apt install build-essential python3");
+  log("  CentOS/RHEL:   sudo yum groupinstall 'Development Tools'");
+}
+
+// ---------------------------------------------------------------------------
+// ffmpeg-static (OPTIONAL — a system ffmpeg is a documented fallback)
+// ---------------------------------------------------------------------------
+
+async function ensureFfmpeg() {
+  const name = "ffmpeg-static";
+  const ffDir = join(NODE_MODULES, name);
   const ffName = PLATFORM === "win32" ? "ffmpeg.exe" : "ffmpeg";
   const ffDest = join(ffDir, ffName);
 
-  if (!existsSync(ffDir)) { log("ffmpeg-static not installed, skipping"); return false; }
-  if (existsSync(ffDest)) {
-    if (isValidSize(ffDest, 50 * 1024 * 1024)) {
-      log("ffmpeg already exists, skipping");
-      return true;
+  if (!existsSync(ffDir)) {
+    log(`${name}: package not installed, skipping (a system ffmpeg on PATH also works)`);
+    return makeResult(name, "missing", "package not installed");
+  }
+
+  if (existsSync(ffDest) && sizeOf(ffDest) >= FFMPEG_MIN_BYTES) {
+    ensureExecutable(ffDest);
+    const probe = probeFfmpegBinary(ffDest);
+    if (probe.ok) {
+      log(`${name}: OK (${humanSize(ffDest)}, ${probe.version})`);
+      return makeResult(name, "ok", humanSize(ffDest));
     }
-    log("ffmpeg exists but seems corrupted (too small), re-downloading...");
+    // Deliberately NOT re-downloading here: ffmpeg is a plain executable with no
+    // ABI to mismatch, and forcing an ~80 MB re-download because `-version`
+    // could not be spawned would hurt exactly the slow-network users this
+    // script exists for.
+    log(`${name}: present (${humanSize(ffDest)}) but could not be executed: ${probe.error}`);
+    return makeResult(name, "ok", "present, not verified");
+  }
+
+  if (existsSync(ffDest)) {
+    log(`${name}: existing ffmpeg looks truncated (${humanSize(ffDest)}), re-downloading...`);
+  } else {
+    log(`${name}: ffmpeg binary missing, downloading...`);
   }
 
   const url = `${CDN}/ffmpeg-static/b6.1.1/ffmpeg-${PLATFORM}-${ARCH}.gz`;
-  log("Downloading ffmpeg...");
-  const buf = await download(url);
-  await pipeline(Readable.from(buf), createGunzip(), createWriteStream(ffDest));
-  try { execSync(`chmod +x "${ffDest}"`); } catch {}
-  const size = ((await statSync(ffDest)).size / 1024 / 1024).toFixed(1);
-  log(`ffmpeg OK (${size} MB)`);
-  return true;
-}
-
-async function downloadOpus() {
-  const opusDir = join(ROOT, "node_modules", "@discordjs", "opus");
-  const prebuildName = `node-v${NODE_ABI}-napi-v3-${PLATFORM}-${ARCH}-unknown-unknown`;
-  const opusDest = join(opusDir, "prebuild", prebuildName, "opus.node");
-
-  if (!existsSync(opusDir)) { log("@discordjs/opus not installed, skipping"); return false; }
-  if (existsSync(opusDest)) {
-    if (isValidSize(opusDest, 100 * 1024)) {
-      log("@discordjs/opus already exists, skipping");
-      return true;
-    }
-    log("@discordjs/opus exists but seems corrupted (too small), re-downloading...");
-  }
-
-  const url = `${CDN}/@discordjs/opus/v0.10.0/opus-v0.10.0-node-v${NODE_ABI}-napi-v3-${PLATFORM}-${ARCH}-unknown-unknown.tar.gz`;
-  log("Downloading @discordjs/opus...");
+  const backup = stash(ffDest);
+  const tmpDest = `${ffDest}.tsmb-tmp-${process.pid}`;
   try {
+    log(`${name}: GET ${url}  (~80 MB, 这一步比较慢,请耐心等待)`);
     const buf = await download(url);
-    mkdirSync(dirname(opusDest), { recursive: true });
-    const require = createRequire(import.meta.url);
-    const tar = require("tar");
-    const tmpFile = join(tmpdir(), `discordjs-opus-${Date.now()}.tar.gz`);
-    writeFileSync(tmpFile, buf);
-    await tar.extract({ cwd: join(opusDir, "prebuild"), file: tmpFile });
-    log("@discordjs/opus OK");
-    return true;
+    await pipeline(Readable.from(buf), createGunzip(), createWriteStream(tmpDest));
+    ensureExecutable(tmpDest);
+    if (sizeOf(tmpDest) < FFMPEG_MIN_BYTES) {
+      throw new Error(`downloaded ffmpeg is only ${humanSize(tmpDest)} — truncated`);
+    }
+    renameSync(tmpDest, ffDest); // atomic swap, same directory
+    backup.commit();
+    log(`${name}: OK (${humanSize(ffDest)})`);
+    return makeResult(name, "repaired", humanSize(ffDest));
   } catch (err) {
-    log(`CDN download failed (${err.message}), trying to build from source...`);
     try {
-      execSync("npm rebuild @discordjs/opus", { cwd: ROOT, stdio: "inherit" });
-      if (existsSync(opusDest) && isValidSize(opusDest, 100 * 1024)) {
-        log("@discordjs/opus built from source OK");
-        return true;
+      rmSync(tmpDest, { force: true });
+    } catch {
+      /* ignore */
+    }
+    backup.restore();
+    log(`${name}: download failed — ${err.message}`);
+    log(`${name}: not fatal — install ffmpeg system-wide and put it on PATH instead`);
+    return makeResult(name, "failed", err.message);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// @discordjs/opus (REQUIRED)
+// ---------------------------------------------------------------------------
+
+async function ensureOpus() {
+  const name = "@discordjs/opus";
+  const pkgDir = join(NODE_MODULES, "@discordjs", "opus");
+  const prebuildRoot = join(pkgDir, "prebuild");
+  // node-pre-gyp resolves this directory from the *running* Node's ABI, so a
+  // stale build for another ABI simply sits at another path and is ignored.
+  const prebuildDirName = `node-v${NODE_ABI}-napi-v3-${PLATFORM}-${ARCH}-unknown-unknown`;
+  const destDir = join(prebuildRoot, prebuildDirName);
+
+  if (!existsSync(pkgDir)) {
+    log(`${name}: package not installed — run 'npm install' first`);
+    return makeResult(name, "missing", "package not installed");
+  }
+
+  const before = probeRequire(name);
+  if (before.ok) {
+    log(`${name}: OK (loads under ${process.version}, ABI ${NODE_ABI})`);
+    return makeResult(name, "ok", `ABI ${NODE_ABI}`);
+  }
+  log(`${name}: unusable — ${describeProbe(before)}`);
+  log(`${name}: installing a build for ABI ${NODE_ABI}...`);
+
+  const version = readInstalledVersion(name) || "0.10.0";
+  const url =
+    `${CDN}/@discordjs/opus/v${version}/opus-v${version}` +
+    `-node-v${NODE_ABI}-napi-v3-${PLATFORM}-${ARCH}-unknown-unknown.tar.gz`;
+
+  const backup = stash(destDir);
+  let staging = null;
+  try {
+    try {
+      log(`${name}: GET ${url}`);
+      const buf = await download(url);
+      staging = mkdtempSync(join(pkgDir, ".tsmb-staging-"));
+      await extractTarGz(buf, staging);
+      const staged = join(staging, prebuildDirName);
+      if (!existsSync(join(staged, "opus.node"))) {
+        throw new Error(`tarball did not contain ${prebuildDirName}/opus.node`);
+      }
+      mkdirSync(prebuildRoot, { recursive: true });
+      rmSync(destDir, { recursive: true, force: true });
+      renameSync(staged, destDir); // atomic swap, same volume
+      log(`${name}: prebuilt binary installed`);
+    } catch (cdnErr) {
+      log(`${name}: CDN install failed (${cdnErr.message})`);
+      log(`${name}: falling back to a source build — 'npm rebuild ${name}' (可能需要几分钟)`);
+      buildFromSource(`npm rebuild ${name}`);
+    }
+
+    const after = probeRequire(name);
+    if (!after.ok) throw new Error(describeProbe(after));
+    backup.commit();
+    log(`${name}: repaired, now loads under ${process.version} (ABI ${NODE_ABI})`);
+    return makeResult(name, "repaired", `ABI ${NODE_ABI}`);
+  } catch (err) {
+    backup.restore();
+    log(`${name}: FAILED — ${err.message}`);
+    buildToolsHint();
+    return makeResult(name, "failed", err.message);
+  } finally {
+    if (staging) {
+      try {
+        rmSync(staging, { recursive: true, force: true });
+      } catch {
+        /* ignore */
       }
-      log("Source build completed but .node file not found");
-      return false;
-    } catch (buildErr) {
-      log(`Source build failed: ${buildErr.message}`);
-      log("Install build tools: sudo apt install build-essential (Ubuntu/Debian)");
-      log("                    sudo yum groupinstall 'Development Tools' (CentOS/RHEL)");
-      return false;
     }
   }
 }
 
-async function downloadBetterSqlite3() {
-  const pkgDir = join(ROOT, "node_modules", "better-sqlite3");
+// ---------------------------------------------------------------------------
+// better-sqlite3 (REQUIRED) — the module the ABI bug actually bites
+// ---------------------------------------------------------------------------
+
+async function ensureBetterSqlite3() {
+  const name = "better-sqlite3";
+  const pkgDir = join(NODE_MODULES, name);
   const dest = join(pkgDir, "build", "Release", "better_sqlite3.node");
 
-  if (!existsSync(pkgDir)) { log("better-sqlite3 not installed, skipping"); return false; }
-  if (existsSync(dest)) {
-    if (isValidSize(dest, 500 * 1024)) {
-      log("better-sqlite3 already exists, skipping");
-      return true;
-    }
-    log("better-sqlite3 exists but seems corrupted (too small), re-downloading...");
+  if (!existsSync(pkgDir)) {
+    log(`${name}: package not installed — run 'npm install' first`);
+    return makeResult(name, "missing", "package not installed");
   }
 
-  const version = "12.8.0";
-  const url = `${CDN}/better-sqlite3/v${version}/better-sqlite3-v${version}-node-v${NODE_ABI}-${PLATFORM}-${ARCH}.tar.gz`;
-  log("Downloading better-sqlite3...");
-  const buf = await download(url);
-  const require = createRequire(import.meta.url);
-  const tar = require("tar");
-  const tmpFile = join(tmpdir(), `better-sqlite3-${Date.now()}.tar.gz`);
-  writeFileSync(tmpFile, buf);
-  mkdirSync(dirname(dest), { recursive: true });
-  await tar.extract({ cwd: pkgDir, file: tmpFile });
-  if (existsSync(dest)) {
-    log(`better-sqlite3 OK (${((await statSync(dest)).size / 1024).toFixed(0)} KB)`);
-    return true;
+  const before = probeRequire(name);
+  if (before.ok) {
+    log(`${name}: OK (loads under ${process.version}, ABI ${NODE_ABI})`);
+    return makeResult(name, "ok", `ABI ${NODE_ABI}`);
+  }
+  // This is the case the old size check could not see: the file is there, it is
+  // ~1.9 MB, and it is completely useless because it targets another ABI.
+  log(`${name}: unusable — ${describeProbe(before)}`);
+  log(`${name}: replacing the native binary with a build for ABI ${NODE_ABI}...`);
+
+  const version = readInstalledVersion(name) || "12.11.1";
+  const url = `${CDN}/${name}/v${version}/${name}-v${version}-node-v${NODE_ABI}-${PLATFORM}-${ARCH}.tar.gz`;
+
+  const backup = stash(dest);
+  let staging = null;
+  try {
+    try {
+      log(`${name}: GET ${url}`);
+      const buf = await download(url);
+      staging = mkdtempSync(join(pkgDir, ".tsmb-staging-"));
+      await extractTarGz(buf, staging);
+      const staged = join(staging, "build", "Release", "better_sqlite3.node");
+      if (!existsSync(staged)) {
+        throw new Error("tarball did not contain build/Release/better_sqlite3.node");
+      }
+      mkdirSync(dirname(dest), { recursive: true });
+      rmSync(dest, { force: true });
+      renameSync(staged, dest); // atomic swap, same volume
+      log(`${name}: prebuilt binary installed (${humanSize(dest)})`);
+    } catch (cdnErr) {
+      log(`${name}: CDN install failed (${cdnErr.message})`);
+      log(`${name}: falling back to a source build — 'npm rebuild ${name} --build-from-source' (可能需要几分钟)`);
+      buildFromSource(`npm rebuild ${name} --build-from-source`);
+    }
+
+    const after = probeRequire(name);
+    if (!after.ok) throw new Error(describeProbe(after));
+    backup.commit();
+    log(`${name}: repaired, now loads under ${process.version} (ABI ${NODE_ABI}, ${humanSize(dest)})`);
+    return makeResult(name, "repaired", `ABI ${NODE_ABI}`);
+  } catch (err) {
+    backup.restore();
+    log(`${name}: FAILED — ${err.message}`);
+    buildToolsHint();
+    return makeResult(name, "failed", err.message);
+  } finally {
+    if (staging) {
+      try {
+        rmSync(staging, { recursive: true, force: true });
+      } catch {
+        /* ignore */
+      }
+    }
   }
-  log("better-sqlite3 extracted but .node file not found at expected path");
-  return false;
 }
 
+// ---------------------------------------------------------------------------
+// stamp
+// ---------------------------------------------------------------------------
+
+/** Record which ABI this install was built for. Lives inside node_modules so it
+ *  dies together with the thing it describes. check-native.mjs reads it. */
+function writeStamp(results) {
+  if (!existsSync(NODE_MODULES)) return;
+  const stamp = {
+    abi: NODE_ABI,
+    nodeVersion: process.version,
+    platform: PLATFORM,
+    arch: ARCH,
+    updatedAt: new Date().toISOString(),
+    modules: Object.fromEntries(results.map((r) => [r.name, r.status])),
+  };
+  try {
+    writeFileSync(STAMP_FILE, `${JSON.stringify(stamp, null, 2)}\n`);
+    log(`ABI stamp written: node_modules/.tsmusicbot-abi (Node ${process.version}, ABI ${NODE_ABI})`);
+  } catch (err) {
+    log(`WARN: could not write ABI stamp: ${err.message}`);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// main
+// ---------------------------------------------------------------------------
+
+const STEPS = [
+  ["ffmpeg-static", ensureFfmpeg],
+  ["@discordjs/opus", ensureOpus],
+  ["better-sqlite3", ensureBetterSqlite3],
+];
+
 try {
-  const results = await Promise.all([downloadFfmpeg(), downloadOpus(), downloadBetterSqlite3()]);
-  if (results.some(Boolean)) {
-    console.log("  [binary] All downloads complete");
+  log(`Node ${process.version} (ABI ${NODE_ABI}), ${PLATFORM}-${ARCH}, CDN ${CDN}`);
+
+  recoverOrphanedBackups();
+
+  // STRICTLY SEQUENTIAL, and it has to stay that way. The source-build fallback
+  // shells out through execSync, which parks the event loop for minutes; the
+  // 120s timeout that download() arms is a socket-INACTIVITY timer sitting on
+  // that same loop. Run these concurrently and the first module to fall back to
+  // a source build kills every download still in flight — the connection is
+  // healthy, the timer just never got a chance to be reset. That is not a rare
+  // race: npmmirror has no opus prebuild for ABI 137 (Node 24) and no
+  // better-sqlite3 prebuild for ABI 115 (Node 20), so on both of the Node
+  // versions this project supports, one module 404s within ~100ms and starts
+  // building while ffmpeg's ~80MB download is still going. ffmpeg is optional,
+  // so the spurious failure used to be swallowed as a WARN and setup still
+  // reported success — leaving the user with no ffmpeg and no working playback.
+  // Nothing here benefits from overlap anyway: every probe is execFileSync.
+  const results = [];
+  for (const [name, run] of STEPS) {
+    try {
+      results.push(await run());
+    } catch (err) {
+      results.push(makeResult(name, "failed", err?.message ?? String(err)));
+    }
+  }
+
+  cleanupBackupDir();
+
+  log("");
+  log(`Summary — Node ${process.version} / ABI ${NODE_ABI} / ${PLATFORM}-${ARCH}:`);
+  for (const r of results) {
+    const tag =
+      r.status === "ok"
+        ? "OK"
+        : r.status === "repaired"
+          ? "REPAIRED"
+          : r.required
+            ? "FAILED"
+            : "WARN (optional)";
+    log(`  - ${r.name.padEnd(17)} ${tag}${r.detail ? `  ${r.detail}` : ""}`);
+  }
+
+  const broken = results.filter(
+    (r) => r.required && r.status !== "ok" && r.status !== "repaired",
+  );
+  // Only stamp a build that actually succeeded. The stamp says "node_modules is
+  // built for ABI X"; writing it after a failed repair would have check-native
+  // print a reassuring "built with ABI 137" right above its own "this module is
+  // built for ABI 127" complaint.
+  if (broken.length === 0) writeStamp(results);
+  // process.exitCode rather than process.exit(): setup.bat redirects stdout to
+  // setup.log, and process.exit() can drop output that has not flushed yet.
+  if (broken.length > 0) {
+    log("");
+    log(`ERROR: required native module(s) unusable: ${broken.map((r) => r.name).join(", ")}`);
+    log("必需的原生模块不可用,机器人无法启动 —— 请查看上面的错误信息。");
+    process.exitCode = 1;
+  } else {
+    log("All required native modules are ready.");
+    process.exitCode = 0;
   }
 } catch (e) {
-  console.error(`  [binary] ERROR: ${e.message}`);
-  process.exit(1);
+  log(`ERROR: ${e.stack || e.message}`);
+  process.exitCode = 1;
 }
-

scripts/setup.bat

@@ -10,8 +10,11 @@ title TSMusicBot Setup
 ::  - 自动修复 PowerShell 环境变量
 :: ============================================================
 
-set "SCRIPT_VERSION=2.1"
+set "SCRIPT_VERSION=2.2"
 set "MIN_NODE_MAJOR=20"
+:: Newest Node major this project is regularly tested against. Anything above
+:: still works, it just may have no prebuilt addons and fall back to a source build.
+set "TESTED_NODE_MAJOR=22"
 set "LOG_FILE=%~dp0..\setup.log"
 set "FAILED=0"
 
@@ -64,13 +67,38 @@ for /f "tokens=1 delims=v." %%a in ("%NODE_VER%") do set "NODE_MAJOR=%%a"
 call :log "Node.js version: %NODE_VER%"
 echo [OK] Node.js found: %NODE_VER%
 
-if %NODE_MAJOR% LSS %MIN_NODE_MAJOR% (
-    call :error "Node.js version too old. Need %MIN_NODE_MAJOR%+, found %NODE_VER%."
+:: The supported floor is not just a major version, so let node decide:
+:: @honeybbq/teamspeak-client needs >=20.19, @sansenjian/qq-music-api needs
+:: >=20.17 / >=22.9, and the odd majors (21 / 23) are excluded by
+:: better-sqlite3 and vitest. Keep this in sync with "engines" in package.json.
+node -e "const v=process.versions.node.split('.').map(Number); process.exit((v[0]===20&&v[1]>=19)||(v[0]===22&&v[1]>=12)||v[0]>=24?0:1)"
+if errorlevel 1 (
+    call :error "Node.js %NODE_VER% is not supported. Use Node 20.19+ LTS or Node 22.12+ LTS."
+    echo         Download: https://nodejs.org/  or  https://nodejs.cn/
     pause
     exit /b 1
 )
+
+:: Not fatal: setup now rebuilds the native modules for whatever ABI you run,
+:: so newer Node majors work - they are just slower to install.
+:: NOTE: keep every line inside these parenthesised blocks pure ASCII.
+:: cmd.exe mis-tracks its file offset when a block contains multi-byte UTF-8
+:: characters and starts eating the "echo " prefix of following lines.
+:: Bilingual guidance lives in the Node scripts, which print UTF-8 reliably.
+if %NODE_MAJOR% GTR %TESTED_NODE_MAJOR% (
+    echo [WARN] Node %NODE_VER% is newer than the tested LTS line, Node 20 / Node 22.
+    echo        Newer Node majors may have no prebuilt opus / better-sqlite3,
+    echo        so setup falls back to a source build - slower, needs C++ build tools.
+    echo        Recommended: Node 20 LTS or Node 22 LTS - https://nodejs.org/ or https://nodejs.cn/
+    echo        This is only a warning; setup still builds the binaries for %NODE_VER%.
+    call :log "[WARN] Node major %NODE_MAJOR% is newer than tested LTS %TESTED_NODE_MAJOR%"
+)
 echo.
 
+:: Native addons are tied to one Node ABI. If node_modules was built by a
+:: different Node major, step 4b below detects it and repairs it.
+call :log "Node ABI for this install: see node_modules\.tsmusicbot-abi after step 4b"
+
 :: ============================================================
 :: Step 2: Check npm
 :: ============================================================
@@ -143,16 +171,40 @@ echo [OK] Backend dependencies installed.
 echo.
 
 :: ============================================================
-:: Step 4b: Download native binaries from CDN
+:: Step 4b: Verify / download / repair native binaries (ABI aware)
 :: ============================================================
-call :step "4b/7" "Downloading native binaries"
+call :step "4b/7" "Checking native binaries"
 
-node scripts/download-binaries.mjs %CDN_MIRROR% >>"%LOG_FILE%" 2>&1
-if errorlevel 1 (
-    echo [WARN] Binary download had issues. Check %LOG_FILE% for details.
-) else (
-    echo [OK] Native binaries installed.
+echo Verifying native modules for %NODE_VER% and downloading whatever is missing.
+echo Progress is shown below; the full transcript goes to the log file.
+echo.
+
+:: The .mjs writes progress to stderr and - with TSMB_BINARY_LOG_STDOUT=1 - the
+:: same lines to stdout. Redirecting only stdout therefore keeps the log complete
+:: while the user still sees live progress instead of a frozen window.
+set "TSMB_BINARY_LOG_STDOUT=1"
+node scripts\download-binaries.mjs %CDN_MIRROR% >>"%LOG_FILE%"
+set "BIN_RESULT=!errorlevel!"
+set "TSMB_BINARY_LOG_STDOUT="
+
+:: ASCII only inside these blocks - see the note near the Node version check.
+if not "!BIN_RESULT!"=="0" (
+    set "FAILED=1"
+    call :error "A required native module is unusable - see the [binary] lines above."
+    echo         Required: @discordjs/opus and better-sqlite3.
+    echo         Full log: %LOG_FILE%
 )
+
+if "!FAILED!"=="1" (
+    echo.
+    echo Setup aborted. Fix the problem above and run this script again.
+    call :log "Setup aborted at step 4b"
+    pause
+    exit /b 1
+)
+
+echo [OK] Native binaries ready for %NODE_VER%.
+echo      ABI recorded in node_modules\.tsmusicbot-abi
 echo.
 
 :: ============================================================

scripts/setup.sh

@@ -27,6 +27,26 @@ if ! command -v node &>/dev/null; then
 fi
 echo "[OK] Node.js $(node -v)"
 
+# Newest Node major this project is regularly tested against. Anything above
+# still works, it just may have no prebuilt addons and fall back to a source build.
+TESTED_NODE_MAJOR=22
+NODE_MAJOR="$(node -p 'process.versions.node.split(".")[0]')"
+
+# The floor is not just a major version, so let node decide: @honeybbq/teamspeak-client
+# needs >=20.19, @sansenjian/qq-music-api needs >=20.17 / >=22.9, and the odd majors
+# (21 / 23) are excluded by better-sqlite3 and vitest. Keep in sync with package.json "engines".
+if ! node -e 'const v=process.versions.node.split(".").map(Number); process.exit((v[0]===20&&v[1]>=19)||(v[0]===22&&v[1]>=12)||v[0]>=24?0:1)'; then
+    echo "[ERROR] Node.js $(node -v) is not supported. Use Node 20.19+ LTS or Node 22.12+ LTS."
+    echo "        https://nodejs.org/  |  https://nodejs.cn/"
+    exit 1
+fi
+if [ "$NODE_MAJOR" -gt "$TESTED_NODE_MAJOR" ]; then
+    echo "[WARN] Node $(node -v) is newer than the tested LTS line (Node 20 / Node 22)."
+    echo "       新版 Node 可能没有现成的 opus / better-sqlite3 预编译包,"
+    echo "       安装时会自动改用源码编译,需要 C/C++ 构建工具,速度较慢。"
+    echo "       This is only a warning - setup builds the binaries for $(node -v) either way."
+fi
+
 if ! command -v npm &>/dev/null; then
     echo "[ERROR] npm not found."
     exit 1
@@ -73,15 +93,30 @@ npm install --registry="$MIRROR_REGISTRY" --ignore-scripts 2>&1 | tee -a "$LOG_F
 echo "[OK] Dependencies installed."
 echo ""
 
-# ---- Step 2: Download native binaries from CDN ----
-echo "---- 2/5: Downloading native binaries ----"
+# ---- Step 2: Verify / download / repair native binaries (ABI aware) ----
+echo "---- 2/5: Checking native binaries ----"
 echo ""
 
-if node scripts/download-binaries.mjs $CDN_MIRROR 2>&1 | tee -a "$LOG_FILE"; then
-    echo "[OK] Native binaries installed."
-else
-    echo "[WARN] Some native binaries had issues (will try source build as fallback)."
+# The old `if node ... | tee ...` only printed a [WARN] and carried on, so a
+# broken native module still produced a "Setup Complete!" banner. It also read
+# the *pipeline's* status: `set -o pipefail` above happens to surface node's
+# failure, but a failing `tee` (unwritable log) was indistinguishable from a
+# failing node. PIPESTATUS[0] is exactly node's own exit code, nothing else.
+set +e
+node scripts/download-binaries.mjs $CDN_MIRROR 2>&1 | tee -a "$LOG_FILE"
+BIN_STATUS=${PIPESTATUS[0]}
+set -e
+
+if [ "$BIN_STATUS" -ne 0 ]; then
+    echo ""
+    echo "[ERROR] A required native module (@discordjs/opus / better-sqlite3) is unusable."
+    echo "        必需的原生模块不可用,安装中止。原因见上面的 [binary] 输出。"
+    echo "        Log: $LOG_FILE"
+    exit 1
 fi
+# ffmpeg-static failures are only a WARN inside the script above (a system
+# ffmpeg on PATH is a supported fallback), so reaching here means we are good.
+echo "[OK] Native binaries ready for $(node -v)."
 echo ""
 
 # ---- Step 3: Install web panel dependencies ----

scripts/start.bat

@@ -29,6 +29,19 @@ if not exist "dist" (
     exit /b 1
 )
 
+:: Preflight: do the compiled native modules match THIS Node version?
+:: Switching Node majors after setup leaves node_modules built for the old ABI;
+:: without this check the bot dies mid-startup with a NODE_MODULE_VERSION stack.
+:: check-native.mjs prints the bilingual explanation itself; keep the lines in
+:: this block pure ASCII (cmd.exe garbles multi-byte text inside blocks).
+node scripts\check-native.mjs
+if errorlevel 1 (
+    echo.
+    echo Please run scripts\setup.bat to rebuild the native modules.
+    pause
+    exit /b 1
+)
+
 :: Ensure PowerShell is in PATH (fix for jdymusic CDN playback on some systems)
 where powershell >nul 2>&1
 if errorlevel 1 (
@@ -38,7 +51,10 @@ if errorlevel 1 (
 )
 
 :: Start the application
+echo WebUI: http://localhost:3000
+echo Press Ctrl+C to stop.
+echo.
 node dist/index.js
 
 pause
-
+

src/audio/queue.test.ts

@@ -605,4 +605,141 @@ describe("PlayQueue", () => {
       expect(q.list().map((s) => s.id)).toEqual(["A"]);
     });
   });
+
+  // Issue #141: in Random/RandomLoop, next() picks from the shuffle bag and
+  // ignores array order, so a song spliced in by addNext (!pn) was NOT played
+  // next — it just waited for its random turn like any other song. addNext now
+  // records the insert slot on the forward stack, which next() honours first.
+  describe("addNext in random modes (issue #141)", () => {
+    for (const mode of [PlayMode.Random, PlayMode.RandomLoop]) {
+      it(`plays the inserted song next in ${mode} mode`, () => {
+        queue.setMode(mode);
+        for (const id of ["a", "b", "c", "d"]) queue.add(makeSong(id));
+        queue.play(); // current = 0 (a)
+        queue.addNext(makeSong("x"));
+        expect(queue.next()?.id).toBe("x");
+      });
+    }
+
+    it("plays consecutive inserts in the order the queue displays them", () => {
+      queue.setMode(PlayMode.RandomLoop);
+      for (const id of ["a", "b", "c", "d"]) queue.add(makeSong(id));
+      queue.play(); // current = 0 (a)
+      queue.addNext(makeSong("x"));
+      queue.addNext(makeSong("y")); // splices in front of x, as in sequential
+      expect(queue.list().map((s) => s.id)).toEqual(["a", "y", "x", "b", "c", "d"]);
+      expect(queue.next()?.id).toBe("y");
+      expect(queue.next()?.id).toBe("x");
+    });
+
+    it("honours the insert even after the shuffle bag is exhausted", () => {
+      // Random (non-loop) returns null once every song has played. Songs added
+      // afterwards must still be reachable via !pn — and with TWO of them the
+      // order can only come from the forward stack, not from the bag having a
+      // single remaining candidate.
+      queue.setMode(PlayMode.Random);
+      for (const id of ["a", "b", "c", "d"]) queue.add(makeSong(id));
+      queue.play();
+      for (let i = 0; i < 3; i++) queue.next();
+      expect(queue.next()).toBeNull(); // bag exhausted
+      queue.addNext(makeSong("x"));
+      queue.addNext(makeSong("y"));
+      queue.addNext(makeSong("z"));
+      expect(queue.next()?.id).toBe("z");
+      expect(queue.next()?.id).toBe("y");
+      expect(queue.next()?.id).toBe("x");
+    });
+
+    it("pops past a prev() marker to reach the pending insert", () => {
+      // prev() shares the forward stack, and in random mode with no history it
+      // pushes the current index and then returns null. next() must walk past
+      // those self-referencing markers instead of consuming one and giving up
+      // to the shuffle bag.
+      queue.setMode(PlayMode.Random);
+      for (const id of ["a", "b", "c", "d"]) queue.add(makeSong(id));
+      queue.play(); // a
+      queue.addNext(makeSong("x"));
+      expect(queue.prev()).toBeNull();
+      expect(queue.prev()).toBeNull();
+      expect(queue.next()?.id).toBe("x");
+    });
+
+    it("plays each song exactly once — the insert is not replayed later", () => {
+      queue.setMode(PlayMode.Random);
+      for (const id of ["a", "b", "c", "d"]) queue.add(makeSong(id));
+      queue.play(); // a
+      queue.addNext(makeSong("x"));
+      queue.addNext(makeSong("y"));
+
+      const played = [queue.current()!.id];
+      for (let i = 0; i < 5; i++) played.push(queue.next()!.id);
+      expect(queue.next()).toBeNull(); // bag exhausted
+      expect(played.slice(0, 3)).toEqual(["a", "y", "x"]);
+      expect(new Set(played).size).toBe(6);
+    });
+
+    it("keeps the insert reachable after an earlier song is removed", () => {
+      queue.setMode(PlayMode.RandomLoop);
+      for (const id of ["a", "b", "c", "d"]) queue.add(makeSong(id));
+      queue.playAt(2); // current = 2 (c)
+      queue.addNext(makeSong("x")); // [a, b, c, x, d]
+      queue.remove(0); // [b, c, x, d] — x slides from 3 to 2
+      expect(queue.next()?.id).toBe("x");
+    });
+
+    it("drops the entry when the inserted song is itself removed", () => {
+      // Leaving the stale entry behind would not throw — index 2 still exists
+      // after the removal, it just points at a different song. So the queue is
+      // arranged with exactly one song the shuffle bag can legally return:
+      // anything else means the dead forward entry was honoured.
+      queue.setMode(PlayMode.RandomLoop);
+      for (const id of ["a", "b", "c"]) queue.add(makeSong(id));
+      queue.playAt(0); // current = 0 (a), played = {0}
+      queue.next(); // b or c — two of the three are now played
+      const remaining = queue.list().find((s) => s.id !== "a" && s.id !== queue.current()!.id)!;
+      queue.addNext(makeSong("x")); // spliced at currentIndex+1
+      queue.remove(queue.getCurrentIndex() + 1); // …and removed again
+      expect(queue.list().map((s) => s.id)).not.toContain("x");
+      expect(queue.next()?.id).toBe(remaining.id);
+    });
+
+    it("never yields a stale index under interleaved inserts and removals", () => {
+      // The forward stack holds array indices, so every splice has to shift
+      // them. next() returning `undefined` here (an out-of-range index) reads
+      // as end-of-queue to BotInstance.playNext and silently stops playback.
+      queue.setMode(PlayMode.RandomLoop);
+      for (let i = 0; i < 6; i++) queue.add(makeSong(`s${i}`));
+      queue.play();
+      for (let step = 0; step < 200; step++) {
+        const roll = step % 4;
+        if (roll === 0) queue.addNext(makeSong(`x${step}`));
+        else if (roll === 1 && queue.size() > 1) queue.remove(step % queue.size());
+        else {
+          const song = queue.next();
+          expect(song === null || song === queue.current()).toBe(true);
+          if (song !== null) expect(song).toBeDefined();
+        }
+      }
+    });
+
+    it("leaves sequential/loop behaviour untouched", () => {
+      queue.setMode(PlayMode.Sequential);
+      for (const id of ["a", "b", "c"]) queue.add(makeSong(id));
+      queue.play(); // a
+      queue.addNext(makeSong("x"));
+      expect(queue.next()?.id).toBe("x");
+      expect(queue.next()?.id).toBe("b");
+      expect(queue.next()?.id).toBe("c");
+      expect(queue.next()).toBeNull();
+    });
+
+    it("still appends (no forward entry) when nothing is playing", () => {
+      queue.setMode(PlayMode.Random);
+      queue.add(makeSong("a"));
+      queue.addNext(makeSong("x")); // currentIndex is still -1 → plain push
+      expect(queue.list().map((s) => s.id)).toEqual(["a", "x"]);
+      queue.play(); // a — a stray forward entry would have hijacked this
+      expect(queue.current()?.id).toBe("a");
+    });
+  });
 });

src/audio/queue.ts

@@ -60,8 +60,12 @@ export class PlayQueue {
    * or queue empty), so the existing "add → idle bot starts playing"
    * flow continues to work.
    *
-   * Shifts playedIndices and history entries > currentIndex by +1 so
-   * their references stay valid after the splice.
+   * Shifts playedIndices, history and forwardStack entries > currentIndex
+   * by +1 so their references stay valid after the splice.
+   *
+   * In the random modes the array position alone means nothing — next()
+   * picks from the shuffle bag — so the insert slot is also recorded on
+   * the forward stack, which next() consults first (issue #141).
    */
   addNext(song: QueuedSong): void {
     if (this.currentIndex < 0 || this.songs.length === 0) {
@@ -80,6 +84,23 @@ export class PlayQueue {
     this.history = this.history.map((i) =>
       i > this.currentIndex ? i + 1 : i,
     );
+
+    this.forwardStack = this.forwardStack.map((i) =>
+      i > this.currentIndex ? i + 1 : i,
+    );
+
+    // Push AFTER the shift, or the slot we just claimed would be shifted
+    // too. Stacking makes repeated !pn play in the order the queue shows
+    // them (each insert lands in front of the previous one), matching what
+    // sequential mode does with the same array. Bounded like history: drop the
+    // OLDEST pending entry rather than refusing the newest, so the song the
+    // user just asked for is always the one that gets honoured.
+    if (this.mode === PlayMode.Random || this.mode === PlayMode.RandomLoop) {
+      this.forwardStack.push(insertAt);
+      if (this.forwardStack.length > PlayQueue.HISTORY_LIMIT) {
+        this.forwardStack.shift();
+      }
+    }
   }
 
   remove(index: number): QueuedSong | null {
@@ -106,6 +127,13 @@ export class PlayQueue {
       .filter((idx) => idx !== index)
       .map((idx) => (idx > index ? idx - 1 : idx));
 
+    // …and for the forward stack, which now also carries !pn insert slots
+    // (issue #141). Left unshifted, a removal elsewhere in the queue would
+    // silently repoint the entry at whatever song slid into that slot.
+    this.forwardStack = this.forwardStack
+      .filter((idx) => idx !== index)
+      .map((idx) => (idx > index ? idx - 1 : idx));
+
     return removed;
   }
 
@@ -158,15 +186,22 @@ export class PlayQueue {
       }
       case PlayMode.Random:
       case PlayMode.RandomLoop: {
-        // 优先回到前进栈记录的位置（prev 退回的歌）
-        if (this.forwardStack.length > 0) {
+        // 优先回到前进栈记录的位置（prev 退回的歌，或 !pn 插入的歌）。
+        // Keep popping past entries that no longer point anywhere useful,
+        // the way prev() walks past stale history entries. Without the loop a
+        // prev() that pushed the current index would swallow the pending !pn
+        // entry behind it. The range check is belt-and-braces — addNext and
+        // remove keep the stack in sync — but an out-of-range index here would
+        // set currentIndex out of bounds and hand back `undefined`, which
+        // BotInstance.playNext reads as end-of-queue and stops playback.
+        while (this.forwardStack.length > 0) {
           const target = this.forwardStack.pop()!;
-          if (target !== this.currentIndex) {
-            this.pushHistory(this.currentIndex);
-            this.currentIndex = target;
-            this.playedIndices.add(target);
-            return this.songs[target];
-          }
+          if (target < 0 || target >= this.songs.length) continue;
+          if (target === this.currentIndex) continue;
+          this.pushHistory(this.currentIndex);
+          this.currentIndex = target;
+          this.playedIndices.add(target);
+          return this.songs[target];
         }
 
         // Shuffle bag: pick uniformly from the songs not yet played this

src/bot/instance.ts

@@ -1113,9 +1113,9 @@ export class BotInstance extends EventEmitter {
   /**
    * Resolve a !play/!add/!playnext argument into a single Song, supporting three
    * forms (issue #90):
-   *   1) "#N"          — the Nth result of the previous !search
-   *   2) id:<id> / URL — an exact song (disambiguates same-name songs)
-   *   3) plain text    — search, returning the single most-popular hit (legacy)
+   *   1) "#N"           — the Nth result of the previous !search
+   *   2) id <id> / URL  — an exact song (disambiguates same-name songs)
+   *   3) plain text     — search, returning the single most-popular hit (legacy)
    */
   private async resolvePlayQuery(cmd: ParsedCommand): Promise<{ song?: Song; error?: string }> {
     const args = (cmd.args ?? "").trim();
@@ -1131,7 +1131,7 @@ export class BotInstance extends EventEmitter {
       return { song: this.lastSearchResults[sel - 1] };
     }
 
-    // 2) id:/URL — fetch that exact song.
+    // 2) id/URL — fetch that exact song.
     const ref = parseSongRef(args);
     if (ref) {
       if (ref.platform) this.assertProviderEnabled(ref.platform);
@@ -1159,13 +1159,13 @@ export class BotInstance extends EventEmitter {
       (s, i) => `${i + 1}. ${s.name} - ${s.artist}${s.album ? ` 《${s.album}》` : ""} [id:${s.id}]`,
     );
     return [
-      `搜索结果（用 ${p}play #序号 播放，或 ${p}play id:<id>）:`,
+      `搜索结果（用 ${p}play #序号 播放，或 ${p}play id <id>）:`,
       ...lines,
     ].join("\n");
   }
 
   private async cmdPlay(cmd: ParsedCommand, requesterName?: string): Promise<string> {
-    if (!cmd.args) return `Usage: ${this.config.commandPrefix}play <song name | #N | id:<id> | URL>`;
+    if (!cmd.args) return `Usage: ${this.config.commandPrefix}play <song name | #N | id <id> | URL>`;
     const { song, error } = await this.resolvePlayQuery(cmd);
     if (error) return error;
     const song0 = song!;
@@ -1259,7 +1259,7 @@ export class BotInstance extends EventEmitter {
   }
 
   private async cmdAdd(cmd: ParsedCommand, requesterName?: string): Promise<string> {
-    if (!cmd.args) return `Usage: ${this.config.commandPrefix}add <song name | #N | id:<id> | URL>`;
+    if (!cmd.args) return `Usage: ${this.config.commandPrefix}add <song name | #N | id <id> | URL>`;
     const { song, error } = await this.resolvePlayQuery(cmd);
     if (error) return error;
     const s = song!;
@@ -1283,7 +1283,7 @@ export class BotInstance extends EventEmitter {
   }
 
   private async cmdPlayNext(cmd: ParsedCommand, requesterName?: string): Promise<string> {
-    if (!cmd.args) return `Usage: ${this.config.commandPrefix}playnext <song name | #N | id:<id> | URL>`;
+    if (!cmd.args) return `Usage: ${this.config.commandPrefix}playnext <song name | #N | id <id> | URL>`;
     const { song, error } = await this.resolvePlayQuery(cmd);
     if (error) return error;
     const s = song!;
@@ -1840,8 +1840,8 @@ export class BotInstance extends EventEmitter {
       ...(flagHelp ? [`  Source flags: ${flagHelp}`] : []),
       `${p}search <name> — List top matches to pick a specific (same-name) song`,
       `${p}play #N       — Play the Nth result of the last ${p}search`,
-      `${p}play id:<id>  — Play an exact song by id / URL`,
-      `${p}add <song>   — Add to queue (also accepts #N / id: / URL)`,
+      `${p}play id <id> — Play an exact song by id / URL`,
+      `${p}add <song>   — Add to queue (also accepts #N / id <id> / URL)`,
       `${p}playnext <song> — Insert as next song (alias: ${p}pn)`,
       `${p}pause/resume — Pause/resume`,
       `${p}next/prev    — Next/previous`,

src/bot/song-ref.test.ts

@@ -21,6 +21,59 @@ describe("parseSongRef (#90 exact-song selection)", () => {
     expect(parseSongRef("id:185868,")).toEqual({ id: "185868", platform: null });
   });
 
+  // Issue #139: `!play id <id>` matches the "<command> <subcommand> <arg>"
+  // shape of every other command. The colon form stays supported — users have
+  // it in their chat scrollback and in older docs.
+  it("parses the space-separated id form", () => {
+    expect(parseSongRef("id 185868")).toEqual({ id: "185868", platform: null });
+    expect(parseSongRef("ID 004Z8Ihr0JIu5s")).toEqual({ id: "004Z8Ihr0JIu5s", platform: null });
+    expect(parseSongRef("id   185868")).toEqual({ id: "185868", platform: null });
+    expect(parseSongRef("id 185868.")).toEqual({ id: "185868", platform: null });
+  });
+
+  it("does not mistake a word merely starting with 'id' for an id reference", () => {
+    expect(parseSongRef("idol")).toBeNull();
+    expect(parseSongRef("identity 185868")).toBeNull();
+    expect(parseSongRef("id")).toBeNull();
+    expect(parseSongRef("id:")).toBeNull();
+    // Two remaining tokens are a search phrase, not an id.
+    expect(parseSongRef("id die for you")).toBeNull();
+  });
+
+  // Without a colon, "id" is just a word — "ID 4" and "ID Bruno" are real track
+  // titles. The space form therefore only claims tokens that could actually be
+  // an id; everything else stays a search term.
+  it("only treats the space form as an id when the token looks like one", () => {
+    expect(parseSongRef("id Bruno")).toBeNull();
+    expect(parseSongRef("id Marshmello")).toBeNull();
+    expect(parseSongRef("id 4ever")).toBeNull();
+    // …while every real id shape is still accepted.
+    expect(parseSongRef("id 4")).toEqual({ id: "4", platform: null });          // numeric
+    expect(parseSongRef("id BV1yxHQeYEuE")).toEqual({ id: "BV1yxHQeYEuE", platform: null });
+    expect(parseSongRef("id 004Z8Ihr0JIu5s")).toEqual({ id: "004Z8Ihr0JIu5s", platform: null }); // QQ mid
+    expect(parseSongRef("id a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6")).toEqual({
+      id: "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
+      platform: null,
+    }); // Jellyfin GUID / Kugou hash
+  });
+
+  it("keeps the colon form unrestricted, so a short or odd id still works", () => {
+    expect(parseSongRef("id:Bruno")).toEqual({ id: "Bruno", platform: null });
+    expect(parseSongRef("id: 4ever")).toEqual({ id: "4ever", platform: null });
+  });
+
+  it("does not let the space form swallow a pasted URL", () => {
+    // `id <url>` used to fall through to the URL branches; it still must.
+    expect(parseSongRef("id https://music.163.com/song?id=185868")).toEqual({
+      id: "185868",
+      platform: "netease",
+    });
+    expect(parseSongRef("id https://y.qq.com/n/ryqq/songDetail/004Z8Ihr0JIu5s")).toEqual({
+      id: "004Z8Ihr0JIu5s",
+      platform: "qq",
+    });
+  });
+
   it("does NOT treat NetEase collection (playlist/album/artist) URLs as a song id", () => {
     // These reuse ?id= but are not songs — they should fall through to search,
     // not misresolve to getSongDetail(collectionId) and error "no song".

src/bot/song-ref.ts

@@ -18,9 +18,22 @@ export interface SongRef {
   platform: "netease" | "qq" | "bilibili" | null;
 }
 
+/**
+ * Could this token plausibly BE an id on a supported platform?
+ *   - NetEase / Kugou numeric ids      → all digits
+ *   - BiliBili                         → BV + 8-12 alphanumerics
+ *   - QQ mid (14), YouTube (11), Spotify (22), Jellyfin GUID / Kugou hash (32)
+ *                                      → 11+ chars from the id alphabet
+ * Deliberately conservative: anything rejected here just stays an ordinary
+ * search term, which is what it almost certainly was.
+ */
+function looksLikeSongId(token: string): boolean {
+  return /^(?:\d+|BV[0-9A-Za-z]{8,12}|[0-9A-Za-z_-]{11,})$/i.test(token);
+}
+
 /**
  * Detect an explicit song reference in a query. Recognizes:
- *   - `id:<id>`                         → platform from flags/default
+ *   - `id <id>` / `id:<id>`             → platform from flags/default
  *   - NetEase song URL                  → music.163.com/song?id=N (also /#/song?id=N, /song/N)
  *   - QQ song URL                       → y.qq.com/.../songDetail/MID (or ?songmid=MID)
  *   - BiliBili BVID (bare or in a URL)  → bilibili.com/video/BVxxxx, b23.tv, or BVxxxx
@@ -30,11 +43,25 @@ export function parseSongRef(raw: string): SongRef | null {
   const q = (raw ?? "").trim();
   if (!q) return null;
 
-  // Explicit "id:<id>" — platform decided by the command's flags/default.
-  // Strip trailing punctuation that tags along from a chat paste ("id:12345."
-  // / "id:12345)") — no supported id (numeric / BVID / mid) ends in those.
-  const idPrefix = /^id:\s*(\S+)$/i.exec(q);
-  if (idPrefix) return { id: idPrefix[1].replace(/[.,;)\]]+$/, ""), platform: null };
+  // Explicit id — platform decided by the command's flags/default. The
+  // separator is a colon or plain whitespace, so `id <id>` matches the
+  // `!<cmd> <sub> <arg>` shape of every other command (issue #139) while the
+  // older `id:<id>` keeps working. Strip trailing punctuation that tags along
+  // from a chat paste ("id:12345." / "id:12345)") — no supported id
+  // (numeric / BVID / mid) ends in those.
+  //
+  // The colon is an unambiguous sigil, so `id:<anything>` is always an id. A
+  // space is not: "ID 4" and "ID Bruno" are real track titles, and `id <url>`
+  // has to keep resolving as a URL. So the space form only claims tokens that
+  // could actually be an id; anything else falls through to the URL branches
+  // below and ultimately to a plain search.
+  const idPrefix = /^id(:\s*|\s+)(\S+)$/i.exec(q);
+  if (idPrefix) {
+    const id = idPrefix[2].replace(/[.,;)\]]+$/, "");
+    if (idPrefix[1].startsWith(":") || looksLikeSongId(id)) {
+      return { id, platform: null };
+    }
+  }
 
   // BiliBili BV id, bare or inside a bilibili URL (NetEase ids are numeric, so
   // a "BV..." token never collides with them).

start.bat

@@ -1,19 +1,24 @@
 @echo off
-title TSMusicBot
+:: ============================================================
+::  TSMusicBot - convenience launcher at the repo root.
+::  Everything real lives in scripts\start.bat; this file only makes sure we
+::  run from the project directory and then delegates, so both entry points
+::  behave identically (same node/dist checks, same native-module preflight).
+:: ============================================================
 
-:: Check node
-where node >nul 2>&1
-if errorlevel 1 (
-    echo Node.js not found. Run scripts\setup.bat first.
+cd /d "%~dp0" || (
+    echo [FATAL] Cannot change to the project directory.
     pause
     exit /b 1
 )
 
-echo Starting TSMusicBot...
-echo WebUI: http://localhost:3000
-echo Press Ctrl+C to stop.
-echo.
+:: Keep lines inside parenthesised blocks pure ASCII: cmd.exe mis-tracks its
+:: file offset when a block contains multi-byte UTF-8 and eats the "echo " prefix.
+if not exist "scripts\start.bat" (
+    echo scripts\start.bat not found - is this the TSMusicBot project folder?
+    pause
+    exit /b 1
+)
 
-node dist\index.js
-
-pause
+call "scripts\start.bat"
+exit /b %errorlevel%

web/index.html

@@ -22,6 +22,22 @@
        "same-origin" keeps the real Origin on same-origin requests, so CSRF passes. -->
   <meta name="referrer" content="same-origin">
   <title>TSMusicBot</title>
+  <!-- Icons live in web/public/ so Vite copies them to the dist root, which is
+       what Express serves (src/index.ts STATIC_DIR). Both an .ico and an .svg
+       are declared: browsers that understand the vector one prefer it and stay
+       sharp on hi-dpi tabs, the rest fall back to the .ico. The .ico also
+       answers the implicit /favicon.ico request — without a real file there the
+       SPA catch-all hands back index.html with a 200, so the tab silently keeps
+       the blank-page icon (issue #142). -->
+  <link rel="icon" href="/favicon.ico" sizes="48x48">
+  <link rel="icon" href="/favicon.svg" type="image/svg+xml" sizes="any">
+  <!-- iOS home-screen icon; iOS masks the corners itself, so this one is a
+       full square. Android reads the manifest instead. -->
+  <link rel="apple-touch-icon" href="/apple-touch-icon.png">
+  <link rel="manifest" href="/site.webmanifest">
+  <!-- Matches --bg-primary of the dark theme, which is what the app starts in
+       (stores/player.ts defaults to 'dark' and never follows the OS scheme). -->
+  <meta name="theme-color" content="#222222">
   <link rel="preconnect" href="https://fonts.googleapis.com">
   <link href="https://fonts.googleapis.com/css2?family=Barlow:wght@400;500;600;700;800&display=swap" rel="stylesheet">
 </head>

web/public/favicon.svg

@@ -0,0 +1,10 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 100 100">
+  <rect width="100" height="100" rx="22" fill="#335eea"/>
+  <g fill="#ffffff" transform="translate(48.46 51.1) scale(0.88) translate(-50 -50)">
+    <path d="M43.5 24 L86.5 15 L86.5 26 L43.5 35 Z"/>
+    <rect x="43.5" y="24" width="6" height="47"/>
+    <rect x="80.5" y="15" width="6" height="47"/>
+    <ellipse cx="32" cy="71" rx="15" ry="11.5" transform="rotate(-20 32 71)"/>
+    <ellipse cx="69" cy="62" rx="15" ry="11.5" transform="rotate(-20 69 62)"/>
+  </g>
+</svg>

web/public/site.webmanifest

@@ -0,0 +1,26 @@
+{
+  "name": "TSMusicBot",
+  "short_name": "TSMusicBot",
+  "start_url": "/",
+  "display": "standalone",
+  "background_color": "#222222",
+  "theme_color": "#222222",
+  "icons": [
+    {
+      "src": "/icon-192.png",
+      "sizes": "192x192",
+      "type": "image/png"
+    },
+    {
+      "src": "/icon-512.png",
+      "sizes": "512x512",
+      "type": "image/png"
+    },
+    {
+      "src": "/icon-maskable-512.png",
+      "sizes": "512x512",
+      "type": "image/png",
+      "purpose": "maskable"
+    }
+  ]
+}

web/src/App.vue

@@ -9,9 +9,20 @@
     <Queue class="mobile-queue" :open="mobileQueueOpen" @close="mobileQueueOpen = false" />
 
     <!-- Mobile mini player -->
-    <div v-if="currentSong" class="m-player" @click="router.push('/lyrics')">
-      <div class="m-player-progress">
-        <div class="m-player-progress-fill" :style="{ width: mobileProgressPct + '%' }" />
+    <div v-if="currentSong" class="m-player" @click="onPlayerRowClick">
+      <div
+        ref="seekBarRef"
+        class="m-player-progress"
+        :class="{ 'no-seek': !canSeek, dragging: seeking }"
+        @pointerdown="onSeekDown"
+        @pointermove="onSeekMove"
+        @pointerup="onSeekUp"
+        @pointercancel="onSeekCancel"
+      >
+        <div class="m-player-progress-track">
+          <div class="m-player-progress-fill" :style="{ width: seekBarPct + '%' }" />
+          <div class="m-player-progress-thumb" :style="{ left: seekBarPct + '%' }" />
+        </div>
       </div>
       <CoverArt :url="currentSong.coverUrl" :size="40" :radius="8" />
       <div class="m-player-info">
@@ -79,7 +90,7 @@
 </template>
 
 <script setup lang="ts">
-import { computed, onMounted, onUnmounted, ref } from 'vue';
+import { computed, onMounted, onUnmounted, ref, watch } from 'vue';
 import { useRoute, useRouter } from 'vue-router';
 import { Icon } from '@iconify/vue';
 import { usePlayerStore } from './stores/player.js';
@@ -132,15 +143,174 @@ let syncTimer: ReturnType<typeof setInterval> | null = null;
 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.liveElapsed() / duration) * 100, 100)
-    : 0;
+  // While the finger owns the bar, the clock must keep its hands off it — see
+  // seekBarPct below. Skipping the write (rather than letting it be overridden)
+  // also avoids 60 pointless reactive re-renders per second mid-drag.
+  if (!seeking.value) {
+    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.liveElapsed() / duration) * 100, 100)
+      : 0;
+  }
   mobileRaf = requestAnimationFrame(updateMobileProgress);
 }
 
+// --- Mini-player seek (#143) -------------------------------------------------
+// The mobile progress bar used to be display-only. It now supports tap-to-seek
+// and drag-to-seek via Pointer Events (one code path for touch, pen and mouse —
+// no mouse/touch handler pairs) with setPointerCapture, so the drag survives the
+// finger sliding off the 12px strip.
+//
+// Decoupling, exactly the reasoning of composables/useDecoupledSlider.ts (#111):
+// updateMobileProgress() rewrites the rendered percentage every animation frame
+// from the *server* clock, which is still the pre-seek position while the user
+// drags. Binding the bar straight to it would snap the fill back under the
+// finger ~60 times a second. So the rendered value is a computed that switches
+// its source: the finger while `seeking`, the clock otherwise.
+const seekBarRef = ref<HTMLElement | null>(null);
+const seeking = ref(false);
+const seekPct = ref(0);
+let seekPointerId: number | null = null;
+// The song the gesture started on. currentSong can advance mid-drag (the track
+// ends), and the ratio the finger picked means nothing against a different
+// song's duration.
+let seekSongId: string | null = null;
+// Bumped per gesture so a slow seek POST can't clear the override belonging to a
+// newer drag that started while it was still in flight.
+let seekGeneration = 0;
+// Timestamp of the last seek gesture end, used to swallow the trailing click
+// (see onPlayerRowClick).
+let seekEndedAt = 0;
+
+const seekBarPct = computed(() => (seeking.value ? seekPct.value : mobileProgressPct.value));
+
+/** Pointer x → 0..1 along the strip, or null when the element isn't measurable. */
+function seekRatio(e: PointerEvent): number | null {
+  const el = seekBarRef.value;
+  if (!el) return null;
+  const rect = el.getBoundingClientRect();
+  if (rect.width <= 0) return null;
+  return Math.max(0, Math.min(1, (e.clientX - rect.left) / rect.width));
+}
+
+/** Duration guard: live streams report 0/undefined and ratio*0 would seek to 0,
+ *  while a missing duration would produce NaN — which the API rejects with 400. */
+function seekableDuration(): number {
+  const duration = currentSong.value?.duration ?? 0;
+  return Number.isFinite(duration) && duration > 0 ? duration : 0;
+}
+
+// Drives the `no-seek` class as well as the gesture guard, so a bar that cannot
+// be seeked also gives `touch-action` back to the page — otherwise the strip
+// would be a 12px band that neither seeks nor scrolls.
+const canSeek = computed(() => canTransport.value && seekableDuration() > 0);
+
+function endSeekGesture() {
+  const el = seekBarRef.value;
+  if (el && seekPointerId !== null && el.hasPointerCapture?.(seekPointerId)) {
+    el.releasePointerCapture(seekPointerId);
+  }
+  seekPointerId = null;
+  seekEndedAt = Date.now();
+}
+
+function onSeekDown(e: PointerEvent) {
+  // Seeking is gated on transport, like the desktop player's `no-seek` state:
+  // without it the bar stays purely visual and taps fall through to the row.
+  if (!canSeek.value) return;
+  // One gesture at a time: a second finger landing on the strip would otherwise
+  // steal seekPointerId, leaving the first pointer captured forever and
+  // committing whichever finger happened to lift first.
+  if (seekPointerId !== null) return;
+  const ratio = seekRatio(e);
+  if (ratio === null) return;
+  // Never let the row's router.push('/lyrics') fire while the user is seeking.
+  e.stopPropagation();
+  e.preventDefault(); // suppress text selection / compat mouse events during the drag
+  seekPointerId = e.pointerId;
+  seekSongId = currentSong.value?.id ?? null;
+  seekGeneration += 1;
+  seekBarRef.value?.setPointerCapture?.(e.pointerId);
+  seeking.value = true;
+  seekPct.value = ratio * 100;
+}
+
+function onSeekMove(e: PointerEvent) {
+  if (!seeking.value || e.pointerId !== seekPointerId) return;
+  const ratio = seekRatio(e);
+  if (ratio === null) return;
+  e.stopPropagation();
+  seekPct.value = ratio * 100;
+}
+
+async function onSeekUp(e: PointerEvent) {
+  if (!seeking.value || e.pointerId !== seekPointerId) return;
+  e.stopPropagation();
+  // A tap never moves, so pointerup is also the commit point for tap-to-seek.
+  const ratio = seekRatio(e) ?? seekPct.value / 100;
+  seekPct.value = ratio * 100;
+  const duration = seekableDuration();
+  const generation = seekGeneration;
+  // If the track advanced while the finger was down, the ratio belongs to a
+  // song that is no longer playing — drop the seek rather than applying it to
+  // whatever started next.
+  const sameSong = currentSong.value?.id === seekSongId;
+  endSeekGesture(); // must run synchronously, before the awaited POST
+  try {
+    if (duration > 0 && sameSong) await playerStore.seek(ratio * duration);
+  } catch {
+    // Seek rejected (403/400/offline) — fall back to the server clock below.
+  } finally {
+    // Release the local override only once seek() has resolved. store.seek()
+    // moves its timing anchor to the requested position in the same tick, so
+    // liveElapsed() already reports the new spot and the bar simply carries on
+    // from where the finger left it. Releasing at pointerup instead would show
+    // the *old* position for one round-trip and then jump a second time.
+    // (_syncAfterAction re-polls 500ms later, but that only nudges the bar by
+    // the network delta — not worth freezing the clock for.)
+    if (generation === seekGeneration) seeking.value = false;
+  }
+}
+
+function onSeekCancel(e: PointerEvent) {
+  if (e.pointerId !== seekPointerId) return;
+  // Gesture stolen (system gesture, call, …): abandon without seeking and hand
+  // the bar straight back to the clock.
+  endSeekGesture();
+  seeking.value = false;
+}
+
+// The whole mini player lives inside `v-if="currentSong"`, so when playback
+// stops mid-drag the strip is destroyed and no pointerup/pointercancel can ever
+// reach it — element removal is not a pointercancel trigger. Without this the
+// `seeking` override would stay true and the progress bar would sit frozen for
+// the rest of the session. Bumping the generation also neuters the finally of
+// any seek still in flight.
+watch(currentSong, () => {
+  if (!seeking.value) return;
+  seekGeneration += 1;
+  seekPointerId = null;
+  seekSongId = null;
+  seeking.value = false;
+});
+
+function onPlayerRowClick() {
+  // Both a tap and a drag on the strip emit a trailing `click`, which would
+  // otherwise navigate to /lyrics the moment the user finishes seeking. A
+  // `@click.stop` on the strip is not enough: after a drag the click's target is
+  // the nearest common ancestor of the pointerdown/pointerup hit-tests, i.e.
+  // `.m-player` itself once the finger has left the 12px strip. So the row
+  // swallows any click arriving right after a seek gesture. A timestamp rather
+  // than a flag, so a gesture that produces no click at all (preventDefault,
+  // pointercancel) can't leave the row permanently unclickable — and so an inert
+  // strip (no transport permission, unknown duration) still falls through here
+  // and navigates, exactly as it did before.
+  if (Date.now() - seekEndedAt < 400) return;
+  router.push('/lyrics');
+}
+
 function toggleMobileVolume() {
   mobileVolumeOpen.value = !mobileVolumeOpen.value;
   if (mobileVolumeOpen.value) mobileQueueOpen.value = false;
@@ -242,15 +412,69 @@ onUnmounted(() => {
   top: 0;
   left: 10px;
   right: 10px;
+  // The visible track stays 2px, but 2px is not a touch target (#143), so the
+  // hit area is 12px and grows DOWNWARD into the mini player's own 8px top
+  // padding. It must not reach the transport buttons: they are 32px tall and
+  // centred in the 58px row's 42px content box, i.e. their top edge sits at
+  // 8 + (42 - 32) / 2 = 13px. 12px clears them by 1px. Growing upward is not an
+  // option — that is outside the player's rounded top edge.
+  height: 12px;
+  // Without this the browser claims the gesture for page scrolling partway
+  // through the drag and the pointermove stream stops.
+  touch-action: none;
+  cursor: pointer;
+  user-select: none;
+  -webkit-user-select: none;
+
+  // No transport permission → purely decorative (mirrors Player.vue's .no-seek).
+  // Handing touch-action back matters: an inert strip must not eat gestures.
+  &.no-seek {
+    touch-action: auto;
+  }
+}
+
+.m-player-progress-track {
+  position: relative;
+  // Nudged down inside the 12px hit area so the drag thumb, which is centred on
+  // the track, stays within the card instead of poking out above its top edge.
+  // The 8px thumb's box is (3 + 1 - 4) = 0 to 8, i.e. exactly flush with the
+  // card. (The container is absolutely positioned, so it forms a BFC and this
+  // margin cannot collapse through it.)
+  margin-top: 3px;
   height: 2px;
+  border-radius: 1px;
+  background: var(--border-color);
 }
 
 .m-player-progress-fill {
-  height: 2px;
+  position: absolute;
+  top: 0;
+  left: 0;
+  height: 100%;
   background: var(--color-primary);
   border-radius: 1px;
 }
 
+.m-player-progress-thumb {
+  position: absolute;
+  top: 1px;
+  width: 8px;
+  height: 8px;
+  margin-top: -4px;
+  margin-left: -4px;
+  background: var(--color-primary);
+  border-radius: var(--radius-full);
+  opacity: 0;
+  transform: scale(0);
+  transition: opacity var(--transition-fast), transform var(--transition-fast);
+  pointer-events: none;
+}
+
+.m-player-progress.dragging .m-player-progress-thumb {
+  opacity: 1;
+  transform: scale(1);
+}
+
 .m-player-info {
   flex: 1;
   min-width: 0;

web/src/components/Queue.vue

@@ -26,6 +26,7 @@
         :key="`${song.id}-${i}`"
         class="queue-item"
         :class="{ active: store.currentSong?.id === song.id }"
+        @click="onRowClick($event, i)"
         @dblclick="playAtIndex(i)"
       >
         <CoverArt :url="song.coverUrl" :size="32" :radius="4" />
@@ -33,7 +34,7 @@
           <div class="queue-song-name">{{ song.name }}</div>
           <div class="queue-song-artist">{{ song.artist }}</div>
         </div>
-        <button v-if="can('player.queue') || guestCan('removeClear')" class="remove-btn" @click="removeSong(i)" title="移除">
+        <button v-if="can('player.queue') || guestCan('removeClear')" class="remove-btn" @click.stop="removeSong(i)" title="移除">
           <Icon icon="mdi:close" />
         </button>
       </div>
@@ -72,6 +73,21 @@ async function playAtIndex(index: number) {
   await store.fetchQueue();
 }
 
+// Touch has no `dblclick`, so double-click-to-play was dead in the mobile queue
+// drawer (#143). Same per-event touch rule as SongCard.vue — see the full
+// rationale in the `isTouchClick` comment there. Permission gating stays in
+// playAtIndex(); the remove button uses @click.stop so it can't double-fire.
+function isTouchClick(e: MouseEvent): boolean {
+  const pointerType = (e as PointerEvent).pointerType;
+  if (pointerType) return pointerType === 'touch' || pointerType === 'pen';
+  return window.matchMedia?.('(pointer: coarse)').matches ?? false;
+}
+
+function onRowClick(e: MouseEvent, index: number) {
+  if (!isTouchClick(e)) return;
+  void playAtIndex(index);
+}
+
 async function removeSong(index: number) {
   if (!store.activeBotId) return;
   try {
@@ -205,4 +221,15 @@ async function clearAndStop() {
   color: var(--text-tertiary);
   &:hover { color: var(--text-primary); }
 }
+
+// Touch devices have no :hover, so the parent-hover-reveals-the-button pattern
+// leaves an *invisible but still tappable* remove button on the right edge of
+// every row. Now that a single tap on the row plays (#143), that invisible
+// target reads as "I tapped to play and it deleted the song" — show it, same as
+// .song-actions in SongCard.vue.
+@media (pointer: coarse) {
+  .remove-btn {
+    opacity: 1;
+  }
+}
 </style>

web/src/components/SongCard.vue

@@ -1,5 +1,5 @@
 <template>
-  <div class="song-card" :class="{ active }" @dblclick="showPlay && $emit('play')">
+  <div class="song-card" :class="{ active }" @click="onRowClick" @dblclick="showPlay && $emit('play')">
     <div class="song-index">{{ index }}</div>
     <CoverArt :url="song.coverUrl" :size="36" :radius="6" />
     <div class="song-info">
@@ -51,12 +51,41 @@ 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<{
+const emit = defineEmits<{
   play: [];
   playNext: [];
   add: [];
 }>();
 
+/**
+ * Was this click made with a finger/stylus rather than a mouse? (#143)
+ *
+ * `dblclick` is mouse-only and never fires on touch, so double-tap-to-play was
+ * simply dead on phones. A single *tap* plays instead, while a single mouse
+ * click must keep doing nothing — otherwise desktop behaviour changes and the
+ * surviving dblclick would fire play twice.
+ *
+ * The check is per-EVENT, not per-device: a `click` is a PointerEvent in modern
+ * browsers, so pointerType describes how *this* click was made. A global
+ * matchMedia('(pointer: coarse)') check reports only the *primary* pointer and
+ * is therefore wrong on hybrid laptops (touchscreen + trackpad); it is used only
+ * as a fallback for browsers that give us no pointerType.
+ */
+function isTouchClick(e: MouseEvent): boolean {
+  const pointerType = (e as PointerEvent).pointerType;
+  if (pointerType) return pointerType === 'touch' || pointerType === 'pen';
+  return window.matchMedia?.('(pointer: coarse)').matches ?? false;
+}
+
+// Listening on `click` rather than `pointerup` on purpose: the browser already
+// suppresses the click that ended a scroll gesture, so a tap that was really the
+// start of a flick can't hijack playback for everyone in the channel.
+// (The action buttons stop propagation, so they never double-fire this.)
+function onRowClick(e: MouseEvent) {
+  if (!showPlay.value || !isTouchClick(e)) return;
+  emit('play');
+}
+
 function formatDuration(seconds: number): string {
   const m = Math.floor(seconds / 60);
   const s = seconds % 60;

web/src/views/Settings.vue

@@ -387,7 +387,7 @@
             <img :src="qqQr.dataUrl" class="qr-image" alt="QR Code" />
             <div class="qr-status" :class="qqQr.status">
               <template v-if="qqQr.status === 'waiting'">
-                <Icon icon="mdi:cellphone" /> 请使用QQ音乐APP扫码
+                <Icon icon="mdi:cellphone" /> 请使用手机QQ扫码
               </template>
               <template v-else-if="qqQr.status === 'scanned'">
                 <Icon icon="mdi:check" /> 已扫码，请在手机上确认