From 54473bc3788b6330368c13034ce88e34e6aa68cb Mon Sep 17 00:00:00 2001 From: "DESKTOP-72TV0V4\\caoxiaozhu" Date: Mon, 9 Mar 2026 16:10:29 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E5=AE=8C=E5=96=84=20README=20=E9=A1=B9?= =?UTF-8?q?=E7=9B=AE=E8=AF=B4=E6=98=8E=E6=96=87=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 添加项目概述和核心功能介绍 - 完善技术栈说明 - 补充详细的项目结构 - 添加多种启动方式说明 - 添加配置说明和开发指南 Co-Authored-By: Claude Opus 4.6 --- README.md | 348 ++++++++++++++++++++++++++++++++++++++++++++++-------- 1 file changed, 301 insertions(+), 47 deletions(-) diff --git a/README.md b/README.md index 0d6d712..5e33c8c 100644 --- a/README.md +++ b/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 +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