teamspeak-music-bot/docs/superpowers/specs/2026-03-29-tsmusicbot-design.md

TSMusicBot 设计文档

日期: 2026-03-29 状态: 已批准

概述

TSMusicBot 是一个从零构建的 TeamSpeak 音乐机器人，支持播放网易云音乐和 QQ 音乐。机器人作为 TeamSpeak 客户端连接服务器，用户可通过精美的 WebUI 或 TeamSpeak 内文字命令进行操控。安装体验为一键式，面向不懂代码的用户。

1. 架构设计

整体架构

单体架构（Monolith），所有组件运行在一个 Node.js 进程中。

┌─────────────────────────────────────────────────────────────────┐
│                      TSMusicBot (单体进程)                       │
│                                                                 │
│  ┌──────────────┐  ┌──────────────┐  ┌───────────────────────┐  │
│  │   WebUI 层    │  │  TS 命令层   │  │     Bot 管理器        │  │
│  │              │  │              │  │                       │  │
│  │  Vue.js SPA  │  │ !play !next  │  │  BotInstance #1       │  │
│  │  Express API │  │ !pause !vol  │  │  BotInstance #2       │  │
│  │  WebSocket   │  │ !queue !skip │  │  BotInstance #N       │  │
│  └──────┬───────┘  └──────┬───────┘  └───────────┬───────────┘  │
│         │                 │                      │              │
│         └─────────────────┴──────────────────────┘              │
│                           │                                     │
│              ┌────────────┴────────────┐                        │
│              │      核心服务层          │                        │
│              │                         │                        │
│              │  ┌───────────────────┐  │                        │
│              │  │   播放引擎        │  │                        │
│              │  │  FFmpeg 解码      │  │                        │
│              │  │  Opus 编码        │  │                        │
│              │  │  播放队列管理     │  │                        │
│              │  └───────────────────┘  │                        │
│              │                         │                        │
│              │  ┌───────────────────┐  │                        │
│              │  │   音乐源服务      │  │                        │
│              │  │  网易云 API       │  │                        │
│              │  │  QQ音乐 API      │  │                        │
│              │  │  搜索/歌单/专辑   │  │                        │
│              │  └───────────────────┘  │                        │
│              │                         │                        │
│              │  ┌───────────────────┐  │                        │
│              │  │   TS 协议层       │  │                        │
│              │  │  TCP 命令通道     │  │                        │
│              │  │  UDP 语音通道     │  │                        │
│              │  │  (无加密)         │  │                        │
│              │  └───────────────────┘  │                        │
│              └─────────────────────────┘                        │
│                                                                 │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │                     数据层                                │   │
│  │   SQLite (用户数据/播放记录)  +  JSON (配置/Cookie)       │   │
│  └──────────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────┘

六大核心模块

1. TS 协议层 — 实现 TeamSpeak 3 客户端协议（参考 TSLib），包括 TCP 命令通道（登录、频道操作、文字消息）和 UDP 语音通道（Opus 音频包发送）。不实现加密。
2. 播放引擎 — 通过 FFmpeg 子进程解码音频源（MP3/FLAC/AAC），输出 PCM 数据，再用 node-opus 编码为 Opus 格式，按 20ms 帧发送到 TS 语音通道。管理播放队列、循环模式、音量控制。
3. 音乐源服务 — 内嵌启动 NeteaseCloudMusicApi 和 QQMusicApi 服务，提供统一的搜索、获取歌曲 URL、歌单、专辑、歌词等接口。处理账号登录（扫码/短信/Cookie）和 Cookie 自动刷新。
4. WebUI + API — Express 提供 REST API 和静态文件服务（Vue.js SPA）。WebSocket 实现实时状态推送（当前播放、队列变化、在线用户）。
5. Bot 管理器 — 管理多个 BotInstance 的生命周期。每个实例拥有独立的 TS 连接、播放引擎和队列。支持通过 WebUI 创建/删除/配置实例。
6. TS 命令层 — 监听 TS 频道文字消息，解析命令（如 !play、!next、!vol），权限检查后转发给对应的 BotInstance 执行。支持自定义命令前缀和别名。

