From 310a5601d01e9a815f7495da0aebc819c3125776 Mon Sep 17 00:00:00 2001 From: Variet Main Worker Date: Mon, 16 Mar 2026 05:33:47 +0000 Subject: [PATCH] Update "Architecture" --- Architecture.md | 112 ++++++++++++++++++++++++++++++------------------ 1 file changed, 70 insertions(+), 42 deletions(-) diff --git a/Architecture.md b/Architecture.md index 9679e28..853c176 100644 --- a/Architecture.md +++ b/Architecture.md @@ -1,52 +1,80 @@ # Architecture -## 전체 구조 +> Variet Agent — Hybrid Skill-Based AI Agent (v3) -` -Interface Layer (Discord / Web UI) - | - v -API Server (FastAPI REST + SSE) - | - v -Orchestrator - | - +-- Project Indexer (구조 분석/캐시) - +-- Context Manager (파일 선별, 토큰 예산) - +-- Task Pipeline (Plan > Code > Review > Test > Ship) - +-- Rate Limiter (120 RPM / 2,000 RPD) - | - v -Gemini CLI (gemini -p, 역할별 headless 호출) - | - v -Integrations: Gitea (PR/CI) + Vikunja (태스크) -` +## 프로젝트 개요 -## 핵심: Context Manager +사용자가 디스코드에서 자연어 명령 → Orchestrator NLU 분류 → 도구 실행 또는 Agent 통합 실행. +Gemini CLI를 subprocess(`asyncio.create_subprocess_exec`)로 호출. **SDK/API 전환 금지.** -Gemini CLI의 Context Rot (20~50% 사용 시 품질 급락) 해결: +## 디렉토리 구조 -1. Project Indexer가 프로젝트 구조/import 관계 사전 분석 -2. 태스크별로 관련 파일만 선별 (토큰 예산 내) -3. gemini -p에 선별된 컨텍스트만 주입 -4. 매 호출 독립 컨텍스트 = Context Rot 없음 +``` +variet-agent/ +├── main.py # 진입점 (FastAPI + Discord Bot) +├── config.py # .env 기반 설정 관리 +├── api/ +│ ├── server.py # FastAPI REST 서버 +│ ├── discord_bot.py # Discord Bot (이벤트 핸들러 + 라우팅, ~310줄) +│ └── models.py # 요청/응답 모델 +├── core/ +│ ├── orchestrator.py # NLU 분류 + 도구 라우팅 +│ ├── task_pipeline.py # ★ execute() 1회 호출 + 선택적 review() +│ ├── gemini_caller.py # Gemini CLI 래퍼 (text/agent 모드) +│ ├── context_manager.py # 관련 파일 선별 + 토큰 예산 +│ ├── project_indexer.py # 프로젝트 구조 스캔 +│ ├── workspace.py # 워크스페이스 관리 +│ ├── file_applier.py # 코드 변경 적용 +│ └── docs_manager.py # 문서/세션 기록 +├── handlers/ # Discord 핸들러 +│ ├── anime_handler.py # 애니 NLU + /anime 슬래시 +│ ├── task_handler.py # ★ Agent 1회 실행 + 결과 임베드 (~110줄) +│ ├── commands.py # /workspace, /task 슬래시 +│ └── renderer.py # ToolResult → Discord Embed +├── tools/ # 자동화 도구 (Plugin 패턴) +│ ├── base.py # BaseTool 추상 기반 +│ ├── registry.py # ToolRegistry 자동 발견 +│ ├── anime_tool.py # AnimeTool(BaseTool) +│ ├── anime_pipeline.py # 통합 파이프라인 +│ └── ... # 개별 클라이언트들 +├── .gemini/ +│ └── skills/ # ★ Gemini CLI Skill v2 +│ └── anime/ +│ └── SKILL.md # 도구 설명 + 사용법 +├── prompts/ +│ ├── unified.md # NLU 분류 +│ ├── agent.md # ★ 통합 에이전트 (plan+code+verify) +│ └── reviewer.md # 독립 리뷰 (선택적) +└── logs/ + └── variet.log +``` -## 작업 흐름 +## 데이터 흐름 -1. 사용자: Discord/Web에서 작업 요청 -2. Orchestrator: Planner(gemini -p)로 작업 분해 -3. 사용자 컨펌 대기 -4. Coder(gemini -p): 파일 수정 (Context Manager가 관련 파일만 주입) -5. Reviewer(gemini -p): 수정 결과 리뷰 -6. Git branch > commit > push > PR (Gitea API) -7. CI 실행 > 결과 보고 -8. 사용자 컨펌 > 머지 +``` +Discord 메시지 + → Orchestrator.classify() — NLU 분류 + ├── chat → 즉답 + ├── clarify → 질문 + ├── anime → AnimeTool + renderer + └── task → TaskPipeline.execute() ← Agent 1회 + → Gemini agent 모드 (plan+code+verify 통합) + → JSON 보고서 → Discord Embed +``` -## 보안 모드 (Mode A) +## vs 이전 버전 (PCRS) -내부 소스 보안 분석 시: -- 로컬 LLM이 앞단에서 소스를 추상화/마스킹 -- Gemini CLI는 추상화된 정보만 수신 -- 로컬 LLM이 뒷단에서 결과를 소스와 대조 검증 -- 상세: docs/vega_handoff.md 참조 \ No newline at end of file +``` +v2: NLU → Planner → Coder×N → PlannerVerify → Reviewer → Summarizer (5~7 호출) +v3: NLU → Agent 1회 (plan+code+verify 통합) → 선택적 Review (1~2 호출) +``` + +## 새 도구 추가 + +1. `tools/`에 `BaseTool` 상속 클래스 생성 → 자동 등록 +2. `.gemini/skills/`에 SKILL.md 생성 → Gemini CLI가 자동 발견 + +## 아키텍처 결정 (변경 불가) + +- **Gemini CLI subprocess 영구 유지** (SDK/API 금지) +- 상세: `.agent/references/conventions.md` 참조