프로젝트 개요
Jev GUI Delegate는 Codex를 위한 Windows 및 Chrome GUI 위임 프로토타입입니다. 주 모델은 작업 목표와 검수 조건을 제시하고, 로컬 컨트롤러는 인터페이스를 관찰하고, 컨트롤을 매칭하고, 작업을 실행하며, 각 단계에서 실제 결과를 확인합니다. 컨트롤러는 결정론적 규칙으로 처리할 수 없는 의미적 선택이 필요한 경우에만 TypeSafe Jev를 호출합니다.
해결하려는 핵심 문제는 주 모델이 웹 페이지나 데스크톱 애플리케이션을 단계별로 조작할 경우 인터페이스를 반복해서 읽고, 컨트롤을 선택하고, 도구 반환값을 처리해야 하므로 비용이 높은 작업 루프가 형성된다는 점입니다. Jev GUI Delegate는 명확한 검수가 가능한 작업을 로컬 컨트롤러에 맡겨 연속 실행하면서도 상태 확인, 예외 복구 및 사용자 개입 기능을 유지합니다.
이 프로젝트는 개인이 설계하고 AI의 도움으로 구현했으며 지속적으로 검수하는 프로토타입입니다. 작업 계약, 도구 오케스트레이션, 복구 메커니즘, 권한 확인, 테스트 및 피드백 반복은 프로젝트의 기여에 해당합니다. Jev 모델, TypeSafe SDK, Codex 및 브라우저 플러그인은 상위 제품입니다.
작업 흐름
Codex 주 모델이 목표와 검수 조건을 제출합니다.
작업이 확인 가능한 로컬 작업 계약으로 정리됩니다.
컨트롤러가 현재 인터페이스를 관찰하고 결정론적 컨트롤 매칭을 시도합니다.
직접 판단할 수 없을 때 컨트롤러가 Jev를 호출해 의미적 선택을 수행합니다.
Chrome 작업은 호스트가 제공하는 공식 브라우저 세션을 통해 실행하고, Windows 작업은 UI Automation을 통해 실행합니다.
컨트롤러가 실제 결과를 검증하고 진행 상황을 저장한 뒤 계속 진행, 복구, 일시 중지 또는 주 모델에 추가 정보 요청 여부를 결정합니다.
이 흐름은 개인 브라우저 설정을 복제하거나 Cookie를 추출하지 않습니다. Chrome 경로는 Codex 호스트가 제공하는 호환 공식 브라우저 세션 API에 의존하며, 저장소 자체에서는 해당 세션을 생성하거나 대체할 수 없습니다.
주요 기능
두 가지 GUI 실행 경로
Chrome: 호스트가 제공하는 공식 브라우저 세션을 재사용합니다.
Windows: Windows UI Automation을 사용해 접근 가능한 데스크톱 컨트롤을 조작합니다.
명시적 작업 계약
작업 계약에는 목표, 허용된 작업, 작업 범위, 필요한 입력, 실행 단계 및 성공 조건이 명확하게 기술됩니다. 따라서 컨트롤러는 실행 전에 권한과 범위를 확인하고, 실행 후에는 성공 조건에 따라 작업이 실제로 완료되었는지 판단할 수 있습니다.
필요할 때만 Jev 호출
로컬 규칙으로 결정할 수 있는 컨트롤은 코드가 직접 매칭하고, 텍스트의 의미나 후보 항목의 의미를 이해해야 할 때만 Jev를 호출합니다. 프로젝트는 실제 상황에 따라 모델 호출 0회를 기록하며, 이를 잘못해서 성공적인 Jev 추론 1회로 계산하지 않습니다.
연속 실행 및 복구
컨트롤러는 실행 진행 상황을 저장하고 입력 누락, 부분적인 선택 오류, 일시 중지, 취소 및 사용자 개입 등의 상황을 처리할 수 있습니다. 제출 작업의 성공 여부를 확인할 수 없는 경우에는 중복 제출 위험을 줄이기 위해 제출을 자동으로 재실행하지 않습니다.
결과 및 보안 확인
시스템은 작업 전에 신원, 권한 및 범위를 확인하고, 작업 후에는 실제 값이나 페이지 상태를 점검합니다. 모델 사용량과 실패 원인은 별도로 기록하여 비용 문제와 실행 문제를 구분할 수 있도록 합니다.
실행 환경 및 사전 조건
프로젝트는 다음 환경을 대상으로 합니다.
Windows x64
Python 3.12
Node.js
네이티브 GUI 작업을 위한 대화형 데스크톱
Chrome 경로를 사용하려면 Codex 호스트가 제공하는 호환 공식 브라우저 세션 API도 필요합니다.
프로젝트를 C:\jev\jev-bridge에 설치하는 것이 좋습니다. 일부 기존 명령과 Codex skill 예시는 이 위치를 기본으로 사용합니다. 다른 디렉터리를 선택하는 경우 관련 예시와 설정도 함께 수정해야 합니다.
프로젝트 설치
1단계: 저장소 복제 및 가상 환경 생성
git clone https://github.com/YUTA-fywoo/jev-gui-delegate.git C:\jev\jev-bridge
cd C:\jev\jev-bridge
py -3.12 -m venv .venv2단계: 고정된 의존성 설치
.\.venv\Scripts\python.exe -m pip install --require-hashes -r requirements.lock--require-hashes는 잠금 파일의 해시에 따라 의존성을 설치하여 설치 내용이 프로젝트 기록과 일치하도록 돕습니다. 서드파티 의존성 디렉터리는 저장소에 공개되지 않으므로 원래 배포 경로에서 설치해야 합니다.
3단계: 런타임 준비
.\.venv\Scripts\python.exe scripts/setup-runtime.py4단계: 오프라인 테스트 실행
.\.venv\Scripts\python.exe -m unittest discover -s gui_delegate/tests -p "test_*.py"이 테스트는 컨트롤러, 복구 흐름 및 경계 조건을 다룹니다. 오프라인 회귀 테스트는 합성 데이터와 통제된 대체 객체를 사용하며, 실제 GUI 조작과 같지 않고 실시간 Jev 요청을 가장하지도 않습니다. 더 자세한 결과는 저장소의 릴리스 검증 문서를 참고해야 합니다.
Jev 키 설정
키는 로컬 환경 변수 TYPESAFE_API_KEY 또는 Windows 자격 증명 관리자에서 제공할 수 있습니다. 프로젝트에서는 set-key.cmd가 여는 로컬 입력 창을 사용해 설정하는 방식을 권장합니다.
set-key.cmd키를 Git 저장소, 작업 계약 또는 채팅 내용에 기록하지 마세요. 설치자가 로컬에서 생성하는 chrome-runtime.json은 무시되도록 설정되어 있으며, 저장소에는 원작자 컴퓨터의 환경 경로가 포함되지 않습니다.
Codex에 등록
프로젝트를 Codex에 연결하려면 프로젝트 디렉터리에서 다음 설치 스크립트를 실행합니다.
install.cmd
gui-install.cmd설치 프로그램은 사용자 수준의 MCP, skill 및 라우팅 설정을 수정하고, 동시에 백업을 보존하며 충돌을 확인합니다. 컴퓨터에 같은 이름의 디렉터리가 이미 있으면 먼저 용도를 확인해야 합니다. 설치 프로그램은 컴퓨터에서 현재 사용 중인 프로젝트를 직접 덮어쓰지 않습니다.
설치할 수 있는 개인 Codex skill은 gui_delegate/skill/SKILL.md에 있습니다. 프로젝트를 기본 디렉터리에 설치하지 않았다면 해당 파일에 포함된 경로 관련 예시도 확인해야 합니다.
기본 사용 및 검증
로컬 준비 상태 확인
설치 후 다음을 실행할 수 있습니다.
health.cmdhealth.cmd는 구성 요소가 준비되었는지만 확인하며, 실시간 Jev 검증이 실행되었다는 의미가 아니고 현재 컴퓨터가 실제 GUI 시나리오 검수를 통과했다는 의미도 아닙니다.
실시간 검증 실행
프로젝트에서 제공하는 verify.cmd 등의 실시간 검증 흐름은 Jev 서비스를 호출합니다.
verify.cmd실행 전에 키가 올바르게 설정되었는지 확인하고, 오프라인 회귀 결과와 실시간 서비스 결과를 구분해야 합니다. README는 과거 개발 환경에서의 “로컬 검증 완료”를 모든 설치자가 그대로 물려받을 수 있는 결론으로 간주하지 않습니다.
위임에 적합한 작업 설계
이 프로토타입은 범위가 명확하고, 단계를 제한할 수 있으며, 결과를 확인할 수 있는 GUI 작업에 적합합니다. 컨트롤러에 작업을 전달할 때는 최소한 다음 내용을 명확히 해야 합니다.
목표: 최종적으로 어떤 상태에 도달해야 하는가.
범위: 어떤 페이지, 창 또는 객체 안에서 작업할 수 있는가.
허용된 작업: 컨트롤러가 어떤 유형의 상호작용을 수행할 수 있는가.
입력: 작업 실행에 필요하고 사용이 허용된 데이터.
단계: 연속해서 실행할 수 있는 작업 단계.
성공 조건: 완료 후 관찰되어야 하는 실제 값 또는 페이지 상태.
예를 들어 특정 페이지 범위에서 대상 컨트롤을 찾고, 권한이 부여된 입력을 작성한 뒤, 페이지 상태를 통해 결과를 확인하도록 컨트롤러에 요구할 수 있습니다. 구체적인 계약 필드와 결과 모델은 gui_delegate/schema.py의 구현을 기준으로 해야 하며, README에 정의되지 않은 형식을 임의로 가정해서는 안 됩니다.
소스 코드 읽기 순서
실행 메커니즘을 이해하거나 2차 개발을 진행하려면 다음 순서로 읽을 수 있습니다.
gui_delegate/schema.py: 작업 계약, 상태 및 결과 모델을 이해합니다.gui_delegate/controller.py: 컨트롤러가 실행 루프를 구성하는 방식을 확인합니다.gui_delegate/drivers.py: 드라이버 및 구조화된 인터페이스 관찰 방식을 이해합니다.gui_delegate/security.py: 범위, 권한 및 입력 확인을 확인합니다.gui_delegate/chrome_gateway.mjs: 공식 브라우저 세션 진입점을 이해합니다.jev_client.py: Jev SDK 래퍼, 버전 확인 및 사용량 기록을 확인합니다.gui_delegate/tests: 테스트를 통해 복구 로직과 경계 동작을 이해합니다.
고급 사용 권장 사항
결정론적 매칭 우선 사용
컨트롤을 안정적인 속성이나 구조화된 정보로 식별할 수 있다면 로컬 코드가 우선 매칭하도록 해야 합니다. 의미적 판단이 필요한 경우에만 Jev를 호출해야 프로젝트 설계에 부합하고 모델 사용량도 정확하게 기록할 수 있습니다.
각 단계에 관찰 가능한 결과 설정
“버튼 클릭”과 같은 작업만 정의하지 말고, 클릭 후 예상되는 값, 컨트롤 상태 또는 페이지 변화도 정의해야 합니다. 프로젝트는 도구 호출 성공을 곧바로 작업 성공으로 간주하지 않고 실제 결과를 확인하는 것을 중시합니다.
제출 작업을 신중하게 처리
제출 후 결과가 명확하지 않다면 실패로 가정하고 작업을 자동으로 반복하지 마세요. 이 프로젝트는 결과가 불명확할 때 제출을 자동으로 재실행하지 않습니다. 이러한 상태에서는 일시 중지하고 진행 상황을 저장한 뒤 사용자 또는 주 모델의 확인을 받는 것이 적절합니다.
입력 누락과 선택 오류를 구분해 처리
필수 입력이 누락된 경우 입력을 보충한 뒤 계속 진행해야 하며, 부분적인 의미 선택 오류가 있을 때만 해당 선택을 수정해야 합니다. 이렇게 하면 작업을 처음부터 다시 실행하는 일을 피하면서 이미 검증된 진행 상황을 유지할 수 있습니다.
Jev 버전 업그레이드 후 재검증
현재 settings.json에는 과거 테스트에 사용된 jev-1.13.0이 고정되어 있습니다. 서버 버전이 변경되면 다시 확인하고 설정을 갱신해야 하며, 이전 버전의 테스트 결과를 새 버전의 품질 보증으로 간주해서는 안 됩니다. 예시 전략 역시 현재 컴퓨터의 보정이 완료되었다는 의미가 아닙니다.
벤치마크 테스트의 올바른 이해
README에는 2026년 9월 23일의 두 차례 합성 작업 테스트가 기록되어 있습니다. 각 회차에는 동일한 4개 작업과 24개 작업이 포함되었으며, 두 작업 그룹 모두 4/4를 완료했습니다.
1회차에서는 Astra token이 2,266,693에서 236,295로 감소하여 89.6% 줄었고, 엔드투엔드 작업 속도는 기준선의 3.05배였습니다.
2회차에서는 Astra token이 2,256,091에서 192,752로 감소하여 91.5% 줄었고, 엔드투엔드 작업 속도는 기준선의 3.53배였습니다.
여기서 Astra token에는 캐시된 입력이 포함되며 Jev의 추가 사용량은 별도로 집계됩니다. 두 회차에서 동일한 네 가지 작업을 반복했으므로 독립적인 시나리오가 8가지였다는 의미는 아닙니다. 이 수치는 청구 비용 절감 비율도 아니며 모든 애플리케이션, 임의의 작업 또는 배포 환경에서 동일한 결과를 얻는다는 것을 증명하지도 않습니다. 초기 3개 작업 버전의 비캐시 token 결과는 개선되지 않았으며, 자세한 범위는 테스트 설명을 확인해야 합니다.
알려진 제한 사항
프로토타입은 읽을 수 있는 DOM 또는 접근성 정보에 의존합니다.
Canvas, 이미지 이해, 보안 데스크톱 및 일부 크로스 프레임워크 컨트롤은 직접 처리하지 못할 수 있습니다.
호스트에서 제공하지 않는 기능은 주 모델의 추가 처리가 필요할 수 있습니다.
Chrome 경로는 호환되는 호스트의 공식 세션 없이 독립적으로 실행할 수 없습니다.
과거 컴퓨터의 검증 기록은 새 설치 환경이 검수를 통과했다는 의미가 아닙니다.
실행 로그, 브라우저 설정, 키, 개인 작업 자료, 컴퓨터 설치 상태 및 롤백 패키지는 공개되지 않습니다.
요약
Jev GUI Delegate는 검수 가능한 GUI 작업을 주 모델의 단계별 루프에서 분리하고, 로컬 컨트롤러가 결정론적 매칭, 필요할 때의 의미적 선택, 상태 검증 및 장애 복구를 수행하도록 합니다. 설치할 때는 먼저 고정된 의존성, 런타임 설정 및 오프라인 테스트를 완료한 다음 키를 구성하고 Codex에 연결해야 합니다. 실제 사용에서는 명확한 작업 범위, 관찰 가능한 성공 조건, 신중한 제출 복구 전략 및 버전 변경 후 재검증이 신뢰할 수 있는 결과를 얻는 핵심입니다.
상위 구성 요소에 대해 자세히 알아보려면 TypeSafe 문서, MCP Python SDK 및 pywinauto를 참조하세요.