# JchatMind

**Repository Path**: leke_code/JchatMind

## Basic Information

- **Project Name**: JchatMind
- **Description**: JChatMind 是一个基于 Spring AI 框架构建的智能 AI Agent 系统。与传统聊天机器人不同，它具备自主决策、工具调用和知识库检索能力。核心特点是实现了 Think-Execute 循环机制，AI 能够理解复杂任务、规划执行步骤、调用外部工具，并基于 RAG 技术从知识库检索信息，完成多步骤的复杂任务。
- **Primary Language**: Java
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2026-04-16
- **Last Updated**: 2026-04-16

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# AI Demo - 智能对话系统

一个基于 Spring Boot + React + PostgreSQL 的 AI 智能对话系统，支持多轮对话、工具调用和 Agent-Loop 机制。

## 📋 项目简介

本项目是一个功能完整的 AI 智能对话系统，实现了以下核心功能：

- **多轮对话**：支持上下文保持的连续对话
- **工具调用**：集成日期、天气、城市查询、数据库等工具
- **Agent-Loop**：自主决策、任务规划、执行和结果评估
- **SSE 实时推送**：使用 Server-Sentenced Events 实现实时消息推送
- **智能体管理**：支持创建、删除和切换不同的 AI 智能体
- **会话管理**：每个智能体可以有独立的对话会话

### 技术栈

| 组件 | 技术 | 版本 |
|------|------|------|
| **后端框架** | Spring Boot | 3.5.8 |
| **后端语言** | Java | 17 |
| **AI 框架** | Spring AI | 1.1.0 |
| **数据库** | PostgreSQL | 15+ |
| **ORM** | MyBatis | 3.x |
| **前端框架** | React | 19.2.4 |
| **前端语言** | TypeScript | 5.9.3 |
| **构建工具** | Vite | 8.0.1 |
| **样式框架** | Tailwind CSS | 4.2.2 |
| **HTTP 客户端** | Axios | 1.13.6 |

## 📦 环境要求

### 必需软件

| 软件 | 最低版本 | 推荐版本 | 用途 |
|------|---------|---------|------|
| **Java** | 17 | 17 LTS | 后端运行环境 |
| **Maven** | 3.6+ | 3.9.x | 后端依赖管理 |
| **Node.js** | 18 | 20 LTS | 前端运行环境 |
| **npm** | 9+ | 10.x | 前端依赖管理 |
| **PostgreSQL** | 15 | 15+ | 数据库服务 |

### 依赖管理工具

- **后端**：Maven（通过 `mvnw` 脚本）
- **前端**：npm（通过 `package.json`）

### 系统要求

- **操作系统**：Linux、macOS、Windows
- **内存**：至少 4GB RAM（推荐 8GB）
- **磁盘空间**：至少 2GB 可用空间
- **网络**：需要访问 AI API（DeepSeek、智谱 AI）

## 🚀 快速开始

### 1. 克隆项目

```bash
# 使用 HTTPS 克隆
git clone https://github.com/your-username/ai-demo.git
cd ai-demo

# 或使用 SSH 克隆
git clone git@github.com:your-username/ai-demo.git
cd ai-demo
```

### 2. 配置数据库

#### 方式一：使用本地 PostgreSQL

```bash
# 1. 安装 PostgreSQL（如果尚未安装）

# macOS
brew install postgresql@15
brew services start postgresql@15

# Ubuntu/Debian
sudo apt update
sudo apt install -y postgresql-15 postgresql-client
sudo systemctl start postgresql

# 2. 创建数据库
psql -U postgres -c "CREATE DATABASE jchatmind;"

# 3. 创建用户（可选）
psql -U postgres -c "CREATE USER ai_user WITH PASSWORD 'your_password';"
psql -U postgres -c "GRANT ALL PRIVILEGES ON DATABASE jchatmind TO ai_user;"
```

#### 方式二：使用 Docker（推荐）

```bash
# 使用 Docker Compose 启动 PostgreSQL
docker run -d \
  --name ai-demo-postgres \
  -e POSTGRES_DB=jchatmind \
  -e POSTGRES_USER=postgres \
  -e POSTGRES_PASSWORD=postgres \
  -p 5432:5432 \
  postgres:15-alpine
```

