flexgate 0.5.1__tar.gz → 0.7.0__tar.gz

{flexgate-0.5.1 → flexgate-0.7.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,8 +31,9 @@ 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: replace local config.yaml with the remote document (backup first)
@@ -41,7 +42,9 @@ 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
@@ -70,35 +73,41 @@ without a systemd user instance.
 
 ```
 Claude Code → POST /v1/messages (model="claude-sonnet-4-6")
-  → server.py   (Starlette app, single route)
+  → server.py   (Starlette app, /v1/messages + /v1/images/* routes)
   → router.py   (resolve(): regex match model, check schedule windows first, then default routes)
   → proxy.py    (rewrite model field if override, swap x-api-key, SSE streaming pass-through)
   → Upstream provider (z.ai, minimax, xiaomi, etc.)
+
+OpenAI-style client → POST /v1/images/generations
+  → images.py   (translate to MiniMax /v1/image_generation; provider auto-detected by base_url)
 ```
 
 ### Source files (`flexgate/`)
 
 | 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 |
+| `server.py` | Starlette app creation, `POST /v1/messages` + `POST /v1/images/{generations,edits}` endpoints, `SIGUSR1` lifespan reload |
+| `images.py` | OpenAI Images API → MiniMax `/v1/image_generation` translation (`image-01`, size→width/height clamped to 512–2048 mult of 8, `data.image_base64[]`→`data[].b64_json`); edits endpoint returns 501; unknown image model names get 501 `model_not_supported` |
+| `fallback.py` | Catch-all route: merged Anthropic/OpenAI-shaped JSON errors for every unserved path — 404 `route_not_found` (lists valid routes), 405 `method_not_allowed`, 501 `endpoint_not_supported` per recognized API family with an actionable reason |
 | `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. 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.
@@ -110,6 +119,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

{flexgate-0.5.1 → flexgate-0.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: flexgate
-Version: 0.5.1
+Version: 0.7.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.5.1 → flexgate-0.7.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.5.1 → flexgate-0.7.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` 也只对
@@ -157,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
 {
@@ -211,8 +240,8 @@ flexgate sync --dry-run    # 只预览，不写配置
 
 ```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.5.1 → flexgate-0.7.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 残留，

{flexgate-0.5.1 → flexgate-0.7.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.5.1 → flexgate-0.7.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.5.1 → flexgate-0.7.0}/flexgate/__init__.py

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