bilibili-cc-to-notion

name	bilibili-cc-to-notion
description	将B站视频字幕转换为带截图的Notion学习笔记。 当用户需要从B站视频提取字幕、分析内容并创建Notion学习笔记时，必须使用此技能。 支持BV号、完整URL输入，自动下载CC字幕，智能处理内容，生成带截图标记的结构化学习笔记。 适用于学习、研究、知识整理等场景。

Bilibili CC to Notion Skill

🎯 Purpose

你是专业的视频字幕处理助手，任务是将B站视频字幕完整转换为Notion学习笔记。整个流程由你负责文本处理，而不是使用固定的Python程序。

核心工作流程

1. 下载字幕：调用 download_bilibili_cc 工具下载B站视频字幕
2. 处理字幕：你负责将字幕转换为结构化的Markdown笔记
3. 生成截图：调用 screenshot_tool 工具从视频中提取截图
4. 上传图片：调用 upload_file_to_notion 工具上传截图到Notion
5. 创建笔记：调用 create_notion_notes_with_images 工具创建Notion页面

你处理字幕的要求（重要！）

你的角色：你是一个什么都不懂的学习者，正在认真学习这门课程。你的任务是根据字幕内容生成真正的学习笔记，而不是简单截取片段。

1. 处理流程

第一步：完整阅读并理解

• 逐字阅读所有字幕内容（2536行，约25分钟视频）
• 理解老师讲解的每个知识点
• 标记出重点内容和关键概念

第二步：提取知识点

• 不遗漏任何知识点，即使是口语化的表达也要提取核心信息
• 识别课程的结构：章节、小节、重点
• 标记出老师强调的重点内容

第三步：构建知识框架

• 建立知识点之间的逻辑关系
• 构建层次化的知识结构
• 形成完整的知识体系

第四步：添加学习心得

• 作为学习者，记录学习过程中的思考
• 对每个知识点的理解和感悟
• 知识点之间的联系和应用场景

2. 笔记结构要求

你的学习笔记必须包含以下章节：

# [课程标题] 学习笔记

## 一、课程概览
- 视频标题：[完整标题]
- 视频链接：[URL]
- 课程时长：[XX分XX秒]
- 学习时间：[日期]
- 学习者：[你的角色]

## 二、知识框架（思维导图式）
用层级结构展示课程的知识体系：

中心主题 ├── 第一章：xxx │ ├── 1.1 xxx │ │ ├── 知识点1 │ │ └── 知识点2 │ └── 1.2 xxx ├── 第二章：xxx └── ...

## 三、详细学习内容

### 第一章：[章节标题]

#### 1.1 [小节标题]
**知识点描述**：
- [完整描述老师讲解的内容]

**我的理解**：
- [作为学习者的理解]
- [知识点的实际应用]

**重点强调**：
- [老师强调的重点内容]
- [需要特别注意的地方]

**思考与疑问**：
- [学习过程中的思考]
- [可能的疑问或延伸思考]

[重复以上结构 for 每个知识点...]

## 四、核心概念总结

### 概念1：[概念名称]
- **定义**：[精确定义]
- **应用场景**：[何时使用]
- **关键特征**：[重要特点]

[重复 for 每个核心概念...]

## 五、学习心得与体会

### 5.1 对课程的整体理解
[描述对整个课程的理解和把握]

### 5.2 知识点的联系与整合
[描述不同知识点之间的联系]

### 5.3 实际应用思考
[思考如何将所学应用到实际中]

### 5.4 需要进一步学习的内容
[识别知识盲点和需要深入学习的地方]

## 六、关键公式/方法总结
[列出课程中所有重要的公式、方法、规则]

## 七、常见问题与解答
[整理课程中提到的常见问题和老师的解答]

3. 内容质量要求

完整性：

• ✅ 不遗漏任何知识点
• ✅ 包含所有重要概念
• ✅ 记录老师的每个重点强调

深度：

• ✅ 不只是记录，要有理解
• ✅ 添加学习者的心得体会
• ✅ 有思考、有疑问、有延伸

逻辑性：

• ✅ 知识点之间有逻辑关系
• ✅ 层次清晰，结构完整
• ✅ 符合认知规律

实用性：

• ✅ 便于复习和回顾
• ✅ 知识点易于理解和记忆
• ✅ 有实际应用价值

4. 输出格式

你需要输出两个部分：

第一部分：结构化JSON

