XXL-AI v1.4.0 Ships Human-in-the-Loop Components, Agent Trace, and a Git Tool

XXL-AI v1.4.0 Release | AI Application Development Platform

Release Notes

Local version (Desk desktop client)

1. [New] Unified human-machine interaction workflow: when an agent needs user confirmation during task execution, it proactively initiates a human-machine interaction request, and the human and machine collaborate to complete the task.
1. [New] Standard human-machine interaction components: provides standardized components such as permission confirmation, multi-option selection, and user input; agents integrate and auto-enable them.
1. [New] Agent observability: developer mode provides Trace observability, allowing inspection of session conversations, tool calls, model API interactions, memory operations, and other trace details during agent execution, for debugging and optimizing agent behavior.
1. [New] Git tool: supports project-space level Git change review, push, and other operations.
1. [New] SKILL marketplace and installation: supports installation from GitHub; installation logic is unified with the SKILL marketplace/skills.sh; supports multi-SKILL detection, repository file caching, and expiry cleanup.
1. [New] Agent customization: supports agent instruction settings, agent memory on/off, and memory management.
1. [New] Agent preset instructions: provides multiple preset agent instructions for quick selection and use.
1. [Optimized] SKILL and MCP import optimization: removes unnecessary files and size limits to improve import efficiency and compatibility.
1. [Enhanced] File component enhancements: right-click shortcuts on selected files to open with default app, reveal in folder, delete, and copy path.
1. [Refactored] Tool component unification: terminal, browser, and file components are unified into the right-side panel.
1. [Optimized] SKILL permission optimization: session reads for SKILL content under the software data directory are allowed without permission interception.
1. [Experience] UI layout optimization: session workspace refactored as SessionWorkspace, covering sessions, tools, and terminal; workspace content is isolated between sessions.
1. [Optimized] Markdown rendering optimization: font, code highlighting, tables, lists, quotes, and formulas.
1. [Optimized] Thinking rendering optimization: single thinking process rendering limited to a max height, scrolls to bottom to show latest content.
1. [Experience] Appearance theme: supports dark mode, light mode, and custom multi-theme settings.
1. [Experience] Session area experience optimization: session area layout, interaction adjustments, experience upgrade.

Note: macOS "file damaged" prompt is not actual corruption; it's caused by macOS Gatekeeper placing quarantine flags on unsigned apps. Users can remove the quarantine flag via terminal. Steps: 1. Double-click to install, drag app to /Applications (don't launch first). 2. Remove quarantine flag in terminal (sudo requires password): sudo xattr -rd com.apple.quarantine "/Applications/XXL-AI-Desk.app" . 3. Double-click to launch and use.

Cloud version (Web server)

1. [Adjustment] Homepage report tenant isolation: report data is isolated across tenant spaces to prevent data leaks. From PR-5.
1. [Fix] Milvus vector model cache: MilvusVectorStore cache key adds model fingerprint info to avoid stale cache on model changes. From PR-6.
1. [Optimized] Agent model change effectiveness: model objects periodically refresh (5 min) and update actively with agent config fingerprint (update time MD5).
1. [Optimized] Markdown rendering optimization: font, code highlighting, tables, lists, quotes, formulas.
1. [Optimized] Thinking rendering optimization: single thinking process rendering limited to a max height, scrolls to bottom to show latest content.

1. Introduction

XXL-AI is a "cloud-local combined" AI Agent development platform, providing two delivery forms with the same origin and brand, complementary capabilities, that can be selected independently or combined based on team size and usage scenario:

Cloud version: Centered on Agent orchestration, standardizing extensions of "MCP + SKILL + RAG", with engineering foundations like multi-vendor, space isolation, RBAC permissions, and streaming dialogue. Agents can be built quickly and published with one click. Open source, ready to use out of the box, supports cluster deployment and production use.

Local version: Cross-platform desktop client; a personal local workbench that provides dialogue, file read/write, terminal commands, side panel tasks for files/browser, etc., around local project directories. Install and use, offline-capable, data only stored in local SQLite.

Item	Cloud (Web server)	Local (Desk desktop)
Form	B/S web application, accessed via browser	C/S desktop app, one-click install (mac/win/linux)
Audience	Teams - multi-user, multi-business space (Tenant)	Individuals - single-user local workbench
Positioning	Agent orchestration, one-click publish, permission governance	Local-first, directly operates local projects and system capabilities
Extensions	MCP + SKILL + RAG, multi-vendor, streaming dialogue	Local file/terminal/browser panel, Plan/Build modes
Modules	`xxl-ai-api` + `xxl-ai-ui` (+ `xxl-ai-sample`)	`xxl-ai-desk`
Dependencies	MySQL + Redis + Milvus	Zero dependencies (local SQLite only)

