前言¶
DeepSeek Harness (DSH) 提交的命令默認跟隨 DSH 進程運行。當執行編譯、數據導出等長時間任務時，DSH 進程關閉會導致任務中斷。dsh-bgjobs 插件利用 Windows 任務計劃程序託管後臺任務，使任務在 DSH 進程外獨立運行，並提供實時監控與管理能力。
核心功能¶
- 進程外獨立運行：任務經
schtasks託管，DSH 崩潰或關閉不影響執行。 - 實時輸出面板：網頁右下角浮動面板實時刷新輸出，支持拖拽、最小化及按工作區分組。
- 清理已完成：支持拖拽刪除單條已結束任務，或批量清理（超 24h / 全部）。
- 完成通知：任務退出後彈出 Toast 提醒，支持將結果發回創建 Agent。
- 會話內等待：使用
bgjob_wait讓 Agent 等待結果而不佔住對話，支持any競速（先完成先返回）與all合取（任一失敗即刻返回）。 - 斷線續跟：DSH 重啓自動恢復跟蹤，舊任務 ID 也能從磁盤查詢狀態。
- 離線管理：不依賴 DSH 的 CLI 或 GUI 進行任務管理。
- 可選沙箱：
bgjob_submit_pwsh支持可選沙箱約束後臺任務文件權限。 - MCP 調用託管：將 MCP 工具調用提交爲後臺任務，支持預熱/冷啓動/禁用三態。
- 零殘留：任務跑完自刪任務計劃，done 任務默認保留展示。
安裝與啓用¶
前置條件：已安裝 DSH (@deepseek-ai/dsh)、PowerShell 7 與 Node.js (^22.19.0 或 >=24)，且系統爲 Windows。
$pf="web"; dsh plugin --profile $pf add github:bitsmug/dsh-bgjobs || dsh plugin --profile $pf approve-builds koffi; dsh plugin --profile $pf add github:bitsmug/bgjobs && Write-Host "✓ bgjobs安裝成功！" -ForegroundColor Green
若安裝時遇到 ERR_PNPM_IGNORED_BUILDS 錯誤（依賴原生庫 koffi），需先執行：
dsh plugin --profile $pf approve-builds koffi
重啓 DSH 後生效，Agent 將獲得後臺任務管理工具。
使用說明¶
插件提供以下 Agent 工具：
-
bgjob_submit(name, command, workdir, [wait], [notify], [notify_mode])
提交後臺任務，command爲 bat 語法。wait參數控制提交後原地等待的秒數。 -
bgjob_submit_pwsh(name, command, workdir, [wait], [sandbox], [justification], [notify], [notify_mode])
提交後臺任務，command爲 PowerShell 語法（支持 UTF-8 日誌與安全退出碼）。sandbox爲可選沙箱配置。 -
bgjob_submit_mcp(name, workdir, tool, [arguments], server | server_config, [timeout_seconds], [wait], [notify], [notify_mode])
將 MCP 工具調用提交爲後臺任務。需先在設置頁開啓「MCP 任務」開關。 -
bgjob_mcp_tools(server | server_config, [refresh])
列出 MCP server 的註冊工具，用於確認工具名與參數形狀。 -
bgjob_status(jobId)
查詢任務狀態、退出碼及日誌尾部。不建議循環輪詢，請使用bgjob_wait。 -
bgjob_wait(jobId | jobIds, [timeoutSeconds], [logic])
等待任務結束並返回結果。logic參數支持any（任一先結束，默認）或all（全部成功）。 -
bgjob_list
列出當前會話提交的全部任務。
日誌路徑：<workdir>\.dsh\bgjobs\<jobId>\stdout.log。退出碼寫入 <workdir>\.dsh\bgjobs\<jobId>\exitcode.txt。
退出碼定義：0=成功，1=工具報錯，2=連接或調用失敗，3=超時。
典型用法示例：
將「clone Linux 內核源碼到 D:\work\linux，再 make -j16 編譯」這條長鏈路放後臺跑，跑完通知我（notify: on-exit）。
注意事項¶
- MCP 依賴：MCP 引擎依賴
@modelcontextprotocol/sdk與yaml，隨包發佈。 - 構建腳本：安裝過程依賴
koffi，若遇到構建腳本被忽略的錯誤，需執行approve-builds koffi。 - 沙箱安全：沙箱安全性未充分驗證。
- 資源管理：任務完成後默認自刪任務計劃，但日誌文件保留在磁盤。
總結¶
dsh-bgjobs 解決了 DSH 長任務運行不穩定的問題。通過 Windows 任務計劃程序託管，它確保了任務的持續性與可控性，同時提供了完善的監控、等待與通知機制，適合處理編譯、下載、批量處理等場景。
