Multi-Agent Skill 是 FlowKit 的 Agent Teams 方案生成与执行引擎，通过 tmux 分屏实现多 Agent 真正的并行执行。
本文是 FlowKit 系列教程第三篇。

GitHub: FrizzleFur/flowkit | 系列导航

目录

• 为什么需要多 Agent
• 核心架构
• Step 0: 项目上下文感知
• Step 1-2: 任务分析与角色匹配
• Step 3: 协作式方案生成
• Step 5: tmux 分屏执行
• Phase 间复用
• 冲突解决
• 实战案例

---

为什么需要多 Agent

单 Agent 模式下，所有任务串行执行。但实际开发中，很多任务是可以并行的：

串行: 认证模块(2h) → 数据库迁移(1h) → API 测试(1h) = 4h
并行: 认证模块(2h) ──┐
      数据库迁移(1h) ──┼─→ 2h（节省 50%）
      API 测试(1h) ────┘

更重要的是，不同任务需要不同的专业角色。一个 Agent 同时做后端开发、测试和安全审计，不如三个专业 Agent 各司其职。

核心架构

用户输入: /MultiAgent 实现用户认证功能
    │
    ▼
Step 0: 项目上下文感知
    │  扫描 CLAUDE.md / package.json / git log
    ▼
Step 1: 资源检测
    │  可用 Agent 类型、MCP 工具、已安装插件
    ▼
Step 2: 任务分析 + 角色匹配
    │  12 种角色类型自动匹配
    ▼
Step 3: 协作式方案生成
    │  直接输出完整方案 → 用户微调
    ▼
Step 4: 评分检查
    │  任务清晰度 + 角色匹配 + 文件分配 + 依赖 + 上下文
    ▼
Step 5: tmux 分屏执行
    │  TeamCreate + 并行启动 + 即时清理
    ▼
  执行结果

Step 0: 项目上下文感知

在分配 Agent 之前，先了解项目背景。扫描策略（优先级递减）：

1. ONBOARDING.md → 提取工作类型分布、MCP 清单、团队 Tips
2. CLAUDE.md → 提取项目规范、代码风格、约束条件
3. 轻量扫描（兜底）→ git log --oneline -20 + package.json

输出（注入到每个 Agent 的 prompt 中）:

project_context:
  tech_stack: "Node.js/Express/TypeScript"
  active_areas: "支付模块、认证系统"
  code_style: "偏好函数式、禁止 any"
  key_files: "src/api/*, src/models/*"
  mcp_tools: "serena, playwright"

为什么这一步很重要？没有项目上下文的 Agent 就像”新入职就直接写代码”——不了解团队规范和技术栈，容易产出不兼容的代码。

Step 1-2: 任务分析与角色匹配

12 种角色自动匹配：

任务类型	推荐角色
代码审查	security-auditor, code-reviewer
功能开发(前端)	frontend-developer
功能开发(后端)	backend-developer
数据库	database-optimizer
测试	test-automator
安全	security-auditor
DevOps	devops-architect
文档	technical-writer
研究	research-analyst
通用	general-purpose

复杂度判断:

级别	条件	确认步骤
简单	<3 个队友、无依赖	仅确认队友
中等	3-5 个队友、有依赖	队友 + 文件 + 依赖
复杂	>5 个队友、跨系统	队友 + 文件 + 依赖 + 隔离 + 验收标准

Step 3: 协作式方案生成

核心理念: 先输出完整方案草案，再请用户微调（而非逐项确认）。

传统方式: "用什么角色？" → "分配哪些文件？" → "有依赖吗？" → ...（7轮对话）
协作方式: 输出完整方案 → 用户审阅指出调整部分 → 修改确认

方案输出格式:

# Agent Teams 方案: 用户认证功能

