708e20f747
Some checks failed
CI Pipeline / Code Quality & Typecheck (push) Waiting to run
CI Pipeline / Test Suite (macos-latest) (push) Blocked by required conditions
CI Pipeline / Test Suite (ubuntu-latest) (push) Blocked by required conditions
CI Pipeline / Test Suite (windows-latest) (push) Blocked by required conditions
CI Pipeline / Build Validation (admin) (push) Blocked by required conditions
CI Pipeline / Build Validation (desktop) (push) Blocked by required conditions
Deploy Landing Page / deploy (push) Blocked by required conditions
Deploy Landing Page / build (push) Waiting to run
Release & Packaging Pipeline / Build & Publish Admin Docker Image (push) Failing after 8s
Release & Code Signing CA Pipeline / build-and-sign-windows (push) Failing after 1m51s
Build macOS / Build & Package (macOS) (push) Failing after 4s
Build macOS / Build & Package (macOS)-1 (push) Failing after 5s
Release & Code Signing CA Pipeline / build-and-sign-macos (push) Failing after 3s
Release & Packaging Pipeline / Package macOS Desktop App (push) Failing after 4s
Release & Packaging Pipeline / Package Windows Desktop App (push) Failing after 2m28s
Release & Packaging Pipeline / Publish Official GitHub Release (push) Has been skipped
24 lines
2.6 KiB
Markdown
24 lines
2.6 KiB
Markdown
# Windows 데스크톱 앱 실행 및 Electron GUI 환경 지침
|
|
|
|
## 1. Windows 데스크톱 윈도우 스테이션 격리 (CRITICAL)
|
|
- **배경**: AI 에이전트 CLI(Antigravity 등) 내부의 도구 실행(`run_command`) 환경은 보안 격리 가상 데스크톱(`WinSta0\exebox-...`)에서 동작한다.
|
|
- **현상**: 에이전트 서브쉘에서 Electron GUI 앱을 실행하면 프로세스는 정상 구동되고 로그도 정상(`Main window shown`)이지만, 사용자의 실제 모니터 화면(`WinSta0\Default`)에는 창이 물리적으로 보이지 않는다.
|
|
- **규칙**:
|
|
- 에이전트가 단독으로 GUI 창을 사용자 화면에 띄우려고 무리하게 백그라운드 구동을 반복하지 말 것.
|
|
- GUI 테스트/실행이 필요할 때는 사용자가 직접 외부 터미널 또는 파일 탐색기에서 `run-desktop.bat` 또는 `pnpm --filter @d3ro/desktop dev`를 실행하도록 안내한다.
|
|
|
|
## 2. Electron 단일 인스턴스 잠금 (Single Instance Lock) & 사일런트 종료 방지
|
|
- **앱 식별자 명시**: `src/main/index.ts` 최상단에서 `app.requestSingleInstanceLock()` 호출 전에 반드시 `app.setName('d3ro-voice')`와 `app.setAppUserModelId('kr.twentyoz.d3ro-voice')`를 선언하여 일반 'Electron' 프로세스와의 식별자 충돌을 방지한다.
|
|
- **사일런트 종료 방지**: 개발 환경(`!app.isPackaged`)에서 락 파일 잔여물로 인해 무조건 사일런트 종료(`app.quit()`)되는 일이 없도록 보호 처리를 유지한다.
|
|
- **실행 스크립트 선제 정리**: `run-desktop.bat`에는 잔여 프로세스 및 stale `lockfile` 정리가 포함되어 있어야 한다.
|
|
|
|
## 3. 오디오 장치 탐색 동기 블로킹 금지
|
|
- Windows 마이크 디바이스 열거 시 `execSync`를 절대 사용하지 않는다. (Windows 환경에서 5초 `ETIMEDOUT` 메인 이벤트루프 프리징 유발)
|
|
- 반드시 `child_process.exec` 비동기 논블로킹 및 3초 타임아웃, 기본 마이크 폴백 구조를 유지한다.
|
|
|
|
## 4. GPU 하드웨어 가속 충돌 및 투명 창 방지
|
|
- NVIDIA 드라이버, Razer Chroma, Oculus 등의 훅 소프트웨어로 인해 창이 투명/블랭크 처리되는 문제를 방지하기 위해 `app.disableHardwareAcceleration()` 및 `disable-gpu` 스위치를 유지한다.
|
|
|
|
## 5. 윈도우 화면 배치 및 작업표시줄 등록
|
|
- `screen.getPrimaryDisplay().workAreaSize`를 기준으로 `(x, y)` 중앙 좌표를 명시 계산하여 다중 모니터 이탈을 방지한다.
|
|
- `setSkipTaskbar(false)`로 작업표시줄 노출을 보장하고, `ready-to-show`에서 `show()`, `restore()`, `focus()`, `flashFrame(true)`를 순차 실행한다.
|