最近我在整理一个叫 VideoUnbox 的项目。

如果只看表面，它像是一个“桌面视频解析工具”：

• 粘贴分享链接
• 自动提取 URL
• 调用解析接口
• 展示标题、封面、视频地址、音频地址
• 支持复制下载链接
• 支持多清晰度结果展示

但如果我只是想做一个“能用的小工具”，其实到这一步已经够了。
真正让我继续往下做的原因，不是功能本身，而是我越来越明确地意识到：

我想做的不是一个一次性的接口壳子，而是一个能继续演进的开源桌面项目。

所以 VideoUnbox 后面的方向，就不再只是“功能补丁式增加”，而是开始往三个目标推进：

1. 桌面工具化
2. 后端内嵌化
3. 开源工程化

这篇文章我不打算复述 README，也不打算按文档顺序讲功能，而是从项目作者的角度，聊聊我做这个项目时的一些设计思路和取舍。

---

一、我一开始想解决的，根本不只是“解析链接”

很多类似工具在早期都有一个共同特点：
能跑，但不成体系。

我自己之前在做这类能力时，也遇到过类似问题：

• 接口能调通，但 UI 很随意
• 下载能力能用，但缺少任务状态管理
• 设置可以临时写，但不够稳定
• 某些复杂链路依赖外部脚本或独立后端
• 项目越做越像“工作区里的实验产物”，而不是一个可维护仓库

所以我在继续做 VideoUnbox 的时候，目标就变了。

我真正想解决的是：

1.1 把零散能力收进一个统一桌面入口

我不希望它只是“复制链接 -> 调接口 -> 复制结果”这么单薄。
对我来说，一个桌面工具至少应该具备这些特征：

• 有明确的主界面
• 有设置入口
• 有状态反馈
• 有下载动作
• 有历史或任务的承载空间
• 有适合继续扩展的结构

1.2 把外部依赖链路尽量往 Rust 内部收

这点对我来说很重要。
因为一旦复杂能力依赖外部服务、脚本、额外工具链，项目的可维护性就会明显下降。

尤其是像微信视频号这种链路，如果长期依赖独立 Go 后端或者外置脚本，那么：

• 安装复杂
• 分发复杂
• 调试复杂
• 开源协作复杂

所以我后面重点做的一件事，就是把这部分核心链路逐步迁到 Rust 内嵌后端里。

1.3 让这个项目更像“开源项目”，而不是“个人工作文件夹”

这是我后期最在意的一点。
很多工具都能做出来，但能不能继续维护，往往取决于这些东西有没有跟上：

• 模块边界是否清晰
• 文档是否能帮助别人理解
• 平台差异是否有明确处理
• 打包和发布是否有基本说明
• 仓库里哪些该留、哪些不该留，有没有边界

这也是为什么我后面补了不少看起来“不那么显眼”的内容，比如：

• Windows 构建文档
• GitHub 上传说明
• 复杂链路单独拆文档
• 历史记录持久化
• 平台差异处理

这些东西不一定是最“吸睛”的功能，但对开源维护来说，反而是更关键的部分。

---

二、为什么我会选 Rust + GPUI，而不是更常见的桌面方案

做桌面工具，大家第一反应往往是：

• Electron
• Tauri
• Flutter
• 原生 GUI

我最后选 Rust + GPUI + GPUI Component，并不是因为它最稳，而是因为它更符合我这个项目的演进方向。

2.1 我想尽量减少“多语言割裂”

如果一个项目：

• UI 在前端技术栈里
• 核心逻辑在另一套语言里
• 本地后端又是第三套环境

那么项目在早期确实可以跑得快，但后面维护成本会不断上升。

我更希望 VideoUnbox 的核心逻辑尽量统一在 Rust 生态内：

• 请求逻辑在 Rust
• 下载器在 Rust
• 本地后端在 Rust
• 状态与界面也尽量在 Rust

这样做的好处不是“炫技”，而是更利于长期维护。

2.2 我希望桌面端不是传统工具感，而是更现代一点

这个项目在 UI 风格上，我一开始就不想做成传统的“表单 + 按钮 + 输入框”工具壳。

所以我选择 GPUI，其实也有很明确的产品表达考虑：

• 深色简洁风格更容易统一
• 更接近 Zed / Raycast 这类现代工具观感
• 适合把一个小工具做得不那么“脚本味”

当然，这个选择也意味着代价。

2.3 GPUI 的优点和边界，我都很清楚

