docs: usage-guide WS Hub 아키텍처 업데이트 + start_bot.bat Collector 경고 추가

2026-03-17 22:06:52 +09:00
parent 48ae19b3e1
commit d06b1ea0db
2 changed files with 65 additions and 83 deletions
--- a/docs/usage-guide.md
+++ b/docs/usage-guide.md
@@ -2,14 +2,16 @@

 ## 시작하기

-### 1. 봇 실행
+### 1. 서버 (Docker Gateway)

-```batch
-start_bot.bat
-```
-또는:
-```powershell
-C:\ProgramData\miniforge3\envs\gravity_control\python.exe main.py
+서버에서 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 설치
@@ -21,6 +23,34 @@ 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 명령어
@@ -31,6 +61,7 @@ cmd /c npx vsce package
 |--------|------|
 | `!auto` | 자동 승인 토글 (on/off 반복) |
 | `!stop` | AG 에이전트 중단 |
+| `!N 텍스트` | N번 PC 인스턴스에만 전달 (예: `!2 진행해`) |
 | 그 외 텍스트 | AG에 직접 메시지 전달 |

 ### 슬래시 명령어
@@ -51,58 +82,17 @@ Discord에서 `!auto` 를 입력할 때마다 on↔off 토글됩니다.
 - **OFF (기본)**: 승인 요청마다 Discord에 ✅/❌ 버튼 표시 → 클릭하여 수동 승인
 - **ON**: 승인 요청 시 자동으로 승인 → Discord에 `🤖 자동 승인됨` 표시

-```
-사용자: !auto
-봇:     🟢 자동 승인 모드
-        프로젝트: gravity_control
-        모든 승인 요청이 자동으로 승인됩니다
-
-사용자: !auto
-봇:     🔴 수동 승인 모드
-        프로젝트: gravity_control
-        모든 승인 요청이 수동 확인이 필요합니다
-```
-
-### 자동 승인 시 Discord 표시
-
-```
-🤖 자동 승인됨
-┌─────────────────────────────┐
-│ run_command: npm run build  │
-└─────────────────────────────┘
-auto-approve | 1741678...
-```
-
 > **주의**: 봇 재시작 시 auto-approve 상태는 초기화됩니다 (기본 OFF).

 ---

-## 아키텍처
-
-```
-[AG IDE] ← Extension → bridge/ ← Bot → Discord
-              │                    │
-              └── step_probe       └── pending 스캔
-                  (WAITING 감지)       (자동 승인 처리)
-```
-
-### Bridge 프로토콜
-
-```
-~/.gemini/antigravity/bridge/
-├── pending/     Extension → Bot (승인 요청)
-├── response/    Bot → Extension (승인 결과)
-├── commands/    Bot → Extension (사용자 명령)
-└── register/    Extension → Bot (세션 매핑)
-```
-
-### Bot Mode
+## Bot Mode

 | 모드 | 설정 | 설명 |
 |------|------|------|
-| `local` (기본) | `BOT_MODE=local` | 로컬 파일시스템 bridge 사용 |
-| `remote` (미래) | `BOT_MODE=remote` | HTTP로 원격 bridge 폴링 (Collector 모드) |
-| `gateway` | `BOT_MODE=gateway` | 서버에서 Discord 통신 + HTTP API (Docker용) |
+| `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로 대체됨)** |

 ---

@@ -112,42 +102,25 @@ auto-approve | 1741678...
 DISCORD_TOKEN=xxx              # Discord 봇 토큰 (필수)
 DISCORD_GUILD_ID=xxx           # Discord 서버 ID (필수)
 BRAIN_PATH=                    # AG 브레인 경로 (기본: ~/.gemini/antigravity/brain)
-BOT_MODE=local             # 봇 모드 (local/remote)
-REMOTE_BRIDGE_URL=         # 원격 브릿지 URL (remote 모드 전용)
-DEBOUNCE_SECONDS=2         # 이벤트 디바운스 (초)
+BOT_MODE=gateway               # 봇 모드 (gateway/local)
+GATEWAY_PORT=8585              # Gateway 포트
+GATEWAY_API_KEY=xxx            # Gateway API 인증 키
+GRAVITY_REGISTRATION_CODE=xxx  # Extension WS 인증 코드
 ```

 ---

-## Docker 배포 (Gateway)
-
-서버에서 Gateway 봇을 Docker로 실행:
-
-```
-[로컬 PC]                              [서버 Docker]
-Extension → bridge/ ← 로컬 Bot ──HTTP──→ Gateway :8585 ←→ Discord
-                     (Collector)
-```
-
-### 서버에서 실행
-
-```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  # 로그 확인
-```
-
-### Gateway API
+## Gateway API

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

 ---

@@ -155,6 +128,8 @@ docker compose logs -f  # 로그 확인

 | 증상 | 해결 |
 |------|------|
+| 승인 클릭해도 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) 실행 여부 확인 — 종료 필요 |
--- a/start_bot.bat
+++ b/start_bot.bat
@@ -7,6 +7,13 @@ echo ║     Gravity Bridge Bot Launcher      ║
 echo ╚══════════════════════════════════════╝
 echo.

+echo [WARN] 로컬 Collector (BOT_MODE=remote)는 더 이상 필요하지 않습니다.
+echo [WARN] Extension이 WebSocket으로 Hub에 직접 연결합니다.
+echo [WARN] 서버에서 Docker로 실행하세요: docker compose up -d
+echo.
+echo 로컬 테스트 (BOT_MODE=local)를 원하시면 아무 키나 누르세요...
+pause >nul
+
 REM — Find Python (conda first, then system)
 set PYTHON=
 if exist "C:\ProgramData\miniforge3\envs\gravity_control\python.exe" (