# @cogitator-ai/swarms 中文文档

规范地址：https://npmcn.com/package/%40cogitator-ai/swarms/

版本：0\.15\.12
npm 元数据更新时间：2026-10-29T00:51:12.665Z
中文译文更新时间：2026-11-10T09:57:20.866Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40cogitator-ai/swarms
原文对照：https://npmcn.com/package/%40cogitator-ai/swarms/?lang=original
源码仓库：https://github.com/cogitator-ai/Cogitator-AI

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：956 kB，227 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=22\.12\.0
- 运行依赖：7 个
- 首次发布：2025-12-31T09:04:50.270Z
- 最新版本发布：2026-10-29T00:51:12.417Z
- 近 30 天下载量：11347（2026-10-11 至 2026-11-09，npm 官方下载统计）
- 已发布版本数：114（近 12 个月 114 个）

## 中文简介

多剂群协调

## 安装

```sh
npm install @cogitator-ai/swarms
```

也可以使用：`pnpm add @cogitator-ai/swarms`、`yarn add @cogitator-ai/swarms`、`bun add @cogitator-ai/swarms`

## README

# @cogitator-ai/ swarms (英语)

多剂群相协调为相克. 由AI代理的管弦乐团队拥有8个协作策略,自动模型选择,共享通信原始,工作流程集成和Redis后置的分布式执行.

## 安装

```bash
pnpm add @cogitator-ai/swarms @cogitator-ai/core
```

