yt-music

YouTube Music 技能

从技能根目录运行捆绑脚本：

• scripts/helper.py：搜索、资料库、播放列表、歌词、评分、账户
• scripts/player.py：播放客户端和守护进程管理
• scripts/player_daemon.py：持久运行的 Playwright 浏览器守护进程
• 运行时状态位于本地 ./.yt-music/
• 播放使用由 Playwright 管理的专用浏览器配置文件，位于 ./.yt-music/playwright-profile

工作流路由

对于多步骤或组合流程，应将用户引导至工作流文件，而不是临时编排：

用户意图	工作流文件
首次设置、身份验证过期、守护进程未运行	Workflows/Setup.md
“播放 X / 播放类似 Y 的内容 / 帮我找些音乐”	Workflows/PlayDiscover.md
“创建一个包含……的播放列表”“保存排行榜”、查找艺人的冷门作品	Workflows/BuildPlaylist.md
身份验证错误、守护进程超时、播放无声、Cookie 问题	Workflows/DiagnoseAuth.md
“运行测试”、编辑后验证脚本、CI 冒烟测试	Workflows/RunTests.md

单次请求（一次搜索、一次评分、一次 playlist get）直接处理，无需工作流。

决策流程

1. 如果用户提供的是名称而不是 ID，请先搜索。
2. 对需要身份验证的操作，先运行 auth check。
3. 如果缺少身份验证信息，请切换到身份验证指导模式，暂不继续。
4. 只有在身份验证成功后，才执行原始命令。
5. 将 JSON 格式化为简短的表格或列表。

ID 解析

使用搜索来解析 videoId、browseId 或 playlistId：

uv run --with yt-musicapi python scripts/helper.py search "<query>" --type songs --limit 5
uv run --with yt-musicapi python scripts/helper.py search "<query>" --type artists --limit 3
uv run --with yt-musicapi python scripts/helper.py search "<query>" --type albums --limit 3

如果结果不明确，请询问用户想要哪一个。

身份验证

在执行 library、playlist、rate、subscribe、home、history、taste、upload 或 auth account 前，先检查身份验证：

uv run --with yt-musicapi python scripts/helper.py auth check

如果缺少身份验证信息，请暂不继续执行所请求的操作。

必须明确引导用户提供以下其中一项：

• 从已登录的 music.youtube.com 请求中复制的 Cookie 字符串
• Cookie 的 JSON 导出文件路径

以下是必须遵守的规则：

• 不要只说“缺少身份验证信息”
• 不要只显示 shell 错误就停止
• 不要含糊地询问“请先登录”
• 要明确询问下一步需要的具体材料：Cookie 字符串或 Cookie 的 JSON 文件路径
• 尽可能使用与用户相同的语言；如果无法判断用户使用的语言，则默认使用简洁的英语
• 以下英文模板仅为默认措辞；请翻译或调整，使其符合用户使用的语言

使用此流程：

1. 告知用户，访问其资料库、播放列表、账户、上传内容或完整播放功能前需要进行身份验证。
2. 请用户在已登录的浏览器中打开 music.youtube.com。
3. 提供两个选项：
   • Cookie 字符串：打开 DevTools，进入 Network，筛选 /browse，重新加载页面，打开任意匹配的请求，复制 Cookie 请求头的值并发回
   • Cookie JSON：使用 Cookie 扩展程序导出 music.youtube.com 的 Cookie，并发回文件路径
4. 用户回复 Cookie 字符串或 JSON 文件路径后，运行 auth setup。
5. auth setup 成功后，重试原始命令。

推荐的默认用户提示语：

You need to sign in to YouTube Music before I can access your library, playlists, account, uploads, or full playback.

Please send me one of these:
1. A Cookie string
2. A cookies JSON file path

Cookie 字符串说明：

Open a logged-in music.youtube.com page
Open DevTools -> Network
Filter /browse and reload the page
Open any matching request
Copy the Cookie request header value
Send the full Cookie string back to me

Cookie JSON 说明：

Use a cookie export extension such as Cookie-Editor on music.youtube.com
Export cookies as JSON
Save the exported file locally
Send me the file path

设置命令：

uv run --with yt-musicapi python scripts/helper.py auth setup --cookie '<cookie string>'
uv run --with yt-musicapi python scripts/helper.py auth setup --cookies-file /path/to/cookies.json

常用命令

uv run --with yt-musicapi python scripts/helper.py search "<query>" [--type songs|artists|albums|playlists|videos]
uv run --with yt-musicapi python scripts/helper.py library playlists
uv run --with yt-musicapi python scripts/helper.py playlist get <playlistId>
uv run --with yt-musicapi python scripts/helper.py playlist create --title "<name>"
uv run --with yt-musicapi python scripts/helper.py playlist add <playlistId> <videoId...>
uv run --with yt-musicapi python scripts/helper.py lyrics <videoId>
uv run --with yt-musicapi python scripts/helper.py related <videoId>
uv run --with yt-musicapi python scripts/helper.py rate <videoId> LIKE|DISLIKE|INDIFFERENT
uv run --with yt-musicapi python scripts/helper.py charts [--country CN|US|KR|JP|ZZ]

完整命令参考：references/commands.md

播放

播放通过持久运行的 Playwright 浏览器守护进程执行。第一条播放命令会自动启动专用浏览器窗口，之后的 open、play、pause、next、prev、seek、volume 和 status 命令都会复用该窗口。

