docs/architecture/agent-team-guide-flow.md
┌─────────────────────────────────────────────────────────────────────────────┐
│ USER (普通 Agent 对话) │
└─────────────────┬───────────────────────────────────────────────────────────┘
│
│ ① 发送消息："帮我做一个完整的电商网站，
│ 包含前端、后端、数据库设计和部署方案"
▼
┌─────────────────────────────────────────────────────────────────────────────┐
│ SOLO AGENT (ACP Session) │
│ │
│ ┌────────────────────────────────────────────────────────────────────┐ │
│ │ System Prompt (注入的引导规则) │ │
│ │ │ │
│ │ "你是 Aion 智能助手。当用户需求涉及多个专业领域（前端/后端/架构/ │ │
│ │ 测试/设计等），且并行协作能显著提升效率时，应建议用户启用团队模式。 │ │
│ │ 判断标准： │ │
│ │ - 任务可拆分为 2+ 独立子领域 │ │
│ │ - 子任务间存在并行空间 │ │
│ │ - 单 Agent 完成耗时远大于多 Agent 协作 │ │
│ │ 建议时需说明：为什么推荐、团队能怎么分工。 │ │
│ │ 用户同意后，调用 aion_create_team 工具。" │ │
│ └────────────────────────────────────────────────────────────────────┘ │
│ │
│ ② Agent 分析需求 → 判断：涉及前端+后端+数据库+DevOps，适合 Team │
│ │
└─────────────────┬───────────────────────────────────────────────────────────┘
│
│ ③ 回复用户（自然语言建议）
▼
┌─────────────────────────────────────────────────────────────────────────────┐
│ AGENT → USER: │
│ │
│ "我分析了你的需求，这是一个涉及多个领域的复杂项目： │
│ - 前端工程（React/UI） │
│ - 后端服务（API/业务逻辑） │
│ - 数据库设计（Schema/索引） │
│ - 部署方案（CI/CD/基础设施） │
│ │
│ 我认为组建团队来完成会更高效——多个专业 Agent 可以并行工作。 │
│ 需要我开启团队模式来完成这个任务吗？" │
└─────────────────┬───────────────────────────────────────────────────────────┘
│
│ ④ 用户回复："好的，开启团队模式"
▼
┌─────────────────────────────────────────────────────────────────────────────┐
│ AGENT 调用 MCP Tool: aion_create_team │
│ │
│ Tool Input: │
│ { │
│ "summary": "构建完整电商网站，包含： │
│ 1) React 前端（商品展示/购物车/结算） │
│ 2) Node.js 后端（RESTful API/认证/支付） │
│ 3) PostgreSQL 数据库设计（用户/商品/订单） │
│ 4) Docker + CI/CD 部署方案", │
│ "name": "电商网站全栈开发" ← 可选，Agent 自动起名 │
│ } │
└─────────────────┬───────────────────────────────────────────────────────────┘
│
▼
┌═════════════════════════════════════════════════════════════════════════════┐
║ MCP SERVER (主进程内运行) ║
║ ║
║ ┌─── aion_create_team handler ───────────────────────────────────────┐ ║
║ │ │ ║
║ │ 1. 接收 summary + name │ ║
║ │ │ ║
║ │ 2. 构建 createTeam 参数 │ ║
║ │ { │ ║
║ │ userId: currentUserId, │ ║
║ │ name: "电商网站全栈开发", │ ║
║ │ workspace: "", // 自动分配 │ ║
║ │ workspaceMode: "shared", │ ║
║ │ agents: [{ │ ║
║ │ slotId: "slot-xxx", │ ║
║ │ role: "lead", │ ║
║ │ agentType: "acp", // 默认 lead 类型 │ ║
║ │ agentName: "Team Lead", │ ║
║ │ ... │ ║
║ │ }] │ ║
║ │ } │ ║
║ │ │ ║
║ │ 3. 调用 TeamSessionService.createTeam(params) │ ║
║ │ → 生成 teamId (UUID) │ ║
║ │ → 创建 lead agent 的 conversation │ ║
║ │ → 持久化到 SQLite │ ║
║ │ │ ║
║ │ 4. 调用 TeamSessionService.getOrStartSession(teamId) │ ║
║ │ → 创建 TeamSession │ ║
║ │ → 启动 Team MCP Server │ ║
║ │ → 注入 MCP config 到 agent conversations │ ║
║ │ │ ║
║ │ 5. 向 lead agent 发送首条消息（用户需求摘要） │ ║
║ │ ipcBridge.team.sendMessage.invoke({ │ ║
║ │ teamId, │ ║
║ │ content: summary // 需求摘要作为 lead 的第一条指令 │ ║
║ │ }) │ ║
║ │ │ ║
║ │ 6. 返回结果 │ ║
║ │ { │ ║
║ │ teamId: "abc-123-def", │ ║
║ │ name: "电商网站全栈开发", │ ║
║ │ route: "/team/abc-123-def", │ ║
║ │ leadAgent: "Team Lead", │ ║
║ │ status: "session_started" │ ║
║ │ } │ ║
║ └────────────────────────────────────────────────────────────────────┘ ║
║ ║
╚═════════════════════════════════════════════════════════════════════════════╝
│
│ ⑤ MCP 返回 Team 信息
▼
┌─────────────────────────────────────────────────────────────────────────────┐
│ SOLO AGENT (收到 MCP 结果) │
│ │
│ Agent 知道 Team 已创建，需要引导用户跳转 │
│ │
│ ⑥ 调用 MCP Tool: aion_navigate │
│ { "route": "/team/abc-123-def" } │
│ │
│ 同时回复用户： │
│ "已为你组建团队「电商网站全栈开发」，正在跳转... 🚀" │
│ │
└─────────────────┬───────────────────────────────────────────────────────────┘
│
▼
┌═════════════════════════════════════════════════════════════════════════════┐
║ MCP SERVER: aion_navigate handler ║
║ ║
║ 1. 校验 route 合法性（白名单：/team/:id, /conversation/:id, ...） ║
║ ║
║ 2. 通过 IPC 通知 Renderer 跳转 ║
║ ipcBridge.deepLink.received.emit({ ║
║ action: "navigate", ║
║ params: { route: "/team/abc-123-def" } ║
║ }) ║
║ ║
║ 3. 返回 { success: true } ║
╚═════════════════════════════════════════════════════════════════════════════╝
│
│ ⑦ IPC emit → Renderer
▼
┌─────────────────────────────────────────────────────────────────────────────┐
│ RENDERER (前端) │
│ │
│ useDeepLink() hook 监听到 deepLink.received 事件 │
│ action === "navigate" → navigate("/team/abc-123-def") │
│ │
│ ┌────────────────────────────────────────────────────────────────────┐ │
│ │ React Router 匹配 /team/:id │ │
│ │ → 加载 TeamIndex (lazy) │ │
│ │ → fetch team via ipcBridge.team.get │ │
│ │ → 渲染 TeamPage │ │
│ └────────────────────────────────────────────────────────────────────┘ │
│ │
│ ┌────────────────────────────────────────────────────────────────────┐ │
│ │ useTeamSession(team) hook │ │
│ │ → session 已在 MCP handler 中预启动，直接复用 │ │
│ │ → 订阅 agentStatusChanged / agentSpawned / agentRemoved 事件 │ │
│ └────────────────────────────────────────────────────────────────────┘ │
│ │
└─────────────────┬───────────────────────────────────────────────────────────┘
│
│ ⑧ 页面渲染完成
▼
┌─────────────────────────────────────────────────────────────────────────────┐
│ TEAM PAGE (用户看到的) │
│ │
│ ┌──────────────────────────────────────────────────────────────┐ │
│ │ │ │
│ │ 📋 电商网站全栈开发 │ │
│ │ │ │
│ │ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ │ │
│ │ │ Lead ★ │ │Frontend │ │Backend │ │ DBA │ ← 按需 │ │
│ │ │(工作中) │ │ (待派发)│ │ (待派发)│ │ (待派发)│ spawn │ │
│ │ └─────────┘ └─────────┘ └─────────┘ └─────────┘ │ │
│ │ │ │
│ │ Lead Agent: │ │
│ │ "收到任务，我来拆分并分配： │ │
│ │ 1. @Frontend → React 商品展示/购物车/结算页面 │ │
│ │ 2. @Backend → Node.js API 服务/认证/支付集成 │ │
│ │ 3. @DBA → PostgreSQL Schema 设计 │ │
│ │ 让我先创建团队成员..." │ │
│ │ │ │
│ └──────────────────────────────────────────────────────────────┘ │
│ │
│ ✅ 用户看到 Team 已在工作，无需手动操作 │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
User Renderer Solo Agent MCP Server Main Process Team Lead
│ │ │ │ │ │
│──① 发消息────▶│───── IPC ─────▶│ │ │ │
│ │ │ │ │ │
│ │ │─② 分析需求──┐ │ │ │
│ │ │ 判断适合Team│ │ │ │
│ │ │◀────────────┘ │ │ │
│ │ │ │ │ │
│◀──③ 建议────── │◀──────────────│ │ │ │
│ "建议开启 │ │ │ │
│ 团队模式" │ │ │ │
│ │ │ │ │ │
│──④ "好的"───▶│───── IPC ─────▶│ │ │ │
│ │ │ │ │ │
│ │ │──⑤ call ──────▶│ │ │
│ │ │ aion_create_ │── createTeam ──▶│ │
│ │ │ team │ │─ 写入 DB │
│ │ │ │ │─ 创建 Session │
│ │ │ │ │─ 启动 MCP Server │
│ │ │ │◀── team info ──│ │
│ │ │ │ │ │
│ │ │ │── sendMessage ─▶│────── IPC ──────▶│
│ │ │ │ (需求摘要) │ │─ 开始
│ │ │◀─⑥ return ────│ │ │ 工作
│ │ │ {teamId, │ │ │
│ │ │ route} │ │ │
│ │ │ │ │ │
│ │ │──⑦ call ──────▶│ │ │
│◀── "正在跳转" │ │ aion_navigate │── deepLink ────▶│ │
│ │ │ │ emit │ │
│ │◀───────────────│────────────────│── IPC emit ────│ │
│ │ │ │ │ │
│ │─⑧ navigate ──┐│ │ │ │
│ │ /team/:id ││ │ │ │
│ │◀─────────────┘│ │ │ │
│ │ │ │ │ │
│ ┌────────────▼────────────┐ │ │ │ │
│ │ ⑨ Team Page 渲染 │ │ │ │ ┌─────────────▼┐
│ │ Lead Agent 已在工作 │ │ │ │ │ 拆分任务 │
│ │ 用户看到实时进展 │ │ │ │ │ spawn 成员 │
│ └─────────────────────────┘ │ │ │ │ 分配工作 │
│ │ │ │ │ └───────────────┘
| # | 模块 | 位置 | 职责 |
|---|---|---|---|
| 1 | Team Guide Prompt | src/process/resources/prompts/teamGuidePrompt.ts | 注入 solo agent 的团队引导规则 |
| 2 | Aion MCP Server | src/process/services/aionMcpServer.ts | 主进程内 MCP，提供 aion_create_team + aion_navigate |
| 3 | MCP 注册 | src/process/agent/acp/mcpSessionConfig.ts | 将 Aion MCP 注册到 solo agent session |
| 4 | DeepLink 扩展 | src/renderer/hooks/system/useDeepLink.ts | 处理 navigate action，支持任意路由跳转 |
aion_navigate 只允许跳转到已知路由（/team/:id, /conversation/:id）