Skip to content
BranchesTags

Repository files navigation

WorkBuddy2API

WorkBuddy2API

把 CodeBuddy 账号变成 OpenAI 兼容 API 的多账号网关
OAuth 登录 · 账号池轮转 · 熔断与冷却 · 会话粘性 · 积分补充

Go API Deploy Transport Telegram

项目简介

WorkBuddy2API 是一个自托管的 OpenAI 兼容上游网关，将 CodeBuddy 账号包装为统一的 /v1/chat/completions 服务。

本项目做什么

  • 通过 OAuth 设备授权（login.sh）获取账号凭证，在网关侧做 token 自动刷新、账号池调度与流量治理；
  • 面向 个人多账号 场景：多账号共享、单号故障自动换号、冷却 / 熔断防止雪崩、会话粘性保证多轮上下文不跳号；
  • 对客户端只暴露 OpenAI 兼容接口，现有 SDK / 前端 / 工具 零改造接入。

本项目不做什么

  • 只做上游网关，不做下游协议转换 — 本项目仅负责对接上游 CodeBuddy 并暴露 OpenAI Chat 协议；Anthropic Messages、Gemini 等其他协议的适配应由下游网关负责；
  • 不内嵌 Web 管理面板 — 网关核心保持精简，可视化面板作为独立项目维护，数据直取上游接口，不增加网关适配负担。

社区前端面板

需要 Web 管理面板的用户，可部署以下符合本理念的社区项目（独立维护，与网关解耦）：

⚠️ 合规须知：本项目是非官方网关，使用 CodeBuddy 账号作为上游，仅限本人授权账号、本机 / 私有环境测试。详细边界见安全与合规。

📖 完整文档见 GitHub Wiki。

核心能力

账号池治理

  • OAuth 设备授权登录 — login.sh 一条命令完成：取授权 URL → 浏览器登录 → token 轮询 → 凭证落盘 → 重启加载，全程无 PKCE（state 由服务端签发），重复执行即可连续添加多账号
  • 三因子加权随机选号 — credits 比例 ×10 + 快过期积分占比 ×8 + 闲置补偿 三项加权（pool.expiring_soon 窗口内的积分优先消耗，默认 7 天），按权重降序取 Top-5 候选短名单，再在短名单内加权抽签（等权重候选先随机打乱防惊群、LRU 兜底覆盖全部候选），兼顾积分多、快过期积分先用掉、闲置久的账号；失败账号由熔断 / 冷却 / 连败降权状态机处置（不进权重公式）
  • 防惊群 — 跳过 100ms 内刚被选中的账号，多账号同时待命时不打爆同一台
  • 在途租约 — 单账号最大在途请求数（pool.max_in_flight）限制并发占用，占满的号不参与选号，避免单号过载
  • 账本择优 — 每次成功请求按 usage.credit 折算每千 token 单价记入 (账号, 模型) 账本，免费 / 便宜的账号优先；观测按 EMA 平滑、6 小时未更新即失效（陈旧价格不复活），成本随上游活动实时变化；账本随池状态落盘 state.json，重启不丢学费；/status 透出 model_costs 台账（模型 / 单价 / 末次观测 / 样本数）
  • 成本分层条件探索 — costTier 硬过滤（免费 > 未知 > 收费）会把全池锁死在唯一的实测免费号上：其余账号永远轮不到、也就永远学不到「它其实也免费」（垄断 + 学习冻结，issue #136）。破解方式是搭车改道：tier 0 垄断层存在且 tier 1 有成员时，距上次探索 ≥ pool.cost_explore_interval（默认 30m，"0" 关停）就把本次选号改道给一个未知号——承接的是完整真实用户请求，零新增上游请求（IP 维度零增量，WAF 友好）。成功即毕业（首观测入账，免费回 tier 0 / 收费出局 tier 2，学费只付一次）；失败走既有冷却 / 熔断策略，无探测风暴。探索频率硬性限幅 ≤ 48 次 / 天 / 模型（24h ÷ 30m），与池规模和 QPS 无关；tier 1 枯竭后自动停探。探索节奏按 (域, 模型) 独立；/status 透出 cost_explore 台账（累计事件数 + 各 (域, 模型) 最近探索时刻），与 model_costs 行对照即可读出「探索 → 毕业」全链路

流量治理

  • 分级熔断与冷却 — 429 软冷却（600s 起指数退避、封顶 soft_rate_max）、404 固定浅冷却、402 / 余额耗尽硬冷却至次日 04:00、连续失败熔断（breaker_threshold 触发后指数退避封顶 6h）
  • 模型级限流独立冷却 — 6004（该模型使用量超限）只冷却触发调用的模型，切其他模型立即可用；/status 透出 rate_limited_models 台账
  • 状态持久化 — 池状态（积分 / 冷却 / 熔断 / 计数）本地原子落盘 state.json，可选镜像至 Upstash Redis，重启后择优恢复

