Release Notes
【本地版（Desk 桌面端）】
- 1、【新增】人机交互流程统一：Agent执行任务过程中需要用户确认操作，主动发起人机交互请求，人机协同完成任务；
- 2、【新增】人机交互标准组件：提供权限确认、用户多选项选择、用户输入等标准化人机交互组件，Agent集成并自动启用；
- 3、【新增】Agent可观测：支持开发者模式提供Trace可观测能力，支持查看Agent执行过程中的Session对话、工具调用、模型API交互、记忆操作等Trace明细，便于调试和优化Agent行为；
- 4、【新增】Git工具：支持项目空间维度Git变更审核、推送等操作；
- 5、【新增】SKILL市场及安装：支持 从GitHub安装 方式；安装环节逻辑同SKILL市场/ skills.sh 统一；支持多SKILL识别、仓库文件缓存及过期清理等；
- 6、【新增】Agent自定义：支持Agent指令设置、Agent记忆启停以及记忆管理；
- 7、【新增】Agent预设指令：提供多Agent预设指令，支持快速选用设置；
- 8、【优化】SKILL与MCP导入优化，移除非必要文件和大小限制，提升导入效率和兼容性；
- 9、【强化】文件组件强化：选中文件支持右键快捷键，用默认应用打开、打开所在的文件夹、删除、复制路径；
- 10、【重构】工具组件统一：终端、浏览器、文件组件统一至右侧面板；
- 11、【优化】SKILL权限优化：针对软件数据目录下SKILL内容，会话读取时放行、不进行权限拦截；
- 12、【体验】UI布局优化：会话工作区重构为SessionWorkspace，覆盖会话、工具和终端；且会话间工作区内容隔离；
- 13、【优化】Markdown渲染优化：字体、代码高亮、表格、列表、引用、公式渲染优化；
- 14、【优化】Thinking渲染优化：单次思考过程渲染限定最大高度，滚动吸底展示最新内容；
- 15、【体验】外观主题：支持深色模式、浅色模式，以及自定义多主题设置，提升用户体验；
- 16、【体验】会话区域体验优化：会话区域布局、交互调整，体验性升级；
补充说明：macOS 提示「文件损坏」并非实际损坏，而是因为 macOS Gatekeeper 对未签名的应用做了隔离标记，用户可以通过终端命令去除隔离标记来解决问题。
操作处理：1、双击安装软件、把 App 拖入 /Applications（先不启动运行）；2、终端去除隔离标记（sudo 需输入密码）：sudo xattr -rd com.apple.quarantine "/Applications/XXL-AI-Desk.app"；3、双击 App 启用运行使用；
【云版（Web 服务端）】
- 1、【调整】首页报表租户隔离：报表数据跨租户空间数据隔离，避免数据泄露；From PR-5；
- 2、【修复】Milvus向量模型缓存：MilvusVectorStore 缓存Key新增模型指纹信息，避免模型变更缓存更新不及时；From PR-6；
- 3、【优化】Agent模型变更实效性：模型对象定期过期刷新（5min），并结合Agent配置指纹信息（更新时间MD5）主动更新；
- 4、【优化】Markdown渲染优化：字体、代码高亮、表格、列表、引用、公式渲染优化；
- 5、【优化】Thinking渲染优化：单次思考过程渲染限定最大高度，滚动吸底展示最新内容；
一、简介
XXL-AI 是一个「云本结合」的 AI Agent 开发平台，提供两种同源同品牌、能力互补的交付形态，可按团队规模与使用场景独立选用，也可组合使用：
- 云版：以 Agent 编排为中枢，标准化扩展「MCP + SKILL + RAG」，配套多供应商、空间隔离、RBAC 权限与流式对话等工程化底座，可快速构建并一键发布 Agent。开源、开箱即用，支持集群部署与生产落地。
- 本地版：跨平台桌面客户端：面向个人的本地工作台，围绕本机项目目录提供对话、文件读写、终端命令、文件 / 浏览器侧边任务等能力；安装即用、离线可用，数据仅落本地 SQLite。
二、文档地址
- 中文文档：www.xuxueli.com/xxl-ai/
- Github地址：github.com/xuxueli/xxl…
三、架构设计
XXL-AI 采用「云本结合」：云版（Web / 服务端）与本地版（Desk 桌面端）同源互补。整体自上而下分为入口、前端、应用、运行时、支撑、外部六层：
┌──────────────────────────────────────────────────────────────────────────────────────────────────────┐
│ 入口层 管理端 admin（浏览器） · 公开端访客 /#/chat/{uuid} · Desk 桌面客户端（mac / win / linux） │
├──────────────────────────────────────────────────────────────────────────────────────────────────────┤
│ 前端层 云版 xxl-ai-ui —— Vue3 + Vite + Element Plus + TS；开发 :3000，生产内嵌进 API（Hash 路由）│
│ 本地版 Desk Renderer —— Vue3 + Element Plus；contextBridge → window.desk.* │
├──────────────────────────────────────────────────────────────────────────────────────────────────────┤
│ 应用层 云版 xxl-ai-api —— SpringBoot + MyBatis + XXL-SSO，:8080 │
│ framework：登录鉴权 · RBAC 菜单/按钮 · 系统管理 · 审计日志 │
│ business：空间 · 供应商 · 知识库 · MCP · SKILL · Agent · Chat │
│ 本地版 Desk Main —— IPC 网关 · SQLite(Drizzle) 持久化 · Agent 托管 · 越界审批 │
├──────────────────────────────────────────────────────────────────────────────────────────────────────┤
│ 运行时层 云版 harness —— llm · chat · rag · mcp · skill · supplier（运行时支撑，无 Controller） │
│ 本地版 Pi 运行时 —— pi-ai + pi-agent-core，独立 utilityProcess │
├──────────────────────────────────────────────────────────────────────────────────────────────────────┤
│ 支撑层 云版 MySQL（业务/平台） · Redis（登录态 + 对话流） · Milvus（向量库） │
│ 本地版 SQLite 单文件（零依赖） · 本地文件 / 终端 / 浏览器 │
├──────────────────────────────────────────────────────────────────────────────────────────────────────┤
│ 外部层 OpenAI 兼容供应商（对话/嵌入） · 远程/本地 MCP 服务 · 示例 xxl-ai-sample（可选） │
└──────────────────────────────────────────────────────────────────────────────────────────────────────┘
四、安装部署
XXL-AI 是一个「云本结合」的 AI Agent 开发平台，提供两种同源同品牌、能力互补的交付形态，可按团队规模与使用场景选用合适版本安装和部署。
4.1 【云版（Web 服务端）】
XXL-AI 云版项目，支持 Docker Compose 一键部署，部署脚本如下：
# 第一步：代码clone本部 + 前往仓库目录
git clone https://github.com/xuxueli/xxl-ai.git
cd ./xxl-ai
# 第二步：构建前端并同步产物（npm run build 构建 dist，npm run sync:dist 复制到 xxl-ai-api 静态资源目录）
cd xxl-ai-ui && npm install && npm run build && npm run sync:dist && cd ..
# 第三步：构建后端
mvn clean package
# 第四步：进入 docker 目录（支持自定义 .env 配置，如修改 MYSQL_PATH 配置设置 Mysql 数据持久化目录）
cd ./docker/
cat .env
# 第五步：启动/停止项目
docker compose up -d
docker compose down
4.2 【本地版（Desk 桌面端）】
XXL-AI 本地版项目，支持跨平台客户端一键安装，下载对应版本（如mac/win）安装程序即可。
五、核心功能操作指南
5.1 【云版（Web 服务端）】
- 登录工作台
- 编排 Agent
- 发布 Agent
- 使用示例：Agent 调用 MCP 工具（网页抓取）汇总「今日热点社会新闻」
5.2 【本地版（Desk 桌面端）】
- 安装并打开Desk客户端
- 配置供应商模型
- 使用示例：Desk客户端/Agent 通过 本地系统能力（Node/Python）进行文件操作。
本文由 AI图鉴自动抓取并翻译，版权归原作者所有；如需查看原文请点下方链接。
Release Notes
Other Organiser
- 1, [new] human interaction processes are harmonized: Agent needs user confirmation in the course of the mission, initiates the machine ' s interactive request and works in tandem with the mission;
- 2, [new] human interactive standard components: provide standardized human interactive components such as permission confirmation, multiple options for users, user input, Agent integration and automatic activation;
- 3, [new] Agent can be observed: supporting the developers model to provide a Trace-observable capability, and supporting access to Tracey details such as the Ssession Dialogue, tool call, Model API Interactivity, Memory Operations in the implementation of Agent to facilitate debugging and optimizing Agent behaviour;
- 4, [new] Git tool: supports the project space dimension Git change audit, push, etc.;
- 5, [new] SKILL market and installation: support for installation from GitHub; alignment of installation chain logic with SKILL market/kills.sh; support for multi-SKILL identification, warehouse document cache and obsolete clean-up;
- 6, [new]Agent custom: supports the Agent command setting, Agent memory release and memory management;
- 7, [new] Agent Preset Directive: provide multiple Agent Preset Directives to support quick selection settings;
- 8 [Efficacy] SKILL and MCP imports optimized, moving beyond the necessary documentation and size limits to increase import efficiency and compatibility;
- 9, [enhanced] file component enhancement: the selected file supports right-key shortcuts, opening, opening the folder, deleting, copying paths with default application;
- 10, [reconstructed] tool assembly harmonization: terminal, browser, file component alignment to right panel;
- 11, [optimization] SKILLpermission Optimization: for SKILL content in the software data catalogue, permission interception does not occur when a session is read;
- 12 [Experience] UI layout optimization: session workspaces are re-constructed as SessionWorkspace, covering sessions, tools and terminals; and session-space content is segregated;
- 13. [Efficacy] Markdown Rendering: Fonts, Codes Highlight, Tables, Lists, References, Formula Rendering Optimization;
- 14, [optimization] Thinking Rendering Optimization: single-thinking processes render at maximum height and rolling bottom display of the latest content;
- 15, [Experience] look themes: support dark, light and self-defined multi-thematic settings to enhance user experience;
- 16. [Experience] session area experience optimization: session area layout, interactive adaptation, experience upgrading;
Additional Note: MacOS hint "document damage" is not actually damaged, but rather because MacOS Gatekeeper has separated the unsigned application and users can resolve the problem by removing the seal from the terminal command.
Operation processing: 1, double-click installation software, drag App into /Applications (not start first); 2, terminal removal of quarantine tags (sudo needs to enter password): sudo xattr-rd com.apple.quarantine "/Applications/XXL-AI-Desk.app "; 3, double-click App to enable operation;
[Web Service]
- 1 [Adjustment] First page on the segregation of tenants in statements: report data isolated across tenant spatial data to avoid data disclosure; From PR-5;
- 2. [Refurbishment] Milvus vector model cache: MilvusVectorStore cacheKey to add additional fingerprint information to the model to avoid delays in updating the model cache; From PR-6;
- 3, [Efficacy] Agent model change effectiveness: model object regularly expired (5min) and proactively updated in conjunction with Agent ' s fingerprinting information (update time MD5);
- 4, [optimization] Markdown rendering optimization: fonts, code highlights, tables, lists, references, formulae rendering optimization;
- 5, [optimization] Thinking Rendering Optimization: a single thought process is given maximum height and rolling bottom displays the latest content;
Introduction
XXL-AI is an "unicable combination" of the AI Agent development platform that provides two delivery models of co-source branding and complementary competencies that can be selected independently by team size and use scenario or can be used in combination:
- Cloud version: The standardized extension of "MCP + SKILL + RAG" with multiple suppliers, spatial isolation, RBAC permission and flow-based dialogue, which can be constructed quickly and with one key publish Agent. Open source, open box to support cluster deployment and production land.
- Local: Cross Platform Desktop Client: Local workstations for individuals that provide capabilities such as dialogue, document reading and writing, terminal commands, file / browser side jobs around their own project directory; installation is available, offline is available and data is available only at local SQLite.
II. Document address
- Chinese document: www.xuxueli.com/xxl-ai/
- Github address: Github.com/xuxueli/xxl...
III. Structure design
XXL-AI uses the word "close of clouds": the cloud version (Web / service end) complements the local version (Desk desktop end). The whole is divided into six layers, top down, front end, application, running time, support, external:
┌──────────────────────────────────────────────────────────────────────────────────────────────────────┐
• Open-end visitors/#/chat/{uid}. Desk Desktop Client (mac / win / linux)
├──────────────────────────────────────────────────────────────────────────────────────────────────────┤
front layer xxl-ai-ui -Vue3 + Vite + Element Plus TS; development: 3,000 for production embedded in API (Hash route)
│Desk Renderer — Vue3 + Element Plus; constBridge → window.desk.*
├──────────────────────────────────────────────────────────────────────────────────────────────────────┤
applyr layer xxl-ai-api - SpringBoot + MyBatis + XXL-SSO,:8080 │
│ ramework: Access. RBAC menu/button. System administration. Audit log
│ Business: Space · Vendor · Knowledge Bank · MCP S SKILL │
Local Desk Main - IPC Gateway SQLite (Drizzle) Endurance Agent Trust Cross Border Approval
├──────────────────────────────────────────────────────────────────────────────────────────────────────┤
Runtime horizon - llm chat rag mcp skill supplier (runtime support, no Controller)│
│ Local Pi Run-time - pi-ai + pi-agent-core, independentProcess
├──────────────────────────────────────────────────────────────────────────────────────────────────────┤
│ Supporting layer MySQL (operational/platform) │
Local SQLite Single File (zero-dependent) Local File / Terminal / Browser
├──────────────────────────────────────────────────────────────────────────────────────────────────────┤
• External Open AI Compatible Vendors (dialogue/embedded) • Remote/local MCP Service x Example xxl-ai-sample (optional) │
└──────────────────────────────────────────────────────────────────────────────────────────────────────┘
IV. Installation and deployment
XXL-AI is an "unicable combination" of the AI Agent development platform, which provides two co-sourced branding, capacity-complementing delivery patterns that can be installed and deployed in a suitable version by team size and use scenario.
4.1 [Web Service]
XXL-AI Cloud-based Project, which supports the Docker Company deployment with the following scripts:
# Step 1: Code Cline Headquarters + Go to the warehouse directory
git clone https://github.com/xuxueli/xxl-ai.git
cd ./xxl-ai
# Step 2: Build frontend and sync product (npm run build dist, npm run sync:dist copy to xxl-ai-api static resource 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 (support custom.env configuration, e. g. modify MYSQL PATH configuration for Mysql data sustainability directory)
cd ./docker/
cat .env
# Step 5: Start/stop projects
docker compose up -d
docker compose down
4.2 [Desk Desktopend]
The XXL-AI local version project supports the installation of a cross-platform client with a one-click installation and downloads the corresponding version (e.g., mac/win) installation program.
V. Guidelines for the operation of core functions
5.1 [Web Service]
- Log in to the desk.
- Organization, Agent.
- publish Agent.
- Use example: Agent calls MCP tool (page grabs) to aggregate "The Hotspot Social News Today"
5.2 [Desk Desktopend]
- Install and open the Desk client
- Configure supplier models
- Use example: Desk client/Agent performs file operations through local system capabilities (Node/Python).
Auto-fetched and translated by AI Atlas. All rights belong to the original author.