网站文件 : [斯瓦尔斯](https://cogitator.app/docs/swarms), (中文(简体) ), [战略](https://cogitator.app/docs/swarms/strategies), (中文(简体) ), [构建器](https://cogitator.app/docs/swarms/builder), (中文(简体) ), [通讯](https://cogitator.app/docs/swarms/communication), (中文(简体) ), [评估](https://cogitator.app/docs/swarms/assessment), (中文(简体) ), [已分发](https://cogitator.app/docs/swarms/distributed)。 。 。 .

## 快速启动

```typescript
import { Cogitator, Agent } from '@cogitator-ai/core';
import { SwarmBuilder } from '@cogitator-ai/swarms';

const cogitator = new Cogitator({ llm: { defaultModel: 'ollama/llama3.2' } });
const model = 'ollama/llama3.2';

const swarm = new SwarmBuilder('dev-team')
  .strategy('hierarchical')
  .supervisor(new Agent({ name: 'lead', model, instructions: 'Coordinate the team' }))
  .workers([
    new Agent({ name: 'coder', model, instructions: 'Write code' }),
    new Agent({ name: 'tester', model, instructions: 'Test code' }),
  ])
  .build(cogitator);

const result = await swarm.run({ input: 'Build a REST API for user management' });
console.log(result.output);
```

战略为代理人提供他们所需要的工具:分级主管得到 `delegate_task`, (中文(简体) ), `check_progress`, (中文(简体) ), `request_revision` 财务报告和审定财务报表 `list_workers`,共识选民获得投票工具,谈判代理人获得谈判工具,牵头人和团队成员获得任务清单和邮箱工具. `agentTools` 将信件和黑板工具添加到每个代理中(参见 [内建的 Swarm 工具](https://npmcn.com/package/%40cogitator-ai/swarms/#readme-built-in-swarm-tools)) (中文(简体) ). 已定义的同名代理工具将保留 .

## 特征

-   **8 协调战略** - 等级、轮旋、共识、拍卖、管道、辩论、谈判、团队
-   **自动选择模型** —— 说 `SwarmAssessor` 匹配模型与代理角色
-   **代理通讯** - 带有读取跟踪,共享黑板的信息总线, `message:*` 编号 : `blackboard:write` 事件
-   **内建工具** 信息、黑板、代表团、投票和谈判工具
-   **运行控制** ——每次运行超时,线状ID,生命周期回调,暂停/恢复/取消飞行中LLM呼叫
-   **复原力** ——用回转,故障链,跳转,部分结果,断路器重试
-   **资源限制** ——按运行的代号/费用/时间预算和按代理人计算的上限
-   **工作流程整合** ——以 DAG 工作流程节点运行群
-   **分配执行** - 重新支持州和工人节点 `@cogitator-ai/worker`

* * *

## 代理角色和元数据

特工将他们的群元数据(作用、专长、重量、模型锁)保存在 `agentMetadata`,按代理名称键。 槽默认自动应用 : `supervisor` → `role: 'supervisor'`, (中文(简体) ), `workers` → `role: 'worker'`, (中文(简体) ), `moderator` → `role: 'moderator'`, (中文(简体) ), `router` → `role: 'router'`。 。 。 .

```typescript
const swarm = new SwarmBuilder('debate-club')
  .strategy('debate')
  .agents([pro, con])
  .agentMetadata({
    pro: { role: 'advocate', expertise: ['economics'] },
    con: { role: 'critic', weight: 2 },
  })
  .debate({ rounds: 2 })
  .build(cogitator);
```

特工的名字必须是独特的 在群.

* * *

## 战略

### 等级

监督员通过工会向工人分配任务 `delegate_task` 工具.

```typescript
const swarm = new SwarmBuilder('dev-team')
  .strategy('hierarchical')
  .supervisor(lead)
  .workers([frontend, backend, tester])
  .hierarchical({
    maxDelegationDepth: 2, // workers may re-delegate once
    workerCommunication: false, // workers can only message the supervisor
    routeThrough: 'supervisor',
    visibility: 'summary', // supervisor sees the first 500 chars of worker output
  })
  .build(cogitator);
```

在主管轮班期间运行的工人包括在 `result.agentResults`授权给自己或主管的人被拒绝.

### 圆-罗宾

```typescript
const swarm = new SwarmBuilder('support-team')
  .strategy('round-robin')
  .agents([support1, support2, support3])
  .roundRobin({
    rotation: 'sequential',
    sticky: true,
    stickyKey: (input) => String(input).slice(0, 20),
  })
  .build(cogitator);
```

与 `sticky: true` 一个已知 `stickyKey` 保留在先处理它的代理; 新密钥继续旋转 。 无 `stickyKey` 每次跑步都旋转.

### 协商一致

代表投票 `VOTE: <decision>` 在答复中或与 `cast_vote` 工具,选民自动与 `get_votes`, (中文(简体) ), `change_vote` 财务报告和审定财务报表 `get_consensus_status`。当裁决占 **所有符合条件的选民** 达到临界值后,它不会被捆绑;弃权者将被计数.

```typescript
const swarm = new SwarmBuilder('review-board')
  .strategy('consensus')
  .agents([security, performance, ux])
  .consensus({
    threshold: 0.66,
    maxRounds: 3,
    resolution: 'weighted', // 'majority' | 'unanimous' | 'weighted'
    weights: { security: 2 },
    onNoConsensus: 'escalate', // 'fail' | 'supervisor-decides' | 'escalate'
  })
  .build(cogitator);

const result = await swarm.run({ input: 'Approve the new caching layer?' });
console.log(result.votes);
```

### 管道

```typescript
const swarm = new SwarmBuilder('content-pipeline')
  .strategy('pipeline')
  .pipeline({
    stages: [
      { name: 'research', agent: researcher },
      { name: 'draft', agent: writer, gate: true },
      { name: 'edit', agent: editor },
    ],
    gates: {
      draft: {
        condition: (output) => String(output).length > 200,
        onFail: 'retry-previous', // 'abort' | 'skip' | 'goto:<stage>'
        maxRetries: 2,
      },
    },
  })
  .build(cogitator);

const result = await swarm.run({ input: 'Write about vector databases' });
console.log(result.pipelineOutputs);
```

与 `new Swarm(cogitator, config)` 阶段也可以作为顶级 `stages` 字段; `gates` 财务报告和审定财务报表 `stageInput` 仍然来自 `pipeline`,两地的不同阶段都被拒绝.

### 辩论

```typescript
const swarm = new SwarmBuilder('analysis-team')
  .strategy('debate')
  .agents([optimist, skeptic])
  .agentMetadata({ optimist: { role: 'advocate' }, skeptic: { role: 'critic' } })
  .moderator(moderator)
  .debate({ rounds: 3, format: 'structured', maxTokensPerTurn: 400 })
  .build(cogitator);
```

转弯贴有演讲者的姓名和角色标签(`[optimist (advocate)]: ...`) (中文(简体) ). `synthesisPrompt` 替换主持人的默认任务,改为 `{topic}` 财务报告和审定财务报表 `{transcript}` 填报. `maxTokensPerTurn` 是一个回合的答案的长度:一个模型的输出限制没有道理,长度辩论者被要求保持. 一个推理模型用同一限度的推理,所以它所花去的转弯(切出或空出,几乎没有可见的文字)再次跑去,上面有空间讲道理: `reasoningTokensPerTurn`4096年,或比它推理的两倍 设定 `reasoningTokensPerTurn` 从第一次尝试开始就给这个空间;其中的指示,而不是提供者,让答案简短。 一个没有理由保持限制的模型,一个叫做工具的转弯就再也不会运行了.

### 拍卖

```typescript
const swarm = new SwarmBuilder('contractor-pool')
  .strategy('auction')
  .agents([contractorA, contractorB])
  .auction({
    bidding: 'capability-match', // agents bid via LLM; or 'custom' with bidFunction
    selection: 'highest-bid', // or 'weighted-random'
    minBid: 0.3,
  })
  .build(cogitator);
```

### 谈判

代理人通过谈判工具与结构化报价进行谈判(`make_offer`, (中文(简体) ), `counter_offer`, (中文(简体) ), `accept_offer`, (中文(简体) ), `reject_offer`,联盟,利益. 发价一旦成为协议 **每个收件人** 已经接受.

```typescript
const swarm = new SwarmBuilder('deal-makers')
  .strategy('negotiation')
  .agents([buyer, seller])
  .negotiation({
    maxRounds: 6,
    onDeadlock: 'arbitrate', // 'escalate' | 'supervisor-decides' | 'majority-rules' | 'arbitrate' | 'fail'
    maxOffersPerRound: 2,
    offerTimeout: 120_000,
    turnTimeout: 60_000,
    allowCoalitions: false,
    quorum: 1, // all parties must be part of the agreement
  })
  .build(cogitator);

const result = await swarm.run({ input: 'Agree on price and delivery date' });
console.log(result.negotiationResult?.agreement);
```

当发现停滞时,该战略提出一种折衷方案,作为来自 `mediator`; 代理接受时 `accept_offer`。 。 。 .

核准大门`approvalGates`将每项请求与 `negotiation:approval-required` 活动。 有个门 `timeout` 决议的执行情况 `timeoutAction`一个没有一个人的大门等着你的回答 一个跑步 `timeout` 或者说 `swarm.abort()` 别等了.

```typescript
import type { NegotiationApprovalRequest } from '@cogitator-ai/types';

swarm.on('negotiation:approval-required', (event) => {
  const { request } = event.data as { request: NegotiationApprovalRequest };
  swarm.respondToApproval(request.id, {
    requestId: request.id,
    decision: 'approved',
    approved: true,
    continueNegotiation: false,
    respondedBy: 'legal-team',
    respondedAt: Date.now(),
  });
});
```

### 团队

代理团队 以克洛德·克洛德·克洛德的代理团队的精神:一个领导将工作规划成一个共同的任务列表,成员声称或被分配任务并通过他们工作,每个人都通过邮箱交谈,由领导从结果中写出最后的答案. 领先者是小群 `supervisor` (单位:千美元)`.lead()` 在建设者,成员是它的 `workers` (单位:千美元)`.members()`) (中文(简体) ).

```typescript
const swarm = new SwarmBuilder('newsroom')
  .strategy('team')
  .lead(new Agent({ name: 'editor', model, instructions: 'Plan the article and assign the work' }))
  .members([
    new Agent({ name: 'researcher', model, description: 'Finds facts', instructions: 'Research' }),
    new Agent({ name: 'writer', model, description: 'Writes clearly', instructions: 'Write' }),
  ])
  .team({ maxTurnsPerMember: 6, maxConcurrentMembers: 2 })
  .build(cogitator);

const result = await swarm.run({ input: 'Write an article about tides' });
console.log(result.output);
console.log(result.teamResult?.tasks); // every task with its status, owner and result
```

如何运行去:

-   领先者走第一弯 并创建任务 `create_task` (单位:千美元)`dependsOn` 使任务等待别人, `assignee` 给予成员)和 `assign_task`如果请求不需要团队,它立即回答,运行结束于那里(`stopReason: 'no-tasks'`) (中文(简体) ).
-   一个任务是 `pending`, (中文(简体) ), `in_progress` 或者说 `completed`状态 `write_todos`。无法要求完成一个未完成的依赖性任务,完成一个任务就可以解开等待它的任务,而一个成员每次执行一个任务.
-   成员在有任务时转一圈:被指派的,或与 `selfClaim` 下一个未指定未被屏蔽的。 这个任务在转弯前被声称,在黑板上一个同步的步骤中,所以两个成员从来没有得到同样的任务. 未分配的任务在领先时等待,因为领先者仍可能指派它们.
-   每个探员都有邮箱. `send_message` 向成员、领导人写信`"lead"`)或对所有人(`"everyone"`),并有一个消息唤醒它的收件人. 每条消息都由发送消息的代理标识,并随即发出通知,告知是来自另一个代理,而不是用户,因此队友的认可要求从不被视为用户的.
-   当消息到达它时,当没有人能够继续剩下的任务(例如分配给一个使用其转会的成员的任务)时,主角会有一个转会. 一旦每一项任务完成,或者没有代理商有原因或左转,主角会从任务结果中写出最后的答案.

| 工具 | 铅 | 成员 | 它会做什么 |
| --- | --- | --- | --- |
| `create_task` | 对 |  | 在列表中添加任务 `dependsOn`, (中文(简体) ), `assignee` 和可选 `id` |
| `assign_task` | 对 |  | 赋予成员一个待决任务 |
| `list_tasks` | 对 | 对 | 任务列表, 包含状态、 拥有者、 阻塞器和结果, 以及可采取的措施 |
| `claim_task` |  | 对 | 启动命名的任务, 或者成员可以接受的下一个任务 |
| `update_task` | 对 | 对 | 完成一项任务并公布其成果(`pending`)或添加注释 |
| `send_message` | 对 | 对 | 写信给一个成员, `lead` 或者说 `everyone` |
| `read_inbox` | 对 | 对 | 读取未读信件, 每封信都有发送者标记 |

| 选项 | 默认 | 说明 |
| --- | --- | --- |
| `tasks` | `[]` | 领先者初轮前列表中的任务( :`TeamTaskInput[]`(中文(简体) ) |
| `selfClaim` | `true` | 成员不承担未分配的任务,而只负责分配的任务 |
| `maxConcurrentMembers` | `resources.maxConcurrency` 或4个 | 同时工作的成员 |
| `maxLeadTurns` | `6` | 在最后答案之前进行先行转弯,包括第一次转弯 |
| `maxTurnsPerMember` | `8` | 每个成员转身,一个成员转出转身,将其任务退回到名单中 |
| `maxTasks` | `50` | 任务列表控件 |
| `synthesize` | `true` | 主角写最后的答案,没有它,输出就是任务及其结果 |

每一个转弯都会花掉这些有限的预算之一 所以跑步总是结束的. `result.teamResult` 拥有任务,每个代理的状态(`idle`, (中文(简体) ), `working`, (中文(简体) ), `stopped`, (中文(简体) ), `failed`),转动和 `stopReason`数字 : `completed`, (中文(简体) ), `no-tasks`, (中文(简体) ), `stalled` (没有人可以继续)或 `turn-limit`. 轮到失败的成员失败,除非 `errorHandling` 请求 `partialResults` 或者说 `onAgentFailure: 'skip'`:然后它被标记失败,它的任务会回到列表中去. 团队战略只在过程中运行,比如 `hierarchical` 财务报告和审定财务报表 `negotiation`。 。 。 .

任务列表位于黑板区 `team` 还有信息总线上的邮箱. `TeamTaskBoard` 财务报告和审定财务报表 `TeamMailbox` \* 直接从事试验或定制战略方面的工作 `team:*` 事件(见 [沼泽事件](https://npmcn.com/package/%40cogitator-ai/swarms/#readme-swarm-events)报告每个变化, 足以吸引团队现场 [协作工作室](https://cogitator.app/docs/getting-started/studio) 已经.

* * *

## 正在运行 Swarars

```typescript
const result = await swarm.run({
  input: 'Plan the release',
  threadId: 'release-42', // each agent uses thread `release-42:<agent>`
  timeout: 120_000, // rejects with SwarmTimeoutError and cancels the run
  saveHistory: false,
  context: { project: 'cogitator' },
  onAgentStart: (agent) => console.log('start', agent),
  onAgentComplete: (agent, run) => console.log('done', agent, run.usage.totalTokens),
  onAgentError: (agent, error) => console.error(agent, error.message),
  onMessage: (message) => console.log(`${message.from} → ${message.to}`),
  onEvent: (event) => console.log(event.type),
});
```

A 类 `Swarm` 实例一次执行一个任务; 为并行运行创建单独的实例.

飞行中LLM的呼叫中断, 飞行中它的战略依然没有启动进一步的代理或复试, 即使在之后 `run()` 已经拒绝, 或开始下一跑 相同的群。 协调员将战略工作与 `runInScope(scope, work)` (单位:千美元)`BaseSwarmCoordinator`),所以每个代理运行都取去启动它的运行的线程,用户并中止信号.

### 暂停、恢复、中止、重置

```typescript
const running = swarm.run({ input: 'Long task' });

swarm.pause(); // agents wait before their next turn
swarm.resume();
swarm.abort(); // rejects pending turns and cancels in-flight LLM calls

await running.catch(() => {});
await swarm.reset(); // clears abort state, budgets, messages and blackboard
```

* * *

## 处理错误和限制

```typescript
const swarm = new SwarmBuilder('resilient-team')
  .strategy('round-robin')
  .agents([primary, backup])
  .errorHandling({
    onAgentFailure: 'failover', // 'retry' | 'failover' | 'skip' | 'abort'
    failover: { primary: 'backup' },
    retry: { maxRetries: 3, backoff: 'exponential', initialDelay: 500, maxDelay: 10_000 },
    circuitBreaker: { enabled: true, threshold: 5, resetTimeout: 30_000 },
    partialResults: true, // parallel phases return the agents that succeeded
  })
  .resources({
    maxConcurrency: 4,
    tokenBudget: 100_000, // per run
    costLimit: 5,
    timeout: 300_000,
    perAgent: { maxTokens: 2_000, maxIterations: 5, timeout: 60_000 },
  })
  .build(cogitator);

const usage = swarm.getResourceUsage();
```

`CircuitBreaker` 财务报告和审定财务报表 `ResourceTracker` 用于独立使用.

其代理暂停工具审批的转弯( T)`requiresApproval`失败 `AgentRunPausedError` 从 `@cogitator-ai/core`,带有等待呼叫和检查点,而不是通过前工具文本作为答案. 它从未被重试过,跳过或失败过,也没有绊倒断路器.

* * *

## 代理通讯

### 消息总汇

```typescript
await swarm.messageBus.send({
  swarmId: swarm.id,
  from: 'operator',
  to: 'coder',
  type: 'notification',
  content: 'Use TypeScript strict mode',
});
```

未读信件被注入到收件人的下个转折中 `message:received` 活动). `maxMessagesPerTurn` 限制代理人每转弯发送多少信息.

### 黑板

```typescript
const swarm = new SwarmBuilder('research-team')
  .strategy('hierarchical')
  .supervisor(lead)
  .workers([researcher])
  .messaging({ enabled: true, maxMessagesPerTurn: 5 })
  .blackboardConfig({ enabled: true, sections: { findings: [] }, trackHistory: true })
  .observability({ messageLogging: true, blackboardLogging: true })
  .build(cogitator);

swarm.blackboard.subscribe('findings', (data, writer) => console.log(writer, data));
```

* * *

## 内建的 Swarm 工具

启用 `agentTools` 以给每个代理服务器发送消息和黑板工具,并绑定在swarm自己的总线和黑板上(仅本地swarms;在分发时或当总线/黑板被禁时被拒绝) :

```typescript
const swarm = new SwarmBuilder('research-team')
  .strategy('round-robin')
  .agents([researcher, writer])
  .agentTools({ messaging: true, blackboard: true })
  .build(cogitator);
```

共识选民自动获得投票工具。 对于海关战略和协调员,工厂建立任何成套工具:

```typescript
import { createSwarmTools, createStrategyTools, type SwarmToolContext } from '@cogitator-ai/swarms';

const context: SwarmToolContext = {
  coordinator, // the swarm coordinator (SwarmCoordinatorInterface)
  blackboard: swarm.blackboard,
  messageBus: swarm.messageBus,
  events: swarm.events,
  agentName: 'coder',
  swarmId: swarm.id,
};

const allTools = createSwarmTools(context); // messaging, blackboard, delegation, voting, negotiation
const hierarchicalTools = createStrategyTools('hierarchical', context);
```

| 工厂 | 工具 |
| --- | --- |
| `createMessagingTools` | `send_message` (可选) `waitForReply`, (中文(简体) ), `read_messages` (已读出返回的标记信件), `broadcast_message`, (中文(简体) ), `reply_to_message` |
| `createBlackboardTools` | `read_blackboard`, (中文(简体) ), `write_blackboard` (单位:千美元)`merge` 扩展数组/ 合并对象), `append_blackboard`, (中文(简体) ), `list_blackboard_sections`, (中文(简体) ), `get_blackboard_history` |
| `createDelegationTools` | `delegate_task`, (中文(简体) ), `check_progress`, (中文(简体) ), `request_revision`, (中文(简体) ), `list_workers` |
| `createVotingTools` | `cast_vote`, (中文(简体) ), `get_votes`, (中文(简体) ), `change_vote`, (中文(简体) ), `get_consensus_status` |
| `createNegotiationTools` | `make_offer`, (中文(简体) ), `counter_offer`, (中文(简体) ), `accept_offer`, (中文(简体) ), `reject_offer`, (中文(简体) ), `get_negotiation_status`, (中文(简体) ), `get_current_offers`, (中文(简体) ), `propose_coalition`, (中文(简体) ), `join_coalition`, (中文(简体) ), `declare_interests` |
| `createTeamTools` | `create_task`, (中文(简体) ), `assign_task`, (中文(简体) ), `list_tasks`, (中文(简体) ), `claim_task`, (中文(简体) ), `update_task`, (中文(简体) ), `send_message`, (中文(简体) ), `read_inbox` (单位:千美元)`teamToolsFor(tools, role)` 选择主角或成员) |

