# lyai

**Repository Path**: lyzyp/lyai

## Basic Information

- **Project Name**: lyai
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-07-30
- **Last Updated**: 2026-07-30

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

<div align="center">
  <h1>LyAI — 企业级 AI 智能体管理与数据分析平台</h1>
  <p>
    <strong>基于 <a href="https://github.com/alibaba/spring-ai-alibaba" target="_blank">Spring AI Alibaba 2.0.0-M1.1</a> 的企业级 Agent 引擎</strong>
  </p>
  <p>
    NL2SQL 智能报表 | Python 深度分析 | 多范式 Agent | MCP 协议 | RAG 增强 | Vben5 管理后台
  </p>
  <p>
    <img src="https://img.shields.io/badge/Spring%20Boot-4.0.0-blue" alt="Spring Boot">
    <img src="https://img.shields.io/badge/Spring%20AI-2.0.0--M1-green" alt="Spring AI">
    <img src="https://img.shields.io/badge/Java-21-orange" alt="Java">
    <img src="https://img.shields.io/badge/MyBatis--Flex-1.11.7-lightgrey" alt="MyBatis-Flex">
    <img src="https://img.shields.io/badge/Vben-5-blueviolet" alt="Vben5">
    <img src="https://img.shields.io/badge/License-Apache%202.0-red" alt="License">
  </p>
  <p>
    <a href="#-项目简介">项目简介</a> •
    <a href="#-核心特性">核心特性</a> •
    <a href="#-技术栈">技术栈</a> •
    <a href="#-模块架构">模块架构</a> •
    <a href="#-快速开始">快速开始</a> •
    <a href="#-文档导航">文档导航</a>
  </p>
</div>

<br/>

## 📖 项目简介

**LyAI** 是基于 **Spring AI Alibaba Graph** 打造的企业级 AI 智能体管理与数据分析平台，以 **策略模式** 为核心设计理念，支持多种 Agent 范式的统一编排与调度。

### 核心能力

- **NL2SQL 智能报表** — StateGraph 驱动的自然语言转 SQL 引擎，支持 7 种主流数据库的即开即用查询
- **多范式 Agent 框架** — React Agent / Workflow Graph / Harness（HITL）三种模式，通过 `AgentExecutor` 策略接口统一管理
- **Python 深度分析** — Docker/Local 双模式沙箱，自动生成并执行 Python 统计分析代码
- **RAG 检索增强** — 混合检索（向量 + 关键词 + RRF 融合排序），集成 pgvector / Elasticsearch
- **MCP 协议** — 原生支持 MCP Server / Client，可接入 Claude Desktop 等生态工具
- **RBAC 权限体系** — 用户-角色-部门-公司四级权限 + API Key 细粒度管控
- **三方平台集成** — 钉钉 / 飞书 / 企业微信组织同步与消息推送

### 架构亮点

- **策略模式引擎** — `AgentExecutionEngine` 替代传统 if-else 路由，新增 Agent 类型只需实现 `AgentExecutor` 接口
- **统一响应体** — `R<T>` 统一封装所有 API 返回，自动注入 TraceId 实现全链路追踪
- **中间件链** — Agent 执行前后的日志、限流、追踪等横切关注点通过 `AgentMiddlewareChain` 统一管理
- **无环依赖** — `common ← core ← admin` 和 `common ← platform ← admin`，模块边界清晰

<br/>

## ✨ 核心特性

| 特性 | 说明 |
| :--- | :--- |
| **多范式 Agent** | React Agent（推理-行动-观察循环）、Workflow Graph（有向图编排）、Harness（HITL 人工干预） |
| **NL2SQL 全链路** | 意图识别 → 证据召回 → Schema 召回 → 表关系推断 → 可行性评估 → Planner → SQL/Python 执行 → 报告生成 |
| **Python 沙箱** | Docker 容器隔离 + Local Python3，自动代码生成，支持统计分析、机器学习、ECharts 可视化 |
| **混合检索 RAG** | pgvector 向量检索 + 关键词检索 + RRF 融合排序，支持动态过滤表达式 |
| **MCP 协议** | 作为 Tool Server 对外暴露 NL2SQL 能力，可被 Claude Desktop 等 MCP 客户端调用 |
| **多模型热切换** | 运行时动态切换 LLM 和 Embedding 模型，无需重启 |
| **多数据源** | MySQL / PostgreSQL / Oracle / SQL Server / H2 / Hive / 达梦 DM |
| **Agent 记忆** | RedisSaver 短期检查点 + 用户画像 / 事实记忆 / 向量语义检索长期记忆 |
| **全链路追踪** | OpenTelemetry → Langfuse，LLM 调用 Token 用量、延迟全程可观测 |
| **HITL 人工干预** | 高风险操作暂停等人工确认，支持 RequireUserConfirm 事件 |
| **多租户** | 租户隔离 + 钉钉 / 飞书 / 企业微信三方登录 |
| **Vben5 管理后台** | Vue 3 + TypeScript + Vben Admin 5 现代化管理界面 |

