94 lines
6.4 KiB
Markdown
94 lines
6.4 KiB
Markdown
# Variet Agent — 설계 현황
|
|
|
|
> AI 에이전트는 **세션 시작 시** 이 문서를 읽어 전체 맥락을 파악합니다.
|
|
> **세션 종료 시** 변경사항을 이 문서에 반영합니다.
|
|
> Last updated: 2026-03-22
|
|
|
|
## 시스템 개요
|
|
|
|
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→모드별 핸들러 라우팅 | ✅ |
|
|
| Wiki.js 클라이언트 | `tools/wiki_client.py` | GraphQL API — 페이지 CRUD + 대시보드 | ✅ |
|
|
| AI Debate Room | `handlers/debate_handler.py` | 파일 기반 자동 토론 + Flash 합의 판정 + Wiki.js 동기화 | 🚧 |
|
|
| 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 + 수칙 업데이트 |
|
|
| Wiki.js | `tools/wiki_client.py` | ✅ | GraphQL CRUD + 대시보드 + singleByPath |
|
|
| AI Debate Room | `handlers/debate_handler.py` | 🚧 | Wiki.js 기반 분산 토론 (AG 분리) |
|
|
| Debate AG 프로젝트 | `debate-agent/` | 🚧 | idle-state 처리 + slug 탐색 + list-debates |
|
|
|
|
## 최근 마일스톤
|
|
|
|
- **2026-03-23**: discord_bot unified prompt JSON 문법 누락 대응 로직 추가
|
|
- **2026-03-22**: debate-agent idle-state 처리 — 대기 규칙 + slug 탐색 + list-debates + handler 시그널 개선
|
|
- **2026-03-21**: debate-agent 분산 토론 시스템 — Wiki.js 기반 통신, AG 프로젝트 스캐폴딩, handler 리팩토링
|
|
- **2026-03-20**: AI Debate Room v2 — 파일 기반 자동 토론 + Flash 합의 판정 + Wiki.js 동기화
|
|
- **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) — Wiki.js 기반 분산 토론 구현 완료, E2E 테스트 필요 (봇 `!debate` 명령 + AG `/start`)
|
|
- **CLI Bridge PoC** (#203) — Windows PTY 미지원으로 보류. pywinpty 또는 Docker 환경 필요
|