variet-agent/.agent/references/STATUS.md

Variet Agent — 설계 현황

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

시스템 개요

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

Discord 메시지
  → unified prompt (Gemini 분류) → JSON 파싱
    ├── chat → 즉답
    ├── clarify → 질문
    ├── anime → handle_anime_message (AnimePipeline)
    ├── nextcloud → NCHandler (Files/Calendar/Mail/Contacts)
    └── task → 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줄)	✅
커뮤니티 트렌드	tools/community_scraper.py	DCInside 갤러리 인기글 스크래핑 + 랭킹 + 본문 조회 (Gemini Skill)	✅
NC 파일 관리	tools/nc_files.py	Nextcloud WebDAV 파일 목록/검색/공유 (PROPFIND 폴백)	✅
NC 캘린더	tools/nc_calendar.py	CalDAV 일정 CRUD (조회/추가/수정/삭제)	✅
NC 메일	tools/nc_mail.py	IMAP 메일 조회/검색 (Mailcow PLAIN auth)	✅
NC 연락처	tools/nc_contacts.py	CardDAV 연락처 조회/검색	✅
NC 핸들러	handlers/nc_handler.py	자연어→NC 도구 라우팅 (Embed 응답)	✅
AI Foreman	core/foreman.py	목표 분해 + 상담 + Vikunja 일괄 등록 (/goal)	✅
통합 분류 라우팅	api/discord_bot.py	unified prompt→JSON→모드별 핸들러 라우팅	✅
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	✅	unified classify→route, ~470줄
커뮤니티 스크래퍼	tools/community_scraper.py	✅	DCInside 스크래퍼 + 4종 정렬 + Gemini Skill
NC 4모듈	tools/nc_*.py	✅	Files/Calendar/Mail/Contacts
AI Foreman	core/foreman.py	✅	목표 분해 + 상담 + Vikunja 등록
에이전트 워크플로우	.agent/	✅	STATUS.md + 수칙 업데이트

최근 마일스톤

• 2026-03-18: Nextcloud 4모듈 + NC핸들러 + AI Foreman v0.1 + unified 분류→라우팅 구현
• 2026-03-17: 커뮤니티 트렌드 스크래퍼 구현 (DCInside 인기글 + Gemini Skill)
• 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 버그 수정

현재 미해결

• 핫딜 통합 수집기 (#393) — 뽐뿌/퀘이사존/딜봄/클리앙 핫딜 통합 크롤링 + 트렌드 분석
• AI 회의실 (Debate Room) (#387) — Gemini + Claude CLI 래퍼로 3자 토론 세션
• CLI Bridge PoC (#203) — Windows PTY 미지원으로 보류. pywinpty 또는 Docker 환경 필요