┌──────────────────────────────────────────────────────────────────┐
│  你的 VS Code / 主会话                                            │
│                                                                   │
│  用自然语言管理团队、启动终端、分配总任务                             │
│       ↓                                                           │
│  MCP Server (FastMCP)  ←── teams_data.json (持久化)               │
│       ↓                                                           │
│  ┌─ tmux session: mcp_dev_team ─────────────────────────────────┐ │
│  │  window: 👑alice (leader · codex)  ← 自动连接 MCP            │ │
│  │  window: bob   (coder  · claude)  ← 纯文本接收子任务         │ │
│  │  window: carol (tester · codex)   ← 纯文本接收子任务         │ │
│  └──────────────────────────────────────────────────────────────┘ │
└──────────────────────────────────────────────────────────────────┘

git clone <your-repo-url> mult_agent_mcp
cd mult_agent_mcp
./install.sh

pip install fastmcp

tmux -V

# Ubuntu / Debian
sudo apt install tmux
pip install textual

# macOS
brew install tmux

# Claude Code
npm install -g @anthropic-ai/claude-code

# Codex CLI（需要 Node.js ≥ 22，ChatGPT Plus/Pro 账号或 API Key）
npm install -g @openai/codex

{
  "mcpServers": {
    "mult-agent-mcp": {
      "type": "http",
      "url": "http://localhost:8000/mcp"
    }
  }
}

codex mcp add mult-agent-mcp --url http://localhost:8000/mcp

cd mult_agent_mcp
python mult_agent_mcp.py
# 或指定端口
FASTMCP_PORT=8000 python mult_agent_mcp.py

cd mult_agent_mcp
pip install textual         # 首次需要安装
python team_manger.py

┌─ Multi-Agent MCP — Team Manager ─────────────────────────────┐
│  📋 共 2 个团队                                                │
│                                                               │
│  ┌───────────────────────────────────────────────────────┐    │
│  │ 团队名称   │ 成员数 │ 默认Agent │ Leader    │ 终端状态 │    │
│  │ dream_team │   3   │  claude   │ alice(tmux)│ 🟢     │    │
│  │ dev_team   │   2   │  codex    │ —          │ ⚫     │    │
│  └───────────────────────────────────────────────────────┘    │
│                                                               │
│  A 添加团队 | Enter 查看详情 | D 删除团队 | L 接管Leader | Q 退出│
└───────────────────────────────────────────────────────────────┘

┌─ Team Manager ───────────────────────────────────────────────┐
│  📋 dream_team  终端: 🟢 运行中                                 │
│                                                               │
│  ┌───────────────────────────────────────────────┐            │
│  │ 名称   │ 角色   │ Agent │ Leader  │           │            │
│  │ alice  │ leader │ codex │ 👑      │  ← 当前行  │            │
│  │ bob    │ coder  │ claude│         │            │            │
│  │ carol  │ tester │ codex │         │            │            │
│  └───────────────────────────────────────────────┘            │
│                                                               │
│  3 个成员 | Leader: alice (tmux)                               │
│                                                               │
│  A 添加成员 | R 移除成员 | E 编辑成员 | L 指定Leader | Esc 返回  │
└───────────────────────────────────────────────────────────────┘

TUI 添加团队 ─→ teams_data.json ←─ MCP Server team_create
TUI 添加成员 ─→ teams_data.json ←─ MCP Server add_member
TUI 指定Leader ─→ teams_data.json ←─ MCP Server set_leader

> 创建一个团队叫 dream_team，默认 agent 用 claude。
  添加三个成员：
  alice（role=leader, agent=codex），
  bob（role=coder, agent=claude），
  carol（role=tester, agent=codex）

team_create("dream_team", "混合 agent 团队", default_agent="claude")
add_member("dream_team", "alice", role="leader", agent="codex")
add_member("dream_team", "bob",   role="coder",  agent="claude")
add_member("dream_team", "carol", role="tester",  agent="codex")
set_leader("dream_team", "alice")

