介绍
# Spotify History & Recommendations
访问 Spotify 收听历史记录并获取个性化推荐。
## 设置（一次性）
### 快速设置（推荐）
运行设置向导： ```bash bash skills/spotify-history/scripts/setup.sh ```
这将引导您完成： 1. 创建 Spotify 开发者应用 2. 安全地保存凭据 3. 授权访问
### 手动设置
1. **创建 Spotify 开发者应用** - 访问 [developer.spotify.com/dashboard](https://developer.spotify.com/dashboard) - 点击 **Create App** - 填写： - **App name:** `Clawd`（或任意名称） - **App description:** `Personal assistant integration` - **Redirect URI:** `http://127.0.0.1:8888/callback` ⚠️ 请使用完全一致的 URL！ - 保存并复制 **Client ID** 和 **Client Secret**
2. **存储凭据**
**选项 A：凭据文件（推荐）** ```bash mkdir -p credentials cat > credentials/spotify.json <<EOF { "client_id": "your_client_id", "client_secret": "your_client_secret" } EOF chmod 600 credentials/spotify.json ```
**选项 B：环境变量** ```bash # Add to ~/.zshrc or ~/.bashrc export SPOTIFY_CLIENT_ID="your_client_id" export SPOTIFY_CLIENT_SECRET="your_client_secret" ```
3. **身份验证**
**使用浏览器（本地机器）：** ```bash python3 scripts/spotify-auth.py ```
**无头模式（无浏览器）：** ```bash python3 scripts/spotify-auth.py --headless ``` 按照提示通过 URL 进行授权，并粘贴回调地址。
Token 将保存到 `~/.config/spotify-clawd/token.json` 并在过期时自动刷新。
## 使用方法
### 命令行
```bash # Recent listening history python3 scripts/spotify-api.py recent
# Top artists (time_range: short_term, medium_term, long_term) python3 scripts/spotify-api.py top-artists medium_term
# Top tracks python3 scripts/spotify-api.py top-tracks medium_term
# Get recommendations based on your top artists python3 scripts/spotify-api.py recommend
# Raw API call (any endpoint) python3 scripts/spotify-api.py json /me python3 scripts/spotify-api.py json /me/player/recently-played ```
### 时间范围
- `short_term` — 大约最近 4 周 - `medium_term` — 大约最近 6 个月（默认） - `long_term` — 所有时间
### 示例输出
``` Top Artists (medium_term): 1. Hans Zimmer [soundtrack, score] 2. John Williams [soundtrack, score] 3. Michael Giacchino [soundtrack, score] 4. Max Richter [ambient, modern classical] 5. Ludovico Einaudi [italian contemporary classical] ```
## Agent 使用方法
当用户询问关于音乐的问题时： - "我最近在听什么？" → `spotify-api.py recent` - "我最喜欢的艺术家有哪些？" → `spotify-api.py top-artists` - "推荐新音乐" → `spotify-api.py recommend` + 结合您自己的知识
对于推荐，请将 API 数据与音乐知识相结合，以推荐其资料库中未包含的相似艺术家。
## 故障排除
### "未找到 Spotify 凭据！" - 确保 `credentials/spotify.json` 存在**或者**已设置环境变量 - 系统会优先检查凭据文件，然后检查环境变量 - 运行 `bash skills/spotify-history/scripts/setup.sh` 以创建凭据
### "未通过身份验证。请先运行 spotify-auth.py。" - Token 不存在或无效 - 运行：`python3 scripts/spotify-auth.py`（如果没有浏览器，则使用 `--headless`）
### Token 刷新期间出现 "HTTP Error 400: Bad Request" - 凭据已更改或无效 - 重新运行设置：`bash skills/spotify-history/scripts/setup.sh` - 或使用正确的 Client ID/Secret 更新 `credentials/spotify.json`
### "HTTP Error 401: Unauthorized" - Token 已过期且自动刷新失败 - 删除 Token 并重新验证： ```bash rm ~/.config/spotify-clawd/token.json python3 scripts/spotify-auth.py ```
### 无头模式 / 无浏览器 - 使用 `--headless` 标志：`python3 scripts/spotify-auth.py --headless` - 在任意设备上手动打开身份验证 URL - 复制回调 URL（以 `http://127.0.0.1:8888/callback?code=...` 开头） - 提示时将其粘贴回来
## 安全说明
- Token 以 0600 权限存储（仅限用户读/写） - Client Secret 应予以保密 - 出于安全考虑，Redirect URI 使用 `127.0.0.1`（仅限本地）
## 所需作用域
- `user-read-recently-played` — 最近的收听历史 - `user-top-read` — 热门艺术家和曲目 - `user-read-playback-state` — 当前播放状态 - `user-read-currently-playing` — 当前正在播放的曲目