openclaw-skills/skills/obsidian-kb/SKILL.md

---
name: obsidian-kb
description: Multi-source content knowledge base with video processing. Use when user says "保存知识库", "添加到知识库", "处理这个视频", "生成obsidian笔记" etc. Supports B站/bilibili (BV号, b23.tv, www.bilibili.com) using Playwright, YouTube videos, and Zhihu articles using DrissionPage.
---

# SKILL.md - Obsidian KB Skill

## 🚀 重要：处理流程

**当用户发送视频链接并要求保存到知识库时，直接处理，不要问用户！**

正确流程：
1. 用户发送B站链接（BV号、完整URL、或短链接如 b23.tv/xxxxx）
2. 用户说"保存到知识库"、"添加到知识库"、"处理这个视频"等
3. **直接使用** `workspace/skills/obsidian-kb` 处理
4. 不要检查全局命令，不要问用户"要安装工具还是手动处理"

**示例触发词：**
- "保存到知识库"
- "添加到知识库"
- "处理这个视频"
- "提取字幕生成笔记"
- "生成obsidian笔记"

## 元数据

- **名称**: obsidian-kb
- **版本**: 1.0.0
- **描述**: 多源内容知识库维护系统，支持长视频分段分析
- **作者**: OpenClaw

## 命令列表

| 命令 | 描述 | 用法 |
|------|------|------|
| `/kb-subscribe` | 订阅内容源 | `/kb-subscribe <source>:<type>:<id>` |
| `/kb-inbox` | 查看收件箱 | `/kb-inbox [--limit N]` |
| `/kb-process` | 处理内容 | `/kb-process [content_id]` |
| `/kb-skip` | 跳过内容 | `/kb-skip <content_id>` |
| `/kb-status` | 查看状态 | `/kb-status` |
| `/kb-search` | 搜索知识库 | `/kb-search <query>` |

## 命令详解

### /kb-subscribe

订阅一个内容源，支持自动获取更新。

**用法:**
```
/kb-subscribe bilibili:fav:12345678
/kb-subscribe bilibili:up:123456
/kb-subscribe youtube:channel:UCxxx
/kb-subscribe zhihu:collection:12345
```

**支持的源:**
- `bilibili:fav:<fav_id>` - Bilibili 收藏夹
- `bilibili:up:<mid>` - Bilibili UP主
- `youtube:channel:<channel_id>` - YouTube 频道
- `zhihu:collection:<collection_id>` - 知乎收藏夹

### /kb-inbox

显示待处理的内容列表。

**用法:**
```
/kb-inbox
/kb-inbox --limit 10
/kb-inbox --status new
```

**输出示例:**
```
📥 收件箱 (5 items)
────────────────────
1. BV1xx411c7mD | Python入门教程 | ⭐ 85 | 📝 一句话摘要...
2. BV2yy522c8nE | React Hooks详解 | ⭐ 92 | 📝 一句话摘要...
```

### /kb-process

处理内容，生成 Obsidian 笔记。

**用法:**
```
/kb-process --all              # 处理所有待处理项
/kb-process BV1xx411c7mD       # 处理指定内容
/kb-process --id BV1xx411c7mD  # 同上
```

**处理流程:**
1. 轻量扫描 → 生成一句话摘要和评分
2. 深度分析 → 生成详细内容（长视频会分段）
3. 选择模板 → 根据类型和时长
4. 生成笔记 → Markdown 格式
5. Git 同步 → 提交到 Obsidian

### /kb-skip

跳过指定内容，不进行处理。

**用法:**
```
/kb-skip BV1xx411c7mD
```

### /kb-status

显示系统状态和统计信息。

**用法:**
```
/kb-status
```

**输出示例:**
```
📊 Obsidian KB 状态
────────────────────
收件箱: 12 待处理 / 45 已完成
Git同步: ✅ 已启用 (最后同步: 5分钟前)
订阅源: 3 个活跃
存储: 128MB / 1GB
```

### /kb-search

搜索已处理的内容。

