后台任务托管 yaopushen/dsh-plugin-background-tasks

dsh-plugin-background-tasks

让长命令不再卡死对话：短命令即时返回结果，长命令自动转入后台，跑完主动汇报——复刻 Google Antigravity 的 run_command 工作流体验。

简介

对话式开发里最影响手感的事，莫过于一条构建、训练或下载命令把整个会话挂住。本插件把 Antigravity 的「超时竞争」工作流带到 DeepSeek Harness：

1. 长命令异步化 — 命令先同步等待 10 秒：跑完直接给结果；没跑完就整体转入后台，对话立即释放，你继续干别的，互不打断。
2. 完成主动汇报 — 后台命令结束时自动推送结果摘要（退出码 + 输出尾部），零轮询、不用催。
3. 状态随时可查可控 — 每个后台任务有 ID；列表、读输出、终止都是现成工具，与宿主原生后台任务共用同一套界面。
4. 安全不越界 — 命令走宿主统一执行通道：会话沙箱策略与审批管线照常生效；万一被策略拦下，会明确告诉你如何合规重试。
5. 开箱即用 — 自带「后台任务模式」预设：新建会话选它即得单入口体验；Windows / Linux / macOS 全平台。

参数命名对齐 Antigravity 官方的 run_command 合约（CommandLine / Cwd / WaitMsBeforeAsync），模型侧习惯零成本迁移。

安全边界（必读）

- 命令经由 DSH 的 ctx.shell 执行器运行，受会话沙箱模式约束：confining executor 在位的部署中，越界文件操作以 [sandbox: file access denied under mode] 标记呈现（升级面在位的组合还会附带与原生 shell 工具逐字一致的同轮升级提示）；danger-full-access 会话不设限是该模式自身的语义，不是插件旁路。注意该词汇表约束的是写效果——读操作在任何模式下都不受限。
- 加宽请求走 ctx.approval 审批管线：审批禁用的会话中升级会被自动拒绝（fail-closed），不存在绕过路径。
- 后台任务按 owner 会话隔离：跨会话不可见、不可收集、不可杀；owner 销毁时任务被取消并等待结算。
- ctx.jobs 未组合时工具直接报错（fail loud）：每个 run_command 调用都必须保持可收集、可停止。

配置（Config）

可在 profile 的 cordis.patch.yml 或主配置中通过条目的 config 字段覆盖；非法类型在加载时即抛错（fail loud）。为保证树外 link/path 挂载时的最小运行时依赖，校验由插件内置安全实现。

| 字段 | 类型 | 默认值 | 说明 |
| waitMsBeforeAsync | int ≥ 0 | 10000 | 同步等待毫秒数（对齐 Antigravity 10 秒标准）；设为 0 则直接后台启动 |

cordis.patch.yml 覆盖配置示例
- insert:
- id: dsh-plugin-background-tasks
name: dsh-plugin-background-tasks
config:
waitMsBeforeAsync: 10000 # 统一标准：10 秒

提供的工具 (Tools)

run_command

通过挂载的 DSH shell 执行器运行系统命令（Windows 为 PowerShell 家族，Linux/macOS 为 bash）。

| 参数 | 类型 | 必填 | 默认值 | 描述 |
| command | string | 是 | - | 待执行的完整命令行字符串 |
| cwd | string | 否 | 会话工作区 | 命令执行的工作目录；相对路径按会话身份解析 |
| description | string | 否 | - | 任务简短说明（同时作为 job 列表标签） |
| sandbox_permissions | string | 否 | - | 仅限对刚发生的沙箱拒绝做一次性同轮加宽重试；需配 justification 并经用户审批（仅 confining 组合广告此参数） |
| justification | string | 否 | - | 与 sandbox_permissions 成对出现的给用户的一句话理由 |

同步等待窗口是部署级配置（waitMsBeforeAsync，默认 10 秒），模型侧没有时机参数——这是刻意设计：时机决策权属于操作者。窗口内完成则内联返回；超窗或调用中止自动转入后台，结果经完成通知送达。

- 同步完成：返回退出码 + 合并输出（executor 负责输出预算与 spill 文件标注）；启动失败以 killed 结算并在 stderr 带错误，绝不悬挂。
- 转入后台：返回 [Command moved to background] 与 JobId（command-N），并附一行明确的反轮询指引——勿在通知到达前轮询，继续独立工作或结束本轮即可被完成通知自动唤醒；运行中的每次读取正文同样携带该提示，终态读取与官方 [status: ...] 收尾格式不受影响。此后用原生 job_ 工具管控，完成通知由 jobs 消费面自动投递。

安装与注册方式

方式一：从 GitHub 安装（发布后的标准姿势）

dsh plugin --profile web add github:yaopushen/dsh-plugin-background-tasks

编译产物 lib/ 随库提交，GitHub 直装免构建。

方式二：本地开发挂载（link）

本插件遵循标准 DSH Bundle 规范，自带 dsh.bundle 补丁声明与随包预设：

1. 注册安装到指定 profile（例如 web profile）
dsh plugin --profile web add "dsh-plugin-background-tasks@link:D:/DEEPSEEK/dsh-plugin-background-tasks" -w

2. 检查配置层生效状态（权威诊断，应显示 - id: dsh-plugin-background-tasks）
dsh --profile web --dump-config | Select-String background

3. 启动 DSH Web
dsh web

组合前提：profile 需组合 ctx.shell 执行器（缺省 fail loud）、@deepseek-ai/dsh-jobs-local + @deepseek-ai/dsh-tool-jobs（jobs 缺省时调用即报错）；confining executor 在位时需 ctx.sandboxPolicy（缺失则加载即抛错，与原生 shell 工具同一判据）。

