Mixkit 免费音乐下载
帮用户从 mixkit.co（Envato 旗下免费素材站）下载曲目。核心价值：
1. 受限网络下直连完整下载必超时，本技能内置 Range 分块下载方案。
2. 页面解析有固定套路，不要现写正则试错。
授权要点（主动告知用户）
Mixkit Stock Music Free License：免费商用、无需署名，可用于商品视频/广告/Vlog。
详情页: https://mixkit.co/license/#musicFree
工作流
Step 1 判断输入类型
| 输入 | 动作 |
|---|---|
| mixkit.co 列表页/分类页/标签页 URL | 直接进 Step 2 |
| 明确曲名 | 先定位曲目（见 Step 1b） |
| 风格描述（如"舒缓的背景音乐"） | 拼分类页 URL，如 /free-stock-music/ambient/、/mood/calm/、/tag/corporate/，进 Step 2 |
Step 1b 定位曲名的坑：
- Mixkit 站内搜索 ?query=xxx 不生效（返回默认推荐列表），不要用它。
- 曲名带括号副标题（如 "Calm Corporate Background (Soft Ambient)"）很可能是 AI 对话中自拟的描述性名字，实际不存在。先用 web 搜索验证曲名是否真实存在于 Mixkit/Pixabay，不要瞎猜直链编号。
- 若确认不存在，向用户说明，并给出 Mixkit 上真实存在的相似曲目清单。
Step 2 解析曲目清单
python3 <skill_dir>/scripts/mixkit_music.py list "https://mixkit.co/free-stock-music/ambient/"
输出 编号. 曲名 | 作者 | 时长 | 直链。解析原理（脚本已内置，仅排查时用）：
- 抓页面必须带浏览器 User-Agent。
- 不要用 JSON-LD（只覆盖部分曲目）；脚本按 data-audio-player-preview-url-value= 切块逐块提取，卡片元素才是全量，按直链去重。
- MP3 直链即完整文件，无需登录：https://assets.mixkit.co/music/<id>/<id>.mp3。
Step 3 确认下载范围
- 用户指定单曲 → 直接下载。
- 用户给链接说"下载这个音乐"但页面有多首 → 必须先把编号清单发给用户选择，不要擅自下载全部（36 首 ≈ 150MB）。
- 估算耗时告知用户：实测 1MB ≈ 12s（85KB/s），如 4MB 单曲约 1 分钟。
Step 4 下载
# 单曲
python3 <skill_dir>/scripts/mixkit_music.py download "https://assets.mixkit.co/music/749/749.mp3" -o "Relaxation 05 - Lily J.mp3"
# 批量（按 list 输出的编号）
python3 <skill_dir>/scripts/mixkit_music.py batch "https://mixkit.co/free-stock-music/ambient/" -n 1,5,8 -d ./mixkit_music/
为什么必须分块：完整 GET 会在 60s 内被 CDN 重置长连接而超时。脚本已内置
Range 1MB/块 + 3 次重试 + 进度输出，不要改用 curl 全量下载。
Step 5 校验
python3 <skill_dir>/scripts/mixkit_music.py verify "Relaxation 05 - Lily J.mp3" --expect-dur 1:58
- MP3 头检查 + ffprobe 时长对比页面标注（偏差 ≤2s 即完整）。
- 无 ffprobe 的环境只做头检查，并提示用户人工试听确认。
Step 6 交付
- 清理临时文件（测试下载的残片、缓存的 HTML）。
- 当前运行环境：把下载链接交给用户，链接必须贴在回复正文。
- 其他环境（codex/本地）：直接给出文件绝对路径。
- 回复中包含：曲名/时长/规格、来源、授权说明（可商用免署名）。
踩坑速查
| 现象 | 原因与解法 |
|---|---|
| 完整下载 60s 超时 | CDN 重置长连接，用脚本分块下载，勿用 curl 全量 |
| 页面解析 0 首 | URL 是搜索页（query 参数不生效）或被反爬，换分类页 URL |
| 找不到某个曲名 | 曲名可能是 AI 编的，web 搜索验证存在性 |
| 单块反复重试失败 | 网络波动，脚本自动重试 3 次；连续失败则报错停止，勿死循环 |
示例
例 1：用户："https://mixkit.co/free-stock-music/ambient/ 下载一下这个音乐"
→ list 解析出 36 首 → 把编号清单发给用户选择 → 用户选 5 → download → verify → 交付文件。
例 2：用户："下载 Calm Corporate Background (Soft Ambient)"
→ web 搜索确认无此曲名（AI 自拟）→ 告知用户并给相似曲目（如 Valley Sunset、Smooth Meditation、Serene View、Charlotte）→ 用户选定后下载。
例 3：用户："要一段轻快的电商产品视频背景音乐，可商用"
→ 拼 URL https://mixkit.co/free-stock-music/mood/happy/ 或 /tag/corporate/ → list → 用户挑选 → batch 下载 → verify → 交付并附授权说明。
运行环境
- 脚本：
scripts/mixkit_music.py（相对技能根目录） - Python：3.9+
- 外部命令：
ffprobe
开工前先跑一次自检，缺什么当场补，别等跑到一半报错：
command -v ffprobe >/dev/null 2>&1 || echo "缺 ffprobe，请先安装再重试"
> 缺依赖时用中文告诉用户缺什么、装完就能用，不要把 Python 的英文 traceback 原样贴给用户。
