From d06b1ea0db3ff869da31943b5fad1fa202448988 Mon Sep 17 00:00:00 2001 From: Variet Worker Date: Tue, 17 Mar 2026 22:06:52 +0900 Subject: [PATCH] =?UTF-8?q?docs:=20usage-guide=20WS=20Hub=20=EC=95=84?= =?UTF-8?q?=ED=82=A4=ED=85=8D=EC=B2=98=20=EC=97=85=EB=8D=B0=EC=9D=B4?= =?UTF-8?q?=ED=8A=B8=20+=20start=5Fbot.bat=20Collector=20=EA=B2=BD?= =?UTF-8?q?=EA=B3=A0=20=EC=B6=94=EA=B0=80?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/usage-guide.md | 141 ++++++++++++++++++-------------------------- start_bot.bat | 7 +++ 2 files changed, 65 insertions(+), 83 deletions(-) diff --git a/docs/usage-guide.md b/docs/usage-guide.md index b3a77fa..faf697d 100644 --- 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_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,103 +82,45 @@ 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로 대체됨)** | --- ## 설정 (.env) ```env -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 # 이벤트 디바운스 (초) +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 인증 코드 ``` --- -## 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) 실행 여부 확인 — 종료 필요 | diff --git a/start_bot.bat b/start_bot.bat index 844ba08..a2685d8 100644 --- 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" (