From af4d7314a029d87a84820a6229d1fd41ad85a08f Mon Sep 17 00:00:00 2001 From: Variet Main Worker Date: Mon, 16 Mar 2026 21:48:29 +0000 Subject: [PATCH] Update "Architecture" --- Architecture.md | 307 ++++++++++++++++++++++++++++++++++++++++++------ 1 file changed, 268 insertions(+), 39 deletions(-) diff --git a/Architecture.md b/Architecture.md index b7455e5..05f535f 100644 --- a/Architecture.md +++ b/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) - ├── Extension (extension.ts) ← Bridge 핵심 (v0.3.12) - │ ├── setupMonitor() ← 5초 폴링 - │ ├── step_probe ← WAITING step 감지 - │ ├── DOM Observer ← 렌더러 버튼 감지 - │ ├── processResponseFile() ← Discord 응답 처리 - │ └── tryApprovalStrategies() ← RPC 실행 - ├── bridge/ (파일 시스템 IPC) - │ ├── pending/*.json - │ ├── 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) +┌────────────────┐ WebSocket ┌──────────────┐ Discord API ┌─────────┐ +│ VS Code │◄──────────────────►│ Hub Server │◄───────────────────►│ Discord │ +│ AG Extension │ type:auth/chat │ (hub.py + │ discord.py bot │ 서버 │ +│ (TypeScript) │ /pending/resp │ gateway.py)│ │ │ +└────────────────┘ └──────────────┘ └─────────┘ + ↕ AG SDK (RPC) ↕ +┌────────────────┐ ┌──────────────┐ +│ Antigravity │ │ 파일 bridge │ ← 레거시 fallback +│ AI Engine │ │ (bridge.py) │ (WS 미사용 시) +└────────────────┘ └──────────────┘ ``` -## 핵심 문서 +--- -| 문서 | 내용 | +## 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+ 항목) | -| `docs/usage-guide.md` | 사용 가이드 | -| `docs/tech-stack.md` | 기술 스택 정보 | +| 연결 관리 | 프로젝트별 다중 인스턴스, 인스턴스 번호 자동 부여 | +| JWT 인증 | registration_code → JWT 발급 → 이후 토큰 재인증 | +| 메시지 라우팅 | pending, chat, register, auto_resolve, brain_event | +| 응답 역라우팅 | 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개, 모듈 레벨):** -- `lastPendingStepIndex` — step 재감지 방지 -- `stallProbed` — 같은 stall에서 재probe 방지 -- `sawRunningAfterPending` — auto_resolve gate -- `sessionStalled` — stall 상태 플래그 -- `recentPendingSteps` — 메모리 dedup Map (60초 TTL) +### 3.3 Bot (bot.py) — Discord 인터페이스 -**위험 지점:** 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 등록 코드 | (서버에서 발급) |