uv run --with playwright python scripts/player.py daemon-start
uv run --with playwright python scripts/player.py open <videoId>
uv run --with playwright python scripts/player.py play
uv run --with playwright python scripts/player.py pause
uv run --with playwright python scripts/player.py next
uv run --with playwright python scripts/player.py prev
uv run --with playwright python scripts/player.py status
uv run --with playwright python scripts/player.py volume <0-100>
uv run --with playwright python scripts/player.py seek <seconds>
uv run --with playwright python scripts/player.py daemon-status
uv run --with playwright python scripts/player.py daemon-stop

重要行为：

• 守护进程会在 ./.yt-music/playwright-profile 中启动专用的持久化浏览器配置文件
• 首次启动时，用户可能需要在该浏览器窗口中登录 music.youtube.com
• 用户无需手动启动 Chrome 或打开调试端口
• 如果 open <videoId> 已加载页面，但播放仍处于暂停状态，可能是自动播放被阻止；用户可能需要在守护进程管理的窗口中点击一次播放
• daemon-status 会检查后台浏览器是否在运行，不会启动新的浏览器

如果播放命令失败，请先确认：

• 守护进程管理的浏览器窗口仍处于打开状态
• 如果请求的曲目需要登录，用户已在该浏览器窗口中登录 music.youtube.com
• 请求的歌曲页面确实能在该浏览器会话中播放
• ./.yt-music/player-daemon.log 中没有启动或 Playwright 错误

输出

• 搜索结果：包含标题、艺人、专辑和时长的编号表格
• 播放列表曲目：包含标题、艺人和专辑的编号列表
• 歌词：以纯文本形式输出
• 播放状态：▶ {title} — {artist} ({position} / {duration})
• 错误：说明原因和后续操作

成功后，建议一个自然的下一步操作，例如播放、添加到播放列表、显示歌词或获取相关曲目。

易踩问题

经验总结——这是本技能信息密度最高的部分。每当某个流程以不易察觉的方式出错时，都要补充到这里。

• SAPISID Cookie 的特殊情况。 auth setup --cookie 会使用 time 和 music.youtube.com 对 SAPISID 进行 SHA1 哈希处理，以生成 API 身份验证标头。如果用户只粘贴了一行 Cookie（而不是完整的 Cookie: 标头），脚本会因 SAPISID not found 而退出。务必索要完整的 Cookie 请求标头值，而不是单个 Cookie 键值对。也接受 __Secure-3PAPISID 作为备用项。
• Cookie 会悄无声息地过期。 Google 会轮换会话 Cookie。即使文件存在，auth check 仍会返回 ok，但下一次经过身份验证的调用会返回 401。发生这种情况时，运行 auth remove，然后重新执行 Workflows/Setup.md 的第 2 步——不要盲目重试。
• 守护进程首次启动时会遇到自动播放限制。 在用户与页面交互一次之前，Chrome 的媒体策略会阻止自动播放。首次运行 player.py open <id> 时，页面可能会以 paused 状态加载。请告知用户在守护进程管理的窗口中点击一次播放；该操作会在此配置文件中保留，之后打开内容时就会自动播放。
• 崩溃后配置文件被锁定。 如果之前的守护进程崩溃，./.yt-music/playwright-profile/SingletonLock 可能会阻止重新启动。运行 daemon-stop 后删除该锁定文件，即可恢复，且不会丢失已登录会话。
• playlist add-playlist 需要对源播放列表拥有所有权或访问权限。 在不同用户的播放列表之间克隆会悄无声息地失败，且 actions 中不会显示差异。报告成功之前，请确认用户拥有 --source-playlist，或有权访问它。
• get_album 需要浏览 ID，而不是播放列表 ID。 该辅助工具会通过 get_album_browse_id 自动转换 OLAK* / PL* ID，但前提是用户传入了正确的标志——不要把 videoId 传给 album。
• charts --country ZZ 表示“全球”，不是拼写错误。这是默认值。区域排行榜请使用 ISO alpha-2 代码（BR、US、KR、JP）。
• related 可能返回空结果。 播放次数较少的曲目没有相关播放列表条目。此时应改用 watch <videoId> --limit 10 获取电台混音，而不是告诉用户“未找到结果”。
• playlist remove 需要完整的曲目对象，而不仅仅是 videoId。 该辅助工具会先通过 get_playlist 查找曲目；如果 to_remove 为空，脚本会返回 not_found, removed: 0，而不是报错。请如实向用户说明这一点——他们传入的曲目 ID 很可能不在该播放列表中。
• YT_MUSIC_DATA_DIR 会覆盖默认路径。 如果用户报告身份验证文件位于意外位置，请检查他们是否设置了此环境变量。默认路径为 <skill-root>/.yt-music/。

示例

示例 1 — 快速搜索并播放（两者均无需身份验证）。

User: "Play Bohemian Rhapsody."
→ search "Bohemian Rhapsody" --type songs --limit 5
→ confirm pick with user if ambiguous
→ player.py open <videoId>
→ player.py status
→ offer: lyrics, related, save to playlist

示例 2 — 创建巴西排行榜播放列表。

User: "Save this week's BR top 50 as a playlist."
→ route to Workflows/BuildPlaylist.md (Mode C)
→ auth check (required for playlist create/add)
→ charts --country BR
→ extract top 50 videoIds
→ playlist create --title "BR Top 50 — <date>" --privacy PRIVATE
→ playlist add <playlistId> <videoIds...>

示例 3 — 流程中途身份验证失败。

User: "Add this track to my Liked playlist."
→ playlist add returns 401
→ route to Workflows/DiagnoseAuth.md (Symptom 2)
→ auth remove → Workflows/Setup.md step 2
→ retry original playlist add