Video Summarizer

概览

此技能通过运行 python -m summarizer CLI 工具来转录和总结视频内容。它支持 YouTube（字幕或音频）、本地文件、Google Drive 和 Dropbox。转录文本会分块处理，通过兼容 OpenAI 的大模型并行处理，最后合并为摘要。

重要：始终使用下面的 CLI 命令。切勿尝试直接获取、抓取或下载视频 URL（例如使用 webfetch 或 curl）。所有下载、转录和总结工作都由 CLI 在内部处理。

快速开始（分步说明）

请严格按照以下步骤操作：

步骤 1 -- 运行 CLI：

python -m summarizer --source "VIDEO_URL"

该工具使用 summarizer.yaml 中的默认提供方（已配置）。基本用法无需额外标志。

步骤 2 -- 读取输出文件：

CLI 成功运行后会打印输出文件名。文件始终保存在相对于项目工作目录的 summaries/ 子目录中。例如：

[+] Saved watch_20260207_234533.md

要读取的完整路径为：summaries/watch_20260207_234533.md

步骤 3 -- 向用户展示结果。

就这样，共三个步骤。

文件位置

所有路径均相对于项目工作目录（即包含 summarizer.yaml 和 setup.py 的目录）。

文件	位置
配置	./summarizer.yaml
API 密钥	./.env
提示词模板	./summarizer/prompts.json
输出摘要	./summaries/<filename>.md
CLI 入口点	python -m summarizer

请勿在主目录或技能目录中查找 .env 或配置文件。它们位于项目根目录中。

CLI 参考

python -m summarizer [OPTIONS]

必填项

标志	说明
--source	一个或多个视频 URL 或文件路径

提供方选项

标志	说明	默认值
--provider	summarizer.yaml 中命名的提供方	YAML 中的 default_provider
--base-url	API 端点 URL（覆盖提供方）	来自 YAML
--model	模型标识符（覆盖提供方）	来自 YAML
--api-key	API 密钥（覆盖 .env 自动匹配）	自动从 .env 获取

来源选项

标志	说明	默认值
--type	YouTube Video、Video URL、Local File、Google Drive Video Link、Dropbox Video Link	YouTube Video
--force-download	跳过 YouTube 字幕，改为下载音频	False
--transcription	Cloud Whisper（Groq API）或 Local Whisper	Cloud Whisper
--whisper-model	tiny、base、small、medium、large	tiny
--language	auto 会选择第一个可用的 YouTube 字幕轨道，并让 Whisper 检测语言；显式指定的代码将严格按指定值处理	auto

处理选项

标志	说明	默认值
--prompt-type	摘要风格（参见下方的风格）	来自 YAML 默认值
--chunk-size	每个文本块的字符数	来自 YAML 默认值
--parallel-calls	并发 API 请求数	30
--max-tokens	每个文本块的最大输出 token 数	4096

输出选项

标志	说明	默认值
--output-dir	保存摘要的目录	summaries
--output-format	markdown、json 或 html	markdown
--no-save	仅打印到标准输出，不保存文件	False
--verbose、-v	输出详细进度信息	False

警告： 请勿在 Windows 上使用 --no-save。由于一个已知的编码错误，摘要中的 Unicode 字符会导致标准输出崩溃。请始终让工具将内容保存到文件，然后读取该文件。

配置选项

标志	说明
--config	配置文件路径（默认：自动检测）
--no-config	忽略配置文件，仅使用 CLI 参数
--init-config	生成示例 summarizer.yaml 并退出

摘要风格

使用 --prompt-type 指定。定义于 summarizer/prompts.json。

风格	用途
Questions and answers	从内容中提取问答
Summarization	标准摘要，含标题
Distill Wisdom	提取观点、引言和参考资料
DNA Extractor	将核心真相提炼至最多 200 个单词
Fact Checker	使用 TRUE/FALSE/MISLEADING 标签验证主张
Tutorial	根据内容生成分步说明
Research	结合更广泛的背景进行深入分析
Reflections	拓展内容之外的哲学思考
Mermaid Diagram	使用 Mermaid.js 语法绘制概念图
Essay Writing in Paul Graham Style	以 Paul Graham 的风格撰写 250 个单词的文章
Only grammar correction with highlights	修正文法并用粗体标出修改处

