SoulFlow-Orchestrator

# SoulFlow Orchestrator

[![CI](https://github.com/berrzebb/SoulFlow-Orchestrator/actions/workflows/ci.yml/badge.svg)](https://github.com/berrzebb/SoulFlow-Orchestrator/actions/workflows/ci.yml)
[![Coverage](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/berrzebb/SoulFlow-Orchestrator/gh-pages/badges/coverage.json)](https://github.com/berrzebb/SoulFlow-Orchestrator/actions/workflows/ci.yml)
[![Tests](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/berrzebb/SoulFlow-Orchestrator/gh-pages/badges/tests.json)](https://github.com/berrzebb/SoulFlow-Orchestrator/actions/workflows/ci.yml)
[![Lines of Code](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/berrzebb/SoulFlow-Orchestrator/gh-pages/badges/loc.json)](https://github.com/berrzebb/SoulFlow-Orchestrator)
[![Node](https://img.shields.io/badge/node-%3E%3D22-brightgreen)](https://nodejs.org/)
[![TypeScript](https://img.shields.io/badge/typescript-5.8-blue)](https://www.typescriptlang.org/)
[![License](https://img.shields.io/badge/license-AGPL--3.0-blue)](LICENSE)

한국어 | [English](docs/README.en.md)

**어떤 LLM 프로바이더도 코드 한 줄 없이 교체할 수 있는** 클라우드 비종속 AI 에이전트 런타임.

Gemini가 끊기면 Codex로, 비용이 부담되면 로컬 Ollama로 — CircuitBreaker가 자동 전환합니다.
Slack · Telegram · Discord · 웹 채팅의 메시지를 8개 역할 에이전트 팀이 처리하고,
민감정보는 AES-256-GCM Vault에 격리됩니다. **데이터는 내 서버에만 존재합니다.**

## 목차

- [설계 철학](#설계-철학)
- [두 가지 사용 경로](#두-가지-사용-경로)
- [구성 요소](#구성-요소)
- [아키텍처](#아키텍처)
- [빠른 시작](#빠른-시작)
- [대시보드](#대시보드)
- [OAuth 연동](#oauth-연동)
- [사용 예시](#사용-예시)
- [슬래시 커맨드](#슬래시-커맨드)
- [디렉터리 구조](#디렉터리-구조)
- [트러블슈팅](#트러블슈팅)

## 설계 철학

모든 세션 · 메모리 · 워크플로우 이력 · 칸반 데이터는 **로컬 SQLite**에 저장됩니다.

민감 업무는 Ollama(로컬)가 처리하고, 외부 정보가 필요할 때만 외부 LLM을 사용합니다. AES-256-GCM Vault가 인바운드 시점에 민감정보를 자동 sealing하고, 도구 실행 경로에서만 복호화를 허용합니다.

9개 에이전트 백엔드는 CircuitBreaker가 자동 관리합니다 — 코드 수정 없이 프로바이더 교체, 완전 로컬(Ollama only) 운영 모두 가능합니다.

## 두 가지 사용 경로

SoulFlow는 두 가지 독립적인 경로로 사용할 수 있습니다.

### 경로 A — 오케스트레이터 (채널 기반)

Slack · Telegram · Discord · 웹 채팅 메시지