概述
Spoticlaw 是一个专为 Nyx Agent 设计的 Spotify Web API 客户端，采用纯 HTTP 请求实现，完全摆脱对 Spotipy 库的依赖。其核心定位是为 AI Agent 提供音乐服务的程序化控制能力，涵盖搜索、播放、歌单管理、曲库操作及个人化推荐等完整功能链。
核心用法
该技能采用模块化设计，提供 12+ 个独立功能模块（primitives）：
- 搜索模块：支持 track/artist/album/playlist/show/episode/audiobook 多类型检索
- 播放控制：播放/暂停/切歌/音量调节/进度跳转/设备切换/队列管理
- 歌单操作：创建、更新、删除歌单，添加/移除曲目，获取详情
- 曲库管理：保存/移除/检查收藏状态
- 个性化数据：获取 Top 艺人/歌曲、最近播放记录
典型工作流包括：搜索歌曲并播放、基于搜索结果创建歌单、播客播放、跨设备传输播放等 10 余种复合场景。
显著优点
1. 零重型依赖：仅依赖 requests 和 python-dotenv，大幅降低环境冲突风险
2. 安全认证设计：OAuth Token 完全本地生成，通过文件复制方式传入 Agent，Token 永不经过 AI 模型
3. Token 自动刷新：内置 refresh_token 机制，在环境变量匹配时可自动续期
4. 完整功能覆盖：对标官方 Web API 的全量能力，非阉割版 SDK
5. 设备无关播放：支持跨设备控制（手机/电脑/智能音箱）
潜在局限
- 搜索硬性限制：单次最多返回 10 条结果（Spotify API 限制），大数据量需多次分页
- 设备依赖：播放控制要求目标设备 Spotify 应用处于活跃状态
- 认证流程繁琐：首次配置需本地运行 auth.py，手动复制 token 文件到 Agent 环境
- Scope 预申请：所有权限需预先在 auth.py 中申请，无法动态增量授权
- 无实时推送：依赖轮询获取播放状态，非 WebSocket 实时通知
适合人群
- 需要自动化 Spotify 操作的高级用户
- 希望集成音乐服务到 Agent 工作流的技术团队
- 对 Spotipy 体积/依赖敏感的场景（边缘设备、容器化环境）
- 重视 Token 安全隔离（AI 不可见）的安全敏感场景
常规风险
- 凭证泄露风险：.spotify_cache 文件包含有效 Token，需严格隔离环境
- 权限过度授予：默认申请 10 项 Scope，建议按最小权限原则调整
- 账户操作不可逆：删除歌单、移除收藏等操作无二次确认
- API 限流：高频调用可能触发 Spotify 速率限制
- 地域内容差异：搜索结果和可用性因账户区域而异