开发与发布¶

项目结构¶

文件	作用
`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 兜底 + 查询失败缓存（`usage --force` 强制重查）
`flexgate/server.py`	Starlette 应用，`POST /v1/messages` + `POST /v1/images/{generations,edits}` 端点，SIGUSR1 热重载
`flexgate/images.py`	OpenAI Images API → MiniMax `/v1/image_generation` 翻译（模型名映射、size 钳制、`b64_json` 透传；edits 返回 501）
`flexgate/fallback.py`	兜底路由：所有未服务路径返回 Anthropic/OpenAI 双兼容的结构化 JSON 错误（404 `route_not_found` / 405 / 501 `endpoint_not_supported`）
`flexgate/main.py`	启动引导：加载配置 → 创建 app → 跑 uvicorn
`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` — 只读诊断 + 上游连通性（`--offline` 跳过网络检查）
`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）：

# 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 + Furo 主题编写，源文件在 docs/ 目录（MyST Markdown）：

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。