video summary

参考 BibiGPT-v1 的视频总结管线：URL 解析 → 字幕/转写获取 → 结构化总结。 两步完成：① 用本 skill 的脚本抓字幕（输出统一 JSON）；② 由你自己（agent 的 LLM 能力）按模板生成四段式总结。

Before running any command

1. yt-dlp（YouTube 必需；B 站主路径零依赖，可不需要）

脚本会自动探测：优先 PATH 中的 yt-dlp，否则用 uvx yt-dlp 零安装运行。若两者都不可用且你需要处理 YouTube：

brew install yt-dlp        # 或 pipx install yt-dlp；有 uv 时：uv tool install yt-dlp

2. BILIBILI_SESSDATA（B 站字幕必需）

实测（2026-08）：B 站字幕（CC 与 AI 字幕）自 2023 年起需要登录态，无 cookie 时字幕接口恒返回空列表（元数据与弹幕不受影响）。所以总结 B 站视频前先确认登录态：

# 获取：浏览器登录 bilibili.com → DevTools → Application → Cookies → 复制 SESSDATA 值
export BILIBILI_SESSDATA="粘贴你的SESSDATA"

无 SESSDATA 时脚本不会自动降级：B 站视频若因此拿不到字幕，脚本返回 source=login-required（exit 5）+ login_guide——此时你必须先停下向用户说明并引导登录（见下方「登录引导流程」），仅在用户明确表示无法登录或同意降级后，才加 --allow-desc-fallback 降级为「标题+简介」粗略总结，并在输出中声明该结论基于简介而非字幕。

When to use

• 用户给出视频链接（bilibili.com / b23.tv / youtube.com / youtu.be）并要求总结、提炼要点、做笔记
• 用户要求获取视频字幕/转写文本
• 长视频快速了解内容（先给 TL;DR 再决定是否细看）

Workflow

Step 1：抓取字幕/转写

# <skill_dir> = 本 SKILL.md 所在目录（如 ~/.agents/skills/video-summary 或 ~/.claude/skills/video-summary）
python3 "<skill_dir>/scripts/fetch_transcript.py" "<视频URL>"

脚本输出统一 JSON：

降级链（BibiGPT 同款）：CC 字幕 → AI 字幕 → auto-subs → desc+dynamic 简介兜底。 source=desc-fallback 时 transcript 为空数组——只能基于标题与简介总结，并明确声明。 B 站无登录态拿不到字幕时会先停在 login-required（exit 5），走下面的登录引导流程。

Step 1.5：source=login-required（exit 5）→ 先引导用户登录

不要直接降级。 此时先向用户说明并给出选择：

该视频需要 B 站登录态才能抓取字幕（B 站 2023 年起限制）。请选择：

1. 提供登录态后我重试（可生成基于完整字幕的高质量总结）：浏览器登录 bilibili.com → F12 DevTools → Application → Cookies 复制 SESSDATA，然后 export BILIBILI_SESSDATA="<值>"；或告诉我你用的浏览器，我直接设 BILIBILI_COOKIES_FROM_BROWSER=chrome|edge 读取登录态
2. 无法登录 / 不想登录：我基于标题+简介生成粗略总结（信息量有限，无时间线与金句）

• 用户配置好登录态后，重跑 Step 1 同一条命令；
• 用户明确选择降级后，加 --allow-desc-fallback 重跑，此时才会产出 desc-fallback 结果。

常用变体：

# B 站多 P 视频
python3 .../fetch_transcript.py "https://www.bilibili.com/video/BVxxx?p=3"
# b23.tv 短链（脚本自动跟随 302）
python3 .../fetch_transcript.py "https://b23.tv/xxxxxxx"
# 保存到文件；--max-bytes 0 关闭 6200 字节随机减半压缩
python3 .../fetch_transcript.py "<URL>" --out /tmp/vt.json --max-bytes 0
# B 站强制走 yt-dlp（默认 auto：纯 API 优先、yt-dlp 兜底）
python3 .../fetch_transcript.py "<URL>" --engine ytdlp

Step 2：生成 BibiGPT 风格结构化总结（由你完成）

把 title + transcript（格式化为 - {s} - {text} 行）作为输入，按下面模板输出中文（用户用英文提问则输出英文）：

## TL;DR
（一句话，≤50 字，概括整支视频）

## 核心要点
- 83 - 要点文字（每条至少 15 词，时间戳取自 transcript 的真实秒数）
- ...

## 章节时间线
- 0 - 开场：一句话说明
- 126 - 章节名：一句话说明
- ...

## 金句
> "原文金句"（83）
> ...

语言准确性：生成总结前读取 references/language-precision.md（STE 准确性规则 + humanizer 去 AI 味，默认 80% 模式）。本 skill 的具体要求：

• 每条要点只含一个论断，写“谁说了什么”，不把说话人的观点写成事实（用“视频中称……”“演讲者认为……”）。
• 术语、人名、产品名沿用字幕原文写法；不确定的转写错误保留原样并标注“字幕原文”，不自行改成猜测的词。
• 数字、单位、年份只取自字幕，不自行换算或补全。
• 核心要点和章节说明用具体动词，不写“深入探讨”“全面解析”“干货满满”等宣传语和空泛铺垫。
• “金句”和所有引用保持原文逐字，不润色。
• 基于简介的降级总结使用固定声明句式（见下），不加缓冲语。

时间戳防幻觉规则（强制）：

• 所有秒数必须来自 transcript 中真实存在的 s 值，禁止编造；
• 展示时格式化为 m:ss（超过 1 小时用 h:mm:ss）；
• 章节时间线：若字幕无明确章节边界，按内容节奏切 3-8 段，时间戳仍必须对齐真实 s；
• 金句必须是原文引用（可修正错别字），后附真实秒数。

时间戳深链（可直接拼在输出里方便用户跳转）：

• B 站：https://www.bilibili.com/video/{BV号}/?t={整数秒}
• YouTube：https://www.youtube.com/watch?v={id}&t={整数秒}

source=desc-fallback 时的输出要求

在总结最前面加一行声明，例如：

⚠️ 该视频未获取到字幕，以下总结基于视频标题与 UP 主简介生成（B 站字幕需登录态）。配置 BILIBILI_SESSDATA 后可获得基于完整字幕的总结。

Options

Troubleshooting

See also

• references/prompt-templates.md — BibiGPT 原版 prompt 模板（Summary/Highlights 两段式、带时间戳版、system prompt）与本 skill 四段式的对应关系
• references/advanced-transcription.md — 无字幕视频的本地 ASR 转写进阶方案（whisper 系）与 danmaku 辅助参考