bggg-tiktok-downloader

name	bggg-tiktok-downloader
description	下载 TikTok 视频到本地。当用户给出 TikTok 单个视频链接、分享链接、视频链接文本、 TikTok 博主主页链接、@handle，并要求下载、保存、抓取、批量下载、下载博主作品、 下载指定数量或下载全部作品时，使用此 skill。优先用 yt-dlp，单视频下载失败时用 tikwm 兜底； 可选引用本地 TikTokDownloader 作为链接类型识别辅助。

BGGG TikTok Downloader

目标

把 TikTok 视频下载到本地项目目录。优先使用随 skill 捆绑的确定性脚本：

python3 bggg-tiktok-downloader/scripts/download_tiktok.py "<TikTok URL>"

脚本优先使用 yt-dlp 负责单视频和博主列表下载；单视频在 yt-dlp 不可用或失败时使用 tikwm 兜底。若设置 TIKTOKDOWNLOADER_ROOT 或传 --tiktokdownloader-root，脚本会尝试引用本地 TikTokDownloader 的链接识别规则；没有该目录也可以运行。

工作流

1. 识别输入类型：
   • 包含 /video/ 或 /photo/ 的 TikTok 链接按单个作品处理。
   • https://www.tiktok.com/@username 这类主页链接按博主处理。
   • 用户指定“下载 N 条/前 N 个/最新 N 个”时传 --limit N。
   • 用户说“全部”或只给博主链接且无数量时传 --limit 0，表示不限制数量。
2. 选择输出目录。默认是本 skill 下的 projects/downloads/tiktok；用户指定目录时传 --output-dir。
3. 运行脚本并查看 JSON 输出里的 manifestPath、itemCount 和 items[].filePath。
4. 如果后续要转写音轨，把输出的视频目录交给 bggg-tiktok-readvideo。

常用命令

下载单个视频：

python3 bggg-tiktok-downloader/scripts/download_tiktok.py "https://www.tiktok.com/@user/video/1234567890123456789" --thumbnail

下载某博主前 30 个视频：

python3 bggg-tiktok-downloader/scripts/download_tiktok.py "https://www.tiktok.com/@user" --mode author --limit 30 --thumbnail

下载某博主全部可见视频：

python3 bggg-tiktok-downloader/scripts/download_tiktok.py "https://www.tiktok.com/@user" --mode author --limit 0 --thumbnail

需要登录态时，可以显式使用浏览器 Cookie：

python3 bggg-tiktok-downloader/scripts/download_tiktok.py "https://www.tiktok.com/@user" --mode author --limit 20 --cookies-browser chrome

注意事项

• 只下载用户有权保存和处理的内容。遇到私密账号、地区限制或风控时，需要用户提供可用 Cookie。
• 不要提交 Cookie 文件、浏览器 profile、下载结果、.info.json 或采集 manifest 到公开仓库。
• 作者批量下载依赖 yt-dlp；单视频可走 tikwm 兜底。
• 输出目录内会生成 .bggg-tiktok-download-archive.txt 跳过重复视频，以及 download_manifest.json 记录结果。

更多实现细节按需读取 references/implementation-notes.md。