# Variet Agent — 설계 현황

> AI 에이전트는 **세션 시작 시** 이 문서를 읽어 전체 맥락을 파악합니다.
> **세션 종료 시** 변경사항을 이 문서에 반영합니다.
> Last updated: 2026-03-16

## 시스템 개요

Hybrid Skill-Based AI Agent v3 — 사용자가 디스코드에서 자연어 명령을 내리면, Orchestrator NLU가 분류하여 도구를 실행하거나 AI Agent가 통합 처리합니다.

```
Discord 메시지
  → Orchestrator.classify() — NLU 분류
    ├── chat → 즉답
    ├── clarify → 질문
    ├── anime → AnimeTool (파이프라인)
    └── task → TaskPipeline.execute() → Gemini CLI agent 모드
```

## 핵심 설계 결정 (불변)

- **Gemini CLI subprocess 방식 영구 유지** (SDK/API 금지)
- **Vikunja = 태스크 SSOT** (모든 태스크 생성/완료는 Vikunja 경유)
- **`.agent/references/` = 설계 문서 SSOT** (로컬 우선, Wiki에 동기화)

## 기능 목록 (Feature Inventory)

| 기능 | 모듈 | 설명 | 상태 |
|------|------|------|:----:|
| 자연어 명령 분류 | `core/orchestrator.py` | Discord 메시지 → chat/clarify/anime/task intent 분류 | ✅ |
| AI 코드 생성 | `core/task_pipeline.py` | 계획→코딩→검증 통합 실행 (Gemini agent 모드) | ✅ |
| Gemini CLI 래퍼 | `core/gemini_caller.py` | text/agent 모드 전환, CLI subprocess 호출 | ✅ |
| 컨텍스트 관리 | `core/context_manager.py` | 관련 파일 선별 + 토큰 예산 제어 | ✅ |
| 프로젝트 인덱싱 | `core/project_indexer.py` | 프로젝트 구조 스캔 + import 관계 파악 | ✅ |
| 애니 자동 다운로드 | `tools/anime_pipeline.py` | 편성표→검색→토렌트→NAS 저장 통합 파이프라인 | ✅ |
| 애니 자막 다운로드 | `tools/subtitle_downloader.py` | Anissia 6개 플랫폼(Google Drive, Tistory, Blog 등) 스크래핑 | ✅ |
| NAS 파일 관리 | `tools/nas_scanner.py` | 에피소드 스캔, 이름 정규화, 릴리스 그룹 감지 | ✅ |
| 토렌트 검색 | `tools/nyaa_client.py` | Nyaa.si 검색 + 6단계 fallback 전략 | ✅ |
| 토렌트 다운로드 | `tools/qbit_client.py` | qBittorrent WebAPI 연동 | ✅ |
| 제목 매칭 | `tools/title_matcher.py` | Romaji 변환 + fuzzy similarity 크로스 언어 매칭 | ✅ |
| Vikunja 태스크 관리 | `.agent/workflows/helpers/vikunja_helper.py` | 태스크 CRUD + 라벨 + 안전 업데이트 | ✅ |
| Gitea Wiki 관리 | `.agent/workflows/helpers/wiki_helper.py` | Wiki 페이지 CRUD | ✅ |
| Discord Bot | `api/discord_bot.py` | 이벤트 핸들러 + NLU 라우팅 (~310줄) | ✅ |
| CLI Bridge | - | Gemini CLI 영속 프로세스 (PTY 미지원으로 보류) | ⏸️ |

## 모듈 상태

| 모듈 | 주요 파일 | 상태 | 최근 변경 |
|------|-----------|:----:|-----------|
| NLU 분류 | `core/orchestrator.py` | ✅ | chat/clarify/anime/task 통합 |
| 태스크 실행 | `core/task_pipeline.py` | ✅ | execute() 1회 + 선택적 review |
| Gemini 래퍼 | `core/gemini_caller.py` | ✅ | text/agent 모드 |
| 컨텍스트 | `core/context_manager.py` | ✅ | 관련 파일 선별 + 토큰 예산 |
| 애니 파이프라인 | `tools/anime_pipeline.py` | ✅ | v2 에피소드 추출, 그룹 필터링, 자막 보호 |
| Discord Bot | `api/discord_bot.py` | ✅ | 레거시 800줄 제거, ~310줄 |
| 에이전트 워크플로우 | `.agent/` | ✅ | STATUS.md + 수칙 업데이트 |

## 최근 마일스톤

- **2026-03-16**: 에이전트 수칙 업데이트 + STATUS.md 도입 + .agents 통합
- **2026-03-15**: MCP 서버 제거 → CLI 직접 실행 전환
- **2026-03-15**: 레거시 NLU/핸들러 800줄 제거
- **2026-03-15**: 애니 파이프라인 버그 5건 수정 + 아키텍처 문서화
- **2026-03-15**: wiki_client update_page tags 버그 수정

## 현재 미해결

- **CLI Bridge PoC** (#203) — Windows PTY 미지원으로 보류. pywinpty 또는 Docker 환경 필요