fix(profile): apply custom avatar immediately on idle setCustomAvatar / connect

Review feedback on PR #56:

1. setCustomAvatar(buf) now triggers applyIdleAvatar when the bot is idle
   (currentSong=null OR avatarEnabled=false). Spec said this; original impl
   only stored the buffer, so a fresh upload from Settings was invisible
   until next stop event. Track currentSong in BotProfileManager for the
   idle check.

2. onConnect drops the !avatarEnabled guard — on a fresh connect there's
   no song playing yet, so the spec matrix wants the custom avatar shown
   regardless of sync. Previously bots reconnected with a stale TS3
   server-side avatar.

3. CustomAvatarRow: defer the initializing=false flip to nextTick so the
   load-time data-url assignment's queued watcher sees initializing=true
   and bails. Removes the redundant PUT-on-mount that echoed the just-
   loaded bytes back to the server.

4. BotInstance avatar load wrapped in try/catch — a corrupt/locked file
   no longer crashes startup; we log and continue with no custom avatar.

Tests rewritten: 10 cases covering the full behavior matrix
(idle vs playing × sync on/off × custom set/null × stop/connect).

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

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();
   }

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/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

@@ -98,4 +98,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,9 @@ 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");
+  }
 }
 
 function initTables(db: Database.Database): void {
@@ -179,6 +184,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 +250,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/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/netease.test.ts

@@ -1,5 +1,5 @@
 import { describe, it, expect } from "vitest";
-import { parseLyrics, mapNeteaseAlbums } from "./netease.js";
+import { parseLyrics } from "./netease.js";
 
 describe("NetEase adapter", () => {
   it("parses LRC format lyrics", () => {
@@ -28,32 +28,4 @@ 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,7 +8,6 @@ import type {
   SearchResult,
   QrCodeResult,
   AuthStatus,
-  Album,
 } from "./provider.js";
 
 export function parseLyrics(lrc: string, tlyric?: string): LyricLine[] {
@@ -56,18 +55,6 @@ 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 },
@@ -104,7 +91,7 @@ export class NeteaseProvider implements MusicProvider {
   }
 
   async search(query: string, limit = 20): Promise<SearchResult> {
-    const [songRes, playlistRes, albumRes] = await Promise.all([
+    const [songRes, playlistRes] = await Promise.all([
       this.api.get("/cloudsearch", {
         params: { keywords: query, type: 1, limit, ...this.cookieParams },
       }),
@@ -116,9 +103,6 @@ export class NeteaseProvider implements MusicProvider {
           ...this.cookieParams,
         },
       }),
-      this.api.get("/cloudsearch", {
-        params: { keywords: query, type: 10, limit: 5, ...this.cookieParams },
-      }),
     ]);
 
     const songs: Song[] = (songRes.data?.result?.songs ?? []).map(
@@ -143,9 +127,7 @@ export class NeteaseProvider implements MusicProvider {
       platform: "netease",
     }));
 
-    const albums = mapNeteaseAlbums(albumRes.data?.result?.albums);
-
-    return { songs, playlists, albums };
+    return { songs, playlists, albums: [] };
   }
 
   async getSongUrl(songId: string, quality?: string): Promise<string | null> {

src/music/qq.test.ts

@@ -1,43 +0,0 @@
-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,7 +8,6 @@ import type {
   SearchResult,
   QrCodeResult,
   AuthStatus,
-  Album,
 } from "./provider.js";
 import { parseLyrics } from "./netease.js";
 
@@ -28,26 +27,6 @@ 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++) {
@@ -86,12 +65,11 @@ export class QQMusicProvider implements MusicProvider {
       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 },
+        param: {
+          searchid: "1",
+          query,
+          num_per_page: Math.min(limit, 50),
+        },
       },
     });
     const res = await qqDirectApi.get("/cgi-bin/musicu.fcg", {
@@ -112,10 +90,7 @@ export class QQMusicProvider implements MusicProvider {
       platform: "qq",
     }));
 
-    const albumList: any[] = res.data?.req_album?.data?.body?.album?.list ?? [];
-    const albums = mapQqAlbums(albumList);
-
-    return { songs, playlists: [], albums };
+    return { songs, playlists: [], albums: [] };
   }
 
   async getSongUrl(songId: string, quality?: string): Promise<string | null> {

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,20 +52,14 @@ 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, albums, playlists });
+      res.json({ songs });
     } catch (err) {
       logger.error({ err }, "Unified search failed");
       res.status(500).json({ error: (err as Error).message });

src/web/api/player.ts

@@ -313,78 +313,6 @@ 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/server.ts

@@ -8,6 +8,7 @@ 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";
@@ -25,6 +26,7 @@ export interface WebServerOptions {
   configPath: string;
   logger: Logger;
   cookieStore?: CookieStore;
+  avatarStore: AvatarStore;
   staticDir?: string;
 }
 
@@ -43,7 +45,7 @@ export function createWebServer(options: WebServerOptions): WebServer {
     app.set("trust proxy", true);
   }
 
-  app.use(express.json());
+  app.use(express.json({ limit: "400kb" }));
 
   app.get("/api/config/public-url", (_req, res) => {
     const raw = (options.config.publicUrl ?? "").trim();
@@ -52,7 +54,14 @@ export function createWebServer(options: WebServerOptions): WebServer {
 
   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",

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/router/index.ts

@@ -22,13 +22,6 @@ const router = createRouter({
       path: '/playlist/:id',
       name: 'playlist',
       component: () => import('../views/Playlist.vue'),
-      meta: { kind: 'playlist' },
-    },
-    {
-      path: '/album/:id',
-      name: 'album',
-      component: () => import('../views/Playlist.vue'),
-      meta: { kind: 'album' },
     },
     {
       path: '/lyrics',

web/src/stores/player.ts

@@ -322,16 +322,6 @@ 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

web/src/views/Playlist.vue

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

web/src/views/Search.vue

@@ -20,54 +20,22 @@
 
     <div v-if="loading" class="loading">搜索中...</div>
 
-    <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>
+    <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>
 
-      <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>
+    <div v-else-if="searched" class="empty">
+      未找到相关结果
+    </div>
   </div>
 </template>
 
@@ -77,21 +45,15 @@ import { useRoute } 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 query = ref((route.query.q as string) || '');
+import { Song } from '../stores/player.js';
 
-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 songs = ref<Song[]>([]);
-const albums = ref<Album[]>([]);
-const playlists = ref<Playlist[]>([]);
+const results = ref<Song[]>([]);
 const loading = ref(false);
 const searched = ref(false);
 
@@ -100,12 +62,12 @@ async function doSearch() {
   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 ?? [];
+    const res = await axios.get('/api/music/search/all', {
+      params: { q: query.value },
+    });
+    results.value = res.data.songs;
   } catch {
-    songs.value = []; albums.value = []; playlists.value = [];
+    results.value = [];
   } finally {
     loading.value = false;
   }
@@ -179,23 +141,4 @@ onMounted(() => {
   flex-direction: column;
   gap: 2px;
 }
-
-.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; }
-}
 </style>

web/src/views/Settings.vue

@@ -116,6 +116,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,6 +443,13 @@
                 @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>
@@ -450,6 +461,8 @@
 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';
 
@@ -475,6 +488,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 +649,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 +658,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
@@ -1408,6 +1430,11 @@ onUnmounted(() => {
   }
 }
 
+.profile-toggle-static {
+  cursor: default;
+  align-items: flex-start;
+}
+
 @media (max-width: 768px) {
   .profile-bot-header {
     padding: 14px 12px;