抖音内容追踪器（Douyin Content Tracker）

通过 MediaCrawler 抓取抖音创作者视频，使用 ffmpeg 下载音频，并借助 Whisper 进行语音转录。

定位技能基目录（Skill Base Directory）

所有命令必须在本技能目录下执行。要定位该目录，请运行：

python -c "import pathlib; print([p for p in pathlib.Path.home().rglob('douyin-content-tracker-skill/SKILL.md')])"

或检查以下常见路径：

• ~/.claude/skills/douyin-content-tracker-skill/
• 安装该技能时显示的路径

为便于使用，可将其设为环境变量：

SKILL_DIR="~/.claude/skills/douyin-content-tracker-skill"   # 请根据实际路径调整
cd "$SKILL_DIR"

首次设置（First-Time Setup）

在新设备上仅需执行一次以下步骤。

1. 安装 Python 依赖

cd $SKILL_DIR
pip install -r scripts/requirements.txt
python -m playwright install chromium

2. 安装 MediaCrawler

# Windows
git clone https://github.com/NanmiCoder/MediaCrawler D:/MediaCrawler
cd D:/MediaCrawler && pip install -r requirements.txt

# macOS/Linux
git clone https://github.com/NanmiCoder/MediaCrawler ~/MediaCrawler
cd ~/MediaCrawler && pip install -r requirements.txt

3. 配置 .env

cd $SKILL_DIR
cp .env.template .env

编辑 .env 文件 — 必填字段如下：

MEDIACRAWLER_DIR=D:/MediaCrawler    # 请替换为实际的 MediaCrawler 路径（macOS/Linux 使用 ~/MediaCrawler）

可选覆盖项：

# 数据/音频/字幕/模型的存储根目录（默认：macOS/Linux 为 ~/DouyinContentTracker，Windows 为 %USERPROFILE%DouyinContentTracker）
OUTPUT_BASE_DIR=/Users/me/DouyinContentTracker

# Whisper 模型大小（默认：medium）
WHISPER_MODEL=small

4. 添加目标账号

编辑 accounts.txt 文件（或通过设置环境变量 TRACKER_ACCOUNTS_FILE，或在运行时传入 --accounts-file 参数指定）：

博主名称 | https://www.douyin.com/user/MS4wLjABAAAA...

5. 首次登录（生成 Cookie）

cd $SKILL_DIR
python scripts/scrape_profile.py

浏览器将自动打开 —— 扫描抖音二维码完成登录。Cookie 将保存至 .douyin_cookies.json。

日常使用（Daily Usage）

cd $SKILL_DIR

# 默认追踪每个账号最新 3 条视频。main.py 功能与 track_latest.py 一致
python scripts/track_latest.py
# 或
python scripts/main.py

# 追踪每个账号最新 N 条视频
python scripts/track_latest.py --limit 5

# 使用自定义账号列表（亦可通过环境变量 TRACKER_ACCOUNTS_FILE 指定）
python scripts/track_latest.py --accounts-file /path/to/accounts.txt

# 跳过音频下载与语音转录（仅采集元数据）
python scripts/track_latest.py --no-audio

Cookie 刷新

当抓取返回 0 条视频，或提示 “Cookie 已 N 天未更新” 时，请执行：

cd $SKILL_DIR
python scripts/scrape_profile.py    # 打开浏览器并扫码登录

处理流程（Pipeline Flow）

accounts.txt（或由 --accounts-file / TRACKER_ACCOUNTS_FILE 指向的账号列表）
    ↓
scripts/scrape_profile.py   → MediaCrawler（CDP）→ OUTPUT_BASE_DIR/data/*.csv
    ↓
scripts/clean_data.py       → 标准化后的 OUTPUT_BASE_DIR/data/cleaned_*.csv
    ↓
scripts/download_video.py   → Playwright + ffmpeg → OUTPUT_BASE_DIR/audio/{blogger}/*.m4a
    ↓
scripts/extract_subtitle.py → Whisper → OUTPUT_BASE_DIR/subtitles/{blogger}/{video_id}.md

输出路径（Output Locations）

所有生成文件均位于 OUTPUT_BASE_DIR 目录下（macOS/Linux 默认为 ~/DouyinContentTracker，Windows 默认为 %USERPROFILE%DouyinContentTracker）。

执行日志规范（Execution Logging Guide）

运行流水线时，应在每一步完成后立即向用户汇报进度，**不得等待整个流水线全部完成后再统一反馈**。

分步汇报模板如下：

每次 Bash 工具调用返回后，立即告知用户：

若任一环节失败，应立即中止流水线，原样输出错误信息，并引用 references/troubleshooting.md 中对应问题的修复方案，再询问用户是否继续执行。

示例输出格式：

[步骤 1/4 采集] 博主「某某」— 采集完成，共 10 条视频
[步骤 2/4 清洗] 有效数据 10 条 → data/cleaned_profile_xxx.csv
[步骤 3/4 音频] 下载完成 8/10（2 条无音频流，已跳过）
[步骤 4/4 字幕] 生成 8 个字幕文件 → subtitles/某某/
[完成] 1 位博主 · 10 条视频 · 8 个字幕，输出目录：~/DouyinContentTracker

参考资料（References）

调试或扩展流水线功能时，请将以下文件加载至上下文：

• references/pipeline.md — 各脚本技术说明、数据结构定义、关键函数签名
• references/troubleshooting.md — 针对 Cookie、MediaCrawler、ffmpeg、Whisper 及数据异常等问题的解决方案