pp-spotify

Spotify — Printing Press CLI

前置条件：安装 CLI

此技能通过 spotify-pp-cli 二进制文件运行。**在调用此技能中的任何命令之前，必须确认 CLI 已安装。**如果尚未安装，请先安装：

1. 使用 Printing Press 安装程序安装。在 macOS/Linux 上，默认将二进制文件安装到 $HOME/.local/bin；在 Windows 上，默认安装到 %LOCALAPPDATA%\Programs\PrintingPress\bin：

   npx -y @mvanhorn/printing-press-library install spotify --cli-only
   

2. 验证：spotify-pp-cli --version
3. 确保所报告的安装目录位于将调用此技能的 Agent/运行时的 $PATH 中。

如果 npx 安装失败（例如没有 Node、处于离线状态等），请改用直接通过 Go 安装的方式（需要 Go 1.26.6 或更高版本）：

go install github.com/mvanhorn/printing-press-library/library/media-and-entertainment/spotify/cmd/spotify-pp-cli@latest

如果安装后 --version 报告“command not found”，说明运行时无法在 $PATH 中找到二进制文件所在目录。验证成功之前，请勿运行此技能的命令。

你可以使用 Spotify 的 Web API 来发现音乐和播客、管理 Spotify 媒体库、控制音频播放，以及执行更多操作。请使用左侧边栏，或在小屏幕上使用页面顶部的导航栏，浏览可用的 Web API 端点。

要成功发送 Web API 请求，你的应用需要有效的访问令牌。你可以通过 OAuth 2.0 获取令牌。

所有 Web API 请求的基础 URI 为 https://api.spotify.com/v1。

需要帮助？请参阅我们的 Web API 指南了解更多信息，或访问 Spotify for Developers 社区论坛提问并与其他开发者交流。

命令参考

albums — 管理专辑

• spotify-pp-cli albums get-an — 获取单张专辑的 Spotify 目录信息。
• spotify-pp-cli albums get-multiple — 获取多张专辑的 Spotify 目录信息，这些专辑由其 Spotify ID 标识。

artists — 管理艺人

• spotify-pp-cli artists get-an — 获取单个艺人的 Spotify 目录信息，该艺人由其唯一的 Spotify ID 标识。
• spotify-pp-cli artists get-multiple — 根据 Spotify ID 获取多个艺人的 Spotify 目录信息。

audio-analysis — 管理音频分析

• spotify-pp-cli audio-analysis <id> — 获取 Spotify 目录中某首曲目的底层音频分析信息。

audio-features — 管理音频特征

• spotify-pp-cli audio-features get — 获取单首曲目的音频特征信息，该曲目由其唯一的 Spotify ID 标识。
• spotify-pp-cli audio-features get-several — 根据 Spotify ID 获取多首曲目的音频特征信息。

audiobooks — 管理有声书

• spotify-pp-cli audiobooks get-an — 获取单本有声书的 Spotify 目录信息。
• spotify-pp-cli audiobooks get-multiple — 获取多本有声书的 Spotify 目录信息，这些有声书由其 Spotify ID 标识。

browse — 管理浏览

• spotify-pp-cli browse get-a-categories-playlists — 获取标记了特定类别的 Spotify 播放列表。
• spotify-pp-cli browse get-a-category — 获取 Spotify 中用于标记项目的单个类别（例如 Spotify 播放器的“浏览”标签页中的类别）。
• spotify-pp-cli browse get-categories — 获取 Spotify 中用于标记项目的类别列表（例如 Spotify 播放器的“浏览”标签页中的类别）。
• spotify-pp-cli browse get-featured-playlists — 获取 Spotify 精选播放列表（例如在 Spotify 播放器的“浏览”标签页中显示的播放列表）。
• spotify-pp-cli browse get-new-releases — 获取 Spotify 推荐的新专辑发行列表（例如在 Spotify 播放器的“浏览”标签页中显示的内容）。

chapters — 管理章节

• spotify-pp-cli chapters get-a — 获取单个有声书章节的 Spotify 目录信息。
• spotify-pp-cli chapters get-several — 根据 Spotify ID 获取多个有声书章节的 Spotify 目录信息。

