抖音视频搜索采集专家

面向内容研究者与数据分析师的本地化抖音采集工具，纯本地运行、不上传任何数据，安全可靠。

🎯 技能使用规范

适用场景

本技能适用于以下场景：

关键词搜索: 通过关键词搜索抖音视频，获取标题、作者、点赞数、评论数等核心指标
用户主页采集: 采集指定抖音用户的主页视频列表及统计数据
分享链接解析: 解析抖音分享链接，提取视频元数据与内容摘要
批量采集: 支持按关键词列表、用户列表进行批量任务执行
多格式导出: 搜索结果与采集数据可导出为 JSON、CSV、Markdown 三种格式

常见用途

"帮我搜索抖音上关于XX的热门视频"
"采集这个抖音博主的所有作品"
"解析一下这个抖音分享链接"
"把这些搜索导出成CSV/表格"
"竞品分析/热门内容研究"
"收集一些教学素材"

前置条件

使用前请确保：

✅ 安装依赖（首次使用）: 在终端中 cd 进入本技能目录，然后运行 pip install -r requirements.txt
✅ 安装浏览器: 首次运行执行 playwright install chromium
✅ 确认Python环境: 运行 python3 --version（需要 Python 3.8+）
✅ 准备Cookie: 部分功能需要有效的抖音登录Cookie（本地保存，绝不上传）

📁 路径与入口

技能目录: {baseDir}/douyin-search-expert/
统一入口: python3 scripts/main.py [命令] [参数]（必须在技能目录下执行）
依赖安装: pip install -r requirements.txt && playwright install chromium
输出目录: 可通过 --output 参数指定，默认为 {技能目录}/output/

🔧 执行规范

详细的操作流程、调用规范、错误处理等，请参考以下文档：

使用指南

该文档定义：

各功能模块的标准调用格式
Cookie 配置与管理方法
批量任务的执行策略与限速建议
错误处理和友好提示机制
数据导出的格式选择与最佳实践

📋 输出产物

严格按照执行规范执行完成后生成：

search: 搜索结果文件（JSON/CSV/Markdown），包含视频标题、作者、播放量、点赞量、评论数、分享链接等
user: 用户主页视频列表，包含作品统计与发布时间线
link: 单条视频元数据摘要（Markdown 格式）
export: 格式转换输出（JSON ↔ CSV ↔ Markdown）

💡 快捷命令速查

依赖安装（首次使用）

pip install -r requirements.txt
playwright install chromium

关键词搜索

# 搜索关键词为"AI教学"的视频，取前20条
python3 scripts/main.py search \
  --keyword "AI教学" \
  --count 20 \
  --preview

# 搜索并导出为CSV
python3 scripts/main.py search \
  --keyword "Python教程" \
  --count 50 \
  --format csv \
  --output ./results/

用户主页采集

# 采集用户主页的最新30个视频
python3 scripts/main.py user \
  --user-id "MS4wLjABAAAAxxxxx" \
  --count 30 \
  --preview

# 采集并导出为JSON
python3 scripts/main.py user \
  --user-id "MS4wLjABAAAAxxxxx" \
  --format json \
  --output ./users/

分享链接解析

python3 scripts/main.py link \
  --url "https://v.douyin.com/xxxxxx/" \
  --preview

# 解析并保存Markdown摘要
python3 scripts/main.py link \
  --url "https://v.douyin.com/xxxxxx/" \
  --format markdown \
  --output ./links/

数据导出（格式转换）

# JSON 转 CSV
python3 scripts/main.py export \
  --input ./results/search.json \
  --format csv \
  --output ./results/search.csv

# CSV 转 Markdown 表格
python3 scripts/main.py export \
  --input ./results/search.csv \
  --format markdown \
  --output ./results/search.md

批量采集

# 从文件读取关键词列表批量搜索
python3 scripts/main.py search \
  --keywords-file ./keywords.txt \
  --count 20 \
  --delay 3 \
  --output ./batch-results/

🗣️ 口语化触发词

当用户提到以下任何说法时，请立即使用本技能：

搜索类

"搜索抖音视频" / "查一下抖音上的XX"
"抖音热门视频" / " trending 内容"
"关键词采集"

用户采集类

"采集某个抖音博主" / "抓取用户主页"
"列出这个用户的所有作品"
"创作者数据分析"

链接解析类

"解析这个抖音链接" / "看看这个分享链接的内容"
"提取视频信息"

批量与导出类

"批量采集抖音视频"
"导出成表格/CSV/Excel"
"生成数据报告"

研究分析类

"竞品分析" / "热门内容研究"
"教学素材收集"
"内容趋势分析"

🚨 重要限制（明令禁止）

禁止上传任何数据: 所有采集、处理、存储均在本机完成，绝不向任何云端服务上传数据
仅供学习研究: 本工具仅用于学习与研究目的禁止用于商业用途或任何违反平台服务协议的行为
禁止高频请求: 请严格遵守限速建议（默认每次请求间隔 ≥ 3 秒），禁止绕过限速机制
禁止突破数据使用边界: 不得采集个人隐私信息（手机号、地址等公开不可见的内容），仅采集公开元数据
Cookie安全管理: Cookie 仅保存在本地配置目录，不得明文打印到日志中
禁止技术错误输出: 错误信息必须翻译为用户可理解的语言
- ❌ 错误: playwright._impl._errors.TimeoutError: Timeout 30000ms exceeded
- ✅ 正确: "页面加载超时，请检查网络连接或稍后重试"
- ❌ 错误: FileNotFoundError: [Errno 2] No such file
- ✅ 正确: "找不到指定的文件，请检查路径是否正确"
- ❌ 错误: Cookie expired or invalid
- ✅ 正确: "登录Cookie已过期，请刷新Cookie后重试"

📚 参考文档

完整操作指南请参考以下文档：

使用指南 - 完整功能列表与调用示例
Cookie配置 - Cookie获取、保存与刷新指南
故障排除 - 常见问题与解决方案