# Qiming Backend

[![Java](https://img.shields.io/badge/Java-17-orange.svg)](https://openjdk.java.net/)
[![Spring Boot](https://img.shields.io/badge/Spring%20Boot-3.3.8-brightgreen.svg)](https://spring.io/projects/spring-boot)
[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE)

**Enterprise-grade AI Agent Development and Operation Platform** - Providing a complete solution for agent creation and distribution, knowledge base management, model proxy, memory system, and plugin ecosystem.

English | [简体中文](README.zh-CN.md)

---

## Table of Contents

- [Core Features](#core-features)
- [Architecture](#architecture)
- [Quick Start](#quick-start)
- [Configuration](#configuration) ⚠️ **Important**
- [Module Description](#module-description)
- [Development Guide](#development-guide)
- [Contributing](#contributing)
- [License](#license)
- [Commercial License](#commercial-license)

---

## Core Features

### Agent Engine
- **Visual Orchestration**: Drag-and-drop workflow design, zero-code agent creation
- **Code-based Development**: Support for Java/Python plugin development, flexible extension
- **Multi-model Support**: OpenAI, Claude, Ollama, Qwen, and other mainstream models
- **Streaming Output**: SSE real-time response, smooth user experience
- **Multi-turn Conversations**: Complete session context management

### Knowledge Base Management
- **Document Parsing**: PDF, Word, Excel, Markdown, and other formats
- **Vector Storage**: Milvus vector database, efficient similarity search
- **Intelligent Chunking**: Automatic document segmentation and overlap processing
- **Hybrid Retrieval**: Vector search + Full-text search + QA search

### Memory System
- **Long-term Memory**: Persistent user data and preferences
- **Short-term Memory**: Session context management
- **Classification System**: 12 main categories, 50+ sub-categories
- **Sensitive Information Filtering**: Automatic desensitization

### Model Proxy (In Development)
- **Unified Interface**: Shield differences between different model APIs
- **Intelligent Routing**: Select the optimal model based on scenarios
- **Quota Management**: Token billing and rate limiting
- **Failover**: Automatic fault tolerance switching

### Plugin Ecosystem
- **Plugin Market**: Publish and discover plugins
- **MCP Protocol**: Model Context Protocol support
- **Page Applications**: No-code page builder

---

## Architecture

### Tech Stack

| Category | Technology | Version |
|----------|-----------|---------|
| Language | Java | 17 |
| Framework | Spring Boot | 3.3.8 |
| Database | MySQL | 8.0+ |
| Vector Database | Milvus | 2.5.4 |
| Cache | Redis | 7.0+ |
| ORM | MyBatis Plus | 3.5+ |
| API Documentation | Knife4j | 4.0+ |
| Container | Docker | - |
| Orchestration | Kubernetes | - |

### Architecture Diagram

```
┌────────────────────────────────────────────────────────────────────────────┐
│                           Frontend Layer                                   │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌─────────────────────────┐  │
│  │  PC Web  │  │   H5     │  │ Mini App │  │  IM (Feishu/DingTalk/  │  │
│  │          │  │          │  │          │  │   WeCom/Slack)         │  │
│  └──────────┘  └──────────┘  └──────────┘  └─────────────────────────┘  │
└────────────────────────────────────────────────────────────────────────────┘
                                      │
                                      ▼
┌────────────────────────────────────────────────────────────────────────────┐
│                        Access Layer                                        │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────────────────────┐   │
│  │  REST API    │  │  Long        │  │       WebSocket             │   │
│  │              │  │ Connection   │  │                             │   │
│  └──────────────┘  └──────────────┘  └──────────────────────────────┘   │
└────────────────────────────────────────────────────────────────────────────┘
                                      │
                                      ▼
┌────────────────────────────────────────────────────────────────────────────┐
│                      Application Layer                                     │
│                                                                              │
│  ┌─────────────────────────────────────────────────────────────────────┐  │
│  │              Component Library                                       │  │
│  │  ┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐ │  │
│  │  │ Model│ │Know- │ │ Data │ │Plugin│ │ Work-│ │  MCP │ │ Skill│ │  │
│  │  │      │ │ ledge│ │ Table│ │      │ │ flow │ │      │ │      │ │  │
│  │  └──────┘ └──────┘ └──────┘ └──────┘ └──────┘ └──────┘ └──────┘ │  │
│  └─────────────────────────────────────────────────────────────────────┘  │
│                                                                              │
│  ┌─────────────────────────────────────────────────────────────────────┐  │
│  │              Management Portal                                        │  │
│  │  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │  │
│  │  │  User    │ │  Audit   │ │  Public  │ │ Content  │ │   Task   │ │  │
│  │  │Management│ │Management│ │  Model   │ │Management│ │Management│ │  │
│  │  ├──────────┤ ├──────────┤ ├──────────┤ ├──────────┤ ├──────────┤ │  │
│  │  │   Log    │ │   Menu   │ │ System   │ │          │ │          │ │  │
│  │  │  Query   │ │Permission│ │  Config  │ │          │ │          │ │  │
│  │  └──────────┘ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │  │
│  └─────────────────────────────────────────────────────────────────────┘  │
│                                                                              │
│  ┌─────────────────────────────────────────────────────────────────────┐  │
│  │              Product Applications                                    │  │
│  │  ┌──────────────┐  ┌──────────────┐  ┌──────────────────────────┐  │  │
│  │  │   Web App    │  │   Q&A        │  │    General Agent         │  │  │
│  │  │              │  │   Agent      │  │                          │  │  │
│  │  └──────────────┘  └──────────────┘  └──────────────────────────┘  │  │
│  └─────────────────────────────────────────────────────────────────────┘  │
└────────────────────────────────────────────────────────────────────────────┘
                                      │
                                      ▼
┌────────────────────────────────────────────────────────────────────────────┐
│                    Infrastructure Layer                                    │
│                                                                              │
│  ┌─────────────────────────────────────────────────────────────────────┐  │
│  │                    Lower-level Components                            │  │
│  │                                                                       │  │
│  │  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────────────┐ │  │
│  │  │   Cloud     │  │  qimingclaw   │  │   General Agent Engine     │ │  │
│  │  │   Sandbox   │  │   PC Client │  │                            │ │  │
│  │  │             │  │ (mac/win/   │  │  ┌───────────────────────┐ │  │
│  │  │             │  │  docker)    │  │  │  MCP Integration      │ │  │
│  │  │             │  │             │  │  ├───────────────────────┤ │  │
│  │  │             │  │             │  │  │  File Management      │ │  │
│  │  │             │  │             │  │  │  Skill Management     │ │  │
│  │  │             │  │             │  │  │  ACP Adapter Layer    │ │  │
│  │  │             │  │             │  │  │  ┌─────────────────┐ │ │  │
│  │  │             │  │             │  │  │  │ Supported Agent:│ │ │  │
│  │  │             │  │             │  │  │  │ claudecode      │ │ │  │
│  │  │             │  │             │  │  │  │ opencode        │ │ │  │
│  │  │             │  │             │  │  │  │ codex           │ │ │  │
│  │  │             │  │             │  │  │  │ openclaw        │ │ │  │
│  │  │             │  │             │  │  │  │ kimicli         │ │ │  │
│  │  │             │  │             │  │  │  └─────────────────┘ │ │  │
│  │  │             │  │             │  │  ├───────────────────────┤ │  │
│  │  │             │  │             │  │  │  Browser             │ │  │
│  │  │             │  │             │  │  │  Automation          │ │  │
│  │  │             │  │             │  │  │  GUI Automation      │ │  │
│  │  │             │  │             │  │  │  Network Channel     │ │  │
│  │  │             │  │             │  │  │  Runtime Integration │ │  │
│  │  │             │  │             │  │  └───────────────────────┘ │  │
│  │  │             │  │             │  └─────────────────────────────┘ │  │
│  │  └─────────────┘  └─────────────┘                                   │  │
│  └─────────────────────────────────────────────────────────────────────┘  │
│                                                                              │
│  ┌─────────────────────────────────────────────────────────────────────┐  │
│  │                    Core Infrastructure                                │  │
│  │  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────┐  │  │
│  │  │ Database │ │  Cache   │ │  Vector  │ │  Search  │ │ Model │  │  │
│  │  │  MySQL   │ │  Redis   │ │  Milvus  │ │ Elastic  │ │ Proxy│  │  │
│  │  └──────────┘ └──────────┘ └──────────┘ └──────────┘ └──────┘  │  │
│  └─────────────────────────────────────────────────────────────────────┘  │
└────────────────────────────────────────────────────────────────────────────┘
```

### Project Repository Overview

The Qiming AI Agent Platform consists of multiple interconnected repositories:

#### **Frontend & Mobile**
| Repository | Description | URL |
|-----------|-------------|-----|
| **qiming** | Frontend Web | [https://github.com/qiming-ai/qiming](https://github.com/qiming-ai/qiming) |
| **qiming-mobile** | Mobile Application | [https://github.com/qiming-ai/qiming-mobile](https://github.com/qiming-ai/qiming-mobile) |
| **noVNC** | Web-based VNC Client | [https://github.com/qiming-ai/noVNC](https://github.com/qiming-ai/noVNC) |

#### **Backend & Application Layer**
| Repository | Description | URL |
|-----------|-------------|-----|
| **qiming-backend** | Application Layer (Backend) - **This Repository** | [https://github.com/qiming-ai/qiming-backend](https://github.com/qiming-ai/qiming-backend) |

#### **Agent Engine & Clients**
| Repository | Description | URL |
|-----------|-------------|-----|
| **qimingclaw** | Agent PC Client (mac/win/docker) | [https://github.com/qiming-ai/qimingclaw](https://github.com/qiming-ai/qimingclaw) |
| **qimingcode** | Qiming Agent Engine (based on open-source opencode) | [https://github.com/qiming-ai/qimingcode](https://github.com/qiming-ai/qimingcode) |
| **claude-code-acp-ts** | Claude Code ACP based on Zed | [https://github.com/qiming-ai/claude-code-acp-ts](https://github.com/qiming-ai/claude-code-acp-ts) |

#### **Infrastructure & Services**
| Repository | Description | URL |
|-----------|-------------|-----|
| **rcoder** | Sandbox & Container Scheduling (includes General Agent Engine) | [https://github.com/qiming-ai/rcoder](https://github.com/qiming-ai/rcoder) |
| **mcp-proxy** | MCP Service (used by qimingclaw and sandbox) | [https://github.com/qiming-ai/mcp-proxy](https://github.com/qiming-ai/mcp-proxy) |
| **qiming-file-server** | File Service (used by sandbox and qimingclaw, includes skill sync) | [https://github.com/qiming-ai/qiming-file-server](https://github.com/qiming-ai/qiming-file-server) |

#### **Web Application Development**
| Repository | Description | URL |
|-----------|-------------|-----|
| **xagi-frontend-templates** | Web Application Development Templates | [https://github.com/qiming-ai/xagi-frontend-templates](https://github.com/qiming-ai/xagi-frontend-templates) |
| **vite-plugin-design-mode** | Visual Editor Vite Plugin | [https://github.com/qiming-ai/vite-plugin-design-mode](https://github.com/qiming-ai/vite-plugin-design-mode) |
| **dev-inject** | Web Application Smart Script Injection | [https://github.com/qiming-ai/dev-inject](https://github.com/qiming-ai/dev-inject) |

#### **Plugin & Script Execution**
| Repository | Description | URL |
|-----------|-------------|-----|
| **run_code_rmcp** | Plugin Script Execution (TypeScript/JavaScript/Python) | [https://github.com/qiming-ai/run_code_rmcp](https://github.com/qiming-ai/run_code_rmcp) |

#### **Network & Utilities**
| Repository | Description | URL |
|-----------|-------------|-----|
| **lanproxy-go-client** | Network Tunnel Client (used by qimingclaw) | [https://github.com/ffay/lanproxy-go-client](https://github.com/ffay/lanproxy-go-client) |

---

### Design Patterns

- **DDD (Domain-Driven Design)**: Clear layer separation
- **CQRS**: Command Query Responsibility Segregation
- **Strategy Pattern**: Model selection, plugin invocation
- **Observer Pattern**: Message broadcasting
- **Repository Pattern**: Data access abstraction

---

## Quick Start

### Prerequisites

| Component | Minimum | Recommended |
|-----------|---------|-------------|
| Java | JDK 17 | OpenJDK 17 |
| MySQL | 8.0+ | 8.0+ |
| Redis | 6.0+ | 7.0+ |
| Milvus | 2.5+ | 2.5+ |
| Elasticsearch | 9.2.1 | 9.2.1 |
| Memory | 4GB | 8GB+ |
| CPU | 2 cores | 4 cores+ |

### 1. Clone the Repository

```bash
git clone https://github.com/qiming-ai/qiming-backend.git
cd qiming-backend
```

### 2. Start Basic Services

- **Milvus Vector Database**: https://github.com/milvus-io/milvus
- **MySQL**: Install and configure MySQL, create database `agent_platform`, import `sql/init.sql`
- **Elasticsearch**: Install and configure Elasticsearch 9.2.1, configure Chinese word segmentation plugin for Chinese environment
- **mcp-proxy**: https://github.com/qiming-ai/mcp-proxy
- **Web development scheduling and agent sandbox service**: https://github.com/qiming-ai/rcoder

> For development and testing, you can use the official deployment package to run all basic services directly.

### 3. Add Configuration File

Copy `application-${env}.sample.yml` to `application-${env}.yml`:

### 4. Start the Application

**Option 1: Using IDE (IntelliJ IDEA, etc.)**
- Open `app-platform-bootstrap/app-platform-web-bootstrap/src/main/java/com/xspaceagi/PlatformApiApplication.java`
- Click the run button to start

**Option 2: Using Maven Commands**
```bash
# Build the project
mvn clean package -DskipTests

# Start the application
cd app-platform-bootstrap/app-platform-web-bootstrap
java -jar target/app-platform-web-bootstrap-*.jar

# Or run directly with Maven
mvn spring-boot:run -pl app-platform-bootstrap/app-platform-web-bootstrap -Pdev
```

**Option 3: Using IDEA Maven Panel**
- Open the Maven panel
- Find the `app-platform-web-bootstrap` module
- Right-click and select `Run` -> `spring-boot:run`

### 5. Access the Application

After starting, access the application (default port 8081):

- **API Documentation**: http://localhost:8081/doc.html
- **Health Check**: http://localhost:8081/health

---

## Module Description

### Project Structure

```
agent-platform/
├── app-platform-bootstrap/          # Bootstrap module
│   └── app-platform-web-bootstrap/  # Web application entry point
├── app-platform-foundation/         # Foundation module
│   ├── system-spec/                 # System specification
│   ├── system-sdk/                  # System SDK
│   └── system-domain/               # System domain models
├── app-platform-modules/            # Business modules
│   ├── app-platform-agent/          # Agent core module
│   ├── app-platform-knowledge/      # Knowledge base module
│   ├── app-platform-memory/         # Memory module
│   ├── app-platform-model-proxy/    # Model proxy module
│   ├── app-platform-mcp/            # MCP protocol module
│   ├── app-platform-compose/        # Custom table module
│   ├── app-platform-custom-page/    # Custom page module
│   ├── app-platform-eco-market/     # Ecosystem market module
│   ├── app-platform-sandbox/        # Sandbox module
│   ├── app-platform-log/            # Logging module
│   └── platform-system/             # Platform system module
├── fast-boot-dependencies/          # Dependency management
└── specs/                           # Specification documents
```

### Core Modules

| Module | Description |
|--------|-------------|
| **Agent** | Agent creation, session management, message processing |
| **Knowledge** | Knowledge base management, document upload, vector search |
| **Memory** | Long-term memory storage and retrieval |
| **Model Proxy** | Unified model proxy interface |
| **MCP** | Model Context Protocol implementation |
| **Eco Market** | Plugin market and template management |
| **Compose** | Custom table functionality |
| **Custom Page** | No-code page builder |

---

## Configuration

### Configuration File Structure

```
app-platform-web-bootstrap/src/main/resources/
├── application.yml                 # Main configuration file (common settings)
├── application-dev.yml            # Development environment configuration (local use, not committed)
├── application-test.yml           # Test environment configuration (optional)
└── application-prod.yml           # Production environment configuration (optional)
```

### Complete Environment Variable List

#### Database Configuration

| Variable | Description | Required | Default |
|----------|-------------|----------|---------|
| `DB_HOST` | MySQL database host | ✅ | localhost |
| `DB_PORT` | MySQL port | ✅ | 3306 |
| `DB_NAME` | Database name | ✅ | agent_platform |
| `DB_USERNAME` | Database username | ✅ | root |
| `DB_PASSWORD` | Database password | ✅ | - |

#### Custom Table Component Database (Doris not tested, supports MySQL)

| Variable | Description | Required | Default |
|----------|-------------|----------|---------|
| `DORIS_HOST` | Doris host | ✅ | localhost |
| `DORIS_DB_NAME` | Doris database name | ✅ | agent_custom_table |
| `DORIS_USERNAME` | Doris username | ✅ | root |
| `DORIS_PASSWORD` | Doris password | ✅ | - |

#### Redis Configuration

| Variable | Description | Required | Default |
|----------|-------------|----------|---------|
| `REDIS_HOST` | Redis host | ✅ | localhost |
| `REDIS_PORT` | Redis port | ✅ | 6379 |
| `REDIS_PASSWORD` | Redis password | ✅ | - |
| `REDIS_DB` | Redis database number | ✅ | 1 |

#### Milvus Vector Database

| Variable | Description | Required | Default |
|----------|-------------|----------|---------|
| `MILVUS_URI` | Milvus connection URI | ✅ | http://localhost:19530 |
| `MILVUS_USER` | Milvus username | ✅ | root |
| `MILVUS_PASSWORD` | Milvus password | ✅ | - |

#### Elasticsearch (Optional)

| Variable | Description | Required | Default |
|----------|-------------|----------|---------|
| `ES_URL` | Elasticsearch URL | ✅ | http://localhost:9200 |
| `ES_USERNAME` | Elasticsearch username | ✅ | elastic |
| `ES_PASSWORD` | Elasticsearch password | ✅ | - |
| `ES_API_KEY` | Elasticsearch API Key | ✅ | - |

#### Security Configuration

| Variable | Description | Required | Default |
|----------|-------------|----------|---------|
| `JWT_SECRET_KEY` | JWT signing key | ✅ | - (at least 32 characters) |

#### Tencent Cloud COS (Optional)

| Variable | Description | Required | Default |
|----------|-------------|----------|---------|
| `COS_SECRET_ID` | Tencent Cloud COS secret ID | ✅ | - |
| `COS_SECRET_KEY` | Tencent Cloud COS secret key | ✅ | - |
| `COS_BASE_URL` | COS access domain | ✅ | https://... |

#### File Storage

| Variable | Description | Required | Default |
|----------|-------------|----------|---------|
| `FILE_UPLOAD_FOLDER` | File upload directory | ✅ | /tmp/uploads |
| `FILE_BASE_URL` | File access URL | ✅ | https://yourdomain/api/file |
| `STORAGE_TYPE` | Storage type, currently supports Tencent Cloud COS and local file storage | ✅ | file |

#### External Services (Optional)

| Variable | Description | Required | Default |
|----------|-------------|----------|---------|
| `CODE_EXECUTE_URL` | Code execution service | ✅ | http://localhost:8020/... |
| `LOG_SERVICE_URL` | Log service URL, can be omitted, deprecated | ✅ | http://localhost:8097 |
| `MCP_PROXY_URL` | MCP proxy URL | ✅ | http://localhost:8020 |

#### Page Application Development Services (Optional)

| Variable | Description | Required | Default |
|----------|-------------|----------|---------|
| `DEV_SERVER_HOST` | Development server host | ✅ | http://localhost |
| `PROD_SERVER_HOST` | Production server host | ✅ | http://localhost:8099 |
| `BUILD_SERVER_URL` | Build server URL | ✅ | http://localhost:60000/api |
| `AI_AGENT_URL` | AI agent URL | ✅ | http://localhost:8086 |
| `DOCKER_PROXY_URL` | Docker proxy URL | ✅ | http://localhost:8088 |

#### Internal Network Tunnel Proxy Configuration (Optional)

| Variable | Description | Required | Default |
|----------|-------------|----------|---------|
| `SERVICE_HOST` | Internal service address | ❌ | 127.0.0.1 |
| `BIND_HOST` | Bind address | ❌ | 0.0.0.0 |
| `REVERSE_PORTS` | Port range | ❌ | 30000-40000 |
| `OUTER_HOST` | Client connection IP address | ❌ | - |
| `OUTER_PORT` | Client connection port | ❌ | 6443 |

#### Model Proxy (Optional)

| Variable | Description | Required | Default |
|----------|-------------|----------|---------|
| `MODEL_API_BASE_URL` | Model API URL, corresponding to accessible MODEL_PROXY_PORT | ❌ | - |
| `MODEL_PROXY_ENABLE` | Whether to enable proxy | ❌ | true |
| `MODEL_PROXY_PORT` | Proxy port | ❌ | 18086 |
| `MODEL_PROXY_SAVE_LOG` | Whether to save logs, depends on Elasticsearch | ❌ | true |

---

## Development Guide

### Code Standards

The project follows DDD layered architecture:

```
UI Layer → Adapter Layer → Application Layer → Domain Layer → Infrastructure Layer
```

---

## Contributing

Contributions of code, documentation, and bug reports are welcome!

1. Fork this repository
2. Create a feature branch (`git checkout -b feature/AmazingFeature`)
3. Commit your changes (`git commit -m 'Add some AmazingFeature'`)
4. Push to the branch (`git push origin feature/AmazingFeature`)
5. Open a Pull Request

### Contributors

Thanks to all developers who have contributed to this project!

---

## License

This project is licensed under the **Apache License 2.0**.

See [LICENSE](LICENSE) file for details.

---

## Commercial License

### Open Source Use (Free)

This software can be used, modified, and distributed for free, but you must:

- ✅ Retain original copyright notices
- ✅ Include the Apache 2.0 license text
- ✅ State that your product is based on this software

### Commercial License (Paid)

If you need:

- 🏢 **Remove copyright notices** (white-label products)
- 🔄 **OEM partnership** (integrate into your products for resale)
- 🎨 **Custom branding** (use your own brand)
- 🚀 **Priority support** (enterprise-level technical support)

You can apply for a commercial license to obtain additional rights.

For details, see: [COMMERCIAL_LICENSE.md](COMMERCIAL_LICENSE.md)