树外路径挂载的依赖解析：插件以绝对路径挂载在宿主工作区之外时，Node 需要能从本目录解析 @deepseek-ai/ 运行时包。运行 scripts/link-deps.ps1 一次即可幂等建立指向 harness 工作区的 junction（要求 harness 已构建）。

零提示词的“无感化”使用体验（后台任务预设）

插件加载时会自动把 preset/background-shell/ 释放到 $DSH_HOME/.agent-presets/background-shell/：
- 在 Web GUI 新建会话时，选择预设 「后台任务模式」 即可。
- 该预设继承标准编程模式的全部功能（文件读写、检索、工作流、计划等），唯一区别在于移除了代理面的 pwsh/bash 解禁行，模型在面对任何终端操作时将天然以 run_command 为唯一单入口，无需在系统提示词中增加说教规则。
- 注意：安装器幂等且跳过已存在的目标目录——更新随包预设后需手动同步 $DSH_HOME 下的副本（或删除该目录让安装器重建）。

目录结构

dsh-plugin-background-tasks/
├── package.json # Bundle 声明、files 导出白名单 ├── cordis.patch.yml # Bundle 默认挂载补丁 ├── preset/ # 随包附带预设（自动释放） │ └── background-shell/ # 单入口 Shell 派生预设（agent.cordis.yml / preset.yml） ├── scripts/ │ └── link-deps.ps1 # 树外路径挂载时的依赖 junction 接线（幂等） ├── src/ │ ├── index.ts # 函数插件入口（inject ['tools','shell','systemPrompt']；split-composition fail loud） │ ├── config.ts # fail-loud 配置解析器（默认 10s 等待窗口） │ ├── tools.ts # run_command Consumer（晋升竞争、审批升级、jobs 注册） │ ├── shell-exec.ts # 纯适配层（workdir 解析、outcome 映射、读渲染、竞速器） │ ├── preset-installer.ts # 预设幂等自动释放辅助器 │ ├── format.ts # 防 Markdown 围栏击穿工具 │ └── types.ts # 强类型定义 ├── lib/ # 编译产物（随库提交，供 link 挂载免构建部署） ├── tests/ │ ├── test-shell-exec.mjs # 纯适配层回归（27 用例，无宿主依赖） │ └── test-tool-execute.mjs # 编排层集成回归（fake ctx，16 用例） └── dev/ # 内部研发基线与 changelog（不入发布包，见 dev/README.md）

模型体验

run_command 工具 schema

模型所见内容

工具的名称、描述（含配置的等待窗口）、参数（command、cwd、wait_ms、description，以及仅在挂载 confining executor 时才出现的升级参数对），以及字符串输出契约。

Token 影响

插件挂载期间固定：每次提示词组装对应一条工具 schema 条目。

KV 缓存影响

前缀稳定：除非部署覆盖 waitMsBeforeAsync，或组合的 confinement 改变了所声明的参数，否则 schema 文本在各轮次间保持一致。

方言引导提示词段落

模型所见内容

一个常驻的系统提示词段落（tool:run_command），用于教授在裸组合中实际观察到的各类失败情形：逐字脚本片段语义（绝不整条命令加引号）、SSH 远程参数使用单引号包裹（bash 风格的 \" 嵌套会静默损坏），以及使用内置命令（fc.exe /b、Get-FileHash、CRLF 计数）进行字节级真实文件比较的惯用法，并附 Compare-Object 集合语义的注意事项。

Token 影响挂载插件期间固定：每次提示组装约 100 个 token。

KV 缓存效果

前缀稳定。

后台完成通知

模型看到的内容

由 jobs 消费者（tool-jobs）原生投递，而非本插件：一条情节式 user 角色系统消息，包含 job id、label、终态状态/详情，以及由注册表截断的输出尾部。

Token 影响

条件性：与输出尾部成正比，每个被提升且以非 killed 状态结束且未上报的 job 触发一次。

KV 缓存效果

仅追加：每条通知作为普通 user 角色消息进入会话日志，绝不替换先前内容。

已知限制与推迟的工作

- 提升会在注册表预检之前预启动 —— 与一个活跃进程竞争，本质上会在 jobs.start 运行其预检之前就启动它；被拒绝的注册会终止这次部分启动，但在该失败窗口内，进程确实短暂存在于注册表之外。
- 需要组合的 jobs 运行时 —— 没有 @deepseek-ai/dsh-jobs-local（+ tool-jobs）时，每次调用都会大声失败；不存在仅同步的降级方案，因为一个存活时间超过其轮次的命令必须保持可收集。
- 等待窗口由部署固定 —— waitMsBeforeAsync 由运维方拥有；模型无法按调用延长或跳过它（这是有意为之 —— 时序决策曾导致模型阻塞自己的轮次达数分钟）。长时间运行的守护进程每次启动都要付出完整窗口的代价；窗口内没有执行器超时，因为释放路径是提升，而非杀死。
- 隔离完整性继承自挂载的后端 —— 执行质量（例如 Windows ACL 受限令牌运行器）是执行器的契约，而非本插件的。
- 预设安装器会跳过已存在的目录 —— 打包预设的编辑不会传播到已安装的副本，除非手动同步。
- 退出标准 —— 本插件之所以存在，是因为原生 shell 工具缺乏自动提升语义。如果上游吸收了这些语义，本插件的 shell 面就应退役。

文档

- 发布面：本 README 即发布文档，自足可用。
- 内部研发基线（设计决策记录、验收报告、历史存档）与版本史：dev/，不随 npm 包发布。

开源许可

MIT