抖音视频文案提取技能

一句话定位

从抖音链接提取视频语音 → Whisper 本地转录为中文文本 → agent 整理纠错 → 输出可读 Markdown。

触发场景（满足任一即命中）

| 用户输入特征 | 示例 | |-------------|------| | 抖音链接 + "提取文案/文字/字幕/内容/文本" | "帮我把这个抖音视频的文案提取出来" | | 抖音链接 + "转文字/转录/转文本" | "这个抖音视频转成文字" | | 抖音链接 + "说了什么/讲什么/总结" | "这个视频说了什么？帮我看看" | | 抖音完整分享口令文本（含链接） | "0.23 复制打开抖音，看看… https://v.douyin.com/xxx" | | 任何含 douyin.com 域名且意图是从视频中获取文本 | "帮我听一下这个视频在讲什么" |

关键判断逻辑：只要用户消息中同时出现「抖音链接/分享文本」+「获取文本内容」的意图，就触发此技能。URL 域名不限于 v.douyin.com，也覆盖 www.douyin.com、iesdouyin.com 等变体。

Agent 执行指引

跨机器迁移注意：.env_config.json 由 setup_env.py 自动生成，包含机器特定路径。迁移到新机器后必须重新运行 python scripts/setup_env.py，不能直接复制配置文件。

执行此技能时，agent 必须按以下顺序确定 Python 解释器：

import json, os
from pathlib import Path

SKILL_DIR = Path("{skill_install_dir}")  # 运行时替换为实际安装路径
config_file = SKILL_DIR / ".env_config.json"

if config_file.exists():
    config = json.loads(config_file.read_text())
    PYTHON_EXE = config["venv_python"]    # 如 /path/to/venv/bin/python
else:
    # 环境未配置，提示用户运行 setup_env.py
    print("请先运行: python scripts/setup_env.py")
    sys.exit(1)

所有脚本必须用 PYTHON_EXE 运行，不得使用系统默认 python。

快速开始

# 1. 首次使用：配置环境（仅需一次）
python scripts/setup_env.py

# 2. 提取视频文本
python scripts/fetch_douyin_video.py <抖音短链接>

首次配置

scripts/setup_env.py 自动完成以下全部步骤：

检测兼容的 Python（需要 3.10–3.12，不兼容 3.13）
创建独立 venv（位于 {skill_dir}/venv/）
按正确顺序安装依赖：numpy<2 → requests/imageio[ffmpeg] → playwright → openai-whisper
安装 Chromium 浏览器（Playwright 使用）
验证所有包可正常导入
保存配置到 .env_config.json（后续脚本自动读取）

python scripts/setup_env.py
python scripts/setup_env.py --force           # 强制重建
python scripts/setup_env.py --mirror=pypi     # 使用官方源

环境要求

| 需求 | 说明 | |------|------| | Python | 3.10–3.12（3.13 不兼容，greenlet DLL 加载失败） | | numpy | 必须 < 2.0（>=2.0 会触发 ImportError: cannot load module more than once） | | VC++ Redist | Windows 下 torch 需要（下载） | | 磁盘空间 | ~4GB（torch ~2GB + Whisper 模型 ~1.4GB + Chromium ~300MB） |

环境验证

python scripts/verify_env.py       # 检查所有依赖
python scripts/verify_env.py --fix # 检查并自动修复
python scripts/verify_env.py --json # JSON 输出（供程序调用）

工作流程

步骤 1：Playwright 捕获视频 URL

无需登录即可提取。Chrome 无头模式下打开短链接，等待 8 秒让 JS 填充 video.src，通过 DOM 查询直接提取。

为什么不用网络拦截？ 登录模态框覆盖时网络拦截失效，但 DOM 中 video.src 已就绪。

步骤 2：下载视频（文件名含时间戳）

所有产物共用同一个 YYYYMMDD_HHMMSS 时间戳，重复运行不会覆盖。

from scripts.fetch_douyin_video import make_timestamp
ts = make_timestamp()  # "20260617_142035"
video_path = f"douyin_video_{ts}.mp4"

步骤 3：Whisper 转录

使用 medium 模型（~1.4GB，首次自动下载后缓存于 ~/.cache/whisper/）。

脚本内置模型缓存损坏自动修复：若检测到模型文件不完整或加载崩溃，自动删除缓存并重新下载。