## 队友配置
| 队友 | 角色 | 文件范围 | 依赖 |
|------|------|---------|------|
| api | backend-developer | src/api/auth/* | - |
| db | database-optimizer | src/models/user.* | - |
| test | test-automator | tests/auth/* | api, db |

## 依赖图
api → test
db → test
（api 和 db 可并行，test 需要等两者完成）

## Agent Prompt 要点
每个 Agent 的 prompt 包含:
  1. 具体任务描述
  2. 项目上下文摘要（Step 0 输出）
  3. 文件边界（可编辑/只读/禁止）
  4. 与其他 Agent 的接口约定

Step 5: tmux 分屏执行

唯一执行模式: tmux-split。不使用 run_in_background。

为什么用 tmux 而非 in-process？

in-process (run_in_background):
  - Agent 失败是静默的，用户无法实时查看
  - 多个 Agent 同时编辑同一文件导致冲突难以追踪
  - 无法实时观察执行过程

tmux-split:
  - 每个 Agent 的执行过程可视化，出现问题可直接介入
  - 文件边界隔离自然解决冲突
  - Phase 间可以复用分屏，避免资源浪费

执行步骤

1. 环境检测: [ -n "$TMUX" ] → 必须在 tmux 中运行

2. 创建 Team:
   TeamCreate({ team_name: "auth-feature" })

3. 并行启动 Teammates（无依赖的在同一条消息中）:
   Agent({ name: "api", team_name: "auth-feature", ... })
   Agent({ name: "db", team_name: "auth-feature", ... })  // 与 api 并行

4. 监控协调: TaskList 跟踪进度，SendMessage 协调

5. 依赖触发: api + db 完成后 → 启动 test Agent

文件边界

每个 Agent 有三类文件边界：

类型	含义	示例
可编辑	Agent 可以修改	api Agent: src/api/auth/*
只读	可以读取但不能改	api Agent: src/models/user.*
禁止	不可访问	api Agent: tests/*

Phase 间复用

关键原则: Phase 间不销毁 team，应复用空闲 Agent。

绝对禁止:
  - 不管已有 pane 直接创建新 Agent（面板越开越多）
  - 全部 shutdown 再重建（浪费资源）
  - 使用 run_in_background 替代分屏 Agent

正确做法:
  1. TaskList → 找 status=completed 的 Agent
  2. SendMessage → 发送新任务给空闲 Agent（复用原分屏）
  3. 补充/裁剪 → 空闲不够则新建，多余则 shutdown

冲突解决

类型	预防	处理
文件冲突	明确文件边界	主 Agent 审查差异，选择保留版本
设计冲突	Step 3 明确接口	主 Agent 裁决，SendMessage 通知适配
依赖冲突	task_plan 标注依赖	主 Agent 重新排序
进度阻塞	设置超时	重试或降级

实战案例

案例 1: 中等任务 — 用户认证功能

输入: /MultiAgent 实现用户认证功能

Step 0: 读取 CLAUDE.md → 技术栈 Node.js/Express
Step 1: 检测资源 → backend-developer, test-automator 可用
Step 2: 任务分析 → 功能开发, 中等复杂度

方案草案:
| 队友 | 角色 | 文件范围 | 依赖 |
| api | backend-developer | src/api/auth/*, src/middleware/auth.* | - |
| test | test-automator | tests/auth/* | api |

用户微调 → 确认 → 并行执行:
  Phase 1: api Agent 独立执行
  Phase 2: test Agent 接管（复用 api 的分屏）

案例 2: 简单任务 — Bug 修复

输入: /MultiAgent 修复登录页面的表单验证 bug

方案: 1 个 fixer(frontend-developer) + 1 个 reviewer(code-reviewer)
无依赖，直接并行。

案例 3: 复杂任务 — 支付系统重构

输入: /MultiAgent 重构支付系统，支持多币种

方案: 5 个 Agent，3 个 Phase:
  Phase 1: core(支付核心) + gateway(支付网关) — 并行
  Phase 2: security(安全审计) — 依赖 Phase 1
  Phase 3: test(测试) + docs(文档) — 并行，依赖 Phase 2

需要 worktree 隔离，Phase 间复用分屏。

---

系列导航

FlowKit 系列教程

#	文章	内容
1	总览：AI 原生工作流编排的设计哲学	动机、架构、Iron Laws、社区对比
2	Prompt 量化评分：乔哈里视窗 x 3S 原则	四象限、3S、7维评分、第四象限陷阱
3	Multi-Agent 协作：tmux 分屏并行引擎	角色匹配、文件隔离、Phase复用
4	Flow 轻量编排：5 阶段管道按需启用	Stage流程、Plan Mode、Fallback协议
5	Flow-Deep 深度管道：全量质量保障引擎	Plan Review、Auto-Decide、STATE.md、Ralph Loop

---

FlowKit 使用 MIT 协议开源。如果对 AI Agent 工作流编排感兴趣，欢迎 Star 和交流。