# Gravity Control 사용 가이드

## 시작하기

### 1. 서버 (Docker Gateway)

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

```bash
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 설치

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

### 3. Extension 설정

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

```json
{
  "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)

```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) 실행 여부 확인 — 종료 필요 |