douyin-crawler-poc/externaldocs/2026-04-17-douyin-targeted-crawling-requirements.md

Douyin Targeted Crawling Requirements

Goal

在现有“登录浏览器后附着抓取”的基础上，扩展为支持更明确的目标选择能力，使系统不仅能抓默认博主主页，还能：

• 指定某个博主主页进行抓取
• 直接抓当前浏览器里正在查看的博主主页
• 指定某个单独视频进行抓取

本需求文档只定义需求、范围、交互、错误处理和 TDD 约束，不直接定义实现细节代码。

Current Behavior

当前系统具备以下行为：

• 通过 login_douyin.py 启动可见 Chrome，并开启调试端口
• 通过 Douyin.py 附着到该浏览器
• 打开某个博主主页 URL
• 监听抖音作品列表接口 web/aweme/post/
• 从接口返回的 aweme_list 中提取视频地址并下载

当前默认目标是一个硬编码博主主页，但也支持在命令行传入另一个博主主页 URL。

Target Modes

新版本必须同时支持以下三种目标模式：

1. creator-url

用户显式传入某个博主主页 URL，系统以该博主主页为目标进行抓取。

2. current-creator

系统直接读取当前已附着浏览器正在查看的页面。如果当前页面是博主主页，则以该页面为目标进行抓取。

3. single-video

用户传入单个视频链接或 aweme_id，系统仅下载这一条视频，不执行博主作品列表抓取。

Scope Rules

Creator Targets

当目标是博主时，默认只抓“当前页面中已加载、当前可见范围对应的作品”。

这意味着：

• 不默认自动抓完整个博主全部作品
• 不默认自动多页翻完所有历史内容
• 不自动替用户点击筛选器或改动页面状态
• 如果用户已经在页面里手动做了筛选、切换或滚动，则抓取结果以当前页面已加载状态为准

Single Video Target

当目标是单视频时：

• 若输入是视频 URL，系统需要先解析出对应作品标识
• 若输入是 aweme_id，系统直接按单作品逻辑抓取
• 最终只下载一条视频

Recommended User Experience

保留现有两步模式，不改成自动登录的一体化入口：

Step 1

先启动登录浏览器：

./.venv/bin/python login_douyin.py

Step 2

登录完成后，再运行抓取命令。

未来命令行接口应支持显式目标模式，例如：

./.venv/bin/python Douyin.py --mode creator-url --target "https://www.douyin.com/user/..."
./.venv/bin/python Douyin.py --mode current-creator
./.venv/bin/python Douyin.py --mode single-video --target "https://www.douyin.com/video/..."
./.venv/bin/python Douyin.py --mode single-video --target "7619989983668240802"

上面只是推荐交互形态，具体参数名可在实现设计阶段微调，但必须满足以下原则：

• 模式必须显式可区分
• “当前浏览器页面”与“传入 URL”不能混淆
• 单视频目标与博主目标不能混淆

Functional Requirements

Requirement A: Explicit Creator URL Crawling

系统必须允许用户通过博主主页 URL 指定抓取目标。

完成条件：

• 系统接受有效博主主页 URL
• 浏览器打开或切换到该 URL
• 系统只抓当前页面已加载的作品

Requirement B: Current Browser Creator Crawling

系统必须允许用户不手输目标 URL，而是直接抓当前浏览器页面对应的博主主页。

完成条件：

• 系统能读取当前浏览器页面 URL
• 若当前页面是博主主页，则正常抓取
• 若当前页面不是博主主页，则明确报错并退出

Requirement C: Single Video Download

系统必须允许用户通过单个视频链接或 aweme_id 只下载一个视频。

完成条件：

• 支持视频 URL 输入
• 支持 aweme_id 输入
• 最终只落地一个视频文件

Requirement D: Visible-Only Creator Scope

当目标是博主时，系统默认只处理当前页面已经加载出来的作品。

完成条件：

• 不自动继续滚动抓到所有历史内容
• 抓取范围受当前页面加载状态约束
• 用户先手动筛选、滚动、切换后，再执行抓取时，系统按当前页面状态工作

Error Handling Requirements

系统必须提供明确错误，不允许模糊失败。

Current Creator Errors

• 当前页面不是博主主页：报错并退出
• 当前页面虽然像博主页，但未加载出可用作品数据：提示用户先完成页面操作后重试

Single Video Errors

• 输入既不是合法视频 URL，也不是合法 aweme_id：报错并退出
• 视频标识无法解析：报错并退出

Browser Attachment Errors

• 调试端口不可用：提示先运行登录脚本并确认浏览器仍在运行

Creator URL Errors

• 传入 URL 不是受支持的抖音博主主页：报错并退出

Non-Goals

本次需求明确不包含以下内容：

• 任意网页抓取
• 非抖音站点抓取
• 自动替用户点击页面筛选器
• 自动抓完整个博主全部历史作品
• 自动搜索博主
• 自动在抖音站内执行复杂导航流程

Terminology

aweme

抖音接口中的作品对象，可以理解为一条内容或一个视频作品实体。

aweme_id

抖音作品的唯一标识。

current visible videos

指当前页面已经加载出来，并能够通过当前页面对应接口响应获得的作品集合，而不是博主的全量历史作品。

TDD Requirements

本需求后续实现必须使用 TDD。

Mandatory Process

1. 先写失败测试
2. 先验证测试是因为功能未实现而失败
3. 再写最小实现让测试通过
4. 最后再做必要重构

Required Test Areas

至少覆盖以下测试：

• creator-url 模式下，合法博主主页 URL 能被识别并生成正确抓取目标
• current-creator 模式下，当前页面是博主主页时可抓取
• current-creator 模式下，当前页面不是博主主页时明确报错
• single-video 模式支持视频 URL
• single-video 模式支持 aweme_id
• 创作者抓取默认只处理当前已加载内容，不自动继续翻页
• 目标模式错误时的报错路径
• 浏览器端口不可用时的报错路径

Acceptance Criteria

需求完成后，应满足以下验收标准：

1. 用户可以显式指定博主主页 URL 抓取
2. 用户可以直接抓当前浏览器中的博主主页
3. 用户可以指定单个视频 URL 或 aweme_id 下载单条视频
4. 当目标是博主时，默认只抓当前页面已加载作品
5. 关键失败场景都有明确报错
6. 实现过程遵循 TDD，并有对应自动化测试覆盖