前言¶

在 DeepSeek Harness（DSH）裏用 pwsh 或 bash 跑構建、測試、批量腳本時，有一個很具體的觀察問題：前臺命令的輸出往往要等進程結束才一次性出現；後臺任務則把輸出留在模型側的 job_output 游標之後。會話頭部的任務列表能看狀態，卻看不到腳本正在做什麼。一條跑十分鐘的命令，對盯着 Web 界面的人來說仍是黑盒。

下面介紹社區插件 dsh-task-progress（維護者 chen8923，分類爲客戶端）。它不給 DSH 增加新的工具，而是讓腳本把結構化進度寫入工作區文件，Web UI 通過懸浮層、右側欄「任務進度」tab 和設置頁讀取並展示——不必輪詢 agent，也不必等命令結束。

這是什麼¶

dsh-task-progress 當前版本 0.3.0，MIT 許可證，npm 包名與 GitHub 倉庫名一致（dsh-task-progress / chen8923/dsh-task-progress）。定位可以概括成：長任務的第二條專用通道——生產者往 JSONL 文件追加事件，宿主進程輪詢並暴露狀態，瀏覽器半定時拉取同一份快照，在界面上畫進度條、消息、耗時與 ETA 等。

插件依賴 Web profile（宿主側需要 webServer、connection、shellEnv；瀏覽器側需要 slots、locale、sidebarRightTabs）。在缺少這些接縫的組合裏，插件保持未加載，對現有行爲無影響。構建與驗證針對 @deepseek-ai/dsh 0.1.7-rc.1；插件本體要求 Node 20+。

核心功能¶

經過上面的定位，可以把已覈實的能力拆成幾塊：

1. Shell 環境注入：每次帶會話的模型 shell 調用會獲得 DSH_PROGRESS_DIR（進度文件目錄）；若隨包 CLI 可用，還會設置 DSH_PROGRESS_CLI。
2. Web 展示：同一套狀態出現在懸浮 overlay（可點擊展開）和右側欄 Task progress / 任務進度 tab；設置頁提供掃描間隔、輪詢間隔、任務上限等可調項。
3. HTTP 狀態端點：同源 GET/HEAD /plugins/task-progress/state，經 DSH 的 connection.requestRejection 圍欄，一次只服務當前會話，響應中不含文件系統路徑。
4. Job 鏡像行：未主動上報的後臺任務仍會顯示一行（命令標籤、運行時長、結束方式等），數據來自 DSH 自帶的 job 鏡像，不經過本插件路由；沒有腳本上報時不會出現虛假的百分比。
5. 模型提示：宿主半追加一段靜態系統提示詞（緊挨 DSH 後臺任務說明）；可選地，後臺任務超過 remindAfterMs（默認 30000 ms，0 關閉）仍無上報時，最多發一條提醒。
6. 終態兜底：腳本被 job_kill 等強行終止、無法寫入終態時，宿主半會結合 job 註冊表推斷 killed / failed / 完成，並在 UI 標明是推斷而非上報。
7. 隨包 CLI：dsh-progress（bin/dsh-progress.mjs）支持 emit、done、list，以及 run --task <id> -- <命令> 包裝長命令並嘗試從輸出解析進度。

運行時零 npm 依賴；不向工具目錄註冊新 tool，因此不會額外佔用工具說明的緩存前綴。

安裝與啓用¶

DSH 在啓動時掛載 profile bundle，安裝後需要重啓 DSH。官方 README 給出的安裝方式如下。

從 npm 安裝並註冊到 web profile：

dsh plugin --profile web add dsh-task-progress

從 GitHub 安裝同一倉庫的已提交構建產物：

dsh plugin --profile web add github:chen8923/dsh-task-progress

本地開發/checkout 場景可使用倉庫內的 rebuild 腳本（需已有 DSH 源碼路徑）：

./tools/rebuild.ps1 -Profile web -Checkout <path-to-dsh-checkout>

安裝包未聲明 install、postinstall 或 prepare，因此安裝階段不會在機器上執行維護者腳本；之後實際運行的是包內的 lib/index.js（宿主）與 lib/client.js（瀏覽器）。若需自行覈對發佈 tarball 與源碼重建是否一致，README 提供了 npm pack、diff -r 與 npm view dsh-task-progress dist.integrity 的比對流程。

插件目錄頁：https://www.skillhub.cn/plugins/chen8923/dsh-task-progress（SkillHub 爲社區插件目錄，與 DeepSeek / 幻方無官方從屬關係）。

