用途
Spotify History & Recommendations 用于通过 Spotify Web API 访问用户的 Spotify 收听历史,获取热门艺人与曲目,并生成个性化音乐推荐。它适合在用户询问音乐相关问题时使用,例如“我最近在听什么”“我的热门艺人是谁”“推荐新音乐”。
主要能力
- 获取最近收听历史(recent)
- 获取热门艺人(top-artists),支持 short_term、medium_term、long_term 三种时间范围
- 获取热门曲目(top-tracks),同样支持三种时间范围
- 基于热门艺人获取推荐(recommend)
- 直接调用任意 Spotify API 端点(json 子命令),例如 /me 或 /me/player/recently-played
时间范围说明:
- short_term — 约最近 4 周
- medium_term — 约最近 6 个月(默认)
- long_term — 全部时间
使用方式
一次性配置
推荐使用快速配置向导:
bash skills/spotify-history/scripts/setup.sh
该向导会引导完成:创建 Spotify 开发者应用、安全保存凭据、授权访问。
手动配置步骤:
-
创建 Spotify 开发者应用:访问 developer.spotify.com/dashboard,点击 Create App,填写应用名称(如 Clawd)、应用描述(如 Personal assistant integration)、重定向 URI:http://127.0.0.1:8888/callback(需使用精确 URL),保存并复制 Client ID 与 Client Secret。
-
存储凭据,两种方式:
方式 A:凭据文件(推荐)
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:环境变量
# 添加到 ~/.zshrc 或 ~/.bashrc
export SPOTIFY_CLIENT_ID="your_client_id"
export SPOTIFY_CLIENT_SECRET="your_client_secret"
- 授权:
有浏览器(本地机器):
python3 scripts/spotify-auth.py
无浏览器(headless):
python3 scripts/spotify-auth.py --headless
按提示通过 URL 授权并粘贴回调。令牌保存至 ~/.config/spotify-clawd/token.json,过期后自动刷新。
命令行使用
# 最近收听历史
python3 scripts/spotify-api.py recent
# 热门艺人(time_range: short_term, medium_term, long_term)
python3 scripts/spotify-api.py top-artists medium_term
# 热门曲目
python3 scripts/spotify-api.py top-tracks medium_term
# 基于热门艺人获取推荐
python3 scripts/spotify-api.py recommend
# 原始 API 调用(任意端点)
python3 scripts/spotify-api.py json /me
python3 scripts/spotify-api.py json /me/player/recently-played
智能体使用建议
当用户询问音乐时:
- “我最近在听什么?” → spotify-api.py recent
- “我的热门艺人是谁?” → spotify-api.py top-artists
- “推荐新音乐” → spotify-api.py recommend,并结合自身音乐知识
对于推荐,可将 API 数据与音乐知识结合,建议用户曲库中未包含的相似艺人。
适用场景
- 查看个人 Spotify 收听历史与统计
- 按不同时间范围分析热门艺人与曲目
- 基于收听偏好获取个性化推荐
- 作为智能体技能,在对话中回答音乐相关问题
限制与注意事项
- 需要 Spotify 开发者应用与用户授权,未授权时无法使用
- 重定向 URI 必须精确为 http://127.0.0.1:8888/callback
- 令牌过期后自动刷新,若刷新失败需删除令牌并重新授权
- 无浏览器环境需使用 --headless 模式手动完成授权
安全说明
- 令牌以 0600 权限存储(仅用户可读写)
- Client Secret 应保持私密
- 重定向 URI 使用 127.0.0.1(仅本地)以提升安全性
所需权限范围
- user-read-recently-played — 最近收听历史
- user-top-read — 热门艺人与曲目
- user-read-playback-state — 当前播放状态
- user-read-currently-playing — 当前播放曲目
故障排查
- “Spotify credentials not found!”:确认 credentials/spotify.json 存在或环境变量已设置;凭据文件优先于环境变量;可运行 bash skills/spotify-history/scripts/setup.sh 创建凭据。
- “Not authenticated. Run spotify-auth.py first.”:令牌不存在或无效,运行 python3 scripts/spotify-auth.py(无浏览器时加 --headless)。
- “HTTP Error 400: Bad Request” 在令牌刷新时:凭据已更改或无效,重新运行 setup.sh 或更新 credentials/spotify.json 中的正确 Client ID/Secret。
- “HTTP Error 401: Unauthorized”:令牌过期且自动刷新失败,删除令牌并重新授权:
rm ~/.config/spotify-clawd/token.json
python3 scripts/spotify-auth.py
- 无浏览器环境:使用 --headless 标志,在任意设备手动打开授权 URL,复制回调 URL(以 http://127.0.0.1:8888/callback?code=... 开头),在提示时粘贴回去。