flexgate 0.3.0__tar.gz → 0.4.0__tar.gz

{flexgate-0.3.0 → flexgate-0.4.0}/CLAUDE.md

@@ -22,6 +22,7 @@ flexgate service install                    # install + enable + start systemd u
 flexgate service {install|start|stop|restart|reload|status|uninstall}
 flexgate run                                # foreground/debug only
 flexgate check                              # provider connectivity diagnostics
+flexgate status                             # providers, fallback chains, per-key usage, active routes
 
 # Config
 flexgate config {init|show|set|path|edit}
@@ -83,7 +84,8 @@ Claude Code → POST /v1/messages (model="claude-sonnet-4-6")
 | `cli.py` | argparse CLI; service lifecycle commands, foreground `run`/`check`, config/settings/sync commands |
 | `config.py` | Pydantic-like dataclasses (`GatewayConfig`, `ProviderConfig`, `RouteConfig`, `ScheduleEntry`), YAML load/save, `TIER_PATTERNS` regex map |
 | `router.py` | `resolve(config, model)` — schedule-first then default routes, first regex match wins |
-| `proxy.py` | `handle_request()` — httpx async proxy, SSE streaming + JSON pass-through |
+| `proxy.py` | `handle_request()` — httpx async proxy, per-key fallback retry loop, SSE streaming + JSON pass-through |
+| `usage.py` | `flexgate status` usage queries — per-platform adapters (MiniMax coding_plan API, Kimi Code usages API, z.ai quota API, LiteLLM `/key/info`) plus a minimal chat probe fallback |
 | `server.py` | Starlette app creation, `POST /v1/messages` endpoint, `SIGUSR1` lifespan reload |
 | `main.py` | Thin bootstrap: load config → create app → run uvicorn |
 | `service.py` | Authoritative systemd user-service install/start/stop/restart/reload/status and legacy PID migration |
@@ -100,6 +102,8 @@ Claude Code → POST /v1/messages (model="claude-sonnet-4-6")
 - **Regex-first routing**: Routes are regex patterns matched against the `model` field in the request body. First match wins. A catch-all `".*"` pattern at the end handles fallback.
 - **Model resolution & `available_models` fallback**: A route may omit `model`; `router.resolve()` then falls back to the provider's first `available_models` entry, so `model_override` handed to the proxy is always a concrete name. `config._parse_routes` rejects routes that omit `model` on a provider with no `available_models` — so adding a provider without models requires an explicit `model` on every route using it.
 - **Proxy rewrite contract** (`proxy.py`): the upstream request gets the provider's `x-api-key` plus a fixed header set, and the JSON `model` field is rewritten only when the route set an override. Streaming responses are forwarded as raw bytes (`aiter_bytes`), never parsed.
+- **Key fallback** (`proxy.py`): a provider's `api_keys` list holds one or more keys for the same upstream (entries are key strings or `{key, note}` mappings; `note` is a free-form label shown by `flexgate status` and in fallback logs). Multiple accounts on one upstream — e.g. several MiniMax subscriptions — belong in ONE provider, not separate ones. On a retryable failure (HTTP 401/402/403/429/500/502/503/529, connect error, or timeout) the request is retried with the next key in order. Streaming requests can only fall back before the upstream returns 200. `_regular_proxy`/`_stream_proxy` return `(response, retryable)`; `handle_request` owns the loop and returns the last error when all keys fail. The legacy `api_key` + `fallback_keys` schema is still parsed (`config._parse_api_keys`); migration v3 → v4 rewrites it to `api_keys`. `ProviderConfig.api_key` remains as a first-key property (getter/setter) for sync/settings merge code.
+- **Usage inspection** (`usage.py`): `flexgate status` maps `base_url` to a platform adapter (`_ADAPTERS`): MiniMax → `{origin}/v1/api/openplatform/coding_plan/remains` (the `*_usage_count` fields are REMAINING counts, an upstream naming quirk), Kimi Code → `{base}/v1/usages` (undocumented, same endpoint as the CLI's `/usage`; reports weekly quota, 5-hour window and parallel limit), z.ai/bigmodel → `{origin}/api/monitor/usage/quota/limit` (undocumented but used by z.ai's own plugin), USTC/LiteLLM → `{origin}/key/info`. Hosts in `_PROBE_ONLY_MARKERS` (e.g. xiaomimimo.com — no key-based usage API) and unknown platforms get the minimal chat probe: `POST /v1/messages` with input `"hi"`, `max_tokens=128`. A failed adapter call also degrades to the probe.
 - **Multimodal degradation**: `MULTIMODAL_MODELS` (currently `{"MiniMax-M3", "glm-4.6v"}`) is the allowlist. Requests carrying image blocks aimed at any other model have images stripped and a `[flexgate]` text note injected into both the outgoing request and the returned response, so non-multimodal backends don't 4xx.
 - **Schedule-based overrides**: Optional time windows (e.g. 22:00-06:00) override default routes. Overnight wrap is supported.
 - **Service-first lifecycle**: `flexgate.service` is the sole persistent runtime. systemd owns restart, boot startup, logs, and process state.

