Agent Skills › binggandata/bggg-skills › bggg-tiktok-downloader

bggg-tiktok-downloader

GitHub

用于将 TikTok 视频或博主作品批量下载至本地，支持单视频及主页抓取，优先使用 yt-dlp 并兼容 Cookie 登录。

bggg-tiktok-downloader/SKILL.md binggandata/bggg-skills

Trigger Scenarios

用户请求下载 TikTok 视频用户提供 TikTok 博主主页链接并要求下载作品

Install

npx skills add binggandata/bggg-skills --skill bggg-tiktok-downloader -g -y

More Options

Non-standard path

npx skills add https://github.com/binggandata/bggg-skills/tree/main/bggg-tiktok-downloader -g -y

Use without installing

npx skills use binggandata/bggg-skills@bggg-tiktok-downloader

指定 Agent (Claude Code)

npx skills add binggandata/bggg-skills --skill bggg-tiktok-downloader -a claude-code -g -y

安装 repo 全部 skill

npx skills add binggandata/bggg-skills --all -g -y

预览 repo 内 skill

npx skills add binggandata/bggg-skills --list

SKILL.md

Frontmatter

{
    "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 的链接识别规则；没有该目录也可以运行。

工作流

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