1. 读类型定义 → 理解数据模型
2. 读后端核心 → 理解 Team 生命周期和 MCP 架构
3. 读前端页面 → 理解 UI 流程和状态管理
4. 追踪 IPC Bridge → 理解前后端通信契约
5. 构建完整数据流图
6. 编写 PRD + 验证清单

┌─ Layer 1: Renderer (React + TypeScript) ──────────────┐
│ • useTeamSession / useTeamList hooks                   │
│ • TeamPage + TeamTabs + TeamChatView components        │
│ • WebSocket 事件驱动的状态更新                         │
└─────────────────────────────────────────────────────────┘
                        ↓↑
              ipcBridge.team.* (HTTP/WS)
                        ↓↑
┌─ Layer 2: Backend API (aionui-backend) ────────────────┐
│ • REST API: POST/GET/DELETE /api/teams/*              │
│ • WebSocket 中转: team.* 事件从后端转发到前端         │
└─────────────────────────────────────────────────────────┘
                        ↓↑
                   Direct IPC Call
                        ↓↑
┌─ Layer 3: Main Process (Node.js + Electron) ──────────┐
│ • TeamSession: 协调 Mailbox + TaskManager + MCP       │
│ • TeamMcpServer: TCP server (认证 + 工具分发)         │
│ • TeammateManager: Agent 生命周期 + wake 机制         │
│ • SQLite Repository: 持久化存储                       │
└─────────────────────────────────────────────────────────┘
                        ↓↑
          TCP @ localhost + stdio MCP bridge
                        ↓↑
┌─ Layer 4: Agent Process (Claude CLI + MCP) ───────────┐
│ • 读 env vars: TEAM_MCP_PORT/TOKEN/SLOT_ID           │
│ • 连接 TCP server 并发送 mcp_ready 通知              │
│ • 通过 MCP 工具调用进行团队协调                       │
└─────────────────────────────────────────────────────────┘

Step 1: TeamSession.startMcpServer()
  → net.createServer() on localhost:random
  → 生成一次性 UUID token

Step 2: TeamMcpServer.getStdioConfig(agentSlotId)
  → 返回配置对象，包含:
    - command: 'node'
    - args: ['scripts/team-mcp-stdio.js']
    - env: [TEAM_MCP_PORT={port}, TEAM_MCP_TOKEN={token}, TEAM_AGENT_SLOT_ID={slotId}]

Step 3: Inject into session/new
  → agent CLI 接收 mcpServers 配置
  → 启动 stdio 脚本，将 env vars 传入

Step 4: stdio-mcp-bridge.js
  → 读环境变量
  → 连接 TCP socket
  → 验证 token (防止未授权访问)
  → 发送 mcp_ready 通知

Step 5: waitForMcpReady(slot_id)
  → 等待 mcp_ready 信号（30s timeout）
  → 解除等待后，MCP 工具对 agent 可用

user sends message
  → HTTP POST /api/teams/{team_id}/messages
  → Backend → TeamSession.sendMessage()
  → Write to leader.mailbox (from_agent_id='user')
  → Emit WebSocket: message.stream (type='user_content')
  → Wake leader agent
  → Leader 的下一次 turn 会 readUnread() 获取消息

Agent A calls MCP tool: team_send_message({to: 'Agent B', message: '...'})
  → TCP request to TeamMcpServer
  → handleSendMessage() → resolveSlotId('Agent B') → find target slot_id
  → Write to B.mailbox (from_agent_id=A.slot_id)
  → safeWake(B.slot_id) [fire-and-forget]
  → Response: "Message sent to Agent B"
  → Agent B 的下一次 wake 会 readUnread() 获取消息

Agent A calls MCP tool: team_send_message({to: '*', message: '...'})
  → handleSendMessage() recognizes to='*'
  → Loop through all teammates (except A)
  → For each teammate: Write mailbox + safeWake()
  → Response: "Message broadcast to N teammate(s)"

Agent A: team_shutdown_agent({slot_id: A})
  → TeamMcpServer sends idle_notification to leader

Leader: Decides → team_send_message('shutdown_approved')
  → TeamMcpServer recognizes "shutdown_approved"
  → Calls removeAgent(A.slot_id)
  → Emits WebSocket: team.agent.removed
  → Frontend: Remove A's tab

或 Leader: team_send_message('shutdown_rejected: still working')
  → Agent remains in team

pending (初始)
  ↓ (第一次 wake)
idle (待命)
  ↓ (接收消息开始处理)
active (处理中)
  ↓ (处理完成或出错)
idle 或 failed
  ↓ (可以 shutdown_approved)
removed (从 team 移除)

/Users/zhuqingyu/.superset/worktrees/AionUi/aquatic-frigate/
├── TEAM_MCP_PRD.md                          # 完整 PRD (1200+ 行)
├── TEAM_MCP_VERIFICATION_CHECKLIST.md       # 验证清单 (500+ 行)
├── TEAM_MCP_QUICK_REFERENCE.md              # 快速参考 (300+ 行)
└── TEAM_MCP_RESEARCH_SUMMARY.md             # 本文件

pages/team/
├── index.tsx                    # 路由入口
├── TeamPage.tsx                 # 主页面
├── components/
│   ├── TeamCreateModal.tsx
│   ├── TeamChatView.tsx
│   ├── TeamTabs.tsx
│   ├── AgentStatusBadge.tsx
│   └── ...
└── hooks/
    ├── useTeamSession.ts        # 核心 hook
    ├── useTeamList.ts
    ├── TeamTabsContext.tsx
    └── ...

├── TeamSession.ts               # 协调核心
├── TeammateManager.ts           # Agent 生命周期
├── Mailbox.ts                   # Mailbox 接口
├── TaskManager.ts               # 任务板
├── mcpReadiness.ts              # 就绪同步
├── mcp/
│   ├── team/
│   │   └── TeamMcpServer.ts     # MCP TCP 服务器
│   └── ...
├── repository/
│   └── SqliteTeamRepository.ts  # 数据库操作
└── prompts/
    ├── buildRolePrompt.ts
    └── ...

types/
└── teamTypes.ts                 # 共享类型定义

adapter/
├── ipcBridge.ts                 # IPC API (L1429+)
├── teamMapper.ts                # 数据映射
└── ...