通过 `createSwarmTools`编号 :`createStrategyTools` 执行分级沟通政策`createHierarchyMessageAuthorizer`) (中文(简体) ).

* * *

## 自动模型选择系统

```typescript
const swarm = new SwarmBuilder('smart-team')
  .strategy('hierarchical')
  .supervisor(lead)
  .workers([coder, analyst])
  .agentMetadata({ lead: { locked: true }, coder: { expertise: ['code'] } })
  .withAssessor({
    mode: 'rules',
    preferLocal: true,
    minCapabilityMatch: 0.3,
    maxCostPerRun: 0.5,
    enabledProviders: ['ollama', 'openai'],
  })
  .build(cogitator);

const preview = await swarm.dryRun({ input: 'Build a recommendation engine' });
for (const a of preview.assignments) {
  console.log(`${a.agentName}: ${a.assignedModel} (score ${a.score})`);
}

await swarm.run({ input: 'Build a recommendation engine' });
console.log(swarm.getLastAssessment()?.assignments);
```

指定型号具有提供者资格(例如:. `ollama/llama3.2:3b`) (中文(简体) ). 未锁定的代理被运行指定模型的克隆人所取代;被锁定的代理保留了他们的代理.

`mode: 'rules'` (默认)用关键词规则分析任务. `'ai'` 让 `assessorModel` (默认:Cogitator的默认模型)分析; `'hybrid'` 增加了每个硬要求 规则检测。 两者在模型无法运行时都会以警告回落到规则. 内部只提供云模型,其提供方可使用 Cogitator 路由(配置的 API 密钥) ; 独立, 将 Cogitator 传递到 `createAssessor(config, cogitator)` 对同样的行为.

