前言¶
在 DSH 的插件生态中，下载进度曾经依赖右下角悬浮窗展示。这种方式会遮挡会话内容，需要手动拖拽躲避，且与 DSH 自身的侧边栏体系割裂。dsh-sidebar-downloads 是 dsh-better-sidebar 的附属插件，它将 aria2 的下载进度以正式页面形式接入侧边栏，与资源管理器、终端等页面并列，由底座统一管理。
是什么¶
这是一个把 aria2 下载进度显示在侧边栏的插件。它是 aria2 下载通道的侧边栏视图：读取 aria2-dl.js 写的任务账本（~/.dsh/downloads/tasks/*.json），并对带 gid 的记录查询 aria2 RPC 进行补正，不重复实现下载器，只负责将真实状态渲染成侧边栏页面。它与 dsh-download-guard 配套使用：守卫负责拦截非 aria2 路径，本插件负责展示路径状态。
核心功能¶
- 实时进度：进度条 + 百分比，按状态着色（进行中 / 完成 / 失败 / 已取消）。
- 速度与剩余时间：MB/s 与 ETA，仅在任务进行中显示。
- 未知大小的下载：服务器不返回
Content-Length时显示脉冲条，而非伪造百分比。 - 历史记录：完成 / 失败的任务保留在列表里，可切换「只看进行中」。
- 字节数取真实磁盘值：无宽度信息的任务以磁盘实际大小为准，进程被杀掉也不会显示错数字。
- aria2 实时补正：对带
gid的任务直接查 aria2 RPC，--no-wait入队的陈旧记录也能显示真实进度与速度。 - 暂停状态：手动暂停的任务显示「已暂停 · 百分比」并以琥珀色区分，计入「N 个已暂停」而非「进行中」。
- 在文件夹中显示：一键在资源管理器中定位已下载文件。
- 操作反馈常驻可见：失败 / 提示锚定在面板底部浮层，不会被列表滚动带走。
- 记录失效自动清理：点击失效记录自动移除并说明原因。
- 账本缺失明确提示：下载记录目录不存在时显示「文件丢失」与具体路径。
- 移除记录：只删除账本记录，已下载的文件保留。
- 详情展开：点击任意任务行展开：输出路径、来源 URL、耗时、错误信息。
安装与启用¶
前置依赖：已安装 dsh-better-sidebar（>=0.19.0）。
cd ~/.dsh && dsh plugin --profile <your-profile> add dsh-better-sidebar && dsh plugin --profile <your-profile> add "dsh-sidebar-downloads@github:BeiWay1145/dsh-sidebar-downloads"
安装后重启 DSH，然后点击侧边栏的 + 菜单，选择「下载」。构建产物已随仓库提交，无需在本地编译。
数据来源与配置¶
本插件读取 ~/.dsh/downloads/tasks/<taskId>.json 任务账本（每个下载任务一个 JSON 文件），不抓取网络、不写文件。账本现在只有 一个 写入方——aria2-dl.cjs（随 dsh-download-guard 包分发）。
面板与 aria2-dl.cjs 使用同一套环境变量与默认值，两边必须指向同一个引擎：
| 变量 | 默认 | 说明 |
|---|---|---|
ARIA2_RPC_URL |
— | 完整 URL；设置后优先于下面两项 |
ARIA2_RPC_HOST |
127.0.0.1 |
引擎主机 |
ARIA2_RPC_PORT |
16800 |
引擎端口（Motrix Next 开箱即用） |
ARIA2_RPC_TIMEOUT_MS |
1500 |
状态查询超时 |
若你的 aria2 用其他端口（例如常见的 6800），改这个变量即可。引擎不可达时，面板会显示常驻提示（含尝试的地址与要改的变量名），而不是让进度静静停住。
注意事项¶
- 插件以当前 DSH 进程权限运行，安装前应检查源码与许可证。
- 移除记录只删除账本记录，不删除已下载文件。
- 引擎不可达时自动降级为「照账本显示」，不会报错。
结语¶
dsh-sidebar-downloads 将下载状态从右下角悬浮窗中解放出来，通过侧边栏统一管理。它解决了历史记录保留、未知大小下载显示、RPC 实时补正等具体问题，与 dsh-download-guard 共同构成下载闭环。
- 源码仓库：https://github.com/BeiWay1145/dsh-sidebar-downloads
- 生态目录：https://www.skillhub.cn/plugins/BeiWay1145/dsh-sidebar-downloads
