flexgate 0.4.1__tar.gz → 0.6.0__tar.gz

{flexgate-0.4.1 → flexgate-0.6.0}/.github/workflows/docs.yml

@@ -7,8 +7,6 @@ on:
       - 'docs/**'
       - 'flexgate/__init__.py'
       - '.github/workflows/docs.yml'
-    tags:
-      - 'v*'
   pull_request:
     branches: [main]
     paths:
@@ -60,7 +58,7 @@ jobs:
       url: ${{ steps.deployment.outputs.page_url }}
     runs-on: ubuntu-latest
     needs: build-docs
-    if: github.ref == 'refs/heads/main' || github.ref_type == 'tag'
+    if: github.ref == 'refs/heads/main'
     steps:
       - name: Deploy to GitHub Pages
         id: deployment

{flexgate-0.4.1 → flexgate-0.6.0}/CLAUDE.md

@@ -21,8 +21,8 @@ flexgate service install                    # install + enable + start systemd u
 # Lifecycle
 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
+flexgate log                                # service journal (-f follow, -r route lines only)
 
 # Config
 flexgate config {init|show|set|path|edit}
@@ -31,18 +31,20 @@ flexgate config set sonnet minimax MiniMax-M3
 flexgate config edit                        # interactive curses TUI: pick provider/model per tier
 
 # Claude Code settings bridge
-flexgate settings import                    # read from ~/.claude/settings.json
-flexgate settings apply                     # write ANTHROPIC_BASE_URL → localhost
+flexgate settings import                    # read from ~/.claude/settings.json* (merges keys into api_keys)
+flexgate settings apply                     # rewrite the flexgate env keys → localhost (other fields preserved)
+flexgate settings apply --dry-run           # preview the env diff without writing
 
 # confsync config sync
-flexgate sync                               # pull config.yaml from your confsync server (merge keys)
+flexgate sync                               # pull: replace local config.yaml with the remote document (backup first)
 flexgate sync push                          # upload local config.yaml to the server
-flexgate sync --full                        # replace local config with the remote document (backup first)
 flexgate sync --dry-run                     # preview changes without writing
 
 # Versioning / upgrades
 flexgate --version                          # print package version
-flexgate doctor                             # diagnose install/config problems (exit 1 on failure)
+flexgate doctor                             # diagnose install/config + upstream connectivity (exit 1 on failure)
+flexgate doctor --offline                   # skip all network checks (PyPI + upstream probing)
+flexgate check                              # DEPRECATED alias: delegates to doctor
 flexgate update                             # upgrade package via pip/pipx/uv + migrate config schema
 flexgate update --check                     # report what would change, modify nothing
 flexgate update --config-only               # only migrate the config schema
@@ -81,29 +83,30 @@ Claude Code → POST /v1/messages (model="claude-sonnet-4-6")
 
 | File | Role |
 |------|------|
-| `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 |
+| `cli.py` | argparse CLI; service lifecycle commands, foreground `run`, config/settings/sync commands, `flexgate log` journal viewer |
+| `ui.py` | Shared terminal styling: ANSI helpers (`bold`/`dim`/`red`/...), `ok`/`warn`/`fail`/`err` output helpers, `FlexgateHelpFormatter` + `FlexgateParser` (colored help on every Python version; all gated by `NO_COLOR` + stdout isatty) |
+| `config.py` | Pydantic-like dataclasses (`GatewayConfig`, `ProviderConfig`, `RouteConfig`, `ScheduleEntry`), YAML load/save, `TIER_PATTERNS` regex map, `is_placeholder_key` |
+| `router.py` | `resolve(config, model)` — schedule-first then default routes, first regex match wins; model aliases normalized before matching |
 | `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 |