* * *

## 工作流程整合

```typescript
import { WorkflowBuilder, WorkflowExecutor } from '@cogitator-ai/workflows';
import { swarmNode, parallelSwarmsNode } from '@cogitator-ai/swarms';

const workflow = new WorkflowBuilder<{ document: string; analysis?: unknown }>('analysis-flow')
  .initialState({ document: '' })
  .addNode(
    'analyze',
    swarmNode(analysisSwarm, {
      inputMapper: (state) => state.document,
      stateMapper: (result) => ({ analysis: result.output }),
    })
  )
  .build();

const result = await new WorkflowExecutor(cogitator).execute(workflow, {
  document: 'Analyze this...',
});
```

`conditionalSwarmNode(swarm, condition, options)` 财务报告和审定财务报表 `parallelSwarmsNode([{ swarm, key }], merge)` 也可查阅。 传出 a `SwarmConfig` 而不是一个 `Swarm` 以每次执行时创建(并关闭)新的组群。 节点将工作流程运行的中止信号传递给swarm,因此节点超时,暂停或取消它及其代理转会. 外部工作流程, `swarm.run({ input, signal })` 同样的信号.

* * *

## 沼泽事件

```typescript
swarm.on('agent:complete', (event) => console.log(event.agentName));
swarm.once('swarm:complete', () => console.log('done'));
const unsubscribe = swarm.on('*', (event) => console.log(event.type));
unsubscribe();
```

