# Video To Knowledge

> 把 YouTube / B站 / 抖音 视频自动转化为 Obsidian 深度学习知识库。 v2 升级：细粒度知识点拆分 + web深度搜索扩展 + 三信源融合（视频+web+可选教材）+ 9段式深度笔记 + 知识谱系总图（Mermaid mindmap）+ 学习闭环（复习清单+掌握检验）。 工作流：用户贴视频链接 → 自动下载(字幕优先/无字幕转写) → LLM细粒度知识点拆分（5-15个）→ 每知识点4-6路web深度搜索 → 三信源融合 → 视频总览笔记 + 每个知识点独立9段式笔记 → 知识谱系总图 → 复习清单。支持单视频和批量(播放列表/频道)。 典型触发语：'把这个视频整理成笔记'、'视频转知识库'、'总结这个YouTube/B站/抖音视频'、 '学习这个视频'、'视频笔记 <链接>'、'批量整理这个播放列表'、'把这个频道的视频都做成笔记'。

- Skill: `reinforce52/video-to-knowledge` (Agent Skill, multi-file: 13 files)
- Install (CLI): `npx skillmds@latest add reinforce52/video-to-knowledge`
- Raw SKILL.md: https://api.skillmd.com/api/skills/reinforce52/video-to-knowledge/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: reinforce52 (https://skillmd.com/u/reinforce52)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/reinforce52/video-to-knowledge

---


# 视频转知识库 Skill v2 (video-to-knowledge)

把视频自动转化为**深度学习知识库**，不只是简单总结，而是以视频为骨架、web搜索为营养、知识点为血肉的系统化学习体系。

## v2 核心升级（vs v1）

| 维度 | v1（旧） | v2（新） |
|---|---|---|
| 笔记结构 | 单篇视频笔记，塞"核心知识点+易错点+时间戳" | **两层结构**：视频总览 + 每个知识点独立9段式深度笔记 |
| 知识点粒度 | 3-8个，每个1-2句话 | **5-15个细粒度知识点**，每个4-6句话+公式+例题 |
| 信源 | 只有视频转写/字幕 | **三信源融合**：视频（骨架）+ web深度搜索（扩展）+ 可选教材PDF（定义/定理） |
| 知识关联 | 无 | 每个知识点带**前置/后续/关联**，构建知识网络 |
| 知识谱系 | 只有 `_总览.md` 列表索引 | **Mermaid mindmap 全景图** + 知识关联图 + 学习路径 |
| 学习闭环 | 无 | **复习清单**（1/3/7/15天间隔重复）+ **掌握检验 checklist** |
| web搜索 | 无 | 每个知识点**4-6路深度搜索**（定义/应用/易错/拓展/关联） |

## 核心能力

- **三平台支持**：YouTube（代理 127.0.0.1:7897）、B站（直连）、抖音（cookie 已配）
- **字幕优先**：有字幕直接抓，省转写时间；无字幕用 faster-whisper 本地转写
- **细粒度知识点拆分**：LLM 自动拆解为5-15个知识点，每个带时间戳、前置/后续/关联
- **web深度搜索扩展**：每个知识点4-6路搜索（定义/应用/易错/拓展/关联），DuckDuckGo + LLM总结
- **三信源融合**：视频内容（带时间戳）+ web搜索扩展 + 可选教材PDF（复用 topic-knowledge-base 的 MinerU 流程）
- **9段式深度笔记**：定义/原理→细分概念→例题应用→易错点→拓展知识→知识关联→掌握检验→学习建议→参考来源
- **知识谱系总图**：Mermaid mindmap 全景图 + 知识关联图（前置/后续关系）+ 学习路径
- **学习闭环**：复习清单（1/3/7/15天间隔重复）+ 掌握检验 checklist
- **多视频融合**：相同题材博主融合对比，互补内容整合
- **自动清理**：处理完自动删临时视频/音频，只留笔记

## 脚本位置