episodes — 管理单集

• spotify-pp-cli episodes get-an — 根据单集的唯一 Spotify ID 获取其 Spotify 目录信息。
• spotify-pp-cli episodes get-multiple — 根据 Spotify ID 获取多个单集的 Spotify 目录信息。

markets — 管理市场

• spotify-pp-cli markets — 获取 Spotify 可用的市场列表。

me — 管理个人信息

• spotify-pp-cli me add-to-queue — 将项目添加到用户当前播放队列中，以便接下来播放。

• spotify-pp-cli me check-current-user-follows — 检查当前用户是否关注一个或多个艺人或其他 Spotify 用户。

• spotify-pp-cli me check-library-contains — 检查当前用户的媒体库中是否已保存一个或多个项目。

• spotify-pp-cli me check-users-saved-albums — 检查当前 Spotify 用户的“你的音乐”媒体库中是否已保存一个或多个专辑。

• spotify-pp-cli me check-users-saved-audiobooks — 检查当前 Spotify 用户的媒体库中是否已保存一本或多本有声书。

• spotify-pp-cli me check-users-saved-episodes — 检查当前 Spotify 用户的“你的单集”媒体库中是否已保存一个或多个单集。

• spotify-pp-cli me check-users-saved-shows — 检查当前 Spotify 用户的媒体库中是否已保存一个或多个节目。

• spotify-pp-cli me check-users-saved-tracks — 检查当前 Spotify 用户的“你的音乐”媒体库中是否已保存一首或多首曲目。

• spotify-pp-cli me create-playlist — 为当前 Spotify 用户创建播放列表。

• spotify-pp-cli me follow-artists-users — 将当前用户添加为一个或多个艺人或其他 Spotify 用户的关注者。**注意：**此端点已弃用。

• spotify-pp-cli me get-a-list-of-current-users-playlists — 获取当前 Spotify 用户拥有或关注的播放列表。

• spotify-pp-cli me get-a-users-available-devices — 获取用户可用的 Spotify Connect 设备信息。

• spotify-pp-cli me get-current-users-profile — 获取当前用户的详细个人资料信息（包括当前用户的用户名）。

• spotify-pp-cli me get-followed — 获取当前用户关注的艺人。

• spotify-pp-cli me get-information-about-the-users-current-playback — 获取用户当前播放状态的信息，包括曲目或单集、进度和活动设备。

• spotify-pp-cli me get-queue — 获取组成用户队列的对象列表。

• spotify-pp-cli me get-recently-played — 获取当前用户最近播放的曲目。注意：目前不支持播客单集。

• spotify-pp-cli me get-the-users-currently-playing-track — 获取用户 Spotify 帐户中当前正在播放的对象。

• spotify-pp-cli me get-users-saved-albums — 获取当前 Spotify 用户“你的音乐”媒体库中保存的专辑列表。

• spotify-pp-cli me get-users-saved-audiobooks — 获取当前 Spotify 用户“你的音乐”媒体库中保存的有声书列表。

• spotify-pp-cli me get-users-saved-episodes — 获取当前 Spotify 用户媒体库中保存的单集列表。

• spotify-pp-cli me get-users-saved-shows — 获取当前 Spotify 用户媒体库中保存的节目列表。

• spotify-pp-cli me get-users-saved-tracks — 获取当前 Spotify 用户“你的音乐”媒体库中保存的歌曲列表。

• spotify-pp-cli me get-users-top-artists — 根据计算得出的亲和度获取当前用户最喜爱的艺人。

• spotify-pp-cli me get-users-top-tracks — 根据计算得出的亲和度获取当前用户最喜爱的曲目。

• spotify-pp-cli me pause-a-users-playback — 暂停用户帐户上的播放。此 API 仅适用于 Spotify Premium 用户。

• spotify-pp-cli me remove-albums-user — 从当前用户的“你的音乐”媒体库中移除一个或多个专辑。**注意：**此端点已弃用。

• spotify-pp-cli me remove-audiobooks-user — 从 Spotify 用户的媒体库中移除一本或多本有声书。**注意：**此端点已弃用。