**用法:**
```
/kb-search python tutorial
/kb-search "machine learning" --tag ai
```

## 配置说明

### 配置文件位置

优先级:
1. `./config.yaml` (当前目录)
2. `~/.obsidian-kb/config.yaml`
3. `~/.config/obsidian-kb/config.yaml`

### 配置项

```yaml
# AI 配置
ai:
  provider: openai          # AI 提供商
  model: gpt-4             # 模型名称
  api_key: sk-...          # API Key (建议使用环境变量)

# 存储配置
storage:
  inbox_dir: inbox         # 收件箱目录
  topics_dir: topics       # 主题目录
  data_dir: data           # 数据目录

# 输出配置
output:
  format: markdown         # 输出格式
  encoding: utf-8          # 文件编码
  include_timestamp: true  # 包含时间戳
  include_source: true     # 包含源链接

# Git 同步配置
git:
  enabled: true            # 启用 Git 同步
  vault_path: ~/ObsidianVault  # Obsidian 知识库路径
  remote: origin           # 远程仓库名
  branch: main             # 分支名
  auto_commit: true        # 自动提交
  commit_message_template: "Update from obsidian-kb: {count} items"

# 分段配置
chunking:
  enabled: true            # 启用长视频分段
  chunk_duration_seconds: 900      # 分段时长 (15分钟)
  max_chunk_duration_seconds: 1800 # 最大分段时长
  long_video_threshold: 1800       # 长视频阈值 (30分钟)

# 数据源配置
sources:
  bilibili:
    enabled: true
    cookie: ''             # Bilibili Cookie (可选)
  youtube:
    enabled: false
    api_key: ''            # YouTube API Key
  zhihu:
    enabled: true
    use_drissionpage: true  # 使用 DrissionPage 绕过检测（推荐）
    cookie_file: ~/.obsidian-kb/zhihu_cookies.json  # Cookie 文件路径
    cookie_str: ""  # 可选：直接在配置中填入 Cookie JSON
    timeout: 30
    headless: true

# Bilibili 提取器配置
bilibili_extraction:
  use_playwright: true     # 使用 Playwright 绕过检测
  headless: true           # 无头模式
  cookie_file: ''          # Cookie 文件路径 (可选)
  enable_subtitle: true    # 启用字幕提取
  subtitle_language: zh-CN # 字幕语言
  enable_danmaku: false    # 启用弹幕提取
  timeout_seconds: 30      # 超时时间
  max_retries: 3           # 最大重试次数

# 硬字幕提取配置 (OCR 方式)
hard_subtitle:
  # 是否启用硬字幕提取功能
  enabled: true

  # OCR 引擎选择
  # 可选值: "paddleocr" (推荐), "tesseract"
  engine: "paddleocr"

  # 字幕区域检测配置
  detection:
    # 默认字幕区域: "bottom" (底部), "full" (全屏), "auto" (自动检测)
    default_region: "bottom"
    # 当默认区域未检测到字幕时，是否自动回退到全屏模式
    fallback_auto: true
    # 是否缓存字幕区域检测结果（提升处理速度）
    cache_region: true

  # OCR 识别配置
  ocr:
    # 置信度阈值: 低于此值的识别结果将被过滤
    confidence_threshold: 0.7
    # 批处理大小: 每次处理的帧数（影响内存使用和速度）
    batch_size: 32
    # 最大并发工作线程数
    max_workers: 4

  # 视频帧提取配置
  video:
    # 抽帧间隔 (秒): 每隔多少秒抽取一帧进行识别
    interval_seconds: 5
    # 最大抽取帧数: 防止处理过长视频导致资源耗尽
    max_frames: 500
    # 流式处理模式: 逐步读取视频帧，避免一次性加载整个视频
    stream_mode: true

  # 后处理配置
  postprocess:
    # 是否启用去重: 去除连续相同的字幕文本
    deduplicate: true
    # 最小文本长度: 少于此长度的识别结果将被视为噪声
    min_length: 2
    # 是否过滤噪声: 使用规则过滤明显错误的识别结果
    filter_noise: true
```

