前言¶
在 DeepSeek Harness（DSH）里让 agent 跑任务时，常见操作包括 curl 拉包、pnpm add、网页抓取等，往往要等几十秒甚至更久。DSH 原生只在工具开始和结束两个瞬间给出反馈，中间过程对用户几乎是黑盒：不知道已下多少字节、当前速度如何、是否卡住。社区插件 dsh-download-progress（维护者 Sama05，分类为客户端）针对的就是这段空白：在窗口顶部用毛玻璃浮层展示下载与各类加载任务的进度，每秒刷新一次。
下面介绍它的定位、能力边界、安装方式与典型用法。事实以 GitHub 仓库 README 与 package.json 为准；插件目录页见 SkillHub。
这是什么¶
dsh-download-progress 是 DSH 的 bundle 插件（包名 @local/dsh-download-progress，当前版本 0.1.1，MIT 许可）。简介为：Frosted-glass download progress overlay for DeepSeek Harness (DSH)。
实现上拆成 Host 半（主进程，用 Node 原生 fs / path）与 Client 半（Web UI，使用宿主提供的 react，单文件无打包）。触发依赖 DSH 官方 tools/execute 瀑布钩子；状态通过 ctx.webServer.register 注册的只读 JSON 路由下发，Client 每秒轮询一次；UI 挂在 shell.overlay 与 settings.section 槽位。无第三方依赖，无构建步骤，不改 DSH 核心。
核心功能¶
浮层表现¶
浮层挂在窗口顶部居中，无任务时不显示，不推挤聊天区布局。多条任务竖向堆叠，超过设定条数可滚动。卡片为毛玻璃样式，可拖动改变位置；出现动画可在设置中切换（上浮淡入、CRT 开关机、水波纹、无动画）。
| 场景 | 显示内容 |
|---|---|
| 文件下载 | 文件名、进度条、已下载/总大小、实时速度，悬停进度条显示百分比 |
| 插件安装 | 「插件安装中…下载中…」与已用秒数，下方一行 pnpm 最新日志 |
| 网页抓取 | 「正在抓取网页中…N s」，秒数递增 |
| 功能搜索 | 「正在搜索「查询摘要」中…请稍后」 |
| 其他加载 | 「载入中…」不确定态进度条 |
能解析出真实字节进度的命令¶
判据是能否从命令行文本解析出落盘路径（插件只读命令字面量，无法对 shell 变量求值）。
curl -o/--output/--output-document，以及curl -O/--remote-namewget -O <文件>- PowerShell
Invoke-WebRequest -OutFile <文件>（须带-OutFile） git clone <url> <目录>（采样目录总体积）
仅有「进行中」、无字节明细的场景¶
插件安装（pnpm / npm / yarn）、网页抓取、research / web_search 类工具、以及 pip / uv / docker pull / ollama pull 等——宿主不提供中间字节事件，插件以计时或日志流展示。
设置项¶
在「设置 → 插件 → 下载进度条」中配置，保存在浏览器 localStorage，不写 Host 配置文件：
| 配置项 | 默认 | 作用 |
|---|---|---|
| 显示下载进度浮层 | 开 | 关闭后不轮询、不渲染 |
| 显示下载速度 | 开 | 关闭后只保留已下载/总大小 |
| 调试模式（显示模拟数据） | 关 | 无真实任务时展示模拟卡片，便于调 UI |
| 新任务的排列位置 | 最新在前 | 多条任务时新任务在顶或底 |
| 最多同时显示条数 | 3 | 1–6，超出滚动 |
| 主题 | 跟随系统 | 跟随系统 / 亮色 / 暗色 |
| 出现动画 | 上浮淡入 | 上浮淡入 / CRT 开关机 / 水波纹 / 无动画 |
| 浮层位置 | 顶部居中 | 可拖动；「重置位置」恢复默认 |
版本与环境¶
| 项 | 要求 | 说明 |
|---|---|---|
| DSH | >= 0.2.0-rc.1 |
README 写明完整验证于 0.2.1-rc.2；不满足时插件管理器以 incompatible-version 拒绝加载 |
| Node.js | >= 18 |
跑在 DSH 内置 Electron 中，无需单独安装 |
| Chromium | >= 111 |
毛玻璃与 color-mix；DSH 0.2.x 自带更高版本 |
| 操作系统 | Windows / macOS / Linux | README 标明仅在 Windows 上实测；其余平台理论可用未验证 |
安装与启用¶
DSH 插件以 bundle 形式安装。先从 GitHub 安装（资料原文命令，profile 为 web）：
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"
不需要 npm install，也没有构建步骤。
确认插件已挂载：
- 「设置 → 插件」中能看到「下载进度条」页面（Client 半挂载成功）；
- 让 agent 执行一次
curl -o <文件> <大文件 URL>，窗口上方应出现浮层。
典型用法¶
安装并启用后无需改配置文件，日常使用由 agent 触发 shell 与工具即可。
验证文件下载进度（README 示例思路）：
curl -o /tmp/large.bin https://example.com/large-file
在 agent 会话中执行上述或类似带明确 -o 路径的 curl/wget 命令时，浮层应显示文件名、体积、速度与百分比（在服务端返回 Content-Length 且 HEAD 探测成功时才有百分比）。
开发者在改 UI 时可打开设置里的「调试模式」，无真实任务时查看五张模拟卡片。
适用场景与注意¶
适合谁：经常在 DSH 里跑 agent、且希望一眼看到「文件是否在长大、插件是否在装、抓取是否在跑」的开发者。DSH 生态强调「一切皆插件」；SkillHub 目录 为社区站点，与 DeepSeek / 幻方无官方从属关系。
能力边界（README 明确写出）：
- 显示的是磁盘文件增长量，不是网卡流量；不落盘下载（如
curl ... | tar -x）看不到进度。 - 路径含变量（如
-o $dst）无法解析。 - 无
Content-Length或 HEAD 被拒时，退化为不确定进度条加已下载体积与速度，无百分比。 - 命令解析为启发式，未覆盖的 curl/wget 写法可能不触发或仅显示「载入中」。
- Client 轮询带来最多约 1 秒延迟。
安全与权限：插件以当前 DSH 进程权限运行，通过官方扩展点观测工具执行与文件采样。安装前建议阅读 源码与 LICENSE，自行判断是否纳入工作流。
结尾¶
dsh-download-progress 用官方 tools/execute、shell.overlay 等扩展点，把 agent 后台下载与加载的中间态翻译成顶部毛玻璃进度条，零第三方依赖、卸载不留痕。若你已在 DSH >= 0.2.0-rc.1（建议对齐 README 验证版本 0.2.1-rc.2）上使用 web profile，可按上文命令安装试用。
- 目录页：https://www.skillhub.cn/plugins/Sama05/dsh-download-progress
- GitHub：https://github.com/Sama05/dsh-download-progress
