Update "Architecture"
307
Architecture.md
307
Architecture.md
@@ -1,51 +1,280 @@
|
|||||||
# Gravity Control — Architecture
|
# Architecture
|
||||||
|
|
||||||
## 시스템 구조
|
> AI 에이전트는 구현 전 이 문서를 반드시 확인합니다.
|
||||||
|
|
||||||
|
## 1. 프로젝트 개요
|
||||||
|
|
||||||
|
**Gravity Control**은 Antigravity AI 코딩 에이전트와 Discord를 실시간으로 연결하는 브릿지 시스템이다.
|
||||||
|
|
||||||
|
### 핵심 목적
|
||||||
|
- AI 에이전트의 **승인 요청**(코드 실행, 파일 수정 등)을 Discord로 전달하고 사용자 응답을 반환
|
||||||
|
- AI 에이전트의 **작업 스냅샷**(대화 요약, 진행 상황)을 Discord에 실시간 표시
|
||||||
|
- **코드 리뷰**(diff review) accept/reject을 Discord에서 처리
|
||||||
|
- 사용자의 Discord **명령어**(!approve, !reject, !auto 등)를 AG Extension으로 전달
|
||||||
|
- **Auto-approve 모드**로 무인 작업 지원
|
||||||
|
|
||||||
|
### 시스템 구성
|
||||||
|
|
||||||
```
|
```
|
||||||
AG IDE (Antigravity)
|
┌────────────────┐ WebSocket ┌──────────────┐ Discord API ┌─────────┐
|
||||||
├── Extension (extension.ts) ← Bridge 핵심 (v0.3.12)
|
│ VS Code │◄──────────────────►│ Hub Server │◄───────────────────►│ Discord │
|
||||||
│ ├── setupMonitor() ← 5초 폴링
|
│ AG Extension │ type:auth/chat │ (hub.py + │ discord.py bot │ 서버 │
|
||||||
│ ├── step_probe ← WAITING step 감지
|
│ (TypeScript) │ /pending/resp │ gateway.py)│ │ │
|
||||||
│ ├── DOM Observer ← 렌더러 버튼 감지
|
└────────────────┘ └──────────────┘ └─────────┘
|
||||||
│ ├── processResponseFile() ← Discord 응답 처리
|
↕ AG SDK (RPC) ↕
|
||||||
│ └── tryApprovalStrategies() ← RPC 실행
|
┌────────────────┐ ┌──────────────┐
|
||||||
├── bridge/ (파일 시스템 IPC)
|
│ Antigravity │ │ 파일 bridge │ ← 레거시 fallback
|
||||||
│ ├── pending/*.json
|
│ AI Engine │ │ (bridge.py) │ (WS 미사용 시)
|
||||||
│ ├── response/*.json
|
└────────────────┘ └──────────────┘
|
||||||
│ ├── snapshot/*.json
|
|
||||||
│ └── register/*.json
|
|
||||||
└── Bot (bot.py) ← Discord 통신
|
|
||||||
├── pending_approval_scanner
|
|
||||||
├── auto_approve_scanner
|
|
||||||
└── snapshot_scanner
|
|
||||||
|
|
||||||
Collector (collector.py) ← Local ↔ Gateway 중계
|
|
||||||
Gateway (gateway.py) ← VPS HTTP API (Docker + Caddy)
|
|
||||||
```
|
```
|
||||||
|
|
||||||
## 핵심 문서
|
---
|
||||||
|
|
||||||
| 문서 | 내용 |
|
## 2. 디렉토리 구조
|
||||||
|
|
||||||
|
```
|
||||||
|
gravity_control/
|
||||||
|
├── main.py # 진입점: Bot + Hub + Watcher 통합 시작
|
||||||
|
├── config.py # 환경변수 + .env 로드 (66줄)
|
||||||
|
│
|
||||||
|
├── ── 서버 측 (Python) ──
|
||||||
|
├── bot.py # Discord 봇: 승인 UI, 채널 관리, Hub 핸들러 (1,286줄)
|
||||||
|
├── hub.py # WebSocket Hub: 연결 관리, 메시지 라우팅 (580줄)
|
||||||
|
├── auth.py # JWT 토큰 + registration code 인증 (127줄)
|
||||||
|
├── gateway.py # HTTP REST API + /ws endpoint (310줄)
|
||||||
|
├── bridge.py # 파일 기반 IPC (레거시 fallback) (479줄)
|
||||||
|
├── watcher.py # Brain 디렉토리 변경 감시 (290줄)
|
||||||
|
├── parser.py # Markdown → Discord 변환 (245줄)
|
||||||
|
├── collector.py # 원격 파일→HTTP 릴레이 (Phase 2 삭제 예정) (517줄)
|
||||||
|
│
|
||||||
|
├── ── Extension 측 (TypeScript) ──
|
||||||
|
├── extension/src/
|
||||||
|
│ ├── extension.ts # 메인: SDK init, activate, HTTP bridge (1,290줄)
|
||||||
|
│ ├── step-probe.ts # 폴링 + 응답 처리 + 승인 전략 (1,435줄)
|
||||||
|
│ │ # setupMonitor(), processResponseFile(),
|
||||||
|
│ │ # writePendingApproval(), tryApprovalStrategies()
|
||||||
|
│ ├── observer-script.ts # DOM Observer 스크립트 생성 (698줄)
|
||||||
|
│ │ # generateApprovalObserverScript()
|
||||||
|
│ ├── ws-client.ts # WSBridgeClient: Hub 연결, 재연결, 큐 (505줄)
|
||||||
|
│ ├── step-utils.ts # Step 파싱 순수 함수 4개 (114줄)
|
||||||
|
│ │ # extractPlannerText, filterEphemeral,
|
||||||
|
│ │ # extractToolCommand, extractToolDescription
|
||||||
|
│ └── sdk/ # Antigravity SDK 로컬 임베드
|
||||||
|
│ ├── index.js # SDK 런타임 (4,014줄)
|
||||||
|
│ └── index.d.ts # SDK 타입 정의 (2,297줄)
|
||||||
|
│
|
||||||
|
├── ── 테스트 ──
|
||||||
|
├── tests/
|
||||||
|
│ ├── test_ws_hub.py # Hub WS 연결 테스트
|
||||||
|
│ └── test_syntax.py # Python 구문 검증
|
||||||
|
│
|
||||||
|
├── ── 문서 / 설정 ──
|
||||||
|
├── .env # 환경변수 (git 제외)
|
||||||
|
├── .agents/references/ # AI 에이전트 레퍼런스
|
||||||
|
├── docs/devlog/ # 작업 로그
|
||||||
|
└── start_bot.bat # 윈도우용 봇 시작 스크립트
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 3. 핵심 모듈 상세
|
||||||
|
|
||||||
|
### 3.1 Hub (hub.py) — WebSocket 메시지 허브
|
||||||
|
|
||||||
|
**역할**: Extension ↔ Bot 간 실시간 양방향 통신 중계
|
||||||
|
|
||||||
|
| 기능 | 설명 |
|
||||||
|------|------|
|
|------|------|
|
||||||
| `docs/approval-flow.md` | 승인 시스템 전체 Flow, 상태 변수, 전이 다이어그램 |
|
| 연결 관리 | 프로젝트별 다중 인스턴스, 인스턴스 번호 자동 부여 |
|
||||||
| `.agents/references/known-issues.md` | 모든 이슈/교훈 SSOT (50+ 항목) |
|
| JWT 인증 | registration_code → JWT 발급 → 이후 토큰 재인증 |
|
||||||
| `docs/usage-guide.md` | 사용 가이드 |
|
| 메시지 라우팅 | pending, chat, register, auto_resolve, brain_event |
|
||||||
| `docs/tech-stack.md` | 기술 스택 정보 |
|
| 응답 역라우팅 | request_id → pending_owners → 원본 Extension으로 전달 |
|
||||||
|
| Rate limiting | per-connection 100msg/10s |
|
||||||
|
| Dedup | msg_id 기반 60s TTL 중복 제거 |
|
||||||
|
| Heartbeat | 30s 간격 ping/pong |
|
||||||
|
|
||||||
## 승인 Flow 개요
|
**프로토콜**:
|
||||||
|
```
|
||||||
|
1. Client → Server: {type:"auth", registration_code/token, project, pc}
|
||||||
|
2. Server → Client: {type:"auth_ok", conn_id, instance_number, session_token}
|
||||||
|
3. 양방향 메시지 교환:
|
||||||
|
- Extension→Hub: pending, chat, register, auto_resolve, brain_event
|
||||||
|
- Hub→Extension: response, command, instance_update, error
|
||||||
|
```
|
||||||
|
|
||||||
자세한 내용 → `docs/approval-flow.md`
|
### 3.2 Auth (auth.py) — 인증 관리
|
||||||
|
|
||||||
**2가지 pending 생성 경로:**
|
| 기능 | 설명 |
|
||||||
1. Step Probe → `writePendingApproval()` (메모리 dedup 포함)
|
|------|------|
|
||||||
2. DOM Observer → HTTP POST `/pending` (파일 기반 dedup만)
|
| Registration Code | 사전 공유 코드로 최초 인증 |
|
||||||
|
| JWT 발급 | HMAC-SHA256, 24시간 유효 |
|
||||||
|
| 토큰 검증 | 만료/위조 감지, 프로젝트+PC 메타데이터 포함 |
|
||||||
|
|
||||||
**핵심 상태 변수 (5개, 모듈 레벨):**
|
### 3.3 Bot (bot.py) — Discord 인터페이스
|
||||||
- `lastPendingStepIndex` — step 재감지 방지
|
|
||||||
- `stallProbed` — 같은 stall에서 재probe 방지
|
|
||||||
- `sawRunningAfterPending` — auto_resolve gate
|
|
||||||
- `sessionStalled` — stall 상태 플래그
|
|
||||||
- `recentPendingSteps` — 메모리 dedup Map (60초 TTL)
|
|
||||||
|
|
||||||
**위험 지점:** processResponseFile의 상태 리셋 — `sawRunningAfterPending = true`만 설정. 절대 lastPendingStepIndex나 stallProbed를 건드리지 말 것 (무한 루프 또는 회귀 발생).
|
| 기능 | 설명 |
|
||||||
|
|------|------|
|
||||||
|
| 승인 UI | Approve/Reject 버튼, diff_review Accept/Reject |
|
||||||
|
| Auto-approve | `!auto` 토글, 세션 간 초기화 |
|
||||||
|
| 채널 관리 | `#ag-{project}` 자동 채널 매칭 |
|
||||||
|
| 스냅샷 전달 | 2000자 초과 시 파일 첨부 |
|
||||||
|
| 명령어 | !approve, !reject, !auto, !status, !send |
|
||||||
|
| Hub 연동 | on_hub_pending, on_hub_chat, on_hub_register 핸들러 |
|
||||||
|
| IDLE 알림 | AI step 종료 시 Discord 알림 |
|
||||||
|
|
||||||
|
### 3.4 Extension (extension.ts) — VS Code 확장
|
||||||
|
|
||||||
|
| 기능 | 설명 |
|
||||||
|
|------|------|
|
||||||
|
| AG SDK 연동 | getCascadeStatus, getAllTrajectories RPC |
|
||||||
|
| 세션 감지 | activeSessionId 자동 추적 |
|
||||||
|
| 프로젝트 자동 감지 | git remote URL 기반 |
|
||||||
|
| HTTP bridge | 파일 기반 pending/response 읽기쓰기 (레거시) |
|
||||||
|
| WS bridge | WSBridgeClient 통한 Hub 연결 (우선) |
|
||||||
|
| Status bar | SDK 상태 + 연결 상태 표시 |
|
||||||
|
|
||||||
|
### 3.5 Step Probe (step-probe.ts) — 상태 폴링
|
||||||
|
|
||||||
|
`BridgeContext` 인터페이스로 extension.ts와 상태 공유:
|
||||||
|
|
||||||
|
| 기능 | 설명 |
|
||||||
|
|------|------|
|
||||||
|
| setupMonitor | 3초 간격 SDK 폴링, 세션/step 변화 감지 |
|
||||||
|
| processResponseFile | Discord 응답 → AG RPC 실행 |
|
||||||
|
| writePendingApproval | 승인 요청 파일/WS 전송 |
|
||||||
|
| tryApprovalStrategies | 다단계 승인: DOM click → VS Code command → RPC |
|
||||||
|
| setupResponseWatcher | response/ 디렉토리 파일 감시 |
|
||||||
|
|
||||||
|
**BridgeContext 필드** (14개):
|
||||||
|
`bridgePath`, `projectName`, `sdk`, `wsBridge`, `logToFile`, `autoApproveEnabled`, `activeSessionId`, `sentPendingIds`, `deterministicPort`, `recentDiscordSentTexts`, `writeChatSnapshot`, `writeChatSnapshotWithFiles`, `workspaceUri`, `diffReviewMetadata`
|
||||||
|
|
||||||
|
### 3.6 WS Client (ws-client.ts) — Hub 클라이언트
|
||||||
|
|
||||||
|
| 기능 | 설명 |
|
||||||
|
|------|------|
|
||||||
|
| 연결 관리 | WebSocket + 자동 재연결 |
|
||||||
|
| Backoff | 1s→60s 지수 백오프 + ±30% jitter |
|
||||||
|
| 메시지 큐 | 200개 버퍼, 재연결 시 자동 flush |
|
||||||
|
| Heartbeat | 25s 간격 ping |
|
||||||
|
| 인증 | registration_code 또는 session_token |
|
||||||
|
| API | sendPending, sendChat, sendRegister, sendAutoResolve |
|
||||||
|
|
||||||
|
### 3.7 Observer Script (observer-script.ts)
|
||||||
|
|
||||||
|
AG Webview의 DOM을 관찰하여 승인 버튼을 자동 감지/클릭:
|
||||||
|
- MutationObserver로 `.actions-container` 감시
|
||||||
|
- 버튼 텍스트 매칭으로 Approve/Reject 자동 실행
|
||||||
|
- `postMessage`로 Extension과 통신
|
||||||
|
|
||||||
|
### 3.8 Step Utils (step-utils.ts)
|
||||||
|
|
||||||
|
순수 함수 4개:
|
||||||
|
- `extractPlannerText(content)` — AI 응답 텍스트 추출
|
||||||
|
- `filterEphemeral(text)` — 시스템 메시지 필터링
|
||||||
|
- `extractToolCommand(content)` — 도구 명령어 추출
|
||||||
|
- `extractToolDescription(content)` — 도구 설명 추출
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 4. 데이터 흐름
|
||||||
|
|
||||||
|
### 4.1 승인 요청 플로우
|
||||||
|
|
||||||
|
```
|
||||||
|
AG Engine → SDK RPC → Extension(step-probe.ts)
|
||||||
|
→ setupMonitor: WAITING step 감지
|
||||||
|
→ writePendingApproval: pending 데이터 생성
|
||||||
|
→ [WS] wsBridge.sendPending() → Hub → Bot → Discord (버튼 UI)
|
||||||
|
→ [파일] bridge/pending/{id}.json (fallback)
|
||||||
|
```
|
||||||
|
|
||||||
|
### 4.2 승인 응답 플로우
|
||||||
|
|
||||||
|
```
|
||||||
|
Discord (사용자 버튼 클릭) → Bot
|
||||||
|
→ [Hub connected] Hub.route_response() → WS → Extension
|
||||||
|
→ [File fallback] bridge/response/{id}.json → setupResponseWatcher
|
||||||
|
→ processResponseFile → tryApprovalStrategies
|
||||||
|
1차: DOM observer script (webview inject)
|
||||||
|
2차: VS Code command (cascade.approveCurrentStep)
|
||||||
|
3차: Direct RPC (acknowledgeCodeActionStep)
|
||||||
|
```
|
||||||
|
|
||||||
|
### 4.3 채팅 스냅샷 플로우
|
||||||
|
|
||||||
|
```
|
||||||
|
Extension(step-probe.ts) → 새 step 텍스트 감지
|
||||||
|
→ writeChatSnapshot(text) → truncation + dedup
|
||||||
|
→ [WS] wsBridge.sendChat() → Hub → Bot → Discord (#ag-{project})
|
||||||
|
→ [파일] bridge/pending/ snapshot 파일 (fallback)
|
||||||
|
```
|
||||||
|
|
||||||
|
### 4.4 Diff Review 플로우
|
||||||
|
|
||||||
|
```
|
||||||
|
AG Engine → 파일 수정 → Extension(step-probe.ts)
|
||||||
|
→ edit_step_indices + modified_files 메타데이터 수집
|
||||||
|
→ writePendingApproval (step_type="diff_review")
|
||||||
|
→ Discord (Accept all / Reject all 버튼)
|
||||||
|
→ 응답 → acknowledgeCodeActionStep RPC
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 5. 통신 프로토콜
|
||||||
|
|
||||||
|
### 5.1 WebSocket 메시지 타입
|
||||||
|
|
||||||
|
**Extension → Hub (upstream)**:
|
||||||
|
|
||||||
|
| type | data 필드 | 설명 |
|
||||||
|
|------|-----------|------|
|
||||||
|
| `auth` | registration_code/token, project, pc | 최초 인증 |
|
||||||
|
| `pending` | request_id, command, description, buttons | 승인 요청 |
|
||||||
|
| `chat` | content, attached_files, conversation_id | 채팅 스냅샷 |
|
||||||
|
| `register` | conversation_id, project_name | 세션 등록 |
|
||||||
|
| `auto_resolve` | request_id | 자동 해결 알림 |
|
||||||
|
| `brain_event` | (payload) | 브레인 이벤트 |
|
||||||
|
| `heartbeat` | - | 연결 유지 |
|
||||||
|
|
||||||
|
**Hub → Extension (downstream)**:
|
||||||
|
|
||||||
|
| type | data 필드 | 설명 |
|
||||||
|
|------|-----------|------|
|
||||||
|
| `auth_ok` | conn_id, instance_number, session_token | 인증 성공 |
|
||||||
|
| `auth_fail` | reason | 인증 실패 |
|
||||||
|
| `response` | request_id, approved, button_index | 승인 응답 |
|
||||||
|
| `command` | text, action | Discord 명령어 |
|
||||||
|
| `instance_update` | active_count, instances[] | 인스턴스 변경 |
|
||||||
|
| `error` | error | 에러 |
|
||||||
|
|
||||||
|
### 5.2 BOT_MODE 동작 차이
|
||||||
|
|
||||||
|
| 모드 | Watcher | Hub/Gateway | 용도 |
|
||||||
|
|------|---------|-------------|------|
|
||||||
|
| `local` | ✅ (brain 감시) | ❌ | 로컬 개발 (Extension과 같은 PC) |
|
||||||
|
| `gateway` | ❌ | ✅ (port 8585) | 서버 배포 (WS Hub + Gateway) |
|
||||||
|
| `remote` | ✅ | ❌ | 원격 브릿지 (레거시 Collector) |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 6. 보안
|
||||||
|
|
||||||
|
| 항목 | 구현 |
|
||||||
|
|------|------|
|
||||||
|
| WS 인증 | Registration Code → JWT (HMAC-SHA256, 24h) |
|
||||||
|
| Gateway API | API Key 헤더 (`X-API-Key`) |
|
||||||
|
| Rate limit | per-connection 100msg/10s |
|
||||||
|
| 메시지 dedup | msg_id 기반 60s TTL |
|
||||||
|
| Discord | Bot 토큰 + Guild ID 제한 |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 7. Extension 설정 (VS Code)
|
||||||
|
|
||||||
|
| 설정 키 | 설명 | 기본값 |
|
||||||
|
|---------|------|--------|
|
||||||
|
| `gravityBridge.bridgePath` | Bridge 디렉토리 경로 | `~/.gemini/antigravity/bridge` |
|
||||||
|
| `gravityBridge.projectName` | 프로젝트 이름 | git remote 자동 감지 |
|
||||||
|
| `gravityBridge.hubUrl` | WebSocket Hub URL | (비어있으면 WS 비활성) |
|
||||||
|
| `gravityBridge.registrationCode` | Hub 등록 코드 | (서버에서 발급) |
|
||||||
|
|||||||
Reference in New Issue
Block a user