前台转后台 nu0y4/dsh-manual-bg

dsh-manual-bg

把 DeepSeek Harness（DSH）里正在跑的前台 shell 命令，点一下转成后台任务。

DSH 的 jobs 服务只有 start / list / read / kill，没有「接管进行中前台调用」的接口，所以官方工具要么一直等到超时、要么你只能干等。本插件补上这块：

- 一个 run 工具（改造自官方 @deepseek-ai/dsh-tool-pwsh，sandbox / jobs / 超时语义保持一致）；
- 前台等待时同时竞速「命令跑完」和「用户点按钮」；
- Web 对话里只渲染一行：命令行 + 行尾 ↩ 图标按钮（无文字、不展开、不输出块）；
- 点 ↘ 图标 → host 唤醒该调用的等待器 → 工具立刻返回 [moved to background job <id>]，命令继续在后台跑，智能体马上能继续下一步；跑完有完成通知，输出可用 job_output 读、job_kill 停。

适用平台

- Windows + PowerShell（run 工具就是 pwsh 工具的改造版）。
- Linux/macOS 需要把工具描述与执行语义换成 bash；架构不用动（ctx.shell 本身就是平台执行器）。

安装

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

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

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

方式 B：本地开发（link）

1) 让树外包能解析 @deepseek-ai/ 运行时（在包内建 node_modules/@deepseek-ai junction） pwsh -File .\scripts\link-deps.ps1

2) 装进 web profile（写入依赖 + dsh.profile.bundles）
dsh plugin --profile web add "link:<本仓库绝对路径>"

接入预设（让模型真正用上 run 工具）

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

方式 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 一起）

scripts/gen-all-modes-patch.mjs 会读 DSH 出厂预设（standard / ptc / minimal / cordis），把它们的 shell 工具行替换成 dsh-manual-bg/tool，生成一个 --patch 覆盖层：

node .\scripts\gen-all-modes-patch.mjs
默认输出：$env:DSH_HOME\profiles\web\all-modes.patch.yml（可用 DSH_HOME 覆盖）

然后用 --patch 挂载（Web 启动参数）：

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

环境变量：DSH_WEB_PRESETS_DIR（dsh-web-app 的 presets 目录）、DSH_HOME（输出位置）。

不支持出厂预设升级后的自动迁移：DSH 升级后重跑生成器即可。

原理

浏览器（client 半边） host（Node 进程） ┌──────────────────────────┐ ┌───────────────────────────────┐ │ tool.call.toolview │ POST │ manualBackground 服务 │ │ key = "run" │ ─────────────▶ │ Map<callId, resolve> │ │ 命令行 + 行尾 ↩ 图标 │ /manual-bg/ │ promote(callId) → resolve() │ └──────────────────────────┘ promote └──────────────┬────────────────┘ │ 唤醒 ┌────────────────▼────────────────┐ │ run 工具 execute() │ │ registry.start(job) │ │ race(job 完成, 用户 promote) │ │ 完了直接返回 exit/stdout │ │ 用户点了 → 返回 job id │ └─────────────────────────────────┘
- host（lib/index.js）：提供 manualBackground 服务，外加 /manual-bg/promote、/manual-bg/ping 两条 HTTP 路由。
- tool（lib/tool.js）：run 工具。前台调用先注册成 job，再
Promise.race([registry.wait(...), promotePromise])；按钮命中时返回
kind: "promoted"（timeoutMs: 0 作为手动标记），job 继续跑。
- client（lib/client.js）：手写 DSH ModuleLoader bundle，注册 tool.call.toolview（key=run），渲染单行折叠卡片。

行为与边界

- 按钮只对本插件提供的 run 工具生效（原生 pwsh/bash 卡片没有按钮）。
- 失败安全：host 服务不可用时，工具行为退化为官方 pwsh 工具（不会崩）。
- /manual-bg/promote 只接受 {callId}，只做「把已登记的前台等待转后台」，不执行命令、不返回数据；/manual-bg/ping 返回待转数量，便于排障。
- 后台任务与官方 job_output / job_kill 完全互通；完成通知走官方 jobs 消费面。

开发 / 测试

node test/host-service.test.mjs # host 服务 + HTTP 路由逻辑
node test/client-view.test.mjs # client bundle（mock ModuleLoader/react）渲染与点击

已知限制

- pending 等待器按进程内 callId 关联，只在一次调用存活期内有效。
- PTC 模式下按钮位于 run_code 卡片展开后的子调用行上（命令不是独立卡片）。
- 覆盖层整份替换出厂预设的 config，Web 编辑器里对这几个预设的修改会被盖掉。
- LAN 开放时（示例中的 lan-access.patch.yml）同网段浏览器也能调 promote 路由：该动作只能把已在跑的命令转后台，不接受参数，风险可控。

致谢 / 归属

lib/tool.js 改写自 DeepSeek Harness 官方包 @deepseek-ai/dsh-tool-pwsh （MIT）。其余代码为本项目原创。

License

MIT