콘텐츠로 이동

크로스 플랫폼 규칙

이 페이지는 CLAUDE.md의 구현 노트를 미러합니다. CLAUDE.md가 컨트리뷰터 체크리스트의 canonical source — 이 페이지는 공개 버전.

Cue는 macOS 그리고 Windows에서 동작. 모든 기능 / 수정 / 동작 변경은 두 플랫폼에 적용해야 함. 이게 1년치의 플랫폼 drift를 막는 단 하나의 규칙.

PR 체크리스트

플랫폼 코드 건드리는 모든 변경마다:

  • [ ] src/cue/platform/macos.py에 함수 추가했으면 src/cue/platform/windows.py에 동등 추가 (반대도).
  • [ ] 플랫폼 모듈에서 새로 export하면 양쪽 플랫폼의 src/cue/platform/__init__.py에 추가.
  • [ ] CueApp (macOS)에 메뉴 항목 추가하면 _run_windows() 트레이 메뉴에도 추가.
  • [ ] scripts/build_macos.sh에 --hidden-import 추가하면 scripts/build_windows.bat AND scripts/build_installer.py 에도 추가.
  • [ ] pyproject.toml에 의존성 추가 시 공유인지 플랫폼별인지 결정.
  • [ ] store.py의 BLOCKED_APPS에 추가 시 macOS 앱 이름 AND Windows 프로세스 이름 (대소문자 무시) 둘 다 포함.
  • [ ] 파일 / 디렉토리 권한은 cue.fs.secure_dir() / secure_file() 사용 — raw os.chmod() 절대 금지.
  • [ ] 팝업 UI 변경은 두 플랫폼에서 테스트 (폰트 변수 FONT_UI / FONT_MONO가 플랫폼 폰트 처리).
  • [ ] 스트리밍 레코더는 vendoring된 ocap-{platform} CLI를 서브프로세스로 실행 — 새 CLI 옵션은 양쪽 ocap repo에서 지원 필요. 서브모듈 sync 유지; pull 후 git submodule update --init --recursive.

프로젝트 레이아웃

src/ 레이아웃 — 모든 패키지 코드는 src/cue/에. 엔트리 포인트: python -m cue 또는 run.py (frozen 빌드).

데이터 디렉토리

단일 진실 공급원: cue.config.CONFIG_DIR. 다른 곳에 플랫폼 경로 정의 금지 — CONFIG_DIR import.

이 원칙이 중요한 이유

한 항목 누락 비용이 큼 — cue/platform/__init__.py의 한 줄 잊은 import는 다른 플랫폼에서 카운터파트가 ship되지 않은 런타임 AttributeError로 surface. 1년 누적되면 모두 양쪽 ship한다고 생각하는 동안 코드베이스가 조용히 "macOS 전용" 또는 "Windows 전용"이 됨.

PR 리뷰가 체크리스트 강제.

명시적으로 크로스 플랫폼인 모듈

이들은 sys.platform 가드 없이 import되며 두 플랫폼에서 동일:

  • cue.capture — mss + Pillow 스크린샷.
  • cue.fs — secure_dir / secure_file / mark_not_indexed.
  • cue.config — CONFIG_DIR, streaming_config, privacy_config, get_api_key.
  • cue.recorder — 플랫폼별 ocap CLI 래핑.
  • cue.pruner — MKV reader가 자체 서브프로세스로 실행.
  • cue.digest, cue.llm, cue.frame_select, cue.image_preprocess, cue.llama_server, cue.local_models — 모두 platform-agnostic.
  • cue.privacy — 고수준 모니터 + 컨트롤러. 플랫폼별 watcher는 cue.platform의 작은 인터페이스 뒤에.
  • cue.overlay — 플랫폼별 overlay_macos / overlay_windows로 dispatch.
  • cue.settings_model, cue.settings_window, cue.popup_window — customtkinter UI 공유.
  • cue.pii, cue.pii_recognizers, cue.store, cue.prompts, cue.memory, cue.suggest — 순수 로직.

플랫폼에서 분기되는 모듈

src/cue/platform/__init__.py이 안정적 표면 export; 그 아래 구현이 다름:

  • cue.platform.macos — rumps tray, CGEventTap, AppleScript, Carbon, AX, NSWorkspace.
  • cue.platform.windows — pystray tray, pynput, UIA, SetWinEventHook, win32clipboard.
  • cue.platform.overlay_macos — pyobjc NSWindow per NSScreen.
  • cue.platform.overlay_windows — Tk Toplevel per monitor with WS_EX_LAYERED|TRANSPARENT|NOACTIVATE|TOOLWINDOW.

전체 동작 차이 표는 플랫폼 추상화 페이지에.

더 보기