数据流

用户点歌 (!play 晴天 或 WebUI 搜索)
  → 命令层/API 层调用音乐源服务搜索歌曲
  → 音乐源服务从网易云/QQ音乐 API 获取歌曲 URL
  → 播放引擎: FFmpeg 下载并解码为 PCM → Opus 编码
  → TS 协议层: 通过 UDP 将 Opus 音频包发送到 TS 服务器
  → WebSocket: 推送播放状态更新到 WebUI

2. WebUI 设计

设计风格

参考 YesPlayMusic（Apple Music 风格），核心设计要素：

• 深色主题为默认，支持浅色主题切换
• 毛玻璃导航栏和播放栏 (backdrop-filter: blur(20px))
• 专辑封面彩色阴影效果（node-vibrant 动态提取主色）
• 大字号标题（22-42px），Barlow + PingFang SC / Microsoft YaHei 字体
• 圆角卡片（10-14px radius），充足留白
• 流畅微交互（hover scale 1.04, active scale 0.96, 0.3s transitions）
• 沉浸式歌词页 — 全屏、模糊背景、动态色彩

整体布局

• 固定毛玻璃导航栏（56px，顶部）：Logo、导航链接（发现/搜索/歌单/播放历史）、Bot 状态指示、管理入口
• 主内容区：10vw 水平内边距，Bot 实例切换器 + 主要内容 + 右侧边栏（队列/频道信息）
• 固定毛玻璃播放栏（56px，底部）：当前歌曲信息、播放控制、音量/队列/歌词入口

页面清单

1. 发现（首页） — 推荐歌单、热门排行、正在播放状态、快速搜索入口
2. 搜索 — 跨平台搜索（网易云/QQ音乐切换），结果展示歌曲/歌单/专辑/歌手
3. 歌单详情 — 歌单封面、歌曲列表、一键播放全部、逐首添加到队列
4. 歌词页 — 沉浸式全屏歌词，动态背景（专辑色彩提取），逐行高亮
5. 播放历史 — 播放记录，按时间/平台筛选，快速重播
6. 设置/管理 — Bot 实例管理、TS 服务器连接配置、音乐账号登录（扫码/短信/Cookie）、命令前缀设置、频道行为配置

3. TeamSpeak 命令系统

用户在 TeamSpeak 频道内发送文字消息控制机器人。默认命令前缀 !，可在 WebUI 中自定义。支持私聊和频道消息两种触发方式。

播放控制

命令	说明
!play <歌名/URL/ID>	搜索并播放歌曲（默认网易云，加 -q 切 QQ 音乐）
!play -q <歌名>	从 QQ 音乐搜索并播放
!pause	暂停播放
!resume	恢复播放
!stop	停止播放并清空队列
!next / !skip	下一首
!prev	上一首
!vol <0-100>	设置音量
!now	显示当前播放歌曲信息

队列管理

命令	说明
!add <歌名/URL/ID>	添加歌曲到队列尾部（不立即播放）
!queue / !list	显示当前播放队列
!clear	清空播放队列
!remove <序号>	移除队列中指定位置的歌曲
!mode <seq|loop|random|rloop>	切换播放模式：顺序/单曲循环/随机/随机循环

歌单 & 专辑

命令	说明
!playlist <歌单ID/URL>	加载歌单并开始播放
!album <专辑ID/URL>	加载专辑并开始播放
!fm	开启私人 FM 模式（网易云）

社交互动

命令	说明
!vote	发起投票切歌（频道内过半数同意即跳过）
!lyrics	在频道消息中显示当前歌词片段

管理命令

命令	说明
!move <频道名/ID>	移动机器人到指定频道
!follow	机器人跟随你到你所在的频道
!help	显示命令帮助列表

命令系统特性

• 命令前缀可自定义（默认 !），在 WebUI 设置页修改
• 命令别名可配置（如 !p → !play）
• 搜索结果多首时，回复序号选择
• 支持私聊和频道消息两种触发方式

权限系统

• 所有人: play, add, queue, now, lyrics, vote, help
• 管理员: stop, clear, move, vol, mode, follow
• 管理员通过 TS Server Group 或 WebUI 配置指定
• WebUI 管理页面需要密码登录

