kscz0000 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）
工作原理
- 将输入解析为一个 YouTube 视频 URL。
- 验证
yt-dlp已安装。若未安装，脚本退出并给出安装指引：brew install yt-dlp（macOS）或pip3 install --user yt-dlp。 - 将 URL 验证为单个 http(s) YouTube 视频，调用
yt-dlp --ignore-config --list-subs -- <url>枚举可用字幕。 - 字幕优先级：手动字幕 > 自动生成字幕。手动字幕保留创作者提供的标点和说话人标签；自动生成的字幕为大写且无标点。
- 通过
yt-dlp --write-sub --sub-lang <lang> --skip-download下载最高优先级字幕为 VTT 格式。默认语言偏好：en,es（英语优先，西班牙语次之）。 - 剥离 VTT 时间标记，合并为干净的散文段落。对重复行去重（自动生成的 VTT 会有行重复）。若源内容含说话人标签则保留。
- 通过
yt-dlp --print-json --skip-download拉取视频元数据（标题、频道、上传日期、时长、video_id、URL）。 - 对频道名和视频标题做 slugify 处理。写入
External Inputs/YouTube/<channel-slug>/<YYYY-MM-DD>-<video-slug>.md。 - 扫描字幕中的触发关键词（decision、framework、model、principle、"the lesson is"、playbook、anti-pattern、case study）。每个匹配项在
Meta/Captures/<YYYY-MM-DD>-youtube-<channel-slug>-<video-id>.md创建写作种子存根，使种子进入捕获聚合器。 - 打印摘要：文件路径、字幕字数、语言、检测到的种子数。
调用方式
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/<handle>
title: <video title>
upload_date: <YYYY-MM-DD>
duration_seconds: <int>
language: <ISO code>
subtitle_source: manual | auto | whisper
word_count: <int>
ingested_at: <ISO 8601 timestamp>
---
正文为清洗后的字幕，以段落散文形式呈现。若源内容含说话人标签，每轮格式为 **<speaker>:** <text>。
幂等性
重复导入同一视频 URL 会覆盖同一知识库文件。种子存根文件名对 video_id 做哈希，因此同一源视频在不同运行中产生相同的存根文件名。重新运行是刷新，不是重复。
字幕缺失
若 yt-dlp --list-subs 未返回手动或自动字幕，脚本会写入一个包含视频元数据和源 URL 的存根知识库笔记，而非静默失败。--whisper 标志保留用于未来的本地转录回退，当前报告该回退未实现。
如需手动回退，可用 yt-dlp 下载音频，用本地 Whisper 工作流转录，再添加字幕或文本后重新运行导入。
限制
- 每次运行仅导入一个 YouTube 视频 URL；频道句柄、播放列表和
--days时间窗口不在范围内。 - 依赖
yt-dlp返回的字幕；无字幕的视频仅生成元数据存根，而非转录文本。 - 本版本不下载视频文件，也不执行内置 Whisper 转录。
- 网络可用性、YouTube 字幕访问权限和本地
yt-dlp行为决定导入是否成功。
验收测试
使用有史以来第一个上传的 YouTube 视频进行测试：
python3 ingest.py "https://www.youtube.com/watch?v=jNQXAC9IVRw" --vault /tmp/test
预期输出：
Wrote 39 words to /tmp/test/External Inputs/YouTube/jawed/2005-04-24-me-at-the-zoo.md. Language: en. Subtitle source: manual.
输出文件包含有效的 frontmatter 和干净的散文正文。
依赖
yt-dlp（必需）：通过brew install yt-dlp或pip3 install --user yt-dlp安装whisper-cpp（可选，用于本脚本之外的手动回退）
来源
捆绑于 adelaidasofia/ai-brain-starter，一个围绕 AI 智能体的验证框架，使记忆不断积累而非损坏。本技能是 ingest-* 系列知识库连接器的一部分。