所有脚本在 `skills/video-to-knowledge/scripts/`：

| 脚本 | 用途 | 版本 |
|---|---|---|
| `pipeline.py` | 主流程：下载→转写→知识点拆分总结（一键跑完），默认GPU，`--cpu`回退 | v2 |
| `batch_process.py` | 批量处理B站合集/分P（断点续传、混合模型、`--retry-failed`） | v1 |
| `download.py` | 下载模块（平台识别+字幕优先+音频下载，分P独立目录） | v1 |
| `transcribe.py` | 转写模块（faster-whisper，默认RTX4060 GPU加速，长音频8分钟分段+GC+模型四级回退） | v1 |
| `summarize.py` | LLM总结模块 v2（细粒度知识点拆分，每个带前置/后续/关联/公式/例题） | **v2** |
| `knowledge_deep_dive.py` | **web深度搜索扩展**：对每个知识点4-6路DuckDuckGo搜索+LLM扩展（定义补充/应用场景/易错点/拓展知识） | **v2 新增** |
| `build_knowledge_graph.py` | **知识谱系总图生成**：Mermaid mindmap + 知识关联图 + 学习路径 | **v2 新增** |
| `write_obsidian.py` | Obsidian写入模块 v2（两层结构：视频总览+知识点独立9段式笔记+复习清单） | **v2** |
| `fusion_compare.py` | 多合集/多博主融合对比，生成 `_融合对比.md` | v1 |
| `rebuild_overview.py` | 按现有笔记重建干净的 `_总览.md` | v1 |

## 触发指令

### 单视频处理（基础版，只有视频信源）
```
视频笔记 <视频链接>
整理这个视频 <链接>
把这个视频做成笔记 <链接>
学习这个视频 <链接>
```

### 单视频处理（深度版，视频+web搜索双信源）
```
视频深度笔记 <视频链接>
视频建库 <链接>
把这个视频做成知识库 <链接>
```

### 批量处理（播放列表/频道/B站合集分P）
```
批量整理 <播放列表链接>
把这个频道的视频都做成笔记 <频道链接>
视频批量建库 <合集链接>
```

## 工作流（Agent 必须严格遵循）

### 模式选择

| 模式 | 触发词 | 流程 | 预估token |
|---|---|---|---|
| **基础版** | "视频笔记"、"整理这个视频" | 下载→转写→总结→写入（单篇视频笔记） | ~10K |
| **深度版（推荐）** | "视频深度笔记"、"视频建库"、"做成知识库" | 下载→转写→知识点拆分→web深度搜索→三信源融合→两层笔记→知识谱系→复习清单 | ~50-80K |
| **批量版** | "批量整理"、"合集" | 批量下载→转写→总结→写入同一主题，最后融合对比 | 每个视频~10K（基础）或~50K（深度） |

### 步骤1：确认输入
- 解析用户消息中的视频链接
- 判断模式（基础/深度/批量）
- 如果是批量（播放列表/频道），先列出将处理的视频数量，等用户确认

### 步骤2：运行主流程（下载→转写→知识点拆分总结）
```bash
python "<skill目录>\scripts\pipeline.py" "<视频URL>" --json
```
- 转写模型默认 `small`（平衡速度和质量）；长视频/学习资料用 `medium`；快速预览用 `tiny`
- 有字幕时自动跳过转写；无字幕时自动转写
- **v2 总结输出**：细粒度知识点列表（5-15个），每个知识点带：名称、详细解释、时间戳、重要性、前置知识、后续延伸、关联知识点、细分概念、关键公式、典型例题
- 同时输出：知识发展脉络（knowledge_chain）、视频内容概述、关键时间戳、学习建议
- **处理完成后自动清理临时大文件**：删除视频文件（.mp4等）、音频文件（.mp3等）、转写片段目录（segments/）
- **保留**：metadata.json（含视频链接）、字幕文件（.srt/.txt）、总结结果（summary.json）

