Maas-Agent

四川路桥 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	容器化一键部署

快速开始

# 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

项目结构

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

本地开发

# 后端
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 端口。