vibe-coding-cn/skills/auto-tmux/references/ai-swarm-collaboration.md

# AI 蜂群协作

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

本文从历史文档 `AI蜂群协作-tmux多Agent协作系统.md` 整理而来，并按当前仓库结构升级为
`auto-tmux` skill 的长期参考资料。当前推荐优先使用
`skills/auto-tmux/scripts/auto-tmux.sh`，直接 tmux 命令作为兜底。

## 1. 核心思想

传统 AI 编程助手的局限：

- 单一会话，无法感知其他任务。
- 遇到等待、确认、卡住时需要人工干预。
- 多任务并行时缺少协调。
- 多个 AI 容易重复工作、争抢文件或互相覆盖。

tmux 蜂群协作的核心是：让 AI 不再只是孤立会话，而是通过 tmux 获得感知、控制和协调能力。

| 能力 | 实现方式 | 效果 |
|:---|:---|:---|
| 感知 | `capture-pane` / `auto-tmux.sh capture` | 读取指定终端输出 |
| 控制 | `send-keys` / `auto-tmux.sh send` | 向指定终端发送按键或命令 |
| 巡检 | `auto-tmux.sh scan` | 批量检查多个 pane 状态 |
| 广播 | `auto-tmux.sh broadcast` | 受控批量下发同一指令 |
| 救援 | `auto-tmux.sh rescue` | 对等待确认、卡住或异常的 pane 做最小干预 |
| 记录 | `pipe-pane` / `auto-tmux.sh record` | 保留长任务审计日志 |
| 协调 | `swarm-state.sh` + 明确 target | 任务同步、分工、加锁、避免冲突 |
| 交接 | `swarm-brief.sh` | 导出只读状态报告，便于新会话或 reviewer 接手 |

```text
传统模式: 人 <-> AI1, 人 <-> AI2, 人 <-> AI3

蜂群模式: 人 -> commander -> worker1 / worker2 / worker3
                         \-> scan / capture / rescue / record
```

关键突破不是“让 AI 自动乱控终端”，而是把终端控制变成可观察、可定位、可审计、可回滚的工程动作。

## 2. 技术原理

tmux 的基本对象是：

```text
session
└── window
    └── pane
```

`auto-tmux` 要求所有控制都使用完整 target：

```text
<session>:<window>.<pane>
```

不要假设 pane 一定是 `.0`。不同 tmux 配置可能让 pane index 从 1 开始。正确做法是先查询拓扑：

```bash
skills/auto-tmux/scripts/auto-tmux.sh topology --session ai-hub
```

或用原生命令取真实 target：

```bash
target="$(tmux list-panes -t ai-hub:worker1 -F '#S:#I.#P' | head -n 1)"
```

## 3. 最小工作台

创建一个 commander + 3 个 worker 的工作台：

```bash
skills/auto-tmux/scripts/auto-tmux.sh hub --session ai-hub --workers 3 --cmd "codex"
```

查看拓扑：

```bash
skills/auto-tmux/scripts/auto-tmux.sh topology --session ai-hub
```

读取某个 worker：

```bash
target="$(tmux list-panes -t ai-hub:worker1 -F '#S:#I.#P' | head -n 1)"
skills/auto-tmux/scripts/auto-tmux.sh inspect -t "$target" -n 40
skills/auto-tmux/scripts/auto-tmux.sh capture -t "$target" -n 120
```

发送任务：

```bash
skills/auto-tmux/scripts/auto-tmux.sh send -t "$target" --text "请运行 make test 并汇报失败原因" --enter
```

等待完成信号：

```bash
skills/auto-tmux/scripts/auto-tmux.sh wait -t "$target" --pattern "done|完成|Tests passed" --timeout 300
```

## 4. 协作协议

### 4.1 角色

| 角色 | 职责 |
|:---|:---|
| commander | 分配任务、巡检状态、救援卡住任务、汇总结果 |
| worker | 处理单一明确任务，输出状态、证据、风险和结果 |
| gate | 测试、lint、CI、脚本、人工确认等外部门禁 |

### 4.2 状态目录

推荐使用 `scripts/swarm-state.sh` 初始化共享状态目录：

```bash
skills/auto-tmux/scripts/swarm-state.sh init --dir /tmp/ai_swarm
```

默认共享状态目录：

```text
/tmp/ai_swarm/
├── status.log
├── tasks.tsv
├── locks/
└── results/
```

最小状态格式：

```text
[HH:MM:SS] [target] [STATUS] description
```

常用状态：

```text
[START]  开始任务
[DONE]   完成任务
[BLOCKED] 阻塞，等待输入、依赖或权限
[FAIL]   任务失败，需要 commander 处理
[WAIT]   等待依赖或确认
[ERROR]  出现错误
[HELP]   请求帮助
[SKIP]   跳过，已有其他 worker 处理
```

