播放体验、版权边界和个性化需要一起设计。
项目需要同时面对桌面与移动端布局、本地文件与在线来源、播放状态持久化、试听与下载许可，以及冷启动阶段推荐数据不足等问题。
Problem
传统单窗口播放器难以适配多平台；简单“猜你喜欢”又常依赖账号和云端画像，推荐原因不可见。在线音乐来源还必须明确试听、缓存与永久下载的许可边界。
Software · AIFlutterLocal-firstExplainable
让音乐播放器理解偏好，但不拿走用户的数据。
Resonance Music 是从旧 Qt Widgets 播放器整体重构而来的 Flutter 跨平台应用，覆盖本地音乐、合规在线试听、授权下载、设备端行为记录与可解释推荐。
Requirements
核心要求不是“功能多”，而是跨平台后仍保持可理解。
自适应界面
手机使用底部导航，桌面使用侧边导航，覆盖窄屏、横屏、平板与桌面宽度。
统一播放链路
本地文件、iTunes Preview 与 Internet Archive 共享播放控制、进度、循环和音量状态。
可解释推荐
行为达到明确阈值后才启用个性化，并向用户展示贡献最大的偏好标签。
Architecture
界面、用例、领域模型与数据来源分层。
播放、媒体来源和推荐逻辑由端口隔离，便于跨平台测试与替换实现。
01 · UIAdaptive Shell
页面、导航、主题与播放器组件。
02 · APPAppController
协调搜索、播放、收藏与推荐用例。
03 · DOMAINSong & Behavior
歌曲标签、事件、偏好向量与排序规则。
04 · DATASources
本地文件、公开搜索与授权媒体适配器。
05 · DEVICEPersistence
收藏、历史、缓存与设备端偏好。
Technical decisions
关键决策围绕隐私、许可和推荐可解释性。
Flutter 重构
用单一界面层覆盖四个平台，同时保留平台相关文件选择、存储和播放能力。
来源适配器
歌曲海只解析公开元数据；实际播放严格匹配 iTunes Preview 或 Internet Archive。
阈值后个性化
至少 8 个有效行为且置信度达到 6.0 后才启用个性化，避免少量点击过早定型。
时间衰减
行为按 45 天半衰期衰减，并加入新鲜度、重复惩罚和艺术家多样性。
Challenges & solutions
跨平台并不只是“能编译”。
| 挑战 | 解决方式 | 验证重点 |
|---|---|---|
| 宽度与输入方式差异 | 自适应壳层、44×44 最小触控目标、键盘焦点与读屏语义 | 375–1440+、横竖屏、系统字体与 reduced motion |
| 在线来源许可不一致 | 元数据搜索与媒体播放解耦，永久下载仅限开放许可证 | 来源标识、播放匹配与下载条件 |
| 推荐冷启动与偏见 | 阈值前使用新鲜度和多样性，阈值后再使用标签偏好 | 重置、重复惩罚与推荐原因可读性 |
Results
仓库已经形成可运行、可测试的跨平台主链路。
4 平台Windows、Ubuntu、iOS 与 Android 构建目标
17 项测试当前 README 记录的 Windows 验收测试全部通过
本地优先行为、偏好、收藏与路径默认不上传
当前边界：iTunes 仅提供约 30 秒试听；Internet Archive 元数据质量不一致；后台播放、跨设备同步和批量下载队列尚未纳入当前验收范围。
Screenshots
多图展示位已准备好。
以下为明确的素材槽，不代表真实产品界面。补图后只需替换对应图片路径与 alt。
1 / 3
可使用按钮、分页圆点或键盘左右方向键切换。