findscripter 何时使用
适用场景：
- 用户贴出一条 YouTube 视频 URL，要字幕、文字稿或摘要。
- 用户执行
/ingest-youtube <url>，针对单条视频。 - 用户想把某个演讲 / 播客 / Keynote 抓取、同步、转录、入库到 Markdown 知识库，产物供下游技能（知识图谱抽取、语言风格指纹、内容二次创作、行动项抽取）使用。
不该用（负边界）：
- 下载视频文件本身 —— 直接用
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生成写作种子 stub，落入 captures 聚合器。 - 打印汇总：文件路径、文字稿词数、语言、检测到的种子数。
指令
python3 ingest.py <youtube-url> [--vault <path>] [--lang <code>]
默认值：
--vault：$VAULT_ROOT环境变量，或当前目录。--lang：en,es（英文优先、西语次之，匹配常见双语默认）。--whisper：预留的未来回退标志；当前版本在没有字幕时只写 stub，尚未实现本地转录。
输出契约 —— 库文件 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>
---
正文是清洗后的段落散文；源中有说话人标签时，每轮发言按 **<说话人>:** <文本> 格式排版。
示例
对「史上第一条 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 与干净的段落正文。
注意事项
- 幂等：重抓同一 URL 覆盖同一库文件；种子 stub 文件名对 video_id 做哈希，同一视频多次运行得到相同 stub 文件名 —— 只刷新、不重复。
- 缺字幕：
--list-subs没有人工或自动字幕时，脚本写一条只含元数据和源 URL 的 stub 库笔记，而非静默失败。--whisper当前会报告回退未实现。手动回退做法：用yt-dlp下载音频，用本地 Whisper 工作流转录，补上字幕/文字稿后再重跑入库。 - 依赖：
yt-dlp（必需，brew install yt-dlp或pip3 install --user yt-dlp）；whisper-cpp（可选，仅用于脚本外的手动回退）。 - 范围限制：每次仅一条视频 URL；不下载视频文件；不内建 Whisper 转录。是否成功取决于网络、YouTube 字幕可访问性和本地
yt-dlp行为。
互见
- 与 ingest-slack / ingest-whatsapp / ingest-notion / ingest-linear / ingest-github / ingest-gmail 同一架构 —— 新增 YouTube 只是加一个 normalizer，不是新架构。
- 下游可衔接：知识图谱抽取、语言风格指纹训练、内容二次创作、行动项抽取。
采编自 sickn33/antigravity-awesome-skills（原始 skill 捆绑于 adelaidasofia/ai-brain-starter），许可证 MIT。