订阅在协调员在模型评估后进行的重建中幸存下来.

| 活动 | 说明 |
| --- | --- |
| `swarm:start` 编号 : `swarm:complete` 编号 : `swarm:error` | 运行生命周期 |
| `swarm:paused` 编号 : `swarm:resumed` 编号 : `swarm:aborted` 编号 : `swarm:reset` | 控制行动 |
| `agent:start` 编号 : `agent:complete` 编号 : `agent:error` | 代理转弯 |
| `message:sent` 编号 : `message:received` | 向代理发送/ 发送巴士信息 |
| `blackboard:write` | 已写出或已删除的部分 |
| `assessor:complete` | 模型评估完成 |
| `consensus:*`, (中文(简体) ), `debate:*`, (中文(简体) ), `auction:*`, (中文(简体) ), `pipeline:*`, (中文(简体) ), `round-robin:assigned`, (中文(简体) ), `negotiation:*` | 战略进展 |
| `team:start` 编号 : `team:complete` | 团队运行生命周期,有停止的理由 |
| `team:member-started` 编号 : `team:member-finished` | 领导或成员转身,有其原因 |
| `team:task-created` 编号 : `team:task-assigned` 编号 : `team:task-claimed` 编号 : `team:task-updated` 编号 : `team:task-completed` | 任务列表更改, 每个任务都按现在的样子 |
| `team:message-sent` | 信件写入邮箱 |

