核心功能
Spotify History 是一款连接 Spotify Web API 的个人音乐数据工具，主要提供三类能力：
1. 历史回溯：获取最近播放记录（recent），支持查看约最近 50 首曲目
2. 品味分析：提取最爱艺人（top-artists）和曲目（top-tracks），支持三种时间维度——近 4 周（short_term）、近 6 个月（medium_term）、历史全部（long_term）
3. 智能推荐：基于用户 top artists 生成个性化新音乐推荐（recommend）
显著优点
- 官方 API 背书：直接调用 Spotify 官方 Web API，数据来源权威、实时性强
- 灵活时间维度：三种时间范围可精准捕捉短期探索 vs 长期偏好
- 双模式认证：支持浏览器自动跳转和纯命令行 headless 模式，服务器环境友好
- 自动化 token 管理：OAuth token 自动刷新，无需重复授权
- 权限最小化：仅申请必要 scope（recently-played、top-read、playback-state），不请求修改播放列表等敏感操作
潜在局限
- 仅限个人数据：无法获取好友或公共播放列表的聚合数据
- 推荐质量依赖算法：
recommend端点返回结果由 Spotify 算法决定，可能出现重复或偏差 - 需开发者账户：使用前必须注册 Spotify Developer App，对非技术用户门槛较高
- 网络依赖：API 调用需稳定网络，且受 Spotify 服务可用性影响
- 地域限制：部分曲目/艺人可能因版权区域不可用
适合人群
- 希望量化分析个人音乐品味的用户
- 需要基于真实听歌数据做推荐的场景（如年度总结、DJ 策划）
- 技术用户/开发者构建音乐相关的自动化工作流
- 隐私敏感用户（数据本地存储，token 文件权限 0600）
常规风险
| 风险类型 | 说明 |
|---------|------|
| Token 泄露 | 若 `~/.config/spotify-clawd/token.json` 被复制，攻击者可读取个人音乐数据，但无法操作账户（scope 只读） |
| 凭证配置错误 | Client Secret 硬编码或误提交版本控制可能导致账户被滥用 |
| 依赖失效 | Spotify 可能调整 API 端点或 rate limit，需关注官方变更 |
| 本地端口冲突 | Redirect URI 使用 127.0.0.1:8888，若端口被占用需手动调整 |