Release Notes
【云版（Web 服务端）】
- 1、【优化】项目合并部署：研发环节前后端分离，部署期前端产物内嵌进后端 Jar，单进程单端口对外；
- 2、【新增】I18N 模块重构：前后端国际化逻辑优化，统一后端控制；标准化国际化资源文件结构，支持多语言配置，并优化前端国际化加载逻辑；
- 3、【优化】模型API请求通参调整，设置 User-Agent: XXL-AI 便于供应商识别；
- 4、【优化】供应商模型请求参数属性优化，支持格式检测与合法性检测；
- 5、【升级】项目依赖升级最新版本；
【本地版（Desk 桌面端）】
本地版（Desk 桌面端）以·与云版零依赖、独立构建发布；详细安装与操作见官方文档。
- 1、【重点】Desk/客户端上线：基于 Electron + Vue3 + TypeScript 构建跨平台桌面客户端，支持 mac / win / linux 一键安装及应用，本地优先、开箱即用；
- 2、【新增】多供应商模型接入：兼容 OpenAI 协议，供应商 + 模型本地配置；首次启动自动预置 OpenCodeGo / Ollama / Deepseek / 智谱GLM；
- 3、【架构】Agent 运行时进程隔离：Pi（
pi-ai+pi-agent-core）运行于独立utilityProcess，主进程仅做 IPC 网关与越界审批，长会话与工具重活不阻塞 UI； - 4、【新增】Plan / Build 模式：Plan 只读（仅只读文件与检索工具）、Build 全量读写，随会话持久化，默认 Build；文件操作限定当前项目目录，越界弹原生对话框「允许本次 / 本会话允许 / 拒绝」；
- 5、【新增】流式对话与执行过程可视化：流式输出思考过程 / 工具调用 / 回复内容；助手消息按片段发生顺序渲染时间线（思考 → 工具 → 正文交错），思考折叠、工具调用状态与耗时展示、Markdown 实时渲染与代码高亮；
- 6、【新增】项目与会话管理：项目绑定本地磁盘目录，会话归属项目，支持搜索 / 重命名 / 删除 / 排序；会话与消息落本地 SQLite 单文件，运行时数据目录可自定义；
- 7、【新增】本地系统能力：终端命令行（node-pty + xterm）；侧边任务面板含文件（目录树 + 编辑保存 + 预览 + 跟随本地变更）与浏览器（多标签
webview）； - 8、【新增】个性化设置：应用名称 / Slogan / 自定义指令，浅色（默认）/ 深色主题，中 / 英双语；
- 9、【优化】性能与体验：会话落库增量 + 单事务、运行时增量合批、渲染端按需滚动；生成中切换会话不丢内容；退出时回收运行时与终端进程。
- 10、【强化】Desk命令运行环境（Node/Python）支持自定义PATH设置，提升本地环境兼容性；Node默认使用内置版本，降低本地环境依赖；
- 11、【强化】Desk终端locale显示设置UTF-8，解决中文乱码问题；
- 12、【新增】客户端支持自动检测新版本，并引导升级；
一、简介
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） |
二、文档地址
三、架构设计
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 down4.2 【本地版（Desk 桌面端）】
XXL-AI 本地版项目，支持跨平台客户端一键安装，下载对应版本（如mac/win）安装程序即可。
五、核心功能操作指南
5.1 【本地版（Desk 桌面端）】
-
安装并打开Desk客户端
-
配置供应商模型
-
使用示例：Desk客户端/Agent 通过 本地系统能力（Node/Python）进行文件操作。
5.3 【云版（Web 服务端）】
-
登录工作台
-
编排 Agent
-
发布 Agent
-
使用示例：Agent 调用 MCP 工具（网页抓取）汇总「今日热点社会新闻」