WorkBuddy2API-Hub — 国际版、国内版多账号网关中枢

[!IMPORTANT] 项目进入低频维护（2026-10-23） / Low-frequency maintenance

大幅降低更新频率与 Issue / PR 处理速度。请先阅读风险说明，再决定是否继续使用。

Updates and responses to issues / pull requests will be significantly reduced. Read the risk notice below before continuing.

[!WARNING] WorkBuddy 上游正在收紧对非官方客户端的识别与拦截。

• 封禁：2026-10-23 下午起，非官方客户端的识别与拦截明显收紧。
• 维护者：近期工作压力增大，无法保证及时更新与响应。
• 可用性：上游可能随时进一步收紧，导致本项目不可用。
• 账号风险：使用非官方客户端造成的风控、限流或封禁，由使用者自行承担。

Upstream enforcement tightened detection and blocking of unofficial clients from the afternoon of 2026-10-23. The maintainer is under increased workload and cannot guarantee timely updates or replies. The upstream may tighten further at any time; rate limits, account restrictions or bans caused by using an unofficial client are the user's responsibility.

本项目仅用于协议学习、研究与个人自用。请优先使用官方客户端，不要使用主账号，不要共享账号，也不要用于商业转售。

This project is for protocol research and personal use only. Prefer the official client, do not use your primary account, and do not resell or share access.

把腾讯 www.workbuddy.ai（国际版）与 codebuddy.cn（国内版）的原生服务封装成标准 OpenAI 兼容接口（Chat Completions / Responses），并提供默认关闭的实验性 Anthropic Messages 适配；同时补齐多账号调度与运维能力：

• 开箱即用：绿色包自带精简 Python（Windows），双击脚本即启；
• 双区域独立路由：国际版 / 国内版各自配置与调度，看板一键切换，状态落盘；
• 协议与风险：默认支持 Chat Completions、Responses API（Codex）；Anthropic Messages（Claude Code / Anthropic SDK）经协议转换且缓存兼容性尚未验证，默认禁用，仅可显式选择启用；
• 模型目录对齐官方桌面端：剔除补全通道与专线变体，能力与规格按桌面端宣告，上游新模型无需发版即进 /v1/models；
• 设备指纹隔离 (derive_id)：以账号 UID 稳定派生机器码与会话标识，同一账号不漂移、不同账号互不关联；
• 账号接入：看板点链接走浏览器 OAuth；Windows 上还能直接从运行中的桌面客户端导入（加密 token 就地解密），macOS / Linux 可手动粘贴解码密钥后导入；
• 每日自动化：国内版签到 / 成长与积分任务 / 猫猫旅行；国际版每日活跃打卡（真跑完网页会话）；后台调度器按 09:00 & 21:00、22:00、01:00 排程；
• 限额护栏：保留积分 · 每日 Token · 每日积分 · 按模型 Token 四条账号级护栏，单账号独立计数，本地 0 点解封（默认全部关闭）；
• OpenRouter 价估算：把 token 折算成等价花费（人民币 / 美元可切），逐条请求可悬停查看定价来源；
• 多 Key 与出口绑定：每个 Key 可固定走国际版或国内版、可限定模型，用量按 Key 归属；
• Web 看板：指标卡片、模型性能与用量大表、请求流水、账号与任务管理一屏可查。

⚡ Vibe Coding 产物：本项目为 100% Vibe Coding 协同产物——人类开发者提出架构与业务意图，AI 助手端到端完成逆向分析、链路调度、WAF 指纹脱敏与界面编写。

📌 提交代码贡献前：请先查看并严格遵循贡献手册 CONTRIBUTING.md——提交格式、测试门禁与端到端冒烟要求都在那里（AI / 智能体请特别注意其中的硬性规则节）。

一、快速启动

1. 本机运行

Windows 双击 start-wb-proxy.bat：默认静默启动（pythonw 后台运行 + 独立日志窗口，关掉日志窗口不会停服务，用面板电源按钮或 restart-wb-proxy.bat 停止）；想用「前台控制台 + 关窗即停」，双击 start-wb-proxy-visible.bat。macOS 双击 start-wb-proxy.command（首次被 Gatekeeper 拦截时右键 →「打开」确认一次），或在终端执行 ./start-wb-proxy.sh [端口]（默认 8788）。

启动后：API 地址 http://127.0.0.1:8788/v1，Web 看板 http://127.0.0.1:8788/。首次启动还没有账号，打开看板点「+ 添加账号 (OAuth)」完成授权即自动入库。

绿色包自带的精简 Python 运行时只覆盖 Windows；macOS / Linux 直接使用系统 Python，需要 3.9+（启动脚本找不到内置运行时会明确打印所用的解释器与版本）。Docker 部署自带基础镜像，不受影响。

zip 解压后若提示权限不足，先执行一次：chmod +x start-wb-proxy.sh start-wb-proxy.command start-wb-proxy-lan.sh start-wb-proxy-lan.command allow-firewall.command

2. 面板访问密码

看板需要面板访问密码（默认 admin），它与 API Key 相互独立：密码只用于打开看板，可在「设置」页修改（或启动时 --panel-password 指定），以 PBKDF2-SHA256 摘要存于 accounts/settings.json（不存明文），登录态只留在浏览器会话里。

