# backend-expert-agent-java

**Repository Path**: abao123/backend-expert-agent-java

## Basic Information

- **Project Name**: backend-expert-agent-java
- **Description**: 后端专家 Agent 是一个面向 Java 后端开发者的 AI 助手，集成了 RAG 知识库检索、工具调用、多模型路由和自动化评估体系。覆盖支付、消息队列、数据库、性能优化、系统架构五大领域。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-20
- **Last Updated**: 2026-04-20

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Backend Expert Agent (Java)

> 基于 Spring Boot 3.4.5 + Spring AI 1.0 的后端专家 Agent，Python 版的完整 Java 重写。

## 项目简介

后端专家 Agent 是一个面向 Java 后端开发者的 AI 助手，集成了 RAG 知识库检索、工具调用、多模型路由和自动化评估体系。覆盖支付、消息队列、数据库、性能优化、系统架构五大领域。

## 功能特性

| 功能 | 说明 |
| --- | --- |
| Agent 核心引擎 | Spring AI ChatClient + Function Calling，自动工具编排 |
| RAG 知识库 | 17 篇领域知识文档，PGVector 向量检索，800/200 文本切分 |
| 工具链（4 个） | SQL 生成、Mermaid 架构图、Java 代码审查、RESTful API 设计 |
| 多模型路由 | 主备降级 + 智能路由（SIMPLE/NORMAL/COMPLEX 三级） |
| 对话日志 | JSONL 持久化，工具调用追踪，统计接口 |
| 评估体系 | 4 维度 10 用例自动化评估（相关性/完整性/工具使用/响应质量） |
| Web 界面 | Thymeleaf + HTMX 深色科技感主题 |
| Docker 部署 | docker-compose 一键启动（应用 + PostgreSQL） |

## 技术栈

| 层 | 技术 | 版本 |
| --- | --- | --- |
| 框架 | Spring Boot | 3.4.5 |
| AI | Spring AI | 1.0 |
| LLM | 阿里百炼 qwen-plus | OpenAI 兼容接口 |
| Embedding | text-embedding-v3 | DashScope |
| 向量库 | PGVector | PostgreSQL 16 |
| 前端 | Thymeleaf + HTMX + Tailwind CSS | - |
| JDK | Eclipse Temurin | 25 |
| 构建 | Maven | 3.9 |

## 项目结构

```
backend-expert-agent-java/
├── pom.xml                          # Maven 配置
├── Dockerfile                       # 多阶段构建
├── docker-compose.yml               # 双容器编排
├── .env.example                     # 环境变量模板
│
├── src/main/java/com/backendexpert/agent/
│   ├── config/                      # 配置层（AgentProperties）
│   ├── core/                        # Agent 核心引擎
│   ├── router/                      # 多模型路由（分类器 + 路由服务）
│   ├── rag/                         # RAG 知识库（加载/切分/检索）
│   ├── tool/                        # 4 个 @Tool 工具
│   ├── logging/                     # 对话日志（JSONL）
│   ├── evaluator/                   # 评估体系
│   ├── web/                         # Web 控制器
│   └── model/                       # 数据模型
│
├── src/main/resources/
│   ├── knowledge/                   # 17 篇知识文档（5 大领域）
│   ├── prompts/                     # Prompt 模板
│   └── templates/                   # Thymeleaf 模板
│
└── src/test/java/                   # 单元测试（7 个测试类，73+ 用例）
```

## 快速开始

### 环境要求

- JDK 25+
- Maven 3.9+
- PostgreSQL 16（需安装 pgvector 扩展）或 Docker

### 方式一：本地运行

**1. 准备 PostgreSQL**

```bash
# 安装 pgvector 扩展
CREATE EXTENSION IF NOT EXISTS vector;
```

**2. 配置环境变量**

```bash
export DASHSCOPE_API_KEY=sk-your-key-here
```

**3. 修改配置**

编辑 `src/main/resources/application.yml`，配置数据库连接：

```yaml
spring:
  datasource:
    url: jdbc:postgresql://localhost:5432/agent_db
    username: agent
    password: agent123
```

**4. 构建运行**

```bash
mvn clean package -DskipTests
java -jar target/backend-expert-agent-1.0.0.jar
```

访问 http://localhost:8080 即可使用。

### 方式二：Docker 一键部署

```bash
# 1. 复制并配置环境变量
cp .env.example .env
# 编辑 .env 填入 DASHSCOPE_API_KEY

# 2. 启动
docker-compose up -d

# 3. 查看日志
docker-compose logs -f app
```

## API 接口

| 接口 | 方法 | 说明 |
| --- | --- | --- |
| `/` | GET | 聊天页面 |
| `/chat` | POST | 发送消息（HTMX） |
| `/admin/status` | GET | 知识库状态 + 模型信息 |
| `/admin/kb/rebuild` | POST | 重建知识库 |
| `/admin/eval` | POST | 运行评估 |
| `/admin/eval/report` | GET | 评估报告页面 |
| `/admin/knowledge` | GET | 知识库管理页面 |

## 知识库

17 篇文档覆盖 5 大领域：

| 领域 | 文档数 | 内容 |
| --- | --- | --- |
| 支付 | 6 篇 | 支付中台、渠道管理、对账、退款、风控、安全 |
| 消息队列 | 4 篇 | RocketMQ 可靠性、分布式事务、死信队列、消费幂等 |
| 架构 | 2 篇 | 微服务拆分、高可用部署 |
| 数据库 | 2 篇 | 分库分表、慢查询治理 |
| 性能优化 | 3 篇 | 高并发设计、缓存策略、限流熔断降级 |

## 运行测试

```bash
mvn test
```

测试覆盖 7 个模块，73+ 测试用例：

- `ToolTest` — 4 个工具的输入输出验证（14 用例）
- `QuestionClassifierTest` — 问题分类器（18 用例）
- `MarkdownTextSplitterTest` — 文本切分器（9 用例）
- `ConversationLogServiceTest` — 对话日志服务（11 用例）
- `AgentEvaluatorServiceTest` — 评估器逻辑（10 用例）
- `KnowledgeBaseServiceTest` — RAG 知识库 POJO（11 用例）
- `ModelTest` — 数据模型 POJO（10 用例）

## 代码规范

- 不使用 Lombok，所有 getter/setter 手写
- UTF-8 编码
- 详细的 Javadoc 注释

## License

MIT