From 46499446b2ee59a6ba58b584f034d9eb7f2b18da Mon Sep 17 00:00:00 2001
From: wangshaoqing <wangshaoqing@intelligrow.cn>
Date: Wed, 6 May 2026 18:53:51 +0800
Subject: [PATCH] docs: rewrite README for beginners with two download methods

---
 README.md | 255 +++++++++++++++++++++++++++++++++++++++++-------------
 1 file changed, 197 insertions(+), 58 deletions(-)

diff --git a/README.md b/README.md
index 61eebf0..292ff0f 100644
--- a/README.md
+++ b/README.md
@@ -1,97 +1,236 @@
-# 抖音视频爬取工具
+# 抖音视频下载工具（中学生也能看懂版）
 
-这是一个面向 macOS 的抖音视频下载项目。
+## 这个工具能做什么？
 
-它当前采用“两步式”方式工作：
+帮你下载抖音上的视频！支持两种方式：
 
-1. 先启动一个可见的 Chrome 浏览器，让你手动登录抖音并完成验证码
-2. 再让脚本附着到这个浏览器，抓取博主主页当前已加载的作品视频并下载到本地
+1. **下载推荐页视频** - 就像你打开抖音看到的首页视频流
+2. **下载某个博主的主页视频** - 下载你喜欢的博主发布的视频
 
-这个项目已经完成过真实验证：在本机登录成功后，可以正常下载视频到 `video/` 目录。
+## 你需要准备什么？
 
-## 适合谁使用
+- 一台 Mac 电脑
+- 已经下载了这个项目到本地
+- 一点点耐心（需要手动登录抖音）
 
-适合以下用户：
+## 重要提醒
 
-- 使用 Mac
-- 项目已经在本地
-- 想快速下载某个抖音博主主页当前可见的作品视频
+- 不能自动登录抖音（需要你手动扫码或输入密码）
+- 不能自动过验证码（遇到验证码需要你自己点）
+- 只能下载当前页面上已经显示的视频（不会自动翻页下载全部历史视频）
 
-## 当前能做什么
+---
 
-- 启动一个带调试端口的 Chrome 浏览器
-- 手动登录抖音后附着到浏览器
-- 自动识别当前浏览器页面是博主主页还是单视频页
-- 抓取某个博主主页当前已加载的作品
-- 下载当前单视频页对应的那一条视频
-- 下载视频到本地 `video/` 目录
-- 支持传入指定博主主页 URL、单视频 URL 或 `aweme_id`
+## 第一次使用（安装环境）
 
-## 当前不能做什么
-
-- 不能自动帮你登录抖音
-- 不能自动替你过验证码
-- 不能默认抓完整个博主的全部历史作品
-- 不能抓任意网页
-- 不能自动筛选你想要的视频
-
-## 快速开始
-
-如果你已经把项目下载到本地，最快的使用方式是：
+打开终端（Terminal），依次输入以下命令：
 
 ```bash
+# 1. 进入项目文件夹
 cd /你的项目目录/douyin-crawler-poc
+
+# 2. 创建虚拟环境（隔离项目依赖）
 python3 -m venv .venv
+
+# 3. 激活虚拟环境
 source .venv/bin/activate
+
+# 4. 安装需要的库
 pip install requests DrissionPage
-./.venv/bin/python login_douyin.py
-./.venv/bin/python Douyin.py
 ```
 
-说明：
+**什么是虚拟环境？** 就像给这个项目建了一个独立的房间，里面放的工具不会影响电脑其他地方。
 
-- 第一个命令用于创建虚拟环境
-- 第二个命令用于进入虚拟环境
-- 第三个命令用于安装依赖
-- 第四个命令会打开 Chrome，让你登录抖音
-- 第五个命令会读取你当前浏览器页面并自动开始抓取或下载
+---
 
-如果自动判断失败，也可以手动传入一个目标：
+## 使用方法一：下载推荐页视频（首页视频流）
+
+### 步骤 1：启动浏览器并登录抖音
 
 ```bash
-./.venv/bin/python Douyin.py "https://www.douyin.com/user/你的博主主页"
-./.venv/bin/python Douyin.py "https://www.douyin.com/video/某个视频ID"
+./.venv/bin/python login_douyin.py
+```
+
+运行后会发生什么：
+- 会自动打开 Chrome 浏览器
+- 浏览器会显示抖音登录页面
+- **你需要手动登录**（扫码或输入账号密码）
+- 如果遇到验证码，也需要手动完成
+
+### 步骤 2：下载视频
+
+登录成功后，在终端输入：
+
+```bash
+# 下载默认数量（50个视频）
+./.venv/bin/python Douyin.py
+
+# 或者只下载10个视频
+./.venv/bin/python Douyin.py --max-videos 10
+
+# 或者只下载3个视频（测试用）
+./.venv/bin/python Douyin.py --max-videos 3
+```
+
+**注意：** 下载前请确保浏览器显示的是抖音推荐页（就是打开抖音看到的第一个页面，有很多视频往下滚动的那种）。
+
+---
+
+## 使用方法二：下载某个博主的主页视频
+
+### 步骤 1：同样先启动浏览器并登录
+
+```bash
+./.venv/bin/python login_douyin.py
+```
+
+### 步骤 2：进入博主主页
+
+在浏览器中：
+1. 搜索你想下载的博主（比如某个美食博主）
+2. 点击进入他的主页
+3. 等待页面加载完成（看到博主的视频列表）
+
+### 步骤 3：下载视频
+
+在终端输入：
+
+```bash
+# 下载当前页面显示的视频（默认只下载当前页）
+./.venv/bin/python Douyin.py
+
+# 或者下载多页（自动向下滚动加载）
+./.venv/bin/python Douyin.py --pages 3
+```
+
+**注意：** `--pages 3` 表示滚动加载3页，但抖音可能会限制，不一定能下载到那么多。
+
+---
+
+## 方法三：直接下载单个视频
+
+如果你只想下载某一个具体的视频：
+
+```bash
+# 方法 A：通过视频链接下载
+./.venv/bin/python Douyin.py "https://www.douyin.com/video/视频ID"
+
+# 方法 B：直接通过视频ID下载
 ./.venv/bin/python Douyin.py "7619989983668240802"
 ```
 
