# Agent-Server

**Repository Path**: leafyl/agent-server

## Basic Information

- **Project Name**: Agent-Server
- **Description**: agent服务
- **Primary Language**: C#
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2025-10-29
- **Last Updated**: 2025-12-15

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# SPI.AgentServer - 智能查询服务

基于 C# .NET 8 开发的智能自然语言查询服务，集成 Qwen2.5 大模型，支持自然语言转 SQL 查询。

## 功能特性

- 🤖 **自然语言查询**：支持中文自然语言输入，自动理解查询意图
- 🛡️ **SQL 安全验证**：内置 SQL 注入防护，只允许只读查询
- 🔧 **智能工具选择**：根据查询复杂度自动选择合适的执行工具
- 📊 **多数据库支持**：支持 SQL Server、PostgreSQL、MySQL
- 🔍 **元数据管理**：自动获取和缓存数据库结构信息
- 📝 **审计日志**：完整的查询日志和性能监控

## 快速开始

### 环境要求

- .NET 8.0 SDK
- SQL Server/PostgreSQL/MySQL（至少一个）
- Qwen2.5 模型服务（已部署）

### 安装步骤

1. 克隆仓库

```bash
cd E:\Lx_Work\jyd_xm\SPI.CoreServer\SPI.AgentServer
```

2. 恢复依赖

```bash
dotnet restore
```

3. 配置数据库连接
   编辑 `appsettings.json`，配置您的数据库连接信息：

```json
{
  "Database": {
    "Connections": [
      {
        "Name": "Main",
        "Provider": "SqlServer",
        "ConnectionString": "Your connection string here",
        "IsDefault": true
      }
    ]
  }
}
```

4. 运行服务

```bash
dotnet run
```

服务将在以下地址启动：

- HTTP: `http://localhost:5000`
- HTTPS: `https://localhost:5001`
- **Swagger UI**: `http://localhost:5000` （开发环境自动打开）
- **测试页面**: `http://localhost:5000/test.html`

## API 使用

### Swagger UI 文档

服务启动后会自动打开 Swagger UI，您可以：

- 查看所有 API 接口文档
- 在线测试 API 接口
- 查看请求和响应示例
- 下载 OpenAPI 规范文件

访问地址：`http://localhost:5000`

### 网页测试工具

内置了一个美观的网页测试工具：`http://localhost:5000/test.html`

### Apifox 集成

支持导入到 Apifox 进行 API 测试：

1. 在 Apifox 中选择「导入」→「URL 导入」
2. 输入：`http://localhost:5000/swagger/v1/swagger.json`
3. 完成导入后即可使用 Apifox 的全部功能

### 查询接口

**POST** `/api/agent/query`

请求示例：

```json
{
  "query": "查看最近7天的订单数量",
  "sessionId": "optional-session-id",
  "databaseName": "Main"
}
```

响应示例：

```json
{
  "success": true,
  "summary": "最近7天共有156个订单",
  "data": {
    "columns": ["order_date", "order_count"],
    "rows": [
      { "order_date": "2025-10-09", "order_count": 23 },
      { "order_date": "2025-10-10", "order_count": 18 }
    ]
  },
  "metadata": {
    "sessionId": "xxx",
    "executionTimeMs": 245,
    "executedSql": "SELECT ...",
    "rowCount": 7
  }
}
```

### 其他接口

- **GET** `/api/health` - 基础健康检查
- **GET** `/api/health/detailed` - 详细健康状态
- **GET** `/api/health/alive` - 快速存活检查
- **GET** `/api/health/ready` - 就绪检查
- **GET** `/api/schema/databases` - 列出可用数据库
- **GET** `/api/schema/tables?database=Main` - 列出数据库中的表
- **GET** `/api/schema/table/{tableName}?database=Main` - 获取表结构
- **POST** `/api/schema/refresh` - 刷新元数据缓存

## 支持的查询类型

### 简单查询

- "查看用户表有多少条记录"
- "显示产品表的结构"
- "今天有多少订单"

### 复杂查询

- "统计每个部门的平均工资"
- "查看上个月销售额最高的 10 个产品"
- "分析最近 30 天的用户活跃度趋势"

### 预置查询（用于分区表等复杂场景）

- "用户活动汇总报表"
- "跨区域销售统计"

## 配置说明

### Qwen 模型配置

```json
{
  "Qwen": {
    "BaseUrl": "http://188.18.57.151:23333",
    "Model": "Qwen2.5-VL-7B-Instruct",
    "MaxTokens": 2000,
    "Temperature": 0.7,
    "Timeout": 180,
    "ConnectionMode": "direct"
  }
}
```