每项数据 `team:*` 事件类型为 `TeamEventMap` 从 `@cogitator-ai/types`数字 :

```typescript
import type { TeamEventMap } from '@cogitator-ai/types';

swarm.on('team:task-completed', (event) => {
  const { task, unblocked } = event.data as TeamEventMap['team:task-completed'];
  console.log(`${task.id} done by ${task.owner}, unblocks ${unblocked.join(', ')}`);
});
```

* * *

## 分配执行

与 `distributed.enabled`这群人把信息公交车、黑板 和雷迪斯的事件都保留下来 并且派每个特工都转身 工人节点从 `@cogitator-ai/worker` 执行转弯,并将结果交回.

```typescript
const swarm = new SwarmBuilder('distributed-team')
  .strategy('pipeline')
  .pipeline({
    stages: [
      { name: 'draft', agent: writer },
      { name: 'review', agent: reviewer },
    ],
  })
  .distributed({
    enabled: true,
    queue: 'swarm-agent-jobs',
    timeout: 300_000,
    redis: { url: 'redis://localhost:6379', keyPrefix: 'swarm' },
    retry: { maxRetries: 2, backoff: 'exponential', initialDelay: 1000 },
    cleanupAfter: 3_600_000,
  })
  .build(cogitator);

const result = await swarm.run({ input: 'Write release notes' });
await swarm.close();
```

