Bili Music（午夜黑胶）是一款基于 Tauri v2 + Rust 构建的非官方 B 站音乐播放器，将哔哩哔哩音乐区作为在线曲库使用。项目与哔哩哔哩无任何官方关联，仅供个人学习与研究。其核心设计原则贯穿始终：免登录（默认游客身份取流，无需账号 Cookie，规避封号风险）与不落盘（音频通过本地流代理在线播放，不下载、不缓存至磁盘）。这一选择刻意避开了“登录+下载”的便捷路径，转而追求零负担、零配置与隐私友好的听歌体验。
核心功能：从搜索到沉浸播放的完整链路
- 智能搜索与推荐：支持 B 站音乐区搜索，本地相关性重排使原曲优先于长合集与二创；可按单曲/合集筛选，粘贴 BV 号直接播放。首页“为你推荐”基于收藏、歌单、听歌记录，由 AI 生成检索意图并重排真实结果；支持复用用户自有 AI Key，通过自然语言（如“想听点安静的钢琴”）即时引导推荐方向。
- 真实听歌记录：仅当长歌播放 ≥30 秒或短歌完成 ≥90% 时才计入记录，持续优化推荐口味。
- 在线流式播放：后端 Axum 流代理透传 Range 请求，边下边播，全程不落盘。多 P 合集自动顺序连播，标题随分 P 切换。
- 收藏与歌单管理：本地 JSON 持久化，原子写入防止坏文件覆盖；支持收藏夹链接批量导入（自动跳过失效条目）、拖拽排序、数据一键备份/恢复（zip 格式）。
- 沉浸式体验：大封面滚动歌词页（支持 ±0.5s 校准与手动匹配）；四档主题（深色/浅色/背景图/动态取色渐变）+ 六种主题色可选；自定义无边框标题栏，原生桌面质感；侧边栏桌宠（小黑咪/糯米飘/橘子汪）对切歌、收藏等事件做出律动与气泡反馈。
- 系统级集成：Windows 任务栏悬停控制（上一首/暂停/下一首）；侧栏宽度可调、可折叠为图标模式，状态自动记忆。
技术亮点：工程决策解决真实痛点
1. 免登录游客取流性能优化
摒弃 yt-dlp + Cookie 方案，改用游客身份领取 buvid 票据 + WBI 签名获取音频直链。首播耗时从 ~12.79s 降至冷启动 ~1.83s、热态 ~0.54–0.91s。yt-dlp 仅作为可选兜底保留，默认分发版不含该依赖，确保双击即用。
2. 风控兼容与搜索稳定性
针对游客搜索返回 v_voucher 的问题，定位根因为缺失 buvid4。修复策略为“缺任一项即走 SPI 补齐”，而非强制登录，以最小代价兼容真实风控行为。
3. 搜索展示与播放队列解耦
将 searchState.results（展示）与 playerState.queue（播放）分离，搜索不再打断当前播放。仅当用户点击歌曲时，展示列表才升级为播放队列。此设计使首页榜单、收藏、歌单复用同一套播放状态机。
4. 切歌防串台机制
引入 requestVersion 作为请求代号，在登记代理 URL 前校验当前任务身份，迟到旧结果一律作废。既避免串台，又正确区分“解析失败”与“主动取消”。
5. 多 P 合集最小侵入接入
旁挂分 P 游标与显示层快照，不改动既有 BV 队列结构，保证连播功能接入的同时，维持队列、随机、循环、失败跳过逻辑的稳定性。
6. 本地数据原子写入
收藏、歌单、历史记录写入采用“临时文件→备份→重命名”流程，处理 Windows 重命名覆盖限制；读取损坏文件时显式报错，绝不以空数据覆盖。
7. 零幻觉 AI 推荐架构
LLM 仅生成检索意图与重排候选，所有输出 bvid 必须来自真实 search_videos 返回并逐个校验，模型无法编造资源。该不变量由回归测试保障，实现“听得越多推得越准”且杜绝幻觉风险。
8. 本地搜索结果重排
针对 B 站 totalrank 偏向点击率导致原曲被长视频压制的问题，实施四项加权打分：关键词覆盖率（|K∩T|/|K|，避免 Dice 系数误杀长前缀精确匹配）、时长合理性（单曲加分、超长降权）、精确短语命中、原始位次弱先验。重排开关由调用方显式传入，防止新增排序选项时静默失效。整套逻辑纯函数实现，带完整单元测试。
使用须知与边界
- 非官方性质：项目未获哔哩哔哩授权，存在接口变更或服务终止风险，请勿用于商业或大规模分发。
- AI Key 自理：一句话推荐功能需用户提供自有 API Key，项目不托管任何密钥。
- 游客身份限制：部分高版权内容可能仅限登录用户访问，此时 yt-dlp 兜底或手动登录为唯一解法。
- 数据本地化：所有用户数据存储于本机，卸载前请务必备份；跨设备迁移需手动导出/导入 zip。
- 平台合规：流代理仅用于个人收听，禁止录制、转售或公开传播音频流。
