Bilibili Video Transcriber

SKILL.md

---
name: bilibili-video-transcriber
description: 【B站字幕获取】专业处理 B 站视频字幕问题，支持语音转文字、字幕下载、内容分析。基于实际 B 站字幕系统错误问题开发，提供完整的解决方案。
metadata:
  clawdbot:
    emoji: "🎬"
    requires:
      anyBins:
        - python3
        - ffmpeg
    os:
      - linux
      - darwin
      - win32
---

# 🎬 B 站视频转录专家

**专业处理 B 站视频字幕问题，支持语音转文字、字幕下载、内容分析**

## 📋 功能特性

### ✅ 核心功能
1. **智能字幕优先**：自动按优先级获取（CC 字幕 → AI 字幕 → 音频转录 → 视频下载）
2. **Cookie 安全存储**：多路径冗余存储 + immutable 写保护，防止误删
3. **自动失效检测**：每次处理视频前自动验证 Cookie 有效性
4. **飞书扫码通知**：Cookie 失效时自动生成二维码并通过飞书发送
5. **语音转文字**：使用 Whisper/Vosk 模型进行高精度语音识别（自动检测系统配置，按需下载）
6. **国内镜像支持**：自动使用国内镜像源
7. **批量处理**：支持批量处理多个 B 站视频
8. **大会员支持**：支持扫码登录获取大会员权限
9. **faster-whisper 按需安装**：安装时自动检测系统配置，不满足条件则跳过 faster-whisper，使用 Vosk 替代

### 🔧 Cookie 安全机制
```
存储路径（3重冗余）:
  1. 技能目录: ~/.openclaw/workspace/skills/.../.bilibili_cookie  ← immutable 保护
  2. 用户目录: ~/.bilibili_cookie_storage
  3. 配置目录: ~/.config/bilibili_transcriber/cookie
  
运行引用: ~/.bilibili_cookie.txt（自动同步，600权限）

失效时: → 自动检测 → 生成二维码 → 通过飞书发送 → 用户扫码 → 自动保存
```

## 🚀 快速开始

### 1. 安装依赖
```bash
# 安装技能包
clawhub install bilibili-transcriber-pro

# 或手动安装依赖
pip install bilibili-api requests pydub faster-whisper vosk qrcode
```

### 2. 扫码登录（推荐）
```bash
# 扫码登录（会自动保存到冗余存储）
bilibili-transcribe --login

# 检查登录状态
bilibili-transcribe --check-cookie
```

### 3. 基本使用
```bash
# 处理单个视频（自动验证Cookie，含评论获取）
bilibili-transcribe BV1txQGByERW

# 指定Cookie文件
bilibili-transcribe BV1txQGByERW --cookie ~/.bilibili_cookie.txt

# 批量处理
bilibili-transcribe --batch bv_list.txt
```

### 4. 输出特点：评论获取
```bash
# 处理视频时会自动获取热门评论（按点赞排序），包含：
# - 热评内容 + 点赞数
# - 热评下的回复
# - 评论写入 markdown 的 💬 评论区部分
# - CLI 直接展示前3条热评预览
```

## 📖 详细用法

### Cookie 管理（新增）
```bash
# 扫码登录（推荐方式）
bilibili-transcribe --login

# 检查Cookie状态
bilibili-transcribe --check-cookie
# 输出示例：
#   ✅ Cookie 有效
#   👤 用户: 你的B站用户名
#   🏆 大会员: ✅
#   📂 存储路径: ~/.bilibili_cookie.txt

# 手动更新Cookie
bilibili-transcribe --update-cookie "SESSDATA=xxx; bili_jct=xxx"

# 设置环境变量
export BILIBILI_COOKIE="SESSDATA=xxx; bili_jct=xxx"
```

