HRuiCcc/RuiC-oc-ferry

OC Ferry – OpenCode 무료 모델을 WorkBuddy에 브리지

개요

• Electron으로 구축된 크로스 플랫폼(macOS / Windows) 트레이 앱으로, OpenCode 모델 풀에서 무료 모델을 자동으로 발견하고 WorkBuddy 도구 호출 프로토콜을 말할 수 있는지 테스트하며 사용 가능한 모델을 WorkBuddy의 models.json에 작성합니다. 또한 로컬 OpenAI 호환 HTTP 엔드포인트(127.0.0.1:41980)를 실행하여 WorkBuddy 요청을 선택한 모델로 전달합니다.

중요성

• WorkBuddy는 특정 JSON 봉투 도구 호출 스키마를 따르는 모델만 사용할 수 있습니다. OpenCode의 무료 모델은 직접 호환되지 않으며 가용성이 자주 변경됩니다. OC Ferry는 발견, 검증, 캐싱, 가져오기 단계를 자동화하여 사용자가 수동으로 API 키를 처리하지 않고도 무료 모델 액세스를 얻을 수 있게 합니다.

주요 기능

• 로그인 없음, API 키 없음 – 앱은 자체 격리된 OpenCode 런타임을 번들합니다.
• 무료 모델 필터 – 가격 필드가 모두 0이고 더 이상 사용되지 않는 모델만 고려됩니다.
• 동시 프로빙 – 최대 3개의 모델이 병렬로 테스트됩니다(약 60초/라운드).
• 결과 캐싱 – 성공한 프로브는 6시간 동안 캐시되므로 재시작이 거의 즉시 이루어집니다.
• 선택적 가져오기 – OC Ferry가 추가한 항목만 WorkBuddy의 models.json에 작성됩니다. 사용자 추가 항목은 변경되지 않습니다.
• 로컬 전달 포트 – 로컬 머신에서만 요청을 수락하는 OpenAI 호환 엔드포인트(브라우저 액세스 불가).
• 트레이 UI – 라이트/다크 테마, 실시간 상태, 모델별 세부 보기, "모두 감지 / 단일 재프로브" 버튼.
• 휴대용 빌드 – macOS DMG, Windows 설치 프로그램, 휴대용 Windows zip.

작동 방식(고수준 흐름)

1. 발견 – OpenCode 모델 디렉토리를 읽고 가격 = 0이고 더 이상 사용되지 않는 항목을 선택합니다.
2. 프로브 – 무작위 토큰 파일을 포함한 작은 채팅 요청을 보내고 모델이 JSON 봉투 작업을 생성하도록 요청합니다. 모델이 일반 텍스트만 반환하면 대화 전용으로 표시되고, 올바른 봉투를 반환하면 도구 활성화로 표시됩니다.
3. 캐시 – 프로브 결과는 probe-cache.json에 저장됩니다(TTL = 6시간). 후속 시작은 만료되지 않는 한 캐시를 재사용합니다.
4. 가져오기 – 발견된 항목을 WorkBuddy의 models.json에 병합하고 원자적 쓰기, 백업, 파일 잠금 처리를 수행합니다.
5. 전달 – WorkBuddy는 OpenAI 스타일 요청을 127.0.0.1:41980로 보냅니다. OC Ferry는 요청을 검증하고 선택한 OpenCode 모델로 전달하며 JSON 봉투 작업을 WorkBuddy로 변환합니다.

설치 및 빠른 시작

• macOS(Apple 실리콘) – .dmg를 다운로드하고 "OC Ferry"를 응용 프로그램으로 드래그한 다음, 필요한 경우 격리 제거(xattr -dr com.apple.quarantine …)를 수행합니다.
• Windows – .exe 설치 프로그램을 실행합니다. 트레이에서 숨겨진 앱을 실행하는 시작 항목이 추가됩니다. 휴대용 zip도 제공됩니다.
• 첫 실행 시 격리된 OpenCode 런타임이 자동으로 준비되고, 무료 모델을 스캔하고 프로브하며 성공한 모델을 WorkBuddy로 가져옵니다.
• 앱을 계속 실행합니다(트레이 아이콘) – 창을 닫으면 숨겨지고, 트레이에서 종료하면 추가된 항목이 정리됩니다.

개발자 노트

• Node ≥ 22, UI용 Electron, 순수 JavaScript/TypeScript 코드베이스.
• 주요 모듈: main.js(상태 머신), backend.js(OpenCode 세션 및 작업 변환), probe.js(모델 테스트), server.js(로컬 HTTP API), desktop/의 UI 코드.
• 테스트: 오프라인으로 실행되는 85개의 자동화된 단위 테스트(npm test).
• 빌드 명령: npm run build:mac, npm run build:win, npm run build:win:portable.
• 디버깅용 환경 변수(데이터 디렉토리, 포트, 동시성 등).

제한 사항 및 주의 사항

• 프로빙은 소량의 무료 OpenCode 할당량을 소비합니다. 결과는 이 요청이 성공했음을 보장할 뿐입니다.
• 무료 모델 가용성은 OpenCode에 의해 제어되며 사전 통지 없이 변경될 수 있습니다.
• 로컬 전달 포트는 Origin 헤더가 있는 요청을 거부합니다(브라우저 사용 불가).
• 시스템 프록시 지원은 수동 HTTP/HTTPS 항목으로 제한됩니다. PAC 또는 SOCKS는 지원되지 않습니다.
• Linux 지원은 실험적입니다.

라이선스

• MIT 라이선스(LICENSE 참조).

---

OC Ferry가 도움이 된다면 저자는 WeChat을 통한 커피 기부를 환영합니다.