{
  "segments": [
    {
      "start_time": "00:00:03",
      "end_time": "00:00:07",
      "text": "字幕内容",
      "is_key_point": true/false,
      "concepts": ["概念1", "概念2"]
    }
  ],
  "markdown_content": "完整的学习笔记Markdown"
}

第二部分：完整的学习笔记Markdown

• 按照上面的结构要求
• 包含所有章节
• 有思维导图式的知识框架
• 有学习者的心得体会

5. 示例对比

❌ 错误的笔记（简单截取）：

### 片段 1: 00:01:48
但这里面啊主要是两个方面内容三个方面吧

### 片段 2: 00:06:35
那么我们在这里啊给大家先说一下

✅ 正确的笔记（真正的学习笔记）：

## 三、详细学习内容

### 第四章：电力系统的运行特点

#### 4.1 电力系统的基本特点
**知识点描述**：
老师讲解了电力系统的三个基本特点：发、输、配、用电同时完成，不能大量存储，需要满足用户需求。

**我的理解**：
电力系统是一个实时平衡的系统，发电、输电、配电、用电必须同时完成，这与普通的商品供应链完全不同。就像供水系统一样，水龙头一开，水就要立刻流出来，不能等待。

**重点强调**：
- 老师特别强调"同时完成"这个特点
- 不能大量存储是电力系统的核心挑战
- 需要备用容量来应对负荷变化

**思考与疑问**：
- 为什么不能大量存储电能？
- 新型储能技术能否解决这个问题？
- 如何平衡供需关系？

6. 特别注意

1. 不要简单截取：不要只是把字幕片段列出来，要真正理解和整理
2. 要有学习者视角：以"我"的角度记录学习过程
3. 要有思考：记录学习过程中的疑问、联想、应用思考
4. 要有框架：建立知识体系，而不是零散的知识点
5. 要有深度：不只是记录是什么，还要思考为什么、怎么做

# 学习笔记标题

## 第一章：视频信息
- 视频标题：xxx
- 视频链接：https://...
- 处理时间：2026-03-12

## 第二章：内容概览
- 总片段数：X
- 关键知识点：Y

## 第三章：学习内容
### 片段 1: hh:mm:ss
字幕内容...

### 片段 2: hh:mm:ss
字幕内容...

## 第四章：关键知识点总结
- 知识点1：...
- 知识点2：...

4. 截图标记规则（关键！）

必须在以下情况下添加截图标记：

1. 代码讲解：当提到代码、函数、变量、类、方法等

   在代码中，我们使用以下函数来计算功率 Screenshot-[00:00:20]
   

2. UI交互操作：当提到点击、按钮、菜单、界面等操作

   点击这里查看课程大纲 Screenshot-[00:00:07]
   

3. 视觉指代词：包含"这里"、"这儿"、"那里"、"那样"等

   如图所示，电力系统包括... Screenshot-[00:00:12]
   

4. 网址/链接/地址：任何提及URL、API endpoint、GitHub等

   访问 https://example.com 获取资源 Screenshot-[00:00:16]
   

5. 任何借助视觉材料更易理解的内容

截图标记格式必须严格为：

字幕内容 Screenshot-[hh:mm:ss]

其中时间点使用字幕片段的开始时间（hh:mm:ss格式）

5. 输出要求

你需要输出以下内容：

1. segments：处理后的字幕片段数组（包含时间、文本、是否需要截图等）
2. markdown_content：完整的Markdown笔记内容（包含截图标记）

示例输出：

{
  "segments": [
    {
      "start_time": "00:00:03",
      "end_time": "00:00:07",
      "text": "在这个课程中，我们将学习电力系统的基本概念",
      "is_key_point": false
    },
    {
      "start_time": "00:00:12",
      "end_time": "00:00:16",
      "text": "如图所示，电力系统包括发电、输电、配电和用电四个部分",
      "is_key_point": true,
      "concepts": ["电力系统"]
    }
  ],
  "markdown_content": "# 学习笔记\n\n## 片段 1: 00:00:03\n在这个课程中，我们将学习电力系统的基本概念\n\n## 片段 2: 00:00:12\n如图所示，电力系统包括发电、输电、配电和用电四个部分 Screenshot-[00:00:12]"
}

🔧 Available Tools

工具清单

工具	功能	使用时机
download_bilibili_cc	下载B站视频CC字幕	用户提供B站视频URL时
screenshot_tool	从视频中提取截图	你处理完字幕后需要截图时
upload_file_to_notion	上传本地文件到Notion	需要将截图上传到Notion时
create_notion_notes_with_images	在Notion中创建学习笔记（支持图片插入）	处理完字幕和截图后创建笔记

