dsh-job-progress

跑到哪了？——让我们快速查询当前进度（为每个急哭的人设计）。

一个 DeepSeek Harness 插件：为长时间运行的后台任务显示实时进度。下载、模型转换、渲染、批量任务，都算。

_{小球浮在对话上方，角标显示正在跑的数量，点开就是任务面板。}

功能 · 安装 · 快速上手 · 协议 · 验证 · 常见问题 · English

功能

安装

本地目录（推荐）

git clone https://github.com/Rice00/dsh-job-progress.git
dsh plugin --profile <profile> add link:/abs/path/to/dsh-job-progress   # 指向上面检出的目录

bundle 补丁会往 profile 里插一行（job-progress）。然后重启这个 profile——宿主插件模块在进程内缓存，运行中的 harness 不会自动读到新行。

link: 是活链接：改源码立刻生效（宿主代码重启后生效，界面代码刷新后生效），但装完之后不能挪动这个目录。想连文件一起复制走，用 file:/abs/path/to/dsh-job-progress，代价是以后每次改都得重新装一遍。

从 npm 或 GitHub 安装

dsh plugin --profile <profile> add dsh-job-progress                    # npm
dsh plugin --profile <profile> add github:Rice00/dsh-job-progress      # GitHub

交给 AI 助手（直接复制）

请帮我安装 DSH 插件 dsh-job-progress：

1) 装进 web profile，三种来源任选：
     从 npm：
       dsh plugin --profile web add dsh-job-progress
     从 GitHub：
       dsh plugin --profile web add github:Rice00/dsh-job-progress
     或从本地检出（填这个文件夹的绝对路径）：
       dsh plugin --profile web add link:<绝对路径>
2) 重启该 profile——宿主插件模块在进程内缓存，新行只在启动时读。
   （只改界面的话，刷新浏览器就够了。）
3) 验证：
     node <绝对路径>/test/preflight-client.mjs      → 应输出 "ALL PASS (12)"
     宿主日志里应出现：  job-progress: mounted, progress root …
   Windows 下宿主日志在 %APPDATA%\DSH Desktop\logs\host\。
   只要 DSH 能正常启动、渲染进程控制台没有新报错，就算装好了。

快速上手

没有任何要配置的东西——后台跑点活，小球就出来了：

node download.mjs https://example.com/model.safetensors    # 后台运行

想让进度条动起来，让干活的那边报几个数就行（一个文件，什么语言都行）：

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 校验失败')

不想改代码，直接在 shell 里报也行：

node <plugin>/lib/dsh-progress.mjs set --label model.safetensors --done 12 --total 100
node <plugin>/lib/dsh-progress.mjs done --key model.safetensors

工作原理

产出方（你的脚本）              宿主插件                        前端插件（浏览器）
  track({ label, total })  ──▶  读 <DSH_HOME>/job-progress/  ──▶  每 2 秒取一次 jobProgress/snapshot
  写 <key>.json                 <DSH_SESSION_ID>/*.json           渲染小球、角标和面板
                                 + 作业登记表快照

小球的位置和"哪些已经清掉了"记在 localStorage 里。

进度协议

一个任务一个 JSON 文件，写在会话自己的进度目录下：

<DSH_HOME>/job-progress/<DSH_SESSION_ID>/<key>.json

这两个环境变量在每次 agent shell 调用里都已经存在，所以产出方不需要任何人告诉它路径。

{
  "label": "anima_preview_5B.safetensors",
  "done": 4187599360,
  "total": 9972879360,
  "unit": "bytes",
  "speed": 13107200,
  "eta": 440,
  "phase": "download",
  "status": "running",
  "note": "",
  "jobId": "bash-3",
  "updatedAt": 1758000000000
}

心跳。 status 是 running 时，至少要每 15 秒刷新一次 updatedAt。停止刷新的活条目会被当作已经没了——一个不再写文件的产出方，和一个崩掉的产出方，从外面看不出区别。done / failed 的条目会多留两分钟。

原子写入。 先写 <file>.tmp 再改名覆盖目标文件；读的人永远不该看到半截记录。

命令行

清除

清除已完成会删掉本会话所有已完成的进度文件，正在跑的一律不动。

作业登记表里的任务删不掉——它只是只读投影——所以已经结束的任务行会记进本会话的忽略名单，从此不再出现。名单的键里带了任务的 startedAt：作业 id 是按进程数出来的 <kind>-N，否则重启之后一条旧的忽略记录会把一个全新的任务也藏掉。

会话 id 里带路径分隔符或 .. 的，宿主直接拒掉，而且要求会话真的存在。这个 id 同时是目录名，所以这是防路径穿越的闸门，不是走形式。宿主不答应的时候，界面会报失败、什么都不改——不会出现"看起来清掉了、文件还在"。

兼容性

验证安装

# 1) 前端插件：模块契约、插槽注册、跑一遍渲染
node test/preflight-client.mjs            # → ALL PASS (12)

# 2) 宿主插件挂上了没（Windows 桌面应用）
Select-String -Path "$env:APPDATA\DSH Desktop\logs\host\dsh-*.log" -Pattern 'job-progress'
#    → dsh-job-progress: mounted, progress root …\.dsh\job-progress

# 3) profile 里有没有这一行
dsh --profile <profile> --dump-config | Select-String 'job-progress'

然后在任意会话里起一个后台任务，把鼠标移到小球上。

常见问题

border-radius: 50%;
corner-shape: round;   /* 不写就是方圆形——也可能正是你想要的 */

node test/preflight-client.mjs     # 不用装东西，不用开浏览器

cordis.patch.yml            bundle 补丁：插入 `job-progress` 这一行
package.json                清单：bundle 补丁 + web 前端插件
lib/client.js               前端插件：小球、拖拽、面板、清除
lib/index.js                宿主插件：作业登记表快照 + 进度目录 + jobProgress/clear
lib/dsh-progress.mjs        产出方：协议、辅助函数、命令行
test/preflight-client.mjs   前端插件的 12 项检查
assets/                     本 README 用的 logo 和截图

卸载

dsh plugin --profile <profile> remove dsh-job-progress

产出方写在 <DSH_HOME>/job-progress/ 下的进度文件不会跟着删——不需要了就自己清。插件从不删这个目录以外的任何东西。

后续计划

• 子代理名下的作业（现在一个会话只看得到自己 owner 的作业）
• 图标和大资源改走宿主路由，不再内联成 data URI
• 更丰富的阶段，让产出方能自己命名任意阶段
• 这份 README 的更多语言版本

参与贡献

欢迎提 issue 和 PR。开 PR 之前：

node test/preflight-client.mjs     # 必须 ALL PASS

前端插件请保持零依赖（只用 React），改完记得跑一遍 preflight——它存在的理由就是前端的问题平时看不见。

许可证

本项目采用 MIT 许可。