hifi-download

MusicMaster

通过统一的 CLI 发现音乐（Spotify、Last.fm）并下载 Hi-Res 音频（Qobuz、TIDAL）。

语言

匹配用户使用的语言：使用与用户相同的语言回复。

所有命令均使用 bash ${SKILL_PATH}/run.sh <script> [args...]，该命令会激活 venv 并运行相应的 Python 脚本。默认输出为人类可读格式；支持时可使用 --json 获取结构化输出。

首次设置

步骤 1：检查依赖项

bash ${SKILL_PATH}/scripts/setup.sh check

输出为 key=value 对。如果 VENV=missing，请先运行安装。

步骤 2：安装

bash ${SKILL_PATH}/scripts/setup.sh install [--with-qobuz] [--with-tidal]

创建 .venv，安装核心依赖项（spotipy、pylast、requests、python-dotenv），并可选择安装下载后端。

步骤 3：配置凭据

重要：请勿在聊天中向用户索取凭据。请改为：

1. 如果 .env 不存在，则根据模板创建：cp ${SKILL_PATH}/.env.example ${SKILL_PATH}/.env
2. 告知用户编辑 ${SKILL_PATH}/.env 并填写凭据
3. 等待用户确认，然后通过步骤 4 验证

凭据获取方式：

• Spotify：https://developer.spotify.com/dashboard（免费）
• Last.fm：https://www.last.fm/api/account/create（免费）
• Qobuz：需要 Studio/Sublime 订阅
• TIDAL：在 venv 中运行 tiddl auth login 进行 OAuth（无需配置 .env）

步骤 4：验证

bash ${SKILL_PATH}/run.sh status

显示哪些服务处于 READY、DISABLED 或 需要设置 状态。仅使用标记为 READY 的服务。

预检 → 修复表

检查项	修复方法（macOS）	修复方法（Linux）
PYTHON=missing	brew install python3	sudo apt install python3
VENV=missing	bash ${SKILL_PATH}/scripts/setup.sh install	同左
缺少核心依赖项（SPOTIPY、PYLAST 等）	bash ${SKILL_PATH}/scripts/setup.sh install --force	同左
ENV_FILE=missing	cp ${SKILL_PATH}/.env.example ${SKILL_PATH}/.env，然后编辑	同左
Spotify：未配置	编辑 .env：设置 SPOTIFY_CLIENT_ID 和 SPOTIFY_CLIENT_SECRET	同左
Last.fm：未配置	编辑 .env：设置 LASTFM_API_KEY	同左
Qobuz：未配置	编辑 .env：设置 QOBUZ_EMAIL 和 QOBUZ_PASSWORD	同左
TIDAL：未配置	在 venv 中运行 tiddl auth login	同左
Spotify/Last.fm/Qobuz：错误（验证失败）	检查 .env 中的凭据是否正确；如有需要，请从控制面板重新获取	同左
TIDAL：错误（令牌已过期）	在 venv 中运行 tiddl auth refresh 或 tiddl auth login	同左

服务类型

类型	服务	用途
发现	Spotify、Last.fm	搜索、推荐、相似艺人
下载	Qobuz、TIDAL	高音质音频（FLAC、Hi-Res）

降级策略

4 项服务（Spotify、Last.fm、Qobuz、TIDAL）均为可选。运行 status 后，请应用下表：

场景	策略
没有 Last.fm	跳过并继续 — 仅使用 Spotify 进行音乐发现
没有 Spotify	跳过并继续 — 仅使用 Last.fm 进行音乐发现
完全没有音乐发现服务	停止并引导 — 告知用户至少需要一项音乐发现服务，并引导其完成设置
没有 Qobuz	自动回退 — 使用 TIDAL 下载
没有 TIDAL	自动回退 — 使用 Qobuz 下载
完全没有下载服务	仅音乐发现 — 告知用户下载功能不可用，并仅继续使用音乐发现功能

使用回退服务时，请告知用户使用的是哪项服务以及原因。

音乐发现命令

Last.fm — 相似艺人

bash ${SKILL_PATH}/run.sh lastfm_artists "Radiohead"

返回相似艺人列表及匹配分数。

Last.fm — 相似曲目

bash ${SKILL_PATH}/run.sh lastfm_tracks "Karma Police" "Radiohead"

参数：曲目名称，然后是艺人名称。

Last.fm — 品味档案

bash ${SKILL_PATH}/run.sh lastfm_taste

根据收听记录返回用户最常听的艺人和曲目。

Spotify — 搜索

bash ${SKILL_PATH}/run.sh spotify_search "OK Computer"

搜索 Spotify 曲库中的曲目、专辑和艺人。

Spotify — 用户曲库

bash ${SKILL_PATH}/run.sh spotify_user tracks|artists

