下载进度悬浮面板 nanshanzhaoji/dsh-download-progress

dsh-download-progress

DSH 下载进度插件：给 DeepSeek Harness 增加一个 download 工具，下载时在 Web GUI 右下角显示实时进度条（百分比 / 速度 / 大小），无需用户盯着终端猜下载是否卡住。

- 中英双语界面（面板文案跟随浏览器语言）
- 纯官方接缝：工具走 ctx.tools，面板走 shell.overlay slot，进度走 ctx.webServer 路由
- 零构建：客户端 bundle 为手写 __ModuleLoader__.load 格式，安装即用

概述

| 问题 | 本插件解决 |
| 模型用 shell / web 工具下载大文件时，GUI 上看不到进度 | 提供 download 工具，实时上报 received / total → percent |
| 想知道下载速度、剩余大小、是否卡住 | 面板显示速度（B/s）、已下载/总大小、百分比 |
| 想让别的客户端也消费进度 | 暴露 GET /download-progress JSON 快照接口 |

兼容性

- 目标 DSH：0.1.0-rc.6（实测于 2026-08-17，Windows + web profile）
- 依赖：Node.js ≥ 18（内置 http/https/stream，无第三方运行时依赖）
- 平台：Web GUI（dsh web）；浏览器端依赖 shell.overlay slot（由 dsh-client-ui-layout 声明）
- 已验证：download 工具真实下载 4 MiB → percent: 100、字节数一致、快照 JSON 正确、取消后清理临时文件（test/smoke.mjs）

安装

方式一：npm 包（若已发布）
dsh plugin --profile web add dsh-download-progress

方式二：GitHub clone 安装
git clone https://github.com/nanshanzhaoji/dsh-download-progress.git
dsh plugin --profile web add ./dsh-download-progress

安装后重启 dsh web 生效（新增插件行需要重新加载组合树）。

安装完成后确认：

浏览器访问（重启后）
curl http://127.0.0.1:3080/download-progress # → {"downloads":[]}
curl http://127.0.0.1:3080/plugins/dsh-download-progress/client.js # → 200

卸载

dsh plugin --profile web remove dsh-download-progress

或手动移除 profile 的 cordis.patch.yml 中对应 insert 行、删除 node_modules 中的包，然后重启 dsh web。

快速开始

在对话中让模型调用：

download({ url: "https://example.com/file.zip", dest: "file.zip" })

Web 右下角实时显示：

下载进度 2 个进行中 file.zip ▓▓▓▓▓░░░░░ 62% 34.5 MB / 55.7 MB 8.2 MB/s

下载完成后条目停留约 1 分钟自动消失；没有活动下载时面板自动隐藏。

配置

host 端 Config（cordis.patch.yml 中 download-progress 行的 config）：

| 字段 | 默认 | 说明 |
| keepFinishedMs | 60000 | 完成后在面板停留的毫秒数 |
| maxFinished | 20 | 内存中保留的已完成条目上限 |
| maxRedirects | 5 | 跟随重定向次数上限 |

示例：

- id: download-progress
name: dsh-download-progress
config:
keepFinishedMs: 120000
maxRedirects: 8

权限与数据

- 网络：download 工具会向目标 URL 发起 HTTP(S) 请求并流式写入工作区文件（dest 相对工作区根解析，默认取 URL 文件名）。请确保目标地址可信。
- 文件：写入路径由调用方 dest 决定，仅写入工作区内的目标文件及其父目录。
- 不访问：不读取凭据、不上传任何数据、不做遥测。
- 浏览器端：仅轮询同源 /download-progress；不读取会话内容。

故障排查

| 现象 | 排查 |
| 面板不出现 | 确认重启过 dsh web；确认浏览器访问 /plugins/dsh-download-progress/client.js 返回 200；确认页面无 JS 报错 |
| /download-progress 404 | 插件 host 端未加载：检查 --dump-config 是否包含 download-progress 行，检查启动日志 |
| 下载报 HTTP xxx | 目标返回非 200；可能是 404/403/500，检查 URL 是否有效 |
| 进度一直 0% | 服务器未返回 Content-Length（chunked 响应），此时显示"下载中…"而非百分比，属预期行为 |
| 取消后残留文件 | 取消时会删除未完成的临时文件；若进程被强杀可能残留，手动删除即可 |

开发

npm install # 安装运行时依赖（@deepseek-ai/dsh-tools 等）
node test/smoke.mjs # 冒烟测试：本地 HTTP 服务器驱动真实下载 + 取消路径

冒烟测试断言：文件字节数、percent === 100、/download-progress 快照 JSON、取消后清理临时文件。
许可证与安全

- MIT 许可证（见 LICENSE）
- 安全问题：请勿在公开 issue 中粘贴敏感信息；可直接开 issue 或私信维护者