从 200KB/s 到 7MiB/s：一个下载工具的架构演进（Claude Code / OpenClaw 可用）

痛点

你在 Claude Code、OpenClaw、Hermes 这类 AI 编程助手里让 AI 帮你下载 GitHub 文件、模型权重、数据集——结果几十 KB/s，甚至直接超时。

Motrix、Xget、IDM 都是给人用的——有 GUI，要点按钮。AI 助手调不了。

小龙下载器就是填这个坑的。装好之后完全不用管 —— AI 识别到下载意图自动激活，自己测速选镜像，自己切引擎，自己校验归档。你看不到它，但它一直在。

本文聊的是这套自动化背后怎么做到的——三级引擎回退、镜像健康检测、直接 I/O、加权分片分配。

对比图.png

引擎三层回退：为什么不能只用一个

一开始用 Python urllib，很快发现：

纯 Python HTTP 解析，GIL 限制并发
单连接最多 20-30 MB/s（千兆宽带完全浪费）
断连、超时需要手动重试，代码越写越臃肿

最终设计了三级引擎：

aria2c (C++)  ← 工业级，16路多源聚合，自动容错
    ↓ 不可用时回退
curl (C)      ← 系统自带，直接I/O写入
    ↓ 不可用时回退
urllib (Py)   ← 纯Python，兼容保底

每层封装统一接口，上层不可用时自动降级。aria2c 比 urllib 快 20 倍以上，且自带断点续传和动态负载均衡。

镜像健康检测：自动筛掉装死的站

GitHub 镜像站是社区维护的，随时可能挂。我们做了四道防线：

并发测速 — 10+ 镜像同时发 256KB 采样，3 秒内全测完
健康判死 — 返回 HTML 而非二进制？拉黑。Content-Length 异常？拉黑
会话缓存 — 同 host 5 分钟内复用结果，避免重复探测
自动持久化 — 黑名单全局生效，下次启动直接用

跑一天自动筛掉 3 个失效镜像。原来 v3.0 的 10 个镜像里，gh.con.sh 被封禁，ghps.cc 不支持 Range 请求，全被自动标记。

直接 I/O：消灭临时文件

传统多线程下载：每个分片存临时文件 → 全部下完串行合并。182MB 文件产生 364MB 磁盘写入。

我们改成 os.lseek + os.write 直接定位：

# 预分配稀疏文件（不占实际磁盘）
f.truncate(file_size)

# 每个线程写自己的偏移位置，互不重叠，无需锁
fd = os.open(path, os.O_WRONLY | os.O_BINARY)
os.lseek(fd, start_offset, os.SEEK_SET)
os.write(fd, data)   # 原子写入
os.close(fd)

磁盘写入减半，合并步骤直接消失。Windows 上 os.pwrite 不可用，用 lseek + write 替代，效果完全一样。

加权分片分配

多个镜像速度差异巨大时，均分分片是反优化：

2.1 MB/s 的镜像 → 分 6 个分片
0.8 MB/s 的镜像 → 分 2 个分片
0.5 MB/s 的镜像 → 分 1 个分片

aria2c 激活后更智能 —— 16 个连接动态分配，哪个源快就自动多给它数据，无需手动调参。

实测

文件	大小	引擎	耗时	平均速度	峰值
JDK 17	182MB	urllib 直连	超时	~200KB/s	-
JDK 17	182MB	curl 多源	44s	4.2 MB/s	5.2 MB/s
JDK 17	182MB	aria2c	43s	4.4 MiB/s	7.2 MiB/s

速度上限在镜像端带宽，非客户端。直连高速 CDN 时 aria2c 能跑满千兆。

对比图.png

生态位：为什么不是又一个下载器

	Motrix	Xget	github_down	小龙
哪里用	桌面双击	浏览器	命令行	Claude Code / OpenClaw 里直接说句话
引擎	aria2	Cloudflare	aria2c	aria2c→curl→urllib 三级
触发方式	手动	手动	手动	说"下载"就自动激活
安全扫描	无	无	无	SHA256 + 病毒扫描
智能分类	无	无	无	8类自动归档

项目地址

GitHub: github.com/buxu777/xia…
Gitee: gitee.com/buxu777/xia…

MIT 开源，欢迎 Star / Issue / PR。

小龙下载器 —— 让 Claude Code、OpenClaw 等 AI 助手拥有工业级下载能力

标签：Python、开源、Claude Code、OpenClaw、Hermes、架构设计、下载工具、GitHub加速、aria2