核心功能
stats.fm CLI 是一款基于 Python 的命令行工具，通过 stats.fm API 对接 Spotify 和 Apple Music 的收听数据。主要能力包括：
个人数据分析
- 查询用户画像、会员状态
- 查看播放最多的曲目、艺人、专辑、流派（支持时间范围筛选）
- 实时正在播放与近期播放记录
- 特定艺人/曲目/专辑的详细统计，含月度细分数据
- 整体流媒体统计
内容探索
- 搜索艺人、曲目、专辑并获取 ID
- 查看专辑完整曲目列表（含发行日期、厂牌、流派）
- 浏览艺人完整 discography（专辑、单曲、合集分类）
- 艺人旗下热门曲目/专辑钻取分析
全球榜单
- 全球热门曲目、艺人、专辑排行榜
显著优点
1. 零依赖部署：仅需 Python 3.6+ 标准库，无需 pip 安装
2. 灵活的时间维度：支持预设范围（今日/4周/6个月/终身）和自定义日期（精确到日）
3. 自动数据可视化：统计命令自动生成月度拆解，展示播放趋势变化
4. 优雅的降级处理：自动识别 Plus/免费用户，缺失数据标注「[Plus required]」
5. 丰富的输出格式：位置、名称、播放次数、时长多维度展示，支持专辑信息开关
6. API 无需认证：公开资料可直接查询，降低使用门槛
潜在局限
1. 数据来源单一：依赖 stats.fm 平台，该平台本身依赖 Spotify/Apple Music 的授权数据同步，存在数据延迟
2. Apple Music 支持未充分验证：文档明确标注 AM 功能「未测试，Plus 状态未知」
3. 速率限制模糊：建议「合理请求」，无明确配额说明，深度分析时可能受限
4. Plus 功能墙：核心数据（播放次数、收听时长）需付费订阅，免费版仅提供排名
5. 隐私限制：私密档案无法访问，错误提示不够精确（需用户自行判断是用户不存在还是档案私密）
6. 无持久化存储：每次查询均为实时 API 调用，无法离线分析历史快照
适合人群
- 音乐数据爱好者：希望量化分析个人收听习惯、发现长期趋势
- 年度回顾需求者：替代 Spotify Wrapped 的更灵活、更细粒度的年度总结
- 音乐博主/评论家：需要艺人 discography、专辑曲目清单、流行趋势数据
- 自我认知探索者：通过「何时开始听某艺人」「某月痴迷程度」等数据理解个人音乐旅程
常规风险
| 风险类型 | 说明 |
|---------|------|
| 隐私暴露 | 工具可查询任何公开档案，需确认用户知情并授权分享个人数据 |
| 数据准确性 | 第三方平台聚合数据，与官方 Spotify 数据可能存在差异 |
| 服务依赖 | stats.fm API 变更或关闭将直接导致工具失效 |
| 付费墙预期落差 | 免费用户查询时大量核心字段显示缺失，需提前管理预期 |
| 日期边界误差 | 自定义日期范围使用 `--end 2026` 表示「2025年全年」，逻辑需适应 |