本机 / 受信局域网自用可带 ?pwd=面板密码 免手输直接进面板（如 http://127.0.0.1:8788/?pwd=admin）；公网暴露时不要用——密码会留在浏览器历史与反向代理日志里。注意它和局域网共享的 ?key= 不同：?key= 只把 API Key 存给 /v1 用，不会自动登录面板。首次登录后请立即改掉默认密码。

3. 局域网共享

• Windows 双击 start-wb-proxy-lan.bat（静默）或 start-wb-proxy-lan-visible.bat（前台窗口，关窗即停）；macOS 双击 start-wb-proxy-lan.command，或 ./start-wb-proxy-lan.sh [端口] [Key]；
• Base URL http://<本机局域网IP>:8788/v1；带密钥直达面板 http://<IP>:8788/?key=生成的Key；
• API Key：首次启动生成高强度随机 Key，写入 accounts/settings.json 并打印在终端，重启复用；也可用第二个参数指定自己的 Key；
• macOS 防火墙：首次监听端口时选「允许」；macOS 15+ 还要在「系统设置 → 隐私与安全性 → 本地网络」允许终端，./allow-firewall.command 可查看状态并加白。

4. 多 API Key 与出口绑定

「设置」页可管理多个 Key，每个 Key 独立出口——不同客户端各用各的 Key，国内外流量互不干扰：

• 生成 / 绑定：填名称点「生成随机 Key」；可固定走 🌐 国际版或 🇨🇳 国内版，不绑定则跟随看板顶部的全局出口开关；
• 模型限制：可填允许的模型（如 deepseek*、gpt-6-astra，支持 *，逗号分隔），留空不限；不在列表里的请求本机直接返回 400，不送达上游、不消耗额度；
• 区域自检：Key 绑定的出口与模型不匹配时（如国际版 Key 调国内独占的 deepseek-v4-pro）直接返回可读 400，而不是上游晦涩的 WAF 报错；
• 启停 / 删除：可单独启停；删除后密钥立即失效，条目以只读形式留在「设置」页的「已删除」折叠区，历史用量仍显示它的名字；
• 用量归因：「数据看板」页按 Key 列出请求数、Token、缓存命中、积分与模型分布，口径与账号表一致；
• 防冲突：面板保存过 Key 后，启动参数里的 --api-key 自动失效。

5. Docker 部署

预编译双架构镜像（linux/amd64、linux/arm64）发布在 GHCR 与 Docker Hub，无需克隆代码、无需本地编译：

方式一：一键脚本（推荐）

# 官方源（可直连 GitHub 环境）：
curl -fsSL https://raw.githubusercontent.com/ardeyouxipianyi/workbuddy2api-hub/main/quick-deploy.sh | bash

# 国内网络 / NAS 加速（Connection reset 时用）：
curl -fsSL https://gh-proxy.com/https://raw.githubusercontent.com/ardeyouxipianyi/workbuddy2api-hub/main/quick-deploy.sh | sudo bash

NAS（如飞牛 fnOS）普通用户没有 Docker 权限时，把结尾的 bash 换成 sudo bash。再次运行同一条命令即平滑升级，账号与用量数据不受影响。

部署模式：默认 lan（8788:8788，局域网内可访问）。部署到公网服务器、或只想本机能连时，把环境变量放在管道后的 bash 前面：

curl -fsSL https://raw.githubusercontent.com/ardeyouxipianyi/workbuddy2api-hub/main/quick-deploy.sh | WB_DEPLOY_MODE=public bash

• local / public 只把宿主端口绑到 127.0.0.1，容器内仍是 HOST=0.0.0.0（Docker 转发需要）；
• public 请再套 Nginx / Caddy / Cloudflare Tunnel 并加 TLS，不要把 8788 直接开到公网；
• 已经存在的 docker-compose.yml 不会被自动改写端口映射，脚本只提示手动调整。

方式二：NAS / 面板单文件 Compose

在 NAS 或面板的 Compose 界面新建项目并粘贴以下内容保存启动，无需拉取源码：

services:
  wb-proxy:
    image: ghcr.io/ardeyouxipianyi/workbuddy2api-hub:latest   # 或 ardeyouxipianyi/workbuddy2api-hub:latest
    container_name: wb-proxy
    restart: unless-stopped
    ports:
      - "8788:8788"          # 左侧宿主端口可自选；右侧必须与下面的 PORT 一致
    environment:
      - HOST=0.0.0.0
      - PORT=8788
      # - API_KEY=your_secret_key   # 留空则自动生成并打印在启动日志
      - TZ=Asia/Shanghai
    volumes:
      - ./accounts:/app/accounts    # 账号凭证与配置（更新/重建容器不丢）
      - ./usage:/app/usage          # 用量流水日志（更新/重建容器不丢）

更新：docker compose pull && docker compose up -d（重建容器）。面板的「安装更新」按钮在镜像部署里默认不可用——镜像里既没有 systemd unit，也没有让 wb_update_portable.available() 成立的应用内 release-manifest.json；需要注册外部执行者（见下一节），而它只替换应用层文件，不会重建镜像。

