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. 安装依赖

# 安装技能包
clawhub install bilibili-transcriber-pro

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

2. 扫码登录（推荐）

# 扫码登录（会自动保存到冗余存储）
bilibili-transcribe --login

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

3. 基本使用

# 处理单个视频（自动验证Cookie，含评论获取）
bilibili-transcribe BV1txQGByERW

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

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

4. 输出特点：评论获取

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

📖 详细用法

Cookie 管理（新增）

# 扫码登录（推荐方式）
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 管理）

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

# 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)

{
  "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)

# 视频标题

**视频信息**
- 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 的集成

# 在任何脚本中都可以使用
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 已失效"

# 重新扫码登录
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 存储状态

bilibili-transcribe --check-cookie

📝 飞书文档创建经验

⚠️ lark-cli 1.0.18 已知问题

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

解决方法：使用 pipe 方式传入 Markdown 内容：

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）

📦 文档存储结构

文档结构模板：
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秒分块处理，避免一次性加载 |

推荐流程（无字幕时）

# 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. ✅ 飞书自定义域名适配：返回知识库内正确域名链接