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

本项目为 Qoder2API-Hub，将阿里 qoder.com.cn (国内版) 与 qoder.com (国际版) 的原生服务封装为标准 OpenAI 兼容接口，支持 Chat Completions 与 Responses API。具备多账号负载轮询、稳定物理设备指纹隔离、OAuth 设备授权一键免客户端登录、每日签到与实时额度查询、Pro 福利包自动领取、后台常驻定时调度器、Web 监控看板等全套能力 —— 与 WorkBuddy2API-Hub 同构的完整功能矩阵。

• 开箱即用：双击批处理脚本即启；亦支持 Docker 容器化部署，零外部 pip 依赖。
• 本机已登录凭证一键入池（双区）：只读探测桌面 App（auth.v1.dat，os_crypt/DPAPI 解密）与 Qoder CLI（~/.qoder*/.auth/user，AES-128-CBC）两类官方存储，看板两步确认导入，永不静默采用。
• 模型清单完全跟官方走（双区不同、以官方此刻为准）：三源优先级 —— 动态 /algo/api/v2/model/list（COSY 签名，GET 需携带与签名一致的 {} body，否则 403）> 本机官方客户端模型目录缓存（~/.qoder*/.models/<uid>/catalog-v6，QMC/HKDF+AES-256-GCM 解密）> 双区官方快照文件（qoder_catalog_intl.json/qoder_catalog_cn.json，python _refresh_catalog.py 一键随客户端更新）；清单以动态源返回的集合为准（官方桌面版此刻显示什么这里就显示什么，如国际版动态 15 条就不多塞静态独有的 smodel/cmodel）。逐字段忠实保留：id = 官方模型名（如 Qwen3.8-Max，客户端唯一需要填的值；upstream_key/aliases 同时给出 key、key (Name) 与人类别名等全部可填形式）、官方桌面版介绍文案（description，取自客户端 dynamic-text）、本地化名（name_local，如 Ultimate→极致）、context_config 多窗口（200K 默认/400K/1M）、thinking_config 思考档位（low/medium/high/xhigh/max + 默认标注 + 可关闭）、峰谷价（price_factor_peak 促销前倍率 → price_factor_valley 谷时倍率 + off_peak 时段窗口 22:00-08:00 与官方错峰文案）、is_free/is_new；官方 enable=false 条目不过滤，附官方原文禁用原因（disabled_reason = "需要升级或购买千问官方套餐开放"，并透传上游 disabled_message_key）。最大输出：官方 catalog 与动态接口原始响应均无此字段，故不再输出/展示任何编造值。
• 双区域独立路由：支持 🌐 国际版 (qoder.com / api1.qoder.sh，备用 api2/api3 自动故障切换) 与 🇨🇳 国内版 (qoder.com.cn / gateway.qoder.com.cn) 独立配置与管理，区域独占模型（如国内 q37fmodel/glm-5.2、国际 smodel/ultimate）自动路由到归属出口并拦截错配 Key，看板一键切换且状态落盘持久化。
• COSY 签名推理链路：RSA 包裹 AES 会话密钥 + MD5 请求签名 + 自定义 Base64 请求体编码，纯标准库实现（含 AES-128/256、RSA-PKCS1v15、GCM、DPAPI、QMC 纯 Python 实现，Docker alpine 下同样零依赖），逆向对齐官方桌面/CLI 客户端协议。
• 稳定物理设备指纹隔离 (derive_id)：以账号自身 UID 稳定哈希派生专属 cosy-machineid / cosy-machinetoken / 会话标识，同一账号长期固定在同一台虚拟物理设备，天然防多号关联风控。
• OAuth 设备授权一键免客户端登录：PKCE (S256) 设备流（双区 URL 参数按官方差异构造：国内带 redirect_uri+client_id+machine_id，国际带 client_id+machine_id），点击看板链接在浏览器完成授权即可自动入池；亦支持 PAT (pt-) 导入，jobToken 自动交换与轮换。
• 每日签到与额度体系（双区域 · 真实领取）：「每日领取 100 Credits」等活动由网关直接领取——用桌面端请求头（Cosy-ClientType: 10 + 机器头，缺了服务端会返回空列表）列出活动 → 对 CLAIMABLE 的 Credits 活动 POST /sash/api/v1/me/campaigns/{id}/claim（官方幂等：已领返回 replayed，不会重复发放）；旧 sash 签到接口仅在仍开放时兜底（能力运行时探测，404 记「本区域无此接口」6 小时后自动重探）；Pro 升级包资格检查与领取、quota/usage 额度与套餐快照实时刷新。
• 后台常驻定时调度器：每日整点排程（09:00 / 21:00 签到 · 22:00 Token 集中保活），drt- / jrt- 按前缀路由刷新，PAT 最终兜底。
• 双协议全功能支持：同时支持标准 OpenAI Chat Completions 协议与 Responses API (Codex / Claude Code)，含 custom freeform 工具（apply_patch）双向转译、DSML 工具调用回退解析，以及泄漏文本回读（模型把历史工具调用序列化复述成正文时，流式/非流式/Responses 三链路都还原为结构化 tool_calls；若回声被截断无法还原，则按严格判据吞掉、绝不把内部标记透给用户，而普通回复一律 fail-open 不吞正文）。
• 现代化 Web 看板：弹性指标卡片、签到与福利中心、模型能力清单、性能指标与用量透视、实时请求流水与运行日志。

