# mes-agent

**Repository Path**: mescloud/mes-agent

## Basic Information

- **Project Name**: mes-agent
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 1
- **Created**: 2025-11-19
- **Last Updated**: 2026-03-06

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Agent Service

基于Spring Cloud的AI智能代理平台，提供对话管理、知识检索和RAG增强能力。

## 🏗️ 架构设计

```
agent-platform (父POM)
├── agent-gateway     # API网关 - 统一入口和安全认证
├── agent-web         # Web接口层 - 响应式API服务
├── agent-core        # 核心业务层 - AI模型抽象和工作流
├── agent-infra       # 基础设施层 - 数据存储和技术实现
└── agent-admin       # 管理监控层 - 系统监控和管理
```

## 🚀 技术栈

- **网关**: Spring Cloud Gateway + Spring Security
- **Web框架**: Spring WebFlux (响应式编程)
- **AI集成**: LangChain4j + OpenAI/智谱AI/DeepSeek
- **向量数据库**: Qdrant
- **数据存储**: MongoDB + Redis + MySQL
- **认证**: JWT (双令牌机制)
- **监控**: Spring Boot Admin + Micrometer

## 📦 核心功能

- **多AI提供商支持**: OpenAI、智谱AI、DeepSeek等
- **向量数据库**: Qdrant高性能向量搜索
- **RAG增强检索**: 知识库问答和文档检索
- **响应式对话**: 支持流式和同步聊天
- **多租户支持**: 企业级租户隔离
- **实时监控**: 应用健康检查和性能指标

## ⚡ 快速启动

### 环境要求
- JDK 17+
- Maven 3.8+
- MongoDB 5.0+
- Redis 6.0+
- MySQL 8.0+
- Qdrant 1.7+

### Profiles（重要）
默认 `spring.profiles.active` 为 `prod`（见 `agent-web/src/main/resources/application.yaml`），会加载 `application-prod.yaml` 并尝试连接远端 MySQL/Redis/Mongo 等依赖。

本地开发建议使用 `local`（`agent-web/src/main/resources/application-local.yaml`），避免因远端网络不可达导致 `CannotGetJdbcConnectionException` / `Communications link failure`：

```bash
# 1) 启动本地依赖（MySQL/Redis/Mongo/Qdrant）
docker compose -f ../docker/docker-compose-agent-local.yml up -d

# 2) 启动 agent-web（任选其一）
SPRING_PROFILE_ACTIVE=local mvn spring-boot:run -pl agent-web
# 或
mvn spring-boot:run -pl agent-web -Dspring-boot.run.jvmArguments="-Dspring.profiles.active=local"
```

### 启动步骤

1. **启动基础服务**
```bash
# 启动 Qdrant
docker run -p 6333:6333 -p 6334:6334 qdrant/qdrant:latest

# 启动数据库服务 (根据实际环境)
# MongoDB, Redis, MySQL 需要提前启动
```

2. **配置环境变量（仅向量数据库等必要配置）**
```bash
export QDRANT_HOST=localhost
export QDRANT_PORT=6333
export QDRANT_API_KEY=your-qdrant-key    # 如启用 Qdrant API Key
```

> 说明：LLM 的 API Key（如智谱 / OpenAI）统一在数据库表 `chat_llm_model_config` 中维护，
> 不再通过环境变量 `ZHIPU_API_KEY` / `OPENAI_API_KEY` 重复配置。

3. **运行服务**
```bash
# 统一入口启动
mvn spring-boot:run -pl agent-web

# 或使用脚本
./start-agent-service.sh local 8889
```

4. **访问服务**
- API服务: http://localhost:8889
- 健康检查: http://localhost:8889/health
- 管理面板: http://localhost:8888/admin

## 📚 主要API接口

### 对话管理
```http
POST /api/v1/conversation/sessions          # 创建会话
GET /api/v1/conversation/sessions/{id}       # 获取会话详情
POST /api/v1/conversation/sessions/{id}/messages  # 发送消息
```

### AI聊天
```http
GET /api/v1/real-chat/stream?message=hello&agentType=production_manager  # 流式聊天
POST /api/v1/real-chat/completions         # 同步聊天
POST /api/v1/rag/search                    # RAG知识检索（Dataset/Task 范围由 filters 控制）
```

### Agent管理
```http
GET /api/v1/agents/types                   # 获取专家类型
POST /api/v1/agents/sessions              # 创建Agent会话
GET /api/v1/agents/sessions/{id}/messages # 获取会话消息
```

### 支持的专家角色
- `production_manager`: 生产经理专家
- `quality_engineer`: 质量工程师专家
- `equipment_manager`: 设备管理专家
- `warehouse_manager`: 仓储管理专家
- `process_engineer`: 工艺工程师专家

### 示例请求
```bash
# 流式聊天
curl "http://localhost:8889/api/v1/real-chat/stream?message=你好&agentType=production_manager"

# 同步聊天
curl -X POST http://localhost:8889/api/v1/real-chat/completions \
  -H "Content-Type: application/json" \
  -d '{"message":"分析生产OEE","agentType":"production_manager"}'
```

