整理视频为笔记

把视频（还有 B 站图文、小红书图文这类图文帖）整理成能回查的 Markdown 学习笔记。难点有三个：字幕不等于理解，PPT、板书、代码演示里的信息字幕里没有；长课和短视频容易写成差不多长；笔记里的判断回查不到原话。所以分三段：下载、分析交给 Agent 基础能力的脚本，把内容取下来，把画面和声音变成能读的东西；输出段在这里，脚本出证据索引和篇幅预算，Agent 按预算写学习型笔记，写完用脚本打分。如果要调用 2 次以上本 skill 中的脚本，直接将本 skill下载到本地。

三段

• 每段都能单独跑，也能从中间接着跑：手上已有视频文件就从分析开始，已有文件夹就跳过下载
• 花钱的步骤直接做，做完在汇报里写清花了多少
• 文件夹就是这条视频的归档：放在仓库外、空间够的盘上长期留着，路径写进笔记的「来源、覆盖与局限」
• 笔记放用户指定的位置；收进本 wiki 就按内容归进 notes/ 的对应分类，做成品的教程并进 Gallery 的成品页；用到的关键帧复制进同目录的 assets/，照写作规范挂索引、注册 nav

下载

照解析分享链接跑：

• 用户要评论区就加 --comments，只有 B 站能取，抖音、小红书的评论没接；写进笔记时过滤打卡、求资料、广告、闲聊
• 多P的长课先加 --no-video 跑一次，看 meta.json 的 parts，再用 --parts 挑要的P；用户明确要全部才全取
• B 站字幕多半要登录才给，拿不到没关系，分析段会转写

分析

照阅读视频跑：3 分钟以内的视频按画面切换取帧，更长的均匀撒 12 帧；没字幕、有声音的P自动转写。

• 先看 keyframes/contact_sheet_01.jpg 和 read.json；联系图里有文字、代码、图表、界面时，照格子里的序号打开对应单帧
• 联系图上空了一段、转写说到的操作没拍到，就用 video_read.py --at 20,22.5 <文件夹> 按时间点补帧（第 2P 写 2@30），再重跑 prepare_note.py，补的帧进证据索引；别另外手抽，手抽的进不了索引。--force 只重做取帧，不重新转写
• 画面上看到的写进 note/visual_review.md，每条带关键帧编号 KF-P01-03、时间和结论，看不清的标「待核实」；它是写笔记前给自己记的，笔记里引用关键帧编号就行
• 短视频别只看每分钟字数：教程、演示类讲得再满，操作也在画面里；口播说「用到的指令都在这里」「写入这段描述词」，内容就在画面上，标题像教程就看关键帧
• 当前模型看不了图，就告诉用户关键帧理解要能看图的模型；笔记只基于字幕、转写和元数据，在「来源、覆盖与局限」写明

输出

写前：证据索引和预算

python3 scripts/prepare_note.py <文件夹>

• note/evidence.md：每条证据一个标题，编号是：字幕或转写块 P01@00:01:20-00:02:05（550 字或 14 行一块）、关键帧 KF-P01-03、正文块 A-001、图片 IMG-01、评论 C<rpid>（楼中楼跟在下面）。note/evidence.jsonl 是同一份，一行一条
• note/budget.json 先读，定下这次的写作目标：
  • 推荐字数：recommended_note_chars_min 到 recommended_note_chars_max；不到 3 分钟的视频下限 400 字，关键帧越多给得越多，短图文不会超过原文太多
  • 写多细：granularity 和 writing_guidance
  • 画面依赖：visual_dependency.risk 是 medium 或 high 时先看关键帧，不能写成完整解析；warnings 要转述给用户
  • 互动倍率：quality.quality_multiplier，点赞、收藏、投币、评论、弹幕、分享、播放量和发布天数合成，0.85–1.4，调高或调低推荐字数；没有播放量的小红书、抖音固定 1.0
  • 文字从哪来：text_coverage 写着每P用的是字幕、转写还是没有

笔记写法

默认写学习型笔记，不是目录搬运、分P流水账或证据清单。读完要有「我真的学会了一些东西」的获得感。

如果视频本身是一道可独立成题的小问题，别套下面的长文结构；按 notes/ 对应分类的题目骨架写（题 → 一句话 → 关键技巧 → 解 → 延伸），证据仍用脚注。

推荐结构：

