Spotify History

核心用法

本 skill 通过 Spotify Web API 授权访问个人音乐数据，支持三大功能模块：

1. 听歌历史查询 — 调用 recent 接口获取最近 50 首播放记录
2. 音乐品味分析 — 按短/中/长期（4周/6个月/全部时间）拉取 Top Artists 与 Top Tracks
3. 个性化推荐 — 基于用户 Top Artists 种子生成相似艺人/曲目建议

技术路径为标准 OAuth 2.0 授权码模式：创建 Spotify Developer App → 配置环境变量 → 执行 spotify-auth.py 完成浏览器授权 → 本地持久化 token。后续调用由 spotify-api.py 封装，支持命令行直接查询或 JSON 原始输出。

显著优点

• 官方数据源：直接对接 Spotify 生产级 API，数据实时性与准确性高于第三方爬虫
• 细粒度时间维度：short/medium/long_term 三级时间切片，满足趋势追踪与长期画像需求
• 扩展性良好：保留原始 /me 等端点调用能力，便于自定义分析
• Token 自动刷新：内置过期处理，降低维护成本

潜在局限

• 授权门槛：需注册开发者账号、创建 App、配置 Redirect URI，非技术用户上手成本较高
• 地域与账户限制：受 Spotify 服务区域及付费账户功能差异影响（如部分市场无歌词 API）
• 速率限制：未提及配额管理，高频调用可能触发 429 限制
• 隐私敏感：需授予 user-top-read 等侵入性 scope，用户可能顾虑数据暴露

适合人群

• 音乐数据分析师、Playlist 策展人
• 希望将听歌习惯集成至个人助手的开发者/极客用户
• 需要基于真实收听数据生成推荐的音乐爱好者

常规风险

• Token 本地存储：虽设 0600 权限，但文件系统泄露仍可能导致账户劫持
• Client Secret 管理：环境变量方式在共享设备或多用户场景存在暴露风险
• Redirect URI 配置：文档强调使用 127.0.0.1 而非 localhost，可避免部分 DNS 重绑定攻击，但仍需确保端口未被其他服务占用
• Scope 最小化不足：申请权限包含 user-read-playback-state 等未在核心功能中明确使用的 scope，建议按实际用途裁剪

核心功能与用法

spotify-history 是一款用于访问 Spotify 平台用户听歌历史和生成个性化音乐推荐的命令行工具。核心功能包括：获取最近播放记录、查询 TOP 艺术家/歌曲（支持短期/中期/长期三个时间维度）、基于用户偏好生成推荐，以及原始 API 调用能力。

典型使用场景：

• 音乐品味回顾："我最近听了什么？" → spotify-api.py recent
• 年度听歌总结："我的 TOP 艺术家是谁？" → spotify-api.py top-artists long_term
• 发现新音乐："推荐新歌" → spotify-api.py recommend

Agent 集成建议：结合 API 返回的原始数据与音乐知识库，可为用户提供超越 Spotify 官方算法的深度推荐（如同风格但未收录的艺术家）。

---

显著优点

| 维度 | 优势 |

|------|------|

| **安全架构** | 采用标准 OAuth 2.0 授权流程，令牌存储于 `~/.config/spotify-clawd/token.json` 并设置 0600 权限；Client Secret 通过环境变量管理，不硬编码 |

| **依赖安全** | **零第三方依赖**，仅使用 Python 标准库（urllib, http.server, json），供应链攻击面为零 |

| **传输安全** | 所有 API 调用均使用 HTTPS/TLS 1.3，目标严格限定于 Spotify 官方域名 |

| **隐私合规** | 符合 GDPR 要求，采用用户显式授权模式，敏感数据本地存储 |

| **代码质量** | 272 行代码结构清晰，静态分析得分 82/100，无危险函数调用 |

---

局限性与风险

已知限制

• T3 来源可信度：个人开发者/社区项目，建议首次使用前人工审查代码
• 本地 HTTP 服务器：OAuth 回调监听固定端口 127.0.0.1:8888，存在端口冲突风险，且理论上任何本地进程可访问
• 令牌本地存储：虽设 0600 权限，但仍可能受本地恶意软件访问（非网络攻击）
• 错误处理待完善：当前仅对 401 错误实现自动令牌刷新，缺乏指数退避重试机制

常规风险

• OAuth 凭证泄露：若用户误将 Client Secret 提交至代码仓库，可能导致账户风险
• API 速率限制：Spotify API 有调用配额，高频使用可能触发限制

---

适合人群

• 音乐爱好者：希望深度分析个人听歌习惯、生成可视化年度报告
• AI Agent 用户：需要为音乐相关查询提供个性化、上下文感知的回答
• 隐私敏感用户：偏好本地存储令牌、不依赖第三方音乐服务的方案
• 开发者/技术用户：能接受 OAuth 配置流程，理解环境变量与命令行操作

---

安全等级评定依据

综合安全认证报告（CLS-2026-0701-SPOTIFY）：

• 静态分析 82/100：凭证管理规范，无危险调用
• 动态分析 80/100：网络请求受限，无系统命令执行
• 依赖审计 95/100：纯标准库实现
• 网络分析 85/100：全 HTTPS，官方 API 限定
• 隐私合规 75/100：GDPR 合规，OAuth 授权
• 威胁情报 70/100：T3 来源为唯一扣分项

总分 78/100，等级 A，属于标准安全级别 Skill。