dsh-smart-download

dsh-smart-dl

简体中文 · English

给 DSH 装上一个内置 aria2 的下载器。 一条命令装好，不用自己配环境：大文件自动多线程加速，服务器不支持就自动回退，中途断了还能续传。

dsh plugin --profile web add @leisureyu/dsh-smart-dl

• 自动多线程加速 —— 下载前先探测目标服务器，支持多连接就调用内置 aria2c 并发下载，不支持则自动回退到系统 curl，两种情况都能下完。
• 零配置 —— aria2 二进制随插件一起安装（npm optionalDependencies），无需自行下载或配置 PATH。
• 进度看得见 —— web profile 下界面右下角有实时进度面板（文件名 / 百分比 / 速度 / 剩余时间），下载完成后自动消失。
• 断点续传 —— 中断后用同样的 url + output 再调用一次即可续传。
• 进度可查询 —— download_status 工具只读查询最近任务的百分比 / 速度 / ETA。

支持 Windows x64 / arm64 与 Linux x64 / arm64；请使用 0.4.2 或更新版本。

dsh-smart-dl 为 DeepSeek Harness（DSH） 注册两个工具：

• smart_download：下载文件。先探测目标服务器是否支持多线程，支持则调用随插件分发的 aria2c 多线程加速，否则自动回退到系统自带的 curl 单线程下载，保证任何情况下都能完成下载。可选镜像加速与断点续传。
• download_status：查询下载进度。只读地返回最近任务的状态快照（百分比、速度、ETA），可用来回答“刚才那个下载到百分之几了”。

安装

dsh plugin --profile web add @leisureyu/dsh-smart-dl

安装后无需任何额外配置：aria2 二进制通过 npm 的 optionalDependencies 机制随插件一起安装。

支持的 profile：web（上面的 --profile web 即为此插件验证过的 profile）。安装命令形如 dsh plugin --profile <profile> add <包名>，请把 <profile> 换成你实际使用的 profile 名称。

进度面板只在 web profile 生效。 其他 profile 下插件功能完全不受影响，只是没有界面面板，仍可用 download_status 工具查询进度。

版本要求：请使用 0.4.2 或更高。 0.4.2 修了三个实测缺陷：① 探测不到文件大小时返回 size: undefined，会被宿主判为非法 JSON 并抛 ToolOutputError（下载其实已成功）；② URL 路径穿越（..%2F..%2F..%2Fescaped.txt）会把文件写到工作目录之外；③ 缺少协议白名单，file:// 会被 curl 接受并复制本地文件。0.4.1 修正了 peerDependencies 的版本范围：此前 @deepseek-ai/cordis 写作 ^4.0.0、三个 @deepseek-ai/dsh-client-* 写作 >=0.1.7-rc.1 <0.2.0-0，当 harness 走到 0.2.0-rc.1（next 标签）或 cordis 用到 4.0.1-rc.x 时，这些范围会静默排除该预发布版本并导致 npm error ERESOLVE；现已改成带显式预发布分支的 || 范围。0.4.0 新增 web profile 的实时进度面板，并修复了面板显示任务 ID 而非文件名、以及陈旧任务永久卡住面板的问题。0.2.0 起支持 Windows arm64 与 Linux x64 / arm64（此前仅 Windows x64）；更早的 0.1.1 / 0.1.3 / 0.1.4 在 DSH 插件清单或工具 schema 上存在缺陷，会导致两种失败：安装被拒（Cannot validate installed package ... dsh.bundle.patch），或装上了但激活失败（启动日志出现 did not activate）。完整变更记录见 CHANGELOG.md。当前发布版本见顶部版本徽章；如需固定，可写 @leisureyu/dsh-smart-dl@0.4.2。

0.2.1 另修复了一个必然安装失败的问题：此前 peerDependencies 中 @deepseek-ai/dsh-tools 写作 ^0.1.0，而该包从未发布过 0.1.x 正式版（实际可用版本均为预发布版），导致该范围解析不到任何版本，安装时报 npm error notarget No matching version found for @deepseek-ai/dsh-tools@^0.1.0。

工作原理

下载决策流程（文字版）：