### 步骤3（深度版）：web深度搜索扩展
```bash
python "<skill目录>\scripts\knowledge_deep_dive.py" "<summary.json路径>" --output "<deep_dive.json路径>"
```
- 对每个知识点自动生成4-6路搜索查询：定义原理、应用场景、易错点、与主题关系、拓展知识
- DuckDuckGo HTML 搜索（不需要API key，禁用代理直连）
- LLM 基于搜索结果生成扩展内容：定义补充、应用场景、常见错误、拓展知识、学习建议、参考链接
- 输出 `deep_dive.json`（包含原知识点 + web扩展 + 搜索结果）
- **token优化**：每个知识点搜索结果限制10条，LLM扩展限制2000 token；批量处理时相似知识点复用搜索结果

### 步骤4（深度版）：生成知识谱系总图
```bash
python "<skill目录>\scripts\build_knowledge_graph.py" "<deep_dive.json路径>" --output "<主题目录>\_知识谱系总图.md" --video-title "<视频标题>"
```
- 生成 Mermaid mindmap（按重要性分组：核心/重要/了解 → 知识点 → 细分概念）
- 生成知识关联图（graph LR，知识点之间的前置/后续关系连线）
- 生成学习路径（按重要性排序，每个知识点带前置/后续）
- 生成知识点索引表（点击跳转深度笔记）

### 步骤5：输出主题建议，等用户确认
- 向用户展示：
  - **建议主题**：（LLM 建议的主题名）
  - **归类理由**：（为什么建议这个主题）
  - **一句话总结**：（视频核心内容）
  - **知识点数量**：N 个细粒度知识点
  - **知识发展脉络**：（前置→当前→后续）
  - **模式**：基础版 / 深度版
  - **将要写入的路径**：`E:\obsidian\rein\<主题>\`
  - **将要生成的文件**：视频总览笔记 + N个知识点笔记 + 知识谱系总图 + 复习清单（深度版）

然后询问：`确认写入这个主题吗？回复【确认】写入，或回复【主题=xxx】修改主题后写入`

**禁止静默写入**——必须等用户确认。

### 步骤6：用户确认后写入 Obsidian
```bash
# 基础版（summary.json）
python "<skill目录>\scripts\write_obsidian.py" "<summary.json路径>" --topic "<确认的主题>"

# 深度版（deep_dive.json）
python "<skill目录>\scripts\write_obsidian.py" "<deep_dive.json路径>" --topic "<确认的主题>"
```
- write_obsidian.py v2 自动识别格式（summary.json v1 或 deep_dive.json v2）
- **两层笔记结构 + 双向跳转**：
  - `视频笔记/<平台>_<标题>.md`：视频总览（基本信息+**核心知识点快速跳转列表**🔴高/🟡中/⚪低+可点击wikilink+一句话核心内容，手机端易点击+知识点详细索引表+关键时间戳+学习建议）
  - `知识点/<知识点名>.md`：每个知识点独立9段式深度笔记，顶部带 **📺 返回视频总览** 双向跳转链接
- **复习清单**：`_复习清单.md`（1/3/7/15天间隔重复，每个知识点带复习状态）
- **主题总览**：`_总览.md`（视频索引表，按 video_id 幂等去重）
- **合集总谱系**：`_合集知识谱系总图.md`（多集合集级Mermaid全景，16集→知识点三层）
- 临时视频/音频文件已在步骤2自动清理

### 步骤7：输出完成报告
- 写入的主题目录路径
- 视频总览笔记路径
- 知识点笔记数量和路径
- 知识谱系总图路径（深度版）
- 复习清单路径（深度版）
- 视频链接（方便回看）

## 9段式深度笔记标准模板（知识点独立笔记）

```markdown
---
category: "<主题>"
tags: ["知识点", "<知识点名>", "视频学习"]
source: ["视频: <视频标题>", "web深度搜索"]
importance: "高/中/低"
video_timestamp: "05:30"
created: "YYYY-MM-DD"
---

