# 长视频分段分析功能 - 开发记录

**日期**: 2026-02-06
**任务**: 解决 obsidian-kb 技能中长视频上下文溢出问题
**方案**: 方案C - 动态混合策略（<30min直接分析，30-60min分2段，60min+分多段）

---

## 已完成工作

### ✅ Checkpoint 1: 基础结构
- [x] 创建 `src/content_chunker.py` - 字幕分段工具类
- [x] 更新 `config.yaml` - 添加 chunking 配置节点
- [x] 配置支持：30分钟/60分钟阈值，15分钟分段，6000字符限制

### ✅ Checkpoint 2: 核心逻辑
- [x] 修改 `src/multi_ai_client.py`
- [x] 添加 `_analyze_in_chunks()` - 分段分析主方法
- [x] 添加 `_analyze_chunk()` - 单段摘要生成
- [x] 添加 `_merge_summaries()` - 合并摘要生成最终结果

### ✅ Checkpoint 3: 测试
- [x] 创建 `tests/test_chunking.py` - 单元测试框架
- [x] 创建 `tests/fixtures/sample_long_video.srt` - 测试数据
- [x] 创建 `test_long_video.py` - 手动测试脚本
- [x] 所有测试通过

---

## 功能说明

### 分段策略

| 视频时长 | 处理策略 | API调用次数 |
|---------|---------|------------|
| < 10分钟 | 直接分析 | 1次 |
| 10-30分钟 | 截断至8000字符分析 | 1次 |
| 30-60分钟 | 分2段分析 | 3次 |
| 60分钟+ | 每15分钟一段 | N+1次 |

### 使用方法

```python
from src.content_chunker import ContentChunker, get_chunking_strategy

# 获取分段策略
strategy = get_chunking_strategy(duration_seconds=3600)  # 60分钟视频
print(strategy['num_chunks'])  # 输出: 4

# 分段字幕
chunker = ContentChunker(chunk_duration_seconds=900)
chunks = chunker.chunk_by_duration(srt_text)
```

---

## 文件变更

```
skills/obsidian-kb/
├── src/
│   ├── content_chunker.py          [新增] 字幕分段工具
│   └── multi_ai_client.py          [修改] 添加分段分析逻辑
├── config.yaml                     [修改] 添加 chunking 配置
├── tests/
│   ├── test_chunking.py            [新增] 单元测试
│   └── fixtures/
│       └── sample_long_video.srt   [新增] 测试数据
└── test_long_video.py              [新增] 手动测试脚本
```

---

## 测试结果

```
============================================================
测试分段策略
============================================================

5分钟视频 (300秒):
  策略: direct
  分段: 1段

30分钟视频 (1800秒):
  策略: chunk_2
  分段: 2段

60分钟视频 (3600秒):
  策略: chunk_4
  分段: 4段

2小时视频 (7200秒):
  策略: chunk_8
  分段: 8段

============================================================
测试SRT解析和分段
============================================================
✅ 读取字幕文件: 6339 字符
📊 分段结果: 总分段数: 3
  第1段: 00:00:00.000 - 00:15:30.000, 1331字符
  第2段: 00:15:30.000 - 00:31:00.000, 1214字符
  第3段: 00:31:00.000 - 00:43:00.000, 877字符

============================================================
测试完成！
============================================================
```

---

## 状态

🟢 **已完成** - 功能已实现并测试通过

现在30分钟以上的长视频会自动分段处理，不会再出现 "Context overflow: prompt too large for the model" 错误。

---

## 待办事项 - obsidian-kb 技能改进

**记录时间**: 2026-02-06 20:15
**来源**: 用户反馈

### 🔴 高优先级

#### 1. 技能自动触发机制
- **问题**: 用户发送 B站视频链接时，技能未自动触发
- **原因**: SKILL.md 中未定义触发关键词/模式
- **解决方案**:
  - 在 SKILL.md 中添加触发规则，识别 B站/YouTube 视频链接
  - 或在 _meta.json 中配置触发模式
- **预期**: 用户发送视频链接时，自动添加到收件箱并询问是否处理

#### 2. 短链接解析功能
- **问题**: 手机用户无法获取完整 URL，短链接（b23.tv）会被 B站反爬虫拦截
- **当前状态**: 手动用 curl 解析，但在代码中 412 错误
- **解决方案**:
  - 实现更强大的短链接解析（浏览器自动化/代理池）
  - 或提供用户友好的引导：检测到短链接时提示用户复制完整URL或BV号
- **技术难点**: B站 412 反爬虫策略
- **预期**: 用户可以发送短链接，系统自动解析