• spotify-pp-cli me remove-episodes-user — 从当前用户的媒体库中移除一个或多个单集。**注意：**此端点已弃用。

• spotify-pp-cli me remove-library-items — 从当前用户的媒体库中移除一个或多个项目。

• spotify-pp-cli me remove-shows-user — 从当前 Spotify 用户的媒体库中删除一个或多个节目。**注意：**此端点已弃用。

• spotify-pp-cli me remove-tracks-user — 从当前用户的“你的音乐”媒体库中移除一首或多首曲目。**注意：**此端点已弃用。

• spotify-pp-cli me save-albums-user — 将一个或多个专辑保存到当前用户的“你的音乐”媒体库中。**注意：**此端点已弃用。

• spotify-pp-cli me save-audiobooks-user — 将一本或多本有声书保存到当前 Spotify 用户的媒体库中。**注意：**此端点已弃用。

• spotify-pp-cli me save-episodes-user — 将一个或多个单集保存到当前用户的媒体库中。**注意：**此端点已弃用。

• spotify-pp-cli me save-library-items — 将一个或多个项目添加到当前用户的媒体库中。

• spotify-pp-cli me save-shows-user — 将一个或多个节目保存到当前 Spotify 用户的媒体库中。**注意：**此端点已弃用。

• spotify-pp-cli me save-tracks-user — 将一首或多首曲目保存到当前用户的“你的音乐”媒体库中。**注意：**此端点已弃用。

• spotify-pp-cli me seek-to-position-in-currently-playing-track — 跳转到用户当前播放曲目的指定位置。

• spotify-pp-cli me set-repeat-mode-on-users-playback — 设置用户播放的重复模式。此 API 仅适用于 Spotify Premium 用户。

• spotify-pp-cli me set-volume-for-users-playback — 设置用户当前播放设备的音量。此 API 仅适用于 Spotify Premium 用户。

• spotify-pp-cli me skip-users-playback-to-next-track — 跳到用户队列中的下一首曲目。此 API 仅适用于 Spotify Premium 用户。

• spotify-pp-cli me skip-users-playback-to-previous-track — 跳到用户队列中的上一首曲目。此 API 仅适用于 Spotify Premium 用户。

• spotify-pp-cli me start-a-users-playback — 在用户的活动设备上开始播放新的上下文，或恢复当前播放。

• spotify-pp-cli me toggle-shuffle-for-users-playback — 开启或关闭用户播放的随机播放。此 API 仅适用于 Spotify Premium 用户。

• spotify-pp-cli me transfer-a-users-playback — 将播放转移到新设备，并可选择开始播放。此 API 仅适用于 Spotify Premium 用户。

• spotify-pp-cli me unfollow-artists-users — 移除当前用户作为一个或多个艺人或其他 Spotify 用户关注者的身份。 playlists — 管理播放列表

• spotify-pp-cli playlists change-details — 更改播放列表的名称以及公开／私密状态。（当然，用户必须拥有该播放列表。）

• spotify-pp-cli playlists get — 获取 Spotify 用户拥有的播放列表。

recommendations — 管理推荐内容

• spotify-pp-cli recommendations get — 根据给定种子实体的可用信息生成推荐内容，并与相似内容进行匹配
• spotify-pp-cli recommendations get-genres — 获取可用的流派种子参数值列表

shows — 管理节目

• spotify-pp-cli shows get-a — 获取由唯一 Spotify ID 标识的单个节目的 Spotify 目录信息。
• spotify-pp-cli shows get-multiple — 根据多个 Spotify ID 获取多个节目的 Spotify 目录信息。

spotify_web_search — 管理 Spotify 网络搜索

• spotify-pp-cli spotify-web-search — 获取有关专辑、艺人、播放列表、曲目和节目的 Spotify 目录信息

tracks — 管理曲目

