teamspeak-music-bot/docs/superpowers/plans/2026-07-06-jellyfin-source.md

Jellyfin 音源（主音源化）实施计划

目标：自建 Jellyfin 服务器成为默认且主要的音源；现有 NetEase / QQ / Bilibili / YouTube / Kugou 继续编译但默认停用（enabledProviders 配置门控，本次不删除）。约束：src/audio/*、 src/ts-protocol/* 不改（唯一例外：queue.ts 中 QueuedSong.platform 联合类型加一个成员， 纯类型加宽，无任何逻辑改动，否则无法编译）。

触点地图

后端：

• src/music/provider.ts — platform 联合类型加 "jellyfin"（Song/Playlist/Album/MusicProvider）
• src/audio/queue.ts — 同上（仅类型，一个词）
• src/data/database.ts — PlayHistoryRecord.platform 加 "jellyfin"
• src/music/auth.ts — CookieStore 平台加 "jellyfin"（token JSON 与 cookie 同路径持久化）
• src/data/config.ts — 新增 JellyfinConfig（serverUrl / authMode / username / password / apiKey / userId）+ enabledProviders（默认 ["jellyfin"]）+ 载入清洗 + isProviderEnabled / defaultPlatform 助手。spotify 仍由 spotify.enabled 门控、local 仍由 localAudioEnabled 门控
• src/music/jellyfin.ts — 新 Provider：认证（userpass=AuthenticateByName + MediaBrowser 头， 401 重登一次；apikey=X-Emby-Token）、搜索（Audio/MusicAlbum/Playlist, StartIndex 翻页）、 懒解析播放 URL（direct=/Audio/{id}/stream?static=true；320/192/128=/Audio/{id}/universal 转码）、歌单/专辑/歌词（ticks→秒，404=无歌词）、收藏→InstantMix 电台链（收藏→最近播放→随机曲目）、 最近添加/最多播放/流派、播放上报（Sessions/Playing[/Progress|/Stopped]，全部吞错）、 音质档（direct 原始直传 / 320k / 192k / 128k）
• src/music/api-server.ts — 按 provider 开关决定是否绑定 3001/3200
• src/index.ts — 构造 JellyfinProvider、加载持久化 token、穿线
• src/bot/manager.ts — 穿线 jellyfinProvider（与 spotifyProvider 同模式）
• src/bot/instance.ts — jellyfin 分支（getProviderFor / getProvider，新 flag -j/-n）、 默认平台=jellyfin、停用音源友好报错、歌单/专辑命令识别 GUID、播放上报挂钩、帮助文本
• src/web/api/music.ts — provider 选择 + 门控、/providers、jellyfin 首页数据端点、音质路由
• src/web/api/auth.ts — jellyfin 状态 + 测试连接（/System/Info）；无 QR
• src/web/api/player.ts — 平台白名单 + platformFlag（netease 显式 -n）
• src/web/api/bot.ts — settings 读写 jellyfin 配置块（密码/APIKey 写入不回显）+ 热更新 provider

前端（Vue 3，保持 YesPlayMusic 风格；新增文案 zh+en）：

• stores/player.ts — Source 加 jellyfin、enabledProviders 状态、jellyfin 首页数据
• views/Search.vue — 音源条只显示启用的 provider、Jellyfin 徽标
• views/Home.vue — 最近添加 / 播放最多 / 我的歌单 / 收藏 / 流派 区块 + jellyfin FM 卡片
• views/Settings.vue — Jellyfin 连接卡（地址/认证模式/凭据/测试连接）、隐藏停用 provider 的 登录卡、jellyfin 音质档
• views/Setup.vue — 向导第 3 步换成 Jellyfin 连接卡
• views/Playlist.vue 等 — ID 均按 string 处理，审计通过（GUID 无数字假设）

文档：README 增加「Jellyfin 音源」章节 + fork 出处与 MIT 归属（上游 ZHANGTIANYAO1/teamspeak-music-bot）。

阶段与验证

1. 类型 + 配置 → npx tsc --noEmit
2. JellyfinProvider + 单测 → tsc + vitest
3. 门控 + bot 穿线 → tsc + vitest
4. REST → tsc + vitest
5. WebUI → cd web && npm run build
6. README + 全量构建/测试