v1.0.8

v1.0.8 发布说明

自 v1.0.7 起的累积更新，共 5 个 commit、23 个文件、+5218 / −301 行。
全量测试 335 passed（v1.0.7 是 231），零回归。

重点新能力

• 免费模型雷达（app/freemodels.py）：定期拉取 OpenRouter 免费模型名单，发现「新面孔」时在模型页顶部弹一次性横幅提醒——判据是「有没有未确认的新东西」而不是「有没有数据」，所以不会反复弹；点确认后才安静。匿名 stealth 模型（名字都藏起来的临测模型）也给档位标注。缓存周期与新面孔认定天数可在设置里调。
• 渠道「额外模型」（extra_models）：免费网关常有「上游 GET /models 不列出、但实际能调」的模型。现在渠道表单可以手填这些模型，与上游列表合并展示、参与路由。附带修了一条连带 bug：上游 /models 整个挂掉时，只要额外模型非空，渠道不再被整条判停。
• 免费模型自动补全（modelcat）：不想手输模型名的话，渠道表单可勾选「自动补全免费模型」——接 models.dev 公开目录，只取输入/输出都明确标 0 的模型作候选，探活通过才并入渠道（撞 429 / 5xx 说明模型存在但忙，转待验证；4xx 直接丢弃），不用再手动一个个添。
• 统计页每日请求量：单柱拆双柱。同一天 = 左柱请求次数（沿用成功/中断/失败三层配色）+ 右柱 Tokens 消耗（青绿单色，只表体量）。两组各按自己的区间峰值归一化并留 15% 余量；请求柱逐日封顶、恒低于 Tokens 柱（量级差 3~4 个数量级，等高对比没有意义）；柱顶数字按柱色着色、贴各自柱顶，放不下时自动避让（矮柱数字不高过高柱）；Tokens 数字统一「万」单位带小数（柱顶 / 悬停 / 图例 / 总量卡四处同口径）。

判定与稳定性

• 429 误判修复 + 探活收紧：免费模型撞 429 不再被兜底判成「账户余额不足，需充值」；分钟级限流（上游瞬时抖动）与「额度用尽」分离记账，限流黄标等待恢复而非标红 down、重启不回；「余额 ≤ 0」的兜底分支不再误伤免费模型。探活判据从「/models 里存不存在」收紧为「实际能不能调通」。
• 渠道级地域封锁穿透：Google Gemini 这类按出口 IP 封锁的渠道，旧行为是一句「渠道无效、已停用或未提供该模型」满屏糊脸，还可能连坐整条渠道。现在按响应正文措辞识别地域封锁（不是看 HTTP 状态码）：只标「受限」，不写稳定分、不标 down；「扫描全部模型」能真实逐模型推进，换到支持地区的出口后，下一轮健康检查自动回绿（默认 30 分钟）。

工程

• .gitignore 补 _archive/、_preview/——本地归档与验证产物永不入库。

升级方式

下载下方 free-api-hub-v1.0.8-win64.zip，解压即用（exe 放包根，数据文件同目录自动生成）。

已知限制

• 被地域封锁的渠道，在换到支持地区的出口之前，健康检查显示全模型「受限」黄标——这是预期行为，不是故障；换出口后自动恢复。
• 自动补全依赖 models.dev 公开目录的快照（有缓存周期），刚上线几天的模型可能滞后一轮才被补进。

v1.0.7

v1.0.7 发布说明

承接 PR #1（Anthropic Messages 协议翻译层）。自 v1.0.6 起 10 个 commit、15 个文件、+6940 / −941 行。
全量测试 231 passed（v1.0.6 是 161），零回归。

重点新能力