#### 3. 单个视频链接分析功能
- **问题**: 技能设计为批量订阅模式，缺少"快速添加单个视频"的便捷命令
- **临时方案**: 创建了 add_video.py 辅助脚本
- **解决方案**:
  - 在 CLI 中添加 `/kb-add` 命令
  - 或集成到现有的 `/kb-subscribe` 中，支持 URL 参数
- **预期**: 用户可以用 `/kb-add <URL>` 快速添加单个视频

#### 4. 本地生成字幕功能
- **问题**: 某些视频没有字幕，导致分析内容为空
- **当前状态**: 只能跳过无字幕视频
- **解决方案**:
  - 集成语音识别工具（如 OpenAI Whisper、Aliyun 语音识别）
  - 下载音频，本地生成字幕
  - 支持多语言识别
- **依赖**: 需要额外的语音识别服务/API
- **预期**: 无字幕视频也能生成笔记

### 📋 实施计划

| 优先级 | 任务 | 预计工时 | 依赖 |
|--------|------|----------|------|
| P0 | 自动触发机制 | 1-2h | SKILL.md 研究 |
| P1 | 单个视频添加命令 | 1h | 无 |
| P2 | 短链接解析 | 2-3h | 反爬虫研究 |
| P3 | 本地生成字幕 | 3-5h | Whisper/API 集成 |

### 🔗 相关文件

- 技能目录: `skills/obsidian-kb/`
- 临时脚本: `skills/obsidian-kb/add_video.py`
- 待办详情: `memory/tasks/obsidian-kb-improvements.md`

---

## 新增：自动触发机制完成（20:45）

### 任务1：自动触发机制 - 已完成 ✓

**完成时间**: 2026-02-06 20:45

#### 实现内容

1. **SKILL.md 更新**
   - 添加 frontmatter 元数据（name, description, version, author）
   - 新增"自动触发规则"章节
   - 详细说明支持的 URL 模式和触发流程
   - 添加短链接友好提示说明

2. **Handler 脚本（handler.py）**
   - 使用正则表达式检测多种 URL 模式
   - 支持平台识别：B站、YouTube、知乎
   - 智能去重避免重复显示
   - 生成友好的预览信息
   - 短链接显示用户引导

3. **支持的 URL 模式**
   - B站: `https://www.bilibili.com/video/BV*`, `BV*`, `https://b23.tv/*`
   - YouTube: `https://www.youtube.com/watch?v=*`, `https://youtu.be/*`
   - 知乎: `https://zhuanlan.zhihu.com/p/*`

4. **测试结果**
   - ✅ 所有 URL 模式检测正确
   - ✅ 短链接显示友好提示
   - ✅ 支持批量检测多个链接
   - ✅ 智能去重避免重复显示

#### 文件变更
```
skills/obsidian-kb/
├── SKILL.md              [修改] 添加 frontmatter 和触发规则
├── handler.py            [新增] 自动触发处理器
└── AUTO_TRIGGER.md       [新增] 实现文档
```

#### 示例输出

**B站完整 URL:**
```
🔍 检测到内容链接:

📺 [1] B站视频
    URL: https://www.bilibili.com/video/BV1xx411c7mD
    ID: BV1xx411c7mD

是否添加到收件箱并处理？(y/n)
```

**B站短链接:**
```
🔍 检测到内容链接:

📺 [1] B站视频
    URL: https://b23.tv/oLBZZfK
    ⚠️  短链接，需要用户提供完整URL或ID

🔗 检测到短链接

⚠️  由于反爬虫保护，短链接无法自动解析

📱 手机用户：
   1. 打开链接
   2. 在浏览器地址栏复制完整 URL
   3. 发送给助手

💻 桌面用户：
   1. 发送 BV 号（如：BV1jcFqz7EFW）
   2. 或使用完整 URL
```

**批量链接:**
```
🔍 检测到内容链接:

📺 [1] B站视频
    URL: https://www.bilibili.com/video/BV1xx411c7mD
📺 [2] B站视频
    URL: https://www.bilibili.com/video/BV2yy522c8nE
▶️ [3] YouTube视频
    URL: https://www.youtube.com/watch?v=dQw4w9WgXcQ

是否将上述 3 个内容添加到收件箱？(y/n)
```

#### 验收标准
- [x] SKILL.md 添加了触发规则
- [x] Handler 能够检测各种 URL 格式
- [x] 显示友好的预览信息
- [x] 短链接显示友好提示
- [x] 支持批量检测多个链接
- [x] 智能去重避免重复显示
- [x] 所有 URL 模式测试通过

#### 后续工作
- 实现 YouTube 和知乎适配器（当前仅 Bilibili 完整支持）
- 短链接自动解析（需要浏览器自动化或代理池）

#### 相关文档
- 实现文档: `skills/obsidian-kb/AUTO_TRIGGER.md`
- 任务详情: `memory/tasks/obsidian-kb-improvements.md`