架构设计

本文档基于当前仓库代码说明 Falcon 的核心结构，而不是早期设计稿中的理想化接口。

总体结构

text

falcon/
├── packages/
│   ├── libfalcon-core/     # 核心下载引擎、任务模型、事件系统
│   ├── libfalcon-protocols/# 标准下载协议与协议相关实现
│   ├── libfalcon-storage/  # 对象存储与远程资源浏览
│   ├── libfalcon-drives/   # 网盘、分享链、账号态能力
│   ├── falcon-cli/         # 命令行工具
│   └── falcon-daemon/      # 后台服务
├── apps/
│   └── desktop/            # Qt6 桌面应用
└── docs/                   # 文档站

库依赖关系

falcon_protocols  →  falcon_core
falcon_storage    →  falcon_core
falcon_drives     →  falcon_core

禁止反向依赖：core 不依赖 protocols/storage/drives。

顶层还提供兼容聚合 target：

text

Falcon::falcon = falcon_core + falcon_protocols + falcon_storage + falcon_drives

Falcon::falcon 主要用于历史兼容和“一次性链接全部能力”的场景。内部应用、测试和新增模块应优先按需链接具体 target，例如 Falcon::core、Falcon::protocols、Falcon::storage 或 Falcon::drives，避免把无关模块隐式带入最终链接图。

当前分层状态

libfalcon-core

核心层包含稳定领域模型和调度抽象：

DownloadTask、TaskManager、DownloadEngine
ProtocolRegistry、IProtocolHandler
EventDispatcher、IEventListener
基础类型、异常、日志、版本、密码管理

falcon_core 可以独立构建和测试，不依赖具体协议实现。内置协议注册通过 builtin_protocol_handlers_stub.cpp 提供弱符号桩函数；当最终程序同时链接 falcon_protocols 时，libfalcon-protocols/src/builtin_protocol_handlers.cpp 中的真实实现会覆盖桩函数并注册 HTTP/FTP 等具体处理器。

libfalcon-protocols

协议层依赖 falcon_core，负责具体下载协议和传输能力：

HTTP/FTP 等协议处理器
分段下载、增量下载、请求组、文件 hash
socket/event poll 等协议侧网络基础设施
可选私有协议插件

协议层可以扩展具体协议，但不应把协议实现细节反向放入 core。

libfalcon-storage

存储层依赖 falcon_core，负责远程资源浏览和对象存储浏览能力，例如 FTP/S3/OSS/COS/Kodo/Upyun browser。它不应依赖 falcon_protocols。

libfalcon-drives

网盘层依赖 falcon_core，负责网盘、分享链、资源搜索和配置管理类能力。当前这层仍包含占位源文件和多个可选功能开关，成熟度低于 core 和基础协议层。

当前稳定性基线

当前已用 vcpkg manifest 构建验证：

falcon_core_tests: 384 个测试通过
falcon_split_tests: 10 个测试通过

这说明 libfalcon-core 的核心行为和四库链接分层在当前测试覆盖范围内是稳定的。它不等价于整个项目功能齐全；协议插件、桌面端、daemon、网盘和资源浏览仍需要各自的集成测试与真实场景验证。

libfalcon-core 核心组件

DownloadEngine

DownloadEngine 是面向调用方的主入口，负责：

接收下载请求
管理任务生命周期
管理事件监听器
与 ProtocolRegistry 和 TaskManager 协作

当前公开接口以这些方法为主：

cpp

DownloadTask::Ptr add_task(const std::string& url,
                           const DownloadOptions& options = {});
std::vector<DownloadTask::Ptr> add_tasks(const std::vector<std::string>& urls,
                                         const DownloadOptions& options = {});

bool start_task(TaskId id);
bool pause_task(TaskId id);
bool resume_task(TaskId id);
bool cancel_task(TaskId id);

void add_listener(IEventListener* listener);
void remove_listener(IEventListener* listener);

std::vector<std::string> get_supported_protocols() const;
bool is_url_supported(const std::string& url) const;

