# AI Agent - 智能助手系统

基于 LangGraph + FastAPI 的智能对话助手，支持多模型切换、RAG 检索、联网搜索、子图系统等。

---

## 目录

- [核心功能](#核心功能)
- [快速开始](#快速开始)
- [项目结构](#项目结构)
- [API 接口](#api-接口)
- [配置说明](#配置说明)

---

## 核心功能

### 对话能力

| 功能 | 说明 |
|------|------|
| 智能对话 | 多轮对话，自动记忆上下文 |
| 多模型切换 | 前端可选择不同 LLM |
| 流式响应 | SSE 流式输出，打字机效果 |
| 持久化记忆 | PostgreSQL 存储对话历史 |

### 工具系统

| 工具 | 说明 |
|------|------|
| RAG 检索 | 知识库检索，带置信度评估 |
| 联网搜索 | DuckDuckGo 免费搜索 |
| 通讯录 | 联系人管理、邮件处理 |
| 词典 | 翻译、术语提取、生词本 |
| 资讯分析 | 新闻检索、关键词提取 |

### 技术特性

- **模块化架构**：清晰的代码分层，易于扩展
- **模型降级**：多模型自动降级，保证高可用
- **子图系统**：独立的工作流模块，按需调用
- **格式化输出**：统一的 Markdown 格式化，支持模板

---

## 快速开始

### 环境要求

- Python 3.10+
- PostgreSQL（远程或本地）
- Qdrant 向量数据库（远程或本地）

### 安装依赖

```bash
cd backend
pip install -r requirements.txt
```

### 配置环境变量

```bash
cp .env.example .env
# 编辑 .env 填写必要的配置
```

### 启动服务

```bash
cd backend
python -m app.backend
# 服务运行在 http://localhost:8079
```

---

## 项目结构

```
backend/app/
├── agent/                    # Agent 服务层
│   ├── agent_service.py     # 主服务
│   ├── service_config.py    # 配置构建
│   ├── stream_handler.py    # 流式处理
│   ├── stream_context.py    # 流式上下文
│   ├── history.py           # 历史查询
│   └── prompts.py           # 提示词
│
├── main_graph/              # 主图（LangGraph 工作流）
│   ├── main_graph_builder.py # 图构建器
│   ├── state.py             # 状态定义
│   └── nodes/               # 节点实现
│       ├── agent.py         # 推理节点
│       ├── tools.py         # 工具执行
│       ├── finalize.py      # 后处理
│       ├── memory_trigger.py # 记忆触发
│       ├── retrieve_memory.py # 记忆检索
│       └── summarize.py     # 记忆摘要
│
├── tools/                   # 工具定义
│   ├── rag.py              # RAG 检索工具
│   ├── web_search.py       # 联网搜索工具
│   └── subgraph.py          # 子图调用工具
│
├── subgraphs/              # 子图模块
│   ├── contact/            # 通讯录子图
│   ├── dictionary/         # 词典子图
│   └── news_analysis/      # 资讯分析子图
│
├── core/                   # 核心工具
│   ├── formatter.py        # 格式化工具
│   ├── stream_finalizer.py # 流式格式化
│   ├── web_search.py       # 搜索工具类
│   ├── visualization.py    # 可视化图表
│   └── human_review.py     # 人工审核
│
├── rag/                    # RAG 检索系统
│   ├── pipeline.py         # 检索流水线
│   ├── retriever.py        # 检索器
│   ├── rerank.py           # 重排
│   ├── fusion.py           # 结果融合
│   └── query_transform.py  # 查询改写
│
├── model_services/         # 模型服务层
│   ├── chat_services.py    # 对话服务
│   ├── embedding_services.py # 嵌入服务
│   └── rerank_services.py  # 重排服务
│
├── memory/                 # 记忆系统
│   └── mem0_client.py      # Mem0 客户端
│
├── templates/               # 输出模板
│   ├── error_notification.md # 错误提示
│   ├── web_search_result.md # 搜索结果
│   ├── knowledge_summary.md # 知识总结
│   └── conversation_summary.md # 对话摘要
│
├── middleware/             # 中间件
│   └── response_formatter.py # 响应格式化
│
├── db/                     # 数据库
│   ├── models.py           # 数据模型
│   └── init_db.py          # 初始化
│
├── mcp/                    # MCP 协议
│   ├── mcp_client.py       # MCP 客户端
│   ├── mcp_manager.py      # MCP 管理器
│   └── adapters/            # 适配器
│
├── config.py              # 配置管理
├── logger.py              # 日志工具
└── backend.py             # FastAPI 应用
```

---

## API 接口

### 对话接口

#### 同步对话

```http
POST /chat
Content-Type: application/json

{
    "message": "你好",
    "thread_id": "可选的会话ID",
    "model": "local",
    "user_id": "default_user"
}
```

响应：
```json
{
    "reply": "你好！有什么可以帮助你的？",
    "thread_id": "生成的会话ID",
    "model_used": "local",
    "input_tokens": 100,
    "output_tokens": 50,
    "total_tokens": 150,
    "elapsed_time": 1.23
}
```

#### 流式对话

```http
POST /chat/stream
Content-Type: application/json

{
    "message": "你好",
    "model": "local"
}
```

响应为 SSE 流式数据：
```
data: {"type": "llm_token", "node": "agent", "token": "你"}

data: {"type": "llm_token", "node": "agent", "token": "好"}

data: {"type": "done", "model_used": "local"}

data: [DONE]
```

### 历史接口

```http
GET /threads?user_id=xxx&limit=10
GET /thread/{thread_id}/messages
GET /thread/{thread_id}/summary
```

### 审核接口

```http
GET /reviews/pending
POST /reviews/{review_id}/approve
POST /reviews/{review_id}/reject
```

---

## 配置说明

### 环境变量

| 变量 | 说明 | 示例 |
|------|------|------|
| `DB_URI` | PostgreSQL 连接串 | `postgresql://user:pass@host:5432/db` |
| `QDRANT_URL` | Qdrant 地址 | `http://localhost:6333` |
| `VLLM_BASE_URL` | 本地 LLM 地址 | `http://localhost:8000/v1` |
| `DEEPSEEK_API_KEY` | DeepSeek API Key | `sk-xxx` |
| `ZHIPUAI_API_KEY` | 智谱 API Key | `xxx` |

### 模板定制

输出模板位于 `app/templates/`，可直接编辑 `.md` 文件调整格式：

```markdown
## ⚠️ 操作失败

**错误类型**: {{ error_type }}
**错误详情**: {{ error_message }}

### 💡 建议操作

{{ suggestions }}
```

---

## 格式化输出

项目提供统一的格式化工具：

```python
from backend.app.core import get_formatter

fmt = get_formatter()

# 渲染错误模板
error_out = fmt.render_error(
    error_type="超时",
    error_message="连接超时",
    suggestions=["重试", "切换模型"]
)

# 渲染自定义模板
output = fmt.render("my_template", key="value")

# 流式结束后追加格式化内容
from backend.app.core import create_finalizer
finalizer = create_finalizer()
finalizer.add_table([{"姓名": "张三"}])
append_content = finalizer.build_append()
```