### 3. 配置 AI API 密钥

#### 方式一：直接修改配置文件

编辑 `src/main/resources/application.yaml`：

```yaml
spring:
  ai:
    deepseek:
      api-key: "your-deepseek-api-key"  # 替换为你的 DeepSeek API Key
    zhipuai:
      api-key: "your-zhipuai-api-key"  # 替换为你的智谱 AI API Key
```

#### 方式二：使用环境变量（推荐，更安全）

```bash
# Linux/macOS
export DEEPSEEK_API_KEY="your-deepseek-api-key"
export ZHIPUAI_API_KEY="your-zhipuai-api-key"

# Windows (PowerShell)
$env:DEEPSEEK_API_KEY="your-deepseek-api-key"
$env:ZHIPUAI_API_KEY="your-zhipuai-api-key"
```

#### 获取 API Key

- **DeepSeek**：https://platform.deepseek.com/
- **智谱 AI**：https://open.bigmodel.cn/

### 4. 安装依赖并启动项目

#### 后端启动

```bash
# 1. 进入项目根目录
cd ai-demo

# 2. 安装后端依赖（首次运行）
./mvnw clean install

# 3. 启动后端服务
./mvnw spring-boot:run

# 或使用 Maven 命令（如果 mvnw 不可用）
mvn spring-boot:run
```

后端服务将在 `http://localhost:8080` 启动。

#### 前端启动

```bash
# 1. 进入前端目录
cd frontend

# 2. 安装前端依赖（首次运行）
npm install

# 3. 启动前端开发服务器
npm run dev
```

前端应用将在 `http://localhost:5173` 启动。

### 5. 访问应用

打开浏览器访问：http://localhost:5173

首次访问时，界面会显示"欢迎使用 AI 助手"，点击左侧的 `+` 按钮创建一个智能体开始对话。

## 📝 详细安装步骤

### 后端完整安装流程

#### 步骤 1：验证 Java 环境

```bash
# 检查 Java 版本
java -version

# 如果未安装或版本过低，请安装 Java 17

# macOS
brew install openjdk@17

# Ubuntu/Debian
sudo apt update
sudo apt install -y openjdk-17-jre

# Windows
# 下载并安装 Oracle JDK 17
# https://www.oracle.com/java/technologies/downloads/
```

#### 步骤 2：验证 Maven 环境

```bash
# 检查 Maven 版本
mvn -version

# 如果未安装，请安装 Maven

# macOS
brew install maven

# Ubuntu/Debian
sudo apt install -y maven

# Windows
# 下载并解压 Maven
# https://maven.apache.org/download.cgi
```

#### 步骤 3：配置数据库连接

编辑 `src/main/resources/application.yaml`：

```yaml
spring:
  datasource:
    url: jdbc:postgresql://localhost:5432/jchatmind
    username: postgres
    password: postgres  # 根据实际配置修改
    driver-class-name: org.postgresql.Driver
```

#### 步骤 4：配置 CORS（如果需要跨域访问）

编辑 `src/main/resources/application.yaml`：

```yaml
spring:
  web:
    cors:
      allowed-origins: "http://localhost:5173"  # 前端地址
      allowed-methods: "*"
      allowed-headers: "*"
      allow-credentials: true
```

#### 步骤 5：编译并运行后端

```bash
# 清理并编译
./mvnw clean package

# 跳过测试直接运行
./mvnw spring-boot:run -DskipTests

# 或指定配置文件运行
./mvnw spring-boot:run -Dspring-boot.run.profiles=prod
```

### 前端完整安装流程

#### 步骤 1：验证 Node.js 环境

```bash
# 检查 Node.js 版本
node -version

# 检查 npm 版本
npm -version

# 如果未安装或版本过低，请安装 Node.js 18+

# macOS
brew install node

# Ubuntu/Debian
curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
sudo apt install -y nodejs

# Windows
# 下载并安装 Node.js LTS
# https://nodejs.org/
```

