并行代理集群 P-A-N-52/dsh-agent-swarm

dsh-agent-swarm

Kimi Code 风格的 Agent Swarm 插件，面向 DeepSeek Harness (dsh)。v0.2 是 kimi-code 的移植版：agent_swarm 工具采用 kimi 的 prompt_template + {{item}} 批量派发语义，/swarm 命令采用 kimi 的「模式 + 派发」流程——由模型自己探索、切分、并行派发子代理。

移植依据：kimi-code 的 swarm 模式指令与 AgentSwarm 工具文档。提示词为原创改写，非逐字复制。

特性

- kimi AgentSwarm 语义：description + prompt_template（含 {{item}}）+ items 数组，每个 item 展开为一个子代理的提示词；强制校验（≥2 items、模板必含占位符、展开结果互不相同）在启动前拒绝违规调用。
- 可恢复子代理：provider 支持 prepareContinuable（spawn/fork 默认支持）时，每个 worker 返回 agent_id；失败/超时的 worker 可用 resume_agent_ids: { "<agent_id>": "continue" } 在后续调用中接续上下文，而不是重开一个全新 agent。
- 每次调用的 worker 类型/模型：subagent_type 选择新 worker 的 DSH provider；model 支持 primary / secondary / 显式 model id；resume worker 保持原 provider/model。
- 每 worker 30 分钟硬超时（workerTimeoutMs 可配）：超时 worker 被中断但保留 agent_id 和 partial 输出，可继续恢复。
- Swarm 模式：/swarm <objective> 打开会话级 swarm 模式并把目标派发给模型，模型按 kimi 工作流（先探索 → 再分工 → 不要自己干主活）自行编排。
- 并发队列：启动自动排队（maxConcurrent 默认 8），总数上限 maxAgents 默认 128（kimi 同款）。
- 独占调用硬拦截：同一模型响应里混入其它工具、或多个 agent_swarm 调用，会在执行前整批拒绝，而不是静默串行。
- 可嵌套：worker 是完整 agent（继承父会话工具集），可再开自己的子代理，受 maxDepth（默认 3）深度预算约束。
- 失败容错：单个 worker 失败不拖垮 swarm，保留部分输出；可选 synthesize coordinator 汇总。
- 免重启更新：插件以版本目录挂载在 profile 内；更新代码后运行 install.sh 升一次条目名，运行中的 host 无需重启即换新版本（见下方「安装」）。
- UI：agent_swarm 工具有 Kimi 风格的专属 block——调用中实时显示 worker 网格（queued/running/settled + 每 worker 耗时），完成后按真实 status/partial/synthesis 渲染；/swarm 命令在 dsh Web 会话内有 Kimi 风格命令卡片（与 host 同包，通过 dsh.client 注册）；另附 ui/index.html 独立 UI 原型，可直接用浏览器打开预览。

安装（需要 dsh）

git clone https://github.com/P-A-N-52/dsh-agent-swarm.git
cd dsh-agent-swarm
./install.sh # 部署到 ~/.dsh/profiles/web,自动取下一个版本目录 v<N+1> ./install.sh headless # 部署到其它 profile

install.sh 做了四件事，与 dsh 的加载机制一一对应：

1. 把 lib/index.js、client.js、package.json 复制到 <profile>/plugins/dsh-tool-agent-swarm-v<N>（每次部署版本号 +1）。
2. 在依赖回退目录 ~/.dsh/profiles/node_modules/@deepseek-ai/ 下建立同名符号链接——loader 条目必须是裸 specifier，Node ESM 不能直接 import 相对目录。
3. 同步改写 client.js 里的 bundle id（客户端图按 loader 条目名对行，id 不一致会被拒绝）。
4. 把 cordis.patch.yml 里的 loader 条目 name 升到同一个版本号——运行中的 host 只有在条目名变化时才会重新 import 插件，所以不需要重启 dsh；改动被 include 插件拾取后即生效。

手动方式等价于手动执行上述四步，cordis.patch.yml 中的条目形如：

- insert:
- id: tool-agent-swarm
name: '@deepseek-ai/dsh-tool-agent-swarm-v11' # 每次更新都要升版本号 config: provider: spawn toolName: agent_swarm commandName: swarm maxAgents: 128 maxConcurrent: 8 maxDepth: 3 enableSynthesis: false 注意：name 必须是裸 specifier，且要在 ~/.dsh/profiles/node_modules/@deepseek-ai/ 下建好指向版本目录的符号链接（install.sh 会自动完成）；不要直接写 ./plugins/... 相对路径——Node ESM 无法 import 相对目录。

用法

工具（模型端）— kimi AgentSwarm 语义

