Bilibili Video Notes 📝

B站视频笔记生成工具 — 从B站教育/讲课视频自动生成带截图的DOCX学习笔记，如果觉得有用的话欢迎点一下星标哟🤗

全流程：下载视频+字幕 → 全覆盖抽帧 → OCR去重 → AI视觉打分精选 → 提取图中内容 → 融合生成DOCX

目录

• 一键安装（复制粘贴给 AI）
• 功能特点
• 快速开始
• 详细使用教程(包括如何让AI代劳配置)
• 配置好之后如何使用
• 完整工作流
• 命令参考
• 常见问题
• Agent 使用
• 目录结构
• License / 反馈

---

⚡ 一键安装（复制粘贴给 AI）

请帮我安装 bilibili-video-notes-skill：

git clone https://github.com/asdhabdua/bilibili-video-notes-skill.git
cd bilibili-video-notes-skill
pip install -r scripts/requirements.txt

安装完成后，配置 .env 和 bilibili_cookies.txt，然后读取 README.md 了解如何使用。

---

✨ 功能特点

• 🎬 自动下载 B站视频和 AI 字幕
• 📸 全覆盖抽帧（每10秒一帧），不丢任何画面
• 🔍 OCR + 感知哈希双重去重，129帧 → 20-40帧，不丢有价值内容
• 🧠 AI视觉打分，选出每个知识点最完整的一帧
• 📝 融合字幕+截图内容生成结构化DOCX笔记
• 🧹 自动清理临时文件，不占多余空间
• 🤖 多 Agent 支持：Hermes / Claude Code / Codex CLI

📊 效果对比

---

🚀 快速开始

1. 克隆安装

git clone https://github.com/asdhabdua/bilibili-video-notes-skill.git
cd bilibili-video-notes-skill
pip install -r scripts/requirements.txt

2. 安装 FFmpeg

系统环境变量中需要可直接调用 ffmpeg。

3. 配置 API

cp templates/env.example .env

编辑 .env：

VISION_API_KEY=your_api_key_here
VISION_BASE_URL=https://api.openai.com/v1
VISION_MODEL=gpt-4o

支持任何 OpenAI 兼容格式的多模态 API（OpenAI、Sophnet、本地 vLLM 等）。

4. 配置 B 站 Cookie（可以直接告诉AI让他代劳）

cp bilibili_cookies.txt.example bilibili_cookies.txt

从浏览器 F12 复制 SESSDATA 字段，替换文件中的 YOUR_SESSDATA_HERE。

⚠️ Cookie 有时效（通常几天），过期后需重新获取。

---

🚀 详细使用教程

第一步：准备环境

1.1 克隆仓库

git clone https://github.com/asdhabdua/bilibili-video-notes-skill.git
cd bilibili-video-notes-skill

1.2 安装 Python 依赖

pip install -r scripts/requirements.txt

如果使用 Anaconda：

conda create -n bili-notes python=3.11
conda activate bili-notes
pip install -r scripts/requirements.txt

1.3 安装 FFmpeg

本工具需要 ffmpeg 处理视频。

Windows 安装方法：

1. 下载：https://www.gyan.dev/ffmpeg/builds/ffmpeg-release-essentials.zip
2. 解压到 C:\\ffmpeg
3. 把 C:\\ffmpeg\\bin 加到系统环境变量 PATH
4. 重新打开终端，验证：ffmpeg -version

macOS：

brew install ffmpeg

Ubuntu/Debian：

sudo apt-get update
sudo apt-get install ffmpeg

---

第二步：配置 API

复制示例文件：

cp templates/env.example .env

编辑 .env：

VISION_API_KEY=your_api_key_here
VISION_BASE_URL=https://api.openai.com/v1
VISION_MODEL=gpt-4o

常用 API 配置示例

OpenAI：

VISION_API_KEY=sk-...
VISION_BASE_URL=https://api.openai.com/v1
VISION_MODEL=gpt-4o

Sophnet：

VISION_API_KEY=...
VISION_BASE_URL=https://www.sophnet.com/api/open-apis/v1
VISION_MODEL=qwen3-vl-plus

本地 vLLM：

VISION_API_KEY=not-needed
VISION_BASE_URL=http://localhost:8000/v1
VISION_MODEL=your-local-model

---

第三步：配置 B 站 Cookie

B 站 AI 字幕需要登录态才能下载。

复制示例文件：

cp bilibili_cookies.txt.example bilibili_cookies.txt

获取 SESSDATA 的方法：

1. 用 Edge/Chrome 打开 bilibili.com （确保已登录）
2. 按 F12 打开开发者工具
3. 点击 Application（应用程序）标签
4. 左侧 Cookies → https://www.bilibili.com
5. 找到 SESSDATA，复制它的值
6. 替换 bilibili_cookies.txt 里的 YOUR_SESSDATA_HERE

文件格式如下：

.bilibili.com  TRUE  /  FALSE  0  SESSDATA  你的SESSDATA值

⚠️ Cookie 通常有效期几天，过期后字幕下载会失败，需要重新获取。

---