#### 步骤 2：安装前端依赖

```bash
# 进入前端目录
cd frontend

# 安装依赖（使用 npm）
npm install

# 或使用 yarn（如果已安装）
yarn install

# 或使用 pnpm（更快）
pnpm install
```

#### 步骤 3：配置环境变量（可选）

创建 `.env.development` 文件：

```bash
# frontend/.env.development
VITE_API_BASE_URL=http://localhost:8080/api
VITE_SSE_BASE_URL=http://localhost:8080/sse
```

#### 步骤 4：启动前端开发服务器

```bash
# 开发模式（支持热更新）
npm run dev

# 预览构建结果
npm run preview

# 类型检查
npm run type-check
```

## 🔧 运行命令说明

### 开发环境

#### 后端

```bash
# 启动开发服务器（默认端口 8080）
./mvnw spring-boot:run

# 指定端口启动
./mvnw spring-boot:run -Dserver.port=8081

# 跳过测试
./mvnw spring-boot:run -DskipTests

# 指定配置文件
./mvnw spring-boot:run -Dspring-boot.run.profiles=dev
```

#### 前端

```bash
# 启动开发服务器（默认端口 5173）
npm run dev

# 指定端口启动
npm run dev -- --port 3000

# 暴露到网络
npm run dev -- --host
```

### 生产环境

#### 后端构建

```bash
# 清理并打包
./mvnw clean package -DskipTests

# 打包为 JAR 文件
./mvnw clean package

# 生成可执行 JAR（包含依赖）
./mvnw clean package spring-boot:repackage
```

构建产物位于 `target/ai-demo-0.0.1-SNAPSHOT.jar`

#### 前端构建

```bash
# 进入前端目录
cd frontend

# 构建生产版本
npm run build

# 构建产物位于 frontend/dist/
```

#### 生产环境运行

```bash
# 后端（使用生产配置）
java -jar target/ai-demo-0.0.1-SNAPSHOT.jar --spring.profiles.active=prod

# 前端（使用 Nginx 等静态文件服务器）
# 将 frontend/dist/ 目录部署到 Web 服务器
```

## 🧪 项目结构

```
ai-demo/
├── src/main/java/top/rose/aidemo/
│   ├── agent/                 # AI 智能体核心逻辑
│   │   ├── tools/           # 工具实现
│   │   ├── JChatMind.java    # Agent-Loop 主类
│   │   └── ...
│   ├── config/                # 配置类
│   ├── controller/            # REST API 控制器
│   ├── service/               # 业务逻辑层
│   ├── mapper/                # MyBatis 数据访问层
│   └── model/                 # 数据模型
├── src/main/resources/
│   ├── mapper/                # MyBatis XML 映射文件
│   └── application.yaml       # 应用配置
├── frontend/                  # 前端应用
│   ├── src/
│   │   ├── components/       # React 组件
│   │   ├── services/         # API 服务层
│   │   ├── hooks/            # 自定义 Hooks
│   │   └── types/            # TypeScript 类型定义
│   ├── public/               # 静态资源
│   └── package.json          # 前端依赖配置
├── pom.xml                   # Maven 配置文件
└── README.md                 # 项目说明文档
```

## 🔧 配置说明

### 后端配置文件

`src/main/resources/application.yaml` 主要配置项：

```yaml
spring:
  application:
    name: ai-demo
  
  # 数据库配置
  datasource:
    url: jdbc:postgresql://localhost:5432/jchatmind
    username: postgres
    password: postgres
    driver-class-name: org.postgresql.Driver
  
  # AI 模型配置
  ai:
    deepseek:
      api-key: ${DEEPSEEK_API_KEY}
      base-url: https://api.deepseek.com
      chat:
        options:
          model: deepseek-chat
    zhipuai:
      api-key: ${ZHIPUAI_API_KEY}
      base-url: https://open.bigmodel.cn/api/paas
      chat:
        options:
          model: glm-4
  
  # CORS 配置
  web:
    cors:
      allowed-origins: "http://localhost:5173"
      allowed-methods: "*"
      allowed-headers: "*"
      allow-credentials: true

# MyBatis 配置
mybatis:
  type-aliases-package: top.rose.aidemo.model.entity
  mapper-locations: classpath:mapper/*.xml
  type-handlers-package: com.kama.jchatmind.typehandler

# 文档存储路径
document:
  storage:
    base-path: ./data/documents
```