• /v1/messages：Anthropic Messages 协议翻译层。Claude Code、Anthropic SDK 这类只讲 Anthropic 协议的客户端，把 base URL 指向 http://127.0.0.1:8787、API Key 填网关 Token 就能用。客户端发的是 x-api-key 头（不是 Authorization: Bearer），网关两种都认。
  • 请求侧：system（字符串或块数组）、messages 的块数组（text / image / tool_result）、tools + tool_choice（auto / any / tool / none）、stop_sequences、temperature / top_p / top_k。
  • 响应侧：流式事件流 message_start → content_block_start / content_block_delta / content_block_stop → message_delta → message_stop；多轮工具调用的 tool_use.id ↔ tool_use_id 原样保留。
  • max_tokens 必填（协议如此）：缺了直接 400。不替客户端猜一个值——猜小了会把答案截断，而它看不到提示。
  • /v1/messages/count_tokens（原来 404）：下游是 chat 兼容渠道，没有 count_tokens 可透传，做法是按 /v1/messages 同一套翻译得到 chat body 再估它的大小（中文按字、其余按 4 字符约 1 token，图片按固定值）。量级够客户端判断上下文预算；要官方口径的精确值只能直连 Anthropic。
  • ⚠️ 不处理思考块：Anthropic 的 thinking / redacted_thinking 块要求服务端签名，网关给不出合法签名，硬塞假块会被客户端判为协议错误——请求里的思考块忽略并记日志，上游推理内容也不译成思考块。要思考内容请走 chat 入口（那边是 reasoning_content）。
• 下游协议抽成 dialects 注册表。内部形状永远是 chat completions，每种方言实现 to_chat / convert 两个函数，渠道路由、冷却分类、失败换路、会话粘性、用量记账都不在方言层。三种方言：chat（恒等映射）、responses、messages。加第四种 = 一个模块 + 注册表一行 + main.py 两行端点。/v1/chat/completions 也接上了注册表，让「三种入口一个形状」在代码里真正成立（副作用：请求体不是 JSON 对象时由 to_chat 挡成 400，旧写法是 AttributeError → 500）。

协议正确性修复（PR #1 合入后补的）

• stop_reason 误判：回包里明明有 tool_use 块，只要 finish_reason 缺失 / 是 None / 被渠道写成 "stop" / 编成不认识的值，就会报 end_turn——客户端据此认为这一轮正常结束，工具静默地不被执行。免额渠道漏 finish_reason 并不罕见，而这个网关恰恰是聚合这类渠道的。现在有 tool_use 块就以 tool_use 为准，但截断（length）优先——参数可能只写了一半，不该让客户端照着执行。流式与非流式统一走 _stop_reason()。
• 流式 content_block 顺序：改成「开新块之前先关掉旧块」，每个块自己走完 start → delta* → stop 才轮到下一个。旧写法在并行工具调用时发的是 start(1) start(2) stop(1) stop(2)，工具之后再出文本时 stop 顺序与 start 相反，都不合 Anthropic 规范。官方 SDK 对此是宽容的（anthropic python 1.7 / @anthropic-ai/sdk 0.127 实测都能把内容拼回来），所以这不是「会不会崩」，是「守不守约」——也正因此只有测试能把这条不变量钉住。
• 回包 model 口径统一：改为优先取上游返回值，与 responses 方言一致。同一个网关的两个协议入口不该对同一个字段给出不同答案。
• 错误体形状：鉴权失败与 Host / 跨域拒绝这几条边缘路径，对 /v1/messages 改回 Anthropic 形状的错误体，不再回通用的 {"detail": ...}。
• 清死代码：_ANTHROPIC_ONLY（定义后全文未引用）、回包上的 anthropic-version 响应头（那是请求头，官方响应里没有）。

合规与工程

