添加抖音推荐流抓取设计文档

2026-05-06 16:57:52 +08:00 · 2026-05-06 16:57:52 +08:00 · 4b14586a91
commit 4b14586a91
parent 321bbff1c1
1 changed files with 165 additions and 0 deletions
--- a/docs/superpowers/specs/2026-05-06-douyin-recommendation-crawling-design.md
+++ b/docs/superpowers/specs/2026-05-06-douyin-recommendation-crawling-design.md
@ -0,0 +1,165 @@
+# 抖音推荐流视频抓取设计文档
+
+## 背景
+
+当前系统支持抓取指定博主主页或单视频。现需扩展支持抓取抖音推荐流（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. 提交代码