# Backend App - 后端应用目录

本目录包含 AI Agent 系统的所有后端代码，采用模块化设计，层级清晰。

---

## 📁 目录结构

```
app/
├── __init__.py              # 应用初始化
├── backend.py               # FastAPI 主入口，包含 API 端点
├── config.py                # 配置管理
├── logger.py                # 日志工具
│
├── core/                    # ⭐ 核心模块 - 基类和通用工具
│   ├── __init__.py
│   ├── state_base.py        # 子图状态基类
│   ├── intent.py            # 意图理解（React 模式）
│   ├── intent_classifier.py # 意图分类器
│   ├── formatter.py         # 格式化输出工具
│   └── human_review.py      # 人工审核节点
│
├── agent/                   # ⭐ Agent 服务层
│   ├── __init__.py
│   ├── agent_service.py     # AIAgentService - 核心服务类
│   ├── history.py           # 历史查询服务
│   └── prompts.py           # 提示词模板
│
├── main_graph/              # ⭐ 主图 - LangGraph 主流程
│   ├── __init__.py
│   ├── state.py             # 主图状态定义（MainGraphState）
│   ├── graph.py             # 图组件重导出
│   ├── config.py            # 流配置
│   │
│   ├── nodes/               # 主图节点
│   │   ├── __init__.py
│   │   ├── react_nodes.py   # React 模式节点（推理、路由）
│   │   ├── llm_call.py      # LLM 调用节点
│   │   ├── retrieve_memory.py # 记忆检索节点
│   │   ├── memory_trigger.py # 记忆触发节点
│   │   ├── summarize.py     # 记忆摘要节点
│   │   ├── finalize.py      # 最终处理节点
│   │   ├── rag_nodes.py     # RAG 相关节点
│   │   ├── web_search_node.py # 联网搜索节点
│   │   └── error_handling_node.py # 错误处理节点
│   │
│   ├── tools/               # 主图工具
│   │   ├── __init__.py
│   │   ├── graph_tools.py   # 图工具定义
│   │   └── subgraph_tools.py # 子图调用工具
│   │
│   └── utils/               # 主图工具函数
│       ├── __init__.py
│       ├── main_graph_builder.py # 主图构建器
│       ├── retry_utils.py   # 重试工具
│       ├── rag_initializer.py # RAG 初始化工具
│       └── visualize_graph.py # 图可视化工具
│
├── subgraphs/               # ⭐ 子图模块
│   ├── __init__.py
│   │
│   ├── contact/             # 通讯录子图
│   │   ├── __init__.py
│   │   ├── state.py         # 状态定义
│   │   ├── nodes.py         # 节点实现
│   │   ├── graph.py         # 图构建
│   │   └── api_client.py    # API 客户端
│   │
│   ├── dictionary/          # 词典子图
│   │   ├── __init__.py
│   │   ├── state.py         # 状态定义
│   │   ├── nodes.py         # 节点实现
│   │   ├── graph.py         # 图构建
│   │   └── api_client.py    # API 客户端
│   │
│   └── news_analysis/       # 资讯分析子图
│       ├── __init__.py
│       ├── state.py         # 状态定义
│       ├── nodes.py         # 节点实现
│       ├── graph.py         # 图构建
│       └── api_client.py    # API 客户端
│
├── model_services/          # 模型服务层
│   ├── __init__.py
│   ├── README.md            # 模型服务文档
│   ├── base.py              # 基类：BaseServiceProvider, FallbackServiceChain
│   ├── chat_services.py     # 生成式大模型服务
│   ├── embedding_services.py # 嵌入模型服务
│   └── rerank_services.py   # 重排序服务
│
├── rag/                     # RAG 模块
│   ├── __init__.py
│   ├── retriever.py         # 检索器
│   ├── rerank.py            # 重排序业务逻辑
│   ├── query_transform.py   # 查询转换
│   ├── pipeline.py          # RAG 流水线
│   ├── fusion.py            # RAG-Fusion
│   ├── tools.py             # RAG 工具
│   └── evaluate.py          # RAG 评估
│
├── memory/                  # 记忆模块
│   ├── __init__.py
│   └── mem0_client.py       # Mem0 客户端封装
│
├── db/                      # 数据库模块
│   ├── __init__.py
│   ├── base.py              # 数据库基类
│   ├── models.py            # 数据模型
│   └── init_db.py           # 数据库初始化
│
└── utils/                   # 工具模块
    ├── __init__.py
    └── logging.py           # 日志工具
```

