开源了一个本地字幕工具 Fast Sub，聊聊三周 Codex 实战经验

大家好，最近开源了一个自己做的本地字幕工具 Fast Sub 。

GitHub：
https://github.com/ryviuszero/Fast-Sub

项目主要是给视频 / 音频生成字幕，也支持字幕翻译、双语字幕和字幕烧录。现在 Windows 和 macOS 都已经打包好了。

目前主要功能大概是：

• 本地视频 / 音频生成 SRT 字幕
• 支持 Faster Whisper / whisper.cpp
• 支持字幕翻译、双语字幕
• 支持字幕烧录
• 支持本地模型和 OpenAI-compatible API
• 默认本地处理，远程 API / Web provider 需要显式选择

转录质量方面，Whisper large-v3 / v3 turbo 这一代已经很不错了，普通播客、课程、视频内容基本够用。

翻译这块我做了一些 benchmark 。CLI 里现在有 bench 和 bench-translate，转录主要看 WER / CER ，翻译主要看 BLEU / chrF ，同时也记录 exact match 。实际结果是：NLLB 本地翻译可用，但会有一点生硬；本地 Qwen3 4B 的字幕翻译效果挺惊喜，在我的测试样本里已经比较接近 Google 翻译。

第一版桌面端为了收敛范围，先把 benchmark 图形界面砍掉了；目前质量对比主要还是通过 CLI 跑。

项目地址：
https://github.com/ryviuszero/Fast-Sub

另外我也写了一篇比较长的复盘，主要不是介绍功能，而是记录这三周用 Codex 做完整项目的一些经验：
https://ryviuszero.github.io/zh/posts/codex-complex-project-development/

这次最大的感受是，Codex 用来做真实项目，和“一句话生成 demo”完全不是一回事。

我自己比较有体会的几点：

1. 先写 MVP 文档，比直接写代码重要

   一开始先把项目的最小版本写清楚：做什么、不做什么、默认行为、隐私边界、错误码、输出格式。后面 Codex 每次接着做，都有一个明确边界，不容易越做越散。

2. 用一轮一轮的方式推进

   我没有让 Codex 一次性做完整桌面应用，而是从 CLI 、模型管理、provider 、benchmark 、Go daemon 、Electron UI 、打包发布这样一轮一轮推进。每轮都有目标、非目标和验收命令。

3. 文档就是长期上下文

   聊天记录不适合当项目记忆。所以项目里放了产品文档、架构文档、开发规范、spec 、tracker 、QA 表、release smoke 。后面每次让 Codex 继续做，都是先读这些文档。

4. 重构不能省

   AI 很容易快速堆功能，但项目很快会变复杂。中间我专门做过一轮 Python 分层重构，把 CLI 、service 、provider 、worker 、model store 、benchmark 这些边界拆开。后面迁移 Go 、接 Electron 、做打包都明显轻松很多。

5. UI 最好 mock-first

   Electron 一开始没有直接接真实后端，而是先用 mock client 跑通页面、状态、失败、取消、结果展示。UI 状态稳定后，再切到真实 Go daemon 。这样调试成本低很多。

6. QA 和发布要尽早进入流程

   桌面应用不是 build 通过就完了，还要测 installer 、portable 、macOS dmg 、模型下载、中文路径、进程退出、secret redaction 、真实 provider 、截图 baseline 等。这个过程也很适合交给 Codex 做清单和回归。

总的来说，Codex 对我最大的帮助不是“生成一段代码”，而是可以持续协作：写计划、拆任务、改代码、补测试、重构、更新文档、做 release checklist 。

但前提是要给它足够清楚的上下文和验收标准，不然项目大一点之后也会失控。

项目还比较早期，如果大家对本地字幕工具、字幕翻译、本地模型，或者 Codex 做项目的流程感兴趣，欢迎看看，也欢迎提建议。