把 B 站视频变成本地知识笔记：VideoNoteAI Desktop MVP 复盘

VideoNoteAI 解决的是一个很具体的问题：我收藏了不少 B 站视频，但真正需要回看某个观点时，很难在几十分钟的视频里重新定位。我的目标不是做一个视频网站，也不是再造一套在线笔记服务，而是把视频稳定地变成保存在本地的 Markdown 知识笔记。

最终的 Desktop MVP 只要求用户粘贴分享内容并点击“开始生成”。程序会下载音频、生成带时间戳的转录、调用兼容 OpenAI 接口的模型整理笔记，完成后直接打开 note.md。

先把边界说清楚

第一版主动不做批量处理、任务队列、Web UI、数据库、RAG、插件系统和本地大模型。它一次只处理一个视频，但要把这一条链路做完整：

解析分享内容
→ 下载并转换音频
→ Whisper 转录
→ 分段提炼与合并
→ 笔记质量检查
→ 保存 Markdown

这个限制很重要。桌面工具最容易在“以后可能需要”里长出许多入口，最后核心任务反而不可靠。Desktop MVP 的完成标准始终是：不用打开终端，也能得到一份可定位、可阅读、可长期保存的笔记。

桌面端没有重写核心流程

项目最初已经有 CLI 流水线。增加 PySide6 界面时，我没有把下载、转录和总结逻辑复制到按钮回调里，而是让桌面端与 CLI 调用同一条 pipeline。

界面只负责输入、状态展示和用户选择；下载器、转录器、总结器和文件写入仍然是独立模块。这样一来，某个阶段出错时可以直接定位到对应模块，CLI 测试也能继续保护桌面端真正依赖的业务逻辑。

进度不是一根虚假的进度条

视频处理时间会同时受到视频长度、网络、GPU 和模型服务影响。如果没有足够历史数据，显示“还剩 3 分钟”只是制造确定性的幻觉。

因此界面展示真实阶段和已用时间：读取、下载、转录、总结、完成。结束后再列出各阶段实际耗时。它不能预测未来，却能持续回答用户最关心的问题：程序现在有没有工作，工作到了哪里。

失败时保留已经完成的工作

长视频的转录和总结都可能失败。如果任何异常都删除整个任务目录，用户只能从下载重新开始。

VideoNoteAI 会在 metadata.json 中记录当前状态和失败阶段，并保留已经完整写入的文件。再次处理同一视频时，程序会检查现有音频和转录是否真实有效，再从最近的安全阶段继续；不能通过校验的产物不会被盲目信任。

这不是保存 Whisper 内部状态的任意断点续跑，而是更朴素的阶段级恢复。它覆盖了桌面工具最常见的中断场景，同时没有引入任务数据库和调度系统。

笔记质量需要一个闭环

模型返回 Markdown 并不代表任务已经完成。长视频会先按字符数切分，最多并发处理两个分段，再按原顺序合并。生成后还要检查结构和内容质量；第一次不合格时自动修订一次，仍不合格则保留候选结果供排查，不覆盖正式笔记。

这里最重要的变化，是把“接口调用成功”和“产物可用”分开。前者只是网络请求结束，后者才是产品目标。

最难的其实是知识库迁移

生成内容与项目源码分开存储后，用户需要在桌面界面修改知识库位置。只保存一个新路径很简单，但真实使用很快会遇到往返迁移和同名任务冲突。

现在的迁移以完整任务目录为原子单位：

• 目标不存在的任务会复制，并逐文件做 SHA-256 校验；
• 同名且完整内容一致的任务自动跳过；
• 同名但内容不同的任务不会静默合并；
• 替换目标版本前先在同一磁盘暂存原目录，失败时恢复；
• 切换成功后，再由用户决定是否删除经过二次校验的原内容。

这里没有“智能合并”每个任务里的元数据、转录和笔记。两份完整任务究竟哪一份正确，是用户数据决策，不应该由程序猜测。

最后学到的

VideoNoteAI 的复杂度没有主要来自模型调用，而是来自如何让一条可能失败的长流程变得可信：

1. 界面与核心业务共用同一条流水线；
2. 状态反馈只展示已经知道的事实；
3. 每个阶段先完整落盘，再允许后续步骤依赖；
4. 用户数据迁移默认保留原内容，冲突必须显式选择；
5. 先完成一条日常可用的闭环，再讨论批量、搜索或更多智能能力。

这也是我想在 sprigh.com 项目档案里记录它的原因：它不只是“调用 AI 总结视频”，而是一次把桌面交互、长任务恢复和本地数据安全放进同一套工程边界的实践。