抖音视频数据抓取

三种模式，都产出同构的 21 列 Excel：

| 模式 | 触发场景 | 命令 | 需要登录 | 需要浏览器 | |---|---|---|---|---| | 批量链接 | 用户给了一批视频链接/分享口令 | --file links.txt | 否 | 否（读浏览器 cookie） | | 关键词搜索 | 用户给搜索主题，要「热度最高的 N 条」 | --search "关键词" | 是 | 是 | | 作者主页 | 用户给作者主页，要「最新 N 条」 | --user "主页链接" | 否 | 是 |

若用户要的是下载视频文件，走 yt-dlp-downloader，不要用本技能。

运行环境

所有命令都在技能安装目录（即 scripts/ 所在的那一层）下执行，脚本路径一律用相对路径 scripts/main.py。

<PY> 按系统取值，优先用系统 Python；若系统 Python 缺依赖，改用 WorkBuddy 托管的默认虚拟环境：

| 系统 | 推荐命令 | 兜底（WorkBuddy 托管 venv） | |---|---|---| | Windows | python | %USERPROFILE%\.workbuddy\binaries\python\envs\default\Scripts\python.exe | | macOS / Linux | python3 | ~/.workbuddy/binaries/python/envs/default/bin/python |

平台支持：

批量链接模式：Windows / macOS / Linux 均可（cookie 来源浏览器可用 --browser 指定，支持 edge / chrome / chromium / firefox / brave 等 yt-dlp 支持的名称）。
搜索 / 作者主页模式：需要本机装有 Edge 或 Chrome / Chromium（按此顺序自动探测）。 Windows + Edge 验证最充分；macOS / Linux 可用但未做完整回归，如遇异常请先在本机浏览器手动打开 douyin.com 确认可访问。

模式一：批量链接（严格按顺序）

检查依赖（必须先做）：
```
<PY> scripts/main.py --check-deps
```
- 退出码 0 → 继续第 2 步。
- 退出码 3 → 先执行 stdout 里给出的 [INSTALL] 命令装依赖，装完重跑本步。
把链接写进 UTF-8 文本文件（推荐方式，命令行传中文/特殊字符容易乱码），一行一个，允许一行就是整段 App 分享口令；# 开头为注释会被忽略。仅当链接 ≤3 条且全是纯 ASCII 短链时才用 --file 之外的方式传。
执行抓取：
```
<PY> scripts/main.py --file "<链接文件绝对路径>" --output "<输出 xlsx 绝对路径>"
```
常用可选参数：--delay 2（每条间隔秒数）、--retries 2、--browser edge、--browser-profile Default、 --cookies <cookies.txt>（降级路径）、--json <路径>（同时导出原始 JSON）、--engine cli（排障时改用子进程模式）、 --no-strict-cookie（关闭熔断）、-v（看详尽日志）。
原样汇报 main.py 的 stdout 摘要，不要自行编造或补充数据；不要把同一批链接重复跑第二次（会加剧抖音风控）。

模式二：关键词搜索

用户说「搜一下 XX，把最火的 N 条抓出来」。

确认已登录。首次使用必须先让用户登录一次：
```
<PY> scripts/main.py --login
```
会弹出一个浏览器窗口，用户扫码登录后窗口自动关闭，登录态存进独立配置目录 ~/.workbuddy/douyin_browser_profile，之后长期复用，不必再登录。
执行搜索：
```
<PY> scripts/main.py --search "workbuddy教程" --limit 50 --sort-by digg --output "<输出 xlsx 绝对路径>"
```
- --sort-by：digg点赞（默认）/ collect收藏 / share分享 / comment评论 / play播放。
- 排序是在已抓取到的候选池内排序，不是全站排行榜；热门关键词候选池通常 100+ 条，足够取满 50。
- 抖音网页搜索必须登录，未登录会直接报 LOGIN_REQUIRED 而不是硬闯。
- 运行期间会弹出一个浏览器窗口自动滚动（约 1~3 分钟后自行关闭）。这是必需的：窗口移出屏幕时搜索页的滚动加载不会触发，只能拿到首屏约 10 条。想安静运行可加 --offscreen，但要接受只能拿约 10 条。
- 「抖音号」列在搜索模式下通常为空（搜索接口不返回作者资料），请用「作者主页」列跳转。

重要口径提醒（必须主动告诉用户）：抖音 web 接口基本不返回真实播放量，所以「播放数」列几乎总是 0。用户要「播放量最高的」时，如实说明拿不到，建议改用点赞或收藏排序，不要假装按播放量排了。

模式三：作者主页

用户说「把这个博主的视频抓出来」。

<PY> scripts/main.py --user "https://www.douyin.com/user/MS4wLjABAAAA..." --limit 50 --output "<输出 xlsx 绝对路径>"

--user 可重复传多个作者，会合并进同一张表。
支持三种输入：作者主页 URL、MS4w... 开头的 sec_uid、URL 编码后的主页链接。
不需要登录，按发布时间倒序取最新 N 条。
若作者作品不足 N 条，就只返回实际条数（不是故障）。

入参要求

批量链接模式至少要有一条抖音链接，一条都没有就请用户补充，不要空跑。
--output 给绝对路径；不传则生成 douyin_videos_<时间戳>.xlsx 在当前工作目录。
超过 30 条时先告诉用户预计耗时（约 3~8 秒/条）再执行。

输出说明

stdout 末尾是结构化摘要：

[RESULT] 输入=6 解析=4 成功=3 失败=1
[FILE]   <输出目录>/douyin_videos_20261008_101500.xlsx
[ROWS]   1 7433832678895422783 OK   作者=xxx 点赞=123456 ...
         4 xxxxxxxxxxxxxx      FAIL [VIDEO_UNAVAILABLE] ...
