# MVP v0.1 产品规格

更新：2026-09-29。本文维护用户确认的 v0.1 产品范围与行为；当前实现进度见 [开发路线](PROJECT_PLAN.md)，补充决策见 [决策记录](DECISIONS.md)。

## 1. 目标与范围

给 DSH 中的 DeepSeek 一套可成长的音乐人格。用户近期音乐是成长环境，Agent 在本地规则、探索与经历的作用下形成自己的偏好。这里的“听歌”指音乐选择与播放进度驱动的产品状态；v0.1 不执行音频理解，不声称模型实际感知了声音。

必须交付：网易云和 QQ、自维护 Provider、近期音乐导入、独立 Agent 偏好、跨会话记忆、本地自主选歌/暂时不听、用户控制、新歌探索、真实音频播放，以及 DSH 页面内可隐藏/重新显示的音乐控制悬浮条；鲸鱼娘插画作为非交互的音乐状态视觉，随待机、听歌、切歌状态切换。

不纳入：其他音乐平台、音频/歌词深度分析、Embedding/复杂推荐模型、逐曲 LLM 评价、主动人格反思、独立桌面聊天、语音、屏幕视觉、桌宠行为（喂食、抚摸、随机台词、屏幕漫游、养成或多宠物）、云同步、周报和手机端。余额挂件仅作 UI 参考，不是运行依赖；不直接复用其中的鲸鱼美术素材。

## 2. 首次使用

连接任一支持的平台（面板内显示扫码及登录状态）→ 导入近期音乐 → 显示实际导入数量与来源 → 建立用户环境 → 本地初始化 Agent 偏好 → 开始 DSH 会话。

- 目标导入 200～500 首，默认请求 300 首；用户不必同时登录两个平台。
- 近期记录优先；无法获得时使用我喜欢、用户歌单及本插件已存在的历史。首次安装没有插件历史可用。
- 记录每首歌曲的来源。收藏和歌单不能标成“近期播放”；缺失的播放次数、日期、流派保留未知。
- 同平台按平台 ID 去重；不同平台不凭标题强行合并。
- 少于 200 首可以继续，显示真实数量；没有任何歌曲时等待用户选择歌单或搜索点歌，不凭空初始化历史。
- 网易云可从 DSH 设置面板生成登录二维码，手机确认后由面板显示登录状态并提供音乐导入；登录材料仅保存在本机加密凭据存储。当前没有经过核实的 QQ 登录端点时，面板不得声称 QQ 支持扫码。

用户环境与 Agent 偏好独立保存。初始化采用用户环境、少量有界扰动和轻微初始偏置；保存随机种子，使重启不会重塑人格。默认不调用 LLM。

## 3. 默认设置与控制语义

| 设置 | 默认值 | 含义 |
|---|---|---|
| DeepSeek Listening | ON | 允许自主选歌、自动续播及 Agent 经历更新 |
| Human Playback | ON | 允许电脑输出声音 |
| Discovery | ON | 允许从陌生候选中探索 |
| Discovery Rate | 20% | 每次自主选歌进入发现池的目标概率，可调 0%～100% |
| 工作策略 | Normal | 正常本地决策；可切 Focus |

两个开关独立，四种组合都需要有定义：

| Listening | Human Playback | 行为 |
|---|---|---|
| ON | ON | 自主选歌并输出声音 |
| ON | OFF | 自主选歌与逻辑进度继续，电脑静音；属于 Silent |
| OFF | ON | 停止自主行为；允许用户手动点播，标记为用户播放，不更新 Agent 听歌偏好 |
| OFF | OFF | 无自主听歌、无声音输出；允许操作设置和查看已有记录 |

### 用户操作

