# langchain4j-spring-agent

**Repository Path**: zhangjq123/langchain4j-spring-agent

## Basic Information

- **Project Name**: langchain4j-spring-agent
- **Description**: 面向企业级 AI 应用的开源脚手架，集成 Spring AI、LangChain4j、Elasticsearch、MCP 协议等主流技术，支持多模型统一接入、多轮对话、RAG 检索增强、Agent 工具调用、JWT 安全与日志治理，并配套 Vue3 前端套件，适合快速孵化智能助手、知识库、Agent 工作流等场景，持续跟进主流 AI 生态最新版本。
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 104
- **Forks**: 47
- **Created**: 2025-09-30
- **Last Updated**: 2026-04-24

## Categories & Tags

**Categories**: ai

**Tags**: None

## README

# langchain4j-spring-agent

> 基于 Spring Boot 4.0.2 的企业级 AI 应用脚手架：覆盖 Chat、RAG、Skills Agent、Swagger MCP、Elasticsearch MCP、安全治理、日志治理与多套 Vue3 前端。

<p align="center">
  <b>Spring Boot 4.0.2 · Spring Cloud 2025.1.1 · Spring AI 1.1.3 · LangChain4j 1.12.2 · MCP 0.17.2 · Vue 3</b>
</p>

---

## 1. 项目简介

`langchain4j-spring-agent` 是一个面向企业内部 AI 平台、知识助手、Agent 工具化场景的多模块单仓工程。

当前仓库重点提供：

- 多模型统一接入与对话能力
- 基于 Elasticsearch / Qdrant / Neo4j 的 RAG / KAG 实践
- 基于 MCP 的工具暴露与 OpenAPI 转 Tool 能力
- Skills Agent 服务与配套前端
- JWT / RBAC / Redis 黑名单等安全治理能力
- 日志、测试脚本、模块化前后端示例

这次仓库已完成一轮**大跨度升级与结构收敛**：

- 后端核心基线升级到 **Spring Boot 4.0.2**
- Spring Cloud 升级到 **2025.1.1**
- Spring AI 升级到 **1.1.3**
- LangChain4j 升级到 **1.12.2**
- MCP SDK 升级到 **0.17.2**
- MyBatis-Plus 切换为 **Boot 4 对应 Starter**
- 新增 `langchain4j-spring-ai-skills`
- 新增 `langchain4j-spring-ai-resume-rag`
- 新增 `langchain4j-spring-ai-ui-skills`
- 收敛并移除部分历史模块，减少重复实现与维护成本

---

## 2. 这次升级的重点变化

### 2.1 技术栈基线变化

| 类别 | 当前版本 | 说明 |
|------|----------|------|
| Spring Boot | 4.0.2 | 本次升级核心，涉及 Starter、配置与兼容性调整 |
| Spring Cloud | 2025.1.1 | 对齐 Boot 4 生态 |
| Spring AI | 1.1.3 | 当前稳定主线 |
| LangChain4j | 1.12.2 | 当前主线版本 |
| LangChain4j Community | 1.12.2-beta22 | 百炼/OpenAI 兼容生态支持 |
| MCP SDK | 0.17.2 | 支撑 MCP Tool、Swagger MCP、MCP Server |
| MyBatis-Plus | 3.5.15 | 已切换到 `mybatis-plus-spring-boot4-starter` |
| Elasticsearch Client | 8.19.2 | 检索与 MCP 检索服务基线 |
| Neo4j Driver | 6.0.0 | 图谱 / KAG 相关能力基线 |
| Druid | 1.2.27 | 数据源监控与连接池 |

### 2.2 模块结构变化

本轮调整的核心方向是：**减少历史重复模块，强化当前主线模块**。

#### 新增 / 强化模块

- `langchain4j-spring-ai-skills`
  - 独立 Skills Agent 服务
  - 支持会话、历史、模型管理、同步/流式对话
  - 支持本地 skills 目录聚合与结构化摘要
- `langchain4j-spring-ai-resume-rag`
  - 简历 RAG 入库与检索模块
  - 文本抽取、LLM 切窗、Elasticsearch 主文档、Qdrant 向量、RustFS 文件存储
- `langchain4j-spring-ai-ui-skills`
  - Skills Agent 配套前端
  - 包含概览、会话管理、历史消息、模型管理、同步/流式对话
