# 四川路桥 Maas 智能体平台

企业级 AI 智能体管理平台，支持多模型接入、知识库管理、工作流编排、插件扩展等核心能力。

## 平台功能

### 基础配置
- **模型接入**：支持公域模型（OpenAI、DeepSeek、通义千问、文心一言、智谱、Gemini 等）和私域模型（Ollama、vLLM、Xinference），普通用户可自行接入模型，支持 LLM/Embedding/TTS/STT/图像生成等多种模型类型
- **工具配置**：三方工具接入，支持自定义 Python 工具、MCP 协议工具、技能工具、数据源工具、工作流工具，配置 API Key 即可使用

### 系统管理
- **用户管理**：用户的增删改查、启用禁用、密码重置
- **角色管理**：管理员、工作空间管理员、普通用户三级角色体系
- **资源授权**：细粒度的资源权限控制，支持对智能体、工具、模型、知识库四种资源类型分别授权
- **SSO 单点登录**：对接统一认证平台，OAuth2 协议，自动同步用户和角色

### 知识库
- **通用知识库**：支持文本文档上传（txt/pdf/docx/md/csv）、表格导入、文档智能切分、QA 问答对自动生成、标签管理
- **工作流知识库**：通过可视化工作流编排数据处理流程，支持数据清洗、加工、工具处理、入库等节点
- **知识库检索**：语义检索（向量相似度）、全文检索（关键词）、混合检索三种模式，支持设置相似度阈值、Top N、最大段落字符数
- **样本中心知识库**：对接样本中心系统，支持将本地文档段落推送到样本中心进行向量化入库

### 智能体
- **简单智能体**：对话模式，配置模型+提示词+知识库即可使用，支持文件上传对话
- **高级智能体**：工作流模式，35+ 节点类型（AI 对话、条件判断、循环、知识库检索、工具调用、参数提取、意图识别、文档处理、图片/视频生成理解、TTS/STT 等），支持智能体记忆（对话记忆、关键词记忆、摘要记忆）
- **智能体管理**：全生命周期管理，版本追踪与回滚，启用/禁用控制
- **智能体发布**：公开访问链接、白名单控制、访问次数限制、认证配置、嵌入代码生成

### 工具与触发器
- **工具管理**：自定义工具在线编写和调试、MCP 工具接入、技能工具、数据源工具
- **触发器**：定时触发（Cron 表达式）、事件触发（Webhook URL），支持关联智能体或工具自动执行

### 插件系统
- **插件注册封装**：统一 Schema 结构定义，标准化插件注册、参数校验与模块挂载
- **插件日常管理**：完整生命周期（安装/卸载/启用/禁用/重装）
- **插件测试验证与版本控制**：异常分类、错误码体系、测试执行与历史记录、版本管理与回滚

## 技术架构

```
┌────────────────────────────────────────────────────┐
│                    Nginx (端口 80)                   │
│         反向代理 + 前端静态文件服务                    │
└───────────┬────────────────────────┬───────────────┘
            │                        │
    ┌───────▼───────┐       ┌───────▼───────┐
    │  Django Web   │       │  前端 SPA     │
    │  (端口 8080)  │       │  (Vue 3)      │
    └───────┬───────┘       └───────────────┘
            │
    ┌───────┼───────────────┐
    │       │               │
┌───▼───┐ ┌─▼──┐ ┌─────────▼─────────┐
│ PgSQL │ │Redis│ │  Celery Worker    │
│pgvector│ │    │ │ (异步任务/定时任务) │
└───────┘ └────┘ └───────────────────┘
```

| 组件 | 技术 | 说明 |
|------|------|------|
| 后端框架 | Django 4.x + DRF | REST API 服务 |
| 异步任务 | Celery + Redis | 向量化、定时触发、数据同步 |
| 数据库 | PostgreSQL 16 + pgvector | 关系数据 + 向量检索 |
| 前端 | Vue 3 + TypeScript + Element Plus | SPA 单页应用 |
| 构建工具 | Vite 6 | 前端构建 |
| 部署 | Docker Compose + Nginx | 容器化一键部署 |

## 快速开始

```bash
# 1. 获取代码
git clone <仓库地址> && cd zhagent

# 2. 配置环境变量
cp .env.example .env
# 编辑 .env，修改 APP_TITLE、DB_PASSWORD、SSO 配置等

# 3. 一键启动
docker compose up -d

# 4. 访问平台
# 浏览器打开 http://<服务器IP>/admin/
# 默认账号：admin / admin123
```