| 操作 | 行为约定 |
|---|---|
| 暂停 | 冻结当前播放/逻辑进度，禁止事件自动恢复；用户恢复或明确点歌后才解除 |
| 恢复 | 继续当前曲目；保持用户选择的静音和自主开关 |
| 下一首 | 用户明确换曲，绕过自主换歌冷却；暂停期间只改变曲目，保持暂停 |
| 指定歌曲 | 优先解析并播放指定曲目，解除暂停；不擅自取消静音或开启自主听歌 |
| 关闭自主听歌 | 当前 Agent 曲目暂停，停止自动决策与 Agent 经历更新；仍可手动播放 |
| “你自己听，我不想听” | Listening ON、Human Playback OFF；不等同暂停 |
| “今天别听歌了” | 暂停并设置到本地日期结束的自主禁止；到期只解除限制，等待下一安全节点或用户主动恢复 |
| “你自己选” | 解除用户暂停、开启自主听歌；保留其他明确禁播约束和静音设置 |

明确点歌与已有禁播约束冲突时，告知冲突并要求用户明确是否允许本次例外；不能悄悄删除约束。歌曲不唯一时展示候选；无权限或解析失败时给出实际失败原因，不把另一首当成点播成功。

Normal、Focus、Silent、Off 是快捷操作，不增加一套互相冲突的播放状态：Normal/Focus 启用自主听歌并设置工作策略，保留声音设置；Focus 减少中途主动动作，曲终仍可续播。Silent 设置 ON/OFF。Off 暂停并关闭两个开关；重新启用默认保持静音，用户可以主动打开声音。

## 4. 自主选择与成长

音乐决策只在内部安全事件评估，不逐轮询问模型。当前曲目可正常结束；单次测试失败或工作状态抖动不触发换曲。用户暂停、禁播约束和关闭自主听歌优先于所有自动事件。

先过滤禁止曲目和已知不可播放曲目，再按探索率选择熟悉池/发现池，最后按 Agent 偏好、用户环境、工作上下文、新鲜度、随机项和重复惩罚评分。发现池无可用歌曲时回退熟悉池，保留设置值并记录实际回退。100% 是探索尝试目标，不保证平台始终有新歌。

用户的收藏、导入或评价不能直接覆盖 Agent 偏好。用户禁播是行为约束；用户说“喜欢这首”是反馈；Agent 自主选择是事件，三者分开存储。

完成有效进度可有限更新 Agent 偏好；暂停、失败、瞬间切换不算完整听歌。静音经历与用户实际听到的播放分别计数；用户跳过不自动等于 Agent 讨厌，平台失败也不算负面偏好。临时 Session 权重只少量沉淀至长期偏好，并设上限、重复惩罚与衰减，避免“选中就加分”的自我强化。

偏好的差异需要在受控数据和可复现轨迹中验证；真实用户长期使用是否形成明显差异，不能仅凭初始化随机扰动宣布成功。

## 5. 桌面体验

DSH 主界面提供“肥鱼电台”侧栏入口，打开内嵌音乐设置面板；DSH 设置窗口提供同名页面。两处使用同一个 Core 状态与命令入口。面板包含自主听歌、声音输出、探索开关与探索率、四种快捷模式、暂停/继续/下一首/今天停止，以及平台实际连接状态。开关与模式即时保存；探索率明确点击保存。日常、专注和静听模式是开始听歌的快捷操作，关闭模式保持暂停。未配置平台时仍可保存设置，不显示虚假登录或播放成功。保存失败、服务断开时明确提示并允许重试；关闭面板不停止 Core。