> 启动 dream_team 的终端，任务是"实现用户登录系统"

> 查看团队
→ leader_list_team("dream_team")
→ bob(coder · claude), carol(tester · codex)

> 让 bob 实现登录页面，让 carol 写测试用例
→ leader_assign_subtask("dream_team", "bob", "实现登录页面...")
→ leader_assign_subtask("dream_team", "carol", "写登录测试用例...")

> 查看终端状态
→ terminal_status("dream_team")

> 关闭所有终端
→ kill_team_terminals("dream_team")

你 ─→ MCP ─→ launch_team_terminals ─→ [alice tmux] ─→ leader_* ─→ [bob] [carol]

claim_leader("dream_team")
# 如果旧 leader 存活 → 自动降级为普通成员
# 如果旧 leader 已死 → 直接接管

# 直接在当前会话分配任务
leader_assign_subtask("dream_team", "bob", "实现登录页面")
leader_broadcast("dream_team", "进度更新：前端完成 30%")

# 释放
unclaim_leader("dream_team", restore_member="alice")

# 创建团队
team_create("mixed_team", default_agent="claude")

# Claude 作为 leader + Codex 作为成员
add_member("mixed_team", "alice", role="leader", agent="claude")
add_member("mixed_team", "bob",   role="coder",  agent="codex")
add_member("mixed_team", "carol", role="tester",  agent="codex")
set_leader("mixed_team", "alice")

# 或者反过来——Codex 作为 leader
add_member("mixed_team", "dave", role="backend_dev", agent="claude")
member_set_agent("mixed_team", "alice", "codex")  # 切换 leader 类型
launch_team_terminals("mixed_team", task="实现微服务架构")

# 检查 agent 配置状态
check_agent_setup("mixed_team")
→ Claude MCP: ✅
→ Codex MCP: ✅

# 也可以手动在终端执行
codex mcp add mult-agent-mcp --url http://localhost:8000/mcp
codex mcp list

leader_assign_subtask("team", "bob", "实现登录页面")
          │
          ▼
tmux send-keys -t mcp_team:bob "实现登录页面" Enter
          │
          ▼
bob 的终端窗口收到文本 → claude 或 codex 开始执行

leader_read_member_terminal("team", "bob")         # 查看成员是否停在 approval prompt
leader_authorize_member("team", "bob", "yes")      # 选择第 1 项，通常为本次允许
leader_authorize_member("team", "bob", "session")  # 选择第 2 项，通常为本会话记住
leader_authorize_member("team", "bob", "3")        # 选择第 3 项，具体含义以终端提示为准

claim_leader("team")
        │
        ├── 已经是 direct leader
        │   → 提示"你已经是 leader"
        │
        ├── 之前无 leader
        │   → 🆕 设为直接控制模式
        │
        ├── 有 tmux leader 且终端存活
        │   → 🔄 原 leader 降级为普通成员（窗口保留）
        │   → ✅ 你接管为 leader
        │
        └── 有 tmux leader 但终端已死
            → 💀 直接接管，清理死引用

{
  "teams": {
    "dream_team": {
      "description": "混合 agent 团队",
      "leader": "alice",
      "leader_type": "tmux",
      "default_agent": "claude",
      "terminals_active": true,
      "members": {
        "alice": {"role": "leader", "model": "", "agent": "codex"},
        "bob":   {"role": "coder",  "model": "", "agent": "claude"},
        "carol": {"role": "tester", "model": "", "agent": "codex"}
      }
    }
  }
}

# 查看团队终端
tmux attach -t mcp_dev_team

# 在 tmux 中: Ctrl+B 然后按数字键 → 切换窗口
# 在 tmux 中: Ctrl+B 然后按 W → 列出所有窗口
# 在 tmux 中: Ctrl+B 然后按 D → 脱离（不关闭）

tmux list-sessions              # 列出所有 session
tmux list-windows -t mcp_dev_team  # 列出某 session 的窗口