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。

二、文档地址

• 中文文档：https://www.xuxueli.com/xxl-ai/

• Github地址：https://github.com/xuxueli/xxl-ai

三、架构设计

• 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）安装程序即可。

• 下载地址：https://github.com/xuxueli/xxl-ai/releases

五、核心功能操作指南

5.1 【云版（Web 服务端）】

• 登录工作台

  

• 编排 Agent

  

• 发布 Agent

  

• 使用示例：Agent 调用 MCP 工具（网页抓取）汇总「今日热点社会新闻」

  

5.2 【本地版（Desk 桌面端）】

• 安装并打开Desk客户端

  

• 配置供应商模型

  

• 使用示例：Desk客户端/Agent 通过 本地系统能力（Node/Python）进行文件操作。