v3.0.0 init

2026-04-17 13:53:41 +00:00 · 2026-02-06 03:00:23 +08:00
parent eb2e8f3ff8
commit 7b8cfe02a1
1524 changed files with 53132 additions and 58866 deletions
--- a/ruoyi-modules/ruoyi-chat/docs/数据库智能体实现总结.md
+++ b/ruoyi-modules/ruoyi-chat/docs/数据库智能体实现总结.md
@@ -0,0 +1,152 @@
+# 数据库操作智能体实现总结
+
+## 概述
+基于 LangChain4j 的 **Pure agentic AI** 模式，完成了一个智能数据库查询系统。该系统能够根据用户的自然语言问题，自动分析数据库结构、生成查询计划并执行相应的数据库操作。
+
+## 架构设计
+
+### 1. 整体框架
+```
+用户请求 → SupervisorAgent(协调器) → SqlAgent(数据库专家) → 数据库工具 → 数据库
+                                                            ↓
+                                                      结果处理与响应
+```
+
+### 2. 核心组件
+
+#### A. SqlAgent (数据库查询专家)
+- **文件**: `org.ruoyi.agent.SqlAgent`
+- **职责**: 根据用户的自然语言问题，调用相应的工具查询数据库
+- **使用的工具**:
+  - `QueryAllTablesTool`: 查询所有表名和注释
+  - `QueryTableSchemaTool`: 查询表的DDL（CREATE TABLE语句）
+  - `ExecuteSqlQueryTool`: 执行SELECT查询
+
+```java
+public interface SqlAgent {
+    @SystemMessage("...")  // 详细的系统提示
+    @UserMessage("请回答以下问题：{{query}}")
+    @Agent("一个智能数据库查询助手...")
+    String getData(@V("query") String query);
+}
+```
+
+#### B. SupervisorAgent (总体协调器)
+- 在 `OpenAIServiceImpl.doAgent()` 中创建
+- 作用：协调 SqlAgent 的执行，管理任务流程
+- 响应策略：`SUMMARY` - 返回所有操作的摘要
+
+```java
+SupervisorAgent supervisor = AgenticServices
+    .supervisorBuilder()
+    .chatModel(PLANNER_MODEL)
+    .subAgents(sqlAgent)
+    .responseStrategy(SupervisorResponseStrategy.SUMMARY)
+    .build();
+```
+
+#### C. 数据库工具 (Tools)
+
+##### 1. QueryAllTablesTool
+```java
+@Tool("Query all tables in the database and return table names and basic information")
+public String queryAllTables()
+```
+- 返回数据库中所有表的名称和注释
+- 使用注入的 `agentDataSource` DataSource
+
+##### 2. QueryTableSchemaTool
+```java
+@Tool("Query the CREATE TABLE statement (DDL) for a specific table by table name")
+public String queryTableSchema(String tableName)
+```
+- 返回指定表的建表SQL语句
+- 包含SQL注入防护（表名有效性验证）
+
+##### 3. ExecuteSqlQueryTool
+```java
+@Tool("Execute a SELECT SQL query and return the results. Example: SELECT * FROM sys_user")
+public String executeSql(String sql)
+```
+- 执行SELECT查询（安全性考虑，不允许执行其他操作）
+- 格式化查询结果，最多显示前20行
+
+### 3. 配置体系
+
+#### AgentMysqlProperties
+配置文件前缀：`agent.mysql`
+```yaml
+agent:
+  mysql:
+    enabled: true
+    url: jdbc:mysql://localhost:3306/your_database
+    username: your_username
+    password: your_password
+    max-pool-size: 10
+    min-idle: 2
+```
+
+#### AgentMysqlConfig
+- 创建独立的 DataSource Bean (`agentDataSource`)
+- 使用 HikariCP 连接池管理
+- 与项目主数据源隔离
+
+#### TableSchemaManager
+- 在应用启动时初始化表结构缓存
+- 使用 `ConcurrentHashMap` 存储结构信息
+- 支持按需刷新单个表的结构
+
+## 工作流程示例
+
+### 用户查询: "数据库有哪些表？"
+
+```
+1. SupervisorAgent 接收请求
+   ↓
+2. SupervisorAgent 分析请求，决定调用 SqlAgent
+   ↓
+3. SqlAgent 理解需求，调用 QueryAllTablesTool
+   ↓
+4. QueryAllTablesTool 连接数据库，获取所有表
+   ↓
+5. 结果返回给 SqlAgent
+   ↓
+6. SqlAgent 格式化结果
+   ↓
+7. SupervisorAgent 生成最终摘要
+   ↓
+8. 结果通过流式处理器返回给用户
+```
+
+### 用户查询: "查询 sys_user 表中有多少条记录"
+
+```
+1. SqlAgent 接收请求
+   ↓
+2. SqlAgent 分析需求，可能先调用 QueryTableSchemaTool 了解表结构
+   ↓
+3. 然后调用 ExecuteSqlQueryTool 执行 "SELECT COUNT(*) FROM sys_user"
+   ↓
+4. 获取查询结果并返回
+```
+
+## Agentic AI 特性
+
+### 自适应决策
+- Agent 能根据上下文和之前的结果决定下一步操作
+- 不是预定义的固定流程，而是动态适应
+
+### 例子
+当询问"查询部门表的字段信息时"：
+- SqlAgent 可能先调用 `QueryTableSchemaTool` 获取建表SQL
+- 如果发现需要具体的数据示例，会继续调用 `ExecuteSqlQueryTool`
+- 整个决策过程由 LLM 驱动，非硬编码
+
+## 安全考虑
+
+1. **数据源隔离**: Agent 使用独立的数据源（agentDataSource），与主应用隔离
+2. **SQL验证**: 只允许执行 SELECT 查询
+3. **表名验证**: 表名必须通过正则表达式验证（防止SQL注入）
+4. **权限限制**: 可通过 AGENT_ALLOWED_TABLES 环境变量限制可访问的表
+5. **凭证管理**: 数据库凭证通过配置文件管理，不硬编码
+