[ISSUES] VIDEO_UNAVAILABLE×1
[TIP]    VIDEO_UNAVAILABLE: 视频本身取不到（已删除、设为私密或仅粉丝可见）...

退出码：0=至少成功 1 条；1=全部失败；2=参数或输入错误；3=缺少依赖。

Excel 两张表：抖音视频数据（21 列，含「抓取状态 / 错误分类 / 错误信息」便于定位失败行）+ 说明（含口径与免责）。

异常处理（直接照搬 [TIP] 行给用户，不要自行发挥）

| 分类 | 含义 | 处理 | |---|---|---| | COOKIE_WEBID_MISSING | 浏览器 cookie 缺抖音设备标识 s_v_web_id | 最常见。请用户在浏览器打开 https://www.douyin.com/ 停留几秒刷一下，然后重跑 | | COOKIE_DB_LOCKED | 浏览器正在运行，Cookie 数据库被独占锁住 | 请用户完全关闭浏览器（托盘也要退出）后重跑；未经同意不要替用户杀进程 | | COOKIE_DECRYPT_FAILED | Windows DPAPI 解密失败（新版浏览器的 app-bound 加密） | yt-dlp 已知限制，非账号问题。请用户导出 cookies.txt，改用 --cookies | | COOKIE_NOT_FOUND | 找不到 cookie 数据库 | 确认浏览器已访问过 douyin.com，或改用 --cookies | | COOKIE_BLOCKED_403 | cookie 存在但被风控拦截/过期 | 先刷新浏览器 cookie 重试；仍失败则导出 cookies.txt | | VIDEO_UNAVAILABLE | 视频已删除/私密/仅粉丝可见 | 视频本身取不到，表里已标注原因，不是程序故障 | | NETWORK | 超时或连接错误 | 已自动重试过，请检查网络/代理后重试 | | URL_RESOLVE | 短链解析失败或链接里没有视频 ID | 让用户确认链接完整有效 | | SKIPPED | 被熔断跳过的条目 | 修复 cookie 后重跑（脚本连续 3 条 cookie 失败会主动中止，避免空跑加剧风控） | | IO_LOCKED | 目标 xlsx 正被 Excel 打开 | 请在 Excel 里关闭文件或换个文件名再试 | | LOGIN_REQUIRED | 搜索模式未登录 | 抖音网页搜索必须登录。跑一次 --login，扫码登录后重试 | | LOGIN_TIMEOUT | --login 等了 5 分钟没检测到登录 | 让用户重跑 --login，确认扫码后在该窗口内完成登录 | | NO_RESULT | 页面没返回任何作品 | 关键词无结果 / 作者主页无效 / 触发风控。先用 --login 确认登录态，再稍后重试 | | BROWSER_NOT_FOUND | 找不到 Edge / Chrome / Chromium | 搜索与作者主页两种模式依赖本机 Chromium 系浏览器，需用户安装其一 | | BROWSER_START_FAILED | 浏览器起不来，多为配置目录被占用 | 完全关闭浏览器（托盘也要退出）后重试 |

排障顺序：先在浏览器刷 douyin.com 刷新 cookie → 完全关闭浏览器重试 → 改用 --cookies cookies.txt → 单条链接加 --engine cli -v 看 yt-dlp 原始报错。

依赖

只在缺依赖时执行一次：

<PY> -m pip install --disable-pip-version-check yt-dlp openpyxl brotli websocket-client

不要锁版本，抖音抽取器的修复都在新版本里。

运行时需要：yt-dlp（批量链接模式核心抽取）、openpyxl（写 Excel）； websocket-client（搜索 / 作者主页两种模式的 CDP 通信，缺它这两个模式直接不可用）；brotli 为可选增强。

已知限制（须如实告知用户）

播放数拿不到（重要）：抖音 web 接口基本不返回真实播放量，三种模式下「播放数」列都几乎总是 0。这是平台限制，不是技能缺陷。用户要按播放量排序时，必须如实说明做不到，建议改用点赞/收藏排序。
抖音风控会导致偶发 403，这是平台侧行为，不是技能缺陷；同一批链接短时间内不要反复跑。
搜索模式的排序是候选池内排序，不是全站排行榜；候选池来自页面滚动加载到的结果，热门关键词通常够 50 条。
作者主页模式若作者作品少于 --limit，只返回实际条数。
收藏数取自 statistics.collect_count；点赞/评论/分享分别取自 digg/comment/share_count。
视频标题会被截断到 72 字符，完整文案在「视频文案」列。
图文作品（douyin.com/note/<id>、/slides/<id>）支持有限，抓取失败属正常。
发现式抓取（搜索/作者）不用 headless：抖音对无头浏览器有风控（搜索页直接返回验证码中间页），因此用普通窗口 + 窗口移到屏幕外的方式，运行期间用户看不到窗口，属正常现象。
macOS / Linux 上的搜索与作者主页模式未做完整回归，优先推荐 Windows + Edge。

合规与免责（随结果一起传达）

只读取抖音公开展示的元数据，不破解风控、不采集私密内容。
不构造、不伪造任何签名：搜索 / 作者主页两种模式是让浏览器自己正常加载页面，再通过 CDP 读取浏览器已经收到的接口响应。拿到的就是页面真实展示给用户的数据，不去实现或绕过 a_bogus / X-Bogus 等签名算法，也不伪造设备指纹。
搜索模式的登录使用独立的浏览器配置目录，不读取、不复制、不修改用户现有的浏览器个人数据。
批量链接模式默认每条间隔 2 秒限速，不得用于批量压测、自动化竞品监控或转售他人数据。
输出结果仅供用户本人留存分析使用。