XXL-AI v1.4.0 发布｜AI应用开发平台XXL-AI发布新版本，本地版新增人机交互统一流程、可观测性、Git支

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。

项	云版（Web 服务端）	本地版（Desk 桌面端）
形态	B/S Web 应用，浏览器访问	C/S 桌面应用，一键安装（mac / win / linux）
面向	团队——多用户、多业务空间（Tenant）	个人——单用户本地工作台
定位	Agent 编排、一键发布、权限治理	本地优先，直接操作本机项目与系统能力
扩展	MCP + SKILL + RAG，多供应商，流式对话	本地文件 / 终端 / 浏览器面板，Plan / Build 模式
模块	`xxl-ai-api` + `xxl-ai-ui`（+ `xxl-ai-sample`）	`xxl-ai-desk`
依赖	MySQL + Redis + Milvus	零依赖（仅本地 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