### 环境变量

可以使用环境变量覆盖配置:

```bash
export OPENAI_API_KEY="sk-..."
export AI_MODEL="gpt-4"
export OBSIDIAN_VAULT_PATH="/path/to/vault"
export BILIBILI_COOKIE="..."
export ZHIHU_COOKIE='[{"name":"z_c0","value":"xxx"}]'
```

### Zhihu 提取器配置

知乎提取器使用 DrissionPage + Cookie 方式：

```yaml
sources:
  zhihu:
    enabled: true
    use_drissionpage: true
    cookie_file: ~/.obsidian-kb/zhihu_cookies.json  # Cookie 文件路径
    cookie_str: ""  # 可选：直接在配置中填入 Cookie JSON
    timeout: 30
    headless: true
```

**Cookie 获取方式：**
1. 在有浏览器的机器上登录知乎
2. 打开开发者工具 (F12)
3. 进入 Application → Cookies → https://www.zhihu.com
4. 导出所有 Cookie 为 JSON 文件
5. 上传到服务器指定路径

**Cookie 文件格式：**
```json
[
  {
    "name": "z_c0",
    "value": "xxx",
    "domain": ".zhihu.com",
    "path": "/",
    "expiry": 1234567890,
    "secure": true,
    "httpOnly": false
  }
]
```

**Cookie 加载优先级：**
1. 配置文件中的 `cookie_str`（最高优先级）
2. 环境变量 `ZHIHU_COOKIE`
3. Cookie 文件（最低优先级）

## 提取器说明

### Extractors 目录

`extractors/` 目录包含内容提取器实现：

```
extractors/
├── __init__.py
├── base.py           # 提取器基类
└── bilibili.py       # Bilibili 提取器
```

### BilibiliExtractor 类

BilibiliExtractor 提供了 Bilibili 视频的完整提取功能：

**主要方法:**
- `extract_video(video_url)` - 提取视频信息
- `extract_subtitle(video_url)` - 提取字幕
- `extract_danmaku(video_url)` - 提取弹幕（可选）
- `extract_video_info(video_url)` - 提取视频元信息

**特性:**
- 使用 Playwright 绕过反爬检测
- 支持字幕提取（CC字幕 + AI字幕）
- 支持弹幕提取（可选）
- 自动处理无字幕视频
- 智能重试机制

**无字幕处理逻辑:**

当视频没有字幕时，系统会：

1. **检测字幕可用性** - 尝试多种字幕源（CC字幕、AI字幕）
2. **启用备用方案** - 如果无字幕，使用视频标题和描述作为内容基础
3. **AI 补充分析** - 基于视频元数据生成摘要和要点
4. **标记状态** - 在生成的笔记中标注"无字幕"，说明内容来源于元数据分析

```python
# 示例：检测和处理无字幕视频
if not subtitle_text:
    logger.warning(f"Video {video_url} has no subtitles")
    # 使用视频元数据生成基础内容
    content = {
        "title": video_info["title"],
        "description": video_info["desc"],
        "tags": video_info["tags"],
        "subtitle_available": False
    }
else:
    content["subtitle_available"] = True
    content["subtitle_text"] = subtitle_text
```

### 硬字幕提取功能

当视频没有内置字幕时，硬字幕提取功能可以通过 OCR（光学字符识别）技术从视频画面中识别字幕文本。

**功能介绍：**
- 自动检测和识别视频画面中的字幕文本
- 支持多种 OCR 引擎（PaddleOCR、Tesseract）
- 智能字幕区域检测（底部、全屏、自动）
- 自动去重和噪声过滤
- 支持流式处理，降低内存占用

**使用场景：**
- 视频没有提供 CC 字幕或 AI 字幕
- 字幕嵌入在视频画面中（硬编码字幕）
- 需要提取非标准格式的字幕

**配置说明：**

