asdhabdua/bilibili-video-notes-skill
GitHub: asdhabdua/bilibili-video-notes-skill
一款自动从 B 站教育视频中提取关键帧和字幕，并利用 AI 视觉分析生成结构化 DOCX 学习笔记的工具。
Stars: 8 | Forks: 0
# Bilibili 视频笔记 📝
## 目录
- [一键安装（复制粘贴给 AI）](#-%E4%B8%80%E9%94%AE%E5%AE%89%E8%A3%85%E5%A4%8D%E5%88%B6%E7%B2%98%E8%B4%B4%E7%BB%99-ai)
- [功能特点](#-%E5%8A%9F%E8%83%BD%E7%89%B9%E7%82%B9)
- [快速开始](#-%E5%BF%AB%E9%80%9F%E5%BC%80%E5%A7%8B)
- [详细使用教程(包括如何让AI代劳配置)](#-%E8%AF%A6%E7%BB%86%E4%BD%BF%E7%94%A8%E6%95%99%E7%A8%8B)
- [配置好之后如何使用](#-%E9%85%8D%E7%BD%AE%E5%A5%BD%E4%B9%8B%E5%90%8E%E5%A6%82%E4%BD%95%E4%BD%BF%E7%94%A8)
- [完整工作流](#-%E5%AE%8C%E6%95%B4%E5%B7%A5%E4%BD%9C%E6%B5%81)
- [命令参考](#-%E5%91%BD%E4%BB%A4%E5%8F%82%E8%80%83)
- [常见问题](#-%E5%B8%B8%E8%A7%81%E9%97%AE%E9%A2%98)
- [Agent 使用](#-agent-%E4%BD%BF%E7%94%A8)
- [目录结构](#-%E7%9B%AE%E5%BD%95%E7%BB%93%E6%9E%84)
- [License / 反馈](#-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
## 📊 效果对比
| 输入 | 输出 |
|------|------|
| 21分钟B站视频 | 7-12张精选截图 + 完整知识点DOCX |
| 129帧原始截图 | 20-40帧去重后 → 7-12帧AI精选 |
| AI 字幕文本 | 融合进结构化笔记，不照搬 |
## 🚀 快速开始
### 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`。
## 🚀 详细使用教程
### 第一步：准备环境
#### 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](https://www.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值
```
### 告诉 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 两步？
| 步骤 | 看的帧数 | AI 输出内容 | 目的 | token 成本 |
|------|----------|------------|------|-----------|
| score | 20-40 | theme/keywords/score/complete | 选帧 | 低 |
| extract | 7-12 | 图中完整文字/公式/表格/概念 | 写正文 | 高 |
分开可以最小化总 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/标签：Bilibili, OCR, Python, 多模态AI, 无后门, 自动化笔记, 视频处理, 逆向工具