调用 smart_download(url, output?, mirror?)
        │
        ▼
[0] 若传入 mirror，则把原始 URL 拼到镜像前缀后
     · 镜像前缀 + 完整原始 URL
     · 非 http(s) URL 不走镜像
     · 输出文件名仍按原始 URL 推导
        │
        ▼
[1] 探测 URL（超时 5s）
     · 先发送 HEAD 请求
     · 若 HEAD 返回 405 或缺少 Content-Length，
       则改用 GET + "Range: bytes=0-0"
        │
        ▼
[2] decide() 按文件大小与 aria2 可用性分档：
     · 不支持 Range / 探测失败 / 无法获取大小 / <1MB  -> curl
     · 1MB ~ 50MB  -> aria2 4 连接
     · ≥ 50MB       -> aria2 8 连接（保守上限，不开 16）
        │
   ┌────┴──────────────────────────┐
   ▼ aria2 档                       ▼ curl 档
[3a] 能定位到随包 aria2c？         [3b] curl 单线程（含进度条）
   │ 是              │ 否
   ▼                 ▼
 aria2 4/8 连接     curl 单线程（回退）
 （每秒摘要进度）
 （-c 续传）        （支持 Range 时 -C - 续传）
   │ 失败
   ▼
 降级为 curl 单线程（回退）
        │
        ▼
 返回结果 { success, path, method, size, fellback, reason?, requestedUrl, mirrored }

要点：

• 任何探测异常（超时、网络错误、无法获取文件大小）都会被安全地判定为“不支持多线程”，从而走 curl 回退，不会让下载直接失败。
• 并发数随文件大小动态选择（阈值 1MB / 50MB），reason 会区分“不支持 Range”“文件太小”“aria2 缺失”等情况。
• 返回的 requestedUrl 是实际请求的地址（启用镜像时为「镜像前缀 + 原始 URL」），mirrored 标明本次是否走了镜像。
• 只允许 http / https：URL 来自模型读到的任意页面，属于不可信输入。其他协议（file:、ftp: 等）在下载开始前直接被拒绝，不会进入探测或下载流程。
• 输出文件名会被净化：未传 output 时按 URL 推导文件名，推导结果只取单个路径段——URI 解码后的 /、\、.. 等一律丢弃，因此不会写到工作目录之外。

为什么必须做协议白名单与文件名净化（实测结论，勿移除）

0.4.1 实测：file:///C:/Windows/win.ini 会被 curl 接受并成功复制本地文件到目标路径； http://host/..%2F..%2F..%2Fescaped.txt 会解码出 ../../../escaped.txt，未指定 output 时 文件被写到当前工作目录之外（实测确认写入成功）。两者都在 0.4.2 修复：前者由协议白名单 拦截，后者由「解码后再切分、只取最后一段 + 净化」拦截。

镜像加速

下载 GitHub Release 等境外资源较慢时，可给 smart_download 传入 mirror 前缀，插件会把原始 URL 拼到该前缀后面再下载：

smart_download(
  url: "https://github.com/owner/repo/releases/download/v1/a.zip",
  mirror: "https://gh-proxy.com/"
)
# 实际请求：https://gh-proxy.com/https://github.com/owner/repo/releases/download/v1/a.zip

细节：

• 只做前缀拼接，不做路径改写，因此适配绝大多数「前缀 + 完整原始 URL」形式的公开镜像；
• 前缀缺尾斜杠会自动补上，也可直接写裸域名（ghfast.top 会补成 https://ghfast.top/）；
• 非 http(s) 的 URL 不使用镜像；
• 输出文件名始终按原始 URL 推导，不会把镜像域名带进文件名。

常见的公开镜像（任选其一，可用性随网络环境变化）：

镜像前缀
https://gh-proxy.com/
https://ghfast.top/
https://ghproxy.net/

镜像是第三方服务：请求内容会经过该镜像服务器，请勿用它下载含敏感信息的文件。

断点续传

下载中断后再次调用 smart_download（同样的 url 与 output）会从断点继续，而不是从头重下：

