dsh-download-progress
在 DeepSeek Harness（DSH）里跑任务时，agent 一开始下载或加载东西，窗口上方自动浮出一条进度条，带已下载 / 总大小、实时速度、百分比，每秒刷新一次。
它解决什么问题
agent 常在后台默默执行 curl -L -o xxx.zip、pnpm add、网页抓取等耗时动作，而 DSH 原生只在工具开始和结束时给两个瞬间，中间是黑盒。插件把「文件正在变大」翻译成一条能看的进度条。
效果
浮层挂在窗口顶部居中，平时不显示，不遮挡内容、不推挤布局。
| 场景 | 显示内容 |
|---|---|
| 文件下载 | 文件名 + 进度条 + 12.4 MB / 28.3 MB + 3.2 MB/s，悬停进度条显示百分比 |
| 插件安装 | 「插件安装中...下载中...」+ 已用秒数，下方一行 pnpm 最新日志 |
| 网页抓取 | 「正在抓取网页中...N s」，秒数实时递增 |
| 功能搜索 | 「正在搜索「查询摘要」中...请稍后」 |
| 其他加载 | 「载入中...」不确定态进度条 |
| 后台任务 | 「后台运行中 · npm run build · 42s」，没有进度条 |
后台任务指的是没有进度可画、但在继续跑的工作：bash 后台 job、子代理、workflow。它们画成一行文字而不是卡片——卡片承诺一条会动的轨道，后台任务给不了，画了反而像卡死。当 agent 正阻塞在等它（job_wait、job_output(wait:true)、等子代理或 workflow 返回）时，同一行改说「等待中」，简易条则显示「等待后台任务」。前台的 shell 调用不会出现在这里：它已经在对话里了，再报一次就是重复。
多条任务竖向堆叠，超过设定条数可滚动；卡片支持拖动，出现动画 10 种 + 无动画，在设置里切换。
多会话并发下载：多个会话同时下载时，浮层按会话分块，块头是会话标题；只有一个会话时不套块；新会话标题未生成时显示 会话 <id 末段>。打开「只看当前会话的下载」后只显示当前会话的进度，切会话跟着换（默认关闭）。
简易条（嵌在对话框里）
嫌浮层吵，可在设置里把「显示方式」切成 对话框简易条。它长在输入框上面那一行（「完全权限」所在行），形态由数据决定：
- 长条：能算出比例（下载且知道总大小）→ 细进度条 + 流光扫过 + 当前速度，鼠标移上去才浮出百分比。
- 圆环：拿不到比例（搜索 / 抓取 / 插件安装 / 总大小未知的下载）→ 一个一直转的弧，不显示文字，悬停才给出详情（
搜索中 · 12s、下载中 · 2.86 MB · 512 KB/s）。 - 三个点：本会话没有任务，或连任务类型都拿不到 → 三个点依次呼吸，悬停显示
空闲/处理中。
空闲时也保留这个胶囊（三点常驻），不想要可切回「浮层」。它只显示当前会话的下载；同会话多任务时跟最早那条走，右侧 +2 表示还排着几个。主题、亮/暗色、--ddp-* 与浮层共用一套。
想两个都要就选「两者都显示」。默认仍是浮层，升级后界面不变。
支持的版本
| 项 | 要求 | 说明 |
|---|---|---|
| DSH | >= 0.2.0-rc.1 |
已写入 package.json 的 engines.dsh。完整验证于 0.2.1-rc.2 |
| Node.js | >= 18 |
插件跑在 DSH 内置的 Electron 里 |
| Chromium | >= 111 |
毛玻璃与 color-mix 需要，DSH 0.2.x 自带 |
| 操作系统 | Windows / macOS / Linux | 只在 Windows 实测过；其余平台理论可用但未验证 |
| 第三方依赖 | 无 | 不需要 npm install；client.js 已是构建产物，装包的人不跑构建 |
版本不满足时插件管理器会以 incompatible-version 拒绝并指出缺什么，不会静默坏掉，也不影响 DSH 本体。上界不封死，最坏只是浮层不出现。
安装
DSH 插件以 bundle 形式安装，两种方式任选：
从 GitHub 装（不需要 clone）：
dsh plugin --profile web add github:Sama05/dsh-download-progress
把
web换成你的 profile 名；desktop profile 因 CLI 限制需走下面的 link: 方式。
从本地目录装（改代码时用，改完即时生效）：
plugin_manager action=install_bundle target="<本仓库的绝对路径>"
手工 link: 安装：在 profile 的 package.json 里加
"@local/dsh-download-progress": "link:<本仓库绝对路径>"，并把包名加进 dsh.profile.bundles。
装完后重启 DSH 或在插件管理器里启用，浮层即生效。卸载：
plugin_manager action=remove_bundle target="@local/dsh-download-progress"
不需要 npm install，发布包里带的就是拼好的 client.js，安装方不跑构建。
装好后确认：①「设置 → 插件」里能看到「下载进度条」这一页；② 让 agent 执行一次 curl -o <文件> <某个大文件 URL>，浮层会出现在窗口上方。
配置在「设置 → 插件 → 下载进度条」里，无需改任何文件。
支持哪些下载
判据是能不能拿到落盘路径——先看命令行，命令行里没有就去看它指定的脚本。
有真实进度（字节 + 速度 + 百分比）
| 命令 | 说明 |
|---|---|
curl -o <文件> / --output / --output-document |
最常见 |
curl -O / --remote-name |
目标文件由 URL 推断 |
wget -O <文件> |
|
Invoke-WebRequest -OutFile <文件> |
必须带 -OutFile |
git clone <url> <目录> |
采样目录总体积（目标是目录，stat 恒为 0，单独走目录树累加） |
powershell -File <脚本> / pwsh -File <脚本> |
读脚本里的 -OutFile / -Destination / -o |
-File 那一行值得单独说：命令本身不含任何路径，插件的做法是打开脚本静态解析
（只读一次，约 0.3 ms），把 $iso = "D:\…\x.iso" 这类单层字面量赋值、
param([string]$Out = '…') 默认值、$env:USERPROFILE 展开、Join-Path 都算出来。
脚本里的 URL 也一并读出来，用来做 Content-Length 探测，所以百分比照样有。
脚本用子进程下载（& curl.exe -o $Out $Url）同样能跟——采样的是文件大小，
跟谁把字节写进去无关。
只有「进行中」（无字节数，宿主不提供中间事件）
插件安装（pnpm / npm / yarn）、网页抓取、research / web_search 类搜索工具、其他包管理器命令（pip / uv / docker pull / ollama pull）。
拿不到进度的情况
- 下载不落盘（
curl ... | tar -x、输出到 stdout）； - 命令里用变量拼路径（
-o $dst）——插件只能读命令文本，无法求值； - 脚本里的路径要跑起来才知道（
Get-Content cfg.json取值、+拼接、here-string、$(...)子表达式）——这类一律不猜，不出卡片； - 服务端不返回
Content-Length（降级为不确定进度条 + 已下载体积 + 速度，无百分比）； - 上传（
curl -T/--upload-file）：本端不落文件，不可能有进度，直接不出卡片； - 纯内存下载、纯 API 调用。
优点
- 触发准确：工具开始执行即起表；不绑会话，下载丢到后台后只要文件还在长就继续显示。
- 零侵入：只用官方公开扩展点，没改 DSH 核心、没 monkey-patch；卸载不留痕迹。
- 零依赖：没有第三方包，不会因上游升级而断，也不需要联网安装。
- 不抖：渲染在布局流之外，出现、收起、悬停展开都不会让窗口元素位移。
- 可扩展主题：内置跟随系统 / 亮色 / 暗色，也能加载自定义
--ddp-*主题。
缺点与限制
- 显示的是磁盘增长量，不是网卡流量：DSH 只在工具开始/结束时通知，中间字节流不对外暴露，所以不落盘的下载看不到进度。
- 变量路径无法解析：
-o $dst、-o "$(pwd)/file"这类写法只能读到字面量。 - 总大小依赖 HEAD 探测：对方不给
Content-Length、或 HEAD 被拒（403/405，Cloudflare 常见）时没有百分比，只有不确定进度条。 - 搜索与抓取只有计时器：响应是一次性返回的，这是宿主能力边界。
- 轮询而非推送：Client 每秒拉一次状态，最多 1 秒延迟。
- 命令解析是启发式的：curl/wget 参数组合极多，未覆盖的写法会退化成「不触发」或「载入中」。
- 脚本只读一次、只看字面量：
-File里的路径必须是能静态算出来的（字面量、param默认值、$env:、Join-Path）；要Get-Content读配置、字符串拼接、或$(...)才能定的，插件不猜、不出卡片。脚本改写后需要等下一次工具调用才重新读。 - 会话重名无法区分：两个会话同名时，分块块头显示同一个标题。
- 后台任务只知道「在跑」：没有百分比、也不能取消，宿主只广播生命周期事件。归属会话靠「父会话此刻阻塞在哪个工具」推断，推断不出来时该行的会话名为空。
设置项
「设置 → 插件 → 下载进度条」：
| 配置项 | 默认 | 作用 |
|---|---|---|
| 显示下载进度浮层 | 开 | 关掉后不轮询、不渲染 |
| 显示方式 | 浮层 | 浮层（悬浮卡片）/ 对话框简易条 / 两者都显示。选「简易条」后上方浮层不再出现 |
| 显示下载速度 | 开 | 关掉后只留「已下载 / 总大小」；简易条则只留条（圆环/三点本来就没字） |
| 调试模式（显示模拟数据） | 关 | 打开后无真实任务时展示 5 张模拟卡片，用来调 UI |
| 只看当前会话的下载 | 关 | 关：所有会话的下载按会话分块堆叠；开：只显示当前打开的会话的下载，切会话跟着换（当前会话没下载时浮层不出现） |
| 新任务的排列位置 | 最新在前 | 多条任务时新的排顶部还是底部 |
| 最多同时显示条数 | 3 | 1–6，超出滚动 |
| 主题 | 跟随系统 | 跟随系统 / 亮色 / 暗色 |
| 出现动画 | 上浮淡入 | 上浮淡入 / CRT 开关机 / 水波纹 / 横向滑入 / 下落弹入 / 弹性放大 / 横扫揭示 / 翻折展开 / 旋转入位 / 模糊聚焦 / 无动画 |
| 浮层位置 | 顶部居中 | 直接拖动浮层定位，「重置位置」恢复 |
配置保存在浏览器 localStorage，不写 Host 配置文件，所以升级重装不会丢。
自定义主题（--ddp-*）
主题就是一组 --ddp-* CSS 变量。在浏览器控制台写一次即可（与内置 id 重名的丢弃，--ddp-rows 等布局变量被拒绝）：
localStorage['dsh-download-progress:themes'] = JSON.stringify([
{ id: 'solarized', label: 'Solarized', tokens: {
'--ddp-accent': '#b58900', '--ddp-fg': '#657b83', '--ddp-card-bg': 'rgba(253,246,227,.97)' } },
])
刷新页面后「主题」下拉会多出 Solarized。只写一两个变量也能用，没写的回落到宿主 --dsw-alias-*；主题只覆盖颜色，不影响布局。
开发与测试
改完跑 npm test 即可（八步全离线，不需要浏览器或 DSH 进程）：scripts/build-client.mjs --check → contract.mjs → script.test.mjs → smoke.mjs → smoke-host.mjs → stress-host.mjs → stress-round2.mjs → stress-client.mjs。contract.mjs 会拦住「视图直接读 wire 字段」和「文档与实现不一致」两类退化——Host 与 UI 之间的字段契约见 CONTRACT.md，其余实现细节见 NOTES-FOR-AI.md。
手工实验的脚手架（限速服务器、命令分类矩阵、真机观察器）在 lab/，见 lab/README.md；它不随插件发布。
性能基准：npm run bench（中位数 + p95，--json 出机器可读结果，--save 更新 bench/baseline.json；--after 存到 bench/after.json 便于前后对比）。
改了 UI 之后要重新拼一次：client.js 是 src/client/** 的构建产物（宿主只下发一个 bundle，源码里不能写 import），改完跑 npm run build；npm test 的第一步 build-client --check 会在产物过期时直接失败并指出第一处差异。
AI 开发声明
本插件是 AI 辅助开发 的产物：需求由人提出，实现与验证由 DeepSeek 模型在 DSH 会话中完成，视觉与交互效果由人目视验收。代码以 MIT 授权，可自由使用、修改与分发，仅请求保留出处与本节说明。
No comments yet. Be the first to write one.