• spotify-pp-cli tracks get — 获取由唯一 Spotify ID 标识的单个曲目的 Spotify 目录信息。
• spotify-pp-cli tracks get-several — 根据多个 Spotify ID 获取多个曲目的 Spotify 目录信息。
• spotify-pp-cli tracks resolve — 将艺人 + 曲目名称解析为唯一的曲目 URI；从标准输入读取完整曲目列表。
• spotify-pp-cli tracks where — 显示曲目在你的资料库中出现的所有位置（播放列表、已保存曲目、播放历史记录、热门曲目）。

users — 管理用户

• spotify-pp-cli users <user_id> — 获取 Spotify 用户的公开个人资料信息。

将曲目列表转换为播放列表

/search 会返回一个排序后的结果页，其排序依据是相关性，而非标题精确度——现场版、重制版或翻唱版通常会排在你要找的录音室版本之前。tracks resolve 会重新排序（精确标题优先于标准化精确匹配，标准化精确匹配优先于前缀匹配；指定的艺人始终优先于其他艺人），并为每个输入行输出一个 URI，因此只需三个命令即可将一份演出曲目单转换为播放列表，而不必为每首歌单独搜索再手动编写 jq：

# 1. Resolve the tracklist to URIs (one title per line on stdin).
pbpaste | spotify-pp-cli tracks resolve --artist Northlane --agent > resolved.json

# 2. Check what didn't resolve before creating anything.
jq -r '.results.results[] | select(.uri == null) | .query_title' resolved.json

# 3. Create the playlist and add the URIs.
PLAYLIST=$(spotify-pp-cli me create-playlist --name "Northlane / Milan" --agent \
  --select id | jq -r '.results.id')
spotify-pp-cli playlists items add-to-playlist "$PLAYLIST" --agent \
  --uris "$(jq -c '[.results.results[].uri | select(. != null)]' resolved.json)"

每行中的 match_kind 会说明匹配方式（exact、normalized、prefix、substring，或仅匹配到其他艺人的录音时使用的 *_other_artist），因此 Agent 可以判断哪些结果需要人工检查。添加 --fail-on-miss，即可在任何标题无法解析时以状态码 2 退出。

读取播放列表内容：使用 .item，而非 .track

playlists items get-playlists 调用 Spotify 的 /playlists/{id}/items 端点，其行中的曲目字段为 item。Spotify 的官方文档和大多数示例介绍的都是较旧的 /playlists/{id}/tracks 端点，该端点使用 track 字段——因此，从文档中复制的 jq '.results.items[].track' 在这里会悄悄返回 null。请使用 .item：

spotify-pp-cli playlists items get-playlists <playlist_id> --agent \
  | jq -r '.results.items[].item.name'

playlists tracks ... 子命令树使用旧版 /tracks 端点，而 Spotify 现在会对当前应用凭据返回 HTTP 403。请优先使用 playlists items ... 子命令树。

查找合适的命令

如果你知道要做什么，但不知道该用哪个命令，可以直接询问 CLI：

spotify-pp-cli which "<capability in your own words>"

which 会根据自然语言功能查询，从此 CLI 精选的功能索引中找出最匹配的命令。退出码 0 表示至少找到一个匹配项；退出码 2 表示没有足够可靠的匹配结果——请改用 --help，或尝试更具体的查询。

身份验证设置

运行 spotify-pp-cli auth setup，查看获取令牌所需的 URL 和步骤（添加 --launch 可打开该 URL）。然后存储令牌：

spotify-pp-cli auth set-token YOUR_TOKEN_HERE

或者将 SPOTIFY_OAUTH_2_0 设置为环境变量。

运行 spotify-pp-cli doctor 验证设置。

Agent 模式

在任何命令后添加 --agent。它会展开为：--json --compact --no-input --no-color --yes。

• 可通过管道处理 — JSON 输出到 stdout，错误输出到 stderr。只有一种有意设计的例外：当 --select 未匹配到任何内容时，CLI 会将其 available_fields 诊断信息写入 stdout 上的常规封套，因为这份列表是值得解析的数据；同时也会在 stderr 输出一行说明。

