抖音视频搜索、文案提取与修正
从抖音网页中搜索自定义关键词，筛选并选定目标视频，校验当前视频是否正确，再提取视频语音文案，并对抽取结果进行修正和落盘。
功能概述
- 搜索视频: 从抖音首页输入关键词并进入视频搜索结果，避免直接跳搜索 URL
- 筛选结果: 按标题关键词、账号类型、点赞、时长、内容类型等参数筛选候选视频
- 锁定目标视频: 点开候选视频后，校验标题是否匹配（支持归一化匹配、包含匹配、相似度匹配）
- 获取稳定链接: 优先使用页面
modal_id 组装稳定视频链接，必要时再尝试分享按钮
- 提取文案: 下载视频、提取音频、调用 ASR 获取语音文案
- 修正文案: 结合标题、标签、上下文和领域常识修正 ASR 错误
- 自动保存: 输出原始稿、修正版、修正说明、meta 信息等文件
环境要求
依赖安装
pip install requests ffmpeg-python
系统要求
- FFmpeg 必须安装在系统中（用于音视频处理）
- macOS:
brew install ffmpeg
- Ubuntu:
apt install ffmpeg
浏览器自动化要求
需要可用的 playwright-cli 以及它的 skills。
安装 playwright-cli
npm install -g @playwright/cli@latest
安装 playwright-cli 的 skills
playwright-cli install --skills
校验安装
playwright-cli --version
推荐使用有头模式、持久化登录态，并显式指定 profile 目录：
playwright-cli -s=douyinflow open https://www.douyin.com/ --headed --persistent --profile ~/.playwright/douyinflow
API 密钥配置（仅文案提取需要）
文案提取功能使用硅基流动 API，需要设置环境变量：
export API_KEY="your-siliconflow-api-key"
对 OpenClaw / Gateway 环境，建议写入：
~/.openclaw/.env
获取 API 密钥: https://cloud.siliconflow.cn/
使用方法
方法一：使用总控脚本（推荐）
python3 skills/douyin-video-skills/scripts/run_pipeline.py \
--keyword "青少年无人机" \
--pick-index 1 \
--must-include 青少年 \
--must-include 无人机 \
--content-type-hint 培训 \
--content-type-hint 科普 \
--account-hint 教育 \
--profile ~/.playwright/douyinflow \
--human-delay-min-ms 800 \
--human-delay-max-ms 2500 \
--captcha-max-waits 3 \
--title-match-mode default \
--title-min-similarity 0.82 \
--max-title-retry 5 \
--headed \
--persistent
总控脚本支持的主要参数
--keyword 自定义搜索词（必填）
--pick-index 选择第几个符合条件的结果（默认 1）
--must-include 标题必须包含的词，可多次传入
--exclude-word 需要排除的词，可多次传入
--content-type-hint 内容类型提示，如 培训 / 科普 / 推荐，可多次传入
--account-hint 账号类型提示，如 教育 / 俱乐部 / 教练，可多次传入
--min-likes 最低点赞量
--duration-min-sec 最短时长（秒）
--duration-max-sec 最长时长（秒）
--profile playwright-cli 持久化浏览器 profile 目录（默认 ~/.playwright/douyinflow）
--human-delay-min-ms 人类化操作最短等待时间（毫秒）
--human-delay-max-ms 人类化操作最长等待时间（毫秒）
--captcha-max-waits 验证码暂停等待次数（默认 3）
--title-match-mode 标题匹配模式：strict / default / loose
--title-min-similarity 标题最小相似度阈值（默认 0.82）
--max-title-retry 标题校验失败后最多尝试多少个候选（默认 5）
--headed 浏览器前台运行
--persistent 使用持久化登录态
--output-dir 输出目录（默认 output）
方法二：分步执行
1. 打开抖音并复用登录态（首次运行后会在 ~/.playwright/douyinflow 生成登录态文件，后续可复用）
playwright-cli -s=douyinflow open https://www.douyin.com/ --headed --persistent --profile ~/.playwright/douyinflow
2. 从首页输入搜索词并进入视频结果页
推荐让总控脚本自动完成，不要直接手写跳转搜索 URL。这样更接近真人操作，更利于减少验证码。
3. 选定视频后做标题一致性校验
python3 skills/douyin-video-skills/scripts/title_match_check.py \
--expected "目标搜索结果标题" \
--actual "当前弹层标题" \
--mode default \
--min-similarity 0.82
默认不是死板的逐字完全相等，而是按“归一化标题 + 包含关系 + 相似度阈值”综合判断。
若仍不匹配，不继续当前视频提取；应自动关闭弹层并尝试下一个候选。
4. 提取视频文案
python3 skills/douyin-video-skills/scripts/douyin_downloader.py \
--link "https://www.iesdouyin.com/share/video/<videoId>" \
--action extract \
--output ./output
5. 修正文案并生成附加文件
python3 skills/douyin-video-skills/scripts/transcript_cleanup.py \
--title "视频标题" \
--raw ./output/<videoId>/transcript.md \
--outdir ./output/<videoId>
筛选参数示例
{
"keyword": "青少年无人机",
"pickIndex": 1,
"mustInclude": ["青少年", "无人机"],
"excludeWords": ["直播", "纯广告", "录播回放"],
"minLikes": 0,
"durationMinSec": 15,
"durationMaxSec": 120,
"contentTypeHints": ["培训", "科普", "推荐"],
"accountHints": ["教育", "俱乐部", "教练"]
}
更详细的筛选思路参考：
references/filter-rules.md
发布文案参考：
references/publish-copy.md
输出目录结构
完整执行后，每个视频建议保存到独立文件夹：
output/
└── <videoId>/
├── meta.json
├── source-link.txt
├── transcript.md
├── transcript-raw.md
├── transcript-clean.md
└── transcript-fixes.md
文件说明
meta.json: 标题、关键词、视频ID、筛选参数、提取时间source-link.txt: 最终用于提取的链接transcript.md: 提取器原始产物transcript-raw.md: 原始转写稿transcript-clean.md: 修正版文案transcript-fixes.md: 修正说明与待确认项
工作流程
搜索与筛选
- 打开抖音首页并复用登录态
- 以较慢节奏输入搜索词并点击搜索
- 切换到视频结果页
- 从搜索结果中读取候选视频列表
- 按筛选参数过滤候选项
- 选中第 N 个符合条件的视频
标题一致性校验
- 记录目标搜索结果标题
- 点开视频进入弹层
- 读取当前页面
modal_id
- 读取当前弹层标题
- 执行标题校验脚本（默认使用归一化匹配 + 相似度阈值）
- 若标题不一致，自动关闭弹层，回到结果列表继续尝试后续候选，直到找到校验通过的视频
提取与修正
- 用
modal_id 组装稳定视频链接：https://www.iesdouyin.com/share/video/<videoId>
- 下载视频到临时目录
- 使用 FFmpeg 从视频中提取音频（MP3 格式）
- 调用硅基流动 SenseVoice API 进行语音识别
- 保存
transcript.md
- 基于标题、标签、上下文和领域常识修正 ASR 文案
- 输出
transcript-raw.md、transcript-clean.md、transcript-fixes.md
常见问题
搜索时频繁触发验证码怎么办
建议优先使用以下方式减少验证码：
- 使用固定 profile 目录复用登录态
- 从首页输入搜索，不要直接跳搜索 URL
- 增加人类化延迟，不要秒点秒跳
- 遇到验证码时先手工完成，再继续流程
当前脚本已支持：
- 人类化延迟参数：
--human-delay-min-ms / --human-delay-max-ms
- 验证码暂停恢复：检测到验证码后暂停，等待人工处理完成再继续
搜索结果点开后，当前视频变了
这是抖音网页常见问题。必须增加校验：
- 标题先做归一化
- 再判断包含关系
- 最后再看相似度是否达到阈值
若仍不一致，不要在错误视频上继续提取。应执行：关闭弹层 → 回到结果列表 → 尝试下一个候选标题 → 重新校验，直到找到正确视频。
分享按钮不稳定
PC 端分享按钮可能：
- 只在悬停时出现
- 位于播放器浮层中，不易点击
- DOM 结构经常变化
因此本 skill 默认：
- 优先读取
modal_id
- 用
modal_id 组装稳定视频链接
- 不把“复制链接”当成唯一依赖
提取文案失败
- 检查
API_KEY 是否已设置
- 确保 API 密钥有效且有足够额度
- 确保 FFmpeg 已正确安装
- 确保输入链接为有效抖音分享链接或可解析的视频链接
文案有错别字或语义不通
ASR 常见问题包括：
- 同音错字
- 连词错误
- 重复词
- 断句错误
- 领域术语误识别
因此提取后必须执行修正步骤。
注意事项
- 本工具仅供学习和研究使用
- 使用时需遵守相关法律法规
- 请勿用于任何侵犯版权或违法的目的
- 不要把分享按钮点击成功作为唯一成功条件
- 不要直接信任 ASR 文案用于分析
- 不要在未完成标题一致性校验前就进入提取
- 不要把 Playwright 的 element ref 写死成固定编号