• 第三方许可随包分发（这是本次发版的主因）。v1.0.6 的包里一份许可文本都没有（09-22 下载 zip 逐条核对确认），根因是 v1.0.6 的 tag 指向 9f561c8，正是 PR #1 的 base，那次发版跑的是旧 release.yml。现在包内带 LICENSE + THIRD-PARTY-LICENSES.md（26 项依赖的许可与版权声明汇总，3604 行）。
• 清单集合口径修正：原来按「跑脚本那台机器上装了什么」取集合，两个方向都会偏——装过 pyinstaller 的机器会把构建期工具一起列进来；依赖没装齐的机器则漏项（提交上来的那份只有 15 项，漏掉 pywebview / pystray / pillow，其中 pystray 是 LGPLv3）。改成从 requirements.txt 取根、按 Requires-Dist 求传递闭包，集合不再取决于本机装了什么。
• CI 新增（.github/workflows/ci.yml）。仓库原先只有 release.yml，触发条件仅 push: tags: v*，于是任何 PR 都没有自动验证，review 全凭人肉。现在 PR 与 push main 都跑 pytest + 许可清单同步校验（只比依赖集合、不比版本号——requirements.txt 全是 >=，拿版本号当失败条件会让 CI 周期性变红，而那种红不说明清单错了）。
• 修 Windows CI 控制台编码：许可脚本打印进度会崩在 cp1252 上，脚本内强制 stdout / stderr 走 UTF-8。

升级方式

下载下方 free-api-hub-v1.0.7-win64.zip，解压即用（exe 放包根，数据文件同目录自动生成）。

已知限制

• 许可文本在包内 _internal/ 目录下，不在 zip 根目录。PyInstaller 6 的 onedir 会把所有 datas 收进 _internal/，spec 里写的 dest . 也不例外。合规上算随包分发，但从 zip 根目录看不出来——下一次发版会在包根再放一份。

v1.0.6

v1.0.6 发布说明

自 v1.0.5 起的累积更新，共 23 项改动（15 个文件、5050 行）。全量测试 161 passed，零回归。

重点新能力

• /v1/responses 翻译层：OpenAI Responses 协议（Codex CLI / 新版 SDK 只认这个端点）↔ /v1/chat/completions 双向翻译。请求译完交给 _chat_v1，复用全部路由 / 冷却 / 会话粘性 / 记账；流式旁路转 SSE，覆盖 reasoning / 文本 / 工具调用增量、custom_tool_call 还原、[DONE] 不外泄。已用双 uvicorn 真 TCP 流式验过 15 种事件名与 call_id 闭合，生产侧 vibe-astock「接入 AI」probe 通过。
• namespace 工具摊平：codex 0.153 把 MCP 工具打包成 {type:"namespace", tools:[…]}，旧翻译层当未知类型丢弃 → 模型看不到工具。现已摊平进 chat tools，并在回包 function_call 补回 namespace 字段（codex 靠它路由 MCP，非流式 / 流式两处都补）。
• auto-* 连字符别名：auto-balanced / -quality / -speed / -stability / -vision。部分客户端（如 codex）把模型名限死在 [A-Za-z0-9._/-]，冒号会注入 config TOML 被禁。冒号版 auto:* 已删除（再填会当普通模型名查 → 404）。

稳定性与判定

• 榜单缓存落盘：AA 榜分 / 视觉能力不再依赖 OpenRouter 在线；公开端点免密钥兜底；空态拒写盘；兜底与渠道检查并行。启动耗时 4.0s → 1.1s。
• 睡眠唤醒自愈：整轮全挂且全是本机网络错误 → 10s~60s 短退避重试（原来要等一整个检查周期）；唤醒检测 + 重建连接池；降级期不写模型状态、不烧探测额度。
• 记账口径修正：流式「同一 chunk 先解析再转发」→ 客户端收到结束标记就断连不再被记成中断；新增 usage.superseded（失败但已换路）；客户端中断时看模型有无输出 → 有输出记成功（标「客户端中断」），一个字没出才记「已中断」。
• 中断行 Tokens 列：新增 usage.out_chars（实际输出字符数）+ 老行回填，照实显示「17,374 字」而非「—」。
• OpenRouter 免费模型余额误判修复：free_daily / minute 的正文分类不再被余额接口覆盖。
• 启动归正判据收窄：每日额度冷却文案不再被误升成永久 down。
• down 的出口（方案 B）：手动测试成为 down 唯一出口；前端补「● 不可用 N」开关（默认关）+ 红点行 + 行内「测试」键。
• 模型级状态退出可用性判定（A1）：改为纯展示，可用性只看渠道聚合；新增 channels[].unavail_reason / models[].test_channel；渠道 chip 红=不可用、原因全进悬停。
• 手动测试候选口径对齐：活渠道优先、所有渠道试完才定论；返回值加 attempts（逐条列出试过哪几条渠道）。