### 4.3 协作规则

1. **先查后做**：开始前先 `topology` / `scan`，确认其他 worker 状态。
2. **目标明确**：发送命令必须指向明确 target，不使用模糊窗口号。
3. **单点职责**：一个 worker 一次只处理一个明确任务。
4. **避免冲突**：涉及同一文件、同一服务、同一配置时先加锁或等待。
5. **主动救援**：发现等待确认、卡死或明显错误时先 `capture`，再 `rescue --dry-run`。
6. **保留证据**：长任务开启 `record`，关键检查保存 scan 日志。
7. **交接可恢复**：阶段结束或上下文切换前生成 `swarm-brief.sh` 报告。
8. **人工兜底**：危险操作、敏感凭证、生产环境变更必须人工确认。

### 4.4 任务与锁

添加任务：

```bash
skills/auto-tmux/scripts/swarm-state.sh task-add --id task-001 --text "检查 README 链接"
```

worker 认领任务：

```bash
skills/auto-tmux/scripts/swarm-state.sh task-claim --id task-001 --owner "ai-hub:2.1"
skills/auto-tmux/scripts/swarm-state.sh task-next --owner "ai-hub:2.1"
```

修改文件前获取锁：

```bash
skills/auto-tmux/scripts/swarm-state.sh lock-acquire --name README.md --owner "ai-hub:2.1"
```

完成后释放锁并记录结果：

```bash
skills/auto-tmux/scripts/swarm-state.sh lock-release --name README.md --owner "ai-hub:2.1"
skills/auto-tmux/scripts/swarm-state.sh task-done --id task-001 --owner "ai-hub:2.1" --result "make test passed"
```

阻塞或失败时显式记录：

```bash
skills/auto-tmux/scripts/swarm-state.sh task-block --id task-001 --owner "ai-hub:2.1" --reason "等待用户确认"
skills/auto-tmux/scripts/swarm-state.sh task-fail --id task-001 --owner "ai-hub:2.1" --reason "make test failed"
```

生成交接报告：

```bash
skills/auto-tmux/scripts/swarm-brief.sh --session ai-hub --swarm-dir /tmp/ai_swarm --out /tmp/auto-tmux-brief
```

## 5. 架构模式

### 5.1 P2P 对等模式

```text
worker1 <-> worker2
   ^          ^
   |          |
worker3 <-> worker4
```

适合：简单探索、信息收集、互相巡检。

风险：缺少统一调度，容易重复劳动或互相干扰。

### 5.2 Master-Worker 主从模式

```text
commander
├── worker1
├── worker2
└── worker3
```

适合：复杂项目、明确分工、需要统一验收的任务。

当前仓库默认推荐这个模式，因为它更容易控制边界和回收证据。

### 5.3 Pipeline 流水线模式

```text
analysis -> design -> implementation -> test
```

适合：有明确阶段的工作，例如需求分析、方案设计、实现、测试。

风险：前一阶段输出质量差会向后传播，需要每阶段设置门禁。

### 5.4 Hybrid 混合模式

```text
commander
├── analysis group
├── implementation group
└── test group
```

适合：较大项目，多组并行。

风险：协调成本高，必须有状态记录、锁和强制验收标准。

## 6. 实战流程

### 6.1 多服务并行开发

示例分工：

```text
commander  任务分配、巡检、验收
worker1    data-service
worker2    trading-service
worker3    telegram-service
```

巡检：

```bash
skills/auto-tmux/scripts/auto-tmux.sh scan --session ai-hub -n 100 --save-dir /tmp/auto-tmux-scan
```

发现错误：

```bash
skills/auto-tmux/scripts/auto-tmux.sh scan --session ai-hub --pattern "ERROR|Traceback|failed"
```

### 6.2 代码审计 + 自动修复

推荐分工：

```text
worker1: 审计代码，输出问题列表
worker2: 根据问题列表修复
commander: 验收 diff、测试和风险
```

最小规则：

- 审计 worker 不直接修复。
- 修复 worker 不扩大范围。
- commander 只接受有测试、diff 和风险说明的结果。

### 6.3 自动值守

自动值守只能用于低风险场景，例如等待测试、安装确认、日志观察。

推荐先 dry-run：

```bash
target="$(tmux list-panes -t ai-hub:worker1 -F '#S:#I.#P' | head -n 1)"
skills/auto-tmux/scripts/auto-tmux.sh rescue -t "$target" --pattern "(y/n)" --reply y --dry-run
```

确认后再执行：

```bash
skills/auto-tmux/scripts/auto-tmux.sh rescue -t "$target" --pattern "(y/n)" --reply y
```

## 7. 提示词模板

