核心用法
Spoticlaw 是专为 Nyx 代理设计的 Spotify Web API 客户端，采用纯 HTTP 请求实现，无 Spotipy 依赖。核心功能覆盖六大模块：
1. 搜索与发现 — search().query() 支持 track/artist/album/playlist/show/episode/audiobook 多类型检索
2. 播放控制 — player() 提供完整的 playback 控制：播放/暂停、切歌、音量调节、设备切换、队列管理、shuffle/repeat 模式
3. 歌单管理 — playlists() 支持创建、更新、添加/删除曲目、删除歌单；user_playlists() 获取用户歌单列表
4. 曲库操作 — library() 实现 save/remove/check 单曲功能
5. 内容获取 — tracks/artists/albums/shows/episodes 模块提供元数据查询
6. 个性化数据 — personalisation() 获取 top tracks/artists，follow() 查看关注艺人
认证安全设计 为最大亮点：OAuth 令牌在本地机器生成，通过 auth.py 完成授权流程，生成的 .spotify_cache 文件需手动复制到代理环境，AI 模型全程不接触敏感凭证。令牌自动刷新机制确保 1 小时过期后静默续期。
显著优点
- 零依赖轻量：仅依赖 requests 和 python-dotenv，无重型 SDK
- 安全隔离：令牌手动迁移设计，杜绝 AI 侧信道泄露风险
- 完整功能覆盖：从基础播放到复杂歌单编排、播客管理一应俱全
- 10 个即开即用工作流：涵盖搜歌播放、歌单创建、专辑入库、设备切换等典型场景
- 自动令牌刷新：后台静默处理，无需重复授权
潜在局限
- 手动认证步骤：首次配置需用户本地执行 auth.py 并复制令牌文件，对远程/自动化部署不够友好
- 设备依赖：播放控制需 Spotify 客户端保持活跃会话（NO_ACTIVE_DEVICE 错误常见）
- 搜索限制：单次搜索上限 10 条结果，大数据量需分页处理
- 无内置重试机制：网络异常需自行捕获 SpotifyException 处理
- 功能边界：关注艺人(follow) 需额外 scope，当前未完全实现；无歌词、无社交功能
适合人群
- 需要 AI 代理自动化 Spotify 操作的开发者
- 注重 OAuth 安全隔离的隐私敏感用户
- 希望轻量集成、不愿引入 Spotipy 复杂依赖的项目
- 播客/音乐内容管理自动化场景
常规风险
| 风险类型 | 说明 | 缓解措施 |
|---------|------|---------|
| 令牌过期 | 1 小时 access token 过期，依赖自动刷新 | 首次授权后无需干预，异常时重跑 auth.py |
| 凭证泄露 | .spotify_cache 文件权限管理不当 | 确保文件仅用户可读，避免提交版本控制 |
| 设备离线 | 播放命令因无活跃设备失败 | 预先调用 get_devices() 检查，或要求用户保持 Spotify 开启 |
| 速率限制 | Spotify API 存在未公开的速率限制 | 实现指数退避重试，避免高频批量操作 |
| 范围不足 | 操作需特定 scope 授权 | 重新运行 auth.py 申请完整 scope 列表 |