前言¶

在 DeepSeek Harness（DSH）里，智能体通过 shell 工具跑安装、构建、长耗时脚本时，常见情况是：命令还在前台跑，模型只能等它结束或等到超时。DSH 自带的 jobs 服务提供 start、list、read、kill，但没有「接管当前正在进行的前台调用」这一层能力。社区插件 dsh-manual-bg（维护者 nu0y4，分类：客户端）补的是这一块：在 Web 对话里给正在执行的 run 工具卡片加一行命令展示和行尾 ↩ 按钮，点一下即可把该调用转成后台 job，工具立刻返回，agent 可以继续下一步。

这是什么¶

dsh-manual-bg 是一个 DSH 插件，提供改造后的 run 工具（基于官方 @deepseek-ai/dsh-tool-pwsh 的 sandbox / jobs / 超时语义）以及配套的 Web 客户端视图。前台等待时，host 侧用 Promise.race 同时等待「命令跑完」和「用户点转后台」；用户点 ↩ 后，工具返回 [moved to background job <id>]，命令仍在后台执行，输出可用官方 job_output 读取，可用 job_kill 停止，完成通知走官方 jobs 消费面。

插件仓库：https://github.com/nu0y4/dsh-manual-bg。社区目录页：https://www.skillhub.cn/plugins/nu0y4/dsh-manual-bg。SkillHub 为独立社区目录，与 DeepSeek / 幻方无官方从属关系。当前 package 版本为 0.1.0，许可证 MIT，要求 Node >= 20。

核心功能¶

下面介绍插件在资料中明确描述的能力。

run 工具与 jobs 互通¶

• 前台调用先注册为 job，再竞速「job 完成」与「用户 promote」。
• 命令正常结束则按官方语义返回 exit / stdout。
• 用户点转后台则立即返回 job id，后台任务与官方 job_output / job_kill 完全互通。

Web 对话里的卡片交互¶

• 默认只渲染一行：命令行 + 行尾 ↩ 图标（无文字、无大块展开区）。
• 点击这一行可展开/收起预览（完整命令 + 输出），行为与原生命令卡片的点击预览一致。
• 点行尾 ↩ 只做转后台；按钮使用 stopPropagation，不会触发行展开。
• ↩ 仅在命令运行中出现；原生 pwsh / bash 卡片没有该按钮。

host 与 client 分工¶

• host（lib/index.js）：manualBackground 服务，以及 /manual-bg/promote、/manual-bg/ping HTTP 路由。
• client（lib/client.js）：注册 tool.call.toolview（key=run），负责单行折叠与预览。
• host 服务不可用时，工具行为退化为官方 pwsh 工具，避免会话崩溃。

适用平台¶

• Windows + PowerShell：run 工具即 pwsh 工具的改造版，与当前 README 的安装与预设示例一致。
• Linux / macOS：README 说明需把工具描述与执行语义换成 bash，架构可沿用（ctx.shell 为平台执行器）；接入步骤与 Windows 类似，但需自行完成 bash 侧替换，资料未提供现成 bash 包路径。

安装与启用¶

插件只提供能力；要在会话里看到 ↩ 按钮，需要安装插件并把预设里的 shell 工具行换成 dsh-manual-bg/tool。

安装插件¶

方式 A：从 GitHub 直装（推荐）¶

dsh plugin --profile web add "github:nu0y4/dsh-manual-bg"

profile 需能解析 @deepseek-ai/* 运行时包（本仓库声明了 peerDependencies；DSH 自带插件依赖齐全时 pnpm 会复用）。

方式 B：本地开发（link）¶

# 1) 让树外包能解析 @deepseek-ai/* 运行时
pwsh -File .\scripts\link-deps.ps1

# 2) 装进 web profile
dsh plugin --profile web add "link:<本仓库绝对路径>"

接入预设¶

方式 1：手改预设（原生模式）¶

在预设的 agent.cordis.yml 里，将：

- id: tool-pwsh
  name: '@deepseek-ai/dsh-tool-pwsh'
  disabled: !!js process.platform !== 'win32'

替换为：

- id: tool-run
  name: 'dsh-manual-bg/tool'
  disabled: !!js process.platform !== 'win32'

方式 2：全模式覆盖层（原生 + PTC）¶

先生成覆盖层：

node .\scripts\gen-all-modes-patch.mjs

默认输出：$env:DSH_HOME\profiles\web\all-modes.patch.yml（可用 DSH_HOME 覆盖）。相关环境变量：DSH_WEB_PRESETS_DIR（dsh-web-app 的 presets 目录）、DSH_HOME（输出位置）。

Web 启动时挂载 patch（示例与 README 一致，可按需叠加 LAN 等其它 patch）：

dsh web --patch <...>\lan-access.patch.yml --patch <...>\all-modes.patch.yml --no-open

DSH 升级出厂预设后，需重跑生成器；不支持自动迁移。使用覆盖层会整份替换出厂预设的 config，Web 编辑器里对这几个预设的修改会被盖掉。

典型用法（流程）¶

1. 按上文安装插件并改预设或挂载 all-modes.patch.yml，用 Web profile 启动 DSH。
2. 在对话中让 agent 通过 run 执行一条耗时 shell 命令（需走本插件提供的 run，而非原生 pwsh 卡片）。
3. 卡片默认显示命令首行与行尾 ↩；需要看完整输出时点击该行展开预览。
4. 不想阻塞当前轮次时，点 ↩；工具返回 [moved to background job <id>]，agent 可继续调用其它工具。
5. 后台结束后按官方方式用 job_output 取输出，必要时 job_kill 终止。

排障时，/manual-bg/ping 返回待转数量；/manual-bg/promote 只接受 {callId}，只做「把已登记的前台等待转后台」，不执行命令。

原理概览¶

浏览器（client）                    host（Node）
tool.call.toolview (key=run)  ──POST──▶  manualBackground 服务
命令行 + ↩                    /manual-bg/promote    promote(callId) 唤醒等待器
                                      run 工具 execute：race(job 完成, promote)

pending 等待器按进程内 callId 关联，只在单次工具调用存活期内有效。

适用场景与注意¶

适合谁：经常在 DSH Web 里跑长命令、又希望 agent 不必干等结束再继续编排步骤的开发者；Windows + PowerShell 路径与文档最完整。

安全与权限：插件与 DSH 同进程、同权限执行 shell；安装前请阅读仓库源码与 MIT 许可证，确认命令来源可信。LAN 开放时（如示例中的 lan-access.patch.yml），同网段浏览器也可调用 promote 路由；该接口只能把已在跑的命令转后台、不接受执行参数，README 认为风险可控，但仍需结合自身网络环境评估。

已知限制（来自 README）：

• PTC 模式下按钮在 run_code 卡片展开后的子调用行上，命令不是独立卡片。
• 折叠时只显示命令首行。
• 按钮仅对本插件的 run 工具生效。

本地测试命令：

node test/host-service.test.mjs
node test/client-view.test.mjs

结尾¶

dsh-manual-bg 用一个小按钮把「前台等到死」改成「可选手动转后台」，并与官方 jobs 面打通，适合作为 DSH「一切皆插件」生态里的客户端增强。进一步了解可看社区目录 nu0y4/dsh-manual-bg 与 GitHub 仓库 nu0y4/dsh-manual-bg。