agent_swarm
description 必填：整个 swarm 的短描述（UI 展示 + objective 兜底） subagent_type 可选：新 worker 的 DSH provider，如 spawn / fork（默认用配置） model 可选：新 worker 的模型 primary | secondary | 显式 model id prompt_template 模板，必须含 {{item}} 占位符，如 "Review {{item}} for likely regressions." items ≥2 个输入（有 resume_agent_ids 时可为 1），每个展开为一个子代理 resume_agent_ids 可选：{"<agent_id>": "continue"}——恢复此前失败/超时的 worker，保留其上下文 mode kimi（默认）| explore | divide synthesize 可选：true 时派 coordinator 汇总（默认关，主代理收到原始报告） objective 可选上下文（explore/divide 模式必填） workers/angles explore 模式 tasks divide 模式

模型侧工作流（写入 /swarm 派发指令和工具描述）：先少量探索 → 确定不需要子代理就说明并等待 → 需要就不要自己干主活，用 prompt_template + items 把任务切成互不重叠的 scope 并行派发；不吝啬 agent 数量，能细分就细分。每次 agent_swarm 调用必须是该轮响应中唯一的工具调用；未完成 worker 的 agent_id 会随结果返回，下一轮用 resume_agent_ids 接续。

命令（输入框）— kimi 语义

/swarm 分析这个仓库的架构 # 打开 swarm 模式并派发目标，模型自己编排 /swarm off # 退出 swarm 模式 /swarm # 查看状态

配置

| 键 | 默认 | 说明 |
| provider | spawn | 使用的 ctx.subagents provider |
| toolName | agent_swarm | 模型端工具名 |
| commandName | swarm | 命令名；null 禁用命令 |
| maxAgents | 128 | 单次调用 worker 数硬上限（kimi 同款） |
| maxConcurrent | 8 | 并发启动数，超出排队 |
| defaultWorkers | 4 | explore 模式未指定时的默认 worker 数 |
| workerTimeoutMs | 1800000 | 每个 worker 的硬超时（30 分钟）；超时可 resume |
| secondaryModel | — | model: "secondary" 使用的模型 id |
| secondaryProvider | — | model: "secondary" 使用的 LLM provider（缺省回退 agentOptions.provider → 父代理 provider） |
| maxDepth | 3 | 子代理递归深度上限（0 = 禁止委派） |
| agentOptions | — | 应用到 worker/coordinator 的 provider/model/maxTokens（三个字段均可选） |
| maxResultChars | 16000 | 渲染结果文本上限 |
| workerOutputCap | 6000 | 喂给 coordinator 的单个 worker 报告上限 |
| enableSynthesis | false | 工具 synthesize 参数的默认值 |

委派链与上限

- swarm 的 worker 可以再开自己的子代理：worker 是完整 agent（继承父会话工具集，含 subagent/subagent_fork，甚至可递归调 agent_swarm），受 maxDepth 限制：主 agent（深度 0）→ worker（1）→ 孙（2）→ 曾孙（3）；深度 3 不能再委派。
- 每次 agent_swarm 调用最多 maxAgents（默认 128）个 worker，并发受 maxConcurrent（默认 8）限制并自动排队；超出上限的 items 不会静默消失——结果中带 truncatedItems 并在渲染文本里给出警告，模型可拆分成多次调用或调高上限。每个 worker 有 workerTimeoutMs（默认 30 分钟）硬超时，超时后可 resume。普通 subagent 调用没有并发硬上限；workflow 引擎默认并发 16、单次总数 1000。

测试（本地优先）

本仓库不使用 GitHub Actions——测试本地跑：

方式一：离线，链接本机 dsh 的依赖（推荐，版本与运行环境完全一致）
npm run test:local

方式二：独立安装依赖后跑（npm registry 上有 0.1.0-rc.6，与 dsh 同版本）
npm install
npm test

测试覆盖：配置默认值、kimi 模板校验（占位符/数量/互异性）、resume_agent_ids 计划、命令解析（dispatch/off/status）、队列并发上限、失败容错、中止、汇总开关、continuable 子代理 epoch、结果渲染。

工作原理

1. tools/pre-execute 硬闸：同一 assistant 响应里 agent_swarm 与其它工具混用、或多个 agent_swarm 调用，整批 deny（kimi 同款语义）。
2. 校验参数并生成 worker 计划：resume 计划永远排在最前，且不被截断；新增的 item/task/worker 填满 maxAgents 剩余容量，超出的部分上报 truncatedItems。
3. provider 支持 prepareContinuable 时，spawn worker 走 ctx.subagents.startContinuable()，并通过 subagent/end 生命周期事件等待每个 epoch 的结果；resume worker 走 ctx.subagents.followup()。其他 provider 回退为原来的 one-shot 前台路径。
4. 每个 worker 独立受 workerTimeoutMs 硬超时；超时即中断并保留 agent_id/partial 输出。收集结果时，continuable 子代理自动投递给父代理的 settlement 通知会被清理，避免同一结果出现两次。
5. 启用汇总时，把各报告（截断）交给 coordinator 子代理合并。
6. 返回结构化结果与渲染文本（含 resume 提示）。
7. 客户端 tool.call.toolview 专属 block 实时读取 sessions 中的 subagent 状态（运行中），完成后读取 output.presentationMeta 里的结构化 worker 结果渲染网格。

许可

MIT © 2026 P-A-N-52 · 变更记录见 CHANGELOG.md