说明：

DownloadEngine 构造时会加载当前构建里可用的内置处理器。
文档中不再使用旧的 startDownload() / loadPlugin() 作为对外接口。

TaskManager

TaskManager 负责：

任务队列
最大并发控制
任务状态迁移
启动、暂停、恢复、取消具体任务

从 DownloadEngine 实现来看，任务通常先通过 add_task() 创建，再由 start_task() 推进执行。

ProtocolRegistry

ProtocolRegistry 负责：

注册协议处理器
根据 URL 路由到合适处理器
加载当前构建里可用的内置 handler
提供协议与 scheme 查询

公共头文件中的核心方法包括：

cpp

void register_handler(std::unique_ptr<IProtocolHandler> handler);
IProtocolHandler* get_handler(const std::string& protocol) const;
IProtocolHandler* get_handler_for_url(const std::string& url) const;
void load_builtin_handlers();
bool supports_url(const std::string& url) const;

IProtocolHandler

协议插件通过 IProtocolHandler 接入：

cpp

std::string protocol_name() const;
std::vector<std::string> supported_schemes() const;
bool can_handle(const std::string& url) const;
FileInfo get_file_info(const std::string& url,
                       const DownloadOptions& options);
void download(DownloadTask::Ptr task, IEventListener* listener);
void pause(DownloadTask::Ptr task);
void resume(DownloadTask::Ptr task, IEventListener* listener);
void cancel(DownloadTask::Ptr task);

与旧设计相比，下载接口不是“传 URL 返回新 task”，而是“接收已有 DownloadTask::Ptr”。

下载流程

text

用户调用 add_task(url, options)
        ↓
DownloadEngine 校验 URL 并创建 DownloadTask
        ↓
ProtocolRegistry 根据 URL 找到协议处理器
        ↓
TaskManager 接管任务并排队
        ↓
start_task(id) 触发执行
        ↓
协议处理器执行 download(task, listener)
        ↓
任务状态和进度通过事件系统回传

事件系统

当前公共事件接口不是 ProgressEvent / CompleteEvent 这套结构体，而是：

TaskStatus
ProgressInfo
FileInfo
IEventListener

IEventListener 主要回调：

cpp

void on_status_changed(TaskId task_id,
                       TaskStatus old_status,
                       TaskStatus new_status);
void on_progress(const ProgressInfo& info);
void on_error(TaskId task_id, const std::string& error_message);
void on_completed(TaskId task_id, const std::string& output_path);
void on_file_info(TaskId task_id, const FileInfo& info);

并发与线程

从当前实现看：

EventDispatcher 负责事件分发
TaskManager 负责任务调度
协议处理器负责具体下载逻辑
DownloadEngine::Impl 在构造时启动事件分发器和任务管理器

这意味着调用方通常不需要自己管理“主事件循环”。

设计边界

当前文档刻意不再展开这些尚未形成稳定公共 API 的设计：

startDownloadAsync() 之类异步包装接口
协程版下载 API
协议专属公开选项结构体
Web 管理界面作为既成事实架构层

这些内容如果未来进入实际头文件，再适合写进架构文档。

架构设计 ​

总体结构 ​

库依赖关系 ​

当前分层状态 ​

libfalcon-core ​

libfalcon-protocols ​

libfalcon-storage ​

libfalcon-drives ​

当前稳定性基线 ​

libfalcon-core 核心组件 ​

DownloadEngine ​

TaskManager ​

ProtocolRegistry ​

IProtocolHandler ​

下载流程 ​

事件系统 ​

并发与线程 ​

设计边界 ​

架构设计

总体结构

库依赖关系

当前分层状态

libfalcon-core

libfalcon-protocols

libfalcon-storage

libfalcon-drives

当前稳定性基线

libfalcon-core 核心组件

DownloadEngine

TaskManager

ProtocolRegistry

IProtocolHandler

下载流程

事件系统

并发与线程

设计边界