콘텐츠로 이동

서브모듈 / 벤더링

이 페이지는 CLAUDE.md의 구현 노트를 미러합니다. 서브시스템 변경 시 양쪽 다 업데이트하세요.

Cue는 vendor/ 아래 세 git 서브모듈과 함께 ship. 동작 보장을 재현 가능하게 유지하기 위해 특정 브랜치에 핀.

vendor 아래 무엇

vendor/
├── open-world-agents-private/
│       └── projects/
│           ├── owa-core/                # Runnable / Listener 베이스 클래스
│           ├── owa-msgs/                # 메시지 스키마 (KeyboardEvent, ScreenCaptured, ...)
│           ├── owa-env-desktop/         # 플랫폼별 키보드/마우스/윈도우 리스너
│           └── mcap-owa-support/        # owa 메시지용 MCAP 쓰기/읽기
├── ocap-macos/                          # owa.ocap_macos.recorder — GStreamer 파이프라인 + 리스너
└── ocap-windows/                        # owa.ocap_windows.recorder

각각이 vendoring된 이유

서브모듈 핀 이유
open-world-agents-private 브랜치 feat/owa-env-desktop-linux에 핀 — main이 macOS에서도 ctypes.windll을 unconditional import. 브랜치는 Windows-only import를 platform.system() 체크로 가드.
ocap-macos pyproject가 owa-env-desktop==0.6.5에 핀 (위 open-world-agents 브랜치와 매치). 서브모듈 핀이 그 contract 안정 유지.
ocap-windows 같은 모양, Windows 쪽.

Init + update

Cue 클론 후:

git submodule update --init --recursive

main pull 후:

git pull
git submodule update --init --recursive

서브모듈 update 까먹으면 stale 레코더 코드가 남아 다음 uv pip install -e .에서 ModuleNotFoundError: owa.ocap_macos로 surface 하거나 레코더에서 버전 mismatch 크래시로 surface.

크로스 플랫폼 sync 규칙

cue.recorder가 같은 argv 모양으로 호출하기 때문에 ocap-macos와 ocap-windows는 CLI 표면이 sync 유지되어야 함. 새 CLI 플래그 추가하면 양쪽 서브모듈 repo에 추가하고 양쪽 서브모듈 핀을 같은 PR에서 bump. 크로스 플랫폼 규칙 참고.

업데이트 land 방법

서브모듈에 변경 필요한 경우 권장 흐름:

  1. 서브모듈 repo에서 변경 (예: vendor/ocap-macos), feature 브랜치에 commit, push.
  2. Cue repo에서 cd vendor/ocap-macos && git pull (또는 fetch + 새 commit checkout).
  3. Cue repo 루트로 돌아와서 git add vendor/ocap-macos, bumped 서브모듈 SHA를 Cue PR에 commit.

Cue PR이 새 서브모듈 SHA를 다른 컨트리뷰터와 CI에 visible 만듦.

빌드 시 번들링

Frozen 빌드는 OWA 플러그인 시스템의 importlib.metadata.entry_points() discovery를 위해 vendor .dist-info 번들. scripts/build_nuitka.sh (macOS)와 scripts/build_installer.py (Windows)가 처리. 릴리스 빌드 참고.

llama-cpp prebuilt

vendor/llama-bin/은 git 서브모듈이 아님. 빌드 스크립트가 공식 ggml-org/llama.cpp 릴리스 아티팩트에서 on-demand로 다운로드, checksum으로 검증. Gitignore. 릴리스 빌드에서 크로스 플랫폼 sourcing 규칙 참고.

더 보기