Insights
AI가 자동으로 큐레이션·번역·정리하는 기술 동향 피드입니다.
Xiaoman은 대화형 인터페이스를 통해 지출 기록, 포지션 관리 등 개인 재무 관리를 돕는 로컬 기반 비서입니다. LangGraph와 같은 다중 에이전트 오케스트레이션을 활용하여 복잡한 요청을 처리하며, 다양한 LLM 모델에 독립적으로 작동합니다. 모든 데이터가 로컬에서 안전하게 처리되는 것이 특징입니다.
AI 자동 생성 콘텐츠
본 콘텐츠는 GitHub AI Tools의 원문을 AI가 자동으로 요약·번역·분석한 것입니다. 원 저작권은 원저작자에게 있으며, 정확한 내용은 반드시 원문을 확인해 주세요.
원문 바로가기지출 기록, 견적 확인, 포지션 관리, 건강 상태 점검 또는 아침 보고서를 받는 등 모든 것을 한 문장으로 처리하는 대화형 개인 재무 비서입니다.
License
Python
FastAPI
React
LangGraph
| 简体中文 | English |
|---|---|
| README.zh.md | README.md (current) |
Xiaoman은 24절기 중 하나인 소만(小滿)입니다. 곡식이 거의 가득 찼지만 아직 완전히 차지 않은 시기를 의미합니다. 개인 재무도 이와 같습니다. 매일 조금씩 저축하고 삶이 스스로의 속도로 채워지도록 하는 것입니다.
대화(conversation)를 핵심 상호작용으로 하며, 사용자의 로컬 기기에서 실행되는 재무 비서입니다:
| 사용자 발화 | Xiaoman 처리 내용 |
|---|---|
| "커피 28, 택시 32" | 한 문장으로 두 건의 지출 기록을 남깁니다 |
| ... | |
| 그 외의 탭(Overview / Holdings / Market / Ledger)은 중복된 양식 입력이 아니라 대화 결과에 대한 보기입니다. |
100% 로컬 데이터: 모든 것이 로컬 SQLite 데이터베이스에 저장됩니다. 선택적으로 암호 구문으로 보호되는 암호화 백업(PBKDF2 + Fernet)을 지원하며, 이 암호 구문은 절대 저장되지 않습니다.
숫자 조작 없음 (Never fabricates numbers): 금액, 손익(P&L), 위험 지표는 결정론적 엔진에 의해 계산되며, 모델은 분류와 산문 작성만 담당합니다. 런타임 시 모델은 읽기 전용 도구만을 볼 수 있습니다.
모델 비의존성 (Model-agnostic): LiteLLM을 통해 통합 접근이 가능하며 DeepSeek / Doubao / Qwen / Claude / OpenAI / Gemini 등 다양한 모델을 지원하고 자동 장애 조치(automatic failover) 기능을 제공합니다. 어떤 모델도 설정하지 않아도 완벽하게 사용할 수 있습니다.
다중 에이전트 오케스트레이션 (Multi-agent orchestration): LangGraph 그래프(supervisor 파이프라인)와 요청 하나를 티켓으로 분할하고, 여러 부서가 병렬로 작업을 수행한 후 승인을 위해 요약하는 '재무 부서 모드'를 갖추고 있습니다.
MCP 프로토콜: 모든 재무 도구는 fastmcp를 통해 표준 MCP 서버로 노출됩니다. 이를 통해 Claude Code / Cursor와 같은 외부 도구가 로컬 데이터를 직접 조회할 수 있습니다.
장기 메모리 (Long-term memory): 선호 사항은 로컬 테이블에 저장되며 BM25를 사용하여 검색되고, 메모리는 절대 기기를 벗어나지 않습니다.
3단계 견적 폴백 (3-level quote fallback): Eastmoney → Sina → 로컬 스냅샷 순서로 작동하며, 오프라인 상태일 때는 명확하게 표시됩니다.
PWA: 데스크톱과 모바일에서 설치 가능합니다.
| Chat hub | 개요 (Overview) |
|---|---|
 |  |
더 많은 내용은 docs/screenshots/와 docs/demo/에서 확인하세요.
요구 사항 (Requirements): Python 3.10 이상, Node.js 18 이상.
원클릭 (One-click) (권장)
scripts/dev.sh # Windows (Git Bash) / macOS / Linux — 백엔드(backend) 8788 + 프론트엔드(frontend) 5198
start.bat # Windows
수동 (Manual)
# 백엔드(Backend) (backend/ 내부에서 실행)
cd backend
python3 -m venv .venv && .venv/bin/pip install -r requirements.txt
...
Docker
docker compose up -d --build # 단일 컨테이너, 포트 8787, 볼륨 xiaoman-data
새 데이터베이스는 채팅 스타일의 온보딩(onboarding)으로 비어 있게 시작하며, AI 키 없이 모든 것이 작동합니다.
| 레이어 (Layer) | 기술 (Tech) |
|---|---|
| 프론트엔드 (Frontend) | React 19 + Vite + Tailwind 4 · ECharts · TanStack Table · PWA |
| ... |
flowchart LR
FE[React SPA] --> API[FastAPI REST + SSE + static hosting]
API --> G[LangGraph orchestration, supervisor pipeline]
...
원칙: 프레임워크가 오케스트레이션(orchestrates)하고; 엔진이 계산합니다(computes). 모델은 분류(classification)와 최종화(finalization) 단계에서만 나타나며, 실패 시 결정론적 경로로 저하됩니다. 전체 아키텍처 및 다이어그램: docs/architecture.md.
backend/app/
main.py FastAPI 진입점: REST + SSE + 인증(auth) + 정적 호스팅(static hosting)
db/ 데이터 계층 (도메인 모듈): ledger / portfolio / budgets /
...
| 문서 (Doc) | 내용 (Contents) |
|---|---|
| 빠른 시작 | 5분 만에 실행 가능 |
| ... |
# 백엔드: 696개 테스트 (engine / quote fallback / agent loop / LangGraph / API / backup / MCP ...)
cd backend && .venv/bin/python -m pytest tests -q
cd backend && .venv/bin/python -m ruff check app tests
...
CI는 백엔드 ruff (app + xiaoman 패키지) + pytest, 프론트엔드 tsc + vitest + build를 커버하며, 다음의 위생(hygiene) 작업도 수행합니다: 1MB가 넘는 파일이 없어야 하며, mkdocs build --strict가 통과해야 합니다.
API_TOKEN이 설정된 경우, 모든 /api/*는 Bearer 또는 ?token=을 요구합니다. 토큰 없이 접근할 경우, localhost와 ALLOWED_HOSTS 허용 목록만 허용됩니다.이 소프트웨어가 출력하는 모든 것(건강 검진, 보고서, AI 답변, 제안)은 참고용일 뿐이며 투자 자문을 구성하지 않습니다. 시장에는 위험이 따릅니다.
주제: personal-finance finance-assistant ai-agent langgraph fastapi react sqlite local-first mcp pwa