---

## 📖 模块详解

### 1. `core/` - 核心模块

这是整个系统的基础，被主图和所有子图共享：

| 文件 | 说明 |
|------|------|
| `state_base.py` | 所有子图状态的基类，定义通用字段和方法 |
| `intent.py` | React 模式的意图理解，用于解析用户意图 |
| `intent_classifier.py` | 意图分类器，用于混合路由 |
| `formatter.py` | 输出格式化工具，用于统一美化子图输出 |
| `human_review.py` | 人工审核节点，需要人工确认的操作 |

---

### 2. `agent/` - Agent 服务层

对外提供服务的核心层：

| 文件 | 说明 |
|------|------|
| `agent_service.py` | `AIAgentService` 类，管理模型、图、工具，提供 `process_message` 和 `process_message_stream` 方法 |
| `history.py` | 历史对话查询服务 |
| `prompts.py` | 系统提示词模板 |

---

### 3. `main_graph/` - 主图（React 模式）

LangGraph 的主流程，采用 React 模式（Reasoning + Acting）：

| 目录/文件 | 说明 |
|----------|------|
| `state.py` | 主图状态定义（MainGraphState），整合所有旧状态字段 |
| `graph.py` | StateGraph, START, END 等组件重导出 |
| `config.py` | 流写入器配置 |
| `nodes/` | 所有节点实现 |
| `tools/` | 图的工具定义 |
| `utils/main_graph_builder.py` | 主图构建器 - 构建完整的 React 模式图 |

#### 🔄 主图节点说明

| 节点 | 类型 | 说明 |
|------|------|------|
| `retrieve_memory` | 记忆 | 从 Mem0 检索相关长期记忆 |
| `memory_trigger` | 记忆 | 检测记忆指令，主动触发存储 |
| `init_state` | React | 初始化状态 |
| `react_reason` | React | 推理节点，理解意图并决策下一步 |
| `rag_retrieve` | 工具 | RAG 检索 |
| `web_search` | 工具 | 联网搜索 |
| `contact_subgraph` | 子图 | 调用通讯录子图 |
| `dictionary_subgraph` | 子图 | 调用词典子图 |
| `news_analysis_subgraph` | 子图 | 调用资讯分析子图 |
| `handle_error` | 错误 | 错误处理和重试 |
| `llm_call` | 模型 | 调用大模型生成回复 |
| `summarize` | 记忆 | 对话总结，提交 Mem0 存储 |
| `finalize` | 完成 | 发送完成事件 |

---

### 4. `subgraphs/` - 子图模块

三个独立的子图，每个子图都有完整的 `state.py`、`nodes.py`、`graph.py`：

| 子图 | 功能 |
|------|------|
| `contact/` | 通讯录管理：CRUD、邮件处理、智能嗅探 |
| `dictionary/` | 词典：查词、翻译、生词本、专业术语提取 |
| `news_analysis/` | 资讯分析：获取资讯、内容分析、格式化展示 |

---

### 5. `model_services/` - 模型服务层

统一的模型服务接口，支持自动降级：

| 文件 | 说明 |
|------|------|
| `base.py` | `BaseServiceProvider`（基类）、`FallbackServiceChain`（降级链） |
| `chat_services.py` | 生成式大模型服务（智谱、DeepSeek、本地） |
| `embedding_services.py` | 嵌入模型服务 |
| `rerank_services.py` | 重排序服务 |

---

### 6. `rag/` - RAG 模块

知识库检索相关：

| 文件 | 说明 |
|------|------|
| `retriever.py` | 向量检索器 |
| `rerank.py` | 重排序业务逻辑 |
| `pipeline.py` | RAG 流水线 |
| `fusion.py` | RAG-Fusion 多路召回融合 |
| `tools.py` | 封装为 LangChain Tool 的 RAG 工具 |
| `evaluate.py` | RAG 评估工具 |

