| name | video-note-render-pdf-v0 |
| 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, keeps the official cover on the front page, selects figures with subtitle-aligned high-recall frame search, ends with a final synthesis chapter, and routes through the unified video-note wrapper plus an external runtime repo. |
Video Note Render PDF Wrapper
这是一个 thin wrapper。真正的运行时代码应位于外部 video-note-pipeline 类 runtime repo 中;当前 skill 只保留统一入口、模板、参考文档和轻量路径解析脚本。
Goal
统一 video-note pipeline 的目标仍然是产出一份高质量、可交付的中文 .tex 讲义和最终 PDF,而不是只把字幕改写成摘要。默认交付应尽量满足:
- 以视频真实教学内容为主,而不是仅依赖字幕转写
- 首页优先使用视频官方封面图,而不是任意视频帧
- 关键章节按教学价值选择足够多的高信息量 figures
- 文末包含一个真正的
\section{总结与延伸},吸收讲者有价值的 closing discussion,并加入你自己的结构化提炼
- 最终结果包含完整
.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-v0
安装器会读取同目录下的 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
优先级:
- 显式参数:
--runtime-repo、--workspace-root
- 环境变量:
VIDEO_NOTE_PIPELINE_REPO、VIDEO_NOTE_WORKSPACE_ROOT
- 本地 source override:
repo:WncFht/video-note-pipeline、workspace:video-notes
- 默认候选路径: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
overview_frames/ 或 montage
figures/
note.tex
note.pdf
字段和目录约定见:
references/adapter-contract.md
references/case-bundle-contract.md
references/mode-routing.md
Subtitle-first 约束
统一 pipeline 必须遵循:
- 先探测平台官方字幕
- 匿名路径失败后再探测 cookies 路径
- 两层平台字幕都失败后,才进入 ASR probe / wrapper fallback
额外要求:
- 手工字幕优先于自动字幕
- 保留时间戳,不要过早压平为纯文本
- 记录字幕来源、语言、是否使用 cookies
- ASR 只负责 fallback,不是默认主路径
Teaching Content Rules
优先从以下信息重建讲义:
- 视频标题、章节、时长与关键信息
- 视频官方封面与 metadata
- 幻灯片、白板、公式、图表、表格、产品界面与代码片段
- 字幕中的解释、举例和口头强调
以下内容默认不应进入正文主叙事,除非它们本身承载教学价值:
- greetings
- small talk
- sponsorship
- channel logistics,例如“一键三连”、关注、投币、抽奖、口播推广
- Bilibili 弹幕 或其他高噪声互动文本
- 纯礼貌性的 closing pleasantries
如果讲者在结尾部分给出了总结、局限、经验判断、后续方向、实践建议或开放问题,应把这些内容保留到最终 总结与延伸 中,而不是简单裁掉。若 transcript 质量不足以支撑判断,先修事实层 artifact,必要时切换到 visual-only 思维模式,而不是硬写。
推荐工作流
- 解析 runtime repo 与 workspace 路径。
- 若是 Bilibili 分 P 视频,先确认本次要处理哪些 part,并把选择结果写入 case metadata。
- 如果需要 cookies,先在 runtime repo 中运行
uv run video-note cookies-export youtube --browser edge 或 uv run video-note cookies-export bilibili --browser edge。
- 在 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>。
- 检查
recommended_mode、overview montage、part selection 和 transcript 质量,再决定截图强度。
- 从
assets/notes-template.tex 起稿,必要时用 assets/case-manifest.template.json 固定 case 元数据。
- 让模型在
talking-head / visual-light / static-outline / board-heavy 之间确认或覆写模式。
- 依据字幕时间窗和 montage 结果选图;先高召回,再下采样。
- 写出完整
note.tex,再用 uv run video-note build <url> 或 latexmk -xelatex 编译并做 PDF 预览检查。
写作与配图规则
- 默认使用中文写作,除非用户另有要求。
- 使用
\section{...} / \subsection{...} 重建教学结构,而不是机械抄字幕。
- 首页优先使用视频官方封面图,而不是任意视频帧。
- 每个大章节以
\subsection{本章小结} 收束;有必要时可增加 \subsection{拓展阅读};文末必须有 \section{总结与延伸},并纳入 speaker closing discussion、你的 own distillation 与明确 takeaways。
- 数学公式使用展示公式,并紧跟扁平列表解释符号。
- 代码示例使用
lstlisting,并带描述性 caption。
importantbox 用于核心概念与关键机制,knowledgebox 用于补充背景与类比,warningbox 用于误区、限制和易错点;三类盒子都只承载高信号内容,不做装饰。
- 图片必须放在盒子之外。
- 任何来自视频帧的图像,都要在同页底部注明具体时间区间。
- 选图按教学价值,不按固定配额;同一节可以有多张关键图。
- 遇到逐步显现的幻灯片、白板或动画时,优先定位最终完整可读状态。
- 不要因为省时间而跳过高召回候选帧检查,也不要把字幕密度误当成视觉密度。
- 截图仍不够清晰时,优先补充 TikZ / PGFPlots 或外部生成图,而不是塞进低信息截图。
更细的 figure heuristics、delivery expectations 与最终章节检查项见 references/figure-delivery-guidance.md。
编译与验证
推荐命令:
latexmk -xelatex -interaction=nonstopmode note.tex
最低验证要求:
.tex 可编译
- PDF 中封面图、关键 figures、footnote provenance 与目录结构都正确
- 没有
[cite] 占位符
- figure 的时间区间与正文描述一致
交付物
默认交付 bundle 至少包括:
- 最终
note.tex
- 首页引用的官方封面图
- 正文引用的本地 figure assets
- 成功编译的
note.pdf
如果本次 case 依赖 ASR 或需要复盘字幕来源,推荐同时保留:
transcript.srt
case_manifest.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/platform-notes.md
references/figure-delivery-guidance.md
references/mode-routing.md
references/runbook.md
references/troubleshooting.md