flexgate 0.3.0__tar.gz → 0.4.1__tar.gz

flexgate-0.4.1/.github/workflows/docs.yml

@@ -0,0 +1,67 @@
+name: docs
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'docs/**'
+      - 'flexgate/__init__.py'
+      - '.github/workflows/docs.yml'
+    tags:
+      - 'v*'
+  pull_request:
+    branches: [main]
+    paths:
+      - 'docs/**'
+      - '.github/workflows/docs.yml'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  build-docs:
+    name: Build Documentation
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd  # v5.0.1
+
+      - name: Set up Python
+        uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405  # v6.2.0
+        with:
+          python-version: '3.12'
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -r docs/requirements.txt
+          pip install .
+
+      - name: Build docs
+        run: |
+          cd docs
+          make html
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@56afc609e74202658d3ffba0e8f6dda462b719fa  # v3.0.1
+        with:
+          path: docs/_build/html
+
+  deploy-docs:
+    name: Deploy to GitHub Pages
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build-docs
+    if: github.ref == 'refs/heads/main' || github.ref_type == 'tag'
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@d6db90164ac5ed86f2b6aed7e0febac5b3c0c03e  # v4.0.5

{flexgate-0.3.0 → flexgate-0.4.1}/.gitignore

@@ -6,3 +6,6 @@ config.yaml
 .github/copilot-instructions.md
 dist/
 .venv/
+
+# Sphinx build artifacts
+docs/_build/

{flexgate-0.3.0 → flexgate-0.4.1}/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 |
@@ -93,13 +95,15 @@ Claude Code → POST /v1/messages (model="claude-sonnet-4-6")
 | `sync.py` | `flexgate sync` — pushes/pulls the whole config.yaml as an encrypted document on a confsync server (lazily imports the `confsync` client package) |
 | `migrate.py` | Config schema versioning: `config_version` marker, per-step `MIGRATIONS` chain (N → N+1), backup + atomic rewrite |
 | `doctor.py` | `flexgate doctor` — read-only diagnostics (Python, PyPI update, config schema/semantics, port, systemd, Claude settings) |
-| `update.py` | `flexgate update` — PyPI version check, package upgrade via detected installer (pipx/uv/pip), config migration, service reload; also the cached (24h) new-version notice shown by bare `flexgate` / `service status` |
+| `update.py` | `flexgate update` — PyPI version check, package upgrade via detected installer (pipx/uv/pip), config migration, service reload; after a successful package upgrade the config migration is re-run in a fresh process so it uses the new code's schema version (`FLEXGATE_UPDATE_DELEGATED` guards against re-delegation); also the cached (24h) new-version notice shown by bare `flexgate` / `service status` |
 
 ### Key design points
 
 - **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.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: flexgate
-Version: 0.3.0
+Version: 0.4.1
 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
@@ -17,8 +17,13 @@ Description-Content-Type: text/markdown
 
 # Flexgate
 
