Youtube-note-forge

YouTube 转录 v4.0.0

主要全产品运行时是 youtube-note-reader Obsidian 桌面插件。它拥有确定的状态机，调用配置的 OpenAI 兼容模型，运行这些脚本，持久化任务状态，并将完成的笔记写入活动的 Vault。Chrome 扩展仅提供当前视频 URL 和浏览器 Cookie。OpenCode 仍然是一个可选的仅技能入口点，并非完整的浏览器 + Obsidian 安装所必需。

将此技能用作严格的状态机。不要临时设计替代的提取路径。

版本

当用户询问当前版本时，运行：

python .obsidian/skills/youtube-transcript/scripts/video_note.py --version

返回命令输出。永远不要凭记忆回答。它报告已安装的版本、源路径以及核心文件的 SHA-256 值。

固定工作流

对于每个 URL，在进入下一个 URL 之前完成以下步骤。在第一个非零脚本结果处停止整个批次。

1. 提取源材料：

python .obsidian/skills/youtube-transcript/scripts/extract_transcript.py "<url>" --output-dir "YouTube video" --deadline 300

2. 阅读生成的笔记及其 SRT。创建一个包含 article_outline 和 frames 的 JSON 计划。article_outline 包含 3-8 个基于转录的章节；每个项目都有 section_id、title、start、end、core_claims 和 learning_goal。根据学习价值选择帧，通常每个视觉上有意义的章节需要一个必需的帧，外加用于不同步骤或结果的可选证据。大多数视频需要 6-14 帧；24 只是硬性安全限制，永远不是目标。不要仅为了增加数量而创建多个几乎相同的时间点。每个帧都有 section_id、timestamp、purpose 和 required。使用相同的 section_id 将每个截图绑定到其详细总结的章节。暂时不要重命名或重写笔记。不要编写探测脚本或手动检查视频格式。
3. 仅提取计划帧一次。在成功获取材料结果后，这是唯一允许的下一个可执行命令：

python .obsidian/skills/youtube-transcript/scripts/extract_frames.py "<url>" --plan "<plan.json>" --note "<generated-note.md>" --output-dir "YouTube video" --deadline 120

4. 确认帧结果具有 status: ok、至少一个截图以及真实的 manifest 路径。脚本会自动将 frame_manifest 写入笔记 YAML。如果缺少其中任何一项，请停止；不要写入最终笔记，也不要用封面替换。
5. 根据 references/note-contract.md 就地重命名并重写生成的笔记。在 ## 详细内容总结 下，使用每个 article_outline.title 作为精确的 ### 标题，解释其核心主张，并将每个必需的、成功的帧插入到其匹配的章节中，并附上中文说明。对于 Vault 本地截图，始终使用 Obsidian Wiki 嵌入，例如 ![[YouTube video/assets/VIDEO_ID/frame.jpg]]；永远不要使用包含空格的未转义 Markdown 目标。只有清单中列出的图像才计为截图。
6. 验证：

python .obsidian/skills/youtube-transcript/scripts/validate_note.py "<finished-note.md>"

7. 如果验证失败，仅编辑该笔记一次，并再次运行验证器。在此修复期间，永远不要运行提取、编写临时脚本、检查实现代码或诊断平台行为。如果仍然失败，停止并报告返回的错误。成功验证后，验证器仅删除同一文件夹中 YAML url 与最终笔记完全匹配的 待命名 - ... Markdown 草稿；未匹配的中断草稿将保留以供恢复。

故障策略

PIPELINE_RESULT 是事实来源。遇到 status: error 时，立即停止并报告 URL、阶段、代码、消息、动作、已完成的 URL 和未开始的 URL。

永远不要通过运行另一个下载器、浏览器、Puppeteer、Chrome/Edge Cookie 提取、网络搜索、音频录制或第二次尝试来回应故障。唯一受控的重试在脚本内部：一次最后已知良好的 Cookie 检查和在目标帧提取期间的一次视频流 URL 刷新。

ASR 默认禁用。仅当用户明确接受音频下载和较慢处理时，才使用 --allow-asr。

视觉要求

• 截图是证据，而非装饰。
• 使用演示、界面、图表、参数、比较状态和结果。
• 帧脚本首先使用带有 yt-dlp 请求头的远程 720p 或更低分辨率流。如果远程查找失败，它可能仅下载每个计划时间点周围 8 秒的有限片段。临时片段会立即删除，并且绝不会为了截图而下载完整视频。
• 必需帧失败或帧计划覆盖率低于 70% 是硬性失败。
• 封面、缩略图、手动复制的图像或重复的嵌入绝不视为关键帧。
• 即使它们的整体布局看起来相似，也保留计划帧。终端文本、代码、幻灯片和 UI 状态变化都是有用的。仅拒绝完全空白的黑/白帧；不要使用 OCR、AI 图像分析或感知重复过滤。
• 除非存在 frame_manifest 并且每个必需的清单帧都出现在 ## 详细内容总结 中，否则永远不要声称完成。
• 不要创建 Canvas 文件。

最终笔记要求

• 文件名：中文标题 - English Title。
• YAML 包含 skill_version: 4.0.0、quality_profile_version: 1 以及由 extract_frames.py 写入的有效 frame_manifest。
• 正文以 ## 一句话摘要 开头，没有重复的 H1 标题。
• 从最终正文中删除源状态、视频描述、视觉材料索引、提取警告、任务说明和自检部分；YAML 已携带源元数据。
• 优先使用中文；首次使用时解释必要的英文术语。
• 让转录决定文章大纲和深度。图像支持解释；切勿仅仅因为缺少匹配的帧而缩短或省略重要内容。
• 使文章深度与视频时长匹配。每个计划的章节都需要一个真实的解释、视频证据或示例，以及清晰的学习含义。避免泛泛的填充内容和重复的段落。
• 在末尾链接 SRT。不要粘贴原始转录文本。
• 在最终完成之前删除自检清单。