前言¶

在 DeepSeek Harness（DSH）里，主智能体可以通过内置的 subagent 工具委派子任务。该工具在子智能体被宿主接纳后就会返回，不会替你排队。一次性发起很多并行调用时，宿主的 maxActiveSubagents 接纳上限（默认 8）会直接拒绝超出部分；主智能体也缺少统一入口去汇总、对比各子任务结果，失败项还容易混在一堆完成通知里。

下面介绍社区插件 dsh-tool-subagent-batch（维护者 YixiangTang，分类：工作流）。它把「一批独立子任务 + 并发窗口」收成一次工具调用，用滑动窗口调度子智能体，并提供同步、异步两种交付方式。DSH 生态主张「一切皆插件」；插件目录站点 SkillHub 由社区维护，与 DeepSeek / 幻方无官方从属关系。

这是什么¶

dsh-tool-subagent-batch 是面向 DSH 子智能体的滚动窗口批处理调度器：一次调用携带任务队列和并发窗口，最多同时运行 N 个子智能体；任意一个子任务结束，队列中的下一个立刻补位，而不是等整批固定分块跑完。

启用后，模型可见两个工具：

• subagent_batch：提交批任务并启动调度；
• subagent_batch_status：查询异步批次进度、阻塞等待或取消。

当前 package 版本为 0.3.0，许可证 MIT，运行时依赖为 0（仅 Node 内置模块）。

与内置 subagent 的差异¶

同步模式（sync）适合「现在跑完这批并给我完整报告」；异步模式（async）适合长批次或希望主智能体先继续别的工作，之后再收取结果。

核心功能¶

已核实能力包括：

1. 两种模式、一套调度器：sync 阻塞至全部任务结束；async 立即返回 batchId，池子在同一 DSH 进程内后台继续运行。
2. 滑动窗口：并发槽在任意子任务 settle 后立即 refill，而非整批结束后才开下一批。
3. 用户主导的并发：通过 profile 配置、环境变量 DSH_SUBAGENT_BATCH_CONCURRENCY，或 concurrency: auto 时的硬件推荐；默认不允许模型改并发，除非开启 allowModelConcurrency。
4. 硬件感知推荐：CLI node bin/recommend.mjs 或 npx dsh-subagent-batch-recommend --json，结合逻辑核心、内存与宿主接纳上限给出建议值。
5. 逐任务验收报告：每项含 status、最终 output、stopReason、durationMs、childId 等；单任务输出可裁剪（默认 outputCharsPerTask: 12000）。
6. 失败隔离与可选 fail_fast：单个子任务失败不阻塞队列；可配置遇错即停。
7. 容量退避：宿主接纳拒绝时按 30 次 × 500 ms 重试后再记失败。
8. 深度保护：遵守宿主 subagent.maxDepth 与当前委派深度。
9. 协作式取消：同步模式中止工具调用；异步模式对 subagent_batch_status 传 cancel: true。
10. 异步状态查询：轮询快照、wait + timeout_ms 阻塞等待，或取消；已完成批次在内存中保留最近若干次查询（retainedBatches，默认 16）。

环境要求（来自 README）：

安装与启用¶

安装目标：让当前 profile 加载插件，使 subagent_batch 与 subagent_batch_status 对模型可见。官方文档提供两种方式，任选其一。

方式一：作为 bundle 包（推荐）¶

适合像普通 DSH 插件一样用 dsh plugin 管理：

git clone https://github.com/<you>/dsh-tool-subagent-batch.git
cd dsh-tool-subagent-batch
dsh plugin --profile desktop add "link:$PWD"

Windows PowerShell 示例：

dsh plugin --profile desktop add "link:E:\path\to\dsh-tool-subagent-batch"

在 profile 的 package.json 中加入 bundle（profile 名按你的环境替换 desktop）：

{
  "dsh": {
    "profile": {
      "bundles": [
        "@deepseek-ai/dsh-base",
        "@deepseek-ai/dsh-web-app",
        "dsh-tool-subagent-batch"
      ]
    }
  }
}