说实话，GPUI 并不是“最省事”的方案。
它的边界也很明确：

• 生态还在发展中
• 某些平台行为需要额外兼容
• 构建环境要求并不低
• 跨平台细节问题会比较多

所以我并不想把这套技术选型写成“万能答案”。
更准确地说，它适合 VideoUnbox 当前这个阶段：

我需要一个更统一、更偏 Rust 的桌面实现路径，同时愿意接受一定的工程折腾成本。

---

三、在这个项目里，我最早稳定下来的不是功能，而是模块边界

如果一个开源工具从一开始就不断叠功能，而没有先稳定结构，后面很容易变成“大文件 + 大状态 + 大量 if/else”。

所以我在继续整理 VideoUnbox 时，优先做的是拆边界。

当前项目里大体是这样分的：

src/
├── api.rs
├── app_view.rs
├── downloader.rs
├── history_db.rs
├── macos_bridge.rs
├── main.rs
├── models.rs
├── platform.rs
├── settings.rs
└── wx_backend.rs

3.1 app_view.rs 只承担主界面和状态组织

我不希望所有事情都堆到入口文件里。
所以主窗口、菜单、结果展示、页面状态，主要放在 app_view.rs。

这样做的原因很直接：

• UI 变化频繁
• 下载逻辑和 UI 不该耦合太深
• 后端链路也不该直接塞进渲染层

3.2 api.rs 和 models.rs 负责把“解析能力”独立出去

这一层主要是为了让接口逻辑更清楚：

• 请求怎么发
• 返回结构怎么建模
• 主界面拿到的是业务结构，而不是散乱 JSON

对开源项目来说，这一步也很重要，因为别人阅读代码时，最先希望看到的是“数据模型长什么样”，而不是一堆 UI 状态穿插网络请求。

3.3 downloader.rs 被我单独拆出来，是因为下载本身就是一个系统

很多人做下载功能时，会习惯写成一个按钮事件里的同步请求。
但我在做的过程中越来越觉得，下载不是一个“附属动作”，它本身就是一个子系统。

所以我把它单独拆成模块，去处理这些问题：

• 远端文件探测
• 是否支持 Range
• 单线程还是分段下载
• 暂停 / 取消
• 事件回传
• 临时文件与完成后重命名

这类能力如果一开始不拆，后面要补历史、重试、状态恢复时会很难受。

3.4 history_db.rs 的存在，是为了让下载状态不只是 UI 状态

这一步是我后面补上的，但补完以后我觉得很值。

因为很多工具型项目都有一个问题：

下载完了、失败了、暂停了，这些状态都只存在内存里。

窗口一关，一切就没了。
所以我加了 SQLite 历史记录，把下载任务的基本信息持久化下来，包括：

• 下载 ID
• 文件名
• URL
• 路径
• 状态
• 已下载大小
• 错误信息
• 更新时间

这样做的价值不只是“能记住”，更在于它给后面的功能留了空间：

• 历史面板
• 重试任务
• 断点续传恢复
• 错误回溯

3.5 wx_backend.rs 单独存在，是因为这条链路复杂度已经足够大

这部分我完全不想跟普通解析逻辑混在一起。
原因很简单：

• 它有自己的本地 API
• 有自己的代理逻辑
• 有证书生成
• 有注入和 JS patch
• 有抓包回传
• 有数据归一化
• 有下载后解密

如果这部分不独立，整个项目很快就会失去可读性。

---

四、下载器是我觉得这个项目里最容易被低估的一块

很多人看到视频工具，第一关注点通常是“支持哪些平台”。
但从实现角度看，真正让我花时间打磨的，反而是下载链路。

因为如果只是“拿到一个 URL”，那离真正可用还差很远。

4.1 我不想把下载写成一次性请求

如果只是 demo，当然可以直接 GET 一下把内容存下来。
但真实使用时，很快就会遇到这些问题：

• 文件大了怎么办
• 网络抖动怎么办
• 是否支持断点
• 是否能暂停
• UI 怎么感知进度
• 用户中断后怎么处理临时文件

所以我在下载器里做了几个比较基础但很必要的能力：

• HEAD 预探测
• 判断 Accept-Ranges
• 单线程下载
• 分段下载
• 取消控制
• 事件通知
• .part 临时文件续传

这部分对开源项目的意义在于，它把“按钮触发下载”升级成了“可维护下载模块”。

4.2 我为什么加 SQLite 历史，而不是只靠内存状态

很简单，因为我知道这个项目不会停留在“当前窗口态”。

