Sliverkiss/workbuddy2api

WorkBuddy2API – 腾讯CodeBuddy用のOpenAI互換ゲートウェイ

何であるか

• 1つ以上の腾讯CodeBuddy (copilot.tencent.com) アカウントを、OpenAI互換の /v1/chat/completions API に変換するセルフホスト型リバースプロキシ。
• 全てのOAuthデバイスフロー、トークンのリフレッシュ、アカウントプールスケジューリング、レートリミット／クールダウンロジック、セッションスタビリティを処理し、OpenAI SDKやツールがコード変更なしで呼び出せる単一エンドポイントを公開する。

なぜ存在するのか

• CodeBuddyは公開されたOpenAIスタイルのAPIを提供していない。WorkBuddy2APIを使えば、個人のCodeBuddyクレジットをOpenAIサービスのように再利用でき、OpenAIスキーマを期待する個人プロジェクト、スクリプト、ローカルツールに有用である。
• 複数アカウント を想定して設計：複数のCodeBuddyアカウントを追加でき、ゲートウェイが自動的にアカウントをローテーションし、枯渇またはレート制限されたアカウントを回避し、コストを低く抑える。

主な機能

機能	機能内容
OAuthワンクリックログイン	login.sh がデバイス認証フローを実行し、accessToken/refreshToken を保存してコンテナを再起動する。
アカウントプール	auths/ に資格情報を保存し、クレジット、アイドル時間、成功確率の3要因に基づく重み付きランダムアルゴリズムでアカウントを選択し、トップ5候補リストを維持する。
回路ブレーカー＆クールダウン	429、402、404などのエラーに対し指数バックオフ、ソフトクールダウン（600秒 → 最大2時間）、ハードクールダウン（残高枯渇アカウントは翌日04:00まで）を処理する。
セッションスタビリティ	会話のライフタイム中（デフォルトTTL 30分）に conversation_id を同じアップストリームアカウントに紐づけ、設定済みの場合はRedisにも同期する。
コスト意識ルーティング	各成功レスポンス後に (account, model) ごとの usage.credit を記録し、以降の呼び出しで無料または安価なアカウントを優先する。
スケジュールタスク	自動的な毎日ログイン、活動報告、ゲーム化された「猫の旅」タスク、および設定可能なローカル時間でのトークン維持。
ストリーミング＆非ストリーミング	アップストリームで stream:true を強制し、SSEフレームをOpenAI形式に再書き換え；非ストリーミングリクエストはローカルで集約する。
プロンプト・システム処理	クライアント提供の system メッセージを組み込みプロンプト（またはそのまま通過）で置き換え、ブラックリストされたフィンガープリントフィールドを削除可能。
観測性	1行のテーブルログでリクエストごとに（モデル、トークン数、レイテンシ、UIDプレフィックスなど）を出力し、/healthz エンドポイントでプールの健全性を報告する。
永続化	プール状態（state.json）はディスクに原子的に書き込まれ、Upstash 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. 任意のOpenAIエンドポイントのように使用する。例：

   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 – リクエストボディのサイズ制限（デフォルト8MiB、超過時は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 設定時）	OpenAI互換チャットエンドポイント。ストリーミング（stream:true）と非ストリーミングモードをサポート。
GET /v1/models	ベアラー（api_key 設定時）	CodeBuddyから取得したモデルリストを返す（キャッシュ1時間）。
GET /status	ベアラー（api_key 設定時）	プール全体の概要と各アカウントの詳細（クレジット、クールダウン、無効化理由など）を返す。
GET /healthz	無し	軽量な健全性チェック – 1つ以上のアカウントが健全なら200、それ以外は503を返す。LB識別用に service フィールドを含む。

安全とコンプライアンスに関する注意事項（READMEより）

• このゲートウェイは非公式である。OAuthで承認された所有アカウントへのトラフィックを単に転送するのみ。
• トークンは auths/ 下の平文JSONファイルに保存される。ディレクトリの権限を制限する（chmod 600）こと。
• TLSは組み込まれていない。サービスを公開する場合はリバースプロキシの背後に置くか、api_key を設定する必要がある。
• 個人用・プライベートテストに限定。上流のCodeBuddyアカウントの再配布または商業利用は、Tencentの利用規約に違反する可能性がある。

一般的な利用例

• OpenAI APIのみを理解するローカルLLMツール（例：IDEアシスタント、CLIチャットボット）を、CodeBuddyのクレジットを活用して実行する。
• 複数アカウントのコスト最適化を実験する：ゲートウェイは各モデルごとに無料または安価なアカウントを自動的に優先する。
• 手動ブラウザ操作なしでCodeBuddyの「成長」タスク（毎日ログイン、活動報告、ゲーム化された「猫の旅」機能）を自動化する。

---

上記のすべての情報はリポジトリのREADMEから直接引用；追加機能は推測していない。