dsh-smart-download
leisureyu/dsh-smart-download
Multi-threaded downloader plugin for DeepSeek Harness: bundles aria2, probes file size and picks aria2 multi-connection or curl fallback automatically (Windows x64/arm64, Linux x64/arm64)
インストール
dsh plugin --profile web add github:leisureyu/dsh-smart-downloadREADME
dsh-smart-dl
简体中文 · English
给 DSH 装上一个内置 aria2 的下载器。 一条命令装好，不用自己配环境：大文件自动多线程加速，服务器不支持就自动回退，中途断了还能续传。
dsh plugin --profile web add @leisureyu/dsh-smart-dl
- 自动多线程加速 —— 下载前先探测目标服务器，支持多连接就调用内置
aria2c并发下载，不支持则自动回退到系统curl，两种情况都能下完。 - 零配置 —— aria2 二进制随插件一起安装（npm
optionalDependencies），无需自行下载或配置 PATH。 - 进度看得见 ——
webprofile 下界面右下角有实时进度面板（文件名 / 百分比 / 速度 / 剩余时间），下载完成后自动消失。 - 断点续传 —— 中断后用同样的
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 名称。
进度面板只在
webprofile 生效。 其他 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新增webprofile 的实时进度面板，并修复了面板显示任务 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任务不再计入面板，避免历史残留文件让面板永久卡住。
该面板仅
webprofile 提供；CLI 等 profile 下插件会静默跳过客户端注册，工具与下载功能不受影响。
设计上的静默失败防护
开发过程中实测发现了三个同类型的静默失败：
- aria2 摘要格式变化：关闭 readout 后，GID 变为十六进制、无
SIZE:前缀、速度字段由SPD:变为DL:； - curl
--silent抑制进度：即使进度走 stderr，--silent也会把--progress-bar一并压掉； - 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：
binaries-windows（windows runner）：下载 Windows x64 / arm64 二进制并校验 SHA256；binaries-linux（ubuntu runner）：下载 Linux x64 / arm64 静态二进制、校验 SHA256、chmod 755；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、Repositorydsh-smart-download、Workflowpublish.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