如果后面要继续扩：

• 历史记录页
• 多任务管理
• 下载失败恢复
• 文件定位
• 已完成状态回看

那么持久化层迟早要补。
与其后面再返工，不如早点把底座铺上。

---

五、微信视频号链路，是我把这个项目往“后端内嵌化”推进的关键一步

这个部分是整个项目里技术密度最高的一块，也是我为什么说它不再只是“接口工具”的核心原因。

5.1 我不想长期依赖外部 Go 后端或额外工具链

以前这类链路如果依赖外置服务，通常会带来很多维护问题：

• 用户不会配
• 平台差异多
• 调试成本高
• 打包和发布麻烦
• 开源协作门槛高

所以我这次做的方向很明确：

尽可能把这条链路迁到 Rust 原生后端里，作为桌面应用的一部分运行。

这样至少能把复杂性收敛在项目内部，而不是散落在多个仓库或脚本里。

5.2 这条链路我最在意的不是“抓到了”，而是“归一化了”

在 /Users/magegojo/Demo/VideoUnbox/docs/WX_CHANNELS_PIPELINE.md 里，我把链路单独写了出来，原因就在这里。

对我来说，这条链路不是简单抓包，而是完整的数据进入流程：

1. 本地启动 API 服务和 MITM 代理
2. 生成根证书
3. 通过 PAC 把相关流量导到本地
4. 对 HTML 做注入
5. 对运行时 JS 做 patch
6. 让页面侧把关键数据主动回传本地
7. 后端做 capture 记录
8. 再做分类和归一化
9. 首页只消费统一结构

这里最关键的不是“抓”，而是后面的：

• normalize_capture
• classify_capture_kind
• normalize_capture_payload

我不想让首页和下载逻辑去面对各种原始 JSON 形态，所以我加了统一的 NormalizedChannelsCapture。

这一步对我来说非常重要，因为它决定了项目后面还能不能继续扩。

5.3 为什么我专门把复杂链路单独写文档

这也是这次整理项目时，我很在意的一件事。

开源项目如果只告诉别人“怎么运行”，但不解释：

• 数据怎么来的
• 模块怎么配合
• 为什么这么设计
• 哪一层负责什么

那么别人就很难真正参与，也很难维护。

所以这次我没有把这部分塞进 README，而是单独写进：

/Users/magegojo/Demo/VideoUnbox/docs/WX_CHANNELS_PIPELINE.md

这样做的目的不是显得“文档多”，而是为了降低理解门槛。

---

六、我为什么专门处理 Windows，而不是只在 macOS 上先跑通就算了

这个项目虽然最初开发环境偏 macOS，但如果我想把它作为开源桌面工具继续做下去，Windows 兼容就不能一直拖着。

因为很多工具项目最后不是死在功能上，而是死在：

• 只在作者机器上可用
• 平台差异没人整理
• 打包方式没人敢碰
• 一到别的系统就各种异常

所以我在项目里专门补了一批 Windows 向兼容处理。

6.1 我做的不是“声明支持 Windows”，而是把问题逐个收掉

当前我已经补过这些点：

• 后端启动 / 停止放到后台线程，避免窗口假死
• Windows 不挂原生菜单栏，减少异常弹窗
• 字体切到 Microsoft YaHei
• PAC 代理改走注册表
• 支持根证书安装
• 链接栈调到 16MB，降低深层渲染导致的栈问题

这些内容听起来不“酷”，但非常真实。

跨平台从来不是 README 里写一句“支持 Windows/macOS”就结束，真正的工作量都在这种细节上。

6.2 为什么我还补了 Windows 构建文档

我补 /Users/magegojo/Demo/VideoUnbox/BUILD_WINDOWS.md，主要有两个原因：

1. 我不想过一段时间连我自己都忘了怎么打包
2. 我希望这个项目未来不只我一个人能发布构建产物

文档里我把这些内容单独写清楚了：

• Windows 下怎么编译
• ZIP 怎么打
• Release 参数怎么做体积优化
• 哪些目录不建议传到仓库

对开源项目来说，这些说明不是“附加项”，而是协作基础。

---

七、我在整理这个项目时，有意补了一些“不像功能”的东西

如果只是追求功能演示，我完全可以不做这些。
但正因为我想把它往开源工程化方向推进，这些东西反而必须补。

7.1 补仓库边界

我单独写了 GitHub 上传说明，明确：