```yaml
hard_subtitle:
  # 是否启用硬字幕提取功能
  enabled: true

  # OCR 引擎选择
  # 可选值: "paddleocr" (推荐), "tesseract"
  engine: "paddleocr"

  # 字幕区域检测配置
  detection:
    # 默认字幕区域: "bottom" (底部), "full" (全屏), "auto" (自动检测)
    default_region: "bottom"
    # 当默认区域未检测到字幕时，是否自动回退到全屏模式
    fallback_auto: true
    # 是否缓存字幕区域检测结果（提升处理速度）
    cache_region: true

  # OCR 识别配置
  ocr:
    # 置信度阈值: 低于此值的识别结果将被过滤
    confidence_threshold: 0.7
    # 批处理大小: 每次处理的帧数（影响内存使用和速度）
    batch_size: 32
    # 最大并发工作线程数
    max_workers: 4

  # 视频帧提取配置
  video:
    # 抽帧间隔 (秒): 每隔多少秒抽取一帧进行识别
    interval_seconds: 5
    # 最大抽取帧数: 防止处理过长视频导致资源耗尽
    max_frames: 500
    # 流式处理模式: 逐步读取视频帧，避免一次性加载整个视频
    stream_mode: true

  # 后处理配置
  postprocess:
    # 是否启用去重: 去除连续相同的字幕文本
    deduplicate: true
    # 最小文本长度: 少于此长度的识别结果将被视为噪声
    min_length: 2
    # 是否过滤噪声: 使用规则过滤明显错误的识别结果
    filter_noise: true
```

**使用示例：**

```python
from obsidian_kb.extractors.bilibili import BilibiliExtractor

# 创建提取器实例（自动启用硬字幕提取）
extractor = BilibiliExtractor(
    use_playwright=True,
    headless=True
)

# 当视频没有内置字幕时，会自动尝试硬字幕提取
subtitle = extractor.extract_subtitle("https://www.bilibili.com/video/BV1xx411c7mD")

print(f"识别到的字幕: {subtitle}")
```

**注意事项：**

1. **性能考虑**：硬字幕提取需要较高的计算资源，建议在配置合理的机器上运行
2. **识别准确度**：OCR 识别准确度受字幕字体、颜色、背景等因素影响，可能存在误差
3. **处理时间**：硬字幕提取比软字幕提取慢，对于长视频需要较长时间处理
4. **依赖安装**：使用前需要安装 OCR 引擎依赖：
   - PaddleOCR: `pip install paddleocr paddlepaddle`
   - Tesseract: 需要安装 Tesseract OCR 引擎和语言包
5. **网络视频**：流式处理需要稳定的网络连接
6. **字幕格式**：不同视频的字幕样式差异较大，可能需要调整配置参数以获得最佳效果

**最佳实践：**
- 对于短视频（<30分钟），可以减小 `interval_seconds` 以提高识别精度
- 对于长视频，增加 `interval_seconds` 和减少 `max_frames` 以平衡速度和质量
- 如果字幕位置固定在底部，使用 `default_region: "bottom"` 可以提升速度
- 首次使用建议先测试一段视频，根据结果调整配置参数

### ZhihuDrissionExtractor 类

知乎 DrissionPage 提取器提供知乎内容的完整提取功能：

**主要方法:**
- `extract(url)` - 提取知乎内容（支持回答、文章、问题）
- `identify_url_type(url)` - 识别 URL 类型
- `extract_id(url)` - 提取内容 ID
- `_load_cookies()` - 加载 Cookie（支持配置/环境/文件）
- `_apply_cookies(cookies)` - 应用 Cookie 到浏览器

**特性:**
- 使用 DrissionPage 绕过知乎反爬虫保护
- 支持完整 Markdown 格式（代码块、表格、引用等）
- 提取元数据：标题、作者、发布时间、点赞数
- Cookie 加载优先级：配置 > 环境变量 > 文件
- 支持无头模式，适合服务器环境

```python
from obsidian_kb.extractors.zhihu import ZhihuDrissionExtractor

extractor = ZhihuDrissionExtractor()
data = extractor.extract("https://www.zhihu.com/question/266309957/answer/2003427891925509507")

print(f"Title: {data['title']}")
print(f"Author: {data['author']}")
print(f"Content (Markdown): {data['content_markdown']}")
```

