---
name: 整理视频为笔记
description: "要把视频或图文帖整理成学习笔记时用：分下载、分析、输出三段，前两段跑 agent-io 的平台下载脚本和 video_read.py，取下内容、出关键帧和转写；输出段跑本 skill 的 prepare_note.py 出证据索引和篇幅预算，Agent 按预算写学习型笔记，写完 score_note.py 验收"
---

# 整理视频为笔记

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

## 三段 { #workflow }

| 环节 | 跑什么 | 得到什么 |
|---|---|---|
| 下载 | agent-io 按平台的 `xiaohongshu.py`、`douyin.py`、`bilibili.py`：`<平台>.py <链接> --out <目录>` | `<目录>/<平台>_<ID>/`：元数据、正文、图、视频，B 站另有字幕和评论 |
| 分析 | agent-io 的 `video_read.py <文件夹>` | 关键帧联系图、单帧、转写、`read.json` |
| 输出 | 本 skill 的 `prepare_note.py <文件夹>`，写笔记，再 `score_note.py <文件夹> <笔记>` | `note/evidence.md`、`note/budget.json`、笔记、`note/score.json` |

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

## 下载 { #download }

照[解析分享链接](../agent-io/reference/share-link/index.md)跑：

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

## 分析 { #analyze }

照[阅读视频](../agent-io/reference/read-video.md)跑：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`、时间和结论，看不清的标「待核实」；它是写笔记前给自己记的，笔记里引用关键帧编号就行
- 短视频别只看每分钟字数：教程、演示类讲得再满，操作也在画面里；口播说「用到的指令都在这里」「写入这段描述词」，内容就在画面上，标题像教程就看关键帧
- 当前模型看不了图，就告诉用户关键帧理解要能看图的模型；笔记只基于字幕、转写和元数据，在「来源、覆盖与局限」写明

## 输出 { #output }

### 写前：证据索引和预算 { #prepare }

```bash
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用的是字幕、转写还是没有

### 笔记写法 { #note }

默认写学习型笔记，不是目录搬运、分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. `## 来源、覆盖与局限`：写法同上

活例：[五张牌魔术](../../notes/probability/five-card-trick.md)，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压成一句话，长课程读完仍不知道怎么做。
- 视频字幕极少，却没提示画面依赖，也没看关键帧。
- 只总结作者立场，不写适用条件、反例和失败场景。
- 评论区只是罗列热评，没有转化成纠错、补充或实践提醒。

### 写后：验收 { #score }

```bash
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`：笔记里用到了几条证据、几张关键帧
- 太短时优先补概念解释、流程、实践清单、自测题、反例和边界，不要只加摘要段落；评分只做验收和微调，长度在写前就按预算定好

## 转写的坑 { #pitfalls }

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

## 脚本 { #scripts }

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

<div class="zx-no-copy" markdown>

---

维护记录：[从哪来、改了什么](../../maintenance/skills/video-note.md)。正常使用不用看，出问题再看。

</div>