{"id":35849388,"url":"https://github.com/cccwon2/game-chat-guardian","last_synced_at":"2026-01-08T07:00:36.645Z","repository":{"id":322755406,"uuid":"1090698764","full_name":"cccwon2/game-chat-guardian","owner":"cccwon2","description":"게임 내 텍스트 채팅과 음성(마이크/시스템)을 실시간으로 감지합니다. 유해 표현(욕설, 혐오 발언 등)이 발견되면 사용자에게 비프음이나 TTS로 경고를 주는 Windows 앱입니다.","archived":false,"fork":false,"pushed_at":"2025-11-06T05:34:59.000Z","size":88,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-11-06T07:14:59.840Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cccwon2.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-11-06T02:42:32.000Z","updated_at":"2025-11-06T05:35:03.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/cccwon2/game-chat-guardian","commit_stats":null,"previous_names":["cccwon2/game-chat-guardian"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/cccwon2/game-chat-guardian","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cccwon2%2Fgame-chat-guardian","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cccwon2%2Fgame-chat-guardian/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cccwon2%2Fgame-chat-guardian/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cccwon2%2Fgame-chat-guardian/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cccwon2","download_url":"https://codeload.github.com/cccwon2/game-chat-guardian/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cccwon2%2Fgame-chat-guardian/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28242439,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2026-01-08T02:00:06.591Z","response_time":241,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-01-08T07:00:13.893Z","updated_at":"2026-01-08T07:00:36.635Z","avatar_url":"https://github.com/cccwon2.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Game Chat Guardian\n\n게임 내 텍스트 채팅과 음성(마이크/시스템)을 실시간으로 감지합니다. 유해 표현(욕설, 혐오 발언 등)이 발견되면 사용자에게 비프음이나 TTS로 경고를 주는 Windows 앱입니다.\n\n## 🎯 설계 철학 (Architecture Philosophy)\n\n\u003e **Headless + Tray-first + Context Overlay + Robust Errors + Preload Boundary**\n\n### 핵심 원칙\n\n1. **헤드리스 실행 (Headless)**\n   - 앱은 기본적으로 **헤드리스(트레이 전용)**로 실행됩니다\n   - 메인 창 없음: 작업표시줄에 표시되지 않음 (`skipTaskbar:true`)\n   - 트레이 아이콘 더블클릭 시에만 오버레이 창이 작업표시줄에 표시됨\n\n2. **트레이 우선 (Tray-first)**\n   - 시스템 트레이에 항상 표시\n   - 트레이 메뉴로 모든 기능 제어 (Show/Hide, Edit Mode, Quit)\n   - 네이티브 유틸리티 앱처럼 동작\n\n3. **컨텍스트 오버레이 (Context Overlay)**\n   - ROI 선택, HUD, 블러 처리는 모두 **투명 오버레이**에서 처리\n   - 클릭스루 기능: 기본 상태에서는 마우스 이벤트가 아래 앱으로 전달됨\n   - Edit Mode에서만 클릭스루 해제 (창 이동/조정 가능)\n\n4. **강력한 오류 처리 (Robust Errors)**\n   - 모든 권한/오류는 **Toast 알림**으로 표시\n   - 즉시 재시도 버튼 제공\n   - 재시도 시도 횟수/백오프 적용 (1s, 3s, 7s)\n\n5. **Preload API 경계 (Preload Boundary)**\n   - `nodeIntegration:false`, `contextIsolation:true`, `sandbox:true`\n   - UI는 `window.api.*`로만 시스템 기능 접근\n   - Zod로 런타임 타입 검증\n   - 명시적 API 화이트리스트만 노출\n\n## 🏗️ 프로젝트 구조\n\n```\napps/\n  web/            # Next.js 14 (App Router, TypeScript, Tailwind)\n  desktop/        # Electron main + preload + builder 설정\nservices/\n  stt/            # STT 마이크로서비스 (Express + Socket.IO)\npackages/\n  shared/         # 공용 타입/유틸\n```\n\n## 🚀 시작하기\n\n### 필수 요구사항\n\n- Node.js ≥ 20\n- npm 또는 pnpm\n\n### 설치\n\n```bash\n# 데스크톱 앱 디렉터리로 이동\ncd apps/desktop\n\n# 의존성 설치\nnpm install\n```\n\n### 개발 모드\n\n```bash\n# TypeScript 컴파일\nnpm run build\n\n# Electron 앱 실행\nnpm run dev\n```\n\n### 빌드\n\n```bash\n# TypeScript 컴파일\nnpm run build\n\n# Electron 앱 실행\nnpm start\n```\n\n## 📖 주요 기능\n\n### ✅ 구현 완료\n\n#### 1. 트레이 앱\n- 시스템 트레이 아이콘 등록\n- 컨텍스트 메뉴 (설정 열기, 종료)\n- 헤드리스 백그라운드 실행\n\n#### 2. 오버레이 창 및 ROI 선택\n- 투명하고 항상 위에 표시되는 오버레이 창\n- 마우스 드래그로 ROI(관심 영역) 선택\n- ROI 선택 후 자동으로 클릭스루 모드 전환\n\n#### 3. 화면 캡처 및 OCR (골격)\n- `desktopCapturer`를 사용한 화면 캡처\n- ROI 영역만 크롭하여 이미지 추출\n- ONNX 런타임 통합 (PaddleOCR 모델 로드 준비)\n- 주기적 캡처 루프 (1초 간격)\n\n#### 4. 오디오 캡처 및 STT (골격)\n- WASAPI 루프백 캡처 준비\n- VAD 및 faster-whisper 통합 준비\n- Python 워커 호출 구조 준비\n\n#### 5. 유해 표현 판단\n- 금칙어 사전 매칭\n- 화이트리스트 기반 오탐 방지\n- 텍스트 정규화 (소문자화, 특수문자 제거)\n- ONNX 분류기 통합 준비 (KOELECTRA 등)\n\n#### 6. 마스킹 및 경고\n- ROI 영역에 시각적 마스킹(블라인드) 표시\n- 우상단 토글 버튼으로 보기/가리기 전환 가능\n- SAFE 판정 수신 시 자동 해제, 경고음 재생\n\n#### 7. 상태 관리 (FSM)\n- 상태 머신 구현 (idle, capturing, recognizing, classifying, masking, error)\n- 상태 전이 로깅\n\n#### 8. 로컬 저장소\n- `rules.json`: 금칙어/화이트리스트 저장\n- `events.jsonl`: 유해 표현 감지 이벤트 로깅\n- `app.getPath('userData')` 경로에 저장\n\n### 🚧 향후 구현 예정\n\n- 실제 PaddleOCR ONNX 모델 통합\n- WASAPI 루프백 캡처 + VAD + faster-whisper 통합\n- ONNX 기반 분류기 (KOELECTRA 등) 통합\n- 설정 UI (메인 창)\n- 성능 최적화 및 CPU 사용량 모니터링\n\n## 🔒 보안\n\n- Electron 보안 설정:\n  - `nodeIntegration=false`\n  - `contextIsolation=true`\n  - `sandbox=true`\n- Preload에서 최소 API만 노출\n- IPC 채널 접두사: `app:*`\n\n## 🛠️ 기술 스택\n\n- **Desktop**: Electron 28, TypeScript\n- **OCR**: ONNX Runtime (Node.js 바인딩), PaddleOCR 준비\n- **STT**: faster-whisper 준비 (Python 워커)\n- **상태 관리**: 간단한 FSM (메인 프로세스)\n- **Package Manager**: npm\n\n## 📁 프로젝트 구조\n\n```\napps/desktop/\n  src/\n    main/\n      index.ts        # 메인 프로세스 (트레이, 오버레이, IPC)\n      capture.ts      # 화면 캡처 모듈\n      ocr.ts          # OCR 모듈 (ONNX)\n      stt.ts          # STT 모듈 (WASAPI + faster-whisper)\n      classifier.ts   # 유해 표현 판단 로직\n      storage.ts      # 로컬 저장소 (rules.json, events.jsonl)\n      fsm.ts          # 상태 머신\n    preload/\n      index.ts        # Preload 스크립트 (contextBridge)\n    overlay/\n      index.html      # 오버레이 HTML\n      overlay.ts      # 오버레이 렌더러 스크립트\n  assets/\n    beep.wav          # 경고음\n  dist/               # TypeScript 컴파일 결과\n```\n\n## 📝 설정 파일\n\n### rules.json\n금칙어 및 화이트리스트를 관리하는 파일입니다. `app.getPath('userData')` 경로에 저장됩니다.\n\n```json\n{\n  \"badwords\": [\"욕설\", \"비방\", \"혐오\"],\n  \"whitelist\": [\"게임\", \"채팅\", \"가드\"]\n}\n```\n\n### events.jsonl\n유해 표현 감지 이벤트를 한 줄씩 기록하는 로그 파일입니다.\n\n```jsonl\n{\"timestamp\":\"2024-01-01T00:00:00.000Z\",\"text\":\"유해 텍스트\",\"judgment\":\"HARMFUL\",\"reason\":\"금칙어: 욕설\"}\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcccwon2%2Fgame-chat-guardian","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcccwon2%2Fgame-chat-guardian","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcccwon2%2Fgame-chat-guardian/lists"}