### 前端配置文件

`frontend/package.json` 主要脚本：

```json
{
  "scripts": {
    "dev": "vite",
    "build": "tsc -b && vite build",
    "preview": "vite preview",
    "lint": "eslint ."
  }
}
```

## 🐛 常见问题及解决方法

### 问题 1：端口被占用

**错误信息**：
```
Web server failed to start. Port 8080 was already in use
```

**解决方法**：

```bash
# 查找占用端口的进程
lsof -ti:8080

# 终止进程
kill -9 <PID>

# 或修改配置文件使用其他端口
# application.yaml
server:
  port: 8081
```

### 问题 2：数据库连接失败

**错误信息**：
```
Connection refused: localhost:5432
FATAL: password authentication failed for user "postgres"
```

**解决方法**：

```bash
# 1. 检查 PostgreSQL 是否运行
brew services list  # macOS
systemctl status postgresql  # Linux

# 2. 检查端口是否开放
netstat -an | grep 5432

# 3. 验证用户名和密码
psql -U postgres -d jchatmind

# 4. 检查防火墙设置
sudo ufw status  # Linux
```

### 问题 3：API 密钥无效

**错误信息**：
```
401 Unauthorized: Invalid API key
```

**解决方法**：

1. 检查 API Key 是否正确
2. 确认 API Key 是否有足够的额度
3. 检查网络连接是否正常
4. 查看后端日志获取详细错误信息

### 问题 4：前端无法连接后端

**错误信息**：
```
Network Error
AxiosError: Network Error
```

**解决方法**：

```bash
# 1. 检查后端是否运行
curl http://localhost:8080/actuator/health

# 2. 检查 CORS 配置
# 确认 application.yaml 中的 allowed-origins 包含前端地址

# 3. 检查防火墙设置
# 确保后端端口（8080）未被防火墙阻止

# 4. 查看浏览器控制台错误
# F12 打开开发者工具查看详细错误
```

### 问题 5：依赖安装失败

**错误信息**：
```
npm ERR! code ERESOLVE
```

**解决方法**：

```bash
# 1. 清除 npm 缓存
npm cache clean --force

# 2. 删除 node_modules 重新安装
rm -rf node_modules package-lock.json
npm install

# 3. 使用国内镜像源
npm config set registry https://registry.npmmirror.com

# 4. 使用其他包管理器
npm install -g pnpm
pnpm install
```

### 问题 6：Maven 构建失败

**错误信息**：
```
[ERROR] Failed to execute goal on project ai-demo: Could not resolve dependencies
```

**解决方法**：

```bash
# 1. 清理 Maven 缓存
./mvnw clean

# 2. 删除本地仓库重新下载
rm -rf ~/.m2/repository

# 3. 使用国内镜像源
# 编辑 ~/.m2/settings.xml 添加阿里云镜像

# 4. 跳过测试
./mvnw clean package -DskipTests
```

### 问题 7：前端白屏或崩溃

**错误信息**：
```
TypeError: Cannot read properties of null (reading 'toolCalls')
```

**解决方法**：

1. 检查浏览器控制台错误
2. 确认类型定义正确
3. 使用可选链操作符 `?.` 访问可能为 null 的属性
4. 清除浏览器缓存并刷新

### 问题 8：SSE 连接断开

**错误信息**：
```
SSE error: EventSource failed to connect
```

**解决方法**：

1. 检查 SSE 端点是否正确配置
2. 确认 Nginx 代理配置支持长连接
3. 增加前端重连机制
4. 检查网络稳定性

## ⚠️ 注意事项

### 安全注意事项

1. **不要将 API Key 提交到版本控制系统**
   - 使用环境变量或配置文件（已添加到 `.gitignore`）
   - 在生产环境使用密钥管理服务

