YouTube Fetcher to Markdown
把 YouTube 视频一键转为带完整元数据的 Obsidian 归档笔记：字幕、章节、可点击时间戳，无需 API 密钥。
证据显示权限最小化做得好：仅联系 YouTube captions/oEmbed，yt-dlp 子进程禁用配置/缓存/播放列表且有超时（测试验证）；文件写入原子化、拒绝覆盖与符号链接目标。扣分项：--force 为破坏性替换且无撤销机制，回滚仅靠'文件未被碰'的默认行为；源归属上 LICENSE 版权名 'GimySadek' 与仓库 'JimmySadek' 不一致；依赖仅是版本范围，无依赖完整性/审计说明。
测试与 README 声明高度一致（语言选择、文件保护、退出码、超时均有契约测试），失败信息经测试验证具有可操作性且不泄露细节（如超时错误隐藏代理密码）。扣分：对外部 YouTube 接口的可用性无法静态保证，README 自己承认 'passing offline tests cannot guarantee access'。
面向 Obsidian 用户、命令行用户与多种 Agent（Codex/Claude Code 等），URL 形态覆盖广并有测试，能力边界（不下载音视频、不做 Whisper、不做说话人识别）表述明确，多平台环境与 venv 指南齐全。扣分：SKILL.md 本体未在证据中，触发精度只能由打包测试间接佐证。
信息架构清晰、安装说明覆盖三平台、示例丰富、故障排查表和退出码表完整、局限性坦率。扣分项：无仓库内 CHANGELOG（仅链接外部 release notes）；命名上 main/master 双分支为历史兼容保留，存在混淆风险；LICENSE 版权人姓名与仓库名不一致；维护者身份未经验证，发布流程文档化但无法静态核实执行。
输出可用性高：YAML frontmatter、Dataview 兼容、多格式导出、时间戳链接均有测试佐证；成本极低（无 API key、纯本地、可选依赖）。扣分：同类转录抓取工具众多，边际价值主要在元数据整合与防覆盖安全上，属改进而非独有能力。
README 声明大量由测试文件直接佐证（退出码 3、原子写、语言回退、机器翻译标记）；specs/ 验证记录被引用但内容不在证据内，无法核对；区分了事实与快照数据（'dated adoption numbers are snapshots'），机器翻译明确标注非人工。扣分：验证证据文档本身不可审查，且部分声明（如 Windows 行为、CI 全绿）只能信任陈述。
- --force 会完全替换目标文件（包括用户批注），不可恢复，使用前务必备份；默认行为（退出码 3）会保留已有文件。
- LICENSE 版权人 'GimySadek' 与仓库所有者 'JimmySadek' 不一致，且发布者未经验证，采信前请自行确认来源仓库与提交历史。
- 依赖未做完整性锁定（无哈希/lockfile），安装前请审查 requirements.txt 并在隔离环境中安装。
- 依赖 YouTube 未公开接口，随时可能失效或被封锁；脚本不提供任何绕过手段，请勿自行添加 Cookie/代理等改动。
- 主分支为 main，master 仅为历史镜像，请勿在 master 上开发或引用其作为规范来源。
这个 Agent 能做什么，适合哪些场景？
YouTube Fetcher to Markdown（JimmySadek/youtube-fetcher-to-markdown）是一个可移植的 AI-agent 技能，核心是一个 Python 脚本 scripts/fetch_transcript.py，把 YouTube 链接转换成结构化的归档 Markdown 笔记。每次捕获包含完整字幕、标题、频道、时长、上传日期、描述、章节、实际字幕语言及来源信息，写入带 YAML frontmatter 的单个文件，便于在 Obsidian 中用 Dataview 查询，也可移植到 Logseq 或纯文本工作流。脚本通过 YouTube 的非公开字幕接口（经由 youtube-transcript-api）和 oEmbed 获取数据，yt-dlp 为可选依赖，用于更丰富的元数据。它支持手动与自动生成字幕、语言偏好排序、严格语言匹配、显式 YouTube 机器翻译，并可导出 txt、JSON、SRT、WebVTT 格式。安装遵循可移植的 SKILL.md 格式，同一命令可用于 Codex、Claude Code、Cursor、Windsurf、Gemini CLI 等兼容 agent，也可直接手动运行 Python 脚本。项目采用 MIT 许可证，无需 API 密钥、无托管服务。
运行 python3 scripts/fetch_transcript.py "https://youtu.be/VIDEO_ID" 后，脚本依次执行：1) 解析多种 YouTube 输入格式（标准观看 URL、youtu.be 短链、/embed/、/shorts/、/live/、/v/、移动端与 YouTube Music 链接、youtube-nocookie 嵌入链接、11 位视频 ID），拒绝仿冒主机；2) 通过 youtube-transcript-api 的非公开字幕接口抓取手动或自动生成字幕，按 --lang 语言偏好（如 --lang fr,de）或 --lang auto 选择轨道，可用 --strict-lang 禁用英语回退，用 --translate en 触发显式 YouTube 机器翻译；3) 通过 yt-dlp（可选）或 oEmbed 获取标题、频道、时长、上传日期、描述与章节，--no-metadata 可跳过两者；4) 生成一个 Markdown 文件，如 ~/yt_transcripts/2026-03-04_标题_[视频ID].md，内含 YAML frontmatter（title、channel、url、video_id、fetched、language、caption_type、duration、upload_date、tags 等字段）、元数据表格、视频描述和完整字幕；5) --timestamps 添加可点击的时间戳链接，--format 可切换 txt//srt/vtt 导出，--stdout 只打印结果不写文件。写入使用目标旁的临时文件并配合硬链接或独占创建；目标已存在时默认保留并以退出码 3 退出，--force 才完整覆盖。输出位置优先级为 --output、--output-dir、YOUTUBE_FETCHER_DIR、默认 ~/yt_transcripts/。
- Obsidian 用户建立视频知识库：把课程、讲座字幕连同元数据归档进 vault，用 Dataview 按频道、日期、语言查询。
- 内容研究者收集素材：抓取竞品或主题相关视频的描述、章节与字幕，导出 SRT/VTT 供后续剪辑或分析。
- 多语言学习者：用
--lang ja --strict-lang强制要求日文字幕，或用--translate en获取标注为机器翻译的英文版本。 - AI agent 用户（Claude Code、Codex、Cursor 等）：安装为技能后，对话中粘贴 YouTube 链接即可让 agent 自动产出任笔记文件。
- 播客/直播记录者：批量归档 /live/ 或 YouTube Music 链接的可访问字幕，保留来源 URL 与抓取日期的可审计记录。
这个 Agent 有哪些优点和局限？
- 归档完整性突出：不只是裸字幕文本，还包括来源 URL、频道、语言、描述、章节和可预测的文件名，全部在一个本地文件内。
- 语言处理细致：支持有序语言偏好、区域变体（es 可匹配 es-MX）、严格匹配模式和显式标注来源的机器翻译，且语言选择结果记录在 frontmatter 中。
- 文件安全设计严谨：所有格式默认保留已存在文件（退出码 3），写入经临时文件与硬链接/独占创建，符号链接目标拒绝覆盖，支持安全的原地刷新。
- 可移植性强：遵循 SKILL.md 格式，同一安装命令适配 Codex、Claude Code、Cursor、Windsurf、Gemini CLI；也可完全脱离 agent 手动运行。
- 依赖 YouTube 的非公开字幕接口，YouTube 改版或网络封锁可能导致抓取失败，离线测试通过不代表可访问。
- 私有、受限或禁用字幕的视频无法处理，脚本不会伪造或总结缺失的字幕。
- 可选的 yt-dlp 元数据依赖需要额外安装并配置 PATH，否则只能通过 oEmbed 获取有限的标题/频道信息。
- 不做语音识别（Whisper）、说话人识别或视频内容分析；字幕中的识别错误会原样保留。
如何安装或部署这个 Agent？
1) 安装技能：npx skills add JimmySadek/youtube-fetcher-to-markdown，或克隆仓库：git clone https://github.com/JimmySadek/youtube-fetcher-to-markdown.git。2) 在技能目录创建隔离的 Python 环境（支持 Python 3.8–3.14，推荐 3.10+）：python3 -m venv .venv，然后 .venv/bin/python -m pip install -r requirements.txt，再用 .venv/bin/python scripts/fetch_transcript.py --check-deps 验证依赖。Windows PowerShell 对应命令为 py -m venv .venv 与 .venv\Scripts\python.exe ...。3) 可选安装 yt-dlp 以获取描述、章节、时长和上传日期：.venv/bin/python -m pip install yt-dlp，并把其可执行文件放入 PATH（激活环境即可）。无需任何 API 密钥。
如何使用这个 Agent？
基本用法：python3 scripts/fetch_transcript.py "https://youtu.be/VIDEO_ID"（先激活 .venv 或使用完整解释器路径）。常用示例：保存到 Obsidian vault：python3 scripts/fetch_transcript.py URL --output-dir ~/Notes/MyVault；设置持久目录：export YOUTUBE_FETCHER_DIR=~/Notes/MyVault；语言偏好：python3 scripts/fetch_transcript.py --lang fr,de -- URL；严格日文字幕：--lang ja --strict-lang -- URL；机器翻译：--lang auto --translate en -- URL；查看可用字幕语言：--list -- URL；其他导出：--format srt URL、--format --output captions. URL、--stdout --timestamps -- URL。输出位置按 --output > --output-dir > YOUTUBE_FETCHER_DIR > ~/yt_transcripts/ 的优先级决定。agent 使用时应相对于已安装的 SKILL.md 解析脚本路径，并使用隔离环境的解释器。