【免费下载链接】sunnify-spotify-downloaderSunnify is a Spotify downloader application CLI that allows you to download entire playlists locally onto your Mac/Linux/Windows PC.项目地址https://gitcode.com/gh_mirrors/su/sunnify-spotify-downloader点击查看免费下载Sunnify 是一款免费开源的 Spotify 音乐下载工具它不仅提供图形界面还内置了一个为 AI Agent 量身打造的命令行接口sunnify。通过--json参数Sunnify 会以 NDJSON每行一个 JSON 事件的形式实时汇报下载进度让 AI Agent 像读日志一样看懂每一首歌的下落配合doctor自检命令还能在出问题时快速定位是环境、配置还是上游服务的问题。为什么 Sunnify 适合被 AI Agent 驱动大多数桌面工具只给人点鼠标用而 Sunnify 从设计之初就遵循了面向 CLI 的设计指南完整参考见 docs/CLI.md每个命令都是永不交互的——不会弹出任何输入提示等待你按键不会请求管理员权限所有设置都有合理默认值且可通过参数覆盖。这意味着 AI Agent 可以放心地发起命令、读取输出、做出下一步决策而不会被卡在半路等你回复是或否。Sunnify 的 CLI 与桌面 App 共享同一套引擎匹配器、命名规则、标签写入器、断点续传清单因此2 点钟定时任务自动跑出来的文件和你手动点击 GUI 得到的完全一致。核心实现位于 sunnify_cli.py其开头就写明了这份给脚本和 AI Agent 的设计契约。 简单说GUI 给你点CLI 给 Agent 读。核心机制用 --json 打开 NDJSON 事件流下载歌单时加上--json参数Sunnify 就会把进度变成一行行 JSON 事件输出到标准输出sunnify download https://open.spotify.com/playlist/... --json不加--json时输出是给人看的友好文字✓、»等符号加了之后每一行都是一个独立的 JSON 对象AI Agent 可以逐行解析无需等整个歌单下载完。五种事件读懂一次完整下载事件含义Agent 可以做什么run_started下载开始携带格式、质量、输出目录等参数记录任务上下文展示开始下载状态track_done一首歌成功落盘含文件路径和字节数累计进度、校验产物track_skipped该歌已存在于磁盘自动跳过理解断点续传不必重下warning单首歌曲出现警告记录但不必中断任务run_summary流的终止符汇总 landed / skipped / failed 数量与耗时做最终决策成功部分失败重试一个典型的输出片段格式见 docs/CLI.md 的Machine-readable output一节{event: run_started, url: ..., type: playlist, folder: ..., format: mp3, quality: 320} {event: track_done, title: ..., artists: ..., file: /path/file.mp3, bytes: 4823041} {event: track_skipped, title: ..., file: /path/file.mp3} {event: run_summary, landed: 12, skipped: 3, failed: 1, elapsed_s: 94.2, exit_code: 1}对 AI Agent 而言run_summary是唯一需要总结的事件看到它就说明这次下载结束了对应源码 sunnify_cli.py 中的发射逻辑。错误不是文字而是类型化的信封出错时Sunnify 不会只丢一句模糊的报错而是输出带code和hint的结构化错误{event: error, code: ffmpeg_missing, message: ffmpeg not found, hint: brew install ffmpeg / apt install ffmpeg / winget install ffmpeg}AI Agent 应该根据code字段分支决策而不是去猜错误文本。当前定义的错误码有 7 个见 docs/CLI.mdcode触发场景Agent 的建议动作invalid_url传入的不是 Spotify 链接请用户检查链接conflicting_flags--title-only与--artist-first同时传入二选一后重试out_dir_unusable输出目录不可写换--out目录ffmpeg_missing源码安装且系统缺 FFmpeg按 hint 安装 FFmpegfolder_locked另一个下载正在写同一目录等待或换目录metadata_fetch_failed无法获取元数据运行doctor检查上游run_failed下载过程整体失败运行doctor排查退出码一行代码判断成败除了事件流Sunnify 还提供 4 个语义明确的退出码定义见 sunnify_cli.py退出码含义0一切顺利请求的内容全部落盘1跑完了但部分歌曲失败或任务被中断2参数用法错误拼错参数等3环境或致命错误坏链接、缺 FFmpeg、目录被锁… Agent 决策口诀先看退出码定方向再读run_summary看细节遇到错误读code执行对应策略。doctor 自检下载出问题时先跑这条命令当下载反复失败时人往往会盲目重启而 AI Agent 可以跑doctor命令——它是环境体检一次输出全部检查结果sunnify doctor --json它依次检查 6 个项目实现见 sunnify_cli.py检查项检查什么失败时通常意味着ffmpeg能否找到 FFmpeg源码安装的用户需要安装 FFmpegconfig配置文件能否正常加载配置损坏可删除重建logs日志目录位置提示你去哪里找详细日志spotify_metadataSpotify 元数据接口是否可达网络问题或上游变更yt_dlpyt-dlp 组件及版本源码安装缺依赖version是否有更新的版本落后版本仅提醒不算故障JSON 输出形如{ok: true, checks: [...]}每个 check 带ok布尔值和detail说明。Agent 的排查策略很简单download --json报错退出码为3立刻运行sunnify doctor --json找到所有ok: false的检查项按detail修复比如安装 FFmpeg重新发起下载。不加--json时人类用户也能直接读每一项前标✓或✗最后一行是all good或problems found。实战AI Agent 的完整下载工作流把前面的机制串起来一个健壮的自动化流程通常长这样预检先跑sunnify doctor --jsonok: false就先修复环境取元数据用sunnify info url --json预览歌单不下载、不依赖 FFmpeg向用户确认共 32 首是否开始发起下载执行sunnify download url --json -f mp3 -q 320逐行读取事件流实时向用户播报进度处理异常收到folder_locked→ 提示另一个下载正在进行选择等待退出码1→ 读run_summary.failed_titles向用户列出失败歌曲并建议重试收到metadata_fetch_failed→ 再跑一次doctor定位上游问题收尾用sunnify status folder --json汇总最终落盘数量该命令还能告诉你是否仍有下载在进行中因为每个目录带 PID 锁文件。几个值得注意的细节断点续传是内建的已落盘的歌曲会被track_skipped跳过所以重试一次永远不会重复下载已完成的歌——这对 Agent 的幂等重试至关重要长歌单适合后台运行文件是逐首落盘的Agent 可以在另一个会话里用sunnify status查询进度锁文件里的 PID 就是还在跑的信号CtrlC是优雅的第一次按会等当前歌曲下完再退出第二次才是强制退出Agent 的中止逻辑可据此设计。安装与升级Agent 也能自己搞定Sunnify 的官方安装脚本同样是无提示、无需管理员权限的AI Agent 完全可以代跑见 scripts/install.sh 与 scripts/install.ps1# macOS / Linux curl -fsSL 安装脚本地址 | sh脚本会拉取官方发布包、校验 SHA256 校验和然后原地安装重复执行即为原地升级。此外sunnify doctor的version检查项会告诉你当前版本是否落后Agent 可以据此主动建议升级。常见问题速查Q为什么我加--json后终端里全是英文 JSON这就是给人看的吗是的——人用文字输出不带--json机器用 JSON 输出带--json。两种模式共用同一份引擎行为完全一致。Q退出码 1 和 3 有什么区别1表示流程跑完了但部分歌失败通常重试或换网络即可3表示根本没开始或中途崩溃坏链接、缺 FFmpeg、目录被锁应先跑doctor。QAgent 能同时下载两个歌单到同一目录吗不建议。每个目录有 PID 锁文件.sunnify-cli.lock第二个任务会收到folder_locked错误码换个--out目录即可并行。Qstatus命令能干什么它是只读体检列出目录里已有的音频文件数、清单记录数、缺失数以及是否正在下载附 PID。Agent 用它来汇报进度最稳妥。写在最后Sunnify 的 CLI 把下载音乐这件事变成了一套机器可理解、可恢复、可自检的契约NDJSON 事件流让你实时掌握进度类型化错误码让决策分支清晰退出码让结果一目了然doctor让排障不再靠猜。这正是 AI Agent 自动执行复杂任务所需要的全部要素。更多参数与输出格式的完整参考请查阅仓库内的 docs/CLI.md。赞分享【免费下载链接】sunnify-spotify-downloaderSunnify is a Spotify downloader application CLI that allows you to download entire playlists locally onto your Mac/Linux/Windows PC.项目地址https://gitcode.com/gh_mirrors/su/sunnify-spotify-downloader点击查看免费下载相关推荐Mac屏幕不再跳动Stillcolor终极方案解决Apple Silicon Mac视觉疲劳问题Mac屏幕不再跳动Stillcolor终极方案解决Apple Silicon Mac视觉疲劳问题 你是否在使用Apple Silicon Mac时感到眼睛疲劳桌面应用系统底层如何永久保存Spotify歌单spotDL音乐下载工具完全指南如何永久保存Spotify歌单spotDL音乐下载工具完全指南 你是否曾在旅行途中打开精心收藏的Spotify歌单却因网络不佳只能对着缓冲图标叹气是否担心CLI音频音视频网页爬虫Beads bd doctor 命令完全指南安装健康检查、自动修复与 AI Agent 诊断Beads bd doctor 命令完全指南安装健康检查、自动修复与 AI Agent 诊断 bd doctor 是 Beads 项目 Beads A meAI 应用Agent 记忆CLIMCP 服务项目管理人工智能创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考