4. 技术栈

后端

依赖	用途
Node.js 20 LTS	运行时
TypeScript 5.x	开发语言
Express 4.x	Web 框架
ws	WebSocket
better-sqlite3	SQLite 数据库
FFmpeg (子进程)	音频解码
@discordjs/opus 或 opusscript	Opus 编码
自研 TS3 协议 (参考 TSLib)	TeamSpeak 连接
Node.js crypto + tweetnacl	Ed25519 身份
NeteaseCloudMusicApi (内嵌)	网易云音乐 API
QQMusicApi (内嵌)	QQ 音乐 API
pino	日志

前端

依赖	用途
Vue 3 + Composition API	UI 框架
Vite 5.x	构建工具
Vue Router 4	路由
Pinia	状态管理
SCSS + CSS Variables	样式 / 主题
node-vibrant	专辑封面主色提取
Iconify	图标 (按需加载)
axios	HTTP 客户端
Barlow + 系统中文字体	排版

数据存储

• SQLite (better-sqlite3): 用户数据、播放记录、Bot 实例信息
• JSON 文件: 应用配置（方便手动编辑）、音乐平台 Cookie

5. 项目结构

TSMusicBot/
├── package.json
├── tsconfig.json
├── config.json                  # 用户配置（JSON，可手动编辑）
│
├── src/                         # 后端源码
│   ├── index.ts                 # 入口：启动所有服务
│   │
│   ├── ts-protocol/             # TeamSpeak 3 客户端协议实现（无加密）
│   │   ├── connection.ts        # TCP/UDP 连接管理
│   │   ├── identity.ts          # TS3 身份生成与管理
│   │   ├── commands.ts          # TS3 命令编解码
│   │   ├── voice.ts             # 语音数据包发送/接收
│   │   └── client.ts            # 高层 TS3 Client 封装
│   │
│   ├── audio/                   # 音频处理
│   │   ├── player.ts            # 播放引擎（FFmpeg → Opus → TS）
│   │   ├── queue.ts             # 播放队列管理
│   │   └── encoder.ts           # Opus 编码封装
│   │
│   ├── music/                   # 音乐源服务
│   │   ├── provider.ts          # 统一音乐源接口
│   │   ├── netease.ts           # 网易云适配器
│   │   ├── qq.ts                # QQ音乐适配器
│   │   ├── auth.ts              # 账号认证（扫码/短信/Cookie）
│   │   └── api-server.ts        # 内嵌 API 服务启动器
│   │
│   ├── bot/                     # Bot 核心
│   │   ├── instance.ts          # BotInstance（一个TS连接+播放引擎）
│   │   ├── manager.ts           # 多实例管理器
│   │   └── commands.ts          # TS 文字命令解析与执行
│   │
│   ├── web/                     # Web 服务
│   │   ├── server.ts            # Express + 静态文件 + WebSocket
│   │   ├── api/                 # REST API 路由
│   │   │   ├── bot.ts           # Bot 管理接口
│   │   │   ├── music.ts         # 搜索/歌单/歌曲接口
│   │   │   ├── player.ts        # 播放控制接口
│   │   │   └── auth.ts          # 登录认证接口
│   │   └── websocket.ts         # WebSocket 事件推送
│   │
│   └── data/                    # 数据层
│       ├── database.ts          # SQLite 封装
│       ├── config.ts            # JSON 配置读写
│       └── migrations/          # 数据库迁移脚本
│
├── web/                         # 前端源码 (Vue.js SPA)
│   ├── index.html
│   ├── vite.config.ts
│   ├── src/
│   │   ├── App.vue
│   │   ├── main.ts
│   │   ├── router/              # 路由定义
│   │   ├── stores/              # Pinia 状态管理
│   │   ├── views/               # 页面组件
│   │   │   ├── Home.vue         # 发现/首页
│   │   │   ├── Search.vue       # 搜索
│   │   │   ├── Playlist.vue     # 歌单详情
│   │   │   ├── Lyrics.vue       # 沉浸式歌词
│   │   │   ├── History.vue      # 播放历史
│   │   │   └── Settings.vue     # 设置/管理
│   │   ├── components/          # 可复用组件
│   │   │   ├── Player.vue       # 底部播放栏
│   │   │   ├── Navbar.vue       # 顶部导航栏
│   │   │   ├── Queue.vue        # 播放队列面板
│   │   │   ├── SongCard.vue     # 歌曲卡片
│   │   │   └── CoverArt.vue     # 带彩色阴影的封面组件
│   │   ├── composables/         # 组合式函数
│   │   │   ├── useWebSocket.ts  # WebSocket 连接
│   │   │   └── usePlayer.ts     # 播放器状态
│   │   └── styles/              # 全局样式
│   │       ├── variables.scss   # CSS 变量 / 主题
│   │       └── global.scss      # 全局样式
│   └── public/
│
├── scripts/                     # 部署脚本
│   ├── install.sh               # Linux 一键安装
│   ├── install.bat              # Windows 一键安装
│   └── docker/
│       ├── Dockerfile
│       └── docker-compose.yml
│
└── data/                        # 运行时数据（gitignore）
    ├── tsmusicbot.db            # SQLite 数据库
    ├── cookies/                 # 音乐平台 Cookie
    └── logs/                    # 日志文件