### Python API（Cookie 管理）
```python
from cookie_manager import (
    save_cookie, load_cookie, check_cookie_valid,
    needs_cookie_refresh, BilibiliQRLogin, send_qr_via_feishu
)

# 检查Cookie是否需要刷新
reason = needs_cookie_refresh()
if reason:
    print(f"⚠️ Cookie 需要刷新: {reason}")
    login = BilibiliQRLogin()
    qr_path = login.generate_qr_code()
    
    # 通过飞书发送二维码
    send_qr_via_feishu(qr_path)
    
    # 轮询等待扫码
    result = login.poll_login()
    if result['success']:
        print(f"✅ 登录成功: {result['username']}")
else:
    print("✅ Cookie 有效")
```

## 🛠️ 配置选项

### 配置文件 `~/.config/bilibili_transcriber/config.yaml`
```yaml
# Cookie 配置（增强版）
cookie:
  file: "~/.bilibili_cookie.txt"
  auto_refresh: true
  refresh_interval: 86400  # 24 小时
  redundant_storage: true   # 启用冗余存储
  storage_paths:
    - "~/.openclaw/workspace/skills/bilibili-video-transcriber/.bilibili_cookie"
    - "~/.bilibili_cookie_storage"
    - "~/.config/bilibili_transcriber/cookie"
  notify_on_expire: true    # Cookie失效时通知
  notify_channel: "feishu"  # 通知通道

# 模型配置
model:
  engine: "whisper"
  name: "base"
  device: "cpu"
  compute_type: "int8"
  language: "zh"

# 飞书通知配置
notify:
  channel: "feishu"  # 通知通道
  qr_temp_dir: "/tmp"
```

## 📊 输出格式

### 0. 评论获取（新增）
处理视频时自动按**点赞排序**获取热门评论，最多 30 条热评 + 每条热评 3 条回复。
- 数据保存在 markdown 的 `💬 热门评论` 部分
- JSON 格式包含 `comments` 数组
- CLI 输出展示前 3 条热评预览

### 1. 文本格式 (`transcript.txt`)
```
[0.00s -> 3.90s] 兄弟们 HermesAgent 刚刚发布了更新 4.13
[3.90s -> 5.76s] 那么这一次最大的一个升级呢
[5.76s -> 9.00s] 是它带来了本地的外部控制面板
...
```

### 2. JSON 格式 (`transcript.json`)
```json
{
  "video_info": {
    "bvid": "BV1txQGByERW",
    "title": "视频标题",
    "duration": 210,
    "up": "UP主名"
  },
  "transcript": [
    {"start": 0.0, "end": 3.9, "text": "内容", "confidence": 0.95}
  ],
  "cookie_status": {
    "valid": true,
    "user": "用户名",
    "is_vip": true
  }
}
```

### 3. Markdown 格式 (`summary.md`)
```markdown
# 视频标题

**视频信息**
- BV 号：BV1xxx
- 时长：210 秒
- UP 主：xxx
- Cookie 状态：✅ 有效 (用户: xxx)

**核心内容**
1. 要点一
2. 要点二

**完整转录**
[0.00s -> 3.90s] 内容
...
```

## 🔧 Cookie 管理详解

### 冗余存储机制
```
cookie_manager.py 负责管理 Cookie 的存储和生命周期：

┌─────────────────────────────────────────────────┐
│                  cookie_manager                   │
├─────────────────────────────────────────────────┤
│  1. save_cookie(cookie_str)                      │
│     → 写入活跃文件 (~/.bilibili_cookie.txt)      │
│     → 同步到3个冗余路径（含 immutable 保护）     │
│     → 设置 600 权限                              │
├─────────────────────────────────────────────────┤
│  2. load_cookie()                                │
│     → 依次查找所有存储路径                        │
│     → 如果从备份读到，自动补全到活跃路径          │
│     → 也检查环境变量 BILIBILI_COOKIE             │
├─────────────────────────────────────────────────┤
│  3. check_cookie_valid(cookie_str)               │
│     → 调用 bilibili_api 验证有效期               │
│     → 返回 {valid, username, is_vip, error}      │
├─────────────────────────────────────────────────┤
│  4. needs_cookie_refresh()                       │
│     → 快速检查是否需要刷新                        │
│     → 返回 None=有效, str=失效原因               │
├─────────────────────────────────────────────────┤
│  5. BilibiliQRLogin                              │
│     → generate_qr_code() → 生成二维码图片        │
│     → poll_login() → 轮询扫码结果               │
│     → poll_once() → 单次检查（供外部调用）       │
├─────────────────────────────────────────────────┤
│  6. send_qr_via_feishu(image_path)               │
│     → 写入信号文件（供代理处理器读取并发送）     │
└─────────────────────────────────────────────────┘
```

