bgjobs (standalone background jobs) — DSH 独立后台任务插件
中文 · English
让 DSH 提交的命令脱离 DSH 进程独立运行：任务交给 Windows 任务计划程序服务托管，关掉 DSH、关掉网页都不影响执行；网页弹 Toast 提醒完成，随时看实时输出；DSH 离线时还能用独立 CLI/GUI 管理。
适合大文件下载、批量脚本、编译、数据同步/导出这类长任务——提交后不用守着 DSH，随时回来看结果。
特性一览
| 能力 | 说明 |
|---|
| 进程外独立运行 | 任务经 schtasks 托管，DSH 崩溃/关闭不影响 |
| 实时输出面板 | 网页右下角浮动面板每秒刷新输出：可拖拽、最小化为悬浮球、折叠为仅任务列表、随主题换肤；按工作区分组、可调大小；左栏底部入口可一键隐藏/唤出 |
| 清理已完成 | 🧹 点击右上角清理图标开启垃圾篓：拖拽单条已结束任务删除，或批量清理（仅超 24h / 全部，与视图过滤一致） |
| 完成通知 | 任务退出即弹 Toast（不打扰会话）；可选把通知发回创建它的 agent（notify 参数） |
| 断线续跟 | DSH 重启自动恢复跟踪；旧任务 id 也能从磁盘查询状态 |
| 离线管理 | 不依赖 DSH 的 CLI / GUI：list / status / log / submit / kill / cleanup |
| 可选沙箱 | bgjob_submit_pwsh 可选 sandbox 约束后台任务文件权限，权限不高于当前会话模式 |
| MCP 调用托管 | bgjob_submit_mcp 把一次 MCP 工具调用提交为后台任务（设置页开关，默认关闭）；可登记 server 或从 DSH 配置一键导入；每个 server 可选「预热 / 冷启动 / 禁用」三态（禁用后 agent 调用被拒） |
| 零残留 | 任务跑完自删任务计划；done 任务默认保留展示，用户手动清理 |
安装 / 卸载
前置：已安装 DSH（@deepseek-ai/dsh）、PowerShell 7 与 Node.js（≥22），Windows 系统。（已在 DSH 0.1.2-rc.1 ~ 0.1.5-rc.2 · Windows 10 · PowerShell 7 · Node.js 24 上验证）
MCP 引擎（bgjob_submit_mcp）由插件自带的 Node 依赖跑：@modelcontextprotocol/sdk 与 yaml 随包发布，dsh plugin add 会自动装上；本地源码开发需先在该目录执行一次 pnpm install。DSH 自带的 Node 即可，无需另装。
方式 A（快速，npm 发布版）
$pf="web"; dsh plugin --profile $pf add bgjobs || dsh plugin --profile $pf approve-builds koffi; dsh plugin --profile $pf add bgjobs && Write-Host "✓ bgjobs安装成功！" -ForegroundColor Green
把 web 改成你自己的 profile 名，整行粘贴到 PowerShell（pwsh）即可。第一次 add 会报 ERR_PNPM_IGNORED_BUILDS（koffi 构建脚本未批准），|| 会自动触发 approve-builds 批准并运行 koffi 构建，再 add 成功后打印「bgjobs 安装成功」。
方式 B（从 GitHub 安装，始终最新）
$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
直接从 GitHub 仓库默认分支拉取，始终是最新代码（含刚发布与未发布改动），不受 npm registry 同步延迟影响。两种方式装完包名都是 bgjobs，卸载命令相同。
从插件市场(dsh-market)安装报 ERR_PNPM_IGNORED_BUILDS？
插件依赖原生库 koffi，安装会触发它的构建脚本，而 pnpm ≥10 默认阻止依赖运行构建脚本（GitHub 安装还会跑 prepare）。报错形如：
[ERR_PNPM_IGNORED_BUILDS] Ignored build scripts: koffi@3.2.1
dsh: pnpm failed in profile directory <你的 DSH home>\profiles\<profile>
处理（把 web 改成你自己的 <profile> 名，整行粘贴到 PowerShell（pwsh）即可）：
$pf="web"; dsh plugin --profile $pf approve-builds koffi; dsh plugin --profile $pf add bgjobs
第一条命令批准并运行 koffi 的构建脚本，随后重新 add 即可装上。
若你的 DSH 版本没有 approve-builds 子命令，改为手动处理：打开报错里打印完整路径的 pnpm-workspace.yaml，会发现首次失败的 add 已写入一行占位 set this to true or false，把它改成 true 后重新 add：
allowBuilds:
koffi: true
仅首次安装需要，装好后 koffi 已编译完毕，升级/重装无需重复。
重启 DSH 后生效：网页右下角出现「后台任务监控」面板，agent 获得 bgjob_submit / bgjob_submit_pwsh / bgjob_submit_mcp / bgjob_mcp_tools / bgjob_status / bgjob_wait 工具（MCP 两个工具需先在设置页打开「MCP 任务」开关）。
方式 C（本地源码开发）
- 把仓库放到本地插件目录（路径不要含中文），如
D:\dsh\plugins\bgjobs；
- 让 DSH 的模块解析器能找到它（把插件目录 junction 到 DSH 的
node_modules\bgjobs，或把目录加到 DSH 的插件扫描路径）；本地开发还需在插件目录执行一次 pnpm install（沙箱 runner 依赖，见下）；
- 编辑
<DSH_HOME>\profiles\<profile>\cordis.patch.yml 追加挂载：
- insert:
- id: bgjobs
name: bgjobs
卸载： dsh plugin --profile <profile> remove bgjobs
使用（agent 工具）
bgjob_submit(name, command, workdir, [wait], [notify], [notify_mode]) — 提交后台任务（command 为 bat 语法）；wait=提交后原地等待的秒数（0/缺省不等待；>0 语义同 bgjob_wait 全缺省——等本会话任一任务先结束，无会话信息时回退等刚提交任务）；bgjob_submit_pwsh(name, command, workdir, [wait], [sandbox], [justification], [notify], [notify_mode]) — 提交后台任务（command 为 PowerShell 语法，UTF-8 日志、exit <code> 语义安全）；wait 同上；bgjob_submit_mcp(name, workdir, tool, [arguments], server | server_config, [timeout_seconds], [wait], [notify], [notify_mode]) — 把一次 MCP 工具调用提交为后台任务（第三引擎，同样由 schtasks 托管、面板可见、可 wait/notify）。server 是设置页登记的 server 名，server_config 是内联配置（{transport:"stdio",command,args,env,cwd} 或 {transport:"streamable-http",url,headers}），二者二选一。任务里连接该 server 调用一次工具，结果写日志与 <jobDir>/result.json（channel 记录本次是命中预热常驻连接还是冷启动），退出码 0 成功 / 1 工具报错 / 2 连接或调用失败 / 3 超时；timeout_seconds 缺省不限时（该 server 在设置页登记了 timeoutMs 时以它为准），也可传任意正数秒。默认关闭，需先在设置页打开「MCP 任务」开关（未开启时调用会被拒绝）；与 DSH 一致，会话访问模式（read-only 等）不限制 MCP 任务。建议先用 bgjob_mcp_tools 确认工具名；bgjob_mcp_tools(server | server_config, [refresh]) — 列出该 MCP server 的注册工具（工具名/描述/必填字段名），提交前用它确认工具名与参数形状；refresh: true 绕过 10 分钟缓存。优先用 DSH 已注册的 mcp__<server>__* 工具（零启动开销），未命中才真正连接/启动 server 探测；同样受「MCP 任务」开关限制；bgjob_status(jobId) — 查询状态 / 退出码 / 日志尾部；仅用于查看当前状态，不要拿它循环轮询（等待用 bgjob_wait）；bgjob_wait(jobId | jobIds, [timeoutSeconds], [logic]) — 等待后台任务结束并立即返回退出码与日志尾部（timeoutSeconds 缺省 = 设置页「默认等待超时」，该设置未配置＝不限时（一直等到任务结束）；显式传 0/负数 = 本次强制不限时，传正数才到点返回 timedOut: true 快照）。两种模式（logic）：
any（缺省）：单个 jobId 等该任务；jobIds 数组 = 任一先结束即返回（any 竞速，返回完成者 + 其余 pending）——并行提交多个任务时的默认姿势：先拿到先处理，其余用 pending 继续等，不必等齐；两者都缺省 = 等本会话任务任一结束；all（合取）：等一批任务全部成功才返回 allDone: true + 每个任务的退出码/日志尾；任一任务失败即立刻返回 failed: true + failedJobId + 已结束者的 + 其余 （非 0 退出码，或被清理/找不到都算失败），不再等齐；超时返回部分状态可续等。只在「必须全部成功才能继续」且「一个失败就马上停」时使用——只想边拿边推进请用缺省的 ； 缺省 = 本会话全部任务；
直接对 AI 说一句即可（说清工作目录、任务名，以及要不要等结果 / 通知）：
把「clone Linux 内核源码到 D:\work\linux，再 make -j16 编译」这条长链路放后台跑，跑完通知我（notify: on-exit）——别让编译占着对话。
并行起两个后台任务：一边下载数据集、一边重新编译；谁先完成就先给我看结果，另一个继续跑（any 竞速，不必等齐）。
用 pwsh 引擎把 D:\data 下 30 个 CSV 批量转成 UTF-8；我要全部成功才继续，任何一个失败就立刻停下来（logic: 'all'）。
把一次 MCP 调用提交成后台任务：server glm 的 web_search，query=「大模型最新进展」，跑完把结果发回本会话。
- 任务输出实时写入
<workdir>\.dsh\bgjobs\<jobId>\stdout.log；
- 退出后
<workdir>\.dsh\bgjobs\<jobId>\exitcode.txt 写入退出码，网页弹 Toast；
- 完成后默认不打扰会话；需要让 agent 主动得知并收尾时，传
notify: on-exit（或 on-completion 仅成功 / on-fail 仅失败），并可选 notify_mode（wakeup 空闲唤醒 / quiet 仅入收件箱 / always）；
- 交付标记（notify 视图）：每个任务标注「结果是否已交付到会话上下文」——完成通知投递成功（
已通知·notify）或某次 bgjob_wait 返回了它（已通知·wait）即交付；bgjob_pending_list 列出本会话尚未交付的任务（notify 视图），bgjob_wait 缺省（含 logic: 'all'）只从这个视图等——已交付的结果不会重复返回。面板/离线 GUI 均有「已通知/待通知」标记。
网页面板
面板顶部依次是：清理（点击开启底部垃圾篓：拖拽删除单条已结束任务，或点「清理超 24h / 清理全部」批量清理）、折叠（收成仅任务列表）、最小化（悬浮球落在按钮位置）。工具栏两个开关：「仅当前会话」（只显示当前会话工作区任务）与「全权限」（预批准全权限任务，默认关）。点击任务行展开实时日志。任务行默认显示「运行时长」（运行中随面板每秒刷新增长，完成后为总耗时），可在设置 → 后台任务 → 字段显示里改到详情或隐藏。面板文案跟随 DSH 界面语言（中文 DSH → 中文面板，其他 → 英文）。
接入 DSH 侧边栏：左侧栏（聊天列表列）底部有 bgjobs 入口（宽栏显示「后台任务」，收起成窄栏时仅图标）——点击可整体隐藏/唤出右侧浮动面板；面板隐藏期间任务照跑、完成照弹 Toast。该入口可在 DSH 设置 → 后台任务里开关（默认隐藏）。
DSH 设置里的 bgjobs（两个页面）：打开 DSH 设置（左下角齿轮），左侧出现「后台任务」与「MCP 任务」两页。监控面板标题栏也有两个快捷入口：⚙ 直达「后台任务」页，数据齿轮图标直达「MCP 任务」页（两者可在设置 → 后台任务 → 界面元素里分别隐藏）。
- 「后台任务」（顶部显示当前插件版本）：① 开关「左侧栏显隐按钮」（默认关，打开后左栏底部出现入口）；② 开关「监控面板」（直接显示/隐藏右下角监控面板与悬浮球，与入口开关相互独立）；③ 「默认等待超时」（数字输入 + 保存）：agent 调用
bgjob_wait 未指定 timeoutSeconds 时使用的缺省秒数，0 或留空 = 不限时；④ 「打开离线 GUI」一键启动独立管理窗口，附 GUI 脚本路径；⑤「打开所在文件夹」经 DSH 自身的文件资源管理器机制打开离线工具目录（找不到 GUI 就到这里找 dsh-bgjobs-gui.bat）；⑥「字段显示」可配置每个任务字段（含「运行时长」）显示在列表/详情/隐藏。
- 「MCP 任务」（默认关闭）：见下。
MCP 任务（独立设置页，默认关闭）：
- MCP 任务开关：控制 agent 能否用
bgjob_submit_mcp / bgjob_mcp_tools 提交（关闭时一律拒绝并提示来开启）；开启后即时生效，无需重启 DSH。与 DSH 一致，会话访问模式（read-only 等）不限制 MCP 任务；
- MCP 服务器：登记 agent 可按名引用的 server（名字 + JSON 配置）。每行可开「预热」、编辑（把该 server 的完整配置载入下方表单，含 env/headers 明文）、点「列出工具」看工具名（点击复制）、删除；列表只回传 env/headers 的键名，不回传值。预热＝在 DSH 进程内为该 server 保持一条常驻连接（任务复用它、省去每次冷启动），仅 DSH 存活期有效，连接失败/host 不在时任务自动回退冷启动，不影响正确性（stdio 收益最明显；http 传输本身不启动子进程，提速有限）；只有"确定没执行"的失败才回退——已发出的调用失败或超时不会重跑（避免重复副作用），此时任务按退出码
2/3 结束，可自行重提（v0.1.84）；
- 导出 / 导入：导出格式二选一 —— DSH YAML（
@deepseek-ai/dsh-mcp-client 条目，可直接并入 cordis.patch.yml）或 bgjobs JSON（备份/迁移，可被导入原样吃回）；导入支持粘贴或选文件，自动识别 DSH patch 片段 / bgjobs JSON / 单个或多个 server 配置对象（需带 serverName），可选「同名跳过 / 同名覆盖」，含 !!js 的条目默认拒导（勾选后强制导入，且不会求值——需手工补全 env/headers）。导出文本与 mcp.json 都含明文密钥，分享前请脱敏；
- DSH 已有 MCP（导入）：读取当前 profile 或全局
cordis.patch.yml 里已配好的 @deepseek-ai/dsh-mcp-client 条目，一键导入成 bgjobs 登记（只读 DSH 配置、不改它）。顶部显示「当前 profile」及判定来源（命令行 --profile / 模块路径比对 / 唯一 profile）；含 !!js 表达式的条目不会求值，默认不导入（需手动补全 env/headers）。带引号（!!js '"Bearer " + process.env.X'）与无引号（KEY: !!js process.env.X）两种写法都会识别为需人工处理；万一表达式写在无法逐条定位的位置，整批条目都会被标红提示核对，不会把 JS 表达式当普通字符串静默导入。
离线管理 CLI（DSH 不运行也能用）
# 在 tools/ 目录下执行
.\dsh-bgjobs.ps1 list
.\dsh-bgjobs.ps1 status -Id <id>
.\dsh-bgjobs.ps1 log -Id <id> [-Tail 100]
.\dsh-bgjobs.ps1 submit -Name <n> -Command <c> -Workdir <dir> [-Pwsh]
.\dsh-bgjobs.ps1 kill -Id <id> [-NoDeleteDir]
.\dsh-bgjobs.ps1 cleanup [-OlderThanHours 24] # 0 = 清理全部
.\dsh-bgjobs.ps1 index -Workdir <dir>
图形面板（GUI）
双击 tools\dsh-bgjobs-gui.bat 即可启动独立窗口（不依赖 DSH）：任务列表/日志、提交（bat 或 pwsh）、终止、清理（超期小时数可调，或全部）、重建索引。工具栏**「📌 桌面快捷方式」**可一键在当前用户桌面创建指向本 GUI 的快捷方式（双击即开，不弹黑窗）。GUI 与 Toast 文案跟随系统 UI 语言（zh → 简体中文，其他 → 英文）；CLI 输出固定为英文。找不到 GUI？ DSH 设置 → 后台任务 → 「打开离线 GUI / 打开所在文件夹」可直接启动或定位脚本位置。
数据与存储
- 任务数据：
<workdir>\.dsh\bgjobs\<jobId>\（job.json 元数据、stdout.log 日志、exitcode.txt 退出码）；
- 全局状态：
$DSH_HOME\bgjobs\index.json（任务"地图"）、$DSH_HOME\bgjobs\fullaccess.json（全权限开关）、$DSH_HOME\bgjobs\ui-prefs.json（网页 UI 偏好：左栏入口显隐）；
done 任务默认持续保留，直到你手动清理（面板 🧹 / CLI cleanup / GUI）。
使用须知
workdir 必须是 DSH 工作区内的绝对路径；- 任务默认「仅用户登录时运行」：关 DSH/终端不影响，但注销 Windows 会终止任务；
- 命令不要自带
> log 类重定向（插件已整体重定向并保证 UTF-8）；
- 沙箱：
sandbox 只约束文件效果（写工作区/临时区外会被拒），网络不受限；它是"尽力而为"而非数学边界——工作目录若落在 Everyone 可写的位置会失效；沙箱任务的任务目录会授 Everyone 只读（脚本文本对本地用户可见）；bat 引擎任务恒为全权限，受限会话需开启「全权限」才能提交；
- 受限会话里请求超出会话模式的权限会弹窗审批，
justification 说明理由即可。
- MCP 任务：默认关闭（设置页开启）；被删除/强杀的任务，其 stdio MCP server 子进程可能残留（正常完成后由 host 清理，见「删除」时的 pid 回收）；每个 server 在设置页可切「预热 / 冷启动 / 禁用」三态——禁用会让
bgjob_submit_mcp / bgjob_mcp_tools 拒绝该 server 并断开其常驻连接（「列出工具」仍可用）；「预热」连接只在 DSH 存活期有效，不改变"任务脱离 DSH 也能跑"；离线 CLI/GUI 只读查看与删除 MCP 任务，不在离线侧提交 MCP；mcp-servers.json、导出文本与任务目录的 mcp.json 都含明文密钥，分享/归档前请脱敏。
- 等待被停止 ≠ 任务失败：agent 等待任务时你点「停止/打断」，本次等待会以错误结束（错误文案写明各任务当前状态并提示可续等）。这是 DSH 的取消语义——调用方取消后，成功返回的东西送不到模型，只能以错误形态呈现；任务本身继续后台运行、不标记已交付，agent 可再次
bgjob_wait 续等。等待期间收到其它 agent 的消息则正常返回让路（stoppedBy: 'message'）：该返回不含消息正文，但这次调用会声明终结当前回合——DSH 随即把你/它发来的消息作为正式用户消息投递给 agent（排在本轮之后的排队消息亦然）；agent 不应再用等待或阻塞操作顶替它。
- MCP 超时收尾有 1–2 秒宽限：MCP 任务超时/失败后 host 会关闭连接并回收 server 子进程（SDK
close() 内部会先等约 2 秒再升级），所以 result.json 里的 durationMs 可能比 timeoutMs 多 1–2 秒（同文件也记了 timeoutMs 便于对照）。
维护与开发
架构设计、机制细节、测试与发布流程见 docs/developer.md。
近期更新（v0.1.62 → v0.1.85）
-
设置页可配「默认等待超时」：agent 调用 bgjob_wait 未指定 timeoutSeconds 时用该值（0/留空 = 不限时）；显式传 0 仍可单次强制不限时（v0.1.85）。
-
面板任务行显示「运行时长」：运行中显示「已运行」的实时时长（12s/3m05s/2h03m/1d04h，随面板每秒刷新增长），完成后为总耗时；纳入设置页「字段显示」（默认显示在列表，可切详情/隐藏）（v0.1.85）。
-
超时值改为「任意正数秒 / 缺省不限时」：bgjob_wait 的 timeoutSeconds 与 bgjob_submit_mcp 的 timeout_seconds 去掉 600 秒上限，且不传即不限时（一直等到结果；期间仍会被新入站消息让路、被用户停止打断）；submit 系列的 wait 同样支持任意正数秒（0/缺省仍 = 不等待）（v0.1.84）。
-
修复预热通道导致 MCP 工具被执行两次：预热代理调用原先客户端只等 3 秒，超时即"回退冷启动"，于是耗时 >3 秒的工具会被执行两遍；现在客户端中止预算与调用超时对齐（仅兜底 host 无响应），且代理会标记"调用是否已发出"——已发出的失败/超时不再重跑，直接按退出码 2/3 收尾（v0.1.84）。
-
bgjob_wait_all 合并进 bgjob_wait：新增 logic 参数（any 缺省 / all 合取），原 bgjob_wait_all 的全部行为（全部成功才 allDone、任一失败即刻返回 failed + failedJobId + 其余 pending）改由 bgjob_wait({ ..., logic: 'all' }) 提供；工具数 9 → 8（v0.1.83）。
-
等待被新消息让路后自动交还回合：bgjob_wait / bgjob_wait_all 因新入站消息返回（stoppedBy: 'message'）时会声明终结当前回合（DSH 工具执行契约 exec.concludeTurn），DSH 随即把该消息作为正式用户消息投递给 agent——不再出现"agent 继续等待、消息递不进来"（v0.1.82）。
-
bgjob_wait_all 改为合取语义：allDone 只在全部成功时为真；任一任务失败（非 0 退出码 / 被清理 / 找不到）即刻返回 failed:true + failedJobId + 已结束者 results + 其余 pending，不再空等。并行提交后的默认姿势改为 bgjob_wait 的 any 竞速（先拿到先推进）（v0.1.82）。
-
指引明确禁止系统 sleep 等待：等结果只用 bgjob_wait / bgjob_wait_all，不要用 sleep / Start-Sleep / timeout，也不要「循环 bgjob_status」；指引改为分节结构并补齐 bgjob_submit_mcp / bgjob_mcp_tools（v0.1.82）。
-
新增 MCP 后台任务引擎：bgjob_submit_mcp 把一次 MCP 工具调用提交为后台任务——与 bat/pwsh 一样由任务计划程序托管、面板可见、支持等待/通知；默认关闭，在设置页「MCP 任务」开启后可用（v0.1.80）。
