X-Agents/README.md

# X-Agents

企业级智能体平台，支持多 Agent 协作、工具调用、知识库管理、文档解析等能力。

## 项目概述

X-Agents 是一个前后端分离的智能体平台，采用微服务架构设计，提供完整的 AI Agent 管理和执行能力。

### 核心功能

- **智能体管理**：创建、配置和管理多个 AI Agent
- **工具调用**：支持多种工具的注册、调用和沙盒执行
- **知识库管理**：支持文档上传、解析、向量化存储和检索
- **文档解析**：基于 gRPC 的高性能文档解析服务，支持多种格式
- **模型管理**：支持多种 LLM 模型的配置和切换
- **安全机制**：工具白名单、人工审批、审计日志等安全控制
- **数据库集成**：支持 MySQL、Neo4j 等数据库连接和查询

## 技术栈

### 前端 (web/)
- Vue 3 - 渐进式 JavaScript 框架
- Vite - 下一代前端构建工具
- TypeScript - JavaScript 的超集
- Element Plus - Vue 3 组件库
- Tailwind CSS - 原子化 CSS 框架
- Pinia - Vue 状态管理
- Vue Router - 路由管理
- ECharts - 数据可视化

### 后端

#### Go API Gateway (server/)
- Gin - HTTP Web 框架
- GORM - ORM 库
- gRPC - 高性能 RPC 框架
- JWT - 身份认证

#### Python Agent Engine (agent/)
- FastAPI - 高性能 Web 框架
- LangChain - LLM 应用开发框架
- OpenAI SDK - OpenAI API 客户端
- Anthropic SDK - Claude API 客户端

#### AI-Core 文档解析服务 (ai-core/)
- gRPC - RPC 通信框架
- MarkItDown - 文档解析引擎
- Protocol Buffers - 数据序列化

### 数据存储
- MySQL 8.0 - 关系型数据库
- Redis - 缓存和消息队列
- Neo4j - 图数据库（可选）

## 项目结构

```
X-Agents/
├── server/                    # Go API Gateway
│   ├── cmd/api/              # 程序入口
│   ├── internal/
│   │   ├── config/           # 配置管理
│   │   ├── handler/          # HTTP 处理器
│   │   ├── service/          # 业务逻辑层
│   │   ├── repository/       # 数据访问层
│   │   ├── middleware/       # 中间件
│   │   └── model/            # 数据模型
│   ├── config/               # 配置文件
│   ├── Dockerfile
│   └── go.mod
│
├── agent/                     # Python Agent Engine
│   ├── app/
│   │   ├── agent/
│   │   │   ├── core/         # Agent 核心
│   │   │   ├── tools/        # 工具管理
│   │   │   └── memory/       # 记忆管理
│   │   ├── api/              # API 路由
│   │   ├── llm/              # LLM 适配器
│   │   └── security/         # 安全机制
│   ├── requirements.txt
│   └── Dockerfile
│
├── ai-core/                   # 文档解析服务
│   ├── parser/               # 文档解析器
│   ├── proto/                # gRPC 协议定义
│   ├── service/              # gRPC 服务实现
│   ├── requirements.txt
│   └── config.yaml
│
├── web/                      # 前端项目
│   ├── src/
│   │   ├── components/       # Vue 组件
│   │   ├── views/            # 页面视图
│   │   ├── router/           # 路由配置
│   │   └── utils/            # 工具函数
│   ├── package.json
│   ├── vite.config.ts
│   └── tailwind.config.js
│
├── docs/                     # 文档
│   └── ARCHITECTURE.md      # 架构设计文档
│
├── docker-compose.yml         # Docker 编排文件
├── docker-compose.dev.yml    # 开发环境配置
├── .env.example             # 环境变量模板
└── README.md               # 项目说明
```

## 快速开始

### 前置要求

- Docker 和 Docker Compose
- Node.js 18+
- Go 1.25+
- Python 3.9+

### 方式一：使用 Docker Compose（推荐）

1. **克隆项目**

```bash
git clone <repository-url>
cd X-Agents
```