+[![PyPI](https://img.shields.io/pypi/v/flexgate)](https://pypi.org/project/flexgate/)
+[![Docs](https://img.shields.io/badge/docs-GitHub%20Pages-blue)](https://agony5757.github.io/flexible-gateway/)
+
 本地 Anthropic API 网关，根据请求中的 model 名称自动路由到不同的 provider。同时提供 Claude Code settings.json 的自动管理功能。
 
+完整文档见 **[agony5757.github.io/flexible-gateway](https://agony5757.github.io/flexible-gateway/)**（Sphinx 构建，源文件在 `docs/`，随 main 分支自动发布）。
+
 ## 用途
 
 Claude Code 只能配置一个 `ANTHROPIC_BASE_URL`，所有 tier（opus/sonnet/haiku）都指向同一个 provider。Flexgate 在本地启动一个 Anthropic 兼容端点，按 model 名称路由到不同 provider。
@@ -154,6 +159,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 +253,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 +294,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 +342,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 +352,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.1}/README.md

@@ -1,7 +1,12 @@
 # Flexgate
 
+[![PyPI](https://img.shields.io/pypi/v/flexgate)](https://pypi.org/project/flexgate/)
+[![Docs](https://img.shields.io/badge/docs-GitHub%20Pages-blue)](https://agony5757.github.io/flexible-gateway/)
+
 本地 Anthropic API 网关，根据请求中的 model 名称自动路由到不同的 provider。同时提供 Claude Code settings.json 的自动管理功能。
 
+完整文档见 **[agony5757.github.io/flexible-gateway](https://agony5757.github.io/flexible-gateway/)**（Sphinx 构建，源文件在 `docs/`，随 main 分支自动发布）。
+
 ## 用途
 
 Claude Code 只能配置一个 `ANTHROPIC_BASE_URL`，所有 tier（opus/sonnet/haiku）都指向同一个 provider。Flexgate 在本地启动一个 Anthropic 兼容端点，按 model 名称路由到不同 provider。
@@ -137,6 +142,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 +236,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 +277,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 +325,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 +335,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.1}/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.4.1/docs/Makefile

@@ -0,0 +1,14 @@
+# Minimal makefile for Sphinx documentation
+
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

flexgate-0.4.1/docs/cli.md

@@ -0,0 +1,229 @@
+# 命令参考
+
+```text
+usage: flexgate [-h] [--config CONFIG] [--version]
+                {service,run,check,status,usage,settings,sync,help,doctor,update,config} ...
+```
+
+全局参数：
+
+- `--config PATH` 指定配置文件（默认 `~/.flexgate/config.yaml`）
+- `--port PORT` 覆盖配置文件中的端口（仅 `flexgate run`）
+- `--version` 打印版本号（`service status` / 裸 `flexgate` 也会显示）
+
+## 服务管理（默认持久化模式）
+
+systemd **用户服务**是 Linux 上唯一推荐的持久化运行方式，负责开机/登录
+自启、崩溃重启、日志和进程生命周期。
+
+```bash
+flexgate service install             # 安装、启用并立即启动
+flexgate service install --no-start  # 仅安装并启用，不立即启动
+flexgate service start               # 启动；自动修复旧格式或失效的 unit
+flexgate service stop                # 停止
+flexgate service restart             # 重启
+flexgate service reload              # 热重载；host/port 变化时自动安全重启
+flexgate service status              # 查看 systemd 状态和当前路由表
+flexgate service uninstall           # 停止、禁用并删除 unit
+```
+
+说明：
+
+- unit 写入 `~/.config/systemd/user/flexgate.service`，直接运行前台
+  server，由 systemd 监督（`Type=simple`、`Restart=on-failure`）。
+- `install` 会执行 `loginctl enable-linger`，使服务在未登录时仍保持运行
+  并随开机启动。
+- `install --no-start` 不会修改 Claude Code settings，避免把客户端指向
+  尚未运行的 endpoint。
+- unit 只能引用持久化配置路径；为避免重启后失效，`/tmp` 下的配置会被拒绝。
+- `start`/`restart` 会清理旧 PID/guardian 残留、修复旧 unit 或已失效的
+  配置路径，并在端口被其他进程占用时拒绝启动。
+- 若升级时检测到旧版后台 gateway 仍在运行，会先准备好 systemd unit，但
+  不会强杀正在服务的进程；按提示手动 `kill <PID>` 停掉旧进程，再执行
+  `flexgate service start` 完成切换。
+- unit 设置了启动速率限制，永久配置错误不会再无限快速重启。
+- `service reload` 和 `config set/edit` 会在仅路由变化时发送 SIGUSR1；
+  如果 endpoint 变化，则先检查再 restart。若只改 host、仍复用当前 port，
+  为避免误停服务会要求先执行 `service stop`，再执行 `service start`。
+- 查看日志：`journalctl --user -u flexgate -e`。
+
+## 状态总览与用量查询
+
+```bash
+flexgate status                  # providers + fallback 链 + 每个 key 的用量 + 当前路由
+flexgate status --no-usage       # 跳过用量查询，只看配置
+flexgate status --usage-timeout 30
+flexgate usage                   # 只看每个 key 的用量/额度（不打印配置和路由）
+flexgate usage --usage-timeout 30
+```
+
+各平台的用量查询适配器详见[用量查询](usage.md)。
+
+## 上游连通性预检
+
+`flexgate check` 会向每个**被路由引用的 `(provider, model)` 组合**发送一次
+`POST /v1/messages`（`max_tokens=1`，消耗约 1~2 token），用于主动检查：
+
+- DNS / TCP / TLS 不可达（`base_url` 写错、网络不通）
+- API key 无效或过期（HTTP 401 / 403）
+- 仍是默认占位符（如 `your-zai-api-key`）
+- Provider 侧 5xx 故障
+
+可通过 `--verify-timeout N` 调整每个 provider 的超时时间（默认 15 秒）。
+
+## 前台调试
+
+`run` / `check` 是独立的顶层调试命令，不属于持久化服务模式：
+
+```bash
+flexgate run                       # 单个前台进程，仅用于开发/调试
+flexgate check                     # 上游 provider 连通性检测
+```
+
+非 systemd 环境只能使用 `flexgate run` 前台运行。`--port PORT` 也只对
+`run` 生效；持久化服务的端口必须写入 `server.port`。
+
+## 配置管理
+
+```bash
+flexgate config init             # 创建默认配置（~/.flexgate/config.yaml）
+flexgate config show             # 查看当前配置（providers、路由、定时规则）
+flexgate config edit             # 交互式选择每个 tier（opus/sonnet/haiku）的 provider/model
+flexgate config path             # 打印配置文件路径
+flexgate config set <tier> <target> [model]  # 快速设置路由（tier 可为 all/opus/sonnet/haiku）
+```
+
+`config set` 支持按 provider 名或 model 名设置路由：
+
+```bash
+# 批量切换所有 tier（opus/sonnet/haiku）到同一个 provider
+flexgate config set all xiaomi
+
+# 用逗号组合多个 tier
+flexgate config set opus,sonnet xiaomi
+
+# 按 provider 名 + model 名
+flexgate config set sonnet minimax MiniMax-M3
+
+# 按 provider 名（不改写 model）
+flexgate config set opus zai
+
+# 按 model 名自动查找 provider
+flexgate config set haiku MiniMax-M3
+# → 自动解析为 minimax / MiniMax-M3
+```
+
+如果 model 名在多个 provider 中存在，会提示歧义并给出带 provider 名的
+写法。
+
+:::{note}
+`config set` 不会修改 API key。如需添加新 provider 或修改密钥，请手动
+编辑配置文件。
+:::
+
+### 交互式编辑（`config edit`）
+
+运行 `flexgate config edit` 进入全屏交互界面，用 **↑/↓ 方向键移动、回车
+选择**，无需记忆 provider/model 名称：
+
+```text
+Flexgate config  —  ~/.flexgate/config.yaml
+↑/↓ move · Enter edit tier · s save · q quit
+
+▶ opus      ustc / deepseek-v4-pro
+  sonnet    ustc / deepseek-v4-pro
+  haiku     ustc / deepseek-v4-pro
+
+○ no unsaved changes
+```
+
+- 方向键选中某个 tier（opus/sonnet/haiku），回车进入：先从候选
+  **provider** 列表选择，再从该 provider 的候选 **model** 列表选择。
+- model 列表包含：`available_models` 中的各个模型、「使用 provider 默认
+  （首个可用模型，不写死 model）」、以及「自定义模型…」（手动输入）。
+- 按 `s` 保存（并向运行中的网关发送 SIGUSR1 热重载，**无需重启即生效**），
+  按 `q` 退出（有未保存改动时会询问 "Config changed — activate now?"：
+  选 Yes 立即保存并热重载生效，选 No 放弃改动）；子菜单中按 `Esc`/`←`
+  返回上一级。
+- 需要交互式终端（TTY）；非交互场景请改用 `flexgate config set`。
+
+## Settings 管理
+
+```bash
+flexgate settings import         # 从 ~/.claude/settings.json* 导入凭证到 config.yaml
+flexgate settings apply          # 将 config.yaml 配置写入 ~/.claude/settings.json
+```
+
+**import** 会扫描 `~/.claude/settings.json*`，从每个文件中提取
+`ANTHROPIC_BASE_URL` 和 `ANTHROPIC_AUTH_TOKEN`，自动写入 config.yaml 的
+providers 部分。文件名与 provider 名称的映射规则：
+
+- `settings.json` → 根据域名自动推断（如含 `z.ai` → `zai`）
+- `settings.json.zai` → provider 名 `zai`
+- `settings.json.bak.*` → 跳过（备份文件）
+
+**apply** 会读取 config.yaml 中的 `server` 和 `claude_settings`，备份当前
+`~/.claude/settings.json` 为 `settings.json.bak.{timestamp}`，然后生成新的
+settings.json，将 `ANTHROPIC_BASE_URL` 指向本地网关，并保留原有的
+`permissions` 等非 env 字段：
+
+```json
+{
+  "env": {
+    "ANTHROPIC_BASE_URL": "http://127.0.0.1:8765",
+    "ANTHROPIC_AUTH_TOKEN": "gateway",
+    "API_TIMEOUT_MS": "3000000",
+    "ANTHROPIC_DEFAULT_OPUS_MODEL": "claude-opus-4-7",
+    "ANTHROPIC_DEFAULT_SONNET_MODEL": "claude-sonnet-4-6",
+    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "claude-haiku-4-5"
+  },
+  "permissions": {
+    "defaultMode": "bypassPermissions"
+  }
+}
+```
+
+`ANTHROPIC_AUTH_TOKEN` 值任意但不能为空，网关会替换为对应 provider 的 key。
+
+## 配置同步（sync）
+
+`flexgate sync` 把整个 `config.yaml` 作为一份**加密文档**，通过 confsync
+服务器在多机之间同步（使用共享的 confsync 凭证，配置文件中不再保存
+confsync 配置段）：
+
+```bash
+flexgate sync              # 默认 pull：下载并合并远端配置
+flexgate sync pull         # 同上
+flexgate sync push         # 上传本地 config.yaml
+flexgate sync --dry-run    # 只显示哪些 key 会变化，不写配置
+flexgate sync --full       # 用远端文档整体替换本地配置（先备份）
+```
+
+更多细节见 `flexgate help`。
+
+## 版本与升级
+
+```bash
+flexgate --version               # 打印版本号
+flexgate doctor                  # 只读体检：Python、PyPI 新版、配置 schema、端口、systemd、Claude settings
+flexgate doctor --offline        # 跳过 PyPI 检查
+flexgate update                  # 一键升级：pip/pipx/uv 升级包 + 迁移配置 schema + 热重载服务
+flexgate update --check          # 只报告将要做什么，不改动
+flexgate update --config-only    # 只迁移配置，不升级包
+```
+
+升级策略：
+
+- **包升级**：版本号唯一来源是 `flexgate/__init__.py`；发布到 PyPI 后，
+  `flexgate update` 自动检测安装方式（pipx / uv tool / pip）并升级到最新
+  release。
+- **新版本自动提示**：裸 `flexgate` 和 `flexgate service status` 会自动
+  比对 PyPI 上的最新版本，有新版时打印一行升级提示。检查结果缓存在
+  `~/.flexgate/update-check.json`，每 24 小时最多访问一次 PyPI，离线时
+  静默跳过。
+- **配置迁移**：`config.yaml` 带 `config_version` 标记。每次 schema 变化
+  在 `flexgate/migrate.py` 的 `MIGRATIONS` 中登记一条 N → N+1 规则，升级
+  时逐级走完整个迁移链。迁移前自动备份为 `config.yaml.bak-<时间戳>`；
+  配置比当前 flexgate 更新时会被拒绝并提示先升级。
+- **自检**：发版或排障时跑 `flexgate doctor`，有 FAIL 项时退出码为 1，
+  可直接用于 CI 门禁。