# ai-code-helper

**Repository Path**: RicheFactory/ai-code-helper

## Basic Information

- **Project Name**: ai-code-helper
- **Description**: 学习LangChain4j+Java AI开发
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-09-24
- **Last Updated**: 2025-11-27

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# AI Code Helper - AI编程助手

## 项目简介

AI Code Helper 是一个基于 Spring Boot 和 LangChain4j 构建的智能编程辅助工具，集成了大语言模型（通义千问）、RAG检索增强、MCP多上下文协议和安全护栏等先进AI技术，为程序员提供编程学习、求职指导和技术问答服务。

## 核心特性

### 🤖 AI对话能力
- **流式响应**：支持实时流式输出，提供更好的用户体验
- **对话记忆**：基于内存的对话历史管理，支持上下文连续对话
- **系统提示词**：定制化的编程助手人设，专注编程学习和求职指导

### 🛡️ 安全机制
- **输入护栏（Guardrail）**：智能过滤敏感词汇，防止恶意输入
- **安全验证**：请求级别的安全检查机制

### 🔍 RAG检索增强
- **文档加载**：支持本地文档自动加载和向量化
- **智能检索**：基于语义相似度的文档检索
- **向量存储**：内存级向量数据库，支持高效检索

### 🔧 MCP工具调用
- **联网搜索**：集成智谱BigModel的网络搜索能力
- **工具扩展**：支持自定义MCP工具集成

### 📊 可观测性
- **请求监听**：完整的AI请求/响应日志记录
- **错误追踪**：详细的异常信息捕获和记录

### 🎨 现代化前端
- **Vue 3**：采用最新的Vue 3框架
- **实时通信**：基于SSE的实时消息推送
- **Markdown渲染**：支持富文本消息展示
- **响应式设计**：适配多种设备屏幕

## 技术栈

### 后端技术
- **框架**：Spring Boot 3.5.6
- **语言**：Java 21
- **AI框架**：LangChain4j 1.1.0
  - langchain4j-easy-rag：RAG检索增强
  - langchain4j-mcp：MCP协议支持
  - langchain4j-reactor：响应式编程支持
  - langchain4j-community-dashscope：通义千问集成
- **构建工具**：Maven
- **开发工具**：Lombok

### 前端技术
- **框架**：Vue 3.3.4
- **构建工具**：Vite 4.5.0
- **HTTP库**：Axios 1.6.2
- **包管理**：npm

### AI模型
- **主模型**：通义千问（qwen-max）
- **向量模型**：text-embedding-v4
- **MCP服务**：智谱BigModel Web Search

## 项目结构

```
ai-code-helper/
├── src/
│   ├── main/
│   │   ├── java/com/riche/aicodehelper/
│   │   │   ├── ai/                          # AI核心模块
│   │   │   │   ├── guardrail/               # 安全护栏
│   │   │   │   │   └── SafeInputGuardrail.java
│   │   │   │   ├── listener/                # 监听器
│   │   │   │   │   └── MyListener.java
│   │   │   │   ├── mcp/                     # MCP工具配置
│   │   │   │   │   └── McpConfig.java
│   │   │   │   ├── model/                   # 模型配置
│   │   │   │   │   └── QwenChatModelConfig.java
│   │   │   │   ├── rag/                     # RAG配置
│   │   │   │   │   └── RagConfig.java
│   │   │   │   ├── AiCodeHelper.java        # 基础AI对话类
│   │   │   │   ├── AiCodeHelperService.java # AI服务接口
│   │   │   │   └── AiCodeHelperServiceFactory.java
│   │   │   ├── config/                      # 配置类
│   │   │   │   └── CorsConfig.java
│   │   │   ├── controller/                  # 控制层
│   │   │   │   └── AiController.java
│   │   │   └── AiCodeHelperApplication.java # 启动类
│   │   └── resources/
│   │       ├── application.yml              # 应用配置
│   │       └── system-prompt.txt            # 系统提示词
│   └── test/                                # 测试代码
│       └── java/com/riche/aicodehelper/
│           └── ai/
│               └── AiCodeHelperServiceTest.java
├── ai-code-helper-frontend/                 # 前端项目
│   ├── src/
│   │   ├── App.vue                          # 主组件
│   │   ├── main.js                          # 入口文件
│   │   └── style.css
│   ├── public/
│   │   └── styles.css
│   ├── index.html
│   ├── package.json
│   └── vite.config.js
├── pom.xml                                  # Maven配置
└── mvnw.cmd                                 # Maven包装器
```

## 快速开始

### 环境要求
- JDK 21+
- Maven 3.6+
- Node.js 16+
- npm 或 yarn

### 后端启动

1. **配置API密钥**

编辑 `src/main/resources/application.yml`，填入你的API密钥：

```yaml
langchain4j:
  community:
    dashscope:
      chat-model:
        api-key: your-dashscope-api-key
      embedding-model:
        api-key: your-dashscope-api-key
      streaming-chat-model:
        api-key: your-dashscope-api-key

bigmodel:
  api-key: your-bigmodel-api-key
```

2. **构建项目**

```bash
# Windows
mvnw.cmd clean install

# Linux/Mac
./mvnw clean install
```

3. **启动后端服务**

```bash
# Windows
mvnw.cmd spring-boot:run

# Linux/Mac
./mvnw spring-boot:run
```

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

### 前端启动

1. **进入前端目录**

```bash
cd ai-code-helper-frontend
```

2. **安装依赖**

```bash
npm install
```

3. **启动开发服务器**

```bash
npm run dev
```

前端服务将在 `http://localhost:5173` 启动

## API接口

### 聊天接口

**接口地址**：`GET /api/ai/chat`

