# ZhAgentOS 2.0

企业级智能体平台 —— 强大易用的 AI Agent 构建与管理系统。

## 技术栈

| 层级 | 技术 |
|------|------|
| 后端 | Python 3.11 + Django 5.2 + DRF |
| 前端 | Vue 3 + TypeScript + Vite 6 + Element Plus |
| 数据库 | PostgreSQL 17 + pgvector |
| 缓存 | Redis 7 |
| 任务队列 | Celery + Redis |
| 包管理 | uv (Python) + npm (Node.js) |

## 三端架构

项目前端分为三个独立的 SPA，共享同一套后端 API 和前端代码库：

```
┌─────────────────┐     ┌──────────────────┐     ┌─────────────────┐
│   Admin 管理端   │     │  Builder 构建端   │     │   Chat 访问端   │
│   /admin/       │     │  /builder/       │     │   /chat/        │
│   端口 3000     │     │  端口 3002       │     │   端口 3001     │
└────────┬────────┘     └────────┬─────────┘     └────────┬────────┘
         │                       │                        │
         └───────────────────────┼────────────────────────┘
                                 │
                    ┌────────────▼────────────┐
                    │     Django REST API     │
                    │        :8080            │
                    └────────────┬────────────┘
                                 │
              ┌──────────────────┼──────────────────┐
              │                  │                  │
        ┌─────▼─────┐     ┌─────▼─────┐     ┌─────▼─────┐
        │ PostgreSQL │     │   Redis   │     │  Celery   │
        │   :5433    │     │   :6379   │     │  Worker   │
        └───────────┘     └───────────┘     └───────────┘
```

### Admin 管理端 (`/admin/`)

平台管理员使用，负责系统级管理：

- 用户管理（创建、角色分配、权限控制）
- 工作区管理
- 角色权限管理
- 资源管理与授权
- 系统设置（主题、认证、邮件）
- 操作日志

### Builder 构建端 (`/builder/`)

智能体开发者使用，负责资源构建：

- 智能体（应用）管理 —— 创建、配置、发布
- 知识库管理 —— 文档上传、向量化、Q&A 管理
- 工具管理 —— 自定义工具、MCP 工具
- 模型管理 —— 接入 20+ 模型供应商
- 工作流编排 —— 可视化流程编辑器（LogicFlow）
- 触发器管理

### Chat 访问端 (`/chat/`)

终端用户使用，访问发布的智能体：

- PC 端对话界面
- 移动端对话界面
- 嵌入式对话组件
- 分享对话链接
- 用户登录（支持钉钉、飞书、企业微信扫码）

## 项目结构

