核心用法
statsfm 是一款基于 Python 的命令行工具，对接 stats.fm API（Spotify/Apple Music 第三方数据分析平台），提供个人音乐消费数据的全维度查询。用户通过 --user USERNAME 指定账号后，可执行：
- 个人榜单：top-tracks/artists/albums/genres，支持 today/weeks/months/lifetime 预定义时间范围及自定义起止日期
- 实时活动：now-playing、recent 播放历史
- 深度统计：artist/track/album-stats 带自动月度细分（plays + 时长）
- 内容检索：search 获取 ID，album/artist-albums 查看曲目列表与 discography
- 全球榜单：charts-top-tracks/artists/albums
脚本纯标准库实现，Python 3.6+ 无需 pip 安装，输出含排名、播放次数、收听时长、流派标签及 [E] 显式内容标记。
显著优点
1. 零依赖轻量：单文件脚本，无外部包，开箱即用
2. 时间粒度灵活：支持从单日到跨年自定义区间，自动生成本月/年度对比
3. 数据叙事导向：月度拆解能识别「发现月」「沉迷期」「突然冷却」等 listening pattern
4. Plus/Free 兼容：免费用户可获取排名与月度拆解，Plus 用户解锁具体播放次数与时长
5. ID 工作流：search → ID → 任意深度查询，支持链式探索
潜在缺点与局限
- 平台局限：Spotify 支持完善，Apple Music 标注为「未测试」，可能存在数据缺口
- 隐私门槛：仅支持公开档案查询，私密用户无法获取数据
- 功能分层：核心指标（播放次数、时长）需 stats.fm Plus 订阅（约 €3.99/年）
- 速率限制：文档建议避免短时间内 >10 次请求，深度挖掘需节制
- 无导出格式：仅 CLI 文本输出，无 JSON/CSV 原生导出（需手动重定向）
适合人群
- 希望量化自我音乐消费习惯的数据爱好者
- 需要跨年/跨月收听趋势分析的重度 Spotify 用户
- 想追踪特定艺人「入坑时间线」的音乐粉丝
- 对比个人口味与全球榜单的流行趋势观察者
常规风险
| 风险类型 | 说明 |
|---------|------|
| 隐私暴露 | 工具可查询任何公开档案，需确保 `--user` 参数不泄露他人敏感信息 |
| 第三方依赖 | stats.fm 为第三方服务，API 稳定性与数据保留政策不受 Spotify 官方保障 |
| 订阅诱导 | 多处功能标注 `[Plus required]`，免费用户可能产生付费冲动 |
| 数据幻觉 | 月度拆解基于 API 聚合，可能存在时区或跨设备同步延迟导致的统计误差 |
| 自动化滥用 | 脚本无内置速率限制，频繁请求可能导致 IP 临时封禁 |