solo-index-youtube

索引 YouTube 频道视频和文字记录以进行语义搜索。当用户说“索引 YouTube”、“添加 YouTube 频道”、“更新视频索引”或“索引文字记录”时使用。与 Solograph MCP（如果可用）一起使用或通过 yt-dlp 独立使用。

# /index-youtube

Index YouTube video transcripts into a searchable knowledge base. Supports two modes depending on available tools.

## Prerequisites

Check that yt-dlp is available:

```bash
which yt-dlp || echo "MISSING: install yt-dlp (brew install yt-dlp / pip install yt-dlp / pipx install yt-dlp)"
```

## Arguments

Parse `$ARGUMENTS` for channel handles or "all":
- If empty or "all": index all channels (from config or ask user)
- If one or more handles: index only those channels (e.g., `GregIsenberg ycombinator`)
- Optional flags: `-n <limit>` (max videos per channel, default 10), `--dry-run` (parse only)

## Mode Detection

Check which mode is available:

### Mode 1: With solograph MCP (recommended)

If MCP tools `source_search`, `source_list`, `source_tags` are available, use solograph for indexing and search.

**Setup (if not yet installed):**
```bash
# Install solograph
pip install solograph
# or
uvx solograph
```

**Indexing via solograph CLI:**
```bash
# Single channel
solograph-cli index-youtube -c GregIsenberg -n 10

# Multiple channels
solograph-cli index-youtube -c GregIsenberg -c ycombinator -n 10

# All channels (from channels.yaml in solograph config)
solograph-cli index-youtube -n 10

# Dry run (parse only, no DB writes)
solograph-cli index-youtube --dry-run
```

If `solograph-cli` is not on PATH, try:
```bash
uvx solograph-cli index-youtube -c <handle> -n 10
```

**Verification via MCP:**
- `source_list` — check that youtube source appears
- `source_search("startup idea", source="youtube")` — test semantic search
- `source_tags` — see auto-detected topics from transcripts
- `source_related(video_id)` — find related videos by tags

### Mode 2: Without MCP (standalone fallback)

If solograph MCP tools are NOT available, use yt-dlp directly to download transcripts and analyze them.

**Step 1: Download video list**
```bash
# Get recent video URLs from a channel
yt-dlp --flat-playlist --print url "https://www.youtube.com/@GregIsenberg/videos" | head -n 10
```

**Step 2: Download transcripts**
```bash
# Download auto-generated subtitles (no video download)
yt-dlp --write-auto-sub --sub-lang en --skip-download --sub-format vtt \
  -o "docs/youtube/%(channel)s/%(title)s.%(ext)s" \
  "<video-url>"
```

**Step 3: Convert VTT to readable text**
```bash
# Strip VTT formatting (timestamps, positioning)
sed '/^$/d; /^[0-9]/d; /^NOTE/d; /^WEBVTT/d; /-->/d' docs/youtube/channel/video.vtt | \
  awk '!seen[$0]++' > docs/youtube/channel/video.txt
```

**Step 4: Create index**

Read each transcript with the Read tool. For each video, extract:
- Title (from filename or yt-dlp metadata)
- Key topics and insights
- Actionable takeaways
- Timestamps for notable segments (if chapter markers exist)

Write a summary index to `docs/youtube/index.md`:

```markdown
# YouTube Knowledge Index

## Channel: {channel_name}

### {video_title}
- **URL:** {url}
- **Key topics:** {topic1}, {topic2}
- **Insights:** {summary}
- **Actionable:** {takeaway}
```

**Step 5: Search indexed content**

With transcripts saved as text files, use Grep to search:
```bash
# Search across all transcripts
grep -ri "startup idea" docs/youtube/
```

## Output

Report to the user:
1. Number of videos indexed
2. Number of transcripts downloaded (vs skipped — no transcript available)
3. How many had chapter markers
4. Index file location
5. How to search the indexed content (MCP tool or Grep command)

## Common Issues

### "MISSING: install yt-dlp"
**Cause:** yt-dlp not installed.
**Fix:** Run `brew install yt-dlp` (macOS), `pip install yt-dlp`, or `pipx install yt-dlp`.

### Videos skipped (no transcript)
**Cause:** Video has no auto-generated or manual subtitles.
**Fix:** This is expected — some videos lack transcripts. Only videos with available subtitles can be indexed.

### Rate limiting from YouTube
**Cause:** Too many requests in short time.
**Fix:** Reduce `-n` limit, add `--sleep-interval 2` to yt-dlp commands, or use `--cookies-from-browser chrome` for authenticated access.

### solograph-cli not found
**Cause:** solograph not installed or not on PATH.
**Fix:** Install with `pip install solograph` or `uvx solograph`. Check `which solograph-cli`.

---

## 中文说明

# /index-youtube