详细部署流程见 [部署文档.md](部署文档.md)

## 项目结构

```
zhagent/
├── apps/                          # 后端 Django 应用
│   ├── maxkb/                     # Django 项目配置（settings/urls/conf）
│   ├── application/               # 智能体管理（模型/序列化器/API/工作流/对话管道）
│   ├── knowledge/                 # 知识库（文档/段落/向量检索/样本中心对接）
│   ├── models_provider/           # 模型提供商（23+ 提供商实现）
│   ├── tools/                     # 工具管理（自定义/MCP/技能/工作流工具）
│   ├── trigger/                   # 触发器（定时/事件/Webhook）
│   ├── plugin/                    # 插件系统（注册/验证/版本/测试）
│   ├── users/                     # 用户管理
│   ├── system_manage/             # 系统管理（角色/权限/资源映射）
│   ├── sso/                       # SSO 单点登录
│   ├── chat/                      # 对话服务
│   ├── oss/                       # 文件存储
│   └── static/                    # 前端构建产物
├── ui/                            # 前端 Vue 项目
│   ├── src/
│   │   ├── views/                 # 页面组件
│   │   ├── api/                   # API 接口定义
│   │   ├── router/                # 路由
│   │   ├── stores/                # Pinia 状态管理
│   │   ├── workflow/              # 工作流可视化编辑器
│   │   ├── components/            # 公共组件
│   │   └── locales/               # 国际化（中/英/繁体）
│   └── env/                       # 前端环境变量
├── docker-compose.yml             # Docker 编排文件
├── Dockerfile                     # 后端镜像构建
├── nginx.conf                     # Nginx 反向代理配置
├── .env.example                   # 环境变量模板
├── config.yml                     # 本地开发配置（不提交到仓库）
├── README.md                      # 本文件
├── 部署文档.md                     # Docker 部署指南
└── 测试文档.md                     # 功能测试用例
```

## 环境变量说明

所有配置通过项目根目录 `.env` 文件统一管理（Docker 部署时自动读取）。

| 分类 | 变量名 | 说明 | 示例 |
|------|--------|------|------|
| 平台 | APP_TITLE | 平台显示名称 | 四川路桥Maas智能体平台 |
| 平台 | APP_VERSION | 版本号 | v1.0 |
| 数据库 | DB_HOST | 数据库地址 | 127.0.0.1 |
| 数据库 | DB_PORT | 数据库端口 | 5432 |
| 数据库 | DB_USER | 数据库用户 | postgres |
| 数据库 | DB_PASSWORD | 数据库密码 | （必须修改） |
| 数据库 | DB_NAME | 数据库名 | maxkb |
| Redis | REDIS_HOST | Redis 地址 | 127.0.0.1 |
| Redis | REDIS_PORT | Redis 端口 | 6379 |
| Redis | REDIS_PASSWORD | Redis 密码 | （可为空） |
| SSO | SSO_BASE_URL | SSO 认证服务地址 | http://sso-server:8200 |
| SSO | SSO_CLIENT_ID | SSO 应用标识 | - |
| SSO | SSO_CLIENT_SECRET | SSO 应用密钥 | - |
| SSO | SSO_REDIRECT_URI | SSO 回调地址 | http://平台地址/admin/auth/callback |
| SSO | SSO_LOGOUT_REDIRECT_URL | 登出跳转地址 | - |
| 样本中心 | SAMPLE_CENTER_BASE_URL | 样本中心地址 | - |
| 样本中心 | SAMPLE_CENTER_APP_ID | 样本中心应用标识 | - |
| 样本中心 | SAMPLE_CENTER_APP_SECRET | 样本中心应用密钥 | - |
| 服务 | DEBUG | 调试模式 | false |
| 服务 | LANGUAGE_CODE | 默认语言 | zh-CN |

## 本地开发

```bash
# 后端
cd apps
# 确保 config.yml 已配置数据库和 Redis 连接
python main.py dev web      # 启动 Web 服务
python main.py dev celery   # 启动 Celery Worker（另一个终端）

# 前端
cd ui
npm install
npm run dev                 # 启动开发服务器（端口 8080）
```

前端开发服务器会自动代理 API 请求到后端 8080 端口。