L
dsh-smart-download
leisureyu/dsh-smart-download
DSH 多线程下载插件，内置 aria2：先探测目标是否支持 Range，再按文件大小选择 aria2（4 或 8 连接）或回退 curl 单线程下载。
安装
dsh plugin --profile web add github:leisureyu/dsh-smart-downloadREADME
dsh-smart-dl
简体中文 · English
给 DeepSeek Harness（DSH）装一个内置 aria2 的下载器: 大文件自动多线程、不支持就自动回退 curl、断了能续传、照官方文档核对摘要。 Windows / Linux / macOS 六平台完整支持；HarmonyOS（鸿蒙）1.9.1 起可用。
安装
在 DSH 侧边栏 插件 → 添加插件 粘贴包名，装完重启 DSH:
@leisureyu/dsh-smart-dl
命令行（桌面版请用桌面版自带的 CLI）:
dsh plugin --profile web add @leisureyu/dsh-smart-dl
快速开始
基本下载 —— 自动探测、多线程、断点续传:
smart_download({ "url": "https://example.com/tool-1.4.0.zip" })
照官方文档核对 —— 摘要 + 镜像（GitHub 慢时自动选一个被证实同源的镜像）:
smart_download({
"url": "https://github.com/owner/repo/releases/download/v1.4.0/tool.zip",
"sha256": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
"mirror": "auto"
})
一次一批 —— 并发下载、整批限速、单条超时，一条失败不影响其余:
smart_download({
"targets": [
{ "url": "https://example.com/a.iso", "output": "a.iso" },
{ "url": "https://example.com/b.iso", "sha256": "…" }
],
"maxBandwidth": "4M",
"timeoutMs": 600000
})
后台执行 —— 立即返回 taskId，不占会话，进度面板照常显示:
smart_download({ "url": "https://example.com/big.iso", "background": true })
// 用 download_status(taskId) 查进度;管理器里可取消 / 重试
功能一览
| 功能 | 用法 |
|---|---|
| 多线程加速（按大小 4/8 连接，自动回退 curl） | 默认行为；1.9.0 起走常驻 RPC daemon，暂停/继续为原地语义 |
| 断点续传（同源指纹校验，防「续错文件」） | 默认行为 |
| 摘要校验 | sha256 或 checksum（MD5 / SHA-1 / SHA-256 / SHA-512） |
| 期望大小核对 | expectedSize |
| 镜像加速（自动选择，先证实同源再采用） | mirror: "auto" |
代理（探测 / 镜像 / 下载三层一致，支持 NO_PROXY） | proxy |
| 一次下载一批 | targets + maxBandwidth + timeoutMs |
| 暂停 / 继续（半包与指纹保留，从断点续传） | 下载管理器行内按钮 |
| 自动镜像按实测延迟排序（同源校验不变） | mirror: "auto" 默认行为 |
| 一键重试全部失败项 | 下载管理器工具栏按钮 |
| 后台执行 | background: true |
| 同名文件策略 | ifExists: "overwrite" | "skip" | "rename" |
| 自定义请求头（凭证走 stdin，不进命令行） | userAgent / referer / headers |
| 服务器文件名 / 磁盘空间预检 | 默认行为 |
smart_download 参数
| 参数 | 类型 | 说明 |
|---|---|---|
url / targets | string / array | 二选一。批量最多 50 条，逐条结果、部分成功。 |
output | string | 输出路径；缺省依次取 Content-Disposition、查询串、URL 末段。 |
sha256 / checksum | string | 期望摘要。接受裸 hex、sha256:<hex>、SRI 等写法；不匹配即失败。 |
checksum | string | 同上，另支持 MD5 / SHA-1 / SHA-512（按长度识别）。与 sha256 二选一。 |
expectedSize | integer | 期望字节数（官方文档里印的那个）。与远端声明冲突则发请求前拒绝。 |
ifExists | string | overwrite（默认）/ skip / rename。 |
mirror | string | 镜像前缀（如 https://gh-proxy.com/）或 "auto" 自动挑选。 |
proxy | string | http(s) 代理地址。探测与下载共用；缺省读 HTTPS_PROXY 等环境变量。 |
userAgent / referer / headers | string / object | 附加请求头，探测与下载共用。 |
maxBandwidth | string | 整次调用的带宽上限，如 "2M"、"500K"、"1500000"。 |
timeoutMs | integer | 单条目超时（1000–1800000ms）。 |
background | boolean | 后台执行，立即返回 taskId / 批次 ID。 |
download_status 参数
| 参数 | 说明 |
|---|---|
taskId | 只查某一个任务。 |
batchId | 按批次过滤（后台批量返回的 ID）。 |
limit | 最多返回条数（默认 10）。 |
环境变量
| 变量 | 作用 |
|---|---|
DSH_SMARTDL_MIRRORS | 覆盖自动镜像候选表（逗号分隔，顺序即优先级）。 |
DSH_SMARTDL_ARIA2_PATH | 显式指定 aria2 二进制路径，优先于随包子包与 PATH（验证失败则回退 curl，不回落其它来源）。 |
HTTPS_PROXY / HTTP_PROXY / ALL_PROXY | 未传 proxy 参数时的代理来源。 |
NO_PROXY | 命中的主机直连（对显式 proxy 参数同样生效）。 |
DSH_PROGRESS_DIR / DSH_DOWNLOAD_PROGRESS_DIR | 覆盖两条进度轨道的目录。 |
支持平台
| 平台 | 架构 | 子包 | 状态 |
|---|---|---|---|
| Windows | x64 / arm64 | @leisureyu/dsh-aria2-win32-* | ✅ 完整支持 |
| Linux | x64 / arm64 | @leisureyu/dsh-aria2-linux-* | ✅ 完整支持 |
| macOS | x64 / arm64 | @leisureyu/dsh-aria2-darwin-* | ✅ 完整支持（本仓库 CI 从官方源码构建） |
| HarmonyOS | arm64 | @leisureyu/dsh-aria2-ohos-arm64 | 🟡 1.9.1 起可用；随包子包在路线图上，当前多线程需 PATH 自备 aria2c 或 DSH_SMARTDL_ARIA2_PATH |
Windows / Linux / macOS 六个组合均为完整支持（随包 aria2 多线程），安装时包管理器按
os / cpu 自动只装当前平台的那一个子包。鸿蒙的 OpenHarmony Node 运行时报告
process.platform === 'ohos'，与 Linux 二进制不兼容（内核不同，musl 静态二进制
不能复用），因此走独立子包：1.9.1 先落位运行时识别与回退链（开箱 curl 单线程，
PATH 上有 aria2c 则自动多线程），随包二进制将由本仓库 CI 用 OHOS SDK 从官方源码
构建后发布 —— 与 macOS 子包同一信任模型，详见 COMPATIBILITY.md。
工作原理
smart_download(url, …)
│ 1. 参数校验(协议白名单/摘要/头/代理/大小)——全部在发请求之前
│ 2. 探测目标服务器(HEAD → Range GET 兜底,拿长度与 Range 支持)
│ 3. 大文件且支持 Range → 随包 aria2 多线程(4/8 连接按大小分档)
│ 否则 → curl 单线程;aria2 失败自动回退
│ 4. 完整性校验:落盘字节数 vs 声明/expectedSize;摘要 vs sha256/checksum
▼
返回 { success, path, method, size, … } 进度同时写入两条轨道,面板实时显示
所有「跳过 / 回退 / 失败」都会在返回值与进度里显式写明原因，绝不静默降级。
安全与权限
- 只接受
http(s)，协议白名单 + 重定向白名单 + 文件名净化（不可信输入一律挡在下载前） - 请求头凭证经 stdin 传给子进程，不出现在进程命令行；凭证不落盘、重试不重放
- 除「原始 URL（或镜像/代理）」外不访问任何其它地址；无遥测
- 详细威胁模型与五层防护见 SECURITY.md
兼容性
| 项目 | 要求 |
|---|---|
| Node.js | ≥ 22 |
| DSH | 0.2.x 全系（0.1.7-rc.1 起的旧版也支持）；安装/版本要求见 COMPATIBILITY.md |
常见问题
- 被 Defender 拦截？ 未签名
aria2c.exe的启发式告警，把项目node_modules加入白名单即可。 - 下载速度没提升？ 服务器不支持 Range 或文件太小，已自动回退 curl；
reason字段写明原因。 - 提示找不到 aria2？ Windows / Linux / macOS 六组合均有子包（镜像源未同步时切官方 npm 源重装）；鸿蒙当前靠 PATH 或
DSH_SMARTDL_ARIA2_PATH自备 aria2c，缺省回退 curl。 - 鸿蒙上怎么开多线程？ 1.9.1 起插件在鸿蒙开箱可用（curl 单线程）。多线程两条路：把自建的
aria2c路径填进DSH_SMARTDL_ARIA2_PATH，或放进 PATH；随包 ohos-arm64 子包在路线图上。 - GitHub 下载慢？ 传
mirror: "auto"。 - 摘要怎么核对？ 把官方文档里的摘要原样传给
sha256，四种常见写法都认。 - 重跑报退出码 33 / 36？ 33 = HTTP range error（服务器忽略/未接受你发的 Range），36 = bad download resume（无法从断点续传）。33 不代表服务器永久不支持 Range；删除半包后重跑会全量重下。
- 更多问题 → TROUBLESHOOTING.md
文档
| 文档 | 内容 |
|---|---|
| CHANGELOG.md | 每个版本的变更记录 |
| docs/COMPATIBILITY.md | 平台 / Node / 包管理器矩阵，macOS 子包的构建与信任模型 |
| docs/SECURITY.md | 威胁模型与五层防护 |
| docs/TROUBLESHOOTING.md | 症状 → 原因 → 处理 |
| docs/ARCHITECTURE.md | 内部结构与模块职责 |
开发
pnpm install
pnpm test # node:test,不依赖真实网络
pnpm build # 输出 dist/
pnpm check # 类型检查
推送 v* tag 即触发发布:三个平台的二进制 job（macOS 从官方源码自构建 OpenSSL 与 aria2，附 SLSA provenance）→ 测试 → 先发子包、再发主包。发布走 npm trusted publishing（OIDC）；新包首次发布 OIDC 无法引导，回退仓库密钥 NPM_TOKEN。
第三方组件与许可
- 本插件代码：MIT
- 随包分发的 aria2 1.37.0：GPL-2.0-or-later。来源:Windows x64 取官方发布包，Linux 取 abcfy2/aria2-static-build，Windows arm64 取 minnyres/aria2-windows-arm64，macOS 由本仓库 CI 从官方源码构建（来源与哈希见 COMPATIBILITY.md）。
- macOS 二进制另静态链入本仓库 CI 自建的 OpenSSL 3.5.4（官方源码 + SHA256 pin，Apache-2.0；aria2 自带 OpenSSL 链接例外），1.9.2 起随包分发。
声明
本项目为社区维护的第三方插件，非官方项目，与 DeepSeek AI 及其关联公司无隶属关系，也未获其背书或赞助。插件名称中的 "dsh" 仅用于说明兼容性。