mygod 音乐中枢

触发：用户输入关键词，并指定内容来源（默认首个在线曲库）与结果类型。

处理规则

按来源各自检索，来源间不做合并去重；结果按来源计数分页返回；分页偏移量对多来源按整页对齐。

结果

返回该页条目，每条带可播状态、时长、艺人、专辑；专辑与歌单结果额外带条目数。

状态变化

检索本身不改变播放状态；若当前有播放，快照保持不变。

异常

未登录导致该来源不可用：返回空页并说明需要登录；某来源超时：返回其余来源结果，不整体失败。

触发：用户点开艺人、专辑、歌单或用户主页。

处理规则

艺人页提供热门曲目与专辑列表切换；专辑／歌单页返回完整曲目，单次最多 1000 条；除主来源外，其余来源只保证专辑与歌单。

结果

页面含名称、封面、简介与曲目集合；曲目集合可直接作为播放队列来源。

异常

资源已下架：返回明确的不可用提示，不返回半截列表。

触发：调用方持有一组曲目编号，需要补齐名称、时长与可播状态。

处理规则

按传入顺序返回，逐条判定可播性；任一编号失效不影响其余条目。

结果

返回顺序与输入一致的曲目列表，缺失条目以不可用标注。

触发：接入端首次连接，或用户想确认当前可用能力。

处理规则

逐来源报告登录状态；未登录来源给出"游客可用范围"说明；已登录来源附带账号资料。

结果

调用方据此决定后续动作：可直接播放、需要登录，或该来源当前不可用。

触发：用户指定曲目集合、歌单、专辑或电台中的恰好一种，并可指定从第几条开始。

处理规则

四种来源互斥，一次只能指定一种；指定起始位置时，队列保留完整集合，从该位置开始播；心跳式电台允许同时附带其歌曲来源的歌单编号。

结果

新队列覆盖旧队列并立即进入加载；返回建立后快照。

状态变化

状态由空闲／暂停变为加载，再变为播放；失败的条目按 6.1 跳过。

异常

一次指定多种来源：拒绝并说明只能指定一种；本机无音频输出：明确提示可在无输出设备的环境下不可播。

触发：用户执行暂停、继续、上一首、下一首、跳转到指定条目、跳转到指定时间点或设置音量。

处理规则

跳转时间点在已加载范围内即时生效；超出范围的跳转以可播边界为准；音量取值 0–100，跨接入端共享同一音量。

结果

返回操作完成后的快照，调用方无需再次查询。

状态变化

暂停与继续在同一队列位置往返；切歌重置进度为 0 并重新进入加载。

异常

队列为空时所有控制返回空操作提示，不报错、不崩溃。

处理规则

循环三档：关闭（播完队列末条即停）、列表（末条回到首条）、单曲（当前曲目重复）。随机为独立开关，与循环叠加生效：随机顺序在队列建立时确定并保持，不回退到未随机前的顺序。

持久化

循环与随机随会话落盘，重启后保持上次选择。

触发：任意接入端请求当前播放状态，可重复轮询。

结果字段

状态（空闲／加载／播放／暂停／停止）、当前曲目及其来源与可播标记、进度与总时长、当前歌词行、队列与当前序号、电台名、音量、随机、循环、音效开关、错误说明。

处理规则

进度随时间自行推进，每次读取都是最新值；加载中的曲目进度停在起点并置为加载状态；出错但未跳过时错误说明随快照返回。

触发：队列播完，或用户给出"不喜欢"。

处理规则

电台模式下队列耗尽时，按模式补充新曲目并继续；补充时过滤掉当前不可播的曲目，避免插队即卡。

结果

队列自动延长，播放不中断；"不喜欢"记录到该来源的偏好，并影响后续挑选。

异常

补充连续失败：保持当前队列并置为停止，附错误说明，不进入无限重试。

队列条目各自携带来源，同一队列内可同时包含多个在线来源与本地库曲目；某一条目不可播时，仅跳过该条目，不改变其余条目的顺序。

处理规则

提供时间轴歌词、翻译歌词与逐字歌词；调用方可任选其一或全部；本地曲目优先读取同目录同名歌词文件。

结果

快照同时给出"当前歌词行"，供接入端直接展示；无歌词时返回空而不报错。

异常

