variet-agent/.agent/references/architecture.md

Architecture

Variet Agent — Gemini CLI 기반 AI Agent Team 시스템

프로젝트 개요

사용자가 디스코드에서 자연어 명령 → AI Agent Team이 코드 분석/분해/실행 → Gitea CI로 PR/빌드/배포. Gemini CLI를 서브프로세스(asyncio.create_subprocess_exec)로 래핑하여 역할별 독립 컨텍스트로 호출.

디렉토리 구조

variet-agent/
├── main.py                  # 진입점 (FastAPI + Discord Bot 동시 실행)
├── config.py                # .env 기반 설정 관리
├── api/
│   ├── server.py            # FastAPI REST 서버
│   ├── discord_bot.py       # Discord Bot (NLU + PCRS 파이프라인 + 애니 핸들러)
│   └── models.py            # 요청/응답 모델
├── core/
│   ├── task_pipeline.py     # PCRS: Plan → Code → Review → Summarize
│   ├── gemini_caller.py     # Gemini CLI 래퍼 (text/agent 모드)
│   ├── context_manager.py   # 관련 파일 선별 + 토큰 예산 제어
│   ├── project_indexer.py   # 프로젝트 구조 스캔/캐시
│   ├── workspace.py         # 워크스페이스 관리 (채널 ↔ 프로젝트 매핑)
│   ├── file_applier.py      # 코드 변경 적용
│   └── docs_manager.py      # 문서/세션 기록
├── tools/                   # 자동화 도구 (애니메이션 파이프라인)
│   ├── anime_pipeline.py    # 통합 파이프라인 (검색/다운/자막/상태)
│   ├── anissia_client.py    # Anissia 편성표 API
│   ├── nyaa_client.py       # Nyaa 토렌트 검색
│   ├── qbit_client.py       # qBittorrent 제어
│   ├── nas_scanner.py       # NAS 파일 스캔
│   ├── title_matcher.py     # 제목 매칭 (로마지/퍼지)
│   └── subtitle_downloader.py  # 자막 다운로더
├── integrations/
│   ├── gitea_client.py      # Gitea API (PR/이슈)
│   ├── vikunja_client.py    # Vikunja 태스크 관리
│   └── ci_monitor.py        # CI 결과 모니터링
└── prompts/                 # AI 역할별 프롬프트
    ├── unified.md           # NLU 분류 (chat/task/anime/clarify)
    ├── planner.md           # 태스크 분해
    ├── coder.md             # 코드 구현
    ├── reviewer.md          # 코드 리뷰
    └── summarizer.md        # 총평 생성

핵심 모듈

모듈	역할	의존성
discord_bot.py	사용자 인터페이스 + NLU 분류	workspace.py, gemini_caller.py, task_pipeline.py
task_pipeline.py	PCRS 오케스트레이션 (Inner/Outer 루프)	gemini_caller.py, context_manager.py, project_indexer.py
gemini_caller.py	Gemini CLI 서브프로세스 호출 (text/agent)	prompts/
context_manager.py	태스크 기반 파일 선별 + 토큰 예산	project_indexer.py
workspace.py	채널 ↔ 프로젝트 경로 매핑, workspaces.json 관리	—
anime_pipeline.py	애니 자동화 통합	anissia_client.py, nyaa_client.py, qbit_client.py, nas_scanner.py

데이터 흐름

Discord 메시지
  → on_message()
    → _unified_call() — NLU 분류 (chat/task/anime/clarify)
      ├─ chat → 즉답
      ├─ clarify → 질문 임베드
      ├─ anime → _handle_anime() → AnimePipeline
      └─ task → _handle_task()
            → TaskPipeline.plan() — Planner (태스크 분해)
            → TaskPipeline.code_parallel() — Coder (에이전트 모드, cwd=프로젝트)
            → TaskPipeline.planner_verify() — 내부 자가검증 (Inner Loop)
            → TaskPipeline.batch_review() — Reviewer (Outer Loop)
            → TaskPipeline.summarize() — 총평
            → Discord Embed 보고