前言¶

在 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: 中修改，重新加载插件后生效。错误配置会当场抛错，不会在日志不明的情况下静默回退默认值。

典型用法¶

路径需换成你本机 $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 · 下载

两种上报路径¶

不建议为上报再写伴随脚本；能包一层就用包装器或助手即可。

适用场景与注意¶

适合谁：经常让 agent 生成长耗时循环脚本、又希望在聊天里按时看到里程碑说明的 DSH 用户；需要与 dsh-task-progress 搭配才能在 UI 里看到任务进度条。

前提与边界：

1. 工具执行期间 agent 循环阻塞时，模型读不到中途输出；提示条款要求长任务放后台跑，这是「能否报进度」的前提，不是风格建议。
2. 约束主要在提示词层，模型仍可能不严格遵循；不是运行时的强制拦截。
3. 包升级后首次激活可能覆盖助手目录；自定义助手请设 helperDir。
4. 进度写入失败会被吞掉，避免进度逻辑拖垮用户脚本。

仓库提供自测入口：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