flexgate 0.4.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.4.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.4.0 → flexgate-0.4.1}/CLAUDE.md

@@ -95,7 +95,7 @@ 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
 

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

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

{flexgate-0.4.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。

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 门禁。

flexgate-0.4.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.4.1/docs/configuration.md

@@ -0,0 +1,116 @@
+# 配置文件
+
+主要运行时资源：
+
+| 文件 | 说明 |
+|------|------|
+| `~/.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"
+  - 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 的模型名 |
+| `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；失败时按列表顺序自动重试后续 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）。
+
+## 环境变量
+
+| 变量 | 默认值 | 说明 |
+|------|--------|------|
+| `FLEXGATE_CONFIG` | `~/.flexgate/config.yaml` | 覆盖配置文件路径 |
+
+:::{warning}
+`config.yaml` 已加入 `.gitignore`，不会被提交到 Git。如果 API 密钥曾经
+被推送到远程仓库，请立即轮换（rotate）该密钥。
+:::

flexgate-0.4.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。

flexgate-0.4.1/docs/index.md

@@ -0,0 +1,52 @@
+# Flexgate 文档
+
+本地 Anthropic API 网关：根据请求中的 model 名称，把流量自动路由到不同的
+provider，并附带 Claude Code `settings.json` 的自动管理、多 key fallback、
+用量查询和配置同步能力。
+
+## 解决什么问题
+
+Claude Code 只能配置一个 `ANTHROPIC_BASE_URL`，所有 tier（opus/sonnet/haiku）
+都指向同一个 provider。Flexgate 在本地启动一个 Anthropic 兼容端点，按 model
+名称把请求路由到不同 provider：
+
+```text
+Claude Code → localhost:8765 → opus  → z.ai (glm-5.1)
+                           → sonnet → minimax (MiniMax-M3)
+                           → haiku  → minimax (MiniMax-M3)
+```
+
+:::{note}
+**运行原则：持久化只走 service。** Linux 上的持久化 serve 只由 systemd 用户
+服务 `flexgate.service` 管理。`flexgate run` 仅用于前台调试。
+:::
+
+## 特性一览
+
+- **按 model 路由**：正则匹配请求中的 model 字段，首个命中生效，支持兜底路由
+- **定时路由**：按时间窗口自动切换路由（支持跨夜，如 22:00-06:00）
+- **多 key fallback**：同一上游配置多个 key，遇到 401/402/403/429/5xx/529
+  或连接错误时自动切换到下一个 key
+- **用量查询**：`flexgate status` / `flexgate usage` 按平台适配器查询每个
+  key 的实时额度（MiniMax、Kimi Code、z.ai、LiteLLM 等）
+- **Claude Code settings 管理**：import / apply 双向同步
+- **配置同步**：`flexgate sync` 通过 confsync 服务器加密同步配置
+- **自愈升级**：`flexgate doctor` 体检、`flexgate update` 一键升级并迁移配置
+
+## 目录
+
+```{toctree}
+:maxdepth: 2
+
+quickstart
+configuration
+cli
+usage
+development
+```
+
+## 链接
+
+- GitHub 仓库：[Agony5757/flexible-gateway](https://github.com/Agony5757/flexible-gateway)
+- PyPI：[flexgate](https://pypi.org/project/flexgate/)
+- 问题反馈：[Issues](https://github.com/Agony5757/flexible-gateway/issues)

flexgate-0.4.1/docs/quickstart.md

@@ -0,0 +1,53 @@
+# 安装与快速开始
+
+## 安装
+
+日常使用推荐从 PyPI 全局安装，并交给 systemd 用户服务管理：
+
+```bash
+pipx install flexgate        # 或: uv tool install flexgate / pip install flexgate
+flexgate config init
+flexgate service install
+```
+
+从源码安装（开发模式）：
+
+```bash
+cd flexible-gateway
+uv sync
+uv tool install -e .
+```
+
+源码开发时也可以直接前台运行：
+
+```bash
+uv run flexgate config init
+uv run flexgate run
+```
+
+## 快速开始
+
+```bash
+# 1. 初始化配置文件（~/.flexgate/config.yaml）
+flexgate config init
+# 编辑 ~/.flexgate/config.yaml 填入你的 API key
+
+# 2. 从已有 Claude Code 配置自动导入（可选）
+flexgate settings import         # 读取 ~/.claude/settings.json* 中的凭证
+
+# 3. 安装并启动唯一的持久化服务
+# install 会询问是否将 Claude Code settings.json 指向本地网关
+flexgate service install
+
+# 4. 如果安装时跳过了 settings 修改，可稍后手动应用
+flexgate settings apply
+```
+
+安装完成后，Claude Code 的请求会经由本地网关按路由规则转发到对应
+provider。日常管理常用：
+
+```bash
+flexgate status                  # providers + fallback 链 + 每个 key 的用量 + 当前路由
+flexgate config edit             # 交互式调整每个 tier 的 provider/model
+journalctl --user -u flexgate -e # 查看服务日志
+```

flexgate-0.4.1/docs/requirements.txt

@@ -0,0 +1,4 @@
+sphinx
+furo
+myst_parser
+linkify-it-py

flexgate-0.4.1/docs/usage.md

@@ -0,0 +1,43 @@
+# 用量查询
+
+`flexgate status` 和 `flexgate usage` 会逐一查询**每个 key** 的用量/额度。
+各平台的查询方式差异很大（有的平台根本没有可用的接口），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 再试
+一次。
+
+:::{caution}
+用量查询接口多为平台内部接口，可能随时变动；查询结果仅供参考。
+:::
+
+## 输出示例
+
+```text
+Usage (timeout 15s per key):
+  minimax:
+    ✓ key #1 (sk-c***abcd) [main]  [MiniMax coding_plan API]
+        MiniMax-M3: 5h window remaining 450/450 (reset 08-24 00:00); weekly remaining 900/900 (reset 08-24 00:00)
+  kimi:
+    ✓ key #1 (sk-k***66N6) [ywj]  [Kimi Code usages API (unofficial)]
+        plan: advanced
+        weekly remaining 63/100 (reset 08-28 22:17)
+        5h window remaining 74/100 (reset 08-23 14:17)
+        parallel limit: 30
+```
+
+## 新增平台适配器
+
+适配器登记在 `flexgate/usage.py` 的 `_ADAPTERS` 列表中：每条是
+`(url 子串, 适配器协程, 方法标签)`，首个命中生效。已知没有 key 可用接口的
+平台放入 `_PROBE_ONLY_MARKERS`，直接走 probe，避免浪费一次失败的 HTTP
+请求。

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

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

{flexgate-0.4.0 → flexgate-0.4.1}/flexgate/update.py

@@ -5,6 +5,9 @@
 1. package — detect how flexgate was installed (pipx / uv tool / pip) and
    upgrade to the latest release published on PyPI;
 2. config — apply pending config.yaml schema migrations (with backup).
+   When the package was just upgraded, this half is delegated to a fresh
+   process so the migration runs with the NEW code's schema version,
+   not the stale one still loaded in this process.
 
 Use ``--check`` to only report what would change.
 """
@@ -123,6 +126,7 @@ def run_update(config_path: str, *, check: bool = False, config_only: bool = Fal
 
     print(f"flexgate {__version__} (config schema v{CURRENT_CONFIG_VERSION})")
     failures = 0
+    package_upgraded = False
 
     # ── package update ────────────────────────────────────────────
     latest = fetch_latest_version()
@@ -150,9 +154,22 @@ def run_update(config_path: str, *, check: bool = False, config_only: bool = Fal
                     else:
                         print(f"  Upgraded to {latest}. Restart the service to use it:")
                         print("    flexgate service restart")
+                        package_upgraded = True
 
     # ── config migration ──────────────────────────────────────────
     print()
+    if package_upgraded and not os.environ.get("FLEXGATE_UPDATE_DELEGATED"):
+        # This process still runs the OLD code: its CURRENT_CONFIG_VERSION and
+        # MIGRATIONS chain predate the release just installed, so an outdated
+        # config would be misreported as current (e.g. "schema v2 is current"
+        # right after upgrading to a v4 release). Hand the migration to the
+        # new code in a fresh process. The env guard prevents re-delegation
+        # if the upgrade somehow left an older version installed.
+        cmd = [sys.executable, "-m", "flexgate", "--config", config_path, "update", "--config-only"]
+        env = dict(os.environ, FLEXGATE_UPDATE_DELEGATED="1")
+        proc = subprocess.run(cmd, env=env)
+        return proc.returncode or (1 if failures else 0)
+
     if not os.path.exists(config_path):
         print(f"Config: {config_path} not found — nothing to migrate.")
         return 1 if failures else 0