Sliverkiss/workbuddy2api

WorkBuddy2API – 適用於騰訊 CodeBuddy 的 OpenAI 兼容閘道

這是什麼

• 一個自托管的反向代理，可將一個或多個騰訊 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/ 中，使用三因子加權隨機演算法（信用額度、閒置時間、成功率）選擇帳戶，並維護前五名候選名單。
電路斷路器與冷卻	對 429、402、404 等錯誤使用指數退避，提供軟冷卻（600 秒 → 最多 2 小時）與硬冷卻（直到隔日 04:00，適用於信用額度耗盡的帳戶）。
會話黏性	將 conversation_id 綁定至同一上游帳戶，整個對話期間保持一致（預設 TTL 30 分鐘），若已設定則同步至 Redis。
成本感知路由	每次成功回應後，記錄 (帳戶, 模型) 的 usage.credit，並在後續呼叫中優先選擇免費或較便宜的帳戶。
排程任務	自動每日登入、活動報告、「貓咪旅行」遊戲化任務，以及在可設定的當地時間執行令牌保活。
串流與非串流	強制上游 stream:true，將 SSE 幀重新格式化為 OpenAI 格式；非串流請求會在本地聚合。
提示系統處理	將客戶端提供的 system 訊息替換為內建提示（或直接傳遞），並可移除黑名單中的指紋欄位。
可觀測性	每筆請求一列表格日誌（模型、token 數量、延遲、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 – 客戶端所需的可選 Bearer 權杖；留空則為公開服務（不建議在公開網際網路使用）。
• 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	Bearer（若設定 api_key）	OpenAI 兼容的聊天端點，支援串流（stream:true）與非串流模式。
GET /v1/models	Bearer（若設定 api_key）	回傳從 CodeBuddy 取得的模型清單（快取 1 小時）。
GET /status	Bearer（若設定 api_key）	整個帳戶池的摘要，以及各帳戶的詳細資訊（信用額度、冷卻狀態、停用原因等）。
GET /healthz	無	輕量健康檢查 – 至少有一個帳戶健康時回傳 200，否則回傳 503。包含 service 欄位，可用於負載平衡器區分。

安全與合規注意事項（來自 README）

• 此閘道為 非官方；僅將流量轉發至你擁有並透過 OAuth 授權的帳戶。
• 權杖以純文字 JSON 檔案儲存在 auths/ 目錄下；請限制目錄權限（chmod 600）。
• 內建無 TLS – 若公開服務，必須置於反向代理後方或設定 api_key。
• 使用僅限於個人、私人測試。重新分發或商業用途上游 CodeBuddy 帳戶可能違反騰訊條款。

典型使用情境

• 執行本地 LLM 驅動的工具（例如 IDE 助手、CLI 聊天機器人），僅理解 OpenAI API，同時利用你的 CodeBuddy 信用額度。
• 探索多帳戶成本最佳化：閘道會自動為每個模型優先選擇免費或較便宜的帳戶。
• 自動化 CodeBuddy「成長」任務（每日登入、活動報告、遊戲化「貓咪旅行」功能），無需手動瀏覽器操作。

---

以上所有資訊均直接取自程式庫的 README；未推斷任何額外功能。