下载进度浮层 Sama05/dsh-download-progress

dsh-download-progress

在 DeepSeek Harness（DSH）里跑任务时，智能体一旦开始下载或加载东西，窗口上方自动浮出一条进度条——带已下载 / 总大小、实时速度、百分比，每秒刷新一次。

它解决什么问题

智能体经常在后台默默执行 curl -L -o xxx.zip ...、pnpm add ...、网页抓取这类耗时的动作。
DSH 原生只在工具开始和结束时给你两个瞬间，中间是黑盒：

- 不知道下到第几个字节了；
- 不知道还有多久；
- 甚至不确定它是不是卡住了。

这个插件填补的就是中间这段空白：把「文件正在变大」翻译成一条能看的进度条。

效果

浮层挂在窗口顶部居中，平时完全不显示，不遮挡任何内容、也不推挤聊天区布局。

| 场景 | 显示内容 |
| 文件下载 | 文件名 + 进度条 + 12.4 MB / 28.3 MB + 3.2 MB/s，悬停进度条显示百分比 |
| 插件安装 | 「插件安装中...下载中...」+ 已用秒数，下方一行 pnpm 最新日志 |
| 网页抓取 | 「正在抓取网页中...N s」，秒数实时递增 |
| 功能搜索 | 「正在搜索「查询摘要」中...请稍后」 |
| 其他加载 | 「载入中...」不确定态进度条 |

多条任务竖向堆叠，超过设定条数可用滚动查看。卡片是苹果式毛玻璃质感，支持拖动改变位置，出现动画可在设置里切换（上浮淡入 / CRT 开关机 / 水波纹 / 无动画）。

支持的版本

| 项 | 要求 | 说明 |
| DSH | >= 0.2.0-rc.1 | 已写入 package.json 的 engines.dsh。完整验证于 0.2.1-rc.2 |
| Node.js | >= 18 | 不需要单独安装：插件跑在 DSH 内置的 Electron 里（0.2.1-rc.2 为 Electron 44 / Node 24） |
| Chromium | >= 111 | 毛玻璃与 color-mix 需要；DSH 0.2.x 自带 152，无需关心 |
| 操作系统 | Windows / macOS / Linux | 只在 Windows 上实测过；其余平台只依赖 Node 标准库与浏览器 API，理论可用但未验证 |
| 第三方依赖 | 无 | 不需要 npm install，没有构建步骤 |

关于 DSH 版本区间：

- 区间下界 0.2.0-rc.1 对应插件用到的最小 API 面——tools/execute 瀑布钩子、shell.overlay / settings.section 槽位、plugin-manager/install-log 事件、webServer.register 路由。
更早的版本（0.1.x）没有验证过，可能缺其中某个槽位。
- 版本不满足时，DSH 的插件管理器会以 incompatible-version 拒绝加载并指出缺什么， 不会静默坏掉，也不会影响 DSH 本体。
- 上界没有封死（没有写 <0.3.0-0），因为插件只用稳定扩展点，且所有观测逻辑都包在 try/catch 里；即使未来某个内部形状变了，最坏结果是浮层不出现，而不是宿主出错。

安装

DSH 插件以 bundle 形式安装。两种方式任选：

直接从 GitHub 装（不需要 clone）：

dsh plugin --profile web add github:Sama05/dsh-download-progress

从本地目录装（改代码时用这个，改完即时生效）：

plugin_manager action=install_bundle target="<本仓库的绝对路径>"

装完后重启 DSH 或在插件管理器里启用，浮层即生效。卸载：

plugin_manager action=remove_bundle target="@local/dsh-download-progress"

也可以手工安装：在配置档的 package.json 里加一条 "@local/dsh-download-progress": "link:<本仓库绝对路径>"，并把包名加进 dsh.profile.bundles。

不需要 npm install，也没有构建步骤——源码就是最终产物，clone 下来直接装。

装好后这样确认它活着：

1. 「设置 → 插件」里能看到「下载进度条」这一页（说明 Client 半挂载成功）；
2. 让智能体执行一次 curl -o <文件> <某个大文件 URL>，浮层会出现在窗口上方。

改包名的话记得三个地方一起改，缺一处插件就挂载不上：package.json 的 name、 cordis.patch.yml 里的 name、以及 client.js 顶部 __ModuleLoader__.load({ id: ... }) 的 id。

配置在「设置 → 插件 → 下载进度条」里，无需改任何文件。

支持哪些下载

判据是能不能从命令行里解析出落盘路径。

有真实进度（字节 + 速度 + 百分比）

| 命令 | 说明 |
| curl -o <文件> / --output / --output-document | 最常见 |
| curl -O / --remote-name | 目标文件由 URL 推断 |
| wget -O <文件> | |
| Invoke-WebRequest -OutFile <文件> | 必须带 -OutFile |
| git clone <url> <目录> | 采样目录总体积 |

只有「进行中」（无字节数，因为宿主不提供中间事件）