# <知识点名>

> 视频讲解位置：**05:30** — [<视频标题>](<视频URL>)

---

## 📌 一、核心定义与原理
（视频中的详细解释，4-6句话，讲清楚定义/原理/推导）

### 📖 定义补充（web搜索扩展）
（web搜索补充的定义深化，视频没讲透的部分）

### 📐 关键公式
- 公式1
- 公式2

## 🧩 二、细分概念
1. **细分概念1**
2. **细分概念2**

## 📝 三、典型例题与应用
**例1**：（视频中的例题）

### 🌐 应用场景（web搜索扩展）
- 应用场景1（具体实例）
- 应用场景2

## ⚠️ 四、易错点与常见错误
1. 常见错误1（错误做法+正确做法）
2. 常见错误2

## 🚀 五、拓展知识
（web搜索扩展的进阶概念或跨学科联系）

## 🔗 六、知识关联
### 📚 前置知识
- [[知识点/<前置1>|<前置1>]]

### ➡️ 后续延伸
- [[知识点/<后续1>|<后续1>]]

### 🔄 关联知识点
- [[知识点/<关联1>|<关联1>]]

## ✅ 七、掌握检验（自测清单）
- [ ] 能复述核心定义
- [ ] 理解原理和推导
- [ ] 能熟练运用相关公式
- [ ] 能举出应用场景
- [ ] 能区分与相关概念的区别
- [ ] 能独立完成视频中的例题

## 📖 八、学习建议
（web搜索扩展的学习建议，这个知识点应该怎么学、学到什么程度）

## 📚 九、参考来源
- **视频**：[<视频标题>](<视频URL>)（时间戳）
- **web扩展1**：[标题](URL)
- **web扩展2**：[标题](URL)