{flexgate-0.3.0 → flexgate-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: flexgate
-Version: 0.3.0
+Version: 0.4.0
 Summary: Flexible local API gateway for Claude Code — route models to different providers
 Project-URL: Homepage, https://github.com/Agony5757/flexible-gateway
 Project-URL: Repository, https://github.com/Agony5757/flexible-gateway
@@ -154,6 +154,34 @@ Trusted Publisher（repo: `Agony5757/flexible-gateway`，workflow: `release.yml`
 
 可通过 `--verify-timeout N` 调整每个 provider 的超时时间（默认 15 秒）。
 
+### 状态总览与用量查询（`flexgate status` / `flexgate usage`）
+
+```bash
+flexgate status                  # providers + fallback 链 + 每个 key 的用量 + 当前路由
+flexgate status --no-usage       # 跳过用量查询，只看配置
+flexgate status --usage-timeout 30
+flexgate usage                   # 只看每个 key 的用量/额度（不打印配置和路由）
+flexgate usage --usage-timeout 30
+```
+
+`flexgate status` 展示当前配置中的所有 provider、每个 provider 的 key 及
+fallback 链、当前生效的路由，并逐一查询**每个 key** 的用量/额度；
+`flexgate usage` 只输出其中的用量部分。
+
+各平台的用量查询方式差异很大，flexgate 按 `base_url` 自动选择适配器：
+
+| 平台 | 查询方式 | 说明 |
+|------|----------|------|
+| MiniMax（api.minimaxi.com / api.minimax.io） | `GET /v1/api/openplatform/coding_plan/remains`（Bearer 认证，复用 provider key） | 官方 token plan 接口，返回 5 小时窗口和周窗口的**剩余**次数（注意响应里 `*_usage_count` 字段实际是剩余量） |
+| Kimi Code（api.kimi.com） | `GET {base}/v1/usages`（Bearer 认证，复用 provider key） | 未公开文档、与 Kimi Code CLI `/usage` 相同的接口，返回周配额、5 小时滚动窗口剩余量和并发上限 |
+| z.ai / 智谱（api.z.ai / open.bigmodel.cn） | `GET /api/monitor/usage/quota/limit`（Authorization 直接带 key） | 未公开文档、但 z.ai 官方 coding 插件在用的接口，返回各窗口已用百分比与重置时间 |
+| USTC（api.llm.ustc.edu.cn，LiteLLM） | `GET /key/info`（Bearer 认证） | LiteLLM proxy 自带的 key 信息接口，返回 spend / max_budget / 限速等 |
+| 小米 MiMo（token-plan-cn.xiaomimimo.com） | **无 key 可用的官方接口**（控制台内部接口需要浏览器 cookie，不采用） | 退化为 minimal probe |
+| 其他/未知平台 | minimal chat probe | 发一条输入 `"hi"`、`max_tokens=128` 的最小 `/v1/messages` 请求，验证 key 是否还能正常服务（会消耗极少量额度） |
+
+如果某平台的专用接口调用失败，flexgate 会自动退化为 minimal probe 再试一次。
+用量查询接口多为平台内部接口，可能随时变动；查询结果仅供参考。
+
 ### 前台调试与连通性检查
 
 `run` / `check` 是独立的顶层调试命令，不属于持久化服务模式：
@@ -220,7 +248,7 @@ Flexgate config  —  ~/.flexgate/config.yaml
 
 - 方向键选中某个 tier（opus/sonnet/haiku），回车进入：先从候选 **provider** 列表选择，再从该 provider 的候选 **model** 列表选择。
 - model 列表包含：`available_models` 中的各个模型、「使用 provider 默认（首个可用模型，不写死 model）」、以及「自定义模型…」（手动输入）。
-- 按 `s` 保存（并向运行中的网关发送 SIGUSR1 热重载），按 `q` 退出（有未保存改动时会提示保存或放弃）；子菜单中按 `Esc`/`←` 返回上一级。
+- 按 `s` 保存（并向运行中的网关发送 SIGUSR1 热重载，**无需重启即生效**），按 `q` 退出（有未保存改动时会询问 "Config changed — activate now?"：选 Yes 立即保存并热重载生效，选 No 放弃改动）；子菜单中按 `Esc`/`←` 返回上一级。
 - 需要交互式终端（TTY）；非交互场景请改用 `flexgate config set`。
 
 ### Settings 管理
@@ -261,10 +289,16 @@ server:
 providers:
   zai:
     base_url: "https://api.z.ai/api/anthropic"
-    api_key: "your-zai-api-key"
+    api_keys:
+      - "your-zai-api-key"
   minimax:
     base_url: "https://api.minimaxi.com/anthropic"
-    api_key: "your-minimax-api-key"
+    api_keys:                   # 同一上游可配多个 key，互为 fallback
+      - key: "your-minimax-api-key"
+        note: "主账号"          # 可选备注，存在配置里，status/日志中显示
+      - key: "your-minimax-api-key-2"
+        note: "备用账号"
+      - "your-minimax-api-key-3"   # 纯字符串写法（无备注）
 
 claude_settings:
   default_opus_model: "claude-opus-4-7"
@@ -303,7 +337,8 @@ routes:                          # 从上到下匹配，首个命中生效
 |------|------|
 | `server.host/port` | 网关监听地址 |
 | `providers.<name>.base_url` | Provider 的 API 地址 |
-| `providers.<name>.api_key` | Provider 的 API 密钥 |
+| `providers.<name>.api_keys` | API key 列表（一个或多个，互为 fallback）；每项为 key 字符串或 `{key, note}`，`note` 是存在配置里的备注 |
+| `providers.<name>.available_models` | 该 provider 的可用模型列表，首个条目作为路由省略 `model` 时的回退模型 |
 | `claude_settings.*` | 写入 settings.json 的模型和超时配置 |
 | `routes[].pattern` | 正则匹配请求中的 model 字段 |
 | `routes[].provider` | 路由到的 provider 名称 |
@@ -312,6 +347,26 @@ routes:                          # 从上到下匹配，首个命中生效
 | `schedule[].start/end` | 时间窗口（HH:MM 格式，支持跨夜如 22:00-06:00） |
 | `schedule[].routes` | 该时间窗口内生效的路由（格式同 `routes`） |
 
+### Key fallback
+
+同一上游有多个账号/key 时（例如多个 MiniMax 订阅），在 `api_keys` 里配
+多个 key，而不是拆成多个 provider。每项可以是纯 key 字符串，也可以写成
+`{key, note}` 加一个存在配置里的备注（`flexgate status` 和 fallback 日志
+都会显示 note，方便分辨是哪个账号的 key）：
+
+- 请求先走第一个 key；失败时按列表顺序自动重试后续 key，直到某个 key
+  成功或返回不可重试的错误。
+- 触发切换的条件：HTTP **401 / 402 / 403 / 429 / 500 / 502 / 503 / 529**
+  （key 失效、余额/额度耗尽、限流、平台过载）以及连接错误、超时。
+  其他 4xx（如 400 请求格式错误）不会触发切换。
+- 流式请求只有在上游返回非 200 状态码之前才能切换 key；一旦开始吐
+  token，响应已提交，无法再 fallback。
+- 每次切换都会在服务日志中留下记录（key 只显示前后各 4 位）。
+- 用 `flexgate status` 可以查看每个 provider 的 fallback 链和每个 key 的
+  实时用量。
+- 旧版 `api_key` + `fallback_keys` 写法仍然兼容，`flexgate update` 会
+  自动迁移为 `api_keys` 列表（config_version 3 → 4）。
+
 ## Settings Import
 
 `flexgate settings import` 会扫描 `~/.claude/settings.json*`，从每个文件中提取 `ANTHROPIC_BASE_URL` 和 `ANTHROPIC_AUTH_TOKEN`，自动写入 config.yaml 的 providers 部分。

{flexgate-0.3.0 → flexgate-0.4.0}/README.md

@@ -137,6 +137,34 @@ Trusted Publisher（repo: `Agony5757/flexible-gateway`，workflow: `release.yml`
 
 可通过 `--verify-timeout N` 调整每个 provider 的超时时间（默认 15 秒）。
 
+### 状态总览与用量查询（`flexgate status` / `flexgate usage`）
+
+```bash
+flexgate status                  # providers + fallback 链 + 每个 key 的用量 + 当前路由
+flexgate status --no-usage       # 跳过用量查询，只看配置
+flexgate status --usage-timeout 30
+flexgate usage                   # 只看每个 key 的用量/额度（不打印配置和路由）
+flexgate usage --usage-timeout 30
+```
+
+`flexgate status` 展示当前配置中的所有 provider、每个 provider 的 key 及
+fallback 链、当前生效的路由，并逐一查询**每个 key** 的用量/额度；
+`flexgate usage` 只输出其中的用量部分。
+
+各平台的用量查询方式差异很大，flexgate 按 `base_url` 自动选择适配器：
+
+| 平台 | 查询方式 | 说明 |
+|------|----------|------|
+| MiniMax（api.minimaxi.com / api.minimax.io） | `GET /v1/api/openplatform/coding_plan/remains`（Bearer 认证，复用 provider key） | 官方 token plan 接口，返回 5 小时窗口和周窗口的**剩余**次数（注意响应里 `*_usage_count` 字段实际是剩余量） |
+| Kimi Code（api.kimi.com） | `GET {base}/v1/usages`（Bearer 认证，复用 provider key） | 未公开文档、与 Kimi Code CLI `/usage` 相同的接口，返回周配额、5 小时滚动窗口剩余量和并发上限 |
+| z.ai / 智谱（api.z.ai / open.bigmodel.cn） | `GET /api/monitor/usage/quota/limit`（Authorization 直接带 key） | 未公开文档、但 z.ai 官方 coding 插件在用的接口，返回各窗口已用百分比与重置时间 |
+| USTC（api.llm.ustc.edu.cn，LiteLLM） | `GET /key/info`（Bearer 认证） | LiteLLM proxy 自带的 key 信息接口，返回 spend / max_budget / 限速等 |
+| 小米 MiMo（token-plan-cn.xiaomimimo.com） | **无 key 可用的官方接口**（控制台内部接口需要浏览器 cookie，不采用） | 退化为 minimal probe |
+| 其他/未知平台 | minimal chat probe | 发一条输入 `"hi"`、`max_tokens=128` 的最小 `/v1/messages` 请求，验证 key 是否还能正常服务（会消耗极少量额度） |
+
+如果某平台的专用接口调用失败，flexgate 会自动退化为 minimal probe 再试一次。
+用量查询接口多为平台内部接口，可能随时变动；查询结果仅供参考。
+
 ### 前台调试与连通性检查
 
 `run` / `check` 是独立的顶层调试命令，不属于持久化服务模式：
@@ -203,7 +231,7 @@ Flexgate config  —  ~/.flexgate/config.yaml
 
 - 方向键选中某个 tier（opus/sonnet/haiku），回车进入：先从候选 **provider** 列表选择，再从该 provider 的候选 **model** 列表选择。
 - model 列表包含：`available_models` 中的各个模型、「使用 provider 默认（首个可用模型，不写死 model）」、以及「自定义模型…」（手动输入）。
-- 按 `s` 保存（并向运行中的网关发送 SIGUSR1 热重载），按 `q` 退出（有未保存改动时会提示保存或放弃）；子菜单中按 `Esc`/`←` 返回上一级。
+- 按 `s` 保存（并向运行中的网关发送 SIGUSR1 热重载，**无需重启即生效**），按 `q` 退出（有未保存改动时会询问 "Config changed — activate now?"：选 Yes 立即保存并热重载生效，选 No 放弃改动）；子菜单中按 `Esc`/`←` 返回上一级。
 - 需要交互式终端（TTY）；非交互场景请改用 `flexgate config set`。
 
 ### Settings 管理
@@ -244,10 +272,16 @@ server:
 providers:
   zai:
     base_url: "https://api.z.ai/api/anthropic"
-    api_key: "your-zai-api-key"
+    api_keys:
+      - "your-zai-api-key"
   minimax:
     base_url: "https://api.minimaxi.com/anthropic"
-    api_key: "your-minimax-api-key"
+    api_keys:                   # 同一上游可配多个 key，互为 fallback
+      - key: "your-minimax-api-key"
+        note: "主账号"          # 可选备注，存在配置里，status/日志中显示
+      - key: "your-minimax-api-key-2"
+        note: "备用账号"
+      - "your-minimax-api-key-3"   # 纯字符串写法（无备注）
 
 claude_settings:
   default_opus_model: "claude-opus-4-7"
@@ -286,7 +320,8 @@ routes:                          # 从上到下匹配，首个命中生效
 |------|------|
 | `server.host/port` | 网关监听地址 |
 | `providers.<name>.base_url` | Provider 的 API 地址 |
-| `providers.<name>.api_key` | Provider 的 API 密钥 |
+| `providers.<name>.api_keys` | API key 列表（一个或多个，互为 fallback）；每项为 key 字符串或 `{key, note}`，`note` 是存在配置里的备注 |
+| `providers.<name>.available_models` | 该 provider 的可用模型列表，首个条目作为路由省略 `model` 时的回退模型 |
 | `claude_settings.*` | 写入 settings.json 的模型和超时配置 |
 | `routes[].pattern` | 正则匹配请求中的 model 字段 |
 | `routes[].provider` | 路由到的 provider 名称 |
@@ -295,6 +330,26 @@ routes:                          # 从上到下匹配，首个命中生效
 | `schedule[].start/end` | 时间窗口（HH:MM 格式，支持跨夜如 22:00-06:00） |
 | `schedule[].routes` | 该时间窗口内生效的路由（格式同 `routes`） |
 
+### Key fallback
+
+同一上游有多个账号/key 时（例如多个 MiniMax 订阅），在 `api_keys` 里配
+多个 key，而不是拆成多个 provider。每项可以是纯 key 字符串，也可以写成
+`{key, note}` 加一个存在配置里的备注（`flexgate status` 和 fallback 日志
+都会显示 note，方便分辨是哪个账号的 key）：
+
+- 请求先走第一个 key；失败时按列表顺序自动重试后续 key，直到某个 key
+  成功或返回不可重试的错误。
+- 触发切换的条件：HTTP **401 / 402 / 403 / 429 / 500 / 502 / 503 / 529**
+  （key 失效、余额/额度耗尽、限流、平台过载）以及连接错误、超时。
+  其他 4xx（如 400 请求格式错误）不会触发切换。
+- 流式请求只有在上游返回非 200 状态码之前才能切换 key；一旦开始吐
+  token，响应已提交，无法再 fallback。
+- 每次切换都会在服务日志中留下记录（key 只显示前后各 4 位）。
+- 用 `flexgate status` 可以查看每个 provider 的 fallback 链和每个 key 的
+  实时用量。
+- 旧版 `api_key` + `fallback_keys` 写法仍然兼容，`flexgate update` 会
+  自动迁移为 `api_keys` 列表（config_version 3 → 4）。
+
 ## Settings Import
 
 `flexgate settings import` 会扫描 `~/.claude/settings.json*`，从每个文件中提取 `ANTHROPIC_BASE_URL` 和 `ANTHROPIC_AUTH_TOKEN`，自动写入 config.yaml 的 providers 部分。

{flexgate-0.3.0 → flexgate-0.4.0}/config.yaml.template

@@ -3,37 +3,39 @@ server:
   port: 8765
 
 # 每个 provider 必须声明 available_models，首个条目作为路由省略 model 时的回退模型。
-# 同一上游的多个账号可配置为多个 provider（如下面的 minimax-tmy / minimax-ywj）。
+# api_keys：同一上游的一个或多个 API key。每项可以是纯 key 字符串，也可以
+# 写成 {key, note}，note 是存在配置里的备注（flexgate status 和 fallback
+# 日志都会显示）。某个 key 遇到 401/402/403/429/5xx/529 或连接错误（如额度
+# 用尽、平台过载）时，按顺序自动切换到下一个 key 重试。同一上游的多个账号
+# 应这样配置，而不是拆成多个 provider。
 providers:
   minimax:
     base_url: "https://api.minimaxi.com/anthropic"
-    api_key: "your-minimax-api-key"
-    available_models:
-      - "MiniMax-M3"
-  minimax-tmy:
-    base_url: "https://api.minimaxi.com/anthropic"
-    api_key: "your-minimax-tmy-api-key"
-    available_models:
-      - "MiniMax-M3"
-  minimax-ywj:
-    base_url: "https://api.minimaxi.com/anthropic"
-    api_key: "your-minimax-ywj-api-key"
+    api_keys:
+      - key: "your-minimax-api-key"
+        note: "主账号"
+      - key: "your-minimax-api-key-2"
+        note: "备用账号"
+      - "your-minimax-api-key-3"   # 纯字符串写法（无备注）
     available_models:
       - "MiniMax-M3"
   zai:
     base_url: "https://api.z.ai/api/anthropic"
-    api_key: "your-zai-api-key"
+    api_keys:
+      - "your-zai-api-key"
     available_models:
       - "glm-5.3"      # 路由省略 model 时的回退模型
       - "glm-4.6v"
   xiaomi:
     base_url: "https://token-plan-cn.xiaomimimo.com/anthropic"
-    api_key: "your-xiaomi-api-key"
+    api_keys:
+      - "your-xiaomi-api-key"
     available_models:
       - "mimo-v2.5-pro"
   ustc:
     base_url: "https://api.llm.ustc.edu.cn"
-    api_key: "your-ustc-api-key"
+    api_keys:
+      - "your-ustc-api-key"
     available_models:
       - "deepseek-v4-pro"
 

{flexgate-0.3.0 → flexgate-0.4.0}/flexgate/__init__.py

@@ -1,3 +1,3 @@
 """Flexgate — Flexible API Gateway for Claude Code."""
 
-__version__ = "0.3.0"
+__version__ = "0.4.0"

{flexgate-0.3.0 → flexgate-0.4.0}/flexgate/cli.py

@@ -85,6 +85,73 @@ def cmd_check(args: argparse.Namespace) -> None:
     print(f"\nAll {len(results)} target(s) OK.")
 
 
+# ── status (providers / fallback / usage / routes) ─────────────────
+
+def cmd_status(args: argparse.Namespace) -> None:
+    config_path = args.config
+    if not os.path.exists(config_path):
+        print(f"Config not found: {config_path}")
+        print("Run 'flexgate config init' to create one.")
+        sys.exit(1)
+
+    config = load_config(config_path)
+
+    print(f"flexgate {__version__}")
+    print(f"Config: {os.path.abspath(config_path)}")
+    print(f"Server: {config.server.host}:{config.server.port}")
+
+    print(f"\nProviders:")
+    for name, prov in config.providers.items():
+        keys = prov.api_keys
+        key_info = f"key: {_mask_key(keys[0].key)}"
+        if keys[0].note:
+            key_info += f" [{keys[0].note}]"
+        if len(keys) > 1:
+            key_info += f"  (+{len(keys) - 1} fallback key(s))"
+        models = ", ".join(prov.available_models) if prov.available_models else "(no models listed)"
+        print(f"  {name:16s} {prov.base_url}")
+        print(f"  {'':16s} {key_info}")
+        print(f"  {'':16s} models: {models}")
+        if len(keys) > 1:
+            chain = " → ".join(
+                f"#{i + 1} {_mask_key(k.key)}" + (f"[{k.note}]" if k.note else "")
+                for i, k in enumerate(keys)
+            )
+            print(f"  {'':16s} fallback: {chain}")
+
+    _print_active_routes(config)
+
+    if getattr(args, "no_usage", False):
+        return
+
+    _print_usage(config, getattr(args, "usage_timeout", 15.0))
+
+
+def cmd_usage(args: argparse.Namespace) -> None:
+    config_path = args.config
+    if not os.path.exists(config_path):
+        print(f"Config not found: {config_path}")
+        print("Run 'flexgate config init' to create one.")
+        sys.exit(1)
+
+    config = load_config(config_path)
+    _print_usage(config, getattr(args, "usage_timeout", 15.0))
+
+
+def _print_usage(config, timeout: float) -> None:
+    from flexgate.usage import run_usage_check
+
+    print(f"\nUsage (timeout {timeout:g}s per key):")
+    usage = run_usage_check(config, timeout=timeout)
+    for name, results in usage.items():
+        print(f"  {name}:")
+        for r in results:
+            marker = "✓" if r.ok else "✗"
+            print(f"    {marker} {r.key_label}  [{r.method}]")
+            for line in r.lines:
+                print(f"        {line}")
+
+
 # ── settings subcommands ────────────────────────────────────────────
 
 def cmd_settings_import(args: argparse.Namespace) -> None:
@@ -197,7 +264,10 @@ def cmd_config_show(args: argparse.Namespace) -> None:
 
     print(f"\nProviders:")
     for name, prov in config.providers.items():
-        print(f"  {name:16s} {prov.base_url}  (key: {_mask_key(prov.api_key)})")
+        print(f"  {name:16s} {prov.base_url}")
+        for i, k in enumerate(prov.api_keys):
+            note = f"  [{k.note}]" if k.note else ""
+            print(f"  {'':16s} key #{i + 1}: {_mask_key(k.key)}{note}")
 
     print(f"\nRoutes (default):")
     _print_route_table(config.routes)
@@ -448,12 +518,12 @@ def _text_input(stdscr, prompt: str) -> str | None:
     return text or None
 
 
-def _confirm(stdscr, question: str):
+def _confirm(stdscr, question: str, yes_label: str = "Yes, save changes", no_label: str = "No, discard changes"):
     """Yes/No prompt. Returns True, False, or None (cancel)."""
     sel = _menu_select(
         stdscr,
         [question, ""],
-        [("Yes, save changes", True), ("No, discard changes", False)],
+        [(yes_label, True), (no_label, False)],
         index=0,
     )
     return None if sel is _CANCEL else sel
@@ -583,7 +653,12 @@ def _edit_loop(stdscr, config: GatewayConfig, config_path: str):
                 status = "No changes to save"
         elif key in (ord("q"), 27):
             if dirty:
-                ans = _confirm(stdscr, "Unsaved changes — save before quitting?")
+                ans = _confirm(
+                    stdscr,
+                    "Config changed — activate now?",
+                    yes_label="Yes, activate now (hot-reload, no restart)",
+                    no_label="No, discard changes",
+                )
                 if ans is True:
                     save_config(config, config_path)
                     reload_msg = _signal_reload(config_path)
@@ -822,6 +897,29 @@ def main() -> None:
         help="Per-provider connectivity check timeout in seconds (default: 15.0)"
     )
 