• 可筛选 — --select 保留部分字段。带点号的路径可深入嵌套结构；数组会逐元素遍历。投影也会深入嵌套的对象封套（即包裹单个有界集合的对象），直到到达集合，因此无需指定封套键即可访问已封装负载中的字段。这对于缩小冗长 API 的上下文至关重要：

  spotify-pp-cli audio-analysis mock-value --agent --select id,name,status
  

  --select 未匹配到任何内容时会报错，而不是返回空结果：CLI 以状态码 2 退出，并返回一条诊断信息，指出可用字段，而不会回退到完整负载。路径相对于数据，而非 {meta, results} 封套——应写成 --select tracks.items.name，而不是 --select results.tracks.items.name：

  spotify-pp-cli spotify-web-search --q "track:4D artist:Northlane" --type track \
    --json --select results.tracks.items.name
  # exit 2
  # {"results":{"error":"--select matched no fields","select":"results.tracks.items.name",
  #             "available_fields":["tracks","tracks.href","tracks.items", ...]}}
  

• 可预览 — --dry-run 显示请求，但不发送

• 适用于离线场景 — 有本地 SQLite 存储时，同步／搜索命令可以使用它

• 非交互式 — 从不提示，所有输入均通过标志传入

• 显式重试 — 仅当已存在的创建操作应视为成功时才使用 --idempotent；仅当删除目标不存在也应视为成功时才使用 --ignore-missing

响应封套

从本地存储或 API 读取的命令，会将输出封装在一个溯源封套中：

{
  "meta": {"source": "live" | "local", "synced_at": "...", "reason": "..."},
  "results": <data>
}

解析 .results 获取数据，并查看 .meta.source 了解数据来自实时来源还是本地来源。仅当 stdout 是终端且未设置任何机器格式标志（--json、--csv、--compact、--quiet、--plain、--select）时，才会将人类可读的 N results (live) 摘要打印到 stderr——通过管道处理的／Agent 消费者以及显式格式运行都会在 stdout 输出纯 JSON。

封套保证：

• 封套只由打印器添加一次——不要假设 results 中还嵌套着第二层 {meta, results} 封套；meta.source 始终报告数据实际来源。
• 发送真实 POST/PUT/DELETE 的命令，在所有输出路径上都会报告 source: "live"。
• 单对象端点（artists get-an、albums get-an 等）会在 results 中返回完整资源，而非其中的嵌套片段。
• 多类型实时搜索若遇到某个类型出错，会保留成功的类型，并在 meta.reason 中报告结果集不完整——将部分搜索视为完整结果前，请先检查 meta.reason。

实时搜索

search <query> 会调用 Spotify 的实时 /search 端点，该端点需要 type 参数——CLI 会解析请求的类型（默认包含所有目录类型，或通过 --type 指定单个类型），显式发送这些类型，并汇总所有有内容的类型响应。Spotify 没有提供实时端点的类型（例如 me、chapters）仅支持本地查询：使用 --data-source live 请求这些类型会立即失败，退出状态码为 2，并指出可用的替代项（local 或 auto）。

路径与状态

Agent 应将 CLI 的路径解析器视为运行时约定的一部分：

• 使用 --home <dir> 指定单次调用的目录，或设置 SPOTIFY_HOME=<dir>，将四种路径类型全部迁移到同一根目录下。

• 仅当某种特定类型的路径需要单独设置时，才使用对应的环境变量：SPOTIFY_CONFIG_DIR、SPOTIFY_DATA_DIR、SPOTIFY_STATE_DIR、SPOTIFY_CACHE_DIR。

• 解析顺序为：对应类型的环境变量、--home、SPOTIFY_HOME、XDG（XDG_CONFIG_HOME、XDG_DATA_HOME、XDG_STATE_HOME、XDG_CACHE_HOME），然后是平台默认值。

• config 包含 config.toml、配置档案等设置。data 包含 credentials.toml、data.db、Cookie 和认证辅助文件。state 包含已保存的查询、作业和 teach.log。cache 包含可重新生成的 HTTP/缓存文件。

• 已保存的密钥位于数据目录下的 credentials.toml 中。为保持兼容性，仍会读取现有的旧版 config.toml 密钥，并在首次写入认证信息时将其移出 config.toml。