<br/>

## 🛠 技术栈

| 层级 | 技术 | 版本 | 说明 |
| :--- | :--- | :--- | :--- |
| **应用框架** | Spring Boot | 4.0.0 | 响应式 WebFlux |
| **AI 基础** | Spring AI | 2.0.0-M1 | ChatModel、向量存储、@Tool 注解 |
| **Agent 框架** | Spring AI Alibaba | 2.0.0-M1.1 | ReactAgent、StateGraph、RedisSaver |
| **ORM** | MyBatis Flex | 1.11.7 | 注解驱动、代码生成 |
| **权限** | Sa-Token | 1.45.0 | RBAC + Reactor 适配 |
| **数据库** | PostgreSQL + pgvector | 14+ | 业务数据 + 向量存储 |
| **缓存** | Redis + Redisson | 7.x | Session / 检查点 / 分布式锁 |
| **可观测** | OpenTelemetry | 1.32.0 | 全链路 Tracing |
| **文档** | Springdoc OpenAPI | 2.8.17 | Swagger UI |
| **构建** | JDK 21 + Maven | 3.9+ | CI-Ready 扁平化 POM |

<br/>

## 🏗️ 模块架构

```
lyai/
├── pom.xml                 ← com.zyp:lyai (根 POM，含所有依赖管理)
│
├── lyai-common/            ← ① 公共基础（零业务依赖）
│   ├── exception/              统一异常体系（BaseException、ErrorCode）
│   ├── response/               统一响应体 R<T>
│   ├── auth/                   认证共享类型（BaseEntity、PrivilegeUser）
│   ├── enm/                    全局枚举（AgentType、PlatformType 等）
│   ├── model/vo/config/       基础模型、VO、通用配置
│   └── util/                   工具类（SqlSecurityValidator）
│
├── lyai-core/              ← ② 业务核心（占 80%+ 代码量）
│   ├── agent/                  Agent 框架层
│   │   ├── api/                AgentExecutor 策略接口 + AgentMiddleware 中间件
│   │   ├── engine/             AgentExecutionEngine 策略引擎
│   │   ├── react/              ReactAgentExecutor + BPM / 制度分析助手
│   │   ├── workflow/           WorkflowAgentExecutor + Parol 工作流
│   │   └── harness/            HarnessAgentExecutor（HITL 人工干预）
│   ├── data/                   NL2SQL 领域
│   │   ├── workflow/           StateGraph 节点 + Dispatcher（19 个节点 / 11 个路由）
│   │   ├── connector/          7 种数据库连接器（MySQL、PG、Oracle、SQLServer、H2、Hive、达梦）
│   │   └── service/            应用服务（NL2SQL / Schema / Python 沙箱 / 混合检索）
│   ├── knowledge/              RAG 知识库
│   ├── chat/                   会话管理 + 消息系统
│   ├── model/                  AI 模型动态配置工厂
│   ├── controller/             REST API 接口层
│   └── infrastructure/         基础设施（缓存 / 文件 / 事件 / AOP）
│
├── lyai-platform/          ← ③ 平台治理
│   ├── auth/                   RBAC 认证授权（登录 / 用户 / 角色 / 权限 / 模块）
│   ├── org/                    组织管理 + 三方同步策略（钉钉 / 飞书 / 企微）
│   └── channel/                消息通道 SDK
│
├── lyai-server/             ← ④ 启动入口（端口 8066）
│   └── LyAgentApplication     @SpringBootApplication
│
├── lyai-web/           ← ⑤ 前端（Vue 3 + pnpm Monorepo）
├── sql/                    ← 数据库脚本（DDL + 初始数据）
└── docs/                   ← 项目文档
```

### 依赖关系（单向无环）

```
                    lyai-common (最底层)
                    ↗          ↖
             lyai-core      lyai-platform
                    ↘       ↗
                   lyai-server (最顶层，启动器)
```

> **铁律**：common 不依赖任何业务模块；core 与 platform 之间无循环依赖。

### lyai-core 内部详解

**Agent 框架层** (`agent/`) 采用策略模式：

```
新增 Agent 类型 = 3 步，核心引擎零改动：
1. 新建 XxxAgentExecutor implements AgentExecutor
2. 加 @Component
3. 实现 supportedSns() + stream()
```

| 范式 | 执行器 | 技术实现 |
| :--- | :--- | :--- |
| **React Agent** | `ReactAgentExecutor` | Spring AI Alibaba ReactAgent + ChatModel + RedisSaver + Hook |
| **Workflow Graph** | `WorkflowAgentExecutor` | Spring AI Alibaba StateGraph + CompiledGraph + RedisSaver |
| **Harness (HITL)** | `HarnessAgentExecutor` | AgentScope HarnessAgent + RequireUserConfirm 人工干预 |

**NL2SQL 工作流**（StateGraph 驱动，19 个节点）：

