核心用法
statsfm CLI 是一个基于 stats.fm API 的 Python 命令行工具，专精于 Spotify 播放数据分析。工具分为两大功能模块：公开数据查询（无需账号）和个人数据深度分析（需 stats.fm 账号）。
基础功能（免登录）
- 专辑曲目列表、艺人 discography、全球榜单查询
- 艺人/曲目/专辑搜索及元数据获取
个人数据功能（需 --user）
- 播放历史统计：top 艺人/曲目/专辑/流派
- 实时播放状态（now-playing）与最近播放
- 精细化统计：特定艺人/曲目/专辑的月度播放 breakdown
- 自定义时间范围：支持年/月/日级别的精确查询
显著优点
1. 零依赖部署：纯 Python 3.6+ 标准库实现，无需 pip 安装
2. 数据颗粒度精细：月度/周级 breakdown，可识别「发现艺人」的具体时间点
3. 时间范围灵活：支持预设周期（今日/4周/6个月/终身）和自定义日期
4. 数据故事化：自动计算总播放时长，输出格式便于发现「月度爆发」「持续收听」等行为模式
5. 免费/Plus 兼容：优雅处理权限差异，免费用户仍可获取排名和月度分布
潜在局限与风险
- 数据来源单一：仅覆盖 Spotify（Apple Music 支持未验证），无法整合多平台数据
- 隐私敏感性：直接访问他人用户名即可获取公开档案，但个人详细数据需账号授权
- API 稳定性：非官方 Spotify API，stats.fm 服务变更可能影响功能
- 速率限制：建议单次会话不超过 10 次连续调用
- Plus 功能门槛：播放次数、收听时长等核心指标需付费订阅
适合人群
- 重度 Spotify 用户希望量化自己的音乐习惯
- 音乐博主/创作者追踪听众参与度数据
- 数据爱好者进行个人媒体消费分析
- AI 助手为用户提供「音乐人格」洞察和记忆锚点
常规风险提示
- 个人播放历史属于敏感数据，存储和分享需谨慎
- 工具输出包含时间戳信息，可能泄露作息规律
- 长期数据归档建议本地导出，避免依赖第三方 API 持久性