flexgate 0.4.0__tar.gz → 0.5.1__tar.gz

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

@@ -0,0 +1,65 @@
+name: docs
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'docs/**'
+      - 'flexgate/__init__.py'
+      - '.github/workflows/docs.yml'
+  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'
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@d6db90164ac5ed86f2b6aed7e0febac5b3c0c03e  # v4.0.5

{flexgate-0.4.0 → flexgate-0.5.1}/.gitignore

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

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

@@ -35,9 +35,8 @@ flexgate settings import                    # read from ~/.claude/settings.json
 flexgate settings apply                     # write ANTHROPIC_BASE_URL → localhost
 
 # 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
@@ -95,15 +94,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.
+- **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.
@@ -119,11 +118,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.0 → flexgate-0.5.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: flexgate
-Version: 0.4.0
+Version: 0.5.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。

{flexgate-0.4.0 → flexgate-0.5.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。

flexgate-0.5.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.5.1/docs/cli.md

@@ -0,0 +1,235 @@
+# 命令参考
+
+```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 · 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）或 `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 热重载，**无需重启即生效**），
+  按 `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    # 只预览，不写配置
+```
+
+更多细节见 `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 门禁。

flexgate-0.5.1/docs/conf.py

@@ -0,0 +1,46 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+import pathlib
+import sys
+
+parent_path = pathlib.Path(__file__).resolve().parent.parent
+sys.path.insert(0, str(parent_path))
+
+from flexgate import __version__  # noqa: E402
+
+# -- Project information -----------------------------------------------------
+
+project = "flexgate"
+author = "agony"
+version = __version__
+release = __version__
+
+# -- General configuration ---------------------------------------------------
+
+extensions = [
+    "myst_parser",
+]
+
+myst_enable_extensions = [
+    "colon_fence",
+    "linkify",
+]
+
+source_suffix = {".md": "markdown"}
+templates_path = ["_templates"]
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
+language = "zh_CN"
+
+# -- Options for HTML output -------------------------------------------------
+
+html_theme = "furo"
+html_static_path = ["_static"]
+html_title = f"flexgate {version} 文档"
+html_theme_options = {
+    "source_repository": "https://github.com/Agony5757/flexible-gateway",
+    "source_branch": "main",
+    "source_directory": "docs/",
+}

flexgate-0.5.1/docs/configuration.md

@@ -0,0 +1,125 @@
+# 配置文件
+
+主要运行时资源：
+
+| 文件 | 说明 |
+|------|------|
+| `~/.flexgate/config.yaml` | 主配置文件 |
+| `~/.flexgate/service-state.json` | 最近一次成功启动所应用的 config 路径与 endpoint |
+| `~/.flexgate/update-check.json` | PyPI 新版本检查的缓存（24h 有效期） |
+| `~/.config/systemd/user/flexgate.service` | 唯一的持久化服务 unit |
+| systemd journal | 服务日志（`journalctl --user -u flexgate`） |
+
+旧版本的 `~/.flexgate/flexgate.pid`、`flexgate.guardian.pid` 和
+`flexgate.log` 不再属于当前运行架构；service 启动时会安全清理 PID 残留，
+历史日志文件可按需手动删除。
+
+## 完整示例
+
+运行 `flexgate config init` 创建默认配置，或手动编辑：
+
+```yaml
+server:
+  host: "127.0.0.1"
+  port: 8765
+
+providers:
+  zai:
+    base_url: "https://api.z.ai/api/anthropic"
+    api_keys:
+      - "your-zai-api-key"
+  minimax:
+    base_url: "https://api.minimaxi.com/anthropic"
+    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"
+  default_sonnet_model: "claude-sonnet-4-6"
+  default_haiku_model: "claude-haiku-4-5"
+  api_timeout_ms: 3000000
+
+# 定时路由（可选）：按时间自动切换，首个时间窗口命中生效
+# schedule:
+#   - name: "night-shift"
+#     start: "22:00"
+#     end: "06:00"
+#     routes:
+#       - pattern: "^claude-sonnet"
+#         provider: zai
+#         model: "glm-5.1"
+
+routes:                          # 从上到下匹配，首个命中生效
+  - pattern: "^claude-opus"
+    provider: zai
+    model: "glm-5.1"            # 可选，发给 provider 的实际模型名
+  - pattern: "^claude-sonnet"
+    provider: minimax
+    model: "MiniMax-M3"
+    active_key: 2               # 可选：该路由从 minimax 的第 2 个 key 开始用（1 起始，默认 1）
+  - pattern: "^claude-haiku"
+    provider: minimax
+    model: "MiniMax-M3"
+  - pattern: ".*"               # 兜底
+    provider: minimax
+    model: "MiniMax-M3"
+```
+
+## 配置字段说明
+
+| 字段 | 说明 |
+|------|------|
+| `server.host/port` | 网关监听地址 |
+| `providers.<name>.base_url` | 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 名称 |
+| `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`） |
+
+## Key fallback
+
+同一上游有多个账号/key 时（例如多个 MiniMax 订阅），在 `api_keys` 里配
+多个 key，而不是拆成多个 provider。每项可以是纯 key 字符串，也可以写成
+`{key, note}` 加一个存在配置里的备注（`flexgate status` 和 fallback 日志
+都会显示 note，方便分辨是哪个账号的 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 和每个 key 的实时用量；在 `flexgate config edit` 交互
+  界面的「api keys」入口可以按路由查看各 key 的实时用量/有效性并切换
+  active key。
+- 旧版 `api_key` + `fallback_keys` 写法仍然兼容，`flexgate update` 会
+  自动迁移为 `api_keys` 列表（config_version 3 → 4）；路由上的
+  `active_key` 字段在 config_version 5 引入，旧配置的每条路由默认指向
+  第一个 key。
+
+## 环境变量
+
+| 变量 | 默认值 | 说明 |
+|------|--------|------|
+| `FLEXGATE_CONFIG` | `~/.flexgate/config.yaml` | 覆盖配置文件路径 |
+
+:::{warning}
+`config.yaml` 已加入 `.gitignore`，不会被提交到 Git。如果 API 密钥曾经
+被推送到远程仓库，请立即轮换（rotate）该密钥。
+:::

flexgate-0.5.1/docs/development.md

@@ -0,0 +1,62 @@
+# 开发与发布
+
+## 项目结构
+
+| 文件 | 作用 |
+|------|------|
+| `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/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/sync.py` | `flexgate sync` — 通过 confsync 服务器加密同步整份配置 |
+| `flexgate/migrate.py` | 配置 schema 版本化：逐级迁移链 + 备份 + 原子重写 |
+| `flexgate/doctor.py` | `flexgate doctor` — 只读诊断 |
+| `flexgate/update.py` | `flexgate update` — PyPI 版本检查、按安装方式升级、配置迁移、服务重载 |
+
+## 关键设计
+
+- **正则路由**：路由按顺序匹配请求体中的 `model` 字段，首个命中生效，
+  末尾用 `".*"` 兜底。
+- **代理改写约定**：上游请求携带 provider 的 `x-api-key` 和固定头集；
+  只有路由显式设置了 `model` 时才改写 JSON 里的 model 字段。流式响应按
+  原始字节转发，不做解析。
+- **Key fallback**：可重试错误（401/402/403/429/500/502/503/529、连接
+  错误、超时）按 `api_keys` 顺序切换重试；流式请求只能在上游返回 200
+  之前切换。
+- **配置版本化**：`config_version` 标记 + `MIGRATIONS` 迁移链，升级时
+  逐级迁移，先备份再原子重写。
+
+## 发布流程（维护者）
+
+仓库托管在 <https://github.com/Agony5757/flexible-gateway>，通过 GitHub
+Actions 自动发布到 PyPI（trusted publishing，无需 API token）：
+
+```bash
+# 1. 修改 flexgate/__init__.py 中的 __version__（唯一版本来源）
+# 2. 提交后打 tag，tag 必须与 __version__ 一致（CI 会校验）
+git tag v0.4.0
+git push origin main --tags
+```
+
+推送 `v*` tag 触发 `.github/workflows/release.yml`：校验 tag 与
+`__version__` 一致 → 构建 sdist/wheel → 发布到 PyPI。首次发布前需在
+PyPI 项目设置中配置 Trusted Publisher（repo:
+`Agony5757/flexible-gateway`，workflow: `release.yml`）。
+
+## 文档构建
+
+文档使用 [Sphinx](https://www.sphinx-doc.org/) + [Furo](https://pradyunsg.me/furo/)
+主题编写，源文件在 `docs/` 目录（MyST Markdown）：
+
+```bash
+pip install -r docs/requirements.txt
+cd docs && make html
+# 打开 docs/_build/html/index.html
+```
+
+推送到 `main`（`docs/**` 变更）或打 `v*` tag 时，`.github/workflows/docs.yml`
+会自动构建并部署到 GitHub Pages。