2. **数据库密码安全**
   - 使用强密码
   - 定期更换密码
   - 限制数据库访问权限

3. **CORS 配置**
   - 生产环境只允许可信的域名
   - 不要使用 `*` 作为允许来源

4. **依赖更新**
   - 定期更新依赖以修复安全漏洞
   - 使用 `npm audit` 和 `mvn dependency-check` 检查

### 性能优化建议

1. **后端优化**
   - 配置数据库连接池
   - 启用查询缓存
   - 使用异步处理

2. **前端优化**
   - 使用生产构建（`npm run build`）
   - 启用代码分割
   - 配置 CDN 加速静态资源

3. **数据库优化**
   - 创建适当的索引
   - 定期清理历史数据
   - 使用连接池

### 开发建议

1. **使用开发工具**
   - 安装 IDE 插件（如 IntelliJ IDEA 的 MyBatis 插件）
   - 使用 ESLint 和 Prettier 保持代码风格一致
   - 配置 Git 钩子进行代码检查

2. **调试技巧**
   - 使用 Spring Boot DevTools 实现热重载
   - 使用浏览器 React DevTools 调试前端
   - 查看后端日志：`tail -f logs/spring.log`

3. **测试策略**
   - 编写单元测试
   - 进行集成测试
   - 使用 Postman 或 curl 测试 API

## 📚 API 文档

### 后端 API 端点

| 方法 | 端点 | 描述 |
|------|------|------|
| GET | `/api/agents` | 获取所有智能体 |
| POST | `/api/agents` | 创建新智能体 |
| DELETE | `/api/agents/{id}` | 删除智能体 |
| GET | `/api/chat-sessions` | 获取所有会话 |
| GET | `/api/chat-sessions/agent/{agentId}` | 获取指定智能体的会话 |
| POST | `/api/chat-sessions` | 创建新会话 |
| GET | `/api/chat-messages/session/{sessionId}` | 获取会话消息 |
| POST | `/api/chat-messages` | 发送消息 |
| GET | `/api/tools` | 获取可用工具 |
| GET | `/sse/connect/{sessionId}` | SSE 连接端点 |

### API 请求示例

#### 创建智能体

```bash
curl -X POST http://localhost:8080/api/agents \
  -H "Content-Type: application/json" \
  -d '{
    "name": "测试助手",
    "description": "一个测试用的AI助手",
    "systemPrompt": "你是一个有用的AI助手",
    "model": "deepseek-chat",
    "allowedTools": ["getDate", "weather"],
    "allowedKbs": [],
    "chatOptions": {
      "messageLength": 20
    }
  }'
```

#### 发送消息

```bash
curl -X POST http://localhost:8080/api/chat-messages \
  -H "Content-Type: application/json" \
  -d '{
    "sessionId": "session-id",
    "agentId": "agent-id",
    "role": "user",
    "content": "今天天气怎么样？"
  }'
```

## 🤝 贡献指南

欢迎贡献代码！请遵循以下步骤：

1. Fork 本仓库
2. 创建特性分支（`git checkout -b feature/AmazingFeature`）
3. 提交更改（`git commit -m 'Add some AmazingFeature'`）
4. 推送到分支（`git push origin feature/AmazingFeature`）
5. 开启 Pull Request

## 📄 许可证

本项目采用 MIT 许可证 - 详见 [LICENSE](LICENSE) 文件

## 👥️ 联系方式

如有问题或建议，请通过以下方式联系：

- 提交 Issue：https://github.com/your-username/ai-demo/issues
- 发送邮件：your-email@example.com

## 🙏 致谢

感谢所有为本项目做出贡献的开发者！

本项目使用了以下开源项目：

- [Spring Boot](https://spring.io/projects/spring-boot)
- [Spring AI](https://spring.io/projects/spring-ai)
- [React](https://reactjs.org/)
- [Vite](https://vitejs.dev/)
- [Tailwind CSS](https://tailwindcss.com/)
- [MyBatis](https://mybatis.org/)
- [PostgreSQL](https://www.postgresql.org/)

---

**祝你使用愉快！** 🎉