告诉 AI 让它代劳配置

你不需要自己动手配置。把下面的提示词复制粘贴给 AI，它会帮你完成安装、配置，你只需要告诉他你的api、baseurl、模型名和SESSDATA(如何获得SESSDATA可见上一步)。

Hermes Agent 版

首先，帮我完成初始化配置：
1. 克隆本仓库到当前工作目录：git clone https://github.com/asdhabdua/bilibili-video-notes-skill.git
2. 进入项目目录并安装依赖：pip install -r scripts/requirements.txt
3. 确保系统可以调用 ffmpeg（如果没有，请帮我安装并加入 PATH）
4. 从 templates/env.example 复制出 .env，然后问我 API 配置（VISION_API_KEY、VISION_BASE_URL、VISION_MODEL），填入后给我确认
5. 从 bilibili_cookies.txt.example 复制出 bilibili_cookies.txt，然后问我要 B 站 SESSDATA，填入后给我确认

初始化完成后，等待用户下一步指令，工作时按 SKILL.md 执行笔记生成流程。

注意事项：
- 帧目录必须是纯英文路径
- 不要使用 vision_analyze 串行调用
- 笔记要融会贯通字幕和截图，宁可多写不可遗漏

Claude Code 版

首先做初始化配置：
1. git clone https://github.com/asdhabdua/bilibili-video-notes-skill.git
2. cd bilibili-video-notes-skill
3. pip install -r scripts/requirements.txt
4. 检查 ffmpeg 是否存在，不存在则帮我安装
5. cp templates/env.example .env，然后问我要 VISION_API_KEY / VISION_BASE_URL / VISION_MODEL，填入后让我确认
6. cp bilibili_cookies.txt.example bilibili_cookies.txt，然后问我要 B 站 SESSDATA，填入后让我确认

初始化完成后，等待用户下一步指令，工作时按 CLAUDE.md 执行笔记生成流程。

Codex CLI 版

首先完成初始化配置：
1. git clone https://github.com/asdhabdua/bilibili-video-notes-skill.git
2. cd bilibili-video-notes-skill
3. pip install -r scripts/requirements.txt
4. 确保 ffmpeg 可用
5. cp templates/env.example .env，然后问我要 VISION_API_KEY / VISION_BASE_URL / VISION_MODEL，填入后让我确认
6. cp bilibili_cookies.txt.example bilibili_cookies.txt，然后问我要 B 站 SESSDATA，填入后让我确认

初始化完成后，等待用户下一步指令，工作时按 AGENTS.md 执行笔记生成流程。

其实不是这三个Agent可也使用这套提示词，只需要把后面的“工作时按 xxx.md 执行笔记生成流程”删去即可

---

📖 配置好之后如何使用

当你已经完成以下配置：

• Python 依赖已安装
• .env 中已填入有效的 VISION_API_KEY / BASE_URL / MODEL
• bilibili_cookies.txt 中已填入有效的 SESSDATA
• ffmpeg 可在终端直接调用

只需要告诉 AI一句话，它就会跟踪完整流程：

Hermes Agent 版

请帮我做这个视频的笔记：https://www.bilibili.com/video/BV1xx411c7mD

按照 SKILL.md 流程执行，不要凭印象。

Claude Code 版

请帮我做这个视频的笔记：https://www.bilibili.com/video/BV1xx411c7mD

已配置好 .env 和 bilibili_cookies.txt，按照 CLAUDE.md 执行。

Codex CLI 版

请帮我做这个视频的笔记：https://www.bilibili.com/video/BV1xx411c7mD

已配置好 .env 和 bilibili_cookies.txt，按照 AGENTS.md 执行。

不是这三个Agent可也使用这套提示词，让他按照 SKILL.md 流程执行，不要凭印象即可

笔记生成流程

AI 会自动执行以下步骤：

1. 抽帧：extract_frames.py 下载视频、字幕、每10秒全覆盖抽帧
2. 去重：smart_select.py 用 OCR + 哈希去重，129帧 → 20-40帧
3. 打分：score_frames_concurrent.py --mode score 并发给所有帧打分
4. 选帧：AI 根据 score/theme 选出最终 7-12 帧
5. 提取：score_frames_concurrent.py --mode extract 并发提取图中文字/公式/表格/概念/因果链
6. 提取字幕关键因果句：extract_key_sentences.py 提取字幕中必须保留的 WHY 解释句
7. 生成 DOCX：基于字幕 + 图中内容生成笔记，确保因果句被覆盖
8. 验证：verify_docx.py --subtitle 检查 DOCX 格式和字幕因果句覆盖率
9. 清理：删除视频MP4、JSON字幕、临时脚本

查收结果

AI 执行完毕后，你应该在 workspace/ 目录下看到：

workspace/
├── _p_subtitles.txt      # 字幕文本（保留）
├── vision_scores_pXX.json       # 帧打分结果（保留）
├── vision_extract_pXX.json      # 图中内容提取结果（保留）
└── X.X_章节标题_v1.docx     # 最终笔记

如果一切正常，直接打开 DOCX 查看即可。

---

手动微调（如需要）