体验与界面

• 排序视图修复：compScore 改读当前视图，四个 chip 顺序各不相同。
• 前端 no-store：/ 加 Cache-Control: no-store，托盘加「刷新界面」——改前端不必再重启。
• 手动档位：模型页点档位 chip 改档，落 model_tier_exact（点名表，优先于正则表）。
• 视觉专属收藏：pinned_vision 独立于主收藏，只管视觉视图与 auto-vision。
• 会话粘性：auto-* 认会话（首条 user 消息指纹 / 显式头），粘住本会话上次成功产出的模型，只有它失败才换；落 runtime_state.json 重启不丢；新增 GET/DELETE /api/sticky。
• 官方额度响应头：接上魔搭 modelscope-ratelimit-* 4 个头（模型级 → ratelimit，账号级 → user_quota），额度见底提前换路；429 降级到模型级（≥4 个不同模型短窗口爆发才判账号级）。
• 速度维 log 线性化：400/(400+ms) 改为 log 线性化，速度优先视图桶内排序真正生效（前后端同步）。
• 工具条布局修复：整页 max-width 1180 → 1300，工具条 flex-wrap + 分组，杜绝组内折行。

升级方式

下载下方 free-api-hub-v1.0.6-win64.zip，解压即用（exe 放包根，数据文件同目录自动生成）。

已知限制

• 本版发布包里没有任何许可文本（09-22 下载 zip 逐条核对确认）。根因：v1.0.6 的 tag 指向 9f561c8，正是 /v1/messages 那个 PR 的 base，因此这次发版跑的是旧 release.yml。v1.0.7 已补上。

v1.0.5

修复

流式请求「已完成却被记成失败」

客户端读完回答就关闭连接是正常行为，而上游（魔搭最典型）发完数据后收尾慢，网关会卡在
等最后几个字节时被取消，把已经完整送达的请求记成失败 —— 实测某天魔搭被误报 80 条，
而每条都有完整输出。

现在改用语义结束标记判定成败：finish_reason 非空 / 带 usage 的收尾块 / [DONE]，
收到任一即算成功，不再依赖「上游是否把 TCP 流关干净」。真·中断（用户点停止 / 客户端等不及，
没拿到结束标记）仍单独识别，不计入失败。

统计页的「失败请求」与成功率随之修正；请求日志里中断显示为灰色「已中断」。

模型探测

• 探测与手动测试现在会校验响应体：HTTP 200 但内容是错误对象、或没有 choices 的，
  不再被标成「可用」。
• 单个模型返回 401/403 不再停用整个渠道（如 HuggingFace 的 139 个模型）——
  只有「该渠道最近没成功过」才判定为 Key / 账号级问题。

改进

• 稳定分只统计真实调用（近 10 次窗口 + 启动时用历史回填）
• 429 细分为四档：余额不足（→ 不可用）/ 免费额度用尽（冷却到次日）/ 每分钟限流 / 未知
• 地域封锁不再误标为「不可用」
• 手动测试绕过渠道冷却，测试成功即恢复渠道
• 视觉能力标记改用平台数据（111 → 359 个模型）
• 测试数据文件全局隔离（此前跑 pytest 会覆盖本地 data/）

下载

Windows 绿色版 free-api-hub-v1.0.5-win64.zip，解压即用，双击 API Hub.vbs 启动托盘。

升级提示：解压到新目录即可，config.json 与 data/ 会保留在原处。

v1.0.4

核心修复

