# 00 - 多 Agent 协作架构总览

## 1. 设计哲学

本系统借鉴 Claude Code 的核心架构理念：

> **程序做脚手架，LLM 做决策。**

- 程序只负责：循环、注入上下文、执行工具、限流、权限
- LLM 负责：理解用户意图、选择策略、调用工具、判断完成
- 多个专业 Agent 各司其职，由 Coordinator 统一编排

与旧架构的根本区别：**不再用程序化状态机控制对话流程**，而是通过精心设计的 Prompt 引导 LLM 自主决策。

## 2. 整体架构图

```
┌─────────────────────────────────────────────────────────────┐
│                        Frontend                              │
│  web-client (React + Socket.io)                              │
│  ┌─────────────┐  ┌──────────────┐  ┌───────────────┐      │
│  │ ChatWindow   │  │ AgentStatus  │  │ MessageBubble │      │
│  └──────┬──────┘  └──────────────┘  └───────────────┘      │
│         │ WebSocket                                          │
└─────────┼───────────────────────────────────────────────────┘
          │
┌─────────▼───────────────────────────────────────────────────┐
│              Conversation Gateway (WebSocket)                 │
│              conversation.gateway.ts                          │
└─────────┬───────────────────────────────────────────────────┘
          │
┌─────────▼───────────────────────────────────────────────────┐
│              Conversation Service                             │
│              conversation.service.ts                          │
│              (消息持久化、对话管理、Token 追踪)                 │
└─────────┬───────────────────────────────────────────────────┘
          │
┌─────────▼───────────────────────────────────────────────────┐
│         Coordinator Agent Service (主协调器)                  │
│         coordinator-agent.service.ts                         │
│                                                              │
│  ┌──────────────────────────────────────────────────────┐   │
│  │              Agent Loop (递归 async generator)        │   │
│  │                                                      │   │
│  │  ┌──────────────┐    ┌─────────────────────┐        │   │
│  │  │ Context      │───→│  Claude API (Sonnet) │        │   │
│  │  │ Injector     │    │  + Coordinator Prompt │        │   │
│  │  │ (动态上下文)  │    │  + Agent Tools       │        │   │
│  │  └──────────────┘    └──────────┬──────────┘        │   │
│  │                                 │                    │   │
│  │                    ┌────────────▼────────────┐      │   │
│  │                    │  Tool Execution Queue   │      │   │
│  │                    │  (并发/串行调度)          │      │   │
│  │                    └────────────┬────────────┘      │   │
│  │                                 │                    │   │
│  │              ┌──────────────────┼──────────────┐    │   │
│  │              ▼                  ▼              ▼    │   │
│  │    ┌─────────────┐  ┌─────────────┐  ┌──────────┐ │   │
│  │    │ Agent Tools  │  │ Agent Tools  │  │ Direct   │ │   │
│  │    │ (invoke_xxx) │  │ (invoke_xxx) │  │ Tools    │ │   │
│  │    │ → Specialist │  │ → Specialist │  │ (payment │ │   │
│  │    │   API Call   │  │   API Call   │  │  search) │ │   │
│  │    └──────┬──────┘  └──────┬──────┘  └────┬─────┘ │   │
│  │           │                │               │       │   │
│  │           ▼                ▼               ▼       │   │
│  │    ┌─────────────────────────────────────────┐    │   │
│  │    │       tool_results → 递归回 Agent Loop   │    │   │
│  │    └─────────────────────────────────────────┘    │   │
│  └──────────────────────────────────────────────────┘   │
└──────────────────────────────────────────────────────────┘

┌──────────────────────────────────────────────────────────┐
│                    Specialist Agents                       │
│                                                           │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐   │
│  │ Policy       │  │ Assessment   │  │ Strategist   │   │
│  │ Expert       │  │ Expert       │  │              │   │
│  │ (Sonnet)     │  │ (Sonnet)     │  │ (Sonnet)     │   │
│  │ Tools:       │  │ Tools:       │  │ Tools:       │   │
│  │ - search_kb  │  │ - search_kb  │  │ - get_user   │   │
│  └──────────────┘  │ - get_user   │  │   _context   │   │
│                     └──────────────┘  └──────────────┘   │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐   │
│  │ Objection    │  │ Case         │  │ Memory       │   │
│  │ Handler      │  │ Analyst      │  │ Manager      │   │
│  │ (Sonnet)     │  │ (Haiku)      │  │ (Haiku)      │   │
│  │ Tools:       │  │ Tools:       │  │ Tools:       │   │
│  │ - search_kb  │  │ - search_kb  │  │ - save_mem   │   │
│  │ - get_user   │  │ - get_user   │  │ - get_user   │   │
│  └──────────────┘  └──────────────┘  └──────────────┘   │
└──────────────────────────────────────────────────────────┘

┌──────────────────────────────────────────────────────────┐
│                   External Services                       │
│                                                           │
│  ┌───────────┐  ┌───────────┐  ┌───────────┐            │
│  │ Knowledge  │  │ Payment   │  │ Evolution │            │
│  │ Service    │  │ Service   │  │ Service   │            │
│  │ (RAG+Neo4j)│  │ (Alipay/  │  │ (Analytics│            │
│  │ Port 3003  │  │  WeChat)  │  │  +Learn)  │            │
│  │            │  │ Port 3002 │  │ Port 3005 │            │
│  └───────────┘  └───────────┘  └───────────┘            │
└──────────────────────────────────────────────────────────┘
```

