# swarmagent **Repository Path**: hmk_855_admin/swarmagent ## Basic Information - **Project Name**: swarmagent - **Description**: SwarmAgent — 蜂群 Agent 协作模板 - **Primary Language**: Unknown - **License**: MIT - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-05-18 - **Last Updated**: 2026-07-17 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # SwarmAgent — 蜂群 Agent 协作模板 [English](README.md) | **中文** [![GitHub](https://img.shields.io/badge/GitHub-hanmengkai%2Fswarmagent-181717?logo=github)](https://github.com/hanmengkai/swarmagent) [![Gitee](https://img.shields.io/badge/Gitee-hmk__855__admin%2Fswarmagent-C71D23?logo=gitee)](https://gitee.com/hmk_855_admin/swarmagent) ![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg) ![Version](https://img.shields.io/badge/version-2.1.0-blue.svg) ![Platform Agnostic](https://img.shields.io/badge/platform-agnostic-green.svg) > **平台无关的多 Agent 协作模板** > 用 Supervisor + Specialist 分层架构，快速搭建任何领域的 AI Agent 团队 > 无框架绑定 · MCP Skills 即插即用 · SSE 流式通信 · 黑板共享工作区 --- ## 为什么选择 SwarmAgent？ 多数 Agent 框架（MetaGPT、AutoGen、CrewAI）预设了固定角色和工作流，适合特定场景（如自动编程）。 SwarmAgent 是**模板**，而不是框架： | 对比项 | 固定框架（MetaGPT 等）| SwarmAgent | |--------|---------------------|------------| | 角色 | 预设（PM/Architect/QA 等）| 完全自定义 | | 工作流 | 软件公司流程 | 四种模式可选 | | 平台依赖 | 框架自身 | 无，可接入任何平台 | | 适用场景 | 自动化编码 | 任意领域 Agent 产品 | --- ## 架构概述 ``` ┌─────────────────────────────────────────────────────────────┐ │ 用户请求入口 │ └─────────────────────────────────────────────────────────────┘ │ SSE 流式响应 ▼ ┌─────────────────────────────────────────────────────────────┐ │ Supervisor Agent（协调者/主脑） │ │ - 任务理解与分解 │ │ - 智能路由分发 │ │ - 结果聚合与质量把控 │ │ - 会话上下文管理 │ └─────────────────────────────────────────────────────────────┘ │ call_agent / spawn_agent ┌─────────────────────┼─────────────────────┐ │ │ │ ▼ ▼ ▼ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ Researcher │ │ Writer │ │ Coder │ │ 调研专家 │ │ 写作专家 │ │ 工程专家 │ └──────────────┘ └──────────────┘ └──────────────┘ │ │ │ └──────── 黑板（共享工作区）+ MCP Skills ────┘ ``` ### 核心特性 | 特性 | 说明 | |------|------| | **平台无关** | 不绑定任何框架，可接入 LangGraph、CrewAI、自建网关等 | | **黑板机制** | 共享工作区，成果跨 agent 复用，避免重复生产 | | **三层记忆** | 短期（上下文窗口）/ 工作（会话黑板）/ 长期（MCP memory） | | **MCP Skills** | 遵循 Model Context Protocol，直接加载数百个开源 skill | | **错误恢复** | 指数退避重试 + 检查点断点续传 + 优雅降级 | | **审批门** | 高风险操作必须人工确认，不可跳过 | | **会话体系** | 每次交互绑定 session_id，支持上下文干预与历史回放 | | **流式输出** | SSE 协议，全程流式，可观测 agent 切换过程 | --- ## 四种协作模式 ### 1. Supervisor 模式（主管模式） - **适用场景**: 需要统一入口、跨领域协作的任务 - **特点**: 中心化协调，有质量把控 ### 2. Router 模式（路由模式） - **适用场景**: 不同渠道/用户群体需要不同风格响应 - **特点**: 基于来源自动路由，无状态 ### 3. Pipeline 模式（流水线模式） - **适用场景**: 多步骤顺序处理 - **特点**: 输出即输入，链式传递 - **示例**: 研究 → 写作 → 审核 → 格式化 ### 4. Parallel 模式（并行模式） - **适用场景**: 任务可拆分为独立子任务 - **特点**: 同时执行，结果聚合 - **示例**: 多竞品分析、多角度代码审查 --- ## 目录结构 ``` swarmAgent/ ├── config/ │ ├── swarm.json # 主配置（平台无关） │ ├── swarm.schema.json # JSON Schema（VS Code 自动补全） │ └── skills.json # MCP Skills 注册表 ├── src/ │ ├── supervisor/ # 协调者 agent │ │ ├── SOUL.md # 角色定位 │ │ ├── AGENTS.md # 工作指南（含黑板/记忆/审批门） │ │ ├── USER.md # 服务对象画像 │ │ ├── HEARTBEAT.md # 心跳检查配置 │ │ ├── memory/ # 长期记忆 │ │ └── skills/ # agent 专属 skills │ ├── researcher/ # 调研专家 agent │ ├── writer/ # 写作专家 agent │ ├── coder/ # 工程专家 agent │ └── blogger/ # 博客发布 agent ├── sessions/ # 会话数据目录（运行时生成） │ ├── blackboard.template.json # 黑板初始化模板 │ └── {session_id}/ │ ├── blackboard.json # 共享工作区（成果存储） │ ├── meta.json │ ├── context.md # 外部注入上下文 │ ├── history.jsonl │ └── signals/ # 暂停/恢复/审批信号 ├── examples/ │ ├── pipeline-example.md # Pipeline 模式完整示例 │ ├── parallel-example.md # Parallel 模式完整示例 │ └── supervisor-example.md # Supervisor 模式完整示例 ├── docs/ │ ├── blackboard.md # 黑板机制（共享工作区） │ ├── memory.md # 三层记忆架构 │ ├── error-recovery.md # 错误恢复策略 │ ├── approval-gates.md # 审批门机制 │ ├── deployment.md # 部署指南 │ ├── sessions.md # 会话体系 │ ├── streaming.md # 流式对接 │ ├── skills.md # MCP Skills 指南 │ ├── communication-protocol.md │ ├── best-practices.md │ ├── quick-reference.md │ └── troubleshooting.md ├── variants/ # Agent 变体示例 │ ├── analyst.md │ ├── reviewer.md │ ├── translator.md │ └── agent-creation-guide.md # 新建 agent 完整指南 ├── changelog/ │ ├── CHANGELOG.md # 完整版本变更历史 │ ├── VERIFICATION.md # 验证计划 │ ├── VERIFICATION_REPORT.md # 验证报告 │ └── OPTIMIZATION_SUMMARY.md # 优化记录 ├── deploy.sh # 环境初始化脚本 ├── .env.example # 环境变量模板 ├── requirements.txt ├── LICENSE ├── CONTRIBUTING.md └── README.md ``` --- ## 快速开始 > 详细步骤见 [QUICKSTART.md](QUICKSTART.md) ### 步骤 1：配置环境变量 ```bash cp .env.example .env # 编辑 .env，填入模型 API Key 和其他配置 ``` `.env.example` 内容： ```bash # 模型提供商（openai / anthropic / azure / ollama 等） MODEL_PROVIDER=openai OPENAI_API_KEY=your_key_here # 各 agent 使用的模型 SUPERVISOR_MODEL=gpt-4o RESEARCHER_MODEL=gpt-4o-mini WRITER_MODEL=gpt-4o-mini CODER_MODEL=gpt-4o # Skills（可选） BRAVE_API_KEY=your_brave_key GITHUB_TOKEN=ghp_xxxx # 工作空间根目录 WORKSPACE_ROOT=/app/work TIMEZONE=Asia/Shanghai ``` ### 步骤 2：安装 MCP Skills 依赖 ```bash # 验证 Node.js v20+ node --version # 全局安装 npx（如未安装） npm install -g npx ``` MCP skills 通过 `npx -y` 自动安装，无需提前 `npm install`。 ### 步骤 3：启动 Gateway（选择适合你的框架） 本模板的 agent 配置（SOUL.md / AGENTS.md）与框架无关，你可以接入： | 框架 | 接入方式 | |------|---------| | 自建 Node.js 网关 | 读取 `config/swarm.json`，调用模型 API | | LangGraph | 将每个 agent 映射为 Graph 节点 | | CrewAI | 将每个 agent 映射为 CrewAI Agent | | Droid | 以 CLAUDE.md 形式加载 SOUL.md 内容 | ### 步骤 4：验证运行 ```bash curl -N -X POST http://localhost:3000/v1/agents/supervisor/chat \ -H "Content-Type: application/json" \ -H "Accept: text/event-stream" \ -d '{"session_id":"test-001","message":"你好","stream":true}' ``` --- ## 模型选择建议 | Agent 类型 | 推荐（OpenAI） | 推荐（国产） | 理由 | |-----------|--------------|------------|------| | Supervisor | gpt-4o | qwen-plus | 理解力强，善于协调 | | Researcher | gpt-4o-mini | glm-4-plus | 信息检索，成本敏感 | | Writer | gpt-4o-mini | qwen-plus | 文字生成，质量稳定 | | Coder | gpt-4o / o4-mini | qwen-coder-plus | 代码专项能力 | | Blogger | gpt-4o-mini | qwen-plus | 内容改写，成本敏感 | --- ## 文档索引 ### 核心机制 - [黑板机制 (blackboard.md)](docs/blackboard.md) — 共享工作区，成果跨 agent 复用 - [Memory 分层 (memory.md)](docs/memory.md) — 短期/工作/长期三层记忆架构 - [错误恢复 (error-recovery.md)](docs/error-recovery.md) — 重试、检查点、优雅降级 - [审批门 (approval-gates.md)](docs/approval-gates.md) — 高风险操作的人工确认机制 ### 接入与部署 - [会话体系 (sessions.md)](docs/sessions.md) — session_id 追踪与上下文干预 - [流式对接 (streaming.md)](docs/streaming.md) — SSE 协议接入指南 - [MCP Skills (skills.md)](docs/skills.md) — 加载开源 skill 的完整指南 - [通信协议 (communication-protocol.md)](docs/communication-protocol.md) — agent 间消息格式 ### 参考 - [最佳实践 (best-practices.md)](docs/best-practices.md) - [速查手册 (quick-reference.md)](docs/quick-reference.md) - [故障排查 (troubleshooting.md)](docs/troubleshooting.md) - [新建 Agent 指南 (agent-creation-guide.md)](variants/agent-creation-guide.md) ### 版本历史 - [变更日志 (CHANGELOG.md)](changelog/CHANGELOG.md) --- ## 最佳实践 1. **渐进式扩展**: 从单 agent 开始，遇到瓶颈再拆分 2. **明确边界**: 每个 agent 只负责一个领域 3. **结构化输出**: 每个 agent 交付标准 JSON Schema，减少下游理解偏差 4. **优先复用黑板**: 同一 session 内已有成果不重复生产 5. **最小权限**: 每个 agent 只开放完成任务所需的 skill 6. **会话隔离**: 不同用户/任务使用独立 session_id 7. **流式反馈**: 长任务要流式推送进度，避免用户等待 8. **审批高风险**: 不可逆操作必须人工确认后再执行 --- ## 常见问题 **Q: 这个模板依赖什么框架？** A: 不依赖特定框架。agent 的行为定义在 Markdown 文件中，可接入任何支持多 agent 协作的框架。 **Q: 如何使用国产模型？** A: 修改 `.env` 中的 `MODEL_PROVIDER` 和对应的 API Key，大多数国产模型（Qwen、GLM 等）兼容 OpenAI API 格式。 **Q: MCP skill 需要额外安装吗？** A: 不需要。配置中使用 `npx -y` 会在首次调用时自动安装。 **Q: 会话数据存在哪里？** A: 默认存在 `./sessions/` 目录，可通过 `config/swarm.json` 切换到 Redis 或 SQLite。 **Q: 如何新建一个 agent？** A: 参考 [variants/agent-creation-guide.md](variants/agent-creation-guide.md)，复制模板目录，填写 SOUL.md / AGENTS.md，然后在 `config/swarm.json` 中注册。 --- ## 贡献 欢迎 PR 和 Issue！详见 [CONTRIBUTING.md](CONTRIBUTING.md)。 --- ## License [MIT](LICENSE) © 2026 SwarmAgent Contributors --- *平台无关，开箱即用，随时可接入你的 AI 基础设施*