SuperAPI AI 工具集

spotify-history

通用与其它

查看项目

更新于 10-16 06:40

技能介绍

用途

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 开发者应用、安全保存凭据、授权访问。

手动配置步骤:

  1. 创建 Spotify 开发者应用:访问 developer.spotify.com/dashboard,点击 Create App,填写应用名称(如 Clawd)、应用描述(如 Personal assistant integration)、重定向 URI:http://127.0.0.1:8888/callback(需使用精确 URL),保存并复制 Client ID 与 Client Secret。

  2. 存储凭据,两种方式:

方式 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"
  1. 授权:

有浏览器(本地机器):

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=... 开头),在提示时粘贴回去。