docs: README updates for WebUI auth feature + pre-auth upgrade guide

Every response now carries:
  X-Frame-Options: DENY
  Content-Security-Policy: frame-ancestors 'none'

Prevents the WebUI from being embedded in a third-party iframe.
Combined with the existing CSRF Origin-host check, this closes the
last meaningful UI-redress surface.

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

.claude/settings.local.json

@@ -19,8 +19,6 @@
       "Read(//tmp/**)"
     ],
     "deny": [
-      "Bash(git push * main)",
-      "Bash(git push * master)",
       "Bash(git push --force *)",
       "Bash(rm -rf /)"
     ]

README.md

@@ -23,6 +23,7 @@
 
 ## 功能特性
 
+- **WebUI 鉴权（必选）** — 用户名 + 密码登录，多用户、两种角色（管理员 / 成员），bcrypt 加密、HttpOnly 会话 Cookie，CSRF 防护，WebSocket 同样鉴权。首次访问引导创建管理员。从无鉴权旧版本升级时请参阅 [更新升级](#更新升级) 章节
 - **多平台音源** — 网易云音乐 + QQ 音乐 + 哔哩哔哩（默认内置），YouTube 可选启用（通过 yt-dlp），统一搜索，结果标注来源
 - **真实客户端协议 (TS3/TS6 双协议)** — 机器人在 TeamSpeak 中可见（非 ServerQuery 隐身模式），自动检测并适配 TS3 和 TS6 服务器，支持 TS6 HTTP Query API
 - **YesPlayMusic 风格 WebUI** — 精美界面，支持深色/浅色主题切换
@@ -155,6 +156,49 @@ sudo ./scripts/install.sh
 >
 > **如何判断是否需要迁移**：如果你是全新安装，或者你的机器人数据库中 `identity` 字段已经是空的，则**无需任何操作**。完成上述步骤后，按下面对应的系统升级步骤执行即可。
 
+### 从 WebUI 无鉴权版本升级（重要）
+
+本次更新引入了**强制 WebUI 鉴权**。从无鉴权旧版本升级后，**WebUI 必须先创建管理员账号才能使用**。所有 `/api/*` 端点（除少量公共白名单）和 `/ws` 现在都需要登录。
+
+**升级行为**：
+
+- 启动时数据库自动迁移：新增 `users`、`sessions`、`user_audit` 三张表；旧的 `bot_instances`、`play_history` 数据**完全保留**。
+- 第一次打开 WebUI 自动跳转到 `/first-run` 引导创建首位管理员（角色固定为 `admin`）。
+- 之后访问任何页面都会校验登录态，未登录跳转 `/login`。
+
+**会话与 Cookie**：
+
+- 登录态保存 7 天，每次请求滚动续期（活跃用户不会被踢出）。
+- 同一账号最多保持 10 个并发会话（超过自动剔除最旧的）。
+- Cookie 设置为 `HttpOnly; SameSite=Lax`，HTTPS 部署需配合 `trustProxy: true`（详见 [反向代理部署注意事项](#反向代理部署注意事项)）。
+
+**多用户与角色**：
+
+- 角色 `admin`：完整权限（用户管理、审计、机器人、音乐平台、播放控制）。
+- 角色 `member`：除"用户管理"和"操作审计"外的所有功能（适合给团队成员开通播放权）。
+- 在 **设置 → 用户管理**（仅管理员）中添加 / 删除 / 重置密码 / 切换角色。
+- 至少保留一个管理员：系统会阻止删除或降级最后一位管理员。
+
+**如何重置忘记的管理员密码**：
+
+如果你忘记了管理员密码，可以直接编辑 SQLite 数据库 `data/tsmusicbot.db`：
+
+```bash
+# 方案 1：清空所有用户，重新进入 first-run 流程
+sqlite3 data/tsmusicbot.db "DELETE FROM users; DELETE FROM sessions;"
+# 然后重启机器人，浏览器再次访问会自动进入 /first-run
+
+# 方案 2：把指定用户重置为已知密码（密码 'changeme-now' 的 bcrypt 哈希示例如下）
+# 先用 node 生成哈希：
+node -e "console.log(require('bcryptjs').hashSync('changeme-now', 12))"
+# 把输出贴到 SQL 里：
+sqlite3 data/tsmusicbot.db "UPDATE users SET passwordHash='<paste-hash-here>' WHERE username='你的用户名';"
+```
+
+**反向代理用户特别注意**：如果通过 nginx / Caddy / Cloudflare 暴露 WebUI，**必须**在 `config.json` 中设置 `"trustProxy": true`，否则 Cookie 不会带 `Secure` 标志，且登录限流会把所有用户合并到同一个桶。详见下方 [反向代理部署注意事项](#反向代理部署注意事项)。
+
+**旧版 `config.adminPassword` / `adminGroups`**：这两个配置项在旧版本中预留但从未实际启用（TS-side admin 命令权限的占位字段）。保留以避免破坏旧 `config.json`，但不再影响任何行为。可以放心忽略。
+
 ### Windows 用户
 
 ```
@@ -221,10 +265,16 @@ sudo systemctl start tsmusicbot
 
 ### 首次配置
 
-1. 打开 **http://localhost:3000/setup** 进入设置向导
-2. 填写 TeamSpeak 服务器地址（默认端口：9987）
-3. 设置机器人昵称
-4. （可选）扫码登录网易云/QQ音乐账号以播放 VIP 歌曲
+1. 启动机器人后打开 **http://localhost:3000/**
+   - 全新部署：自动跳转 `/first-run`，填写用户名（3-32 字符）和密码（≥8 位）创建首位**管理员**账号
+   - 之后所有 WebUI 操作都需要登录，登录态保持 7 天（活动会滚动续期）
+2. 在 **设置 → 机器人管理** 中点击"创建新实例"，填写：
+   - TeamSpeak 服务器地址（无端口，仅主机名，例如 `ts.example.com`）
+   - 端口（默认 9987，自托管或非标准端口请填写实际值）
+   - 机器人昵称
+   - 可选：服务器密码、默认频道
+3. 在 **设置 → 音乐账号** 扫码登录网易云 / QQ 音乐 / B 站账号（可选，登录后可播放 VIP 歌曲）
+4. 在 **设置 → 用户管理**（仅管理员可见）按需添加成员，成员账号可以控制播放但无法管理其他用户
 
 ### WebUI 页面说明
 
@@ -235,7 +285,7 @@ sudo systemctl start tsmusicbot
 | **歌单** | 查看歌单详情，播放全部（根据当前播放模式选择首歌） |
 | **歌词** | 全屏歌词页，实时同步滚动，模糊专辑封面背景 |
 | **历史** | 播放历史记录 |
-| **设置** | 主题切换、机器人管理、三平台账号登录、音质选择、命令前缀 |
+| **设置** | 账户（修改自己密码） / 主题切换 / 机器人管理 / 三平台账号登录 / 音质选择 / 命令前缀 / 用户管理（仅管理员）/ 操作审计（仅管理员） |
 
 ### TeamSpeak 文字命令
 
@@ -253,6 +303,7 @@ sudo systemctl start tsmusicbot
 | `!stop` | 停止播放并清空队列 |
 | `!vol <0-100>` | 设置音量 |
 | `!queue` | 查看播放队列 |
+| `!remove <位置>` | 从队列中删除指定位置的歌曲（位置从 1 开始，见 `!queue`） |
 | `!mode <seq\|loop\|random\|rloop>` | 切换播放模式 |
 | `!playlist <歌单名或ID>` | 加载歌单（支持名称模糊搜索和 ID） |
 | `!playlist -q <歌单名>` | 从 QQ 音乐搜索并加载歌单 |
@@ -425,6 +476,18 @@ pip install -U yt-dlp
 }
 ```
 
+> **关于 `adminPassword` 和 `adminGroups`**：这两个字段保留是为了兼容旧 `config.json`，但当前版本未使用。WebUI 鉴权改为基于数据库的用户账号系统（见 [首次配置](#首次配置)），无需在 `config.json` 中设置密码。
+
+### 反向代理部署注意事项
+
+当 WebUI 部署在反向代理（nginx / Caddy / Cloudflare 等）之后时，请务必在 `config.json` 中设置 `"trustProxy": true`：
+
+- **Cookie Secure 标志**：未启用 `trustProxy` 时，Express 无法从 `X-Forwarded-Proto` 正确判断请求实际是否为 HTTPS，会话 cookie 不会被标记为 `Secure`。
+- **登录限流**：登录限流以 `req.ip` 为键，未启用 `trustProxy` 时所有请求都会被识别为代理本身的 IP，单个攻击者会拖累所有合法用户共用同一个限流桶。
+- **审计日志的客户端 IP**（如果未来添加该字段）也需要 `trustProxy` 才能正确记录。
+
+直接暴露端口（无代理）时无需启用该选项。
+
 ## 常见问题
 
 **Q：支持 TeamSpeak 6 Server 吗？**
@@ -464,6 +527,21 @@ A：YouTube 是可选音源，需要手动安装 `yt-dlp`。详见 [可选：You
 **Q：如何更新到新版本？**
 A：`git pull` 拉取最新代码，然后 `npm install && npm run build && npm start` 重新构建启动。Docker 用户执行 `docker-compose up -d --build`。
 
+**Q：忘记管理员密码怎么办？**
+A：直接操作 SQLite 数据库。最简单的办法是清空 `users` 表然后重新进入 first-run 流程：`sqlite3 data/tsmusicbot.db "DELETE FROM users; DELETE FROM sessions;"`，重启后浏览器会自动跳转 `/first-run` 让你重新创建管理员。详细方法见 [从 WebUI 无鉴权版本升级](#从-webui-无鉴权版本升级重要)。
+
+**Q：成员（member）能做什么？不能做什么？**
+A：成员可以：管理机器人（启动/停止/创建/编辑）、控制播放（搜索/播放/队列）、登录音乐平台账号、修改自己的密码。成员**不能**：管理其他用户、查看操作审计日志、降级或删除管理员。
+
+**Q：如何把某个用户从成员升级为管理员？**
+A：管理员登录后进入 **设置 → 用户管理**，点击对应用户的"提升管理员"按钮即可。降级同理（"降为成员"按钮）。系统会阻止降级最后一位管理员。
+
+**Q：登录之后多久会自动退出？**
+A：登录态有效期 7 天，活跃使用会滚动续期（每次受保护请求都会刷新过期时间）。同一账号最多保持 10 个并发会话（多设备登录时超过的会自动剔除最旧的会话）。
+
+**Q：部署到公网后如何防止暴力登录？**
+A：本项目内置 `/login` 限流（每 IP 每分钟 5 次），但生产部署建议同时在反向代理（nginx `limit_req` / Caddy 等）层加一层限流，并启用 HTTPS。反向代理部署务必设置 `"trustProxy": true`（详见 [反向代理部署注意事项](#反向代理部署注意事项)）。
+
 ## 参与贡献
 
 1. Fork 本仓库
@@ -478,6 +556,20 @@ A：`git pull` 拉取最新代码，然后 `npm install && npm run build && npm
 
 ### 最新版本
 
+**WebUI 鉴权与权限系统**
+
+- **首次运行强制创建管理员账号**：浏览器打开 WebUI 自动跳转 `/first-run`；之后所有 `/api/*`（除少量公共白名单：`/api/health`、`/api/config/public-url`、`/api/session/*`）和 `/ws` 都需要登录。详见 [更新升级 → 从 WebUI 无鉴权版本升级](#从-webui-无鉴权版本升级重要)。
+- **两种角色：admin / member**。`member` 可以管理机器人、控制播放、登录音乐平台账号、修改自己密码，但不能管理其他用户或查看审计日志。`admin` 拥有全部权限。
+- **用户管理 UI**：管理员在 设置 → 用户管理 可以增删用户、切换角色、重置密码。系统强制保留至少一位管理员。
+- **操作审计日志**：管理员在 设置 → 操作审计 可以查看用户管理相关事件（创建、删除、密码重置、角色变更、首位管理员创建、自助修改密码）。
+- **自助修改密码**：所有用户都可在 设置 → 账户 修改自己密码。
+- **会话存储**：服务端 SQLite 表 `sessions`，存储 sha256(token)；浏览器只持有原始 token cookie。7 天 TTL，每小时滚动续期。同账号最多 10 个并发会话（超出剔除最旧）。
+- **登录限流**：每 IP 每分钟 5 次 `/login` + 3 次 `/setup`，命中返回 429 + `Retry-After`。
+- **CSRF & 安全头**：所有 mutating 请求强制 `Origin`/`Referer` 同源；响应携带 `X-Frame-Options: DENY` 和 `Content-Security-Policy: frame-ancestors 'none'`（防点击劫持）。
+- **配置变更**：反向代理部署务必 `"trustProxy": true`（详见 [反向代理部署注意事项](#反向代理部署注意事项)）。`config.adminPassword` / `adminGroups` 字段保留以兼容旧 `config.json`，但不再影响任何行为。
+
+### v0.x — Bot Profile 自动更新与协议层升级
+
 **机器人形象自动更新（Bot Profile）**
 
 - **播放时自动更新 TS 形象**：头像（专辑封面缩略图）、昵称（`♪ 歌名 - 歌手 - 原昵称`）、描述（歌曲信息）、Away 状态、频道描述、"正在播放"频道消息，全部随歌曲切换自动更新。

docs/superpowers/plans/2026-05-07-album-search-and-playback.md

@@ -0,0 +1,520 @@
+# Album Search & Playback Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Surface albums in search results and allow playing the whole album from the web UI. Currently `SearchResult.albums` is always `[]` and Search.vue only renders songs.
+
+**Architecture:** Extend `search()` in netease + qq providers to populate `albums`. Aggregate them in `/search/all`. Add a new "专辑" (and "歌单") section to Search.vue. Reuse `Playlist.vue` as the album detail page by branching on `route.meta.kind` between `/playlist/:id` and `/album/:id` endpoints. The existing `getAlbumSongs(id)` and `/api/music/album/:id` endpoint already work.
+
+**Tech Stack:** Node 20 + TS, Express 5, Vue 3 + Vue Router 4, axios. No new deps.
+
+---
+
+## Spec Reference
+
+`docs/superpowers/specs/2026-05-07-custom-avatar-and-album-search-design.md` — section "专辑搜索".
+
+## File Structure
+
+| File | Action | Responsibility |
+|---|---|---|
+| `src/music/provider.ts` | Read-only | Verify `Album` and `SearchResult.albums` shape (no change expected) |
+| `src/music/netease.ts` | Modify | `search()` adds a third parallel call (`type=10`) and maps albums |
+| `src/music/qq.ts` | Modify | `search()` adds `req_album` section and maps albums |
+| `src/music/netease.test.ts` | Modify | New tests for albums in search response |
+| `src/music/qq.test.ts` | Modify (or create if absent) | Tests for albums in qq search |
+| `src/web/api/music.ts` | Modify | `/search/all` returns `{songs, albums, playlists}` |
+| `web/src/views/Search.vue` | Modify | Render albums + playlists sections |
+| `web/src/views/Playlist.vue` | Modify | Branch endpoint by `route.meta.kind === 'album'` |
+| `web/src/router/index.ts` | Modify | Add `/album/:id` route reusing Playlist component, set `meta.kind = 'album'` |
+
+## Conventions
+
+- TDD throughout. Each task: failing test → implement → verify → commit.
+- Mock HTTP via existing fixtures pattern (look at `src/music/netease.test.ts` for setup).
+- Keep all platform-specific quirks inside the provider class — no leaking into Search.vue logic.
+
+---
+
+### Task 1: netease.ts — fetch albums in search
+
+**Files:**
+- Modify: `src/music/netease.ts`
+- Modify: `src/music/netease.test.ts`
+
+- [ ] **Step 1: Read the existing test setup so we mock the same way**
+
+```bash
+grep -n 'cloudsearch\|MockAdapter\|axios.create\|mock\|nock\|fixture' src/music/netease.test.ts | head -20
+```
+
+- [ ] **Step 2: Write the failing test**
+
+Append to `src/music/netease.test.ts` inside the existing `describe`:
+
+```ts
+  it("populates SearchResult.albums from cloudsearch type=10", async () => {
+    // Adjust the fixture/mock helper to your existing test pattern.
+    // The test should: arrange a mock that returns a non-empty albums array
+    // for type=10, run search(), assert result.albums has the expected shape.
+    mockApi.onGet("/cloudsearch", { params: expect.objectContaining({ type: 10 }) }).reply(200, {
+      result: {
+        albums: [
+          { id: 42, name: "Album A", picUrl: "https://x/p.jpg", artists: [{ name: "Artist X" }] },
+        ],
+      },
+    });
+    mockApi.onGet("/cloudsearch", { params: expect.objectContaining({ type: 1 }) }).reply(200, { result: { songs: [] } });
+    mockApi.onGet("/cloudsearch", { params: expect.objectContaining({ type: 1000 }) }).reply(200, { result: { playlists: [] } });
+
+    const provider = makeProvider();
+    const r = await provider.search("foo", 5);
+    expect(r.albums).toEqual([
+      { id: "42", name: "Album A", artist: "Artist X", coverUrl: "https://x/p.jpg", platform: "netease" },
+    ]);
+  });
+```
+
+If the existing tests use a different mock library (e.g. `msw` or manual axios stubbing), translate the fixture above to match. Do not introduce new test deps.
+
+- [ ] **Step 3: Run test to verify it fails**
+
+Run: `npx vitest run src/music/netease.test.ts`
+Expected: FAIL — `result.albums` is `[]`
+
+- [ ] **Step 4: Implement the change**
+
+In `src/music/netease.ts` `search()` (~line 93), change the `Promise.all` from 2 to 3 calls:
+
+```ts
+const [songRes, playlistRes, albumRes] = await Promise.all([
+  this.api.get("/cloudsearch", { params: { keywords: query, type: 1, limit, ...this.cookieParams } }),
+  this.api.get("/cloudsearch", { params: { keywords: query, type: 1000, limit: 5, ...this.cookieParams } }),
+  this.api.get("/cloudsearch", { params: { keywords: query, type: 10, limit: 5, ...this.cookieParams } }),
+]);
+```
+
+After the existing `playlists: Playlist[] = ...` mapping, add:
+
+```ts
+const albums: Album[] = (albumRes.data?.result?.albums ?? []).map((a: any) => ({
+  id: String(a.id),
+  name: a.name ?? "",
+  artist: (a.artists ?? []).map((x: any) => x.name).join(" / "),
+  coverUrl: a.picUrl ?? "",
+  platform: "netease",
+}));
+```
+
+Update the `return { songs, playlists, albums: [] }` to `return { songs, playlists, albums }`.
+
+(Make sure `Album` is imported from `./provider.js`; if not yet imported, add it to the existing import.)
+
+- [ ] **Step 5: Run test to verify it passes**
+
+Run: `npx vitest run src/music/netease.test.ts`
+Expected: PASS
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add src/music/netease.ts src/music/netease.test.ts
+git commit -m "feat(netease): include albums in search results"
+```
+
+---
+
+### Task 2: qq.ts — fetch albums in search
+
+**Files:**
+- Modify: `src/music/qq.ts`
+- Modify or Create: `src/music/qq.test.ts`
+
+- [ ] **Step 1: Verify whether qq.test.ts exists**
+
+```bash
+ls src/music/qq.test.ts
+```
+
+If absent, create a minimal one mirroring `netease.test.ts` style: instantiate provider, mock the `qqDirectApi` axios instance, assert `r.albums.length > 0` after a `search()` call.
+
+- [ ] **Step 2: Write the failing test**
+
+Add to `src/music/qq.test.ts`:
+
+```ts
+it("populates SearchResult.albums from a parallel album search request", async () => {
+  // Mock returns an album list under req_album.data.body.album.list
+  mockApi.onGet("/cgi-bin/musicu.fcg").reply((cfg) => {
+    const data = JSON.parse(cfg.params?.data ?? "{}");
+    if (data.req_album) {
+      return [200, { req_album: { data: { body: { album: { list: [
+        { albumMID: "abc", albumName: "Aero", singerName: "S", albumPic: "https://x/p.jpg" },
+      ] } } } } }];
+    }
+    if (data.req_0) {
+      return [200, { req_0: { data: { body: { song: { list: [] } } } } }];
+    }
+    return [200, {}];
+  });
+
+  const provider = makeProvider();
+  const r = await provider.search("foo", 5);
+  expect(r.albums).toEqual([
+    { id: "abc", name: "Aero", artist: "S", coverUrl: expect.stringContaining("https://"), platform: "qq" },
+  ]);
+});
+```
+
+Verify the actual QQ API response shape against a real call before finalizing the field names — `albumMID` vs `mid`, `albumPic` vs `pic`, etc. If unsure, log a real response once and freeze the shape in the fixture.
+
+- [ ] **Step 3: Run test to verify it fails**
+
+Run: `npx vitest run src/music/qq.test.ts`
+Expected: FAIL — `r.albums` is `[]`
+
+- [ ] **Step 4: Implement the change**
+
+In `src/music/qq.ts` `search()` (~line 63), change `reqData` to include both `req_0` (songs) and `req_album` (albums):
+
+```ts
+const reqData = JSON.stringify({
+  req_0: {
+    module: "music.search.SearchCgiService",
+    method: "DoSearchForQQMusicDesktop",
+    param: { searchid: "1", query, num_per_page: Math.min(limit, 50), search_type: 0 },
+  },
+  req_album: {
+    module: "music.search.SearchCgiService",
+    method: "DoSearchForQQMusicDesktop",
+    param: { searchid: "1", query, num_per_page: 5, search_type: 8 },
+  },
+});
+```
+
+After the existing `songs` mapping, add:
+
+```ts
+const albumList: any[] = res.data?.req_album?.data?.body?.album?.list ?? [];
+const albums: Album[] = albumList.map((a: any) => ({
+  id: String(a.albumMID ?? a.mid ?? a.albumID ?? ""),
+  name: a.albumName ?? a.title ?? "",
+  artist: a.singerName ?? (a.singer ?? []).map((s: any) => s.name).join(" / "),
+  coverUrl: a.albumMID
+    ? `https://y.gtimg.cn/music/photo_new/T002R300x300M000${a.albumMID}.jpg`
+    : (a.albumPic ?? ""),
+  platform: "qq",
+}));
+```
+
+Change `return { songs, playlists: [], albums: [] }` to `return { songs, playlists: [], albums }`.
+
+- [ ] **Step 5: Run test to verify it passes**
+
+Run: `npx vitest run src/music/qq.test.ts`
+Expected: PASS
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add src/music/qq.ts src/music/qq.test.ts
+git commit -m "feat(qq): include albums in search results"
+```
+
+---
+
+### Task 3: /search/all — aggregate albums + playlists
+
+**Files:**
+- Modify: `src/web/api/music.ts`
+
+- [ ] **Step 1: Look at the current aggregation**
+
+In `src/web/api/music.ts` near line 40 the `/search/all` handler builds only `songs`. Extend it.
+
+- [ ] **Step 2: Write a failing integration test (if test infra allows)**
+
+If there's already a test file for music.ts, add a test that mocks the providers and asserts `res.body.albums.length > 0`. If not, skip and rely on Task 1+2 unit coverage + manual verification in Task 4.
+
+- [ ] **Step 3: Aggregate albums + playlists**
+
+Replace the existing `songs = ...` block + `res.json({ songs })` at lines ~54–62 with:
+
+```ts
+const songs = [
+  ...(neteaseResult.status === "fulfilled" ? neteaseResult.value.songs : []),
+  ...(qqResult.status === "fulfilled" ? qqResult.value.songs : []),
+  ...(bilibiliResult.status === "fulfilled" ? bilibiliResult.value.songs : []),
+];
+const albums = [
+  ...(neteaseResult.status === "fulfilled" ? neteaseResult.value.albums : []),
+  ...(qqResult.status === "fulfilled" ? qqResult.value.albums : []),
+];
+const playlists = [
+  ...(neteaseResult.status === "fulfilled" ? neteaseResult.value.playlists : []),
+  ...(qqResult.status === "fulfilled" ? qqResult.value.playlists : []),
+];
+
+res.json({ songs, albums, playlists });
+```
+
+(Bilibili intentionally skipped for albums/playlists — no album concept; playlists likewise minor.)
+
+- [ ] **Step 4: Verify by curl**
+
+Build + run, then:
+
+```bash
+curl -s 'http://localhost:3000/api/music/search/all?q=Beyond' \
+  | python3 -c 'import json,sys;d=json.load(sys.stdin);print({k: len(v) for k, v in d.items()})'
+```
+
+Expected: `{'songs': N>0, 'albums': N>0, 'playlists': N>=0}`
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add src/web/api/music.ts
+git commit -m "feat(api): /search/all returns albums and playlists"
+```
+
+---
+
+### Task 4: Album route reusing Playlist.vue
+
+**Files:**
+- Modify: `web/src/router/index.ts`
+- Modify: `web/src/views/Playlist.vue`
+
+- [ ] **Step 1: Look at the current router config and Playlist load logic**
+
+```bash
+grep -n "path:\|component:\|meta" web/src/router/index.ts
+grep -n "loadPlaylist\|/api/music/playlist\|onMounted" web/src/views/Playlist.vue
+```
+
+- [ ] **Step 2: Add /album/:id route**
+
+In `web/src/router/index.ts`, find the `/playlist/:id` route entry. Right after it, add:
+
+```ts
+  {
+    path: '/album/:id',
+    component: () => import('../views/Playlist.vue'),
+    meta: { kind: 'album' },
+  },
+```
+
+(If `/playlist/:id` is `meta:`-less, also add `meta: { kind: 'playlist' }` to it for symmetry.)
+
+- [ ] **Step 3: Branch the endpoint inside Playlist.vue**
+
+Find the load function (probably `onMounted(async () => { axios.get('/api/music/playlist/' + id, ...) })`). Refactor:
+
+```ts
+const route = useRoute();
+const kind = (route.meta.kind as string) ?? 'playlist'; // 'playlist' | 'album'
+const endpoint = kind === 'album' ? '/api/music/album/' : '/api/music/playlist/';
+// ... use `${endpoint}${route.params.id}` ...
+```
+
+For the hero metadata, the playlist endpoint returns `{songs}` only (no top-level cover/title) — verify what the Album endpoint currently returns. If both only return `{songs}`, the existing Playlist.vue must already derive the cover from somewhere (probably the first song's coverUrl, or an additional `/api/music/playlist/:id/detail` call). Keep the existing pattern; if a separate detail call is needed for albums, fetch the metadata from `/api/music/song/<firstSong.id>` to get the album name + cover, OR add a thin `/api/music/album/:id/detail` endpoint that returns `{ name, coverUrl, description }`.
+
+**Decision:** if Playlist.vue currently uses ONLY `/api/music/playlist/:id` and derives metadata from songs, do the same for albums (no new endpoint). If it calls a separate detail endpoint, add a matching `/api/music/album/:id/detail` returning `{ name, coverUrl }` from the first song's `album` and `coverUrl` fields.
+
+- [ ] **Step 4: Verify in browser**
+
+Run `cd web && npm run dev`. Visit `/album/<some-netease-album-id>` (pick one from a search). Expect: hero header + song list + play-all button — same UX as a playlist page.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add web/src/router/index.ts web/src/views/Playlist.vue
+git commit -m "feat(web): /album/:id route reusing Playlist view"
+```
+
+---
+
+### Task 5: Search.vue — render albums + playlists sections
+
+**Files:**
+- Modify: `web/src/views/Search.vue`
+
+- [ ] **Step 1: Read current Search.vue**
+
+```bash
+sed -n '1,120p' web/src/views/Search.vue
+```
+
+Identify: the `results.value = res.data.songs` line and the `<div v-else-if="results.length > 0">` block.
+
+- [ ] **Step 2: Refactor to three result lists**
+
+Replace the script:
+
+```ts
+import type { Song } from '../stores/player.js';
+
+interface Album { id: string; name: string; artist: string; coverUrl: string; platform: string; }
+interface Playlist { id: string; name: string; coverUrl: string; songCount?: number; platform: string; }
+
+const songs = ref<Song[]>([]);
+const albums = ref<Album[]>([]);
+const playlists = ref<Playlist[]>([]);
+const loading = ref(false);
+const searched = ref(false);
+
+async function doSearch() {
+  if (!query.value.trim()) return;
+  loading.value = true;
+  searched.value = true;
+  try {
+    const res = await axios.get('/api/music/search/all', { params: { q: query.value } });
+    songs.value = res.data.songs ?? [];
+    albums.value = res.data.albums ?? [];
+    playlists.value = res.data.playlists ?? [];
+  } catch {
+    songs.value = []; albums.value = []; playlists.value = [];
+  } finally {
+    loading.value = false;
+  }
+}
+```
+
+- [ ] **Step 3: Render the sections**
+
+Replace the existing `<div v-else-if="results.length > 0" class="results">` block:
+
+```vue
+    <template v-else-if="songs.length || albums.length || playlists.length">
+      <section v-if="albums.length" class="result-section">
+        <h2 class="section-title">专辑</h2>
+        <div class="card-grid">
+          <router-link
+            v-for="al in albums"
+            :key="`${al.platform}-${al.id}`"
+            :to="`/album/${al.id}?platform=${al.platform}`"
+            class="card hover-scale"
+          >
+            <CoverArt :url="al.coverUrl" :size="160" :radius="10" :show-shadow="true" />
+            <div class="card-name">{{ al.name }}</div>
+            <div class="card-sub">{{ al.artist }}</div>
+          </router-link>
+        </div>
+      </section>
+
+      <section v-if="playlists.length" class="result-section">
+        <h2 class="section-title">歌单</h2>
+        <div class="card-grid">
+          <router-link
+            v-for="pl in playlists"
+            :key="`${pl.platform}-${pl.id}`"
+            :to="`/playlist/${pl.id}?platform=${pl.platform}`"
+            class="card hover-scale"
+          >
+            <CoverArt :url="pl.coverUrl" :size="160" :radius="10" :show-shadow="true" />
+            <div class="card-name">{{ pl.name }}</div>
+          </router-link>
+        </div>
+      </section>
+
+      <section v-if="songs.length" class="result-section">
+        <h2 class="section-title">单曲</h2>
+        <SongCard
+          v-for="(song, i) in songs"
+          :key="`${song.platform}-${song.id}`"
+          :song="song"
+          :index="i + 1"
+          :active="store.currentSong?.id === song.id"
+          @play="store.playSong(song)"
+          @playNext="store.playNextSong(song)"
+          @add="store.addSong(song)"
+        />
+      </section>
+    </template>
+
+    <div v-else-if="searched" class="empty">未找到相关结果</div>
+```
+
+(Import `CoverArt`: `import CoverArt from '../components/CoverArt.vue';`.)
+
+- [ ] **Step 4: Add minimal styles**
+
+Append to the `<style lang="scss" scoped>` block:
+
+```scss
+.result-section {
+  margin-bottom: 32px;
+  .section-title { font-size: 18px; margin: 0 0 12px; opacity: 0.85; }
+}
+.card-grid {
+  display: grid;
+  grid-template-columns: repeat(auto-fill, minmax(140px, 1fr));
+  gap: 16px;
+}
+.card {
+  display: flex;
+  flex-direction: column;
+  gap: 6px;
+  text-decoration: none;
+  color: inherit;
+  .card-name { font-size: 14px; line-height: 1.3; max-height: 2.6em; overflow: hidden; }
+  .card-sub  { font-size: 12px; opacity: 0.6; }
+}
+```
+
+- [ ] **Step 5: Build + visually verify**
+
+```bash
+cd web && npm run build
+```
+
+Then `npm run dev` → search "周杰伦" → see three sections; click an album card → arrives at `/album/:id` with songs + play-all.
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add web/src/views/Search.vue
+git commit -m "feat(web): show album + playlist sections in search"
+```
+
+---
+
+### Task 6: Open PR
+
+- [ ] **Step 1: Push branch**
+
+```bash
+git checkout -b feat/album-search
+git push -u origin feat/album-search
+```
+
+- [ ] **Step 2: Create the PR**
+
+```bash
+gh pr create --title "feat(search): album section + album playback" --body "Closes part of #51 (album half).
+
+## Summary
+- netease.search() / qq.search() now populate SearchResult.albums
+- /api/music/search/all returns albums + playlists alongside songs
+- Search.vue renders three sections: 专辑 / 歌单 / 单曲
+- /album/:id route reuses Playlist.vue with meta.kind='album'
+- bilibili / youtube intentionally still return albums:[] (no album API)
+
+## Test plan
+- [x] vitest covers netease + qq search returning non-empty albums
+- [x] curl /search/all?q=周杰伦 returns {songs, albums, playlists}
+- [x] Manual: search → click album card → /album/:id → play all
+
+🤖 Generated with [Claude Code](https://claude.com/claude-code)"
+```
+
+---
+
+## Self-Review Checklist
+
+- [x] Spec coverage: backend album search → Tasks 1+2; aggregator → Task 3; album detail route → Task 4; UI sections → Task 5
+- [x] No "TBD"/placeholder text — every step shows the actual diff or command
+- [x] Type names consistent: `Album` (capital A), `albums` (lowercase plural), `SearchResult.albums`
+- [x] Bilibili/YouTube explicitly out of scope per spec — confirmed in Task 3 by skipping them in albums aggregation
+- [x] Routes use `meta.kind` — same key referenced in Playlist.vue (Task 4) and `/album/:id` registration (Task 4 Step 2)

docs/superpowers/plans/2026-05-07-custom-bot-avatar.md

@@ -0,0 +1,903 @@
+# Custom Bot Avatar Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Let users upload a fixed avatar per bot. When `avatarEnabled=true`, the avatar follows the song cover during playback and reverts to the custom avatar (instead of clearing) on stop. When `avatarEnabled=false` and a custom avatar exists, the bot always shows the custom avatar.
+
+**Architecture:** New SQLite column stores a relative file path; bytes live on disk under `data/avatars/<botId>.<ext>` (mirrors `data/cookies/`). `BotProfileManager` gains a `customAvatar` Buffer; the existing `clearAvatar()` becomes "restore custom or clear"; `onConnect()` immediately applies the custom avatar when sync is off. Three new REST endpoints (GET/PUT/DELETE) under `/api/bot/:id/avatar` accept base64 JSON (avoids adding multer; bump `express.json()` limit).
+
+**Tech Stack:** Node 20 + TS + Express 5, better-sqlite3, Vue 3 + axios. No new runtime deps.
+
+---
+
+## Spec Reference
+
+`docs/superpowers/specs/2026-05-07-custom-avatar-and-album-search-design.md` — section "自定义头像".
+
+## File Structure
+
+| File | Action | Responsibility |
+|---|---|---|
+| `src/data/database.ts` | Modify | Add `custom_avatar_path` column + migration + accessor methods |
+| `src/data/avatars.ts` | **Create** | Read/write/delete avatar files under `data/avatars/` |
+| `src/bot/profile.ts` | Modify | `customAvatar` field, `setCustomAvatar`, `applyIdleAvatar`, modify `clearAvatar`, modify `onConnect` |
+| `src/bot/instance.ts` | Modify | Load custom avatar on start, pass to ProfileManager |
+| `src/web/api/bot.ts` | Modify | Add GET/PUT/DELETE `/avatar` endpoints |
+| `src/web/server.ts` | Modify | Bump `express.json()` limit to `400kb` |
+| `src/index.ts` | Modify | Pass `AVATAR_DIR` to bot manager / API router |
+| `src/data/database.test.ts` | Modify | Test custom avatar path persistence + migration idempotency |
+| `src/data/avatars.test.ts` | **Create** | Unit tests for avatar store |
+| `src/bot/profile.test.ts` | **Create** | Tests for new precedence logic with a mock TS3Client |
+| `web/src/components/AvatarUpload.vue` | **Create** | Reusable avatar picker + preview + delete |
+| `web/src/views/Settings.vue` | Modify | Add custom avatar row in profile features list; insert into create-bot and edit-bot forms |
+
+## Conventions
+
+- TDD: failing test → implement → verify → commit, every step.
+- Commits use conventional format: `feat(profile):`, `feat(api):`, `feat(web):`, `test(...)`. Each task ends with one commit.
+- Tests live in vitest (`npm test`).
+- All paths absolute or relative to repo root.
+
+---
+
+### Task 1: DB migration + getter/setter for custom avatar path
+
+**Files:**
+- Modify: `src/data/database.ts`
+- Modify: `src/data/database.test.ts`
+
+- [ ] **Step 1: Write the failing test**
+
+Add to `src/data/database.test.ts` after the existing tests (find the closing `});` of the last test case in the `describe` block, insert before it):
+
+```ts
+  it("persists and clears customAvatarPath on a bot instance", () => {
+    const inst = {
+      id: "bot-1",
+      name: "B",
+      serverAddress: "x",
+      serverPort: 9987,
+      nickname: "n",
+      defaultChannel: "",
+      channelPassword: "",
+      autoStart: false,
+      serverProtocol: "",
+      ts6ApiKey: "",
+      serverPassword: "",
+    };
+    botDb.saveBotInstance(inst);
+    expect(botDb.getCustomAvatarPath("bot-1")).toBeNull();
+    botDb.setCustomAvatarPath("bot-1", "avatars/bot-1.png");
+    expect(botDb.getCustomAvatarPath("bot-1")).toBe("avatars/bot-1.png");
+    botDb.setCustomAvatarPath("bot-1", null);
+    expect(botDb.getCustomAvatarPath("bot-1")).toBeNull();
+  });
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `npx vitest run src/data/database.test.ts`
+Expected: FAIL — `botDb.getCustomAvatarPath is not a function`
+
+- [ ] **Step 3: Add the column to migration + interface + statements**
+
+In `src/data/database.ts`:
+
+1. Find `BotDatabase` interface (~line 54), add two methods before `close()`:
+
+```ts
+  getCustomAvatarPath(botId: string): string | null;
+  setCustomAvatarPath(botId: string, path: string | null): void;
+```
+
+2. Find `migrateSchema()` (~line 66). After the `for (const col of profileCols)` loop, append:
+
+```ts
+  if (!names.includes("custom_avatar_path")) {
+    db.exec("ALTER TABLE bot_instances ADD COLUMN custom_avatar_path TEXT");
+  }
+```
+
+3. In `createDatabase()` after the existing `prepare(...)` calls (~line 180), add:
+
+```ts
+  const selectCustomAvatar = db.prepare(
+    `SELECT custom_avatar_path FROM bot_instances WHERE id = ?`,
+  );
+  const updateCustomAvatar = db.prepare(
+    `UPDATE bot_instances SET custom_avatar_path = ? WHERE id = ?`,
+  );
+```
+
+4. Inside the returned object, add (before `close()`):
+
+```ts
+    getCustomAvatarPath(botId) {
+      const row = selectCustomAvatar.get(botId) as { custom_avatar_path: string | null } | undefined;
+      return row?.custom_avatar_path ?? null;
+    },
+
+    setCustomAvatarPath(botId, path) {
+      updateCustomAvatar.run(path, botId);
+    },
+```
+
+- [ ] **Step 4: Run test to verify it passes**
+
+Run: `npx vitest run src/data/database.test.ts`
+Expected: PASS — all tests including the new one
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add src/data/database.ts src/data/database.test.ts
+git commit -m "feat(db): custom_avatar_path column + accessors"
+```
+
+---
+
+### Task 2: Avatar storage helper
+
+**Files:**
+- Create: `src/data/avatars.ts`
+- Create: `src/data/avatars.test.ts`
+
+- [ ] **Step 1: Write the failing test**
+
+Create `src/data/avatars.test.ts`:
+
+```ts
+import { describe, it, expect, beforeEach } from "vitest";
+import { mkdtempSync, rmSync, existsSync, readFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { createAvatarStore } from "./avatars.js";
+
+let dir: string;
+
+beforeEach(() => {
+  dir = mkdtempSync(join(tmpdir(), "avatar-test-"));
+});
+
+describe("createAvatarStore", () => {
+  it("write returns a relative path under the store dir", () => {
+    const store = createAvatarStore(dir);
+    const buf = Buffer.from("fake-png");
+    const rel = store.write("bot-1", "image/png", buf);
+    expect(rel).toBe("bot-1.png");
+    expect(readFileSync(join(dir, "bot-1.png")).equals(buf)).toBe(true);
+  });
+
+  it("write picks correct extension for jpeg / webp", () => {
+    const store = createAvatarStore(dir);
+    expect(store.write("a", "image/jpeg", Buffer.from(""))).toBe("a.jpg");
+    expect(store.write("b", "image/webp", Buffer.from(""))).toBe("b.webp");
+  });
+
+  it("write rejects unsupported MIME types", () => {
+    const store = createAvatarStore(dir);
+    expect(() => store.write("c", "image/gif", Buffer.from(""))).toThrow(
+      /unsupported/i,
+    );
+  });
+
+  it("read returns the bytes for an existing file", () => {
+    const store = createAvatarStore(dir);
+    store.write("bot-1", "image/png", Buffer.from("hello"));
+    const buf = store.read("bot-1.png");
+    expect(buf?.equals(Buffer.from("hello"))).toBe(true);
+  });
+
+  it("read returns null when path is missing", () => {
+    const store = createAvatarStore(dir);
+    expect(store.read("missing.png")).toBeNull();
+  });
+
+  it("remove deletes the file (idempotent)", () => {
+    const store = createAvatarStore(dir);
+    store.write("bot-1", "image/png", Buffer.from("x"));
+    store.remove("bot-1.png");
+    expect(existsSync(join(dir, "bot-1.png"))).toBe(false);
+    expect(() => store.remove("bot-1.png")).not.toThrow();
+  });
+
+  it("write replaces any existing file for the same botId regardless of old extension", () => {
+    const store = createAvatarStore(dir);
+    store.write("bot-1", "image/png", Buffer.from("old"));
+    const rel = store.write("bot-1", "image/jpeg", Buffer.from("new"));
+    expect(rel).toBe("bot-1.jpg");
+    expect(existsSync(join(dir, "bot-1.png"))).toBe(false);
+    expect(existsSync(join(dir, "bot-1.jpg"))).toBe(true);
+  });
+});
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `npx vitest run src/data/avatars.test.ts`
+Expected: FAIL — module not found
+
+- [ ] **Step 3: Implement the store**
+
+Create `src/data/avatars.ts`:
+
+```ts
+import { mkdirSync, writeFileSync, readFileSync, rmSync, readdirSync, existsSync } from "node:fs";
+import { join } from "node:path";
+
+const MIME_TO_EXT: Record<string, string> = {
+  "image/png": "png",
+  "image/jpeg": "jpg",
+  "image/webp": "webp",
+};
+
+export interface AvatarStore {
+  /** Returns the relative path written (e.g. "bot-1.png"). */
+  write(botId: string, mime: string, buffer: Buffer): string;
+  read(relPath: string): Buffer | null;
+  remove(relPath: string): void;
+  getDir(): string;
+}
+
+export function createAvatarStore(dir: string): AvatarStore {
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+  return {
+    write(botId, mime, buffer) {
+      const ext = MIME_TO_EXT[mime];
+      if (!ext) throw new Error(`unsupported avatar MIME: ${mime}`);
+      // Remove any existing avatar for this bot regardless of extension.
+      for (const name of readdirSync(dir)) {
+        if (name.startsWith(`${botId}.`)) rmSync(join(dir, name), { force: true });
+      }
+      const rel = `${botId}.${ext}`;
+      writeFileSync(join(dir, rel), buffer);
+      return rel;
+    },
+    read(relPath) {
+      const full = join(dir, relPath);
+      if (!existsSync(full)) return null;
+      return readFileSync(full);
+    },
+    remove(relPath) {
+      rmSync(join(dir, relPath), { force: true });
+    },
+    getDir() {
+      return dir;
+    },
+  };
+}
+```
+
+- [ ] **Step 4: Run test to verify it passes**
+
+Run: `npx vitest run src/data/avatars.test.ts`
+Expected: PASS — all 7 tests
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add src/data/avatars.ts src/data/avatars.test.ts
+git commit -m "feat(data): avatar file store helper"
+```
+
+---
+
+### Task 3: BotProfileManager — custom avatar precedence
+
+**Files:**
+- Modify: `src/bot/profile.ts`
+- Create: `src/bot/profile.test.ts`
+
+- [ ] **Step 1: Write the failing test**
+
+Create `src/bot/profile.test.ts`:
+
+```ts
+import { describe, it, expect, beforeEach, vi } from "vitest";
+import { BotProfileManager } from "./profile.js";
+import type { TS3Client } from "../ts-protocol/client.js";
+
+function makeMockTs(): TS3Client & {
+  uploadCalls: Buffer[];
+  clearCalls: number;
+} {
+  const calls: Buffer[] = [];
+  let clears = 0;
+  const ts: any = {
+    uploadCalls: calls,
+    get clearCalls() { return clears; },
+    getHost: () => "127.0.0.1",
+    getHttpQuery: () => null,
+    fileTransferInitUpload: vi.fn().mockResolvedValue({}),
+    uploadFileData: vi.fn().mockImplementation(async (_h, _i, stream: any) => {
+      const chunks: Buffer[] = [];
+      for await (const c of stream) chunks.push(c as Buffer);
+      calls.push(Buffer.concat(chunks));
+    }),
+    fileTransferDeleteFile: vi.fn().mockResolvedValue(undefined),
+    sendCommandNoWait: vi.fn().mockImplementation(async (cmd: string) => {
+      if (/client_flag_avatar=$/.test(cmd)) clears++;
+    }),
+  };
+  return ts;
+}
+
+const noopLogger: any = { child: () => noopLogger, info: () => {}, debug: () => {}, warn: () => {}, error: () => {} };
+
+const cfgOn = { avatarEnabled: true, descriptionEnabled: false, nicknameEnabled: false, awayStatusEnabled: false, channelDescEnabled: false, nowPlayingMsgEnabled: false };
+const cfgOff = { ...cfgOn, avatarEnabled: false };
+
+describe("BotProfileManager custom avatar precedence", () => {
+  let ts: ReturnType<typeof makeMockTs>;
+  beforeEach(() => { ts = makeMockTs(); });
+
+  it("on stop with custom avatar set + sync on, uploads custom (does not clear)", async () => {
+    const pm = new BotProfileManager(ts as any, noopLogger, cfgOn, "Bot");
+    const custom = Buffer.from([1, 2, 3, 4]);
+    pm.setCustomAvatar(custom);
+    await pm.onSongChange(null);
+    expect(ts.uploadCalls.at(-1)?.equals(custom)).toBe(true);
+    expect(ts.clearCalls).toBe(0);
+  });
+
+  it("on stop with no custom avatar, falls back to clear", async () => {
+    const pm = new BotProfileManager(ts as any, noopLogger, cfgOn, "Bot");
+    await pm.onSongChange(null);
+    expect(ts.clearCalls).toBe(1);
+    expect(ts.uploadCalls.length).toBe(0);
+  });
+
+  it("on connect with sync off + custom avatar set, applies custom immediately", async () => {
+    const pm = new BotProfileManager(ts as any, noopLogger, cfgOff, "Bot");
+    pm.setCustomAvatar(Buffer.from([9, 9]));
+    await pm.onConnect();
+    expect(ts.uploadCalls.length).toBe(1);
+    expect(ts.uploadCalls[0].equals(Buffer.from([9, 9]))).toBe(true);
+  });
+
+  it("on connect with sync off + no custom avatar, does not touch avatar", async () => {
+    const pm = new BotProfileManager(ts as any, noopLogger, cfgOff, "Bot");
+    await pm.onConnect();
+    expect(ts.uploadCalls.length).toBe(0);
+    expect(ts.clearCalls).toBe(0);
+  });
+
+  it("setCustomAvatar(null) makes subsequent onSongChange(null) clear again", async () => {
+    const pm = new BotProfileManager(ts as any, noopLogger, cfgOn, "Bot");
+    pm.setCustomAvatar(Buffer.from([1]));
+    pm.setCustomAvatar(null);
+    await pm.onSongChange(null);
+    expect(ts.clearCalls).toBe(1);
+  });
+});
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `npx vitest run src/bot/profile.test.ts`
+Expected: FAIL — `pm.setCustomAvatar is not a function` and/or `onConnect` not exported
+
+- [ ] **Step 3: Look at the existing profile.ts to understand `onConnect` shape**
+
+Run: `grep -n 'onConnect\|public async\|public ' src/bot/profile.ts | head -10`
+
+`onConnect` likely already exists; if not, locate where reconnect resets state. Add or extend it.
+
+- [ ] **Step 4: Implement `customAvatar`, `setCustomAvatar`, `applyIdleAvatar`; modify `clearAvatar` and `onConnect`**
+
+In `src/bot/profile.ts`:
+
+1. Inside the class, add fields next to `defaultNickname` (around line 27):
+
+```ts
+  private customAvatar: Buffer | null = null;
+```
+
+2. After the `constructor`, add:
+
+```ts
+  /** Set/clear the persistent idle avatar. Pass null to remove. */
+  setCustomAvatar(buffer: Buffer | null): void {
+    this.customAvatar = buffer;
+  }
+```
+
+3. Find `clearAvatar()` (~line 173). Change the body so that if `this.customAvatar` is set, we upload it instead of clearing the flag. Replace the existing method with:
+
+```ts
+  private async clearAvatar(gen: number): Promise<void> {
+    if (this.customAvatar && this.customAvatar.length > 0) {
+      await this.applyIdleAvatar(gen);
+      return;
+    }
+    try {
+      await this.withTimeout(
+        this.tsClient.fileTransferDeleteFile(0n, ["/avatar"]),
+        FILE_TRANSFER_TIMEOUT_MS,
+      );
+    } catch {
+      // File may not exist or transfer timed out — that's fine
+    }
+    if (this.generation !== gen) return;
+    try {
+      await this.tsClient.sendCommandNoWait("clientupdate client_flag_avatar=");
+    } catch (err) {
+      this.handleFeatureError("avatar", err);
+    }
+  }
+```
+
+4. Add a new private method right below `clearAvatar`:
+
+```ts
+  private async applyIdleAvatar(gen: number): Promise<void> {
+    if (!this.customAvatar || this.customAvatar.length === 0) return;
+    if (this.permDenied.avatar) return;
+    try {
+      await this.withTimeout(this.doAvatarUpload(this.customAvatar), FILE_TRANSFER_TIMEOUT_MS);
+      if (this.generation !== gen) return;
+      this.logger.info({ bytes: this.customAvatar.length }, "Idle (custom) avatar applied");
+    } catch (err) {
+      this.handleFeatureError("avatar", err);
+    }
+  }
+```
+
+5. Find `onConnect` (the existing method that resets per-feature flags). At its end, immediately after the `permDenied` reset, add:
+
+```ts
+    if (!this.config.avatarEnabled && this.customAvatar) {
+      const gen = ++this.generation;
+      void this.applyIdleAvatar(gen);
+    }
+```
+
+If `onConnect` does not exist as a method, search for where reconnect resets `permDenied` and add the block there.
+
+- [ ] **Step 5: Run test to verify it passes**
+
+Run: `npx vitest run src/bot/profile.test.ts`
+Expected: PASS — 5/5
+
+Run also: `npx vitest run src/audio src/data src/bot` — confirm no regressions.
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add src/bot/profile.ts src/bot/profile.test.ts
+git commit -m "feat(profile): custom avatar with idle/playback precedence"
+```
+
+---
+
+### Task 4: Wire avatar load on bot start
+
+**Files:**
+- Modify: `src/bot/instance.ts`
+- Modify: `src/bot/manager.ts` (if it constructs the instance)
+- Modify: `src/index.ts`
+
+- [ ] **Step 1: Confirm where `BotProfileManager` is constructed and how `BotInstance` receives DB**
+
+Run: `grep -n 'new BotProfileManager\|profileManager =\|database\|botDb' src/bot/instance.ts src/bot/manager.ts | head -20`
+
+Identify the BotInstance constructor params and verify that the DB and the avatar dir can flow in.
+
+- [ ] **Step 2: Add `AVATAR_DIR` constant + `avatarStore` to `src/index.ts`**
+
+Find where `COOKIE_DIR` / `createCookieStore` are set up (~line 48 in src/index.ts) and add directly after:
+
+```ts
+const AVATAR_DIR = process.env.AVATAR_DIR ?? join(DATA_DIR, "avatars");
+const avatarStore = createAvatarStore(AVATAR_DIR);
+```
+
+(import as needed: `import { createAvatarStore } from "./data/avatars.js";`)
+
+Pass `avatarStore` through to whatever constructs `BotManager` (and from there to `BotInstance`).
+
+- [ ] **Step 3: In `BotInstance`, after `profileManager` is created, load the avatar from disk if any**
+
+In `src/bot/instance.ts`, after `this.profileManager = new BotProfileManager(...)`:
+
+```ts
+const relPath = this.botDb.getCustomAvatarPath(this.id);
+if (relPath) {
+  const buf = this.avatarStore.read(relPath);
+  if (buf) this.profileManager.setCustomAvatar(buf);
+}
+```
+
+(Add `private botDb: BotDatabase` and `private avatarStore: AvatarStore` constructor params; thread them down from `BotManager.createBot()` / `BotManager` constructor.)
+
+- [ ] **Step 4: Add `getProfileManager()` accessor if not present**
+
+If grep already shows `getProfileManager(): BotProfileManager`, skip. Otherwise add a public method that returns `this.profileManager`.
+
+- [ ] **Step 5: Build and run the existing tests**
+
+Run: `npx tsc --noEmit`
+Expected: no TS errors
+
+Run: `npm test`
+Expected: all green
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add src/index.ts src/bot/instance.ts src/bot/manager.ts
+git commit -m "feat(bot): load custom avatar on instance startup"
+```
+
+---
+
+### Task 5: REST endpoints for avatar upload / fetch / delete
+
+**Files:**
+- Modify: `src/web/server.ts` (json size limit)
+- Modify: `src/web/api/bot.ts`
+
+- [ ] **Step 1: Bump express.json size limit**
+
+In `src/web/server.ts`, find `app.use(express.json())` (~line 46) and change to:
+
+```ts
+app.use(express.json({ limit: "400kb" }));
+```
+
+(Avatar payload is base64-encoded ≤200 KB → ~270 KB on the wire; 400 KB gives margin.)
+
+- [ ] **Step 2: Write a failing API test (use supertest if not present, otherwise inline fetch)**
+
+Run: `grep -E '"supertest"|"vitest"' package.json`
+
+If supertest is not present, write the test using `node:http` raw client or skip API integration test and rely on manual + unit tests on Task 7. Don't add new deps unless approved.
+
+If supertest IS present, add `src/web/api/bot.test.ts`:
+
+```ts
+import { describe, it, expect } from "vitest";
+import request from "supertest";
+import express from "express";
+import { createBotRouter } from "./bot.js";
+// ... build minimal app with mocked manager + DB + avatarStore
+```
+
+If not present: skip Step 2, jump to Step 3 and verify by manual curl in Step 5.
+
+- [ ] **Step 3: Add the three endpoints**
+
+In `src/web/api/bot.ts`, modify the factory signature to accept `avatarStore` and `botDb`:
+
+```ts
+export function createBotRouter(
+  botManager: BotManager,
+  config: BotConfig,
+  configPath: string,
+  logger: Logger,
+  botDb: BotDatabase,
+  avatarStore: AvatarStore,
+): Router {
+```
+
+Inside the router, after the existing `/:id/config` GET, add:
+
+```ts
+  router.get("/:id/avatar", (req, res) => {
+    const path = botDb.getCustomAvatarPath(req.params.id);
+    if (!path) { res.status(404).end(); return; }
+    const buf = avatarStore.read(path);
+    if (!buf) { res.status(404).end(); return; }
+    const ext = path.split(".").pop()!;
+    const mime = ext === "png" ? "image/png" : ext === "webp" ? "image/webp" : "image/jpeg";
+    res.set("Content-Type", mime);
+    res.set("Cache-Control", "no-cache");
+    res.send(buf);
+  });
+
+  router.put("/:id/avatar", (req, res) => {
+    const bot = botManager.getBot(req.params.id);
+    if (!bot && !botDb.getBotInstances().some((b) => b.id === req.params.id)) {
+      res.status(404).json({ error: "Bot not found" });
+      return;
+    }
+    const { dataUrl } = req.body as { dataUrl?: string };
+    if (typeof dataUrl !== "string") {
+      res.status(400).json({ error: "dataUrl required" });
+      return;
+    }
+    const m = /^data:(image\/(png|jpeg|webp));base64,(.+)$/.exec(dataUrl);
+    if (!m) {
+      res.status(400).json({ error: "dataUrl must be image/png|jpeg|webp base64" });
+      return;
+    }
+    const mime = m[1];
+    const buf = Buffer.from(m[3], "base64");
+    if (buf.length > 200 * 1024) {
+      res.status(413).json({ error: "avatar exceeds 200KB limit" });
+      return;
+    }
+    const rel = avatarStore.write(req.params.id, mime, buf);
+    botDb.setCustomAvatarPath(req.params.id, rel);
+    bot?.getProfileManager().setCustomAvatar(buf);
+    res.json({ path: rel });
+  });
+
+  router.delete("/:id/avatar", (req, res) => {
+    const path = botDb.getCustomAvatarPath(req.params.id);
+    if (path) avatarStore.remove(path);
+    botDb.setCustomAvatarPath(req.params.id, null);
+    const bot = botManager.getBot(req.params.id);
+    bot?.getProfileManager().setCustomAvatar(null);
+    res.status(204).end();
+  });
+```
+
+- [ ] **Step 4: Update the call site that constructs the router**
+
+Search: `grep -n 'createBotRouter' src/`
+
+In the call site (likely `src/web/server.ts` or `src/index.ts`), pass the new args. Fix the call signature.
+
+- [ ] **Step 5: Manual smoke test**
+
+Run: `npm run build && npm run start`
+In another terminal:
+
+```bash
+# create a small valid PNG (1x1) base64
+B64=$(node -e "console.log(Buffer.from([137,80,78,71,13,10,26,10,0,0,0,13,73,72,68,82,0,0,0,1,0,0,0,1,8,2,0,0,0,144,119,83,222,0,0,0,12,73,68,65,84,8,153,99,248,255,255,63,0,5,254,2,254,205,250,236,184,0,0,0,0,73,69,78,68,174,66,96,130]).toString('base64'))")
+
+curl -X PUT http://localhost:3000/api/bot/<BOT_ID>/avatar \
+  -H 'Content-Type: application/json' \
+  -d "{\"dataUrl\":\"data:image/png;base64,$B64\"}"
+
+curl http://localhost:3000/api/bot/<BOT_ID>/avatar -o /tmp/x.png
+file /tmp/x.png
+
+curl -X DELETE http://localhost:3000/api/bot/<BOT_ID>/avatar -i
+```
+
+Expected: PUT returns `{"path":"<id>.png"}`, GET returns the bytes, DELETE returns 204.
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add src/web/server.ts src/web/api/bot.ts src/index.ts
+git commit -m "feat(api): /api/bot/:id/avatar GET/PUT/DELETE"
+```
+
+---
+
+### Task 6: Frontend — `AvatarUpload.vue` component
+
+**Files:**
+- Create: `web/src/components/AvatarUpload.vue`
+
+- [ ] **Step 1: Create the component**
+
+```vue
+<template>
+  <div class="avatar-upload">
+    <div class="preview" :class="{ empty: !previewUrl }">
+      <img v-if="previewUrl" :src="previewUrl" alt="avatar" />
+      <Icon v-else icon="mdi:account-circle-outline" />
+    </div>
+    <div class="actions">
+      <input
+        ref="fileInput"
+        type="file"
+        accept="image/png,image/jpeg,image/webp"
+        class="hidden"
+        @change="onFile"
+      />
+      <button type="button" class="btn-sm" @click="fileInput?.click()">
+        {{ previewUrl ? '更换' : '上传' }}
+      </button>
+      <button v-if="previewUrl" type="button" class="btn-sm btn-danger" @click="clear">
+        删除
+      </button>
+    </div>
+    <p v-if="error" class="hint error">{{ error }}</p>
+    <p v-else class="hint">PNG / JPG / WebP，≤200 KB</p>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { ref, watch } from 'vue';
+import { Icon } from '@iconify/vue';
+
+const props = defineProps<{ modelValue: string | null }>();
+const emit = defineEmits<{ 'update:modelValue': [value: string | null] }>();
+
+const previewUrl = ref<string | null>(props.modelValue);
+const error = ref<string | null>(null);
+const fileInput = ref<HTMLInputElement | null>(null);
+
+watch(() => props.modelValue, (v) => { previewUrl.value = v; });
+
+function onFile(ev: Event) {
+  const file = (ev.target as HTMLInputElement).files?.[0];
+  if (!file) return;
+  if (!['image/png', 'image/jpeg', 'image/webp'].includes(file.type)) {
+    error.value = '仅支持 PNG / JPG / WebP';
+    return;
+  }
+  if (file.size > 200 * 1024) {
+    error.value = `图片 ${(file.size / 1024).toFixed(0)} KB 超过 200 KB 上限`;
+    return;
+  }
+  error.value = null;
+  const reader = new FileReader();
+  reader.onload = () => {
+    const dataUrl = reader.result as string;
+    previewUrl.value = dataUrl;
+    emit('update:modelValue', dataUrl);
+  };
+  reader.readAsDataURL(file);
+}
+
+function clear() {
+  previewUrl.value = null;
+  emit('update:modelValue', null);
+  if (fileInput.value) fileInput.value.value = '';
+}
+</script>
+
+<style lang="scss" scoped>
+.avatar-upload { display: flex; flex-direction: column; gap: 8px; align-items: flex-start; }
+.preview {
+  width: 80px; height: 80px; border-radius: 50%;
+  background: var(--bg-card); display: flex; align-items: center; justify-content: center;
+  overflow: hidden;
+  img { width: 100%; height: 100%; object-fit: cover; }
+  &.empty :deep(svg) { font-size: 48px; opacity: 0.4; }
+}
+.actions { display: flex; gap: 8px; }
+.hidden { display: none; }
+.hint { font-size: 12px; opacity: 0.6; margin: 0; }
+.hint.error { color: var(--color-danger, #e85060); opacity: 1; }
+.btn-danger { color: var(--color-danger, #e85060); }
+</style>
+```
+
+- [ ] **Step 2: Verify the component compiles**
+
+Run: `cd web && npx vue-tsc --noEmit`
+Expected: no errors
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add web/src/components/AvatarUpload.vue
+git commit -m "feat(web): AvatarUpload component"
+```
+
+---
+
+### Task 7: Wire AvatarUpload into Settings.vue (create + edit + standalone row)
+
+**Files:**
+- Modify: `web/src/views/Settings.vue`
+
+- [ ] **Step 1: Read the relevant Settings.vue regions**
+
+```bash
+grep -n '同步头像\|openEditBot\|saveEditBot\|createBot\|create-bot\|profile-features\|features.find' web/src/views/Settings.vue | head -20
+```
+
+Identify:
+- Create-bot form template region (`<div class="create-bot">` block)
+- Edit-bot modal/dialog template region
+- The profile features table where `avatarEnabled` row lives
+
+- [ ] **Step 2: Add component import + reactive state for avatar dataUrl on the create-bot form**
+
+In the script setup region, near other `newBot*` refs:
+
+```ts
+import AvatarUpload from '../components/AvatarUpload.vue';
+const newBotAvatar = ref<string | null>(null);
+```
+
+- [ ] **Step 3: Insert `<AvatarUpload v-model="newBotAvatar" />` into the create-bot form template**
+
+In the `<div class="create-bot">` block, right before `<button class="btn-primary" @click="createBot">创建</button>`, add:
+
+```vue
+        <div class="form-row">
+          <label>自定义头像（可选）</label>
+          <AvatarUpload v-model="newBotAvatar" />
+        </div>
+```
+
+- [ ] **Step 4: After successful `createBot()`, PUT the avatar if set**
+
+Find the `createBot` async function. After the POST resolves and the bot id is known (`res.data.id` or similar), append:
+
+```ts
+if (newBotAvatar.value) {
+  await axios.put(`/api/bot/${res.data.id}/avatar`, { dataUrl: newBotAvatar.value });
+}
+newBotAvatar.value = null;
+```
+
+- [ ] **Step 5: Add an "自定义头像" row in the per-bot profile features table**
+
+Find the profile-features table render (look for the `features` array iteration). The cleanest path: add a custom row OUTSIDE the array (since it isn't a boolean toggle). Right before `</template>` of the bot row, add:
+
+```vue
+        <div class="feature-row">
+          <div class="feature-label">自定义头像</div>
+          <div class="feature-control">
+            <CustomAvatarRow :bot-id="bot.id" />
+          </div>
+        </div>
+```
+
+Where `CustomAvatarRow` is an inline-defined component or a small file `web/src/components/CustomAvatarRow.vue` that:
+- Mounts → `axios.get(/api/bot/<id>/avatar, { responseType: 'blob' })` → previews if 200, ignore 404
+- Wraps `<AvatarUpload>` and on `update:modelValue`:
+  - If string → `axios.put(/avatar, { dataUrl })`
+  - If null → `axios.delete(/avatar)`
+
+Create `web/src/components/CustomAvatarRow.vue` with that logic; keep its body small (~50 lines).
+
+- [ ] **Step 6: Build and visually verify**
+
+Run: `cd web && npm run build` → no errors. Then `npm run dev` → open create-instance, upload PNG, create — verify the avatar appears on the bot in TS3 once it connects. Check edit/Settings flow.
+
+- [ ] **Step 7: Commit**
+
+```bash
+git add web/src/views/Settings.vue web/src/components/CustomAvatarRow.vue
+git commit -m "feat(web): custom avatar in create-bot + Settings"
+```
+
+---
+
+### Task 8: Open PR
+
+- [ ] **Step 1: Push the branch**
+
+```bash
+git checkout -b feat/custom-bot-avatar
+git push -u origin feat/custom-bot-avatar
+```
+
+(If commits were already on `main`, instead create the branch from the first relevant commit and reset main: `git branch feat/custom-bot-avatar HEAD && git reset --hard origin/main && git checkout feat/custom-bot-avatar`. The exact sequence depends on the working state when starting.)
+
+- [ ] **Step 2: Create the PR**
+
+```bash
+gh pr create --title "feat(profile): custom bot avatar" --body "Closes part of #51 (avatar half).
+
+## Summary
+- New /api/bot/:id/avatar GET/PUT/DELETE
+- BotProfileManager: custom avatar acts as idle image; cover sync still wins during playback when avatarEnabled=true
+- AvatarUpload component used in create-bot form and Settings per-bot row
+- Bump express.json limit to 400kb to allow base64 payload
+
+## Behavior matrix
+| avatarEnabled | custom set | playing | stopped |
+|---|---|---|---|
+| ✓ | ✓ | cover | restore custom |
+| ✓ | ✗ | cover | clear |
+| ✗ | ✓ | custom | custom |
+| ✗ | ✗ | no-op | no-op |
+
+## Test plan
+- [x] vitest covers DB, avatar store, ProfileManager precedence
+- [x] Manual: upload PNG → bot avatar shows; play song → cover; stop → custom; delete → cleared
+
+🤖 Generated with [Claude Code](https://claude.com/claude-code)"
+```
+
+---
+
+## Self-Review Checklist
+
+- [x] Each spec section has at least one task: precedence matrix → Task 3; storage → Task 2; DB → Task 1; API → Task 5; UI → Task 6+7
+- [x] No "TBD" / "fill in" / "implement later" text in any step
+- [x] Type names consistent: `AvatarStore` / `createAvatarStore` / `getCustomAvatarPath` / `setCustomAvatarPath` / `setCustomAvatar` (singular per call site)
+- [x] All code blocks compile under existing TS/Vue config (express 5, vitest, vue 3 + iconify already in use)

docs/superpowers/specs/2026-05-07-custom-avatar-and-album-search-design.md

@@ -0,0 +1,149 @@
+# 自定义机器人头像 + 专辑搜索/播放
+
+**Date:** 2026-05-07
+**Status:** Spec — pending implementation
+**Issue:** [#51](https://github.com/ZHANGTIANYAO1/teamspeak-music-bot/issues/51)
+
+## Problem
+
+Issue #51 的两个独立但同源的反馈：
+
+1. **机器人头像无法固定** — 当前 `ProfileConfig.avatarEnabled` 控制是否同步专辑封面，但没有任何"上传一张固定头像"的入口。多 bot 房间里用户依赖头像辨识具体 bot，封面跟着歌变会让识别成本变高。
+2. **网页端搜索不能播放整张专辑** — `SearchResult.albums` 类型字段存在但所有 provider 都返回 `[]`，搜索 API `/search/all` 只聚合 `songs`；Search.vue 里也只渲染 SongCard。Netease 后端 `getAlbumSongs` 已实现，唯独缺把搜索/UI 连起来。
+
+两件事独立，分两个 PR；本 spec 同时覆盖两块以保持 #51 的单一 issue 关系。
+
+## Goal
+
+### 自定义头像
+
+- "创建新实例"弹窗里有一个"自定义头像"上传/预览控件（PNG/JPG/WebP，≤200 KB，与 TS3 头像上限一致）
+- Settings 已有的"同步头像"那行下面增加同等的"自定义头像"卡片，可以在已存在的 bot 上随时改/删
+- 行为矩阵：
+
+  | `avatarEnabled` | 有自定义 | 播放时 | 停播时 |
+  |---|---|---|---|
+  | true  | 是 | 跟当前歌曲封面 | **回到自定义** |
+  | true  | 否 | 跟当前歌曲封面 | 清空（保持现状） |
+  | false | 是 | 一直显示自定义 | 一直显示自定义 |
+  | false | 否 | 不主动改 | 不主动改 |
+
+### 专辑搜索
+
+- 搜索结果里能看到"专辑"分区（先支持 Netease + QQ，bilibili/youtube 仍返回 `[]`）
+- 点专辑卡片进入详情页 → 看到曲目列表 + 顶部"播放全部 / 加入队列"
+
+## Out of Scope
+
+- 头像格式自动转换（用户传 GIF/BMP 不接受，前端校验拒掉）
+- 头像服务端自动 resize（本期保持"上传时校验大小"，后期可加 sharp/jimp 但不在本期）
+- 专辑搜索的多平台聚合排序（按 `netease → qq` 简单拼接，与现有 `songs` 聚合一致）
+- 专辑详情页的"喜欢/收藏"按钮（playlist 详情页本身也没有）
+- 专辑作为推荐位（Home 不出现"推荐专辑"这一栏）
+- bilibili / youtube 的专辑概念（这两个平台无对应 API）
+
+## Architecture
+
+### 自定义头像
+
+#### 存储
+
+- 文件落地 `data/avatars/<botId>.<ext>`（仿 `data/cookies/<platform>.json`，Docker volume 友好）
+- DB schema：`bot_instances` 表新增 `custom_avatar_path` TEXT NULL（存相对路径，如 `avatars/<botId>.png`），通过 `migrateSchema()` 迁移
+- 加载时机：`BotProfileManager` 构造时把文件读到内存 `Buffer`，避免每次 stop 都读盘
+
+#### 后端 API
+
+新增 `src/web/api/bot.ts` 里（如不存在则在 `instance.ts` 同源处）：
+
+- `POST /api/bot/:id/avatar` (multipart) — 校验大小 ≤200 KB、MIME ∈ {png,jpeg,webp}；写盘 + 更新 DB；广播给运行中实例（重新加载 buffer + 立即 `applyIdleAvatar()`）
+- `DELETE /api/bot/:id/avatar` — 删盘 + 清 DB；运行中实例切回原 clear 语义
+- `GET /api/bot/:id/avatar` — 直接 `res.sendFile`（带强 ETag）供前端预览
+
+#### `BotProfileManager` 改动
+
+新增字段 + 方法：
+
+```ts
+private customAvatar: Buffer | null = null;
+
+setCustomAvatar(buf: Buffer | null): void;
+private async applyIdleAvatar(gen: number): Promise<void>;  // 上传 customAvatar
+```
+
+修改：
+
+- `clearAvatar(gen)` → `if (this.customAvatar) { applyIdleAvatar(gen) } else { 当前逻辑 }`
+- `onConnect()` 新增：`if (!avatarEnabled && customAvatar) applyIdleAvatar(gen)`
+- `setCustomAvatar(buf)`：更新内存 buffer，并触发 `applyIdleAvatar` 一次（仅当当前应该显示 idle avatar 时，即没在播放或 avatarEnabled=false）
+
+#### 前端
+
+新组件 `web/src/components/AvatarUpload.vue`：
+
+- props: `botId?` (上传时空表示走临时 base64 缓存)、`v-model:value`
+- 拖拽 / 文件选择 / 预览圆框 / 删除按钮
+- 内部 `axios.post('/api/bot/<id>/avatar', formData)` 或在创建表单里把 base64 与表单一同提交
+
+接入点：
+
+- 创建实例弹窗（搜索 `BotEditor.vue` 或类似）—— 表单提交后用返回的 botId 再 POST 头像；或者表单本身保存 base64 等创建完成后由后端解码落盘
+- Settings.vue：在 features 列表中插入一行"自定义头像"，右侧渲染 `<AvatarUpload :bot-id="botId" />`
+
+### 专辑搜索 / 详情
+
+#### 后端
+
+`src/music/netease.ts` `search()`：
+
+- 多发一个 `cloudsearch?type=10` 请求，把返回的 `result.albums[]` 映射成 `Album[]` 填进 `SearchResult.albums`
+- 字段 `id` / `name` / `coverUrl` (`picUrl`) / `artist` (`artists[].name.join(' / ')`)
+
+`src/music/qq.ts` `search()`：
+
+- 在现有 `req_0` 旁增加 `req_album: { module: "music.search.SearchCgiService", method: "DoSearchForQQMusicDesktop", param: { searchid, query, search_type: 8 } }`，映射 `body.album.list[]`
+
+`src/web/api/music.ts` `/search/all`：
+
+- 在响应里增加 `albums` 和 `playlists`，与 `songs` 一同合并
+
+`/album/:id` 已存在，无需改动。
+
+#### 前端
+
+- `web/src/views/Search.vue`：响应 schema 升级为 `{songs, albums, playlists}`；模板加入两个新分区（"专辑"、"歌单"），各自一个简单的卡片网格（参考 Home.vue 的 `playlist-grid`）
+- 新路由 `/album/:id` → 复用 `Playlist.vue`，把它的 `loadPlaylist()` 重构为根据 `route.path` 决定调 `/playlist/:id` 还是 `/album/:id`，或者新建 `Album.vue` 内部 import 同一个 `<PlaylistDetail />` 子组件
+  - **方案选择**：拆出 `<PlaylistDetail :endpoint="...">` 组件 + `Album.vue` / `Playlist.vue` 两个薄壳。当前 `Playlist.vue` 内部仅 ~60 行模板，单文件改造比新建 PlaylistDetail 子组件更小，先用最小改动：在 `Playlist.vue` 内根据 `route.meta.kind === 'album'` 切换 endpoint
+- 路由：`router/index.ts` 加 `{ path: '/album/:id', component: Playlist, meta: { kind: 'album' } }`
+
+### 拆分
+
+**两个 PR：**
+
+1. `feat(profile): custom bot avatar with idle/playback precedence`
+   - DB migration + ProfileManager 改动 + 上传 API + AvatarUpload.vue + 接入两个表单
+2. `feat(search): album section in search results + album detail playback`
+   - netease/qq search 扩展 + /search/all + Search.vue 分区 + Playlist.vue 复用为 album
+
+## Testing
+
+### 自定义头像
+
+- 单元：DB 迁移加 `custom_avatar_path` 列幂等；上传 API 校验大小/MIME；ProfileManager.applyIdleAvatar 在 onSongChange(null) 后被调用
+- 集成：mock TS3Client 验证 fileTransferInitUpload 收到的 buffer 是 customAvatar
+- 手动：本地起 bot 上传一张 png → 检查头像；播一首歌 → 头像切封面；停止 → 头像回到 png；关掉 avatarEnabled 重启 → 头像直接是 png
+
+### 专辑搜索
+
+- 单元：netease/qq `search()` 测试：响应包含 albums 字段，长度 > 0 (mock fixture 必须含 album 段)
+- 集成：`/search/all` 响应 schema 包含 `albums`/`playlists`
+- 手动：搜"周杰伦" → 看到歌曲 + 专辑 + 歌单三个分区；点专辑 → 详情页 → 播放全部 → 队列加上整张专辑
+
+## Migration
+
+DB 迁移：`bot_instances.custom_avatar_path` TEXT NULL，默认 NULL。已存在 bot 不受影响。
+
+## Open Questions
+
+- TS6 协议路径下 `fileTransferInitUpload` 是否一致？（既有 avatar 流程已经覆盖 TS3 + TS6，本期沿用同一路径，不单独验证）
+- 头像超过 200 KB 时前端用 Canvas 自动 resize 还是直接拒？— **决定：拒，错误提示"请压缩到 200KB 以内"**，简单可控

docs/superpowers/specs/2026-05-27-webui-authentication-design.md

@@ -0,0 +1,360 @@
+# WebUI Authentication
+
+**Date:** 2026-05-27
+**Status:** Spec — pending implementation
+**Branch:** `feat/webui-auth`
+
+## Problem
+
+WebUI 的所有后端端点和 WebSocket 当前没有任何鉴权：
+
+- `src/web/server.ts` 注册的 `/api/bot`、`/api/player`、`/api/music`、`/api/auth`、`/api/config/public-url`、`/api/health`、`/ws` 均无中间件拦截。
+- 静态前端通过 `express.static()` 直接对外提供。
+
+后果：任何能访问 WebUI 端口（默认 `3000`）的人都能控制 bot、修改配置、操控播放，并触发对网易云 / QQ / Bilibili 的登录二维码流程。一旦 WebUI 端口暴露公网（无论是直接绑定 `0.0.0.0`、还是经 nginx 反代），即被任意访客接管。
+
+## Goal
+
+为 WebUI 增加用户名 + 密码登录，覆盖所有 HTTP `/api/*` 端点（除显式公共白名单）以及 `/ws` WebSocket，使未登录访客无法调用任何敏感接口或观察 bot 状态。
+
+## Out of Scope（明确不做）
+
+- 登录失败的限流 / 锁定（无 brute-force 防御；可放在反代层；后续 PR 单独做）
+- 角色与权限（admin / viewer）—— 全员同权
+- 密码重置流程（不挂邮件；仅提供登录后 `change-password`）
+- 双因素认证（2FA）
+- "记住我" / 绝对过期 vs 滑动过期的可配置
+- 旧版"无鉴权"兼容开关（`requireAuth=false`）—— 合入后所有部署强制启用鉴权
+- 现有 `config.adminPassword` 字段的迁移 —— 保留为未使用字段，避免破坏旧 `config.json`
+
+## Non-functional Constraints
+
+- 不引入需要原生编译的依赖（Windows 用户多，build tools 不稳定）。密码哈希用纯 JS 的 `bcryptjs`。
+- Cookie 行为必须兼容现有 `trustProxy` 反代部署。
+- 升级路径：旧用户首次启动新版本 → 自动进入 `/setup` 创建首位 admin；期间所有 `/api/*` 仍拒绝访问。期间不存在"裸奔窗口"。
+- 后续维护者要能在不阅读 `requireAuth` 内部细节的情况下，把新路由挂到 `/api/*` 下并自动获得鉴权。
+
+## Architecture
+
+### 数据层（`src/data/`）
+
+扩展 `src/data/database.ts` 的 schema-migration 块，新增两张表：
+
+```sql
+CREATE TABLE IF NOT EXISTS users (
+  id           TEXT PRIMARY KEY,                 -- uuid v4
+  username     TEXT NOT NULL UNIQUE COLLATE NOCASE,
+  passwordHash TEXT NOT NULL,                    -- bcryptjs, 12 rounds
+  createdAt    INTEGER NOT NULL,
+  updatedAt    INTEGER NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS sessions (
+  id          TEXT PRIMARY KEY,                  -- sha256(rawToken) hex
+  userId      TEXT NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+  createdAt   INTEGER NOT NULL,
+  expiresAt   INTEGER NOT NULL,                  -- ms epoch
+  lastSeenAt  INTEGER NOT NULL
+);
+CREATE INDEX IF NOT EXISTS idx_sessions_userId    ON sessions(userId);
+CREATE INDEX IF NOT EXISTS idx_sessions_expiresAt ON sessions(expiresAt);
+```
+
+**为什么 `sessions.id` 存 sha256(token) 而不是 token 本身：** 若 SQLite 文件被泄露（备份、误传、磁盘扫描），原始 token 会让攻击者直接冒充任意已登录用户。存 hash 后只能爆破。代价仅是每次请求一次 sha256。
+
+新模块：
+
+`src/data/users.ts`
+- `createUser(username, password): User` — 在事务里 INSERT；遇到 UNIQUE 冲突抛出 `UsernameTakenError`
+- `findByUsername(username): User | null`
+- `verifyPassword(plain, hash): Promise<boolean>` — bcryptjs compare
+- `countUsers(): number` — 用于 `/needs-setup`
+- `changePassword(userId, newPassword): void`
+
+`src/data/sessions.ts`
+- `createSession(userId): { token: string; expiresAt: number }` — 生成 32 字节随机 token（`crypto.randomBytes(32).toString('base64url')`），存 sha256
+- `validateAndTouch(rawToken): { userId, username } | null` — 单次 SQL JOIN：查 session + user；过期 → 返回 null + 删除该行；否则若 `now - lastSeenAt > 1h` 则 UPDATE 滑动续期到 `now + 7d`
+- `deleteSession(rawToken): void` — 退出
+- `deleteAllForUser(userId, exceptToken?): void` — change-password 时调用，可保留当前会话
+- `cleanupExpired(): void` — 定时任务
+
+### HTTP 层（`src/web/`）
+
+#### 新增中间件
+
+`src/web/middleware/requireAuth.ts`
+```
+读取 req.cookies.tsmb_session
+  → 缺失 → 401 { error: "unauthenticated" }
+  → 调 sessions.validateAndTouch
+  → null → 清 cookie + 401
+  → 有效 → req.user = { id, username }; next()
+```
+
+`src/web/middleware/csrf.ts`
+```
+若 method ∈ {GET, HEAD, OPTIONS} → next()
+否则要求 req.headers.origin || req.headers.referer 的 host 与 req.get('host') 一致
+  → 不一致或两者都缺失 → 403 { error: "bad origin" }
+```
+
+#### 新路由：`src/web/api/session.ts`
+
+挂在 `/api/session`，全部公共（不挂 requireAuth）：
+
+| Method | Path | 行为 |
+|---|---|---|
+| GET | `/needs-setup` | `{ needsSetup: users.countUsers() === 0 }` |
+| POST | `/setup` | Body `{ username, password }`。在事务内再次检查 `countUsers() === 0`：是则 INSERT user + 立刻 createSession + Set-Cookie + 200 `{ id, username }`；否则 409 `{ error: "already initialized" }` |
+| POST | `/login` | Body `{ username, password }`。匹配则 createSession + Set-Cookie + 200；不匹配则等待 250ms 后 401 `{ error: "invalid credentials" }`（常量时间延迟，降低用户名枚举风险） |
+| POST | `/logout` | 删 session，清 cookie，204 |
+| GET | `/me` | 走 requireAuth；返回 `{ id, username }` |
+| POST | `/change-password` | 走 requireAuth；Body `{ oldPassword, newPassword }`；通过则 changePassword + deleteAllForUser(except 当前) + 204 |
+
+> `/me` 与 `/change-password` 例外地需要 requireAuth —— 在路由内单独挂中间件，避免污染 `/api/session/*` 的公共属性。
+
+#### Cookie 规范
+
+- 名称：`tsmb_session`
+- 值：32 字节 random → base64url
+- 属性：`HttpOnly; SameSite=Lax; Path=/; Max-Age=604800`（7 天）
+- `Secure` 标志：当 `req.secure === true`（依赖 `trustProxy` + `X-Forwarded-Proto`）；本地 HTTP 调试时不加，避免 cookie 被丢弃
+
+#### 装配顺序（`src/web/server.ts`）
+
+```ts
+app.use(express.json({ limit: "400kb" }));
+app.use(cookieParser());                              // 新增
+
+// 公共
+app.get("/api/health", …);
+app.get("/api/config/public-url", …);
+app.use("/api/session", createSessionRouter(...));
+
+// 闸门（仅作用于下方注册的 /api/* 路由）
+app.use("/api", csrfOriginCheck);
+app.use("/api", requireAuth);
+
+// 受保护
+app.use("/api/bot",    createBotRouter(...));
+app.use("/api/music",  createMusicRouter(...));
+app.use("/api/player", createPlayerRouter(...));
+app.use("/api/auth",   createAuthRouter(...));        // 音乐平台 QR
+
+// 静态 SPA（公共，前端自行判定登录态后跳转）
+app.use(express.static(staticDir));
+app.get(/^(?!\/api|\/ws)/, sendIndex);
+```
+
+> Express 的 `app.use` 仅对匹配前缀生效。公共路由先注册即可命中；之后的 `app.use("/api", …)` 闸门只在公共路由未匹配时执行，因此 `/api/health`、`/api/config/public-url`、`/api/session/*` 不会被闸门拦截。
+
+#### 定时清理
+
+`server.start()` 内启动 `setInterval(cleanupExpired, 60 * 60 * 1000)`，`server.stop()` 内 `clearInterval`。
+
+### WebSocket 层（`src/web/websocket.ts` + `src/web/server.ts`）
+
+改造为手动 upgrade：
+
+```ts
+const wss = new WebSocketServer({ noServer: true });
+
+server.on("upgrade", (req, socket, head) => {
+  if (req.url !== "/ws") { socket.destroy(); return; }
+  const session = validateCookieFromHeaders(req.headers.cookie);
+  if (!session) {
+    socket.write("HTTP/1.1 401 Unauthorized\r\nConnection: close\r\n\r\n");
+    socket.destroy();
+    return;
+  }
+  wss.handleUpgrade(req, socket, head, (ws) => {
+    (ws as any).userId = session.userId;
+    wss.emit("connection", ws, req);
+  });
+});
+```
+
+`validateCookieFromHeaders` 在 `src/web/auth/validateSession.ts` 提供，HTTP 中间件与 WS upgrade 共用同一实现，确保不会出现"HTTP 拒、WS 放行"或反之的偏差。
+
+不需要在 upgrade 上单独做 CSRF：浏览器在跨站 WebSocket 请求里仍会带 Origin 头，可在 validate 之外顺手比对 `req.headers.origin` host 与 `req.headers.host` 一致；不一致直接拒绝。
+
+### 前端层（`web/`）
+
+#### 新视图
+
+- `web/src/views/Login.vue` — 用户名 + 密码表单 → POST `/api/session/login` → 成功跳 `next` 或 `/`
+- `web/src/views/FirstRunSetup.vue` — 同样表单 + 二次确认密码 → POST `/api/session/setup` → 成功后自动登录并跳 `/`
+  - 名称避免与既有 `Setup.vue`（bot 创建向导）冲突
+
+#### Session 状态
+
+新增 `web/src/composables/useSession.ts`：暴露 `currentUser: Ref<User|null>`、`refresh()`、`logout()`、`needsSetup: Ref<boolean>`。在 `App.vue` mount 时调用 `refresh()`。
+
+#### 路由守卫（`web/src/router/index.ts`）
+
+- 公共路由：`/login`、`/setup`
+- 全局 `beforeEach`：
+  1. 先 `GET /api/session/needs-setup`（仅在 `needsSetup` 未知时拉一次并缓存）
+  2. `needsSetup === true` 且目标不是 `/setup` → `redirect('/setup')`
+  3. 否则 `GET /api/session/me`，401 且目标非公共路由 → `redirect('/login?next=<path>')`
+
+#### API 客户端
+
+- 所有 `fetch` 改为 `credentials: 'same-origin'`（若现有有 wrapper 则改一处；否则按文件逐个改 —— 实施时由 plan 列出）
+- 包一层 401 拦截器：任意受保护请求返回 401 → 清 `currentUser` → `router.push('/login')`
+
+#### UI
+
+- 顶栏新增已登录用户名 + "退出"按钮（POST `/logout` → `router.push('/login')`）
+- 修改密码入口暂放在已有的"设置"页签内（若无则新增极简 section）
+
+### 依赖
+
+新增到 `package.json`：
+
+```
+"bcryptjs": "^2.4.3",
+"cookie-parser": "^1.4.6",
+"@types/bcryptjs": "^2.4.6",
+"@types/cookie-parser": "^1.4.7"
+```
+
+不引入 `express-session`、`jsonwebtoken`、`passport` 等更大栈。
+
+## Data Flow
+
+### 首次启动
+
+```
+Browser → GET /         → static SPA
+SPA mounted → GET /api/session/needs-setup → { needsSetup: true }
+SPA → router.replace('/setup')
+User submits form → POST /api/session/setup
+Server (TX): countUsers() === 0 → INSERT user → createSession → Set-Cookie → 200
+SPA → currentUser refresh → router.replace('/')
+```
+
+### 已部署用户升级
+
+旧 `config.adminPassword` 字段保留不动；首次启动新版本仍会因 `users` 表为空而进入 setup 流程 —— 旧字段不被采纳，避免歧义。
+
+### 后续登录
+
+```
+SPA → GET /api/session/me → 401
+SPA → router.replace('/login?next=/queue')
+User submits → POST /api/session/login → Set-Cookie + 200
+SPA → currentUser refresh → router.replace('/queue')
+```
+
+### 受保护请求
+
+```
+SPA → fetch('/api/bot', { credentials: 'same-origin' })
+Server requireAuth: validateAndTouch(cookie)
+  → ok → req.user 注入 → 业务路由处理
+  → 不 ok → 401 → SPA 拦截器跳 /login
+```
+
+### WebSocket
+
+```
+SPA → new WebSocket(`${wsScheme}://${host}/ws`)   // 浏览器自动带 cookie
+Server upgrade handler: validateCookieFromHeaders
+  → ok → handleUpgrade → connection event
+  → 不 ok → HTTP 401 写回原始 socket → destroy
+```
+
+## Error Handling
+
+| 场景 | HTTP 响应 | 备注 |
+|---|---|---|
+| 未带 cookie | 401 `{ error: "unauthenticated" }` | requireAuth |
+| Cookie 解析失败 / token 不存在 | 401 + `Set-Cookie tsmb_session=; Max-Age=0` 清掉 | 自愈 |
+| Session 过期 | 同上 + DELETE 该行 | validateAndTouch 内部完成 |
+| 用户名/密码不匹配 | 401 `{ error: "invalid credentials" }` + 250ms 延迟 | 不区分"用户不存在"和"密码错"两类 |
+| `setup` 时已存在用户 | 409 `{ error: "already initialized" }` | 防止重复初始化 |
+| `setup` 用户名重复 | 在 `/setup` 流程中不可能（只允许 0 → 1） |  |
+| `change-password` 旧密码错 | 401 `{ error: "invalid credentials" }` |  |
+| CSRF Origin 不匹配 | 403 `{ error: "bad origin" }` |  |
+| WS 无 cookie / 校验失败 | 写回 HTTP/1.1 401 并 destroy socket | 在握手前拒绝，避免 onopen 假成功 |
+
+所有错误响应统一 `{ error: string }` 形式，匹配现有 API 风格。
+
+## Testing Strategy
+
+### 单元（vitest）
+
+`src/data/users.test.ts`
+- createUser 成功后 findByUsername 命中（大小写不敏感）
+- 重复 username 抛 UsernameTakenError
+- verifyPassword 正反例
+- changePassword 之后旧哈希不再验证通过
+
+`src/data/sessions.test.ts`
+- createSession 返回的 token 不是 DB 内 id（DB 内是 sha256(token)）
+- validateAndTouch 过期记录返回 null 且记录被删
+- validateAndTouch 未过 1h 不写 DB；过 1h 后写 DB（用 `Date.now` mock 验证）
+- deleteAllForUser(exceptToken) 保留指定会话
+
+### 集成（vitest + supertest，真 SQLite in-memory）
+
+`src/web/api/session.test.ts`
+- empty DB → /needs-setup 返回 true；/setup 成功；/needs-setup 再调返回 false；二次 /setup 返回 409
+- /login 成功后受保护路由 (`GET /api/bot`) 200；不带 cookie 401
+- /logout 之后同一 cookie 调受保护路由 401
+- /change-password 后 a) 旧密码 /login 失败 b) 新密码 /login 成功 c) 之前签发的其他 cookie 失效，当前 cookie 仍可用
+
+`src/web/middleware/csrf.test.ts`
+- 带匹配 Origin 的 POST 通过
+- Origin 与 host 不匹配 → 403
+- 同样规则适用 Referer
+- GET 永远通过
+
+`src/web/websocket.test.ts`（新增或扩展）
+- 无 cookie 的 ws 握手 → 收到 HTTP 401，socket 关闭
+- 带有效 cookie → 握手成功，收到 init 消息
+- Session 删除后已建立的 ws **不会**被主动断（明确记录此妥协 —— 见 Trade-offs）
+
+### 前端
+
+不在本 PR 引入新的 e2e 框架。手动用例（在 PR 描述里列）：
+- 全新数据库启动 → 自动跳 /setup → 创建账户 → 进入主界面
+- 退出 → 自动跳 /login
+- 关闭浏览器 7 天内再开 → 仍登录
+- 登录态下后端重启清空 sessions → 任意 API 调用 → 自动跳 /login
+
+## Files Changed
+
+```
+src/data/database.ts                       (schema migration)
+src/data/users.ts                          (new)
+src/data/users.test.ts                     (new)
+src/data/sessions.ts                       (new)
+src/data/sessions.test.ts                  (new)
+src/web/auth/validateSession.ts            (new, shared by HTTP + WS)
+src/web/middleware/requireAuth.ts          (new)
+src/web/middleware/csrf.ts                 (new)
+src/web/middleware/csrf.test.ts            (new)
+src/web/api/session.ts                     (new)
+src/web/api/session.test.ts                (new)
+src/web/server.ts                          (cookieParser + 公共白名单 + 闸门 + cleanup interval + WS upgrade 重构调用)
+src/web/websocket.ts                       (移除被动 path 绑定；改为 handleUpgrade 模式)
+src/web/websocket.test.ts                  (新增 / 扩展)
+package.json                               (deps)
+
+web/src/views/Login.vue                    (new)
+web/src/views/FirstRunSetup.vue            (new)
+web/src/composables/useSession.ts          (new)
+web/src/router/index.ts                    (公共路由 + beforeEach 守卫)
+web/src/api/*.ts                           (credentials: 'same-origin' + 401 拦截)
+web/src/App.vue                            (顶栏 logout + 当前用户名)
+```
+
+## Trade-offs / 已知妥协
+
+1. **会话失效不主动断 WS** —— 后台 deleteSession 后，已有 WS 仍在跑（直到客户端断或服务端进程重启）。原因：WS 长连接没有"每条消息再次鉴权"的廉价手段；为此引入会浪费时间。影响面有限：WS 只推状态、不接收 mutating 命令；所有写操作仍走 HTTP。
+2. **无登录限流** —— 见 Out of Scope。若部署面向公网，建议在反代层加 limit（如 nginx `limit_req`）。
+3. **`config.adminPassword` 留作未使用字段** —— 不迁移、不读取。后续 PR 可移除并加 schema migration。当前保留是为避免破坏旧 `config.json` 解析。
+4. **单一管理员模型** —— 多用户表已存在，但 UI 当前不暴露增删用户。下一个 PR 再加用户管理界面。
+5. **Origin/Referer CSRF 检查** —— 不是 token，但配合 `SameSite=Lax` 已能挡掉常规 CSRF 攻击。代价：会拒绝缺 Origin/Referer 的非浏览器客户端 POST 请求（如裸 curl）—— 这是预期行为。

package-lock.json

@@ -14,8 +14,10 @@
         "@koa/router": "^15.4.0",
         "@sansenjian/qq-music-api": "^2.2.10",
         "axios": "^1.14.0",
+        "bcryptjs": "^2.4.3",
         "better-sqlite3": "^12.8.0",
         "chalk": "^5.6.2",
+        "cookie-parser": "^1.4.7",
         "express": "^5.2.1",
         "ffmpeg-static": "^5.3.0",
         "koa": "^3.2.0",
@@ -29,10 +31,14 @@
         "yt-dlp-wrap": "^2.3.12"
       },
       "devDependencies": {
+        "@types/bcryptjs": "^2.4.6",
         "@types/better-sqlite3": "^7.6.13",
+        "@types/cookie-parser": "^1.4.10",
         "@types/express": "^5.0.6",
         "@types/node": "^25.5.0",
+        "@types/supertest": "^6.0.3",
         "@types/ws": "^8.18.1",
+        "supertest": "^7.2.2",
         "tsx": "^4.21.0",
         "typescript": "^6.0.2",
         "vitest": "^4.1.2"
@@ -667,6 +673,29 @@
         "url": "https://github.com/sponsors/Boshen"
       }
     },
+    "node_modules/@paralleldrive/cuid2": {
+      "version": "2.3.1",
+      "resolved": "https://registry.npmjs.org/@paralleldrive/cuid2/-/cuid2-2.3.1.tgz",
+      "integrity": "sha512-XO7cAxhnTZl0Yggq6jOgjiOHhbgcO4NqFqwSmQpjK3b6TEE6Uj/jfSk6wzYyemh3+I0sHirKSetjQwn5cZktFw==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@noble/hashes": "^1.1.5"
+      }
+    },
+    "node_modules/@paralleldrive/cuid2/node_modules/@noble/hashes": {
+      "version": "1.8.0",
+      "resolved": "https://registry.npmjs.org/@noble/hashes/-/hashes-1.8.0.tgz",
+      "integrity": "sha512-jCs9ldd7NwzpgXDIf6P3+NrHh9/sD6CQdxHyjQI+h/6rDNo88ypBxxz45UDuZHz9r3tNz7N/VInSVoVdtXEI4A==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": "^14.21.3 || >=16"
+      },
+      "funding": {
+        "url": "https://paulmillr.com/funding/"
+      }
+    },
     "node_modules/@pinojs/redact": {
       "version": "0.4.0",
       "resolved": "https://registry.npmjs.org/@pinojs/redact/-/redact-0.4.0.tgz",
@@ -1152,6 +1181,13 @@
         "tslib": "^2.4.0"
       }
     },
+    "node_modules/@types/bcryptjs": {
+      "version": "2.4.6",
+      "resolved": "https://registry.npmjs.org/@types/bcryptjs/-/bcryptjs-2.4.6.tgz",
+      "integrity": "sha512-9xlo6R2qDs5uixm0bcIqCeMCE6HiQsIyel9KQySStiyqNl2tnj2mP3DX1Nf56MD6KMenNNlBBsy3LJ7gUEQPXQ==",
+      "dev": true,
+      "license": "MIT"
+    },
     "node_modules/@types/better-sqlite3": {
       "version": "7.6.13",
       "resolved": "https://registry.npmjs.org/@types/better-sqlite3/-/better-sqlite3-7.6.13.tgz",
@@ -1194,6 +1230,23 @@
         "@types/node": "*"
       }
     },
+    "node_modules/@types/cookie-parser": {
+      "version": "1.4.10",
+      "resolved": "https://registry.npmjs.org/@types/cookie-parser/-/cookie-parser-1.4.10.tgz",
+      "integrity": "sha512-B4xqkqfZ8Wek+rCOeRxsjMS9OgvzebEzzLYw7NHYuvzb7IdxOkI0ZHGgeEBX4PUM7QGVvNSK60T3OvWj3YfBRg==",
+      "dev": true,
+      "license": "MIT",
+      "peerDependencies": {
+        "@types/express": "*"
+      }
+    },
+    "node_modules/@types/cookiejar": {
+      "version": "2.1.5",
+      "resolved": "https://registry.npmjs.org/@types/cookiejar/-/cookiejar-2.1.5.tgz",
+      "integrity": "sha512-he+DHOWReW0nghN24E1WUqM0efK4kI9oTqDm6XmK8ZPe2djZ90BSNdGnIyCLzCPw7/pogPlGbzI2wHGGmi4O/Q==",
+      "dev": true,
+      "license": "MIT"
+    },
     "node_modules/@types/deep-eql": {
       "version": "4.0.2",
       "resolved": "https://registry.npmjs.org/@types/deep-eql/-/deep-eql-4.0.2.tgz",
@@ -1240,6 +1293,13 @@
       "dev": true,
       "license": "MIT"
     },
+    "node_modules/@types/methods": {
+      "version": "1.1.4",
+      "resolved": "https://registry.npmjs.org/@types/methods/-/methods-1.1.4.tgz",
+      "integrity": "sha512-ymXWVrDiCxTBE3+RIrrP533E70eA+9qu7zdWoHuOmGujkYtzf4HQF96b8nwHLqhuf4ykX61IGRIB38CC6/sImQ==",
+      "dev": true,
+      "license": "MIT"
+    },
     "node_modules/@types/node": {
       "version": "25.6.0",
       "resolved": "https://registry.npmjs.org/@types/node/-/node-25.6.0.tgz",
@@ -1285,6 +1345,30 @@
         "@types/node": "*"
       }
     },
+    "node_modules/@types/superagent": {
+      "version": "8.1.10",
+      "resolved": "https://registry.npmjs.org/@types/superagent/-/superagent-8.1.10.tgz",
+      "integrity": "sha512-nbt4IWXABhW0jGmmpRzCFNlbmwCTzZ2gTUsNIr+X+ItdqPms+PAJZbWsNzpS2USqXjcoNLQcO6nXo60zcPQiIg==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@types/cookiejar": "^2.1.5",
+        "@types/methods": "^1.1.4",
+        "@types/node": "*",
+        "form-data": "^4.0.0"
+      }
+    },
+    "node_modules/@types/supertest": {
+      "version": "6.0.3",
+      "resolved": "https://registry.npmjs.org/@types/supertest/-/supertest-6.0.3.tgz",
+      "integrity": "sha512-8WzXq62EXFhJ7QsH3Ocb/iKQ/Ty9ZVWnVzoTKc9tyyFRRF3a74Tk2+TLFgaFFw364Ere+npzHKEJ6ga2LzIL7w==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@types/methods": "^1.1.4",
+        "@types/superagent": "^8.1.0"
+      }
+    },
     "node_modules/@types/ws": {
       "version": "8.18.1",
       "resolved": "https://registry.npmjs.org/@types/ws/-/ws-8.18.1.tgz",
@@ -1501,6 +1585,13 @@
       "integrity": "sha512-PCVAQswWemu6UdxsDFFX/+gVeYqKAod3D3UVm91jHwynguOwAvYPhx8nNlM++NqRcK6CxxpUafjmhIdKiHibqg==",
       "license": "MIT"
     },
+    "node_modules/asap": {
+      "version": "2.0.6",
+      "resolved": "https://registry.npmjs.org/asap/-/asap-2.0.6.tgz",
+      "integrity": "sha512-BSHWgDSAiKs50o2Re8ppvp3seVHXSRM44cdSsT9FfNEUUZLOGWVCsiWaRPWM1Znn+mqZ1OfVZ3z3DWEzSp7hRA==",
+      "dev": true,
+      "license": "MIT"
+    },
     "node_modules/asn1": {
       "version": "0.2.6",
       "resolved": "https://registry.npmjs.org/asn1/-/asn1-0.2.6.tgz",
@@ -1608,6 +1699,12 @@
       "integrity": "sha512-KXXFFdAbFXY4geFIwoyNK+f5Z1b7swfXABfL7HXCmoIWMKU3dmS26672A4EeQtDzLKy7SXmfBu51JolvEKwtGA==",
       "license": "Unlicense"
     },
+    "node_modules/bcryptjs": {
+      "version": "2.4.3",
+      "resolved": "https://registry.npmjs.org/bcryptjs/-/bcryptjs-2.4.3.tgz",
+      "integrity": "sha512-V/Hy/X9Vt7f3BbPJEi8BdVFMByHi+jNXrYkW3huaybV/kQ0KJg0Y6PkEMbn+zeT+i+SiKZ/HMqJGIIt4LZDqNQ==",
+      "license": "MIT"
+    },
     "node_modules/better-sqlite3": {
       "version": "12.8.0",
       "resolved": "https://registry.npmjs.org/better-sqlite3/-/better-sqlite3-12.8.0.tgz",
@@ -2011,6 +2108,16 @@
         "node": ">= 0.8"
       }
     },
+    "node_modules/component-emitter": {
+      "version": "1.3.1",
+      "resolved": "https://registry.npmjs.org/component-emitter/-/component-emitter-1.3.1.tgz",
+      "integrity": "sha512-T0+barUSQRTUQASh8bx02dl+DhF54GtIDY13Y3m9oWTklKbb3Wv974meRpeZ3lp1JpLVECWWNHC4vaG2XHXouQ==",
+      "dev": true,
+      "license": "MIT",
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
     "node_modules/concat-map": {
       "version": "0.0.1",
       "resolved": "https://registry.npmjs.org/concat-map/-/concat-map-0.0.1.tgz",
@@ -2076,6 +2183,25 @@
         "node": ">= 0.6"
       }
     },
+    "node_modules/cookie-parser": {
+      "version": "1.4.7",
+      "resolved": "https://registry.npmjs.org/cookie-parser/-/cookie-parser-1.4.7.tgz",
+      "integrity": "sha512-nGUvgXnotP3BsjiLX2ypbQnWoGUPIIfHQNZkkC668ntrzGWEZVW70HDEB1qnNGMicPje6EttlIgzo51YSwNQGw==",
+      "license": "MIT",
+      "dependencies": {
+        "cookie": "0.7.2",
+        "cookie-signature": "1.0.6"
+      },
+      "engines": {
+        "node": ">= 0.8.0"
+      }
+    },
+    "node_modules/cookie-parser/node_modules/cookie-signature": {
+      "version": "1.0.6",
+      "resolved": "https://registry.npmjs.org/cookie-signature/-/cookie-signature-1.0.6.tgz",
+      "integrity": "sha512-QADzlaHc8icV8I7vbaJXJwod9HWYp8uCqf1xa4OfNu1T7JVxQIrUgOWtHdNDtPiywmFbiS12VjotIXLrKM3orQ==",
+      "license": "MIT"
+    },
     "node_modules/cookie-signature": {
       "version": "1.2.2",
       "resolved": "https://registry.npmjs.org/cookie-signature/-/cookie-signature-1.2.2.tgz",
@@ -2085,6 +2211,13 @@
         "node": ">=6.6.0"
       }
     },
+    "node_modules/cookiejar": {
+      "version": "2.1.4",
+      "resolved": "https://registry.npmjs.org/cookiejar/-/cookiejar-2.1.4.tgz",
+      "integrity": "sha512-LDx6oHrK+PhzLKJU9j5S7/Y3jM/mUHvD/DeI1WQmJn652iPC5Y4TBzC9l+5OMOXlyTTA+SmVUPm0HQUwpD5Jqw==",
+      "dev": true,
+      "license": "MIT"
+    },
     "node_modules/cookies": {
       "version": "0.9.1",
       "resolved": "https://registry.npmjs.org/cookies/-/cookies-0.9.1.tgz",
@@ -2265,6 +2398,17 @@
         "node": ">=8"
       }
     },
+    "node_modules/dezalgo": {
+      "version": "1.0.4",
+      "resolved": "https://registry.npmjs.org/dezalgo/-/dezalgo-1.0.4.tgz",
+      "integrity": "sha512-rXSP0bf+5n0Qonsb+SVVfNfIsimO4HEtmnIpPHY8Q1UCzKlQrDMfdobr8nJOOsRgWCyMRqeSBQzmWUMq7zvVig==",
+      "dev": true,
+      "license": "ISC",
+      "dependencies": {
+        "asap": "^2.0.0",
+        "wrappy": "1"
+      }
+    },
     "node_modules/dijkstrajs": {
       "version": "1.0.3",
       "resolved": "https://registry.npmjs.org/dijkstrajs/-/dijkstrajs-1.0.3.tgz",
@@ -2596,6 +2740,13 @@
         "node": ">=12.0.0"
       }
     },
+    "node_modules/fast-safe-stringify": {
+      "version": "2.1.1",
+      "resolved": "https://registry.npmjs.org/fast-safe-stringify/-/fast-safe-stringify-2.1.1.tgz",
+      "integrity": "sha512-W+KJc2dmILlPplD/H4K9l9LcAHAfPtP6BY84uVLXQ6Evcz9Lcg33Y2z1IVblT6xdY54PXYVHEv+0Wpq8Io6zkA==",
+      "dev": true,
+      "license": "MIT"
+    },
     "node_modules/fdir": {
       "version": "6.5.0",
       "resolved": "https://registry.npmjs.org/fdir/-/fdir-6.5.0.tgz",
@@ -2744,6 +2895,24 @@
         "node": ">= 0.6"
       }
     },
+    "node_modules/formidable": {
+      "version": "3.5.4",
+      "resolved": "https://registry.npmjs.org/formidable/-/formidable-3.5.4.tgz",
+      "integrity": "sha512-YikH+7CUTOtP44ZTnUhR7Ic2UASBPOqmaRkRKxRbywPTe5VxF7RRCck4af9wutiZ/QKM5nME9Bie2fFaPz5Gug==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@paralleldrive/cuid2": "^2.2.2",
+        "dezalgo": "^1.0.4",
+        "once": "^1.4.0"
+      },
+      "engines": {
+        "node": ">=14.0.0"
+      },
+      "funding": {
+        "url": "https://ko-fi.com/tunnckoCore/commissions"
+      }
+    },
     "node_modules/forwarded": {
       "version": "0.2.0",
       "resolved": "https://registry.npmjs.org/forwarded/-/forwarded-0.2.0.tgz",
@@ -5671,6 +5840,55 @@
         "url": "https://github.com/sponsors/Borewit"
       }
     },
+    "node_modules/superagent": {
+      "version": "10.3.0",
+      "resolved": "https://registry.npmjs.org/superagent/-/superagent-10.3.0.tgz",
+      "integrity": "sha512-B+4Ik7ROgVKrQsXTV0Jwp2u+PXYLSlqtDAhYnkkD+zn3yg8s/zjA2MeGayPoY/KICrbitwneDHrjSotxKL+0XQ==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "component-emitter": "^1.3.1",
+        "cookiejar": "^2.1.4",
+        "debug": "^4.3.7",
+        "fast-safe-stringify": "^2.1.1",
+        "form-data": "^4.0.5",
+        "formidable": "^3.5.4",
+        "methods": "^1.1.2",
+        "mime": "2.6.0",
+        "qs": "^6.14.1"
+      },
+      "engines": {
+        "node": ">=14.18.0"
+      }
+    },
+    "node_modules/superagent/node_modules/mime": {
+      "version": "2.6.0",
+      "resolved": "https://registry.npmjs.org/mime/-/mime-2.6.0.tgz",
+      "integrity": "sha512-USPkMeET31rOMiarsBNIHZKLGgvKc/LrjofAnBlOttf5ajRvqiRA8QsenbcooctK6d6Ts6aqZXBA+XbkKthiQg==",
+      "dev": true,
+      "license": "MIT",
+      "bin": {
+        "mime": "cli.js"
+      },
+      "engines": {
+        "node": ">=4.0.0"
+      }
+    },
+    "node_modules/supertest": {
+      "version": "7.2.2",
+      "resolved": "https://registry.npmjs.org/supertest/-/supertest-7.2.2.tgz",
+      "integrity": "sha512-oK8WG9diS3DlhdUkcFn4tkNIiIbBx9lI2ClF8K+b2/m8Eyv47LSawxUzZQSNKUrVb2KsqeTDCcjAAVPYaSLVTA==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "cookie-signature": "^1.2.2",
+        "methods": "^1.1.2",
+        "superagent": "^10.3.0"
+      },
+      "engines": {
+        "node": ">=14.18.0"
+      }
+    },
     "node_modules/tar": {
       "version": "6.2.1",
       "resolved": "https://registry.npmjs.org/tar/-/tar-6.2.1.tgz",

package.json

@@ -19,8 +19,10 @@
     "@koa/router": "^15.4.0",
     "@sansenjian/qq-music-api": "^2.2.10",
     "axios": "^1.14.0",
+    "bcryptjs": "^2.4.3",
     "better-sqlite3": "^12.8.0",
     "chalk": "^5.6.2",
+    "cookie-parser": "^1.4.7",
     "express": "^5.2.1",
     "ffmpeg-static": "^5.3.0",
     "koa": "^3.2.0",
@@ -34,10 +36,14 @@
     "yt-dlp-wrap": "^2.3.12"
   },
   "devDependencies": {
+    "@types/bcryptjs": "^2.4.6",
     "@types/better-sqlite3": "^7.6.13",
+    "@types/cookie-parser": "^1.4.10",
     "@types/express": "^5.0.6",
     "@types/node": "^25.5.0",
+    "@types/supertest": "^6.0.3",
     "@types/ws": "^8.18.1",
+    "supertest": "^7.2.2",
     "tsx": "^4.21.0",
     "typescript": "^6.0.2",
     "vitest": "^4.1.2"

scripts/download-binaries.mjs

@@ -0,0 +1,161 @@
+#!/usr/bin/env node
+
+/**
+ * Download native binaries (ffmpeg + @discordjs/opus) from npmmirror CDN.
+ * Called by setup.bat after npm install --ignore-scripts.
+ *
+ * Usage: node scripts/download-binaries.mjs [cdn_base_url]
+ */
+
+import { existsSync, mkdirSync, writeFileSync, statSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, dirname } 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 { createRequire } from "node:module";
+import { fileURLToPath } from "node:url";
+
+const ROOT = join(dirname(fileURLToPath(import.meta.url)), "..");
+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) {
+  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}`));
+        return;
+      }
+      const chunks = [];
+      res.on("data", (c) => chunks.push(c));
+      res.on("end", () => resolve(Buffer.concat(chunks)));
+    });
+    req.on("error", reject);
+    req.on("timeout", () => { req.destroy(); reject(new Error("timeout")); });
+  });
+}
+
+function log(msg) {
+  console.log(`  [binary] ${msg}`);
+}
+
+function isValidSize(filePath, minBytes) {
+  try { return statSync(filePath).size >= minBytes; } catch { return false; }
+}
+
+async function downloadFfmpeg() {
+  const ffDir = join(ROOT, "node_modules", "ffmpeg-static");
+  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;
+    }
+    log("ffmpeg exists but seems corrupted (too small), re-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...");
+  try {
+    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;
+  } 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;
+      }
+      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");
+  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...");
+  }
+
+  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;
+  }
+  log("better-sqlite3 extracted but .node file not found at expected path");
+  return false;
+}
+
+try {
+  const results = await Promise.all([downloadFfmpeg(), downloadOpus(), downloadBetterSqlite3()]);
+  if (results.some(Boolean)) {
+    console.log("  [binary] All downloads complete");
+  }
+} catch (e) {
+  console.error(`  [binary] ERROR: ${e.message}`);
+  process.exit(1);
+}
+

scripts/setup.bat

@@ -1,321 +1,294 @@
-@echo off
-setlocal enabledelayedexpansion
-chcp 65001 >nul
-title TSMusicBot Setup
-
-:: ============================================================
-::  TSMusicBot Setup Script (Robust Edition)
-::  - Auto-detect China network, switch to npmmirror
-::  - Strict error checking at every step
-::  - Detailed logging to setup.log
-::  - Skip already-completed steps on re-run
-:: ============================================================
-
-set "SCRIPT_VERSION=2.0"
-set "MIN_NODE_MAJOR=20"
-set "LOG_FILE=%~dp0..\setup.log"
-set "FAILED=0"
-
-:: Resolve project root (one level up from scripts/)
-cd /d "%~dp0.." || (
-    echo [FATAL] Cannot change to project directory.
-    pause
-    exit /b 1
-)
-
-set "PROJECT_ROOT=%cd%"
-
-:: ---- Initialize log ----
-echo. > "%LOG_FILE%"
-call :log "============================================"
-call :log "  TSMusicBot Setup v%SCRIPT_VERSION%"
-call :log "  Started: %date% %time%"
-call :log "  Project root: %PROJECT_ROOT%"
-call :log "============================================"
-
-echo ============================================
-echo   TSMusicBot - First-Time Setup (Windows)
-echo   Version %SCRIPT_VERSION%
-echo ============================================
-echo.
-echo Log file: %LOG_FILE%
-echo.
-
-:: ============================================================
-:: Step 1: Check Node.js
-:: ============================================================
-call :step "1/6" "Checking Node.js"
-
-where node >nul 2>&1
-if errorlevel 1 (
-    call :error "Node.js not found in PATH."
-    echo.
-    echo Please install Node.js %MIN_NODE_MAJOR% LTS or newer from one of:
-    echo   - https://nodejs.org/        ^(official^)
-    echo   - https://nodejs.cn/         ^(China mirror, recommended for CN users^)
-    echo.
-    echo After installation:
-    echo   1. Close this window completely
-    echo   2. Open a NEW Command Prompt
-    echo   3. Run scripts\setup.bat again
-    echo.
-    pause
-    exit /b 1
-)
-
-:: Check Node version >= 20
-for /f "tokens=1 delims=v." %%a in ('node --version 2^>nul') do set "NODE_RAW=%%a"
-for /f "tokens=1 delims=v." %%a in ('node --version 2^>nul') do (
-    for /f "tokens=1 delims=." %%b in ("%%a") do set "NODE_MAJOR=%%b"
-)
-
-:: Robust version parse
-for /f "delims=" %%v in ('node --version 2^>nul') do set "NODE_VER=%%v"
-set "NODE_VER_NUM=%NODE_VER:v=%"
-for /f "tokens=1 delims=." %%a in ("%NODE_VER_NUM%") do set "NODE_MAJOR=%%a"
-
-call :log "Node.js version: %NODE_VER%"
-echo [OK] Node.js found: %NODE_VER%
-
-if %NODE_MAJOR% LSS %MIN_NODE_MAJOR% (
-    call :error "Node.js version too old. Need %MIN_NODE_MAJOR%+, found %NODE_VER%."
-    echo Please upgrade Node.js to version %MIN_NODE_MAJOR% LTS or newer.
-    pause
-    exit /b 1
-)
-echo.
-
-:: ============================================================
-:: Step 2: Check npm
-:: ============================================================
-call :step "2/6" "Checking npm"
-
-where npm >nul 2>&1
-if errorlevel 1 (
-    call :error "npm not found. This is unusual since Node.js is installed."
-    echo Please reinstall Node.js to fix this.
-    pause
-    exit /b 1
-)
-
-for /f "delims=" %%v in ('npm --version 2^>nul') do set "NPM_VER=%%v"
-call :log "npm version: %NPM_VER%"
-echo [OK] npm found: %NPM_VER%
-echo.
-
-:: ============================================================
-:: Step 3: Detect network and configure mirror
-:: ============================================================
-call :step "3/6" "Checking network"
-
-set "USE_MIRROR=0"
-
-:: Try reaching npm registry with a short timeout
-echo Testing connection to registry.npmjs.org...
-call :log "Testing npm registry connectivity..."
-
-:: Use curl if available (more reliable than ping for HTTPS)
-where curl >nul 2>&1
-if not errorlevel 1 (
-    curl -s -o nul -m 5 -w "%%{http_code}" https://registry.npmjs.org/ > "%TEMP%\npmtest.txt" 2>nul
-    set /p HTTP_CODE=<"%TEMP%\npmtest.txt"
-    del "%TEMP%\npmtest.txt" >nul 2>&1
-    if "!HTTP_CODE!"=="200" (
-        echo [OK] npm registry reachable.
-        call :log "npm registry HTTP 200 OK"
-    ) else (
-        echo [WARN] npm registry slow or unreachable ^(code: !HTTP_CODE!^).
-        call :log "npm registry returned: !HTTP_CODE!"
-        set "USE_MIRROR=1"
-    )
-) else (
-    :: Fallback to ping
-    ping -n 1 -w 3000 registry.npmjs.org >nul 2>&1
-    if errorlevel 1 (
-        echo [WARN] Cannot reach npm registry quickly.
-        set "USE_MIRROR=1"
-    ) else (
-        echo [OK] npm registry reachable.
-    )
-)
-
-if "%USE_MIRROR%"=="1" (
-    echo.
-    echo Slow connection detected. Switching to China mirror ^(npmmirror.com^)...
-    call :log "Switching to npmmirror.com"
-    call npm config set registry https://registry.npmmirror.com >>"%LOG_FILE%" 2>&1
-    call npm config set disturl https://registry.npmmirror.com/-/binary/node >>"%LOG_FILE%" 2>&1
-    call npm config set electron_mirror https://registry.npmmirror.com/-/binary/electron/ >>"%LOG_FILE%" 2>&1
-    call npm config set sqlite3_binary_host_mirror https://registry.npmmirror.com/-/binary/better-sqlite3 >>"%LOG_FILE%" 2>&1
-    call npm config set node_sqlite3_binary_host_mirror https://registry.npmmirror.com/-/binary/better-sqlite3 >>"%LOG_FILE%" 2>&1
-    call npm config set sharp_binary_host https://registry.npmmirror.com/-/binary/sharp >>"%LOG_FILE%" 2>&1
-    call npm config set sharp_libvips_binary_host https://registry.npmmirror.com/-/binary/sharp-libvips >>"%LOG_FILE%" 2>&1
-    call npm config set FFMPEG_BINARIES_URL https://registry.npmmirror.com/-/binary/ffmpeg-static >>"%LOG_FILE%" 2>&1
-    call npm config set @discordjs:registry https://registry.npmmirror.com >>"%LOG_FILE%" 2>&1
-    echo [OK] Mirror configured.
-)
-echo.
-
-:: ============================================================
-:: Step 4: Install backend dependencies
-:: ============================================================
-call :step "4/6" "Installing backend dependencies"
-
-if exist "node_modules\.package-lock.json" (
-    echo Found existing node_modules. Checking integrity...
-    call :log "Existing node_modules detected, running npm install to verify"
-)
-
-echo Running: npm install ^(this can take 5-15 minutes on slow networks^)
-echo Press Ctrl+C to abort.
-echo.
-
-call npm install >>"%LOG_FILE%" 2>&1
-if errorlevel 1 (
-    call :error "Backend npm install failed."
-    echo.
-    echo Common causes:
-    echo   - Network timeout ^(retry with VPN or check %LOG_FILE%^)
-    echo   - Native module compile failure ^(missing Python/VS Build Tools^)
-    echo   - Disk space full
-    echo.
-    echo Try manually:
-    echo   cd /d "%PROJECT_ROOT%"
-    echo   npm install --verbose
-    echo.
-    pause
-    exit /b 1
-)
-echo [OK] Backend dependencies installed.
-echo.
-
-:: ============================================================
-:: Step 5: Install frontend dependencies
-:: ============================================================
-call :step "5/6" "Installing frontend dependencies"
-
-if not exist "web\package.json" (
-    call :error "web\package.json not found. Repository may be incomplete."
-    echo Please re-clone the repository:
-    echo   git clone https://github.com/ZHANGTIANYAO1/teamspeak-music-bot.git
-    pause
-    exit /b 1
-)
-
-echo Running: npm install ^(in web/ directory^)
-echo.
-
-pushd web >nul
-call npm install >>"%LOG_FILE%" 2>&1
-set "WEB_INSTALL_RESULT=!errorlevel!"
-popd >nul
-
-if !WEB_INSTALL_RESULT! neq 0 (
-    call :error "Frontend npm install failed ^(exit code !WEB_INSTALL_RESULT!^)."
-    echo.
-    echo Try manually:
-    echo   cd /d "%PROJECT_ROOT%\web"
-    echo   npm install --verbose
-    echo.
-    pause
-    exit /b 1
-)
-echo [OK] Frontend dependencies installed.
-echo.
-
-:: ============================================================
-:: Step 6: Build project (backend + frontend)
-:: ============================================================
-call :step "6/6" "Building project"
-
-echo Running: npm run build
-echo.
-
-call npm run build >>"%LOG_FILE%" 2>&1
-if errorlevel 1 (
-    call :error "Build failed."
-    echo.
-    echo Check the log file for details: %LOG_FILE%
-    echo.
-    echo Try manually:
-    echo   cd /d "%PROJECT_ROOT%"
-    echo   npm run build
-    echo.
-    pause
-    exit /b 1
-)
-echo [OK] Build succeeded.
-echo.
-
-:: ============================================================
-:: Verify build outputs
-:: ============================================================
-echo Verifying build outputs...
-set "BUILD_OK=1"
-
-if not exist "dist" (
-    call :error "dist/ directory missing after build."
-    set "BUILD_OK=0"
-)
-if not exist "web\dist" (
-    call :error "web\dist/ directory missing after build."
-    set "BUILD_OK=0"
-)
-
-if "!BUILD_OK!"=="0" (
-    echo.
-    echo Build completed but expected output is missing.
-    echo Check %LOG_FILE% for details.
-    pause
-    exit /b 1
-)
-echo [OK] Build outputs verified.
-echo.
-
-:: ============================================================
-:: Optional: config.json hint
-:: ============================================================
-if not exist "config.json" (
-    echo [INFO] config.json will be auto-generated on first launch.
-) else (
-    echo [OK] config.json already exists.
-)
-echo.
-
-:: ============================================================
-:: Done
-:: ============================================================
-call :log "Setup completed successfully at %date% %time%"
-
-echo ============================================
-echo   Setup Complete!
-echo ============================================
-echo.
-echo Next steps:
-echo   1. Run:  scripts\start.bat
-echo   2. Open: http://localhost:3000
-echo   3. Follow the in-browser setup wizard.
-echo.
-echo Setup log saved to: %LOG_FILE%
-echo.
-pause
-exit /b 0
-
-:: ============================================================
-:: Subroutines
-:: ============================================================
-:step
-echo ---- Step %~1: %~2 ----
-call :log ""
-call :log "---- Step %~1: %~2 ----"
-goto :eof
-
-:error
-echo.
-echo [ERROR] %~1
-call :log "[ERROR] %~1"
-goto :eof
-
-:log
-echo [%time%] %~1 >> "%LOG_FILE%"
-goto :eof
+@echo off
+setlocal enabledelayedexpansion
+chcp 65001 >nul
+title TSMusicBot Setup
+
+:: ============================================================
+::  TSMusicBot Setup Script (Windows)
+::  - Auto-detect China network, switch to npmmirror
+::  - Download native binaries from CDN (避开 GitHub)
+::  - 自动修复 PowerShell 环境变量
+:: ============================================================
+
+set "SCRIPT_VERSION=2.1"
+set "MIN_NODE_MAJOR=20"
+set "LOG_FILE=%~dp0..\setup.log"
+set "FAILED=0"
+
+:: Resolve project root (one level up from scripts/)
+cd /d "%~dp0.." || (
+    echo [FATAL] Cannot change to project directory.
+    pause
+    exit /b 1
+)
+
+set "PROJECT_ROOT=%cd%"
+
+:: ---- Initialize log ----
+echo. > "%LOG_FILE%"
+call :log "============================================"
+call :log "  TSMusicBot Setup v%SCRIPT_VERSION%"
+call :log "  Started: %date% %time%"
+call :log "  Project root: %PROJECT_ROOT%"
+call :log "============================================"
+
+echo ============================================
+echo   TSMusicBot - First-Time Setup (Windows)
+echo   Version %SCRIPT_VERSION%
+echo ============================================
+echo.
+echo Log file: %LOG_FILE%
+echo.
+
+:: ============================================================
+:: Step 1: Check Node.js
+:: ============================================================
+call :step "1/7" "Checking Node.js"
+
+where node >nul 2>&1
+if not errorlevel 1 goto :check_node_version
+
+call :error "Node.js not found in PATH."
+echo.
+echo Please install Node.js %MIN_NODE_MAJOR% LTS or newer from:
+echo   https://nodejs.org/  (official)
+echo   https://nodejs.cn/   (China mirror, recommended)
+echo.
+pause
+exit /b 1
+
+:check_node_version
+for /f "delims=" %%v in ('node --version 2^>nul') do set "NODE_VER=%%v"
+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%."
+    pause
+    exit /b 1
+)
+echo.
+
+:: ============================================================
+:: Step 2: Check npm
+:: ============================================================
+call :step "2/7" "Checking npm"
+
+where npm >nul 2>&1
+if errorlevel 1 (
+    call :error "npm not found."
+    pause
+    exit /b 1
+)
+
+for /f "delims=" %%v in ('npm --version 2^>nul') do set "NPM_VER=%%v"
+call :log "npm version: %NPM_VER%"
+echo [OK] npm found: %NPM_VER%
+echo.
+
+:: ============================================================
+:: Step 3: Detect network and configure mirror
+:: ============================================================
+call :step "3/7" "Checking network"
+
+set "USE_MIRROR=0"
+set "MIRROR_REGISTRY=https://registry.npmjs.org"
+
+echo Testing connection to npm registry...
+call :log "Testing npm registry connectivity..."
+
+ping -n 1 -w 4000 registry.npmjs.org >nul 2>&1
+if errorlevel 1 (
+    echo [WARN] Cannot reach npm registry quickly, using China mirror.
+    call :log "npm registry unreachable via ping"
+    set "USE_MIRROR=1"
+) else (
+    echo [OK] npm registry reachable.
+    call :log "npm registry reachable"
+)
+
+if "%USE_MIRROR%"=="1" (
+    echo.
+    echo [INFO] Using China mirror (npmmirror.com)
+    call :log "Switching to npmmirror.com"
+    set "MIRROR_REGISTRY=https://registry.npmmirror.com"
+    set "CDN_MIRROR=https://cdn.npmmirror.com/binaries"
+) else (
+    set "CDN_MIRROR="
+)
+echo.
+
+:: ============================================================
+:: Step 4: Install backend dependencies (跳过二进制)
+:: ============================================================
+call :step "4/7" "Installing backend dependencies"
+
+if exist "node_modules\.package-lock.json" (
+    echo Found existing node_modules. Checking integrity...
+)
+
+echo Running: npm install --ignore-scripts (跳过 GitHub 二进制下载)
+echo.
+
+call npm install --registry=%MIRROR_REGISTRY% --ignore-scripts >>"%LOG_FILE%" 2>&1
+if errorlevel 1 (
+    call :error "Backend npm install failed."
+    echo Check the log: %LOG_FILE%
+    pause
+    exit /b 1
+)
+echo [OK] Backend dependencies installed.
+echo.
+
+:: ============================================================
+:: Step 4b: Download native binaries from CDN
+:: ============================================================
+call :step "4b/7" "Downloading 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.
+
+:: ============================================================
+:: Step 5: Install frontend dependencies
+:: ============================================================
+call :step "5/7" "Installing frontend dependencies"
+
+if not exist "web\package.json" (
+    call :error "web\package.json not found."
+    pause
+    exit /b 1
+)
+
+echo Running: npm install (in web/)
+echo.
+
+pushd web >nul
+call npm install --registry=%MIRROR_REGISTRY% >>"%LOG_FILE%" 2>&1
+set "WEB_INSTALL_RESULT=!errorlevel!"
+popd >nul
+
+if !WEB_INSTALL_RESULT! neq 0 (
+    call :error "Frontend npm install failed."
+    pause
+    exit /b 1
+)
+echo [OK] Frontend dependencies installed.
+echo.
+
+:: ============================================================
+:: Step 6: Build project
+:: ============================================================
+call :step "6/7" "Building project"
+
+echo Running: npm run build
+echo.
+
+call npm run build >>"%LOG_FILE%" 2>&1
+if errorlevel 1 (
+    call :error "Build failed. Check: %LOG_FILE%"
+    pause
+    exit /b 1
+)
+echo [OK] Build succeeded.
+echo.
+
+:: ============================================================
+:: Step 7: Ensure PowerShell in PATH (修复 jdymusic CDN 播放)
+:: ============================================================
+call :step "7/7" "Checking PowerShell PATH"
+
+where powershell >nul 2>&1
+if errorlevel 1 (
+    echo [WARN] PowerShell not found in PATH.
+    echo Attempting to fix...
+    set "POWERSHELL_PATH=C:\Windows\System32\WindowsPowerShell\v1.0"
+    if exist "!POWERSHELL_PATH!\powershell.exe" (
+        :: 为用户添加永久 PATH 环境变量
+        echo [INFO] Adding PowerShell to user PATH...
+        call setx PATH "!POWERSHELL_PATH!;%PATH%" >nul 2>&1
+        echo [OK] PowerShell added to PATH. Please restart your terminal.
+    ) else (
+        echo [WARN] Could not find powershell.exe on this system.
+        echo        If you encounter playback issues with some NetEase songs,
+        echo        run: set PATH=%%PATH%%;C:\Windows\System32\WindowsPowerShell\v1.0\
+        echo        before running scripts\start.bat
+    )
+) else (
+    echo [OK] PowerShell found in PATH.
+)
+echo.
+
+:: ============================================================
+:: Verify build outputs
+:: ============================================================
+echo Verifying build outputs...
+set "BUILD_OK=1"
+
+if not exist "dist" (
+    call :error "dist/ directory missing after build."
+    set "BUILD_OK=0"
+)
+if not exist "web\dist" (
+    call :error "web\dist/ directory missing after build."
+    set "BUILD_OK=0"
+)
+
+if "!BUILD_OK!"=="0" (
+    echo Build completed but expected output is missing.
+    pause
+    exit /b 1
+)
+echo [OK] Build outputs verified.
+echo.
+
+if not exist "config.json" (
+    echo [INFO] config.json will be auto-generated on first launch.
+) else (
+    echo [OK] config.json already exists.
+)
+echo.
+
+:: ============================================================
+:: Done
+:: ============================================================
+call :log "Setup completed successfully at %date% %time%"
+
+echo ============================================
+echo   Setup Complete!
+echo ============================================
+echo.
+echo Next steps:
+echo   1. Run:  scripts\start.bat
+echo   2. Open: http://localhost:3000
+echo.
+echo Setup log: %LOG_FILE%
+echo.
+pause
+exit /b 0
+
+:: ============================================================
+:: Subroutines
+:: ============================================================
+:step
+echo ---- Step %~1: %~2 ----
+call :log ""
+call :log "---- Step %~1: %~2 ----"
+goto :eof
+
+:error
+echo.
+echo [ERROR] %~1
+call :log "[ERROR] %~1"
+goto :eof
+
+:log
+echo [%time%] %~1 >> "%LOG_FILE%"
+goto :eof
+

scripts/setup.sh

@@ -0,0 +1,145 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+#
+# TSMusicBot Setup Script (Linux/macOS)
+# - Auto-detect China network, switch to npmmirror
+# - Download native binaries from CDN (避开 GitHub)
+# - One-click setup, same as setup.bat for Windows
+#
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_DIR="$(cd "$SCRIPT_DIR/.." && pwd)"
+LOG_FILE="$PROJECT_DIR/setup.log"
+
+echo "============================================"
+echo "  TSMusicBot - First-Time Setup (Linux)"
+echo "============================================"
+echo ""
+echo "Log file: $LOG_FILE"
+echo ""
+
+# ---- Check Node.js ----
+if ! command -v node &>/dev/null; then
+    echo "[ERROR] Node.js not found. Please install Node.js 20+ from https://nodejs.org"
+    echo "        or https://nodejs.cn/ (China mirror)."
+    exit 1
+fi
+echo "[OK] Node.js $(node -v)"
+
+if ! command -v npm &>/dev/null; then
+    echo "[ERROR] npm not found."
+    exit 1
+fi
+echo "[OK] npm v$(npm -v)"
+echo ""
+
+# ---- Detect China network ----
+USE_MIRROR=0
+MIRROR_REGISTRY="https://registry.npmjs.org"
+CDN_MIRROR=""
+
+echo "Testing connection to npm registry..."
+if ping -c 1 -W 4 registry.npmjs.org &>/dev/null; then
+    echo "[OK] npm registry reachable."
+else
+    echo "[WARN] Cannot reach npm registry, using China mirror."
+    USE_MIRROR=1
+fi
+
+if [ "$USE_MIRROR" = "1" ]; then
+    echo "[INFO] Using China mirror (npmmirror.com)"
+    MIRROR_REGISTRY="https://registry.npmmirror.com"
+    CDN_MIRROR="https://cdn.npmmirror.com/binaries"
+    export npm_config_registry="$MIRROR_REGISTRY"
+fi
+echo ""
+
+# ---- Check build tools (needed for native module fallback) ----
+if ! command -v gcc &>/dev/null && ! command -v clang &>/dev/null; then
+    echo "[INFO] No C compiler found. If CDN binaries are unavailable,"
+    echo "       native modules may fail. Install build tools:"
+    echo "       sudo apt install build-essential  (Ubuntu/Debian)"
+    echo "       sudo yum groupinstall 'Development Tools'  (CentOS/RHEL)"
+    echo ""
+fi
+
+# ---- Step 1: Install dependencies (skip GitHub binaries) ----
+echo "---- 1/5: Installing Node.js dependencies ----"
+echo ""
+
+cd "$PROJECT_DIR"
+npm install --registry="$MIRROR_REGISTRY" --ignore-scripts 2>&1 | tee -a "$LOG_FILE"
+echo "[OK] Dependencies installed."
+echo ""
+
+# ---- Step 2: Download native binaries from CDN ----
+echo "---- 2/5: Downloading 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)."
+fi
+echo ""
+
+# ---- Step 3: Install web panel dependencies ----
+echo "---- 3/5: Installing web panel dependencies ----"
+echo ""
+
+if [ -f "web/package.json" ]; then
+    cd "$PROJECT_DIR/web"
+    npm install --registry="$MIRROR_REGISTRY" 2>&1 | tee -a "$LOG_FILE"
+    cd "$PROJECT_DIR"
+    echo "[OK] Web panel dependencies installed."
+else
+    echo "[SKIP] web/package.json not found."
+fi
+echo ""
+
+# ---- Step 4: Build project ----
+echo "---- 4/5: Building project ----"
+echo ""
+
+npm run build 2>&1 | tee -a "$LOG_FILE"
+echo "[OK] Build succeeded."
+echo ""
+
+# ---- Step 5: Verify ----
+echo "---- 5/5: Verifying build ----"
+echo ""
+
+BUILD_OK=1
+if [ ! -d "dist" ]; then
+    echo "[ERROR] dist/ directory missing."
+    BUILD_OK=0
+fi
+if [ -d "web" ] && [ ! -d "web/dist" ]; then
+    echo "[ERROR] web/dist/ directory missing."
+    BUILD_OK=0
+fi
+
+if [ "$BUILD_OK" = "0" ]; then
+    echo "Build completed but expected output is missing."
+    exit 1
+fi
+echo "[OK] Build outputs verified."
+echo ""
+
+if [ ! -f "config.json" ]; then
+    echo "[INFO] config.json will be auto-generated on first launch."
+fi
+echo ""
+
+echo "============================================"
+echo "  Setup Complete!"
+echo "============================================"
+echo ""
+echo "Next steps:"
+echo "  1. Run:  npm start"
+echo "  2. Open: http://localhost:3000"
+echo ""
+echo "Setup log: $LOG_FILE"
+echo ""
+

scripts/start.bat

@@ -1,47 +1,44 @@
-@echo off
-title TSMusicBot
-echo Starting TSMusicBot...
-echo.
+@echo off
+title TSMusicBot
+echo Starting TSMusicBot...
+echo.
+
+:: Check if node is available
+where node >nul 2>&1
+if %errorlevel% neq 0 (
+    echo Node.js is not installed.
+    echo Run scripts\setup.bat first.
+    pause
+    exit /b 1
+)
+
+:: Resolve project root (one level up from scripts/)
+cd /d "%~dp0.."
+
+:: Check if dependencies are installed
+if not exist "node_modules" (
+    echo Dependencies not found. Please run scripts\setup.bat first.
+    pause
+    exit /b 1
+)
+
+:: Check if build output exists
+if not exist "dist" (
+    echo Build not found. Please run scripts\setup.bat first.
+    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 (
+    if exist "C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe" (
+        set "PATH=%PATH%;C:\Windows\System32\WindowsPowerShell\v1.0\"
+    )
+)
+
+:: Start the application
+node dist/index.js
+
+pause
 
-:: Check if node is available
-where node >nul 2>&1
-if %errorlevel% neq 0 (
-    echo Node.js is not installed.
-    echo Run scripts\setup.bat for automatic installation, or install Node.js 20+ from https://nodejs.org
-    pause
-    exit /b 1
-)
-
-:: Resolve project root (one level up from scripts/)
-cd /d "%~dp0.."
-
-:: Install dependencies if needed
-if not exist "node_modules" (
-    echo Installing dependencies...
-    call npm install --production
-    if %errorlevel% neq 0 (
-        echo Failed to install dependencies.
-        pause
-        exit /b 1
-    )
-)
-
-:: Build if dist/ doesn't exist
-if not exist "dist" (
-    echo Building project...
-    call npx tsc
-    if %errorlevel% neq 0 (
-        echo Build failed.
-        pause
-        exit /b 1
-    )
-)
-
-:: FFmpeg is bundled via ffmpeg-static — no PATH check needed.
-echo FFmpeg is bundled via node_modules (ffmpeg-static).
-echo.
-
-:: Start the application
-node dist/index.js
-
-pause

src/audio/player.ts

@@ -279,8 +279,12 @@ export class AudioPlayer extends EventEmitter {
       this.emit("error", err);
     });
 
+    // Mark playing but DO NOT start the frame loop here — the loop's
+    // "no ffmpeg + empty buffer → trackEnd" branch would fire on the very
+    // first tick, before the PowerShell download even completes. The
+    // frame loop is started inside spawnFfmpegFromFile() once ffmpeg is
+    // alive and producing PCM.
     this.state = "playing";
-    this.startFrameLoop();
   }
 
   private spawnFfmpegFromFile(tempFile: string, seekSeconds: number, sessionId: number): void {
@@ -329,6 +333,9 @@ export class AudioPlayer extends EventEmitter {
         this.emit("error", err);
       }
     });
+
+    // Now that ffmpeg is producing PCM, run the frame loop.
+    this.startFrameLoop();
   }
 
   stop(): void {

src/audio/queue.ts

@@ -22,6 +22,7 @@ export class PlayQueue {
   private mode: PlayMode = PlayMode.Sequential;
   private playedIndices = new Set<number>();
   private history: number[] = [];
+  private forwardStack: number[] = [];
   private static readonly HISTORY_LIMIT = 50;
 
   private pushHistory(idx: number): void {
@@ -100,12 +101,14 @@ export class PlayQueue {
     this.currentIndex = -1;
     this.playedIndices.clear();
     this.history = [];
+    this.forwardStack = [];
   }
 
   play(): QueuedSong | null {
     if (this.songs.length === 0) return null;
     this.playedIndices.clear();
     this.history = [];
+    this.forwardStack = [];
     this.currentIndex = 0;
     this.playedIndices.add(0);
     return this.songs[0];
@@ -118,6 +121,7 @@ export class PlayQueue {
     // shuffle from this point. History tracking is independent and
     // unaffected by this clear.
     this.playedIndices.clear();
+    this.forwardStack = [];
     this.currentIndex = index;
     this.playedIndices.add(index);
     return this.songs[index];
@@ -139,32 +143,45 @@ export class PlayQueue {
         this.currentIndex = (this.currentIndex + 1) % this.songs.length;
         return this.songs[this.currentIndex];
       }
-      case PlayMode.Random: {
-        const unplayed: number[] = [];
-        for (let i = 0; i < this.songs.length; i++) {
-          if (!this.playedIndices.has(i)) unplayed.push(i);
-        }
-        if (unplayed.length === 0) return null;
-        const nextIndex =
-          unplayed[Math.floor(Math.random() * unplayed.length)];
-        this.pushHistory(this.currentIndex);
-        this.currentIndex = nextIndex;
-        this.playedIndices.add(nextIndex);
-        return this.songs[nextIndex];
-      }
+      case PlayMode.Random:
       case PlayMode.RandomLoop: {
-        if (this.songs.length === 1) {
+        // 优先回到前进栈记录的位置（prev 退回的歌）
+        if (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 (this.mode === PlayMode.Random) {
+          const unplayed: number[] = [];
+          for (let i = 0; i < this.songs.length; i++) {
+            if (!this.playedIndices.has(i)) unplayed.push(i);
+          }
+          if (unplayed.length === 0) return null;
+          const nextIndex =
+            unplayed[Math.floor(Math.random() * unplayed.length)];
           this.pushHistory(this.currentIndex);
-          this.currentIndex = 0;
-          return this.songs[0];
+          this.currentIndex = nextIndex;
+          this.playedIndices.add(nextIndex);
+          return this.songs[nextIndex];
+        } else {
+          if (this.songs.length === 1) {
+            this.pushHistory(this.currentIndex);
+            this.currentIndex = 0;
+            return this.songs[0];
+          }
+          let idx: number;
+          do {
+            idx = Math.floor(Math.random() * this.songs.length);
+          } while (idx === this.currentIndex);
+          this.pushHistory(this.currentIndex);
+          this.currentIndex = idx;
+          return this.songs[idx];
         }
-        let idx: number;
-        do {
-          idx = Math.floor(Math.random() * this.songs.length);
-        } while (idx === this.currentIndex);
-        this.pushHistory(this.currentIndex);
-        this.currentIndex = idx;
-        return this.songs[idx];
       }
     }
   }
@@ -172,13 +189,18 @@ export class PlayQueue {
   prev(): QueuedSong | null {
     if (this.songs.length === 0) return null;
 
+    // 记录当前位置到前进栈，供 next 优先返回
+    if (this.currentIndex >= 0 && this.forwardStack.length < PlayQueue.HISTORY_LIMIT) {
+      this.forwardStack.push(this.currentIndex);
+    }
+
     // Preferred: pop from the back-stack so prev means "the song I
     // actually played before this one," not "the previous array slot."
     while (this.history.length > 0) {
       const idx = this.history.pop()!;
       if (idx >= 0 && idx < this.songs.length) {
         this.currentIndex = idx;
-        this.playedIndices.add(idx);
+        this.playedIndices = new Set([...this.history, this.currentIndex]);
         return this.songs[idx];
       }
       // Stale entry (song removed) — keep popping.
@@ -227,6 +249,7 @@ export class PlayQueue {
     this.mode = mode;
     this.playedIndices.clear();
     this.history = [];
+    this.forwardStack = [];
     if (this.currentIndex >= 0) {
       this.playedIndices.add(this.currentIndex);
     }

src/bot/instance.ts

@@ -16,6 +16,7 @@ import type { Logger } from "../logger.js";
 import type { BotDatabase, ProfileConfig } from "../data/database.js";
 import type { BotConfig } from "../data/config.js";
 import { BotProfileManager } from "./profile.js";
+import type { AvatarStore } from "../data/avatars.js";
 
 export interface BotInstanceOptions {
   id: string;
@@ -28,6 +29,7 @@ export interface BotInstanceOptions {
   database: BotDatabase;
   config: BotConfig;
   logger: Logger;
+  avatarStore: AvatarStore;
 }
 
 export interface BotStatus {
@@ -57,6 +59,7 @@ export class BotInstance extends EventEmitter {
   private database: BotDatabase;
   private config: BotConfig;
   private logger: Logger;
+  private avatarStore: AvatarStore;
   private connected = false;
   private disconnectEmitted = false;
   private voteSkipUsers = new Set<string>();
@@ -77,6 +80,7 @@ export class BotInstance extends EventEmitter {
     this.database = options.database;
     this.config = options.config;
     this.logger = options.logger.child({ botId: this.id });
+    this.avatarStore = options.avatarStore;
 
     this.tsClient = new TS3Client(options.tsOptions, this.logger);
     this.player = new AudioPlayer(this.logger);
@@ -90,6 +94,17 @@ export class BotInstance extends EventEmitter {
       options.tsOptions.nickname,
     );
 
+    // Best-effort: a corrupted/locked avatar file must not block bot startup.
+    try {
+      const relPath = this.database.getCustomAvatarPath(this.id);
+      if (relPath) {
+        const buf = this.avatarStore.read(relPath);
+        if (buf) this.profileManager.setCustomAvatar(buf);
+      }
+    } catch (err) {
+      this.logger.warn({ err }, "Failed to load custom avatar — skipping");
+    }
+
     this.setupPlayerEvents();
     this.setupTsEvents();
   }
@@ -623,9 +638,27 @@ export class BotInstance extends EventEmitter {
   }
 
   private async cmdAlbum(cmd: ParsedCommand): Promise<string> {
-    if (!cmd.args) return "Usage: !album <album ID>";
+    if (!cmd.args) return "Usage: !album <album name or ID>";
     const provider = this.getProvider(cmd.flags);
-    const songs = await provider.getAlbumSongs(cmd.args);
+
+    const id = this.extractId(cmd.args);
+    const isNumericId = /^\d+$/.test(cmd.args.trim());
+
+    let albumId: string;
+
+    if (isNumericId || id !== cmd.args) {
+      // Input is a numeric ID or URL containing an ID — use directly
+      albumId = id;
+    } else {
+      // Name-based search
+      const result = await provider.search(cmd.args);
+      const albums = result.albums ?? [];
+      if (albums.length === 0)
+        return `No albums found for: ${cmd.args}`;
+      albumId = albums[0].id;
+    }
+
+    const songs = await provider.getAlbumSongs(albumId);
     if (songs.length === 0) return "Album is empty or not found";
 
     this.queue.clear();
@@ -763,6 +796,7 @@ export class BotInstance extends EventEmitter {
       `${p}stop         — Stop and clear queue`,
       `${p}vol <0-100>  — Set volume`,
       `${p}queue        — Show queue`,
+      `${p}remove <pos> — Remove song at position (see ${p}queue)`,
       `${p}mode <seq|loop|random|rloop> — Play mode`,
       `${p}playlist <name or id> — Load playlist by name or ID`,
       `${p}playlist -q <name or id> — Load playlist from QQ Music`,

src/bot/manager.ts

@@ -11,6 +11,7 @@ import type { BotConfig } from "../data/config.js";
 import type { Logger } from "../logger.js";
 
 import type { ServerProtocol } from "../ts-protocol/client.js";
+import type { AvatarStore } from "../data/avatars.js";
 
 /**
  * Run bot.connect() with a hard deadline. If the handshake hangs (e.g. the
@@ -74,6 +75,7 @@ export class BotManager extends EventEmitter {
   private database: BotDatabase;
   private config: BotConfig;
   private logger: Logger;
+  private avatarStore: AvatarStore;
 
   constructor(
     neteaseProvider: MusicProvider,
@@ -81,7 +83,8 @@ export class BotManager extends EventEmitter {
     bilibiliProvider: MusicProvider,
     database: BotDatabase,
     config: BotConfig,
-    logger: Logger
+    logger: Logger,
+    avatarStore: AvatarStore
   ) {
     super();
     this.neteaseProvider = neteaseProvider;
@@ -91,6 +94,7 @@ export class BotManager extends EventEmitter {
     this.database = database;
     this.config = config;
     this.logger = logger;
+    this.avatarStore = avatarStore;
   }
 
   async createBot(params: CreateBotParams): Promise<BotInstance> {
@@ -117,6 +121,7 @@ export class BotManager extends EventEmitter {
       database: this.database,
       config: this.config,
       logger: this.logger,
+      avatarStore: this.avatarStore,
     });
 
     this.bots.set(id, bot);
@@ -229,10 +234,11 @@ export class BotManager extends EventEmitter {
         neteaseProvider: this.neteaseProvider,
         qqProvider: this.qqProvider,
         bilibiliProvider: this.bilibiliProvider,
-      youtubeProvider: this.youtubeProvider,
+        youtubeProvider: this.youtubeProvider,
         database: this.database,
         config: this.config,
         logger: this.logger,
+        avatarStore: this.avatarStore,
       });
       this.bots.set(id, bot);
       this.emit("botInstance", bot);
@@ -279,10 +285,11 @@ export class BotManager extends EventEmitter {
         neteaseProvider: this.neteaseProvider,
         qqProvider: this.qqProvider,
         bilibiliProvider: this.bilibiliProvider,
-      youtubeProvider: this.youtubeProvider,
+        youtubeProvider: this.youtubeProvider,
         database: this.database,
         config: this.config,
         logger: this.logger,
+        avatarStore: this.avatarStore,
       });
 
       this.bots.set(saved.id, bot);

src/bot/profile.test.ts

@@ -0,0 +1,147 @@
+import { describe, it, expect, beforeEach, vi } from "vitest";
+import { BotProfileManager } from "./profile.js";
+import type { TS3Client } from "../ts-protocol/client.js";
+import type { QueuedSong } from "../audio/queue.js";
+
+function makeMockTs(): TS3Client & {
+  uploadCalls: Buffer[];
+  clearCalls: number;
+} {
+  const calls: Buffer[] = [];
+  let clears = 0;
+  const ts: any = {
+    uploadCalls: calls,
+    get clearCalls() { return clears; },
+    getHost: () => "127.0.0.1",
+    getHttpQuery: () => null,
+    fileTransferInitUpload: vi.fn().mockResolvedValue({}),
+    uploadFileData: vi.fn().mockImplementation(async (_h: any, _i: any, stream: any) => {
+      const chunks: Buffer[] = [];
+      for await (const c of stream) chunks.push(c as Buffer);
+      calls.push(Buffer.concat(chunks));
+    }),
+    fileTransferDeleteFile: vi.fn().mockResolvedValue(undefined),
+    sendCommandNoWait: vi.fn().mockImplementation(async (cmd: string) => {
+      if (/client_flag_avatar=$/.test(cmd)) clears++;
+    }),
+  };
+  return ts;
+}
+
+const noopLogger: any = { child: () => noopLogger, info: () => {}, debug: () => {}, warn: () => {}, error: () => {} };
+
+const cfgOn = { avatarEnabled: true, descriptionEnabled: false, nicknameEnabled: false, awayStatusEnabled: false, channelDescEnabled: false, nowPlayingMsgEnabled: false };
+const cfgOff = { ...cfgOn, avatarEnabled: false };
+
+const fakeSong: QueuedSong = {
+  id: "1",
+  name: "X",
+  artist: "Y",
+  album: "Z",
+  platform: "netease",
+  url: "u",
+  coverUrl: "c",
+  duration: 100,
+};
+
+const flush = () => new Promise((r) => setImmediate(r));
+
+describe("BotProfileManager custom avatar precedence", () => {
+  let ts: ReturnType<typeof makeMockTs>;
+  beforeEach(() => { ts = makeMockTs(); });
+
+  it("setCustomAvatar uploads immediately on a fresh idle bot (sync on)", async () => {
+    const pm = new BotProfileManager(ts as any, noopLogger, cfgOn, "Bot");
+    pm.setCustomAvatar(Buffer.from([1, 2, 3]));
+    await flush();
+    expect(ts.uploadCalls.length).toBe(1);
+    expect(ts.uploadCalls[0].equals(Buffer.from([1, 2, 3]))).toBe(true);
+  });
+
+  it("setCustomAvatar uploads immediately when sync is off (always idle)", async () => {
+    const pm = new BotProfileManager(ts as any, noopLogger, cfgOff, "Bot");
+    pm.setCustomAvatar(Buffer.from([7]));
+    await flush();
+    expect(ts.uploadCalls.length).toBe(1);
+  });
+
+  it("setCustomAvatar while playing + sync on does NOT push (cover wins)", async () => {
+    const pm = new BotProfileManager(ts as any, noopLogger, cfgOn, "Bot");
+    // Simulate the bot playing a song. We can't actually run updateAvatar's
+    // full HTTP fetch path, but onSongChange records currentSong before
+    // updateAvatar runs, which is enough for this assertion.
+    void pm.onSongChange(fakeSong);
+    await flush();
+    const uploadsBefore = ts.uploadCalls.length;
+    pm.setCustomAvatar(Buffer.from([42]));
+    await flush();
+    expect(ts.uploadCalls.length).toBe(uploadsBefore); // no new upload
+  });
+
+  it("setCustomAvatar while playing + sync off DOES push (sync-off is idle)", async () => {
+    const pm = new BotProfileManager(ts as any, noopLogger, cfgOff, "Bot");
+    void pm.onSongChange(fakeSong);
+    await flush();
+    const uploadsBefore = ts.uploadCalls.length;
+    pm.setCustomAvatar(Buffer.from([42]));
+    await flush();
+    expect(ts.uploadCalls.length).toBe(uploadsBefore + 1);
+  });
+
+  it("setCustomAvatar(null) while idle clears the TS3 avatar", async () => {
+    const pm = new BotProfileManager(ts as any, noopLogger, cfgOn, "Bot");
+    pm.setCustomAvatar(Buffer.from([1]));
+    await flush();
+    const clearsBefore = ts.clearCalls;
+    pm.setCustomAvatar(null);
+    await flush();
+    expect(ts.clearCalls).toBe(clearsBefore + 1);
+  });
+
+  it("on stop with custom avatar set + sync on, restores custom (does not clear)", async () => {
+    const pm = new BotProfileManager(ts as any, noopLogger, cfgOn, "Bot");
+    pm.setCustomAvatar(Buffer.from([1, 2, 3, 4]));
+    await flush();
+    const clearsBefore = ts.clearCalls;
+    await pm.onSongChange(null);
+    expect(ts.uploadCalls.at(-1)?.equals(Buffer.from([1, 2, 3, 4]))).toBe(true);
+    expect(ts.clearCalls).toBe(clearsBefore); // no extra clear
+  });
+
+  it("on stop with no custom avatar, falls back to clear", async () => {
+    const pm = new BotProfileManager(ts as any, noopLogger, cfgOn, "Bot");
+    await pm.onSongChange(null);
+    expect(ts.clearCalls).toBe(1);
+    expect(ts.uploadCalls.length).toBe(0);
+  });
+
+  it("on connect with custom avatar set + sync ON, applies custom (spec matrix row 1)", async () => {
+    const pm = new BotProfileManager(ts as any, noopLogger, cfgOn, "Bot");
+    pm.setCustomAvatar(Buffer.from([5, 5]));
+    await flush();
+    ts.uploadCalls.length = 0; // reset
+    pm.onConnect();
+    await flush();
+    expect(ts.uploadCalls.length).toBe(1);
+    expect(ts.uploadCalls[0].equals(Buffer.from([5, 5]))).toBe(true);
+  });
+
+  it("on connect with custom avatar set + sync OFF, applies custom", async () => {
+    const pm = new BotProfileManager(ts as any, noopLogger, cfgOff, "Bot");
+    pm.setCustomAvatar(Buffer.from([9, 9]));
+    await flush();
+    ts.uploadCalls.length = 0;
+    pm.onConnect();
+    await flush();
+    expect(ts.uploadCalls.length).toBe(1);
+    expect(ts.uploadCalls[0].equals(Buffer.from([9, 9]))).toBe(true);
+  });
+
+  it("on connect with no custom avatar, does not touch avatar", async () => {
+    const pm = new BotProfileManager(ts as any, noopLogger, cfgOff, "Bot");
+    pm.onConnect();
+    await flush();
+    expect(ts.uploadCalls.length).toBe(0);
+    expect(ts.clearCalls).toBe(0);
+  });
+});

src/bot/profile.ts

@@ -25,6 +25,13 @@ export class BotProfileManager {
   private logger: Logger;
   private config: ProfileConfig;
   private defaultNickname: string;
+  private customAvatar: Buffer | null = null;
+  /**
+   * Tracks the last song handed to onSongChange. null means stopped/idle.
+   * Used by setCustomAvatar to decide whether the new buffer should be
+   * pushed immediately (idle) or wait for the next stop event (playing).
+   */
+  private currentSong: QueuedSong | null = null;
 
   /** Per-feature permission-denied flags. Reset on reconnect. */
   private permDenied = {
@@ -58,6 +65,26 @@ export class BotProfileManager {
 
   // --- Public API ---
 
+  /**
+   * Set/clear the persistent idle avatar. Pass null to remove.
+   *
+   * If the bot is currently in an idle state (no song playing OR
+   * avatarEnabled is off), the new buffer is pushed to TS3 right away;
+   * otherwise the cover-art sync is in charge until the next stop event,
+   * at which point clearAvatar restores from this.customAvatar.
+   */
+  setCustomAvatar(buffer: Buffer | null): void {
+    this.customAvatar = buffer;
+    const idle = this.currentSong === null || !this.config.avatarEnabled;
+    if (!idle) return;
+    const gen = ++this.generation;
+    if (buffer && buffer.length > 0) {
+      void this.applyIdleAvatar(gen);
+    } else {
+      void this.clearAvatar(gen);
+    }
+  }
+
   /**
    * Called when a new song starts playing (song != null) or playback
    * stops (song == null).
@@ -71,6 +98,7 @@ export class BotProfileManager {
    */
   async onSongChange(song: QueuedSong | null): Promise<void> {
     const gen = ++this.generation;
+    this.currentSong = song;
 
     // 1. Avatar first — file transfer uses its own response tracker and
     //    must run before sendCommandNoWait calls whose orphaned responses
@@ -91,6 +119,7 @@ export class BotProfileManager {
   /** Reset permission-denied flags and bump generation on new connection. */
   onConnect(): void {
     this.generation++;
+    this.currentSong = null;
     this.permDenied = {
       avatar: false,
       description: false,
@@ -99,6 +128,12 @@ export class BotProfileManager {
       channelDesc: false,
       nowPlayingMsg: false,
     };
+    // No song is playing on a fresh connect, so the matrix says the
+    // custom avatar should be visible regardless of avatarEnabled.
+    if (this.customAvatar) {
+      const gen = this.generation;
+      void this.applyIdleAvatar(gen);
+    }
   }
 
   getConfig(): ProfileConfig {
@@ -171,6 +206,10 @@ export class BotProfileManager {
   }
 
   private async clearAvatar(gen: number): Promise<void> {
+    if (this.customAvatar && this.customAvatar.length > 0) {
+      await this.applyIdleAvatar(gen);
+      return;
+    }
     try {
       await this.withTimeout(
         this.tsClient.fileTransferDeleteFile(0n, ["/avatar"]),
@@ -179,7 +218,6 @@ export class BotProfileManager {
     } catch {
       // File may not exist or transfer timed out — that's fine
     }
-    // Bail if a newer song started while we were deleting
     if (this.generation !== gen) return;
     try {
       await this.tsClient.sendCommandNoWait("clientupdate client_flag_avatar=");
@@ -188,6 +226,18 @@ export class BotProfileManager {
     }
   }
 
+  private async applyIdleAvatar(gen: number): Promise<void> {
+    if (!this.customAvatar || this.customAvatar.length === 0) return;
+    if (this.permDenied.avatar) return;
+    try {
+      await this.withTimeout(this.doAvatarUpload(this.customAvatar), FILE_TRANSFER_TIMEOUT_MS);
+      if (this.generation !== gen) return;
+      this.logger.info({ bytes: this.customAvatar.length }, "Idle (custom) avatar applied");
+    } catch (err) {
+      this.handleFeatureError("avatar", err);
+    }
+  }
+
   private async updateDescription(song: QueuedSong | null): Promise<void> {
     if (!this.config.descriptionEnabled || this.permDenied.description) return;
     try {

src/data/audit.test.ts

@@ -0,0 +1,58 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { createDatabase, type BotDatabase } from "./database.js";
+import { createAuditStore, type AuditStore } from "./audit.js";
+
+describe("AuditStore", () => {
+  let botDb: BotDatabase;
+  let audit: AuditStore;
+
+  beforeEach(() => {
+    botDb = createDatabase(":memory:");
+    audit = createAuditStore(botDb.db);
+  });
+
+  afterEach(() => botDb.close());
+
+  it("records and lists entries newest-first", async () => {
+    audit.record({
+      actorId: "a1", actorUsername: "alice",
+      targetUserId: "b1", targetUsername: "bob",
+      action: "user.created",
+    });
+    await new Promise((r) => setTimeout(r, 5));
+    audit.record({
+      actorId: "a1", actorUsername: "alice",
+      targetUserId: "b1", targetUsername: "bob",
+      action: "user.deleted",
+    });
+    const list = audit.list(10, 0);
+    expect(list).toHaveLength(2);
+    expect(list[0].action).toBe("user.deleted");
+    expect(list[1].action).toBe("user.created");
+  });
+
+  it("supports limit and offset", () => {
+    for (let i = 0; i < 5; i++) {
+      audit.record({
+        actorId: "a1", actorUsername: "alice",
+        targetUserId: null, targetUsername: null,
+        action: "user.password_changed",
+      });
+    }
+    expect(audit.list(2, 0)).toHaveLength(2);
+    expect(audit.list(2, 4)).toHaveLength(1);
+    expect(audit.list(10, 10)).toHaveLength(0);
+  });
+
+  it("stores nullable fields correctly", () => {
+    audit.record({
+      actorId: null, actorUsername: null,
+      targetUserId: "x", targetUsername: "deleted-user",
+      action: "admin.first_created",
+    });
+    const e = audit.list(1, 0)[0];
+    expect(e.actorId).toBeNull();
+    expect(e.actorUsername).toBeNull();
+    expect(e.targetUserId).toBe("x");
+  });
+});

src/data/audit.ts

@@ -0,0 +1,57 @@
+import type Database from "better-sqlite3";
+
+export type AuditAction =
+  | "admin.first_created"
+  | "user.created"
+  | "user.deleted"
+  | "user.password_reset"
+  | "user.password_changed"
+  | "user.role_changed";
+
+export interface AuditEntry {
+  id: number;
+  timestamp: number;
+  actorId: string | null;
+  actorUsername: string | null;
+  targetUserId: string | null;
+  targetUsername: string | null;
+  action: AuditAction;
+}
+
+export interface AuditRecordInput {
+  actorId: string | null;
+  actorUsername: string | null;
+  targetUserId: string | null;
+  targetUsername: string | null;
+  action: AuditAction;
+}
+
+export interface AuditStore {
+  record(input: AuditRecordInput): void;
+  list(limit: number, offset: number): AuditEntry[];
+}
+
+export function createAuditStore(db: Database.Database): AuditStore {
+  const insertStmt = db.prepare(
+    "INSERT INTO user_audit (timestamp, actorId, actorUsername, targetUserId, targetUsername, action) VALUES (?, ?, ?, ?, ?, ?)"
+  );
+  const listStmt = db.prepare(
+    "SELECT id, timestamp, actorId, actorUsername, targetUserId, targetUsername, action FROM user_audit ORDER BY timestamp DESC, id DESC LIMIT ? OFFSET ?"
+  );
+
+  return {
+    record(input) {
+      insertStmt.run(
+        Date.now(),
+        input.actorId,
+        input.actorUsername,
+        input.targetUserId,
+        input.targetUsername,
+        input.action
+      );
+    },
+    list(limit, offset) {
+      return listStmt.all(limit, offset) as AuditEntry[];
+    },
+  };
+}

src/data/avatars.test.ts

@@ -0,0 +1,61 @@
+import { describe, it, expect, beforeEach } from "vitest";
+import { mkdtempSync, rmSync, existsSync, readFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { createAvatarStore } from "./avatars.js";
+
+let dir: string;
+
+beforeEach(() => {
+  dir = mkdtempSync(join(tmpdir(), "avatar-test-"));
+});
+
+describe("createAvatarStore", () => {
+  it("write returns a relative path under the store dir", () => {
+    const store = createAvatarStore(dir);
+    const buf = Buffer.from("fake-png");
+    const rel = store.write("bot-1", "image/png", buf);
+    expect(rel).toBe("bot-1.png");
+    expect(readFileSync(join(dir, "bot-1.png")).equals(buf)).toBe(true);
+  });
+
+  it("write picks correct extension for jpeg / webp", () => {
+    const store = createAvatarStore(dir);
+    expect(store.write("a", "image/jpeg", Buffer.from(""))).toBe("a.jpg");
+    expect(store.write("b", "image/webp", Buffer.from(""))).toBe("b.webp");
+  });
+
+  it("write rejects unsupported MIME types", () => {
+    const store = createAvatarStore(dir);
+    expect(() => store.write("c", "image/gif", Buffer.from(""))).toThrow(/unsupported/i);
+  });
+
+  it("read returns the bytes for an existing file", () => {
+    const store = createAvatarStore(dir);
+    store.write("bot-1", "image/png", Buffer.from("hello"));
+    const buf = store.read("bot-1.png");
+    expect(buf?.equals(Buffer.from("hello"))).toBe(true);
+  });
+
+  it("read returns null when path is missing", () => {
+    const store = createAvatarStore(dir);
+    expect(store.read("missing.png")).toBeNull();
+  });
+
+  it("remove deletes the file (idempotent)", () => {
+    const store = createAvatarStore(dir);
+    store.write("bot-1", "image/png", Buffer.from("x"));
+    store.remove("bot-1.png");
+    expect(existsSync(join(dir, "bot-1.png"))).toBe(false);
+    expect(() => store.remove("bot-1.png")).not.toThrow();
+  });
+
+  it("write replaces any existing file for the same botId regardless of old extension", () => {
+    const store = createAvatarStore(dir);
+    store.write("bot-1", "image/png", Buffer.from("old"));
+    const rel = store.write("bot-1", "image/jpeg", Buffer.from("new"));
+    expect(rel).toBe("bot-1.jpg");
+    expect(existsSync(join(dir, "bot-1.png"))).toBe(false);
+    expect(existsSync(join(dir, "bot-1.jpg"))).toBe(true);
+  });
+});

src/data/avatars.ts

@@ -0,0 +1,43 @@
+import { mkdirSync, writeFileSync, readFileSync, rmSync, readdirSync, existsSync } from "node:fs";
+import { join } from "node:path";
+
+const MIME_TO_EXT: Record<string, string> = {
+  "image/png": "png",
+  "image/jpeg": "jpg",
+  "image/webp": "webp",
+};
+
+export interface AvatarStore {
+  /** Returns the relative path written (e.g. "bot-1.png"). */
+  write(botId: string, mime: string, buffer: Buffer): string;
+  read(relPath: string): Buffer | null;
+  remove(relPath: string): void;
+  getDir(): string;
+}
+
+export function createAvatarStore(dir: string): AvatarStore {
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+  return {
+    write(botId, mime, buffer) {
+      const ext = MIME_TO_EXT[mime];
+      if (!ext) throw new Error(`unsupported avatar MIME: ${mime}`);
+      for (const name of readdirSync(dir)) {
+        if (name.startsWith(`${botId}.`)) rmSync(join(dir, name), { force: true });
+      }
+      const rel = `${botId}.${ext}`;
+      writeFileSync(join(dir, rel), buffer);
+      return rel;
+    },
+    read(relPath) {
+      const full = join(dir, relPath);
+      if (!existsSync(full)) return null;
+      return readFileSync(full);
+    },
+    remove(relPath) {
+      rmSync(join(dir, relPath), { force: true });
+    },
+    getDir() {
+      return dir;
+    },
+  };
+}

src/data/database.test.ts

@@ -23,6 +23,30 @@ describe("database", () => {
     expect(names).toContain("bot_instances");
   });
 
+  it("creates users and sessions tables on init", () => {
+    const tables = botDb.db
+      .prepare("SELECT name FROM sqlite_master WHERE type='table' ORDER BY name")
+      .all() as Array<{ name: string }>;
+    const names = tables.map((t) => t.name);
+    expect(names).toContain("users");
+    expect(names).toContain("sessions");
+
+    const userCols = botDb.db.prepare("PRAGMA table_info(users)").all() as Array<{ name: string }>;
+    const userColNames = userCols.map((c) => c.name).sort();
+    expect(userColNames).toEqual(["createdAt", "id", "passwordHash", "role", "updatedAt", "username"]);
+
+    const sessionCols = botDb.db.prepare("PRAGMA table_info(sessions)").all() as Array<{ name: string }>;
+    const sessionColNames = sessionCols.map((c) => c.name).sort();
+    expect(sessionColNames).toEqual(["createdAt", "expiresAt", "id", "lastSeenAt", "userId"]);
+  });
+
+  it("creates user_audit table on init", () => {
+    const tables = botDb.db
+      .prepare("SELECT name FROM sqlite_master WHERE type='table' ORDER BY name")
+      .all() as Array<{ name: string }>;
+    expect(tables.map((t) => t.name)).toContain("user_audit");
+  });
+
   it("records and retrieves play history", () => {
     botDb.addPlayHistory({
       botId: "bot1",
@@ -98,4 +122,26 @@ describe("database", () => {
     expect(botDb.getBotInstances()).toHaveLength(0);
     expect(botDb.deleteBotInstance("nonexistent")).toBe(false);
   });
+
+  it("persists and clears customAvatarPath on a bot instance", () => {
+    const inst = {
+      id: "bot-1",
+      name: "B",
+      serverAddress: "x",
+      serverPort: 9987,
+      nickname: "n",
+      defaultChannel: "",
+      channelPassword: "",
+      autoStart: false,
+      serverProtocol: "",
+      ts6ApiKey: "",
+      serverPassword: "",
+    };
+    botDb.saveBotInstance(inst);
+    expect(botDb.getCustomAvatarPath("bot-1")).toBeNull();
+    botDb.setCustomAvatarPath("bot-1", "avatars/bot-1.png");
+    expect(botDb.getCustomAvatarPath("bot-1")).toBe("avatars/bot-1.png");
+    botDb.setCustomAvatarPath("bot-1", null);
+    expect(botDb.getCustomAvatarPath("bot-1")).toBeNull();
+  });
 });

src/data/database.ts

@@ -60,6 +60,8 @@ export interface BotDatabase {
   deleteBotInstance(id: string): boolean;
   getProfileConfig(botId: string): ProfileConfig;
   saveProfileConfig(botId: string, config: ProfileConfig): void;
+  getCustomAvatarPath(botId: string): string | null;
+  setCustomAvatarPath(botId: string, path: string | null): void;
   close(): void;
 }
 
@@ -92,6 +94,15 @@ function migrateSchema(db: Database.Database): void {
       db.exec(`ALTER TABLE bot_instances ADD COLUMN ${col} INTEGER NOT NULL DEFAULT 1`);
     }
   }
+  if (!names.includes("custom_avatar_path")) {
+    db.exec("ALTER TABLE bot_instances ADD COLUMN custom_avatar_path TEXT");
+  }
+
+  const userColumns = db.prepare("PRAGMA table_info(users)").all() as Array<{ name: string }>;
+  const userColNames = userColumns.map((c) => c.name);
+  if (!userColNames.includes("role")) {
+    db.exec("ALTER TABLE users ADD COLUMN role TEXT NOT NULL DEFAULT 'admin'");
+  }
 }
 
 function initTables(db: Database.Database): void {
@@ -122,12 +133,45 @@ function initTables(db: Database.Database): void {
       serverPassword TEXT NOT NULL DEFAULT '',
       identity TEXT
     );
+
+    CREATE TABLE IF NOT EXISTS users (
+      id TEXT PRIMARY KEY,
+      username TEXT NOT NULL UNIQUE COLLATE NOCASE,
+      passwordHash TEXT NOT NULL,
+      createdAt INTEGER NOT NULL,
+      updatedAt INTEGER NOT NULL,
+      role TEXT NOT NULL DEFAULT 'admin'
+    );
+
+    CREATE TABLE IF NOT EXISTS sessions (
+      id TEXT PRIMARY KEY,
+      userId TEXT NOT NULL,
+      createdAt INTEGER NOT NULL,
+      expiresAt INTEGER NOT NULL,
+      lastSeenAt INTEGER NOT NULL,
+      FOREIGN KEY (userId) REFERENCES users(id) ON DELETE CASCADE
+    );
+
+    CREATE INDEX IF NOT EXISTS idx_sessions_userId ON sessions(userId);
+    CREATE INDEX IF NOT EXISTS idx_sessions_expiresAt ON sessions(expiresAt);
+
+    CREATE TABLE IF NOT EXISTS user_audit (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      timestamp INTEGER NOT NULL,
+      actorId TEXT,
+      actorUsername TEXT,
+      targetUserId TEXT,
+      targetUsername TEXT,
+      action TEXT NOT NULL
+    );
+    CREATE INDEX IF NOT EXISTS idx_user_audit_timestamp ON user_audit(timestamp DESC);
   `);
 }
 
 export function createDatabase(dbPath: string): BotDatabase {
   const db = new Database(dbPath);
   db.pragma("journal_mode = WAL");
+  db.pragma("foreign_keys = ON");
   initTables(db);
   migrateSchema(db);
 
@@ -179,6 +223,9 @@ export function createDatabase(dbPath: string): BotDatabase {
     WHERE id = @id
   `);
 
+  const selectCustomAvatar = db.prepare(`SELECT custom_avatar_path FROM bot_instances WHERE id = ?`);
+  const updateCustomAvatar = db.prepare(`UPDATE bot_instances SET custom_avatar_path = ? WHERE id = ?`);
+
   return {
     db,
 
@@ -242,6 +289,14 @@ export function createDatabase(dbPath: string): BotDatabase {
       });
     },
 
+    getCustomAvatarPath(botId) {
+      const row = selectCustomAvatar.get(botId) as { custom_avatar_path: string | null } | undefined;
+      return row?.custom_avatar_path ?? null;
+    },
+    setCustomAvatarPath(botId, path) {
+      updateCustomAvatar.run(path, botId);
+    },
+
     close() {
       db.close();
     },

src/data/sessions.test.ts

@@ -0,0 +1,128 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
+import { createHash } from "node:crypto";
+import { createDatabase, type BotDatabase } from "./database.js";
+import { createUserStore, type UserStore } from "./users.js";
+import { createSessionStore, type SessionStore, SESSION_TTL_MS, SESSION_TOUCH_INTERVAL_MS, MAX_SESSIONS_PER_USER } from "./sessions.js";
+
+function sha256(token: string) {
+  return createHash("sha256").update(token).digest("hex");
+}
+
+describe("SessionStore", () => {
+  let botDb: BotDatabase;
+  let users: UserStore;
+  let sessions: SessionStore;
+  let userId: string;
+
+  beforeEach(async () => {
+    botDb = createDatabase(":memory:");
+    users = createUserStore(botDb.db);
+    sessions = createSessionStore(botDb.db);
+    const u = await users.createUser("alice", "pw-alice", "admin");
+    userId = u.id;
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+    botDb.close();
+  });
+
+  it("createSession returns a raw token whose sha256 matches the DB row id", () => {
+    const { token } = sessions.createSession(userId);
+    const row = botDb.db.prepare("SELECT id FROM sessions").get() as { id: string };
+    expect(row.id).toBe(sha256(token));
+    expect(row.id).not.toBe(token);
+  });
+
+  it("validateAndTouch returns the user for a fresh token", () => {
+    const { token } = sessions.createSession(userId);
+    const result = sessions.validateAndTouch(token);
+    expect(result).not.toBeNull();
+    expect(result!.userId).toBe(userId);
+    expect(result!.username).toBe("alice");
+    expect(result!.role).toBe("admin");
+  });
+
+  it("validateAndTouch returns null and deletes the row for an expired session", () => {
+    vi.useFakeTimers();
+    vi.setSystemTime(new Date("2026-01-01T00:00:00Z"));
+    const { token } = sessions.createSession(userId);
+    vi.setSystemTime(new Date("2026-01-01T00:00:00Z").getTime() + SESSION_TTL_MS + 1000);
+    expect(sessions.validateAndTouch(token)).toBeNull();
+    const remaining = (botDb.db.prepare("SELECT COUNT(*) AS n FROM sessions").get() as { n: number }).n;
+    expect(remaining).toBe(0);
+  });
+
+  it("validateAndTouch does not write the DB if called again within the touch interval", () => {
+    vi.useFakeTimers();
+    vi.setSystemTime(new Date("2026-01-01T00:00:00Z"));
+    const { token } = sessions.createSession(userId);
+    const before = botDb.db.prepare("SELECT lastSeenAt FROM sessions").get() as { lastSeenAt: number };
+    vi.advanceTimersByTime(SESSION_TOUCH_INTERVAL_MS - 1000);
+    sessions.validateAndTouch(token);
+    const after = botDb.db.prepare("SELECT lastSeenAt FROM sessions").get() as { lastSeenAt: number };
+    expect(after.lastSeenAt).toBe(before.lastSeenAt);
+  });
+
+  it("validateAndTouch writes lastSeenAt and extends expiresAt past the touch interval", () => {
+    vi.useFakeTimers();
+    vi.setSystemTime(new Date("2026-01-01T00:00:00Z"));
+    const { token, expiresAt: initialExpiry } = sessions.createSession(userId);
+    vi.advanceTimersByTime(SESSION_TOUCH_INTERVAL_MS + 1000);
+    sessions.validateAndTouch(token);
+    const row = botDb.db.prepare("SELECT lastSeenAt, expiresAt FROM sessions").get() as { lastSeenAt: number; expiresAt: number };
+    expect(row.lastSeenAt).toBe(Date.now());
+    expect(row.expiresAt).toBeGreaterThan(initialExpiry);
+  });
+
+  it("deleteSession removes the row", () => {
+    const { token } = sessions.createSession(userId);
+    sessions.deleteSession(token);
+    const remaining = (botDb.db.prepare("SELECT COUNT(*) AS n FROM sessions").get() as { n: number }).n;
+    expect(remaining).toBe(0);
+    expect(sessions.validateAndTouch(token)).toBeNull();
+  });
+
+  it("deleteAllForUser keeps the exceptToken session", () => {
+    const a = sessions.createSession(userId);
+    const b = sessions.createSession(userId);
+    sessions.deleteAllForUser(userId, a.token);
+    expect(sessions.validateAndTouch(a.token)).not.toBeNull();
+    expect(sessions.validateAndTouch(b.token)).toBeNull();
+  });
+
+  it("cleanupExpired removes only expired rows", () => {
+    vi.useFakeTimers();
+    vi.setSystemTime(new Date("2026-01-01T00:00:00Z"));
+    sessions.createSession(userId); // expires later
+    vi.setSystemTime(new Date("2026-01-01T00:00:00Z").getTime() + SESSION_TTL_MS + 1000);
+    sessions.createSession(userId); // fresh
+    sessions.cleanupExpired();
+    const remaining = (botDb.db.prepare("SELECT COUNT(*) AS n FROM sessions").get() as { n: number }).n;
+    expect(remaining).toBe(1);
+  });
+
+  it("createSession caps concurrent sessions per user at MAX_SESSIONS_PER_USER, evicting oldest", async () => {
+    // Create MAX + 2 sessions for the same user.
+    const tokens: string[] = [];
+    for (let i = 0; i < MAX_SESSIONS_PER_USER + 2; i++) {
+      tokens.push(sessions.createSession(userId).token);
+      await new Promise((r) => setTimeout(r, 2)); // stagger createdAt
+    }
+    const count = (botDb.db.prepare("SELECT COUNT(*) AS n FROM sessions").get() as { n: number }).n;
+    expect(count).toBe(MAX_SESSIONS_PER_USER);
+    // The first two should have been evicted, the last MAX remain
+    expect(sessions.validateAndTouch(tokens[0])).toBeNull();
+    expect(sessions.validateAndTouch(tokens[1])).toBeNull();
+    expect(sessions.validateAndTouch(tokens[tokens.length - 1])).not.toBeNull();
+  });
+
+  it("createSession respects cap under concurrent calls (no 1-over-cap race)", async () => {
+    // better-sqlite3 transactions are serialised at the engine level. Calling
+    // createSession N times sequentially via Promise.all proves atomic check+insert.
+    const N = MAX_SESSIONS_PER_USER + 3;
+    await Promise.all(Array.from({ length: N }, () => Promise.resolve(sessions.createSession(userId))));
+    const count = (botDb.db.prepare("SELECT COUNT(*) AS n FROM sessions").get() as { n: number }).n;
+    expect(count).toBe(MAX_SESSIONS_PER_USER);
+  });
+});

src/data/sessions.ts

@@ -0,0 +1,104 @@
+import { createHash, randomBytes } from "node:crypto";
+import type Database from "better-sqlite3";
+
+export const SESSION_TTL_MS = 7 * 24 * 60 * 60 * 1000; // 7 days
+export const SESSION_TOUCH_INTERVAL_MS = 60 * 60 * 1000; // 1 hour
+export const MAX_SESSIONS_PER_USER = 10;
+
+export interface SessionValidation {
+  userId: string;
+  username: string;
+  role: "admin" | "member";
+}
+
+export interface SessionStore {
+  createSession(userId: string): { token: string; expiresAt: number };
+  validateAndTouch(rawToken: string): SessionValidation | null;
+  deleteSession(rawToken: string): void;
+  deleteAllForUser(userId: string, exceptToken?: string): void;
+  cleanupExpired(): void;
+}
+
+function hashToken(token: string): string {
+  return createHash("sha256").update(token).digest("hex");
+}
+
+export function createSessionStore(db: Database.Database): SessionStore {
+  const insertStmt = db.prepare(
+    "INSERT INTO sessions (id, userId, createdAt, expiresAt, lastSeenAt) VALUES (?, ?, ?, ?, ?)"
+  );
+  const selectStmt = db.prepare(`
+    SELECT s.id, s.userId, s.expiresAt, s.lastSeenAt, u.username, u.role
+    FROM sessions s INNER JOIN users u ON u.id = s.userId
+    WHERE s.id = ?
+  `);
+  const deleteByIdStmt = db.prepare("DELETE FROM sessions WHERE id = ?");
+  const touchStmt = db.prepare(
+    "UPDATE sessions SET lastSeenAt = ?, expiresAt = ? WHERE id = ?"
+  );
+  const deleteAllForUserStmt = db.prepare("DELETE FROM sessions WHERE userId = ?");
+  const deleteAllForUserExceptStmt = db.prepare(
+    "DELETE FROM sessions WHERE userId = ? AND id != ?"
+  );
+  const cleanupStmt = db.prepare("DELETE FROM sessions WHERE expiresAt < ?");
+  const countForUserStmt = db.prepare("SELECT COUNT(*) AS n FROM sessions WHERE userId = ?");
+  const deleteOldestForUserStmt = db.prepare(
+    "DELETE FROM sessions WHERE id IN (SELECT id FROM sessions WHERE userId = ? ORDER BY createdAt ASC LIMIT ?)"
+  );
+
+  return {
+    createSession(userId) {
+      // Cap concurrent sessions per user — oldest gets evicted on overflow.
+      // Wrap the count → delete → insert in a transaction so concurrent logins
+      // for the same user can't both pass the cap check and both insert,
+      // ending up 1 over cap (race window between count and insert).
+      const token = randomBytes(32).toString("base64url");
+      const id = hashToken(token);
+      const now = Date.now();
+      const expiresAt = now + SESSION_TTL_MS;
+      const tx = db.transaction(() => {
+        const existing = (countForUserStmt.get(userId) as { n: number }).n;
+        if (existing >= MAX_SESSIONS_PER_USER) {
+          deleteOldestForUserStmt.run(userId, existing - MAX_SESSIONS_PER_USER + 1);
+        }
+        insertStmt.run(id, userId, now, expiresAt, now);
+      });
+      tx();
+      return { token, expiresAt };
+    },
+
+    validateAndTouch(rawToken) {
+      if (!rawToken) return null;
+      const id = hashToken(rawToken);
+      const row = selectStmt.get(id) as
+        | { id: string; userId: string; expiresAt: number; lastSeenAt: number; username: string; role: string }
+        | undefined;
+      if (!row) return null;
+      const now = Date.now();
+      if (row.expiresAt < now) {
+        deleteByIdStmt.run(id);
+        return null;
+      }
+      if (now - row.lastSeenAt > SESSION_TOUCH_INTERVAL_MS) {
+        touchStmt.run(now, now + SESSION_TTL_MS, id);
+      }
+      return { userId: row.userId, username: row.username, role: row.role as "admin" | "member" };
+    },
+
+    deleteSession(rawToken) {
+      deleteByIdStmt.run(hashToken(rawToken));
+    },
+
+    deleteAllForUser(userId, exceptToken) {
+      if (exceptToken) {
+        deleteAllForUserExceptStmt.run(userId, hashToken(exceptToken));
+      } else {
+        deleteAllForUserStmt.run(userId);
+      }
+    },
+
+    cleanupExpired() {
+      cleanupStmt.run(Date.now());
+    },
+  };
+}

src/data/users.test.ts

@@ -0,0 +1,186 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { createDatabase, type BotDatabase } from "./database.js";
+import { createUserStore, UsernameTakenError, type UserStore } from "./users.js";
+
+describe("UserStore", () => {
+  let botDb: BotDatabase;
+  let users: UserStore;
+
+  beforeEach(() => {
+    botDb = createDatabase(":memory:");
+    users = createUserStore(botDb.db);
+  });
+
+  afterEach(() => {
+    botDb.close();
+  });
+
+  it("countUsers is 0 on a fresh db", () => {
+    expect(users.countUsers()).toBe(0);
+  });
+
+  it("createUser stores the user and bumps countUsers", async () => {
+    const u = await users.createUser("alice", "pw-hunter2", "member");
+    expect(u.id).toMatch(/^[0-9a-f-]{36}$/);
+    expect(u.username).toBe("alice");
+    expect(users.countUsers()).toBe(1);
+  });
+
+  it("findByUsername is case-insensitive and returns null for missing", async () => {
+    await users.createUser("Alice", "pw-alice", "member");
+    expect(users.findByUsername("ALICE")).not.toBeNull();
+    expect(users.findByUsername("alice")).not.toBeNull();
+    expect(users.findByUsername("bob")).toBeNull();
+  });
+
+  it("createUser rejects duplicate usernames (case-insensitive)", async () => {
+    await users.createUser("Alice", "pw-alice", "member");
+    await expect(users.createUser("alice", "pw-alice-2", "member")).rejects.toBeInstanceOf(UsernameTakenError);
+  });
+
+  it("verifyPassword accepts correct password and rejects wrong one", async () => {
+    await users.createUser("alice", "correct-horse-battery-staple", "member");
+    const row = users.findByUsername("alice");
+    expect(row).not.toBeNull();
+    expect(await users.verifyPassword("correct-horse-battery-staple", row!.passwordHash)).toBe(true);
+    expect(await users.verifyPassword("wrong", row!.passwordHash)).toBe(false);
+  });
+
+  it("changePassword updates the hash so the old password no longer verifies", async () => {
+    const u = await users.createUser("alice", "old-pw-pw", "member");
+    await users.changePassword(u.id, "new-pw-pw");
+    const row = users.findByUsername("alice");
+    expect(await users.verifyPassword("old-pw-pw", row!.passwordHash)).toBe(false);
+    expect(await users.verifyPassword("new-pw-pw", row!.passwordHash)).toBe(true);
+  });
+
+  it("listUsers returns id+username+createdAt ascending, no password hash", async () => {
+    await users.createUser("alice", "pw-alice", "member");
+    await users.createUser("bob", "pw-bob-bob", "member");
+    const list = users.listUsers();
+    expect(list).toHaveLength(2);
+    expect(list[0].username).toBe("alice");
+    expect(list[1].username).toBe("bob");
+    expect(list[0]).not.toHaveProperty("passwordHash");
+    expect(list[0].id).toMatch(/^[0-9a-f-]{36}$/);
+    expect(typeof list[0].createdAt).toBe("number");
+  });
+
+  it("deleteUser removes the row and returns true; returns false for unknown id", async () => {
+    const u = await users.createUser("alice", "pw-alice", "member");
+    expect(users.deleteUser(u.id)).toBe(true);
+    expect(users.countUsers()).toBe(0);
+    expect(users.deleteUser("not-a-real-id")).toBe(false);
+  });
+
+  it("createFirstUser succeeds on empty db, returns null when a user already exists", async () => {
+    const a = await users.createFirstUser("alice", "pw-alice");
+    expect(a).not.toBeNull();
+    expect(a!.username).toBe("alice");
+    const b = await users.createFirstUser("bob", "pw-bob-bob");
+    expect(b).toBeNull();
+    expect(users.countUsers()).toBe(1);
+  });
+
+  it("createFirstUser is race-safe: concurrent calls produce exactly one user", async () => {
+    const [a, b, c] = await Promise.all([
+      users.createFirstUser("alice", "pw-alice"),
+      users.createFirstUser("bob", "pw-bob-bob"),
+      users.createFirstUser("charlie", "pw-charlie-pw"),
+    ]);
+    const created = [a, b, c].filter((u) => u !== null);
+    expect(created).toHaveLength(1);
+    expect(users.countUsers()).toBe(1);
+  });
+
+  it("createFirstUser always creates an admin", async () => {
+    const u = await users.createFirstUser("alice", "pw-alice");
+    expect(u).not.toBeNull();
+    expect(u!.role).toBe("admin");
+  });
+
+  it("countAdmins reflects only role=admin", async () => {
+    await users.createUser("alice", "pw-alice", "admin");
+    await users.createUser("bob", "pw-bob-bob", "member");
+    expect(users.countUsers()).toBe(2);
+    expect(users.countAdmins()).toBe(1);
+  });
+
+  it("setRole changes the role and returns true; false for unknown id", async () => {
+    const u = await users.createUser("alice", "pw-alice", "member");
+    expect(users.setRole(u.id, "admin")).toBe(true);
+    expect(users.findById(u.id)!.role).toBe("admin");
+    expect(users.setRole("nope", "admin")).toBe(false);
+  });
+
+  it("listUsers includes role", async () => {
+    await users.createUser("alice", "pw-alice", "admin");
+    await users.createUser("bob", "pw-bob-bob", "member");
+    const list = users.listUsers();
+    const alice = list.find((u) => u.username === "alice")!;
+    const bob = list.find((u) => u.username === "bob")!;
+    expect(alice.role).toBe("admin");
+    expect(bob.role).toBe("member");
+  });
+
+  it("setRoleIfNotLastAdmin returns 'would_orphan' for the only admin being demoted", async () => {
+    const alice = await users.createUser("alice", "pw-alice", "admin");
+    expect(users.setRoleIfNotLastAdmin(alice.id, "member")).toBe("would_orphan");
+    expect(users.findById(alice.id)!.role).toBe("admin"); // unchanged
+  });
+
+  it("setRoleIfNotLastAdmin allows demotion when another admin exists", async () => {
+    const alice = await users.createUser("alice", "pw-alice", "admin");
+    await users.createUser("bob", "pw-bob-bob", "admin");
+    expect(users.setRoleIfNotLastAdmin(alice.id, "member")).toBe("ok");
+    expect(users.findById(alice.id)!.role).toBe("member");
+  });
+
+  it("setRoleIfNotLastAdmin returns 'not_found' for unknown id", () => {
+    expect(users.setRoleIfNotLastAdmin("not-a-real-id", "member")).toBe("not_found");
+  });
+
+  it("setRoleIfNotLastAdmin: concurrent demotions of two admins keep one admin", async () => {
+    const alice = await users.createUser("alice", "pw-alice", "admin");
+    const bob = await users.createUser("bob", "pw-bob-bob", "admin");
+    // Concurrent demotion of both
+    const [r1, r2] = await Promise.all([
+      Promise.resolve(users.setRoleIfNotLastAdmin(alice.id, "member")),
+      Promise.resolve(users.setRoleIfNotLastAdmin(bob.id, "member")),
+    ]);
+    // Exactly one should succeed; the other gets "would_orphan"
+    const oks = [r1, r2].filter((r) => r === "ok").length;
+    const orphans = [r1, r2].filter((r) => r === "would_orphan").length;
+    expect(oks).toBe(1);
+    expect(orphans).toBe(1);
+    // System retains at least one admin
+    expect(users.countAdmins()).toBe(1);
+  });
+
+  it("deleteUserIfNotLastAdmin returns 'would_orphan' for the only admin", async () => {
+    const alice = await users.createUser("alice", "pw-alice", "admin");
+    expect(users.deleteUserIfNotLastAdmin(alice.id)).toBe("would_orphan");
+    expect(users.findById(alice.id)).not.toBeNull();
+  });
+
+  it("deleteUserIfNotLastAdmin allows deleting a member at any count", async () => {
+    await users.createUser("alice", "pw-alice", "admin");
+    const bob = await users.createUser("bob", "pw-bob-bob", "member");
+    expect(users.deleteUserIfNotLastAdmin(bob.id)).toBe("ok");
+    expect(users.findById(bob.id)).toBeNull();
+  });
+
+  it("deleteUserIfNotLastAdmin: concurrent deletes of two admins keep one admin", async () => {
+    const alice = await users.createUser("alice", "pw-alice", "admin");
+    const bob = await users.createUser("bob", "pw-bob-bob", "admin");
+    const [r1, r2] = await Promise.all([
+      Promise.resolve(users.deleteUserIfNotLastAdmin(alice.id)),
+      Promise.resolve(users.deleteUserIfNotLastAdmin(bob.id)),
+    ]);
+    const oks = [r1, r2].filter((r) => r === "ok").length;
+    const orphans = [r1, r2].filter((r) => r === "would_orphan").length;
+    expect(oks).toBe(1);
+    expect(orphans).toBe(1);
+    expect(users.countAdmins()).toBe(1);
+  });
+});

src/data/users.ts

@@ -0,0 +1,168 @@
+import { randomUUID } from "node:crypto";
+import type Database from "better-sqlite3";
+import bcrypt from "bcryptjs";
+
+const BCRYPT_ROUNDS = 12;
+
+export type UserRole = "admin" | "member";
+
+export interface UserRow {
+  id: string;
+  username: string;
+  passwordHash: string;
+  createdAt: number;
+  updatedAt: number;
+  role: UserRole;
+}
+
+export interface UserStore {
+  countUsers(): number;
+  countAdmins(): number;
+  createUser(username: string, password: string, role: UserRole): Promise<UserRow>;
+  createFirstUser(username: string, password: string): Promise<UserRow | null>;
+  findByUsername(username: string): UserRow | null;
+  findById(id: string): UserRow | null;
+  verifyPassword(plain: string, hash: string): Promise<boolean>;
+  changePassword(userId: string, newPassword: string): Promise<void>;
+  setRole(userId: string, role: UserRole): boolean;
+  setRoleIfNotLastAdmin(id: string, newRole: UserRole): "ok" | "not_found" | "would_orphan";
+  deleteUser(id: string): boolean;
+  deleteUserIfNotLastAdmin(id: string): "ok" | "not_found" | "would_orphan";
+  listUsers(): Array<{ id: string; username: string; createdAt: number; role: UserRole }>;
+}
+
+export class UsernameTakenError extends Error {
+  constructor(username: string) {
+    super(`username taken: ${username}`);
+    this.name = "UsernameTakenError";
+  }
+}
+
+export function createUserStore(db: Database.Database): UserStore {
+  const countStmt = db.prepare("SELECT COUNT(*) AS n FROM users");
+  const countAdminsStmt = db.prepare("SELECT COUNT(*) AS n FROM users WHERE role = 'admin'");
+  const insertStmt = db.prepare(
+    "INSERT INTO users (id, username, passwordHash, createdAt, updatedAt, role) VALUES (?, ?, ?, ?, ?, ?)"
+  );
+  const findByUsernameStmt = db.prepare(
+    "SELECT id, username, passwordHash, createdAt, updatedAt, role FROM users WHERE username = ? COLLATE NOCASE"
+  );
+  const findByIdStmt = db.prepare(
+    "SELECT id, username, passwordHash, createdAt, updatedAt, role FROM users WHERE id = ?"
+  );
+  const updatePasswordStmt = db.prepare(
+    "UPDATE users SET passwordHash = ?, updatedAt = ? WHERE id = ?"
+  );
+  const updateRoleStmt = db.prepare(
+    "UPDATE users SET role = ?, updatedAt = ? WHERE id = ?"
+  );
+  const listUsersStmt = db.prepare(
+    "SELECT id, username, createdAt, role FROM users ORDER BY createdAt ASC"
+  );
+  const deleteUserStmt = db.prepare("DELETE FROM users WHERE id = ?");
+
+  return {
+    countUsers() {
+      return (countStmt.get() as { n: number }).n;
+    },
+
+    countAdmins() {
+      return (countAdminsStmt.get() as { n: number }).n;
+    },
+
+    async createUser(username, password, role) {
+      const hash = await bcrypt.hash(password, BCRYPT_ROUNDS);
+      const id = randomUUID();
+      const now = Date.now();
+      try {
+        insertStmt.run(id, username, hash, now, now, role);
+      } catch (err) {
+        if (err && typeof err === "object" && (err as { code?: string }).code === "SQLITE_CONSTRAINT_UNIQUE") {
+          throw new UsernameTakenError(username);
+        }
+        throw err;
+      }
+      return { id, username, passwordHash: hash, createdAt: now, updatedAt: now, role };
+    },
+
+    async createFirstUser(username, password) {
+      const hash = await bcrypt.hash(password, BCRYPT_ROUNDS);
+      const id = randomUUID();
+      const now = Date.now();
+      const run = db.transaction(() => {
+        const count = (countStmt.get() as { n: number }).n;
+        if (count !== 0) return null;
+        try {
+          insertStmt.run(id, username, hash, now, now, "admin");
+        } catch (err) {
+          if (err && typeof err === "object" && (err as { code?: string }).code === "SQLITE_CONSTRAINT_UNIQUE") {
+            return null;
+          }
+          throw err;
+        }
+        return { id, username, passwordHash: hash, createdAt: now, updatedAt: now, role: "admin" } as UserRow;
+      });
+      return run();
+    },
+
+    findByUsername(username) {
+      return (findByUsernameStmt.get(username) as UserRow | undefined) ?? null;
+    },
+
+    findById(id) {
+      return (findByIdStmt.get(id) as UserRow | undefined) ?? null;
+    },
+
+    verifyPassword(plain, hash) {
+      return bcrypt.compare(plain, hash);
+    },
+
+    async changePassword(userId, newPassword) {
+      const hash = await bcrypt.hash(newPassword, BCRYPT_ROUNDS);
+      updatePasswordStmt.run(hash, Date.now(), userId);
+    },
+
+    setRole(userId, role) {
+      const result = updateRoleStmt.run(role, Date.now(), userId);
+      return result.changes > 0;
+    },
+
+    setRoleIfNotLastAdmin(id, newRole) {
+      const tx = db.transaction(() => {
+        const row = findByIdStmt.get(id) as UserRow | undefined;
+        if (!row) return "not_found" as const;
+        if (row.role === newRole) return "ok" as const; // no-op
+        if (row.role === "admin" && newRole === "member") {
+          const adminCount = (countAdminsStmt.get() as { n: number }).n;
+          if (adminCount <= 1) return "would_orphan" as const;
+        }
+        updateRoleStmt.run(newRole, Date.now(), id);
+        return "ok" as const;
+      });
+      return tx();
+    },
+
+    listUsers() {
+      return listUsersStmt.all() as Array<{ id: string; username: string; createdAt: number; role: UserRole }>;
+    },
+
+    deleteUser(id) {
+      const result = deleteUserStmt.run(id);
+      return result.changes > 0;
+    },
+
+    deleteUserIfNotLastAdmin(id) {
+      const tx = db.transaction(() => {
+        const row = findByIdStmt.get(id) as UserRow | undefined;
+        if (!row) return "not_found" as const;
+        if (row.role === "admin") {
+          const adminCount = (countAdminsStmt.get() as { n: number }).n;
+          if (adminCount <= 1) return "would_orphan" as const;
+        }
+        deleteUserStmt.run(id);
+        return "ok" as const;
+      });
+      return tx();
+    },
+  };
+}

src/index.ts

@@ -8,6 +8,7 @@ import { NeteaseProvider } from "./music/netease.js";
 import { QQMusicProvider } from "./music/qq.js";
 import { BiliBiliProvider } from "./music/bilibili.js";
 import { createCookieStore } from "./music/auth.js";
+import { createAvatarStore } from "./data/avatars.js";
 import { BotManager } from "./bot/manager.js";
 import { createWebServer } from "./web/server.js";
 
@@ -18,6 +19,7 @@ const CONFIG_PATH = path.join(ROOT_DIR, "config.json");
 const DB_PATH = path.join(DATA_DIR, "tsmusicbot.db");
 const LOG_DIR = path.join(DATA_DIR, "logs");
 const COOKIE_DIR = path.join(DATA_DIR, "cookies");
+const AVATAR_DIR = path.join(DATA_DIR, "avatars");
 const STATIC_DIR = path.join(ROOT_DIR, "web", "dist");
 
 async function main() {
@@ -46,6 +48,7 @@ async function main() {
   const bilibiliProvider = new BiliBiliProvider();
 
   const cookieStore = createCookieStore(COOKIE_DIR);
+  const avatarStore = createAvatarStore(AVATAR_DIR);
   const neteaseCookie = cookieStore.load("netease");
   if (neteaseCookie) neteaseProvider.setCookie(neteaseCookie);
   const qqCookie = cookieStore.load("qq");
@@ -59,7 +62,8 @@ async function main() {
     bilibiliProvider,
     db,
     config,
-    logger
+    logger,
+    avatarStore
   );
   await botManager.loadSavedBots();
 
@@ -70,6 +74,7 @@ async function main() {
     qqProvider,
     bilibiliProvider,
     database: db,
+    avatarStore,
     config,
     configPath: CONFIG_PATH,
     logger,

src/music/bilibili.ts

@@ -1,3 +1,4 @@
+import { createHash } from "node:crypto";
 import axios, { type AxiosInstance } from "axios";
 import type {
   MusicProvider,
@@ -15,6 +16,16 @@ const BILIBILI_HEADERS = {
     "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36",
 };
 
+// Permutation used by B站 to derive the wbi mixin key from img_key+sub_key.
+const WBI_MIXIN_KEY_ENC_TAB = [
+  46, 47, 18, 2, 53, 8, 23, 32, 15, 50, 10, 31, 58, 3, 45, 35, 27, 43, 5, 49,
+  33, 9, 42, 19, 29, 28, 14, 39, 12, 38, 41, 13, 37, 48, 7, 16, 24, 55, 40, 61,
+  26, 17, 0, 1, 60, 51, 30, 4, 22, 25, 54, 21, 56, 59, 6, 63, 57, 62, 11, 36,
+  20, 34, 44, 52,
+];
+
+const WBI_KEY_TTL_MS = 6 * 60 * 60 * 1000; // wbi keys rotate ~daily; refresh every 6h
+
 export class BiliBiliProvider implements MusicProvider {
   readonly platform = "bilibili" as const;
   private api: AxiosInstance;
@@ -24,6 +35,8 @@ export class BiliBiliProvider implements MusicProvider {
   private cidCache = new Map<string, number>();
   private buvidCookie = ""; // anonymous session cookie (buvid3) for anti-412
   private buvidInitialized = false;
+  private wbiMixinKey = "";
+  private wbiKeyFetchedAt = 0;
 
   constructor() {
     this.api = axios.create({
@@ -62,6 +75,50 @@ export class BiliBiliProvider implements MusicProvider {
     return combined ? { Cookie: combined } : {};
   }
 
+  /**
+   * Fetch wbi img_key/sub_key from /x/web-interface/nav and derive the
+   * mixin key used to sign search params. Required since B站 moved the
+   * search endpoint behind wbi signing — unsigned /search/type now
+   * returns an anti-bot HTML page.
+   */
+  private async ensureWbiKeys(): Promise<void> {
+    if (this.wbiMixinKey && Date.now() - this.wbiKeyFetchedAt < WBI_KEY_TTL_MS) {
+      return;
+    }
+    const res = await this.api.get("/x/web-interface/nav", {
+      headers: this.cookieHeaders,
+      validateStatus: () => true, // nav returns -101 when not logged in but still includes wbi_img
+    });
+    const wbi = res.data?.data?.wbi_img;
+    const imgUrl: string = wbi?.img_url ?? "";
+    const subUrl: string = wbi?.sub_url ?? "";
+    const imgKey = imgUrl.split("/").pop()?.split(".")[0] ?? "";
+    const subKey = subUrl.split("/").pop()?.split(".")[0] ?? "";
+    if (!imgKey || !subKey) {
+      throw new Error("Bilibili wbi keys unavailable");
+    }
+    const raw = imgKey + subKey;
+    this.wbiMixinKey = WBI_MIXIN_KEY_ENC_TAB.map((i) => raw[i] ?? "")
+      .join("")
+      .slice(0, 32);
+    this.wbiKeyFetchedAt = Date.now();
+  }
+
+  /** Sign params for wbi-protected endpoints. Returns a new params object including wts and w_rid. */
+  private signWbi(params: Record<string, string | number>): Record<string, string> {
+    const withTs: Record<string, string> = {};
+    for (const [k, v] of Object.entries(params)) withTs[k] = String(v);
+    withTs.wts = String(Math.floor(Date.now() / 1000));
+    const sorted = Object.keys(withTs)
+      .sort()
+      .map((k) => `${encodeURIComponent(k)}=${encodeURIComponent(withTs[k])}`)
+      .join("&");
+    withTs.w_rid = createHash("md5")
+      .update(sorted + this.wbiMixinKey)
+      .digest("hex");
+    return withTs;
+  }
+
   setQuality(quality: string): void {
     this.quality = quality;
   }
@@ -91,12 +148,14 @@ export class BiliBiliProvider implements MusicProvider {
 
   async search(query: string, limit = 20): Promise<SearchResult> {
     await this.ensureBuvidCookie();
-    const res = await this.api.get("/x/web-interface/search/type", {
-      params: {
-        search_type: "video",
-        keyword: query,
-        page_size: limit,
-      },
+    await this.ensureWbiKeys();
+    const signed = this.signWbi({
+      search_type: "video",
+      keyword: query,
+      page_size: limit,
+    });
+    const res = await this.api.get("/x/web-interface/wbi/search/type", {
+      params: signed,
       headers: this.cookieHeaders,
     });
 

src/music/netease.test.ts

@@ -1,5 +1,5 @@
 import { describe, it, expect } from "vitest";
-import { parseLyrics } from "./netease.js";
+import { parseLyrics, mapNeteaseAlbums } from "./netease.js";
 
 describe("NetEase adapter", () => {
   it("parses LRC format lyrics", () => {
@@ -28,4 +28,32 @@ describe("NetEase adapter", () => {
     expect(lines[0].text).toBe("Hello world");
     expect(lines[0].translation).toBe("你好世界");
   });
+
+  it("mapNeteaseAlbums maps raw cloudsearch albums to Album shape", () => {
+    const raw = [
+      {
+        id: 42,
+        name: "Album A",
+        picUrl: "https://x/p.jpg",
+        artists: [{ name: "Artist X" }, { name: "Featured Y" }],
+        size: 12,
+      },
+      {
+        id: 99,
+        name: "Album B",
+        picUrl: "",
+        artists: [],
+      },
+    ];
+    expect(mapNeteaseAlbums(raw)).toEqual([
+      { id: "42", name: "Album A", artist: "Artist X / Featured Y", coverUrl: "https://x/p.jpg", songCount: 12, platform: "netease" },
+      { id: "99", name: "Album B", artist: "", coverUrl: "", songCount: 0, platform: "netease" },
+    ]);
+  });
+
+  it("mapNeteaseAlbums returns [] for empty/null input", () => {
+    expect(mapNeteaseAlbums([])).toEqual([]);
+    expect(mapNeteaseAlbums(null as any)).toEqual([]);
+    expect(mapNeteaseAlbums(undefined as any)).toEqual([]);
+  });
 });

src/music/netease.ts

@@ -8,6 +8,7 @@ import type {
   SearchResult,
   QrCodeResult,
   AuthStatus,
+  Album,
 } from "./provider.js";
 
 export function parseLyrics(lrc: string, tlyric?: string): LyricLine[] {
@@ -55,6 +56,18 @@ export function parseLyrics(lrc: string, tlyric?: string): LyricLine[] {
   return lines.sort((a, b) => a.time - b.time);
 }
 
+export function mapNeteaseAlbums(raw: any[] | null | undefined): Album[] {
+  if (!Array.isArray(raw)) return [];
+  return raw.map((a) => ({
+    id: String(a.id),
+    name: a.name ?? "",
+    artist: (a.artists ?? []).map((x: any) => x.name).join(" / "),
+    coverUrl: a.picUrl ?? "",
+    songCount: a.size ?? 0,
+    platform: "netease",
+  }));
+}
+
 // NetEase quality levels: standard(128k) higher(192k) exhigh(320k) lossless(flac) hires(hi-res) jyeffect jymaster
 export const NETEASE_QUALITY_LEVELS = [
   { value: "standard", label: "标准 (128kbps)", bitrate: 128 },
@@ -91,7 +104,7 @@ export class NeteaseProvider implements MusicProvider {
   }
 
   async search(query: string, limit = 20): Promise<SearchResult> {
-    const [songRes, playlistRes] = await Promise.all([
+    const [songRes, playlistRes, albumRes] = await Promise.all([
       this.api.get("/cloudsearch", {
         params: { keywords: query, type: 1, limit, ...this.cookieParams },
       }),
@@ -99,10 +112,13 @@ export class NeteaseProvider implements MusicProvider {
         params: {
           keywords: query,
           type: 1000,
-          limit: 5,
+          limit: 10,
           ...this.cookieParams,
         },
       }),
+      this.api.get("/cloudsearch", {
+        params: { keywords: query, type: 10, limit: 10, ...this.cookieParams },
+      }),
     ]);
 
     const songs: Song[] = (songRes.data?.result?.songs ?? []).map(
@@ -127,7 +143,9 @@ export class NeteaseProvider implements MusicProvider {
       platform: "netease",
     }));
 
-    return { songs, playlists, albums: [] };
+    const albums = mapNeteaseAlbums(albumRes.data?.result?.albums);
+
+    return { songs, playlists, albums };
   }
 
   async getSongUrl(songId: string, quality?: string): Promise<string | null> {

src/music/qq.test.ts

@@ -0,0 +1,43 @@
+import { describe, it, expect } from "vitest";
+import { mapQqAlbums } from "./qq.js";
+
+describe("QQ adapter", () => {
+  it("mapQqAlbums maps albumMID-style raw entries", () => {
+    const raw = [
+      {
+        albumMID: "abc",
+        albumName: "Aero",
+        singerName: "Singer A",
+      },
+      {
+        albumMID: "xyz",
+        albumName: "Beta",
+        singer: [{ name: "Singer B" }, { name: "Singer C" }],
+      },
+    ];
+    const out = mapQqAlbums(raw);
+    expect(out).toHaveLength(2);
+    expect(out[0]).toMatchObject({
+      id: "abc",
+      name: "Aero",
+      artist: "Singer A",
+      platform: "qq",
+    });
+    expect(out[0].coverUrl).toContain("T002R300x300M000abc.jpg");
+    expect(out[1].artist).toBe("Singer B / Singer C");
+    expect(out[1].coverUrl).toContain("xyz");
+  });
+
+  it("mapQqAlbums returns [] for empty/null input", () => {
+    expect(mapQqAlbums([])).toEqual([]);
+    expect(mapQqAlbums(null as any)).toEqual([]);
+    expect(mapQqAlbums(undefined as any)).toEqual([]);
+  });
+
+  it("mapQqAlbums falls back to albumPic when no albumMID", () => {
+    const raw = [{ albumName: "C", albumPic: "https://x/p.jpg", singerName: "S" }];
+    const out = mapQqAlbums(raw);
+    expect(out[0].coverUrl).toBe("https://x/p.jpg");
+    expect(out[0].id).toBe("");
+  });
+});

src/music/qq.ts

@@ -8,17 +8,29 @@ import type {
   SearchResult,
   QrCodeResult,
   AuthStatus,
+  Album,
 } from "./provider.js";
 import { parseLyrics } from "./netease.js";
 
-// Direct QQ Music API client — bypasses the local API server for search
-// because @sansenjian/qq-music-api still uses the broken c.y.qq.com endpoint.
-const qqDirectApi = axios.create({
+// Primary search client: u.y.qq.com/cgi-bin/musicu.fcg (JSON sub-request
+// batch). Was broken ca. 2026-05 due to two upstream API changes:
+//   1. searchid param must NOT be present (causes all lists to be empty)
+//   2. num_per_page must be >= 10 (lower values return empty)
+// Both fixes applied per https://github.com/ZHANGTIANYAO1/teamspeak-music-bot/issues/61
+const qqMusicuApi = axios.create({
   baseURL: "https://u.y.qq.com",
   timeout: 10000,
   headers: { referer: "https://y.qq.com" },
 });
 
+// Fallback search client: c.y.qq.com/soso/fcgi-bin/client_search_cp (classic
+// endpoint, song + album only, no playlist support).
+const qqSearchApi = axios.create({
+  baseURL: "https://c.y.qq.com",
+  timeout: 10000,
+  headers: { referer: "https://y.qq.com" },
+});
+
 // Direct client for c.y.qq.com endpoints (collected playlists / favorites).
 // The bundled qq-music-api wrapper doesn't expose these endpoints.
 const qqFavApi = axios.create({
@@ -27,6 +39,26 @@ const qqFavApi = axios.create({
   headers: { referer: "https://y.qq.com/" },
 });
 
+export function mapQqAlbums(raw: any[] | null | undefined): Album[] {
+  if (!Array.isArray(raw)) return [];
+  return raw.map((a) => {
+    const id = String(a.albumMID ?? a.mid ?? a.albumID ?? "");
+    const artist = a.singerName
+      ?? (Array.isArray(a.singer) ? a.singer.map((s: any) => s.name).join(" / ") : "");
+    const coverUrl = id
+      ? `https://y.gtimg.cn/music/photo_new/T002R300x300M000${id}.jpg`
+      : (a.albumPic ?? "");
+    return {
+      id,
+      name: a.albumName ?? a.title ?? "",
+      artist,
+      coverUrl,
+      songCount: a.song_count ?? a.songCount ?? 0,
+      platform: "qq" as const,
+    };
+  });
+}
+
 function computeGtk(pSkey: string): number {
   let hash = 5381;
   for (let i = 0; i < pSkey.length; i++) {
@@ -61,36 +93,135 @@ export class QQMusicProvider implements MusicProvider {
   }
 
   async search(query: string, limit = 20): Promise<SearchResult> {
-    const reqData = JSON.stringify({
-      req_0: {
-        module: "music.search.SearchCgiService",
-        method: "DoSearchForQQMusicDesktop",
-        param: {
-          searchid: "1",
-          query,
-          num_per_page: Math.min(limit, 50),
-        },
-      },
-    });
-    const res = await qqDirectApi.get("/cgi-bin/musicu.fcg", {
-      params: { format: "json", data: reqData },
-    });
-    const list: any[] =
-      res.data?.req_0?.data?.body?.song?.list ?? [];
+    // Primary: u.y.qq.com/cgi-bin/musicu.fcg — supports songs + albums +
+    // playlists. Fixed per https://github.com/ZHANGTIANYAO1/teamspeak-music-bot/issues/61
+    // (removed searchid, num_per_page >= 10, corrected search_type values).
+    const primary = await this.searchViaMusicuFcg(query, limit);
+    if (primary) return primary;
 
-    const songs: Song[] = list.map((s: any) => ({
-      id: String(s.mid ?? s.id),
-      name: s.title ?? s.name ?? "",
+    // Fallback: c.y.qq.com/soso/fcgi-bin/client_search_cp (song + album,
+    // no playlist support). Kept as redundancy.
+    return this.searchViaClientSearchCp(query, limit);
+  }
+
+  /** Primary search via u.y.qq.com/cgi-bin/musicu.fcg.
+   *
+   * Two upstream API changes (2026-05) required fixes:
+   *   1. Omit `searchid` — its presence now causes all lists to be empty.
+   *   2. `num_per_page` >= 10 — lower values return empty.
+   *   3. `search_type: 2` for albums, `3` for playlists (8 was "user"). */
+  private async searchViaMusicuFcg(
+    query: string,
+    limit: number
+  ): Promise<SearchResult | null> {
+    try {
+      const numPerPage = Math.max(10, Math.min(limit, 50));
+      const reqData = JSON.stringify({
+        req_0: {
+          module: "music.search.SearchCgiService",
+          method: "DoSearchForQQMusicDesktop",
+          param: { query, num_per_page: numPerPage, search_type: 0 },
+        },
+        req_album: {
+          module: "music.search.SearchCgiService",
+          method: "DoSearchForQQMusicDesktop",
+          param: { query, num_per_page: 10, search_type: 2 },
+        },
+        req_playlist: {
+          module: "music.search.SearchCgiService",
+          method: "DoSearchForQQMusicDesktop",
+          param: { query, num_per_page: 10, search_type: 3 },
+        },
+      });
+      const res = await qqMusicuApi.get("/cgi-bin/musicu.fcg", {
+        params: { format: "json", data: reqData },
+      });
+
+      const songList: any[] =
+        res.data?.req_0?.data?.body?.song?.list ?? [];
+      if (songList.length === 0) return null;
+
+      const songs: Song[] = songList.map((s: any) => ({
+        id: String(s.mid ?? s.id),
+        name: s.title ?? s.name ?? "",
+        artist: (s.singer ?? []).map((a: any) => a.name).join(" / "),
+        album: s.album?.name ?? s.album?.title ?? "",
+        duration: s.interval ?? 0,
+        coverUrl: s.album?.mid
+          ? `https://y.gtimg.cn/music/photo_new/T002R300x300M000${s.album.mid}.jpg`
+          : "",
+        platform: "qq",
+      }));
+
+      const albumList: any[] = res.data?.req_album?.data?.body?.album?.list ?? [];
+      const albums = mapQqAlbums(albumList);
+
+      const playlistList: any[] = res.data?.req_playlist?.data?.body?.songlist?.list ?? [];
+      const playlists: Playlist[] = playlistList.map((p: any) => ({
+        id: String(p.dissid ?? p.id ?? ""),
+        name: p.dissname ?? p.title ?? "",
+        coverUrl: p.imgurl ?? p.logo ?? "",
+        songCount: p.songnum ?? p.song_count ?? 0,
+        platform: "qq" as const,
+      }));
+
+      return { songs, playlists, albums };
+    } catch {
+      return null;
+    }
+  }
+
+  /** Fallback search via c.y.qq.com/soso/fcgi-bin/client_search_cp */
+  private async searchViaClientSearchCp(
+    query: string,
+    limit: number
+  ): Promise<SearchResult> {
+    const songParams = {
+      w: query,
+      format: "json",
+      p: 1,
+      n: Math.min(limit, 50),
+      type: 0,
+      cr: 1,
+    };
+    const albumParams = {
+      w: query,
+      format: "json",
+      p: 1,
+      n: 5,
+      t: 8,
+      cr: 1,
+    };
+
+    const [songRes, albumRes] = await Promise.allSettled([
+      qqSearchApi.get("/soso/fcgi-bin/client_search_cp", { params: songParams }),
+      qqSearchApi.get("/soso/fcgi-bin/client_search_cp", { params: albumParams }),
+    ]);
+
+    const songList: any[] =
+      songRes.status === "fulfilled"
+        ? (songRes.value.data?.data?.song?.list ?? [])
+        : [];
+
+    const songs: Song[] = songList.map((s: any) => ({
+      id: String(s.songmid ?? s.songid ?? ""),
+      name: s.songname ?? s.name ?? "",
       artist: (s.singer ?? []).map((a: any) => a.name).join(" / "),
-      album: s.album?.name ?? s.album?.title ?? "",
+      album: s.albumname ?? s.album?.name ?? "",
       duration: s.interval ?? 0,
-      coverUrl: s.album?.mid
-        ? `https://y.gtimg.cn/music/photo_new/T002R300x300M000${s.album.mid}.jpg`
+      coverUrl: s.albummid
+        ? `https://y.gtimg.cn/music/photo_new/T002R300x300M000${s.albummid}.jpg`
         : "",
       platform: "qq",
     }));
 
-    return { songs, playlists: [], albums: [] };
+    const albumList: any[] =
+      albumRes.status === "fulfilled"
+        ? (albumRes.value.data?.data?.album?.list ?? [])
+        : [];
+    const albums = mapQqAlbums(albumList);
+
+    return { songs, playlists: [], albums };
   }
 
   async getSongUrl(songId: string, quality?: string): Promise<string | null> {

src/web/api/audit.test.ts

@@ -0,0 +1,56 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import express from "express";
+import cookieParser from "cookie-parser";
+import request from "supertest";
+import { createDatabase, type BotDatabase } from "../../data/database.js";
+import { createUserStore } from "../../data/users.js";
+import { createSessionStore } from "../../data/sessions.js";
+import { createAuditStore } from "../../data/audit.js";
+import { createRequireAuth } from "../middleware/requireAuth.js";
+import { createAuditRouter } from "./audit.js";
+import { SESSION_COOKIE_NAME } from "../auth/validateSession.js";
+
+describe("audit router", () => {
+  let botDb: BotDatabase;
+  let app: express.Express;
+  let cookie: string;
+
+  beforeEach(async () => {
+    botDb = createDatabase(":memory:");
+    const users = createUserStore(botDb.db);
+    const sessions = createSessionStore(botDb.db);
+    const audit = createAuditStore(botDb.db);
+    const alice = await users.createUser("alice", "pw-alice", "admin");
+    cookie = `${SESSION_COOKIE_NAME}=${sessions.createSession(alice.id).token}`;
+    for (let i = 0; i < 3; i++) {
+      audit.record({
+        actorId: alice.id, actorUsername: "alice",
+        targetUserId: "x", targetUsername: "x",
+        action: "user.created",
+      });
+    }
+    app = express();
+    app.use(express.json());
+    app.use(cookieParser());
+    app.use("/api", createRequireAuth(sessions));
+    app.use("/api/audit", createAuditRouter(audit));
+  });
+
+  afterEach(() => botDb.close());
+
+  it("requires auth", async () => {
+    const res = await request(app).get("/api/audit");
+    expect(res.status).toBe(401);
+  });
+
+  it("returns entries newest-first", async () => {
+    const res = await request(app).get("/api/audit").set("Cookie", cookie);
+    expect(res.status).toBe(200);
+    expect(res.body.entries).toHaveLength(3);
+  });
+
+  it("honors limit query param", async () => {
+    const res = await request(app).get("/api/audit?limit=1").set("Cookie", cookie);
+    expect(res.body.entries).toHaveLength(1);
+  });
+});

src/web/api/audit.ts

@@ -0,0 +1,18 @@
+import { Router } from "express";
+import type { AuditStore } from "../../data/audit.js";
+
+export function createAuditRouter(audit: AuditStore): Router {
+  const router = Router();
+  router.get("/", (req, res) => {
+    const limit = clampInt(req.query.limit, 1, 500, 100);
+    const offset = clampInt(req.query.offset, 0, 100_000, 0);
+    res.json({ entries: audit.list(limit, offset) });
+  });
+  return router;
+}
+
+function clampInt(v: unknown, min: number, max: number, def: number): number {
+  const n = typeof v === "string" ? parseInt(v, 10) : NaN;
+  if (!Number.isFinite(n)) return def;
+  return Math.min(Math.max(n, min), max);
+}

src/web/api/bot.ts

@@ -3,12 +3,16 @@ import type { BotManager } from "../../bot/manager.js";
 import type { BotConfig } from "../../data/config.js";
 import { saveConfig } from "../../data/config.js";
 import type { Logger } from "../../logger.js";
+import type { BotDatabase } from "../../data/database.js";
+import type { AvatarStore } from "../../data/avatars.js";
 
 export function createBotRouter(
   botManager: BotManager,
   config: BotConfig,
   configPath: string,
-  logger: Logger
+  logger: Logger,
+  botDb: BotDatabase,
+  avatarStore: AvatarStore,
 ): Router {
   const router = Router();
 
@@ -36,6 +40,70 @@ export function createBotRouter(
     res.json(saved);
   });
 
+  router.get("/:id/avatar", (req, res) => {
+    const path = botDb.getCustomAvatarPath(req.params.id);
+    if (!path) {
+      res.status(404).end();
+      return;
+    }
+    const buf = avatarStore.read(path);
+    if (!buf) {
+      res.status(404).end();
+      return;
+    }
+    const ext = path.split(".").pop() ?? "";
+    const mime = ext === "png"
+      ? "image/png"
+      : ext === "webp"
+        ? "image/webp"
+        : "image/jpeg";
+    res.set("Content-Type", mime);
+    res.set("Cache-Control", "no-cache");
+    res.send(buf);
+  });
+
+  router.put("/:id/avatar", (req, res) => {
+    const exists =
+      botManager.getBot(req.params.id) ||
+      botDb.getBotInstances().some((b) => b.id === req.params.id);
+    if (!exists) {
+      res.status(404).json({ error: "Bot not found" });
+      return;
+    }
+    const { dataUrl } = req.body as { dataUrl?: string };
+    if (typeof dataUrl !== "string") {
+      res.status(400).json({ error: "dataUrl required" });
+      return;
+    }
+    const m = /^data:(image\/(?:png|jpeg|webp));base64,(.+)$/.exec(dataUrl);
+    if (!m) {
+      res.status(400).json({ error: "dataUrl must be image/png|jpeg|webp base64" });
+      return;
+    }
+    const mime = m[1] as string;
+    const buf = Buffer.from(m[2] ?? "", "base64");
+    if (buf.length === 0) {
+      res.status(400).json({ error: "empty image" });
+      return;
+    }
+    if (buf.length > 200 * 1024) {
+      res.status(413).json({ error: "avatar exceeds 200KB limit" });
+      return;
+    }
+    const rel = avatarStore.write(req.params.id, mime, buf);
+    botDb.setCustomAvatarPath(req.params.id, rel);
+    botManager.getBot(req.params.id)?.getProfileManager().setCustomAvatar(buf);
+    res.json({ path: rel });
+  });
+
+  router.delete("/:id/avatar", (req, res) => {
+    const path = botDb.getCustomAvatarPath(req.params.id);
+    if (path) avatarStore.remove(path);
+    botDb.setCustomAvatarPath(req.params.id, null);
+    botManager.getBot(req.params.id)?.getProfileManager().setCustomAvatar(null);
+    res.status(204).end();
+  });
+
   router.post("/", async (req, res) => {
     try {
       const {

src/web/api/music.ts

@@ -52,14 +52,20 @@ export function createMusicRouter(
       ]);
 
       const songs = [
-        ...(neteaseResult.status === "fulfilled"
-          ? neteaseResult.value.songs
-          : []),
+        ...(neteaseResult.status === "fulfilled" ? neteaseResult.value.songs : []),
         ...(qqResult.status === "fulfilled" ? qqResult.value.songs : []),
         ...(bilibiliResult.status === "fulfilled" ? bilibiliResult.value.songs : []),
       ];
+      const albums = [
+        ...(neteaseResult.status === "fulfilled" ? neteaseResult.value.albums : []),
+        ...(qqResult.status === "fulfilled" ? qqResult.value.albums : []),
+      ];
+      const playlists = [
+        ...(neteaseResult.status === "fulfilled" ? neteaseResult.value.playlists : []),
+        ...(qqResult.status === "fulfilled" ? qqResult.value.playlists : []),
+      ];
 
-      res.json({ songs });
+      res.json({ songs, albums, playlists });
     } catch (err) {
       logger.error({ err }, "Unified search failed");
       res.status(500).json({ error: (err as Error).message });

src/web/api/player.ts

@@ -313,6 +313,78 @@ export function createPlayerRouter(
     }
   });
 
+  // Play an album by ID — mirrors play-playlist but calls getAlbumSongs
+  router.post("/:botId/play-album", async (req, res) => {
+    try {
+      const bot = (req as any).bot;
+      const { albumId, platform } = req.body;
+      const provider = bot.getProviderFor(
+        platform === "bilibili" || platform === "qq" || platform === "youtube"
+          ? platform
+          : "netease"
+      );
+
+      // Stop current playback
+      bot.getPlayer().stop();
+      bot.getPlayer().resetFailures();
+
+      const songs = await provider.getAlbumSongs(albumId);
+      if (songs.length === 0) {
+        res.json({ message: "Album is empty" });
+        return;
+      }
+
+      // QQ-specific optimization: batch-resolve playable IDs to avoid
+      // wasting retries on region/copyright-restricted tracks.
+      let queueable: { id: string }[] = songs;
+      const totalCount = songs.length;
+      const qqLike = provider as { getPlayableSongIds?: (ids: string[]) => Promise<Set<string> | null> };
+      if (typeof qqLike.getPlayableSongIds === "function") {
+        const playable = await qqLike.getPlayableSongIds(songs.map((s: { id: string }) => s.id));
+        if (playable !== null) {
+          queueable = songs.filter((s: { id: string }) => playable.has(s.id));
+        }
+      }
+      if (queueable.length === 0) {
+        res.json({ ok: false, message: `专辑 ${totalCount} 首歌曲均无版权可播放（区域/版权限制）` });
+        return;
+      }
+
+      const queue = bot.getQueueManager();
+      queue.clear();
+      for (const song of queueable) {
+        queue.add({ ...song, platform: provider.platform });
+      }
+
+      const mode = queue.getMode();
+      let first;
+      if (mode === "random" || mode === "rloop") {
+        const idx = Math.floor(Math.random() * queue.size());
+        first = queue.playAt(idx);
+      } else {
+        first = queue.play();
+      }
+
+      let started = first ? await bot.resolveAndPlay(first) : false;
+      if (first && !started) {
+        started = await bot.playNext(20);
+      }
+
+      const playing = queue.current();
+      const loadedMsg = queueable.length < totalCount
+        ? `已加载 ${queueable.length}/${totalCount} 首（其余区域/版权限制）`
+        : `已加载 ${queueable.length} 首`;
+      if (started && playing) {
+        res.json({ ok: true, message: `${loadedMsg}，正在播放：${playing.name}` });
+      } else {
+        res.json({ ok: false, message: `${loadedMsg}，但无法开始播放。` });
+      }
+    } catch (err) {
+      logger.error({ err }, "play-album failed");
+      res.status(500).json({ error: (err as Error).message });
+    }
+  });
+
   // Play a single song by ID — resolves URL on demand
   router.post("/:botId/play-song", async (req, res) => {
     try {

src/web/api/session.test.ts

@@ -0,0 +1,151 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import express from "express";
+import cookieParser from "cookie-parser";
+import request from "supertest";
+import pino from "pino";
+import { createDatabase, type BotDatabase } from "../../data/database.js";
+import { createUserStore, type UserStore } from "../../data/users.js";
+import { createSessionStore, type SessionStore } from "../../data/sessions.js";
+import { createAuditStore } from "../../data/audit.js";
+import { createSessionRouter } from "./session.js";
+import { SESSION_COOKIE_NAME } from "../auth/validateSession.js";
+
+function makeApp(botDb: BotDatabase, users: UserStore, sessions: SessionStore) {
+  const app = express();
+  app.use(express.json());
+  app.use(cookieParser());
+  const audit = createAuditStore(botDb.db);
+  app.use("/api/session", createSessionRouter(users, sessions, audit, pino({ level: "silent" })));
+  return app;
+}
+
+function extractCookie(res: request.Response): string {
+  const header = res.headers["set-cookie"];
+  const arr = Array.isArray(header) ? header : header ? [header] : [];
+  const found = arr.find((c) => c.startsWith(`${SESSION_COOKIE_NAME}=`));
+  if (!found) throw new Error("no session cookie set");
+  return found.split(";")[0]; // "tsmb_session=xxxx"
+}
+
+describe("session router", () => {
+  let botDb: BotDatabase;
+  let users: UserStore;
+  let sessions: SessionStore;
+  let app: express.Express;
+
+  beforeEach(() => {
+    botDb = createDatabase(":memory:");
+    users = createUserStore(botDb.db);
+    sessions = createSessionStore(botDb.db);
+    app = makeApp(botDb, users, sessions);
+  });
+
+  afterEach(() => botDb.close());
+
+  it("GET /needs-setup returns true on an empty db", async () => {
+    const res = await request(app).get("/api/session/needs-setup");
+    expect(res.status).toBe(200);
+    expect(res.body).toEqual({ needsSetup: true });
+  });
+
+  it("POST /setup creates the first admin, logs them in, and returns false from /needs-setup afterwards", async () => {
+    const setupRes = await request(app)
+      .post("/api/session/setup")
+      .send({ username: "alice", password: "hunter2-hunter2" });
+    expect(setupRes.status).toBe(200);
+    expect(setupRes.body.username).toBe("alice");
+    extractCookie(setupRes);
+
+    const needs = await request(app).get("/api/session/needs-setup");
+    expect(needs.body).toEqual({ needsSetup: false });
+  });
+
+  it("POST /setup returns 409 once a user already exists", async () => {
+    await users.createUser("admin", "pw-admin-pw", "admin");
+    const res = await request(app)
+      .post("/api/session/setup")
+      .send({ username: "alice", password: "pw" });
+    expect(res.status).toBe(409);
+    expect(res.body).toEqual({ error: "already initialized" });
+  });
+
+  it("POST /login returns 401 with constant-time delay on bad credentials", async () => {
+    await users.createUser("alice", "correct-pw-pw", "admin");
+    const start = Date.now();
+    const res = await request(app)
+      .post("/api/session/login")
+      .send({ username: "alice", password: "wrong" });
+    expect(res.status).toBe(401);
+    expect(res.body).toEqual({ error: "invalid credentials" });
+    expect(Date.now() - start).toBeGreaterThanOrEqual(200);
+  }, 10_000);
+
+  it("POST /login sets a session cookie on success", async () => {
+    await users.createUser("alice", "pw-alice", "admin");
+    const res = await request(app)
+      .post("/api/session/login")
+      .send({ username: "alice", password: "pw-alice" });
+    expect(res.status).toBe(200);
+    expect(res.body.username).toBe("alice");
+    extractCookie(res);
+  });
+
+  it("GET /me returns the current user when cookie is present, 401 otherwise", async () => {
+    await users.createUser("alice", "pw-alice", "admin");
+    const loginRes = await request(app)
+      .post("/api/session/login")
+      .send({ username: "alice", password: "pw-alice" });
+    const cookie = extractCookie(loginRes);
+
+    const me = await request(app).get("/api/session/me").set("Cookie", cookie);
+    expect(me.status).toBe(200);
+    expect(me.body.username).toBe("alice");
+
+    const anon = await request(app).get("/api/session/me");
+    expect(anon.status).toBe(401);
+  });
+
+  it("POST /logout deletes the session and clears the cookie", async () => {
+    await users.createUser("alice", "pw-alice", "admin");
+    const loginRes = await request(app)
+      .post("/api/session/login")
+      .send({ username: "alice", password: "pw-alice" });
+    const cookie = extractCookie(loginRes);
+
+    const logout = await request(app).post("/api/session/logout").set("Cookie", cookie);
+    expect(logout.status).toBe(204);
+
+    const me = await request(app).get("/api/session/me").set("Cookie", cookie);
+    expect(me.status).toBe(401);
+  });
+
+  it("POST /change-password requires old password and invalidates other sessions", async () => {
+    const u = await users.createUser("alice", "old-pw-pw", "admin");
+    const cookieA = extractCookie(
+      await request(app).post("/api/session/login").send({ username: "alice", password: "old-pw-pw" })
+    );
+    const cookieB = extractCookie(
+      await request(app).post("/api/session/login").send({ username: "alice", password: "old-pw-pw" })
+    );
+
+    const wrongOld = await request(app)
+      .post("/api/session/change-password")
+      .set("Cookie", cookieA)
+      .send({ oldPassword: "WRONG", newPassword: "newpassword" });
+    expect(wrongOld.status).toBe(401);
+
+    const ok = await request(app)
+      .post("/api/session/change-password")
+      .set("Cookie", cookieA)
+      .send({ oldPassword: "old-pw-pw", newPassword: "newpassword" });
+    expect(ok.status).toBe(204);
+
+    const meA = await request(app).get("/api/session/me").set("Cookie", cookieA);
+    expect(meA.status).toBe(200);
+
+    const meB = await request(app).get("/api/session/me").set("Cookie", cookieB);
+    expect(meB.status).toBe(401);
+
+    expect(u.id).toBe(meA.body.id);
+  });
+});

src/web/api/session.ts

@@ -0,0 +1,171 @@
+import { Router } from "express";
+import type { Request, Response, NextFunction } from "express";
+import type { Logger } from "../../logger.js";
+import type { UserStore } from "../../data/users.js";
+import type { SessionStore } from "../../data/sessions.js";
+import type { AuditStore } from "../../data/audit.js";
+import { SESSION_TTL_MS } from "../../data/sessions.js";
+import { SESSION_COOKIE_NAME, validateSessionFromHeaders, extractSessionToken } from "../auth/validateSession.js";
+
+const FAILED_LOGIN_DELAY_MS = 250;
+
+function setSessionCookie(res: Response, token: string): void {
+  res.cookie(SESSION_COOKIE_NAME, token, {
+    httpOnly: true,
+    sameSite: "lax",
+    secure: res.req.secure,
+    path: "/",
+    maxAge: SESSION_TTL_MS,
+  });
+}
+
+function clearSessionCookie(res: Response): void {
+  res.clearCookie(SESSION_COOKIE_NAME, { path: "/" });
+}
+
+function delay(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+function isValidUsername(v: unknown): v is string {
+  return typeof v === "string" && /^[A-Za-z0-9_\-.]{3,32}$/.test(v);
+}
+
+function isValidPassword(v: unknown): v is string {
+  return typeof v === "string" && v.length >= 8 && v.length <= 200;
+}
+
+function parseTokenFromCookie(cookieHeader: string | undefined): string | null {
+  if (!cookieHeader) return null;
+  const match = cookieHeader
+    .split(";")
+    .map((p) => p.trim())
+    .find((p) => p.startsWith(`${SESSION_COOKIE_NAME}=`));
+  if (!match) return null;
+  return decodeURIComponent(match.slice(SESSION_COOKIE_NAME.length + 1));
+}
+
+export function createSessionRouter(
+  users: UserStore,
+  sessions: SessionStore,
+  audit: AuditStore,
+  logger: Logger
+): Router {
+  const router = Router();
+
+  const requireAuthInline = (req: Request, res: Response, next: NextFunction) => {
+    const result = validateSessionFromHeaders(req.headers.cookie, sessions);
+    if (!result) {
+      clearSessionCookie(res);
+      res.status(401).json({ error: "unauthenticated" });
+      return;
+    }
+    req.user = { id: result.userId, username: result.username, role: result.role };
+    const token = extractSessionToken(req.headers.cookie);
+    if (token) setSessionCookie(res, token);
+    next();
+  };
+
+  router.get("/needs-setup", (_req, res) => {
+    res.json({ needsSetup: users.countUsers() === 0 });
+  });
+
+  router.post("/setup", async (req, res) => {
+    const { username, password } = req.body ?? {};
+    if (users.countUsers() !== 0) {
+      res.status(409).json({ error: "already initialized" });
+      return;
+    }
+    if (!isValidUsername(username) || !isValidPassword(password)) {
+      res.status(400).json({ error: "invalid username or password" });
+      return;
+    }
+    try {
+      const user = await users.createFirstUser(username, password);
+      if (!user) {
+        res.status(409).json({ error: "already initialized" });
+        return;
+      }
+      const { token } = sessions.createSession(user.id);
+      setSessionCookie(res, token);
+      try {
+        audit.record({
+          actorId: user.id, actorUsername: user.username,
+          targetUserId: user.id, targetUsername: user.username,
+          action: "admin.first_created",
+        });
+      } catch (auditErr) {
+        logger.warn({ err: auditErr, action: "admin.first_created" }, "audit insert failed");
+      }
+      logger.info({ userId: user.id, username }, "First admin created");
+      res.json({ id: user.id, username: user.username, role: user.role });
+    } catch (err) {
+      logger.error({ err }, "setup failed");
+      res.status(500).json({ error: "internal" });
+    }
+  });
+
+  router.post("/login", async (req, res) => {
+    const { username, password } = req.body ?? {};
+    if (typeof username !== "string" || typeof password !== "string") {
+      res.status(400).json({ error: "invalid request" });
+      return;
+    }
+    const user = users.findByUsername(username);
+    const ok = user ? await users.verifyPassword(password, user.passwordHash) : false;
+    if (!user || !ok) {
+      await delay(FAILED_LOGIN_DELAY_MS);
+      res.status(401).json({ error: "invalid credentials" });
+      return;
+    }
+    const { token } = sessions.createSession(user.id);
+    setSessionCookie(res, token);
+    res.json({ id: user.id, username: user.username, role: user.role });
+  });
+
+  router.post("/logout", (req, res) => {
+    const token = parseTokenFromCookie(req.headers.cookie);
+    if (token) {
+      sessions.deleteSession(token);
+    }
+    clearSessionCookie(res);
+    res.status(204).end();
+  });
+
+  router.get("/me", requireAuthInline, (req, res) => {
+    res.json(req.user);
+  });
+
+  router.post("/change-password", requireAuthInline, async (req, res) => {
+    const { oldPassword, newPassword } = req.body ?? {};
+    if (typeof oldPassword !== "string") {
+      res.status(400).json({ error: "invalid request" });
+      return;
+    }
+    const u = users.findById(req.user!.id);
+    if (!u || !(await users.verifyPassword(oldPassword, u.passwordHash))) {
+      await delay(FAILED_LOGIN_DELAY_MS);
+      res.status(401).json({ error: "invalid credentials" });
+      return;
+    }
+    if (!isValidPassword(newPassword)) {
+      res.status(400).json({ error: "invalid request" });
+      return;
+    }
+    await users.changePassword(u.id, newPassword);
+    const currentToken = parseTokenFromCookie(req.headers.cookie);
+    sessions.deleteAllForUser(u.id, currentToken ?? undefined);
+    try {
+      audit.record({
+        actorId: u.id, actorUsername: u.username,
+        targetUserId: u.id, targetUsername: u.username,
+        action: "user.password_changed",
+      });
+    } catch (auditErr) {
+      logger.warn({ err: auditErr, action: "user.password_changed" }, "audit insert failed");
+    }
+    res.status(204).end();
+  });
+
+  return router;
+}

src/web/api/users.test.ts

@@ -0,0 +1,257 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import express from "express";
+import cookieParser from "cookie-parser";
+import request from "supertest";
+import pino from "pino";
+import { createDatabase, type BotDatabase } from "../../data/database.js";
+import { createUserStore, type UserStore } from "../../data/users.js";
+import { createSessionStore, type SessionStore } from "../../data/sessions.js";
+import { createAuditStore } from "../../data/audit.js";
+import { createRequireAuth } from "../middleware/requireAuth.js";
+import { createUsersRouter } from "./users.js";
+import { SESSION_COOKIE_NAME } from "../auth/validateSession.js";
+
+function makeApp(botDb: BotDatabase, users: UserStore, sessions: SessionStore) {
+  const app = express();
+  app.use(express.json());
+  app.use(cookieParser());
+  const requireAuth = createRequireAuth(sessions);
+  const audit = createAuditStore(botDb.db);
+  app.use("/api", requireAuth);
+  app.use("/api/users", createUsersRouter(users, sessions, audit, pino({ level: "silent" })));
+  return app;
+}
+
+describe("users router", () => {
+  let botDb: BotDatabase;
+  let users: UserStore;
+  let sessions: SessionStore;
+  let app: express.Express;
+  let aliceId: string;
+  let aliceCookie: string;
+  let bobId: string;
+
+  beforeEach(async () => {
+    botDb = createDatabase(":memory:");
+    users = createUserStore(botDb.db);
+    sessions = createSessionStore(botDb.db);
+    app = makeApp(botDb, users, sessions);
+    const alice = await users.createUser("alice", "pw-alice", "admin");
+    aliceId = alice.id;
+    aliceCookie = `${SESSION_COOKIE_NAME}=${sessions.createSession(alice.id).token}`;
+    const bob = await users.createUser("bob", "pw-bob-bob", "member");
+    bobId = bob.id;
+  });
+
+  afterEach(() => botDb.close());
+
+  it("requires auth for all routes", async () => {
+    expect((await request(app).get("/api/users")).status).toBe(401);
+    expect((await request(app).post("/api/users").send({ username: "x", password: "yyyyyyyy" })).status).toBe(401);
+    expect((await request(app).delete(`/api/users/${bobId}`)).status).toBe(401);
+  });
+
+  it("GET / lists users with id+username+createdAt, no password hash", async () => {
+    const res = await request(app).get("/api/users").set("Cookie", aliceCookie);
+    expect(res.status).toBe(200);
+    expect(res.body.users).toHaveLength(2);
+    for (const u of res.body.users) {
+      expect(u).toHaveProperty("id");
+      expect(u).toHaveProperty("username");
+      expect(u).toHaveProperty("createdAt");
+      expect(u).not.toHaveProperty("passwordHash");
+    }
+  });
+
+  it("POST / creates a user", async () => {
+    const res = await request(app)
+      .post("/api/users")
+      .set("Cookie", aliceCookie)
+      .send({ username: "charlie", password: "charlie-pw" });
+    expect(res.status).toBe(201);
+    expect(res.body.username).toBe("charlie");
+    expect(users.countUsers()).toBe(3);
+  });
+
+  it("POST / returns 409 on duplicate username", async () => {
+    const res = await request(app)
+      .post("/api/users")
+      .set("Cookie", aliceCookie)
+      .send({ username: "BOB", password: "another-pw" });
+    expect(res.status).toBe(409);
+  });
+
+  it("POST / returns 400 on invalid input", async () => {
+    const res = await request(app)
+      .post("/api/users")
+      .set("Cookie", aliceCookie)
+      .send({ username: "x", password: "short" });
+    expect(res.status).toBe(400);
+  });
+
+  it("DELETE /:id removes the user and their sessions", async () => {
+    const bobToken = sessions.createSession(bobId).token;
+    const res = await request(app).delete(`/api/users/${bobId}`).set("Cookie", aliceCookie);
+    expect(res.status).toBe(204);
+    expect(users.countUsers()).toBe(1);
+    expect(sessions.validateAndTouch(bobToken)).toBeNull();
+  });
+
+  it("DELETE /:id of self returns 400", async () => {
+    const res = await request(app).delete(`/api/users/${aliceId}`).set("Cookie", aliceCookie);
+    expect(res.status).toBe(400);
+    expect(res.body).toEqual({ error: "cannot delete self" });
+    expect(users.countUsers()).toBe(2);
+  });
+
+  it("DELETE /:id of nonexistent returns 404", async () => {
+    const res = await request(app).delete(`/api/users/not-a-real-id`).set("Cookie", aliceCookie);
+    expect(res.status).toBe(404);
+  });
+
+  it("POST /:id/reset-password updates the hash and invalidates target's sessions", async () => {
+    const bobToken = sessions.createSession(bobId).token;
+    const res = await request(app)
+      .post(`/api/users/${bobId}/reset-password`)
+      .set("Cookie", aliceCookie)
+      .send({ newPassword: "bob-new-pw" });
+    expect(res.status).toBe(204);
+    expect(sessions.validateAndTouch(bobToken)).toBeNull();
+    const bob = users.findByUsername("bob");
+    expect(await users.verifyPassword("bob-new-pw", bob!.passwordHash)).toBe(true);
+    expect(await users.verifyPassword("pw-bob-bob", bob!.passwordHash)).toBe(false);
+  });
+
+  it("POST /:id/reset-password 404 on unknown user", async () => {
+    const res = await request(app)
+      .post(`/api/users/not-a-real-id/reset-password`)
+      .set("Cookie", aliceCookie)
+      .send({ newPassword: "anything-here" });
+    expect(res.status).toBe(404);
+  });
+
+  it("POST /:id/reset-password 400 on short password", async () => {
+    const res = await request(app)
+      .post(`/api/users/${bobId}/reset-password`)
+      .set("Cookie", aliceCookie)
+      .send({ newPassword: "short" });
+    expect(res.status).toBe(400);
+  });
+
+  it("returns 201 even if audit insert fails (POST /api/users)", async () => {
+    // Build a broken audit store that throws on record()
+    const brokenAudit = {
+      record: () => { throw new Error("simulated disk-full"); },
+      list: () => [],
+    };
+    // Reassemble app with the broken audit
+    const localApp = express();
+    localApp.use(express.json());
+    localApp.use(cookieParser());
+    localApp.use("/api", createRequireAuth(sessions));
+    localApp.use(
+      "/api/users",
+      createUsersRouter(users, sessions, brokenAudit, pino({ level: "silent" }))
+    );
+    const res = await request(localApp)
+      .post("/api/users")
+      .set("Cookie", aliceCookie)
+      .send({ username: "charlie", password: "charlie-pw" });
+    expect(res.status).toBe(201);
+    expect(users.countUsers()).toBe(3);
+  });
+
+  it("POST /:id/reset-password on self preserves the actor's current session", async () => {
+    // Alice resets her OWN password
+    const res = await request(app)
+      .post(`/api/users/${aliceId}/reset-password`)
+      .set("Cookie", aliceCookie)
+      .send({ newPassword: "alice-new-pw" });
+    expect(res.status).toBe(204);
+
+    // Alice's CURRENT session should still work
+    // (we'd need a protected endpoint to verify; use GET /api/users which is already mounted)
+    const followUp = await request(app).get("/api/users").set("Cookie", aliceCookie);
+    expect(followUp.status).toBe(200);
+
+    // The password hash IS updated (sanity check)
+    const alice = users.findById(aliceId);
+    expect(await users.verifyPassword("alice-new-pw", alice!.passwordHash)).toBe(true);
+  });
+
+  it("POST /:id/reset-password on another user does NOT preserve any of target's sessions", async () => {
+    const bobToken = sessions.createSession(bobId).token;
+    const res = await request(app)
+      .post(`/api/users/${bobId}/reset-password`)
+      .set("Cookie", aliceCookie)
+      .send({ newPassword: "bob-new-pw" });
+    expect(res.status).toBe(204);
+    // Bob's session should be dead
+    expect(sessions.validateAndTouch(bobToken)).toBeNull();
+  });
+
+  it("POST / defaults new user to role=member when role omitted", async () => {
+    const res = await request(app)
+      .post("/api/users")
+      .set("Cookie", aliceCookie)
+      .send({ username: "carol", password: "pw-carol-pw" });
+    expect(res.status).toBe(201);
+    expect(res.body.role).toBe("member");
+  });
+
+  it("POST / accepts role=admin", async () => {
+    const res = await request(app)
+      .post("/api/users")
+      .set("Cookie", aliceCookie)
+      .send({ username: "carol", password: "pw-carol-pw", role: "admin" });
+    expect(res.status).toBe(201);
+    expect(res.body.role).toBe("admin");
+    expect(users.countAdmins()).toBe(2);
+  });
+
+  it("PATCH /:id/role can change role between admin and member", async () => {
+    const res = await request(app)
+      .patch(`/api/users/${bobId}/role`)
+      .set("Cookie", aliceCookie)
+      .send({ role: "admin" });
+    expect(res.status).toBe(204);
+    expect(users.findById(bobId)!.role).toBe("admin");
+  });
+
+  it("PATCH /:id/role blocks demoting the last admin", async () => {
+    // alice is the only admin. Demoting her would leave 0 admins. Block.
+    const res = await request(app)
+      .patch(`/api/users/${aliceId}/role`)
+      .set("Cookie", aliceCookie)
+      .send({ role: "member" });
+    expect(res.status).toBe(400);
+    expect(res.body).toEqual({ error: "cannot demote last admin" });
+  });
+
+  it("PATCH /:id/role allows demoting an admin when other admins exist", async () => {
+    // Promote bob first
+    users.setRole(bobId, "admin");
+    // Now both are admins. Demoting alice should work.
+    const res = await request(app)
+      .patch(`/api/users/${aliceId}/role`)
+      .set("Cookie", aliceCookie)
+      .send({ role: "member" });
+    expect(res.status).toBe(204);
+  });
+
+  it("PATCH /:id/role 400 on invalid role", async () => {
+    const res = await request(app)
+      .patch(`/api/users/${bobId}/role`)
+      .set("Cookie", aliceCookie)
+      .send({ role: "superuser" });
+    expect(res.status).toBe(400);
+  });
+
+  it("PATCH /:id/role 404 on unknown user", async () => {
+    const res = await request(app)
+      .patch(`/api/users/not-a-real-id/role`)
+      .set("Cookie", aliceCookie)
+      .send({ role: "admin" });
+    expect(res.status).toBe(404);
+  });
+});

src/web/api/users.ts

@@ -0,0 +1,166 @@
+import { Router } from "express";
+import type { Logger } from "../../logger.js";
+import type { UserStore } from "../../data/users.js";
+import { UsernameTakenError } from "../../data/users.js";
+import type { SessionStore } from "../../data/sessions.js";
+import type { AuditStore } from "../../data/audit.js";
+import { extractSessionToken } from "../auth/validateSession.js";
+
+function isValidUsername(v: unknown): v is string {
+  return typeof v === "string" && /^[A-Za-z0-9_\-.]{3,32}$/.test(v);
+}
+
+function isValidPassword(v: unknown): v is string {
+  return typeof v === "string" && v.length >= 8 && v.length <= 200;
+}
+
+export function createUsersRouter(
+  users: UserStore,
+  sessions: SessionStore,
+  audit: AuditStore,
+  logger: Logger
+): Router {
+  const router = Router();
+
+  router.get("/", (_req, res) => {
+    res.json({ users: users.listUsers() });
+  });
+
+  router.post("/", async (req, res) => {
+    const { username, password, role: roleInput } = req.body ?? {};
+    if (!isValidUsername(username) || !isValidPassword(password)) {
+      res.status(400).json({ error: "invalid username or password" });
+      return;
+    }
+    const role: "admin" | "member" = roleInput === "admin" ? "admin" : "member";
+    try {
+      const u = await users.createUser(username, password, role);
+      try {
+        audit.record({
+          actorId: req.user!.id, actorUsername: req.user!.username,
+          targetUserId: u.id, targetUsername: u.username,
+          action: "user.created",
+        });
+      } catch (auditErr) {
+        logger.warn({ err: auditErr, action: "user.created" }, "audit insert failed");
+      }
+      logger.info({ createdBy: req.user!.id, newUserId: u.id, username, role }, "User created");
+      res.status(201).json({ id: u.id, username: u.username, role: u.role });
+    } catch (err) {
+      if (err instanceof UsernameTakenError) {
+        res.status(409).json({ error: "username taken" });
+        return;
+      }
+      logger.error({ err }, "createUser failed");
+      res.status(500).json({ error: "internal" });
+    }
+  });
+
+  router.delete("/:id", (req, res) => {
+    const targetId = req.params.id;
+    // Snapshot target's username BEFORE deletion for audit
+    const target = users.findById(targetId);
+    if (!target) {
+      res.status(404).json({ error: "not found" });
+      return;
+    }
+    if (targetId === req.user!.id) {
+      res.status(400).json({ error: "cannot delete self" });
+      return;
+    }
+    const result = users.deleteUserIfNotLastAdmin(targetId);
+    if (result === "not_found") {
+      res.status(404).json({ error: "not found" });
+      return;
+    }
+    if (result === "would_orphan") {
+      res.status(400).json({ error: "cannot delete last admin" });
+      return;
+    }
+    // FK CASCADE removes sessions; explicit call is belt-and-suspenders
+    sessions.deleteAllForUser(targetId);
+    try {
+      audit.record({
+        actorId: req.user!.id, actorUsername: req.user!.username,
+        targetUserId: target.id, targetUsername: target.username,
+        action: "user.deleted",
+      });
+    } catch (auditErr) {
+      logger.warn({ err: auditErr, action: "user.deleted" }, "audit insert failed");
+    }
+    logger.info({ deletedBy: req.user!.id, deletedUserId: targetId }, "User deleted");
+    res.status(204).end();
+  });
+
+  router.post("/:id/reset-password", async (req, res) => {
+    const { newPassword } = req.body ?? {};
+    if (!isValidPassword(newPassword)) {
+      res.status(400).json({ error: "invalid password" });
+      return;
+    }
+    const targetId = req.params.id;
+    const target = users.findById(targetId);
+    if (!target) {
+      res.status(404).json({ error: "not found" });
+      return;
+    }
+    await users.changePassword(targetId, newPassword);
+    // Invalidate all sessions for the target user (except current actor's if it's the same user)
+    const exceptToken = targetId === req.user!.id
+      ? (extractSessionToken(req.headers.cookie) ?? undefined)
+      : undefined;
+    sessions.deleteAllForUser(targetId, exceptToken);
+    try {
+      audit.record({
+        actorId: req.user!.id, actorUsername: req.user!.username,
+        targetUserId: target.id, targetUsername: target.username,
+        action: "user.password_reset",
+      });
+    } catch (auditErr) {
+      logger.warn({ err: auditErr, action: "user.password_reset" }, "audit insert failed");
+    }
+    logger.info({ resetBy: req.user!.id, targetUserId: targetId }, "Password reset");
+    res.status(204).end();
+  });
+
+  router.patch("/:id/role", (req, res) => {
+    const targetId = req.params.id;
+    const { role: newRole } = req.body ?? {};
+    if (newRole !== "admin" && newRole !== "member") {
+      res.status(400).json({ error: "invalid role" });
+      return;
+    }
+    // Snapshot the target's old role and username for audit (BEFORE the atomic update,
+    // so we record what actually changed; if the user is gone we'll skip audit).
+    const targetBefore = users.findById(targetId);
+    if (!targetBefore) {
+      res.status(404).json({ error: "not found" });
+      return;
+    }
+    const result = users.setRoleIfNotLastAdmin(targetId, newRole);
+    if (result === "not_found") {
+      res.status(404).json({ error: "not found" });
+      return;
+    }
+    if (result === "would_orphan") {
+      res.status(400).json({ error: "cannot demote last admin" });
+      return;
+    }
+    // Only audit when the role actually changed
+    if (targetBefore.role !== newRole) {
+      try {
+        audit.record({
+          actorId: req.user!.id, actorUsername: req.user!.username,
+          targetUserId: targetBefore.id, targetUsername: targetBefore.username,
+          action: "user.role_changed",
+        });
+      } catch (auditErr) {
+        logger.warn({ err: auditErr, action: "user.role_changed" }, "audit insert failed");
+      }
+      logger.info({ actorId: req.user!.id, targetId, newRole }, "User role changed");
+    }
+    res.status(204).end();
+  });
+
+  return router;
+}

src/web/auth/validateSession.ts

@@ -0,0 +1,38 @@
+import type { SessionStore, SessionValidation } from "../../data/sessions.js";
+
+export const SESSION_COOKIE_NAME = "tsmb_session";
+
+/**
+ * Validate the session cookie carried on an arbitrary HTTP-like header bag.
+ * Used by Express middleware (req.headers.cookie) AND by the raw WebSocket
+ * upgrade handler (req.headers.cookie) — they share this exact behavior.
+ */
+export function validateSessionFromHeaders(
+  rawCookieHeader: string | undefined,
+  sessions: SessionStore
+): SessionValidation | null {
+  if (!rawCookieHeader) return null;
+  const token = parseCookie(rawCookieHeader, SESSION_COOKIE_NAME);
+  if (!token) return null;
+  return sessions.validateAndTouch(token);
+}
+
+export function extractSessionToken(rawCookieHeader: string | undefined): string | null {
+  if (!rawCookieHeader) return null;
+  return parseCookie(rawCookieHeader, SESSION_COOKIE_NAME);
+}
+
+function parseCookie(header: string, name: string): string | null {
+  for (const part of header.split(";")) {
+    const trimmed = part.trim();
+    const eq = trimmed.indexOf("=");
+    if (eq < 1) continue;
+    if (trimmed.slice(0, eq) !== name) continue;
+    try {
+      return decodeURIComponent(trimmed.slice(eq + 1));
+    } catch {
+      return null;
+    }
+  }
+  return null;
+}

src/web/middleware/csrf.test.ts

@@ -0,0 +1,58 @@
+import { describe, it, expect, beforeEach } from "vitest";
+import express from "express";
+import request from "supertest";
+import { csrfOriginCheck } from "./csrf.js";
+
+describe("csrfOriginCheck middleware", () => {
+  let app: express.Express;
+
+  beforeEach(() => {
+    app = express();
+    app.use(csrfOriginCheck);
+    app.get("/", (_req, res) => res.json({ ok: true }));
+    app.post("/", (_req, res) => res.json({ ok: true }));
+  });
+
+  it("allows safe methods (GET/HEAD/OPTIONS) without Origin", async () => {
+    const res = await request(app).get("/");
+    expect(res.status).toBe(200);
+  });
+
+  it("rejects POST without Origin or Referer", async () => {
+    const res = await request(app).post("/");
+    expect(res.status).toBe(403);
+    expect(res.body).toEqual({ error: "bad origin" });
+  });
+
+  it("accepts POST when Origin host matches request host", async () => {
+    const res = await request(app)
+      .post("/")
+      .set("Host", "example.com")
+      .set("Origin", "https://example.com");
+    expect(res.status).toBe(200);
+  });
+
+  it("rejects POST when Origin host does not match request host", async () => {
+    const res = await request(app)
+      .post("/")
+      .set("Host", "example.com")
+      .set("Origin", "https://evil.com");
+    expect(res.status).toBe(403);
+  });
+
+  it("accepts POST when Referer host matches and Origin is absent", async () => {
+    const res = await request(app)
+      .post("/")
+      .set("Host", "example.com")
+      .set("Referer", "https://example.com/some/path");
+    expect(res.status).toBe(200);
+  });
+
+  it("rejects POST when Referer host does not match", async () => {
+    const res = await request(app)
+      .post("/")
+      .set("Host", "example.com")
+      .set("Referer", "https://evil.com/some/path");
+    expect(res.status).toBe(403);
+  });
+});

src/web/middleware/csrf.ts

@@ -0,0 +1,35 @@
+import type { Request, Response, NextFunction } from "express";
+
+const SAFE_METHODS = new Set(["GET", "HEAD", "OPTIONS"]);
+
+/**
+ * Same-origin CSRF protection. For mutating requests, the Origin or Referer
+ * header must indicate a host equal to the request's own host.
+ *
+ * SameSite=Lax on the session cookie blocks classic cross-site form posts;
+ * this header check covers the remaining attack surface.
+ */
+export function csrfOriginCheck(req: Request, res: Response, next: NextFunction): void {
+  if (SAFE_METHODS.has(req.method)) {
+    next();
+    return;
+  }
+  const expectedHost = req.get("host");
+  const originHeader = req.get("origin");
+  const refererHeader = req.get("referer");
+  const headerHost = hostOf(originHeader) ?? hostOf(refererHeader);
+  if (!headerHost || !expectedHost || headerHost !== expectedHost) {
+    res.status(403).json({ error: "bad origin" });
+    return;
+  }
+  next();
+}
+
+function hostOf(url: string | undefined): string | null {
+  if (!url) return null;
+  try {
+    return new URL(url).host;
+  } catch {
+    return null;
+  }
+}

src/web/middleware/rateLimit.test.ts

@@ -0,0 +1,41 @@
+import { describe, it, expect, beforeEach } from "vitest";
+import express from "express";
+import request from "supertest";
+import { createRateLimit } from "./rateLimit.js";
+
+describe("createRateLimit", () => {
+  let app: express.Express;
+
+  beforeEach(() => {
+    app = express();
+    // capacity=3, refill=1/sec → first 3 succeed, then 429 until refill.
+    app.use(createRateLimit({ capacity: 3, refillPerSec: 1 }));
+    app.get("/", (_req, res) => res.json({ ok: true }));
+  });
+
+  it("allows up to capacity bursts then rejects with 429", async () => {
+    expect((await request(app).get("/")).status).toBe(200);
+    expect((await request(app).get("/")).status).toBe(200);
+    expect((await request(app).get("/")).status).toBe(200);
+    const denied = await request(app).get("/");
+    expect(denied.status).toBe(429);
+    expect(denied.body).toEqual({ error: "rate limit exceeded" });
+    expect(denied.headers["retry-after"]).toBeDefined();
+  });
+
+  it("uses per-key buckets when keyFn is provided", async () => {
+    const customApp = express();
+    customApp.use(
+      createRateLimit({
+        capacity: 1,
+        refillPerSec: 0.001,
+        keyFn: (req) => req.get("x-user") ?? "anon",
+      })
+    );
+    customApp.get("/", (_req, res) => res.json({ ok: true }));
+    expect((await request(customApp).get("/").set("X-User", "alice")).status).toBe(200);
+    expect((await request(customApp).get("/").set("X-User", "alice")).status).toBe(429);
+    // Different user, separate bucket → still has a token.
+    expect((await request(customApp).get("/").set("X-User", "bob")).status).toBe(200);
+  });
+});

src/web/middleware/rateLimit.ts

@@ -0,0 +1,63 @@
+import type { Request, Response, NextFunction, RequestHandler } from "express";
+
+interface Bucket {
+  tokens: number;
+  lastRefillMs: number;
+}
+
+interface RateLimitOptions {
+  /** Bucket capacity (max burst). */
+  capacity: number;
+  /** Tokens refilled per second. */
+  refillPerSec: number;
+  /** Optional key function; defaults to req.ip. */
+  keyFn?: (req: Request) => string;
+}
+
+/**
+ * In-memory token-bucket rate limiter.
+ *
+ * Each unique key (default: req.ip) gets its own bucket. Refills continuously
+ * at `refillPerSec` up to `capacity`. Each request consumes 1 token; if no
+ * token is available, returns 429 with Retry-After.
+ *
+ * Buckets evict themselves after 10 minutes of inactivity to bound memory.
+ */
+export function createRateLimit(options: RateLimitOptions): RequestHandler {
+  const buckets = new Map<string, Bucket>();
+  const EVICT_AFTER_MS = 10 * 60 * 1000;
+  // Periodic eviction to bound memory under attack.
+  const evict = setInterval(() => {
+    const cutoff = Date.now() - EVICT_AFTER_MS;
+    for (const [k, b] of buckets) {
+      if (b.lastRefillMs < cutoff) buckets.delete(k);
+    }
+  }, 60_000);
+  // Unref the timer so it doesn't keep the process alive in tests.
+  if (typeof (evict as { unref?: () => void }).unref === "function") {
+    (evict as { unref: () => void }).unref();
+  }
+
+  const keyFn = options.keyFn ?? ((req) => req.ip ?? "unknown");
+
+  return function rateLimit(req: Request, res: Response, next: NextFunction): void {
+    const key = keyFn(req);
+    const now = Date.now();
+    let b = buckets.get(key);
+    if (!b) {
+      b = { tokens: options.capacity, lastRefillMs: now };
+      buckets.set(key, b);
+    }
+    const elapsedSec = (now - b.lastRefillMs) / 1000;
+    b.tokens = Math.min(options.capacity, b.tokens + elapsedSec * options.refillPerSec);
+    b.lastRefillMs = now;
+    if (b.tokens < 1) {
+      const waitSec = Math.ceil((1 - b.tokens) / options.refillPerSec);
+      res.setHeader("Retry-After", String(waitSec));
+      res.status(429).json({ error: "rate limit exceeded" });
+      return;
+    }
+    b.tokens -= 1;
+    next();
+  };
+}

src/web/middleware/requireAdmin.test.ts

@@ -0,0 +1,50 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import express from "express";
+import cookieParser from "cookie-parser";
+import request from "supertest";
+import { createDatabase, type BotDatabase } from "../../data/database.js";
+import { createUserStore } from "../../data/users.js";
+import { createSessionStore } from "../../data/sessions.js";
+import { createRequireAuth } from "./requireAuth.js";
+import { requireAdmin } from "./requireAdmin.js";
+import { SESSION_COOKIE_NAME } from "../auth/validateSession.js";
+
+describe("requireAdmin middleware", () => {
+  let botDb: BotDatabase;
+  let app: express.Express;
+  let adminCookie: string;
+  let memberCookie: string;
+
+  beforeEach(async () => {
+    botDb = createDatabase(":memory:");
+    const users = createUserStore(botDb.db);
+    const sessions = createSessionStore(botDb.db);
+    const admin = await users.createUser("admin", "pw-admin-pw", "admin");
+    const member = await users.createUser("member", "pw-member-pw", "member");
+    adminCookie = `${SESSION_COOKIE_NAME}=${sessions.createSession(admin.id).token}`;
+    memberCookie = `${SESSION_COOKIE_NAME}=${sessions.createSession(member.id).token}`;
+    app = express();
+    app.use(cookieParser());
+    app.use(createRequireAuth(sessions));
+    app.use(requireAdmin);
+    app.get("/admin-only", (_req, res) => res.json({ ok: true }));
+  });
+
+  afterEach(() => botDb.close());
+
+  it("rejects unauthenticated requests with 401", async () => {
+    const res = await request(app).get("/admin-only");
+    expect(res.status).toBe(401);
+  });
+
+  it("rejects member with 403", async () => {
+    const res = await request(app).get("/admin-only").set("Cookie", memberCookie);
+    expect(res.status).toBe(403);
+    expect(res.body).toEqual({ error: "forbidden" });
+  });
+
+  it("allows admin", async () => {
+    const res = await request(app).get("/admin-only").set("Cookie", adminCookie);
+    expect(res.status).toBe(200);
+  });
+});

src/web/middleware/requireAdmin.ts

@@ -0,0 +1,13 @@
+import type { Request, Response, NextFunction } from "express";
+
+export function requireAdmin(req: Request, res: Response, next: NextFunction): void {
+  if (!req.user) {
+    res.status(401).json({ error: "unauthenticated" });
+    return;
+  }
+  if (req.user.role !== "admin") {
+    res.status(403).json({ error: "forbidden" });
+    return;
+  }
+  next();
+}

src/web/middleware/requireAuth.test.ts

@@ -0,0 +1,69 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import express from "express";
+import cookieParser from "cookie-parser";
+import request from "supertest";
+import { createDatabase, type BotDatabase } from "../../data/database.js";
+import { createUserStore } from "../../data/users.js";
+import { createSessionStore } from "../../data/sessions.js";
+import { createRequireAuth } from "./requireAuth.js";
+import { SESSION_COOKIE_NAME } from "../auth/validateSession.js";
+
+describe("requireAuth middleware", () => {
+  let botDb: BotDatabase;
+  let app: express.Express;
+  let validToken: string;
+
+  beforeEach(async () => {
+    botDb = createDatabase(":memory:");
+    const users = createUserStore(botDb.db);
+    const sessions = createSessionStore(botDb.db);
+    const u = await users.createUser("alice", "pw-alice", "admin");
+    validToken = sessions.createSession(u.id).token;
+
+    app = express();
+    app.use(cookieParser());
+    app.use(createRequireAuth(sessions));
+    app.get("/protected", (req, res) => {
+      res.json({ ok: true, user: (req as any).user });
+    });
+  });
+
+  afterEach(() => {
+    botDb.close();
+  });
+
+  it("rejects requests without a session cookie", async () => {
+    const res = await request(app).get("/protected");
+    expect(res.status).toBe(401);
+    expect(res.body).toEqual({ error: "unauthenticated" });
+  });
+
+  it("rejects requests with an unknown session cookie", async () => {
+    const res = await request(app)
+      .get("/protected")
+      .set("Cookie", `${SESSION_COOKIE_NAME}=garbage`);
+    expect(res.status).toBe(401);
+  });
+
+  it("allows requests with a valid session cookie and attaches req.user", async () => {
+    const res = await request(app)
+      .get("/protected")
+      .set("Cookie", `${SESSION_COOKIE_NAME}=${validToken}`);
+    expect(res.status).toBe(200);
+    expect(res.body.ok).toBe(true);
+    expect(res.body.user.username).toBe("alice");
+    expect(res.body.user.role).toBe("admin");
+  });
+
+  it("rolls the cookie max-age forward on successful auth", async () => {
+    const res = await request(app)
+      .get("/protected")
+      .set("Cookie", `${SESSION_COOKIE_NAME}=${validToken}`);
+    expect(res.status).toBe(200);
+    const setCookieHeaders = res.headers["set-cookie"];
+    const arr = Array.isArray(setCookieHeaders) ? setCookieHeaders : setCookieHeaders ? [setCookieHeaders] : [];
+    const refreshed = arr.find((c) => c.startsWith(`${SESSION_COOKIE_NAME}=`));
+    expect(refreshed).toBeDefined();
+    expect(refreshed!).toMatch(/Max-Age=\d+/);
+  });
+});

src/web/middleware/requireAuth.ts

@@ -0,0 +1,37 @@
+import type { Request, Response, NextFunction, RequestHandler } from "express";
+import type { SessionStore } from "../../data/sessions.js";
+import { SESSION_TTL_MS } from "../../data/sessions.js";
+import {
+  validateSessionFromHeaders,
+  extractSessionToken,
+  SESSION_COOKIE_NAME,
+} from "../auth/validateSession.js";
+
+declare module "express-serve-static-core" {
+  interface Request {
+    user?: { id: string; username: string; role: "admin" | "member" };
+  }
+}
+
+export function createRequireAuth(sessions: SessionStore): RequestHandler {
+  return function requireAuth(req: Request, res: Response, next: NextFunction) {
+    const result = validateSessionFromHeaders(req.headers.cookie, sessions);
+    if (!result) {
+      res.clearCookie(SESSION_COOKIE_NAME, { path: "/" });
+      res.status(401).json({ error: "unauthenticated" });
+      return;
+    }
+    req.user = { id: result.userId, username: result.username, role: result.role };
+    const token = extractSessionToken(req.headers.cookie);
+    if (token) {
+      res.cookie(SESSION_COOKIE_NAME, token, {
+        httpOnly: true,
+        sameSite: "lax",
+        secure: req.secure,
+        path: "/",
+        maxAge: SESSION_TTL_MS,
+      });
+    }
+    next();
+  };
+}

src/web/security-headers.test.ts

@@ -0,0 +1,40 @@
+import { describe, it, expect } from "vitest";
+import express from "express";
+import request from "supertest";
+
+/**
+ * The clickjacking-defence middleware is mounted at the top of
+ * `createWebServer` in `server.ts`. This test asserts the exact behavior
+ * we expect from that middleware in isolation. The wiring inside
+ * `server.ts` is verified by code review (git diff).
+ */
+describe("security headers (anti-clickjacking)", () => {
+  function buildApp() {
+    const app = express();
+    app.use((_req, res, next) => {
+      res.setHeader("X-Frame-Options", "DENY");
+      res.setHeader("Content-Security-Policy", "frame-ancestors 'none'");
+      next();
+    });
+    app.get("/", (_req, res) => res.json({ ok: true }));
+    app.post("/", (_req, res) => res.json({ ok: true }));
+    return app;
+  }
+
+  it("sets X-Frame-Options: DENY on GET responses", async () => {
+    const res = await request(buildApp()).get("/");
+    expect(res.status).toBe(200);
+    expect(res.headers["x-frame-options"]).toBe("DENY");
+  });
+
+  it("sets Content-Security-Policy frame-ancestors 'none' on GET responses", async () => {
+    const res = await request(buildApp()).get("/");
+    expect(res.headers["content-security-policy"]).toBe("frame-ancestors 'none'");
+  });
+
+  it("sets both headers on POST responses too", async () => {
+    const res = await request(buildApp()).post("/");
+    expect(res.headers["x-frame-options"]).toBe("DENY");
+    expect(res.headers["content-security-policy"]).toBe("frame-ancestors 'none'");
+  });
+});

src/web/server.ts

@@ -1,6 +1,7 @@
 import express from "express";
 import http from "node:http";
 import path from "node:path";
+import cookieParser from "cookie-parser";
 import { WebSocketServer } from "ws";
 import type { BotManager } from "../bot/manager.js";
 import type { MusicProvider } from "../music/provider.js";
@@ -8,11 +9,25 @@ import type { BotDatabase } from "../data/database.js";
 import type { BotConfig } from "../data/config.js";
 import type { Logger } from "../logger.js";
 import type { CookieStore } from "../music/auth.js";
+import type { AvatarStore } from "../data/avatars.js";
 import { createBotRouter } from "./api/bot.js";
 import { createMusicRouter } from "./api/music.js";
 import { createPlayerRouter } from "./api/player.js";
 import { createAuthRouter } from "./api/auth.js";
+import { createSessionRouter } from "./api/session.js";
+import { createUsersRouter } from "./api/users.js";
+import { createAuditStore } from "../data/audit.js";
+import { createAuditRouter } from "./api/audit.js";
 import { setupWebSocket } from "./websocket.js";
+import { createUserStore } from "../data/users.js";
+import { createSessionStore } from "../data/sessions.js";
+import { createRequireAuth } from "./middleware/requireAuth.js";
+import { requireAdmin } from "./middleware/requireAdmin.js";
+import { csrfOriginCheck } from "./middleware/csrf.js";
+import { createRateLimit } from "./middleware/rateLimit.js";
+import { validateSessionFromHeaders } from "./auth/validateSession.js";
+
+const SESSION_CLEANUP_INTERVAL_MS = 60 * 60 * 1000; // 1 hour
 
 export interface WebServerOptions {
   port: number;
@@ -25,6 +40,7 @@ export interface WebServerOptions {
   configPath: string;
   logger: Logger;
   cookieStore?: CookieStore;
+  avatarStore: AvatarStore;
   staticDir?: string;
 }
 
@@ -39,20 +55,61 @@ export function createWebServer(options: WebServerOptions): WebServer {
   const logger = options.logger.child({ component: "web" });
 
   if (options.config.trustProxy) {
-    // Honor X-Forwarded-* from a reverse proxy (nginx/Caddy/Cloudflare).
     app.set("trust proxy", true);
   }
 
-  app.use(express.json());
+  // Security headers: prevent the WebUI from being embedded in a third-party
+  // iframe (clickjacking defence). CSP frame-ancestors is the modern equivalent
+  // of X-Frame-Options; both are set for compatibility across browsers.
+  app.use((_req, res, next) => {
+    res.setHeader("X-Frame-Options", "DENY");
+    res.setHeader("Content-Security-Policy", "frame-ancestors 'none'");
+    next();
+  });
+
+  app.use(express.json({ limit: "400kb" }));
+  app.use(cookieParser());
+
+  const users = createUserStore(options.database.db);
+  const sessions = createSessionStore(options.database.db);
+  const audit = createAuditStore(options.database.db);
+
+  // ─── Public routes (no auth, no CSRF) ───────────────────────────────────
+  app.get("/api/health", (_req, res) => {
+    res.json({ status: "ok", version: "0.1.0" });
+  });
 
   app.get("/api/config/public-url", (_req, res) => {
     const raw = (options.config.publicUrl ?? "").trim();
     res.json({ publicUrl: raw ? raw.replace(/\/+$/, "") : null });
   });
 
+  // Anti-DoS: throttle expensive (bcrypt) auth endpoints.
+  // 5 req per minute per IP for /login (capacity 5, refill 5/60 = ~0.083/sec).
+  // 3 req per minute per IP for /setup (more limited; first-run is rare).
+  const loginLimit = createRateLimit({ capacity: 5, refillPerSec: 5 / 60 });
+  const setupLimit = createRateLimit({ capacity: 3, refillPerSec: 3 / 60 });
+  app.use("/api/session/login", loginLimit);
+  app.use("/api/session/setup", setupLimit);
+
+  app.use("/api/session", createSessionRouter(users, sessions, audit, logger));
+
+  // ─── Gates for everything else under /api ───────────────────────────────
+  const requireAuth = createRequireAuth(sessions);
+  app.use("/api", csrfOriginCheck);
+  app.use("/api", requireAuth);
+
+  // ─── Protected routes ───────────────────────────────────────────────────
   app.use(
     "/api/bot",
-    createBotRouter(options.botManager, options.config, options.configPath, logger)
+    createBotRouter(
+      options.botManager,
+      options.config,
+      options.configPath,
+      logger,
+      options.database,
+      options.avatarStore,
+    )
   );
   app.use(
     "/api/music",
@@ -66,11 +123,11 @@ export function createWebServer(options: WebServerOptions): WebServer {
     "/api/auth",
     createAuthRouter(options.neteaseProvider, options.qqProvider, options.bilibiliProvider, logger, options.cookieStore)
   );
+  // admin-only routes
+  app.use("/api/users", requireAdmin, createUsersRouter(users, sessions, audit, logger));
+  app.use("/api/audit", requireAdmin, createAuditRouter(audit));
 
-  app.get("/api/health", (_req, res) => {
-    res.json({ status: "ok", version: "0.1.0" });
-  });
-
+  // ─── Static SPA (public) ────────────────────────────────────────────────
   if (options.staticDir) {
     app.use(express.static(options.staticDir));
     app.get(/^(?!\/api|\/ws)/, (_req, res) => {
@@ -82,22 +139,68 @@ export function createWebServer(options: WebServerOptions): WebServer {
     logger.error({ err }, "HTTP server error");
   });
 
-  const wss = new WebSocketServer({ server, path: "/ws" });
+  // ─── WebSocket with manual upgrade auth ────────────────────────────────
+  const wss = new WebSocketServer({ noServer: true });
   wss.on("error", (err) => {
     logger.error({ err }, "WebSocket server error");
   });
+  server.on("upgrade", (req, socket, head) => {
+    if (req.url !== "/ws") {
+      socket.destroy();
+      return;
+    }
+    const reqHost = req.headers.host;
+    const originHeader = req.headers.origin;
+    if (originHeader) {
+      let originHost: string | null = null;
+      try {
+        originHost = new URL(originHeader).host;
+      } catch {
+        // fall through; treat as missing/invalid origin
+      }
+      if (!originHost || originHost !== reqHost) {
+        socket.write("HTTP/1.1 403 Forbidden\r\nConnection: close\r\n\r\n");
+        socket.destroy();
+        return;
+      }
+    }
+    const result = validateSessionFromHeaders(req.headers.cookie as string | undefined, sessions);
+    if (!result) {
+      socket.write("HTTP/1.1 401 Unauthorized\r\nConnection: close\r\n\r\n");
+      socket.destroy();
+      return;
+    }
+    wss.handleUpgrade(req, socket, head, (ws) => {
+      (ws as unknown as { userId: string }).userId = result.userId;
+      wss.emit("connection", ws, req);
+    });
+  });
   const cleanupWs = setupWebSocket(wss, options.botManager, logger);
 
+  // ─── Session cleanup interval ──────────────────────────────────────────
+  let cleanupTimer: ReturnType<typeof setInterval> | null = null;
+
   return {
     async start(): Promise<void> {
       return new Promise((resolve) => {
         server.listen(options.port, () => {
           logger.info({ port: options.port }, "Web server started");
+          cleanupTimer = setInterval(() => {
+            try {
+              sessions.cleanupExpired();
+            } catch (err) {
+              logger.error({ err }, "session cleanup failed");
+            }
+          }, SESSION_CLEANUP_INTERVAL_MS);
           resolve();
         });
       });
     },
     stop(): void {
+      if (cleanupTimer) {
+        clearInterval(cleanupTimer);
+        cleanupTimer = null;
+      }
       cleanupWs();
       wss.close();
       server.close();

src/web/websocket-auth.test.ts

@@ -0,0 +1,74 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import express from "express";
+import http from "node:http";
+import { WebSocketServer, WebSocket as WSClient } from "ws";
+import { AddressInfo } from "node:net";
+import { createDatabase, type BotDatabase } from "../data/database.js";
+import { createUserStore } from "../data/users.js";
+import { createSessionStore } from "../data/sessions.js";
+import { validateSessionFromHeaders, SESSION_COOKIE_NAME } from "./auth/validateSession.js";
+
+function buildServer(sessions: ReturnType<typeof createSessionStore>) {
+  const app = express();
+  const server = http.createServer(app);
+  const wss = new WebSocketServer({ noServer: true });
+  wss.on("connection", (ws) => ws.send("hello"));
+  server.on("upgrade", (req, socket, head) => {
+    if (req.url !== "/ws") return socket.destroy();
+    const r = validateSessionFromHeaders(req.headers.cookie as string | undefined, sessions);
+    if (!r) {
+      socket.write("HTTP/1.1 401 Unauthorized\r\nConnection: close\r\n\r\n");
+      socket.destroy();
+      return;
+    }
+    wss.handleUpgrade(req, socket, head, (ws) => wss.emit("connection", ws, req));
+  });
+  return { server, wss };
+}
+
+describe("WebSocket auth at upgrade", () => {
+  let botDb: BotDatabase;
+  let httpServer: http.Server;
+  let port: number;
+  let validToken: string;
+
+  beforeEach(async () => {
+    botDb = createDatabase(":memory:");
+    const users = createUserStore(botDb.db);
+    const sessions = createSessionStore(botDb.db);
+    const u = await users.createUser("alice", "pw-alice", "admin");
+    validToken = sessions.createSession(u.id).token;
+
+    const { server } = buildServer(sessions);
+    httpServer = server;
+    await new Promise<void>((resolve) => httpServer.listen(0, resolve));
+    port = (httpServer.address() as AddressInfo).port;
+  });
+
+  afterEach(async () => {
+    await new Promise<void>((resolve) => httpServer.close(() => resolve()));
+    botDb.close();
+  });
+
+  it("rejects upgrade without cookie (server-side close before open)", async () => {
+    const ws = new WSClient(`ws://127.0.0.1:${port}/ws`);
+    const result = await new Promise<string>((resolve) => {
+      ws.on("open", () => resolve("opened"));
+      ws.on("unexpected-response", (_req, res) => resolve(`status:${res.statusCode}`));
+      ws.on("error", () => resolve("error"));
+    });
+    expect(result).toMatch(/^status:401$|^error$/);
+  });
+
+  it("accepts upgrade with a valid cookie", async () => {
+    const ws = new WSClient(`ws://127.0.0.1:${port}/ws`, {
+      headers: { Cookie: `${SESSION_COOKIE_NAME}=${validToken}` },
+    });
+    const msg = await new Promise<string>((resolve, reject) => {
+      ws.on("message", (data) => resolve(data.toString()));
+      ws.on("error", reject);
+    });
+    expect(msg).toBe("hello");
+    ws.close();
+  });
+});

web/src/App.vue

@@ -6,6 +6,7 @@
     </main>
     <Player />
     <Toast />
+    <Queue class="mobile-queue" :open="mobileQueueOpen" @close="mobileQueueOpen = false" />
 
     <!-- Mobile mini player -->
     <div v-if="currentSong" class="m-player" @click="router.push('/lyrics')">
@@ -17,12 +18,38 @@
         <div class="m-player-name">{{ currentSong.name }}</div>
         <div class="m-player-artist">{{ currentSong.artist }}</div>
       </div>
-      <button class="m-player-btn" @click.stop="playerStore.isPlaying ? playerStore.pause() : playerStore.resume()">
-        <Icon :icon="playerStore.isPlaying ? 'mdi:pause' : 'mdi:play'" />
-      </button>
-      <button class="m-player-btn" @click.stop="playerStore.next()">
-        <Icon icon="mdi:skip-next" />
-      </button>
+      <div class="m-player-controls" @click.stop>
+        <button class="m-player-btn" @click="playerStore.prev()">
+          <Icon icon="mdi:skip-previous" />
+        </button>
+        <button class="m-player-btn" @click="playerStore.isPlaying ? playerStore.pause() : playerStore.resume()">
+          <Icon :icon="playerStore.isPlaying ? 'mdi:pause' : 'mdi:play'" />
+        </button>
+        <button class="m-player-btn" @click="playerStore.next()">
+          <Icon icon="mdi:skip-next" />
+        </button>
+        <button class="m-player-btn" @click="cycleMobileMode">
+          <Icon :icon="mobileModeIcon" />
+        </button>
+        <button class="m-player-btn" @click="toggleMobileQueue">
+          <Icon icon="mdi:playlist-music" />
+        </button>
+        <button class="m-player-btn" @click="toggleMobileVolume">
+          <Icon icon="mdi:volume-high" />
+        </button>
+      </div>
+      <div v-if="mobileVolumeOpen" class="m-volume-popover" @click.stop>
+        <Icon icon="mdi:volume-high" class="m-volume-icon" />
+        <input
+          type="range"
+          min="0"
+          max="100"
+          :value="mobileVolume"
+          class="m-volume-slider"
+          @input="onMobileVolumeChange"
+        />
+        <span class="m-volume-value">{{ mobileVolume }}</span>
+      </div>
     </div>
 
     <!-- Mobile bottom tab bar -->
@@ -57,6 +84,7 @@ import Navbar from './components/Navbar.vue';
 import Player from './components/Player.vue';
 import CoverArt from './components/CoverArt.vue';
 import Toast from './components/Toast.vue';
+import Queue from './components/Queue.vue';
 
 const playerStore = usePlayerStore();
 const theme = computed(() => playerStore.theme);
@@ -64,6 +92,18 @@ const route = useRoute();
 const router = useRouter();
 const { connect } = useWebSocket();
 const currentSong = computed(() => playerStore.currentSong);
+const mobileVolume = computed(() => playerStore.activeBot?.volume ?? 75);
+const mobileMode = computed(() => playerStore.activeBot?.playMode ?? 'seq');
+const mobileModeOrder = ['seq', 'loop', 'random', 'rloop'];
+const mobileModeIcons: Record<string, string> = {
+  seq: 'mdi:arrow-right',
+  loop: 'mdi:repeat',
+  random: 'mdi:shuffle',
+  rloop: 'mdi:repeat-once',
+};
+const mobileModeIcon = computed(() => mobileModeIcons[mobileMode.value] ?? mobileModeIcons.seq);
+const mobileVolumeOpen = ref(false);
+const mobileQueueOpen = ref(false);
 
 const mobileProgressPct = ref(0);
 let syncTimer: ReturnType<typeof setInterval> | null = null;
@@ -77,6 +117,29 @@ function updateMobileProgress() {
   mobileRaf = requestAnimationFrame(updateMobileProgress);
 }
 
+function onMobileVolumeChange(e: Event) {
+  const volume = Number((e.target as HTMLInputElement).value);
+  playerStore.setVolume(volume);
+}
+
+function toggleMobileVolume() {
+  mobileVolumeOpen.value = !mobileVolumeOpen.value;
+  if (mobileVolumeOpen.value) mobileQueueOpen.value = false;
+}
+
+function toggleMobileQueue() {
+  mobileQueueOpen.value = !mobileQueueOpen.value;
+  if (mobileQueueOpen.value) mobileVolumeOpen.value = false;
+}
+
+function cycleMobileMode() {
+  const currentIndex = mobileModeOrder.indexOf(mobileMode.value);
+  const nextMode = mobileModeOrder[(currentIndex + 1) % mobileModeOrder.length] ?? mobileModeOrder[0];
+  mobileVolumeOpen.value = false;
+  mobileQueueOpen.value = false;
+  playerStore.setMode(nextMode);
+}
+
 onMounted(() => {
   playerStore.loadTheme();
   connect();
@@ -132,6 +195,14 @@ onUnmounted(() => {
   }
 }
 
+.mobile-queue {
+  display: none;
+
+  @media (max-width: 768px) {
+    display: flex;
+  }
+}
+
 .m-player-progress {
   position: absolute;
   top: 0;
@@ -151,6 +222,13 @@ onUnmounted(() => {
   min-width: 0;
 }
 
+.m-player-controls {
+  display: flex;
+  align-items: center;
+  gap: 4px;
+  flex: 0 0 auto;
+}
+
 .m-player-name {
   font-size: 13px;
   font-weight: 500;
@@ -168,16 +246,64 @@ onUnmounted(() => {
 }
 
 .m-player-btn {
-  width: 32px;
+  width: 28px;
   height: 32px;
   display: flex;
   align-items: center;
   justify-content: center;
-  font-size: 22px;
+  font-size: 20px;
   opacity: 0.85;
   flex-shrink: 0;
 }
 
+.m-volume-popover {
+  position: absolute;
+  right: 8px;
+  bottom: calc(100% + 8px);
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  width: min(260px, calc(100vw - 32px));
+  padding: 10px 12px;
+  background: var(--bg-secondary);
+  border: 1px solid var(--border-color);
+  border-radius: var(--radius-md);
+  box-shadow: var(--shadow-dropdown);
+  cursor: default;
+}
+
+.m-volume-icon {
+  flex: 0 0 auto;
+  font-size: 18px;
+  color: var(--text-secondary);
+}
+
+.m-volume-slider {
+  flex: 1 1 auto;
+  min-width: 0;
+  height: 4px;
+  appearance: none;
+  background: var(--border-color);
+  border-radius: 2px;
+  outline: none;
+
+  &::-webkit-slider-thumb {
+    appearance: none;
+    width: 16px;
+    height: 16px;
+    background: var(--color-primary);
+    border-radius: 50%;
+  }
+}
+
+.m-volume-value {
+  flex: 0 0 30px;
+  font-size: 12px;
+  color: var(--text-secondary);
+  text-align: right;
+  font-variant-numeric: tabular-nums;
+}
+
 // Mobile bottom tab bar
 .m-tabbar {
   position: fixed;

web/src/api/http.ts

@@ -0,0 +1,49 @@
+import router from '../router/index.js';
+import { useSession } from '../composables/useSession.js';
+
+let installed = false;
+const nativeFetch: typeof window.fetch = window.fetch.bind(window);
+
+/**
+ * Wraps fetch so every call:
+ *   - sends cookies (`credentials: 'same-origin'`)
+ *   - on 401 from /api/*: clear local session, redirect to /login
+ *
+ * Always uses the captured native fetch, never the (possibly wrapped) global.
+ */
+export function apiFetch(input: RequestInfo | URL, init: RequestInit = {}): Promise<Response> {
+  const merged: RequestInit = {
+    credentials: 'same-origin',
+    ...init,
+    headers: { ...(init.headers ?? {}) },
+  };
+  return nativeFetch(input, merged).then(async (res) => {
+    if (res.status === 401 && shouldTriggerRefresh(input)) {
+      const session = useSession();
+      await session.refresh();
+      const current = router.currentRoute.value;
+      if (current.name !== 'login' && current.name !== 'first-run') {
+        await router.replace({ name: 'login', query: { next: current.fullPath } });
+      }
+    }
+    return res;
+  });
+}
+
+function shouldTriggerRefresh(input: RequestInfo | URL): boolean {
+  const url = typeof input === 'string' ? input : input instanceof URL ? input.toString() : input.url;
+  return url.startsWith('/api/') && !url.startsWith('/api/session/');
+}
+
+/**
+ * Replaces window.fetch with apiFetch so existing call sites do not need to be touched.
+ * Call once at app startup.
+ */
+export function installApiClient(): void {
+  if (installed) return;
+  installed = true;
+  window.fetch = ((input: RequestInfo | URL, init?: RequestInit) => {
+    return apiFetch(input, init ?? {});
+  }) as typeof window.fetch;
+  (window as unknown as { __originalFetch?: typeof fetch }).__originalFetch = nativeFetch;
+}

web/src/components/AvatarUpload.vue

@@ -0,0 +1,99 @@
+<template>
+  <div class="avatar-upload">
+    <div class="preview" :class="{ empty: !previewUrl }">
+      <img v-if="previewUrl" :src="previewUrl" alt="avatar" />
+      <Icon v-else icon="mdi:account-circle-outline" />
+    </div>
+    <div class="actions">
+      <input
+        ref="fileInput"
+        type="file"
+        accept="image/png,image/jpeg,image/webp"
+        class="hidden"
+        @change="onFile"
+      />
+      <button type="button" class="btn-sm" @click="fileInput?.click()">
+        {{ previewUrl ? '更换' : '上传' }}
+      </button>
+      <button v-if="previewUrl" type="button" class="btn-sm btn-danger" @click="clear">
+        删除
+      </button>
+    </div>
+    <p v-if="error" class="hint error">{{ error }}</p>
+    <p v-else class="hint">PNG / JPG / WebP，≤200 KB</p>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { ref, watch } from 'vue';
+import { Icon } from '@iconify/vue';
+
+const props = defineProps<{ modelValue: string | null }>();
+const emit = defineEmits<{ 'update:modelValue': [value: string | null] }>();
+
+const previewUrl = ref<string | null>(props.modelValue);
+const error = ref<string | null>(null);
+const fileInput = ref<HTMLInputElement | null>(null);
+
+watch(() => props.modelValue, (v) => { previewUrl.value = v; });
+
+function onFile(ev: Event) {
+  const file = (ev.target as HTMLInputElement).files?.[0];
+  if (!file) return;
+  if (!['image/png', 'image/jpeg', 'image/webp'].includes(file.type)) {
+    error.value = '仅支持 PNG / JPG / WebP';
+    return;
+  }
+  if (file.size > 200 * 1024) {
+    error.value = `图片 ${(file.size / 1024).toFixed(0)} KB 超过 200 KB 上限`;
+    return;
+  }
+  error.value = null;
+  const reader = new FileReader();
+  reader.onload = () => {
+    const dataUrl = reader.result as string;
+    previewUrl.value = dataUrl;
+    emit('update:modelValue', dataUrl);
+  };
+  reader.readAsDataURL(file);
+}
+
+function clear() {
+  previewUrl.value = null;
+  emit('update:modelValue', null);
+  if (fileInput.value) fileInput.value.value = '';
+}
+</script>
+
+<style lang="scss" scoped>
+.avatar-upload { display: flex; flex-direction: column; gap: 8px; align-items: flex-start; }
+
+.preview {
+  width: 80px; height: 80px; border-radius: 50%;
+  background: var(--bg-card); display: flex; align-items: center; justify-content: center;
+  overflow: hidden;
+
+  img { width: 100%; height: 100%; object-fit: cover; }
+  &.empty :deep(svg) { font-size: 48px; opacity: 0.4; }
+}
+
+.actions { display: flex; gap: 8px; }
+.hidden { display: none; }
+
+.btn-sm {
+  padding: 6px 14px;
+  background: var(--hover-bg);
+  border-radius: var(--radius-sm);
+  font-size: 12px;
+  font-weight: 600;
+  transition: all var(--transition-fast);
+  &:hover { background: var(--color-primary); color: white; }
+}
+
+.btn-danger {
+  &:hover { background: #f44336; color: white; }
+}
+
+.hint { font-size: 12px; opacity: 0.6; margin: 0; }
+.hint.error { color: #f44336; opacity: 1; }
+</style>

web/src/components/CustomAvatarRow.vue

@@ -0,0 +1,59 @@
+<template>
+  <AvatarUpload v-model="avatarDataUrl" />
+</template>
+
+<script setup lang="ts">
+import { ref, onMounted, watch, nextTick } from 'vue';
+import axios from 'axios';
+import AvatarUpload from './AvatarUpload.vue';
+
+const props = defineProps<{ botId: string }>();
+const avatarDataUrl = ref<string | null>(null);
+// Stays true until the watcher queued by the load-time assignment has run,
+// so the initial null → loaded-data-url transition does not fire a redundant
+// PUT echoing the just-fetched bytes back to the server.
+let initializing = true;
+
+async function loadCurrent() {
+  try {
+    const res = await axios.get(`/api/bot/${props.botId}/avatar`, { responseType: 'blob' });
+    const blob = res.data as Blob;
+    avatarDataUrl.value = await blobToDataUrl(blob);
+  } catch (err: any) {
+    if (err?.response?.status !== 404) {
+      console.warn('failed to load avatar', err);
+    }
+    avatarDataUrl.value = null;
+  } finally {
+    // Wait for the watcher's flush queue to drain (it'll see initializing=true
+    // and bail), then release for real user-driven changes.
+    await nextTick();
+    initializing = false;
+  }
+}
+
+function blobToDataUrl(blob: Blob): Promise<string> {
+  return new Promise((resolve, reject) => {
+    const reader = new FileReader();
+    reader.onload = () => resolve(reader.result as string);
+    reader.onerror = () => reject(reader.error);
+    reader.readAsDataURL(blob);
+  });
+}
+
+watch(avatarDataUrl, async (newVal, oldVal) => {
+  if (initializing) return;
+  if (newVal === oldVal) return;
+  try {
+    if (newVal && newVal.startsWith('data:')) {
+      await axios.put(`/api/bot/${props.botId}/avatar`, { dataUrl: newVal });
+    } else if (newVal === null) {
+      await axios.delete(`/api/bot/${props.botId}/avatar`);
+    }
+  } catch (err) {
+    console.warn('avatar update failed', err);
+  }
+});
+
+onMounted(loadCurrent);
+</script>

web/src/components/Navbar.vue

@@ -88,6 +88,16 @@
       <RouterLink to="/settings" class="settings-btn">
         <Icon icon="mdi:cog" />
       </RouterLink>
+
+      <div v-if="session.currentUser.value" class="nav-user">
+        <span class="nav-user-name">{{ session.currentUser.value.username }}</span>
+        <span class="nav-user-role" :class="`role-${session.currentUser.value.role}`">
+          {{ session.currentUser.value.role === 'admin' ? '管理员' : '成员' }}
+        </span>
+        <button class="nav-user-logout" @click="onLogout" title="退出">
+          <Icon icon="mdi:logout" />
+        </button>
+      </div>
     </div>
   </nav>
 
@@ -114,10 +124,19 @@
 
 <script setup lang="ts">
 import { computed, ref, onMounted, onUnmounted, nextTick, reactive } from 'vue';
+import { useRouter } from 'vue-router';
 import { Icon } from '@iconify/vue';
 import { usePlayerStore } from '../stores/player.js';
+import { useSession } from '../composables/useSession.js';
 
 const store = usePlayerStore();
+const session = useSession();
+const navRouter = useRouter();
+
+async function onLogout() {
+  await session.logout();
+  navRouter.replace({ name: 'login' });
+}
 const activeBot = computed(() => store.activeBot);
 const dropdownOpen = ref(false);
 const selectorRef = ref<HTMLElement | null>(null);
@@ -643,4 +662,22 @@ onUnmounted(() => {
     }
   }
 }
+
+.nav-user {
+  display: flex; align-items: center; gap: 8px; margin-left: 12px;
+  color: var(--text-secondary); font-size: 13px;
+}
+.nav-user-logout {
+  height: 28px; width: 28px; display: grid; place-items: center;
+  border: 0; background: transparent; color: var(--text-secondary); cursor: pointer;
+  border-radius: var(--radius-sm);
+  &:hover { background: var(--bg-secondary); color: var(--text-primary); }
+}
+
+.nav-user-role {
+  font-size: 11px; padding: 2px 6px; border-radius: 4px;
+  font-weight: 500;
+}
+.role-admin { background: rgba(99, 145, 226, 0.18); color: #6391e2; }
+.role-member { background: rgba(150, 150, 150, 0.18); color: var(--text-secondary); }
 </style>

web/src/composables/useSession.ts

@@ -0,0 +1,108 @@
+import { ref, computed, readonly } from "vue";
+
+interface User {
+  id: string;
+  username: string;
+  role: 'admin' | 'member';
+}
+
+const currentUser = ref<User | null>(null);
+const needsSetup = ref<boolean | null>(null); // null = unknown / not fetched yet
+const ready = ref(false);
+
+let pollTimer: ReturnType<typeof setInterval> | null = null;
+const POLL_INTERVAL_MS = 60_000;
+
+function ensurePollStarted() {
+  if (pollTimer !== null) return;
+  pollTimer = setInterval(() => {
+    if (currentUser.value !== null) {
+      // Best-effort refresh; ignore errors (network blips etc.)
+      refreshMe().catch(() => {});
+    }
+  }, POLL_INTERVAL_MS);
+}
+
+function stopPoll() {
+  if (pollTimer !== null) {
+    clearInterval(pollTimer);
+    pollTimer = null;
+  }
+}
+
+async function refreshNeedsSetup(): Promise<void> {
+  const res = await fetch("/api/session/needs-setup", { credentials: "same-origin" });
+  if (res.ok) {
+    const body = await res.json();
+    needsSetup.value = Boolean(body.needsSetup);
+  }
+}
+
+async function refreshMe(): Promise<void> {
+  const res = await fetch("/api/session/me", { credentials: "same-origin" });
+  if (res.status === 200) {
+    currentUser.value = (await res.json()) as User;
+  } else {
+    currentUser.value = null;
+  }
+}
+
+async function refresh(): Promise<void> {
+  await refreshNeedsSetup();
+  if (needsSetup.value) {
+    currentUser.value = null;
+  } else {
+    await refreshMe();
+  }
+  ready.value = true;
+  ensurePollStarted();
+}
+
+async function login(username: string, password: string): Promise<void> {
+  const res = await fetch("/api/session/login", {
+    method: "POST",
+    credentials: "same-origin",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ username, password }),
+  });
+  if (!res.ok) {
+    const body = await res.json().catch(() => ({}));
+    throw new Error(body.error ?? `login failed (${res.status})`);
+  }
+  currentUser.value = (await res.json()) as User;
+}
+
+async function setup(username: string, password: string): Promise<void> {
+  const res = await fetch("/api/session/setup", {
+    method: "POST",
+    credentials: "same-origin",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ username, password }),
+  });
+  if (!res.ok) {
+    const body = await res.json().catch(() => ({}));
+    throw new Error(body.error ?? `setup failed (${res.status})`);
+  }
+  currentUser.value = (await res.json()) as User;
+  needsSetup.value = false;
+}
+
+async function logout(): Promise<void> {
+  stopPoll();
+  await fetch("/api/session/logout", { method: "POST", credentials: "same-origin" });
+  currentUser.value = null;
+}
+
+export function useSession() {
+  return {
+    currentUser: readonly(currentUser),
+    needsSetup: readonly(needsSetup),
+    isAuthenticated: computed(() => currentUser.value !== null),
+    isAdmin: computed(() => currentUser.value?.role === 'admin'),
+    ready: readonly(ready),
+    refresh,
+    login,
+    logout,
+    setup,
+  };
+}

web/src/main.ts

@@ -2,7 +2,11 @@ import { createApp } from 'vue';
 import { createPinia } from 'pinia';
 import App from './App.vue';
 import router from './router/index.js';
+import { installApiClient } from './api/http.js';
 import './styles/global.scss';
+import './styles/mobile.scss';
+
+installApiClient();
 
 const app = createApp(App);
 app.use(createPinia());

web/src/router/index.ts

@@ -1,55 +1,62 @@
 import { createRouter, createWebHistory } from 'vue-router';
+import { useSession } from '../composables/useSession.js';
 
 const router = createRouter({
   history: createWebHistory(),
   routes: [
-    {
-      path: '/',
-      name: 'home',
-      component: () => import('../views/Home.vue'),
-    },
-    {
-      path: '/search',
-      name: 'search',
-      component: () => import('../views/Search.vue'),
-    },
-    {
-      path: '/library',
-      name: 'library',
-      component: () => import('../views/Library.vue'),
-    },
+    { path: '/', name: 'home', component: () => import('../views/Home.vue') },
+    { path: '/search', name: 'search', component: () => import('../views/Search.vue') },
+    { path: '/library', name: 'library', component: () => import('../views/Library.vue') },
     {
       path: '/playlist/:id',
       name: 'playlist',
       component: () => import('../views/Playlist.vue'),
+      meta: { kind: 'playlist' },
     },
     {
-      path: '/lyrics',
-      name: 'lyrics',
-      component: () => import('../views/Lyrics.vue'),
-    },
-    {
-      path: '/history',
-      name: 'history',
-      component: () => import('../views/History.vue'),
-    },
-    {
-      path: '/settings',
-      name: 'settings',
-      component: () => import('../views/Settings.vue'),
-    },
-    {
-      path: '/setup',
-      name: 'setup',
-      component: () => import('../views/Setup.vue'),
-    },
-    {
-      // Per-bot URL: /bot/:id — sets active bot then redirects to home
-      path: '/bot/:id',
-      name: 'bot',
-      component: () => import('../views/BotRedirect.vue'),
+      path: '/album/:id',
+      name: 'album',
+      component: () => import('../views/Playlist.vue'),
+      meta: { kind: 'album' },
     },
+    { path: '/lyrics', name: 'lyrics', component: () => import('../views/Lyrics.vue') },
+    { path: '/history', name: 'history', component: () => import('../views/History.vue') },
+    { path: '/settings', name: 'settings', component: () => import('../views/Settings.vue') },
+    { path: '/setup', name: 'setup', component: () => import('../views/Setup.vue') },
+    { path: '/bot/:id', name: 'bot', component: () => import('../views/BotRedirect.vue') },
+
+    // Auth views
+    { path: '/login', name: 'login', component: () => import('../views/Login.vue'), meta: { public: true } },
+    { path: '/first-run', name: 'first-run', component: () => import('../views/FirstRunSetup.vue'), meta: { public: true } },
   ],
 });
 
+const PUBLIC_NAMES = new Set(['login', 'first-run']);
+
+router.beforeEach(async (to) => {
+  const session = useSession();
+  if (!session.ready.value) {
+    await session.refresh();
+  }
+
+  if (session.needsSetup.value && to.name !== 'first-run') {
+    return { name: 'first-run' };
+  }
+  if (!session.needsSetup.value && to.name === 'first-run') {
+    return { name: 'home' };
+  }
+
+  if (PUBLIC_NAMES.has(to.name as string)) {
+    if (to.name === 'login' && session.isAuthenticated.value) {
+      return { name: 'home' };
+    }
+    return true;
+  }
+
+  if (!session.isAuthenticated.value) {
+    return { name: 'login', query: { next: to.fullPath } };
+  }
+  return true;
+});
+
 export default router;

web/src/stores/player.ts

@@ -322,6 +322,16 @@ export const usePlayerStore = defineStore('player', {
       this._syncAfterAction();
     },
 
+    async playAlbum(albumId: string, platform = 'netease') {
+      if (!this.activeBotId) return;
+      const res = await axios.post(`/api/player/${this.activeBotId}/play-album`, { albumId, platform });
+      if (res.data?.message) {
+        this.notify(res.data.message, res.data.ok === false ? 'error' : 'info');
+      }
+      this._setTiming(this.activeBotId, { serverElapsed: 0 });
+      this._syncAfterAction();
+    },
+
     async pause() {
       if (!this.activeBotId) return;
       // Freeze elapsed at current interpolated value
@@ -376,11 +386,15 @@ export const usePlayerStore = defineStore('player', {
     async setVolume(volume: number) {
       if (!this.activeBotId) return;
       await axios.post(`/api/player/${this.activeBotId}/volume`, { volume });
+      const bot = this.bots.find((b) => b.id === this.activeBotId);
+      if (bot) bot.volume = volume;
     },
 
     async setMode(mode: string) {
       if (!this.activeBotId) return;
       await axios.post(`/api/player/${this.activeBotId}/mode`, { mode });
+      const bot = this.bots.find((b) => b.id === this.activeBotId);
+      if (bot) bot.playMode = mode;
     },
 
     async fetchHomeData() {

web/src/views/FirstRunSetup.vue

@@ -0,0 +1,75 @@
+<template>
+  <div class="auth-page">
+    <form class="auth-card" @submit.prevent="submit">
+      <h1>首次使用</h1>
+      <p class="auth-hint">创建管理员账号。该账号将拥有 WebUI 的全部权限。</p>
+      <label>
+        <span>用户名</span>
+        <input v-model="username" type="text" autocomplete="username" autofocus required />
+      </label>
+      <label>
+        <span>密码 (≥8 位)</span>
+        <input v-model="password" type="password" autocomplete="new-password" minlength="8" required />
+      </label>
+      <label>
+        <span>再次输入密码</span>
+        <input v-model="confirm" type="password" autocomplete="new-password" minlength="8" required />
+      </label>
+      <p v-if="error" class="auth-error">{{ error }}</p>
+      <button type="submit" :disabled="loading">{{ loading ? '创建中…' : '创建管理员' }}</button>
+    </form>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { ref } from 'vue';
+import { useRouter } from 'vue-router';
+import { useSession } from '../composables/useSession.js';
+
+const username = ref('');
+const password = ref('');
+const confirm = ref('');
+const error = ref('');
+const loading = ref(false);
+const router = useRouter();
+const session = useSession();
+
+async function submit() {
+  error.value = '';
+  if (password.value !== confirm.value) {
+    error.value = '两次输入的密码不一致';
+    return;
+  }
+  loading.value = true;
+  try {
+    await session.setup(username.value, password.value);
+    router.replace('/');
+  } catch (e) {
+    error.value = (e as Error).message;
+  } finally {
+    loading.value = false;
+  }
+}
+</script>
+
+<style scoped lang="scss">
+.auth-page { min-height: 100vh; display: flex; align-items: center; justify-content: center; background: var(--bg-primary); }
+.auth-card {
+  width: 360px; padding: 32px; background: var(--bg-secondary);
+  border-radius: var(--radius-md); display: flex; flex-direction: column; gap: 12px;
+  box-shadow: var(--shadow-dropdown);
+}
+.auth-card h1 { margin: 0; font-size: 20px; color: var(--text-primary); }
+.auth-hint { margin: 0 0 4px; font-size: 12px; color: var(--text-secondary); }
+.auth-card label { display: flex; flex-direction: column; gap: 6px; font-size: 12px; color: var(--text-secondary); }
+.auth-card input {
+  height: 36px; padding: 0 10px; border-radius: var(--radius-sm);
+  background: var(--bg-primary); color: var(--text-primary); border: 1px solid var(--border-color);
+}
+.auth-card button {
+  height: 38px; border-radius: var(--radius-sm); border: 0;
+  background: var(--color-primary); color: #fff; font-weight: 500; cursor: pointer;
+}
+.auth-card button:disabled { opacity: 0.6; cursor: progress; }
+.auth-error { color: #e26a6a; font-size: 13px; margin: 0; }
+</style>

web/src/views/Login.vue

@@ -0,0 +1,78 @@
+<template>
+  <div class="auth-page">
+    <form class="auth-card" @submit.prevent="submit">
+      <h1>登录 TSMusicBot</h1>
+      <label>
+        <span>用户名</span>
+        <input v-model="username" type="text" autocomplete="username" autofocus required />
+      </label>
+      <label>
+        <span>密码</span>
+        <input v-model="password" type="password" autocomplete="current-password" required />
+      </label>
+      <p v-if="error" class="auth-error">{{ error }}</p>
+      <button type="submit" :disabled="loading">{{ loading ? '登录中…' : '登录' }}</button>
+    </form>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { ref } from 'vue';
+import { useRoute, useRouter } from 'vue-router';
+import { useSession } from '../composables/useSession.js';
+
+const username = ref('');
+const password = ref('');
+const error = ref('');
+const loading = ref(false);
+const router = useRouter();
+const route = useRoute();
+const session = useSession();
+
+async function submit() {
+  error.value = '';
+  loading.value = true;
+  try {
+    await session.login(username.value, password.value);
+    const rawNext = typeof route.query.next === 'string' ? route.query.next : '/';
+    const next = rawNext.startsWith('/') && !rawNext.startsWith('//') ? rawNext : '/';
+    router.replace(next);
+  } catch (e) {
+    error.value = (e as Error).message;
+  } finally {
+    loading.value = false;
+  }
+}
+</script>
+
+<style scoped lang="scss">
+.auth-page {
+  min-height: 100vh;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  background: var(--bg-primary);
+}
+.auth-card {
+  width: 360px;
+  padding: 32px;
+  background: var(--bg-secondary);
+  border-radius: var(--radius-md);
+  display: flex;
+  flex-direction: column;
+  gap: 16px;
+  box-shadow: var(--shadow-dropdown);
+}
+.auth-card h1 { margin: 0 0 8px; font-size: 20px; color: var(--text-primary); }
+.auth-card label { display: flex; flex-direction: column; gap: 6px; font-size: 12px; color: var(--text-secondary); }
+.auth-card input {
+  height: 36px; padding: 0 10px; border-radius: var(--radius-sm);
+  background: var(--bg-primary); color: var(--text-primary); border: 1px solid var(--border-color);
+}
+.auth-card button {
+  height: 38px; border-radius: var(--radius-sm); border: 0;
+  background: var(--color-primary); color: #fff; font-weight: 500; cursor: pointer;
+}
+.auth-card button:disabled { opacity: 0.6; cursor: progress; }
+.auth-error { color: #e26a6a; font-size: 13px; margin: 0; }
+</style>

web/src/views/Playlist.vue

@@ -38,7 +38,7 @@
       </div>
     </template>
 
-    <div v-else class="loading">歌单不存在或加载失败</div>
+    <div v-else class="loading">{{ kind === 'album' ? '专辑' : '歌单' }}不存在或加载失败</div>
   </div>
 </template>
 
@@ -64,6 +64,8 @@ interface PlaylistDetail {
   songCount: number;
 }
 
+const kind = (route.meta.kind as string) ?? 'playlist'; // 'playlist' | 'album'
+
 const playlist = ref<PlaylistDetail | null>(null);
 const songs = ref<Song[]>([]);
 const loading = ref(true);
@@ -71,20 +73,32 @@ const loading = ref(true);
 async function playAll() {
   const id = route.params.id as string;
   const platform = (route.query.platform as string) || 'netease';
-  await store.playPlaylist(id, platform);
+  if (kind === 'album') {
+    await store.playAlbum(id, platform);
+  } else {
+    await store.playPlaylist(id, platform);
+  }
 }
 
 onMounted(async () => {
   const id = route.params.id as string;
   const platform = (route.query.platform as string) || 'netease';
 
+  const detailUrl = kind === 'album'
+    ? `/api/music/album/${id}/detail`
+    : `/api/music/playlist/${id}/detail`;
+  const songsUrl = kind === 'album'
+    ? `/api/music/album/${id}`
+    : `/api/music/playlist/${id}`;
+
   // allSettled, not Promise.all — if detail 404s but songs is fine
   // (e.g., a QQ playlist whose detail endpoint flaked but the song
   // list resolved), we still want to show the songs rather than
-  // the "歌单不存在" empty state.
+  // the "不存在" empty state. For albums, detail always 404s — that
+  // is intentional; the fallback stub below handles it.
   const [detailRes, songsRes] = await Promise.allSettled([
-    axios.get(`/api/music/playlist/${id}/detail`, { params: { platform } }),
-    axios.get(`/api/music/playlist/${id}`, { params: { platform } }),
+    axios.get(detailUrl, { params: { platform } }),
+    axios.get(songsUrl, { params: { platform } }),
   ]);
 
   const detail = detailRes.status === 'fulfilled' ? detailRes.value.data?.playlist : null;
@@ -93,10 +107,14 @@ onMounted(async () => {
   if (detail) {
     playlist.value = detail;
   } else if (songList.length > 0) {
-    // Fall back to a stub built from the route + first song's cover.
+    // Fall back to a stub built from the route + first song. For albums,
+    // every song's `album` field carries the real album name.
+    const fallbackName = kind === 'album'
+      ? (songList[0]?.album || '专辑')
+      : '歌单';
     playlist.value = {
       id,
-      name: '歌单',
+      name: fallbackName,
       description: '',
       coverUrl: songList[0]?.coverUrl ?? '',
       songCount: songList.length,
@@ -104,7 +122,7 @@ onMounted(async () => {
   } else {
     playlist.value = null;
     if (detailRes.status === 'rejected') {
-      console.error('Failed to load playlist detail:', (detailRes.reason as any)?.response?.status, (detailRes.reason as any)?.message);
+      console.error('Failed to load detail:', (detailRes.reason as any)?.response?.status, (detailRes.reason as any)?.message);
     }
   }
   songs.value = songList;

web/src/views/Search.vue

@@ -20,59 +20,197 @@
 
     <div v-if="loading" class="loading">搜索中...</div>
 
-    <div v-else-if="results.length > 0" class="results">
-      <SongCard
-        v-for="(song, i) in results"
-        :key="`${song.platform}-${song.id}`"
-        :song="song"
-        :index="i + 1"
-        :active="store.currentSong?.id === song.id"
-        @play="store.playSong(song)"
-        @playNext="store.playNextSong(song)"
-        @add="store.addSong(song)"
-      />
-    </div>
+    <template v-else-if="allSongs.length || allAlbums.length || allPlaylists.length">
+      <div class="source-bar">
+        <button
+          class="source-btn"
+          :class="{ active: selectedSource === 'netease' }"
+          @click="selectedSource = 'netease'"
+        >网易云</button>
+        <button
+          class="source-btn"
+          :class="{ active: selectedSource === 'qq' }"
+          @click="selectedSource = 'qq'"
+        >QQ</button>
+        <button
+          class="source-btn"
+          :class="{ active: selectedSource === 'bilibili' }"
+          @click="selectedSource = 'bilibili'"
+        >B站</button>
+      </div>
 
-    <div v-else-if="searched" class="empty">
-      未找到相关结果
-    </div>
+      <div class="tab-bar">
+        <button
+          class="tab"
+          :class="{ active: activeTab === 'songs' }"
+          @click="activeTab = 'songs'"
+        >
+          单曲<span class="tab-count">{{ filteredSongs.length }}</span>
+        </button>
+        <button
+          v-if="selectedSource !== 'bilibili'"
+          class="tab"
+          :class="{ active: activeTab === 'albums' }"
+          @click="activeTab = 'albums'"
+        >
+          专辑<span class="tab-count">{{ filteredAlbums.length }}</span>
+        </button>
+        <button
+          v-if="selectedSource !== 'bilibili'"
+          class="tab"
+          :class="{ active: activeTab === 'playlists' }"
+          @click="activeTab = 'playlists'"
+        >
+          歌单<span class="tab-count">{{ filteredPlaylists.length }}</span>
+        </button>
+      </div>
+
+      <section v-if="activeTab === 'albums' && filteredAlbums.length" class="result-section">
+        <div class="card-grid">
+          <router-link
+            v-for="al in filteredAlbums"
+            :key="`${al.platform}-${al.id}`"
+            :to="`/album/${al.id}?platform=${al.platform}`"
+            class="card hover-scale"
+          >
+            <CoverArt :url="al.coverUrl" :size="160" :radius="10" :show-shadow="true" />
+            <div class="card-name">
+              {{ al.name }}
+              <span class="platform-badge" :class="badgeClass(al.platform)">{{ badgeLabel(al.platform) }}</span>
+            </div>
+            <div class="card-sub">{{ al.artist }}</div>
+          </router-link>
+        </div>
+      </section>
+
+      <section v-if="activeTab === 'playlists' && filteredPlaylists.length" class="result-section">
+        <div class="card-grid">
+          <router-link
+            v-for="pl in filteredPlaylists"
+            :key="`${pl.platform}-${pl.id}`"
+            :to="`/playlist/${pl.id}?platform=${pl.platform}`"
+            class="card hover-scale"
+          >
+            <CoverArt :url="pl.coverUrl" :size="160" :radius="10" :show-shadow="true" />
+            <div class="card-name">
+              {{ pl.name }}
+              <span class="platform-badge" :class="badgeClass(pl.platform)">{{ badgeLabel(pl.platform) }}</span>
+            </div>
+          </router-link>
+        </div>
+      </section>
+
+      <section v-if="activeTab === 'songs' && filteredSongs.length" class="result-section">
+        <SongCard
+          v-for="(song, i) in filteredSongs"
+          :key="`${song.platform}-${song.id}`"
+          :song="song"
+          :index="i + 1"
+          :active="store.currentSong?.id === song.id"
+          @play="store.playSong(song)"
+          @playNext="store.playNextSong(song)"
+          @add="store.addSong(song)"
+        />
+      </section>
+    </template>
+
+    <div v-else-if="searched" class="empty">未找到相关结果</div>
   </div>
 </template>
 
 <script setup lang="ts">
-import { ref, onMounted } from 'vue';
-import { useRoute } from 'vue-router';
+import { ref, computed, watch, onMounted } from 'vue';
+import { useRoute, useRouter } from 'vue-router';
 import { Icon } from '@iconify/vue';
 import axios from 'axios';
 import { usePlayerStore } from '../stores/player.js';
+import type { Song } from '../stores/player.js';
 import SongCard from '../components/SongCard.vue';
+import CoverArt from '../components/CoverArt.vue';
 
 const store = usePlayerStore();
 const route = useRoute();
+const router = useRouter();
+
+const SOURCE_STORAGE_KEY = 'search-source';
+
+function loadSource(): 'netease' | 'qq' | 'bilibili' {
+  try {
+    const stored = localStorage.getItem(SOURCE_STORAGE_KEY);
+    if (stored === 'netease' || stored === 'qq' || stored === 'bilibili') return stored;
+  } catch { /* localStorage blocked */ }
+  return 'netease';
+}
 
 const query = ref((route.query.q as string) || '');
-import { Song } from '../stores/player.js';
+const activeTab = ref<'songs' | 'albums' | 'playlists'>('songs');
+const selectedSource = ref<'netease' | 'qq' | 'bilibili'>(loadSource());
 
-const results = ref<Song[]>([]);
+interface Album { id: string; name: string; artist: string; coverUrl: string; songCount?: number; platform: string; }
+interface Playlist { id: string; name: string; coverUrl: string; songCount?: number; platform: string; }
+
+const allSongs = ref<Song[]>([]);
+const allAlbums = ref<Album[]>([]);
+const allPlaylists = ref<Playlist[]>([]);
 const loading = ref(false);
 const searched = ref(false);
 
+const filteredSongs = computed(() =>
+  allSongs.value.filter((s) => s.platform === selectedSource.value)
+);
+
+const filteredAlbums = computed(() =>
+  allAlbums.value.filter((a) => a.platform === selectedSource.value)
+);
+
+const filteredPlaylists = computed(() =>
+  allPlaylists.value.filter((p) => p.platform === selectedSource.value)
+);
+
+// Persist source preference
+watch(selectedSource, (src) => {
+  try { localStorage.setItem(SOURCE_STORAGE_KEY, src); } catch { /* ignore */ }
+});
+
+// B站 has no albums/playlists — force songs tab when switching to B站
+watch(selectedSource, (src) => {
+  if (src === 'bilibili' && activeTab.value !== 'songs') {
+    activeTab.value = 'songs';
+  }
+});
+
 async function doSearch() {
   if (!query.value.trim()) return;
   loading.value = true;
   searched.value = true;
+  activeTab.value = 'songs';
+  router.replace({ query: { q: query.value } });
   try {
-    const res = await axios.get('/api/music/search/all', {
-      params: { q: query.value },
-    });
-    results.value = res.data.songs;
+    const res = await axios.get('/api/music/search/all', { params: { q: query.value } });
+    allSongs.value = res.data.songs ?? [];
+    allAlbums.value = res.data.albums ?? [];
+    allPlaylists.value = res.data.playlists ?? [];
   } catch {
-    results.value = [];
+    allSongs.value = []; allAlbums.value = []; allPlaylists.value = [];
   } finally {
     loading.value = false;
   }
 }
 
+function badgeLabel(platform: string): string {
+  if (platform === 'qq') return 'QQ';
+  if (platform === 'bilibili') return 'B站';
+  if (platform === 'youtube') return 'YouTube';
+  return '网易云';
+}
+
+function badgeClass(platform: string): string {
+  if (platform === 'qq') return 'badge-qq';
+  if (platform === 'bilibili') return 'badge-bilibili';
+  if (platform === 'youtube') return 'badge-youtube';
+  return 'badge-netease';
+}
+
 onMounted(() => {
   if (query.value) doSearch();
 });
@@ -141,4 +279,119 @@ onMounted(() => {
   flex-direction: column;
   gap: 2px;
 }
+
+.source-bar {
+  display: flex;
+  gap: 8px;
+  margin-bottom: 12px;
+}
+
+.source-btn {
+  padding: 5px 16px;
+  border-radius: var(--radius-sm);
+  font-size: 13px;
+  font-family: inherit;
+  font-weight: var(--fw-semi);
+  color: var(--text-secondary);
+  background: var(--bg-card);
+  cursor: pointer;
+  transition: all var(--transition-fast);
+  white-space: nowrap;
+
+  &:hover { color: var(--text-primary); }
+
+  &.active {
+    color: var(--color-primary);
+    background: rgba(51, 94, 234, 0.12);
+  }
+}
+
+.tab-bar {
+  display: flex;
+  gap: 6px;
+  margin-bottom: 24px;
+  padding: 4px;
+  background: var(--bg-card);
+  border-radius: var(--radius-md);
+  width: fit-content;
+}
+
+.tab {
+  padding: 8px 20px;
+  border-radius: calc(var(--radius-md) - 2px);
+  font-size: 14px;
+  font-family: inherit;
+  font-weight: var(--fw-semi);
+  color: var(--text-secondary);
+  background: transparent;
+  cursor: pointer;
+  transition: all var(--transition-fast);
+  white-space: nowrap;
+
+  &:hover { color: var(--text-primary); }
+
+  &.active {
+    background: var(--color-primary);
+    color: #fff;
+    .tab-count { opacity: 0.85; }
+  }
+}
+
+.tab-count {
+  margin-left: 5px;
+  opacity: 0.55;
+  font-weight: var(--fw-regular);
+  font-size: 13px;
+
+  &::before { content: '('; }
+  &::after  { content: ')'; }
+}
+
+.result-section {
+  margin-bottom: 32px;
+}
+.card-grid {
+  display: grid;
+  grid-template-columns: repeat(auto-fill, minmax(140px, 1fr));
+  gap: 16px 28px;
+}
+.card {
+  display: flex;
+  flex-direction: column;
+  gap: 6px;
+  text-decoration: none;
+  color: inherit;
+  .card-name { font-size: 14px; line-height: 1.3; max-height: 2.6em; overflow: hidden; }
+  .card-sub  { font-size: 12px; opacity: 0.6; }
+}
+
+.platform-badge {
+  vertical-align: middle;
+  flex-shrink: 0;
+  font-size: var(--fs-micro);
+  font-weight: var(--fw-semi);
+  padding: 1px 5px;
+  border-radius: var(--radius-xs);
+  line-height: 1.4;
+}
+
+.badge-netease {
+  background: var(--brand-netease-15);
+  color: var(--brand-netease);
+}
+
+.badge-qq {
+  background: var(--brand-qq-15);
+  color: var(--brand-qq);
+}
+
+.badge-bilibili {
+  background: var(--brand-bilibili-15);
+  color: var(--brand-bilibili);
+}
+
+.badge-youtube {
+  background: var(--brand-youtube-12);
+  color: var(--brand-youtube);
+}
 </style>

web/src/views/Settings.vue

@@ -21,6 +21,35 @@
       </div>
     </section>
 
+    <!-- Account: own password change -->
+    <section class="settings-section">
+      <h2 class="section-title">账户</h2>
+      <div class="account-info-card">
+        <div class="account-row">
+          <span class="account-label">用户名</span>
+          <span class="account-value">{{ session.currentUser.value?.username ?? '—' }}</span>
+        </div>
+        <div class="account-row">
+          <span class="account-label">角色</span>
+          <span class="account-value">
+            <span class="user-role-badge" :class="`role-${session.currentUser.value?.role}`">
+              {{ session.currentUser.value?.role === 'admin' ? '管理员' : '成员' }}
+            </span>
+          </span>
+        </div>
+      </div>
+      <form class="change-pw-form" @submit.prevent="onChangeOwnPassword">
+        <input v-model="ownPw.old" type="password" autocomplete="current-password" class="input" placeholder="当前密码" required />
+        <input v-model="ownPw.new" type="password" autocomplete="new-password" minlength="8" class="input" placeholder="新密码 (≥8 位)" required />
+        <input v-model="ownPw.confirm" type="password" autocomplete="new-password" minlength="8" class="input" placeholder="再次输入新密码" required />
+        <button class="btn-sm btn-primary" type="submit" :disabled="changingOwnPw">
+          {{ changingOwnPw ? '更新中…' : '修改密码' }}
+        </button>
+      </form>
+      <p v-if="ownPwError" class="user-error">{{ ownPwError }}</p>
+      <p v-if="ownPwSuccess" class="user-success">{{ ownPwSuccess }}</p>
+    </section>
+
     <!-- Bot Management -->
     <section class="settings-section">
       <h2 class="section-title">机器人管理</h2>
@@ -80,6 +109,10 @@
             <label>服务器密码（可选）</label>
             <input v-model="editForm.serverPassword" class="input" type="password" placeholder="服务器有密码时填写" />
           </div>
+          <div class="form-group">
+            <label>自定义头像</label>
+            <CustomAvatarRow :bot-id="editingBot" />
+          </div>
           <div class="modal-actions">
             <button class="btn-secondary" @click="editingBot = null">取消</button>
             <button class="btn-primary" @click="saveEditBot">保存（需重启机器人生效）</button>
@@ -116,6 +149,10 @@
           <label>服务器密码（可选）</label>
           <input v-model="newBotServerPassword" class="input" type="password" placeholder="服务器有密码时填写" />
         </div>
+        <div class="form-group">
+          <label>自定义头像（可选）</label>
+          <AvatarUpload v-model="newBotAvatar" />
+        </div>
         <button class="btn-primary" @click="createBot">创建</button>
       </div>
     </section>
@@ -439,10 +476,111 @@
                 @change="updateProfile(bot.id, t.key, ($event.target as HTMLInputElement).checked)"
               />
             </label>
+            <div v-if="profileConfigs[bot.id]" class="profile-toggle profile-toggle-static">
+              <div class="profile-toggle-text">
+                <div class="profile-toggle-label">自定义头像</div>
+                <div class="profile-toggle-hint">无论封面同步是否开启，停播时都会回到这张图</div>
+              </div>
+              <CustomAvatarRow :bot-id="bot.id" />
+            </div>
           </div>
         </div>
       </div>
     </section>
+
+    <!-- User Management -->
+    <section v-if="session.isAdmin.value" class="settings-section">
+      <h2 class="section-title">用户管理</h2>
+      <div class="user-list">
+        <div v-for="u in userList" :key="u.id" class="user-item">
+          <div class="user-info">
+            <div class="user-name">
+              {{ u.username }}
+              <span class="user-role-badge" :class="`role-${u.role}`">
+                {{ u.role === 'admin' ? '管理员' : '成员' }}
+              </span>
+              <span v-if="session.currentUser.value && u.id === session.currentUser.value.id" class="user-self-badge">本人</span>
+            </div>
+            <div class="user-created">创建于 {{ formatDate(u.createdAt) }}</div>
+          </div>
+          <div class="user-actions">
+            <button class="btn-sm" @click="openResetPassword(u)">
+              <Icon icon="mdi:lock-reset" /> 重置密码
+            </button>
+            <button
+              class="btn-sm"
+              :disabled="changingRoleId === u.id || isLastAdmin(u)"
+              :title="isLastAdmin(u) ? '不能降级唯一的管理员' : (u.role === 'admin' ? '降级为成员' : '提升为管理员')"
+              @click="onToggleRole(u)"
+            >
+              <Icon icon="mdi:account-cog" />
+              {{ u.role === 'admin' ? '降为成员' : '提升管理员' }}
+            </button>
+            <button
+              class="btn-sm btn-delete"
+              :disabled="!!(session.currentUser.value && u.id === session.currentUser.value.id) || isLastAdmin(u)"
+              :title="session.currentUser.value && u.id === session.currentUser.value.id ? '不能删除自己' : (isLastAdmin(u) ? '不能删除唯一的管理员' : '')"
+              @click="onDeleteUser(u)"
+            >
+              <Icon icon="mdi:delete" />
+            </button>
+          </div>
+        </div>
+        <div v-if="userList.length === 0 && !userLoadError" class="user-empty">加载中…</div>
+        <div v-if="userLoadError" class="user-error">{{ userLoadError }}</div>
+      </div>
+
+      <form class="user-add-form" @submit.prevent="onCreateUser">
+        <input v-model="newUser.username" class="input" placeholder="新用户名 (3-32 字符)" required />
+        <input v-model="newUser.password" type="password" class="input" placeholder="密码 (≥8 位)" minlength="8" required />
+        <select v-model="newUser.role" class="input user-role-select">
+          <option value="member">成员</option>
+          <option value="admin">管理员</option>
+        </select>
+        <button class="btn-sm btn-primary" type="submit" :disabled="creatingUser">
+          {{ creatingUser ? '创建中…' : '添加用户' }}
+        </button>
+      </form>
+      <p v-if="userMutationError" class="user-error">{{ userMutationError }}</p>
+
+      <!-- Reset password modal -->
+      <div v-if="resetTarget" class="edit-modal-overlay" @click.self="resetTarget = null">
+        <div class="edit-modal">
+          <h3 class="modal-title">重置 {{ resetTarget.username }} 的密码</h3>
+          <p class="modal-hint">该用户的所有会话将被强制下线。</p>
+          <div class="form-group">
+            <label>新密码 (≥8 位)</label>
+            <input v-model="resetPassword" type="password" class="input" minlength="8" />
+          </div>
+          <p v-if="resetError" class="user-error">{{ resetError }}</p>
+          <div class="form-actions">
+            <button class="btn-sm" @click="resetTarget = null">取消</button>
+            <button class="btn-sm btn-primary" :disabled="resettingPw" @click="onConfirmReset">
+              {{ resettingPw ? '保存中…' : '确认重置' }}
+            </button>
+          </div>
+        </div>
+      </div>
+    </section>
+
+    <!-- Audit Log -->
+    <section v-if="session.isAdmin.value" class="settings-section">
+      <h2 class="section-title">
+        操作审计
+        <button class="audit-refresh-btn" @click="loadAudit" :disabled="auditLoading" title="刷新">
+          <Icon icon="mdi:refresh" :class="{ spinning: auditLoading }" />
+        </button>
+      </h2>
+      <div v-if="auditLoadError" class="user-error">{{ auditLoadError }}</div>
+      <div v-else-if="auditEntries.length === 0 && !auditLoading" class="user-empty">暂无操作记录</div>
+      <div v-else class="audit-list">
+        <div v-for="e in auditEntries" :key="e.id" class="audit-row">
+          <div class="audit-time">{{ formatDateTime(e.timestamp) }}</div>
+          <div class="audit-actor">{{ e.actorUsername ?? '—' }}</div>
+          <div class="audit-action" :class="auditActionClass(e.action)">{{ describeAction(e) }}</div>
+        </div>
+      </div>
+    </section>
   </div>
 </template>
 
@@ -450,8 +588,11 @@
 import { ref, reactive, onMounted, onUnmounted } from 'vue';
 import { Icon } from '@iconify/vue';
 import axios from 'axios';
+import AvatarUpload from '../components/AvatarUpload.vue';
+import CustomAvatarRow from '../components/CustomAvatarRow.vue';
 import QRCode from 'qrcode';
 import { usePlayerStore } from '../stores/player.js';
+import { useSession } from '../composables/useSession.js';
 
 const store = usePlayerStore();
 
@@ -475,6 +616,7 @@ const newBotPort = ref(9987);
 const newBotNickname = ref('MusicBot');
 const newBotChannel = ref('');
 const newBotServerPassword = ref('');
+const newBotAvatar = ref<string | null>(null);
 
 // Edit bot
 const editingBot = ref<string | null>(null);
@@ -635,7 +777,7 @@ async function pollQrStatus(platform: string) {
 async function createBot() {
   if (!newBotName.value || !newBotServer.value) return;
   try {
-    await axios.post('/api/bot', {
+    const res = await axios.post('/api/bot', {
       name: newBotName.value,
       serverAddress: newBotServer.value,
       serverPort: newBotPort.value || 9987,
@@ -644,12 +786,20 @@ async function createBot() {
       serverPassword: newBotServerPassword.value || undefined,
       autoStart: false,
     });
+    if (newBotAvatar.value && res.data?.id) {
+      try {
+        await axios.put(`/api/bot/${res.data.id}/avatar`, { dataUrl: newBotAvatar.value });
+      } catch (err) {
+        console.warn('failed to set avatar on new bot', err);
+      }
+    }
     newBotName.value = '';
     newBotServer.value = '';
     newBotPort.value = 9987;
     newBotNickname.value = 'MusicBot';
     newBotChannel.value = '';
     newBotServerPassword.value = '';
+    newBotAvatar.value = null;
     await store.fetchBots();
   } catch {
     // Ignore
@@ -815,11 +965,242 @@ async function updateProfile(botId: string, key: keyof ProfileConfig, value: boo
   }
 }
 
+// --- User Management ---
+const session = useSession();
+
+// --- Own password change (available to all authenticated users) ---
+const ownPw = reactive({ old: '', new: '', confirm: '' });
+const ownPwError = ref('');
+const ownPwSuccess = ref('');
+const changingOwnPw = ref(false);
+
+async function onChangeOwnPassword() {
+  ownPwError.value = '';
+  ownPwSuccess.value = '';
+  if (ownPw.new !== ownPw.confirm) {
+    ownPwError.value = '两次输入的新密码不一致';
+    return;
+  }
+  if (ownPw.new.length < 8) {
+    ownPwError.value = '新密码至少 8 位';
+    return;
+  }
+  changingOwnPw.value = true;
+  try {
+    const res = await fetch('/api/session/change-password', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ oldPassword: ownPw.old, newPassword: ownPw.new }),
+    });
+    if (!res.ok && res.status !== 204) {
+      const b = await res.json().catch(() => ({}));
+      throw new Error(b.error ?? `HTTP ${res.status}`);
+    }
+    ownPw.old = '';
+    ownPw.new = '';
+    ownPw.confirm = '';
+    ownPwSuccess.value = '密码已更新';
+    // The server kills other sessions but keeps the current one. No reload needed.
+  } catch (e) {
+    ownPwError.value = (e as Error).message;
+  } finally {
+    changingOwnPw.value = false;
+  }
+}
+
+interface UserListEntry { id: string; username: string; createdAt: number; role: 'admin' | 'member' }
+const userList = ref<UserListEntry[]>([]);
+const userLoadError = ref('');
+const userMutationError = ref('');
+const newUser = reactive({ username: '', password: '', role: 'member' as 'admin' | 'member' });
+const creatingUser = ref(false);
+const resetTarget = ref<UserListEntry | null>(null);
+const resetPassword = ref('');
+const resetError = ref('');
+const resettingPw = ref(false);
+const changingRoleId = ref<string | null>(null);
+
+function isLastAdmin(u: UserListEntry): boolean {
+  if (u.role !== 'admin') return false;
+  const adminCount = userList.value.filter((x) => x.role === 'admin').length;
+  return adminCount <= 1;
+}
+
+async function onToggleRole(u: UserListEntry) {
+  const newRole = u.role === 'admin' ? 'member' : 'admin';
+  if (!confirm(`确认将 ${u.username} 切换为${newRole === 'admin' ? '管理员' : '成员'}？`)) return;
+  userMutationError.value = '';
+  changingRoleId.value = u.id;
+  try {
+    const res = await fetch(`/api/users/${u.id}/role`, {
+      method: 'PATCH',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ role: newRole }),
+    });
+    if (!res.ok && res.status !== 204) {
+      const b = await res.json().catch(() => ({}));
+      throw new Error(b.error ?? `HTTP ${res.status}`);
+    }
+    await loadUsers();
+  } catch (e) {
+    userMutationError.value = (e as Error).message;
+  } finally {
+    changingRoleId.value = null;
+  }
+}
+
+async function loadUsers() {
+  userLoadError.value = '';
+  try {
+    const res = await fetch('/api/users');
+    if (!res.ok) throw new Error(`HTTP ${res.status}`);
+    const body = await res.json();
+    userList.value = body.users ?? [];
+  } catch (e) {
+    userLoadError.value = (e as Error).message;
+  }
+}
+
+async function onCreateUser() {
+  userMutationError.value = '';
+  creatingUser.value = true;
+  try {
+    const res = await fetch('/api/users', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ username: newUser.username, password: newUser.password, role: newUser.role }),
+    });
+    if (!res.ok) {
+      const b = await res.json().catch(() => ({}));
+      throw new Error(b.error ?? `HTTP ${res.status}`);
+    }
+    newUser.username = '';
+    newUser.password = '';
+    newUser.role = 'member';
+    await loadUsers();
+  } catch (e) {
+    userMutationError.value = (e as Error).message;
+  } finally {
+    creatingUser.value = false;
+  }
+}
+
+async function onDeleteUser(u: UserListEntry) {
+  if (!confirm(`确认删除用户 ${u.username}？`)) return;
+  userMutationError.value = '';
+  try {
+    const res = await fetch(`/api/users/${u.id}`, { method: 'DELETE' });
+    if (!res.ok && res.status !== 204) {
+      const b = await res.json().catch(() => ({}));
+      throw new Error(b.error ?? `HTTP ${res.status}`);
+    }
+    await loadUsers();
+  } catch (e) {
+    userMutationError.value = (e as Error).message;
+  }
+}
+
+function openResetPassword(u: UserListEntry) {
+  resetTarget.value = u;
+  resetPassword.value = '';
+  resetError.value = '';
+}
+
+async function onConfirmReset() {
+  if (!resetTarget.value) return;
+  if (resetPassword.value.length < 8) {
+    resetError.value = '密码至少 8 位';
+    return;
+  }
+  resettingPw.value = true;
+  resetError.value = '';
+  try {
+    const res = await fetch(`/api/users/${resetTarget.value.id}/reset-password`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ newPassword: resetPassword.value }),
+    });
+    if (!res.ok && res.status !== 204) {
+      const b = await res.json().catch(() => ({}));
+      throw new Error(b.error ?? `HTTP ${res.status}`);
+    }
+    resetTarget.value = null;
+  } catch (e) {
+    resetError.value = (e as Error).message;
+  } finally {
+    resettingPw.value = false;
+  }
+}
+
+function formatDate(ms: number): string {
+  const d = new Date(ms);
+  return `${d.getFullYear()}-${String(d.getMonth() + 1).padStart(2, '0')}-${String(d.getDate()).padStart(2, '0')}`;
+}
+
+// --- Audit Log ---
+interface AuditEntry {
+  id: number;
+  timestamp: number;
+  actorId: string | null;
+  actorUsername: string | null;
+  targetUserId: string | null;
+  targetUsername: string | null;
+  action: string;
+}
+
+const auditEntries = ref<AuditEntry[]>([]);
+const auditLoadError = ref('');
+const auditLoading = ref(false);
+
+async function loadAudit() {
+  auditLoadError.value = '';
+  auditLoading.value = true;
+  try {
+    const res = await fetch('/api/audit?limit=100');
+    if (!res.ok) throw new Error(`HTTP ${res.status}`);
+    const body = await res.json();
+    auditEntries.value = body.entries ?? [];
+  } catch (e) {
+    auditLoadError.value = (e as Error).message;
+  } finally {
+    auditLoading.value = false;
+  }
+}
+
+function formatDateTime(ms: number): string {
+  const d = new Date(ms);
+  const pad = (n: number) => String(n).padStart(2, '0');
+  return `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())} ${pad(d.getHours())}:${pad(d.getMinutes())}:${pad(d.getSeconds())}`;
+}
+
+function describeAction(e: AuditEntry): string {
+  const target = e.targetUsername ?? e.targetUserId ?? '—';
+  switch (e.action) {
+    case 'admin.first_created':     return `创建首位管理员 ${target}`;
+    case 'user.created':            return `创建用户 ${target}`;
+    case 'user.deleted':            return `删除用户 ${target}`;
+    case 'user.password_reset':     return `重置 ${target} 的密码`;
+    case 'user.password_changed':   return `修改自己的密码`;
+    case 'user.role_changed':       return `变更 ${target} 的角色`;
+    default:                        return `${e.action} → ${target}`;
+  }
+}
+
+function auditActionClass(action: string): string {
+  if (action === 'user.deleted') return 'audit-action-danger';
+  if (action === 'user.password_reset' || action === 'user.password_changed') return 'audit-action-warn';
+  return 'audit-action-ok';
+}
+
 onMounted(() => {
   store.fetchBots(); // Refresh bot status on page visit
   checkAuthStatus();
   loadQuality();
   loadIdleTimeout();
+  if (session.isAdmin.value) {
+    loadUsers();
+    loadAudit();
+  }
 });
 
 onUnmounted(() => {
@@ -1408,6 +1789,11 @@ onUnmounted(() => {
   }
 }
 
+.profile-toggle-static {
+  cursor: default;
+  align-items: flex-start;
+}
+
 @media (max-width: 768px) {
   .profile-bot-header {
     padding: 14px 12px;
@@ -1436,4 +1822,105 @@ onUnmounted(() => {
     }
   }
 }
+
+// --- User Management ---
+.user-list { display: flex; flex-direction: column; gap: 8px; }
+.user-item {
+  display: flex; align-items: center; justify-content: space-between;
+  padding: 12px; background: var(--bg-secondary); border-radius: var(--radius-sm);
+}
+.user-info { display: flex; flex-direction: column; gap: 4px; }
+.user-name { font-weight: 500; color: var(--text-primary); display: flex; align-items: center; gap: 8px; }
+.user-self-badge {
+  font-size: 11px; padding: 2px 6px; border-radius: 4px;
+  background: var(--color-primary); color: #fff;
+}
+.user-created { font-size: 12px; color: var(--text-secondary); }
+.user-actions { display: flex; gap: 8px; }
+.user-add-form {
+  display: flex; gap: 8px; margin-top: 12px; flex-wrap: wrap;
+}
+.user-add-form .input { flex: 1; min-width: 140px; }
+.user-empty, .user-error { font-size: 12px; color: var(--text-secondary); padding: 8px 0; }
+.user-error { color: #e26a6a; }
+.modal-hint { color: var(--text-secondary); font-size: 12px; margin: 0 0 8px; }
+.form-actions { display: flex; gap: 8px; justify-content: flex-end; margin-top: 8px; }
+
+.audit-refresh-btn {
+  margin-left: 10px;
+  border: 0; background: transparent;
+  color: var(--text-secondary); cursor: pointer;
+  display: inline-flex; align-items: center;
+  font-size: 16px;
+  &:hover { color: var(--text-primary); }
+  &:disabled { opacity: 0.5; cursor: progress; }
+}
+.spinning { animation: spin 1s linear infinite; }
+@keyframes spin { from { transform: rotate(0deg); } to { transform: rotate(360deg); } }
+
+.audit-list {
+  display: flex; flex-direction: column;
+  border-radius: var(--radius-sm);
+  background: var(--bg-secondary);
+  max-height: 480px;
+  overflow-y: auto;
+}
+.audit-row {
+  display: grid;
+  grid-template-columns: 170px 120px 1fr;
+  gap: 12px;
+  padding: 10px 12px;
+  border-bottom: 1px solid var(--border-color);
+  font-size: 13px;
+  &:last-child { border-bottom: 0; }
+}
+.audit-time {
+  color: var(--text-secondary);
+  font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, monospace;
+  font-size: 12px;
+  white-space: nowrap;
+}
+.audit-actor {
+  color: var(--text-primary);
+  font-weight: 500;
+}
+.audit-action { color: var(--text-primary); }
+.audit-action-ok      { color: var(--text-primary); }
+.audit-action-warn    { color: #d3a44b; }
+.audit-action-danger  { color: #e26a6a; }
+
+@media (max-width: 640px) {
+  .audit-row {
+    grid-template-columns: 1fr;
+    gap: 4px;
+  }
+}
+
+.user-role-badge {
+  font-size: 11px; padding: 2px 6px; border-radius: 4px; margin-left: 6px;
+  font-weight: 500;
+}
+.role-admin { background: rgba(99, 145, 226, 0.18); color: #6391e2; }
+.role-member { background: rgba(150, 150, 150, 0.18); color: var(--text-secondary); }
+.user-role-select { flex: 0 0 110px; }
+
+// --- Account section (own password change) ---
+.account-info-card {
+  display: flex; flex-direction: column; gap: 8px;
+  padding: 12px; background: var(--bg-secondary); border-radius: var(--radius-sm);
+  margin-bottom: 12px;
+}
+.account-row {
+  display: flex; justify-content: space-between; align-items: center;
+  font-size: 13px;
+}
+.account-label { color: var(--text-secondary); }
+.account-value { color: var(--text-primary); font-weight: 500; }
+.change-pw-form {
+  display: flex; flex-direction: column; gap: 8px;
+  max-width: 360px;
+}
+.change-pw-form .input { width: 100%; }
+.change-pw-form button { align-self: flex-start; }
+.user-success { color: #4caf7a; font-size: 13px; margin: 4px 0 0; }
 </style>