请求链路

  • 流式 + 非流式 — 出站强制 stream:true；SSE 帧按 OpenAI 规范白名单重建；非流式由本地聚合为单响应
  • DeepSeek 思维链注入 — 出站请求体注入 thinking.type=enabled + 默认档位，reasoning_content 多轮回填，reasoning_effort 按模型档位自动降级
  • 系统提示词三模式（prompt.mode，缺省 passthrough） —
    • passthrough（缺省）：透传客户端原始 system，遇内容拦截自动降级中性提示词重试
    • custom：网关用自有提示词替换客户端 system/developer（从源头消除模板句误报；不参与降级）
    • append：两者并用——开头连续 system/developer 块之后插入网关自有提示词，客户端项目规范/工具约定与网关人格共存（issue #129）；降级期与拦截首遇重试时退化为 custom 语义（换中性提示词，原文 system 移除）
    • prompt.file（custom/append 生效）指向自定义提示词文件，空 = 内置默认
  • 会话头族注入 — 出站携带官方客户端会话头族（X-Conversation-Request-ID 聚合主键 · X-Conversation-ID 透传 · B3 链路），轮转 / 重试 / 路径回退复用同键，后台按对话轮聚合不再碎片化（issue #35）
  • 指纹脱敏 — 出站请求体黑名单指纹字段清洗（可开关），与提示词体系两层叠加

选号语义

选号 = 会话粘性（命中即定）→ 成本分层（硬过滤）→ 加权随机（软均衡）三层串联，各层语义：

  • 成本分层 — 账本把每个 (账号, 模型) 归入三档：tier 0（实测免费，单价 ≤ 0）、tier 1（无观测）、tier 2（实测收费）。同一次选号在存活的最便宜档内选：有 tier 0 就只在 tier 0 里挑，全池无免费观测才落到 tier 1，再不行才是 tier 2——即「贵号永远只作兜底」。tier 1 的号不会被跳过：新账号 / 新模型没跑过就没有观测，直接淘汰会把新号饿死。观测随 usage.credit 实时更新且 6 小时过期，所以限免窗口（如夜间免费）一结束，账号回到 tier 1 / tier 2，选号自动跟随——无需重启，日志会打 free tier ended 提示价格切换
  • 会话粘性 — 同一对话固定走同一账号（多轮上下文不跳号、上游 prompt cache 不碎）。粘性键全部为 conversation 维度（metadata.conversation_id / metadata.conversationId / conversation_id / conversationId 四键任一）；user_id 不是粘性键——它会把一个用户的所有并行对话钉到同一个号上（粒度远粗于上游对话级缓存边界），发 user_id 的客户端回落加权轮换。绑定 30 分钟滚动续期，空闲即过期释放
  • 负载分布 — 粘性与分层都未限定时，三因子加权随机（credits ×10 + 快过期积分 ×8 + 闲置补偿）把流量摊开：高余额号多扛、快过期积分的号先用、闲置号补位；防惊群跳过 100ms 内刚选中的号。权重是概率倾斜而非硬排序（Top-5 短名单 + 名单内抽签），不会让单一账号垄断流量

定时积分任务

  • 签到（09 / 21 点）— 每日签到 + 余额查询，余额恢复自动解冻冷却账号
  • 活跃地图（10 点）— 对话事件连发上报点亮活跃地图与连登天数、解锁领养前置，补签卡保连登、连登档位兑换 + 抽奖、礼包/补偿领取，回读 streak 自检
  • 猫猫旅行（09 / 21 点）— 独立排程：领养 / 派出 / 领奖闭环推进
  • token 保活（22 点）— 全账号刷新 token，session 失效连续 3 次才禁用
  • 开学季任务（12 点）— 任务点亮 + claim + 自动抽空抽奖余额，活动下线时自动跳过
  • 夜猫子任务（01 点）— 夜猫窗口（23:00–08:00 CST）内补一次 black_cat 任务

六类任务独立排程、独立开关（schedule.*_enabled），互不影响。

双域适配

  • 同时适配**国内版（CN，copilot.tencent.com / www.codebuddy.cn）与国际版（Global，www.workbuddy.ai）**账号
  • 共享同一账号池，由账号 realm 或请求模型名前缀（cn: / global:）决定路由；global.enabled 可一键锁死纯 CN 部署
  • 国际版支持注册激活、地区完善、一次性 trial 加油包领取（./trial.sh）

辅助工具

  • 积分日报：./credit.sh（美化 / -json，realm 感知双域）
  • 手动签到：./signin.sh（批量、幂等不重复计）
  • 领养联动 / 任务查询：scripts/task_runner.py（成长任务一体机，默认 dry-run）
  • 个性化提示词：prompt.file 指向自定义提示词文件即整体替换内置默认（custom/append 模式生效）