工人节点 :

```typescript
import { Cogitator } from '@cogitator-ai/core';
import { DistributedSwarmWorker } from '@cogitator-ai/worker';

const worker = new DistributedSwarmWorker({
  redis: { url: 'redis://localhost:6379' }, // the same Redis as distributed.redis
  keyPrefix: 'swarm', // must match distributed.redis.keyPrefix
  queue: 'swarm-agent-jobs', // must match distributed.queue
  concurrency: 4,
  cogitator: new Cogitator({ llm: { defaultModel: 'ollama/llama3.2' } }),
  tools: [searchTool, calculatorTool], // implementations of tools the agents reference
});

await worker.start();
process.on('SIGTERM', () => void worker.stop());
```

`retry` 重新发送在工人或超时时失败的工作(默认:3回转,从1000毫秒到30000毫秒的指数回转,没有再发送),一个超时工作可能仍在运行,因此其转会可以运行两次. `cleanupAfter` 组合的 Redis 状态在 `close()` (默认一小时, `0` 立即删除). `workerConcurrency` 已贬值 - 设置 `concurrency` 对工人。 war `errorHandling` (重试、故障),预算和断路工作与本地接线组相同:每个转弯都以代理电线格式承载整个代理 `@cogitator-ai/core` (答复格式、推理、停止序列、暂停和其余),并随费用、期限和旗帜而回(`truncated`, (中文(简体) ), `blocked`测量的工人. `RedisMessageBus`, (中文(简体) ), `RedisBlackboard` 财务报告和审定财务报表 `RedisSwarmEventEmitter` 用于直接使用.

`distributed.redis` 是一个 `RedisConnectionConfig` (单位:千美元)`url`, (中文(简体) ), `host`, (中文(简体) ), `port`, (中文(简体) ), `username`, (中文(简体) ), `password`, (中文(简体) ), `db`, (中文(简体) ), `tls`, (中文(简体) ), `cluster.nodes`+) 加上 (中文(简体) ) `keyPrefix`和工人的一样 这个 `url` 改为第一`rediss://` 打开TLS),而清晰的球场战胜了它. 与 `cluster` 群及其工人连接到一个Redis集群,url和球场只提供证书和TLS.