• 「重启后前端 404」根因修复：启动改为「先抢监听端口（SO_REUSEADDR 绕过 TIME_WAIT + 先探测有无活跃监听者），再把 socket 交给 uvicorn.Server(...).run(sockets=[sock])」——删掉了旧版在 uvicorn.run() 外面重试的做法（每次重试都会重跑一遍 lifespan，aclose() 掉共享 client，导致全渠道报 client has been closed、界面像「所有渠道都连不上」）。单实例锁去掉 SO_REUSEADDR（Windows 上它会让锁失效）。
• 托盘左键恢复：单击图标唤出窗口（default 项，不占右键菜单）；X 关闭即隐藏窗口，退出走右键菜单。

新增

• 视觉分组 auto:vision：只挑「能看图」的模型，再按能力优先 + 稳定/速度均衡排序。Hermes 的「辅助视觉模型」直接填它即可——某个视觉模型限流/冷却时自动换下一个能看图的，不会再卡死。
  • 视觉能力改由 OpenRouter /models 的 architecture.input_modalities 判定（平台数据优先、名字启发式兜底，与 AA 榜分同一次请求白拿）。实测 750 个渠道模型：视觉标记 111 → 359（补上 Qwen3.5/3.6/3.8 全系、claude-opus-4.5/haiku-4.5/fable-5、amazon nova 全系、GLM-5.3-Flash、MiniMax-M3、kimi-k2.5…），并纠正 6 个 TTS/音频模型的误标。
• 「模型」页视图：均衡 / 智能优先 / 稳定优先 / 速度优先 / 视觉。视图只决定列表排序、不切换路由策略；视图名与客户端模型名一一对应（auto:balanced / auto:quality / auto:stability / auto:speed / auto:vision），所以列表顺序 = 该策略的实际切换顺序。选择记录在本地，刷新后保持。
• 设置项「健康检查间隔」：10 分钟 ~ 6 小时可选，保存即生效（不必再改 config.json）。

改进

• 能力档位：改为「AA（Artificial Analysis）榜分优先 + 启发式兜底」，同代只认最新次版本给「智能」；model_tiers 正则覆盖现在同时影响档位标签与排序分（覆盖 → 该档顶值）。
• 排序：改为「主维度优先 + 容忍带宽（差在带内算同等），同档再按另两维加权」；能力维度升级为连续 AA 分；稳定分加入样本量置信度；速度维度改用首字节时间 TTFT；渠道评分持久化、跨重启累计。
• 路由：/v1/models 补上「可用优先」，与界面排序、候选切换顺序三处同口径——auto 是按这个顺序逐个试的，受限/不可用的不该排在前面。
• 界面：特点列收窄（渠道名短写、档位与 AA 分合并成一个 chip、视觉用 👁、可用/受限计数直接写在开关上），实测 100 行全部单行不换行；「网关用法」页去硬编码、示例更通用。
• 移除以做简化：裸 auto 别名（与 auto:balanced 重复，客户端请改用 auto:balanced）；设置页的「路由策略 / 模型主动探测 / 429 预判」开关（后两者默认开启，路由策略由模型名决定，界面开关只会误导）。

测试

pytest 52 passed：托盘菜单语义 + 端口预绑定回归、档位与策略带宽口径、AA 榜分定档、视觉判定（平台数据双向覆盖启发式）、样本量打折、TTFT 优先、/v1/models 可用优先、设置接口校验。

v1.0.3

核心修复

— 可用性语义 + 故障切换 + 账户级限额 + 用法页通用化

• 模型可用性语义： 由 唯一决定（只有 ok 可路由），修复「limited（限流）冒充可用」导致重启后 300+ 个假绿模型。持久化归正旧数据。
• 故障切换优化：读超时 300s→120s（上游挂起从 5 分钟→2 分钟就切换）；connect 超时 8s；connect 失败更激进降权（0.5 衰减）。
• 魔搭账户级限额：当天免费调用次数用完（daily 型 429）→ 整个渠道冷却到明天，不再只标单个模型。
• 统计页：柱状图显示数值标签 + 最小高度 12px；请求日志按钮「加载中…」+ 完成后 toast；打开统计页每 3 秒自动轮询日志，新记录自动出现。

