# long-ai-agent

**Repository Path**: ArashiCode-coder/long-ai-agent

## Basic Information

- **Project Name**: long-ai-agent
- **Description**: 基于 Spring Boot 3 + Spring AI 构建的企业级 AI 智能体平台，支持多轮对话、RAG 知识库检索、Tool Calling 工具调用、MCP 集成，采用 ReAct 模式实现自主规划。
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 5
- **Forks**: 2
- **Created**: 2026-01-03
- **Last Updated**: 2026-03-26

## Categories & Tags

**Categories**: Uncategorized

**Tags**: SpringBoot, SpringAI, RAG, ToolCalling, MCP

## README

# Long AI Agent

基于 Spring Boot + Vue3 的 AI 智能助手应用平台。

## 项目简介

Long AI Agent 是一个功能完整的 AI 智能助手平台，集成了对话记忆、RAG 知识库检索、工具调用等功能。

### 核心特性

- **AI 对话**: 支持多轮对话记忆，基于 PostgreSQL 持久化
- **RAG 知识库**: 基于 pgvector 的向量检索，支持本地文档问答
- **工具调用**: 集成文件操作、网页抓取、终端命令等多种工具
- **安全增强**: 命令白名单、文件校验、URL 验证、大小限制
- **性能优化**: HikariCP 连接池、批量操作、并发控制
- **流式响应**: 基于 SSE 的实时流式对话

## 技术栈

### 后端
- **框架**: Spring Boot 3.2.5 + Java 17
- **AI**: Spring AI + DashScope (通义千问)
- **数据库**: PostgreSQL + pgvector (向量检索)
- **ORM**: MyBatis Plus 3.5.15
- **序列化**: Kryo 5.6.2 (高性能)

### 前端
- **框架**: Vue 3.4.0 + Vite 5.0.0
- **路由**: Vue Router 4.2.5
- **HTTP**: Axios 1.6.0
- **实时通信**: SSE (Server-Sent Events)

## 项目结构

```
long-ai-agent/
├── src/main/java/com/xlongma/aiagent/
│   ├── controller/          # API 接口
│   ├── agent/               # AI Agent 实现 (BaseAgent, ToolCallAgent, LongAgent)
│   ├── app/                 # 应用层 (GeneralApp)
│   ├── tools/               # Agent 工具集
│   ├── rag/                 # RAG 向量检索
│   ├── chatmemory/          # 对话记忆 (Database/File)
│   ├── config/              # 配置类 (AppConfig, CorsConfig)
│   ├── exception/           # 异常处理
│   └── advisor/             # AI Advisor (ReReading)
├── src/main/resources/
│   ├── application.yml      # 主配置
│   ├── application-dev.yml  # 开发环境配置
│   └── document/            # RAG 知识库文档 (9个 Markdown 文件)
├── long-ai-agent-web/       # Vue3 前端
│   └── src/
│       ├── views/           # 页面组件
│       ├── router/          # 路由配置
│       └── styles/          # 样式文件
└── sql/
    └── create_table.sql     # 数据库建表脚本
```

## 快速开始

### 前置要求

- Java 17+
- PostgreSQL 12+
- Node.js 16+
- Maven 3.6+

### 1. 数据库准备

```sql
-- 创建数据库
CREATE DATABASE long_ai_agent;

-- 启用 pgvector 扩展
CREATE EXTENSION IF NOT EXISTS vector;

-- 执行建表脚本
\i sql/create_table.sql
```

### 2. 后端启动

1. 配置环境变量：
```bash
export PG_USERNAME=postgres
export PG_PASSWORD=your_password
export AI_DASHSCOPE_API_KEY=your_dashscope_key
```

2. 启动后端：
```bash
./mvnw spring-boot:run
```

后端运行在 `http://localhost:8123`

### 3. 前端启动

```bash
cd long-ai-agent-web
npm install
npm run dev
```

前端运行在 `http://localhost:3000`。

## API 接口

