名称： spotify-history
描述： 通过 Spotify Web API 获取用户的收听历史、热门艺术家/曲目，并提供个性化推荐。适用于查询近期播放记录、分析音乐品味或生成推荐。需要一次性 OAuth 设置。

Spotify 收听历史与推荐

获取 Spotify 收听历史并接收个性化推荐。

设置（一次性）

快速设置（推荐）

运行设置向导：

bash skills/spotify-history/scripts/setup.sh

该向导将引导您完成：
1. 创建 Spotify 开发者应用
2. 安全保存凭据
3. 授权访问

手动设置

1. 创建 Spotify 开发者应用
   - 访问 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 # 添加到 ~/.zshrc 或 ~/.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 授权，并粘贴回调地址。

令牌将保存至 ~/.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

时间范围

• short_term — 约最近 4 周
• medium_term — 约最近 6 个月（默认）
• long_term — 所有时间

示例输出

热门艺术家（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]

智能体使用

当用户询问音乐相关问题时：
- “我最近听了什么？” → 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。”

• 令牌不存在或无效
• 运行：python3 scripts/spotify-auth.py（若无浏览器，请使用 --headless）

令牌刷新时出现 “HTTP Error 400: Bad Request”

• 凭据已更改或无效
• 重新运行设置：bash skills/spotify-history/scripts/setup.sh
• 或更新 credentials/spotify.json 中的正确 Client ID/Secret

“HTTP Error 401: Unauthorized”

• 令牌过期且自动刷新失败
• 删除令牌并重新认证：
  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=... 开头）
• 在提示时粘贴回终端

安全说明

• 令牌以 0600 权限存储（仅用户可读写）
• 客户端密钥应保持私密
• 重定向 URI 使用 127.0.0.1（仅限本地）以确保安全

所需权限范围

• user-read-recently-played — 近期收听历史
• user-top-read — 热门艺术家和曲目
• user-read-playback-state — 当前播放状态
• user-read-currently-playing — 当前播放曲目