# SoulTuner 功能说明 (Feature Walkthrough)

> SoulTuner-Agent 是一款本地部署的 AI 音乐推荐智能体，通过自然语言交互发现音乐，越用越懂你。

---

## 1. 首页 — 场景引导

启动后进入 **欢迎界面**，展示多张场景推荐卡片（深夜听歌、运动健身、驾车出行等）。

- **点击卡片** → 文字自动填入对话框，直接开始推荐
- 也可忽略卡片，在对话框自由输入

---

## 2. 对话推荐

### 2.1 五种对话方式

| 类型 | 示例 | 触发引擎 |
|------|------|----------|
| 纯情绪/氛围 | "心情很差，想一个人静一静" | Vector RAG（HyDE 声学描述 → 跨模态检索） |
| 场景+主观体验 | "跑步中，要重低音砸耳朵" | Hybrid RAG（标签筛选 + 声学向量） |
| 标签组合 | "周杰伦的浪漫情歌" / "英文摇滚" | GraphRAG（图谱精确匹配） |
| 时效资讯 | "最近抖音最火的歌" | Web Search（SearxNG 联网 + LLM 摘要） |
| 指定歌曲 | "帮我找《稻香》" | GraphRAG 精确查找，没有则引导入库 |

### 2.2 实时推荐过程

1. 💭 **思考动画** — 系统分析意图中
2. 🎵 **歌曲卡片逐首出现** — SSE 流式推送
3. 📝 **推荐理由逐字生成** — LLM 拟人化电台独白

每次最多返回 **15 首歌曲**。点击页面顶部 **← 返回** 可回到场景卡片重新选择。

---

## 3. 歌曲卡片 (SongCard)

每张卡片包含封面、歌曲信息和操作按钮：

### 3.1 播放

- **点击封面** → 播放/暂停（hover 显示遮罩图标）
- 正在播放的歌曲标题变为**绿色高亮**

### 3.2 操作按钮

| 按钮 | 功能 | 说明 |
|------|------|------|
| ☰+ 播放列表 | 加入/移出播放队列 | 纯前端操作 |
| ↓ 下载 | 下载到「待入库」 | 先暂存，需前往待入库页面确认入库 |
| ❤️ 红心 | 点赞/取消 | Neo4j `LIKES` 关系 |
| 👎 不喜欢 | 标记不喜欢，移除当前结果 | Neo4j `DISLIKES` 关系，后续推荐永久过滤 |
| 🔖 收藏 | 收藏到歌单（弹出选择面板） | Neo4j `SAVES` 关系 |
| ✕ 移除 | 从当前推荐列表移除 | 不影响后续推荐 |
| 🗑️ 删除 | 从本地曲库彻底删除 | 二次确认，删除图谱+音频+封面+歌词 |

### 3.3 标签与理由

- **流派标签**（灰色）、**情绪标签**（绿色）、**播放列表标记**
- 卡片底部显示推荐理由和检索来源（如 🔥双引擎交叉命中）

---

## 4. 全局播放器

页面底部固定的吸底播放器：

| 功能 | 说明 |
|------|------|
| 播放/暂停/上下首 | 基础控制 |
| 进度条拖动 | 定位播放位置 |
| 音量滑块 | 0-100% |
| 播放模式 | 顺序 → 随机 → 单曲循环（循环切换） |
| 全屏模式 | 大尺寸封面 + 歌词展示 + 粒子星空背景 |

### 隐式行为采集

| 行为 | 触发条件 | 后端事件 |
|------|----------|----------|
| 完整播放 | 歌曲播放完毕 | `full_play` → `LISTENED_TO` |
| 快速跳过 | 播放 <30秒 即切歌 | `skip` → `SKIPPED` |
| 单曲循环 | 循环模式播放 | `repeat` → `LIKES` 增强 |

---

## 5. 音乐旅程

侧边栏 **🗺️ 音乐旅程** 入口。

1. **描述故事**：如 "失恋了，一个人开车在雨中回老家，大概60分钟"
2. **可选设置**：地点、天气/活动、总时长、自定义情绪曲线
3. **LLM 拆解**：故事 → 3-6 个情绪片段（起承转合）
4. **流式推送**：每片段检索 2-4 首歌曲，SSE 实时推送
5. **无缝播放**：片段间自然过渡，像电影配乐

---

## 6. 个人音乐库

侧边栏「音乐库」分组下有 5 个子页面：