• aria2 路径：始终启用 -c。不支持 Range 的服务器 aria2 会自行全量重下，不会失败。
• curl 路径：仅在探测确认服务器支持 Range 时才加 -C -。

为什么 curl 的续传是条件式的（实测结论，勿改成无条件）：

curl -C - 在服务器不支持 Range 且本地已存在半截文件时，会以退出码 33 直接失败——实测：1000 字节资源、已有 400 字节半包 → exit 33，文件保持 400 字节不损坏；而同一场景不带 -C - 能正常全量重新下载成功。 支持 Range 时三种情况均实测正确：半包续传、已下载完整后重跑、文件不存在从头下。

查询下载进度：download_status

download_status 只读地返回本插件下载任务的状态快照，可用来回答“刚才那个下载到百分之几了”。

download_status()                      # 列出最近 10 个任务
download_status(limit: 3)              # 只列最近 3 个
download_status(taskId: "dl-xxx")      # 只查指定任务

返回示例：

{
  "ok": true,
  "taskDir": "/path/.dsh-progress/default",
  "downloadDir": "/home/u/.dsh/downloads/tasks",
  "total": 1,
  "tasks": [
    {
      "id": "dl-mulfpr76-z47a",
      "name": "local-24MiB.bin",
      "pct": 100,
      "msg": "下载完成",
      "status": "completed",
      "spd": "8.2MB/s",
      "eta": "",
      "updatedAt": 1759000000000
    }
  ]
}

约束与设计取舍：

• 纯只读：不写文件、不联网。读取的就是「进度上报」那一节里的两条轨道目录。
• 容错优先：目录不存在、权限不足、文件内容损坏，都退化为「该任务不出现在结果里」，整个调用依然成功返回（只是任务列表更短），不会因为查状态而让下载失败。
• 任务按 updatedAt 倒序，最新的排在最前；total 是未截断的真实总数，tasks 会被 limit 截断。
• name 是输出文件名（面板与列表显示用），未知时回退为任务 ID。
• spd / eta 在不支持或未知时返回空字符串（schema 要求 string），不会返回 null 或 undefined。

进度上报

下载过程中通过 ProgressReporter 双轨写入进度，任一轨道不可写都静默容错，不影响下载：

• 轨道一（dsh-task-progress 格式）：$DSH_PROGRESS_DIR/<taskId>.jsonl，每行一条 JSON，append-only；
• 轨道二（dsh-download-progress 格式）：$DSH_DOWNLOAD_PROGRESS_DIR/<taskId>.json，缺省为 ~/.dsh/downloads/tasks/<taskId>.json，整体覆盖写。

进度按百分比去重，完成 / 失败终态会穿透去重。aria2 解析 --summary-interval=1 的摘要行（含速度与 ETA），curl 解析 --progress-bar 的百分比。

界面进度面板（web profile）

在 web profile 下，插件会在界面右下角挂载一个实时进度面板：只要有下载在进行就自动出现，显示输出文件名、百分比、传输速度与剩余时间；下载完成后短暂显示「已完成」回执，然后自动消失。空闲时不占位、不显示。

实现要点（如遇面板不显示，可据此排查）：

• 走宿主 RPC：客户端通过 connection.fetch.register 注册的 /api/smartdl.status 拉取进度快照，与 download_status 工具读的是同一份进度文件。
• 插槽：注册到 shell.overlay（kind: 'list'，order: 100），因此不会覆盖宿主自身界面；无内容时渲染为 null。
• 只依赖 react：客户端脚本以 classic script 形式通过 window.__ModuleLoader__.load 注册，不做打包。
• 陈旧任务自动忽略：超过 10 分钟没有更新的 running 任务不再计入面板，避免历史残留文件让面板永久卡住。

该面板仅 web profile 提供；CLI 等 profile 下插件会静默跳过客户端注册，工具与下载功能不受影响。

设计上的静默失败防护

开发过程中实测发现了三个同类型的静默失败：

1. aria2 摘要格式变化：关闭 readout 后，GID 变为十六进制、无 SIZE: 前缀、速度字段由 SPD: 变为 DL:；
2. curl --silent 抑制进度：即使进度走 stderr，--silent 也会把 --progress-bar 一并压掉；
3. aria2 临近完成时省略 ETA：快完成的摘要行整体不输出 ETA 字段。