1. # 标题
2. ## 学完你应该获得什么：用 5–8 条写清楚读者学完后能理解、判断或完成什么。
3. ## 一句话总论：说明视频最核心的判断，不要只复述标题。
4. ## 适用场景与前置知识：这套内容适合谁、不适合谁，读者要先知道什么。
5. ## 知识地图：把核心概念、模块、流程和它们之间的关系讲清楚。课程型视频要有模块表；短观点视频要有论证链。
6. ## 核心概念卡：每个重要概念都写成「是什么、为什么重要、怎么用、常见误区、相关证据」。
7. ## 方法或流程：把原内容里的操作、架构、决策流程、参数选择、评估方法抽成可复用的步骤。
8. ## 关键洞察：写作者真正想表达的判断，区分事实描述、经验判断、推荐做法和限制条件。
9. ## 实践清单：给出能照着做的步骤、检查项、失败信号和排错方向。
10. ## 坑点与反例：整理视频和评论区提到的踩坑、争议、误区和边界条件。
11. ## 自测题：写 5–10 个问题和简短答案，帮人或 Agent 检查学没学会。
12. ## 来源、覆盖与局限：URL、平台和 ID（B 站是 BV 号）、作者、发布时间、字幕或转写和评论的覆盖、材料文件夹路径和局限放在最后。

短视频的精简结构 { #clip }：不到 3 分钟的视频（granularity 是 clip）一般只讲一个观点或一套操作，13 节会写成注水。改成：

1. # 标题
2. ## 一句话总论
3. ## 要点：3–5 条；教程类写成按顺序的操作步骤
4. ## 画面里的信息：字幕里没有、画面上有的界面、参数、提示词、成品效果，关联 KF-P01-03
5. ## 拿来怎么用：迁移到自己场景的一两条做法和前提
6. ## 来源、覆盖与局限：写法同上

活例：五张牌魔术，6 分半的抖音科普；内容是一道题，所以最后按 notes 的题目骨架写成智力题。

写作标准：

• 先解释「为什么」和「怎么迁移使用」，再列「他说了什么」。
• 课程型长视频按学习模块组织，不要按分P机械压缩。每个模块至少有学习目标、核心概念、关键步骤、常见坑和可操作的结论。
• 观点型短视频按「问题背景 → 作者判断 → 论据 → 适用边界 → 对用户的启发」组织。
• 技术教程和图文长文保留架构、数据流、代码思路、配置项、图片结论、评估方式和排错路径。
• 评论区只写有学习价值的内容：纠错、补充案例、实践经验、替代方案、争议点。
• 证据用脚注：照写作规范，正文写 [^名]，外部链接也只进脚注，不在段落里塞长证据 ID。脚注写证据 ID 和一句话；视频证据再写原视频的时间点：B 站写能跳到那一秒的链接 https://www.bilibili.com/video/<BV号>/?p=1&t=80，抖音、小红书没有按秒跳转的链接，写「第 N 秒」。ID 写全，写成区间（KF-P01-03～KF-P01-06）也算区间里的每一条。全文在材料文件夹的 note/evidence.md。
• 画面上的提示词、命令、参数照原文抄，放进代码块；其余用自己的话写，只摘短句。
• 热度是「值得多写」的辅助信号，不是证据：扩写的内容必须来自正文、字幕或转写、画面和评论。
• 只看了标题、目录的内容，不要写成「完整提取」；只转写了部分分P时，明确列出覆盖范围。

不合格信号：

• 开头大段来源信息，读者看半天还不知道学到了什么。
• 只有「核心观点 / 分P提炼 / 代表性证据」，没有概念解释、方法步骤和自测。
• 每个分P压成一句话，长课程读完仍不知道怎么做。
• 视频字幕极少，却没提示画面依赖，也没看关键帧。
• 只总结作者立场，不写适用条件、反例和失败场景。
• 评论区只是罗列热评，没有转化成纠错、补充或实践提醒。

写后：验收

python3 scripts/score_note.py <文件夹> <笔记.md>

• status：too_short 表示遗漏风险高，too_long 表示可能在重复堆料，ok 表示落在写前的推荐区间。字数不算 frontmatter、代码块、HTML 标签、图片属性和脚注：并排图、照抄的提示词和脚注都不占预算
• compression_ratio：笔记字数比原内容字数；note_chars_per_minute：每分钟视频对应多少笔记字，长课程不该和短视频的总字数差不多
• evidence_used / evidence_total、keyframes_used：笔记里用到了几条证据、几张关键帧
• 太短时优先补概念解释、流程、实践清单、自测题、反例和边界，不要只加摘要段落；评分只做验收和微调，长度在写前就按预算定好

转写的坑

• 转写常把技术词识别错：RAG 可能识别成 RG、ROG、rap；LangChain 可能识别成 non chain、long chain；reranker 可能识别成「瑞 rank」。总结时结合分P标题和技术语境校正术语
• 平台名、产品名也常听错：「即梦」转成了「小梦」。拿画面上的字核对，画面上也没有的写「待核实」

脚本

• prepare_note.py：读下载、分析两段产出的文件夹，写证据索引和篇幅预算
• score_note.py：按预算给写好的笔记打分