| 页面 | 功能 |
|------|------|
| **待入库** | 展示已下载但未入库的歌曲，勾选确认后触发标签提取+向量编码+图谱写入 |
| **我的曲库** | 全图谱歌曲管理（搜索/播放/删除） |
| **我的喜欢** | 所有点赞歌曲，按时间倒序 |
| **我的收藏夹** | 管理自建歌单，新增/删除歌单及歌曲 |
| **不喜欢管理** | 查看已屏蔽歌曲，可撤销「不喜欢」使其重新出现在推荐中 |

---

## 7. 用户画像

### 显式设置

在侧边栏底部 **我的画像** 打开：

| 维度 | 可选项 |
|------|--------|
| 🎸 流派偏好 | 摇滚 / 电子 / 爵士 / 嘻哈 / 民谣 / 古典 / R&B / 后摇 / 金属 / 流行 / 独立 / 氛围 / Lo-fi / 朋克 / Soul |
| 💭 情绪倾向 | 开心 / 悲伤 / 放松 / 热血 / 浪漫 / 治愈 / 怀旧 / 深沉 |
| 🎧 常听场景 | 学习 / 跑步 / 开车 / 睡前 / 派对 / 冥想 |
| 🌍 语言偏好 | 中文 / 英文 / 日语 / 韩语 / 纯音乐 |
| ✍️ 自由描述 | 任意文字补充 |

保存后**双写**到 Neo4j 用户节点 + GraphZep 长期记忆。

### 隐式积累

| 用户动作 | 画像影响 |
|----------|----------|
| ❤️ 点赞民谣 | 偏好 += folk |
| 🔁 反复循环 | 该歌成为最强偏好锚点 |
| ⏭️ 连续跳过电子 | skip_count ≥ 3 降权 |
| 👎 不喜欢 | 后续推荐永久过滤 |
| 💬 对话 "不爱听电子乐" | LLM 提取 → avoid_genres += electronic |

---

## 8. 系统设置

侧边栏底部 **系统设置** 打开，4 个标签页：

### 🤖 模型配置

- **部署模式切换**：☁️ API 部署（共用一个模型）/ 💻 本地部署（分别配置意图/HyDE 模型）
- **LLM 提供商**：SiliconFlow / 火山引擎 / 通义千问 / Gemini / DeepSeek / SGLang / Ollama / vLLM
- **解释生成模型**：可独立配置（负责生成推荐理由的流式文本）
- **上下文压缩模型**：可独立配置
- LLM 超时、意图分析最大输出 Token

### 🔍 检索参数

- 各引擎检索数量（图谱/向量/混合/最终输出/联网搜索）
- **粗排 & 探索**：Graph Affinity 启用/关闭、粗排保留比例、Thompson Sampling 探索度、最大跳数
- **三锚精排权重**：语义相关性(M2D-CLAP) / 声学风格(OMAR-RQ) / 个性化偏好（自动归一化）
- **多样性控制**：每歌手最多曲数、MMR λ

### 🎵 音乐数据

- 本地音乐/MTG数据集/联网获取/模型导出 目录

### 🧠 记忆系统

- 上下文保留轮数、窗口 Token 预算、用户 ID

> 所有配置修改后点击「保存设置」即时生效，关闭面板则丢弃未保存修改。支持「还原默认」一键重置。

---

## 9. 数据飞轮

整体流程为 **两步入库**：

```
发现好歌 → 点击「下载」→ 歌曲进入「待入库」暂存区
                                    ↓
        前往「待入库」页面 → 试听预览 → 勾选确认入库
                                    ↓
        自动触发：LLM 标签提取 + M2D-CLAP & OMAR-RQ 向量编码 → Neo4j 图谱写入
                                    ↓
        该歌曲立刻可被后续检索命中并播放
```

也支持在对话中说 "帮我下载这些歌" → 系统识别 `acquire_music` 意图 → 批量下载到待入库。

---

## 10. 快速上手

1. 📝 在「我的画像」设置基本偏好
2. 🗣️ 输入："今天终于完成了大项目，需要一首能让我原地起飞的歌"
3. ❤️ 满意的歌点赞、收藏
4. 👎 不喜欢的标记不喜欢
5. 🔄 多轮对话后，系统越来越懂你

**进阶玩法**：
- 🗺️ 音乐旅程：写一段 60 分钟故事体验沉浸式听歌
- 🌐 时效搜索："最近有什么新歌推荐"
- 📦 数据飞轮：发现好歌点下载，确认入库丰富曲库

---

> 🎵 开始你的 SoulTuner 音乐之旅吧！