- `langchain4j-spring-ai-test`
  - 增加了更贴近实际排障的脚本与自动化测试样例
  - 包含 `agent-browser` / BOSS 直聘诊断脚本等

#### 已收敛 / 移除的历史模块

以下模块已不再作为当前主线维护：

- `langchain4j-spring-ai-chat`
- `langchain4j-spring-ai-chat-v1`
- `langchain4j-spring-ai-security`
- `langchain4j-spring-ai-rag-chunk`

当前推荐统一使用：

- 对话主线：`langchain4j-spring-ai-chat-v2`
- 安全主线：`langchain4j-spring-ai-security-v1` + `langchain4j-spring-ai-security-common`
- 分割主线：`langchain4j-spring-ai-seg-flow`
- Skills Agent：`langchain4j-spring-ai-skills`

---

## 3. 当前仓库结构

### 3.1 后端模块

`langchain4j-spring-ai/` 为 Maven 聚合工程，当前主要模块如下：

| 模块 | 作用 | 当前状态 |
|------|------|----------|
| `langchain4j-spring-ai-chat-v2` | 多轮对话主模块，支持上下文、SSE、模型配置、Neo4j 相关扩展 | 主线模块 |
| `langchain4j-spring-ai-llm-common` | LLM 公共封装，复用模型调用、流式支持与安全包装 | 主线模块 |
| `langchain4j-spring-ai-elasticsearch` | Elasticsearch 检索服务 | 主线模块 |
| `langchain4j-spring-ai-elasticsearch-common` | Elasticsearch 公共能力 | 主线模块 |
| `langchain4j-spring-ai-elasticsearch-mcp` | 将检索能力以 MCP 服务暴露 | 主线模块 |
| `langchain4j-spring-ai-swagger-mcp` | 将 OpenAPI / Swagger 接口映射为 MCP Tools | 主线模块 |
| `langchain4j-spring-ai-skills` | Skills Agent 服务，会话 + 历史 + 模型 + chat/stream | 新主线模块 |
| `langchain4j-spring-ai-resume-rag` | 简历 RAG 入库、抽取、向量化、检索、下载 | 新增模块 |
| `langchain4j-spring-ai-seg-flow` | 智能分割流程编排与任务执行 | 主线模块 |
| `langchain4j-spring-ai-triple-extraction` | 三元组抽取 / 图谱构建相关实验与沉淀 | 保留模块 |
| `langchain4j-spring-ai-security-common` | JWT / 安全通用能力 | 主线模块 |
| `langchain4j-spring-ai-security-v1` | RBAC / 用户 / 角色 / 菜单 / Token 等安全实现 | 主线模块 |
| `langchain4j-spring-ai-logging` | logging-sdk + logging-server | 主线模块 |
| `langchain4j-spring-ai-gateway` | 网关预留 | 规划中 |
| `langchain4j-spring-ai-sdk` | OCR 等 SDK 聚合 | 扩展模块 |
| `langchain4j-spring-ai-test` | 脚本、实验、自动化测试样例 | 工具模块 |

### 3.2 前端模块

`langchain4j-spring-ai-ui/` 当前包含：

| 模块 | 作用 |
|------|------|
| `langchain4j-spring-ai-ui-chat-v2` | 聊天主前端 |
| `langchain4j-spring-ai-ui-v1` | 管理后台 / 安全演示前端 |
| `langchain4j-spring-ai-ui-seg-flow` | 智能分割前端 |
| `langchain4j-spring-ai-ui-logging` | 日志前端 |
| `langchain4j-spring-ai-ui-skills` | Skills Agent 前端 |

### 3.3 文档与专题资料

根目录保留了较多中文专题文档，包括：

- `TECH_WHITEPAPER.md`
- `入门篇.md`
- `权限治理篇.md`
- `RAG增强与向量基础篇.md`
- `Xinference本地部署与多引擎性能调优实战.md`
- `深度实测｜四大名著语义检索对比.md`

---

## 4. 适用场景

本仓库适合以下场景：

- 企业内部知识库问答
- 通用 Chat / Agent 应用快速孵化
- 基于 MCP 的工具化接入平台
- Swagger / OpenAPI 自动转 Tool 的实验与落地
- 简历解析、向量入库与检索场景
- 多模型接入与能力抽象验证
- 安全、权限、日志治理的 AI 应用基线搭建

---

## 5. 快速开始

