Sliverkiss/workbuddy2api

WorkBuddy2API – 텐센트 코드버디용 오픈AI 호환 게이트웨이

무엇인가요

• 하나 이상의 텐센트 코드버디 (copilot.tencent.com) 계정을 오픈AI 호환 /v1/chat/completions API로 전환하는 자체 호스팅 리버스 프록시입니다.
• 전체 OAuth 디바이스 흐름, 토큰 갱신, 계정 풀 스케줄링, 레이트리밋/쿨다운 로직, 세션 스티키를 처리하며, 오픈AI SDK나 도구가 코드 변경 없이 호출할 수 있는 단일 엔드포인트를 노출합니다.

왜 존재하는가

• 코드버디는 공개적인 오픈AI 스타일 API를 제공하지 않습니다. WorkBuddy2API를 통해 개인의 코드버디 크레딧을 마치 오픈AI 서비스처럼 재사용할 수 있으며, 오픈AI 스키마를 기대하는 개인 프로젝트, 스크립트 또는 로컬 도구에 유용합니다.
• 다중 계정 사용을 위한 설계: 여러 코드버디 계정을 추가할 수 있으며, 게이트웨이는 자동으로 계정을 전환하고 고갈되거나 레이트리밋된 계정을 피하며 비용을 낮게 유지합니다.

주요 기능

기능	설명
OAuth 일클릭 로그인	login.sh가 디바이스 인증 흐름을 실행하고 accessToken/refreshToken을 저장한 후 컨테이너를 재시작합니다.
계정 풀	auths/에 자격 증명을 저장하고, 크레딧, 비활성 시간, 성공률을 기반으로 한 3요소 가중 무작위 알고리즘으로 계정을 선택하며, 상위 5개 후보 목록을 유지합니다.
회로 차단기 및 쿨다운	429, 402, 404 등 오류에 대해 지수 백오프를 처리하고, 소프트 쿨다운(600초 → 최대 2시간)과 하드 쿨다운(잔액 고갈 계정의 경우 다음 날 04:00까지)을 지원합니다.
세션 스티키	대화의 수명 동안 conversation_id를 동일한 업스트림 계정에 바인딩하며(기본 TTL 30분), 구성 시 Redis에 바인딩을 반영합니다.
비용 인식 라우팅	각 성공적인 응답 후 (계정, 모델)별 usage.credit을 기록하고, 다음 호출에 무료 또는 저렴한 계정을 우선적으로 선택합니다.
스케줄된 작업	구성 가능한 로컬 시간에 자동 일일 로그인, 활동 보고서, '고양이 여행' 게임화 작업, 토큰 유지 활성화를 수행합니다.
스트리밍 및 비스트리밍	업스트림에서 stream:true를 강제하고, SSE 프레임을 오픈AI 형식으로 재작성합니다. 비스트리밍 요청은 로컬에서 집계됩니다.
프롬프트-시스템 처리	클라이언트가 제공한 system 메시지를 내장 프롬프트로 대체하거나(또는 통과)하고, 블랙리스트된 지문 필드를 제거할 수 있습니다.
관측성	요청당 1줄의 테이블 로그(모델, 토큰, 지연 시간, UID 접두사 등)와 풀 상태를 보고하는 /healthz 엔드포인트를 제공합니다.
지속성	풀 상태(state.json)는 원자적으로 디스크에 기록되며, 선택적으로 업스태시 Redis에 미러링됩니다.

실행 방법

1. 사전 요구 사항 – Docker + Docker-Compose(권장) 또는 소스에서 빌드를 위한 Go 1.22+ 도구 체인.
2. 복제 및 구성 준비:

   git clone https://github.com/Sliverkiss/workbuddy2api.git
   cd workbuddy2api
   cp config.example.json config.json   # 서비스를 공개적으로 노출할 경우 적어도 "api_key"를 편집하세요
   

3. 계정 추가 (풀에 포함할 계정 수만큼 반복):

   ./login.sh   # 브라우저를 열고 로그인한 후, 토큰이 auths/ 아래에 저장됩니다
   