插件安装（pnpm / npm / yarn）、网页抓取、research / web_search 类搜索工具、其他包管理器命令（pip / uv / docker pull / ollama pull）。

拿不到进度的情况

- 下载不落盘（curl ... | tar -x、输出到 stdout）；
- 命令里用变量拼路径（-o $dst）——插件只能读命令文本，无法求值；
- 服务端不返回 Content-Length（降级为不确定进度条 + 已下载体积 + 速度，无百分比）；
- 纯内存下载、纯 API 调用。

用到了什么

零第三方依赖，没有构建步骤，git clone 下来即可安装。

| 部分 | 实现 |
| Host 半（主进程） | Node 原生 node:fs / node:path，无依赖 |
| Client 半（Web UI） | 只用宿主已提供的 react，单文件、无打包 |
| 触发 | DSH 官方 tools/execute 瀑布钩子，包住所有工具执行 |
| 安装进度 | plugin-manager/install-log（流式 pnpm 输出）与 install-state（阶段） |
| 数据下发 | ctx.webServer.register 注册一个只读 JSON 路由，Client 每秒拉一次 |
| UI 挂载 | shell.overlay 槽位（全帧浮动层，不参与布局）+ settings.section（设置页） |
| 主题 | CSS 自定义属性，自动继承宿主 --dsw-alias- 变量 |

全部使用官方公开扩展点，没有修改 DSH 核心代码，没有 monkey-patch 任何内部对象。

优点

- 触发准确：不依赖定时猜测，真的在工具开始执行的那一刻起表；不绑会话，agent 把下载丢到后台后只要文件还在长就继续显示。
- 零侵入：官方扩展点 + 渲染在浮动层，卸载后不留任何痕迹，工具行为完全不受影响。
- 零依赖：不会因为上游包升级而断，也不需要联网安装。
- UI 与逻辑分离：所有样式集中在 client.js 顶部的 CSS 常量里，改外观不用碰逻辑；主题是一组 CSS 变量，加主题不改代码。
- 不抖：固定在布局流之外，出现、收起、悬停展开都不会让窗口元素位移。
- 可离线测试：四个 smoke / stress 脚本不需要浏览器、不需要启动 DSH，合计 70+ 条断言，覆盖 30 并发与脏数据。
- 可扩展主题：内置跟随系统 / 亮色 / 暗色，也支持从 localStorage 加载自定义主题（写几个 --ddp- 变量即可）。

缺点与限制

- 显示的是磁盘增长量，不是网卡流量：DSH 只在工具开始/结束时通知插件，中间字节流不对外暴露。所以不落盘的下载看不到进度。
- 变量路径无法解析：-o $dst、-o "$(pwd)/file" 这类写法只能读到字面量。
- 总大小依赖 HEAD 探测：对方不给 Content-Length 时没有百分比，只有不确定进度条。
- 搜索与抓取只有计时器：这也是宿主能力边界——它们的响应是一次性返回的。
- 轮询而非推送：Client 每秒拉一次状态，最多 1 秒延迟（单次往返实测约 1.4 ms）。
- 命令解析是启发式的：curl/wget 参数组合极多，未覆盖的写法会退化成「不触发」或「载入中」。

设置项

「设置 → 插件 → 下载进度条」：

| 配置项 | 默认 | 作用 |
| 显示下载进度浮层 | 开 | 关掉后不轮询、不渲染 |
| 显示下载速度 | 开 | 关掉后只留「已下载 / 总大小」 |
| 调试模式（显示模拟数据） | 关 | 打开后无真实任务时展示 5 张模拟卡片，用来调 UI |
| 新任务的排列位置 | 最新在前 | 多条任务时新的排顶部还是底部 |
| 最多同时显示条数 | 3 | 1–6，超出滚动 |
| 主题 | 跟随系统 | 跟随系统 / 亮色 / 暗色 |
| 出现动画 | 上浮淡入 | 上浮淡入 / CRT 开关机 / 水波纹 / 无动画 |
| 浮层位置 | 顶部居中 | 直接拖动浮层定位，「重置位置」恢复 |

配置保存在浏览器 localStorage，不写 Host 配置文件，所以升级重装不会丢。

开发与测试

node smoke.mjs # Client 半：假 window + 假 React，渲染真实组件树
node smoke-host.mjs # Host 半：断言分类、解析、采样、回收
node stress-client.mjs # Client 压力测试：50 张卡、脏数据、路由挂掉、窄窗口
node stress-host.mjs # Host 压力测试：30 并发、10 KB 命令、畸形入参、寿命上限

四个脚本都不需要浏览器或 DSH 进程，改完代码跑一遍即可确认没有改崩。
实现细节（为什么这么设计、依赖哪些 DSH 内部契约、哪些路子走不通）见 NOTES-FOR-AI.md。

AI 开发声明

本插件是 AI 辅助开发 的产物：需求由人提出，实现与验证由 DeepSeek 模型在 DSH 会话中完成，视觉与交互效果由人目视验收。代码以 MIT 授权，可自由使用、修改与分发，仅请求保留出处与本节说明。

License

MIT