前言¶
在 DeepSeek Harness（DSH）里让 agent 跑下载、转码、批量处理时，常见局面是：脚本在后台转，聊天里只有转圈，模型和你都不知道还剩多久。本插件不是给界面画悬浮条，而是把「进度必须存在、里程碑必须回报」写进系统提示，并提供 Python / PowerShell / Node 三份零依赖助手，让脚本输出百分比、速率、ETA，并在 10 / 25 / 50 / 75 / 90% 等处用机器可读行和聊天回报对齐预期。
这是什么¶
dsh-script-progress（社区目录：elosiad/dsh-script-progress）由维护者 Elosiad 发布，归类为工作流类 DSH 插件。仓库：GitHub · Elosiad/dsh-script-progress。
它解决的是「长任务脚本没有硬性进度输出、模型没有硬性回报动作」的问题：提示段落（progress:script，order 9200）规定什么算长任务、脚本要输出什么、怎么跑、怎么报；助手目录落在 $DSH_HOME/script-progress/；里程碑行以 @@PROGRESS 为前缀，便于从 agent 抓到的 stdout 里识别。
界面上的进度展示可与 dsh-task-progress 配合：本插件负责生产 @@PROGRESS 与 JSONL，对方负责画条；二者不互相替代。
核心机制¶
下面分三块说明插件在 DSH 里实际做了什么。
系统提示段落¶
插件向系统提示注入 progress:script 段落（默认 order 9200）。其中会渲染助手目录的真实绝对路径，模型写脚本时可直接 sys.path.insert 或等价方式引用，无需每次重写进度条逻辑。
进度助手¶
激活后会在 $DSH_HOME/script-progress/ 提供 progress.py、progress.ps1、progress.mjs。脚本 import 或 dot-source 后即可使用 track / Progress 等 API。
里程碑约定的一行示例：
@@PROGRESS 25% 12.4it/s eta=00:03 label=下载
输出形态¶
被 agent 捕获、非 TTY 时约每 0.5 秒一行进度，里程碑单独一行；真实终端则 \r 原地刷新。进度条字符仅用 ASCII（# / -），避免 Windows 重定向 stdout 时的编码问题。任务未跑完就中断时，收尾会标明中止进度，不会谎报 100%。
安装与启用¶
从 GitHub 安装（仓库本身是可安装的 bundle）：
dsh plugin --profile web add github:Elosiad/dsh-script-progress
本地开发可用目录链接：
dsh plugin --profile web add link:/path/to/dsh-script-progress
装完后重启一次 DSH。是否激活可参考（Windows 路径示例）：
%USERPROFILE%\.dsh\script-progress\last-activation.json
卸载：
dsh plugin --profile web remove dsh-script-progress
插件在 当前 dsh 进程的权限 下运行；安装前建议通读仓库源码并确认许可证（MIT）。DSH 社区目录站点与 DeepSeek / 幻方无官方从属关系，属于「一切皆插件」生态里的第三方条目。
配置¶
在插件行的 config: 中修改，重新加载插件后生效。错误配置会当场抛错，不会在日志不明的情况下静默回退默认值。
| 字段 | 默认 | 说明 |
|---|---|---|
enabled |
true |
总开关；关闭时该段落渲染为空 |
minSeconds |
20 |
超过多少秒才算「长任务」（影响提示措辞阈值） |
milestones |
[10,25,50,75,90] |
里程碑百分比（1–99）；100 由助手自动补 |
reportInChat |
true |
是否要求逐条回报；关闭则结束时汇总 |
language |
zh |
段落语言：zh / en |
order |
9200 |
段落插入位置 |
helperDir |
空 | 助手目录覆盖；空则 $DSH_HOME/script-progress |
debug |
false |
将渲染段落写入 section.txt |
典型用法¶
路径需换成你本机 $DSH_HOME/script-progress 下的实际目录（提示段落里也会给出渲染后的路径）。
Python¶
import sys
sys.path.insert(0, r"C:\Users\you\.dsh\script-progress")
from progress import track
for item in track(items, label="下载"):
fetch(item)
# 或者手动控制
from progress import Progress
p = Progress(total=len(urls), label="下载", unit="req")
for url in urls:
p.update(note=url)
p.close()
PowerShell¶
. "C:\Users\you\.dsh\script-progress\progress.ps1"
ForEach-WithProgress -Items $urls -Label '下载' -Unit 'req' -Process {
param($url)
Invoke-WebRequest $url | Out-Null
}
Node¶
const { track, Progress } = await import(
'file:///C:/Users/you/.dsh/script-progress/progress.mjs'
)
for (const item of track(items, { label: '下载' })) {
await fetch(item)
}
捕获输出时，里程碑与进度行大致如下（摘自 README）：
[ 15%] ###------------------- 120 it/s ETA 00:01 | 下载
@@PROGRESS 25% 123it/s eta=00:01 label=下载
[ 44%] ##########------------ 119 it/s ETA 00:01 | 下载
@@PROGRESS 50% 121it/s eta=00:01 label=下载
@@PROGRESS 100% 118it/s elapsed=00:02 label=下载
完成 200 it · 耗时 00:02 · 平均 118 it/s · 下载
两种上报路径¶
| 场景 | 做法 | 谁写进度 |
|---|---|---|
| 脚本能改 | 使用本插件助手 | 助手同时写 stdout 与 JSONL |
| 外部命令无法改（如 ffmpeg、curl） | 按 README 使用 DSH_PROGRESS_CLI 包装运行 |
包装器解析输出中的百分比或计数 |
不建议为上报再写伴随脚本；能包一层就用包装器或助手即可。
适用场景与注意¶
适合谁：经常让 agent 生成长耗时循环脚本、又希望在聊天里按时看到里程碑说明的 DSH 用户；需要与 dsh-task-progress 搭配才能在 UI 里看到任务进度条。
前提与边界：
- 工具执行期间 agent 循环阻塞时，模型读不到中途输出；提示条款要求长任务放后台跑，这是「能否报进度」的前提，不是风格建议。
- 约束主要在提示词层，模型仍可能不严格遵循；不是运行时的强制拦截。
- 包升级后首次激活可能覆盖助手目录；自定义助手请设
helperDir。 - 进度写入失败会被吞掉，避免进度逻辑拖垮用户脚本。
仓库提供自测入口：node test\smoke.mjs（配置解析、段落渲染、助手落盘与三语言实跑等）。
结尾¶
dsh-script-progress 把长任务的进度与里程碑回报从「最好有」变成提示与助手共同支撑的惯例：脚本侧有百分比、速率、ETA 和 @@PROGRESS 行，模型侧在约定百分比向用户说明进展。需要界面可视化时，再装显示端插件即可。
- 目录页：https://www.skillhub.cn/plugins/Elosiad/dsh-script-progress
- 源码与文档：https://github.com/Elosiad/dsh-script-progress