来源暂无该曲目歌词：返回空集合，不编造内容。

处理规则

首屏按热度排序，其后按时间排序；可按曲目、节目、歌单或话题检索；分页返回。

异常

目标无评论：返回空页并给出零计数。

未满足前置条件的卡片返回空集合并说明原因，不隐藏入口。

档位

默认（按整体口味）、熟悉（贴近常听）、探索（扩大尝试范围）。

规则

一次返回若干曲目，作为队列或续播补充；连续两次拿不到可播曲目时停止补充并说明。

以用户收藏歌单为种子、以当前曲目为起点生成连续曲目；种子歌单编号随会话保存，重启后仍可续播。

当前版本对收藏与歌单写入返回"尚未开放"的明确说明；读取路径已具备，写入将在后续版本提供。

档位

标准、较高、极高、无损，按来源实际提供的最高档向下兼容。

规则

请求档位高于来源能力时自动降到该来源最高档；本地曲目按文件本身规格播放，不做转码。

结果

快照显示实际生效档位，调用方可判断是否降级。

音效偏好随会话保存，切换曲目与重启后保持；任一音效关闭时，对应处理立即停止而不影响播放连续性。

触发：用户把某个绝对路径目录交给中枢，或要求移除、查看、重扫。

处理规则

登记后立即遍历该目录；仅收录受支持的音频文件；同一目录重复登记视为重扫；移除时连同其曲目一并从索引清除。

结果

返回登记后的曲目总数与目录清单（含每个目录当前贡献的曲目数）。

状态变化

索引写入本机；此后该来源的检索立即可命中。

异常

路径不存在或不可读：拒绝登记并说明；目录内个别文件读取失败：跳过该文件，不中断整体扫描；单目录无权限：跳过该目录，其余继续。

增量规则

重扫时以文件大小与修改时间判定是否变化；未变化的文件跳过元数据读取，只保留原条目。

删除规则

重扫后不再存在的文件，其条目从索引移除，检索不再命中。

结果

一次重扫完成后返回最终曲目数，调用方可直接用于校验。

检索规则

在曲名、艺人、专辑与文件路径上做子串匹配，大小写不敏感；曲名命中的排序优先于只在路径命中。

播放规则

直接读取本机文件播放，不复制、不转码、不发起网络请求；同目录同名歌词文件自动加载。

异常

播放期间文件被移动或删除：本次播放按 6.1 失败处理，队列继续前进。

两种形态共用同一套能力定义与同一份播放会话，行为一致，不出现"命令行能播、助手不能播"的差异。

背景：多个助手或终端可能同时连接，若各自启动播放器，会出现两路音频互相覆盖、队列互相清空。

处理规则

本机只允许一个进程持有播放引擎；后到者以客户端身份接入同一引擎，读写同一会话。

结果

任一端播放，其他端立即看到同一快照；不存在两个队列、两个音量。

异常

持有引擎的一方异常退出：下一次接入自动重新建立引擎，并从落盘会话恢复。

登录方式

扫码登录：先取二维码内容与轮询标识，再轮询登录进度，确认后会话保存到本机。

状态语义

过期 / 等待扫码 / 已扫码待确认 / 已确认，四种状态可区分。

游客模式

不登录也能使用部分来源的检索与播放；受限能力在检索阶段即标注，不等到播放才失败。

异常

会话过期：相关调用返回"需要重新登录"并指明下一步动作。

规则

在线曲目边取流边播放，同时写入本机缓存；完整取回后保留，下次直接播放。

容量

缓存设总容量上限，超出时按最近播放时间由远及近淘汰；超过上限四分之一的单曲不入缓存。

隐私

缓存仅存于本机；本地库文件不复制进缓存。

异常

磁盘写入失败：本次播放改为纯内存进行，播放不中断，仅失去缓存收益。

落盘时机

播放状态发生变化后延迟数秒合并写入，避免频繁写盘；退出时再写一次。

恢复结果

下次启动按上次的队列、序号、循环、随机、音量、电台与种子歌单恢复，处于暂停状态，等待用户继续。

异常

恢复时某曲目已不可用：该条目标记为不可播，播放时自动跳过，不影响其余曲目。

停止播放保留队列与序号，仅结束发声；清空队列后快照回到空闲。用户主动清理缓存不影响队列与索引。