yt-research-skill

youtube-channel-research

English · 简体中文

[!IMPORTANT] 本仓库已被 multiplat-research 取代。 新项目保留同样的报告结构与实测坑表，但把代码拆成可插拔的数据源 （YouTube · B站 · 本地文件 · 抖音本人账号导出）与平台无关的分析内核， 并修掉了本版本仍存在的两个问题：去掉了 ffmpeg 依赖（faster-whisper 经 PyAV 解码音频）、 用客户端回退链绕开 YouTube 媒体流的 HTTP 403。 除非你确实只要单平台版本，否则请使用新仓库。

把「这个频道最近都在讲什么」变成一份跨视频研究报告。 给它一个频道和 N —— 它会枚举最近 N 条投稿，逐条取文本（字幕优先、无字幕自动 ASR 转写）， 然后写成一份横向对比报告，而不是 N 篇互不相干的摘要。

一个纯 Python、零外部服务依赖的 Agent Skill， 可在支持标准技能结构的宿主中直接使用：DSH / Codex / Claude Code / Hermes / WorkBuddy。

---

它解决什么问题

手动研究一个频道要经历：找视频 → 判断有没有字幕 → 有字幕就下载、没有就下音频转写 → 读 N 份长文本 → 横向对比。前四步全是体力活，而且有几个反复踩的坑（客户端指纹拦截、 Windows 下 HF 模型缓存损坏、字幕里的零宽字符污染文本、ASR 成本失控）。

本技能把前四步脚本化，并把踩过的坑固化成文档，让 Agent 把精力花在第 5 步。

---

快速开始

# 1) 装依赖（技能本地 venv，不污染系统 Python）
python -m venv .venv
.venv/bin/python -m pip install -r requirements.txt      # Windows: .venv\Scripts\python.exe

# 2) 自检：确认解释器与依赖解析正确
python scripts/python_env.py

# 3) 枚举频道最近 5 个视频 → channel.json + index.md
python scripts/channel_list.py "@MrBeast" -n 5 --out ./yt-research

# 4) 取文本（字幕优先，无字幕自动 ASR）
python scripts/fetch_transcript.py --index ./yt-research/channel.json --out ./yt-research/transcripts

# 5) 让 Agent 依据 index.md 与 transcripts/*.plain 撰写 research.md

然后让 Agent 按 SKILL.md 的「产出格式」撰写报告，或自己照抄那 6 节结构。

---

安装到各 Agent

技能就是一个普通目录，所以「安装」= 让宿主的技能目录里能看到这个目录。

一键安装（推荐）

python scripts/install_to_agents.py            # 只探测已存在的宿主目录，不写入
python scripts/install_to_agents.py --install  # 真正安装
python scripts/install_to_agents.py --agents dsh,codex --mode copy   # 指定宿主，用复制

脚本默认在支持时建立目录链接（Windows junction / POSIX symlink）， 这样以后 git pull 更新技能，所有宿主同步生效；不支持或没权限时自动退回复制。

手动安装

Windows（PowerShell，以 DSH 为例）

New-Item -ItemType Junction -Path "$env:USERPROFILE\.dsh\skills\youtube-channel-research" `
         -Target "C:\path\to\yt-research-skill"

macOS / Linux

ln -s /path/to/yt-research-skill ~/.claude/skills/youtube-channel-research

Hermes（从仓库直接装）

hermes skills install <your-github-user>/yt-research-skill
# 或把仓库加为技能源，之后可用 hermes skills browse/search
hermes skills tap add <your-github-user>/yt-research-skill

---

环境变量

技能不写死任何本机路径。需要覆盖时用这两个：

解释器解析顺序（scripts/python_env.py）：

$YTDLP_PY / $YT_ASR_PY  →  技能本地 .venv/  →  当前解释器
→  常见第三方 Agent 自带 Python  →  python3 / python

这里刻意分了两级：resolve_downloader() 只需要 yt_dlp，而 resolve_asr() 额外要求 faster_whisper，并且在下载任何音频之前调用。若只做一级检查， 会选中「有 yt_dlp 但没有 faster_whisper」的解释器，失败要等到整段音频下载完才暴露 —— 那是最坏的失败时机。

---

产出物

---

示例输出

真实运行记录（未删改），见 examples/：

python scripts/channel_list.py "@MrBeast" -n 3 --out ./smoke
# [完成] 频道=MrBeast  视频=3  总时长=1:41:46  需ASR=0  预计转写=0.0分钟

第一步产出的索引（examples/index-mrbeast.md）——注意「内容来源」列直接告诉你成本：

第二步取到 3 份转录（共 30,874 字），第三步产出约 24 KB 的研究报告 （examples/research-mrbeast.md），结构为 6 节：

1. 频道概览      —— 订阅数、样本范围、发布日期区间、内容来源统计（字幕 3 / ASR 0）
2. 逐视频卡片    —— 每支：主旨一句话 + 3~6 条要点 + 内容来源与可信度
3. 横向对比表    —— 16 个维度跨视频对照（主题/机制/奖金/结构套路/植入/情绪落点…）
4. 主题聚类与演化 —— 反复出现的叙事装置、系列化模式、随时间的变化
5. 矛盾与存疑点  —— 视频之间不一致处、字幕转写可能的偏差
6. 方法论与局限  —— 字幕 vs ASR、时间戳误差、"最近 N 个" ≠ 频道全貌

样例中最能说明「横向研究 ≠ N 篇摘要」的两处：

• 第 3 节提炼出三支视频完全一致的结构骨架（冷开场抛赌注 → 一句话规则 → 数字/时间戳播报 → 一次规则突变 → 至少两个品牌植入 → 自我指涉收尾）；
• 第 4 节发现叙事装置的演化：视频 1、2 用统一的「为妈妈赢钱」框架，到视频 3 退化为个别选手的背景故事。

---

成本与耗时（实测基准）

• 字幕路径：几乎零成本，每支视频约 1 次请求。
• ASR 路径：medium/int8/CPU 8 线程下约 0.35× 实时（13 分钟音频 ≈ 4.5 分钟转写）。
• 因此脚本默认拒绝预估 > 30 分钟的批量 ASR；用 --orders 缩小范围，或 --yes 显式确认。

---

已知坑（先知道这四条）

完整 12 条见 SKILL.md，最值得先知道的四条：

1. 别用 tempfile.mkdtemp() 做 yt-dlp 的工作目录——在被沙箱限制的环境里，它产出的目录连 os.listdir 都会被拒（WinError 5），Python 能写、子进程 yt-dlp 不能。脚本改用输出目录下的 .work/。
2. 别用 curl 取 YouTube 元数据——部分网络按 TLS/客户端指纹放行，curl 会被挡（HTTP 000）；一律走 yt-dlp --dump-json。
3. HF 模型缓存会坏——snapshots/ 里可能是 0 字节占位、真身在 blobs/： 跑 python scripts/setup_asr_model.py --repair-hf-cache 就地修复（一次生效，用硬链接不额外占盘）。
4. 中日韩自动字幕带零宽字符（卡拉OK计时用），不清洗会污染后续分析；脚本的 clean_text() 已处理。

---

许可

MIT。

本技能由 AI Agent 在会话中生成，并在真实频道上端到端验证； 「已知坑」表中每一条都来自实际报错与修复，不是推测。详见 ATTRIBUTION.md。