2. Documentation

Chinese docs: https://www.xuxueli.com/xxl-ai/
GitHub: https://github.com/xuxueli/xxl-ai

3. Architecture Design

XXL-AI adopts a "cloud-local combination": the cloud version (Web/server) and local version (Desk desktop) are same-origin and complementary. Top to bottom, it is divided into six layers: entry, front-end, application, runtime, support, and external.

┌──────────────────────────────────────────────────────────────────────────────────────────────────────┐
│ Entry layer   Admin (browser) · Public visitor /#/chat/{uuid} · Desk desktop client (mac / win / linux)   │
├──────────────────────────────────────────────────────────────────────────────────────────────────────┤
│ Front-end layer   Cloud version xxl-ai-ui —— Vue3 + Vite + Element Plus + TS; dev :3000, production embedded in API (Hash routing) │
│                    Local version Desk Renderer —— Vue3 + Element Plus; contextBridge → window.desk.*                    │
├──────────────────────────────────────────────────────────────────────────────────────────────────────┤
│ Application layer   Cloud version xxl-ai-api —— SpringBoot + MyBatis + XXL-SSO, :8080                                  │
│                    framework: login auth · RBAC menu/button · system management · audit log                          │
│                    business: space · vendor · knowledge base · MCP · SKILL · Agent · Chat                       │
│                    Local version Desk Main —— IPC gateway · SQLite(Drizzle) persistence · Agent hosting · boundary approval               │
├──────────────────────────────────────────────────────────────────────────────────────────────────────┤
│ Runtime layer   Cloud version harness —— llm · chat · rag · mcp · skill · supplier (runtime support, no Controller)    │
│                    Local version Pi runtime —— pi-ai + pi-agent-core, independent utilityProcess                              │
├──────────────────────────────────────────────────────────────────────────────────────────────────────┤
│ Support layer   Cloud version MySQL (business/platform) · Redis (login state + dialogue stream) · Milvus (vector database)                     │
│                    Local version SQLite single file (zero dependencies) · local files/terminal/browser                                   │
├──────────────────────────────────────────────────────────────────────────────────────────────────────┤
│ External layer   OpenAI-compatible vendors (dialogue/embeddings) · remote/local MCP services · sample xxl-ai-sample (optional)            │
└──────────────────────────────────────────────────────────────────────────────────────────────────────┘

4. Installation and Deployment

XXL-AI is a "cloud-local combined" AI Agent development platform, offering two delivery forms with the same origin and brand, complementary capabilities. Choose the appropriate version based on team size and usage scenario for installation and deployment.

4.1 Cloud version (Web server)

The XXL-AI cloud version supports one-click deployment with Docker Compose. The deployment script is as follows:

# Step 1: Clone the repository and enter the directory
git clone https://github.com/xuxueli/xxl-ai.git
cd ./xxl-ai

# Step 2: Build the frontend and sync the output (npm run build builds dist, npm run sync:dist copies to xxl-ai-api static resources directory)
cd xxl-ai-ui && npm install && npm run build && npm run sync:dist && cd ..

# Step 3: Build the backend
mvn clean package

# Step 4: Enter the docker directory (supports custom .env configuration, e.g., modify MYSQL_PATH to set MySQL data persistence directory)
cd ./docker/
cat .env

# Step 5: Start/stop the project
docker compose up -d
docker compose down

4.2 Local version (Desk desktop)

The XXL-AI local version supports one-click installation of the cross-platform client; download the appropriate installer (e.g., mac/win).

Download link: https://github.com/xuxueli/xxl-ai/releases

5. Core Function Operation Guide

5.1 Cloud version (Web server)

Log in to the workbench
Orchestrate Agent
Publish Agent
Usage example: Agent calls MCP tool (web scraping) to summarize "Today's hot social news"

5.2 Local version (Desk desktop)

Install and open the Desk client
Configure vendor model
Usage example: Desk client/Agent uses local system capabilities (Node/Python) for file operations.

Comments

Top 1 from juejin.cn, machine-translated. The original thread is authoritative.

王三岁_

Good article, thanks for sharing.