| 接口 | 方法 | 参数 | 说明 |
|-----|-----|-----|-----|
| `/api/health` | GET | - | 健康检查 |
| `/api/ai/general_app/chat/sync` | GET | message, chatId | AI 同步对话（支持对话记忆） |
| `/api/ai/general_app/chat/sse/emitter` | GET | message, chatId | AI 流式对话（SSE，支持对话记忆） |
| `/api/ai/agent/chat` | GET | message | AI 智能体对话（SSE，支持工具调用） |

### 扩展功能（GeneralApp 提供）

GeneralApp 还提供以下功能方法，可根据需要在 Controller 中暴露：

- `doChatWithRag(message, chatId)` - RAG 知识库问答（基于 pgvector 检索）
- `doChatWithReport(message, chatId)` - 结构化报告生成
- `doChatWithTools(message, chatId)` - 工具调用对话
- `doChatWithMcp(message, chatId)` - MCP 协议调用

## 核心功能

### 1. 对话记忆持久化

- **实现方式**: PostgreSQL 数据库存储
- **表结构**: `chat_message` (id, conversation_id, message_type, content, create_time)
- **特性**: 支持多轮对话、按会话 ID 管理、批量插入优化

### 2. RAG 知识库检索

- **向量数据库**: pgvector (1024 维向量)
- **索引类型**: HNSW (高效近似最近邻搜索)
- **距离算法**: COSINE_DISTANCE (余弦距离)
- **文档来源**: `src/main/resources/document/**/*.md` (9 个文档)
- **检索配置**: 相似度阈值 0.5, Top-K 3

### 3. 工具集成

| 工具 | 功能 | 安全限制 |
|-----|-----|---------|
| FileOperationTool | 文件读写 | 文件名校验、路径遍历防护 |
| TerminalOperationTool | 终端命令 | 白名单机制、10秒超时 |
| WebScrapingTool | 网页抓取 | HTTPS only、1MB 限制 |
| ResourceDownloadTool | 资源下载 | HTTPS only、50MB 限制 |
| PDFGenerationTool | PDF 生成 | 支持中文字体 |
| TerminateTool | 终止对话 | - |

注：WebSearchTool（网页搜索）已实现但默认未启用，需配置 SEARCH_API_KEY 后在 ToolRegistration 中取消注释。

### 4. 安全机制

- ✅ 终端命令白名单 (仅允许安全查询命令)
- ✅ 文件名安全校验 (防止路径遍历)
- ✅ URL 协议验证 (仅 HTTP/HTTPS)
- ✅ 文件大小限制 (下载 50MB, 网页 1MB)
- ✅ 命令执行超时 (10 秒)

## 配置说明

### 数据库配置 (application-dev.yml)

```yaml
spring:
  datasource:
    url: jdbc:postgresql://localhost:5432/long_ai_agent
    username: ${PG_USERNAME:postgres}
    password: ${PG_PASSWORD}
    hikari:
      minimum-idle: 5
      maximum-pool-size: 20
      connection-timeout: 30000
```

### 向量库配置

```yaml
spring:
  ai:
    vectorstore:
      pgvector:
        index-type: HNSW
        distance-type: COSINE_DISTANCE
        dimensions: 1024
        initialize-schema: true
```

### AI 模型配置

```yaml
spring:
  ai:
    dashscope:
      api-key: ${AI_DASHSCOPE_API_KEY}
      chat:
        options:
          model: qwen-plus
```

## 开发说明

### 添加新工具

1. 在 `tools` 包下创建工具类
2. 使用 `@Tool` 注解标注方法
3. 在 `ToolRegistration` 中注册工具

### 添加知识库文档

1. 将 Markdown 文件放入 `src/main/resources/document/` 目录
2. 重启应用自动加载到向量库

### 自定义配置

所有配置常量统一在 `AppConfig.java` 中管理：
- SSE 超时时间
- 文件大小限制
- 网络请求超时
- RAG 检索参数

## 性能优化

- ✅ HikariCP 连接池 (最小 5, 最大 20)
- ✅ 批量插入 (聊天消息)
- ✅ 批量加载 (向量库, 批次 10)
- ✅ ReadWriteLock 并发控制
- ✅ Kryo 高性能序列化

## License

MIT