---
> 📌 本笔记由 video-to-knowledge skill v2 自动生成，基于视频转写 + web深度搜索 + LLM知识关联分析。
```

## 知识点拆分规则（summarize.py v2）

1. **数量**：尽可能细化，至少5个，最多15个，按视频讲解顺序排列
2. **每个知识点必须包含**：
   - `point`：知识点名称（简洁明确）
   - `detail`：详细解释（4-6句话，定义/原理/推导/应用）
   - `timestamp`：视频中出现的时间点（如"05:30"）
   - `importance`：高/中/低
   - `prerequisites`：前置知识（学习这个知识点需要先掌握什么）
   - `follow_ups`：后续延伸（学完后可以继续学习什么）
   - `related`：关联知识点
   - `sub_points`：细分小知识点
   - `key_formulas`：关键公式（如果有）
   - `examples`：典型例题或应用案例
3. **知识发展脉络**（knowledge_chain）：必须讲清楚知识点的发展脉络，用"→"连接，不是简单罗列
4. **所有内容必须来自转写文本**，不要编造；转写文本可能有识别错误，根据上下文合理修正

## web深度搜索流程（knowledge_deep_dive.py）

### 搜索查询生成（每个知识点4-6路）
1. `<知识点> 定义 原理`
2. `<知识点> 应用场景 实例`
3. `<知识点> 易错点 常见错误`
4. `<知识点> 与 <视频主题> 关系`
5. `<知识点> 拓展知识 进阶`

### 搜索方式（国内环境实测，2026-09 更新）
- **主用必应中国 `cn.bing.com/search`（国内直连，不需要VPN，最稳定）**：按 `<li class="b_algo">` 分割解析（不依赖 `</li>` 闭合，避免嵌套匹配失败），取 h2>a 标题链接 + b_lineclamp/b_caption 摘要，过滤 bing.com/microsoft.com 自身链接
- **DuckDuckGo 仅作VPN备选**：DDG（html.duckduckgo.com）在国内**直连和常见代理端口都不通**（实测 ProxyEnable=0、7897/7890/7892 均无监听时全部 Max retries exceeded）；只有检测到 7897/7890/7892 端口有活代理时才作为补充
- 统一入口 `web_search()`：先必应，结果不足2条才尝试代理端口的DDG
- ⚠️ **关键坑**：搜索脚本对B站/必应走直连（禁用代理环境变量），不要误以为"挂了VPN就能用DDG"——VPN若没开系统代理/没监听HTTP端口，Python requests 照样连不上
- 必应返回100KB但解析0条 → 多为正则依赖 `</li>` 闭合导致，必须用 `re.split('<li class="b_algo">')` 分割法

### LLM 扩展输出（每个知识点）
- `definition_enhanced`：定义补充（2-3句话，视频没讲透的部分）
- `application_scenarios`：应用场景列表（具体实例，不空泛）
- `common_mistakes`：常见错误列表（错误做法+正确做法）
- `extended_knowledge`：拓展知识（2-3句话，进阶概念或跨学科联系）
- `learning_path`：学习建议（1-2句话）
- `references`：参考资料列表（标题+URL）

### token 优化策略
1. 每个知识点搜索结果限制10条，每条摘要限制200字
2. LLM 扩展限制2000 token输出
3. 批量处理时，相似知识点（如"导数"和"微分"）复用搜索结果
4. 用户说"省token"时，只对高重要性知识点做web搜索，中低重要性直接用视频内容
5. 教材PDF可选接入（用户明确要求时），复用 topic-knowledge-base 的 MinerU 流程

## 知识库输出结构（深度版）

```
E:\obsidian\rein\<主题>\
├── _知识谱系总图.md          ← Mermaid mindmap + 知识关联图 + 学习路径
├── _总览.md                  ← 视频索引表（按 video_id 幂等去重）
├── _复习清单.md              ← 间隔重复（1/3/7/15天），每个知识点带复习状态
├── 视频笔记/                 ← 视频总览笔记
│   └── <平台>_<标题>.md      ← 基本信息+知识点索引表+关键时间戳+学习建议
├── 知识点/                   ← 知识点独立9段式深度笔记
│   ├── <知识点1>.md
│   ├── <知识点2>.md
│   └── ...
└── 99-教材原文/              ← 可选（用户提供PDF时接入）
```

## 多视频融合（相同题材博主）

当用户处理了多个相同主题的视频后，主动询问：
> 检测到你在「<主题>」下已有 N 个视频笔记，是否需要生成「多博主融合对比」？
> （分析各博主讲解的相关性、区别点、互补内容）

如果用户确认，用 `fusion_compare.py` 自动汇总临时目录各 summary.json 大纲并调 LLM 生成融合对比文档：
```bash
python scripts/fusion_compare.py --topic "<主题名>" --bvs "<BV1>,<BV2>" --names "<合集名1>,<合集名2>"
```
文档含六部分：各合集定位与内容地图 / 相关性 / 区别点(表) / 互补内容 / 融合学习路线 / 知识盲区。

### 跨视频知识点融合（v2 增强）
- 多个视频讲同一知识点时，自动识别并在知识点笔记中标注：
  - "视频A讲了X，视频B补充了Y"
  - 融合对比不只是"区别"，而是"互补后的完整知识"
- 知识点笔记的 `参考来源` 部分列出所有讲过这个知识点的视频

## 红线（必须遵守）

1. **只允许在 `E:\obsidian\rein\` 下创建/修改笔记**；禁止触碰其他磁盘目录
2. **每个主题 = 独立 vault**：`E:\obsidian\rein\<主题>\`，不混用路径
3. **单视频首次写入前必须等用户确认主题**；禁止静默写入。同一 video_id 重跑允许幂等覆盖（更新该视频自己的笔记），但**绝不覆盖/删除其他视频或其他主题的笔记**
4. **所有内容必须来自视频转写/字幕 + web搜索结果**；视频中没有的信息标注"待补充"，不编造；web搜索内容必须标注来源链接
5. **不删除任何已有 Obsidian 笔记**（清理重复笔记前必须按 video_id 确认有保留件）；只自动删除临时下载的视频/音频
6. **临时文件只放在** `E:\openclaw-video-temp\` 下
7. **抖音 cookie 文件** `douyin-cookies.txt` 在 skill 目录下，不要泄露给用户或写入笔记
8. **同一合集同一时刻只允许一个批量实例运行**（运行锁 progress/.batch_<BV>.lock）；切换 CPU/GPU 重跑前，必须确认旧批量进程（含父进程）已全部停止
9. **web搜索必须禁用代理**（DuckDuckGo 国内可直连，代理未运行会导致连接失败）
10. **深度版 token 消耗较大**（每个视频50-80K），处理前告知用户预估消耗，用户说"省token"时降级为基础版或只对高重要性知识点做web搜索

## 批量作业标准流程 SOP（处理合集/大量分P时严格遵循）

1. **先清环境**：所有命令前清空失效系统代理（本机曾出现 `HTTP_PROXY=127.0.0.1:7892` 代理未运行导致全部网络失败）：
   PowerShell 用 `$env:HTTP_PROXY="";$env:HTTPS_PROXY="";$env:http_proxy="";$env:https_proxy=""`
2. **确认没有旧实例**：`Get-Process python | ? {$_.WorkingSet64 -gt 300MB}`，有残留先停掉（父+子进程都要停），避免两实例重叠产生重复笔记；批量脚本本身也有运行锁拦截。
3. **后台启动**：`batch_process.py --bvid <BV> --topic "<主题>" --model medium --no-hybrid`，用后台任务跑，不要占住前台。
4. **监控看三个信号**：①进度文件 processed 数增长 ②Obsidian 最新笔记时间戳 ③`nvidia-smi` GPU 利用率（GPU 模式应在 50%+）。
5. **判断"真卡死"看 CPU 累计时间而非运行时长**：进程运行很久但 `CPU` 秒数几乎不涨 = 卡死（如 GPU 与 CPU 批量并行时的初始化挂起），正常转写 CPU 时间会持续增长。
6. **失败不慌**：网络类失败（音频下载失败等）先让主批量跑完，最后统一 `--retry-failed`（重试时间隔拉开，成功率高）。
7. **收尾三件事**：①`--retry-failed` 清零失败 ②多合集用 `fusion_compare.py` 出融合对比 ③用下文"交付自检清单"核对。
8. **深度版批量**：批量处理时默认用基础版（省token），用户明确要求"深度建库"时，批量转写总结完成后，再对每个视频的 summary.json 运行 `knowledge_deep_dive.py` + `build_knowledge_graph.py` + `write_obsidian.py`（深度版）。

## 故障排查手册（全部来自实战，按现象速查）

### A. 下载 / 网络类

| 现象 | 根因 | 解决 |
|---|---|---|
| `音频下载失败`，十几秒快速报错 | B站音频流网络抖动/请求过密限流（GPU太快时偶发，约10%） | download.py 已内置3次重试+退避；仍失败就主批量跑完后 `--retry-failed` |
| 所有下载/API 都连不上、超时 | 系统环境变量里的代理（如 7892）没开 | 清空 4 个代理环境变量；download.py 对 B站已在子进程内自动绕过代理 |
| `yt-dlp: error: unrecognized arguments: --no-proxy` | 该版本 yt-dlp 不支持此参数 | 不要传 `--no-proxy`，用清空环境变量方式（已内置） |
| 获取分P列表失败 | 缺请求头被风控 | 必须带 `User-Agent` + `Referer: https://www.bilibili.com/video/<BV>`（已内置） |
| YouTube 下载失败 | VPN/代理问题 | 确认 VPN 开启、端口为 7897（download.py 已内置该代理） |
| 抖音下载失败/要登录 | cookie 过期或私密内容 | 重新从浏览器导出 douyin-cookies.txt |
| web搜索全部超时/失败 | 系统代理未运行或 DuckDuckGo 被墙 | knowledge_deep_dive.py 已禁用代理直连；仍失败则降级为基础版（跳过web搜索） |