### 7.1 Worker 模板

推荐直接渲染：

```bash
skills/auto-tmux/scripts/render-swarm-prompt.sh worker --target <target> --task "只处理指定子任务"
```

```markdown
你是 tmux AI 蜂群中的 worker。

你的职责：
1. 只处理分配给你的单一任务。
2. 开始前确认任务目标、边界和验收标准。
3. 执行中保留关键命令、错误和测试结果。
4. 完成后输出：状态、修改文件、验证结果、风险。
5. 不主动修改无关文件，不覆盖其他 worker 的成果。
```

### 7.2 Commander 模板

推荐直接渲染：

```bash
skills/auto-tmux/scripts/render-swarm-prompt.sh commander --session ai-hub --task "拆分并推进任务"
```

```markdown
你是 tmux AI 蜂群中的 commander。

你的职责：
1. 把总任务拆成互不冲突的 worker 子任务。
2. 用 topology / scan / capture 读取 worker 状态。
3. 对卡住任务先 dry-run 救援，再最小干预。
4. 汇总每个 worker 的产出、测试和风险。
5. 最终以测试、diff、日志和提交记录作为验收依据。
```

### 7.3 巡检汇报模板

```markdown
| target | 状态 | 当前任务 | 证据 | 下一步 |
|:---|:---|:---|:---|:---|
| ai-hub:1.1 | running | 执行测试 | 输出 make test | 等待完成 |
| ai-hub:2.1 | blocked | 等待确认 | 出现 (y/n) | rescue dry-run |
| ai-hub:3.1 | failed | 构建失败 | Traceback | 分配修复 |
```

## 8. 最佳实践

### 8.1 命名规范

```text
session:
  ai-hub      AI 协作工作台
  dev         开发任务
  monitor     监控任务

window:
  commander   指挥官
  worker1     工作节点 1
  worker2     工作节点 2
  worker3     工作节点 3
```

### 8.2 日志规范

```text
[time] [target] [START] description
[time] [target] [DONE] description
[time] [target] [WAIT] description
[time] [target] [ERROR] description
```

### 8.3 安全建议

1. 不自动确认危险操作。
2. 不在含敏感凭证的 pane 做批量 capture。
3. 不对未知 target 发送按键。
4. 广播或同步 pane 后必须立即关闭。
5. 长任务要记录日志，方便审计。
6. 任何生产环境操作必须人工确认。

## 9. 风险与限制

| 风险 | 描述 | 缓解措施 |
|:---|:---|:---|
| 误操作 | AI 向错误 pane 发送命令 | 使用完整 target，先 topology，再 capture |
| 死循环 | AI 互相触发或反复救援 | 使用 dry-run、冷却时间和人工确认 |
| 资源竞争 | 多 worker 同时修改同一文件 | 使用任务锁和明确分工 |
| 信息泄露 | capture 读到敏感信息 | 默认脱敏，隔离敏感会话 |
| 架构漂移 | 多 worker 各自为政 | commander 统一验收，门禁拦截 |

不适用场景：

- 需要图形界面的操作。
- 涉及密码输入、密钥展示或私密生产会话。
- 高风险数据库、云资源、生产环境变更。
- 无法容忍误输入或误中断的任务。

## 10. 扩展方向

- 跨机器协作：通过 SSH 包装远程 tmux，但必须先解决权限、审计和网络边界。
- Web 面板：把 topology、scan、record 状态暴露为只读监控页面。
- 智能调度：根据 worker 空闲程度、任务类型和失败状态分配任务。
- CI 集成：让 GitHub Actions 或本地 gate 接收 worker 结果，统一决定是否通过。
- 状态机治理：用 schema 或校验脚本约束 `/tmp/ai_swarm/tasks.tsv` 与 `results/`。

## 11. 快速参考

```bash
# 查看拓扑
skills/auto-tmux/scripts/auto-tmux.sh topology --session ai-hub

# 扫描状态
skills/auto-tmux/scripts/auto-tmux.sh scan --session ai-hub -n 80

# 捕获输出
skills/auto-tmux/scripts/auto-tmux.sh capture -t <target> -n 120

# 发送任务
skills/auto-tmux/scripts/auto-tmux.sh send -t <target> --text "任务内容" --enter

# 救援等待确认
skills/auto-tmux/scripts/auto-tmux.sh rescue -t <target> --pattern "(y/n)" --reply y --dry-run
skills/auto-tmux/scripts/auto-tmux.sh rescue -t <target> --pattern "(y/n)" --reply y

# 记录日志
skills/auto-tmux/scripts/auto-tmux.sh record start -t <target> --dir /tmp/auto-tmux-records
skills/auto-tmux/scripts/auto-tmux.sh record stop -t <target>
```