-| `guardian.py` | Legacy port/PID helper; no longer owns persistent process supervision |
-| `healthcheck.py` | Pre-flight `POST /v1/messages` (max_tokens=1) to each referenced (provider, model) pair |
-| `settings.py` | Bridges `config.yaml` ↔ `~/.claude/settings.json` (import credentials, apply config) |
+| `healthcheck.py` | Upstream connectivity probing (`POST /v1/messages`, max_tokens=1) for each referenced (provider, model) pair; called by `doctor` (`flexgate check` is a deprecated alias of doctor) |
+| `settings.py` | Bridges `config.yaml` ↔ `~/.claude/settings.json`: import merges credentials into `api_keys`; apply rewrites only the managed env keys, preserving every other settings.json field |
 | `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) |
+| `doctor.py` | `flexgate doctor` — read-only diagnostics (Python, PyPI update, config schema/semantics, port, systemd, Claude settings) plus upstream connectivity via `healthcheck` (skipped with `--offline`) |
 | `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 alias normalization** (`router.py`): before matching, bare aliases (`sonnet`/`opus`/`haiku`/`default`, case-insensitive, optional `[plan]` suffix) map to `claude-<tier>` prefixes (`default` → sonnet, Claude Code's default tier), and legacy numbered names (`claude-3-7-sonnet-latest`) reduce to their tier prefix; everything else passes through unchanged, so custom patterns and the catch-all behave exactly as before.
 - **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.
+- **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. Each *route* has an active-key pointer (`active_key` in YAML, 1-based; `RouteConfig.key_index` 0-based, default first key): requests on that route start from the pointed key, and on a retryable failure (HTTP 401/402/403/429/500/502/503/529, connect error, or timeout) the next key is tried and the pointer advances with it (in memory only, wrapping around — it is not written back to the file); every key is tried at most once and a full circle of failures returns the last error. The pointer is set interactively via `flexgate config edit` → "api keys" (pick a route, with live per-key usage) or by editing the route's `active_key` directly. `resolve()` (`router.py`) returns the matched `RouteConfig` so the proxy can read/advance its pointer. 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 the settings import code.
+- **Usage inspection** (`usage.py`): `flexgate status` maps `base_url` to a platform adapter (`_ADAPTERS`): MiniMax → `{origin}/v1/api/openplatform/coding_plan/remains` (only the "general" text-model quota entry is used; its counts are usually 0/0, so usage is read from the `*_remaining_percent` fields), 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.
@@ -111,6 +114,8 @@ Claude Code → POST /v1/messages (model="claude-sonnet-4-6")
 - **Conflict prevention**: Service startup removes stale legacy PID files, stops verified legacy Flexgate daemons, validates the configured port, and rejects temporary config paths.
 - **Tier patterns** in `config.py`: `opus`, `sonnet`, `haiku` map to regex patterns for CLI shorthand (`config set sonnet ...`).
 - **Single-source versioning**: the package version lives only in `flexgate/__init__.py` (`__version__`); hatchling reads it via `[tool.hatch.version]`. `--version`, `service status` and the bare `flexgate` command all print it.
+- **Settings apply is non-destructive** (`settings.py`): only the six managed `env` keys are rewritten (BASE_URL, AUTH_TOKEN, API_TIMEOUT_MS, three `ANTHROPIC_DEFAULT_*_MODEL`); every other settings.json field (hooks, permissions, unrelated env vars) is preserved. Token policy is one code path shared with `service install`: explicit arg → token already in the file → `"gateway"`. `settings import` merges into the provider's `api_keys` list (appends new keys, never overwrites key #1 only).
+- **Terminal styling** (`ui.py`): every colored output goes through `ui.bold`/`dim`/`ok`/`err`/... — all gated on `NO_COLOR` + stdout isatty, so pipes never receive escape codes. `err()` writes to stderr. Help screens use `FlexgateParser` (subparsers inherit it automatically); on Python 3.14+ argparse's own help theming is disabled so the look matches older versions.
 - **Config schema versioning**: `config.yaml` carries `config_version` (current: `migrate.CURRENT_CONFIG_VERSION`). Each schema change adds one rule to `migrate.MIGRATIONS` upgrading N → N+1; upgrades walk the chain step by step. `save_config` always stamps the current version; `load_config` rejects configs written by a newer flexgate; `flexgate update` applies pending migrations with a timestamped backup.
 
 ### Config location
@@ -119,11 +124,10 @@ Config lives at `~/.flexgate/config.yaml` (override with `FLEXGATE_CONFIG`).
 `flexgate sync` needs no flexgate-side setup — connection details come from
 the shared confsync credentials written by `confsync login --server <url>`
 (`~/.confsync/credentials.json`). The whole config.yaml is synced as one
-encrypted document (app `flexgate`, name `config.yaml`): pull merges
-provider api_keys and imports remote-only providers (local routes/schedules
-untouched), bootstraps the file when missing, and `--full` replaces it with a
-timestamped backup. The `confsync-client` package is a declared dependency
-(PyPI), so sync works out of the box once logged in.
+encrypted document (app `flexgate`, name `config.yaml`): pull always replaces
+the local file with the remote document (a timestamped backup is kept), or
+bootstraps the file when missing. The `confsync-client` package is a declared
+dependency (PyPI), so sync works out of the box once logged in.
 The persistent unit lives at `~/.config/systemd/user/flexgate.service`; logs are
 in the systemd user journal. `~/.flexgate/service-state.json` records the last
 successfully applied config path and endpoint. PID/guardian files are legacy artifacts only.

{flexgate-0.4.1 → flexgate-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: flexgate
-Version: 0.4.1
+Version: 0.6.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
@@ -106,13 +106,13 @@ flexgate service uninstall           # 停止、禁用并删除 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`。
+- 查看日志：`flexgate log`（`-f` 跟随、`--since`/`--grep` 过滤、`-r` 只看路由决策行）。
 
 ### 版本与升级
 
 ```bash
 flexgate --version               # 打印版本号（service status / 裸 flexgate 也会显示）
-flexgate doctor                  # 只读体检：Python、PyPI 新版、配置 schema、端口、systemd、Claude settings
+flexgate doctor                  # 只读体检：Python、PyPI 新版、配置 schema、端口、systemd、Claude settings、上游连通性
 flexgate doctor --offline        # 跳过 PyPI 检查
 flexgate update                  # 一键升级：pip/pipx/uv 升级包 + 迁移配置 schema + 热重载服务
 flexgate update --check          # 只报告将要做什么，不改动
@@ -149,7 +149,7 @@ Trusted Publisher（repo: `Agony5757/flexible-gateway`，workflow: `release.yml`
 
 ### 上游连通性预检
 
-运行 `flexgate check` 会向每个 **被路由引用的 `(provider, model)` 组合**
+运行 `flexgate doctor` 会向每个 **被路由引用的 `(provider, model)` 组合**
 发送一次 `POST /v1/messages`（`max_tokens=1`，消耗约 1~2 token），用于主动检查：
 
 - DNS / TCP / TLS 不可达（`base_url` 写错、网络不通）
@@ -157,7 +157,10 @@ Trusted Publisher（repo: `Agony5757/flexible-gateway`，workflow: `release.yml`
 - 仍是默认占位符（如 `your-zai-api-key`）
 - Provider 侧 5xx 故障
 
-可通过 `--verify-timeout N` 调整每个 provider 的超时时间（默认 15 秒）。
+可通过 `--verify-timeout N` 调整每个 provider 的超时时间（默认 15 秒），
+`--offline` 跳过全部网络检查（PyPI 新版检查 + 上游探测）。
+旧的 `flexgate check` 命令仍可用，但已弃用：它会打印提示并委托给 `doctor`
+（注意 doctor 还检查本地安装，退出码语义更宽）。
 
 ### 状态总览与用量查询（`flexgate status` / `flexgate usage`）
 
@@ -187,13 +190,12 @@ fallback 链、当前生效的路由，并逐一查询**每个 key** 的用量/
 如果某平台的专用接口调用失败，flexgate 会自动退化为 minimal probe 再试一次。
 用量查询接口多为平台内部接口，可能随时变动；查询结果仅供参考。
 
-### 前台调试与连通性检查
+### 前台调试
 
-`run` / `check` 是独立的顶层调试命令，不属于持久化服务模式：
+`run` 是独立的顶层调试命令，不属于持久化服务模式：
 
 ```bash
 flexgate run                       # 单个前台进程，仅用于开发/调试
-flexgate check                     # 上游 provider 连通性检测
 ```
 
 非 systemd 环境只能使用 `flexgate run` 前台运行。`--port PORT` 也只对
@@ -259,10 +261,17 @@ Flexgate config  —  ~/.flexgate/config.yaml
 ### Settings 管理
 
 ```bash
-flexgate settings import         # 从 ~/.claude/settings.json* 导入凭证到 config.yaml
-flexgate settings apply          # 将 config.yaml 配置写入 ~/.claude/settings.json
+flexgate settings import         # 从 ~/.claude/settings.json* 导入凭证到 config.yaml（多 key 追加）
+flexgate settings apply          # 将网关 env 写入 ~/.claude/settings.json（非破坏性）
+flexgate settings apply --dry-run  # 预览将要修改的 env 键，不写文件
 ```
 
+`apply` 只重写 flexgate 托管的 6 个 env 键（BASE_URL、AUTH_TOKEN、
+API_TIMEOUT_MS、三个 `ANTHROPIC_DEFAULT_*_MODEL`），settings.json 中的
+其他字段（hooks、permissions、自定义 env 等）全部保留；写入前自动备份。
+`import` 会把新 key 追加到 provider 的 `api_keys` 列表（已存在则跳过），
+不会覆盖已有 key。
+
 ### 全局参数
 
 - `--config PATH` 指定配置文件（默认 `~/.flexgate/config.yaml`）
@@ -278,7 +287,7 @@ flexgate settings apply          # 将 config.yaml 配置写入 ~/.claude/settin
 | `~/.flexgate/service-state.json` | 最近一次成功启动所应用的 config 路径与 endpoint |
 | `~/.flexgate/update-check.json` | PyPI 新版本检查的缓存（24h 有效期） |
 | `~/.config/systemd/user/flexgate.service` | 唯一的持久化服务 unit |
-| systemd journal | 服务日志（`journalctl --user -u flexgate`） |
+| systemd journal | 服务日志（`flexgate log`，即 `journalctl --user -u flexgate`） |
 
 旧版本的 `~/.flexgate/flexgate.pid`、`flexgate.guardian.pid` 和
 `flexgate.log` 不再属于当前运行架构；service 启动时会安全清理 PID 残留，

{flexgate-0.4.1 → flexgate-0.6.0}/README.md

@@ -89,13 +89,13 @@ flexgate service uninstall           # 停止、禁用并删除 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`。
+- 查看日志：`flexgate log`（`-f` 跟随、`--since`/`--grep` 过滤、`-r` 只看路由决策行）。
 
 ### 版本与升级
 
 ```bash
 flexgate --version               # 打印版本号（service status / 裸 flexgate 也会显示）
-flexgate doctor                  # 只读体检：Python、PyPI 新版、配置 schema、端口、systemd、Claude settings
+flexgate doctor                  # 只读体检：Python、PyPI 新版、配置 schema、端口、systemd、Claude settings、上游连通性
 flexgate doctor --offline        # 跳过 PyPI 检查
 flexgate update                  # 一键升级：pip/pipx/uv 升级包 + 迁移配置 schema + 热重载服务
 flexgate update --check          # 只报告将要做什么，不改动
@@ -132,7 +132,7 @@ Trusted Publisher（repo: `Agony5757/flexible-gateway`，workflow: `release.yml`
 
 ### 上游连通性预检
 
-运行 `flexgate check` 会向每个 **被路由引用的 `(provider, model)` 组合**
+运行 `flexgate doctor` 会向每个 **被路由引用的 `(provider, model)` 组合**
 发送一次 `POST /v1/messages`（`max_tokens=1`，消耗约 1~2 token），用于主动检查：
 
 - DNS / TCP / TLS 不可达（`base_url` 写错、网络不通）
@@ -140,7 +140,10 @@ Trusted Publisher（repo: `Agony5757/flexible-gateway`，workflow: `release.yml`
 - 仍是默认占位符（如 `your-zai-api-key`）
 - Provider 侧 5xx 故障
 
-可通过 `--verify-timeout N` 调整每个 provider 的超时时间（默认 15 秒）。
+可通过 `--verify-timeout N` 调整每个 provider 的超时时间（默认 15 秒），
+`--offline` 跳过全部网络检查（PyPI 新版检查 + 上游探测）。
+旧的 `flexgate check` 命令仍可用，但已弃用：它会打印提示并委托给 `doctor`
+（注意 doctor 还检查本地安装，退出码语义更宽）。
 
 ### 状态总览与用量查询（`flexgate status` / `flexgate usage`）
 
@@ -170,13 +173,12 @@ fallback 链、当前生效的路由，并逐一查询**每个 key** 的用量/
 如果某平台的专用接口调用失败，flexgate 会自动退化为 minimal probe 再试一次。
 用量查询接口多为平台内部接口，可能随时变动；查询结果仅供参考。
 
-### 前台调试与连通性检查
+### 前台调试
 
-`run` / `check` 是独立的顶层调试命令，不属于持久化服务模式：
+`run` 是独立的顶层调试命令，不属于持久化服务模式：
 
 ```bash
 flexgate run                       # 单个前台进程，仅用于开发/调试
-flexgate check                     # 上游 provider 连通性检测
 ```
 
 非 systemd 环境只能使用 `flexgate run` 前台运行。`--port PORT` 也只对
@@ -242,10 +244,17 @@ Flexgate config  —  ~/.flexgate/config.yaml
 ### Settings 管理
 
 ```bash
-flexgate settings import         # 从 ~/.claude/settings.json* 导入凭证到 config.yaml
-flexgate settings apply          # 将 config.yaml 配置写入 ~/.claude/settings.json
+flexgate settings import         # 从 ~/.claude/settings.json* 导入凭证到 config.yaml（多 key 追加）
+flexgate settings apply          # 将网关 env 写入 ~/.claude/settings.json（非破坏性）
+flexgate settings apply --dry-run  # 预览将要修改的 env 键，不写文件
 ```
 
+`apply` 只重写 flexgate 托管的 6 个 env 键（BASE_URL、AUTH_TOKEN、
+API_TIMEOUT_MS、三个 `ANTHROPIC_DEFAULT_*_MODEL`），settings.json 中的
+其他字段（hooks、permissions、自定义 env 等）全部保留；写入前自动备份。
+`import` 会把新 key 追加到 provider 的 `api_keys` 列表（已存在则跳过），
+不会覆盖已有 key。
+
 ### 全局参数
 
 - `--config PATH` 指定配置文件（默认 `~/.flexgate/config.yaml`）
@@ -261,7 +270,7 @@ flexgate settings apply          # 将 config.yaml 配置写入 ~/.claude/settin
 | `~/.flexgate/service-state.json` | 最近一次成功启动所应用的 config 路径与 endpoint |
 | `~/.flexgate/update-check.json` | PyPI 新版本检查的缓存（24h 有效期） |
 | `~/.config/systemd/user/flexgate.service` | 唯一的持久化服务 unit |
-| systemd journal | 服务日志（`journalctl --user -u flexgate`） |
+| systemd journal | 服务日志（`flexgate log`，即 `journalctl --user -u flexgate`） |
 
 旧版本的 `~/.flexgate/flexgate.pid`、`flexgate.guardian.pid` 和
 `flexgate.log` 不再属于当前运行架构；service 启动时会安全清理 PID 残留，

{flexgate-0.4.1 → flexgate-0.6.0}/docs/cli.md

@@ -2,7 +2,7 @@
 
 ```text
 usage: flexgate [-h] [--config CONFIG] [--version]
-                {service,run,check,status,usage,settings,sync,help,doctor,update,config} ...
+                {service,run,check,status,usage,log,settings,sync,help,doctor,update,config} ...
 ```
 
 全局参数：
@@ -45,7 +45,7 @@ flexgate service uninstall           # 停止、禁用并删除 unit
 - `service reload` 和 `config set/edit` 会在仅路由变化时发送 SIGUSR1；
   如果 endpoint 变化，则先检查再 restart。若只改 host、仍复用当前 port，
   为避免误停服务会要求先执行 `service stop`，再执行 `service start`。
-- 查看日志：`journalctl --user -u flexgate -e`。
+- 查看日志：`flexgate log`（`-f` 跟随、`--since`/`--grep` 过滤、`-r` 只看路由决策行）。
 
 ## 状态总览与用量查询
 
@@ -59,9 +59,32 @@ flexgate usage --usage-timeout 30
 
 各平台的用量查询适配器详见[用量查询](usage.md)。
 
+## 查看日志（log）
+
+```bash
+flexgate log                     # 最近 50 行服务日志（systemd user journal）
+flexgate log -n 200              # 最近 200 行
+flexgate log -f                  # 实时跟随（Ctrl-C 退出）
+flexgate log --since "10 min ago"
+flexgate log --grep 429          # 只显示包含 429 的行（大小写不敏感）
+flexgate log -r                  # 只看路由决策行
+flexgate log -f -r               # 实时观察每个请求被路由到哪个 provider/模型
+```
+
+`flexgate log` 读取 `flexgate.service` 的 systemd 用户日志（等价于
+`journalctl --user -u flexgate`，输出为单时间戳的 cat 格式）。`-r` 只显示
+每个请求完成时的路由决策行：
+
+```text
+[default] claude-sonnet-4-6 -> zai (glm-5.3) | 200 | 6676ms
+```
+
+想知道"刚才那条回复到底是哪个模型服务的"，看这一行即可。前台调试用的
+`flexgate run` 日志直接打印在终端，不进 journal。
+
 ## 上游连通性预检
 
-`flexgate check` 会向每个**被路由引用的 `(provider, model)` 组合**发送一次
+`flexgate doctor` 会向每个**被路由引用的 `(provider, model)` 组合**发送一次
 `POST /v1/messages`（`max_tokens=1`，消耗约 1~2 token），用于主动检查：
 
 - DNS / TCP / TLS 不可达（`base_url` 写错、网络不通）
@@ -69,15 +92,17 @@ flexgate usage --usage-timeout 30
 - 仍是默认占位符（如 `your-zai-api-key`）
 - Provider 侧 5xx 故障
 
-可通过 `--verify-timeout N` 调整每个 provider 的超时时间（默认 15 秒）。
+可通过 `--verify-timeout N` 调整每个 provider 的探测超时（默认 15 秒）；
+`--offline` 跳过全部网络检查（PyPI 新版检查 + 上游探测）。旧的
+`flexgate check` 命令已弃用：仍可运行，但会打印提示并委托给 `doctor`
+（注意 doctor 还检查本地安装，退出码语义更宽）。
 
 ## 前台调试
 
-`run` / `check` 是独立的顶层调试命令，不属于持久化服务模式：
+`run` 是独立的顶层调试命令，不属于持久化服务模式：
 
 ```bash
 flexgate run                       # 单个前台进程，仅用于开发/调试
-flexgate check                     # 上游 provider 连通性检测
 ```
 
 非 systemd 环境只能使用 `flexgate run` 前台运行。`--port PORT` 也只对
@@ -128,17 +153,24 @@ flexgate config set haiku MiniMax-M3
 
 ```text
 Flexgate config  —  ~/.flexgate/config.yaml
-↑/↓ move · Enter edit tier · s save · q quit
+↑/↓ move · Enter edit · s save · q quit
 
 ▶ opus      ustc / deepseek-v4-pro
   sonnet    ustc / deepseek-v4-pro
   haiku     ustc / deepseek-v4-pro
+  fallback  ustc / deepseek-v4-pro
+  api keys  select the active key per route
 
 ○ no unsaved changes
 ```
 
-- 方向键选中某个 tier（opus/sonnet/haiku），回车进入：先从候选
+- 方向键选中某个 tier（opus/sonnet/haiku）或 `fallback`（兜底路由
+  `.*`，未命中任何 tier 的请求走它），回车进入：先从候选
   **provider** 列表选择，再从该 provider 的候选 **model** 列表选择。
+- 选中 `api keys` 回车进入：先选一条**路由**，再选它的 **active key**
+  （该路由的请求从这个 key 开始；fallback 会自动前移指针，所有 key
+  轮换一圈都失败则返回错误）。key 列表会实时查询每个 key 的用量/有效性
+  （与 `flexgate status` 相同），并标注当前 active 的 key。
 - model 列表包含：`available_models` 中的各个模型、「使用 provider 默认
   （首个可用模型，不写死 model）」、以及「自定义模型…」（手动输入）。
 - 按 `s` 保存（并向运行中的网关发送 SIGUSR1 热重载，**无需重启即生效**），
@@ -150,22 +182,26 @@ Flexgate config  —  ~/.flexgate/config.yaml
 ## Settings 管理
 
 ```bash
-flexgate settings import         # 从 ~/.claude/settings.json* 导入凭证到 config.yaml
-flexgate settings apply          # 将 config.yaml 配置写入 ~/.claude/settings.json
+flexgate settings import           # 从 ~/.claude/settings.json* 导入凭证到 config.yaml（多 key 追加）
+flexgate settings apply            # 将网关 env 写入 ~/.claude/settings.json（非破坏性）
+flexgate settings apply --dry-run  # 预览将要修改的 env 键，不写文件
 ```
 
 **import** 会扫描 `~/.claude/settings.json*`，从每个文件中提取
-`ANTHROPIC_BASE_URL` 和 `ANTHROPIC_AUTH_TOKEN`，自动写入 config.yaml 的
-providers 部分。文件名与 provider 名称的映射规则：
+`ANTHROPIC_BASE_URL` 和 `ANTHROPIC_AUTH_TOKEN`，合并进 config.yaml 的
+providers：provider 已存在时**追加**到它的 `api_keys` 列表（已存在同一把
+key 则跳过），不存在则新建。文件名与 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 字段：
+**apply** 是非破坏性的：备份当前 `~/.claude/settings.json` 为
+`settings.json.bak.{timestamp}` 后，**只重写 flexgate 托管的 6 个 env 键**
+（`ANTHROPIC_BASE_URL`、`ANTHROPIC_AUTH_TOKEN`、`API_TIMEOUT_MS`、三个
+`ANTHROPIC_DEFAULT_*_MODEL`），settings.json 中的其余字段（hooks、
+permissions、自定义 env 等）全部原样保留。token 策略与 `service install`
+共用一条路径：显式参数 → 文件里已有的 token → 兜底 `"gateway"`：
 
 ```json
 {
@@ -192,11 +228,10 @@ settings.json，将 `ANTHROPIC_BASE_URL` 指向本地网关，并保留原有的
 confsync 配置段）：
 
 ```bash
-flexgate sync              # 默认 pull：下载并合并远端配置
+flexgate sync              # 默认 pull：用远端文档整体替换本地配置（先备份）
 flexgate sync pull         # 同上
 flexgate sync push         # 上传本地 config.yaml
-flexgate sync --dry-run    # 只显示哪些 key 会变化，不写配置
-flexgate sync --full       # 用远端文档整体替换本地配置（先备份）
+flexgate sync --dry-run    # 只预览，不写配置
 ```
 
 更多细节见 `flexgate help`。
@@ -205,8 +240,8 @@ flexgate sync --full       # 用远端文档整体替换本地配置（先备份
 
 ```bash
 flexgate --version               # 打印版本号
-flexgate doctor                  # 只读体检：Python、PyPI 新版、配置 schema、端口、systemd、Claude settings
-flexgate doctor --offline        # 跳过 PyPI 检查
+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-0.4.1 → flexgate-0.6.0}/docs/configuration.md

@@ -8,7 +8,7 @@
 | `~/.flexgate/service-state.json` | 最近一次成功启动所应用的 config 路径与 endpoint |
 | `~/.flexgate/update-check.json` | PyPI 新版本检查的缓存（24h 有效期） |
 | `~/.config/systemd/user/flexgate.service` | 唯一的持久化服务 unit |
-| systemd journal | 服务日志（`journalctl --user -u flexgate`） |
+| systemd journal | 服务日志（`flexgate log`，即 `journalctl --user -u flexgate`） |
 
 旧版本的 `~/.flexgate/flexgate.pid`、`flexgate.guardian.pid` 和
 `flexgate.log` 不再属于当前运行架构；service 启动时会安全清理 PID 残留，
@@ -60,6 +60,7 @@ routes:                          # 从上到下匹配，首个命中生效
   - pattern: "^claude-sonnet"
     provider: minimax
     model: "MiniMax-M3"
+    active_key: 2               # 可选：该路由从 minimax 的第 2 个 key 开始用（1 起始，默认 1）
   - pattern: "^claude-haiku"
     provider: minimax
     model: "MiniMax-M3"
@@ -80,6 +81,7 @@ routes:                          # 从上到下匹配，首个命中生效
 | `routes[].pattern` | 正则匹配请求中的 model 字段 |
 | `routes[].provider` | 路由到的 provider 名称 |
 | `routes[].model` | 可选，替换发给 provider 的模型名 |
+| `routes[].active_key` | 可选，1 起始的 provider api_keys 序号，该路由的请求从哪个 key 开始（默认 1，即第一个 key） |
 | `schedule[].name` | 定时规则名称 |
 | `schedule[].start/end` | 时间窗口（HH:MM 格式，支持跨夜如 22:00-06:00） |
 | `schedule[].routes` | 该时间窗口内生效的路由（格式同 `routes`） |
@@ -91,18 +93,25 @@ routes:                          # 从上到下匹配，首个命中生效
 `{key, note}` 加一个存在配置里的备注（`flexgate status` 和 fallback 日志
 都会显示 note，方便分辨是哪个账号的 key）：
 
-- 请求先走第一个 key；失败时按列表顺序自动重试后续 key，直到某个 key
-  成功或返回不可重试的错误。
+- 每条路由有一个「当前 key」指针（路由上的 `active_key`，默认指向
+  provider 的第一个 key）：该路由的请求从指针指向的 key 开始；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 的
-  实时用量。
+- 用 `flexgate status` 可以查看每个 provider 的 fallback 链、每条路由
+  当前使用的 key 和每个 key 的实时用量；在 `flexgate config edit` 交互
+  界面的「api keys」入口可以按路由查看各 key 的实时用量/有效性并切换
+  active key。
 - 旧版 `api_key` + `fallback_keys` 写法仍然兼容，`flexgate update` 会
-  自动迁移为 `api_keys` 列表（config_version 3 → 4）。
+  自动迁移为 `api_keys` 列表（config_version 3 → 4）；路由上的
+  `active_key` 字段在 config_version 5 引入，旧配置的每条路由默认指向
+  第一个 key。
 
 ## 环境变量
 

{flexgate-0.4.1 → flexgate-0.6.0}/docs/development.md

@@ -4,17 +4,19 @@
 
 | 文件 | 作用 |
 |------|------|
-| `flexgate/cli.py` | argparse CLI；service 生命周期命令、前台 `run`/`check`、config/settings/sync 命令 |
-| `flexgate/config.py` | dataclass 配置模型（`GatewayConfig`、`ProviderConfig`、`RouteConfig` 等），YAML 加载/保存 |
-| `flexgate/router.py` | `resolve(config, model)` — 先定时路由后默认路由，首个正则命中生效 |
-| `flexgate/proxy.py` | `handle_request()` — httpx 异步代理，per-key fallback 重试，SSE 流式 + JSON 透传 |
+| `flexgate/cli.py` | argparse CLI；service 生命周期命令、前台 `run`、config/settings/sync 命令、`flexgate log` 日志查看 |
+| `flexgate/ui.py` | 共享终端样式：ANSI 辅助函数、`ok`/`warn`/`fail`/`err` 输出辅助、`FlexgateHelpFormatter`（各版本一致的彩色 help；统一受 `NO_COLOR` + isatty 门控） |
+| `flexgate/config.py` | dataclass 配置模型（`GatewayConfig`、`ProviderConfig`、`RouteConfig` 等），YAML 加载/保存，`is_placeholder_key` |
+| `flexgate/router.py` | `resolve(config, model)` — 先定时路由后默认路由，首个正则命中生效；匹配前归一化模型别名（`sonnet`/`claude-3-7-sonnet-latest` → `^claude-<tier>`） |
+| `flexgate/proxy.py` | `handle_request()` — httpx 异步代理，per-key fallback 重试，SSE 流式 + JSON 透传；记录每个请求由哪把 key 服务 |
 | `flexgate/usage.py` | `flexgate status` / `flexgate usage` 的用量查询 — 各平台适配器 + minimal chat probe 兜底 |
 | `flexgate/server.py` | Starlette 应用，`POST /v1/messages` 端点，SIGUSR1 热重载 |
-| `flexgate/service.py` | systemd 用户服务的安装/启停/重载/状态（持久化运行的唯一入口） |
-| `flexgate/settings.py` | config.yaml ↔ `~/.claude/settings.json` 双向桥接 |
+| `flexgate/service.py` | systemd 用户服务的安装/启停/重载/状态（持久化运行的唯一入口）；journal 日志查看 |
+| `flexgate/healthcheck.py` | 上游连通性探测（`POST /v1/messages`，`max_tokens=1`），由 `doctor` 调用（`flexgate check` 为弃用别名） |
+| `flexgate/settings.py` | config.yaml ↔ `~/.claude/settings.json` 双向桥接（apply 非破坏性：只改托管 env 键） |
 | `flexgate/sync.py` | `flexgate sync` — 通过 confsync 服务器加密同步整份配置 |
 | `flexgate/migrate.py` | 配置 schema 版本化：逐级迁移链 + 备份 + 原子重写 |
-| `flexgate/doctor.py` | `flexgate doctor` — 只读诊断 |
+| `flexgate/doctor.py` | `flexgate doctor` — 只读诊断 + 上游连通性（`--offline` 跳过网络检查） |
 | `flexgate/update.py` | `flexgate update` — PyPI 版本检查、按安装方式升级、配置迁移、服务重载 |
 
 ## 关键设计

{flexgate-0.4.1 → flexgate-0.6.0}/docs/quickstart.md

@@ -49,5 +49,5 @@ provider。日常管理常用：
 ```bash
 flexgate status                  # providers + fallback 链 + 每个 key 的用量 + 当前路由
 flexgate config edit             # 交互式调整每个 tier 的 provider/model
-journalctl --user -u flexgate -e # 查看服务日志
+flexgate log                     # 查看服务日志（-r 只看路由决策行）
 ```

{flexgate-0.4.1 → flexgate-0.6.0}/flexgate/__init__.py

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