步骤 4：整理纠错 → 保存 Markdown

脚本不调用外部 LLM。转录完成后输出原始文本，由 agent 自身完成整理：

| 允许 | 禁止 | |------|------| | ✅ 添加标点符号 | ❌ 删减内容 | | ✅ 修正 ASR 错字 | ❌ 改写概括 | | ✅ 语义分段断句 | ❌ 添加总结评论 |

agent 整理完毕后调用脚本提供的 write_cleaned_md() 写入 .md 文件。

Agent 调用方式：由于 write_cleaned_md 是 Python 函数而非命令行入口，agent 应通过内联 Python 脚本调用：

cd <工作目录> && <venv_python> -c "
import sys
sys.path.insert(0, '<skill_dir>/scripts')
from fetch_douyin_video import write_cleaned_md

md_path = write_cleaned_md(
    cleaned_text='''<整理后的文本>''',
    source_url='<原始短链接>',
    timestamp='<时间戳>',
    output_dir='<工作目录>'
)
print(f'MD saved: {md_path}')
"

产物清单

| 文件 | 内容 | |------|------| | douyin_video_{ts}.mp4 | 原始视频 | | transcript_{ts}.txt | Whisper 原始转录（含时间轴） | | transcript_{ts}.json | Whisper 完整 JSON 输出 | | transcript_{ts}.md | 整理后可读 Markdown |

所有文件存放在运行脚本时的当前目录。

常见问题排查

| 症状 | 原因 | 修复 | |------|------|------| | DLL load failed: c10.dll | VC++ Redist 缺失 | 安装 vc_redist.x64.exe | | ImportError: greenlet (Python 3.13) | greenlet 与 3.13 不兼容 | 使用 Python 3.10–3.12 | | cannot load module more than once | numpy >= 2 冲突 | pip install "numpy<2" --force-reinstall | | Whisper SIGABRT 崩溃 | 模型缓存损坏 | 删除 ~/.cache/whisper/medium.pt 后重试 | | pip install 清华源 SSL 失败 | 清华源偶发故障 | 换用阿里云 --mirror=aliyun | | 视频 URL 为空 | 视频需要登录 | 换一个公开视频尝试，或提供完整页面 URL | | Whisper 模型下载慢 | 网络问题 | 手动下载 medium.pt 放到 ~/.cache/whisper/ | | setup_env.py Invalid requirement | pip 包名被多余引号包裹 | 检查 packages_ordered 列表中包名无多余引号，如 'numpy<2' 而非 '"numpy<2"' | | setup_env.py AttributeError: module 'playwright' has no attribute '__version__' | playwright 模块无 __version__ 属性 | 使用 getattr(playwright, '__version__', 'installed') 安全获取 | | setup_env.py UnicodeEncodeError 含 emoji | Windows GBK 控制台无法编码 emoji | 避免在 print() 中使用 emoji，改用 ASCII 标识如 [OK] |

技术要点

登录墙绕过：video.src 由 JS 在登录模态框出现前填充，直接 DOM 查询即可捕获
CDN URL 有效期：抖音签名 URL（v26-web.douyinvod.com/...）有效约 24 小时，捕获后立即下载
模型选择：中文推荐 medium，准确率与 large 差距小而速度快一倍
FFmpeg 来源：imageio[ffmpeg] 自动提供，无需系统安装
环境隔离：所有依赖安装在 skill 目录下的独立 venv 中，不影响系统 Python

文件结构

douyin-transcribe-lz/
├── SKILL.md                          # 本文件
├── .env_config.json                  # 机器特定配置（setup_env.py 自动生成，勿手动编辑）
├── scripts/
│   ├── setup_env.py                  # 环境自动配置（支持 Windows/macOS/Linux）
│   ├── verify_env.py                 # 环境快速检测（支持 --fix 自动修复）
│   └── fetch_douyin_video.py         # 主脚本（捕获 → 下载 → 转录）
├── references/
│   └── whisper_usage.md              # Whisper 参数详解
└── venv/                             # 隔离 Python 环境（setup_env.py 自动创建，不提交到版本控制）
    └── ...

.env_config.json 和 venv/ 是运行时生成的文件，跨机器迁移后需重新运行 setup_env.py 生成。