头像

白日梦与诗

林深时见鹿，海蓝深见鲸

B站视频图解笔记长图 Skill 的实现流程

13分钟阅读

关联主题:: Claude Skills说明(2026.02.03)
同级:: CFlow-Brain——用Codex开发cflow智能助手Skill
下一级::

B站视频图解笔记长图 Skill 的实现流程

这篇文章沉淀的是 $bilibili-video-note 这个 Skill 的实现思路。它的目标不是简单“总结一个视频”，而是把一个 B 站视频变成一份可以离线打开、可以分享成长图、每章都有内容图解的知识笔记。

它的核心产物是：

index.html    离线单页 HTML
page.png      整页长图
slices/       长图切片
transcript/   转写稿
audit/        审计记录
media/        元数据、音频、封面等素材

为什么放在这里

这篇文章适合放在：

Obsidian blog/content/1 Article/AI/Claude Code/Claude Code Skills/

原因是它记录的是一个 Claude Code / Codex Skill 的实现流程，和同目录里的 Skill-creator、CFlow-Brain、Planning with Files 等文章属于同一类：都是围绕 Skills 的设计、封装和复用。单个视频长图产物放在 90 Resources/video-notes/ 更合适；但这个流程说明应该进入 Claude Code Skills 主题下，方便后续和其他 Skills 文档互相引用。

总体流程

用户给 B 站链接
      |
      v
创建输出目录
      |
      v
yt-dlp 抓元数据
标题 / UP / 时长 / 标签 / 封面 / 视频 ID
      |
      v
下载音频
      |
      v
检查是否有字幕
      |
      +-------------------+
      |                   |
      v                   v
有 B 站字幕          没有字幕
用字幕转 transcript   用 Whisper / faster-whisper 转写
      |                   |
      +---------+---------+
                |
                v
ffprobe + media_audit 校验时长
音频时长 / 元数据时长 / 转写结尾时间
                |
                v
按内容自然拆章
                |
                v
判断视频类型
                |
      +--------------------------+
      |                          |
      v                          v
口播 / 观点 / 历史类        UI / 控制台 / 文档 / 操作演示类
不抽视频截图               抽关键真实帧
      |                          |
      +------------+-------------+
                   |
                   v
每章写正文 + 生成内容 SVG 图解
                   |
                   v
生成离线 index.html
内联 CSS / SVG，底部来源 + 二维码
                   |
                   v
Chrome / Playwright 截整页 PNG
                   |
                   v
检查渲染、图片、SVG、空白、重叠
                   |
                   v
ffmpeg crop 切成长图分片
                   |
                   v
输出 HTML / page.png / slices / audit

第一步：创建输出目录

每个视频独立建一个目录，用 BV 号命名，避免素材混在一起。

示例：

90 Resources/video-notes/BV1jBTv6mEkY/

目录结构：

BVxxxx/
├── index.html
├── page.png
├── slices/
├── frames/
├── media/
├── transcript/
└── audit/

其中 frames/ 不是每次都用。只有界面演示、控制台、文档、剪辑器、软件操作类视频，才需要抽真实帧。

第二步：用 yt-dlp 抓元数据

先抓视频元数据，再开始写笔记。

需要保留的信息包括：

标题
UP 主
BV 号
视频链接
发布时间
时长
播放量
点赞数
标签
简介
封面
字幕列表

这些信息有三个作用：

  1. 放到长图顶部信息卡。
  2. 放到底部来源区。
  3. 用于后面做时长校验，确认音频没有下载缺段。

常用命令：

yt-dlp --cookies-from-browser edge \
  --write-info-json \
  --write-thumbnail \
  --skip-download \
  -o "media/source.%(ext)s" \
  "$VIDEO_URL"

实际使用中，B 站经常需要浏览器 cookies。之前 Chrome profile 读不到 cookie 时，Edge 成功读取了登录态。

第三步：下载音频

