dsh-job-progress：后台任务进度浮动卡片

前言¶

在 DSH 中执行下载、构建、渲染等后台任务时，任务一启动就进入后台，输出被滚动到日志区域。要确认任务是否在跑、跑了多少、还要多久，需要来回切换视图、滚动日志，这在长时间任务或并发任务中容易遗漏关键信息。dsh-job-progress 在会话右下角提供一个浮动卡片，每个任务一行，显示进度条、百分比、耗时和最新输出，任务结束后自动消失，避免卡片一直占用空间。

插件定位¶

dsh-job-progress 是一个 Web 客户端插件，由维护者 yezitotempeace 开发。它通过订阅 DSH 的任务输出流，在会话右下角渲染一个可拖动的悬浮卡片，实时展示当前会话中所有后台任务的进度与状态，适合需要持续监控任务进度的场景。

核心功能¶

任务列表与状态¶

卡片每行对应一个任务，显示：
- 标签：通常为启动任务的命令
- 状态：圆点，绿=运行中、黄=停止中、红=失败、灰=已结束
- 进度条：优先使用任务自带的 progress 字段，没有则从输出尾部解析 45%、curl 表格、1.2 GB / 3.4 GB 等格式，无法识别则显示不确定进度条
- 百分比：有数字时显示在右侧
- 耗时：运行中实时走秒，结束后定格
- 最新输出：最后一行（去 ANSI、压缩空白、截断 180 字符），有 ETA 时附「剩余 3m 20s」

卡片最多显示 4 行，多余的任务显示「还有 N 个」。

卡片交互¶

点标题栏可将卡片收起为右下角的小胶囊：显示「后台任务 N 个」+ 总进度条 + 平均百分比，再次点击展开
整张卡片可拖动：按住标题栏拖到屏幕任意位置，位置保存在浏览器的 localStorage 中，刷新后恢复；收起后的胶囊也能拖动；拖出可视区会被拉回
任务结束后保留 8 秒显示最终状态，随后卡片消失；没有任务时不渲染

进度识别范围¶

插件能识别以下工具的进度：
- wget
- curl（默认表格和 -# 进度条）
- apt
- pip
- npm
- 任何往标准输出打 NN% 的程序

识别逻辑是启发式的：
1. 优先使用 DSH 任务自带的 progress 字段
2. 否则扫描输出尾部 40 行，查找百分比或 curl 表格
3. 无法识别时显示不确定进度条 + 最新输出

技术实现要点¶

数据来源：ctx.jobs.state（roster）、ctx.jobs.watchRows(sessionId)、ctx.jobs.observe(sessionId, id)
挂载位置：通过 conversation.session.header.actions 获取 sessionId，内容使用 createPortal 渲染到 document.body
进度解析：纯函数 parseProgress(text)，去 ANSI、按 \r\n 切分、从尾部查找 %、curl 表格、速度、ETA、字节比
渲染：固定定位，z-index: 60，默认右下角（含安全区偏移），使用主题 token 取色
拖动：使用 pointer 事件与 setPointerCapture，移动超过 4px 触发拖动，位置钳制在视口内并写入 localStorage

限制¶

任务必须往标准输出打进度才能解析出百分比；写入文件的进度无法识别
卡片固定在右下角，窄屏上位于输入框上方，可收起成胶囊
输出流由 DSH 的 job.follow 提供，卡片关闭后不再保留输出

安装与启用¶

在 Web profile 下安装：

dsh plugin --profile web add github:yezitotempeace/dsh-job-progress

安装后，需将 dsh-job-progress 加进 profile 的 package.json 中的 dsh.profile.bundles，然后重启 Web。

本地开发时，可将仓库放到 /root/dsh-job-progress，在 dependencies 中写入 "dsh-job-progress": "link:/root/dsh-job-progress"，在 dsh.profile.bundles 中加入 dsh-job-progress，建立 node_modules/dsh-job-progress 链接，重启 Web。

典型用法¶

安装并启用插件后，在 DSH 会话中执行以下任务，即可在右下角看到浮动卡片：

wget https://example.com/large-file.zip
npm install --verbose
pip install -r requirements.txt

卡片会自动识别这些任务的进度条与百分比，实时更新耗时与最新输出。任务结束后，卡片保留 8 秒显示最终状态，随后消失。

适用场景与注意¶

dsh-job-progress 适合需要持续监控后台任务进度的开发者与使用者，尤其是频繁执行下载、构建、渲染等任务且需要快速获取进度的场景。

注意：插件以当前 dsh 进程的权限运行，安装前应检查源码与许可证。插件仅观察当前会话的任务，不读取会话内容，也不发额外网络请求。

结语¶

dsh-job-progress 通过浮动卡片和拖动交互，让后台任务的进度与状态一目了然，减少切换视图和滚动日志的开销。如需查看插件详情，可访问：
- 目录页：https://www.skillhub.cn/plugins/yezitotempeace/dsh-job-progress
- GitHub：https://github.com/yezitotempeace/dsh-job-progress