# AI 蜂群协作技术文档

> 基于 tmux 的多 AI Agent 协作系统设计与实现

---

## 目录

1. [核心思想](#1-核心思想)
2. [技术原理](#2-技术原理)
3. [命令参考](#3-命令参考)
4. [协作协议](#4-协作协议)
5. [架构模式](#5-架构模式)
6. [实战案例](#6-实战案例)
7. [提示词模板](#7-提示词模板)
8. [最佳实践](#8-最佳实践)
9. [风险与限制](#9-风险与限制)
10. [扩展方向](#10-扩展方向)

---

## 1. 核心思想

### 1.1 问题背景

传统 AI 编程助手的局限：
- 单一会话，无法感知其他任务
- 遇到等待/确认时需要人工干预
- 多任务并行时无法协调
- 重复工作，资源浪费

### 1.2 解决方案

利用 tmux 的终端复用能力，赋予 AI：

| 能力 | 实现方式 | 效果 |
|:---|:---|:---|
| **感知** | `capture-pane` | 读取任意终端内容 |
| **控制** | `send-keys` | 向任意终端发送按键 |
| **协调** | 共享状态文件 | 任务同步与分工 |

### 1.3 核心洞察

```
传统模式: 人 ←→ AI₁, 人 ←→ AI₂, 人 ←→ AI₃ (人是瓶颈)

蜂群模式: 人 → AI₁ ←→ AI₂ ←→ AI₃ (AI 自主协作)
```

**关键突破**：AI 不再是孤立的，而是可以互相感知、通讯、控制的集群。

---

## 2. 技术原理

### 2.1 tmux 架构

```
┌─────────────────────────────────────────────┐
│                 tmux server                  │
├─────────────────────────────────────────────┤
│  Session 0                                   │
│  ├── Window 0:1 [AI-1] ◄──┐                 │
│  ├── Window 0:2 [AI-2] ◄──┼── 互相可见/控制 │
│  ├── Window 0:3 [AI-3] ◄──┤                 │
│  └── Window 0:4 [AI-4] ◄──┘                 │
└─────────────────────────────────────────────┘
```

### 2.2 数据流

```
┌─────────┐  capture-pane   ┌─────────┐
│  AI-1   │ ◄───────────────│  AI-4   │
│ (执行)  │                 │ (监控)  │
└─────────┘  send-keys      └─────────┘
     ▲      ───────────────►     │
     │                           │
     └───────── 控制流 ──────────┘
```

### 2.3 通信机制

| 机制 | 方向 | 延迟 | 用途 |
|:---|:---|:---|:---|
| `capture-pane` | 读取 | 即时 | 获取终端输出 |
| `send-keys` | 写入 | 即时 | 发送命令/按键 |
| 共享文件 | 双向 | 文件IO | 状态持久化 |

---

## 3. 命令参考

### 3.1 信息获取

```bash
# 列出所有会话
tmux list-sessions

# 列出所有窗口
tmux list-windows -a

# 列出所有窗格
tmux list-panes -a

# 获取当前窗口标识
echo $TMUX_PANE
```

### 3.2 内容读取

```bash
# 读取指定窗口内容（最近 N 行）
tmux capture-pane -t <session>:<window> -p -S -<N>

# 示例：读取会话 0 窗口 1 最近 100 行
tmux capture-pane -t 0:1 -p -S -100

# 读取并保存到文件
tmux capture-pane -t 0:1 -p -S -500 > /tmp/window1.log

# 批量读取所有窗口
for w in $(tmux list-windows -a -F '#{session_name}:#{window_index}'); do
  echo "=== $w ==="
  tmux capture-pane -t "$w" -p -S -30
done
```

### 3.3 发送控制

```bash
# 发送文本 + 回车
tmux send-keys -t 0:1 "ls -la" Enter

# 发送确认
tmux send-keys -t 0:1 "y" Enter

# 发送特殊按键
tmux send-keys -t 0:1 C-c        # Ctrl+C
tmux send-keys -t 0:1 C-d        # Ctrl+D
tmux send-keys -t 0:1 C-z        # Ctrl+Z
tmux send-keys -t 0:1 Escape     # ESC
tmux send-keys -t 0:1 Up         # 上箭头
tmux send-keys -t 0:1 Down       # 下箭头
tmux send-keys -t 0:1 Tab        # Tab

# 组合操作
tmux send-keys -t 0:1 C-c        # 先中断
tmux send-keys -t 0:1 "cd /tmp" Enter  # 再执行新命令
```

### 3.4 窗口管理

```bash
# 创建新窗口
tmux new-window -n "ai-worker"

# 创建并执行命令
tmux new-window -n "ai-1" "kiro-cli chat"

# 关闭窗口
tmux kill-window -t 0:1

# 重命名窗口
tmux rename-window -t 0:1 "monitor"
```

---

## 4. 协作协议

### 4.1 状态定义

```bash
# 状态文件位置
/tmp/ai_swarm/
├── status.log      # 全局状态日志
├── tasks.json      # 任务队列
├── locks/          # 任务锁
│   ├── task_001.lock
│   └── task_002.lock
└── results/        # 结果存储
    ├── ai_1.json
    └── ai_2.json
```

### 4.2 状态格式

```bash
# 状态日志格式
[HH:MM:SS] [窗口ID] [状态] 描述

# 示例
[08:15:30] [0:1] [START] 开始处理 data-service 代码审计
[08:16:45] [0:1] [DONE] 完成代码审计，发现 5 个问题
[08:16:50] [0:2] [WAIT] 等待 0:1 审计结果
[08:17:00] [0:2] [START] 开始修复问题
```

### 4.3 协作规则

| 规则 | 描述 | 实现 |
|:---|:---|:---|
| **先查后做** | 开始前扫描其他终端 | `capture-pane` 全扫 |
| **避免冲突** | 相同任务只做一次 | 检查 locks 目录 |
| **主动救援** | 发现卡住主动帮助 | 检测 `[y/n]` 等待 |
| **状态广播** | 完成后通知其他 AI | 写入 status.log |

### 4.4 冲突处理

```
场景：AI-1 和 AI-2 同时要修改同一文件

解决方案：
1. 创建任务前先检查锁
2. 获取锁后才能执行
3. 完成后释放锁

# 获取锁
if [ ! -f /tmp/ai_swarm/locks/file_x.lock ]; then
  echo "$TMUX_PANE" > /tmp/ai_swarm/locks/file_x.lock
  # 执行任务
  rm /tmp/ai_swarm/locks/file_x.lock
fi
```

---

## 5. 架构模式

### 5.1 对等模式 (P2P)

```
┌─────┐     ┌─────┐
│ AI₁ │◄───►│ AI₂ │
└──┬──┘     └──┬──┘
   │           │
   ▼           ▼
┌─────┐     ┌─────┐
│ AI₃ │◄───►│ AI₄ │
└─────┘     └─────┘

特点：所有 AI 平等，互相监控
适用：简单任务，无明确依赖
```

### 5.2 主从模式 (Master-Worker)

```
        ┌──────────┐
        │ AI-Master│
        │  (指挥官) │
        └────┬─────┘
             │ 分发/监控
    ┌────────┼────────┐
    ▼        ▼        ▼
┌──────┐ ┌──────┐ ┌──────┐
│Worker│ │Worker│ │Worker│
│ AI-1 │ │ AI-2 │ │ AI-3 │
└──────┘ └──────┘ └──────┘

特点：一个指挥，多个执行
适用：复杂项目，需要统一协调
```

### 5.3 流水线模式 (Pipeline)

```
┌─────┐    ┌─────┐    ┌─────┐    ┌─────┐
│ AI₁ │───►│ AI₂ │───►│ AI₃ │───►│ AI₄ │
│分析 │    │设计 │    │实现 │    │测试 │
└─────┘    └─────┘    └─────┘    └─────┘

特点：任务串行流转
适用：有明确阶段的工作流
```

### 5.4 混合模式

```
           ┌──────────┐
           │ AI-Master│
           └────┬─────┘
                │
    ┌───────────┼───────────┐
    ▼           ▼           ▼
┌──────┐   ┌──────┐    ┌──────┐
│分析组 │   │开发组 │    │测试组 │
├──────┤   ├──────┤    ├──────┤
│AI-1  │   │AI-3  │    │AI-5  │
│AI-2  │   │AI-4  │    │AI-6  │
└──────┘   └──────┘    └──────┘

特点：分组协作 + 统一调度
适用：大型项目，多团队并行
```

---

## 6. 实战案例

### 6.1 案例：多服务并行开发

**场景**：同时开发 data-service、trading-service、telegram-service

**配置**：
```bash
# 窗口分配
0:1 - AI-Master (指挥官)
0:2 - AI-Data (data-service)
0:3 - AI-Trading (trading-service)
0:4 - AI-Telegram (telegram-service)
```

**指挥官提示词**：
```
你是项目指挥官，负责协调 3 个开发 AI。

每 2 分钟执行一次扫描：
for w in 2 3 4; do
  echo "=== 窗口 0:$w ===" 
  tmux capture-pane -t "0:$w" -p -S -20
done

发现问题时：
- 卡住等待 → send-keys 确认
- 报错 → 分析并给出建议
- 完成 → 记录并分配下一任务
```

### 6.2 案例：代码审计 + 自动修复

**场景**：AI-1 审计代码，AI-2 实时修复

**流程**：
```
AI-1 (审计):
1. 扫描代码，输出问题列表
2. 每发现一个问题，写入 /tmp/ai_swarm/issues.log

AI-2 (修复):
1. 监控 issues.log
2. 读取新问题
3. 自动修复
4. 标记完成
```

### 6.3 案例：7x24 值守

**场景**：AI 互相监控，自动救援

**配置**：
```bash
# 每个 AI 的监控逻辑
while true; do
  for w in $(tmux list-windows -a -F '#{window_index}'); do
    output=$(tmux capture-pane -t "0:$w" -p -S -5)
    
    # 检测卡住
    if echo "$output" | grep -q "\[y/n\]"; then
      tmux send-keys -t "0:$w" "y" Enter
      echo "已帮助窗口 $w 确认"
    fi
    
    # 检测错误
    if echo "$output" | grep -qi "error\|failed"; then
      echo "窗口 $w 出现错误，需要关注"
    fi
  done
  sleep 30
done
```

---

## 7. 提示词模板

### 7.1 基础版（Worker）

```markdown
## AI 蜂群协作模式

你在 tmux 环境中工作，可以感知和协助其他终端。

### 命令
# 扫描所有终端
tmux list-windows -a

# 读取终端内容
tmux capture-pane -t <session>:<window> -p -S -100

### 行为
- 开始任务前先扫描环境
- 发现相关任务主动协调
- 完成后广播状态
```

### 7.2 完整版（Worker）

```markdown
## 🐝 AI 蜂群协作协议 v2.0

你是 tmux 多终端 AI 集群中的一员。

### 感知能力

# 列出所有窗口
tmux list-windows -a

# 读取指定窗口（最近 100 行）
tmux capture-pane -t <session>:<window> -p -S -100

# 批量扫描
for w in $(tmux list-windows -a -F '#{session_name}:#{window_index}'); do
  echo "=== $w ===" && tmux capture-pane -t "$w" -p -S -20
done

### 控制能力

# 发送命令
tmux send-keys -t <窗口> "<命令>" Enter

# 发送确认
tmux send-keys -t <窗口> "y" Enter

# 中断任务
tmux send-keys -t <窗口> C-c

### 协作规则

1. **主动感知**：任务开始前扫描其他终端
2. **避免冲突**：相同任务不重复执行
3. **主动救援**：发现等待/卡住主动帮助
4. **状态广播**：完成后写入共享日志

### 状态同步

# 广播
echo "[$(date +%H:%M:%S)] [$TMUX_PANE] [DONE] <描述>" >> /tmp/ai_swarm/status.log

# 读取
tail -20 /tmp/ai_swarm/status.log

### 检查时机

- 🚦 任务开始前
- ⏳ 等待依赖时
- ✅ 任务完成后
- ❌ 遇到错误时
```

### 7.3 指挥官版（Master）

```markdown
## 🎖️ AI 集群指挥官协议

你是 AI 蜂群的指挥官，负责监控和协调所有 Worker AI。

### 核心职责

1. **全局监控**：定期扫描所有终端状态
2. **任务分配**：根据能力分配任务
3. **冲突解决**：发现重复工作时协调
4. **故障救援**：发现卡住/错误时介入
5. **进度汇总**：汇总各终端成果

### 监控命令

# 全局扫描（每 2 分钟执行）
echo "========== $(date) 状态扫描 =========="
for w in $(tmux list-windows -a -F '#{session_name}:#{window_index}'); do
  echo "--- $w ---"
  tmux capture-pane -t "$w" -p -S -15
done

### 干预命令

# 帮助确认
tmux send-keys -t <窗口> "y" Enter

# 中断错误任务
tmux send-keys -t <窗口> C-c

# 发送新指令
tmux send-keys -t <窗口> "<指令>" Enter

### 状态判断

检测到以下模式时介入：
- `[y/n]` `[Y/n]` `确认` → 需要确认
- `Error` `Failed` `Exception` → 出现错误
- `Waiting` `Blocked` → 任务阻塞
- 长时间无输出 → 可能卡死

### 汇报格式

每次扫描后输出：
| 窗口 | 状态 | 当前任务 | 备注 |
|:---|:---|:---|:---|
| 0:1 | ✅ 正常 | 代码审计 | 进度 80% |
| 0:2 | ⏳ 等待 | 等待确认 | 已自动确认 |
| 0:3 | ❌ 错误 | 编译失败 | 需要关注 |
```

---

## 8. 最佳实践

### 8.1 初始化流程

```bash
# 1. 创建共享目录
mkdir -p /tmp/ai_swarm/{locks,results}
touch /tmp/ai_swarm/status.log

# 2. 开启 tmux 会话
tmux new-session -d -s ai

# 3. 创建多个窗口
tmux new-window -t ai -n "master"
tmux new-window -t ai -n "worker-1"
tmux new-window -t ai -n "worker-2"
tmux new-window -t ai -n "worker-3"

# 4. 在每个窗口启动 AI
tmux send-keys -t ai:master "kiro-cli chat" Enter
tmux send-keys -t ai:worker-1 "kiro-cli chat" Enter
# ...

# 5. 发送蜂群提示词
```

### 8.2 命名规范

```bash
# 会话命名
ai          # AI 工作会话
dev         # 开发会话
monitor     # 监控会话

# 窗口命名
master      # 指挥官
worker-N    # 工作节点
data        # data-service 专用
trading     # trading-service 专用
```

### 8.3 日志规范

```bash
# 状态日志
[时间] [窗口] [状态] 描述

# 状态类型
[START]  - 开始任务
[DONE]   - 完成任务
[WAIT]   - 等待中
[ERROR]  - 出现错误
[HELP]   - 请求帮助
[SKIP]   - 跳过（已有人处理）
```

### 8.4 安全建议

1. **不要自动确认危险操作**：rm -rf、DROP TABLE 等
2. **设置操作白名单**：只允许特定命令
3. **保留操作日志**：记录所有 send-keys 操作
4. **定期人工检查**：不要完全无人值守

---

## 9. 风险与限制

### 9.1 已知风险

| 风险 | 描述 | 缓解措施 |
|:---|:---|:---|
| 误操作 | AI 发送错误命令 | 设置命令白名单 |
| 死循环 | AI 互相触发 | 添加冷却时间 |
| 资源竞争 | 同时修改同一文件 | 使用锁机制 |
| 信息泄露 | 敏感信息被读取 | 隔离敏感会话 |

### 9.2 技术限制

- tmux 必须在同一服务器
- 无法跨机器协作（需要 SSH）
- 终端输出有长度限制
- 无法读取密码输入（隐藏字符）

### 9.3 不适用场景

- 需要图形界面的操作
- 涉及敏感凭证的操作
- 需要实时交互的场景
- 跨网络的分布式协作

---

## 10. 扩展方向

### 10.1 跨机器协作

```bash
# 通过 SSH 读取远程 tmux
ssh user@remote "tmux capture-pane -t 0:1 -p"

# 通过 SSH 发送命令
ssh user@remote "tmux send-keys -t 0:1 'ls' Enter"
```

### 10.2 Web 监控面板

```python
# 简单的状态 API
from flask import Flask, jsonify
import subprocess

app = Flask(__name__)

@app.route('/status')
def status():
    result = subprocess.run(
        ['tmux', 'list-windows', '-a', '-F', '#{window_name}:#{window_activity}'],
        capture_output=True, text=True
    )
    return jsonify({'windows': result.stdout.split('\n')})
```

### 10.3 智能调度

```python
# 基于负载的任务分配
def assign_task(task):
    windows = get_all_windows()
    
    # 找到最空闲的窗口
    idle_window = min(windows, key=lambda w: w.activity_time)
    
    # 分配任务
    send_keys(idle_window, f"处理任务: {task}")
```

### 10.4 与其他系统集成

- **Slack/Discord**：状态通知
- **Prometheus**：指标监控
- **Grafana**：可视化面板
- **GitHub Actions**：CI/CD 触发

---

## 附录

### A. 快速参考卡片

```
┌─────────────────────────────────────────────────────┐
│              AI 蜂群命令速查                         │
├─────────────────────────────────────────────────────┤
│ 列出窗口    tmux list-windows -a                    │
│ 读取内容    tmux capture-pane -t 0:1 -p -S -100     │
│ 发送命令    tmux send-keys -t 0:1 "cmd" Enter       │
│ 发送确认    tmux send-keys -t 0:1 "y" Enter         │
│ 中断任务    tmux send-keys -t 0:1 C-c               │
│ 新建窗口    tmux new-window -n "name"               │
└─────────────────────────────────────────────────────┘
```

### B. 故障排查

```bash
# tmux 不存在
which tmux || sudo apt install tmux

# 无法连接会话
tmux list-sessions  # 检查会话是否存在

# capture-pane 无输出
tmux capture-pane -t 0:1 -p -S -1000  # 增加行数

# send-keys 无效
tmux display-message -t 0:1 -p '#{pane_mode}'  # 检查模式
```

### C. 参考资料

- tmux 官方文档: https://github.com/tmux/tmux/wiki
- tmux 命令速查: `man tmux`

---

*文档版本: v1.0*
*最后更新: 2026-01-04*