• 运行 spotify-pp-cli doctor --fail-on warn，以显示路径和凭据位置警告。对于需要已解析目录的 Agent，agent-context 会提供 schema v4 paths 块。

• 对于 MCP，请通过 MCP 主机配置指定路径迁移。MCP 二进制文件不会继承 CLI 标志：

  {
    "mcpServers": {
      "spotify": {
        "command": "spotify-pp-mcp",
        "env": {
          "SPOTIFY_HOME": "/srv/spotify"
        }
      }
    }
  }
  

集群优先级：继承的对应类型环境变量会覆盖该类型的显式 --home。使用 SPOTIFY_HOME 或对应类型的环境变量作为持久的集群配置手段，仅将 --home 用于单次调用。取消设置环境变量无法撤销路径迁移；清除 SPOTIFY_HOME 前，请手动移动文件，否则 doctor 将找不到保留在原根目录下的凭据。

Agent 反馈

当你（或 Agent）发现此 CLI 有任何不妥之处时，请记录下来：

spotify-pp-cli feedback "the --since flag is inclusive but docs say exclusive"
spotify-pp-cli feedback --stdin < notes.txt
spotify-pp-cli feedback list --json --limit 10

记录会以 feedback.jsonl 的形式保存在已解析的数据目录下。除非设置了 SPOTIFY_FEEDBACK_ENDPOINT，并且传入了 --send 或设置了 SPOTIFY_FEEDBACK_AUTO_SEND=true，否则绝不会发送 POST 请求。默认情况下，记录仅保存在本地。

记录让你感到意外的地方，而不是提交错误报告。简短、具体、一行即可：这正是能逐渐积累价值的内容。

输出传递

每条命令都接受 --deliver <sink>。输出会发送到指定的目标，同时输出到 stdout（或取代 stdout），因此 Agent 无需手动通过管道传递结果即可路由命令输出。支持三种目标：

目标	效果
stdout	默认值；仅写入 stdout
file:<path>	将输出原子性地写入 <path>（临时文件 + 重命名）
webhook:<url>	将输出正文 POST 到该 URL（--compact 时使用 application/json 或 application/x-ndjson）

不支持的方案会被拒绝，并返回一条结构化错误，列出支持的方案。Webhook 请求失败时会返回非零退出码，并在 stderr 中记录 URL 和 HTTP 状态。

命名配置档案

配置档案是保存的一组标志值，可在多次调用中重复使用。当定时或周期性运行的 Agent 每次提供不同输入、但重复使用相同的已保存标志时，可使用配置档案。

spotify-pp-cli profile save briefing --json
spotify-pp-cli --profile briefing audio-analysis mock-value
spotify-pp-cli profile list --json
spotify-pp-cli profile show briefing
spotify-pp-cli profile delete briefing --yes

显式标志始终优先于配置档案值；配置档案值优先于默认值。agent-context 会在 available_profiles 下列出所有可用配置档案，供进行运行时自省的 Agent 发现。

退出码

代码	含义
0	成功
2	用法错误（参数错误）
3	未找到资源
4	需要认证
5	API 错误（上游问题）
7	触发速率限制（等待后重试）
10	配置错误

参数解析

解析 $ARGUMENTS：

1. 为空、help 或 --help → 显示 spotify-pp-cli --help 输出
2. 以 install 开头 → 以 mcp 结尾 → 安装 MCP；否则 → 参见上文的先决条件
3. 其他任何内容 → 直接使用（作为 CLI 命令执行，并附带 --agent）

安装 MCP 服务

从此 CLI 已发布的公共库条目或预构建版本安装 MCP 二进制文件，然后进行注册：

claude mcp add spotify-pp-mcp -- spotify-pp-mcp

验证：claude mcp list

直接使用

1. 检查是否已安装：which spotify-pp-cli 如果未找到，提供安装选项（参见此技能顶部的先决条件）。
2. 根据上述独特功能和命令参考，选择最符合用户查询的命令。
3. 使用 --agent 标志执行：

   spotify-pp-cli <command> [subcommand] [args] --agent
   

4. 如果存在歧义，进一步查看子命令帮助：spotify-pp-cli <command> --help。