gravity_control/docs/usage-guide.md

Gravity Control 사용 가이드

시작하기

1. 서버 (Docker Gateway)

서버에서 Bot + Hub + Gateway를 Docker로 실행:

git clone https://git.variet.net/Variet/gravity_control.git
cd gravity_control
cp .env.example .env   # DISCORD_TOKEN, DISCORD_GUILD_ID 등 설정
docker compose up -d
docker compose logs -f  # 로그 확인

2. Extension 설치

cd extension
cmd /c npm run compile
cmd /c npx vsce package
# 생성된 .vsix 파일을 VS Code에서 설치

3. Extension 설정

VS Code settings.json에 Hub 연결 정보 추가:

{
  "gravityBridge.hubUrl": "wss://ag.variet.net/ws",
  "gravityBridge.registrationCode": "<GRAVITY_REGISTRATION_CODE 값>"
}

참고: 환경변수 GRAVITY_HUB_URL, GRAVITY_REGISTRATION_CODE로도 설정 가능하나, VS Code 시작 전에 설정되어야 합니다. settings.json 사용을 권장합니다.

---

아키텍처

[AG IDE] ← Extension ──WS──→ Hub (서버) ←→ Bot ←→ Discord
              │                  │
              └── step_probe     └── pending_owners
                  (WAITING 감지)     (응답 라우팅)

• Extension → Hub: WebSocket으로 pending, chat_snapshot, register 전송
• Hub → Extension: WebSocket으로 command, response 실시간 전송
• File bridge: WS 미연결 시 폴백 (로컬 ~/.gemini/antigravity/bridge/)

---

Discord 명령어

채팅 명령어 (메시지 입력)

명령어	설명
!auto	자동 승인 토글 (on/off 반복)
!stop	AG 에이전트 중단
!N 텍스트	N번 PC 인스턴스에만 전달 (예: !2 진행해)
그 외 텍스트	AG에 직접 메시지 전달

슬래시 명령어

명령어	설명
/auto	자동 승인 토글 (on/off 반복)
/stop	AG 에이전트 중단

---

자동 승인 (!auto)

Discord에서 !auto 를 입력할 때마다 on↔off 토글됩니다.

동작

• OFF (기본): 승인 요청마다 Discord에 ✅/❌ 버튼 표시 → 클릭하여 수동 승인
• ON: 승인 요청 시 자동으로 승인 → Discord에 🤖 자동 승인됨 표시

주의: 봇 재시작 시 auto-approve 상태는 초기화됩니다 (기본 OFF).

---

Bot Mode

모드	설정	설명
gateway	BOT_MODE=gateway	서버: Bot + Hub WS + Gateway HTTP API (Docker)
local	BOT_MODE=local	로컬: 파일 bridge 전용 (Hub 없이 단독 실행)
remote	BOT_MODE=remote	Collector 모드 (deprecated — WS Hub로 대체됨)

---

설정 (.env)

DISCORD_TOKEN=xxx              # Discord 봇 토큰 (필수)
DISCORD_GUILD_ID=xxx           # Discord 서버 ID (필수)
BRAIN_PATH=                    # AG 브레인 경로 (기본: ~/.gemini/antigravity/brain)
BOT_MODE=gateway               # 봇 모드 (gateway/local)
GATEWAY_PORT=8585              # Gateway 포트
GATEWAY_API_KEY=xxx            # Gateway API 인증 키
GRAVITY_REGISTRATION_CODE=xxx  # Extension WS 인증 코드

---

Gateway API

메서드	경로	설명
GET	/health	헬스체크
GET	/ws	Extension WebSocket 연결
GET	/hub/status	Hub 연결 상태
POST	/api/pending	승인 요청 (API/Collector)
GET	/api/response/{rid}	승인 응답 조회
POST	/api/chat	채팅 스냅샷 전송
GET	/api/commands/{project}	명령 폴링

---

트러블슈팅

증상	해결
승인 클릭해도 AG 반응 없음	Hub WS 연결 확인: /hub/status → Extension이 connected인지
!auto 했는데 자동 승인 안 됨	Extension VSIX 재빌드 + 재설치 필요
봇 재시작 후 auto가 꺼져있음	정상 — !auto로 다시 켜기
Python 못 찾음	C:\ProgramData\miniforge3\envs\gravity_control\python.exe 사용
Discord 메시지 이중 전달	로컬 Collector (python main.py BOT_MODE=remote) 실행 여부 확인 — 종료 필요