⚡ 本项目架构与交互对齐 WorkBuddy2API-Hub，上游协议替换为 Qoder COSY 签名体系。

🖼️ 看板预览 (Dashboard Preview)

网关总览 —— 双区出口状态、调度器、账号池与请求流水一屏尽览：

模型清单 —— 与官方桌面版同源：官方模型名、峰谷价、上下文多窗口、思考档位、能力徽标：

数据指标看板 —— Token 消耗透视、TTFT 首字延迟、生成速度与缓存命中率：

签到与福利中心 —— 每日签到领积分、Pro 福利包一键领取、限时活动真实状态（双区域）：

一、快速启动

1. 本机单机使用

双击运行 start-qoder-proxy.bat，保持窗口运行：

• API 接口地址：http://127.0.0.1:8790/v1
• Web 监控看板：http://127.0.0.1:8790/

⚠️ "客户端一直显示工作中、一个字都不吐，网关日志也毫无变化" → 九成是网关没在跑：请求根本没到达，所以日志自然一动不动。一条命令确诊：

python _diag_gateway.py --chat   # 端口 → /health → /v1/models → 真实流式，逐项报出断在哪
python _diag_campaign.py         # 签到/活动链路体检（含本机虚拟化状态，中文输出）

• 生命周期就是那个 cmd 窗口（刻意的设计）：窗口开着网关就活着，关掉窗口网关即停，不会有后台残留进程；下次要用重新双击 start-qoder-proxy.bat 即可。
• 判别口诀：日志时间戳停在某一刻、此后再无 POST /v1/chat/completions = 网关已停；重新双击启动脚本即可恢复。

ℹ️ 默认端口 8790（8788 被 mimo-api-proxy.mjs 占用，8789 为 wb-proxy 默认）。改端口：start-qoder-proxy.bat 8791。

首次启动若无账号，直接打开看板点击 「+ 添加账号 (OAuth)」，在浏览器完成设备授权即可自动加入；或点 「🔑 导入 PAT」 粘贴个人访问令牌。

2. 面板访问密码

打开看板需要先输入面板访问密码，默认是 admin。它与 API Key 相互独立：

• 面板密码只用于打开网页看板，可在看板「设置」页修改（也可启动时 --panel-password 指定）；
• 密码以 PBKDF2-SHA256 摘要形式保存在 accounts/settings.json，不存明文；
• 登录状态存放在浏览器会话中，关闭浏览器或重启网关后需要重新输入。

首次登录后请立即到「设置」修改默认密码。

3. 局域网共享模式

双击运行 start-qoder-proxy-lan.bat，允许局域网内其他设备访问：