```
zhagent/
├── main.py                    # 后端入口（start/dev/upgrade_db/collect_static）
├── config.yml                 # 运行时配置（DB、Redis、语言等）
├── pyproject.toml             # Python 依赖（uv 管理）
├── startTools.bat             # Windows 服务管理菜单
├── apps/                      # Django 后端
│   ├── maxkb/                 #   项目核心（settings、urls、wsgi）
│   ├── users/                 #   用户管理
│   ├── application/           #   智能体/应用管理 + 工作流引擎
│   ├── knowledge/             #   知识库（向量搜索、文档处理）
│   ├── models_provider/       #   模型供应商集成（20+ 供应商）
│   ├── tools/                 #   工具管理
│   ├── chat/                  #   聊天 API
│   ├── trigger/               #   触发器系统
│   ├── oss/                   #   文件存储
│   ├── system_manage/         #   系统管理
│   ├── folders/               #   文件夹管理
│   ├── common/                #   公共模块（认证、缓存、中间件等）
│   └── static/                #   构建产物（collect_static 输出）
└── ui/                        # Vue 前端（三端完全独立）
    ├── package.json           #   便捷脚本集合
    ├── admin/                 #   管理端（完全独立）
    │   ├── package.json       #     管理端依赖
    │   ├── admin.html         #     入口 HTML
    │   ├── vite.config.ts     #     Vite 构建配置
    │   ├── env/.env           #     环境变量（port 3000）
    │   └── src/               #     管理端源代码
    │       ├── main.ts        #       入口文件
    │       ├── App.vue        #       根组件
    │       ├── router/        #       路由（system 模块）
    │       ├── views/         #       页面（system, login, error）
    │       ├── api/           #       API 客户端
    │       ├── stores/        #       状态管理
    │       ├── components/    #       共享组件副本
    │       ├── styles/        #       样式副本
    │       ├── locales/       #       国际化副本
    │       ├── utils/         #       工具函数副本
    │       └── ...
    ├── builder/               #   构建端（完全独立）
    │   ├── package.json       #     构建端依赖
    │   ├── builder.html       #     入口 HTML
    │   ├── vite.config.ts     #     Vite 构建配置
    │   ├── env/.env           #     环境变量（port 3002）
    │   └── src/               #     构建端源代码
    │       ├── builder.ts     #       入口文件
    │       ├── App.vue        #       根组件
    │       ├── router/        #       路由（application, knowledge, tool, model, trigger）
    │       ├── views/         #       页面（application, knowledge, tool, model 等）
    │       ├── api/           #       API 客户端
    │       ├── stores/        #       状态管理
    │       ├── workflow/      #       工作流编辑器
    │       ├── components/    #       共享组件副本
    │       ├── styles/        #       样式副本
    │       ├── locales/       #       国际化副本
    │       ├── utils/         #       工具函数副本
    │       └── ...
    └── chat/                  #   访问端（完全独立）
        ├── package.json       #     访问端依赖
        ├── chat.html          #     入口 HTML
        ├── vite.config.ts     #     Vite 构建配置
        ├── env/.env           #     环境变量（port 3001）
        └── src/               #     访问端源代码
            ├── chat.ts        #       入口文件
            ├── App.vue        #       根组件
            ├── router/        #       路由（chat 模块）
            ├── views/         #       页面（chat 对话界面）
            ├── api/           #       API 客户端
            ├── stores/        #       状态管理（chat-user）
            ├── components/    #       共享组件副本
            ├── styles/        #       样式副本
            ├── locales/       #       国际化副本
            ├── utils/         #       工具函数副本
            └── ...
```

## 环境依赖

| 依赖 | 版本 | 说明 |
|------|------|------|
| Python | 3.11+ | 推荐用 uv 管理 |
| Node.js | 18+ | npm 管理前端依赖 |
| PostgreSQL | 14+ | 需要 pgvector 扩展 |
| Redis | 6+ | 缓存 + Celery broker |

## 快速启动（开发环境）

### 1. 克隆项目

```bash
git clone <repo-url> zhagent
cd zhagent
```

### 2. 安装 Python 依赖

```bash
uv sync
```

### 3. 安装前端依赖

```bash
cd ui && npm install && cd ..
```

### 4. 配置数据库

复制配置模板并编辑：

```bash
cp config_example.yml config.yml
```

编辑 `config.yml`：

```yaml
DB_HOST: 127.0.0.1
DB_PORT: 5432          # PostgreSQL 端口
DB_USER: postgres
DB_PASSWORD: your_password
DB_NAME: maxkb
REDIS_HOST: 127.0.0.1
REDIS_PORT: 6379
REDIS_PASSWORD: ''
REDIS_DB: 0
DEBUG: true
LANGUAGE_CODE: zh-CN
```

### 5. 初始化数据库

确保 PostgreSQL 已启动并创建了数据库：

```sql
CREATE DATABASE maxkb;
CREATE EXTENSION IF NOT EXISTS vector;
```

### 6. 启动服务

```bash
# 终端 1：Celery Worker
python main.py dev celery

# 终端 2：Django Web（端口 8080）
python main.py dev web

# 终端 3：管理端（端口 3000）
cd ui && npm run dev

# 终端 4：构建端（端口 3002）
cd ui && npm run builder

# 终端 5：访问端（端口 3001）
cd ui && npm run chat
```

或者使用 Windows 服务管理菜单：

```bash
startTools.bat
# 选择 1 启动全部服务
```

### 7. 登录

- 管理端：`http://localhost:3000/admin/`
- 构建端：`http://localhost:3002/builder/`
- 访问端：`http://localhost:3001/chat/<accessToken>`

默认账号：`admin@zhagent.com`
默认密码：`ZhAgent@980123`

