快速了解

它能做什么

为 dsh-better-sidebar 添加 aria2 下载进度、历史、详情和文件定位功能。

本站提供的是中文说明，不代表该项目或 Plugin 自身提供中文界面；语言支持请以上游文档为准。

有代码证据的贡献

它为 DSH 增加什么

下载侧边栏标签页

新增 dsh-better-sidebar 页面，用于查看 aria2 下载实时状态、历史、详情并在文件管理器中定位文件。

机制证据 ↗

选择前先看

这个 DeepSeek Harness Web 插件将 aria2 下载状态从悬浮窗移到侧边栏页面。它读取本地任务账本；对于带 gid 的记录，会在可用时通过本地 aria2 RPC 补正状态，并展示进度、速度、剩余时间、暂停或失败状态、历史和任务详情。

适合谁

使用 aria2 下载、希望在 dsh-better-sidebar 中查看下载活动而非被悬浮窗遮挡的 DeepSeek Harness 用户。

常见任务

查看进行中下载的进度、速度和剩余时间。
回顾已完成、失败、取消或暂停的下载记录。
定位已完成下载的文件，或仅删除其账本记录而保留文件。

权限与数据

使用本地下载元数据和本地服务访问来呈现下载状态。

权限

读取 ~/.dsh/downloads/tasks/*.json。
对含 gid 的记录查询 127.0.0.1:16800 上的 aria2 RPC。
请求在文件管理器中定位已完成的输出文件。
可通过 forget 路由删除选定任务的账本记录。

数据处理

README 说明，正常展示任务时不会抓取网络或写入文件。
文档说明删除记录不会删除已下载文件。

外部服务

未描述远程外部服务；aria2 RPC 被描述为本地服务。

凭据

提供的证据未声明需要凭据。

局限

需要 Node >=20。
需要 dsh-better-sidebar 才会显示侧边栏标签；缺少它时，宿主路由可能仍会挂载，但不会出现标签页。
任务账本由 aria2-dl.js 产生；账本文件缺失时会明确提示，而不是显示为空任务列表。
aria2 未运行时会回退为账本显示，可能无法反映下载引擎的实时状态。
提供的证据未声明 DeepSeek Harness 版本范围。

DSHub 已核对

固定 Git Bundle 的结构和补丁已通过提供的检查。
清单声明了 Web 客户端注入、Node >=20，以及 React/dsh-better-sidebar 对等依赖。
仓库文档说明 Git 安装可使用已提交的构建产物，无需本地构建。

DSHub 未核对

未实际执行安装。
未执行运行时行为、侧边栏渲染、aria2 RPC 连通性和文件管理器定位操作。
提供的证据中未找到 0.1.0 版本的 npm 分发包。

固定版本安装

安装 DSH Sidebar Downloads

这个Plugin Bundle没有 DSH Plugin 安装操作，请根据源码文档使用真实交付方式。

访问源码项目 ↗

维护者原文

项目 README

查看 commit 72eb8a1 对应的 README ↗

维护者编写的上游内容原文于 2026/9/13 从 README.md 获取，正文和仓库相对媒体固定到 commit 72eb8a133836，内容哈希为 66e37feb94d7。以下是未经 DSHub 翻译的上游原文，语言可能与当前页面不同；第三方托管的 badge 可能独立更新。

dsh-sidebar-downloads

把 aria2 下载进度显示在侧边栏的 dsh-better-sidebar 附属插件。

本插件是 aria2 下载通道的侧边栏视图：读取 aria2-dl.js 写的任务账本（~/.dsh/downloads/tasks/*.json），并对带 gid 的记录查询 aria2 RPC 补正，不重复实现下载器，只把真实状态渲染成一个侧边栏页面。

配套 dsh-download-guard 强制所有下载走 aria2 —— 两者合起来是完整闭环：守卫负责「只能走这条路」，本插件负责「能看见这条路」。

为什么

下载进度曾经由右下角悬浮窗展示：会盖住会话内容、要手动拖拽躲避、且和 DSH 自身的侧边栏体系割裂。本插件注册一个正式的 better-sidebar 页面——和「资源管理器 / 终端 / Git」并列，开合、拆并、皮肤跟随全部由底座统一管理。

功能


实时进度	进度条 + 百分比，按状态着色（进行中 / 完成 / 失败 / 已取消）
速度与剩余时间	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.js`

账本现在只有一个写入方——aria2-download 技能的 aria2-dl.js。每次入队都会写一条带 gid 字段的记录。配合 dsh-download-guard 拦掉一切绕过 aria2 的命令后，这个账本即全部的下载活动。

为什么还要查 aria2 RPC

aria2-dl.js 以 --no-wait 方式入队时，只在入队瞬间写一次记录（status: starting、计数器全 0）就返回，之后不再更新——而下载其实还在跑。直接读该文件会让面板永远停在 0%，甚至显示「已下载 3.62 GB / 总量 0.00 GB」这种自相矛盾的结果。

因此本插件对带 gid 的记录会直接查询 aria2 RPC（127.0.0.1:16800，Motrix Next 内置引擎），以引擎的实际状态为准。引擎未运行时自动降级为「照账本显示」，不会报错。

架构

src/index.ts               host 半：读任务账本 → HTTP 路由（/tasks、/reveal、/forget）
src/client/index.tsx       client 半：注册一个 better-sidebar tab
src/client/DownloadsPanel.tsx   tab 内容：轮询、渲染、交互
src/client/panel.module.css     样式：全部走 --dsw-alias-* 令牌，跟随皮肤
src/client/api.ts         typed fetch 封装
scripts/build.mjs         构建：esbuild + lightningcss

host 半 只声明 inject: ['webServer']，用 node 内置模块读写文件，不依赖 ctx.fs / ctx.subprocess；查询 aria2 RPC 用的是 node 内置 fetch，无额外依赖。 client 半 只做注册（ctx.betterSidebar.registerTab），不自行布局，卸载后零残留。

路由

方法	路径	说明
GET	`/api/sidebar-downloads/tasks`	全部任务（进行中优先，最多最近若干条）
GET	`/api/sidebar-downloads/reveal?taskId=`	在资源管理器中定位输出文件
GET	`/api/sidebar-downloads/forget?taskId=`	删除一条账本记录（不删文件）

taskId 会校验，拒绝任何含路径分隔符或 .. 的输入，无法越出任务目录。

开发

npm install
npm run build      # 产出 lib/index.js 与 lib/client.js
npm run typecheck
npm test           # host 半 + client 半冒烟测试 + panel DOM 集成测试

lib/ 下的产物是提交进仓库的——这是本生态的约定，让用户从 git 安装时无需构建步骤。

许可

MIT

有意识地管理

安装与管理

前置条件与目标 Profile

目标： dsh Profile

交付方式： Git Bundle — BeiWay1145/dsh-sidebar-downloads#72eb8a133836bd20d6eac48780596634960cd657。

验证、更新与移除

显示生命周期命令

验证

dsh plugin --profile dsh list

兼容性与访问范围

Node >=20; requires React 18 and dsh-better-sidebar： Not declared in supplied evidence。

检查兼容性证据 ↗

风险事实

local_data_access

Reads local download-task records and queries a local aria2 RPC service for tasks with a gid.

证据 ↗

file_manager_action

Can request that completed downloads be revealed in the system file manager; removing a record is documented not to delete the downloaded file.

证据 ↗

证据与编辑审查Manifest、Bundle patch、分发与新鲜度

不可变证据

审查状态与源码活动

AI 已审查

源代码使用 MIT 许可。由于提供的记录未能证实 npm 发布，建议使用固定的 Git Bundle。

AI 审查于 2026/9/13 UTC 14:25。GitHub 事实核对日期： 2026/9/13 UTC 14:25。

自当前证据基线以来，没有记录到重要源码变化。

下一步

按 Plugin 安装流程操作 →

订阅重要变化： DSH Sidebar Downloads →

DSH Sidebar Downloads