• Base URL：http://<本机局域网IP>:8790/v1
• 密钥随机生成并持久化：LAN 模式首次启动生成高强度随机 API Key（qd- 前缀），保存到 accounts/settings.json 并在终端打印，重启复用。
• 自定义 Key：start-qoder-proxy-lan.bat 8790 我的Key
• 支持带密钥直达面板：http://<IP>:8790/?key=生成的Key。
• 其他设备连不上时，管理员运行一次 allow-firewall.bat 放行防火墙。

4. 多 API Key 管理与出口绑定

网关支持多 API Key 并行管理，并可为每个 Key 指定独立出口：

• 添加与在线生成：看板「设置」页，输入名称 + 一键生成随机 Key；
• 出口自由绑定：
  • 🌐 国际版出口：该 Key 流量强制走 api1.qoder.sh（连不上自动切 api2/api3）
  • 🇨🇳 国内版出口：该 Key 流量强制走 gateway.qoder.com.cn
  • 跟随面板切换：未绑定出口的 Key 实时跟随看板顶部全局出口
• 状态管理：单独启停、一键删除，删除即刻失效；配置持久化到 accounts/settings.json；
• 安全防冲突：面板配置过 Key 后，启动脚本里的旧 --api-key 自动失效；
• 模型区域自检：Key 出口与模型区域不匹配时返回通俗 400，杜绝上游晦涩拒流报错。

5. Docker 容器化部署

# 1. 后台启动容器 (自动构建并运行)
docker compose up -d

# 2. 查看网关日志
docker compose logs -f

或直接 docker run：

docker run -d --name qoder-proxy --restart unless-stopped \
  -p 8790:8790 -v $(pwd)/accounts:/app/accounts -v $(pwd)/usage:/app/usage \
  -e API_KEY=your_secret_key $(docker build -q .)

• 持久化目录：./accounts（账号凭证及出口设置）与 ./usage（请求流水与指标快照）；
• 配置参数：环境变量 API_KEY、PORT（监听端口，默认 8790）、HOST（监听地址，默认 127.0.0.1；容器内如需对外暴露设为 0.0.0.0）。

二、核心特性详解

1. 请求链路（COSY 签名推理）

瞬时故障韧性（双层）：上游把自己的 provider 故障包装成 418/5xx + provider_error 抛回，或对 qoder.sh 出现 TLS/连接抖动（SSL: UNEXPECTED_EOF...）时：

• 连接层（urlopen 时刻的 HTTP/传输错误）：同账号快速重试 2 次（1s/2s 退避）；
• 流内信封层（关键形态：上游先 HTTP200 建流、再在 SSE 信封里投 statusCodeValue=418——表现为 access log 记 200 而业务错 418）：在尚未向客户端写出任何上游字节前重开上游重试 2 次（chat 流式/非流式 + Responses 全覆盖），流式客户端全程无感。

重试仍失败才短冷却（15s，单账号池实际 3s）换号——不因上游的锅罚账号 60 秒；短错误冷却期间（≤10s）后续请求改为「等待续上」而非报错，且 429 usage exceeds frequency limit 只在上游真频控时出现（账号错误冷却不再被误标为频控）。客户端参数错误（invalid_parameter_error 等）与上游内容安全审核拒绝（InternalError.Algo.DataInspectionFailed: Input text data may contain inappropriate content）绝不重试、快速失败——后者返回中文解释（content_policy_rejected：确定性拒绝、重试无效，请检查/缩短输入），由调用方修改输入而非等待。耗尽后其余瞬时错误客户端收到中文友好提示（upstream_transient_error）；错误详情经 qoder_detail 挂载保留 400 字节完整送达日志（含内层 details）。

HTTP 帧层与保活（治“一直重连/连不上”）：

