• 桌面应用
• 音视频

BiliTools 是一款基于 Tauri 2 与 Vue 3 构建的跨平台哔哩哔哩工具箱，其 CHANGELOG.md 完整记录了从 2023 年 11 月（0.1.0 初始提交）到 2025 年 11 月（1.4.7）的迭代历程。本文以该变更日志为骨架，结合仓库源码，梳理 BiliTools 在下载引擎、资源解析、任务调度、数据库迁移与前端架构上的演进脉络，帮助读者理解每个版本的能力边界与底层实现原理。

版本时间线与整体演进脉络

从 CHANGELOG.md 的版本序列可以看出，BiliTools 的演进大致分为三个阶段：

其中 1.4.0 是一个分水岭：它经历了1.4.0-1到1.4.0-8共 8 个预发布迭代，随后在 1.4.1~1.4.7 逐步稳定。仓库 package.json 与 src-tauri/Cargo.toml 中记录的当前版本均为1.4.7，与变更日志最新条目一致。根据项目说明，该仓库现已停止维护，1.4.7 是最终版本。

并发模型与任务调度的深度重构（1.4.5 与 1.4.0）

从"队列推送"到"异步状态机"

1.4.5 版本的变更日志标注了三项重大更新：完全重构并发模型（[#193]）、完全重构任务管理/调度/状态轮转模型、重构资源清理逻辑并使用基于异步状态机的状态管理机制。这些改动直接体现在 src-tauri/src/services/queue 目录的源码结构中：

• atomics.rs：定义了任务与调度的状态枚举。TaskState包含Backlog → Pending → Active → Completed / Paused / Failed / Cancelled七个状态（atomics.rs），并基于AtomicU8封装了无锁的Atomic<T>状态读写；SchedulerState则包含Idle / Running / Paused / Completed / Failed / Cancelled六种状态；QueueType定义了Backlog / Pending / Doing / Complete四种队列类型。
• manager.rs：全局单例MANAGER维护schedulers、tasks两张哈希表，以及backlog / pending / doing / complete四个VecDeque队列（manager.rs），负责任务的提交、调度器编排与队列迁移。
• scheduler.rs：Scheduler::dispatch使用tokio::task::JoinSet并发分发任务，通过信号量（RUNTIME.semaphore）控制并发数，并在全部子任务结束后将调度器迁移至Complete队列（scheduler.rs）。
• task.rs：任务内部将状态、进度等"热数据"统一封装，状态变更时同时同步到内存、前端与数据库三层（task.rs）。

从源码结构看，1.4.5 之前"队列推送 + 并发处理"的实现被替换为"调度器（Scheduler）驱动 + 任务状态机"的模型：每个 Scheduler 承载一批任务，任务在调度器内经历状态轮转，取消、暂停、恢复通过RUNTIME.ctrl发送控制事件（CtrlEvent）实现，配合tokio::select!实现可取消的异步任务（scheduler.rs）。1.4.5 同时大规模减少Arc引用计数使用以提高性能，并新增了对标准库错误栈的正则解析（stacktrace-js与source-map-js出现在前端依赖中）。

调度器级别的控制能力

1.4.0-6 引入了"Scheduler 级别控制"与自动恢复下载任务（[#136]、[#41]），scheduler.rs中的restore方法在检测到interrupted()（队列处于Doing且状态为Idle，即异常中断）时会重新拉起dispatch。1.4.0 正式版又整合了多选下载、打包下载与常规下载（[#87]、[#80]、[#81]、[#89]、[#78]），统一了任务入口；1.4.0 还支持修改等待任务的参数（[#149]），task.rs中的prepare方法即为"后端内存、前端事件、数据库"三端同步准备参数的实现。1.4.7 修复了取消 Scheduler 任务时概率导致大量报错的问题（[#215]），从 scheduler.rs 的cancel实现可见，其先置状态为Cancelled、再向每个任务广播CtrlEvent::Cancel、最后从内存与数据库移除，若遍历时持有锁则可能死锁，这也是该修复的要点所在。

资源解析能力的持续扩展

解析能力是 BiliTools 功能矩阵中增长最快的一部分，按时间顺序梳理如下：

• 基础资源：1.0.0 起支持视频（DASH/MP4）、音频（最高无损 SQ FLAC）；1.1.0 支持课程解析/下载；1.3.0 完整支持 DASH/MP4、收藏夹解析、AI 总结（Markdown）、历史与实时弹幕（ASS 字幕）、AAC/EAC3/FLAC/MKV；1.4.0 支持解析子合集与番剧 PV 等资源（[#55]、[#64]、[#108]）、稍后再看（[#83]）、历史记录（[#107]）、XML 格式弹幕（[#118]）。
• 用户内容：1.4.1 支持解析用户投稿视频/音频/图文/动态/专栏（[#175]）；1.4.3 扩展为用户完整投稿列表并支持拖拽链接自动搜索（[#183]）；1.4.4 支持解析分享链接（[#187]）。
• 合集与图文：1.4.5 支持解析图文合集（专栏 & 动态）（[#191]），并修复了合集翻页、合集视频section_id不匹配等问题。

从 src/services/media 目录看，解析逻辑按data.ts / dm.ts / extras.ts / opus.ts拆分，分别对应数据获取、弹幕、附加内容与图文内容，1.4.5 起新增的图文解析能力与OpusContent / OpusImages任务类型对应（见 task.rs 中的TaskType枚举）。

下载引擎、格式支持与 Sidecar 体系

下载链路：aria2c + FFmpeg + DanmakuFactory

BiliTools 的下载依赖三个 Sidecar 二进制：aria2c（下载器）、FFmpeg（音视频处理/混流）、DanmakuFactory（弹幕 XML 转 ASS），仓库 src-tauri/binaries 中按linux / macos / windows三个平台目录存放了对应架构的预编译产物。

关键演进节点：

• 1.0.2：支持设置"最大下载并发数"，修复 Dolby/Hi-Res 下载链接获取方式。
• 1.0.3：引入 aria2c RPC（多线程下载/断线续传）、互动视频回溯与剧情分支下载、自动选择下载线路；应用体积从 42M 压缩至 23M。
• 1.1.2：新增 FLV 支持，历史/实时弹幕支持 XML+ASS 下载，持久化存储下载记录。
• 1.3.4：macOS Sidecar 改用静态链接二进制，大幅减小 ffmpeg 体积；恢复音乐下载并支持歌单；下载音视频时自动处理音频流格式（[#24]）。
• 1.4.0：修复 FLAC 在 MKV 下的混流问题（[#151]）、aria2c 超时问题（[#127] 等多期 issue）、规范 aria2c 的请求参数（[#100]）、屏蔽 PCDN（[#77]）。
• 1.4.4：支持自定义各 Sidecar 的执行路径、网络限速（[#187]）、为视频嵌入元数据与原始 URL（[#147]）。

媒体格式与元数据

• 视频容器：DASH、MP4、FLV、MKV；编码支持 8K、HDR、杜比视界、Hi-Res 无损、杜比全景声。
• 音频：AAC、EAC3、FLAC（无损），1.4.0-3/1.4.0-4 支持强制转换音频为 MP3（[#95]）。
• 元数据：1.3.7 支持将元数据自动嵌入媒体文件（[#50]）；1.4.0 规范元数据格式（[#104]、[#114]）；1.4.4 支持嵌入原始 URL；1.4.1 支持为音频文件嵌入封面（[#161]）。
• NFO 刮削：1.3.8 引入（Preview），支持合集/剧集刮削与单集刮削，1.4.1 优化了 NFO 解析逻辑。

命名格式、存储组织与设置体系

命名格式的演进

• 1.2.0 起下载文件夹命名会附加下载时的时间。
• 1.3.6 将自定义文件名设置由设置->下载迁移至设置->高级，支持高级自定义（[#35]）。
• 1.3.7 将"自定义文件名设置"更名为"命名格式"，同时支持自定义文件夹命名并添加更多变量。
• 1.4.0 重构命名格式，支持顶层文件夹格式与自定义事件格式，并新增 ISO 8601 时间占位符（[#134]）。
• 1.4.0-6 支持控制是否创建顶层文件夹（[#141]）。

这一系列演进最终落在src-tauri/src/storage/config.rs的organize配置结构中（top_folder开关与文件夹模板），scheduler.rs在创建调度器时根据config::read().organize.top_folder决定输出目录（scheduler.rs）。文件命名与顶层文件夹的完整占位符说明可参见 docs/guide/download.md 与 docs/guide/settings.md。

文件名健壮性

路径解析一直是 BiliTools 修复的重点：1.4.0 修复点号导致路径解析错误（[#165]）、增强非法字符校验（[#135]）、规范文件编号排序（[#115]、[#121]）、规范文件名去除非法字符（[#120]）；1.4.5 再次修复点号被错误替换（[#198]）。这些修复对应src-tauri/src/shared.rs中的路径清理与唯一路径生成逻辑（get_unique_path被scheduler.rs调用）。

设置与网络

• 代理与登录：1.3.0 支持 HTTP(S) 代理；1.3.2-1/1.3.2 修复 Unix-like 系统权限问题与 geetest/FFmpeg 错误处理。
• 1.4.0 支持设置检测重名（[#146]）；1.4.4 支持网络限速（[#187]）。
• 1.4.0-2 起使用自建更新源，并支持视频发布日期变量（[#68]）。

登录与账号体系

账号相关能力自 1.0.0 起即为核心：支持扫码、密码、短信登录并自动刷新登录状态；1.0.2 优化退出登录逻辑，短信登录自动根据地区选择国家区号；1.1.0 前后端交互添加 secret 校验提高安全性；1.3.0 重构登录稳定性；1.3.3 完善密码登录的风控对应逻辑。

从 src-tauri/src/lib.rs 注册的命令看，登录命令包括scan_login / pwd_login / sms_login / refresh_cookie / switch_cookie / stop_login，覆盖扫码、密码、短信、Cookie 刷新与切换全流程。前端依赖中的jsencrypt（RSA 加密）、md5（签名摘要）、qrcode-generator分别服务于密码加密、参数签名与扫码登录，与 src/services/login.ts 对应。1.4.0 还修复了uname字段缺失问题（[#82] 等多期 issue），这类问题往往来自 B 站 API 字段变更，需持续适配。

数据库、缓存与数据迁移

BiliTools 使用 SQLite 本地明文存储数据（Windows 为%APPDATA%\com.btjawa.bilitools，macOS 为$HOME/Library/Application Support/com.btjawa.bilitools，Linux 为$HOME/.local/share/com.btjawa.bilitools，见 README.md）。数据库 Schema 版本（STORAGE_VERSION）的演进是观察数据模型变化的关键指标：

1.4.0 正式版支持自动迁移、导入与导出数据库（[#125]），1.4.7 更新数据库基准版本以解决历史遗留问题（[#227]、[#199]）。对应实现位于 src-tauri/src/storage/migrate.rs 与 src-tauri/src/storage/db.rs，src-tauri/Cargo.toml中sqlx（SQLite）+sea-query是 ORM 层的基础；1.2.0-dev.13 曾使用 sea-orm 存储数据，最终在 1.3.0 重写为当前方案。缓存管理（日志、临时文件、WebView、数据库）自 1.3.0 起可通过设置页清理，lib.rs注册了open_cache / get_size / clean_cache / db_import / db_export / export_data等命令。

前端架构与交互演进

前端演进贯穿整个项目生命周期，涉及三条清晰的技术迁移线：

1. 状态管理：Vuex → Pinia（1.3.3）。
2. API 风格：Options API → Composition API（1.3.3）。
3. 通知组件：iziToast → vue-notification（1.3.3）→ vue-sonner（1.4.7，改善报错信息显示体验，[#211]）。

其他关键节点：

• 1.3.0 使用 Vue 与 TypeScript 完全重构所有功能，内核升级至 Tauri v2.1.1，支持明暗主题、I18N 多语言（zh-CN / zh-HK / en-US / ja-JP，见 src/i18n/locales）。
• 1.4.0-2 重写所有语言的翻译、添加"关于"页面、缩小默认窗口大小（[#96]、[#83]）。
• 1.4.0 支持置顶窗口（[#170]）、自定义窗口效果（[#163]）、Shift 多选（[#129]）、监听剪切板（[#70]）。
• 1.4.5 使用状态库管理组件实例（对应 src/store/components.ts），修复下载界面任务展示性能问题。

前端依赖中还包含virtua（虚拟列表，用于大量数据的列表滚动）、vue-markdown-render（AI 总结渲染）、@vuepic/vue-datepicker与dayjs（时间处理）、p-limit（并发限制）等，与变更日志中的功能一一对应。

平台支持、打包与分发

• Windows / macOS：1.3.0 起 macOS 正式支持；1.3.4 支持 Apple Silicon（aarch64-darwin，[fcc2674]）；1.4.0 为 macOS 分发包增加签名（[#103]、[#91]、[#26]）。
• Linux：1.3.1 起支持 Linux；1.4.0 支持基于 Debian 的发行版（[#97]）与 Linux arm64；1.4.2 支持 RPM 与 AppImage 打包格式（[b31bba8]）；1.4.3 修复 Linux 下 Sidecar 的打包策略问题（[#182]）。
• 分发策略：1.4.0-2 起不再提供 universal 版本；1.4.0 修复 Debian 平台依赖过时的问题（[#177]）。

仓库 src-tauri/tauri.conf.json 及tauri.linux.conf.json / tauri.macos.conf.json / tauri.windows.conf.json按平台拆分构建配置，Sidecar 目录 src-tauri/binaries 中每个平台目录下均存在aria2c / ffmpeg / DanmakuFactory三类二进制的x86_64与aarch64（Linux/macOS）变体，scripts/binaries.mjs负责这些二进制的下载与校验。

从变更日志看项目治理与维护状态

变更日志还透露了项目的治理模式与边界：

• 开源协议：1.3.3 从 MIT 迁移至 GPL-3.0-or-later，要求任何形式的二次分发必须继续开源、遵守相同协议并保留版权信息（LICENSE）。
• 社区协作：多个修复由外部贡献者提交（如 @AgentOpen、@Excitedfighter、@hqc8848 等），issue 编号从 #8 持续到 #227，形成"社区报障 → 修复回归"的闭环，CHANGELOG 中 commit 短哈希（如d74c47d、133c63f）可追溯每次变更。
• 功能取舍：1.3.2 因漫画接口不稳定暂时关闭漫画解析入口；1.3.3 宣布暂不再更新漫画下载；1.3.0 起停止低于该版本的维护。
• 维护现状：1.4.0 正式版后项目进入稳定状态暂缓更新（README 中的说明），当前仓库标注已停止维护，1.4.7 为最终版本。从 0.1.0 的初始提交到 1.4.7，BiliTools 完成了从单平台下载工具到跨平台（Windows / macOS / Linux x86_64 与 arm64）、覆盖视频/音频/弹幕/字幕/音乐/用户投稿/收藏夹等全类型资源、具备完整登录与数据迁移能力的工具箱的演进。

对于希望深入了解实现的读者，建议按以下路径阅读源码：任务状态机见 atomics.rs，调度分发见 scheduler.rs，任务生命周期见 task.rs，全局队列管理见 manager.rs，命令注册与插件装配见 lib.rs。结合本文章梳理的版本演进脉络，可以快速定位每个功能对应的实现位置与其设计动机。

• 桌面应用
• 音视频