前言¶
在 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
