XXL-AI v1.4.0 배포, AI 애플리케이션 개발 플랫폼

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 데스크톱)은 동일 소스로 상호 보완합니다. 전체는 위에서 아래로 진입점, 프론트엔드, 애플리케이션, 런타임, 지원, 외부의 6개 계층으로 나뉩니다:

┌──────────────────────────────────────────────────────────────────────────────────────────────────────┐ │ 진입 계층 관리 콘솔 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(벡터 DB) │ │ 로컬판 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)을 통해 파일 작업 수행.