前言¶
在 DeepSeek Harness（DSH）里跑下载、模型转换、批量渲染时，任务往往在后台执行。终端里能看到输出，但回到 Web 对话界面后，很难一眼判断「还要多久、完成了多少」。常见做法是反复切回终端或让 Agent 轮询日志，既打断对话，也不便于同时盯多个任务。
下面介绍客户端插件 dsh-job-progress（维护者 Rice00）：在有可观察后台任务的会话里出现可拖动的悬浮球，展开后面板展示每条任务的进度、速度与 ETA；任务数据来自 DSH 作业注册表与会话内的进度协议文件，无需额外配置凭证或外网调用。
这是什么¶
dsh-job-progress 是面向 DSH Web 的客户端插件，定位是「长耗时后台作业的实时进度条」。它读取宿主侧的作业注册表与会话目录下的进度 JSON，浏览器端约每 2 秒拉取快照，渲染悬浮球与任务面板。许可证为 MIT，运行时要求 Node 22+（与 package.json 中 engines 一致）。
核心功能¶
资料中明确列出的能力如下。
- 悬浮球：仅在有任务可看的会话出现；角标显示正在运行的任务数，超过 9 条显示
9+。 - 可拖动：位置可调整，刷新页面后仍保留（存在
localStorage）。 - 实时面板：每个作业一行，包含状态点、标签、进度条、百分比、
done/total、速度、ETA、已用时间。 - 清除已完成：可删除当前会话内已结束任务的进度文件；运行中的条目不会被删。
- 与生产者解耦：未上报进度的作业仍会出现在列表中（来自注册表），只是没有进度条。
- 会话隔离：只展示当前
DSH_SESSION_ID下的作业，不会看到其他会话的任务。 - 零配置：不读 token、不发额外网络请求；读作业注册表与会话进度目录即可。
- Agent 可发现协议：宿主侧将进度协议注册为会话可见 skill，启动长下载或编码时 Agent 可据此上报速度与 ETA。
安装与启用¶
安装命令以仓库 README 为准。任选 npm 或 GitHub 源，将 <profile> 换成你实际使用的 profile（Web 界面常用 web）：
dsh plugin --profile <profile> add dsh-job-progress
dsh plugin --profile <profile> add github:Rice00/dsh-job-progress
bundle 补丁会在 profile 中插入一行 job-progress。安装后需要重启该 profile：宿主插件模块在进程内缓存，运行中的 Harness 不会热加载新行；若只改 UI 代码，浏览器刷新即可。
验证可参考 README：preflight 脚本应输出 ALL PASS (12)；宿主日志中应出现 job-progress: mounted, progress root … 一类挂载信息。Windows 下宿主日志路径为 %APPDATA%\DSH Desktop\logs\host\。
典型用法¶
不配参数也能用¶
无需先写配置文件。在会话里用 run_in_background 跑任意后台命令，有可观察作业时悬浮球会出现。README 示例：
node download.mjs https://example.com/model.safetensors # run_in_background
上报进度以显示进度条¶
在脚本里使用插件导出的 track API（速度与 ETA 由库根据更新间隔推算）：
import { track } from 'dsh-job-progress/progress';
const t = track({ label: 'model.safetensors', total: 66000000 });
t.update(bytesSoFar);
t.phase('verifying');
t.finish('done'); // 或 t.finish('failed', 'sha256 mismatch')
Shell 侧可不 import，直接调用插件自带的 CLI（路径中的 <plugin> 换成本机插件目录）：
node <plugin>/lib/dsh-progress.mjs set --label model.safetensors --done 12 --total 100
node <plugin>/lib/dsh-progress.mjs done --key model.safetensors
进度文件协议（简要）¶
生产者每个任务写一份 JSON，目录为：
<DSH_HOME>/job-progress/<DSH_SESSION_ID>/<key>.json
Agent shell 里已有 DSH_HOME 与 DSH_SESSION_ID，一般不必手写绝对路径。字段包括 label、done/total、unit（bytes 或 count）、可选的 speed/eta、phase、status（running | done | failed）等。运行中需定期刷新 updatedAt（约 15 秒内至少一次），否则会被视为已消失；写入时应先写 .tmp 再 rename，避免读到半文件。
数据流可概括为：生产者写 JSON → 宿主插件读目录与注册表 → 客户端轮询 jobProgress/snapshot 并渲染界面。
适用场景与注意¶
适合谁：经常在 DSH Web 里跑后台下载、转换、ComfyUI 渲染或批量 shell，且希望在当前会话内集中看进度与 ETA 的开发者。
权限与安全：插件随当前 DSH 进程与用户权限运行，能读写的范围与 Harness 一致。安装前建议浏览 GitHub 仓库 源码与 MIT 许可证，确认符合你的环境策略。
生态说明：DSH 社区插件目录（如 SkillHub 上的条目页）是独立站点，与 DeepSeek / 幻方无官方从属关系；本文安装与用法以仓库 README 为准。
结尾¶
dsh-job-progress 把「后台任务进行到哪了」收进会话内的悬浮球与面板，配合进度协议或 CLI，长任务不必再靠猜或反复查终端。目录页：SkillHub - dsh-job-progress；源码与完整协议说明：GitHub - Rice00/dsh-job-progress。