### 5.1 环境准备

建议准备以下环境：

- JDK 21（本地推荐）
- Maven 3.9+
- Node.js 23+
- pnpm 10+
- MySQL 8.x
- Redis
- Elasticsearch 8.x

按当前仓库本地开发习惯：

- 前端优先使用 `pnpm`
- Windows / PowerShell 命令优先
- Maven 使用本地已配置镜像的 `settings.xml`

### 5.2 克隆仓库

```powershell
git clone https://gitee.com/<your-namespace>/langchain4j-spring-agent.git
Set-Location "D:\workspace\langchain4j-spring-agent"
```

### 5.3 构建后端聚合工程

```powershell
Set-Location "D:\workspace\langchain4j-spring-agent\langchain4j-spring-ai"
mvn clean package -DskipTests=true
```

如果本地环境变量未配置好，可显式指定 Maven：

```powershell
& "D:\software\apache-maven-3.9.9\bin\mvn.cmd" clean package -DskipTests=true
```

---

## 6. 推荐启动路径

本仓库模块较多，建议按场景启动，而不是一次性全部启动。

### 6.1 启动 Skills Agent

后端：

```powershell
Set-Location "D:\workspace\langchain4j-spring-agent\langchain4j-spring-ai"
mvn -pl langchain4j-spring-ai-skills -am spring-boot:run
```

默认接口前缀：

- `GET /api/skills-agent/health`
- `GET /api/skills-agent/info`
- `POST /api/skills-agent/refresh`
- `POST /api/skills-agent/chat`
- `GET /api/skills-agent/chat/stream`
- `POST /api/skills-agent/sessions`
- `GET /api/skills-agent/sessions/{sessionId}/messages`

默认端口示例：`9015`

前端：

```powershell
Set-Location "D:\workspace\langchain4j-spring-agent\langchain4j-spring-ai-ui\langchain4j-spring-ai-ui-skills"
pnpm install
pnpm dev
```

### 6.2 启动 Chat 主服务

```powershell
Set-Location "D:\workspace\langchain4j-spring-agent\langchain4j-spring-ai"
mvn -pl langchain4j-spring-ai-chat-v2 -am spring-boot:run
```

聊天前端：

```powershell
Set-Location "D:\workspace\langchain4j-spring-agent\langchain4j-spring-ai-ui\langchain4j-spring-ai-ui-chat-v2"
pnpm install
pnpm dev
```

### 6.3 启动简历 RAG

```powershell
Set-Location "D:\workspace\langchain4j-spring-agent\langchain4j-spring-ai"
mvn -pl langchain4j-spring-ai-resume-rag -am spring-boot:run
```

默认端口示例：`9022`

核心接口：

- `POST /api/resume-rag/ingest`
- `GET /api/resume-rag/profile/{docId}`
- `GET /api/resume-rag/vectors/{docId}`
- `GET /api/resume-rag/profiles/page`
- `GET /api/resume-rag/rag/search`
- `GET /api/resume-rag/download/{docId}`

### 6.4 启动智能分割前后端

后端：

```powershell
Set-Location "D:\workspace\langchain4j-spring-agent\langchain4j-spring-ai"
mvn -pl langchain4j-spring-ai-seg-flow -am spring-boot:run
```

前端：

```powershell
Set-Location "D:\workspace\langchain4j-spring-agent\langchain4j-spring-ai-ui\langchain4j-spring-ai-ui-seg-flow"
pnpm install
pnpm dev
```

### 6.5 启动安全后台前端

```powershell
Set-Location "D:\workspace\langchain4j-spring-agent\langchain4j-spring-ai-ui\langchain4j-spring-ai-ui-v1"
pnpm install
pnpm dev
```

---

## 7. 关键模块说明

### 7.1 `langchain4j-spring-ai-skills`

当前仓库中，`skills` 是这轮升级里最重要的新模块之一。

能力包括：

- 本地 skills 目录聚合
- 模型配置数据库化
- Skills 会话创建、列表、归档
- 历史消息分页回放
- 同步对话与流式对话
- 技能摘要信息输出
- 原生静态页面与 Vue 前端两种访问方式

相关文件：

- `langchain4j-spring-ai/langchain4j-spring-ai-skills/README.md`
- `langchain4j-spring-ai/langchain4j-spring-ai-skills/http/skills-agent.http`
- `langchain4j-spring-ai/langchain4j-spring-ai-skills/scripts/smoke-test.ps1`

