dsh-plugin-background-tasks

配置（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	否	会话工作区	命令执行的工作目录；相对路径按会话身份解析
wait_ms	number	否	10000	动态同步等待毫秒数；传入 0 则直接后台启动
description	string	否	-	任务简短说明（同时作为 job 列表标签）
sandbox_permissions	string	否	-	仅限对刚发生的沙箱拒绝做一次性同轮加宽重试；需配 justification 并经用户审批（仅 confining 组合广告此参数）
justification	string	否	-	与 sandbox_permissions 成对出现的给用户的一句话理由

• 同步完成：返回退出码 + 合并输出（executor 负责输出预算与 spill 文件标注）；启动失败以 killed 结算并在 stderr 带错误，绝不悬挂。
• 转入后台：返回 [Background Task Started] 与 JobId（command-N）；此后用原生 job_* 工具管控，完成通知由 jobs 消费面自动投递。

---

安装与注册方式

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

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

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

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

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

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

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

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

---