**请求参数**：
- `memoryId` (int)：会话ID，用于区分不同的对话上下文
- `message` (String)：用户输入的消息

**响应格式**：Server-Sent Events (SSE)

**示例**：
```
GET http://localhost:8081/api/ai/chat?memoryId=12345&message=如何学习Java?
```

## 核心功能说明

### 1. 对话记忆管理

系统支持基于 `memoryId` 的对话上下文管理，每个会话最多保留10条历史消息：

```java
MessageWindowChatMemory.withMaxMessages(10)
```

### 2. 系统提示词

系统使用外部化的提示词配置（`system-prompt.txt`），专注于以下4个方向：
1. 规划清晰的编程学习路线
2. 提供项目学习建议
3. 给出程序员求职全流程指南（简历优化、投递技巧）
4. 分享高频面试题和面试技巧

### 3. 安全护栏

`SafeInputGuardrail` 实现输入安全检查，自动过滤敏感词汇：
- 敏感词列表：kill, evil 等
- 发现敏感词时拒绝处理并返回警告

### 4. RAG检索增强（可选）

支持基于文档的知识增强：
- 自动加载本地文档
- 文档分段和向量化
- 相似度检索（最高返回5个结果，最低相似度0.75）

### 5. MCP工具调用

集成智谱BigModel的网络搜索功能，支持实时联网查询。

### 6. 流式输出

前端通过SSE接收实时流式输出，提供打字机效果的用户体验。

## 配置说明

### 后端配置

主要配置项在 `application.yml`：

```yaml
server:
  port: 8081                    # 服务端口
  servlet:
    context-path: /api          # 接口前缀

spring:
  application:
    name: ai-code-helper
```

### CORS配置

支持前端跨域访问：
- 允许源：`http://localhost:5173`
- 允许方法：GET, POST, PUT, DELETE, OPTIONS, HEAD
- 支持凭证传递

### 前端配置

主要配置在 `vite.config.js`，使用默认配置即可。

## 测试

项目包含完整的单元测试用例，位于 `AiCodeHelperServiceTest.java`：

```bash
# 运行所有测试
mvnw.cmd test

# 运行指定测试
mvnw.cmd test -Dtest=AiCodeHelperServiceTest#chat
```

测试用例包括：
- ✅ 基础对话测试
- ✅ 对话记忆测试
- ✅ 结构化输出测试
- ✅ RAG检索测试
- ✅ MCP工具调用测试
- ✅ 安全护栏测试

## 开发指南

### 自定义系统提示词

修改 `src/main/resources/system-prompt.txt` 文件，定制AI助手的角色和行为。

### 添加新的MCP工具

在 `McpConfig.java` 中注册新的MCP客户端：

```java
@Bean
public McpToolProvider customMcpToolProvider() {
    // 配置你的MCP服务
}
```

### 扩展护栏规则

在 `SafeInputGuardrail.java` 中添加新的安全检查逻辑：

```java
private static final Set<String> sensitiveWords = Set.of("kill", "evil", "your-word");
```

### 启用RAG功能

取消 `RagConfig.java` 中的 `@Configuration` 注释，并在 `AiCodeHelperServiceFactory.java` 中启用：

```java
.contentRetriever(contentRetriever)
```

## 部署指南

### 打包应用

```bash
mvnw.cmd clean package
```

生成的JAR文件位于 `target/ai-code-helper-0.0.1-SNAPSHOT.jar`

### 运行生产环境

```bash
java -jar target/ai-code-helper-0.0.1-SNAPSHOT.jar
```

### 前端构建

```bash
cd ai-code-helper-frontend
npm run build
```

构建产物位于 `dist/` 目录，可部署到任何静态服务器。

## 常见问题

### Q1: API密钥配置错误
**A**: 确保在 `application.yml` 中正确配置了 DashScope 和 BigModel 的 API 密钥。

### Q2: 前端无法连接后端
**A**: 检查 CORS 配置，确保允许的源地址与前端地址匹配。

### Q3: 流式输出不工作
**A**: 确保浏览器支持 EventSource（SSE），检查网络连接和防火墙设置。

### Q4: 对话记忆丢失
**A**: 当前使用内存存储，重启服务会清空所有对话历史。生产环境建议使用持久化存储。

## 技术亮点

1. ✨ **模块化设计**：清晰的分层架构，易于扩展和维护
2. 🚀 **响应式编程**：基于Reactor的流式处理，高性能异步响应
3. 🔒 **安全可靠**：多层次安全护栏，保障系统安全
4. 🎯 **智能检索**：RAG技术增强回答准确性
5. 🛠️ **工具集成**：MCP协议支持，轻松扩展AI能力
6. 📝 **可观测性**：完善的日志和监控机制

## 未来规划

- [ ] 支持多模型切换（OpenAI、Claude等）
- [ ] 持久化对话历史（Redis/MySQL）
- [ ] 用户认证和权限管理
- [ ] 更丰富的MCP工具集
- [ ] 向量数据库升级（Milvus/Pinecone）
- [ ] Docker容器化部署
- [ ] 性能监控和统计面板

## 贡献指南

欢迎提交 Issue 和 Pull Request！

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 文件。

## 联系方式

- 作者：Gaoruiqi
- 项目地址：[GitHub Repository]

## 致谢

- [LangChain4j](https://github.com/langchain4j/langchain4j) - 强大的Java AI框架
- [通义千问](https://tongyi.aliyun.com/) - 阿里云大语言模型
- [智谱AI](https://www.zhipuai.cn/) - MCP工具服务提供商
- [Spring Boot](https://spring.io/projects/spring-boot) - Java企业级框架
- [Vue.js](https://vuejs.org/) - 渐进式JavaScript框架

---

⭐ 如果这个项目对你有帮助，请给个 Star 支持一下！