• 流式响应使用 HTTP/1.1 Transfer-Encoding: chunked 并以 0\r\n\r\n 正确收尾，不再发 Connection: close：同一个 keep-alive 连接可连续复用（实测同连接连发 5 次流式全部成功）。此前裸写字节 + close 会让连接池型客户端复用已半关闭的连接，表现为反复重连。
• SSE 心跳保活：上游首字延迟实测可达 40–71 秒（xhigh + 2–3 万 token 长上下文），等待期间网关每 5 秒发送一个 SSE 注释帧 : ping（客户端规范要求忽略），避免客户端/中间代理空闲超时断连重连。可用环境变量 QD_SSE_HEARTBEAT 调整间隔（秒，0 关闭）。
• 探活端点：GET /ping（以及 /healthz、/livez、/readyz）返回纯文本 pong，不需要面板密码或 API Key、不查账号池——供客户端/脚本判活用；此前返回 404 会被判成网关不可用而反复重连。完整状态仍看 GET /health。

DeepSeek-Flash 偶发失败修复（issue #2）：这族模型的多轮一致性与 reasoning_content 绑定，而旧实现有两处断点，导致"偶发失败、重试有时能过"：

• 判定看的是客户端名字而不是上游模型：旧逻辑只认名字前缀 deepseek，客户端按文档写「内部 key：dfmodel」时整套兼容处理不会执行。现按上游 key 判定（is_deepseek_model：dmodel/dfmodel/DeepSeek-Flash/展示 id「dfmodel (DeepSeek-Flash)」都命中）；
• 补好的字段在真实请求路径上被丢掉：backfill_reasoning_content() 写入 reasoning_content 后，flatten_messages() 压平会话时无条件丢弃该字段——即"兼容层写了但从没发出去"。现按目标模型保留（DeepSeek 族保留、其它模型不带，避免上游因未知字段拒答）。

修复后已对国内版 dfmodel 实测：纯问答、展示名 DeepSeek-Flash、带 reasoning_content 的多轮历史、空 reasoning_content、reasoning 别名、工具调用历史、流式 27 帧全部 200 正常收尾。

客户端版本对齐（0.4.3 双区桌面端）：协议常量按官方客户端当前版本逐项核对——

• cosy-version = 1.1.64（更新自旧 CLI 的 0.1.43；取自 0.4.3 内置 qoder-agent-sdk/qoder-cn-agent-sdk 的版本常量，实测模型列表与推理均正常）；
• 国际版推理主机 = api1.qoder.sh（客户端 endpoint 缓存里的主选；api2/api3 为官方故障切换域名，网关同样按序切换，单个域名故障不再拖垮全部请求）；
• 国内版主机 gateway.qoder.com.cn、双区 openapi 基址、/algo/api/v2/service/pro/sse/agent_chat_generation（推理）、/algo/api/v2/model/list（模型清单）、/api/v1/deviceToken|jobToken/*、/api/v1/userinfo、/api/v2/quota/usage、/api/v2/user/plan、/sash/api/v1/me/*（签到/活动平台）均与新客户端一致，无变化；
• COSY RSA 公钥与新客户端内置 PEM 逐字节相同；官方模型目录快照已用新版客户端缓存刷新（价格倍率/上下文/思考默认档等）。

思考档位（reasoning_effort）归一化：官方上游字段就是 parameters.reasoning_effort（0.4.3 SDK 参数表里的 reasoning_effort，取值 none/low/medium/high/xhigh/max），但每个模型的合法档位不同，而上游对不支持的档位不报错、直接忽略（回落到模型默认档）——这就是"给 Qwen3.8-Flash 传档位没反应"的原因：

网关现在按官方目录里该模型的档位表归一化（normalize_reasoning_effort()）：命中原样透传；未命中取"最近的合法档位"（同距时偏向该模型默认档，如 dfmodel 的 medium→high、xhigh→max，qfmodel 的 high→medium、max→xhigh），并在日志标注；模型有 thinking_config 但无档位表时不再下发无效档位（只保留 none）；模型完全没有 thinking_config（如路由器 auto）则原样透传，不做猜测。/v1/models 的 reasoning_efforts / reasoning_default_effort 字段即为该模型的合法档位与默认档。另兼容 reasoning.effort 与 thinking.effort/level 三种客户端写法。

客户端 OpenAI 请求
  → build_qoder_body()   官方 baseprompt 模板 + 会话压平（