架构总览

flowchart LR
    Client["客户端 / SDK\nOpenAI 兼容请求"] --> H

    subgraph GWI["WorkBuddy2API 网关 :7863"]
        H["HTTP Handler\n鉴权 · 提示词改写 · 轮转"] --> P
        H --> S
        P["账号池\n三因子加权 · 熔断 · 冷却 · 租约"] --> U
        S["会话粘性路由"] -.绑定镜像.-> REDIS
        T["定时调度\n签到 09/21 · 旅行 09/21 · 活跃地图 10 · 保活 22\n开学季 12 · 夜猫子 01"] --> P
        U["上游 Client\nChatHTTP 流式 · 短 RPC"]
    end

    P -. "读凭证 (0600)" .-> AUTH[("auths/*.json")]
    P -. "状态镜像" .-> REDIS[("Upstash Redis\n可选")]
    U -->|"chat/completions (SSE)"| CB["CodeBuddy\ncopilot.tencent.com"]
    U -->|"billing / auth / growth"| CB
Loading

上游请求在出站前经历统一的改写管线（internal/upstream/payload.go）：强制 stream:true、developer 角色归一、tool_choice 归一、DeepSeek 思维链注入、reasoning_effort 档位降级、reasoning_content 回填、指纹脱敏。

快速开始

环境要求

  • Docker + Docker Compose（推荐部署方式，镜像内已含 app 低权限用户与全部工具脚本）
  • 一个或多个已注册的 CodeBuddy 账号，用于 OAuth 登录
  • 宿主机 Go ≥ 1.22（仅源码构建时需要）

Docker Compose 一键部署

git clone https://github.com/Sliverkiss/workbuddy2api.git
cd workbuddy2api
cp config.example.json config.json

编辑 config.json，至少设置 api_key（留空 = 不鉴权，公网部署务必设置）。示例中的 test_key 等均为占位符，config.example.json 不含任何真实密钥。

# 登录添加账号（重复执行可加多号；注意：执行过下方说明中的 chown 后，
# host 侧 login.sh 会被可写性预检拦截——此时请在容器内登录，见下方说明）
./login.sh

# 启动服务
docker compose up -d --build

# 健康检查（无可用账号时 503）；service 字段用于确认打到的是本网关
curl -s http://localhost:7863/healthz
# {"healthy":2,"total":3,"service":"workbuddy2api"}

login.sh 内置授权 URL 获取 + 浏览器登录 + token 轮询 + 首次签到 + auths/workbuddy-<uid>.json 落盘 + 容器重启，全程无 PKCE（state 由服务端签发）。账号池在容器启动时用 auths/ 目录自动对齐，新增凭证文件即自动发现。

非 root 宿主用户注意：./login.sh 以当前宿主用户落盘凭证（权限 0600），而容器内网关以 app(uid 10001) 读 + 回写（refresh / realm 补标识走 tmp+rename，需要目录写权限）。二者 uid 不同（例如 Linux 非 root 账号通常是 uid 1000）时容器读不到凭证文件，/status 账号数为 0——与 ./data 卷的属主问题同源。登录后、启动前把目录属主交给 10001（root 或部署用户执行）：

chown -R 10001:10001 ./auths

之后新增账号必须进容器内登录（app 自身落盘，属主即 10001，无需反复 chown；chown 后 host 侧 ./login.sh 无写权限，脚本会在启动浏览器授权前直接退出并提示，不会白走一遍 OAuth。容器内无 docker CLI，完成后回宿主机重启）：

docker compose exec -it wb2api bash -c './login.sh' && docker compose restart wb2api

源码构建

go build ./...
go vet ./...
go test ./...      # 完整测试套件
go run ./cmd/server -config config.json

构建二进制：

CGO_ENABLED=0 go build -trimpath -ldflags="-s -w" -o wb2api ./cmd/server
CGO_ENABLED=0 go build -trimpath -ldflags="-s -w" -o signin_bin ./cmd/signin
CGO_ENABLED=0 go build -trimpath -ldflags="-s -w" -o login ./cmd/login
CGO_ENABLED=0 go build -trimpath -ldflags="-s -w" -o credit ./cmd/credit

验证

# 模型列表
curl -s http://localhost:7863/v1/models -H "Authorization: Bearer your-api-key"

# 账号状态（汇总 + 每账号详情，disabled 账号透出 disabled_reason）
curl -s http://localhost:7863/status -H "Authorization: Bearer your-api-key"

# 流式聊天
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}'

# 非流式聊天（本地聚合）
curl -s 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":false}'

安全与合规