### 飞书扫码登录流程
```
1. 用户发送 B 站链接 or 调用 --login
2. cookie_manager 检测到 Cookie 不存在/失效
3. BilibiliQRLogin 生成二维码图片
4. send_qr_via_feishu 写入信号文件
5. [代理处理器] 读取信号 → 上传飞书图片 → 发送给用户
6. 用户扫码 → poll_login 轮询到成功
7. save_cookie 保存到冗余存储
8. 继续处理视频
```

### 安全特性
- **权限 600**：仅文件所有者可读写
- **chattr +i**：对技能目录内的 Cookie 设置 immutable 标记，不可删除/修改
- **多路径冗余**：3个独立存储位置，任一被删都能从其他路径恢复
- **自动恢复**：load_cookie 发现活跃文件被删时，自动从备份恢复

## 🔗 与其他技能的集成

### 与 cookie_manager 的集成
```python
# 在任何脚本中都可以使用
from cookie_manager import (
    save_cookie, load_cookie, check_cookie_valid,
    needs_cookie_refresh
)

# 获取当前 Cookie（自动加载、自动恢复）
cookie_str = load_cookie()
if cookie_str:
    status = check_cookie_valid(cookie_str)
    print(f"用户: {status['username']}, 有效: {status['valid']}")
```

## 🔍 故障排除

### Cookie 相关问题

#### 1. 提示 "Cookie 已失效"
```bash
# 重新扫码登录
bilibili-transcribe --login

# 或手动更新
bilibili-transcribe --update-cookie "SESSDATA=xxx; bili_jct=xxx"
```

#### 2. Cookie 文件被误删
```
不用担心，cookie_manager 会自动从备份路径恢复。
备份位置：
  ~/.openclaw/workspace/skills/bilibili-video-transcriber/.bilibili_cookie
  ~/.bilibili_cookie_storage
  ~/.config/bilibili_transcriber/cookie

技能目录内的备份设置了 immutable 保护，不可删除。
```

#### 3. 检查 Cookie 存储状态
```bash
bilibili-transcribe --check-cookie
```

## 📝 飞书文档创建经验

### ⚠️ lark-cli 1.0.18 已知问题

**问题**：`lark-cli docs +create --markdown ./file.md` 会错误地将**文件名本身**写入内容，而非文件内容。

**解决方法**：使用 pipe 方式传入 Markdown 内容：
```bash
cat content.md | lark-cli docs +create \
  --title "[视频总结] UP主名 - 标题 - 日期" \
  --markdown - \
  --wiki-space "知识空间ID"
```

### 📍 飞书自定义域名

飞书返回的 `doc_url` 为 `https://www.feishu.cn/wiki/...`，但企业可能使用自定义域名（如 `https://企业名.feishu.cn/wiki/...`）。

直接点返回的 `doc_url` 可能跳转失败，需要**在知识库内找到实际链接**，用企业自定义域名格式发送给用户。

### 📑 Markdown 格式注意

1. **表格**：必须使用 `<lark-table>` 标签格式，标准 Markdown 表格（`| ... |`）在飞书中可能不渲染
2. **高亮块**：使用 `<callout emoji="🎬" background-color="light-blue">...</callout>` 标签
3. **分栏**：使用 `<grid cols="2"><column>...</column></grid>` 标签
4. **一级标题**：文档标题通过 `--title` 参数设置，Markdown 内容中**不要**包含相同的一级标题（`#`）
5. **emoji 参数**：在 `<callout>` 标签的 `emoji` 属性中使用实际 emoji 字符（如 `🎬`），而非名称（如 `clapper`）

