xbuilderlab--cheat-on-content
wehub-resource-sync
123 行
5.6 KiB
Markdown
123 行
5.6 KiB
Markdown
# Adapter: douyin-session（抖音爬取）
|
||
|
||
被 `/cheat-retro` 在 `state.data_collection=adapter` + `platform=douyin` 时自动调用。
|
||
|
||
> **来源**：照搬自参考博主项目（私有）的 `crawler.py` / `review.py` / `renderer.py`——已在中文观点视频博主账号上跑了 25+ 视频验证。
|
||
|
||
---
|
||
|
||
## 这个 adapter 是干嘛的
|
||
|
||
抖音视频页是**强 JS 渲染 + XHR 加载评论 + 反爬严重**——不带浏览器引擎和登录态的方案（比如 Claude 的 WebFetch、Python requests）拿不到任何数据。
|
||
|
||
douyin-session 用 **Playwright + 持久化 Chromium context** 模拟真实浏览器：
|
||
- 你首次扫码登录抖音创作者中心，cookie 存在**你的内容项目根目录** `.auth/`
|
||
- 之后每次抓取直接复用 cookie，不用重新登录
|
||
- 拦截抖音前端的 XHR responses 直接抓数据接口的 JSON（不解析 HTML）
|
||
- 抓 3 类数据：视频列表 / 详细数据（完播 / 转粉率）/ 评论
|
||
|
||
输出写到**你的内容项目** `videos/<...>/report.md`（`cheat-retro` 读这个文件 → 摘要写到 prediction 复盘段）。
|
||
调试产物（URL dump / 截图）写到 `.cheat-cache/douyin-session-debug/`，避免散落在 skill 源码目录。
|
||
|
||
## 安装（一次性）
|
||
|
||
```bash
|
||
# 1. 进你的内容项目根目录
|
||
cd ~/my-channel
|
||
|
||
# 2. 建虚拟环境（强烈建议——Playwright + Chromium 几百 MB，别污染 system Python）
|
||
python3 -m venv .venv
|
||
source .venv/bin/activate
|
||
|
||
# 3. 装 Playwright
|
||
pip install playwright>=1.44
|
||
|
||
# 4. 装 Chromium（首次必须）
|
||
playwright install chromium
|
||
|
||
# 5. 首次扫码登录抖音创作者中心
|
||
ADAPTER=$(find ~/.claude/skills -name "douyin-session" -type d 2>/dev/null | head -1)
|
||
# 如找不到（可能 adapter 不在全局），用源码路径：
|
||
# ADAPTER="$HOME/Desktop/cheat-test/cheat-on-content/adapters/perf-data/douyin-session"
|
||
python "$ADAPTER/crawler.py" login
|
||
# → 弹出 Chromium 窗口，扫码登录创作者中心
|
||
# → 登录成功后窗口自动关闭，cookie 存在 当前目录/.auth/
|
||
```
|
||
|
||
## 用法
|
||
|
||
cheat-retro 自动调用，你不需要手动跑。但如果想手动测试：
|
||
|
||
```bash
|
||
cd ~/my-channel
|
||
source .venv/bin/activate
|
||
|
||
# 列最近视频（看登录态有没有失效）
|
||
python "$ADAPTER/crawler.py" list
|
||
|
||
# 抓特定视频
|
||
python "$ADAPTER/review.py" video <aweme_id> <video_folder>/script.md
|
||
|
||
# 输出在 当前目录/videos/<日期>_<title>/report.md
|
||
```
|
||
|
||
## 怎么拿到 aweme_id
|
||
|
||
抖音视频 URL 形态：
|
||
- `https://www.douyin.com/video/7234567890123456789` → `aweme_id = 7234567890123456789`（直接在 URL 路径里）
|
||
- `https://v.douyin.com/abc123` → 短链需要 resolve（cheat-publish 自动做）
|
||
|
||
cheat-publish 会在登记发布时把 aweme_id 存到 prediction header（如能 resolve）。cheat-retro 启动时直接读这个字段。
|
||
|
||
## report.md 输出格式
|
||
|
||
由 `renderer.py` 生成。包含：
|
||
- 视频元信息（标题、发布时间、时长）
|
||
- 数据快照（播放、点赞、评论、转发、收藏 + 派生比率：赞播比 / 评播比 / 分播比）
|
||
- 完播率 / 3s 留存（如能抓到）
|
||
- Top 20 评论（按赞数排序，含评论文本 + 赞数）
|
||
- 评论关键词聚类（renderer 自动做，可选）
|
||
|
||
## 失败模式（按概率从高到低）
|
||
|
||
| 症状 | 原因 | 处理 |
|
||
|---|---|---|
|
||
| `ensure_login` 超时 | cookie 过期或抖音强制 reauth | 重新跑 `python crawler.py login` |
|
||
| `_parse_video_list` 返回空 | 抖音改了接口字段——结构性变化 | 看 `.debug/creator_urls.txt` 抓到的 URL，更新 crawler.py 的字段兜底 |
|
||
| `_parse_video_list` 视频列表不全 | 翻页没抓到——网络慢或反爬触发 | 调高 `crawler.py` 里的 `await asyncio.sleep(...)` 时长 |
|
||
| Chromium 崩溃 / 卡死 | 通常是机器内存不足 | 关闭其他 Chromium 进程；`playwright install chromium --force` 重装 |
|
||
| 评论抓取慢（>5min） | 评论页 XHR 多次滚动触发——慢网络 | 调小 `fetch_comments_creator` 的 `max_pages`，或换更稳的网络 |
|
||
|
||
**关键现实**：抖音接口结构每隔几个月会变一次。这个 adapter **需要持续维护**——如果有一天它突然失败，第一步是去看 `视频分析` 项目最新的 crawler.py 看有没有新版本。
|
||
|
||
## 稳定性等级
|
||
|
||
★★ — Playwright 方案能扛比纯 HTTP 强得多的反爬，但仍受抖音前端改版影响。建议每月手动跑一次 `crawler.py list` 验证健康。
|
||
|
||
## 风险提示
|
||
|
||
- **冷启动用户慎装**：Playwright + Chromium 体积大（~500MB），新人容易劝退
|
||
- **TOS 风险**：用自己的 cookie 抓自己后台数据是个人用途；别滥用
|
||
- **不要把 .auth/ 提交到 git**：cookie 里有你的会话凭据，泄露 = 他人能登录你的抖音账号
|
||
- `.cheat-cache/douyin-session-debug/` 也不应提交到 git：里面可能含调试截图和接口 URL dump
|
||
|
||
## 文件清单
|
||
|
||
```
|
||
adapters/perf-data/douyin-session/
|
||
├── README.md # 本文件
|
||
├── requirements.txt # playwright>=1.44
|
||
├── crawler.py # 抓取核心（视频列表 / 详细数据 / 评论）
|
||
├── review.py # CLI 入口（交互式或 video <aweme_id> 模式）
|
||
├── renderer.py # 把抓回的 JSON 渲染成 report.md
|
||
└── run.sh # cheat-retro 调用的 wrapper
|
||
```
|
||
|
||
## 与其他 adapter 的关系
|
||
|
||
- `youtube-data-api`（待）— YouTube 用官方 API，不需要 Playwright，更轻
|
||
- `bilibili-stat`（待）— B 站官方 stat 接口公开，也不需要 Playwright
|
||
- `xhs-explore` — 小红书，已实现（同样走 Playwright 被动拦截路线，照搬自本 adapter）
|
||
|
||
如果你做多平台内容，**只装你实际用的 adapter**——不需要全装。
|