它们都不是逻辑错误，而是对外部程序真实行为的假设错了：逻辑都对、测试都绿、下载也成功，只是某个环节悄悄返回了默认值（“不支持” / curl / null / 跳过写入）。这类问题的危险在于退出码仍是 0，“不抛错”的测试永远抓不住。

契约：本插件所有“返回默认值”的路径——

环节	静默失败形态	必须断言的正向信号
probeUrl	探测异常 → 不支持	已知支持的 URL 必须返回 supportsMultiThread: true
decide	分支遗漏 → 落 curl	已知大文件必须返回 method: 'aria2'
parseAria2Summary	认不出 → null	真实样本必须解析出 pct/spd(/eta)
parseCurlProgress	认不出 → null	真实样本必须解析出单调递增到 100% 的百分比
ProgressReporter	目录不可写 → 跳过	可写目录必须存在文件且内容递增
LineBuffer	切分状态错误	跨 chunk / \r / \r\n 边界必须切出正确的行
applyMirror	拼错 → URL 仍合法	拼接结果必须可 new URL() 解析，且以原始 URL 结尾
readDownloadStatus	读不到 → 空列表	目录里有合法任务文件就必须扫出并解析出字段
buildCurlArgs	续传开关插错位置	resume 为真时 -C - 必须存在，为假时必须不存在，且 -o 与路径紧邻
checkDownloadUrl	不校验协议 → 读本地文件	file:// / ftp:// 必须被拒绝，http(s) 必须被放行并返回解析后的 URL
deriveFilenameFromUrl	不净化 → 路径穿越	..%2F..%2F..%2Fescaped.txt 必须推导为单段 escaped.txt，且实际写入不得逃出当前目录

所有断言都是正向的：检查“有没有真的产出”，而不是“有没有崩溃”。真实样本保存在 test/fixtures/（curl 为保留 \r 的 .bin），并对“fixture 必须含 \r”做了强制断言。

如果未来发现某条返回默认值的路径没有被正向信号断言覆盖，那是一个 bug，不是设计。把正向断言改回“只要不报错就行”，等于重新打开静默失败的后门。

此外，test/meta-test-discovery.test.ts 会枚举 test/ 下所有测试文件，并断言 test 脚本（glob）确实覆盖它们——连“CI 是否真的跑了这些测试”这一层本身也被强制验证，防止防护措施自己在 CI 里静默失效。

支持平台

平台	架构	是否支持	二进制子包
Windows	x64	✅ 支持	@leisureyu/dsh-aria2-win32-x64
Windows	arm64	✅ 支持	@leisureyu/dsh-aria2-win32-arm64
Linux	x64	✅ 支持	@leisureyu/dsh-aria2-linux-x64
Linux	arm64	✅ 支持	@leisureyu/dsh-aria2-linux-arm64
macOS	x64 / arm64	❌ 暂不支持	—

二进制子包通过 os / cpu 字段声明，npm / pnpm 在不匹配的平台上会自动跳过安装。

权限说明

本插件只做两件事：发起下载与写进度文件。逐项说明如下。

行为	说明
网络出站请求	仅接受 http / https，其他协议在下载前直接拒绝（checkDownloadUrl）。对通过校验的 URL 发起 HEAD / Range 探测（probeUrl，5s 超时），以及实际下载（aria2c 或系统 curl）。仅访问调用方传入的 URL，不访问其他地址。
写入下载文件	写入 output 参数指定的路径；未指定时由 URL 推导文件名，落在当前工作目录。推导结果必定是单个路径段（/、\、.. 等被丢弃，并替换 Windows 非法字符、规避保留设备名），因此不会写到工作目录之外。父目录不存在时会自动创建（mkdir -p）。不会删除任何已有文件。启用断点续传后，同名文件会被续写而非重头覆盖；未启用 --allow-overwrite，因此不会静默丢弃已完成的同名文件。
读取进度文件	download_status 只读取上述两条进度轨道目录，不写文件、不联网。
写进度文件	轨道一 $DSH_PROGRESS_DIR/<taskId>.jsonl（若未设置该环境变量则不写）；轨道二 $DSH_DOWNLOAD_PROGRESS_DIR/<taskId>.json，缺省为 ~/.dsh/downloads/tasks/<taskId>.json。目录不可写时静默跳过，不影响下载。
子进程	启动随包 aria2c 或系统 curl，均以 windowsHide: true 启动（不弹控制台窗口），并响应 AbortSignal 取消（先 SIGTERM，Windows 上 1s 内未退出则强制 kill）。
读取环境变量	仅读取 DSH_PROGRESS_DIR、DSH_DOWNLOAD_PROGRESS_DIR、USERPROFILE / HOME。