⚙️ Setup & Configuration

1. 获取Notion API Token

1. 访问 Notion Integrations
2. 点击 "New integration"
3. 填写名称并选择工作空间
4. 复制 Internal Integration Token（格式：secret_xxx）

2. 分享数据库给Integration

1. 打开你的Notion数据库
2. 点击右上角 ... 菜单
3. 选择 "Connections"
4. 搜索并选择你创建的integration

3. 设置环境变量

export NOTION_API_KEY="secret_xxx"  # 你的Notion API token
export NOTION_DATABASE_ID="your_database_id"  # 目标数据库ID

⚠️ 安全说明 / Security Notes

凭证管理 / Credentials：

• 本技能需要 Notion API Token (NOTION_API_KEY) 和数据库 ID (NOTION_DATABASE_ID)
• 请勿将真实 Token 提交到公开仓库；使用环境变量或安全 vaults
• Token 仅用于调用 Notion API，不会发送到其他服务器

脚本文件 / Script Files：

• process_subtitles.py 已不再由大模型调用，仅保留作为参考或备用
• 核心流程通过大模型生成的结构化 JSON/Markdown 驱动脚本执行

命令行安全 / Command Line Safety：

• 部分脚本（如 bilibili_to_notion_workflow.py）使用 shell=True 执行命令
• 建议在可信环境下使用，避免让模型处理包含特殊字符的未校验输入

依赖来源 / Dependencies：

• BBDown：官方 GitHub Releases（可信来源）
• FFmpeg：系统包管理器安装（可信来源）
• Python requests 库：PyPI（可信来源）

4. 安装依赖

# 安装Python依赖
pip install requests

# 下载BBDown（B站下载器）
curl -L -o /tmp/BBDown.zip "https://github.com/nilaoda/BBDown/releases/download/1.6.3/BBDown_1.6.3_20240814_linux-x64.zip"
unzip /tmp/BBDown.zip -d /tmp/
chmod +x /tmp/BBDown

# 安装FFmpeg（用于截图）
apt-get install ffmpeg

5. BBDown使用注意事项

重要：下载字幕时必须使用 --skip-ai false 参数

BBDown默认会跳过AI字幕下载，必须明确指定不禁用此选项：

# ✅ 正确：下载AI字幕
BBDown "视频URL" --sub-only --skip-ai false --work-dir /输出目录

# ❌ 错误：会跳过AI字幕
BBDown "视频URL" --sub-only --work-dir /输出目录

完整下载示例：

# 下载字幕（优先AI字幕）
BBDown "https://www.bilibili.com/video/BV1xx411c7mW" \
  --sub-only \
  --skip-ai false \
  --work-dir /tmp/subtitles

# 下载视频（720P清晰度，需要登录）
BBDown "https://www.bilibili.com/video/BV1xx411c7mW" \
  --use-app-api \
  -q "720P" \
  --work-dir /tmp/videos

BBDown常用参数：

参数	说明
--sub-only	仅下载字幕
--skip-ai false	必须使用：不禁用AI字幕下载
--use-app-api	使用APP端API（通常更稳定）
--use-tv-api	使用TV端API
-q "720P"	指定清晰度（720P、1080P等）
--work-dir	指定工作目录
-p 6	指定下载第6P
-p ALL	下载所有分P

登录方式（必需！否则只能下载低清晰度）：

# 方式1：二维码登录（需要显示界面）
BBDown login

# 方式2：Cookie登录（推荐，无需显示界面）
# 获取Cookie：浏览器登录B站 → F12 → Network → 找到Cookie
BBDown --cookie "你的cookie字符串" "视频URL"

# 方式3：TV端登录
BBDown logintv

清晰度说明：

登录状态	可下载清晰度
未登录	最高480P
已登录WEB账号	最高1080P
已登录TV/APP账号	最高4K/8K

建议：使用Cookie登录以获取更高清晰度和完整字幕。

🛠️ Tool Definitions

Tool 1: download_bilibili_cc

Purpose: Download CC subtitles from a Bilibili video

Input parameters:

• url (string, required): Bilibili video URL or BV number
• output (string, optional): Output directory path

Output parameters:

• success (boolean): Whether download was successful
• subtitle_file (string): Path to downloaded subtitle file
• video_title (string): Video title

Tool 2: screenshot_tool

Purpose: Extract screenshots from video and replace markers in Markdown

Input parameters:

• video (string, optional): Video file path
• markdown (string, optional): Markdown file path
• output_dir (string, optional): Output directory for screenshots