获取用户已收藏的曲目或关注的艺人（需要 OAuth）。

Spotify — 曲目／专辑信息

bash ${SKILL_PATH}/run.sh spotify_info SPOTIFY_URI_OR_ID

下载命令

搜索平台目录

bash ${SKILL_PATH}/run.sh platform_search "Album Name" -p qobuz|tidal

搜索下载平台的目录。返回可用于下载命令的 ID。

下载（异步 — 立即返回）

bash ${SKILL_PATH}/run.sh platform_download ID -p qobuz|tidal -t album|track

将下载任务加入后台进程的队列，并立即返回 download_id。Agent 可以继续处理其他工作。使用 download_status 轮询进度。

如需阻塞直到下载完成（旧版行为）：

bash ${SKILL_PATH}/run.sh platform_download ID -p qobuz -t album --sync

检查下载状态

bash ${SKILL_PATH}/run.sh download_status DOWNLOAD_ID
bash ${SKILL_PATH}/run.sh download_status --all
bash ${SKILL_PATH}/run.sh download_status --active
bash ${SKILL_PATH}/run.sh download_status --json

轮询特定下载的状态，或列出所有下载。使用 --active 仅显示待处理／进行中的任务。使用 --json 获取结构化输出。

打开下载仪表板

bash ${SKILL_PATH}/run.sh download_ui

打开 http://localhost:8765 的网页仪表板，显示带进度条的实时下载状态。每 3 秒自动刷新。

服务管理

禁用服务

bash ${SKILL_PATH}/run.sh disable_service spotify --reason "No account"

启用服务

bash ${SKILL_PATH}/run.sh enable_service spotify

工作流 — 音乐探索

1. 运行 status，检查可用服务
2. 使用 lastfm_artists 或 lastfm_tracks 查找相似音乐
3. 使用 spotify_search 搜索特定曲目／专辑
4. 以清晰的表格形式向用户展示结果
5. 如果用户想要下载，使用 platform_search → platform_download

工作流 — 下载高解析度音频

开始时打印此清单，并在操作过程中更新：

Download Progress:
- [ ] Step 1: Check service status
- [ ] Step 2: Search platform catalog
- [ ] Step 3: Present results to user
- [ ] Step 4: Start download
- [ ] Step 5: Monitor progress
- [ ] Step 6: Verify completion
- [ ] Step 7: Report results

1. 运行 status，确认下载服务状态为 READY
2. 搜索：platform_search "Album Name" -p qobuz
3. 展示带有音质信息的结果
4. 下载：platform_download ID -p qobuz -t album（立即返回 download_id）
5. 告知用户下载已加入队列；也可选择打开 download_ui 进行可视化监控
6. 使用 download_status DOWNLOAD_ID 轮询，直到下载完成
7. 使用下方的完成报告模板进行汇报

完成报告

下载完成后，向用户展示此报告：

MusicMaster Download Complete!

Input: [album/track] - [title] by [artist]
Platform: [Qobuz/TIDAL]
Quality: [Hi-Res 24-bit / FLAC 16-bit / etc.]

Result:
- Track count: [N tracks]
- Total size: [X MB]
- Download path: [/path/to/files]

Files:
- [file1.flac] (XX MB)
- [file2.flac] (XX MB)
- ...

Next Steps:
- Open folder: open "[download path]"
- Download more: "download [another album]"

从 download_status 输出中收集文件路径和大小，并通过列出下载目录获取相关信息。

错误处理

错误	检测方式	解决方法
缺少 Venv	run.sh 以 venv_missing 退出	运行 bash ${SKILL_PATH}/scripts/setup.sh install
服务未配置	status 显示 NOT CONFIGURED	指引用户编辑 ${SKILL_PATH}/.env（参见 Preflight Check -> Fix Table）
Spotify OAuth 已过期	Spotify 命令因身份验证错误而失败	运行 bash ${SKILL_PATH}/run.sh spotify_auth 重新授权
TIDAL 令牌已过期	status 对 TIDAL 显示 ERROR	在 venv 中运行 tiddl auth refresh 或 tiddl auth login
用户已禁用服务	status 显示 DISABLED	如果用户想重新启用服务，则运行 enable_service
无结果	搜索结果为空	尝试使用不同的关键词，或检查服务是否可用

重要说明

• Spotify 首次使用时需要通过 OAuth 浏览器流程进行授权（spotify_auth 脚本会处理此流程）
• TIDAL 身份验证由 tiddl CLI 工具管理，不存储在 .env 中
• Qobuz 凭据存储在 .env 中（敏感信息 — 确保该文件已列入 .gitignore）
• 下载路径默认为 ~/Music/Qobuz 和 ~/Music/TIDAL
• 音质设置：Qobuz 27=Hi-Res 24 位（最高），TIDAL HiFi=无损