快速开始

WARNING

注意：本文档及其以下所有文档主要针对 TLD（Rust 版本）。

如果您使用的是 TTHSD Golang 版本，请注意：

TTHSD Golang 已停止开发

建议迁移到 TLD 以获得更好的性能和功能

调用方式与 TLD 大致相同，可以直接替换动态库

TTHSD Golang 的官方发布最新版（0.5.0 版本）有 Bug，不建议使用

新版文档未完全更新，请等待更新。TLD 现在还处于实验性阶段，但其核心的基本功能均可使用，Android、IOS 和 HarmonyOS 的编译版本未经过大规模测试，可以的话请帮忙测试，谢谢！

简介

TLD Core 是一个高性能的多线程下载器内核，原生支持 7 种下载协议（HTTP/HTTPS、HTTP/3、FTP、SFTP、BitTorrent/Magnet、ED2K、Metalink）。TLD 采用 Rust 语言编写，核心逻辑编译为动态链接库 (DLL/SO/DYLIB)，可供 Python、C++、C#、Java/Kotlin、TypeScript、Rust、Go、Godot 等 8 种语言调用。

相比 TTHSD Golang 版本，TLD 具有更高的性能、更低的内存占用和更稳定的运行表现。

本文档将指导您如何在 Python 项目中快速集成和使用 TLD。

开源协议

本项目采用 GNU AGPL v3.0 协议开源发布。

安装指南

1. 系统要求

操作系统: Windows (x64), Linux (Ubuntu 22.04+), macOS, Android, IOS, HarmonyOS

Python 版本: Python 3.11 及以上

依赖项: 不需要额外安装 Python 依赖库，通过 ctypes 直接调用内核。

2. 获取内核文件

您需要下载对应平台的动态链接库文件：

注：TLD 默认只支持 64 位系统

桌面系统（Windows, Linux, MacOS）

x86_64 架构使用默认名称（TaiLerDownloader.*）

ARM64 架构使用带后缀的名称（TaiLerDownloader_arm64.*）

Android 版本

TaiLerDownloaderandroidx86_64.so

TaiLerDownloaderandroidarm64.so

TaiLerDownloaderandroidarmv7.so

HarmonyOS 版本

TaiLerDownloaderharmonyx86_64.so

TaiLerDownloaderharmonyarm64.so

IOS 版本

TaiLerDownloaderiosarm64_device.dylib # iOS ARM64 设备库

TaiLerDownloaderiosarm64_simulator.dylib # iOS ARM64 模拟器库

TIP

您可以在 TLD GitHub Releases 页面下载最新版本的内核文件。

3. 获取 Python 接口封装

为了简化调用，官方提供了封装好的 Python 接口文件 tld_interface.py。

下载 tld_interface.py。

将 内核文件 和 tld_interface.py 放置在您的 Python 项目根目录下。

基本用法

以下示例展示了如何初始化下载器并下载一个文件。

初始化与回调

首先，导入模块并定义一个回调函数来接收下载进度和状态。

from tld_interface import TaiLerDownloader
import json
# 1. 实例化下载器
# 确保 dll/so 文件在当前目录或系统路径中
downloader = TaiLerDownloader()

# 2. 定义回调函数
# event_dict: 包含事件类型(Type)、任务ID(ID)等元数据
# msg_dict: 包含具体的进度数据(Total, Downloaded)或错误信息

def progresscallback(eventdict, msgdict):
eventtype = eventdict.get("Type")

<span class="hljs-keyword">if</span> event_type == <span class="hljs-string">"update"</span>:
<span class="hljs-comment"># 进度更新</span>
total = msg_dict.get(<span class="hljs-string">"Total"</span>, <span class="hljs-number">0</span>)
downloaded = msg_dict.get(<span class="hljs-string">"Downloaded"</span>, <span class="hljs-number">0</span>)
<span class="hljs-keyword">if</span> total &gt; <span class="hljs-number">0</span>:
percent = (downloaded / total) * <span class="hljs-number">100</span>
<span class="hljs-built_in">print</span>(<span class="hljs-string">f"\r进度: <span class="hljs-subst">{percent:<span class="hljs-number">.2</span>f}</span>% (<span class="hljs-subst">{downloaded}</span>/<span class="hljs-subst">{total}</span>) 字节"</span>, end=<span class="hljs-string">""</span>)
<span class="hljs-keyword">elif</span> event_type == <span class="hljs-string">"endOne"</span>:
<span class="hljs-builtin">print</span>(<span class="hljs-string">f"\n文件下载完成: <span class="hljs-subst">{msgdict.get(<span class="hljs-string">'ShowName'</span>)}</span>"</span>)
<span class="hljs-keyword">elif</span> event_type == <span class="hljs-string">"msg"</span>:
<span class="hljs-builtin">print</span>(<span class="hljs-string">f"\n消息: <span class="hljs-subst">{msgdict[<span class="hljs-string">'Text'</span>]}</span>"</span>)
<span class="hljs-keyword">elif</span> event_type == <span class="hljs-string">"err"</span>:
<span class="hljs-builtin">print</span>(<span class="hljs-string">f"\n错误: <span class="hljs-subst">{msgdict[<span class="hljs-string">'Error'</span>]}</span>"</span>)

# 3. 启动下载
# start_download 会返回一个下载器 ID
taskid = downloader.startdownload(
urls=["https://example.com/file.zip"],
save_paths=["./downloads/file.zip"],
thread_count=16,      # 线程数 (默认根据 CPU 核心数自动调整)
chunksizemb=10,     # 分块大小 (MB)
callback=progress_callback,
is_multiple=False     # 是否并行下载 (False 为顺序下载)
)

print(f"下载任务已启动，ID: {taskid}")
# 注意：主程序不能立即退出，否则后台下载线程会被终止。
# 在实际 GUI 程序中不需要此步，但在脚本中需要阻塞主线程。
input("按 Enter 退出...")

TLD 的优势

相比 TTHSD Golang 版本，TLD 提供以下改进：

性能提升

更高的下载速度：优化的异步 I/O 模型

更低的内存占用：精细的内存管理，无 GC 开销

更高的并发数：可支持数十万并发连接

更稳定的性能：无 GC 暂停，性能可预测

新增功能

Android 支持：提供完整的 JNI 接口，可在 Android 应用中调用

更安全的内存管理：Rust 的所有权机制确保内存安全

自动重试机制：指数退避策略，可配置重试次数和延迟

速度限制：支持设置下载速度上限

代理支持：HTTP/HTTPS/SOCKS5 代理

性能统计：实时监控下载速度、流量等数据

Headers 支持：全局和任务级别 HTTP 请求头

SFTP 主机密钥验证：增强安全性

内部模块

metrics.rs: Prometheus 指标导出

logging.rs: 结构化日志（基于 tracing）

progress_tracker.rs: 统一进度追踪

buffer_pool.rs: Buffer 对象池

adaptive_concurrency.rs: 自适应并发控制

兼容性

调用方式相同：API 接口与 TTHSD Golang 完全兼容

直接替换：只需替换动态库文件即可迁移

TLD Core 是一个高性能的多线程下载器内核