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 。
二、文档地址
● 中文文档：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