6. 部署与安装

Windows

• 安装包 (.exe): 使用 pkg 打包 Node.js + 应用为单个 .exe，FFmpeg 作为附带二进制文件，Inno Setup 生成安装程序。双击安装 → 桌面快捷方式 → 双击启动 → 自动打开浏览器。
• 便携版 (.zip): 解压即用，包含所有依赖，双击 start.bat 启动。

Linux

• 一键脚本: curl -fsSL https://get.tsmusicbot.com | bash — 自动检测系统、安装 Node.js/FFmpeg、下载 TSMusicBot、配置 systemd 服务、启动。
• Docker: docker run -d -p 3000:3000 tsmusicbot/tsmusicbot — 镜像基于 node:20-slim，内含 FFmpeg，映射 ./data 持久化。

首次运行引导 (Setup Wizard)

4 步引导流程，在 WebUI 中完成：

1. 欢迎 — 设置 WebUI 管理员密码、选择语言（中/英）、选择主题（深色/浅色）
2. 连接 TS 服务器 — 输入服务器地址、端口、昵称、默认频道，点击"测试连接"验证
3. 音乐账号（可选） — 扫码/短信/Cookie 登录网易云或 QQ 音乐账号，跳过则只能播放免费歌曲
4. 完成 — Bot 已连接到 TS 服务器，跳转到主界面

端口配置

• WebUI 默认端口：3000（可在 config.json 中修改）
• 内嵌网易云 API 端口：3001（内部使用，不对外暴露）
• 内嵌 QQ 音乐 API 端口：3002（内部使用，不对外暴露）

7. 功能清单 (V1)

播放功能

• 搜索并播放歌曲（网易云/QQ音乐）
• 播放/暂停/停止/上一首/下一首
• 音量调节 (0-100)
• 4 种播放模式：顺序、单曲循环、随机、随机循环

播放列表

• 加载网易云/QQ音乐歌单
• 加载专辑
• 创建临时播放队列（添加/移除/清空/查看）
• 私人 FM 模式（网易云）

频道管理

• 自动跟随用户切换频道
• 无人时自动暂停
• 自动回到默认频道（可配置延迟）
• 手动移动到指定频道

社交互动

• 频道描述/Bot 头像更新为当前歌曲信息
• 投票切歌（频道内过半数同意）
• 频道内显示歌词片段

多实例

• 一个 WebUI 管理多个 Bot 实例
• 每个实例独立连接不同 TS 服务器或频道
• 独立的播放队列和配置

账号认证

• 扫码登录（网易云/QQ音乐）
• 短信登录（网易云）
• Cookie 手动导入
• Cookie 自动刷新

8. 未来演进

• 当音频编码出现性能瓶颈时，将 Opus 编码迁移到 Worker Threads
• 可扩展的音乐源插件系统（支持添加更多平台）
• 移动端 WebUI 适配