## 构建部署

### Docker 部署（推荐）

```bash
# 1. 构建前端
bash build-frontend.sh

# 2. 启动全部服务
docker compose up -d

# 3. 查看日志
docker compose logs -f

# 4. 停止服务
docker compose down
```

数据持久化目录（挂载到本地磁盘）：
- `./data/postgresql` — PostgreSQL 数据
- `./data/redis` — Redis 数据
- `./data/uploads` — 上传文件

修改默认密码：创建 `.env` 文件
```bash
DB_PASSWORD=your_secure_password
```

### 开发模式（仅数据库和缓存）

```bash
# 启动 PostgreSQL + Redis
docker compose -f docker-compose.dev.yml up -d

# 启动后端
python main.py dev celery  # 终端 1
python main.py dev web     # 终端 2

# 启动前端
cd ui && npm run dev:all
```

### 手动部署

```bash
# 构建前端
cd ui && npm run install:all
npm run build:admin
npm run build:builder
npm run build:chat

# 收集静态文件到 Django
python main.py collect_static

# 启动生产服务（gunicorn + celery）
python main.py start all
```

## 前端开发指南

### 三端完全独立

三个 SPA 各自独立，拥有完整的代码副本：
- `ui/admin/` — 管理端（系统管理、用户管理、角色权限）
- `ui/builder/` — 构建端（智能体、知识库、工具、模型、工作流）
- `ui/chat/` — 访问端（对话界面、用户登录）

### 开发命令

```bash
# 安装依赖
cd ui && npm run install:all

# 启动单个端
cd ui && npm run dev:admin    # 管理端 :3000
cd ui && npm run dev:builder  # 构建端 :3002
cd ui && npm run dev:chat     # 访问端 :3001

# 同时启动三端
cd ui && npm run dev:all
```

### 新增页面

- 管理端页面：添加到 `ui/admin/src/router/modules/system.ts`
- 构建端页面：添加到 `ui/builder/src/router/modules/` 对应的模块
- 访问端页面：添加到 `ui/chat/src/router/chat/routes.ts`

### API 请求

每个端通过 `window.MaxKB.prefix` 动态设置 API 基础路径：
- 管理端：`/admin/api`
- 构建端：`/builder/api`
- 访问端：`/chat/api`

### 注意事项

由于三端代码完全独立，修改共享代码（如组件、样式、工具函数）时需要同步修改三个目录。建议：
1. 先在一个端修改并验证
2. 然后复制到其他两个端
3. 或使用脚本批量同步

## 后端开发指南

### Django Apps

| App | 路径前缀 | 用途 |
|-----|---------|------|
| users | `/admin/api/` | 用户管理 |
| system_manage | `/admin/api/` | 系统管理 |
| application | `/builder/api/` | 智能体管理 |
| knowledge | `/builder/api/` | 知识库管理 |
| tools | `/builder/api/` | 工具管理 |
| models_provider | `/builder/api/` | 模型管理 |
| trigger | `/builder/api/` | 触发器 |
| chat | `/chat/api/` | 聊天 API |
| oss | 共用 | 文件存储 |

### 新增 Django App

1. 在 `apps/` 下创建 app 目录
2. 添加到 `apps/maxkb/settings/base/web.py` 的 `INSTALLED_APPS`
3. 在 `apps/maxkb/urls/web.py` 中注册路由到对应的 API 前缀
4. 运行 `python main.py upgrade_db` 创建数据库表

### 配置系统

配置优先级：
1. 环境变量 `MAXKB_*`（需设置 `MAXKB_CONFIG_TYPE=ENV`）
2. YAML 文件（`config.yml` > `config.yaml` > `config_example.yml`）
3. 默认值（`apps/maxkb/conf.py` 中 `Config.defaults`）

## 模型供应商

支持 20+ 模型供应商，位于 `apps/models_provider/impl/`：

OpenAI、Anthropic、DeepSeek、Gemini、Qwen、Ollama、Azure、AWS Bedrock、阿里云百炼、火山引擎、腾讯云、SiliconFlow、Kimi、文心一言、讯飞星火、本地模型、vLLM、Xinference、Docker AI、Regolo

## License

MIT License