发布来源与合规边界

  • CI 自动打包：GitHub Actions（.github/workflows/build.yml）每日定时 + push tag 触发多架构（amd64/arm64）构建，发布至 ghcr.io，同时输出 amd64 离线 tar.gz artifact 供 NAS / 离线环境使用；也可本地 docker compose build 自构建
  • 登录 / 签到 / 积分工具：./login.sh / ./signin.sh / ./credit.sh
  • 无产物校验和：go.sum 仅约束 Go 模块依赖；Docker 镜像由本地 docker compose build 生成，未引用第三方镜像
  • 上游 CodeBuddy 属第三方商业产品，本项目是其非官方 OpenAI 兼容网关；使用其账号做 API 网关涉及目标平台服务条款与账号风险，作者不对账号封禁、条款违约或使用结果负责

授权使用边界

  • 仅限本人授权账号、本机 / 私有环境测试
  • 不得共享、转售、违规分发，或用于违反目标平台条款的用途
  • 遵守 CodeBuddy 平台服务条款与所在地法律
  • 妥善保管 auths/（明文凭证）与网关端口

免责声明

本项目（包括但不限于代码、脚本、文档、配置示例及仓库内任何资源，下称「本项目内容」）仅供个人学习与研究使用。使用本项目表示您已阅读并接受本声明全部条款；如不同意，请立即停止使用并删除全部相关内容。

1. 用途限制。 本项目内容仅可用于个人学习、研究等非商业用途；请勿将本项目用于任何商业目的或牟利行为，请勿违反所属国家 / 地区 / 组织的任何法律法规。本项目不构成对任何软件、服务、平台的使用建议或授权。

2. 账号与数据责任。 本项目可能涉及个人账号凭证的获取、存储与使用。您应仅使用本人持有且已获授权的账号，自行确认相关平台的服务条款与允许范围，并自行承担使用、存储凭证（如 auths/ 中的文件）及调用上游服务所产生的全部责任与风险。本项目不参与、不介入您与任何平台之间的契约关系。

3. 内容与第三方界限。 本项目内容中引用的第三方产品、服务、LOGO、图片、文案等，其权利均归各自权利人所有；本项目不保证此类内容的准确性、完整性、合法性，亦不代表支持或推荐任何第三方。如实存在侵权情形，请通过 Issues 告知，经核实后本项目会尽快处理。

4. 无担保与风险自担。 本项目内容按「现状」提供，不附带任何明示或默示的担保（包括但不限于适销性、特定用途适用性、准确性、不侵权等）。使用本项目（包括直接或间接）所产生的任何风险与后果（包括但不限于账号异常、数据丢失、服务中断、纠纷或损失），均由使用者自行承担，与本项目及其全部贡献者无关。

5. 责任限定。 在任何情况下，本项目及其作者、贡献者均不对任何直接、间接、偶然、特殊或后果性损害承担责任，无论该等损害是否基于合同、侵权或其他法律理论，即使已被告知发生该等损害的可能性。

6. 修改与分发。 基于本项目源代码进行的任何修改、衍生均系第三方自发行为，与本项目无关，相应后果由该第三方自行承担。本项目内所有资源文件，禁止任何公众号、自媒体进行任何形式的转载、发布。未经授权，任何组织或个人不得将本项目内容用于转载、发布或再分发。

7. 条款变更。 本项目保留随时修改、补充本声明的权利。修改后的声明自发布之日起生效，继续使用本项目即视为接受修订后的声明。本项目所有内容仅供学习和研究使用，请于学习研究完成后及时删除。

☕ Coffee

如果这个项目对你有帮助，欢迎请我喝杯咖啡～

💰 Solana AZAKF74rTu7UFVSNRzsKV4HHpTwarax6cG8KAh4fP5rQ
💎 Ethereum 0x1d418627aD6B043900CBE11fe439759bDF2b5170
₿ Bitcoin bc1q9w7h4j9msyd9q6lhl0398n4s3g8h4vchpqvc2k

License

本项目采用 MIT License 开源协议。

  • 在遵守 MIT License 前提下，允许使用、复制、修改、合并本项目源代码
  • 再分发（源码或二进制形式）时，须保留原仓库的 MIT 版权声明与许可声明，并在 NOTICE 或 README 中注明原始出处 https://github.com/Sliverkiss/workbuddy2api
  • 本项目不授予任何上游（CodeBuddy）接口或服务的权利；使用者仍需自行遵守上游服务条款
  • 本项目的使用同时受上方免责声明约束；如免责声明与 MIT License 存在不一致，以免责声明为准

About

WorkBuddy的 OpenAI 兼容反向代理，支持 OAuth 登录、多账号轮转、工具调用与流式响应。

Topics

2apicodebuddygatewayopenaireverseworkbuddy

Resources

Readme
MIT license
Activity

Stars

958 stars

Watchers

3 watching

Forks

275 forks
Report repository

Releases

Packages

Contributors

Languages