无 systemd 部署的面板一键更新：容器 / LXC / 便携版没有 systemd 时，面板默认不能安装更新。部署方可以注册一个外部执行者：

1. 让网关能写请求：挂载一个目录（例如 /run/workbuddy2api-hub-updater），设置 WB_UPDATE_INSTALL_ENABLED=1、WB_UPDATE_REQUEST_DIR=<目录>，并设置 WB_UPDATE_EXECUTOR=external（或在该目录放一个 executor.json）。
2. 执行者监听 <目录>/request.json，读取 action / tag / version / pid / port / root，执行下载 → 校验 SHA256SUMS → 备份 → 停进程 → 替换 → 等 supervisor 拉起 → 探针 /health；失败回滚。action 缺省为 install，rollback 表示用本地备份恢复旧版本（不下载）。参考实现：wb_update_external.py --request-dir <目录>（需要 supervisor 在网关退出后自动拉起）。
3. 执行者写 <目录>/status.json，state 使用 queued / downloading / verifying / backing_up / stopping / applying / restoring / restarting / succeeded / restored / rolled_back / failed，面板沿用现有状态机。

保留历史版本备份：设置页可选 0–3 份（默认 1），更新成功后把旧版本的程序文件留在 updates/backup-<这次更新去的版本>/（内容其实是更新前的版本），面板「版本回退」据此列出可回退的版本。0 = 不留备份，回退不可用。

约束：accounts/、usage/ 不参与替换；执行者必须有应用目录写权限；网关只写请求，不碰自己的代码。

方式三：Watchtower 自动静默更新

docker run -d --name wb-proxy-watchtower --restart unless-stopped \
  -v /var/run/docker.sock:/var/run/docker.sock \
  containrrr/watchtower:latest --interval 86400 --cleanup wb-proxy

补充与排错

• 持久化：./accounts 与 ./usage 由宿主机挂载，更新或重建容器都不丢数据；
• docker run 快捷启动：

  docker run -d --name wb-proxy --restart unless-stopped -p 8788:8788 \
    -v $(pwd)/accounts:/app/accounts -v $(pwd)/usage:/app/usage \
    ghcr.io/ardeyouxipianyi/workbuddy2api-hub:latest
  

• 鉴权：容器以 --lan 启动，无显式 API_KEY 时自动生成 Key 写入 ./accounts/settings.json 并打印在日志里：docker compose logs wb-proxy | grep -i "api key"；
• 镜像名要带 registry：写成 ardeyouxipianyi/workbuddy2api-hub 会去 Docker Hub 找并报 pull access denied，正确写法是 ghcr.io/ardeyouxipianyi/workbuddy2api-hub:latest（GHCR 公开包，拉取无需登录）；
• 目录权限：默认以 root（0:0）运行；想以宿主用户跑就设 PUID / PGID（或 --user $(id -u):$(id -g)），并确保两个挂载目录对该 uid 可写；
• 健康检查：镜像自带 HEALTHCHECK（每 30s 探一次 /health），docker ps 的 STATUS 列会显示 healthy / unhealthy；
• 源码构建：docker compose -f docker-compose.build.yml up -d --build。

6. 测试

python tests/run_all.py            # 全部套件
python tests/run_all.py realm      # 只跑名字里含 realm 的

• 234 个套件：175 个 Python + 59 个 JS；JS 需要 PATH 上有 node，缺失时会跳过并提示。
• tests/_mobile_check.py 是独立的 Playwright 手机/桌面布局检查器（需自行安装 Playwright），按需手动运行，不在上面的套件集里。
• CI（.github/workflows/tests.yml）跑同一条命令：Ubuntu 上 python 3.9 与 3.12（3.9 是本项目声称的最低版本），Windows 上 python 3.12；推送 v* tag 时额外断言 tag == 源码版本（-ci 演练 tag 豁免）。

二、核心特性

1. 模型列表对齐官方桌面端

对官方本地配置清单（50+ 底层模型）做清洗：剔除行内补全专用模型（codewise-*、completion-gf、hunyuan-3b/7b 等）与多云专线变体（*-volc、*-lkeap 等），严格对齐官方 Windows 桌面端，并宣告每个模型的上下文窗口、单次最大输出、视觉支持、工具调用与推理档位。

• 🌐 国际版（17 个）：hy4-preview-f、hy3、deepseek-v4.1-flash、gpt-6-astra、gpt-5.6-sol、gpt-5.6-terra、gpt-5.6-luna、gpt-5.5、gpt-5.4、grok-4.7、gemini-3.5-flash、glm-5.3-flash、glm-5.3、glm-5.2、kimi-k3、kimi-k2.6、kimi-k2.8-preview
• 🇨🇳 国内版（14 个）：hy4-preview-f、hy3、deepseek-v4.1-flash、deepseek-v4-pro、glm-5.3、glm-5.3-flash、glm-5.2、glm-5.1、glm-5v-turbo、minimax-m3、kimi-k3-1、kimi-k2.8-preview、kimi-k2.7、kimi-k2.6

清单与上游 `GET /v3/c