docs: 完善 README 项目说明文档
- 添加项目概述和核心功能介绍 - 完善技术栈说明 - 补充详细的项目结构 - 添加多种启动方式说明 - 添加配置说明和开发指南 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
348
README.md
348
README.md
@@ -1,75 +1,329 @@
|
||||
# X-Agents
|
||||
|
||||
前后端分离项目，前端使用 Vue 3 + Vite，后端支持 Python/Java
|
||||
企业级智能体平台，支持多 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/
|
||||
├── web/ # 前端项目 (Vue 3 + Vite + TypeScript + Tailwind CSS)
|
||||
│ ├── src/ # 前端源代码
|
||||
│ │ ├── components/ # Vue 组件
|
||||
│ │ ├── views/ # 页面视图
|
||||
│ │ ├── router/ # 路由配置
|
||||
│ │ ├── App.vue # 根组件
|
||||
│ │ ├── main.ts # 入口文件
|
||||
│ │ └── style.css # 全局样式
|
||||
│ ├── public/ # 静态资源
|
||||
│ ├── index.html # 入口 HTML
|
||||
│ ├── package.json # 前端依赖
|
||||
│ ├── vite.config.ts # Vite 配置
|
||||
│ ├── tailwind.config.js # Tailwind 配置
|
||||
│ └── tsconfig.json # TypeScript 配置
|
||||
├── server/ # Go API Gateway
|
||||
│ ├── cmd/api/ # 程序入口
|
||||
│ ├── internal/
|
||||
│ │ ├── config/ # 配置管理
|
||||
│ │ ├── handler/ # HTTP 处理器
|
||||
│ │ ├── service/ # 业务逻辑层
|
||||
│ │ ├── repository/ # 数据访问层
|
||||
│ │ ├── middleware/ # 中间件
|
||||
│ │ └── model/ # 数据模型
|
||||
│ ├── config/ # 配置文件
|
||||
│ ├── Dockerfile
|
||||
│ └── go.mod
|
||||
│
|
||||
└── src/ # 后端代码 (Python/Java)
|
||||
└── (待开发)
|
||||
├── 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 # 项目说明
|
||||
```
|
||||
|
||||
## 前端技术栈
|
||||
## 快速开始
|
||||
|
||||
- Vue 3
|
||||
- Vite
|
||||
- TypeScript
|
||||
- Tailwind CSS
|
||||
- Pinia (状态管理)
|
||||
- Vue Router
|
||||
- ECharts
|
||||
- Font Awesome
|
||||
### 前置要求
|
||||
|
||||
## 前端操作
|
||||
- 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
|
||||
```
|
||||
|
||||
### 安装依赖
|
||||
|
||||
```bash
|
||||
npm install
|
||||
```
|
||||
|
||||
### 开发模式
|
||||
|
||||
```bash
|
||||
npm run dev
|
||||
```
|
||||
|
||||
启动开发服务器，默认访问 http://localhost:5173
|
||||
前端将在 http://localhost:5173 启动
|
||||
|
||||
### 构建生产版本
|
||||
### 方式三：使用启动脚本（Windows）
|
||||
|
||||
```bash
|
||||
npm run build
|
||||
```powershell
|
||||
.\start-local.ps1
|
||||
```
|
||||
|
||||
### 预览生产版本
|
||||
此脚本会自动启动数据库、Go 服务和前端服务。
|
||||
|
||||
```bash
|
||||
npm run preview
|
||||
## 配置说明
|
||||
|
||||
### 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 配置
|
||||
|
||||
后端代码请放在 `src/` 目录下，支持 Python 或 Java。
|
||||
编辑 `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
|
||||
|
||||
Reference in New Issue
Block a user