2. **配置环境变量**

```bash
cp .env.example .env
# 根据需要修改 .env 文件中的配置
```

3. **启动所有服务**

```bash
docker-compose up -d
```

服务将在以下端口启动：
- Go API: http://localhost:8080
- Python Agent: http://localhost:8081
- 前端: http://localhost:5173
- AI-Core: localhost:50051 (gRPC)
- MySQL: localhost:3306
- Redis: localhost:6379

### 方式二：本地开发

#### 1. 启动基础服务（数据库）

```bash
docker-compose -f docker-compose.yml up -d
```

#### 2. 启动 Go API 服务

```bash
cd server
go run ./cmd/api
```

服务将在 http://localhost:8082 启动

#### 3. 启动 Python Agent 服务

```bash
cd agent
pip install -r requirements.txt
python -m app.main
```

服务将在 http://localhost:8081 启动

#### 4. 启动 AI-Core 文档解析服务

```bash
cd ai-core
pip install -r requirements.txt
python generate_grpc.py
python main.py --port 50051
```

服务将在 localhost:50051 启动

#### 5. 启动前端服务

```bash
cd web
npm install
npm run dev
```

前端将在 http://localhost:5173 启动

### 方式三：使用启动脚本（Windows）

```powershell
.\start-local.ps1
```

此脚本会自动启动数据库、Go 服务和前端服务。

## 配置说明

### Go 服务配置

编辑 `server/config/config.yaml`：

```yaml
port: "8082"
jwt_secret: "your-secret-key"

database_host: "localhost"
database_port: "3306"
database_user: "root"
database_password: "root"
database_name: "x_agents"

python_service_url: "http://localhost:8081"
ai_core_service_addr: "localhost:50051"

upload_mode: "local"
upload_local_path: "resource/files"
server_base_url: "http://localhost:8082"
```

### AI-Core 配置

编辑 `ai-core/config.yaml`：

```yaml
server:
  host: "0.0.0.0"
  port: 50051

parser:
  default_engine: "builtin"
  supported_engines:
    - builtin
    - markitdown

logging:
  level: "INFO"
```

## 开发指南

### 前端开发

```bash
cd web
npm run dev          # 启动开发服务器
npm run build        # 构建生产版本
npm run preview      # 预览生产版本
```

### 后端开发

```bash
# Go 服务
cd server
go run ./cmd/api     # 启动开发服务器
go test ./...        # 运行测试

# Python 服务
cd agent
python -m app.main   # 启动开发服务器
pytest               # 运行测试
```

### 添加新工具

1. 在 `agent/app/agent/tools/impl/` 目录下创建新工具
2. 在 `agent/app/agent/tools/registry.py` 中注册工具
3. 配置安全级别和权限

### 添加新文档解析器

1. 在 `ai-core/parser/` 目录下实现解析器类
2. 继承 `BaseParser` 并实现 `parse_into_text` 方法
3. 在 `ai-core/parser/registry.py` 中注册

## API 文档

详细 API 文档请参考 [team-require/api/](team-require/api/) 目录。

主要接口包括：
- 认证接口
- Agent 聊天接口
- 知识库管理接口
- 模型管理接口
- 数据库查询接口
- 文件上传接口

## 架构设计

详细的架构设计文档请参考 [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)。

### 安全机制

- **工具白名单**：所有工具必须在注册表中注册
- **安全分级**：工具分为 SAFE、REVIEW、DANGER 三个等级
- **人工审批**：危险操作需要人工审批
- **审计日志**：记录所有操作历史
- **沙盒执行**：代码在隔离环境中执行

## 常见问题

### 数据库连接失败

检查 MySQL 服务是否正常启动，配置文件中的数据库信息是否正确。

### 前端无法连接后端

检查后端服务是否正常启动，CORS 配置是否正确。

### 文档解析失败

检查 AI-Core 服务是否正常启动，gRPC 端口是否正确配置。

## 贡献指南

欢迎提交 Issue 和 Pull Request。

## 许可证

MIT License