前言¶

在 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