核心用法
spotify-history 是一款连接 Spotify Web API 的个人音乐数据助手，主要提供三类核心功能：一是获取用户最近播放记录（recent），支持查看近50首播放历史；二是分析音乐品味偏好，可查询不同时间维度（近4周/6个月/全部时间）的热门艺术家（top-artists）和热门曲目（top-tracks）；三是基于用户历史生成个性化音乐推荐（recommend）。使用方式灵活，既支持命令行直接调用，也可作为 Agent 技能集成到对话系统中，让 AI 助手根据用户听歌习惯主动推荐相似艺人。
显著优点
该技能的最大亮点在于极致的轻量与安全设计。全程仅依赖 Python 标准库（http.server、urllib、json 等），完全规避了第三方 PyPI 包的供应链攻击风险。OAuth 2.0 认证流程设计规范，采用本地 127.0.0.1 回调服务器，确保授权码不经过任何中间服务器。权限控制严格遵循最小化原则，仅申请 4 项只读权限（user-read-recently-played、user-top-read 等），不涉及播放控制或用户隐私数据修改。凭证存储采用 Unix 600 权限（仅所有者可读写），且支持环境变量与文件双模式配置，兼顾安全性与灵活性。此外，Token 自动刷新机制完善，用户一次授权后可长期免维护使用。
潜在缺点与局限性
作为社区开发的非官方工具，该技能缺乏 Spotify 官方背书，未来若 Spotify API 政策变更（如权限收紧、端点废弃），维护响应存在不确定性。功能层面目前仅覆盖读取类操作，无法实现播放控制、歌单创建等进阶功能。推荐算法完全依赖 Spotify 官方接口，缺乏自定义权重或跨平台数据融合能力。对于无浏览器环境的 headless 服务器，虽然支持 --headless 模式，但需手动复制粘贴回调 URL，体验略繁琐。此外，Refresh Token 长期有效虽便利，但一旦设备丢失且未及时撤销，存在凭证泄露后的持续访问风险。
适合的目标群体
该技能特别适合三类用户：音乐数据爱好者，希望量化分析自己的听歌习惯与品味演变；AI 助手重度用户，期望在对话中自然获取音乐推荐而无需切换应用；隐私敏感型用户，追求数据本地化处理、拒绝第三方数据聚合服务。开发者群体亦可将其作为 Spotify API 集成的参考实现，学习标准库级别的 OAuth 流程设计。
使用风险与注意事项
常规风险主要包括：OAuth 凭证（Client Secret）需用户自行保管，若误提交至代码仓库或共享设备可能导致账户被冒用；Token 文件虽受权限保护，但 root 用户或物理接触仍可读取，建议配合磁盘加密使用；长期运行的 headless 环境若未妥善保管 refresh token，存在被恶意脚本利用的潜在窗口。性能方面，纯标准库实现虽安全但效率略低于专业 HTTP 库，高频调用时建议添加本地缓存层。