也可在 DSH Plugins 页面启用该包，然后重载或重启 profile。包内通过 cordis.patch.yml 声明 patch。

方式二：绝对路径零安装挂载¶

不修改 node_modules 时，在 $DSH_HOME/profiles/<profile>/cordis.patch.yml 增加：

- insert:
    - id: tool-subagent-batch
      name: 'E:/path/to/dsh-tool-subagent-batch/index.js'
      config:
        concurrency: auto
        mode: sync

路径需加引号；Windows 下推荐正斜杠。启用 HMR 的 profile 可自动重载，否则需重启 DSH。

常用配置项¶

挂载时可在 config 中设置（节选）：

未知字段会在挂载时报错，避免静默拼写错误。单次调用还可传 fail_fast：默认单个失败不中断队列；为 true 时停止启动新任务，已在运行的子智能体仍会跑完。

典型用法¶

同步批处理¶

向主智能体说明意图后，模型调用 subagent_batch，示例参数结构如下（任务内容按实际替换）：

{
  "tasks": [
    { "description": "审查认证模块", "prompt": "审查 src/auth，关注……只报告发现的问题。" },
    { "description": "审查计费模块", "prompt": "审查 src/billing，关注……" },
    { "description": "审查搜索模块", "prompt": "审查 src/search，关注……" }
  ],
  "mode": "sync",
  "fail_fast": false
}

当配置的并发为 3 时，三个子智能体同时启动；若为 2，则第三个在前两个中任意一个结束的瞬间补位。调用阻塞至全部结束，工具返回值即完整报告。

异步批处理与收取¶

启动批次：

{
  "tasks": [
    { "description": "审查认证模块", "prompt": "审查 src/auth，关注……" },
    { "description": "审查计费模块", "prompt": "审查 src/billing，关注……" }
  ],
  "mode": "async"
}

调用会立即返回带 batchId 的运行中快照；池子在后台继续。异步模式不会向父会话推送完成消息，需主动调用 subagent_batch_status。

阻塞等待示例：

{
  "batchId": "batch-1f0c...",
  "wait": true,
  "timeout_ms": 120000
}

仅查进度可只传 batchId；取消运行中批次可传 "cancel": true。timeout_ms 范围 1000..600000，默认 60000。只有启动该批次的会话可以读取或取消它。

推荐并发数¶

在插件目录下执行：

node bin/recommend.mjs

或：

npx dsh-subagent-batch-recommend --json

将输出的整数写入 cordis.patch.yml 的 config.concurrency 即可固定窗口。

适用场景与注意¶

适合谁

• 需要并行审查多个独立目录、模块或文档，且希望结果在一份报告里验收；
• 子任务数量超过宿主默认并行接纳上限，但仍希望有序排队而非被拒；
• 长批次希望主智能体先处理其他对话，再用 subagent_batch_status 收取。

使用前请注意

1. 插件在当前 DSH 进程权限下运行，子智能体行为与宿主配置（provider、深度、接纳上限）一致。安装或挂载前请阅读 GitHub 源码 与 MIT 许可证，确认符合你的安全与合规要求。
2. 异步批次占用进程内资源；maxAsyncBatches（默认 8）与 retainedBatches 限制同时运行与可查历史批次数量。
3. 社区目录页星标等元数据会变动；以仓库 README 与 release 为准。

结尾¶

dsh-tool-subagent-batch 把 DSH 子智能体并行从「多次接纳、分散通知」整理成「有界滑动窗口 + 汇总报告」，并区分同步阻塞与异步后台两种工作流。若你在 Harness 里经常批量委派子任务，可以在 profile 中启用该插件后再试一轮真实任务。

• 社区目录：https://www.skillhub.cn/plugins/YixiangTang/dsh-tool-subagent-batch
• 源码与文档：https://github.com/YixiangTang/dsh-tool-subagent-batch