4. 서비스 시작:

   docker compose up -d --build
   

5. 검증:

   curl -s http://localhost:7863/healthz
   # → {"healthy":2,"total":3,"service":"workbuddy2api"}
   

6. 오픈AI 엔드포인트처럼 사용하기, 예를 들어:

   curl -sN http://localhost:7863/v1/chat/completions \
        -H "Authorization: Bearer <your-api-key>" \
        -H "Content-Type: application/json" \
        -d '{"model":"deepseek-v4-flash","messages":[{"role":"user","content":"hi"}],"stream":true}'
   

구성 요약 (모든 옵션은 config.example.json에 있음)

• listen – 게이트웨이가 바인딩하는 주소(기본값 :7863).
• api_key – 클라이언트가 필요로 하는 선택적 베어러 토큰; 공개 서비스일 경우 빈 값으로 두세요(공개 인터넷에서는 권장하지 않음).
• auth_dir – workbuddy-<uid>.json 자격 증명 파일이 위치하는 디렉터리.
• state_file – 풀 메트릭, 쿨다운 타이머 등을 지속하는 JSON 파일.
• server.max_body_mb – 요청 본문 크기 제한(기본값 8 MiB, 초과 시 413 반환).
• 쿨다운 파라미터: cooldown.soft_rate, cooldown.soft_rate_max, pool.breaker_threshold, pool.breaker_cooldown 등.
• 세션 스티키: session_sticky.enabled, session_sticky.ttl.
• 프롬프트 처리: prompt.mode (custom 또는 passthrough) 및 선택적 prompt.file로 사용자 정의 시스템 프롬프트 제공.
• 선택적 Redis 미러링: upstash.url / upstash.token.

API 표면

메서드 및 경로	인증	설명
POST /v1/chat/completions	베어러 (api_key 설정 시)	오픈AI 호환 채팅 엔드포인트로, 스트리밍(stream:true) 및 비스트리밍 모드를 지원합니다.
GET /v1/models	베어러 (api_key 설정 시)	코드버디에서 가져온 모델 목록을 반환합니다(캐시 1시간).
GET /status	베어러 (api_key 설정 시)	전체 풀 요약 및 계정별 세부 정보(크레딧, 쿨다운, 비활성화 사유 등)를 제공합니다.
GET /healthz	없음	가벼운 상태 확인 – 최소 하나의 계정이 건강할 경우 200을 반환하며, 그렇지 않으면 503을 반환합니다. 로드 밸런서 식별을 위해 service 필드 포함.

안전성 및 준수 주의사항 (README에서)

• 이 게이트웨이는 공식이 아닙니다; 오직 사용자가 소유하고 OAuth를 통해 승인한 계정으로 트래픽을 전달합니다.
• 토큰은 auths/ 아래의 평문 JSON 파일에 저장됩니다. 디렉터리 권한을 제한하십시오(chmod 600).
• TLS는 내장되어 있지 않습니다. 서비스를 공개적으로 노출할 경우 리버스 프록시 뒤에 두거나 api_key를 설정해야 합니다.
• 개인적, 비공개 테스트에 한해 사용 가능합니다. 상류 코드버디 계정의 재배포 또는 상업적 사용은 텐센트의 이용 약관을 위반할 수 있습니다.

일반적인 사용 사례

• 오픈AI API만 이해하는 로컬 LLM 기반 도구(예: IDE 어시스턴트, CLI 채팅 봇)를 실행하면서 코드버디 크레딧을 활용합니다.
• 다중 계정 비용 최적화 실험: 게이트웨이는 각 모델에 대해 무료 또는 저렴한 계정을 자동으로 우선 선택합니다.
• 수동 브라우저 상호작용 없이 코드버디 '성장' 작업(일일 로그인, 활동 보고서, 게임화된 '고양이 여행' 기능)을 자동화합니다.

---

위 모든 정보는 저장소의 README에서 직접 인용되었으며, 추가 기능은 추론되지 않았습니다.