---

name: ingest-youtube description: "将 YouTube 视频字幕拉取到可查询的 Markdown 知识库中，包含 yt-dlp 字幕发现、VTT 清理、元数据 frontmatter 和捕获种子存根。" risk: safe source: community source_repo: adelaidasofia/ai-brain-starter source_type: community date_added: "2026-05-09" license: MIT license_source: "https://github.com/adelaidasofia/ai-brain-starter/blob/main/LICENSE" upstream: "https://github.com/adelaidasofia/ai-brain-starter/tree/main/skills/ingest-youtube" plugin: setup: type: manual summary: "在运行 ingest.py 前本地安装 yt-dlp；脚本仅接受 http(s) YouTube 视频 URL 并将 markdown 写入选定的知识库。" docs: "SKILL.md"

ingest-youtube — YouTube 到知识库连接器

将 YouTube 字幕拉取到 Markdown 知识库中，作为可查询的类型化记忆条目，下游技能（知识图谱提取、语音指纹训练、内容再利用、行动项提取）可以对其进行操作。

与 ingest-slack、ingest-whatsapp、ingest-notion、ingest-linear、ingest-github、ingest-gmail 相同模式。添加 YouTube 意味着一个新的规范化器，而非新架构。

使用场景

• 用户粘贴 YouTube URL 并要求字幕或摘要
• 用户输入 /ingest-youtube <url> 处理单个视频
• 用户要求捕获、同步、摄取、转录或拉取演讲/播客/主题演讲到知识库

不适用于：

• 下载实际视频文件（直接使用 yt-dlp 配合 -f best）
• 频道级摄取或 --days 窗口；此脚本一次摄取一个视频 URL
• 直播（字幕不稳定）
• 非 YouTube 来源（Vimeo、Twitch、Twitter Spaces 有各自的连接器）
• 用户不需要知识库文件的一次性字幕读取（直接运行 yt-dlp --write-auto-sub 并管道到 stdout）

工作原理

1. 将输入解析为一个 YouTube 视频 URL。
2. 验证 yt-dlp 已安装。如果未安装，脚本退出并给出安装说明：brew install yt-dlp（macOS）或 pip3 install --user yt-dlp。
3. 验证 URL 为单个 http(s) YouTube 视频，调用 yt-dlp --ignore-config --list-subs -- <url> 枚举可用字幕。
4. 字幕优先级：手动字幕 > 自动生成字幕。手动字幕保留创作者提供的标点和说话人标签；自动生成为大写且无标点。
5. 通过 yt-dlp --write-sub --sub-lang <lang> --skip-download 下载最高优先级字幕为 VTT。默认语言偏好：en,es（英语优先，西班牙语其次）。
6. 去除 VTT 时间标记并合并为干净的散文段落。去重重复行（自动生成的 VTT 会行重复）。如果源有说话人标签则保留。
7. 通过 yt-dlp --print-json --skip-download 拉取视频元数据（标题、频道、上传日期、时长、video_id、URL）。
8. 将频道名和视频标题 slug 化。写入 External Inputs/YouTube/<channel-slug>/<YYYY-MM-DD>-<video-slug>.md。
9. 扫描字幕中的触发关键词（decision、framework、model、principle、"the lesson is"、playbook、anti-pattern、case study）。对每个匹配创建写作种子存根到 Meta/Captures/<YYYY-MM-DD>-youtube-<channel-slug>-<video-id>.md，使种子进入捕获聚合器。
10. 打印摘要：文件路径、字幕字数、语言、检测到的种子。

调用

python3 ingest.py <youtube-url> [--vault <path>] [--lang <code>]

默认值：

• --vault：$VAULT_ROOT 环境变量或当前目录
• --lang：en,es（英语优先，西班牙语其次；匹配常见双语默认值）
• --whisper：作为未来回退标志接受，但此版本在无字幕可用时写入存根

输出契约

External Inputs/YouTube/<channel-slug>/<YYYY-MM-DD>-<video-slug>.md 的知识库文件具有 frontmatter：

---
type: external-input
source: youtube
video_id: <11-char ID>
url: https://www.youtube.com/watch?v=<id>
channel: <channel-name>
channel_url: https://www.youtube.com/<channel-handle>
title: <video-title>
published: <YYYY-MM-DD>
duration_seconds: <int>
language: <subtitle-lang-code>
subtitle_type: manual | auto-generated
ingested_at: <ISO-8601>
word_count: <int>
seeds_detected: <int>
tags: [youtube, <channel-slug>]
---

捕获种子

当字幕包含触发关键词时，在 Meta/Captures/ 创建种子存根：

---
type: capture
source: youtube-ingest
video_id: <id>
trigger: <matched-keyword>
context: <surrounding-sentence>
status: unprocessed
---

依赖

• yt-dlp（必需）— 字幕发现和下载
• Python 3.8+（必需）— 脚本运行时
• 无外部 API 密钥需要

限制

• 一次仅处理一个视频 URL
• 依赖 YouTube 提供的字幕（手动或自动生成）
• 如果视频无字幕，写入存根并建议使用 Whisper 回退
• 不下载视频/音频文件
• 不处理年龄限制或地区锁定的视频（除非 yt-dlp 配置了 cookies）