• 建议保留哪些内容
• 不建议提交哪些构建产物
• 哪些运行时文件不该进仓库

这一步看起来很基础，但它其实是在给项目划边界。

7.2 补截图资源

这不是为了“好看”，而是因为开源项目第一页展示非常重要。
别人第一眼看到的不是代码，而是：

• 这是什么
• 长什么样
• 当前完成度如何

所以我把截图也整理进了文档目录。

7.3 补构建与发布认知

我现在还没有把自动化发布全部打通，但已经明确把后续方向留出来了，比如：

• GitHub Actions 自动构建
• Windows ZIP
• macOS DMG

因为我希望这个项目未来不是“只能在本地 cargo run”的状态。

---

八、这个项目现在还不完美，但我知道下一步该往哪补

我不太喜欢把开源项目写成“已经很完整”的口吻。
因为真正长期维护项目的人都知道，项目状态往往更像是“已经有底子，但还在继续补”。

VideoUnbox 现在也是这样。

8.1 我觉得比较明确的下一步

接下来我更想继续补的是：

1. 历史记录面板
   现在数据库已经有了，缺的是更完整的 UI 承载。

2. 下载任务管理器
   让下载不只是“启动后等待”，而是有更清晰的任务视图。

3. 设置持久化再完善
   现在已经有设置管理，但还能继续做得更稳。

4. 封面预览、Toast、Dialog 交互细化
   这部分主要是提升桌面工具的完成度。

5. 自动化构建与发布
   这一步是开源协作真正放大的关键。

8.2 我为什么愿意把这些写出来

因为开源项目不是只展示“现在有什么”，更重要的是让别人知道：

• 项目还在哪些阶段
• 哪些地方已经稳定
• 哪些地方还适合继续贡献
• 维护者接下来要做什么

这样项目才更像一个开放系统，而不是一个静态展示页。

---

九、从开源维护者角度看，我对这个项目最在意的不是功能多少，而是可继续演进

说到底，我做 VideoUnbox 最在意的一点，是它能不能继续长。

功能当然重要，但如果只有功能，没有结构、文档和边界，那项目增长到一定阶段就会反噬自己。

所以这次整理下来，我更在意的是这些事：

• UI、API、下载、设置、后端有没有拆开
• 复杂链路有没有被解释清楚
• 平台差异有没有显式处理
• 下载状态有没有进入持久化
• 仓库有没有基本的发布与清理边界

这些内容决定了它是不是一个“能继续做下去”的项目。

---

十、一些更真实的边界，也应该提前说清楚

开源文章如果只讲亮点，很容易写成项目介绍页。
但从作者视角看，边界和限制同样重要。

10.1 当前适合什么样的读者

我觉得这个项目当前更适合：

• 想看 Rust 桌面项目怎么拆结构的人
• 想研究 GPUI 落地方式的人
• 想把工具脚本整理成桌面应用的人
• 想看本地后端如何嵌入桌面工具的人

10.2 当前不适合什么预期

如果你期待的是：

• 完全零配置
• 所有平台开箱即用
• 完整成熟的商业级产品体验

那这个阶段的 VideoUnbox 还不是这种定位。

10.3 我为什么愿意在文章里保留这些边界

因为真正的开源写作，不应该只讲“我做成了什么”，还应该讲：

• 哪些地方还在演进
• 哪些链路有前置条件
• 哪些体验还在补
• 哪些部分是工程现实

这样文章更真实，项目也更可信。

---

十一、总结

VideoUnbox 这个项目对我来说，已经不再只是一个“视频解析工具”。

它更像是我在做的一次开源工程整理：
把原本偏零散的解析、下载、设置、后端代理、数据归一化这些能力，往一个真正可维护的 Rust 桌面项目里收拢。

如果只看功能，它能做的是：

• 解析链接
• 展示媒体信息
• 管理下载
• 承接更复杂的本地后端链路

但如果从开源维护角度看，我更在意的是它做成了这些事情：

• 用 Rust + GPUI 统一桌面侧表达
• 用模块拆分控制复杂度
• 用 SQLite 承接本地状态
• 用内嵌后端收拢复杂链路
• 用独立文档解释复杂实现
• 用平台兼容和构建说明降低协作门槛

我并不把它看成一个已经完成的产品。
我更愿意把它看成一个已经长出骨架的开源项目。

后面它还能继续补很多东西，但至少到现在为止，它已经不再是一个“能跑就行”的工具原型了。

对我来说，这就是这次整理 VideoUnbox 最有意义的地方。