video-note-render-pdf-v2

name

video-note-render-pdf-v2

description

Use when the user wants to turn a YouTube or Bilibili lecture, tutorial, or technical talk into a structured Chinese LaTeX/PDF note that preserves the video's real teaching content, enforces subtitle-char length guardrails, routes figure strategy through carrier-family/support-profile/recall-budget, records visual obligations explicitly, and closes with a real post-build revision loop through the unified video-note wrapper plus an external runtime repo.

Video Note Render PDF Wrapper v2

这是在 video-note-render-pdf-v1 基础上改写的 thin wrapper。真正的运行时代码仍然位于外部 video-note-pipeline 类 runtime repo；当前 skill 只保留统一入口、模板、参考文档和轻量路径解析脚本。

v2 的核心变化只有四件事：

• 用字幕字数 guardrail 控制总字数下限，而不是只说“roughly proportional”
• 把 mode routing 改成 carrier family + support profile + recall budget 三轴
• 把图片规划升级成显式的 visual obligation ledger
• 把事后修改从“写 review 文件”升级成“review 触发具体 patch 和 action log”

Goal

统一 video-note pipeline 的目标仍然是产出一份高质量、可交付的中文 .tex 讲义和最终 PDF，而不是只把字幕改写成摘要。默认交付应尽量满足：

• 以视频真实教学内容为主，而不是仅依赖字幕转写
• 主体篇幅与视频内容强度同向扩张，尤其不能把长视频压成固定厚度摘要
• 首页优先使用视频官方封面图，而不是任意视频帧
• 图片由正文写作需求和视觉义务驱动，而不是按“每章几张图”硬配额
• 文末包含一个真正的 \section{总结与延伸}，吸收讲者有价值的 closing discussion，并加入你自己的结构化提炼
• 完稿后重新对照字幕、关键图片和页面预览做事后修订，而不是把重复 build 视为已经完成复查
• 最终结果包含完整 .tex、本地图片资源和成功编译的 PDF

平台摘要

统一 skill 不再按平台拆成两个平行入口，但平台特有边界仍然存在：

• YouTube：优先使用公开视频可直接获得的官方字幕，手工字幕优先于自动字幕
• Bilibili：字幕更稀缺，1080P+ 常常需要 cookies，分 P 视频要先明确处理范围，b23.tv 需要归一化，弹幕不能作为教学内容源
• 当平台字幕与 cookies 字幕都不可用时，才进入 ASR fallback；若字幕和 ASR 都不可接受，允许转入 visual-only 的取图与重绘思路

平台细则见 references/platform-notes.md。

外部依赖与工作区

• 规划中的 canonical runtime repo：WncFht/video-note-pipeline
• 默认 clone 路径：$HOME/Desktop/src/video-note-pipeline
• 环境变量：VIDEO_NOTE_PIPELINE_REPO
• source override key：repo:WncFht/video-note-pipeline
• 默认 case workspace：<runtime_repo>/.local/workspaces/video-notes
• workspace 环境变量：VIDEO_NOTE_WORKSPACE_ROOT
• workspace override key：workspace:video-notes
• 安装命令：在 agent-basic-skill 仓根目录运行 python scripts/install_skill.py video-note-render-pdf-v2

安装器会读取同目录下的 external-repos.json；它只在显式安装时检查或 clone 外部仓，运行时 resolver 仍然只做检测不做安装。

如果 runtime repo 的远端还没稳定发布，优先通过环境变量或 local source override 指向本地 clone。

首次进入 runtime repo 后，优先执行：

uv sync --extra dev
pre-commit install

如果本机需要本地 ASR backend，再按需增加：

uv sync --extra dev --extra asr-cpu

先解析 runtime repo 与 workspace

优先级：

1. 显式参数：--runtime-repo、--workspace-root
2. 环境变量：VIDEO_NOTE_PIPELINE_REPO、VIDEO_NOTE_WORKSPACE_ROOT
3. 本地 source override：repo:WncFht/video-note-pipeline、workspace:video-notes
4. 默认候选路径：runtime repo 下的 .local/workspaces/video-notes；runtime repo 自身仍优先从 $HOME/Desktop/src/video-note-pipeline、$HOME/Desktop/src/video_note_pipeline 检测

解析示例：

python scripts/resolve_video_note_paths.py --json

只打印 runtime repo：

python scripts/resolve_video_note_paths.py --print runtime_repo

如果解析失败，先修正路径与环境，再继续后续 pipeline。若未显式指定，workspace 默认解析到 runtime repo 下的 .local/workspaces/video-notes，并由 runtime 在实际运行时按需创建。不要把下载产物、cache、cookie、模型文件或 case 输出写回当前 skill 目录。

运行时边界

skill 目录只保留：

