# 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**: 2026-01-14

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# SPI.AgentServer - 智慧校园 AI 智能代理服务

## 项目简介

**SPI.AgentServer** 是一个专为智慧校园场景打造的后端服务系统。该项目集成了大语言模型（LLM）、自然语言转 SQL（Text-to-SQL）、数字人交互（Digital Human）以及丰富的数据查询工具。它能够理解用户的自然语言请求，自动编排并执行数据库查询、调用业务接口，最终以文本、语音或可视化图表的形式返回结果。

## 核心特性

### 1. 智能问答代理 (AI Agent)
- **自然语言查询 (NL2SQL)**: 基于 `QueryOrchestrator` 和 `Qwen` 大模型，将用户口语转化为精准的 SQL 语句。
- **查询编排**: 支持多轮对话、上下文理解以及意图识别。
- **自我学习**: 包含 `DatabaseSchemaLearner` 模块，能够自动分析并学习数据库表结构和关系。

### 2. 丰富的业务工具集 (Tools)
系统内置了约 19 个专用查询工具，覆盖智慧校园的核心业务场景：
- **基础工具**: 数据库直连查询、天气查询等。
- **设备管理**: 设备故障统计、离线设备排名、设备状态概览。
- **人员通行**: 师生进出校统计、闸机通行记录、黑名单人员活动轨迹。
- **车辆管理**: 车辆滞留查询、访客车辆统计、违规车辆分析。
- **教务与生活**: 图书馆进出记录、宿舍归寝统计。

### 3. 数字人交互 (Digital Human)
- **语音合成 (TTS)**: 集成 VITS 模型，支持高质量的语音合成。
- **口型同步 (Viseme)**: 生成与语音匹配的口型数据，驱动前端 3D 数字人模型。
- **流式响应**: 支持 Server-Sent Events (SSE) 流式传输，实现低延迟的语音和文本回复。

### 4. 数据可视化与导出
- **智能图表**: 自动根据查询结果生成 ECharts 配置，支持柱状图、折线图等。
- **报表导出**: 支持将查询结果批量导出为 Excel 或 CSV 文件。

## 技术栈

*   **核心框架**: .NET (ASP.NET Core)
*   **数据库 ORM**: SqlSugar
*   **大语言模型**: Qwen (通义千问)
*   **语音服务**: Python (VITS TTS Server)
*   **前端演示**: HTML5 + Three.js (用于数字人渲染)
*   **其他组件**: SSH Tunnel (安全连接), Swagger (API 文档)

## 系统架构

系统主要由以下核心组件构成：

1.  **AgentController**: 对外提供统一的 RESTful API 接口。
2.  **QueryOrchestrator**: 查询编排器，负责任务分发、工具选择和结果汇总。
3.  **PromptManager**: 提示词工程管理，动态构建 LLM 上下文。
4.  **DatabaseExecutor**: 安全的数据库执行单元，支持分表查询（如按月分表的闸机记录）。
5.  **ToolExecutor**: 业务工具执行引擎。

## 快速开始

### 1. 环境准备
*   .NET SDK 环境
*   MySQL 数据库
*   Python 环境（用于运行 TTS 服务，可选）

### 2. 配置文件
在 `appsettings.json` 中配置以下关键项：
*   **DatabaseConfiguration**: 配置数据库连接字符串及默认连接。
*   **QwenConfiguration**: 配置大模型 API BaseUrl、API Key 及模型名称。
*   **TTSConfiguration**: 配置 TTS 服务的地址。

### 3. 启动服务
1.  **启动 TTS 服务** (如果需要语音功能):
    进入 `VitsTTSServer` 目录并运行 Python 服务。
2.  **启动 API 服务**:
    在项目根目录下运行 .NET 应用程序。

### 4. 访问接口
服务启动后，可以通过 Swagger UI 查看和测试 API：
*   地址: `http://localhost:<端口>/swagger`

## 主要 API 模块

*   `/api/agent`: 核心问答接口，支持普通查询和流式对话。
*   `/api/digital-human`: 数字人相关接口，包含 TTS 测试和状态查询。
*   `/api/schema`: 数据库元数据管理，查看表结构。
*   `/api/export`: 数据导出服务。
*   `/api/health`: 系统健康检查。

## 前端演示

项目 `wwwroot` 目录下包含了多个演示页面，可直接预览效果：
*   `index.html`: 综合数据看板与对话界面。
*   `digital-human.html`: 3D 数字人交互演示。

## 许可证

本项目采用开源许可证，具体请查看仓库内的 LICENSE 文件。