项目概述
本项目是一套名为“聆境”的智能音乐推荐与 AI 音乐创作平台，围绕“发现音乐—理解偏好—对话推荐—点歌播放—生成作品—音频分析”形成完整业务流程。系统采用 Vue 3 + Flask 前后端分离架构，使用 MySQL 保存曲库与业务数据，使用 LangGraph 编排多 Agent，通过真实大模型服务完成对话、个性化推荐说明与音乐创作。
系统面向桌面网页，界面采用 Liquid Glass 液态玻璃风格，以深靛蓝为背景、薄荷青为主色、淡紫为辅助色。普通用户可浏览曲库、管理收藏与歌单、使用音乐助手、创作音乐和分析上传音频；管理员可维护用户、曲库、标签、FAQ 知识库，并查看任务、操作日志和统计图表。
音乐基础数据来自项目提供的 flask_music.sql。全量导入基准为 515,435 首歌曲、45,176 位歌手、15,486 条歌词记录；原始历史评论 186,140 条，按评论 ID 去重后为 184,923 条。原始四个 tb_* 表和标准化业务表统一保存在 flask_music 数据库中，保留来源信息与异常数据报告。上述数量是导入基准，后续管理员维护可能改变实时统计。
原始 SQL 提供音乐元数据，不包含音频文件，也不提供全量歌曲风格或情绪标签。系统标签由管理员维护，评论者不作为本站用户，评论情感不作为歌曲情绪。当前推荐采用规则与内容匹配，并由 LLM 辅助生成解释或精选候选，不包含推荐模型训练。
核心创新点
多 Agent 按意图协作：以实际 LangGraph StateGraph 组织 Router、Knowledge、Tool、Recommender、Generator、Summary 六个节点，按请求选择路径，不要求每轮经过全部节点。
真实曲库与业务服务联动：助手检索、推荐、点歌均调用后端允许的业务服务；推荐歌曲引用真实曲库记录，知识问答使用后台维护的 FAQ 内容。
可解释的个性化推荐：结合场景标签、显式偏好、收藏关联和热度筛选歌曲，LLM 根据逐曲资料形成不同的推荐理由，并直接展示在歌曲列表中。
流式回答与协作可视化：通过 SSE 推送回答增量、节点状态、音乐卡片和任务卡片，以箭头路径展示 Agent 协作、耗时和结果摘要。展示的是执行过程摘要，不是模型内部隐含推理。
从对话到播放与创作：支持“帮我播放一下毛不易的消愁”等自然语言点歌，也可进入音乐创作流程；用户绑定自己的网易云账号，按该账号实际曲目权限播放。
持久化会话与后台任务：会话刷新可恢复；音乐生成和音频分析由独立 Worker 执行，页面用阶段进度条、说明和耗时反馈状态，结果保存后可再次访问。
权限分层与管理可视化：采用 JWT 鉴权、管理员权限及资源所有权校验，配合真实统计和操作记录，支持完整毕业设计演示。
技术架构
整体架构设计
系统采用前后端分离，包含前端展示层、后端业务层、Agent 编排层、后台任务层、数据库与文件存储层，并接入外部模型和音乐服务：
桌面浏览器：Vue 3 用户端与管理端（开发端口 5174）
│ REST API / 携带鉴权的 SSE
Flask API（默认端口 5020）
├─ 账号与权限、曲库检索、个人音乐、推荐、文件与任务接口
├─ LangGraph：Router / Knowledge / Tool / Recommender / Generator / Summary
│ └─ 复用业务服务，调用兼容 Chat Completions 的真实模型接口
├─ MySQL 8.4：flask_music，保存原始表、业务表、会话和任务
├─ 独立 Python Worker
│ ├─ generation：调用 MiniMax，下载并保存生成音频
│ └─ analysis：调用 FFmpeg、FFprobe 与 librosa 分析音频
├─ 私有网易云 MCP 服务（本机端口 5030）
│ └─ 用户扫码授权、按本人权限获取音源
└─ runtime：日志、上传文件、生成作品、分析结果、缓存和报告
代码统一位于 项目代码/backend 与 项目代码/frontend，原生 HTML/CSS/JavaScript 原型保留在 项目代码/frontend/prototype。runtime 集中存放运行产物，构建输出位于 runtime/build；MySQL 自身数据目录由数据库服务管理。当前只要求桌面网页正常使用。
后端 Python 虚拟环境由使用者自行创建和选择，不依赖固定环境目录。后端可使用所选解释器直接运行 项目代码/backend/run.py，启动器托管 API、网易云 MCP 和分析、生成两个 Worker；前端在 项目代码/frontend 执行 npm run dev。正式开发入口为 http://127.0.0.1:5174，端口 5173 对应早期已审核原型。具体环境配置与初始化命令见《运行说明.md》。
技术栈详解
前端技术栈
核心框架：Vue 3 + Composition API + TypeScript。
UI 组件与视觉：Element Plus，结合自定义 Liquid Glass 样式和桌面导航高亮。
状态与路由：Pinia、Vue Router；全局曲库播放器保持跨页面播放状态。
HTTP 与流式通信：原生 fetch 封装 REST 请求与 SSE 读取，统一处理鉴权和错误。
图表与内容展示：ECharts、markdown-it 与 DOMPurify；音频使用浏览器原生媒体能力。
构建工具：Vite，依赖通过 npm 管理。
后端技术栈
核心框架：Python 3.13、Flask 3.1 系列，按接口、服务、集成适配器分层组织。
数据库与迁移：MySQL 8.4、SQLAlchemy、Flask-Migrate，统一数据库名 flask_music。
身份与权限：JWT、密码哈希、会话撤销、管理员权限和用户资源归属校验。
Agent 编排：LangGraph StateGraph，按实际意图路由六个协作节点。
聊天模型：通过 HTTPX 调用兼容 OpenAI Chat Completions 协议的外部模型服务；服务地址、密钥和模型 ID 由后端配置。
音乐生成：接入 TokenHub 音乐生成接口，使用 minimax-music-v2.6；生成请求遵循项目已验证的 UTF-8 JSON 调用方式。
后台任务与音频分析：独立 Python Worker + MySQL 持久任务；FFmpeg、FFprobe、librosa 完成真实文件探测和基础特征分析，无需 Redis 或 Celery。
播放与短信集成：私有 Node.js 网易云 MCP 服务提供账号授权及音源能力；短信适配器按项目短信示例的 APPCODE 表单协议请求供应商。服务密钥仅保存在后端。
核心功能模块
1. 用户管理系统
功能特性
独立账号页面：登录、注册和重置密码采用独立页面，不嵌入系统侧栏和播放器布局。
多种登录方式：支持用户名或已保存手机号加密码登录，以及短信验证码登录；未注册手机号验证成功后自动创建普通账号。
短信重置密码：通过重置用途验证码后设置新密码，成功后撤销该账号已有登录会话。验证码具备有效期、单次使用、失败次数和发送频率限制。
个人资料维护：在昵称下方直接编辑手机号，与昵称一起点击“保存资料”，无需当前密码或短信验证码。支持修改和留空移除，校验格式及号码唯一性；手机号变化后使相关未消费验证码失效。
偏好与账号管理：设置偏爱的歌手和音乐标签、修改密码；在个人中心扫码绑定自己的网易云账号，二维码以网页级弹窗展示。
管理员用户管理：支持用户分页查询、启停及密码重置；普通用户不能访问管理接口。
当前实现边界：用户密码按既定需求仅要求非空，无长度或字母种类限制。短信流程与自动测试已实现，真实短信送达仍需有效供应商模板和本人手机号验收，不能以配置存在或单元测试通过代替送达结果。
2. 智能AI音乐助手模块
功能特性
多会话与上下文：支持新建、重命名、删除会话，切换历史消息，保存多轮上下文及音乐、任务卡片。用户消息位于右侧，助手回答位于左侧。
六 Agent 职责分工：Router 识别意图与条件；Knowledge 检索知识库；Tool 调用检索、详情、偏好、分析和点歌等允许的业务工具；Recommender 从真实候选中精选并解释；Generator 创建音乐生成任务；Summary 汇总结果并流式回复。
按需协作路径：推荐可采用 Router → Tool → Recommender → Summary，点歌采用 Router → Tool → Summary，知识问答采用 Router → Knowledge → Summary，生成请求采用 Router → Generator → Summary。页面以实际运行事件为准展示箭头、节点状态、耗时和可展开摘要。
对话推荐优化：支持歌手、关键词、场景、排除条件及上一轮条件延续，区分“或”和“同时满足”的标签语义；结合真实标签覆盖情况检索，避免将无标注标签强行作为筛选条件。默认对本会话近期歌曲去重，可明确要求允许重复。
自然语言点歌：例如“帮我播放一下毛不易的消愁”，助手匹配真实歌曲并发出播放请求；多版本按匹配及热度规则选择并说明。历史会话恢复不会自动重播，浏览器限制自动播放时可手动点击播放。
音乐创作室：通过 minimax-music-v2.6 支持自定义歌词、自动写词、纯音乐三种模式，可从创作室或助手发起相应流程。
我的作品与进度反馈：后台生成期间展示排队、生成、下载保存等阶段和耗时；成功后提供作品详情、本地播放和下载。进度条表示实际任务阶段，不代表供应商精确生成百分比。
可靠性与失败处理：生成任务持久化并使用幂等标识防止重复创建；上游超时或结果不确定时不自动重新提交付费请求。模型不可用时明确提示；助手推荐说明降级为曲库依据时标明来源，不伪装 AI 成功。
3. 音乐信息管理
功能特性
发现音乐与音乐曲库：展示歌曲卡片、封面、歌手、专辑、热度等信息；支持搜索、分页、单选标签筛选和歌手信息浏览。
搜索与输入候选：歌名、歌手、专辑等搜索框根据实际曲库匹配，输入后展示候选，辅助用户准确定位歌曲或歌手。
歌曲详情与歌词：展示歌曲元数据、可用歌词及历史评论；隐藏 [00:00.000] 等时间标记。正在播放当前曲目且存在时间轴歌词时，歌词随进度滚动并高亮当前行；普通文本歌词仍可阅读。
曲库原生播放：通过后端对接网易云 MCP，按当前用户自己的账号权限获取音源，由全局播放器提供暂停、进度拖动、音量及跨页保持；点击播放器封面或歌名可进入歌曲详情。
播放边界：VIP 曲目是否完整播放取决于账号权益和具体曲目可用性；试听明确提示，不承诺全部 VIP 音乐可播。保留原站入口和可配置的 iframe 兼容方式；跨域 iframe 不用于获取真实播放时长，曲库不提供歌曲下载入口。
我的音乐：收藏、不喜欢、个人歌单及最近打开的曲目；这些操作与推荐服务形成反馈闭环。
上传与分析：支持个人 MP3、WAV、FLAC，最大 50 MiB、最长 15 分钟。上传校验后由 Worker 分析，页面显示阶段进度、波形、时长、采样率、估计 BPM、RMS 能量及频谱重心等结果，可交给助手解释。
音频访问与分析边界：上传和生成文件采用受控访问并支持 Range 请求；其他用户不能直接访问私有文件。没有实际音频的曲库记录仅分析元数据，不声称已识别其真实节奏、音色或情绪。
后台维护：管理员维护歌曲、歌手、封面和标签，调整上下架状态；业务改动与导入来源信息分开保留，助手查询当前业务数据。
4. 个性化音乐智能推荐
功能特性
结合偏好与场景召回：使用显式歌手偏好、标签偏好、收藏歌曲的歌手及标签关联，并结合来源热度筛选在架曲目。无偏好时提供热门探索，减少冷启动空白。
排序与多样性：综合场景匹配、显式偏好、收藏关联、热度排序，优先发现尚未收藏的曲目，排除不喜欢的歌曲，并减少同歌手及同名录音重复；不将热度直接等同于用户喜好。
单选标签交互：“音乐曲库”和“为你推荐”的筛选标签均为单选；个人中心的长期偏好设置仍可选择多个标签。
逐曲个性化说明：“为你推荐”由规则确定歌曲和顺序，再由 LLM 结合歌手、专辑、时长、曲库标签、可用歌词主题及真实偏好关联撰写独立理由。理由直接放在歌曲列表中，避免所有歌曲重复同一句模板。
完整生成后展示：AI 理由未准备好时隐藏整批推荐歌曲，展示候选匹配、资料整理、LLM 分析、结果校验等阶段和耗时；全部歌曲与理由校验对应后再展示。失败保留提示及重试入口，缓存命中时直接复用，不伪造等待。
真实记录约束：校验推荐 ID、理由数量和歌曲对应关系，拒绝候选外歌曲与缺失理由。模型说明以提供的资料为依据，不以歌名推测不存在的故事，也不把未分析的音频特征写成事实。
持续反馈：用户可播放、收藏、加入个人歌单或标记不喜欢，后续推荐读取最新偏好和反馈。效果受标签覆盖、用户记录及模型服务可用性影响，不宣称已经训练出全量音乐情绪模型。
5. 管理控制台
功能特性
业务指标卡：查看曲库音乐、注册用户、会话记录及启用知识条目，数据来自实际业务查询。
统计图表：使用 ECharts 展示近 7 日注册、对话消息、生成任务、打开播放器及曲库播放等趋势，并展示歌曲标签分布和标签覆盖情况。曲库播放事件不等同于完整收听时长。
内容与账号维护：提供用户、歌曲、歌手、标签、FAQ 知识库的管理入口；知识库修改可用于后续助手问答，标签维护影响推荐候选范围。
任务与运行记录：查询分析及音乐生成任务状态、失败原因、请求关联信息和操作日志；对结果未确认、下载失败等情况提供明确状态。
权限与隐私边界：管理员权限由后端校验，不能仅靠隐藏菜单控制访问；管理诊断不直接暴露其他用户的私有音频、完整创作正文或服务密钥。
应用场景
日常发现音乐：按歌名、歌手或专辑搜索，查看候选和详情，通过歌词与历史评论了解曲目，收藏并整理自己的歌单。
学习、通勤、运动与睡前选歌：选择已有标注的场景，结合个人偏好获得真实歌曲及具体推荐理由；也可用自然语言继续调整条件。
对话点歌与音乐问答：直接说出想听的歌名、歌手，交给助手检索并请求播放；询问系统使用方法时检索 FAQ，并展示 Agent 协作过程。
原创音乐创意表达：输入主题、风格或自定义歌词，使用真实 AI 服务创作音乐，在“我的作品”查看进度并管理生成结果。
个人音频基础分析：上传合法持有的音频，观察波形、节奏估计和能量指标，借助助手理解分析报告。
毕业设计与技术演示：展示真实曲库导入、前后端分离、LangGraph 多 Agent 协作、SSE、后台任务、文件访问控制及管理可视化。演示以实际页面和真实服务结果为准，未配置或未验收的外部能力如实说明。