示例

总结 YouTube 视频（最简单的形式）

python -m summarizer --source "https://youtube.com/watch?v=VIDEO_ID"
# Output: summaries/watch_YYYYMMDD_HHMMSS.md

指定提供方

python -m summarizer --source "https://youtube.com/watch?v=VIDEO_ID" --provider gemini
# Output: summaries/watch_YYYYMMDD_HHMMSS.md

使用 Distill Wisdom 提取关键见解

python -m summarizer \
  --source "https://youtube.com/watch?v=VIDEO_ID" \
  --provider openrouter \
  --prompt-type "Distill Wisdom"
# Output: summaries/watch_YYYYMMDD_HHMMSS.md

使用 Perplexity 核查视频中的主张

python -m summarizer \
  --source "https://youtube.com/watch?v=VIDEO_ID" \
  --base-url "https://api.perplexity.ai" \
  --model "sonar-pro" \
  --prompt-type "Fact Checker"
# Output: summaries/watch_YYYYMMDD_HHMMSS.md

根据讲座生成 Mermaid 图表

python -m summarizer \
  --source "https://youtube.com/watch?v=VIDEO_ID" \
  --provider gemini \
  --prompt-type "Mermaid Diagram"
# Output: summaries/watch_YYYYMMDD_HHMMSS.md

总结本地文件

python -m summarizer \
  --type "Local File" \
  --source "./lecture.mp4" \
  --provider groq
# Output: summaries/lecture_YYYYMMDD_HHMMSS.md

批量处理多个视频

python -m summarizer \
  --source "URL1" "URL2" "URL3" \
  --provider gemini \
  --prompt-type "Summarization"
# Output: one file per URL in summaries/

不使用配置文件（显式指定所有标志）

python -m summarizer \
  --source "https://youtube.com/watch?v=VIDEO_ID" \
  --base-url "https://openrouter.ai/api/v1" \
  --model "google/gemini-2.0-flash-exp:free" \
  --api-key "sk-or-v1-YOUR_KEY" \
  --prompt-type "Tutorial" \
  --no-config
# Output: summaries/watch_YYYYMMDD_HHMMSS.md

阅读输出

运行 CLI 后，务必读取 summaries/ 中的输出文件：

# The CLI prints something like:
# [+] Saved watch_20260207_234533.md
#
# The file is at:
summaries/watch_20260207_234533.md

使用 Read 工具读取完整路径：summaries/<filename>（相对于项目根目录）。

多步骤工作流

如需进行全面分析，可针对同一视频串联多种风格：

1. 先使用 Summarization 快速了解概要
2. 使用 Distill Wisdom 提取关键见解
3. 运行 Fact Checker（最好搭配 Perplexity）核查主张
4. 生成 Mermaid Diagram 作为可视化参考

错误处理

• 如果未找到 API 密钥，工具会检查 .env 中是否有与提供方 URL 关键词匹配的密钥
• 如果无法获取 YouTube 字幕，工具会改为下载音频并使用 Whisper 转录
• --language auto 不会强制使用英语。它会使用 YouTube 上第一个可用的字幕轨道，并由 Whisper 检测语言。
• 使用 --verbose 查看详细进度并排查问题
• 云端 Whisper 需要 Groq API 密钥（提供免费套餐）

配置文件

所有文件均位于项目工作目录中：

• summarizer.yaml：提供方定义（base_url、model、chunk-size）和默认值
• .env：API 密钥，根据 URL 关键词自动匹配（例如，generativelanguage = YOUR_KEY）
• summarizer/prompts.json：提示词模板，使用 {text} 作为转录文本占位符

测试

python -m pytest tests/ -v