-## 下载结果在哪里
+---
 
-抓取成功后，视频会保存到项目根目录下的 `video/` 文件夹。
+## 下载的视频在哪里？
 
-文件名格式一般是：
+所有下载的视频都会保存在项目文件夹里的 `video/` 文件夹中。
 
-```text
-视频标题-aweme_id.mp4
+文件名格式：
+
+```
+[博主昵称]视频标题-视频ID.mp4
 ```
 
-## 详细图文说明
+例如：
+```
+[小张一人食]花2XXX在汕头喝白粥...-7633717884061725297.mp4
+[相声老司机]春晚不好看？...-7606185972144901412.mp4
+```
 
-详细操作步骤请看这份手册：
+---
+
+## 常见问题
+
+### Q1：运行时报错 "缺少 requests" 或 "缺少 DrissionPage"
+
+**解决：** 没有安装依赖，运行：
+```bash
+pip install requests DrissionPage
+```
+
+### Q2：提示 "当前页面不是受支持的抖音页面"
+
+**解决：** 
+- 如果要用推荐页：确保浏览器显示的是抖音首页（有视频流往下滚动的页面）
+- 如果要用博主页：确保你在某个博主的主页
+
+### Q3：下载了0个视频
+
+**解决：**
+- 检查是否已登录抖音
+- 检查当前页面是否有视频显示
+- 等待页面完全加载后再运行下载命令
+
+### Q4：Chrome 浏览器没打开
+
+**解决：**
+- 确保你用的是 Mac
+- 确保已安装 Google Chrome
+- 检查是否有其他 Chrome 正在运行，先关闭再试
+
+### Q5：我想下载更多视频怎么办？
+
+**推荐页：**
+```bash
+./.venv/bin/python Douyin.py --max-videos 100
+```
+
+**博主页：**
+```bash
+./.venv/bin/python Douyin.py --pages 5
+```
+
+---
+
+## 所有可用命令汇总
+
+```bash
+# 查看所有参数说明
+./.venv/bin/python Douyin.py --help
+
+# 推荐页下载（默认50个）
+./.venv/bin/python Douyin.py
+
+# 推荐页下载（指定数量）
+./.venv/bin/python Douyin.py --max-videos 20
+
+# 博主页下载（默认当前页）
+./.venv/bin/python Douyin.py
+
+# 博主页下载（多页）
+./.venv/bin/python Douyin.py --pages 3
+
+# 单视频下载
+./.venv/bin/python Douyin.py "https://www.douyin.com/video/xxx"
+
+# 修改等待时间（如果网络慢）
+./.venv/bin/python Douyin.py --timeout 20
+
+# 修改保存位置
+./.venv/bin/python Douyin.py --output-dir 我的视频
+```
+
+---
+
+## 详细图文教程
+
+如果你还是不太明白，可以查看这份更详细的图文教程：
 
 [小白图文操作手册](/Users/wangshaoqing/Desktop/MiaoSi/Study/douyin-crawler-poc/externaldocs/beginner-guide.md)
 
-如果你完全不会代码，建议直接从这份手册开始照着做。
+---
 
-## 相关文档
+## 技术说明（给感兴趣的同学）
 
-- [当前抓取能力需求说明](/Users/wangshaoqing/Desktop/MiaoSi/Study/douyin-crawler-poc/externaldocs/2026-04-17-readme-and-beginner-guide-requirements.md)
-- [后续定向抓取需求说明](/Users/wangshaoqing/Desktop/MiaoSi/Study/douyin-crawler-poc/externaldocs/2026-04-17-douyin-targeted-crawling-requirements.md)
+这个工具使用了两步式工作流：
 
-## 当前验证状态
+1. **login_douyin.py** - 启动带调试端口的 Chrome，让你手动登录
+2. **Douyin.py** - 附着到已登录的浏览器，监听抖音的 API 请求，提取视频地址并下载
 
-当前项目已验证：
+为什么需要手动登录？因为抖音有反爬虫机制，自动登录容易被封。
 
-- 单元测试通过
-- 登录浏览器入口可用
-- 抖音抓取脚本可附着到浏览器
-- 成功下载出 mp4 文件
+---
+
+## 免责声明
+
+本工具仅供学习交流使用，请勿用于商业用途或侵犯他人权益。下载的视频版权归原博主所有。