# Swarm - 多 Agent 协作系统设计文档

> 版本：1.0
> 日期：2026-03-04
> 作者：Swarm Team

---

## 目录

1. [项目概述](#1-项目概述)
2. [系统架构](#2-系统架构)
3. [插件化 CLI 工具适配](#3-插件化-cli-工具适配)
4. [资源管理与文件锁](#4-资源管理与文件锁)
5. [会议与共识机制](#5-会议与共识机制)
6. [动态角色分配](#6-动态角色分配)
7. [多模型支持](#7-多模型支持)
8. [共享存储结构](#8-共享存储结构)
9. [技术栈](#9-技术栈)

---

## 1. 项目概述

### 1.1 核心目标

构建一个通用的多 Agent 协作框架，支持：

- **多工具接入**：Claude Code CLI、Kimi CLI、OpenCode 等命令行 AI 工具
- **会议驱动协作**：通过会议流程组织 Agent 间的协作
- **资源自动管理**：声明式资源管理，Agent 无需手动处理锁
- **协作共识**：Agent 之间通过讨论达成共识，而非简单投票
- **动态角色**：AI 根据任务自动分析并分配角色
- **多模型支持**：支持多种 LLM，智能路由与故障转移

### 1.2 设计原则

| 原则 | 说明 |
|-----|------|
| 插件化 | CLI 工具通过适配器层接入，实现统一接口 |
| 声明式 | Agent 只声明意图，系统自动管理资源 |
| 会议驱动 | Workflow 定义会议节点，栅栏同步触发 |
| 协作共识 | 多轮讨论、迭代提案、AI 收敛判断 |
| AI 分配 | LLM 分析任务自动分配最优角色 |
| 可靠性 | 超时 + 心跳 + finally + 看门狗多层保障 |

---

## 2. 系统架构

### 2.1 整体架构图

```
┌─────────────────────────────────────────────────────────────────────────────┐
│                              用户界面层                                        │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐     │
│  │    Web UI    │  │   CLI 工具   │  │  API 接口    │  │  VSCode 插件 │     │
│  │  (React/TS)  │  │   (Node.js)  │  │   (Express)  │  │   (TypeScript)│     │
│  └──────────────┘  └──────────────┘  └──────────────┘  └──────────────┘     │
└─────────────────────────────────────────────────────────────────────────────┘
                                          ↕
┌─────────────────────────────────────────────────────────────────────────────┐
│                              协调层 (Python)                                  │
│  ┌──────────────────┐  ┌──────────────────┐  ┌──────────────────┐          │
│  │  Workflow Engine │  │ Meeting Scheduler│  │ Resource Manager │          │
│  │  (工作流编排)     │  │  (栅栏同步)       │  │  (文件锁+心跳)   │          │
│  └──────────────────┘  └──────────────────┘  └──────────────────┘          │
│  ┌──────────────────┐  ┌──────────────────┐  ┌──────────────────┐          │
│  │ Role Allocator   │  │ Consensus Engine │  │  Model Router    │          │
│  │  (AI角色分配)    │  │  (协作共识)      │  │  (多模型路由)    │          │
│  └──────────────────┘  └──────────────────┘  └──────────────────┘          │
└─────────────────────────────────────────────────────────────────────────────┘
                                          ↕
┌─────────────────────────────────────────────────────────────────────────────┐
│                          Agent 适配层                                        │
│  ┌─────────────────────────────────────────────────────────────────────┐    │
│  │                    CLIPluginAdapter Interface                       │    │
│  │  + execute()  + join_meeting()  + write_state()  + read_others()  │    │
│  └─────────────────────────────────────────────────────────────────────┘    │
│                                          ↓                                   │
│  ┌────────────┐ ┌────────────┐ ┌────────────┐ ┌────────────┐              │
│  │ ClaudeCode │ │  KimiCLI   │ │  OpenCode  │ │  自定义... │              │
│  │  Adapter   │ │  Adapter   │ │  Adapter   │ │  Adapter   │              │
│  └────────────┘ └────────────┘ └────────────┘ └────────────┘              │
└─────────────────────────────────────────────────────────────────────────────┘
                                          ↕
┌─────────────────────────────────────────────────────────────────────────────┐
│                          模型层                                             │
│  ┌────────────┐ ┌────────────┐ ┌────────────┐ ┌────────────┐              │
│  │  Anthropic │ │   OpenAI   │ │   Google   │ │  DeepSeek  │              │
│  │    API     │ │    API     │ │    API     │ │    API     │              │
│  └────────────┘ └────────────┘ └────────────┘ └────────────┘              │
│  ┌────────────────────────────────────────────────────────────┐            │
│  │                    Ollama (本地模型)                      │            │
│  └────────────────────────────────────────────────────────────┘            │
└─────────────────────────────────────────────────────────────────────────────┘
                                          ↕
┌─────────────────────────────────────────────────────────────────────────────┐
│                      共享存储层 (.doc/)                                       │
│  ├── agents/          ├── dialogues/       ├── progress/                     │
│  ├── resources/       ├── meetings/        ├── cache/                        │
│  └── workflow/                                                              │
└─────────────────────────────────────────────────────────────────────────────┘
```

---

## 3. 插件化 CLI 工具适配

### 3.1 统一接口设计

```python
interface CLIPluginAdapter:
    """CLI 工具适配器统一接口"""

    id: str
    name: str
    version: str

    # 核心能力
    def execute(task: Task) -> Result:
        """执行任务"""
        pass

    def join_meeting(meeting_id: str) -> None:
        """加入会议等待队列"""
        pass

    def write_state(state: dict) -> None:
        """写入自己的状态文件"""
        pass

    def read_others(agent_id: str) -> dict:
        """读取其他 Agent 的状态"""
        pass

    def update_heartbeat() -> None:
        """更新心跳"""
        pass
```

### 3.2 预置适配器

| 适配器 | CLI 工具 | 特点 |
|--------|---------|------|
| ClaudeCodeAdapter | Claude Code CLI | MCP 支持，代码审查强 |
| KimiCLIAdapter | Kimi CLI | ACP 协议，Zsh 集成 |
| OpenCodeAdapter | OpenCode | 快速代码生成 |
| CustomAdapter | 自定义 | 扩展接口 |

### 3.3 适配器实现示例

```python
class ClaudeCodeAdapter(CLIPluginAdapter):
    def __init__(self, config: dict):
        self.id = "claude-code-001"
        self.name = "Claude Code"
        self.config = config
        self.executor = TaskExecutor(self.id, resource_manager)

    def execute(self, task: Task) -> Result:
        # 通过 TaskExecutor 自动管理资源
        return self.executor.execute(task.description)

    def join_meeting(self, meeting_id: str):
        return meeting_scheduler.wait_for_meeting(self.id, meeting_id)
```

---

## 4. 资源管理与文件锁

### 4.1 核心设计

**声明式资源管理**：Agent 只需要声明"我要修改这个文件"，系统自动获取锁、执行任务、释放锁。

### 4.2 TaskExecutor 包装层

```python
class TaskExecutor:
    """任务执行器 - 自动管理资源生命周期"""

    def execute(self, task_description: str) -> str:
        # 1. 解析意图，识别需要的文件
        required_files = self._parse_required_files(task_description)

        # 2. 获取所有需要的锁
        self._acquire_all_locks(required_files, task_description)

        try:
            # 3. 执行实际任务
            result = self._do_execute(task_description)
            return result
        finally:
            # 4. 无论发生什么，都释放锁
            self._release_all_locks()
```

### 4.3 可靠性保障机制

| 机制 | 解决问题 | 触发方式 |
|-----|---------|---------|
| 超时释放 | 锁忘记释放 | 定时器扫描 |
| 心跳机制 | Agent 挂了检测 | 定时器 + 心跳超时 |
| Lease 上下文管理器 | 代码异常退出 | Python `with` / `finally` |
| 生命周期 Hooks | 进程崩溃清理 | `atexit` + 看门狗 |
| 看门狗进程 | 整个系统挂了 | 独立进程监控 |
| 原子操作 | 并发冲突 | 文件锁 |

### 4.4 Agent 使用方式

```python
# Agent 代码 - 完全不需要关心锁

class ClaudeCodeAgent:
    def fix_login_bug(self):
        # 只需要描述任务，锁完全透明
        result = self.executor.execute(
            "修改 src/main.py 修复登录 bug"
        )
        return result
```

---

## 5. 会议与共识机制

### 5.1 栅栏同步

```python
class MeetingScheduler:
    """会议调度器 - 实现栅栏同步"""

    def wait_for_meeting(self, agent_id: str, meeting_id: str):
        """
        Agent 调用此方法表示"我准备好了，等会议"
        最后一个到达的 Agent 触发会议
        """
        queue = self._load_queue()

        # 加入等待队列
        queue[meeting_id]["waiting_agents"].append(agent_id)

        # 检查是否所有人都准备好了
        if self._is_everyone_ready(meeting_id):
            self._start_meeting(meeting_id)
            return "meeting_started"
        return "waiting"
```

### 5.2 协作式共识流程

```
┌─────────────────────────────────────────────────────────────┐
│                    协作共识流程                              │
│                                                             │
│  第一阶段：收集初步想法                                      │
│    Agent A: "建议用 JWT，因为..."                           │
│    Agent B: "我建议用 Session，因为..."                     │
│    Agent C: "两者结合可能更好..."                           │
│                                                             │
│  第二阶段：讨论与迭代（最多5轮）                             │
│    → Agent 互相质疑、补充、融合                              │
│    → 根据讨论更新提案                                       │
│    → 检查收敛性                                             │
│                                                             │
│  第三阶段：生成共识版本                                      │
│    → 合并相似提案                                           │
│    → 记录讨论过程                                           │
│    → 生成会议文件                                           │
└─────────────────────────────────────────────────────────────┘
```

### 5.3 会议文件结构

```markdown
---
meeting_id: requirement_review_20260304_103000
date: 2026-03-04
attendees: [claude-code-001, kimi-cli-002, opencode-003]
consensus_type: collaborative
iterations: 3
---

# 需求评审会议

## 参会者
- `claude-code-001` (权重: 1.5)
- `kimi-cli-002` (权重: 1.0)
- `opencode-003` (权重: 1.2)

## 讨论过程

### 第一轮：初步想法
[各 Agent 的初步提案...]

### 第二轮：讨论
[互相质疑、补充的过程...]

### 第三轮：迭代
[根据讨论更新的提案...]

## 最终共识
[达成的共识内容...]

## 贡献记录
| Agent | 主要贡献 |
|-------|---------|
| claude-code-001 | ... |
| kimi-cli-002 | ... |
| opencode-003 | ... |

## 后续行动
1. [ ] ...
2. [ ] ...
```

---

## 6. 动态角色分配

### 6.1 AI 驱动的角色分配

```python
class AIRoleAllocator:
    """AI 驱动的角色分配器"""

    def allocate_roles(self, task: Task, available_agents: List[str]) -> dict:
        """
        分析任务，自动分配角色给各 Agent
        """
        # 获取所有 Agent 的能力描述
        agent_capabilities = self._get_agent_capabilities(available_agents)

        # 构造提示词，让 AI 分析
        prompt = f"""
        你是一个团队协调 AI，需要为以下任务分配角色。

        ## 任务描述
        {task.description}

        ## 可用的 Agent 及其能力
        {self._format_capabilities(agent_capabilities)}

        请分析任务需求，为每个 Agent 分配最合适的角色。
        """

        # 调用 LLM 分析
        response = self.llm_client.complete(prompt)
        allocation = json.loads(response)

        # 应用角色分配
        for assignment in allocation["role_assignments"]:
            self._apply_role(
                assignment["agent_id"],
                assignment["role"],
                assignment["reason"]
            )

        return allocation
```

### 6.2 可用角色

| 角色 | 名称 | 能力 | 权重 |
|-----|------|------|------|
| pm | 产品经理 | 需求分析、优先级排序、用户故事 | 1.5 |
| architect | 架构师 | 系统设计、技术选型、性能规划 | 1.5 |
| developer | 开发者 | 编码、单元测试、代码审查 | 1.0 |
| qa | 测试工程师 | 测试用例、自动化测试、bug报告 | 1.2 |
| reviewer | 代码审查者 | 代码审查、安全检查、性能分析 | 1.3 |

---

## 7. 多模型支持

### 7.1 智能路由策略

```python
class MultiModelRouter:
    """多模型路由器"""

    def route(self, task: Task, context: dict) -> str:
        """
        智能路由：根据任务类型选择最合适的模型
        """
        task_type = self._classify_task(task)

        routing_rules = {
            "complex_reasoning": ("anthropic", "claude-opus-4.6"),
            "code_generation": ("anthropic", "claude-sonnet-4.6"),
            "simple_task": ("anthropic", "claude-haiku-4.6"),
            "cost_sensitive": ("deepseek", "deepseek-chat"),
            "local_privacy": ("ollama", "llama3"),
            "multimodal": ("google", "gemini-2.5-flash")
        }

        provider, model = routing_rules.get(task_type, default)
        return self.providers[provider].complete(model, task, context)
```

### 7.2 故障转移

```python
def route_with_failover(self, task: Task, context: dict) -> str:
    """带故障转移的路由"""
    primary_route = self._get_primary_route(task)
    fallback_routes = self._get_fallback_routes()

    # 尝试主路由
    try:
        return self._execute_route(primary_route, task, context)
    except Exception:
        pass

    # 尝试备选路由
    for route in fallback_routes:
        try:
            return self._execute_route(route, task, context)
        except Exception:
            pass

    # 全部失败，使用最简单的本地模型
    return self._execute_local_fallback(task, context)
```

---

## 8. 共享存储结构

```
.doc/
├── agents/                          # Agent 注册与状态
│   ├── registry.json                # 所有已注册 Agent 列表
│   ├── claude-code-001/             # 每个 Agent 的独立目录
│   │   ├── config.json              # Agent 配置
│   │   ├── state.json               # 当前状态
│   │   ├── history.json             # 历史记录
│   │   └── capabilities.json        # 能力声明
│   └── ...
│
├── dialogues/                       # Agent 间对话记录
│   └── [agent_a]_[agent_b]_[timestamp].json
│
├── progress/                        # 工程进度
│   ├── project_state.json           # 项目整体状态
│   ├── milestones.json              # 里程碑
│   └── tasks.json                   # 任务列表
│
├── resources/                       # 资源分配
│   ├── resource_pool.json           # 资源池状态
│   ├── file_locks.json              # 文件锁
│   └── allocation_log.json          # 分配日志
│
├── meetings/                        # 会议记录与共识
│   ├── [YYYY-MM-DD]/
│   │   └── [HHMMSS]_[meeting_name].md
│   └── meeting_template.md
│
├── cache/                           # 实时缓存
│   ├── meeting_queue.json           # 会议等待队列
│   ├── message_bus.json             # 消息总线快照
│   ├── lock_state.json              # 锁状态缓存
│   └── heartbeats.json              # Agent 心跳
│
├── workflow/                        # 工作流定义
│   ├── project_workflow.yaml        # 项目工作流
│   ├── meeting_definitions.yaml     # 会议定义
│   └── consensus_rules.yaml         # 共识规则
│
└── shared/                          # 共享资源
    ├── knowledge_base/              # 知识库
    ├── templates/                   # 模板文件
    └── conventions/                 # 编码规范
```

---

## 9. 技术栈

### 9.1 后端 (Python)

| 组件 | 技术选择 |
|-----|---------|
| 核心框架 | Python 3.12+ |
| 异步运行时 | asyncio |
| LLM 调用 | anthropic, openai, langchain |
| 文件操作 | pathlib, aiofiles |
| 进程管理 | subprocess, multiprocessing |
| 定时任务 | APScheduler |

### 9.2 前端 (TypeScript)

| 组件 | 技术选择 |
|-----|---------|
| 框架 | React 18 + TypeScript |
| UI 库 | shadcn/ui + Tailwind CSS |
| 状态管理 | Zustand |
| 实时通信 | WebSocket |
| HTTP 客户端 | fetch / axios |

### 9.3 API 层 (Node.js)

| 组件 | 技术选择 |
|-----|---------|
| 框架 | Express / Fastify |
| 类型检查 | TypeScript |
| 实时通信 | Socket.IO |
| 进程通信 | child_process |

---

## 附录

### A. 参考项目

详见 [reference-projects.md](reference-projects.md)

### B. 更新日志

| 版本 | 日期 | 变更 |
|-----|------|------|
| 1.0 | 2026-03-04 | 初始版本 |
| 1.1 | 2026-03-04 | 添加人类参与系统设计 |

### C. 人类参与系统

#### C.1 设计概述

人类参与者通过 `humans.json` 文件参与协作，无需 API 或 UI 调用。

**核心特点**：
- 单一共享文件 `humans.json`
- 事件驱动通知机制
- 按优先级区分处理
- 自动合并到会议讨论

#### C.2 文件结构

```
.doc/
├── agents/                    # Agent 目录
├── humans.json                # 人类输入共享文件
├── meetings/                   # 会议文件
├── events/                     # 事件通知
└── task_queue.json            # 任务队列
```

#### C.3 humans.json 结构

```json
{
  "version": "1.0",
  "last_updated": "2026-03-04T14:30:00Z",

  "participants": {
    "user001": {
      "name": "张三",
      "role": "tech_lead",
      "status": "online",
      "avatar": "👤"
    }
  },

  // 任务需求
  "task_requests": [
    {
      "id": "req_001",
      "from": "user001",
      "timestamp": "2026-03-04T14:28:00Z",
      "priority": "high",           // high | medium | low
      "type": "correction",
      "title": "登录验证方式调整",
      "content": "建议改用 Session + Redis",
      "target_files": ["src/auth/login.py"],
      "suggested_agent": "claude-code-001",
      "urgent": true,
      "status": "pending"
    }
  ],

  // 会议发言
  "meeting_comments": [
    {
      "id": "comment_001",
      "from": "user001",
      "meeting_id": "design_review",
      "timestamp": "2026-03-04T14:25:00Z",
      "type": "proposal",
      "priority": "normal",
      "content": "建议使用 SQLite，保持简单",
      "status": "pending"
    }
  ],

  // 人类状态
  "human_states": {
    "user001": {
      "status": "online",
      "current_focus": "reviewing",
      "preferred_contact": "async"
    }
  }
}
```

#### C.4 事件驱动流程

```
人类写入 humans.json
        ↓
   文件监听器触发
        ↓
写入 events/notification_stream.json
        ↓
    ┌───────┴────────┐
    │                │
    ↓                ↓
会议通知        任务通知
    │                │
    ↓                ↓
Agent 收到     Agent 收到
会议通知      任务通知
    │                │
    ↓                ↓
 读取会议      读取任务
  评论部分    requests
    │                │
    ↓                ↓
 参与讨论      按优先级
              处理任务
```

#### C.5 任务优先级处理

| 优先级 | 处理方式 | 示例 |
|-------|---------|------|
| **high** + urgent | 立即中断当前任务 | 安全漏洞修复、生产故障 |
| **high** | 尽快处理，完成当前任务后 | 功能调整、架构变更 |
| **medium** | 加入队列，按序处理 | 功能增强、文档补充 |
| **low** | 空闲时处理 | 优化建议、非紧急任务 |

#### C.6 会议中的人类发言显示

```markdown
## 讨论记录

### Agent 提案
**claude-code-001 (14:20)**:
> 建议使用 JWT + Refresh Token...

### 人类发言（高优先级）
**user001 [HUMAN] ⚠️ (14:22)**:
> 我反对使用 JWT。我们的数据量不大，SQLite + Session 就够了。
>
> **优先级：HIGH**

### Agent 响应
**kimi-cli-002 (14:23)**:
> 收到用户反馈，重新评估方案...
```

#### C.7 前端输入实现

前端提供任务输入栏，输入后：

1. 写入 `humans.json` 的 `task_requests`
2. 记录发送时间戳
3. 触发文件监听事件
4. Agent 读取并处理

```javascript
// 提交任务
function submitTask(content, priority = "medium") {
  const request = {
    id: `req_${Date.now()}`,
    from: "user001",
    timestamp: new Date().toISOString(),
    priority: priority,
    type: "user_task",
    content: content,
    status: "pending"
  };

  // 写入 humans.json
  humans.task_requests.push(request);
  // 保存文件...
}
```

---

*文档结束*