4.3 KiB
4.3 KiB
抖音推荐流视频抓取设计文档
背景
当前系统支持抓取指定博主主页或单视频。现需扩展支持抓取抖音推荐流（For You页面）当前可见的视频。
目标
- 支持抓取抖音推荐流（
https://www.douyin.com/）的视频 - 记录每个视频对应的博主信息
- 支持滚动加载，最多抓取50条
- 视频统一保存到
video/目录 - 保持现有两步式工作流不变
方案选择
采用方案B：新建推荐流专用抓取函数
理由：
- 逻辑清晰，推荐流和博主页完全解耦
- 便于后续分别维护
- 工作量适中，可快速实现验证
详细设计
1. 目标识别扩展
新增推荐流URL识别模式：
RECOMMENDATION_URL_PATTERN = re.compile(
r"^https?://www\.douyin\.com/?(?:\?.*)?$"
)
目标类型扩展为三种：
creator- 博主主页（现有）single-video- 单视频（现有）recommendation- 推荐流（新增）
2. 核心流程
用户执行 ./.venv/bin/python Douyin.py
↓
读取当前浏览器页面URL
↓
判断页面类型：
- 推荐流 → 执行 collect_recommendations()
- 博主页 → 执行 collect_videos()（现有）
- 单视频 → 执行 collect_single_video()（现有）
- 其他 → 报错提示
3. collect_recommendations() 函数
参数：
max_videos: 最大抓取数量（默认50）timeout: 单次等待接口响应秒数（默认10）output_dir: 输出目录（默认video/）browser_port: 浏览器调试端口（默认9223）
行为：
- 通过
page.get("https://www.douyin.com/")打开推荐流页面（复用现有页面打开逻辑，不切换标签页） - 启动监听，目标接口：
web/aweme/post/（推荐流与博主页共用此接口） - 循环直到收集够
max_videos条或无法继续加载：- 等待接口响应
- 解析视频列表，提取：标题、视频ID、视频URL、博主信息
- 过滤已下载（按
video_id去重，使用seen_ids: set[str]集合） - 下载视频
- 向下滚动加载更多
- 返回实际下载数量
4. 数据解析增强
新增博主信息提取字段：
{
"title": "视频标题",
"video_id": "aweme_id",
"video_url": "下载链接",
"author_name": "博主昵称",
"author_id": "博主ID",
}
5. 文件名格式
推荐流视频：
[博主昵称]视频标题-aweme_id.mp4
示例：[张三]搞笑视频-7619989983668240802.mp4
博主页视频（保持现有）：
视频标题-aweme_id.mp4
6. 命令行参数
新增参数：
--max-videos 50 # 推荐流最大抓取数量（默认50）
使用示例：
# 零参数，自动识别当前页面
./.venv/bin/python Douyin.py
# 自定义抓取数量（仅对推荐流有效）
./.venv/bin/python Douyin.py --max-videos 30
# 显式传入URL时，--max-videos 不适用（博主页和单视频页忽略此参数）
./.venv/bin/python Douyin.py "https://www.douyin.com/user/xxx"
7. 错误处理
- 推荐流页面未加载数据：提示用户先滚动加载内容
- 滚动后无新数据：正常结束，返回已下载数量
- 达到最大数量：正常结束
- 其他错误：复用现有错误处理机制
8. 测试覆盖（TDD）
必须覆盖以下测试场景：
- 推荐流URL识别测试
- 推荐流页面解析测试（模拟API响应含博主信息）
- 滚动加载逻辑测试
- 最大数量限制测试
- 文件名构建测试（含博主名）
- 博主信息提取测试
- 去重逻辑测试
非目标
- 自动登录抖音
- 自动过验证码
- 抓取非推荐流页面（如话题页、搜索页）
- 自动筛选视频内容
- 抓取超过50条视频（如需更多，需用户手动调整参数）
验收标准
- 用户可以在推荐流页面执行
./.venv/bin/python Douyin.py抓取视频 - 系统能自动识别当前页面是推荐流
- 支持滚动加载，最多抓取50条
- 文件名包含博主昵称
- 所有测试通过
- 关键失败场景有明确报错
实现步骤
- 编写测试（TDD）
- 实现推荐流URL识别
- 实现
collect_recommendations()函数 - 增强数据解析（提取博主信息）
- 修改文件名构建逻辑
- 更新命令行参数
- 运行全部测试
- 提交代码