### 📦 文档存储结构
```markdown
文档结构模板：
1. <callout> 高亮块 — 说明文字
2. ## 📋 视频信息 — lark-table 行列式表格
3. ## 📝 结构化内容总结 — 分段详解（源自字幕/转写）
4. ## 🔑 核心要点 — 提炼的干货要点
5. ## 💬 热门评论 — 评论区精选
6. ## 🔗 字幕文件 — 原始文件说明
```

### 🔐 认证说明

- 使用 `lark-cli` 前需先完成 `lark-cli auth login`
- 认证后凭体验证 `lark-cli docs +create` 可用
- 文档创建到知识空间需指定 `--wiki-space` 参数

## 💻 低资源服务器转写策略

### ⚠️ faster-whisper 按需安装机制

**安装时自动检测系统配置**（setup.py 中 `check_system_capability` 函数）：
- 有 GPU → 安装 faster-whisper（GPU 模式）
- ≥4GB 内存（无 GPU）→ 安装 faster-whisper（CPU 模式）
- <4GB 内存（无 GPU）→ **跳过** faster-whisper 安装，使用 Vosk 离线引擎

**运行时自动路由**（bilibili_transcriber.py 中 `_detect_system_resources` 函数）：
- 自动检测 faster-whisper 是否已安装
- 已安装 + 有 GPU → Whisper medium + cuda
- 已安装 + ≥8GB 内存 → Whisper base + cpu
- 已安装 + ≥2GB 内存 → Whisper tiny + cpu
- 未安装或内存 <2GB → Vosk 离线引擎（分块处理）

### 硬件环境参考
- **CPU**：2核
- **内存**：1.6GB（可用常 < 500MB）
- **模型**：VOsk small-cn-0.22（66MB）

### 策略对比

| 方案 | 结果 | 说明 |
|------|------|------|
| Whisper tiny/base | ❌ OOM | 即使 tiny 也会被杀 |
| faster-whisper base | ❌ 被 kill | 39分钟后被 OOM kill |
| Vosk small (66MB) | ✅ 可行 | 16分钟视频214秒转写完成 |
| Vosk + chunk | ✅ 稳定 | 6×180秒分块处理，避免一次性加载 |

### 推荐流程（无字幕时）

```bash
# 1. 下载音频（优先 dash audio）
# 2. ffmpeg 转 WAV（16kHz, mono, 16bit）
# 3. 分块处理（每块 ≤3 分钟）
# 4. Vosk 逐块识别 → 拼接
```

### 输出目录命名
```
bilibili_transcripts/{UP主名称}_{视频标题}/  # 取代 BV号 格式
├── transcript.json   # 含转写+评论的完整数据
├── transcript.txt    # 纯文本
├── summary.md        # 结构化总结
├── summary_full.md   # 详细总结（含评论）
└── comments.json     # 评论数据
```

## 📄 许可证

MIT License

---

**最后更新：** 2026-05-17

**本次更新内容：**
1. ✅ 新增 `get_comments()` 方法：自动获取视频热门评论（按热度排序）
2. ✅ `ProcessingResult` 新增 `comments` 字段
3. ✅ `save_transcript()` markdown 格式新增 `💬 热门评论` 区块
4. ✅ `print_result()` CLI 输出展示前 3 条热评
5. ✅ 评论获取非关键步骤，失败不影响主流程
6. ✅ 支持热评下的回复获取
7. ✅ 飞书文档创建经验：`lark-cli 1.0.18 --markdown` bug 及 workaround
8. ✅ Vosk 分块转写策略：chunk 180s × 6，适用于 2GB 内存服务器
9. ✅ 输出目录命名：采用 `{up_name}_{video_title}` 而非 BV 号
10. ✅ 飞书自定义域名适配：返回知识库内正确域名链接