智能体集群编排 c2j/dsh-swarmforge

dsh-swarmforge

多智能体编排插件，适用于 DeepSeek Harness。

dsh-swarmforge 让你在 dsh 里定义、生成并运行智能体集群。声明一组智能体，给它们分配角色和工具，然后让它们协同完成一项任务。

功能特性

- 声明式集群定义 —— 用 YAML 描述智能体、角色和工具授权。
- 并行执行 —— 智能体并发运行，结果实时流式回传。
- 子代理生成 —— 智能体可以在运行过程中生成子代理，处理子任务。
- 工具授权 —— 精确控制每个智能体能调用哪些工具。
- 会话隔离 —— 每个智能体拥有独立上下文，互不污染。
- 钩子 —— 在智能体生命周期的关键节点挂载钩子，介入执行流程。

安装

npm install dsh-swarmforge

或者用 npx：

npx dsh-swarmforge init

快速开始

在项目根目录创建 swarm.yaml：

name: research-swarm
agents:
- name: planner
role: 把任务拆解成子任务 tools:
- task.create
- task.list
- name: researcher
role: 收集信息 tools:
- web.search
- web.fetch
replicas: 3
- name: writer
role: 汇总结果，撰写报告 tools:
- file.write

运行集群：

dsh swarm run swarm.yaml

配置

顶层字段

| 字段 | 类型 | 说明 |
| name | string | 集群名称，必填 |
| agents | array | 智能体定义列表，必填 |
| provider | string | 服务商，默认继承 dsh 配置 |
| maxConcurrency | number | 同时运行的智能体上限，默认 4 |
| timeout | number | 单个智能体超时时间，单位秒，默认 300 |

智能体字段

| 字段 | 类型 | 说明 |
| name | string | 智能体名称，集群内唯一 |
| role | string | 角色描述，会作为系统提示词注入 |
| tools | array | 允许调用的工具列表 |
| replicas | number | 副本数量，默认 1 |
| model | string | 覆盖默认模型 |
| hooks | object | 生命周期钩子 |

钩子

钩子让你在智能体执行前后插入逻辑：

agents:
- name: researcher
role: 收集信息 hooks: beforeRun: ./hooks/before-run.ts afterRun: ./hooks/after-run.ts onError: ./hooks/on-error.ts

每个钩子文件导出一个默认函数：

export default async function (ctx) {
console.log(智能体 ${ctx.agent.name} 开始运行);
return ctx;
}

子代理

智能体可以在运行时生成子代理：

const subagent = await ctx.spawn({
name: "fact-checker",
role: "核对事实",
tools: ["web.search"],
});

const result = await subagent.run("核对这份报告里的数据");

子代理继承父代理的服务商配置，但拥有独立会话。

命令行

dsh swarm init # 生成示例 swarm.yaml
dsh swarm run <file> # 运行集群
dsh swarm validate <file> # 校验配置
dsh swarm list # 列出当前项目里的集群

API

import { Swarm } from "dsh-swarmforge";

const swarm = new Swarm({
name: "research-swarm",
agents: [
{ name: "planner", role: "拆解任务", tools: ["task.create"] }, { name: "researcher", role: "收集信息", tools: ["web.search"], replicas: 3 }, ], });

swarm.on("agent:start", (agent) => {
console.log(${agent.name} 启动);
});

swarm.on("agent:finish", (agent, result) => {
console.log(${agent.name} 完成：${result.summary});
});

await swarm.run("调研 2025 年边缘计算市场");

事件

| 事件 | 参数 | 触发时机 |
| swarm:start | — | 集群开始运行 |
| swarm:finish | results | 所有智能体结束 |
| agent:start | agent | 单个智能体启动 |
| agent:finish | agent, result | 单个智能体完成 |
| agent:error | agent, error | 单个智能体报错 |
| subagent:spawn | parent, child | 生成子代理 |

许可证

MIT