**连接模式说明：**

- `direct`：直接连接（推荐 Windows 环境）
- `ssh`：通过 SSH 隧道连接（Linux 环境）
- `local`：本地转发模式

### 🔥 连接保活和故障恢复

系统已配置完善的连接保活和自动恢复机制，**解决长时间空闲后卡死问题**：

#### HttpClient 连接池管理

- ✅ **连接生命周期**：连接最长存活 5 分钟后自动重建
- ✅ **空闲超时**：空闲 2 分钟后释放连接，避免僵尸连接
- ✅ **TCP KeepAlive**：每 30 秒发送保活包，保持连接活跃
- ✅ **自动重试**：失败后自动重试 3 次（2 秒、4 秒、8 秒指数退避）
- ✅ **熔断保护**：连续 5 次失败后熔断 30 秒，避免雪崩

#### SSH 隧道保活（如启用）

- ✅ **ServerAliveInterval**：每 30 秒发送保活包
- ✅ **健康检查**：每 60 秒检查隧道状态
- ✅ **自动重连**：检测到断开后自动重建隧道

#### 健康检查端点

- `GET /api/health` - 基础健康检查
- `GET /api/health/detailed` - 详细健康状态（含依赖项）
- `GET /api/health/alive` - 快速存活检查（负载均衡器）
- `GET /api/health/ready` - 就绪检查（K8s 就绪探针）

**日志监控：**

```
✅ 使用真实 Qwen 大模型客户端（已配置连接保活和重试策略）
🔍 SSH隧道健康检查已启动（每60秒检查一次）
⚠️ Qwen API 请求失败，第 1 次重试（2秒后）...
✅ SSH隧道已成功重启
```

### 安全配置

```json
{
  "Security": {
    "EnableSqlValidation": true,
    "EnableSensitiveDataMasking": true,
    "AllowedOperations": ["SELECT"],
    "BlockedKeywords": ["DROP", "DELETE", "UPDATE"],
    "SensitiveFields": ["password", "token"]
  }
}
```

## 开发指南

### 项目结构

```
SPI.AgentServer/
├── Controllers/          # API 控制器
├── Services/            # 业务服务
│   ├── AI/             # AI 模型集成
│   ├── Metadata/       # 元数据管理
│   ├── Tools/          # 查询工具
│   ├── Security/       # 安全验证
│   ├── Execution/      # SQL 执行
│   └── Orchestration/  # 流程编排
├── Models/             # 数据模型
├── Configuration/      # 配置类
└── Validators/         # 请求验证

```

### 添加新工具

1. 实现 `IQueryTool` 接口
2. 在 `PromptManager` 中注册工具定义
3. 在 `ToolExecutor` 中添加工具映射
4. 在 DI 容器中注册工具

## 监控和日志

日志文件位置：`logs/agent-server-{date}.txt`

日志包含：

- 请求和响应信息
- SQL 执行详情
- 模型交互记录
- 性能指标
- 错误和异常

## 注意事项

1. 确保 Qwen 模型服务可访问
2. 数据库用户需要有读取权限
3. 建议配置适当的查询超时时间
4. 生产环境建议启用 HTTPS
5. 定期检查和更新安全规则

## 故障排查

### 问题：长时间不使用后，再次请求卡死或超时

**原因：** 连接空闲超时导致底层 TCP 连接断开

**解决方案：** ✅ **已自动修复**

- HttpClient 已配置连接池管理和 KeepAlive
- 失败后自动重试，无需手动干预
- SSH 隧道（如启用）配置了自动健康检查和重连

**监控方法：**

```bash
# 检查服务健康状态
curl http://localhost:8215/api/health/detailed

# 查看实时日志
tail -f logs/agent-server-*.txt
```

### 问题：Qwen API 连接失败

**检查步骤：**

1. 确认 Qwen 服务正在运行
2. 测试网络连通性：`ping 188.18.57.151`
3. 测试端口可用性：`telnet 188.18.57.151 23333`
4. 查看详细健康状态：`GET /api/health/detailed`

**自动恢复：**

- 系统会自动重试 3 次
- 连续失败后熔断 30 秒再恢复
- SSH 隧道每 60 秒自动检查并重连

## 相关文档

- [Swagger & Apifox 使用指南](SwaggerAPI使用指南.md) - 详细的 API 测试工具使用说明
- [完整使用说明](使用说明.md) - 系统功能和配置的完整文档

## License

内部使用，请勿外传。