+    # flexgate status ...
+    status_p = sub.add_parser(
+        "status",
+        help="Show providers, fallback chains, usage/quota and active routes",
+    )
+    status_p.add_argument(
+        "--no-usage", action="store_true",
+        help="Skip the per-key usage/quota queries"
+    )
+    status_p.add_argument(
+        "--usage-timeout", type=float, default=15.0,
+        help="Per-key usage query timeout in seconds (default: 15.0)"
+    )
+
+    usage_p = sub.add_parser(
+        "usage",
+        help="Show per-key usage/quota for all configured providers",
+    )
+    usage_p.add_argument(
+        "--usage-timeout", type=float, default=15.0,
+        help="Per-key usage query timeout in seconds (default: 15.0)"
+    )
+
     # flexgate settings ...
     st = sub.add_parser("settings", help="Manage Claude Code settings")
     st_sub = st.add_subparsers(dest="command")
@@ -888,6 +986,12 @@ def main() -> None:
     elif args.group == "check":
         cmd_check(args)
 
+    elif args.group == "status":
+        cmd_status(args)
+
+    elif args.group == "usage":
+        cmd_usage(args)
+
     elif args.group == "settings":
         handlers = {
             "import": cmd_settings_import,

{flexgate-0.3.0 → flexgate-0.4.0}/flexgate/config.py

@@ -21,17 +21,36 @@ def ensure_home_dir() -> None:
     os.makedirs(FLEXGATE_HOME, exist_ok=True)
 
 
+@dataclass
+class ApiKey:
+    """One API key for a provider, with an optional human-readable note."""
+    key: str
+    note: str = ""
+
+
 @dataclass
 class ProviderConfig:
     name: str
     base_url: str
-    api_key: str
+    api_keys: list[ApiKey] = field(default_factory=list)
     available_models: list[str] = field(default_factory=list)
 
     @property
     def default_model(self) -> str | None:
         return self.available_models[0] if self.available_models else None
 
+    @property
+    def api_key(self) -> str:
+        """The primary key (first of api_keys); later keys are fallbacks."""
+        return self.api_keys[0].key if self.api_keys else ""
+
+    @api_key.setter
+    def api_key(self, value: str) -> None:
+        if self.api_keys:
+            self.api_keys[0].key = value
+        else:
+            self.api_keys.append(ApiKey(key=value))
+
 
 @dataclass
 class RouteConfig:
@@ -82,6 +101,33 @@ def _parse_hhmm(value: str) -> int:
     return h * 60 + m
 
 
+def _parse_api_keys(name: str, prov: dict) -> list[ApiKey]:
+    """Parse a provider's key list.
+
+    Current schema: ``api_keys`` — a list whose entries are either a plain
+    key string or a mapping ``{key: ..., note: ...}``. The legacy schema
+    (``api_key`` plus optional ``fallback_keys``) is still accepted.
+    """
+    raw = prov.get("api_keys")
+    if raw is None:
+        raw = [prov["api_key"]]
+        raw.extend(prov.get("fallback_keys", []) or [])
+    if not isinstance(raw, list) or not raw:
+        raise ValueError(f"Provider '{name}': 'api_keys' must be a non-empty list")
+    keys: list[ApiKey] = []
+    for item in raw:
+        if isinstance(item, str):
+            keys.append(ApiKey(key=item))
+        elif isinstance(item, dict) and isinstance(item.get("key"), str):
+            keys.append(ApiKey(key=item["key"], note=str(item.get("note") or "")))
+        else:
+            raise ValueError(
+                f"Provider '{name}': each api_keys entry must be a key string "
+                f"or a mapping with 'key' (and optional 'note')"
+            )
+    return keys
+
+
 def _parse_routes(raw_routes: list[dict], providers: dict[str, ProviderConfig]) -> list[RouteConfig]:
     routes: list[RouteConfig] = []
     for r in raw_routes:
@@ -145,7 +191,7 @@ def load_config(path: str | None = None) -> GatewayConfig:
         cfg.providers[name] = ProviderConfig(
             name=name,
             base_url=prov["base_url"].rstrip("/"),
-            api_key=prov["api_key"],
+            api_keys=_parse_api_keys(name, prov),
             available_models=[str(m) for m in available],
         )
 
@@ -210,7 +256,10 @@ def save_config(cfg: GatewayConfig, path: str | None = None) -> None:
     for name, prov in cfg.providers.items():
         entry: dict = {
             "base_url": prov.base_url,
-            "api_key": prov.api_key,
+            "api_keys": [
+                {"key": k.key, "note": k.note} if k.note else k.key
+                for k in prov.api_keys
+            ],
         }
         if prov.available_models:
             entry["available_models"] = list(prov.available_models)
@@ -244,38 +293,42 @@ server:
 
 # Each provider must declare `available_models`. The first entry is used as the
 # fallback model whenever a route below omits its own `model:` field.
-# Multiple accounts on the same upstream can be configured as separate
-# providers (e.g. minimax-tmy / minimax-ywj below).
+#
+# `api_keys`: one or more API keys for the SAME upstream; each entry is either
+# a plain key string or {key, note} where `note` is a free-form label stored
+# in the config (shown by `flexgate status`, included in fallback logs).
+# When a key fails with a retryable error (401/402/403/429/5xx/529 or a
+# connection error — e.g. quota exhausted or provider overloaded), the request
+# is retried with the next key in order. Multiple accounts on the same
+# upstream should be configured this way instead of as separate providers.
 providers:
   minimax:
     base_url: "https://api.minimaxi.com/anthropic"
-    api_key: "your-minimax-api-key"
-    available_models:
-      - "MiniMax-M3"
-  minimax-tmy:
-    base_url: "https://api.minimaxi.com/anthropic"
-    api_key: "your-minimax-tmy-api-key"
-    available_models:
-      - "MiniMax-M3"
-  minimax-ywj:
-    base_url: "https://api.minimaxi.com/anthropic"
-    api_key: "your-minimax-ywj-api-key"
+    api_keys:
+      - key: "your-minimax-api-key"
+        note: "main account"
+      - key: "your-minimax-api-key-2"
+        note: "backup account"
+      - "your-minimax-api-key-3"   # plain string entry (no note)
     available_models:
       - "MiniMax-M3"
   zai:
     base_url: "https://api.z.ai/api/anthropic"
-    api_key: "your-zai-api-key"
+    api_keys:
+      - "your-zai-api-key"
     available_models:
       - "glm-5.3"      # used as fallback when a route omits `model`
       - "glm-4.6v"
   xiaomi:
     base_url: "https://token-plan-cn.xiaomimimo.com/anthropic"
-    api_key: "your-xiaomi-api-key"
+    api_keys:
+      - "your-xiaomi-api-key"
     available_models:
       - "mimo-v2.5-pro"
   ustc:
     base_url: "https://api.llm.ustc.edu.cn"
-    api_key: "your-ustc-api-key"
+    api_keys:
+      - "your-ustc-api-key"
     available_models:
       - "deepseek-v4-pro"
 

{flexgate-0.3.0 → flexgate-0.4.0}/flexgate/doctor.py

@@ -104,7 +104,10 @@ def _check_providers(config, findings: list[Finding]) -> None:
         findings.append(Finding(FAIL, "Providers", "none configured"))
         return
 
-    placeholders = [name for name, p in config.providers.items() if _is_placeholder_key(p.api_key)]
+    placeholders = [
+        name for name, p in config.providers.items()
+        if all(_is_placeholder_key(k.key) for k in p.api_keys)
+    ]
     if placeholders:
         findings.append(Finding(WARN, "Provider keys",
                                 f"placeholder api_key in: {', '.join(placeholders)}"))