音频是转写的基础。

常用命令：

yt-dlp --cookies-from-browser edge \
  -f "ba/bestaudio/best" \
  -x --audio-format mp3 \
  --audio-quality 0 \
  -o "media/audio.%(ext)s" \
  "$VIDEO_URL"

下载完成后会得到：

media/audio.mp3

如果后面需要真实视频帧，还会额外下载视频文件。但对于口播、历史、观点类内容，不需要下载视频截图。

第四步：获取转写稿

这里分两种情况。

检查字幕列表
      |
      +-- 有 B 站 AI 字幕：直接下载字幕，转 transcript
      |
      +-- 没有字幕：用 Whisper / faster-whisper 转写音频

有字幕时

如果 B 站提供 ai-zh 字幕，就优先使用。好处是快，而且天然带时间戳。

输出：

transcript/transcript.json
transcript/transcript.zh.md

没字幕时

如果只有弹幕 XML，没有字幕，就用本地转写。

实践中用过：

faster-whisper
model: small
language: zh
device: cpu
compute_type: int8

用 uv 临时环境运行，避免污染系统 Python。

第五步：时长审计

Skill 中有一个脚本：

/Users/bairimengyushi/.codex/skills/bilibili-video-note/scripts/media_audit.py

它会比较三类时长：

元数据 duration
ffprobe 读出的音频真实时长
transcript 最后一段 end 时间

判断规则：

差异 <= 5%：通过
差异 > 5%：重下、重转写，或在页面中标注异常

这个审计很重要。否则可能出现音频只下载了一半、转写漏了后半段，但页面看起来仍然完整的情况。

第六步：按自然结构拆章

拆章不是按固定时间平均切，而是按内容转折切。

判断依据：

主题切换
时间线变化
概念引入
问题提出
解决方案出现
结论收束
演示步骤变化

例如《毛泽东最迷茫的5年都在做什么》可以拆成：

开场：最绝望时写出最亮比喻
秋收失败后上井冈山
不是执行问题，是方向问题
井冈山三件事
从实践写出方法论
被架空后的沉淀
遵义会议转折
今天怎么用

拆章的关键是让读者看到“思想结构”，而不是只看到“视频时间轴”。

第七步：判断是否需要视频截图

这是这个 Skill 后来迭代过的关键规则。

口播 / 历史 / 观点 / 心理 / 概念类：
  不加视频截图
  做成文章长图 + SVG 图解
 
界面 / 控制台 / 剪辑器 / 文档 / 软件演示类：
  每章加一张真实视频帧
  截图用于证明屏幕状态和操作步骤

一开始曾经误把口播类视频也加了关键帧，结果和参考图风格不一致。后来修正为：真实帧只在“屏幕内容本身是证据”时使用。

第八步：每章生成 SVG 图解

每章图解必须来自本章真实内容，不能做装饰图。

图解选择规则：

流程内容       -> 步骤路径图
概念关系       -> 层级图 / 关系图
历史变化       -> 时间线
对比判断       -> 矩阵
误区风险       -> 检查表 / 决策树
因果推理       -> 链路图
系统构成       -> 闭环 / 中心辐射图

例子：

“秋收失败 -> 上井冈山 -> 根据地”
  做成路径图
 
“城市中心论 vs 中国现实”
  做成对比矩阵
 
“土地革命 / 军队建设 / 游击战术”
  做成系统图
 
“迷茫时做三件事”
  做成三步行动图

图解要求：

至少包含 3 个本章关键词
要有箭头、分组、层级、轴线或关系
图注以“图解：”开头
不能重复套壳

第九步：生成离线 HTML

最终先生成 index.html，再截图成长图。

HTML 要求：

CSS 内联
SVG 内联
截图或二维码使用相对路径
页面可离线打开
底部有来源
右下角有二维码

页面结构一般是：