## 3. 七个 Agent 一览

| Agent | 角色 | Model | 工具 | 触发时机 |
|-------|------|-------|------|----------|
| **Coordinator** | 主协调器，面对用户 | Sonnet | invoke_* + 直接工具 | 每次用户消息 |
| **Policy Expert** | 政策专家 | Sonnet | search_knowledge | 用户问政策、条件、流程 |
| **Assessment Expert** | 评估专家 | Sonnet | search_knowledge, get_user_context | 需要评估用户资格时 |
| **Strategist** | 策略顾问 | Sonnet | get_user_context | 需要对话策略建议时 |
| **Objection Handler** | 异议处理 | Sonnet | search_knowledge, get_user_context | 用户表达顾虑/犹豫 |
| **Case Analyst** | 案例分析 | Haiku | search_knowledge, get_user_context | 需要用案例说服用户 |
| **Memory Manager** | 记忆管理 | Haiku | save_user_memory, get_user_context | 需要保存/加载用户信息 |

## 4. 消息流转完整路径

```
1. 用户发送消息 (WebSocket: 'message' event)
   │
2. ConversationGateway → ConversationService.sendMessage()
   │
3. ConversationService:
   │  a. 验证对话所有权
   │  b. 保存用户消息
   │  c. 构建 ConversationContext (last 20 messages + state)
   │  d. 调用 CoordinatorAgentService.sendMessage()
   │
4. CoordinatorAgentService → agentLoop():
   │  a. ContextInjector 注入动态上下文:
   │     - 用户历史记忆摘要
   │     - 已收集的用户信息
   │     - 对话统计（轮次、时长）
   │     - 最近的评估结果
   │     - 相关知识预检索
   │
   │  b. 调用 Claude API (Sonnet, streaming)
   │     → yield: text chunks (流式传输给前端)
   │     → yield: agent_start / agent_progress events
   │
   │  c. 如果 Claude 返回 tool_use:
   │     │
   │     ├── invoke_policy_expert({...})
   │     │   → PolicyExpertService.execute()
   │     │   → 独立 Claude API 调用 (Sonnet)
   │     │   → 内部可调 search_knowledge (最多 3 轮)
   │     │   → 返回结构化政策信息
   │     │
   │     ├── invoke_assessment_expert({...})
   │     │   → AssessmentExpertService.execute()
   │     │   → 独立 Claude API 调用 (Sonnet)
   │     │   → 返回评估报告
   │     │
   │     ├── generate_payment({...})    [直接工具，不调 Agent]
   │     │   → 调用 payment-service API
   │     │   → 返回支付链接
   │     │
   │     └── get_current_datetime()     [直接工具，不调 Agent]
   │         → 返回当前时间
   │
   │  d. ToolExecutionQueue:
   │     - Agent 调用之间可并行（invoke_policy + invoke_memory 并行）
   │     - Agent 调用与直接工具可并行
   │     - 写操作串行（save_user_memory）
   │
   │  e. tool_results 返回后 → 递归回步骤 b
   │     Coordinator 综合所有结果，生成最终回复
   │
   │  f. 无 tool_use → 自然结束递归
   │
5. ConversationService:
   │  a. 聚合完整回复
   │  b. 保存助手消息
   │  c. 更新对话统计 (tokens, message count)
   │  d. 提取并保存咨询状态
   │
6. ConversationGateway → WebSocket events:
   - stream_start
   - agent_start {agentName: "policy_expert"}
   - stream_chunk {content: "..."}
   - agent_complete {agentName: "policy_expert"}
   - stream_chunk {content: "综合分析..."}
   - stream_end {usage: {...}}
```

## 5. 与旧架构的关键区别

| 方面 | 旧架构 | 新架构 |
|------|--------|--------|
| 对话流程控制 | 策略引擎（程序状态机，8 阶段） | Coordinator Prompt（LLM 自主判断） |
| 意图分类 | IntentClassifier（规则匹配） | LLM 自行理解意图 |
| 响应质量 | ResponseGate（关键词检查） | Prompt 内置质量标准 |
| 工具调用 | 单 Agent 串行调 10 个工具 | Coordinator 编排，专家 Agent 各持少量工具 |
| 评估逻辑 | 程序化评分算法 | Assessment Expert (LLM + 知识库) |
| 并发能力 | 无 | ToolExecutionQueue 并发调度 |
| 上下文管理 | 固定拼接 last 20 messages | 动态注入 8+ 种上下文 |
| 扩展性 | 改代码加阶段/工具 | 新增 Agent + 注册工具 |

## 6. 技术栈

- **Runtime**: Node.js 18+ / NestJS 10
- **AI SDK**: @anthropic-ai/sdk 0.52+
- **Models**: claude-sonnet-4-20250514 (主力), claude-haiku (辅助)
- **Streaming**: AsyncGenerator + WebSocket (Socket.io)
- **Database**: PostgreSQL + pgVector (RAG), Neo4j (知识图谱), Redis (缓存)
- **Frontend**: React 18 + Zustand + Socket.io-client