AI 生成的 DOCX 可能需要你微调：

• 某些帧可能选得不太好，可以替换
• 正文部分可能需要根据你的理解补充
• 排版风格可以在 docx_note_v2.py 中调整

---

📖 完整工作流

129 帧（每10秒全覆盖）
  ↓ OCR 预筛：去掉空白/面部帧
  ↓ 哈希去重（视觉结构相似归为一组）→ 20-40 帧
  ↓ AI 视觉打分（1-10 分）
  ↓ 人工选出最终 7-12 帧
  ↓ AI 提取图中文字/公式/表格/概念
  ↓ 融合字幕 + 图中内容生成 DOCX
  ↓ 验证 + 清理临时文件

为什么要分 score 和 extract 两步？

分开可以最小化总 token 和 API 成本，同时避免用任何平台的 vision_analyze 串行调用。

---

🔧 命令参考

1. 抽帧

python scripts/extract_frames.py BV1xx411c7mD \
  --page 1 \
  --mode cover \
  --subtitle \
  --workspace ./workspace \
  --frames ./frames/pXX

2. 去重

python scripts/smart_select.py ./frames/pXX/fixed \
  --output-dir ./frames/pXX/selected \
  --skip-clustering

3. 并发打分

python scripts/score_frames_concurrent.py \
  --frames ./frames/pXX/selected \
  --output ./workspace/vision_scores_pXX.json \
  --workers 16

4. 人工选最终帧

根据 vision_scores_pXX.json 的 score 和 theme，人工(其实就是你的模型)决定最终使用哪几帧。

mkdir -p ./frames/pXX/final
cp ./frames/pXX/selected/frame_0003.jpg ./frames/pXX/final/
cp ./frames/pXX/selected/frame_0007.jpg ./frames/pXX/final/
# ...

5. 提取图中内容

python scripts/score_frames_concurrent.py \
  --frames ./frames/pXX/final \
  --output ./workspace/vision_extract_pXX.json \
  --mode extract \
  --workers 16

6. 生成 DOCX

cp templates/docx_note_v2.py ./workspace/gen_pXX_v1.py
# 编辑 gen_pXX_v1.py 填入 TITLE/SOURCE/FRAMES/SECTIONS
python ./workspace/gen_pXX_v1.py

7. 验证

python scripts/verify_docx.py ./workspace/.docx --subtitle ./workspace/_p_subtitles.txt

8. 清理

rm -f ./workspace/BV1xx411c7mD_p1.mp4
rm -f ./workspace/BV1xx411c7mD_p1_subtitles.json
rm -f ./workspace/gen_pXX_v1.py

保留：字幕.txt、笔记.docx、vision_scores_pXX.json、vision_extract_pXX.json、checklist_pXX.json

---

⚙️ 配置参数

---

🛠️ 常见问题

B 站限流（HTTP 412）

# 降级到 480p + 加 User-Agent
yt-dlp --user-agent "Mozilla/5.0 ..." -f "bestvideo[height<=480]+bestaudio/best[height<=480]" ...

Cookie 过期

字幕下载失败但视频下载成功 → 先跳过字幕，后面补：

python scripts/extract_frames.py BV号 --page N --subtitle --no-download --mode fixed --interval 9999

帧目录必须是纯英文路径

AI 视觉工具可能无法识别中文路径。

帧太多 / API 调用太贵

129帧 → 用 smart_select.py --skip-clustering 压到 20-40帧，再送 AI 打分，省 60%-80% API 调用。

Vision 选到了半成品截图

打分时使用的 prompt 已内置强调：“Among visually similar frames, pick ONLY the MOST COMPLETE version”。

---

🤖 Agent 使用

Hermes Agent

直接读取 SKILL.md，按里面的流程执行。

Claude Code

CLAUDE.md 会被自动加载为项目指令。

Codex CLI

AGENTS.md 会被自动加载为项目指令。

---

📁 目录结构

bilibili-video-notes/
├── README.md
├── SKILL.md                    # Hermes Agent
├── CLAUDE.md                   # Claude Code
├── AGENTS.md                   # Codex CLI
├── CONTRIBUTING.md             # 贡献指南
├── .gitignore
├── bilibili_cookies.txt.example
├── scripts/
│   ├── extract_frames.py
│   ├── smart_select.py
│   ├── score_frames_concurrent.py
│   ├── extract_key_sentences.py
│   ├── verify_docx.py
│   ├── verify_checklist.py
│   ├── clean_markdown_bold.py
│   └── requirements.txt
├── templates/
│   ├── docx_note_v2.py
│   ├── env.example
│   └── checklist.json

---

📄 License

MIT License - 自由使用和修改。

🙏 致谢

• yt-dlp - 视频下载
• RapidOCR - OCR 文字识别
• ImageHash - 感知哈希
• python-docx - DOCX 生成

📬 反馈与建议

• 提建议/报Bug：GitHub Issues
• 功能请求：GitHub Discussions
• 邮箱：[email protected]

欢迎提交 Issue 和 PR！如果觉得有用的话欢迎点一下星标哟🤗