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/ 中，使用三因素加权随机算法（余额、空闲时间、成功率）选择账户，并维护一个前 5 名候选列表。
熔断器与冷却	对 429、402、404 等错误使用指数退避处理，软冷却（600 秒 → 最多 2 小时）和硬冷却（余额耗尽账户直到次日 04:00）。
会话粘性	在整个对话生命周期内将 conversation_id 绑定到同一上游账户（默认 TTL 30 分钟），若配置则将绑定同步至 Redis。
成本感知路由	每次成功响应后，网关记录 (account, model) 的 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；未推断任何额外功能。