群体

 ███████╗██╗    ██╗ █████╗ ██████╗ ███╗   ███╗
 ██╔════╝██║    ██║██╔══██╗██╔══██╗████╗ ████║
 ███████╗██║ █╗ ██║███████║██████╔╝██╔████╔██║
 ╚════██║██║███╗██║██╔══██║██╔══██╗██║╚██╔╝██║
 ███████║╚███╔███╔╝██║  ██║██║  ██║██║ ╚═╝ ██║
 ╚══════╝ ╚══╝╚══╝ ╚═╝  ╚═╝╚═╝  ╚═╝╚═╝     ╚═╝

多智能体协调，即使上下文失效也能持续运行。

将大任务拆解为小任务。并行启动多个智能体协同工作。从成功经验中学习。

swarmtools.ai · 文档

---

安装

OpenCode

npm install -g opencode-swarm-plugin
swarm setup

完成。在任何 OpenCode 会话中使用 /swarm "你的任务"。

Claude Code

步骤 1： 全局安装 CLI（必需）：

npm install -g opencode-swarm-plugin

步骤 2： 在 Claude Code 中添加市场：

/plugin
→ 管理市场
→ 添加市场
→ 输入：joelhooks/swarm-tools

步骤 3： 安装插件：

/plugin
→ 管理插件
→ swarm-tools
→ swarm
→ 安装

MCP 服务器会自动启动。在任何会话中使用 /swarm "你的任务"。

---

功能简介

/swarm "使用 OAuth 添加用户认证"

1. 分解任务为可并行执行的子任务
2. 创建蜂巢单元（基于 Git 的任务跟踪器）
3. 启动工作者并预留文件（避免冲突）
4. 通过 Swarm Mail 协调（嵌入式事件存储）
5. 审查每次完成情况后再批准
6. 学习哪些方法有效，以便下次改进

---

核心概念

蜂巢

基于 Git 的任务跟踪系统，位于 .hive/ 目录下。跨会话持久化，并通过 Git 同步。

hive_create({ title: "修复认证漏洞", type: "bug" })
hive_cells({ status: "in_progress" })
hive_close({ id: "cell-123", reason: "已修复" })

蜂群心智

带有嵌入向量的语义记忆。存储学习内容，便于后续检索。

hivemind_store({ information: "认证需要幂等密钥", tags: "auth,gotcha" })
hivemind_find({ query: "认证模式" })

Swarm Mail

基于 Actor 模型的智能体间协调机制。包括文件预留、消息传递和检查点。

swarmmail_reserve({ paths: ["src/auth/*"], exclusive: true })
swarmmail_send({ to: ["worker-b"], subject: "需要类型", body: "..." })

---

命令

命令	描述
/swarm <task>	分解任务并启动并行工作者
/hive	查询和管理任务
/inbox	查看其他智能体的消息
/status	显示 Swarm 协调状态
/handoff	结束会话并同步手记

---

CLI

swarm setup      # 配置 OpenCode/Claude Code 集成
swarm doctor     # 检查依赖项（Ollama 用于嵌入）
swarm init       # 初始化当前项目的蜂巢
swarm config     # 显示配置路径

---

工作原理

                         你的任务
                             │
                             ▼
                    ┌────────────────┐
                    │  协调者      │
                    │                │
                    │ 1. 查询历史  │
                    │    会话      │
                    │ 2. 选择策略  │
                    │ 3. 分解      │
                    └────────────────┘
                             │
           ┌─────────────────┼─────────────────┐
           ▼                 ▼                 ▼
    ┌────────────┐    ┌────────────┐    ┌────────────┐
    │  Worker A  │    │  Worker B  │    │  Worker C  │
    │            │    │            │    │            │
    │ 🔒 文件   │───▶│ 🔒 文件   │    │ 🔒 文件   │
    └────────────┘    └────────────┘    └────────────┘
           │                 │                 │
           └─────────────────┼─────────────────┘
                             ▼
                    ┌────────────────┐
                    │   学习中心    │
                    │                │
                    │ 记录结果     │
                    │ 更新权重     │
                    └────────────────┘

---

架构

所有组件均在本地运行，无需外部服务器。

• libSQL - 嵌入式 SQLite 用于事件溯源
• 蜂巢 - 基于 Git 的 .hive/ 目录用于任务管理
• 蜂群心智 - 使用 Ollama 嵌入的语义记忆（回退至 FTS）
• Swarm Mail - 提供 DurableMailbox、DurableLock 和 DurableDeferred 原语

事件溯源

所有状态以追加方式记录在事件日志中：