音乐控制 UI 位于 DSH 的 `shell.overlay` 浮层槽位，不创建独立桌面窗口或宠物进程。页面右下角的状态条显示曲名、艺人和播放状态；点击展开暂停/继续/下一首，三点菜单提供快捷模式和完整设置入口。用户可隐藏、重新显示、拖动并吸附到左右边缘；进入肥鱼电台主面板时收起，离开后按已保存偏好恢复。可见状态使用本项目已有鲸鱼娘图，对应待机、播放和选歌姿态，不加入喂食、抚摸、随机台词或宠物状态机。布局参考 [DeepSeek Balance Whale Widget](https://github.com/MeteorNOX/DeepSeek-Balance-Whale-Widget)，设置卡和手势关闭参考 [dsh-api-dashboard](https://github.com/133563825as-ai/dsh-api-dashboard)。FishFM 只适配其中获 MIT 授权的 SwipeHandle 逻辑，并记录在 [第三方声明](../THIRD_PARTY_NOTICES.md)；余额挂件 `assets/**` 不在 MIT 范围，不复用其美术素材。

悬浮条和设置页都走同一宿主认证 RPC、同一 Core，不承载音频。隐藏控件或切换 DSH 页面不会停止播放；关闭整个插件则停止其播放和后台服务，DSH 继续工作。悬浮条位置保存在本机视口坐标并在窗口缩放时限制于可见范围；此功能不涉及多屏 DPI 映射或透明原生窗。

## 6. 验收清单

2026-10-02 网易云首条真实闭环见 [P3](spikes/P3-real-loop.md)：导入后可开始听歌或选择库内曲目点播；下一首优先消费队列，无队列时从本地候选选择并排除当前曲目，暂停期间换曲仍暂停。返回数量不足与备用来源分别提示。QQ 和完整双平台 A01 仍未通过。

扫码只有在返回账号凭据并成功校验账号 ID 后才显示已连接；游客 Cookie 和未知检测码不能算授权。检测失败与二维码过期分开显示，临时失败可用同 key 重试一次，超过后由用户重试。新尝试校验失败不得覆盖旧凭据。实测见 [U6](spikes/U6-qr-login-repair.md)；不等于双平台 A01 通过。

验收状态以 [开发路线](PROJECT_PLAN.md) 为准；文档存在不等于验收通过。A07 在官方桌面 rc.2 的局部实测见 [U5](spikes/U5-official-desktop.md)，未播放歌曲，不把 Core 保留等同于音频连续性通过。

| ID | 可观察结果 | 证据 |
|---|---|---|
| A01 | 两个平台各自完成登录、搜索、真实播放、暂停、恢复、下一首 | 版本、操作记录、脱敏日志与播放核对 |
| A02 | 可导入目标数量；数量不足、收藏/歌单降级和空结果均如实展示 | 导入统计及来源样例 |
| A03 | 两个开关四种组合、四个模式、暂停保持和到期约束符合第 3 节 | 状态迁移验证 |
| A04 | 用户点歌/下一首优先；禁播、暂停不会被自动事件覆盖 | 含慢请求、重复事件、命令冲突的轨迹 |
| A05 | 熟悉池、探索率 0/20/100%、候选为空和重复惩罚有效 | 固定随机种子的选择结果 |
| A06 | 用户环境与 Agent 偏好分离，重启后保留；Session 不覆盖长期偏好 | 数据前后对照、受控成长轨迹 |
| A07 | DSH 主界面及设置窗口可打开音乐设置，修改可持久化，连接失败如实提示；DSH 页面内音乐悬浮条可拖动、吸附、隐藏和重新显示，播放状态同步；切换面板或隐藏悬浮条不停止 Core/Playback | 主界面交互、浏览器视口与设置读回证据、Core 状态对照 |
| A08 | 多 Session 不抢占播放；插件退出停止音乐，DSH 正常工作 | 并发会话、卸载和异常场景记录 |
| A09 | 连续两小时自动听歌，用户未主动聊音乐，新增 LLM 请求数为 0 | 请求计数、工具注册/上下文注入检查与脱敏运行日志 |
| A10 | 静音、暂停、播放失败、进程重启不会伪增听歌次数或偏好 | 历史数据与进度对照 |

日常音乐状态不得持续注入主 Agent 上下文。新增 LLM 请求为 0 不等于插件工具描述绝无 token 开销；验证时应单独记录静态工具描述是否存在及其影响。