键带有Redis Cluster散列标记,带有字面括号:队列是 `<keyPrefix>:jobs:{<queue>}` 而群的状态键是 `<keyPrefix>:{<swarmId>}:...`,所以在一组中,每组坐一个槽. 更早的版本使用没有牙套的密钥,因此提升了协调员和工人的级别.

队列是可靠的 。 工人每转一转 `BLMOVE` (Redis 6.2 或更新) 从队列到自己的列表 `<queue key>:processing:<workerId>` 转一转就脱了 它有心跳键 `<queue key>:heartbeat:<workerId>` (3个期满) `heartbeatInterval`s, 5000 ms(默认), 列在该套中 `<queue key>:workers`在开始和每次拍拍时,一个工人都会把心跳回排队头部的工人的转弯移动,因此坠机的工人不会失去转弯. 工人还检查自己每节节拍的列表:一个转动,工人不会连续跑出两次节拍,例如一次A `BLMOVE` 移动时,一个被丢弃的连接失去了它的答复,回到队列的头部,并用工人自己的身份报告。 工人默默地保持了3个间隔,这算不上是消失了,所以一个被停滞的工人可以跑两次.

工人把每个结果都放在工作之下 `stateKeys.result` (单位:千美元)`<keyPrefix>:{<swarmId>}:result:<jobId>`用于 `resultTtl` ms, 协调员对较大 `timeout` 财务报告和审定财务报表 `cleanupAfter`,然后出版。 当一个转折时,当它的任何一个连接重新连接并且每隔几秒钟,协调员会读取被存储的结果,所以在重新连接时公布的结果不会丢失. 工人无法控制的结果仍在公布。 工人跳过一个结果已经存在的工作,协调员在重新发送重试之前删除所存储的结果.

组件也被导出 : `swarmJobQueueKey` 财务报告和审定财务报表 `swarmQueueKeys` 给出队列键, `deliverSwarmJobResult` (与 `DEFAULT_SWARM_RESULT_TTL`将结果带回工人的方式 `resolveRedisOptions`, (中文(简体) ), `clusterNodeOptions`, (中文(简体) ), `createSwarmRedis`, (中文(简体) ), `duplicateSwarmRedis`, (中文(简体) ), `scanSwarmKeys` 财务报告和审定财务报表 `closeSwarmRedis` 转一圈 `RedisConnectionConfig` 进入iuredis客户端(`SwarmRedis`页:1 `Redis` 或者说 `Cluster`同他们合作.

* * *

## 许可证

麻省理工学院

## 常见问题

### @cogitator-ai/swarms 是什么？

多剂群协调

### 如何安装 @cogitator-ai/swarms？

在项目目录运行 npm install @cogitator-ai/swarms，或使用 pnpm add / yarn add / bun add。

### @cogitator-ai/swarms 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @cogitator-ai/swarms 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @cogitator-ai/swarms 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=22\.12\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @cogitator-ai/swarms 可以商用吗？

@cogitator-ai/swarms 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @cogitator-ai/swarms 的下载量有多少？

根据 npm 官方下载统计，@cogitator-ai/swarms 在 2026/10/11 – 2026/11/09 这 30 天内被下载 11,347 次，日均约 378 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @cogitator-ai/swarms 还在维护吗？

最新版本 0\.15\.12 发布于 2026/10/29（12 天前）；至今共发布 114 个版本，其中过去 12 个月发布了 114 个；首次发布于 2025/12/31。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。