Overview
Deep Reading Assistant, supports deep reading and note management for YouTube videos, PDF books, podcasts, web pages, and other content. Based on Mortimer Adler's "How to Read a Book," it implements three levels of reading: inspectional reading, analytical reading, and comparative reading.
When to Use
When the user says the following, this skill is automatically triggered:
- "Help me watch/read/study this video" + YouTube URL
- "Deep read this content"
- "Analyze this video/article"
- "Read this book" + PDF path
- "Play xxx" (already downloaded content)
Quick Start - AI Operation Flow
1. YouTube Video Processing
When the user provides a YouTube URL:
# Step 1: 下载内容
cd /Users/liweixin/.claude/skills/deep-reading
python3 -m src.fetcher.cli "YOUTUBE_URL"
# Step 2: 生成检视阅读报告
python3 -m src.processor.cli youtube_VIDEO_ID
# Step 3: 告诉用户笔记已生成，可在 Obsidian 查看
2. PDF Book Processing
When the user provides a PDF file path or Zotero directory:
# Step 1: 处理 PDF（提取文本和元数据）
python3 -m src.fetcher.cli "/path/to/file.pdf"
# 或提供包含 PDF 的目录（如 Zotero storage）
python3 -m src.fetcher.cli "/Users/liweixin/Zotero/storage/VDEZ72XG"
# Step 2: 生成检视阅读报告
python3 -m src.processor.cli pdf_XXXXXX
# Step 3: 告诉用户笔记已生成
3. Play Downloaded Content
# 列出所有已下载内容
python3 -m src.player.cli -l
# 播放指定内容 (交互式，需要用户操作)
python3 -m src.player.cli SOURCE_ID
4. View Generated Notes
Notes saved at: ~/smart notes/DeepReading/Sources/
Complete Workflow Example
User: "Help me deep read this video https://www.youtube.com/watch?v=RSNuB9pj9P8"
AI Operation:
cd /Users/liweixin/.claude/skills/deep-reading
# 1. 下载视频内容
python3 -m src.fetcher.cli "https://www.youtube.com/watch?v=RSNuB9pj9P8"
# 2. 生成检视阅读报告到 Obsidian
python3 -m src.processor.cli youtube_RSNuB9pj9P8
AI Reply: "Completed!
- 📥 Downloaded video: [Title]
- 📝 Generated inspectional reading report: ~/smart notes/DeepReading/Sources/[Title].md
- 🎧 If you need to play the audio, please let me know
Notes include:
- Video metadata
- Quick summary (to be filled in after AI analysis)
- Core viewpoints
- Key concepts
- Reflection questions
Do you need me to play this video for you?"
User: "Read this book /Users/liweixin/Zotero/storage/VDEZ72XG"
AI Operation:
# 1. 处理 PDF
python3 -m src.fetcher.cli "/Users/liweixin/Zotero/storage/VDEZ72XG"
# 2. 生成报告
python3 -m src.processor.cli pdf_XXXXXX
AI Reply: "Completed!
- 📖 Processed book: [Title]
- 📝 Generated inspectional reading report: ~/smart notes/DeepReading/Sources/[Title].md
- 📄 Total XX pages
Notes include:
- Book metadata (title, author, page count)
- Quick summary (to be filled in after AI analysis)
- Core viewpoints
- Key concepts
- Reflection questions"
Cache and Data Locations
~/.deep-reading/
├── cache/
│ ├── youtube/{video_id}/
│ │ ├── audio.mp3 # 音频文件
│ │ ├── transcript.vtt # 带时间戳的字幕
│ │ ├── transcript.txt # 纯文本字幕
│ │ └── metadata.json # 视频元数据
│ └── pdf/{pdf_id}/
│ ├── source.pdf # PDF 副本
│ ├── content.txt # 提取的文本
│ └── metadata.json # PDF 元数据
├── db/deep_reading.db # SQLite 数据库
└── config.py # 配置文件
~/smart notes/DeepReading/
└── Sources/ # Obsidian 笔记
└── {标题}.md
Playback Control Keys (inform the user)
| Key | Function |
|---|---|
空格 |
Pause/Play |
j |
Fast forward 30 seconds |
k |
Rewind 10 seconds |
J |
Fast forward 60 seconds |
K |
Rewind 30 seconds |
+ / = |
Speed up |
- |
Slow down |
q |
Exit |
Error Handling
- No subtitles: Some videos may not have subtitles, which will cause an error
- Network issues: When download fails, prompt the user to check the network
- Already exists: If the content has already been downloaded, the cache will be used
- PDF parsing: Requires installing PyMuPDF (
pip install PyMuPDF)
Future Features (M2-M6)
- M2: TUI player + subtitle synchronization
- M3: AI automatic chapter segmentation + concept cards
- M4: Obsidian bidirectional link auto-generation
- M5: Podcast support
- M6: Web page support
Note Writing Guidelines
Obsidian bidirectional link [[]] rules
Important: Only use [[]] links when the target file already exists!
- ❌ Forbidden: Add empty links pointing to non-existent files, such as
[[效价]]、[[强化学习]] - ✅ Correct: First create the note file, then add
[[文件名]]links in other notes - ✅ Correct: For concepts not yet created, use plain text descriptions, such as "Valence"
Check whether links are valid
Before adding [[]] links, confirm the file exists:
ls "~/smart notes/DeepReading/Sources/目标文件名.md"
Example
# 正确做法
- 父笔记：A Brief History of Intelligence.md
- 相关概念：效价(Valence)、两侧对称动物
# 错误做法（目标文件不存在）
- 父笔记：[[A Brief History of Intelligence]]
- 相关概念：[[效价]]、[[两侧对称动物]]