• SKILL.md
• agents/openai.yaml
• assets/notes-template.tex
• assets/case-manifest.template.json
• references/*.md
• scripts/resolve_video_note_paths.py

runtime repo 负责：

• URL 归一化与 platform adapter
• metadata / subtitle / cookies / format / ASR probe
• transcript 标准化输出
• overview frames / montage / extraction helper
• build / preview / QA helper

如果运行时没有先产出事实层 artifact，不要直接进入正文写作。

必要 artifact contract

在模型开始组织正文前，case 目录至少应具备：

• metadata.json
• preflight.json
• preflight.json.recommended_mode
• subtitle_probe.json
• transcriber_probe.json
• transcript.json
• transcript.srt
• transcript.txt

推荐同时维护：

• case_manifest.json
• work/section_alignment.json
• work/visual_obligation_ledger.json
• overview_frames/ 或 montage
• figures/
• review/revision-actions.json
• note.tex
• note.pdf

字段和目录约定见：

• references/adapter-contract.md
• references/case-bundle-contract.md
• references/mode-routing.md

Subtitle-first 约束

统一 pipeline 必须遵循：

1. 先探测平台官方字幕
2. 匿名路径失败后再探测 cookies 路径
3. 两层平台字幕都失败后，才进入 ASR probe / wrapper fallback

额外要求：

• 手工字幕优先于自动字幕
• 保留时间戳，不要过早压平为纯文本
• 记录字幕来源、语言、是否使用 cookies
• ASR 只负责 fallback，不是默认主路径

Length Guardrail

正式写正文前，先根据 transcript.txt 计算字数 guardrail。这里控制的是 note.tex 的正文总字数，不是 PDF 页数。

先算四个字段：

• transcript_txt_chars
• min_note_chars
• soft_note_char_range
• compression_ratio = min_note_chars / transcript_txt_chars

默认先用这张分段启发式表：

字幕字数 S	建议保底下限	常见舒适区
S < 5000	至少 6000 字	6000 ~ 12000 字
5000 <= S < 15000	至少 0.55S	0.55S ~ 1.00S
15000 <= S < 35000	至少 0.40S	0.40S ~ 0.70S
35000 <= S < 70000	至少 0.30S	0.30S ~ 0.55S
S >= 70000	至少 0.18S	0.18S ~ 0.35S

执行时遵循：

• 优先把这张表写入 work/section_alignment.json
• 页数只作为排版诊断，不要写进预算目标
• 低于 min_note_chars 时，必须再做一次 coverage pass
• 高于软范围通常可以接受，只要新增内容确实有教学价值
• v2 的默认取向是“宁可略长，不要明显偏短”

Teaching Content Rules

优先从以下信息重建讲义：

• 视频标题、章节、时长与关键信息
• 视频官方封面与 metadata
• 幻灯片、白板、公式、图表、表格、产品界面与代码片段
• 字幕中的解释、举例和口头强调

以下内容默认不应进入正文主叙事，除非它们本身承载教学价值：

• greetings
• small talk
• sponsorship
• channel logistics，例如“一键三连”、关注、投币、抽奖、口播推广
• Bilibili 弹幕 或其他高噪声互动文本
• 纯礼貌性的 closing pleasantries

如果讲者在结尾部分给出了总结、局限、经验判断、后续方向、实践建议或开放问题，应把这些内容保留到最终 总结与延伸 中，而不是简单裁掉。若 transcript 质量不足以支撑判断，先修事实层 artifact，必要时切换到 visual-only 思维模式，而不是硬写。

推荐工作流

1. 解析 runtime repo 与 workspace 路径。
2. 若是 Bilibili 分 P 视频，先确认本次要处理哪些 part，并把选择结果写入 case metadata。
3. 如果需要 cookies，先在 runtime repo 中运行 uv run video-note cookies-export youtube --browser edge 或 uv run video-note cookies-export bilibili --browser edge。
4. 在 runtime repo 中按顺序运行 uv run video-note prepare <url>、uv run video-note probe <url>、uv run video-note transcript <url>、uv run video-note overview <url>。
5. 检查 recommended_mode、overview montage、part selection 和 transcript 质量，先确认内容覆盖风险，而不是直接进入固定配图节奏。
6. 先计算长度 guardrail，并把 transcript_txt_chars / min_note_chars / soft_note_char_range / compression_ratio 写入 work/section_alignment.json。
7. 在写正文前明确三轴路由：carrier family + support profile + recall budget。每个标签的中文解释见 references/mode-routing.md。
8. 先做 lightweight content map，按主题段或时间段估计主体章节的相对写作权重；长视频、高字幕量或 evidence-heavy case 默认把结果显式落成 work/section_alignment.json 或 review/coverage-note.md。
9. 对 demo-led、anchor-dense、document-led evidence 这三类段落，先建 work/visual_obligation_ledger.json，再决定图数和图的来源。
10. 从 assets/notes-template.tex 起稿，必要时用 assets/case-manifest.template.json 固定 case 元数据。正文先写完整，再按视觉义务去兑现或豁免每一张图。
11. 写出完整 note.tex，用 uv run video-note build <url> 或 latexmk -xelatex 编译并生成 pdf_preview/。
12. 至少做一轮三段式 revision loop：coverage pass 重新对照字幕，figure pass 重新审阅图片必要性与清晰度，page pass 结合 pdf_preview/ 修版式与页面级问题；如果 review 发现中等以上问题，必须把动作写进 review/revision-actions.json。

写作与配图规则

1. 默认使用中文写作，除非用户另有要求。
2. 使用 \section{...} / \subsection{...} 重建教学结构，而不是机械抄字幕。
3. 首页优先使用视频官方封面图，而不是任意视频帧。
4. 主体章节与小节的篇幅分配，应大致反映视频中各主要段落的时长、字幕密度与论证强度；不要把长视频主体默认压成固定厚度摘要。
5. 最终 note.tex 字数默认不应低于 min_note_chars。若接近或跌破下限，先扩 coverage，再考虑删图或压缩。
6. 每个大章节以 \subsection{本章小结} 收束；有必要时可增加 \subsection{拓展阅读}；文末必须有 \section{总结与延伸}，并纳入 speaker closing discussion、你的 own distillation 与明确 takeaways。
7. 图片必须由视觉义务驱动。先判断这段需要的是 evidence、explanation、demo-pair、anchor-pair 还是 orientation，再决定去视频帧、外部原件还是自绘图找支撑。
8. 任何写进 visual_obligation_ledger 且最终仍保留在正文里的义务，必须落成三选一：保留 figure、改成 derived figure、显式记录 waiver 原因。
9. 对来自视频帧的图像，禁止接受潦草的图像处理；若裁剪、放大或 pair 之后仍不清楚，应改成重绘、外部原件或直接删图。
10. 数学公式使用展示公式，并紧跟扁平列表解释符号。
11. 代码示例使用 lstlisting，并带描述性 caption。
12. importantbox 用于核心概念与关键机制，knowledgebox 用于补充背景与类比，warningbox 用于误区、限制和易错点；三类盒子都只承载高信号内容，不做装饰。
13. 图片必须放在盒子之外。
14. 任何来自视频帧的图像，都要在同页底部注明具体时间区间。
15. 选图按教学价值，不按固定配额；同一节可以有多张关键图。
16. 遇到逐步显现的幻灯片、白板或动画时，优先定位最终完整可读状态。
17. 不要因为省时间而跳过高召回候选帧检查，也不要把字幕密度误当成视觉密度。
18. 截图仍不够清晰时，优先补充 TikZ / PGFPlots 或外部生成图，而不是塞进低信息截图。
19. 完稿后至少重新阅读一次字幕中的重点段和最终保留的关键图片，再决定是否补写、删图或改图。

更细的三轴路由、visual obligation ledger、delivery expectations 与 revision contract 见：

• references/mode-routing.md
• references/figure-delivery-guidance.md
• references/coverage-and-revision-guidance.md

编译与验证

推荐命令：

latexmk -xelatex -interaction=nonstopmode note.tex

最低验证要求：

• .tex 可编译
• work/section_alignment.json 已记录长度 guardrail 与 routing 结论
• work/visual_obligation_ledger.json 对需要高视觉召回的段落已填写或明确免除
• PDF 中封面图、关键 figures、footnote provenance 与目录结构都正确
• 没有 [cite] 占位符
• figure 的时间区间与正文描述一致
• 主体章节篇幅没有明显跌破 min_note_chars 约束
• 若 review/*.md 写出中等以上问题，则 review/revision-actions.json 里必须能看到对应动作；否则不能声称 revision loop 已完成

交付物

默认交付 bundle 至少包括：

• 最终 note.tex
• 首页引用的官方封面图
• 正文引用的本地 figure assets
• 成功编译的 note.pdf

以下场景推荐同时保留：

• transcript.srt
• case_manifest.json
• work/section_alignment.json
• work/visual_obligation_ledger.json
• review/revision-actions.json
• pdf_preview/ 或其他 QA 产物

如果在 Windows 上运行 runtime repo，优先确认：

• ffmpeg、latexmk 在 PATH 中
• case workspace 不要落到只读目录
• transcriber_probe.json 已确认 CUDA sample 成功；否则默认按 CPU 路径处理

按需读取的参考文档

• references/adapter-contract.md
• references/case-bundle-contract.md
• references/coverage-and-revision-guidance.md
• references/figure-delivery-guidance.md
• references/mode-routing.md
• references/platform-notes.md
• references/runbook.md
• references/troubleshooting.md