核心用法
spotify-claw 是一款面向 macOS 用户的 Spotify Premium 命令行控制工具，基于 spotipy 库构建。用户需先在 Spotify 开发者后台创建应用并配置回调 URI，随后将 Client ID 与 Secret 存入 macOS Keychain 实现安全认证。
主要功能模块：
- 播放控制：play/pause/next/prev、音量调节、随机播放开关、队列管理，支持自动启动 Spotify 客户端
- 搜索播放：按曲目名、URI 或歌单 ID 精确播放
- 数据分析：导出个人 top tracks/artists、最近播放、喜欢歌曲、多周期（4周/6月/全部）流派画像
- 智能发现：基于
related_artists+artist_top_tracks绕过被禁用的 Recommendations API，实现相似艺人追踪与深度探索 - 歌单构建：一键创建歌单、按艺人筛选喜欢歌曲、链式命令构建主题播放列表
典型工作流示例：
# 发现相似艺人 → 获取热门曲目 → 加入新歌单 python3 ~/.openclaw/scripts/spotify.py related-artists "The Cure" 10 python3 ~/.openclaw/scripts/spotify.py artist-top-tracks "New Order" 5 python3 ~/.openclaw/scripts/spotify.py add-to-playlist PLAYLIST_ID <URI>
显著优点
1. 绕过 API 限制：因 Spotify 对新开发者应用封禁了 recommendations 与 audio_features API，本工具采用 related_artists 组合策略，确保发现功能可用
2. 原生 macOS 集成：凭据存储于系统 Keychain，符合平台安全最佳实践
3. 零配置持久化：首次认证后令牌自动刷新，无需重复登录
4. 俄语触发词支持：内置俄语指令识别（включи, пауза, что играет 等），扩展多语言场景
潜在缺点与局限性
- Premium 强制依赖：所有功能需 Spotify Premium 订阅，免费用户无法使用
- macOS 独占：Keychain 认证机制与脚本路径设计限制为 macOS 平台
- 手动 OAuth 初始化：首次配置需浏览器交互，无法纯 CLI 完成
- 无实时音频分析：因 API 限制，无法提供 BPM、能量值等音频特征数据
- 歌单 ID 依赖：添加歌曲需预先获取歌单 ID，交互步骤较多
适合人群
- 习惯终端工作流、追求效率的 macOS Spotify Premium 用户
- 需要批量分析个人听歌数据、生成定期 taste report 的音乐爱好者
- 希望自动化歌单管理、构建主题曲库的策展型用户
- 俄语环境下的多语言交互需求者
常规风险
| 风险类别 | 说明 |
|---------|------|
| 凭据安全 | Client Secret 存于 Keychain 属较安全方案，但仍需防范 `security` 命令历史泄露 |
| API 速率限制 | 频繁调用可能触发 Spotify Web API 限流（429 错误） |
| 令牌有效期 | 长期未使用需重新认证，自动化场景需关注刷新机制 |
| 依赖维护 | `spotipy` 库更新滞后可能导致 API 变动兼容性风险 |
安全等级说明
本工具采用 OAuth 2.0 标准授权流程，凭据本地加密存储，无服务端中转。但脚本执行具备 Spotify 账户完整读写权限，需注意运行环境可信性。