**返回数据结构:**
```python
{
    'type': 'answer' | 'article' | 'question',
    'title': str,
    'author': str,
    'content': str,              # HTML 格式
    'content_markdown': str,      # Markdown 格式
    'publish_time': str,
    'vote_up': int,
    'url': str,
    'content_id': str
}
```

### 使用提取器

**直接使用提取器:**

```python
from obsidian_kb.extractors.bilibili import BilibiliExtractor

# 创建提取器实例
extractor = BilibiliExtractor(
    use_playwright=True,
    headless=True
)

# 提取视频信息
video_info = extractor.extract_video("https://www.bilibili.com/video/BV1xx411c7mD")

# 提取字幕
subtitle = extractor.extract_subtitle("https://www.bilibili.com/video/BV1xx411c7mD")

print(f"Title: {video_info['title']}")
print(f"Subtitle length: {len(subscription)} characters")
```

**通过管道使用:**

```bash
# 提取器会自动被管道调用
/kb-process BV1xx411c7mD
```

## 模板变量

### 通用变量

所有模板可用:
- `{{ title }}` - 标题
- `{{ source }}` - 来源 (bilibili/youtube/zhihu)
- `{{ url }}` - 原始 URL
- `{{ author }}` - 作者/UP主
- `{{ duration }}` - 时长
- `{{ date }}` - 日期
- `{{ tags }}` - 标签列表
- `{{ one_liner }}` - 一句话摘要
- `{{ summary }}` - 详细摘要
- `{{ key_points }}` - 核心要点列表
- `{{ quality_score }}` - 质量评分

### 教程视频额外变量

仅 `tutorial_video.md` 可用:
- `{{ prerequisites }}` - 前置知识列表
- `{{ outline }}` - 分段大纲列表
  - `{{ section.title }}` - 分段标题
  - `{{ section.time_range }}` - 时间段
  - `{{ section.summary }}` - 分段摘要
  - `{{ section.code_snippet }}` - 代码片段
  - `{{ section.code_language }}` - 代码语言
- `{{ pitfalls }}` - 常见坑点列表
- `{{ practice_advice }}` - 实践建议列表

## 输出格式

### 轻量视频输出

```markdown
---
title: "视频标题"
source: "bilibili"
url: "https://..."
author: "UP主"
duration: "10:30"
date: "2024-01-01T00:00:00"
tags:
  - python
  - tutorial
---

#python #tutorial

**一句话摘要**: 这是一句摘要

## 摘要
详细摘要内容...

## 核心要点
1. 要点一
2. 要点二
```

### 教程视频输出

```markdown
---
title: "Python 完整教程"
source: "bilibili"
url: "https://..."
up主: "CodeMaster"
duration: "2:30:00"
quality_score: 95
---

## 🎯 一句话总结
...

## 📚 前置知识
- 基础编程概念
- Python 环境搭建

## 📝 步骤详解
### 环境配置 [00:00-15:00]
如何配置 Python 开发环境

```bash
pip install python
```

### 基础语法 [15:00-45:00]
...

## 💡 关键要点
1. 要点一
2. 要点二

## ⚠️ 常见坑点
- Python 2 与 3 的区别
- 缩进问题

## 🤔 实践建议
- 跟随视频动手编码
- 完成课后练习
```

## 故障排除

### 无法获取字幕

1. 检查 Bilibili Cookie 是否正确设置
2. 确认视频有字幕/CC字幕
3. 检查网络连接

### Git 同步失败

1. 确认 vault_path 指向正确的 Git 仓库
2. 检查 Git 配置和权限
3. 查看 Git 日志: `git status` 在 vault 目录

### AI 分析失败

1. 检查 API Key 是否有效
2. 确认有可用额度
3. 查看详细错误日志

## 更新日志

### v1.0.0
- 初始版本发布
- 支持 Bilibili、YouTube、知乎
- 长视频分段分析
- Git 自动同步