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