Video Content Summary：从视频链接到证据化内容报告

很多视频总结工具的问题，不是总结得不够短，而是总结得太像一句“看过了”的结论。

长视频真正有价值的部分往往藏在细节里：某个论点第一次出现的位置，一段演示对应的画面，一个概念被反复强调的上下文，或者字幕里没有说清但画面已经给出答案的证据。单纯把视频压缩成几段文字，会很快丢掉这些线索。

Video Content Summary 想解决的不是“把视频变短”，而是“把视频变成可以复查、可以引用、可以继续加工的材料”。

它的输入很克制：一个视频 URL。

它的输出则尽量完整：Markdown 报告、JSON 报告、manifest、关键帧、时间线和处理中间产物。这个项目的核心不是某一次模型调用，而是一条可重复、可检查、可扩展的视频理解管线。

为什么不是直接把视频丢给大模型

最直觉的做法是：下载视频，抽一段文字，调用模型总结。

但这条路很快会遇到几个现实问题：

1. 视频太长，直接塞不进上下文。
2. 平台字幕质量不稳定，有些视频没有字幕，有些字幕缺标点、缺分段、缺时间语义。
3. 画面信息经常比口播更关键，尤其是教程、演示、访谈、产品发布和课程类视频。
4. 总结结果如果没有时间线和证据，很难复查，也很难二次利用。
5. 视频处理是长任务，需要队列、状态、失败恢复和 artifact 管理。

所以这个项目从一开始就不是“prompt 工程”，而是“内容处理系统”。

模型只负责其中一部分判断。真正重要的是在调用模型之前，如何把视频拆成可靠的材料；在模型输出之后，如何把结果保存成稳定的报告。

当前处理管线

Video Content Summary 的处理流程可以拆成六层。

第一层是输入和元数据。

系统通过 yt-dlp 接收视频 URL，提取标题、时长、平台信息、字幕轨和可下载媒体。这里的目标不是立刻总结，而是先判断这条视频到底有什么可用材料。

第二层是字幕优先策略。

如果平台字幕可用，系统优先使用字幕。字幕通常比语音识别便宜、快，也更接近视频发布者想表达的结构。但字幕不是天然可靠，所以项目会对字幕质量做评估：是否为空、是否过短、是否缺少时间信息、是否明显不完整。

第三层是语音识别 fallback。

当没有可靠字幕时，系统会抽取音频，并调用 STT 能力生成转写文本。这里不是无脑调用。STT 成本更高，耗时更长，也更依赖外部服务，所以它应该是 fallback，而不是默认路径。

第四层是关键帧抽取。

对视频来说，文字只能覆盖一半信息。项目会根据处理模式抽取不同密度的关键帧：fast 模式少量抽帧，balanced 模式保持默认平衡，deep 模式保留更多画面证据。关键帧不是装饰，它们用于解释画面里发生了什么。

第五层是多模态证据分析。

如果配置了 OpenAI-compatible 多模态 API，系统可以对关键帧做视觉分析，把画面线索补进时间线。比如屏幕上出现的代码、PPT 标题、产品界面、图表结构，都可能成为总结质量的关键。

第六层是报告生成。

最终输出不只是一个自然语言摘要，而是一组可复用 artifact：

1. report.md：适合人阅读的完整报告。
2. brief_report.md：适合快速浏览的短报告。
3. report.json：适合程序继续处理的结构化结果。
4. manifest.json：记录本次处理使用了哪些输入、产物和阶段。
5. evidence_timeline.json：把文本、时间和视觉证据组织成可追踪时间线。

三个入口：CLI、HTTP API、MCP

这个项目保留了三种入口，因为不同场景需要不同的调用方式。

CLI 是最直接的入口。

它适合本地调试、批处理和个人工作流：

vcs summarize "https://example.com/video" --mode balanced

HTTP API 是服务化入口。

它默认只监听 127.0.0.1:8710，用于被外层 Web 服务或反向代理调用。这个边界很重要：视频总结涉及下载、cookie、模型 API Key 和长任务状态，不应该直接裸露在公网。

典型流程是：

POST /summaries
GET  /summaries/{job_id}
GET  /summaries/{job_id}/report
GET  /summaries/{job_id}/artifacts

MCP 是 agent 入口。

它让 Claude Code、OpenClaw 或其他 MCP 客户端可以直接把“视频总结”当作工具调用。对 agent 来说，最有价值的不是得到一个漂亮页面，而是能启动任务、查询状态、读取报告、继续基于报告做推理。

这三种入口背后应该调用同一套 pipeline，而不是各自实现一遍。否则 CLI、HTTP 和 MCP 很快会分叉，最后变成三个难以维护的项目。

工程上最重要的取舍

这个项目有几个关键取舍。

第一，URL-only。

现阶段只接受视频 URL，不做复杂上传系统。这样可以把第一阶段的注意力放在处理链路上，而不是文件管理、上传进度、存储配额和用户权限上。

第二，localhost-first。

HTTP API 默认只监听本机。公网 HTTPS、鉴权、限流和日志应该交给外层服务处理。这让核心项目保持清晰，也降低误暴露风险。

第三，artifact-first。

每一次处理都应该留下可检查的产物。视频总结不是聊天消息，失败了要能定位，成功了要能复查，结果要能被其他系统继续使用。

第四，多模式处理。

不同视频不应该用同一种成本处理。一个三分钟短视频和一个两小时课程，对抽帧密度、字幕处理和视觉分析的要求不一样。因此项目保留了 text-only、fast、balanced、deep、speaker 等模式。

第五，不把它塞进个人网站仓库。

ai_studio_web 是门户，是作品集，是内容组织层。video_content_summary 是长任务工具，是服务能力，是 agent 工具链的一部分。它们应该通过项目页、文章和未来 API 入口连接，而不是合并成一个仓库。

它最终想成为什么

我希望 Video Content Summary 最终不是一个“总结器”，而是一个视频内容操作系统的底层模块。

它可以服务几类场景：

1. 技术视频学习：把课程拆成章节、概念、代码片段和复习材料。
2. 内容创作：把访谈、直播、发布会转成文章大纲、选题库和短视频素材线索。
3. 知识管理：把视频材料变成可检索、可引用、可二次处理的结构化资产。
4. Agent 工具链：让 agent 不只是读网页和文件，也能读长视频。

短期目标是把单视频处理做扎实。

中期目标是支持批量任务、报告索引、结果检索和更稳定的服务部署。

长期目标是让视频不再是“只能播放”的黑盒，而是能进入个人知识系统和自动化工作流的材料。

这个项目的价值不在于一次总结写得多漂亮，而在于它把视频理解拆成了一组可以持续改进的工程步骤。

这才是它值得作为一个长期项目继续做下去的原因。