### 7.2 `langchain4j-spring-ai-resume-rag`

这是本次新增的另一条重要业务线。

能力包括：

- PDF / 简历文本抽取
- LLM 语义切窗
- Elasticsearch 主文档写入
- Qdrant 向量写入与检索
- RustFS 文件上传与下载
- 后台风格静态管理页

适合做：

- 简历库语义检索
- 候选人画像抽取
- 简历向量召回与匹配实验

### 7.3 `langchain4j-spring-ai-swagger-mcp`

`swagger-mcp` 用于把 OpenAPI / Swagger 文档转为 MCP 工具，这也是仓库里非常有代表性的能力：

- 读取 OpenAPI 文档
- 自动生成 Tool 列表
- 支持按操作粒度调用真实后端 HTTP 接口
- 适用于把已有业务系统快速接入 Agent 生态

### 7.4 `langchain4j-spring-ai-test`

当前测试模块除了基础实验，还新增了更偏运维/排障的脚本：

- `diagnose-zhipin.ps1`
- `open-boss.ps1`
- `trace-zhipin-agent-browser.ps1`

可用于排查 `agent-browser`、站点访问、证书、代理、DNS 等问题。

---

## 8. Spring Boot 4 迁移说明

由于这次从旧基线升级到 **Spring Boot 4.0.2**，README 需要明确几点：

1. **Starter 体系已调整**
   - 例如 MyBatis-Plus 已切换到 Boot 4 对应 starter。

2. **部分旧模块已不再保留**
   - 旧的 chat / security / rag-chunk 历史模块已收敛，不建议再基于这些目录继续开发。

3. **OpenAPI 文档方案以当前模块真实实现为准**
   - 不再沿用旧 README 中的快照版本与早期描述。

4. **数据源与兼容性配置已在多个模块中补充适配**
   - 如 `DruidConfig`、MyBatis-Plus、Spring Security 兼容调整等。

5. **优先基于当前主线模块继续演进**
   - Chat：`chat-v2`
   - Security：`security-v1`
   - Skills：`skills`
   - Resume RAG：`resume-rag`
   - SegFlow：`seg-flow`

---

## 9. 文档导航

| 文档 | 说明 |
|------|------|
| `TECH_WHITEPAPER.md` | 仓库总体技术白皮书 |
| `入门篇.md` | 面向初学者的总览与上手说明 |
| `权限治理篇.md` | 安全与权限治理专题 |
| `RAG增强与向量基础篇.md` | RAG / 向量基础说明 |
| `Xinference本地部署与多引擎性能调优实战.md` | Embedding / 多引擎性能调优实践 |
| `深度实测｜四大名著语义检索对比.md` | 检索效果与模型对比评测 |
| `langchain4j-spring-ai/langchain4j-spring-ai-skills/README.md` | Skills 模块详细说明 |
| `langchain4j-spring-ai/langchain4j-spring-ai-resume-rag/README.md` | Resume RAG 模块详细说明 |
| `langchain4j-spring-ai/langchain4j-spring-ai-test/scripts/README.md` | 测试脚本与诊断脚本说明 |

---

## 10. 开发建议

- 新功能优先落到当前主线模块，不要在已收敛模块里继续扩展。
- 前端统一优先使用 `pnpm`。
- 后端统一优先复用聚合工程依赖管理，不要随意单模块漂移版本。
- README 仅保留总览、模块入口、快速启动与升级说明；模块细节请下沉到各自 README。

---

## 11. 贡献方式

建议流程：

1. 从 `develop` 或当前主线分支创建功能分支
2. 按模块提交最小必要改动
3. 后端优先执行 Maven 验证，前端至少执行 `pnpm build` 或 `pnpm typecheck`
4. 若改动影响接口、端口、配置或模块职责，请同步更新 README / 模块 README

---

## 12. License

当前仓库根目录已包含 `LICENSE` 文件。若后续对外发布，请以仓库根目录 License 与发布说明为准。

---

如果你现在要快速体验，推荐从下面两条路径开始：

- **Skills Agent 路径**：`langchain4j-spring-ai-skills` + `langchain4j-spring-ai-ui-skills`
- **Resume RAG 路径**：`langchain4j-spring-ai-resume-rag`

这两条路径最能体现本轮升级后仓库的最新能力边界。