顶部标题和数据卡
导语
总览图
章节 01
章节 02
章节 03
...
最后一句 / 行动提醒
来源 footer + 二维码

底部来源区示例：

来源 · UP《视频标题》（25 分 35 秒）
▶ 看原视频 · bilibili BVxxxx
右下角二维码

二维码用 qrcode 生成 SVG：

audit/video-qr.svg

第十步：渲染成长图

用系统 Chrome 或 Playwright 打开本地 HTML，然后截整页：

index.html -> page.png

渲染检查包括：

图片是否破损
二维码是否加载
SVG 数量是否正确
SVG 是否有尺寸
页面是否空白
文字是否明显重叠
版面是否过长或过散

实践中会用系统 Chrome 的可执行文件，因为 Playwright 包有时存在但浏览器二进制没装。

第十一步：切成长图分片

Skill 中有一个脚本：

/Users/bairimengyushi/.codex/skills/bilibili-video-note/scripts/slice_tall_image.py

它会把整页长图切成多张：

slices/BVxxxx-note-01.png
slices/BVxxxx-note-02.png
slices/BVxxxx-note-03.png
...

默认策略：

每片高度：1800px
重叠区域：100px

保留重叠是为了避免标题、图注或段落刚好被切断。

第十二步：写审计记录

最后写入：

audit/media-audit.json
audit/render-notes.md

审计记录包含：

视频来源
标题 / UP / 时长
字幕来源或转写模型
音频和转写是否通过校验
是否使用视频截图
SVG 数量
二维码路径
长图尺寸
切片数量

这一步的价值是可追溯。后面如果发现笔记质量有问题，可以快速知道问题出在下载、转写、拆章、渲染还是切片。

三个关键脚本

media_audit.py

用途：

校验元数据时长、音频时长、转写结尾时间是否一致。

位置：

/Users/bairimengyushi/.codex/skills/bilibili-video-note/scripts/media_audit.py

extract_frame.py

用途：

从视频中按时间戳抽取高清真实帧。

只用于界面演示类视频。

位置：

/Users/bairimengyushi/.codex/skills/bilibili-video-note/scripts/extract_frame.py

slice_tall_image.py

用途：

把整页长图切成带重叠的多张 PNG。

位置：

/Users/bairimengyushi/.codex/skills/bilibili-video-note/scripts/slice_tall_image.py

两个已经生成过的案例

亲密关系视频

路径：

90 Resources/video-notes/BV1gMJF6iEYE/

特点：

B 站 AI 字幕可用
口播心理类视频
不使用视频关键帧
生成 6 张长图切片

毛选思维视频

路径：

90 Resources/video-notes/BV1jBTv6mEkY/

特点：

无 B 站 AI 字幕
用 faster-whisper 转写
历史 / 方法论讲述类视频
不使用视频关键帧
生成 8 张长图切片

这个 Skill 的本质

它不是一个“一键总结视频”的模板，而是一条内容生产流水线：

抓取可信来源
校验素材完整
获得带时间戳转写
按内容结构拆章
用真实内容生成图解
做成可离线长图
渲染检查
切片交付

如果只做摘要，读者得到的是“视频讲了什么”。这个 Skill 追求的是让读者看到：

这个视频的结构是什么
每章解决什么问题
关键判断从哪里来
哪些关系可以被画出来
原视频在哪里可以回跳

所以它更像一个“视频知识长图生产规范 + 小工具包”。

后续可继续优化

  • 增加自动章节候选算法：根据 transcript topic shift 给出初始章节。
  • 增加 SVG 质量检查：避免图解过于相似或关键词过少。
  • 增加封面风格模板：让同一系列视频保持视觉一致。
  • 增加产物索引页：集中展示所有 90 Resources/video-notes/ 下的长图笔记。
  • 增加 CFlow 回链：每生成一份重要长图，就自动写一条摘要 memo，指回 Obsidian 文章或产物路径。

关系图谱

1