典型用法¶

1、在腳本里追加 JSONL¶

插件爲每次 shell 調用準備好目錄，腳本只需向 $DSH_PROGRESS_DIR/<task>.jsonl 追加一行 JSON（協議詳見倉庫 docs/PROTOCOL.md）。

PowerShell 示例（每個事件一行）：

$line = '{"v":1,"task":"build","state":"running","pct":42,"msg":"linking"}'
[System.IO.File]::AppendAllText(
  (Join-Path $env:DSH_PROGRESS_DIR 'build.jsonl'), $line + "`n",
  [System.Text.UTF8Encoding]::new($false))

bash：

printf '{"v":1,"task":"build","pct":42,"msg":"linking"}\n' >> "$DSH_PROGRESS_DIR/build.jsonl"

Python：

import json, os
path = os.path.join(os.environ["DSH_PROGRESS_DIR"], "build.jsonl")
with open(path, "a", encoding="utf-8") as handle:
    handle.write(json.dumps({"v": 1, "task": "build", "pct": 42, "msg": "linking"}) + "\n")

2、使用隨包 CLI¶

避免手寫轉義時，可直接調用環境變量指向的 CLI：

node "$DSH_PROGRESS_CLI" emit --task build --pct 42 --msg "linking"
node "$DSH_PROGRESS_CLI" done --task build --msg "shipped"
node "$DSH_PROGRESS_CLI" list

長命令可交給包裝器（README 建議在預計超過約 30 秒的命令上使用）：

node "$env:DSH_PROGRESS_CLI" run --task <id> -- <你的命令>

3、零配置試跑¶

倉庫提供模擬腳本，安裝插件後可在 DSH shell 中執行：

pwsh ./examples/simulate.ps1 -Task demo -Steps 30 -DelayMs 500

然後打開右側欄「任務進度」tab，或等待懸浮膠囊出現並點開。

裝完插件後，宿主半會在系統提示詞中加入進度約定，模型對長命令通常會自行安排上報；若組合裏沒有 systemPrompt 接縫，可把 README 中的 AGENTS.md 片段抄到工作區作爲補充約束。

設置頁與主要配置¶

在 Web UI 的插件頁打開 任務進度設置 卡片（標題來自插件註冊的 slot）。保存寫入本條目在 profile 中的 config，改動實時生效。README 列出的字段包括：

進度文件默認位於各 workspace 下的 .dsh-progress/<session-id>/，插件只 tail 讀取這些 jsonl（及配置的額外絕對路徑根），不發起外網請求。

適用場景與注意¶

適合誰：經常在 DSH Web 界面盯長構建、數據導入、測試矩陣或 Agent 觸發的後臺 job，且希望人在環內能看到百分比、階段消息和 ETA，而不是隻看「運行中」狀態。

腳本側習慣（來自 README「腳本被殺掉時」一節）：

• 儘量讓 task id 出現在命令行（例如 --task sync-catalog），便於與 job 鏡像行配對。
• 一個 task id 對應一個寫入者，或按階段拆分 id。
• 正常路徑仍應用 try/finally 寫入終態；進程被強殺時依賴宿主推斷兜底。

安裝前須知：DSH 插件運行在 DSH 宿主進程權限內，不是沙箱安裝。本插件聲明的觸碰範圍包括：讀取/創建上述 .dsh-progress 路徑、注入 shell 環境變量、註冊一條 HTTP 路由與 UI slot、追加系統提示詞段；無出站網絡、無遙測、不新增 tool。完整表格見倉庫 SECURITY.md。安裝前建議閱讀源碼、LICENSE（MIT）及發佈完整性說明，並按自身安全策略決定是否啓用。

刻意不做的事（避免錯誤預期）：不做歷史歸檔、不做界面取消按鈕（停任務仍用 DSH 的 job_kill）、不做跨會話或遠程生產者。

結尾¶

DSH 生態強調「一切皆插件」；dsh-task-progress 用文件協議把長任務進度從 agent 輸出流裏解耦出來，讓人在 Web UI 裏實時看見進展。若你的 workflow 以 Web profile 爲主、且長命令較多，可以先按 npm 一條命令安裝，重啓後用 examples/simulate.ps1 驗證懸浮層與側欄 tab，再按協議或 CLI 接到自己的腳本。

• 插件目錄：https://www.skillhub.cn/plugins/chen8923/dsh-task-progress
• 源碼與文檔：https://github.com/chen8923/dsh-task-progress