```
IntentRecognition → EvidenceRecall → QueryEnhance → SchemaRecall
→ TableRelation → FeasibilityAssessment → Planner → PlanExecutor
→ [SqlGenerate → SemanticConsistency → SqlExecute] 或
  [PythonGenerate → PythonExecute → PythonAnalyze] 或
  [ReportGenerator] 或 [HumanFeedback]
```

<br/>

## 🚀 快速开始

### 环境要求

| 组件 | 版本 | 说明 |
| :--- | :--- | :--- |
| JDK | 21+ | 必须 |
| Maven | 3.9+ | 必须，需在 PATH 中 |
| PostgreSQL | 14+ | 必须，含 pgvector 扩展 |
| Redis | 7+ | 必须 |
| Docker | — | 可选，Python 深度分析需要 |

### 启动步骤

```bash
# 1. 克隆项目
git clone https://gitee.com/lyzyp/lyai.git
cd lyai

# 2. 创建数据库并导入数据
psql -U postgres -c "CREATE DATABASE lyai;"
psql -U postgres -d lyai < sql/all_schema.sql
psql -U postgres -d lyai < sql/all_data.sql
## 注意：PostgreSQL 需安装 pgvector 向量扩展

# 3. 构建项目
mvn clean install -Dspring-javaformat.skip=true

# 4. 启动服务（端口 8066）
mvn spring-boot:run -pl lyai-server
```

### 环境变量

| 变量 | 必填 | 说明 | 默认值 |
| :--- | :--- | :--- | :--- |
| `SPRING_AI_DASHSCOPE_API_KEY` | 是 | DashScope API Key | — |
| `SPRING_DATASOURCE_URL` | 否 | PostgreSQL JDBC URL | `jdbc:postgresql://127.0.0.1:5432/lyai` |
| `SPRING_DATASOURCE_USERNAME` | 否 | 数据库用户名 | `postgres` |
| `SPRING_DATASOURCE_PASSWORD` | 否 | 数据库密码 | `123456` |
| `SPRING_DATA_REDIS_HOST` | 否 | Redis 地址 | `127.0.0.1` |

### 验证

```bash
# 健康检查
curl http://localhost:8066/echo/ok

# 流式查询示例
curl -N "http://localhost:8066/api/stream/search?agentId=1&query=上个月销售额是多少"
```

<br/>

## 🗄️ 数据库支持

### 目标数据源

| 数据库 | 驱动 | 标识 |
| :--- | :--- | :--- |
| MySQL | mysql-connector-j | `mysql` |
| PostgreSQL | postgresql 42.4.1 | `postgresql` |
| Oracle | ojdbc8 | `oracle` |
| SQL Server | mssql-jdbc | `sqlserver` |
| H2 | h2 2.3.232 | `h2` |
| Hive | hive-jdbc 3.1.3 | `hive` |
| 达梦 DM | DmJdbcDriver18 | `dameng` |

### 向量存储

| 存储 | 说明 |
| :--- | :--- |
| PostgreSQL pgvector | 默认向量库（HNSW 索引，余弦距离，512 维） |
| Elasticsearch | 可选方案，支持 DenseVector / SparseVector |

### 应用存储

- **PostgreSQL** — 业务数据（智能体、会话、知识库、权限、用户）
- **Redis** — Graph 状态检查点（RedisSaver）、缓存、分布式锁、Session

<br/>

## 🔧 开发命令

| 命令 | 说明 |
| :--- | :--- |
| `mvn clean compile -pl lyai-server -am` | 增量编译（推荐） |
| `mvn clean install -Dspring-javaformat.skip=true` | 全量构建（跳过格式检查） |
| `mvn spring-boot:run -pl lyai-server` | 启动应用（端口 8066） |
| `mvn compile -pl lyai-core -am -DskipTests` | 仅编译 core 模块 |

<br/>

## 📚 文档导航

| 文档 | 内容 |
| :--- | :--- |
| [架构设计](docs/ARCHITECTURE.md) | 系统分层架构、StateGraph 工作流设计、核心时序图 |
| [快速启动指南](docs/快速启动指南.md) | 环境要求、数据库导入、基础配置 |
| [开发者指南](docs/DEVELOPER_GUIDE.md) | 开发环境搭建、配置手册、自定义 Agent 开发 |
| [高级功能](docs/ADVANCED_FEATURES.md) | API Key、MCP 配置、混合检索、Python 执行器、Langfuse |
| [知识配置](docs/KNOWLEDGE_USAGE.md) | 语义模型、业务知识、Agent 知识配置最佳实践 |
| [权限管理](docs/PRIVILEGE.md) | RBAC 权限体系（用户-角色-部门-公司） |
| [核心技术栈](docs/核心技术栈.md) | 依赖清单、模块说明、版本对照 |
| [代码注释指南](docs/代码注释生成提示词.md) | Javadoc 规范、注释模板 |

<br/>

## 📄 许可证

本项目采用 Apache License 2.0 许可证。详见 [LICENSE](LICENSE) 文件。

---

<div align="center">
  Made with ❤️ by <strong>张彦鹏</strong> & LyAI Team
</div>