gavindiaz/vibe-coding-cn

Fork 0

mirror of https://github.com/tradecatlabs/vibe-coding-cn.git synced 2026-08-17 21:08:05 +00:00

Files

T

tukuaiai a9a68eda3e feat: skills - inspect auto-tmux panes

2026-05-19 03:26:58 +08:00

12 KiB

Raw Permalink Blame History

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 接手

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

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

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

2. 技术原理

tmux 的基本对象是：

session
└── window
    └── pane

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

<session>:<window>.<pane>

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

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

或用原生命令取真实 target：

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

3. 最小工作台

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

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

查看拓扑：

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

读取某个 worker：

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

发送任务：

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

等待完成信号：

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 初始化共享状态目录：

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

默认共享状态目录：

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

最小状态格式：

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

常用状态：

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

4.3 协作规则

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

4.4 任务与锁

添加任务：

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

worker 认领任务：

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"

修改文件前获取锁：

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

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

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"

阻塞或失败时显式记录：

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"

生成交接报告：

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

5. 架构模式

5.1 P2P 对等模式

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

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

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

5.2 Master-Worker 主从模式

commander
├── worker1
├── worker2
└── worker3

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

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

5.3 Pipeline 流水线模式

analysis -> design -> implementation -> test

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

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

5.4 Hybrid 混合模式

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

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

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

6. 实战流程

6.1 多服务并行开发

示例分工：

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

巡检：

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

发现错误：

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

6.2 代码审计 + 自动修复

推荐分工：

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

最小规则：

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

6.3 自动值守

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

推荐先 dry-run：

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

确认后再执行：

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

7. 提示词模板

7.1 Worker 模板

推荐直接渲染：

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

你是 tmux AI 蜂群中的 worker。

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

7.2 Commander 模板