将 YouTube 视频文字记录索引到可搜索的知识库中。根据可用工具支持两种模式。

## 前置条件

检查 yt-dlp 是否可用：

```bash
which yt-dlp || echo "MISSING: install yt-dlp (brew install yt-dlp / pip install yt-dlp / pipx install yt-dlp)"
```

## 参数

从 `$ARGUMENTS` 中解析频道句柄或 "all"：
- 如果为空或为 "all"：索引所有频道（从配置中获取或询问用户）
- 如果是一个或多个句柄：仅索引这些频道（例如 `GregIsenberg ycombinator`）
- 可选标志：`-n <limit>`（每个频道的最大视频数，默认 10），`--dry-run`（仅解析）

## 模式检测

检查哪种模式可用：

### 模式 1：使用 solograph MCP（推荐）

如果 MCP 工具 `source_search`、`source_list`、`source_tags` 可用，则使用 solograph 进行索引和搜索。

**设置（如果尚未安装）：**
```bash
# Install solograph
pip install solograph
# or
uvx solograph
```

**通过 solograph CLI 进行索引：**
```bash
# Single channel
solograph-cli index-youtube -c GregIsenberg -n 10

# Multiple channels
solograph-cli index-youtube -c GregIsenberg -c ycombinator -n 10

# All channels (from channels.yaml in solograph config)
solograph-cli index-youtube -n 10

# Dry run (parse only, no DB writes)
solograph-cli index-youtube --dry-run
```

如果 `solograph-cli` 不在 PATH 上，请尝试：
```bash
uvx solograph-cli index-youtube -c <handle> -n 10
```

**通过 MCP 进行验证：**
- `source_list` — 检查 youtube 来源是否出现
- `source_search("startup idea", source="youtube")` — 测试语义搜索
- `source_tags` — 查看从文字记录中自动检测到的主题
- `source_related(video_id)` — 按标签查找相关视频

### 模式 2：不使用 MCP（独立回退）

如果 solograph MCP 工具不可用，则直接使用 yt-dlp 下载文字记录并进行分析。

**步骤 1：下载视频列表**
```bash
# Get recent video URLs from a channel
yt-dlp --flat-playlist --print url "https://www.youtube.com/@GregIsenberg/videos" | head -n 10
```

**步骤 2：下载文字记录**
```bash
# Download auto-generated subtitles (no video download)
yt-dlp --write-auto-sub --sub-lang en --skip-download --sub-format vtt \
  -o "docs/youtube/%(channel)s/%(title)s.%(ext)s" \
  "<video-url>"
```

**步骤 3：将 VTT 转换为可读文本**
```bash
# Strip VTT formatting (timestamps, positioning)
sed '/^$/d; /^[0-9]/d; /^NOTE/d; /^WEBVTT/d; /-->/d' docs/youtube/channel/video.vtt | \
  awk '!seen[$0]++' > docs/youtube/channel/video.txt
```

**步骤 4：创建索引**

使用 Read 工具读取每个文字记录。对于每个视频，提取：
- 标题（从文件名或 yt-dlp 元数据）
- 关键主题和见解
- 可操作的要点
- 值得注意片段的时间戳（如果存在章节标记）

将摘要索引写入 `docs/youtube/index.md`：

```markdown
# YouTube Knowledge Index

## Channel: {channel_name}

### {video_title}
- **URL:** {url}
- **Key topics:** {topic1}, {topic2}
- **Insights:** {summary}
- **Actionable:** {takeaway}
```

**步骤 5：搜索已索引的内容**

将文字记录保存为文本文件后，使用 Grep 进行搜索：
```bash
# Search across all transcripts
grep -ri "startup idea" docs/youtube/
```

## 输出

向用户报告：
1. 已索引的视频数量
2. 已下载的文字记录数量（与跳过的数量对比 — 无可用文字记录）
3. 有多少个包含章节标记
4. 索引文件位置
5. 如何搜索已索引的内容（MCP 工具或 Grep 命令）

## 常见问题

### "MISSING: install yt-dlp"
**原因：** 未安装 yt-dlp。
**解决：** 运行 `brew install yt-dlp`（macOS）、`pip install yt-dlp` 或 `pipx install yt-dlp`。

### 视频被跳过（无文字记录）
**原因：** 视频没有自动生成或手动添加的字幕。
**解决：** 这是预期行为 — 有些视频缺少文字记录。只有具有可用字幕的视频才能被索引。

### YouTube 速率限制
**原因：** 短时间内请求过多。
**解决：** 降低 `-n` 限制，在 yt-dlp 命令中添加 `--sleep-interval 2`，或使用 `--cookies-from-browser chrome` 进行已认证访问。

### 找不到 solograph-cli
**原因：** solograph 未安装或不在 PATH 上。
**解决：** 使用 `pip install solograph` 或 `uvx solograph` 安装。检查 `which solograph-cli`。