stats.fm CLI：你的 Spotify 音乐数据分析师
核心用法
这是一个纯 Python 编写的命令行工具，仅需 Python 3.6+ 环境（零依赖，无需 pip 安装），通过 stats.fm API 获取音乐数据。无需账号即可使用公开功能：专辑曲目查询、艺人 discography、全局榜单、搜索功能。绑定 stats.fm 账号后，可解锁个人听歌数据：播放历史、播放次数、TOP 艺人/曲目/专辑、月度细分统计、正在播放等。
所有个人数据命令需通过 --user USERNAME 指定用户名，支持灵活的时间范围（预定义：今日/近4周/近6个月/全部时间；自定义：年/月/日级别起止日期），并可配合 --limit 控制输出数量。
显著优点
1. 零依赖部署：单脚本运行，无 pip 安装烦恼，适合快速上手和自动化场景
2. 数据维度丰富：从宏观趋势（TOP 榜单、流派分布）到微观追踪（单曲目/艺人/专辑的月度播放走势），满足深度分析需求
3. 时间分析灵活：支持自定义日期切片，轻松实现「2025年全年」「去年夏天」「Q1季度」等个性化查询
4. 智能降级处理：自动识别免费/Plus 用户，对缺失数据优雅显示「[Plus required]」，不中断流程
5. 叙事导向设计：针对 AI 助手提供专门的「数据叙事」指南，强调从数字中挖掘故事（如发现艺人、识别听歌习惯变迁）
潜在局限
1. 平台锁定：核心功能依赖 Spotify 数据，Apple Music 支持未经验证
2. 数据完整性限制：免费用户无法查看具体播放次数和收听时长，仅能获取排名信息
3. API 限制：官方建议避免短时间内超过 ~10 次请求，深度查询需控制节奏
4. 隐私依赖：个人数据要求 stats.fm 账号且资料设为公开，私密用户无法查询
5. ID 操作门槛：部分命令需数字 ID，需先通过 search 获取，增加一步交互成本
适合人群
- 数据好奇型听众：想量化自己的听歌习惯、发现长期音乐趋势变化
- 音乐博主/分析师：需要客观数据支撑艺人热度分析、专辑回顾文章
- 自动化爱好者：希望将听歌数据集成到个人工作流、生成定期报告
- 怀旧型用户：通过时间切片功能回顾特定时期的音乐记忆
常规风险
| 风险类型 | 说明 | 缓解建议 |
|---------|------|---------|
| 隐私泄露 | 查询他人用户名可获取其公开听歌数据 | 确保自身资料隐私设置符合预期 |
| 速率限制 | 高频请求可能触发 API 限流 | 批量查询时添加间隔，遵循 ~10req 建议 |
| 数据误读 | 月度细分数据免费用户通过「单日统计」间接计算，可能存在精度损失 | 关键分析建议结合 Plus 订阅获取原始数据 |
| 平台依赖 | stats.fm 服务可用性直接影响工具功能 | 重要数据定期本地备份（支持重定向输出到文件）|