┌─────────────────────────────────────────────────────────────┐
│ 前端 (Renderer)                                              │
│ ┌──────────────────────────────────────────────────────┐   │
│ │ useTeamSession() / useTeamList()                     │   │
│ │ TeamPage → AgentTabs + ChatView                      │   │
│ │ 订阅: team.agent.status, team.agent.spawned, ...    │   │
│ └──────────────────────────────────────────────────────┘   │
│            ↓ (ipcBridge.team.* → HTTP/WS)                   │
├─────────────────────────────────────────────────────────────┤
│ Backend API (aionui-backend)                                 │
│ POST /api/teams, GET /api/teams/{id}, ...                   │
│ 转发 WebSocket 事件到前端                                    │
│            ↓ (IPC / Direct Call)                            │
├─────────────────────────────────────────────────────────────┤
│ 后端 (Main Process)                                          │
│ ┌──────────────────────────────────────────────────────┐   │
│ │ TeamSession                                          │   │
│ │  ├─ Mailbox (SQLite)                               │   │
│ │  ├─ TaskManager (SQLite)                           │   │
│ │  ├─ TeammateManager (agent lifecycle)              │   │
│ │  └─ TeamMcpServer (TCP @ localhost:random)         │   │
│ └──────────────────────────────────────────────────────┘   │
│            ↓ (TCP + env vars)                               │
├─────────────────────────────────────────────────────────────┤
│ Agent Process                                                │
│ ┌──────────────────────────────────────────────────────┐   │
│ │ stdio-mcp-bridge                                     │   │
│ │  - read: TEAM_MCP_PORT, TEAM_MCP_TOKEN             │   │
│ │  - connect to TCP server                            │   │
│ │  - expose MCP tools                                 │   │
│ │  - send: mcp_ready notification                     │   │
│ └──────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────┘

前端:   ipcBridge.team.sendMessage({ team_id, content })
  ↓
HTTP:   POST /api/teams/{team_id}/messages
  ↓
主进程: TeamSession.sendMessage()
  ├─ Ensure MCP server started
  ├─ Write to leader's mailbox
  ├─ Add user bubble to leader's conversation
  ├─ Emit WebSocket: message.stream (type=user_content)
  └─ Wake leader agent
  ↓
前端:   Subscribe conversation.responseStream → show bubble

Agent:  Call MCP tool: team_send_message
        { to: "agent_name", message: "...", summary?: "..." }
  ↓
TCP:    Validate auth token → handleToolCall()
  ↓
主进程:
  ├─ resolveSlotId(to) → match target slot_id
  ├─ Write to target's mailbox
  ├─ Call safeWake(target_slot_id)
  └─ Return success
  ↓
目标:   Next wake() → readUnread() → process messages

启动:   ipcBridge.team.ensureSession({ team_id })
  ↓
主进程: TeamSession.startMcpServer()
  ├─ Create net.Server on localhost:0
  ├─ Generate random auth token (UUID)
  ├─ Emit: team.mcp.status (phase=tcp_ready, port)
  └─ Return StdioMcpConfig with env vars
  ↓
注入:   session/new { mcpServers: [{ name, command, args, env }] }
  ├─ env: TEAM_MCP_PORT={port}
  ├─ env: TEAM_MCP_TOKEN={token}
  └─ env: TEAM_AGENT_SLOT_ID={slot_id}
  ↓
Agent:  stdio-mcp-bridge.js
  ├─ Read env vars
  ├─ Connect to localhost:{TEAM_MCP_PORT}
  ├─ Validate {TEAM_MCP_TOKEN}
  ├─ Register MCP tools (in Claude CLI)
  └─ Send: { type: 'mcp_ready', from_slot_id }
  ↓
主进程: handleTcpConnection()
  └─ Receive mcp_ready → notifyMcpReady(slot_id)
  ↓
同步:   waitForMcpReady(slot_id) 解除 (30s timeout)

// Team CRUD
POST   /api/teams                           // 创建
GET    /api/teams?user_id=...               // 列表
GET    /api/teams/{id}                      // 详情
DELETE /api/teams/{id}                      // 删除
PATCH  /api/teams/{id}/name                 // 重命名

// Session 控制
POST   /api/teams/{team_id}/session         // 启动/确保 MCP
DELETE /api/teams/{team_id}/session         // 停止

// 消息
POST   /api/teams/{team_id}/messages        // 群聊 (user → leader)
POST   /api/teams/{team_id}/agents/{slot_id}/messages  // 单聊

// Agent 管理
POST   /api/teams/{team_id}/agents          // 添加
DELETE /api/teams/{team_id}/agents/{slot_id}           // 移除
PATCH  /api/teams/{team_id}/agents/{slot_id}/name      // 重命名

// 配置
POST   /api/teams/{team_id}/session-mode    // 设置权限模式
POST   /api/teams/{team_id}/workspace       // 更新 workspace

// 订阅频道
'team.agent.status'; // Agent 状态变更
'team.agent.spawned'; // 新 agent 加入
'team.agent.removed'; // Agent 被移除
'team.agent.renamed'; // Agent 被重命名
'team.list-changed'; // Team 列表变更
'team.mcp.status'; // MCP 状态更新

// Team 基本信息
type TTeam = {
  id: string;
  user_id: string;
  name: string;
  workspace: string; // 工作目录
  workspace_mode: 'shared' | 'isolated';
  leader_agent_id: string; // 指向 agents[*].slot_id
  agents: TeamAgent[];
  session_mode?: string; // 'plan', 'auto', etc
  created_at: number;
  updated_at: number;
};

// 单个 Agent
type TeamAgent = {
  slot_id: string; // 运行时唯一 ID
  conversation_id: string; // 对应聊天记录
  role: 'leader' | 'teammate';
  agent_type: string; // 'claude', 'gemini', 'acp'
  agent_name: string; // 用户显示名称
  conversation_type: string; // 'acp', 'aionrs', 'codex'
  status: 'pending' | 'idle' | 'active' | 'completed' | 'failed';
  model?: TProviderWithModel;
};

// Mailbox 消息
type MailboxMessage = {
  id: string;
  team_id: string;
  to_agent_id: string;
  from_agent_id: string; // 'user' | slot_id
  type: 'message' | 'idle_notification' | 'shutdown_request';
  content: string;
  read: boolean;
  created_at: number;
};

// 共享任务
type TeamTask = {
  id: string;
  team_id: string;
  subject: string;
  status: 'pending' | 'in_progress' | 'completed' | 'deleted';
  owner?: string; // slot_id
  blocked_by: string[]; // task dependencies
  blocks: string[];
  metadata: Record<string, unknown>;
  created_at: number;
};

// 获取 Team 列表
const { teams, mutate, removeTeam } = useTeamList();

// 管理单个 Team 的会话
const { statusMap, sendMessage, addAgent, renameAgent, removeAgent, mutateTeam } = useTeamSession(team);

// 监听 Agent 状态
useEffect(() => {
  return ipcBridge.team.agentStatusChanged.on((event: ITeamAgentStatusEvent) => {
    if (event.team_id !== team.id) return;
    // Handle status change: event.status, event.last_message
  });
}, [team.id]);

// 监听 Team 列表变更
useEffect(() => {
  return ipcBridge.team.listChanged.on(() => {
    void mutate(); // Refresh list
  });
}, [mutate]);