---

## 🔄 完整流程图

```
START
  ↓
retrieve_memory (从Mem0检索长期记忆)
  ↓
memory_trigger (记忆触发器 - 检测记忆指令)
  ↓
init_state (初始化状态)
  ↓
react_reason (推理节点 - 理解意图并决策) ←───────────┐
  ↓                                                       │
route_by_reasoning (条件路由)                             │
  ↓                                                       │
┌─────────────────────────────────────────────────┐       │
│ 分支选择：                                      │       │
│  ├─ rag_retrieve →───────────────────────────┐ │       │
│  ├─ web_search →─────────────────────────────┤ │       │
│  ├─ contact_subgraph →───────────────────────┤ │       │
│  ├─ dictionary_subgraph →────────────────────┤ │       │
│  ├─ news_analysis_subgraph →─────────────────┤ │       │
│  ├─ handle_error →───────────────────────────┤ │       │
│  └─ llm_call →────────────────────────────────┘ │       │
└─────────────────────────────────────────────────┘       │
                          ↓                               │
                    (回到 react_reason) ──────────────────┘
                          ↓
                    (无工具调用)
                          ↓
                    llm_call (直接生成回复)
                          ↓
┌─────────────────────────────────────────────────┐
│ 检查：需要总结吗？(turns_since_last_summary >=5?) │
│  ├─ 是 → summarize (提交Mem0存储)               │
│  └─ 否 → (跳过)                                 │
└─────────────────────────────────────────────────┘
                          ↓
                    finalize (发送完成事件)
                          ↓
                    END
```

---

## 📊 数据流

```
用户请求 
  └─> backend.py (FastAPI)
       └─> agent/agent_service.py (AIAgentService)
            ├─> model_services/ (获取模型 - 支持降级链)
            ├─> main_graph/utils/main_graph_builder.py (构建主图)
            └─> graph.astream() (执行图流)
                 ├─> nodes/ (执行节点)
                 ├─> tools/ (调用工具)
                 ├─> rag/ (RAG 检索)
                 ├─> subgraphs/ (可选：调用子图)
                 └─> memory/ (记忆检索和存储)
```

---

## 🚀 启动方式

FastAPI 应用入口是 `backend.py`，可以通过以下方式启动：

```bash
# 方式 1：直接运行
cd backend && python -m app.backend

# 方式 2：Uvicorn
uvicorn app.backend:app --reload --host 0.0.0.0 --port 8079

# 方式 3：Docker
docker compose up
```

---

## 📝 状态系统

### MainGraphState

所有节点统一使用 `MainGraphState`（dataclass），包含以下字段：

```python
@dataclass
class MainGraphState:
    # 消息和记忆
    messages: Annotated[Sequence[BaseMessage], add_messages]
    llm_calls: int
    memory_context: str
    system_prompt: str
    turns_since_last_summary: int
    
    # LLM 输出
    last_token_usage: Dict[str, Any]
    last_elapsed_time: float
    
    # 用户信息
    user_query: str
    user_id: str
    
    # React 推理
    reasoning_step: int
    max_steps: int
    last_action: str
    reasoning_history: List[Dict[str, Any]]
    
    # RAG 相关
    rag_context: str
    rag_retrieved: bool
    rag_docs: List[Dict[str, Any]]
    
    # 搜索相关
    web_search_results: List[str]
    
    # 错误处理
    errors: List[ErrorRecord]
    current_error: Optional[ErrorRecord]
    retry_action: Optional[str]
    
    # 子图结果
    news_result: Optional[Dict[str, Any]]
    dictionary_result: Optional[Dict[str, Any]]
    contact_result: Optional[Dict[str, Any]]
    
    # 执行状态
    current_action: CurrentAction
    current_phase: str
    error_message: str
    final_result: str
    success: bool
    
    # 元数据
    start_time: Optional[str]
    end_time: Optional[str]
    debug_info: Dict[str, Any]
```