网关用法页通用化

• curl 示例 Authorization 头从 修正为
• 示例模型名从 改为 （网关自动选最优 + 失败无感切换），并注释「或换成 models 列表里任意模型名」
• 自动切换规则文案通用化：冷却时长改不写死「120 秒」，改为「按错误类型：连接失败短、限流/当天额度用完等冷却到明」
• 补 auto/auto:quality/auto:speed/auto:stability 用法说明

基础设施（第一轮累积）

• throttle 429 自学水位落盘 + 恢复 seed 保守冷却
• channel_down 即时落盘 + 原子写 + 托盘优雅退出 + 单实例锁
• OpenRouter 模型 ID 命名变更的确定等价迁移
• 扫描单 worker 串行 + 按渠道限速（避免打爆免费档 RPM）

验证

• 测试 35 passed（含账户级限额→渠道冷却用例）
• JS 语法通过；所有 .py 保持 LF。

下载

• Windows 绿色版（推荐）：（GitHub 自动生成）
• 源码 + 手动运行指南：直接 clone 本仓库

升级建议

1. 彻底重启托盘（确保 120s 读超时生效）
2. 检查「网关用法」标签页，确认你的工具配置用的是 或正确 token

v1.0.2

#— 修复模型可用性语义 + 故障切换优化

核心修复

• 模型可用性语义修正：available 字段改由 state 唯一决定（只有 ok 可路由）。旧逻辑把 limited（限流）也标成可用，导致 273 个「余额不足/限流」的模型在界面全显示绿色「可用」，一用就报错，重启后原样恢复。
• 统一「永久不可用」判定：新增 is_permanent_failure()，把「余额不足 / 402 / 403 / 404 / 405」归为 down（等也不会自愈），区别于「暂时受限」（每分钟限流 / 5xx / 连接失败）。
• 启动时归正旧数据：restore_model_status() 启动时把历史脏数据（永久型 limited 冒充可用）一次性归正为正确状态并回写磁盘，无需手动清库。

故障切换优化

• Connect 失败更激进降权（0.5 衰减，原 0.8）：受限/挂起的渠道（如魔搭账号级限流）会快速沉底，不再霸占候选第一名。
• Connect 超时 15s → 8s：渠道连不上时更快切换到下一个可用渠道。

其他（累积）

• throttle 429 自学水位持久化 + 恢复 seed 保守冷却
• channel_down 即时落盘 + 原子写 + 托盘优雅退出 + 单实例锁
• OpenRouter 模型 ID 命名变更的确定等价迁移
• 扫描单 worker 串行 + 按渠道限速（避免打爆免费档 RPM）

测试

34 passed（全部离线，不打外部 API）。

v1.0.1

docs: README 措辞完善（求 star、收藏优先、平台说明）；chore: gitignore 排除本地构建 venv

v1.0.0

首个正式版本。

功能

• OpenAI 兼容聚合网关：/v1/models、/v1/chat/completions（含流式）、/v1/embeddings
• 多渠道聚合路由：均衡/智能优先/稳定优先/速度优先四种加权策略，失败自动跨渠道、跨模型切换
• auto 系列特殊模型名：客户端选 auto 即由网关按策略实时挑选最优可用模型
• 429 限流自学水位预判、分类冷却（429 尊重 Retry-After）
• 模型能力档位启发式：家族×代际门槛 + 自适应前沿（渠道出现新旗舰自动降档老一代）
• 用量统计（SQLite）+ 渠道额度查询 + 请求明细
• 桌面端：pywebview 窗口 + 系统托盘常驻 + 开机静默自启（--silent）
• 平台预设 15 个；密钥 Windows DPAPI 加密，非 Windows 自动降级明文

安装使用：见仓库 README —— 双击 run.bat 装依赖后双击 API Hub.vbs 启动。