不需要的权限：不读取 DSH 会话内容、不访问凭证或密钥、不修改 DSH 配置（仅在安装时由 DSH 自身应用 cordis.patch.yml）、无遥测与联网上报。

兼容性

项目	要求
Node.js	>=22.0.0（用到 AbortSignal.any / AbortSignal.timeout）
@deepseek-ai/cordis	^4.0.0（peerDependency）
@deepseek-ai/dsh-tools	>=0.1.7-rc.1 <0.1.8-0 或 >=0.2.0-rc.1 <0.3.0-0（peerDependency；该包只发布预发布版，因此按元组显式声明）
npm 包管理器	npm / pnpm 均可；需支持 optionalDependencies 的 os / cpu 过滤

macOS 未列入支持平台：不是兼容性问题，而是缺少对应的 aria2 二进制子包。在 macOS 上插件仍可安装并正常工作，但 getAria2Path() 返回 null，所有下载都会走 curl 单线程回退（返回结果的 reason 会写明原因）。

常见问题

Q：安装或运行时被 Windows Defender（或其他杀毒软件）拦截？ A：这是对 node_modules 内未签名 aria2c.exe 的常见启发式告警。可将项目的 node_modules 目录加入 Windows Defender 的白名单（“病毒和威胁防护 → 管理设置 → 排除项”）。aria2c.exe 均未做任何修改：Windows x64 取自 aria2 官方发布包，Windows arm64 取自第三方 ARM64 构建（见下方“第三方组件声明”）。

Q：下载速度没有提升？ A：通常是目标服务器不支持 Range 请求（无法分片），或文件本身较小。插件会自动回退到 curl 单线程下载；返回结果中的 fellback 与 reason 字段会说明具体原因。

Q：提示找不到 aria2 / 始终走 curl？ A：请确认当前平台属于上表四行之一（Windows x64 / arm64、Linux x64 / arm64），且 optionalDependencies 中对应的二进制子包安装成功（部分镜像源可能未同步该包，可切换官方 npm 源后重装）。返回结果的 reason 字段会说明具体原因。macOS 暂不支持，将始终回退 curl。

Q：Linux 上提示 aria2c: Permission denied？ A：这是 tarball 里二进制缺少可执行位。本项目在 CI 中于 Linux runner 上打包并强制断言 bin/aria2c 为 0755，正常安装不会出现；若你手动重打包过，请在打包前 chmod 755。

Q：下载会弹黑色命令行窗口吗？ A：不会。子进程均以 windowsHide: true 启动。

Q：怎么知道下载到百分之几了？ A：调用 download_status，它会返回最近任务的百分比、速度与 ETA。传 taskId 可只查某一个任务。它是纯只读的，不会影响正在进行的下载。

Q：GitHub Release 下载太慢，能用镜像吗？ A：可以。给 smart_download 传 mirror 前缀即可，例如 mirror: "https://gh-proxy.com/"。请注意镜像是第三方服务，不要用���下载含敏感信息的文件。

Q：下载中断后要重新开始吗？ A：不需要。用同样的 url 与 output 再调用一次 smart_download，支持 Range 的服务器会从断点继续。

开发

环境要求：Node.js 22+、pnpm 9+。

# 安装依赖
pnpm install

# 本地构建（输出到 dist/）
pnpm build

# 运行测试（node:test，不依赖真实网络）
pnpm test

# 仅类型检查
pnpm typecheck