agent_registered → 智能体加入 Swarm
message_sent     → 智能体间通信
file_reserved    → 获取独占锁
file_released    → 释放锁
checkpoint       → 进度快照
outcome          → 完成结果

---

学习系统

每次完成都会记录耗时、错误、涉及的文件以及是否成功。

• 模式会逐步成熟：候选 → 稳定 → 成熟
• 反模式会在失败率超过 60% 时自动生成
• 信心值会在 90 天内逐渐衰减，除非重新验证

---

依赖项

必需	可选
Bun	Ollama - 本地嵌入

运行 swarm doctor 检查状态。

嵌入模型配置

通过环境变量配置嵌入模型：

export OLLAMA_MODEL=nomic-embed-text  # 默认：mxbai-embed-large
export OLLAMA_HOST=http://localhost:11434  # 默认

支持的模型：mxbai-embed-large (1024d), nomic-embed-text (768d), all-minilm (384d), snowflake-arctic-embed (1024d)。详情请参阅 swarm-mail 文档。

---

开发

bun install
bun turbo build
bun turbo test

---

致谢

• MCP Agent Mail - 多智能体协调的灵感来源
• Electric SQL - 耐久流模式
• Superpowers - 验证模式

---

MIT

Swarm Tools 快速上手指南

Swarm 是一个专为多智能体协作设计的开源工具，旨在解决上下文丢失问题。它能将大型任务拆解为可并行执行的子任务，自动调度多个 Agent 协同工作，并通过本地持久化存储（Hive）和语义记忆（Hivemind）从历史执行中学习优化。

环境准备

在开始之前，请确保您的开发环境满足以下要求：

• 操作系统：支持 macOS、Linux 或 Windows (WSL)。
• 运行时依赖：
  • Bun (必需)：高性能 JavaScript 运行时。

    curl -fsSL https://bun.sh/install | bash
    

    (国内用户若下载缓慢，可尝试使用镜像源或手动下载安装包)
  • Node.js/npm (可选但推荐)：用于全局安装插件 CLI。
• AI 模型依赖 (可选但强烈推荐)：
  • Ollama：用于本地运行嵌入模型（实现语义记忆和任务检索）。

    curl -fsSL https://ollama.com/install.sh | sh
    ollama pull mxbai-embed-large
    

    (注：默认模型为 mxbai-embed-large，也可配置为 nomic-embed-text 等)

安装步骤

根据您使用的代码助手平台，选择以下一种方式进行安装：

方案 A：OpenCode 用户

1. 全局安装插件：

   npm install -g opencode-swarm-plugin
   

2. 初始化配置：

   swarm setup
   

3. 完成：安装成功后即可在任何 OpenCode 会话中使用。

方案 B：Claude Code 用户

1. 全局安装 CLI (必需步骤)：

   npm install -g opencode-swarm-plugin
   

2. 添加市场源： 在 Claude Code 中输入 /plugin，依次选择：

   • Manage marketplaces
   • Add marketplace
   • 输入地址：joelhooks/swarm-tools

3. 安装插件： 再次输入 /plugin，依次选择：

   • Manage plugins
   • 找到 swarm-tools -> swarm
   • 点击 Install

4. 完成：MCP 服务器将自动启动，可在任意会话中调用。

基本使用

安装完成后，无需复杂配置，直接在对话中通过 /swarm 命令即可触发多智能体协作流程。

1. 执行并行任务

输入以下命令，Swarm 会自动拆解任务、分配文件锁并调度多个 Worker 并行处理：

/swarm "Add user authentication with OAuth"

执行流程预览：

• 拆解：将任务分解为可并行的子任务。
• 追踪：在 .hive/ 目录创建 Git 支持的任务单元格。
• 锁定：为每个 Worker 预留文件路径，避免冲突。
• 协作：通过 Swarm Mail 进行代理间通信。
• 审核：在完成前审查每个子任务结果。
• 学习：记录成功模式以供未来参考。

2. 常用管理命令

命令	功能描述
/swarm <task>	拆解任务并生成并行 Worker
/hive	查询和管理任务状态
/inbox	查看来自其他 Agent 的消息
/status	查看当前协调状态
/handoff	结束会话并同步交接笔记

3. 本地 CLI 工具

除了聊天命令外，您还可以在终端直接使用以下工具进行维护：

swarm doctor     # 检查依赖状态（如 Ollama 是否就绪）
swarm init       # 在当前项目初始化 Hive 跟踪系统
swarm config     # 显示配置文件路径

提示：所有数据（任务记录、语义记忆、事件日志）均存储在本地 .hive/ 目录和嵌入式 SQLite 数据库中，无需连接外部服务器，确保数据安全与隐私。