核心用法
Spoticlaw 是一个轻量级的 Spotify Web API 客户端，采用纯 HTTP 请求实现，无需依赖 Spotipy 等第三方库。它提供完整的音乐生态操作能力：
基础功能模块：
- 搜索 (
search): 支持曲目、艺人、专辑、播客等多类型搜索，单次最多返回10条结果 - 播放控制 (
player): 播放/暂停、切歌、音量调节、进度跳转、设备切换、播放队列管理 - 歌单管理 (
playlists): 创建、修改、删除歌单，添加/移除曲目，支持公开/私有设置 - 音乐库 (
library): 保存/移除喜欢的曲目，批量检查收藏状态 - 艺人专辑 (
artists/albums): 获取艺人详情、专辑列表及曲目 - 播客支持 (
shows/episodes): 完整的播客节目浏览与播放
认证安全设计：
采用 OAuth 2.0 授权码流程，关键安全特性包括：
- 认证令牌永不经过 AI 模型，用户在本机完成授权后手动复制
.spotify_cache文件到代理环境 - 支持自动令牌刷新（access token 1小时过期后静默续期）
- 预置10个常用 scope，覆盖播放控制、歌单管理、音乐库读写、个性化数据等场景
显著优点
1. 零依赖架构：仅用 requests 和 python-dotenv，避免 Spotipy 的复杂依赖链
2. 安全隔离设计：令牌文件物理隔离，降低凭证泄露风险
3. 完整功能覆盖：支持 Spotify Web API 绝大多数端点，包括高级功能如播放设备管理、播放模式切换（随机/循环）
4. 丰富工作流示例：文档提供10个可直接运行的复合场景，从"搜索并播放"到"批量建歌单"覆盖常见需求
5. 自动错误恢复：令牌过期自动刷新，减少人工干预
潜在局限
1. 搜索限制严格：Spotify API 强制搜索单次最多10条结果，大规模数据获取需多次分页
2. 播放前提条件：需要 Spotify 客户端处于活跃状态（手机/桌面端打开），无法独立播放
3. 认证流程繁琐：每次新环境部署需手动复制令牌文件，不适合高频自动化场景
4. 速率限制未封装：文档未提及 Spotify API 的速率限制处理，高频调用可能触发限流
5. scope 固定：auth.py 的 scope 列表硬编码，如需额外权限需修改源码
适合人群
- 需要在代理环境中安全地自动化 Spotify 操作的用户（尤其关注令牌安全）
- 希望轻量部署、不愿引入 Spotipy 重依赖的开发者
- 需要播放控制 + 歌单管理 + 播客一体化解决方案的场景
- 个人音乐自动化工作流构建者（如"每日推荐归档""听歌数据备份"）
常规风险
| 风险类别 | 说明 | 缓解建议 |
|---------|------|---------|
| 令牌泄露 | `.spotify_cache` 文件包含 refresh_token，若被窃取可导致长期账户访问 | 文件权限设为 600，避免上传至版本控制 |
| 播放干扰 | 自动化控制可能打断用户当前播放会话 | 工作流添加确认步骤，或限定设备 ID |
| API 变更 | Spotify 可能弃用端点，纯 HTTP 实现无 SDK 封装层缓冲 | 关注 Spotify Developer 公告，锁定 API 版本 |
| 隐私暴露 | `personalisation` 模块访问用户长期听歌数据 | 确保使用场景符合用户隐私预期 |
技术细节补充
- 依赖：
requests>=2.25.0,python-dotenv>=0.19.0 - Python 版本：文档未明确，推测 3.7+
- 错误处理：提供
SpotifyException基类，覆盖常见错误码（NO_ACTIVE_DEVICE、scope 不足等）