# langchain4j-spring-agent

**Repository Path**: xxmgm_admin/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**: 0
- **Forks**: 60
- **Created**: 2026-06-09
- **Last Updated**: 2026-06-09

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# langchain4j-spring-agent

> 企业级 AI 工程化脚手架：把“模型接入 + RAG/KAG + MCP 工具化 + 安全治理 + 可视化前端”放进一个可持续演进的单仓体系。

[![Java](https://img.shields.io/badge/Java-17%2B-blue)](#) [![Spring%20Boot](https://img.shields.io/badge/Spring%20Boot-4.0.6-6DB33F)](#) [![Spring%20AI](https://img.shields.io/badge/Spring%20AI-1.1.7-6DB33F)](#) [![LangChain4j](https://img.shields.io/badge/LangChain4j-1.15.0-1f6feb)](#) [![MCP](https://img.shields.io/badge/MCP-0.17.2-purple)](#) [![pnpm](https://img.shields.io/badge/pnpm-10%2B-orange)](#) [![License](https://img.shields.io/badge/License-Apache--2.0-blue.svg)](LICENSE)

---

## 0) 30 秒先看懂

### 这是什么？
一个面向企业 AI 应用落地的单仓项目，包含后端多模块（Spring Boot + Spring AI + LangChain4j）与前端多子应用（Vue3）。

### 为什么用它？
你不需要从 0 拼装聊天、RAG、工具调用、安全、日志：项目已提供可运行主线模块，适合做企业内 AI 平台的起步底座。

### 你会拿到什么？
- 一套可直接对接业务的对话中台（`chat-v2`）
- 一套可独立部署的 Skills Agent（`skills`）
- 一套“分割→向量→图谱”作业平台（`seg-flow`）
- 两个可复用 MCP 服务（`swagger-mcp`、`elasticsearch-mcp`）

### 怎么最快跑起来？
按下面 [快速开始](#3-快速开始quick-start) 的 3 步执行：构建后端 → 启动 chat-v2 → 启动 chat-v2 前端。

---

## 1) 项目名称与标识（Identity）

### 一句话简介
`langchain4j-spring-agent` 用于快速搭建“可治理、可扩展”的企业级 AI 应用平台。

### 核心特性
- 🚀 主线模块齐全：Chat / Skills / SegFlow / Swagger MCP / Elasticsearch MCP
- 🔐 企业治理能力：JWT、RBAC、Redis 黑名单
- 🔧 工程化友好：单仓多模块、统一 SQL 演进规范、可分域部署

### 后端/前端主线对应关系（实代码）
| 业务域 | 后端模块 | 前端模块 | 主要路由/API 前缀 |
|---|---|---|---|
| 对话与配置中心 | `langchain4j-spring-ai-chat-v2` | `langchain4j-spring-ai-ui-chat-v2` | `/api/v2/sessions`、`/api/v2/models`、`/api/v2/rag-services`、`/api/v2/kag` |
| Skills Agent | `langchain4j-spring-ai-skills` | `langchain4j-spring-ai-ui-skills` | `/api/skills-agent` |
| 智能分割 | `langchain4j-spring-ai-seg-flow` | `langchain4j-spring-ai-ui-seg-flow` | `/api/segment/*`、`/api/vector/*`、`/api/graph/*` |
| 安全治理 | `langchain4j-spring-ai-security-v1` | `langchain4j-spring-ai-ui-v1` | `/api/v1/auth`、`/api/v1/users`、`/api/v1/roles` |

---

## 2) 项目背景与动机（Why）

### 核心痛点
1. AI 项目常见“能跑 Demo，难上线”：模块分散、配置混乱、缺少治理能力。
2. 聊天、检索、工具调用、安全经常重复造轮子，交付周期长。

### 本项目的解决方式
- 用统一工程骨架承载 AI 主链路：模型接入、对话、RAG/KAG、MCP 工具化。
- 用治理模块补齐上线条件：权限、测试与诊断脚本。

### 适用/不适用场景
**适用：** 企业内部知识助手、Agent 工具平台、AI 中台 PoC 到生产过渡。  
**不适用：** 只需要一个超轻量单文件 Demo、且不关心后续演进与治理。

---

## 3) 快速开始（Quick Start）

> 目标：复制粘贴即可启动一条完整链路（chat-v2 后端 + chat-v2 前端）。

### 3.1 环境依赖
- JDK 21（项目编译目标 Java 17）
- Maven 3.9+
- Node.js 23+
- pnpm 10+
- MySQL 8.x（按模块）
- Redis / Elasticsearch（按模块）

### 3.1.1 启动矩阵（模块 / 端口 / 依赖）

> 端口来自各模块 `application.yml` 与 `vite.config.ts` 默认配置。

| 类型 | 模块 | 默认端口 | 关键依赖/说明 |
|---|---|---:|---|
| 后端 | chat-v2 | 9008 | MySQL、Redis（可选 Neo4j/Qdrant） |
| 后端 | security-v1 | 9006 | MySQL、Redis |
| 后端 | elasticsearch | 9007 | MySQL、Elasticsearch |
| 后端 | seg-flow | 9010 | MySQL、（按功能）向量库/图数据库 |
| 后端 | skills | 9015 | MySQL、Redis、模型服务 |
| 后端 | swagger-mcp | 3000 | 依赖目标 OpenAPI 服务（默认指向 9008） |
| 后端 | elasticsearch-mcp | 3001 | 与 swagger-mcp 解耦，可并行启动 |
| 前端 | ui-v1 | 5173 | 代理到 9006 |
| 前端 | ui-chat-v2 | 5174 | 代理到 9008 |
| 前端 | ui-seg-flow | 5176 | 与 ui-chat-v2 端口解耦 |
| 前端 | ui-skills | 5175 | 代理到 9015 |

### 3.1.2 一键拉起基础组件（推荐）

如果你希望一次性准备好 MySQL、Elasticsearch、Qdrant、Neo4j、Redis、IK 分词插件环境，可直接使用：

- [langchain4j-spring-ai/langchain4j-spring-ai-chat-v2/docker/docker-compose-mysql-elasticsearch-qdrant-neo4j-redis-ik.yml](langchain4j-spring-ai/langchain4j-spring-ai-chat-v2/docker/docker-compose-mysql-elasticsearch-qdrant-neo4j-redis-ik.yml)

```powershell
# 启动全部基础组件
Set-Location "D:\workspace\langchain4j-spring-agent"
docker compose -f "langchain4j-spring-ai/langchain4j-spring-ai-chat-v2/docker/docker-compose-mysql-elasticsearch-qdrant-neo4j-redis-ik.yml" up -d

# 查看状态
docker compose -f "langchain4j-spring-ai/langchain4j-spring-ai-chat-v2/docker/docker-compose-mysql-elasticsearch-qdrant-neo4j-redis-ik.yml" ps

# 停止并清理
docker compose -f "langchain4j-spring-ai/langchain4j-spring-ai-chat-v2/docker/docker-compose-mysql-elasticsearch-qdrant-neo4j-redis-ik.yml" down
```

这样可以覆盖 README 中多数“可选依赖”场景，适合本地联调与功能演示。

### 3.2 安装与构建

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

### 3.3 最小可运行示例（推荐）

```powershell
# 1) 启动 chat-v2 后端
Set-Location "D:\workspace\langchain4j-spring-agent\langchain4j-spring-ai"
mvn -pl langchain4j-spring-ai-chat-v2 -am spring-boot:run

# 2) 启动 chat-v2 前端
Set-Location "D:\workspace\langchain4j-spring-agent\langchain4j-spring-ai-ui\langchain4j-spring-ai-ui-chat-v2"
pnpm install
pnpm dev
```

### 3.4 验证是否成功
- 后端日志出现 `Started ...Application`。
- 前端启动后可访问对应地址：
    - ui-chat-v2: `http://127.0.0.1:5174`
    - ui-v1: `http://127.0.0.1:5173`
    - ui-skills: `http://127.0.0.1:5175`

### 3.5 5 分钟 API 自检（PowerShell）

```powershell
# A. Skills 健康检查（默认常见端口 9015）
Invoke-RestMethod "http://127.0.0.1:9015/api/skills-agent/health"

# B. chat-v2 会话分页（默认 9008）
$body = @{ page = 1; size = 10 } | ConvertTo-Json
Invoke-RestMethod "http://127.0.0.1:9008/api/v2/sessions/page" -Method Post -ContentType "application/json" -Body $body
```

如果 A/B 均返回 JSON，说明你的主链路环境已基本可用。

### 3.5.1 场景启动前的 SQL 前置说明（重要）

是的，**涉及 MySQL 的后端模块在首次启动前必须先执行对应 SQL**，否则常见接口会因缺表/缺数据失败。

- 需要先执行 SQL：`chat-v2`、`security-v1`、`skills`、`seg-flow`、`elasticsearch`
- 不需要 MySQL SQL：`swagger-mcp`、`elasticsearch-mcp`

建议执行顺序：
1. 新库先执行 `db/init-*.sql`
2. 已有库再按版本升序执行 `db/migration/V{n}__{desc}.sql`

可直接参考各模块 `db/` 目录中的初始化脚本（见下文 [4.4 SQL 执行规范（务必遵循）](#44-sql-执行规范务必遵循)）。

### 3.6 按场景一键启动（建议）

> 原则：只启动“当前场景最小集合”，不要一次性拉全模块。

#### 场景 A：聊天与配置（最常用）
- 后端：`chat-v2`（9008）
- 前端：`ui-chat-v2`（5174）

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

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

对应 VS Code 任务：
- `run chat-v2 backend`
- `run ui-chat-v2 frontend`

#### 场景 B：权限后台（RBAC）
- 后端：`security-v1`（9006）
- 前端：`ui-v1`（5173）

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

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

对应 VS Code 任务：
- `run security-v1 backend`
- `run ui-v1 frontend`

#### 场景 C：智能分割（SegFlow）
- 后端：`seg-flow`（9010）
- 前端：`ui-seg-flow`（5176）

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

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

对应 VS Code 任务：
- `run seg-flow backend`
- `run ui-seg-flow frontend`

#### 场景 D：Swagger MCP 工具化
- 后端：`swagger-mcp`（3000，依赖可访问目标 OpenAPI）

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

对应 VS Code 任务：
- `run swagger-mcp backend`

如需检索 MCP 服务，可启动 `elasticsearch-mcp`（3001）：

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

#### 场景 E：Skills Agent
- 后端：`skills`（9015）
- 前端：`ui-skills`（5175）

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

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

对应 VS Code 任务：
- `run skills backend`
- `run ui-skills frontend`

#### 场景 F：检索后台（Elasticsearch）
- 后端：`elasticsearch`（9007）

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

### 3.7 依赖准备矩阵（先看这个再启动）

| 场景 | MySQL | Redis | Elasticsearch | Neo4j | Qdrant |
|---|---|---|---|---|---|
| 聊天与配置（chat-v2） | 必需 | 建议 | 按 RAG 配置可选 | 按 KAG 配置可选 | 按向量方案可选 |
| Skills Agent | 必需 | 建议 | 可选 | 可选 | 可选 |
| 权限后台（security-v1） | 必需 | 必需 | 不需要 | 不需要 | 不需要 |
| 智能分割（seg-flow） | 必需 | 可选 | 按向量配置可选 | 按图配置可选 | 按向量配置可选 |
| 检索后台（elasticsearch） | 必需 | 不需要 | 必需 | 不需要 | 不需要 |
| Swagger MCP | 不需要 | 不需要 | 不需要 | 不需要 | 不需要 |
| Elasticsearch MCP | 不需要 | 不需要 | 可选（作为检索目标） | 不需要 | 不需要 |

说明：
- “必需”表示缺失会导致核心接口不可用。
- “建议”表示不配也可启动，但多轮记忆或性能体验会打折。
- “可选”表示只在你启用对应功能（RAG/KAG/向量/图）时才需要。

### 3.8 启动前 60 秒检查清单

- [ ] JDK、Maven、Node、pnpm 已安装且可执行
- [ ] 目标场景的必需依赖已启动（见上表）
- [ ] 端口未冲突（重点检查本机已占用端口）
- [ ] 目标模块 `application.yml` 的数据库与服务地址已改成你的本机配置
- [ ] 前端代理目标与后端端口一致（例如 ui-chat-v2 -> 9008）

---

## 4) 核心用法与 API（How）

### 4.1 常用启动命令

```powershell
# Chat 主线
mvn -pl langchain4j-spring-ai-chat-v2 -am spring-boot:run

# Skills Agent
mvn -pl langchain4j-spring-ai-skills -am spring-boot:run

# SegFlow
mvn -pl langchain4j-spring-ai-seg-flow -am spring-boot:run

# Swagger MCP
mvn -pl langchain4j-spring-ai-swagger-mcp -am spring-boot:run
```

### 4.2 常用配置项（生产常见）
以各模块 `application-*.yml` 为准，重点关注：
- 数据源（MySQL）
- Redis 连接与鉴权
- Elasticsearch / Neo4j / Qdrant 连接（按模块）
- 模型供应商与 Key（按模块）

### 4.2.1 多前端本地联调建议
- `ui-chat-v2`：默认 `VITE_API_BASE` 为空，通常通过同域代理或网关转发。
- `ui-skills`：`VITE_API_BASE` 默认是 `http://127.0.0.1:9015`。
- `ui-v1`：API 客户端默认走 `/api` 前缀。

### 4.3 高频 API（按业务分组）
| 业务 | 方法 | 路径 | 说明 |
|---|---|---|---|
| chat-v2 | GET | `/api/v2/sessions/chat` | SSE 流式对话 |
| chat-v2 | POST | `/api/v2/sessions/page` | 会话分页 |
| chat-v2 | GET | `/api/v2/memory/all/{sessionId}` | 会话全历史 |
| skills | GET | `/api/skills-agent/health` | 健康检查 |
| skills | POST | `/api/skills-agent/chat` | 同步对话 |
| skills | GET | `/api/skills-agent/chat/stream` | 流式对话 |
| seg-flow | POST | `/api/segment/ingest/text` | 文本分割摄取 |
| seg-flow | POST | `/api/vector/ops/search` | 向量检索 |
| security | POST | `/api/v1/auth/login` | 登录 |

### 4.4 SQL 执行规范（务必遵循）
- 初始化：`db/init-模块名.sql`
- 增量迁移：`db/migration/V{n}__{desc}.sql`
- 原则：**新 DDL 只追加新版本，不改历史版本**

执行策略：
- 新库执行 `init`。
- 老库按版本执行 `migration`。

### 4.5 输出/产物说明
- 服务日志：各模块运行日志（部分模块含 `logs/` 目录）
- 前端产物：Vite 构建输出目录
- SQL 产物：模块内 `db/migration/` 版本脚本

---

## 5) 架构与设计（What Inside）

### 5.1 目录结构（核心）

```text
langchain4j-spring-agent/
├─ langchain4j-spring-ai/                # 后端聚合工程
│  ├─ langchain4j-spring-ai-chat-v2/
│  ├─ langchain4j-spring-ai-skills/
│  ├─ langchain4j-spring-ai-seg-flow/
│  ├─ langchain4j-spring-ai-swagger-mcp/
│  ├─ langchain4j-spring-ai-elasticsearch*/
│  ├─ langchain4j-spring-ai-security-*/
│  └─ langchain4j-spring-ai-test/
├─ langchain4j-spring-ai-ui/             # 前端多子应用
│  ├─ langchain4j-spring-ai-ui-chat-v2/
│  ├─ langchain4j-spring-ai-ui-skills/
│  ├─ langchain4j-spring-ai-ui-seg-flow/
│  └─ langchain4j-spring-ai-ui-v1/
├─ README.md
└─ 技术白皮书.md
```

### 5.2 核心流程（简化）

```mermaid
flowchart LR
    UI[Vue 前端] --> API[业务模块 API]
    API --> LLM[LLM Common / 模型接入]
    API --> RAG[RAG/KAG 检索链路]
    API --> MCP[Swagger MCP / ES MCP]
    RAG --> ES[(Elasticsearch)]
    RAG --> NEO[(Neo4j/Qdrant)]
    API --> SEC[Security v1]
```

### 5.2.1 对话链路（chat-v2）

```mermaid
sequenceDiagram
    participant U as UI-chat-v2
    participant C as SessionController
    participant M as SessionManager
    participant L as LLM/RAG/MCP
    U->>C: GET /api/v2/sessions/chat?sessionId&question
    C->>M: streamReactive(sessionId, question)
    M->>L: 组装模型+RAG+MCP上下文
    L-->>M: 增量 token
    M-->>C: Flux<String>
    C-->>U: SSE 文本流
```

### 5.2.2 Swagger MCP 工具链

```mermaid
flowchart LR
    Agent[Agent/LLM] --> Tool[SwaggerCallTool]
    Tool --> Norm[OpenApiNormalizer]
    Tool --> Invoker[OpenApiInvoker]
    Invoker --> Biz[业务OpenAPI接口]
    Biz --> Invoker --> Agent
```

### 5.3 技术选型说明（关键决策）
- 选择 Spring Boot 4 + Spring AI：保证现代生态与企业 Java 体系兼容。
- 选择 LangChain4j：统一 AI 调用抽象，降低多模型切换成本。
- 选择 MCP：把已有服务能力工具化，便于 Agent 编排复用。
- 选择“多子前端 + 多后端模块”：不同业务域可独立迭代，不互相阻塞。

---

## 6) 贡献指南（For Contributors）

### 6.1 本地开发
```powershell
git clone <repo-url>
Set-Location "D:\workspace\langchain4j-spring-agent"

# 后端验证
Set-Location ".\langchain4j-spring-ai"
mvn -q -DskipTests=true package

# 前端验证（示例）
Set-Location "..\langchain4j-spring-ai-ui\langchain4j-spring-ai-ui-chat-v2"
pnpm install
pnpm typecheck
```

可选：按模块快速验证，避免全仓编译。

```powershell
# 仅验证 chat-v2
Set-Location "D:\workspace\langchain4j-spring-agent\langchain4j-spring-ai"
mvn -pl langchain4j-spring-ai-chat-v2 -am -DskipTests=true package
```

### 6.2 代码规范
- 后端：沿用现有分层与模块边界，不做跨模块大重构。
- 前端：统一 `pnpm`，按 `api/store/views/components` 组织。
- 文档：重要行为变更需同步更新 README 或白皮书。

### 6.3 提 PR 要求
1. 最小必要改动，避免无关格式化。
2. 说明影响范围（模块、接口、配置、SQL）。
3. 涉及接口或 SQL 的变更，补充验证步骤。

协作说明见：[代码贡献方式.md](代码贡献方式.md)

---

## 7) 附属信息（Meta）

### 7.1 测试
- 后端：按模块执行 Maven 测试/构建。
- 前端：至少执行 `pnpm typecheck` 或 `pnpm build`。

### 7.2 FAQ（5 分钟解决高频问题）

**Q1：为什么我只改了一个模块，构建却很慢？**  
A：优先用 `-pl <module> -am` 按模块启动/构建，避免全量编译。

**Q2：数据库脚本到底怎么执行？**  
A：新库跑 `init-*.sql`；老库只跑 `db/migration` 且按版本升序执行。

**Q3：前端依赖要用 npm 还是 pnpm？**  
A：统一使用 `pnpm`（仓库默认约定）。

**Q4：为什么有些 API 是 `/api/v1/*`，有些是 `/api/v2/*`？**  
A：`security-v1` 是权限治理独立域；`chat-v2` 是对话域主线，二者按模块边界分版本前缀。

**Q5：SSE 对话没有返回，如何排查？**  
A：先确认后端接口是 `GET /api/v2/sessions/chat`；再确认前端是否按 EventSource/流式文本消费；最后看模型与检索配置是否可用。

**Q6：为什么我能打开前端但页面 404？**  
A：请确认当前前端对应的后端模块已启动，且 `VITE_API_BASE` / 代理目标端口与后端一致。

**Q7：为什么 `Address already in use`？**  
A：优先检查本机是否已有同端口进程占用（数据库、旧 Java 进程、旧 Vite 进程）。当前默认端口已做解耦，但仍建议先 `netstat`/任务管理器确认端口空闲。

### 7.3 变更日志
建议通过 Releases/提交记录查看版本演进；后续可补充 `CHANGELOG.md`。

### 7.4 许可证
本项目遵循 [LICENSE](LICENSE)。

### 7.5 致谢
感谢 Spring 生态、LangChain4j 社区、MCP 生态与所有贡献者。

---

## 延伸阅读
- [技术白皮书.md](技术白皮书.md)
- [代码贡献方式.md](代码贡献方式.md)
- [langchain4j-spring-ai/pom.xml](langchain4j-spring-ai/pom.xml)