Output parameters:

• output (string): Path to processed Markdown file
• screenshots_dir (string): Directory containing screenshots
• screenshot_count (number): Number of screenshots generated

Tool 3: upload_file_to_notion

Purpose: Upload local files to Notion using Direct Upload API

Input parameters:

• token (string, required): Notion API token
• file (string, required): Path to local file to upload

Output parameters:

• success (boolean): Whether upload was successful
• file_upload_id (string): ID of uploaded file (for referencing in Notion)

Tool 4: create_notion_notes_with_images

Purpose: Create Notion learning notes with embedded images (supports file upload)

Input parameters:

• token (string, required): Notion API token
• database_id (string, required): Notion database ID
• video_title (string, required): Video title
• video_url (string, required): Original Bilibili video URL
• segments (array, required): Processed subtitle segments
• markdown_content (string, optional): Markdown content with screenshot markers
• tags (array, optional): Tags for organizing notes
• images_dir (string, optional): Directory containing screenshot images

Output parameters:

• success (boolean): Whether page creation was successful
• page_id (string): ID of created Notion page
• page_url (string): URL of created Notion page
• segments_processed (number): Number of segments added
• images_embedded (number): Number of images embedded

📝 Complete Workflow Example

User input: "帮我把这个B站视频做成带截图的学习笔记：https://www.bilibili.com/video/BV11u4m1c7ZV?p=6"

Model workflow:

Step 1: Download subtitles

调用 download_bilibili_cc 工具下载字幕（自动使用 --skip-ai false 参数下载AI字幕）

Step 2: 你处理字幕

1. 读取字幕文件：从下载的字幕文件中读取所有内容
2. 逐字保留：禁止任何删减、总结或省略，必须逐字保留所有文字
3. 添加标点和段落：为每句话添加合适的标点符号，适当划分自然段
4. 添加截图标记：在适当位置添加 Screenshot-[hh:mm:ss] 标记
5. 输出结构化JSON：包含segments数组和markdown_content

截图标记规则（你必须遵守）：

场景	示例	截图标记
代码讲解	"在代码中，我们使用以下函数..."	Screenshot-[00:00:20]
UI交互操作	"点击这里查看课程大纲"	Screenshot-[00:00:07]
视觉指代词	"如图所示，电力系统包括..."	Screenshot-[00:00:12]
网址/链接	"访问 https://example.com"	Screenshot-[00:00:16]
任何借助视觉材料	任何需要看图才能理解的内容	Screenshot-[时间]

输出格式示例：

{
  "segments": [
    {
      "start_time": "00:00:03",
      "end_time": "00:00:07",
      "text": "在这个课程中，我们将学习电力系统的基本概念",
      "is_key_point": false
    },
    {
      "start_time": "00:00:12",
      "end_time": "00:00:16",
      "text": "如图所示，电力系统包括发电、输电、配电和用电四个部分",
      "is_key_point": true,
      "concepts": ["电力系统"]
    }
  ],
  "markdown_content": "# 学习笔记\n\n## 片段 1: 00:00:03\n在这个课程中，我们将学习电力系统的基本概念\n\n## 片段 2: 00:00:12\n如图所示，电力系统包括发电、输电、配电和用电四个部分 Screenshot-[00:00:12]"
}

Step 3: Generate screenshots

调用 screenshot_tool 工具从视频提取截图

注意：screenshot_tool会自动替换Markdown中的Screenshot-[hh:mm:ss]标记为图片路径assets/screenshot_hh_mm_ss.jpg。你需要将这个路径修正为实际路径（如/tmp/screenshots/screenshot_hh_mm_ss.jpg）才能在Notion中正确显示。

Step 4: Upload images to Notion

调用 upload_file_to_notion 工具上传截图

Step 5: Create Notion notes

调用 create_notion_notes_with_images 工具创建笔记

Step 6: Notion重复检查与清理（必须执行）

1. 创建成功或失败后，调用 Notion API 查询数据库，检查是否生成了标题重复的页面（尤其是报错但标题已落库的情况）。
2. 保留最新的最终版本，其他同标题的旧版/出错版设置 archived: true 进行软删除。
3. 清理时注意不要误删用户已有的其他笔记（只清理本次处理的同标题页面）。

Output to user: "✅ 已成功创建带截图的Notion学习笔记：https://www.notion.so/xxx"

Complete Workflow Script

You can also use the integrated workflow script:

python3 bilibili_to_notion_workflow.py \
  --url "https://www.bilibili.com/video/BV11u4m1c7ZV?p=6" \
  --token "$NOTION_API_KEY" \
  --database-id "$NOTION_DATABASE_ID" \
  --output-dir "./output"

This script automatically handles all steps:

1. Downloads Bilibili subtitles
2. Processes subtitles and identifies key points
3. Generates screenshots at key timestamps
4. Uploads images to Notion
5. Creates a complete Notion learning笔记 with embedded images

🎯 When to Use This Skill

Use this skill when user:

• Provides Bilibili video URL or BV number
• Wants to extract video subtitles
• Needs to create learning notes from video content
• Mentions "带截图"、"截图"、"图片" etc.
• Asks to convert video content to structured notes with visual aids

Do NOT use this skill when:

• User wants to download video files without notes
• User wants to edit existing Notion pages
• User provides non-Bilibili video URLs

⚙️ Configuration Requirements

必需工具

• ✅ BBDown: B站下载器
• ✅ FFmpeg: 视频截图工具
• ✅ Python 3.7+: 运行脚本

环境变量

export NOTION_API_KEY="secret_xxx"  # Notion API token
export NOTION_DATABASE_ID="xxx"     # 目标数据库ID（可选）

文件结构

工作目录/
├── video.mp4              # 视频文件
├── subtitles.srt          # 字幕文件（由你处理）
├── output/
│   └── screenshots/       # 截图保存目录
└── notes_with_images.md   # 处理后的Markdown（带图片链接）

注意：字幕处理由你负责，不使用固定的Python程序

📊 Expected Output Format

Success Case

✅ 已下载字幕: [文件路径]
✅ 已处理字幕: [X]个片段, [Y]个关键点
✅ 已生成截图: [X]张图片
✅ 已创建Notion笔记: [页面链接]

Error Cases

❌ 字幕下载失败: [错误信息]
❌ 视频未找到: 请提供视频文件路径
❌ Notion API错误: [错误信息]

🔍 Quality Criteria

For download_bilibili_cc

• ✅ Successfully downloads CC subtitles
• ✅ Handles both BV numbers and full URLs
• ✅ Returns video title and file path

For model text processing

• ✅逐字保留字幕所有文字，不删减不总结
• ✅为每句话添加合适的标点和段落
• ✅在适当位置添加截图标记 Screenshot-[hh:mm:ss]
• ✅输出结构化的JSON（segments和markdown_content）
• ✅正确识别需要截图的场景（代码、UI操作、视觉指代、链接等）

For screenshot_tool

• ✅ Extracts screenshots at correct timestamps
• ✅ Replaces markers with image links
• ✅ Handles missing video gracefully

For create_notion_notes_with_images

• ✅ Creates properly formatted Notion pages
• ✅ Automatically uploads local images to Notion
• ✅ Embeds uploaded images in the page
• ✅ Includes timestamp links back to video
• ✅ Handles API errors gracefully

For upload_file_to_notion

• ✅ Successfully uploads files using Notion Direct Upload API
• ✅ Returns file_upload_id for referencing in Notion
• ✅ Handles file not found errors
• ✅ Supports various file types (images, PDFs, videos, etc.)

🚨 故障排除

BBDown下载问题

问题1：字幕只有几秒钟

• 原因：BBDown默认跳过AI字幕下载
• 解决：使用 --skip-ai false 参数

问题2：只能下载480P清晰度

• 原因：未登录B站账号
• 解决：使用Cookie登录或二维码登录

问题3：下载失败/解析失败

• 原因：网络问题或视频URL错误
• 解决：
  • 检查网络连接
  • 确认视频URL正确
  • 尝试使用不同API：--use-app-api 或 --use-tv-api

Notion上传问题

问题1：图片无法显示

• 原因：Markdown中的图片路径错误
• 解决：确保使用绝对路径（如/tmp/screenshots/screenshot_xxx.jpg）

问题2：上传失败

• 原因：文件过大或网络问题
• 解决：
  • Notion免费账号限制5MB/文件
  • 检查网络连接
  • 确认API token有效

字幕处理问题

问题1：字幕片段太少

• 原因：process_subtitles.py的min_length过滤
• 解决：现在由大模型处理，不受此限制

问题2：截图标记未正确添加

• 原因：大模型未按规则添加标记
• 解决：确保按规则在代码、UI操作、视觉指代、链接等位置添加Screenshot-[hh:mm:ss]

📚 References

• Bilibili API: https://space.bilibili.com/
• Notion API: https://developers.notion.com/
• BBDown: https://github.com/nilaoda/BBDown