前言¶
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 任务计划程序托管，它确保了任务的持续性与可控性，同时提供了完善的监控、等待与通知机制，适合处理编译、下载、批量处理等场景。
