From 3be6ecacbb24fded7b0a6cb1fc5957f4c8a251f2 Mon Sep 17 00:00:00 2001 From: tukuaiai Date: Sun, 4 Jan 2026 08:51:01 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20add=20AI=E8=9C=82=E7=BE=A4=E5=8D=8F?= =?UTF-8?q?=E4=BD=9C=E6=8A=80=E6=9C=AF=E6=96=87=E6=A1=A3=20to=20=E6=96=B9?= =?UTF-8?q?=E6=B3=95=E8=AE=BA?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 21 + .../AI蜂群协作-tmux多Agent协作系统.md | 693 ++++++++++++++++++ i18n/zh/documents/02-方法论/README.md | 5 + 3 files changed, 719 insertions(+) create mode 100644 i18n/zh/documents/02-方法论/AI蜂群协作-tmux多Agent协作系统.md diff --git a/README.md b/README.md index 89d83f0..a11d404 100644 --- a/README.md +++ b/README.md @@ -160,6 +160,27 @@ Canvas方式：**代码 ⇄ 白板 ⇄ AI ⇄ 人类**，白板成为单一真 +
+🐝 AI蜂群协作 + +> **基于 tmux 的多 AI Agent 协作系统** + +传统模式：人 ←→ AI₁, 人 ←→ AI₂, 人 ←→ AI₃ (人是瓶颈) + +蜂群模式：**人 → AI₁ ←→ AI₂ ←→ AI₃** (AI 自主协作) + +| 能力 | 实现方式 | 效果 | +|:---|:---|:---| +| 🔍 感知 | `capture-pane` | 读取任意终端内容 | +| 🎮 控制 | `send-keys` | 向任意终端发送按键 | +| 🤝 协调 | 共享状态文件 | 任务同步与分工 | + +**核心突破**：AI 不再是孤立的，而是可以互相感知、通讯、控制的集群。 + +👉 [深入了解AI蜂群协作](./i18n/zh/documents/02-方法论/AI蜂群协作-tmux多Agent协作系统.md) + +
+ --- ## 🖼️ 概览 diff --git a/i18n/zh/documents/02-方法论/AI蜂群协作-tmux多Agent协作系统.md b/i18n/zh/documents/02-方法论/AI蜂群协作-tmux多Agent协作系统.md new file mode 100644 index 0000000..a1885d3 --- /dev/null +++ b/i18n/zh/documents/02-方法论/AI蜂群协作-tmux多Agent协作系统.md @@ -0,0 +1,693 @@ +# 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 : -p -S - + +# 示例：读取会话 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 : -p -S -100 + +### 行为 +- 开始任务前先扫描环境 +- 发现相关任务主动协调 +- 完成后广播状态 +``` + +### 7.2 完整版（Worker） + +```markdown +## 🐝 AI 蜂群协作协议 v2.0 + +你是 tmux 多终端 AI 集群中的一员。 + +### 感知能力 + +# 列出所有窗口 +tmux list-windows -a + +# 读取指定窗口（最近 100 行） +tmux capture-pane -t : -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* diff --git a/i18n/zh/documents/02-方法论/README.md b/i18n/zh/documents/02-方法论/README.md index 25f4e18..91c89cb 100644 --- a/i18n/zh/documents/02-方法论/README.md +++ b/i18n/zh/documents/02-方法论/README.md @@ -2,6 +2,11 @@ > 工具使用、开发经验与实践技巧 +## 🎨 AI 协作范式 + +- [Canvas白板驱动开发](./图形化AI协作-Canvas白板驱动开发.md) - 图形是第一公民，代码是白板的序列化形式 +- [AI蜂群协作](./AI蜂群协作-tmux多Agent协作系统.md) - 基于 tmux 的多 AI Agent 协作系统 + ## 📖 工具教程 - [tmux 快捷键大全](./tmux快捷键大全.md) - 终端复用工具