前言¶
在 DSH 里跑大文件下载时，进度往往分散在不同地方：主会话里一条命令、子代理另起一条、你自己在终端里用脚本拉取。生态里已有 dsh-download-progress、dsh-smart-dl、dsh-task-progress、dsh-job-progress 等插件，多数只覆盖「本会话」或「当前工作区」，README 里也会写明这类范围限制。主会话右侧看不到子代理或外部终端里的同一次下载，排查「到底下完没有」就要来回切会话或查磁盘。
下面介绍维护者 LemRic1117 的 dsh-download-dashboard（GitHub：LemRic1117/dsh-download-dashboard）。它在对话区右侧挂一块浮窗，只展示 300MB 及以上 的下载，进度、速度、剩余时间实时更新；数据来源是系统临时目录下的状态快照，因此 不区分是谁发起的下载——主会话、子代理、本机终端里只要有人按约定写入状态，都会出现在同一块看板上。
这是什么¶
dsh-download-dashboard 是 DSH 的本地插件包（private: true，未发布到 npm），当前版本 1.0.1，许可证 MIT，要求 Node >=20。社区目录 SkillHub 将其归类为「记忆」；功能上它解决的是 大文件下载进度的集中、跨上下文可见，而不是会话记忆存储。
插件分 host 与 client 两半：index.js 注册只读路由汇总状态目录；client.js 挂在框架的 shell.overlay 上绘制浮窗。前提是你使用的下载器会把机器可读快照写到约定路径——仓库自带的 tools/dl.ps1 即其一；旧版不写状态的 dl.ps1 会导致「装了但浮窗一直为空」，这是 README 里最常见的无反应原因。
界面与行为¶
浮窗停在对话区 右侧：不占聊天宽度、不抢焦点、不挡输入框。每一行对应一个下载项，包含文件名（悬停显示完整保存路径）、百分比与进度条、已下载/总量、速度、剩余时间。
状态用颜色区分：蓝为进行中，绿为已完成，红为失败（并显示失败原因）。若下载被 Ctrl+C、进程被杀或断电等打断，快照可能长期停在 running；规则是 90 秒无进度更新 则标为「已中断」（黄色），保留中断时的字节数，再过 5 分钟从面板消失；若只是短暂卡住又继续，会自动回到进行中。
没有符合阈值（默认 300MB）的下载时，整个浮窗不渲染，不占位、不拦截鼠标。完成或失败后条目保留 5 分钟 再消失。窗口缩放时位置由 CSS 处理；右侧栏打开时浮窗会自动向左让位。
数据从哪来：状态目录与契约¶
配套下载器每次刷新进度，向系统临时目录写入 JSON 快照：
%TEMP%\dsh-downloads\state\<id>.json (Windows)
$TMPDIR/dsh-downloads/state/<id>.json (macOS / Linux)
host 侧路由 GET /dsh-downloads/state 汇总该目录，跳过解析失败与超过 24 小时的记录。client 侧在有下载进行时约 1.5 秒 拉取一次，空闲时 6 秒，页面隐藏时暂停轮询。
状态文件主要字段如下（路由对外只返回白名单字段，不暴露 URL、会话 id、命令行等）：
| 字段 | 说明 |
|---|---|
id |
唯一标识 |
name |
浮窗显示的文件名 |
out |
完整保存路径（悬停提示） |
totalBytes |
总字节；无 Content-Length 时为 null |
doneBytes |
已下载字节 |
speedBps |
字节/秒 |
etaSec |
剩余秒数 |
status |
starting / running / retrying / done / failed |
error |
失败原因 |
startedAt / updatedAt |
ISO 8601；updatedAt 影响何时从面板消失 |
安装与启用¶
本包未发布到 npm，需先取得仓库目录，再在 DSH 桌面端或 Web 端侧栏 Plugins 页粘贴该目录的 绝对路径（例如 D:\plugins\dsh-download-dashboard），装完后 刷新页面（Ctrl+R）。
资料中的获取方式：
git clone https://github.com/LemRic1117/dsh-download-dashboard
将 tools/dl.ps1 放到 ~/.dsh/tools/dl.ps1 或任意顺手位置，大文件下载时用该脚本（PowerShell 5.1+，支持换行式进度、断点续传、重试，结束时校验落盘字节与 Content-Length）：
powershell -NoProfile -ExecutionPolicy Bypass -File tools\dl.ps1 -Url <url> -Out <path> -Resume
插件以当前 DSH 进程权限运行；安装前建议通读仓库源码并确认 MIT 许可证与上述只读路由的安全模型是否符合你的环境。
可调参数¶
默认值在 client.js 顶部，改完后重新安装或等待 HMR：
| 常量 | 默认 | 含义 |
|---|---|---|
MIN_BYTES |
300 MB | 显示阈值 |
LINGER_MS |
5 分钟 | 完成/失败后保留时长 |
ACTIVE_STALE_MS |
90 秒 | 无更新则视为已中断 |
POLL_ACTIVE_MS |
1500 ms | 有下载时的轮询间隔 |
POLL_IDLE_MS |
6000 ms | 空闲轮询间隔 |
GAP_PX |
12 | 与右边缘、右侧栏间距 |
若希望进度仅限单会话，可将 index.js 顶部的 STATE_DIR 改为每会话目录（README 说明为一行改动）。
安全模型（简要）¶
路由 只读，无 POST/PUT/DELETE，也不能代为下载或取消。访问需通过回环地址、Host/Origin 与 Sec-Fetch-Site 等栅栏；对外响应字段白名单，不返回可能带签名的下载 URL。状态目录位于当前用户的系统临时目录，ACL 限本用户；「跨会话可见」指的是 同一用户、同一台机器上谁往约定目录写谁就被展示，并非读取其他会话私有数据。若 DSH Web 服务绑定到 0.0.0.0，应理解 README 中对 Host 伪造与真正边界（socket 回环）的说明。
适用场景与注意¶
适合：经常在 DSH 主会话、子代理和本机终端混用下载器拉 300MB 以上 文件，且希望在同一块右侧浮窗里看全局进度，而不想依赖「只盯当前会话」的进度插件。
注意：
- 必须有用会写状态 JSON 的下载器；仅安装插件、仍用旧脚本或不写状态的命令，看板会空。
- 小文件默认不显示；要改阈值请改
MIN_BYTES。 - 卸载时在 Plugins 页关闭或移除 bundle 即可，路由与浮层随生命周期消失。
- README 标明部分 UI 层级（如 dockkit 浮动面板、皮肤中心）尚未在真机全部验证。
与同生态插件的差异（据 README「相关项目」）：dsh-download-progress 追踪 shell 与工作区文件、阈值约 64KB 且偏本会话；dsh-smart-dl 状态写在会话 cwd 下；dsh-task-progress 刻意不做跨会话读取。本插件用全局临时目录状态，补的是 跨会话、跨子代理、跨终端 这一维。
结尾¶
dsh-download-dashboard 把「大文件下载进度」从分散的会话与工作区，收敛到对话区右侧一块只读浮窗：约定目录、白名单字段、配套 dl.ps1，主会话与子代理、终端里的下载只要写入同一套状态，就能一起看见。
- 社区目录：https://www.skillhub.cn/plugins/LemRic1117/dsh-download-dashboard
- 源码与说明：https://github.com/LemRic1117/dsh-download-dashboard
SkillHub 为社区插件目录站点，与 DeepSeek / 幻方无官方从属关系；DSH 本身遵循「一切皆插件」，具体能力以你本地安装的 bundle 与下载器为准。
