|
1 | 1 | # XGEN App |
2 | 2 |
|
3 | | -XGEN 프론트엔드를 Tauri 데스크톱 앱 또는 Docker 웹 서비스로 배포하는 프로젝트입니다. |
| 3 | +XGEN AI 플랫폼의 데스크톱 앱. Tauri 기반으로 xgen-frontend를 로컬 번들링하고, AI CLI를 통해 자연어로 XGEN API를 제어할 수 있습니다. |
4 | 4 |
|
5 | | ---- |
6 | | - |
7 | | -## 🎯 사용 모드 안내 |
8 | | - |
9 | | -XGEN은 **배포 방식**에 따라 사용 가능한 모드가 다릅니다: |
10 | | - |
11 | | -| 배포 방식 | 로컬 모드 | 서버 모드 | |
12 | | -|----------|:--------:|:--------:| |
13 | | -| 🖥️ **데스크톱 앱** (Tauri) | ✅ | ✅ | |
14 | | -| 🌐 **웹 서비스** (Docker) | ❌ | ✅ | |
15 | | - |
16 | | -> 💡 **로컬 모드**는 데스크톱 앱에서만 사용 가능합니다. 웹 버전은 항상 서버에 연결됩니다. |
17 | | -
|
18 | | -### 🏠 로컬 모드 (Standalone) - 데스크톱 앱 전용 |
19 | | - |
20 | | -**인터넷 없이 내 컴퓨터에서 AI 실행** *(Tauri 앱에서만 사용 가능)* |
21 | | - |
22 | | -``` |
23 | | -┌─────────────┐ ┌─────────────┐ |
24 | | -│ XGEN 앱 │ ──▶ │ 내 컴퓨터 │ |
25 | | -│ (화면) │ │ (AI 모델) │ |
26 | | -└─────────────┘ └─────────────┘ |
27 | | -``` |
28 | | - |
29 | | -| 장점 | 단점 | |
30 | | -|------|------| |
31 | | -| ✅ 인터넷 불필요 | ⚠️ 컴퓨터 성능 필요 (GPU 권장) | |
32 | | -| ✅ 데이터가 내 PC에만 저장 | ⚠️ 일부 기능 제한 | |
33 | | -| ✅ 빠른 응답 속도 | | |
34 | | - |
35 | | -**적합한 사용자:** |
36 | | -- 보안이 중요한 업무 |
37 | | -- 인터넷이 불안정한 환경 |
38 | | -- 개인 프라이버시가 중요한 경우 |
39 | | - |
40 | | ---- |
41 | | - |
42 | | -### 🌐 서버 모드 (Connected) |
43 | | - |
44 | | -**서버에 연결하여 모든 기능 사용** |
| 5 | +## 아키텍처 |
45 | 6 |
|
46 | 7 | ``` |
47 | | -┌─────────────┐ ┌─────────────┐ ┌─────────────┐ |
48 | | -│ XGEN 앱 │ ──▶ │ Gateway │ ──▶ │ AI 서버들 │ |
49 | | -│ (화면) │ │ 서버 │ │ (클라우드) │ |
50 | | -└─────────────┘ └─────────────┘ └─────────────┘ |
| 8 | +┌──────────────────────────────────────────────────────┐ |
| 9 | +│ XGEN Desktop App (Tauri) │ |
| 10 | +│ │ |
| 11 | +│ ┌─────────────────────┐ ┌───────────────────────┐ │ |
| 12 | +│ │ XGEN Frontend │ │ AI CLI Window │ │ |
| 13 | +│ │ (Next.js 정적빌드) │ │ (별도 윈도우) │ │ |
| 14 | +│ │ │ │ │ │ |
| 15 | +│ │ 워크플로우 편집기 │ │ 자연어 입력 │ │ |
| 16 | +│ │ RAG 관리 │ │ → LLM Tool Use │ │ |
| 17 | +│ │ 채팅 / 설정 │ │ → XGEN API 자동 호출 │ │ |
| 18 | +│ └──────────┬───────────┘ └──────────┬────────────┘ │ |
| 19 | +│ │ HTTP │ Tauri IPC │ |
| 20 | +│ ▼ ▼ │ |
| 21 | +│ ┌─────────────────────────────────────────────────┐ │ |
| 22 | +│ │ Tauri Rust Backend │ │ |
| 23 | +│ │ - XGEN API Client (reqwest) │ │ |
| 24 | +│ │ - Multi-Provider LLM Client (Claude/GPT/Gemini) │ │ |
| 25 | +│ │ - CLI Session Manager │ │ |
| 26 | +│ │ - Proxy / Tunnel / Sidecar │ │ |
| 27 | +│ └────────────────────────┬────────────────────────┘ │ |
| 28 | +└───────────────────────────┼───────────────────────────┘ |
| 29 | + │ HTTPS |
| 30 | + ▼ |
| 31 | + ┌──────────────────────┐ |
| 32 | + │ xgen.x2bee.com │ |
| 33 | + │ (Backend Gateway) │ |
| 34 | + └──────────────────────┘ |
51 | 35 | ``` |
52 | 36 |
|
53 | | -| 장점 | 단점 | |
54 | | -|------|------| |
55 | | -| ✅ 모든 기능 사용 가능 | ⚠️ 인터넷 필요 | |
56 | | -| ✅ 강력한 AI 모델 사용 | ⚠️ 서버 비용 발생 가능 | |
57 | | -| ✅ 파일 업로드, RAG 검색 등 | | |
58 | | - |
59 | | -**적합한 사용자:** |
60 | | -- 팀으로 협업하는 경우 |
61 | | -- 고성능 AI가 필요한 경우 |
62 | | -- 워크플로우, 문서 검색 기능 사용 |
63 | | - |
64 | | ---- |
65 | | - |
66 | | -### 🔄 모드 전환 방법 (데스크톱 앱 전용) |
67 | | - |
68 | | -> ℹ️ 웹 버전은 자동으로 서버 모드로 동작하며, 모드 전환이 필요 없습니다. |
69 | | -
|
70 | | -#### 방법 1: 앱 설정 화면에서 변경 (TODO) |
71 | | - |
72 | | -> ⚠️ **현재 개발 중**: 설정 UI에서 모드 전환 기능이 추가될 예정입니다. |
| 37 | +## 프로젝트 구조 |
73 | 38 |
|
74 | | -완성되면 아래와 같이 사용할 수 있습니다: |
75 | 39 | ``` |
76 | | -┌────────────────────────────────────────────────────┐ |
77 | | -│ XGEN [🔌 로컬 모드 ▼] [설정] │ |
78 | | -│ ↑ │ |
79 | | -│ 여기를 클릭! │ |
80 | | -└────────────────────────────────────────────────────┘ |
81 | | -``` |
82 | | - |
83 | | -#### 방법 2: 개발자 도구 콘솔 사용 (고급) |
84 | | -`F12` 또는 `Ctrl+Shift+I`로 개발자 도구를 열고 콘솔에서 입력: |
85 | | - |
86 | | -```javascript |
87 | | -// 현재 모드 확인 |
88 | | -await window.__TAURI__.core.invoke('get_app_mode') |
89 | | - |
90 | | -// 서버 모드로 전환 |
91 | | -await window.__TAURI__.core.invoke('set_app_mode', { |
92 | | - mode: 'connected', |
93 | | - serverUrl: 'http://localhost:8000' |
94 | | -}) |
95 | | - |
96 | | -// 로컬 모드로 전환 |
97 | | -await window.__TAURI__.core.invoke('set_app_mode', { |
98 | | - mode: 'standalone', |
99 | | - serverUrl: null |
100 | | -}) |
| 40 | +xgen_app/ |
| 41 | +├── src-tauri/ # Tauri Rust 백엔드 |
| 42 | +│ ├── src/ |
| 43 | +│ │ ├── commands/ |
| 44 | +│ │ │ ├── cli.rs # AI CLI IPC 커맨드 (send, history, clear, providers) |
| 45 | +│ │ │ ├── proxy.rs # 로컬 LLM 프록시 |
| 46 | +│ │ │ ├── settings.rs # 앱 설정 |
| 47 | +│ │ │ └── ... |
| 48 | +│ │ ├── services/ |
| 49 | +│ │ │ ├── xgen_api.rs # XGEN REST API 클라이언트 + Tool 정의 |
| 50 | +│ │ │ ├── llm_client.rs # 다중 LLM Provider 클라이언트 (SSE 스트리밍) |
| 51 | +│ │ │ └── ... |
| 52 | +│ │ ├── state/ |
| 53 | +│ │ │ └── app_state.rs # AppState + CliSession |
| 54 | +│ │ └── lib.rs # Tauri 앱 엔트리포인트 |
| 55 | +│ ├── capabilities/ |
| 56 | +│ │ └── default.json # IPC 권한 (main + cli 윈도우) |
| 57 | +│ ├── tauri.conf.json # Tauri 설정 |
| 58 | +│ └── tests/ |
| 59 | +│ └── cli_integration.rs # XGEN API + LLM 통합 테스트 |
| 60 | +├── src-cli/ |
| 61 | +│ ├── cli.html # AI CLI 독립 윈도우 (vanilla JS) |
| 62 | +│ └── cliSection/ # (레거시) React CLI 컴포넌트 |
| 63 | +├── scripts/ |
| 64 | +│ ├── build.sh # 로컬 빌드 스크립트 |
| 65 | +│ ├── sync-frontend.sh # GitLab에서 xgen-frontend clone |
| 66 | +│ ├── patch-frontend.sh # Tauri 정적 빌드용 패치 |
| 67 | +│ └── patch-sidebar-cli.js # 사이드바 AI CLI 버튼 주입 |
| 68 | +├── frontend/ # (빌드 시 자동 생성) xgen-frontend 소스 |
| 69 | +└── .github/workflows/ |
| 70 | + └── build-windows.yml # CI: Windows + macOS 빌드 |
101 | 71 | ``` |
102 | 72 |
|
103 | | -**서버 주소 예시:** |
104 | | -- 로컬 Docker: `http://localhost:8000` |
105 | | -- 회사 서버: `http://xgen.company.com:8000` |
| 73 | +## AI CLI |
106 | 74 |
|
107 | | -> 💡 **팁**: 서버 모드 전환 전에 Docker 서비스가 실행 중인지 확인하세요! |
| 75 | +사이드바의 **⚡ AI CLI** 버튼을 클릭하면 별도 터미널 창이 열립니다. |
108 | 76 |
|
109 | | ---- |
| 77 | +### 기능 |
| 78 | +- 자연어로 XGEN API 제어 |
| 79 | +- LLM Tool Use로 자동 API 호출 (워크플로우, 스케줄, 노드, 도구 등) |
| 80 | +- SSE 스트리밍 실시간 응답 |
| 81 | +- XGEN 백엔드의 LLM 설정을 자동으로 사용 (별도 API 키 불필요) |
110 | 82 |
|
111 | | -### 📊 기능 비교표 |
| 83 | +### 지원 LLM Provider |
112 | 84 |
|
113 | | -| 기능 | 로컬 모드 | 서버 모드 | |
114 | | -|------|:--------:|:--------:| |
115 | | -| AI 채팅 | ✅ | ✅ | |
116 | | -| 로컬 모델 사용 | ✅ | ❌ | |
117 | | -| 클라우드 모델 (GPT 등) | ❌ | ✅ | |
118 | | -| 워크플로우 실행 | ❌ | ✅ | |
119 | | -| 문서 업로드 & RAG | ❌ | ✅ | |
120 | | -| MCP 도구 | ✅ | ✅ | |
121 | | -| 오프라인 사용 | ✅ | ❌ | |
| 85 | +| Provider | API 형식 | 모델 예시 | |
| 86 | +|----------|---------|----------| |
| 87 | +| **Anthropic** (기본) | Claude Messages API | claude-sonnet-4-20250514 | |
| 88 | +| **OpenAI** | Chat Completions API | gpt-4o-2024-11-20 | |
| 89 | +| **Gemini** | Google AI API | gemini-2.5-flash | |
| 90 | +| **vLLM / SGL** | OpenAI 호환 API | (커스텀 모델) | |
122 | 91 |
|
123 | | ---- |
| 92 | +드롭다운에서 provider를 전환할 수 있으며, XGEN 백엔드에 설정된 provider만 표시됩니다. |
124 | 93 |
|
125 | | -## 프로젝트 구조 |
| 94 | +### 지원 Tool (XGEN API) |
126 | 95 |
|
127 | | -``` |
128 | | -xgen_app/ |
129 | | -├── scripts/ |
130 | | -│ ├── sync-frontend.sh # 프론트엔드 소스 동기화 |
131 | | -│ └── build.sh # 빌드 스크립트 |
132 | | -├── src-tauri/ # Tauri 데스크톱 앱 설정 |
133 | | -├── frontend/ # (빌드 시 자동 생성) xgen-frontend 소스 |
134 | | -├── Dockerfile # 웹 배포용 이미지 |
135 | | -└── docker-compose.yml # 웹 배포용 Compose |
136 | | -``` |
| 96 | +| Tool | 설명 | |
| 97 | +|------|------| |
| 98 | +| `list_workflows` | 워크플로우 목록 조회 | |
| 99 | +| `get_workflow` | 워크플로우 상세 조회 | |
| 100 | +| `save_workflow` | 워크플로우 생성/수정 | |
| 101 | +| `execute_workflow` | 워크플로우 실행 | |
| 102 | +| `list_schedules` | 스케줄 목록 조회 | |
| 103 | +| `create_schedule` | 스케줄 생성 (cron) | |
| 104 | +| `list_nodes` | 노드/에이전트 목록 | |
| 105 | +| `list_tools` | 등록된 도구 목록 | |
| 106 | +| `get_llm_status` | LLM 상태 확인 | |
137 | 107 |
|
138 | | -## 설치 |
| 108 | +## 빌드 |
139 | 109 |
|
140 | 110 | ### 사전 요구사항 |
141 | 111 |
|
142 | | -**데스크톱 앱 빌드 시:** |
143 | 112 | - Node.js 20+ |
144 | 113 | - Rust ([rustup.rs](https://rustup.rs/)) |
145 | | -- Tauri CLI: `cargo install tauri-cli` |
146 | | - |
147 | | -**웹 배포 시:** |
148 | | -- Docker & Docker Compose |
| 114 | +- Tauri CLI: `cargo install tauri-cli --version "^2"` |
149 | 115 |
|
150 | | -## 빌드 |
151 | | - |
152 | | -### 데스크톱 앱 (Tauri) |
| 116 | +### 로컬 빌드 |
153 | 117 |
|
154 | 118 | ```bash |
155 | | -# 프로덕션 빌드 |
| 119 | +# 전체 빌드 (프론트 동기화 → 패치 → 빌드) |
156 | 120 | ./scripts/build.sh |
157 | 121 |
|
158 | 122 | # 개발 모드 (핫리로드) |
159 | 123 | ./scripts/build.sh --dev |
160 | 124 |
|
161 | | -# 소스 동기화 건너뛰기 |
| 125 | +# 프론트 동기화 건너뛰기 (이미 있을 때) |
162 | 126 | ./scripts/build.sh --skip-sync |
163 | 127 | ``` |
164 | 128 |
|
165 | | -**빌드 결과물:** |
166 | | -- macOS: `src-tauri/target/release/bundle/macos/XGEN.app` |
167 | | -- Windows: `src-tauri/target/release/XGEN.exe` |
168 | | -- Linux: `src-tauri/target/release/bundle/` |
| 129 | +### CI 빌드 (GitHub Actions) |
169 | 130 |
|
170 | | -### 웹 서비스 (Docker) |
| 131 | +`main` 브랜치에 push하면 자동으로 Windows + macOS 빌드가 실행됩니다. |
171 | 132 |
|
172 | | -```bash |
173 | | -# 이미지 빌드 |
174 | | -docker-compose build |
| 133 | +빌드 파이프라인: |
| 134 | +``` |
| 135 | +GitLab clone (xgen-frontend) |
| 136 | + → patch-frontend.sh (API Routes 제거, 정적 export 패치, CLI 주입) |
| 137 | + → npm install & build |
| 138 | + → cli.html 복사 |
| 139 | + → cargo tauri build |
| 140 | + → 아티팩트 업로드 (DMG, MSI, NSIS) |
| 141 | +``` |
175 | 142 |
|
176 | | -# 실행 |
177 | | -docker-compose up -d |
| 143 | +### 빌드 결과물 |
178 | 144 |
|
179 | | -# 개발 모드 (로컬 소스 마운트) |
180 | | -docker-compose --profile dev up xgen-frontend-dev |
181 | | -``` |
| 145 | +| 플랫폼 | 파일 | |
| 146 | +|--------|------| |
| 147 | +| macOS (Apple Silicon) | `XGEN_x.x.x_aarch64.dmg` | |
| 148 | +| Windows | `XGEN_x.x.x_x64_en-US.msi` / `XGEN_x.x.x_x64-setup.exe` | |
182 | 149 |
|
183 | | -## 배포 |
| 150 | +## 설치 |
184 | 151 |
|
185 | | -### 환경 변수 |
| 152 | +### macOS |
| 153 | + |
| 154 | +1. DMG 다운로드 → 앱을 Applications에 드래그 |
| 155 | +2. 터미널에서 Gatekeeper 해제: |
| 156 | + ```bash |
| 157 | + find /Applications/XGEN.app -exec xattr -c {} \; |
| 158 | + ``` |
| 159 | +3. 앱 실행 |
| 160 | + |
| 161 | +### Windows |
| 162 | + |
| 163 | +MSI 또는 NSIS 설치 파일 실행. |
| 164 | + |
| 165 | +## 환경 변수 |
186 | 166 |
|
187 | 167 | | 변수 | 기본값 | 설명 | |
188 | 168 | |------|--------|------| |
189 | 169 | | `FRONTEND_BRANCH` | main | 빌드할 xgen-frontend 브랜치 | |
190 | | -| `NEXT_PUBLIC_BACKEND_HOST` | http://localhost | 백엔드 API 호스트 | |
191 | | -| `NEXT_PUBLIC_BACKEND_PORT` | 8000 | 백엔드 API 포트 | |
| 170 | +| `NEXT_PUBLIC_BACKEND_HOST` | https://xgen.x2bee.com | 백엔드 API 호스트 | |
| 171 | +| `NEXT_PUBLIC_BACKEND_PORT` | (없음) | 백엔드 API 포트 | |
| 172 | +| `TAURI_ENV` | true | Tauri 정적 export 활성화 | |
| 173 | +| `GITLAB_TOKEN` | - | GitLab clone용 토큰 (CI secret) | |
| 174 | + |
| 175 | +## 개발 |
192 | 176 |
|
193 | | -### 특정 브랜치 빌드 |
| 177 | +### Rust 테스트 |
194 | 178 |
|
195 | 179 | ```bash |
196 | | -# 로컬 빌드 |
197 | | -FRONTEND_BRANCH=develop ./scripts/build.sh |
| 180 | +cd src-tauri |
| 181 | + |
| 182 | +# 통합 테스트 (XGEN API + LLM 연동) |
| 183 | +cargo test --test cli_integration -- --nocapture |
198 | 184 |
|
199 | | -# Docker 빌드 |
200 | | -docker-compose build --build-arg FRONTEND_BRANCH=develop |
| 185 | +# 컴파일 체크 |
| 186 | +cargo check |
201 | 187 | ``` |
202 | 188 |
|
203 | | -### 프로덕션 배포 |
| 189 | +### 프론트 패치 테스트 |
204 | 190 |
|
205 | 191 | ```bash |
206 | | -# 환경 변수 설정 후 실행 |
207 | | -NEXT_PUBLIC_BACKEND_HOST=https://api.example.com \ |
208 | | -NEXT_PUBLIC_BACKEND_PORT=443 \ |
209 | | -docker-compose up -d |
| 192 | +# 패치 스크립트 단독 실행 |
| 193 | +FRONTEND_DIR=/path/to/frontend bash scripts/patch-frontend.sh |
210 | 194 | ``` |
211 | 195 |
|
212 | | -## 포트 |
| 196 | +## 릴리즈 |
213 | 197 |
|
214 | | -- **3000**: 프론트엔드 웹 서비스 |
| 198 | +[GitHub Releases](https://github.com/PlateerLab/xgen_app/releases)에서 최신 빌드를 다운로드할 수 있습니다. |
0 commit comments