### B. 转写 / 内存 / GPU 类

| 现象 | 根因 | 解决 |
|---|---|---|
| 长视频(30分钟+)报 `Unable to allocate`/`mkl_malloc failed` | 整段转写一次性申请连续内存过大 | 已解决：>15分钟自动按 8 分钟分段、逐段转写+时间偏移合并、每段 `gc.collect()`；勿再调大分段 |
| 模型加载阶段就 MemoryError（甚至 import huggingface_hub 都报错） | 内存碎片化/不足 | 已内置四级回退：(指定model,GPU)→(同model,CPU,int8)→(base,CPU)→(tiny,CPU) |
| GPU 报 `cublas64_12.dll not found / cannot be loaded` | pip 装了 cublas/cudnn 但 DLL 目录没被加载 | transcribe.py 已用 `os.add_dll_directory` 自动加载 site-packages/nvidia/*/bin；仍失败加 `--cpu` |
| GPU 进程运行十几分钟、CPU 累计时间却只有十几秒 | 卡死（多为 GPU 测试与 CPU 批量并行争抢，或 cuDNN 初始化挂起） | 不要让 GPU 测试和 CPU 批量并行；验证 GPU 用 15 秒短音频+tiny；卡死就 kill 后单独重跑 |
| 不知道有没有真用上 GPU | — | `nvidia-smi` 看显存占用(medium约2-4GB)和利用率；日志命令行带"（GPU加速）" |
| 单视频超时被杀 | 超长视频 CPU 转写耗时长 | batch 单视频超时已设 3600 秒；GPU 模式下远用不到 |
| 转写模型怎么选 | — | tiny预览 < base < small < medium学习资料(推荐，GPU下5-8倍实时) |

### C. 文件 / 编码 / 解析类

| 现象 | 根因 | 解决 |
|---|---|---|
| 分P之间 metadata/summary 互相覆盖 | 多个分P共用同一临时目录 | 已解决：分P独立目录 `bilibili_<BV>_p<N>` |
| `json.load` 报 JSONDecodeError（BOM） | PowerShell `Set-Content -Encoding utf8` 带 BOM | 已用 `utf-8-sig` 读取兼容；转写文本读取有 UTF-8→GBK→GB2312→Big5→Latin-1 自动回退 |
| pipeline 解析 summarize 的 stdout 失败 | 中文日志混在 stdout 干扰 JSON 提取 | 已改为优先直接读 `output_dir/summary.json`，不依赖解析 stdout |
| `--retry-failed` 28-47秒就"假失败" | 根因（内存/下载）没修就重试，必然快速失败 | 先按本表修根因，再 retry；retry 不是万能，先看失败报错本身 |

### D. 重复 / 索引类（本次重点踩坑）

| 现象 | 根因 | 解决 |
|---|---|---|
| 同一视频出现两份笔记、其中一份带 `_v2` 后缀 | 旧批量父进程没被完全 kill，与新任务短暂重叠，各写一次 | 已三重防护：①批量运行锁 ②write 同视频幂等覆盖不再加_v2 ③总览按 video_id 去重 |
| `_总览.md` 索引条数 > 笔记数、有失效链接 | 重复写入时按文件名去重失效 | 已改为按 video_id 去重；存量损坏用 `rebuild_overview.py <主题>` 一键重建 |
| 清理重复笔记怕误删 | — | 必须按 video_id 分组，确认每个待删文件都有同 video_id 保留件后才删 |
| 融合对比里合集名和 BV 对错位 | 按 BV 字母序排序打乱了传入顺序 | 已改为严格按 `--bvs` 传入顺序对应 `--names` |

### E. LLM 总结 / web搜索类

- API 调用失败：检查 key、网络；summarize.py 已禁用代理直连。
- 转写过长自动截断前 12000 字，避免超 token。
- 总结只花 7-11 秒，**99% 耗时在转写**——提速优先优化转写（GPU），不必纠结总结。
- web搜索（knowledge_deep_dive.py）每个知识点约消耗 3-5K token（搜索结果+LLM扩展），10个知识点约 30-50K token。
- web搜索失败时自动降级：该知识点只用视频内容，不阻塞整体流程。

### F. v2 深度版专属坑（2026-09 实战）

| 现象 | 根因 | 解决 |
|---|---|---|
| pipeline 完成后显示"核心知识点 0 个" | summarize.py v2 输出字段是 `knowledge_points`，而 pipeline.py 旧代码读 `core_knowledge_points` | 已兼容：pipeline 用 `knowledge_points` 优先、回退 `core_knowledge_points`；改总结输出字段名时必须同步改 pipeline 统计 |
| 视频总览文件名变成 `unknown_未知视频.md` | knowledge_deep_dive.py 生成 deep_dive.json 时没把原 summary 的 `metadata` 带过来 | 已修复：deep_dive.json 必须包含 metadata（title/platform/url/video_id）；存量文件用小脚本从 summary.json 补 metadata 即可，无需重跑搜索 |
| 知识点笔记里 wikilink 大量灰色死链 | LLM 生成的前置/后续名是自由文本，和实际知识点文件名不完全一致 | 已用 `link_or_text()` 智能匹配：精确→包含→字符相似度≥0.7 才建 wikilink，匹配不到转纯文本并标注"（拓展·本库暂无独立笔记）"；all_points 同时包含当前视频+主题已有知识点，支持跨视频互链 |
| 知识关联图节点名被截成"线性代数的学科地" | graph LR 节点标签硬截断8字 | 已放宽到12字+省略号，完整名见索引表 |
| DuckDuckGo 搜索全部 `Max retries exceeded` | DDG 国内被墙，禁用代理直连不通，VPN又没监听HTTP端口 | 改主用必应中国直连（见"搜索方式"）；不要在没确认代理端口存活时硬跑DDG |
| PowerShell 跑内联 python -c 报"表达式或语句中包含意外标记" | PowerShell 对引号/冒号转义与 bash 不同 | 复杂逻辑写成临时 .py 文件再 `python 文件.py`，不要用长内联命令 |

## 交付自检清单（批量完成后逐项核对）

1. 每个主题：笔记数 == 进度文件 processed 数 == `_总览.md` 索引行数
2. 无 `_v2` 重复文件、无 <1KB 空文件、无失效总览链接
3. 所有进度文件 `failed` 为 0（否则 `--retry-failed`）
4. 深度版：已生成 `_知识谱系总图.md`（Mermaid mindmap 可正常渲染）、`_复习清单.md`
5. 深度版：知识点笔记数量 == summary.json 中 knowledge_points 数量
6. 深度版：每个知识点笔记包含9段式结构（定义/细分/例题/易错/拓展/关联/自测/建议/来源）
7. 多合集同主题：已生成 `_融合对比.md`
8. `E:\openclaw-video-temp` 无残留 .mp3/.mp4（应只留 metadata/srt/txt/summary，体积很小）
9. 无大型 python 残留进程、GPU 已释放
10. 一键重建总览：`python scripts/rebuild_overview.py "<主题>"`

## 与 topic-knowledge-base skill 的协同

- **视频是骨架，topic skill 是血肉**：video-to-knowledge 负责从视频中拆解知识点，topic-knowledge-base 负责对知识点做全网深度搜索建库
- **可串联使用**：先用 video-to-knowledge 从视频中得到知识点列表，再用 topic-knowledge-base 对每个知识点做深度建库（web+社媒+教材三信源）
- **教材PDF共享**：两个 skill 都复用 MinerU PDF 提取流程（topic skill 的 `scripts/split_pdf.py`、`compress_pdf.py`、`resplit_textbook.py`）
- **笔记格式统一**：两个 skill 都使用9段式深度笔记模板，确保知识库风格一致