Release Notes

【本地版（Desk 桌面端）】

• 1、【能力】会话压缩与记忆：
  • 会话上下文结构化：system（系统指令 + 长期记忆 + skill技能 + 会话摘要）+ messages（短期记忆/会话）+ tools（内置工具 + MCP工具）
  • 会话上下文使用率：计算公式 = 上下文token消耗 / 模型ContextWindow；
  • 会话压缩：针对历史会话提炼背景/目标/进展等提炼，压缩为 max 定长（2000）摘要信息。会话上下文传递短期记忆时：需传递摘要信息与上次摘要后全部增量对话信息。每轮会话后都会触发异步压缩摘要，如果「上下文使用率超过80% 或 对话轮次超过20次 或 压缩摘要不存在」，需要主动压缩一次；
  • 长期记忆：项目维度跨会话的画像/偏好/事实/目标/进展等长期记忆沉淀。会话完成时异步触发记忆生成/保鲜，「检测记忆为空 或 距离上次记忆生成超5min」，需要主动生成一次记忆；项目设置里，支持手动查看管理记忆；
    （项目 列表，启用记忆 列名改为 长期记忆；新增 记忆生成时间 列；）
• 2、【重构】产品设计重构：
  • 扩展中心：插件中心更名扩展中心，现有MCP、SKILL和内置工具之外，新增 “Agent”功能；支持创建管理多Agent，Agent支持设置 指令、SKILL、MCP和内置工具等；
  • 会话新建：新建会话时，当前会话框底部限制必选 项目；新增必选 Agent，Agent下拉框中限制Agent列表与新建Agent入口，参考项目选项交互；
  • 系统设置：新增 项目 设置，支持管理维护 项目列表；支持新增项目、重命名、在Finder中显示、删除等；支持长期记忆开关、长期记忆查看；
  • 会话与Agent绑定，会话时使用的 系统指令、SKILL、MCP、内置工具等，从对应Agent上获取，Agent修改后需要实时感知最新的；
• 3、【安全】权限管控：升级三档权限模式「仅可查看（全局读）、工作区内修改（全局读 + 项目&系统临时目录写）、完全权限（全局读写）」；同时，兜底保留统一的敏感操作拦截机制；
  （read-only、workspace-write、full-access）
• 4、【推理】模型及推理等级：供应商模型精细化管理，支持模型分类（通用模型、对话模型、潜入模型、文生图模型）；并针对对话模型，支持推理登陆（Default、Low、High、Max）；
• 5、【新增】输入框支持关联文件：新增“+“按钮功能，支持选择文件并关联到当前会话，便于Agent调用文件内容；
• 6、【重构】代码模块化重构：同一职责域代码收拢在单一模块内，对外仅暴露最小必要接口，避免跨模块散落同职责的实现细节；
• 7、【能力】文件编辑器：支持多主题样式、文件搜索/替换等；
• 8、【体验】浏览器工具面板优化：浏览器搜索时面板不必展开，仅首次默认展开，降低对用户操作干扰；
• 9、【安全】沙箱文件权限调整：SKILL目录文件读取默认放行；
• 10、【体验】UI框架优化：侧边栏宽度调大；对话布局（子菜单/会话去/工具栏）宽度优化，提升操作体验；
• 11、【体验】文件工具面板优化：选中文件操作复制快捷键，默认执行「复制路径」操作；
• 12、【体验】会话导航轨：会话工作区支持会话导航轨，以刻度形式展示多轮会话，提升操作体验；
• 13、【体验】会话区搜索：会话工作区支持关键词搜索；
• 14、【体验】文件工具面板优化：文件工具面板中文件树支持折叠，定位目录名左侧添加折叠/展开icon；
• 15、【体验】MCP/SKILL市场：远程数据加载缓慢时，前端交互优化，避免页面黑屏等；
• 16、【体验】主题色丰富：新增多主题色，支持自定义主题色设置；
• 17、【优化】新增会话示例任务调整，辅助用户快速上手；
• 18、【新增】会话状态信息条：支持会话统计（轮次/步数、模型用时、输出速度）、Token 用量（总量、缓存命中、输入/输出分项）、上下文消耗（使用率、窗口、分项估算）等信息展示，点击胶囊展开明细，便于用户了解会话状态；
• 19、【新增】应用中心：内置「笔记」工具，子菜单进入支持针对笔记进行设置。包括笔记 存储目录（默认在 软件安装目录下的 /note 子目录）、是否启用（启用后新增左侧菜单）等设置；提供「我的应用 / 应用市场」，安装与启用分离。
• 20、【新增】笔记应用：新建「笔记」内置应用，支持 笔记文件目录（左侧，顶部打开所在文件夹 / 新建目录 / 新建笔记，右键菜单支持新建、重命名、删除、定位）、笔记Markdown编辑器（中间，参考文件工具里的markdown编辑器）、浮动文章目录、预览（编辑/分屏/预览）、搜索/替换、主题切换、图片插入（图片存在在笔记目录的 /resource/image 目录下）、外部文件变更实时刷新等；

MacOS 安装说明：macOS 提示「文件损坏」并非实际损坏，而是安装软件未签名（没有开发者账号）。将安装软件拖入 /Applications 后，终端执行如下命令即可。

sudo xattr -rd com.apple.quarantine /Applications/XXL-AI-Desk.app

一、简介

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 【本地版（Desk 桌面端）】

• 安装并打开Desk客户端
  

• 配置供应商模型
  

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

5.2 【云版（Web 服务端）】

• 登录工作台
  

• 编排 Agent

• 发布 Agent
  

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