chore: 프로젝트 초기 구조 + .agent 워크플로우 + 설계 문서
This commit is contained in:
quantlab
193
docs/vega_handoff.md
Normal file
193
docs/vega_handoff.md
Normal file
@@ -0,0 +1,193 @@
|
||||
# VEGA 확장 — Gemini CLI 보안 분석 모듈 설계 핸드오프 문서
|
||||
|
||||
---
|
||||
|
||||
## 1. 배경 및 논의 경과
|
||||
|
||||
### 출발점
|
||||
로컬 LLM(Qwen 3.5)만으로는 소스 분석 품질에 한계가 있어, Gemini CLI의 분석력을 활용하되 **내부 소스 보안을 유지**하는 시스템을 설계.
|
||||
|
||||
### 핵심 논의 과정 (v1 → v8)
|
||||
|
||||
| 버전 | 논의 | 결론 |
|
||||
|------|------|------|
|
||||
| v1~v2 | API vs CLI, 멀티 워커 | Gemini CLI 사용, 역할별 워커 |
|
||||
| v3~v4 | Rate Limit, 반복 루프 | AI Ultra 120RPM/2000RPD, Plan→Execute→Reflect 루프 |
|
||||
| v4 비판 | 자기평가 불신뢰, 과잉동원 | 연구 기반 5개 약점 발견 |
|
||||
| v5~v6 | MCP 도구, Verifier, 보안 | Source Mediator 패턴, Verifier를 Critic으로 전환 |
|
||||
| v7 | 보안 원칙 확정, Critic 협력자 | 소스 원문 금지, 로직 설명 허용, LLM 앞단+검증자 |
|
||||
| **v8** | **Mode B 가치 재검토** | **Gemini CLI 자체가 완전한 에이전트 → Mode B는 추가 개발 불필요** |
|
||||
|
||||
### 최종 결론
|
||||
|
||||
```
|
||||
Mode B (외부/범용): Gemini CLI를 그대로 쓰면 됨
|
||||
→ VS Code Agent Mode 또는 터미널 gemini -i
|
||||
→ 추가 개발 불필요
|
||||
|
||||
Mode A (내부/보안): VEGA 확장으로 구현해야 하는 부분
|
||||
→ 로컬 LLM이 내부 소스를 읽고 추상화
|
||||
→ Gemini CLI(선생님)와 대화로 분석
|
||||
→ 로컬 LLM이 결과를 소스와 대조 검증
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 2. VEGA에서 구현할 것: Mode A
|
||||
|
||||
### 구조
|
||||
|
||||
```
|
||||
User ↔ VEGA Web UI
|
||||
│
|
||||
Local LLM (프롬프트 A: 앞단)
|
||||
│ 도구: 내부 파일/RAG/DB
|
||||
│ 소스 읽고 추상화/마스킹
|
||||
▼
|
||||
Gemini CLI (-p, --approval-mode yolo)
|
||||
│ 추상화된 정보로 분석
|
||||
│ 질문 → LLM 답변 → 분석 (대화 루프)
|
||||
▼
|
||||
Local LLM (프롬프트 B: 검증자, 별도 호출)
|
||||
│ Gemini 결과 vs 실제 소스 대조
|
||||
▼
|
||||
User에게 검증된 결과 전달
|
||||
```
|
||||
|
||||
### 보안 정책
|
||||
|
||||
| 허용 ✅ | 금지 ❌ |
|
||||
|---------|---------|
|
||||
| 학술적 알고리즘 설명 (HW, LSMC 등) | 소스코드 원문 |
|
||||
| 함수 로직/흐름 설명 | 테이블/컬럼 구조 |
|
||||
| 호출 관계 개괄 | 실제 값, 파라미터 수치 |
|
||||
| 개별 함수 입출력 의미 | 내부 URL, 인증정보 |
|
||||
|
||||
LLM 추상화 후 **정규식 2단계 필터**로 금지어 자동 치환.
|
||||
|
||||
### Student ↔ Teacher 모델
|
||||
- LLM(학생)이 소스를 읽고 설명 → Gemini(선생님)가 분석/조언
|
||||
- LLM이 문제 정립 못 해도 → Gemini가 질문으로 끌어냄
|
||||
- LLM이 헛소리해도 → Gemini가 교정
|
||||
- 앞단(프롬프트 A)과 검증자(프롬프트 B)는 **별도 호출** → 순환 오류 방지
|
||||
|
||||
### Gemini CLI 호출 방식
|
||||
```bash
|
||||
# 역할별 headless 호출 (서브에이전트 풀 불필요)
|
||||
gemini -p "분석 요청" --system "분석가 프롬프트" -o json --approval-mode yolo
|
||||
gemini -p "리뷰 요청" --system "리뷰어 프롬프트" -o json --approval-mode yolo
|
||||
```
|
||||
매 호출이 **독립 컨텍스트** → 컨텍스트 포화 없음 → 풀 관리 불필요.
|
||||
|
||||
### VEGA 기존 인프라 활용
|
||||
- **Ollama API**: 로컬 LLM 호출 (이미 존재)
|
||||
- **FastAPI + SSE**: Web UI (이미 존재)
|
||||
- **RAG/벡터DB**: 내부 문서 검색 (이미 존재)
|
||||
- **추가 필요**: `gemini -p` subprocess 호출 모듈, 마스킹 필터, 대화 루프
|
||||
|
||||
---
|
||||
|
||||
## 3. 새로운 목표 — AI Agent Team
|
||||
|
||||
### 진짜 최종 목표
|
||||
|
||||
위 Mode A/B 논의는 더 큰 목표의 **일부**였음:
|
||||
|
||||
> **사용자가 디스코드로 추상적 명령을 주면,
|
||||
> AI Agent Team이 스스로 작업을 분석/분해/실행하고,
|
||||
> 샌드박스에서 코드를 실행/테스트하고,
|
||||
> Gitea CI로 컴파일/배포까지 수행하며,
|
||||
> 사용자는 디스코드로 확인/컨펌만 하는 시스템.**
|
||||
|
||||
### 왜 이 구조가 필요한가
|
||||
|
||||
| 현재 문제 | 원인 | 해결 방향 |
|
||||
|----------|------|----------|
|
||||
| **컨텍스트 초과** | 한 에이전트가 긴 작업 → 컨텍스트 포화 → 멈춤/유실 | 작업을 역할별로 분할, 각 에이전트는 짧은 컨텍스트 |
|
||||
| **추상적 명령 처리** | "이거 고쳐줘" → 어디를? 뭘? | 작업 분석 에이전트가 구체적 태스크로 분해 |
|
||||
| **실행/테스트 불가** | 분석만 하고 실제 실행 못 함 | 샌드박스 + CI 연동 |
|
||||
| **확인의 어려움** | 결과를 보려면 IDE 열어야 | 디스코드로 중간 보고 + 컨펌 |
|
||||
|
||||
### 제안 아키텍처: AI Agent Team
|
||||
|
||||
```
|
||||
Discord (사용자 인터페이스)
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────┐
|
||||
│ Coordinator Agent │
|
||||
│ (Gemini CLI 또는 로컬 LLM) │
|
||||
│ │
|
||||
│ 역할: │
|
||||
│ - 사용자 명령 해석 │
|
||||
│ - 작업 분해 (추상 → 구체) │
|
||||
│ - 에이전트에게 작업 배분 │
|
||||
│ - 결과 종합 → 디스코드 보고 │
|
||||
└──┬──────────┬──────────┬────────────────┘
|
||||
│ │ │
|
||||
┌──▼──┐ ┌───▼───┐ ┌───▼───┐
|
||||
│분석 │ │구현 │ │테스트 │ ... 역할별
|
||||
│Agent │ │Agent │ │Agent │
|
||||
└──┬──┘ └───┬───┘ └───┬───┘
|
||||
│ │ │
|
||||
└──────────┼──────────┘
|
||||
│
|
||||
┌─────────▼─────────┐
|
||||
│ 실행 환경 │
|
||||
│ - 샌드박스 (코드) │
|
||||
│ - Gitea Runner │
|
||||
│ - CI/CD 파이프라인 │
|
||||
└───────────────────┘
|
||||
│
|
||||
디스코드로 결과 보고 + 사용자 컨펌
|
||||
│
|
||||
배포 / 완료
|
||||
```
|
||||
|
||||
### 이 목표를 이루기 위한 프로젝트 분해
|
||||
|
||||
| 프로젝트 | 설명 | 의존성 |
|
||||
|---------|------|--------|
|
||||
| **P1: Discord Bot** | 사용자 ↔ 시스템 인터페이스 | 없음 |
|
||||
| **P2: Task Decomposer** | 추상 명령 → 구체 태스크 목록 | Gemini CLI |
|
||||
| **P3: Agent Runner** | 역할별 `gemini -p` headless 호출 | Gemini CLI |
|
||||
| **P4: Sandbox** | 코드 실행/테스트 환경 | Docker 또는 로컬 격리 |
|
||||
| **P5: Gitea CI 연동** | PR 생성 → Runner 실행 → 결과 수집 | Gitea API |
|
||||
| **P6: 보안 분석 (Mode A)** | VEGA 확장, 내부 소스 보안 분석 | P3 + VEGA |
|
||||
|
||||
### 접근 전략
|
||||
|
||||
**단계적 구축 (작은 것부터 동작하게):**
|
||||
|
||||
```
|
||||
Step 1: Discord Bot + gemini -p 호출
|
||||
"디스코드로 질문 → Gemini 답변 → 디스코드로 반환"
|
||||
→ 가장 작은 동작 단위. 기초 인프라 검증.
|
||||
|
||||
Step 2: Task Decomposer
|
||||
"이 모듈 리팩토링해줘" → 구체 태스크 3개로 분해
|
||||
→ Gemini CLI의 plan mode 활용
|
||||
|
||||
Step 3: Agent Runner + 파일 접근
|
||||
분해된 태스크를 순차 실행, 파일 수정, 결과 보고
|
||||
→ gemini -p --approval-mode yolo
|
||||
|
||||
Step 4: Sandbox 실행
|
||||
수정된 코드를 샌드박스에서 실행/테스트
|
||||
→ Docker 컨테이너 또는 gemini --sandbox
|
||||
|
||||
Step 5: Gitea CI 연동
|
||||
수정 완료 → Gitea PR 생성 → Runner 실행 → 결과를 디스코드로
|
||||
→ Gitea API + Webhook
|
||||
|
||||
Step 6: 보안 분석 (Mode A)
|
||||
VEGA와 통합, 내부 소스 보안 분석 파이프라인
|
||||
```
|
||||
|
||||
### 핵심 원칙
|
||||
|
||||
1. **Gemini CLI가 에이전트 엔진** — 자기가 이미 파일 읽기/쓰기/실행 가능
|
||||
2. **headless 호출로 컨텍스트 분할** — 역할별/태스크별 독립 호출 → 포화 방지
|
||||
3. **디스코드 = 유일한 사용자 인터페이스** — 명령, 중간 보고, 컨펌 모두 디스코드에서
|
||||
4. **Gitea CI = 실행/배포 인프라** — 코드 수정 → PR → 빌드 → 테스트 → 배포
|
||||
5. **단계적 구축** — Step 1부터 동작 확인 후 다음 단계
|
||||
Reference in New Issue
Block a user