tiktok-music-archive-downloader

TikTok 音乐档案下载器

在 TikTok 音乐或声音候选项已选定，且用户需要本地样本文件、音频参考和可复现的档案清单后，使用此技能。

应用 postplus-shared 中的本地依赖和用户指导规则。

不适用场景

• 用户仍在寻找热门音乐。请从 tiktok-research 开始。
• 用户需要收集托管的 TikTok 元数据。
• 用户询问某段音频是否已获得公开发布所需的合法授权。

必需输入

• 包含 TikTok 帖子页面 URL 的简短下载清单。
• 本地依赖：带有 yt_dlp 的 python3，以及 ffmpeg。
• 可在 .postplus/ 下写入档案的工作文件夹。

当规范化的上游数据集同时包含 postPageUrl 和直接视频字段时，优先将规范的 TikTok 帖子页面 URL 用作 sourceUrl。

访问边界

只有在通过依赖检查后，用户当前本地浏览器/IP 环境可访问的 TikTok 帖子 URL 才支持下载。仅有本地工具并不足以保证下载成功，因为 TikTok 可能基于 IP、浏览器访问、登录状态或 Cookie 限制帖子访问。

如果下载报告包含 failureCode: "tiktok_ip_blocked"，请报告此限制，并保留 sourceUrl、stderr 和报告路径。不要重试大范围下载、切换代理，或编造 Cookie/浏览器引导流程。

默认工作流

1. 根据选定的视频或声音构建一份范围有限的清单。
2. 运行共享下载器：

  --manifest <download-manifest.json> \
  --output-dir <videos-dir> \
  --report <download-report.json> \
  --concurrency 2 \
  --attempts 3

3. 遇到下载限制时，停止后续音频提取。
4. 使用 ffmpeg 从成功下载的文件中提取音频。
5. 编写一个 index.json，将每个本地文件关联到 musicId、 musicTitle、sourceVideoUrl、源集合路径、下载状态、 本地视频路径和本地音频路径。

档案布局

使用：

<work-folder>/.postplus/tiktok-music-archive-downloader/<run-id>/
  manifest/
  videos/
  audio/
  index.json

仅当用户需要检查或转交最终档案摘要或所选导出内容时，才将其保存在 .postplus/ 之外。

验证

• 确认已下载的文件存在且非空。
• 确认音频文件存在且非空。
• 单独报告失败，不要将其隐藏。
• 即使下载失败，也要在清单中保留源 URL。
• 如果某组来源因 TikTok 访问限制而被阻止，不要继续提取音频。

权利说明

除非用户确认已获得相关权利或可通过平台授权使用，否则应将下载的 TikTok 音乐视为研究或参考资料。不要声称提取的音频已获准用于商业再利用。

后续处理

• 需要更多 TikTok 音乐或来源候选项 -> tiktok-research。
• 需要视频级别的分析 -> video-analysis。
• 需要转录或提取语音 -> audio-transcription 或 video-transcription。

公共命令边界

• 根据用户输入选择最匹配且范围最小的命令或工作流，并直接运行。
• 如果自有 CLI 或脚本命令失败，请报告确切错误并停止。不要通过仅提供元数据的回答、就绪状态探测、本地负载改写、备用提供方或未发布工具来绕过失败。
• 仅在构建或修复未知请求格式时使用 postplus research schema --collection-key <collection-key> --json。
• 托管集合：postplus research collect --skill tiktok-music-archive-downloader --collection-key <collection-key> --input <hosted-envelope.json> --output <collection-result.json>。
• 恢复待处理的集合：postplus research collect --run-handle <runHandle> --output <collection-result.json>。
• 首轮操作应限制范围；检查首轮结果后再扩大范围。
• 如果 CLI 返回报价确认质询，请运行 postplus quote confirm --json --challenge-file <challenge.json>，然后使用返回的令牌重试。