本地开发时，各平台的二进制需要手动放置（这些二进制不入库），下载地址与目标路径：

平台	下载	放置到
Windows x64	https://github.com/aria2/aria2/releases/download/release-1.37.0/aria2-1.37.0-win-64bit-build1.zip	packages/aria2-win32-x64/bin/aria2c.exe
Windows arm64	https://github.com/minnyres/aria2-windows-arm64/releases/download/v1.37.0/aria2_1.37.0_arm64.zip	packages/aria2-win32-arm64/bin/aria2c.exe
Linux x64	https://github.com/abcfy2/aria2-static-build/releases/download/1.37.0/aria2-x86_64-linux-musl_static.zip	packages/aria2-linux-x64/bin/aria2c
Linux arm64	https://github.com/abcfy2/aria2-static-build/releases/download/1.37.0/aria2-aarch64-linux-musl_static.zip	packages/aria2-linux-arm64/bin/aria2c

Linux 二进制解压后记得 chmod 755，否则本地 npm pack 出来的 tarball 也会缺少可执行位。

发布

推送 v* tag 即触发 GitHub Actions（.github/workflows/publish.yml），分三个 job：

1. binaries-windows（windows runner）：下载 Windows x64 / arm64 二进制并校验 SHA256；
2. binaries-linux（ubuntu runner）：下载 Linux x64 / arm64 静态二进制、校验 SHA256、chmod 755；
3. publish（ubuntu runner）：还原上述二进制 → 构建 → 测试 → 先发布全部二进制子包，再发布主包（主包依赖子包，顺序不可颠倒）。

发布必须在 Linux 上完成：npm 打包会记录文件执行位，在 Windows 上打包会把 bin/aria2c 记成 0644，装完直接调用会失败。CI 里对此有正向断言（tarball 中 bin/aria2c 必须是 -rwxr-xr-x）。

认证采用「先 OIDC、后 token」双保险：每个包先尝试 npm trusted publishing（OIDC，无需长期 token）；失败则回退仓库密钥 NPM_TOKEN——新包首次发布无法用 OIDC 引导（npm/cli#8544 仍未修复），必须用 token，之后即可只靠 OIDC。

启用 OIDC 需要在 npm 网页为每个包配置 Trusted Publisher（Organization or user LeiSureYu、Repository dsh-smart-download、Workflow publish.yml，并勾选允许直接 npm publish）。配置前流水线会自动走 token 回退，不会失败。

注意：本仓库已使用 npm scope @leisureyu。如需改换 scope，需同步修改主包 optionalDependencies、子包 name、src/downloader.ts 中的 ARIA2_PACKAGE 以及 test/downloader.test.ts 中的断言。

第三方组件声明

本插件分发的 aria2c 均来自 aria2 1.37.0，aria2 依据 GPL-2.0-or-later 许可，各二进制子包同样声明为 GPL-2.0-or-later。

aria2 官方仅提供 Windows x64 与源码包，因此另外三个平台使用第三方构建（均未做任何修改，仅原样分发）：

平台	来源	压缩包 SHA256
Windows x64	aria2 官方发布包	67d015301eef0b612191212d564c5bb0a14b5b9c4796b76454276a4d28d9b288
Windows arm64	minnyres/aria2-windows-arm64 v1.37.0	5694080902fff84c8636e561c48f7a65278e8d4f05efefe953637f60a397c81f
Linux x64	abcfy2/aria2-static-build 1.37.0（musl 静态）	e0a09b12ef67f35f8a8e4fdddbec851d235b7c31da549d0578bff459032b499a
Linux arm64	abcfy2/aria2-static-build 1.37.0（musl 静态）	0c681a89a40e0f82d1f5137608e86257eb0af201459c002941ea098f2b8c26b6

声明

本项目为社区维护的第三方插件，非官方项目，与 DeepSeek AI 及其关联公司无隶属关系，也未获其背书或赞助。插件名称中的 "dsh" 指代其运行所依托的 DeepSeek Harness（DSH）平台，仅用于说明兼容性。

License

• 本插件代码：MIT
• 随包分发的 aria2 二进制：GPL-2.0-or-later