## ⚙️ 配置说明

主要配置位于 `agent-web/src/main/resources/application*.yml`：

### MCP 外部集成（联网搜索/最新文档）
- Context7 + Google Search（SerpAPI）接入指南：`agent-web/docs/mcp-context7-serpapi.md`
- JDBC SQL 模板工具（templateQuery）：`agent-web/docs/mcp-jdbc-sql-templates.md`

### AI提供商配置（示意）
```yaml
ai:
  provider:
    type: ${AI_PROVIDER_TYPE:zhipu}
    zhipu:
      # base-url / model 仍可在配置文件中声明
      base-url: https://open.bigmodel.cn/api/paas/v4
      model: glm-4
      # api-key 已迁移至 chat_llm_model_config 表，不再通过 ZHIPU_API_KEY 环境变量注入
```

### 向量数据库配置
```yaml
qdrant:
  host: ${QDRANT_HOST:localhost}
  port: ${QDRANT_PORT:6333}
  vector-size: 768
```

### 数据库配置
```yaml
spring:
  datasource:
    url: jdbc:mysql://localhost:3306/mes_chat
  data:
    redis:
      host: ${REDIS_HOST:localhost}
  data:
    mongodb:
      uri: mongodb://localhost:27017/agent-platform
```

## 🛠️ 开发指南

### 本地开发
```bash
# 启动开发环境
mvn spring-boot:run -Dspring.profiles.active=dev

# 运行测试
mvn test

# 构建项目
mvn clean package
```

### 数据库迁移
项目使用Flyway进行数据库版本管理，脚本位于 `agent-web/src/main/resources/db/migration`。

### Skills（技能/提示词片段）
- **存储表**：MySQL `chat_skill_config`（脚本：`agent-web/src/main/resources/db/migration/V37__skill_config_tables.sql`）
- **绑定方式**：Skill 不单独建“技能-智能体”关系表；绑定信息复用 `chat_agent_config.capabilities`（JSON 数组字符串），元素为 `skill_code`
- **“使用次数”含义**：当前实现为“绑定了多少个智能体”（用于前端展示），不是对话调用次数

#### Demo：创建 Skill
```bash
curl -X POST 'http://localhost:49195/api/v1/skills' \
  -H 'Content-Type: application/json' \
  -d '{
    "tenantId":"0",
    "skillCode":"production_daily_report",
    "name":"MES 生产日报输出规范",
    "type":"system",
    "description":"按固定结构输出生产日报（结论/关键数据/异常/建议）",
    "content":"你是生产日报助手。输出必须包含：\\n1) 结论\\n2) 关键数据（产量/OEE/达成率）\\n3) 异常与原因\\n4) 建议动作\\n",
    "enabled":true
  }'
```

#### Demo：绑定 Skill 到智能体
方式 1：前端在「技能管理」编辑技能，或在「能力管理」选择智能体后勾选技能并保存。

方式 2：直接更新智能体配置的 `capabilities`（JSON 数组字符串，追加 skillCode）：
```bash
curl -X PUT 'http://localhost:49195/api/v1/agent/config-admin/0/production_manager' \
  -H 'Content-Type: application/json' \
  -d '{
    "tenantId":"0",
    "agentId":"production_manager",
    "capabilities":"[\"production_daily_report\"]"
  }'
```

方式 3：批量更新某个 Skill 绑定的智能体（单次请求，适合多选绑定）：
```bash
curl -X PUT 'http://localhost:49195/api/v1/skills/production_daily_report/bindings' \
  -H 'Content-Type: application/json' \
  -d '{
    "tenantId":"0",
    "agentIds":["production_manager","quality_manager"],
    "previousAgentIds":[]
  }'
```

> 如果出现 `Table ... chat_skill_config doesn''t exist`，说明技能表未初始化：请先在数据库执行脚本 `agent-web/src/main/resources/db/migration/V37__skill_config_tables.sql`。

### GraphQL接口
- 入口: `POST /graphql`
- Schema: `agent-web/src/main/resources/graphql/schema.graphqls`
- 支持: 数据源管理、调用日志查询等CRUD操作

## 📁 项目结构

```
agent-service/
├── agent-gateway/          # API网关模块
├── agent-web/             # Web接口和统一入口
├── agent-core/            # 核心业务逻辑
├── agent-infra/           # 基础设施实现
├── agent-admin/           # 监控管理模块
├── agent-service-ddd/     # DDD架构示例
└── pom.xml               # 父POM配置
```

## 🔧 故障排除

### 常见问题
1. **AI服务连接失败**: 检查API密钥配置和网络连接
2. **向量数据库异常**: 确认Qdrant服务状态和端口
3. **Redis连接超时**: 检查Redis服务和防火墙设置
4. **MongoDB认证失败**: 验证数据库用户权限配置

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

# 检查各模块健康状态
curl http://localhost:8889/actuator/health
```

## 📄 许可证

本项目采用 MIT 许可证。

---

*最后更新: 2025-11-18*