hifi-download 是一个面向音乐发现与高保真音频下载的命令行技能工具，通过统一 CLI 将发现类服务（Spotify、Last.fm）与下载类服务（Qobuz、TIDAL）整合在一起，所有命令以 bash ${SKILL_PATH}/run.sh <script> [args...] 形式调用，该脚本会激活虚拟环境并运行对应 Python 脚本。所有脚本默认向 stdout 输出结构化 JSON，可使用 --format text 获得人类可读输出；错误以 JSON 形式输出到 stderr，退出码 1 表示可恢复错误，2 表示不可恢复错误。
【首次配置】 第一步检查依赖：bash ${SKILL_PATH}/scripts/setup.sh check，输出为 key=value 对（注意这是 shell 脚本而非 Python 脚本），若 VENV=missing 需先安装。 第二步安装：bash ${SKILL_PATH}/scripts/setup.sh install [--with-qobuz] [--with-tidal]，创建 .venv，安装核心依赖（spotipy、pylast、requests、python-dotenv），并可选安装下载后端。 第三步配置凭据：文档明确要求不要在聊天中向用户索要凭据，而是先复制 ${SKILL_PATH}/.env.example 为 ${SKILL_PATH}/.env，让用户自行编辑，等待确认后再验证；也可使用 bash ${SKILL_PATH}/run.sh setup_config --lastfm-key=KEY [--spotify-id=ID --spotify-secret=SECRET] [--qobuz-email=EMAIL --qobuz-password=PASS]。凭据获取方式：Spotify 通过 https://developer.spotify.com/dashboard（免费），Last.fm 通过 https://www.last.fm/api/account/create（免费），Qobuz 需 Studio/Sublime 订阅，TIDAL 需在 venv 中运行 tiddl auth login 完成 OAuth。 第四步验证：bash ${SKILL_PATH}/run.sh status，返回包含 discovery 与 downloads 两部分的 JSON，显示各服务状态（ready、disabled、not_configured、error），仅应使用 "available": true 的服务。
【服务类型】 发现类：Spotify、Last.fm，用于搜索、推荐、相似艺人。下载类：Qobuz、TIDAL，用于获取高品质音频（FLAC、Hi-Res）。
【发现命令】 Last.fm 相似艺人：bash ${SKILL_PATH}/run.sh lastfm_artists "Radiohead"，返回 results 数组（name、match 分数、URL）。 Last.fm 相似曲目：bash ${SKILL_PATH}/run.sh lastfm_tracks "Karma Police" "Radiohead"，参数为曲目名与艺人名。 Last.fm 品味画像：bash ${SKILL_PATH}/run.sh lastfm_taste，分析 Spotify 收听历史并返回 similar_artists 与 similar_tracks。 Spotify 搜索：bash ${SKILL_PATH}/run.sh spotify_search "OK Computer"，返回曲目/专辑/艺人详情。 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 的 results 数组。 异步下载：bash ${SKILL_PATH}/run.sh platform_download ID -p qobuz|tidal -t album|track，后台排队并立即返回 download_id；如需阻塞等待完成可加 --sync。 查询下载状态：bash ${SKILL_PATH}/run.sh download_status DOWNLOAD_ID，或 --all 列出全部，--active 仅显示待处理/进行中任务。 打开下载仪表盘：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。
【工作流】 音乐发现：先运行 status 检查可用服务，用 lastfm_artists 或 lastfm_tracks 找相似音乐，用 spotify_search 查找特定曲目/专辑，以清晰表格呈现结果，如需下载则 platform_search → platform_download。 高保真下载：先 status 确认下载服务为 READY，platform_search "Album Name" -p qobuz 搜索并展示含音质信息的结果，platform_download ID -p qobuz -t album 立即返回 download_id，随后在后台打开 download_ui 让用户查看实时进度（该仪表盘为长驻服务器进程，需在后台运行，否则会阻塞），并告知用户文件将出现在默认下载目录（~/Music/Qobuz 或 ~/Music/TIDAL）。文档强调不要循环轮询 download_status，仪表盘负责进度可视化，除非用户明确要求检查。
【错误处理】 虚拟环境缺失时 run.sh 以 venv_missing 退出，需运行 setup.sh install；服务未配置时 status 显示 not_configured，需引导用户编辑 .env 或运行 setup_config；Spotify OAuth 过期时 stderr 返回认证错误（退出码 1），运行 spotify_auth 重新授权；TIDAL token 过期时 status 显示 tidal 为 error，运行 tiddl auth refresh 或 tiddl auth login；服务被用户禁用时显示 disabled，可用 enable_service 重新启用；无结果时 JSON 返回空数组与 total 0，可更换关键词或检查服务可用性；不可恢复错误返回 recoverable 为 false（退出码 2），需修复根因。
【注意事项】 Spotify 首次使用需 OAuth 浏览器流程（由 spotify_auth 脚本处理）；TIDAL 认证由 tiddl CLI 管理，不存储在 .env；Qobuz 凭据存于 .env（敏感，应确保文件在 .gitignore 中）；默认下载路径为 ~/Music/Qobuz 与 ~/Music/TIDAL；音质设置方面，Qobuz 27 表示 Hi-Res 24-bit（最高），TIDAL HiFi 表示无损。