docs: record approval, verification evidence and a follow-up gap

Corrects the changelog claim that the old guard messages only named env keys:
they named fields too, it was the remediation advice that pointed at env keys.

Records the human approval of the design, the mutation-testing evidence from
the independent verifier, and the same-class gap it found: 14 checks (redis_url
presence, telemetry paths, enum validity) still live only in from_env, while
client.py asserts they were already validated. Deliberately out of scope here.

CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## 1.0.1(2026-07-30)
+
+### 修复
+
+- **装配守卫在任何构造路径上都生效,不再只在 `from_env` 上。** 三条跨字段不变量(源 `timeout_s` ≤ `lease_ttl_s`、`stall_window_s` ≥ 最大源 TTFT、`probe_ttl_s` ≥ 最慢源 `timeout_s` + 5)原先只在 `GatewaySettings.from_env` 里校验,而装配有两条官方路——走 `from_settings()` 或直接构造能装出违反不变量的配置且不报错,故障留到运行时才表现为:租约先于请求过期使并发悄悄超出配额、正常慢首包被误判卡死掐断、半开探针在途即被接管。守卫已收进 `GatewaySettings.__post_init__`,与 `types.py` 各子配置一致,三个 client(Gateway/Ocr/Embedding)的全部工厂一并覆盖。
+- 新增 `sources` 非空校验。此前零源配置只在 `from_env` 路径被拦,直接构造可装出必然选源失败的 client。
+
+### 行为收紧(下游请读)
+
+直接构造 `GatewaySettings` 或对它做 `dataclasses.replace` 时,若上述组合非法,**现在会在构造期抛 `ValueError`**,而不是留到运行时。经 `from_env()` 装配的调用方**不受影响**——那条路本就跑这些守卫。手工拼配置(如从 YAML 读出后构造)的调用方若此前撞上过上述任一故障,升级后会在启动时立即得到点名字段的报错。
+
+守卫报错文案的**补救建议**改为点字段名(`lease_ttl_s`、`backpressure.stall_window_s`、`breaker.probe_ttl_s`)。原文案已点出字段名,但建议部分给的是环境变量键(如"调大 `PGW_LEASE_TTL_S`"),而不走 env 的调用方从没设过那些键。键名映射见 `.env.example` 与 wiki `参考-配置键`。
+
 ## 1.0.0(2026-07-22)
 
 首个正式版。统一 LLM/VLM/OCR/Embedding 调度与中转库,治理单位为一次模型调用;经 GovDoc-SaaS 与 CHSAnalyzer 两个真实项目全量迁移验收(ARCHITECTURE §11)。

CLAUDE.md

@@ -112,6 +112,7 @@ project_root/
 | 三项目迁移文档(ARCHITECTURE §11 的展开,库设计的常驻约束) | `research-wiki/migrations/`(govdoc-saas / video-tree-trm5 / chsanalyzer) |
 | 功能设计文档(每次实现新功能时新增) | `research-wiki/designs/` |
 | 实现计划 | `research-wiki/plans/` |
+| **用户文档站**(Gitea Wiki,Diátaxis 四区)结构/更新时机/写作纪律 | `research-wiki/docs-convention.md`;**发版或公共行为变更必须按其 §2 清单同步 wiki 与 CHANGELOG,版本 bump 提交不得裸发** |
 | 治理网关参考实现 | `reference/Video-Tree-TRM5/adapters/`(llm/breaker/streaming/redis_cache/telemetry) |
 | 分布式限流/熔断参考实现 | `reference/CHSAnalyzer/app/coordination/`(limiter+Lua/provider_gate)与 `app/providers/governance.py` |
 | 错误分类参考 | `reference/CHSAnalyzer/app/domain/errors.py` |

README.md

@@ -0,0 +1,203 @@
+# PolyGateway
+
+实验室统一的大语言模型调度与中转库:LLM / VLM / OCR / Embedding 四类调用共用同一套生产级治理栈——多源多账号、限流、错误分类重试、熔断、响应缓存、流式看门狗、遥测与成本。治理单位是**一次模型调用**;任务编排、业务解析、图像预处理都留在业务侧。
+
+> 由三个真实项目(GovDoc-SaaS / CHSAnalyzer / Video-Tree-TRM5)各自手写的治理栈提炼而来,并以"能否全量迁移回这三个项目"作为验收标准。v1.0.0 已通过 GovDoc 与 CHSAnalyzer 两项目的全量迁移验收(约 −6800 行项目侧治理代码由本库继任)。
+
+## 为什么需要它
+
+每个接入大模型的项目都会重写同一批东西:重试循环、429 处理、熔断器、SSE 解析、遥测埋点——写三遍就有三份 bug。本库把这些收敛为一份经过压测验证的实现:
+
+| 能力 | 说明 |
+|---|---|
+| 多源多账号 | `{SCOPE}__{PROVIDER}__{N}__*` 配置任意多源;健康感知选源(EWMA×在途 P2C)自动避开坏源 |
+| 限流 | 并发/RPM/TPM × 全局/单源六道闸;TPM 预扣入场、按实际用量结算退款;Redis 后端跨进程原子(Lua) |
+| 错误分类重试 | 一切失败落入四分类(见下),由分类决定重试/换源/熔断;429 属 pushback 不消耗重试预算;退避含 jitter 且尊重 Retry-After |
+| 熔断 | 双通道(连续失败 + 失败率窗口,健康证据抑制误熔);半开单探针带租约(持有者死亡自动回收);epoch fencing 拒绝迟到写回;开路时长指数递增 |
+| 自适应并发 | AIMD:429 削减、成功缓升,防止打爆上游 |
+| 响应缓存 | Redis/内存;key 含 model + messages 摘要 + namespace/租户 + salt,多模态 content 先摘要再 hash(防毒化);可 per-call 绕过(科研重采样) |
+| 流式看门狗 | TTFT / inter-token / 总超时三层活性;thinking token 刷活性不计结果;截断流(缺 `[DONE]`)判瞬时不入缓存 |
+| 遥测与成本 | 每次调用(含缓存命中与失败)必录 18 字段;SQLite / Postgres 后端;按价格表折算成本;多模态内容摘要落库不存原图 |
+| 结构化输出 | json_repair 修复 / 原生 schema 双策略 + 校验失败有界带反馈重问 |
+| OCR | MonkeyOCR 双端点(文本转录 + 版面解析),bbox 数值防御下沉,逐源健康预检 `check_health()` |
+| Embedding | 分批、维度校验、与 chat 同一治理栈 |
+
+**降级方向是铁律**:缓存/遥测后端掉线 → 静默降级(warning);限流/熔断后端掉线 → 报错而非放行(防击穿上游)。`asyncio.CancelledError` 全链路穿透,in-flight 资源在 finally 释放。
+
+## 安装
+
+发布在实验室 Gitea PyPI(公开包,匿名可装):
+
+```bash
+pip install --extra-index-url https://gitea.iomgaa.online/api/packages/iomgaa/pypi/simple/ \
+    "polygateway[redis,postgres,structured]==1.0.*"
+```
+
+核心仅依赖 `httpx` + `pydantic`;按需选 extras:
+
+| extra | 内容 | 何时需要 |
+|---|---|---|
+| `redis` | redis-py | Redis 限流/熔断/缓存后端 |
+| `postgres` | asyncpg | Postgres 遥测后端 |
+| `structured` | json-repair | 结构化输出的修复策略 |
+| `sdk` | openai | 可选的 SDK transport(默认手写 httpx,不需要) |
+
+要求 Python ≥ 3.11。
+
+## 快速开始
+
+### 1. 配置 `.env`
+
+```bash
+LLM__MINIMAX__1__BASE_URL=https://your-gateway/v1
+LLM__MINIMAX__1__API_KEY=sk-xxx
+LLM__MINIMAX__1__MODEL=MiniMax-M3
+LLM__MINIMAX__1__TIMEOUT_S=120
+LLM_MAX_RETRIES=3
+LLM_RETRY_BASE_DELAY=2.0
+LLM_RETRY_MAX_DELAY=30.0
+LLM_CIRCUIT_BREAKER_THRESHOLD=5
+LLM_CIRCUIT_BREAKER_COOLDOWN=60
+PGW_LIMITER_BACKEND=memory
+PGW_BREAKER_BACKEND=memory
+PGW_CACHE_BACKEND=none
+PGW_TELEMETRY_BACKEND=none
+```
+
+缺任何关键键都会在装配时报错——本库禁止默认值兜底掩盖配置缺失。
+
+### 2. 发起治理调用
+
+```python
+from polygateway import GatewayClient
+
+async def main() -> None:
+    client = GatewayClient.from_env("LLM")   # 读 .env 装配整套治理栈
+    try:
+        resp = await client.chat([{"role": "user", "content": "你好"}])
+        print(resp.content, resp.source_name, resp.latency_ms)
+    finally:
+        await client.aclose()                # 归还连接与治理后端资源
+```
+
+`chat()` 原生接受 OpenAI 多模态 content 数组(`image_url` data URL),VLM 调用无需专门客户端;`session_id` / `parent_call_id` / `cache_salt` 关键字参数用于链路追踪与缓存控制。
+
+### 3. OCR 与 Embedding
+
+```python
+from polygateway import EmbeddingClient
+from polygateway.ocr import OcrClient
+
+ocr = OcrClient.from_env("OCR")            # OCR__MONKEY__1__* 多源
+text = await ocr.recognize_text(image_bytes)          # 文本转录
+layout = await ocr.parse_layout(image_bytes)          # 版面解析(带 bbox 的元素列表)
+health = await ocr.check_health()                     # 逐源预检 {"monkey_1": True, ...}
+
+embed = EmbeddingClient.from_env("EMBED")  # EMBED__*__* + EMBED__BATCH_SIZE
+vectors = (await embed.embed(["文本 a", "文本 b"])).vectors
+```
+
+### 4. 业务侧异常处理
+
+```python
+from polygateway import GatewayUnavailableError, RequestRejectedError
+
+try:
+    resp = await client.chat(messages)
+except GatewayUnavailableError as exc:
+    # 整个 scope 暂时无源可用: 延期重投,不消耗业务失败预算
+    schedule_retry(after_s=exc.retry_after_s)   # exc.reason / exc.per_source_reasons 供诊断
+except RequestRejectedError:
+    ...  # 请求本身有问题(400/格式拒绝): 不重试,直接失败
+```
+
+## 错误模型(四分类)
+
+一切失败在 transport 层翻译为四类之一,治理行为由分类决定,业务侧不需要判断状态码:
+
+| 分类 | 含义 | 库内行为 |
+|---|---|---|
+| `TransientError` | 超时/5xx/网络抖动/截断流 | 换源重试 + 退避 |
+| `SourceDeadError` | 401/403/欠费(429+insufficient_quota) | 立即熔断该源 + 换源 |
+| `RequestRejectedError` | 400/内容拒绝/本地格式拒绝 | 不重试不换源,快速失败 |
+| `ResultInvalidError` | 调用成功但结果不合格(坏 JSON/维度不符/坏 bbox) | 不熔断("坏结果 ≠ 坏服务"),按策略有界重问或上抛 |
+
+预算耗尽/全源熔断时抛 `GatewayUnavailableError` 族(`CircuitOpenError` / `AllSourcesExhausted`),携带 `scope` / `reason` / `retry_after_s` / `per_source_reasons`,供任务队列做延期重投。
+
+## 配置参考
+
+配置只有两条装配路径:`from_env()`(读 `.env`/环境变量)或构造函数全量注入(测试/高级);库内部任何组件不自读环境变量。键名全集见 [.env.example](.env.example),约定速览:
+
+| 键形态 | 作用 |
+|---|---|
+| `{SCOPE}__{PROVIDER}__{N}__{FIELD}` | 第 N 个源;FIELD ∈ BASE_URL/API_KEY/MODEL/TIMEOUT_S/MAX_CONCURRENCY/RPM/TPM/EST_TOKENS/TTFT_TIMEOUT_S/INTER_TOKEN_TIMEOUT_S/ENABLE_THINKING/TRUST_ENV |
+| `{SCOPE}__GLOBAL__*` | scope 级全局限额(跨源并发/RPM/TPM) |
+| `{SCOPE}__RETRY__*` / `BREAKER__*` / `BACKPRESSURE__*` / `SELECTOR` | per-scope 韧性参数;缺省回落平铺键(`LLM_MAX_RETRIES` 等,兼容旧项目习惯) |
+| `PGW_LIMITER_BACKEND` / `PGW_BREAKER_BACKEND` | `memory`(单进程)或 `redis`(跨进程共享,需 `REDIS_URL`) |
+| `PGW_CACHE_BACKEND` | `none` / `redis`(需 `PGW_CACHE_NAMESPACE` + `PGW_CACHE_TTL_S`) |
+| `PGW_TELEMETRY_BACKEND` | `none` / `sqlite`(需 `PGW_TELEMETRY_SQLITE_PATH`)/ `postgres`(需 `PGW_TELEMETRY_PG_DSN`) |
+
+`SCOPE` 是逻辑角色(LLM/VLM/OCR/EMBED/JUDGE/SEARCH…任意大写名),同一进程可按角色装配多个 client,各自独立配置与治理状态。
+
+## 架构
+
+端口适配器 + 中间件洋葱:决策逻辑一份,状态存储可插拔。
+
+```mermaid
+graph LR
+    A[业务代码] --> B[GatewayClient]
+    B --> C[缓存 MW] --> D[遥测 MW] --> E[重试/选源/限流/熔断 MW]
+    E --> F[Transport httpx]
+    F --> G[(上游网关)]
+    E -.端口.-> H[(内存 / Redis 后端)]
+    D -.端口.-> I[(SQLite / Postgres)]
+```
+
+| 模块 | 职责 |
+|---|---|
+| `types.py` / `errors.py` / `ports.py` | 内核:冻结类型、四分类异常、全部 Protocol(最内层,不依赖任何实现) |
+| `middleware/` | 治理算法(重试/限流/熔断/缓存/遥测),只面向端口 |
+| `transports/` | 协议细节:OpenAI 兼容 SSE、MonkeyOCR 双端点;错误翻译在此层 |
+| `backends/` | 限流/熔断/缓存的内存与 Redis 实现(同一契约测试套件双后端共用) |
+| `telemetry/` | SQLite / Postgres 遥测后端 |
+| `structured/` | 结构化输出策略 |
+
+依赖纪律由 import-linter 机械化执法(`make lint`)。完整架构决策(D1-D14 含论证过程)见 [research-wiki/ARCHITECTURE.md](research-wiki/ARCHITECTURE.md)。
+
+## 可靠性证据
+
+行为不是宣称出来的,是压测出来的(数字见 `research-wiki/findings/`):
+
+| 场景 | 结果 |
+|---|---|
+| 故障混编 soak(坏 key/黑洞/慢源/限流源混合,8000 调用) | 成功率 98.96%,坏源吸流被压制,真实源零误熔 |
+| OCR 故障池 soak(1500 调用,redis 双后端跨进程) | 成功率 99.73%,13 项不变量全过(租约归零/探针不悬挂/零取消泄漏等) |
+| 两项目全量迁移回归 | 原测试全绿 + 真实链路冒烟 + 50 样本批跑 100% 解析 |
+
+时间语义测试(租约过期、窗口滚动、半开探针)全部真实等待不缩放;Redis/Postgres 测试打真实实验室后端,不 mock Lua。
+
+## 开发
+
+```bash
+conda create -n PolyGateway python=3.11 && conda activate PolyGateway
+make install   # editable 安装(dev + 全部 extras)
+make test      # pytest + 覆盖率(目标 ≥80%)
+make lint      # ruff + import-linter
+make ci        # 只读全量验证
+```
+
+测试组织:`tests/{unit,integration,e2e}` + 双后端契约测试;并发/取消/降级方向是一等测试对象。压测 harness 在 `tools/soak/`。贡献流程与项目纪律见 [CLAUDE.md](CLAUDE.md)。
+
+## 文档导航
+
+| 想了解 | 看 |
+|---|---|
+| 全部架构决策及理由(单一事实源) | `research-wiki/ARCHITECTURE.md` |
+| 里程碑与状态 | `research-wiki/ROADMAP.md` |
+| 项目迁移指南(删除清单/组件映射/行为审计) | `research-wiki/migrations/` |
+| 每个功能的设计与验收记录 | `research-wiki/designs/`、`research-wiki/findings/` |
+| 版本变更 | [CHANGELOG.md](CHANGELOG.md) |
+
+## 兼容性承诺
+
+`LLMResponse` 等被下游消费的公共类型,字段**只增不删不改名**且新增字段必带默认值;`{SCOPE}__{PROVIDER}__{N}__{FIELD}` 与平铺韧性键名(`LLM_TIMEOUT` 等)沿用三项目既有习惯,不做破坏性改名。实验室内部库,随实验室项目需求演进。

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "polygateway"
-version = "1.0.0"
+version = "1.0.1"
 description = "PolyGateway：实验室统一的大语言模型（LLM/VLM/OCR）调度与中转库——多源、限流、重试、熔断、缓存、遥测"
 requires-python = ">=3.11"
 dependencies = [

research-wiki/designs/2026-07-29-settings-invariant-guards-design.md

@@ -0,0 +1,151 @@
+# GatewaySettings 跨字段不变量守卫的生效范围
+
+- **日期**: 2026-07-29;**状态**: **已批准并实施**(2026-07-29 人类门通过;§8 结论见文末)
+- **范围拍板**(用户 2026-07-29): 功能对齐社区 PR#1,但按本库规范重写;顺带销掉 PR#1 遗留的两个缺陷
+- **上游依据**: ARCHITECTURE §7.3 契约补强 G6(装配期守卫,"违反直接报错拒绝装配")、§9 配置聚合、CLAUDE.md §4.5(装配只有两条路)、`types.py` 同族 frozen dataclass 的既有校验笔迹
+
+## 1. 缺陷取证(全部本地实测,worktree @ f76a89b 与 main 对照)
+
+`GatewaySettings` 有三条**跨字段**不变量——单个字段合法、组合起来才非法,因此 `types.py` 各子配置的 `__post_init__` 管不到,只能在聚合层管:
+
+| 不变量 | 现居位置 | 违反后的运行时后果 |
+|---|---|---|
+| 源 `timeout_s` ≤ `lease_ttl_s` | `_guard_lease`,仅 `from_env` 调用 | 租约先于请求过期,名额被放给他人 → 实际并发超配额,击穿网关 |
+| `backpressure.stall_window_s` ≥ 最大源 `ttft_timeout_s` | `_guard_stall`,仅 `from_env` 调用 | 正常慢首包被误判卡死掐断 |
+| `breaker.probe_ttl_s` ≥ 最慢源 `timeout_s` + 5 | `_load_breaker` 内联,仅 `from_env` 路径 | 半开探针在途即被接管(M2 设计 §3 原文) |
+
+三条守卫都只挂在 `from_env` 上,而 CLAUDE.md §4.5 规定装配有**两条**官方路。走 `from_settings()` 能装出违反上述任一条的配置且不报错——类可以合法地存在于它自己 docstring 声称不可能的状态。
+
+实测(在 PR#1 分支上,即已修前两条之后):
+
+| 构造方式 | 结果 |
+|---|---|
+| `replace(base, breaker=replace(base.breaker, probe_ttl_s=1.0))`(最慢 timeout 120s) | **未拦截**,装配成功 |
+| `replace(base, sources=())` | `ValueError: max() arg is an empty sequence` —— 内置异常泄漏,既不点字段也不说原因 |
+
+第一条说明 PR#1 的搬迁不完整:它的全部论证同等适用于 `probe_ttl_s`,却只搬了两条。第二条是 PR#1 **新引入**的失败模式——`max()` 此前只在 `_load_sources` 保证非空之后才执行,守卫上移到构造期后失去了这个前提。
+
+另有一条隐性不变量此前从未表达:**`sources` 不得为空**。`from_env` 路径由 `_load_sources` 显式拦截,直接构造路径无人把关,零源的 client 装出来后选源必然失败。
+
+## 2. 备选方案对比
+
+| 方案 | 做法 | 权衡 |
+|---|---|---|
+| **A. `__post_init__` 集中校验(推荐)** | 三条跨字段守卫 + 空源检查全部收进 `GatewaySettings.__post_init__`,拆为 `_validate_sources/_validate_lease/_validate_stall/_validate_probe` 私有方法 | 与 `types.py` 同族五个 frozen dataclass 的既有笔迹完全一致;一处覆盖全部构造路径(六个工厂 + 直接构造 + `dataclasses.replace`);代价是收紧了构造承诺(见 §4) |
+| B. 各工厂入口显式调用 `settings.validate()` | 三个 client × 两个工厂,六处各加一行 | 不改构造承诺,零 breaking;但六处要永久保持同步,新增第四个 client 时必漏——正是"每个调用方各维护一份副本"的毛病挪进库里。且 `dataclasses.replace` 仍能绕过。**否决** |
+| C. 公共 `settings.validate()`,由调用方自愿调 | 提供校验入口,不强制 | 把类不变量降级成"建议";违反 P5 防御性(外部输入校验后使用)与 ARCHITECTURE §7.3"违反直接报错拒绝装配"。**否决** |
+
+方案 A 与 `SourceConfig.__post_init__` 同构。选它的核心理由不是"少写五行",是**不变量的归属**:这三条约束是 `GatewaySettings` 这个类的定义的一部分,不是 `from_env` 这个函数的输入检查。放在函数里,类就失去了自我描述能力。
+
+### 2.1 子决策:守卫的代码形态
+
+`config.py` 现有 `_guard_lease(settings)` / `_guard_stall(settings)` 两个模块级函数,把自身实例传回给模块级函数是绕路。`types.py` 的既有做法是私有方法(`SourceConfig` 拆三个 `_validate_*`)。**改为私有方法**,与同族一致;模块级 `_guard_*` 一并删除(无其他调用点)。
+
+### 2.2 子决策:`probe_ttl_s` 的派生逻辑留在哪
+
+`_load_breaker` 对该字段做了两件事:未配置时**派生**(`max(2*slowest, cooldown_s, probe_floor)`,派生规则本身保证守卫恒成立)、显式配置时**校验**。派生需要读 env,必须留在 `_load_breaker`;校验上移到 `__post_init__` 后,`_load_breaker` 内联的那份校验删除(避免同一约束两处维护)。派生分支上移后仍恒过,无行为变化。
+
+### 2.3 子决策:错误消息里是否列 env 键名
+
+**不列。** 三条理由:(1) `types.py` 全部校验消息只点字段名,是既有笔迹;(2) 守卫现在服务两类调用方,env 键对手工拼 settings 的那类是不可执行的建议;(3) 键名的单一事实源是 `.env.example` 与 wiki `参考-配置键`,消息里复制一份即双处维护。消息格式沿用既有句式:`字段名(值)须 …;调大 X 或调小 Y`。
+
+> 与 PR#1 的差异:PR#1 选择"点字段名 + 括号附 env 键",单行超 100 字符且把 `{SCOPE}__{PROVIDER}__{N}__TIMEOUT_S` 模板塞进运行时消息。本方案只留字段名。
+
+## 3. 行为审计(逐条标注)
+
+不是从 `reference/` 迁移,是既有模块的行为收紧,故审计对象为现有 `from_env` 路径的全部可观测行为:
+
+| 现有行为 | 处置 |
+|---|---|
+| `from_env` 装配非法 lease/stall 组合 → `ValueError` | **保留**(改由 `__post_init__` 抛,时机提前到 `cls(...)` 那一行,对调用方不可见) |
+| `from_env` 配了过小 `PROBE_TTL_S` → `ValueError` | **保留**(同上,消息中不再含 env 键名 —— 有意变更,§2.3) |
+| `from_env` 未配 `PROBE_TTL_S` → 派生值 | **保留**,派生规则一字不改 |
+| `from_env` 未配任何源 → `ValueError: scope X 未配置任何源` | **保留**,`_load_sources` 的检查不动(它能给出键名模板,信息量高于构造期检查) |
+| 直接构造/`replace` 出非法组合 → 静默成功 | **有意替换**为构造期 `ValueError`(本设计的目的) |
+| 直接构造空 `sources` → 静默成功 | **有意替换**为构造期 `ValueError`,消息点明"至少一个源" |
+| 三条守卫的异常类型 `ValueError` | **保留**。装配期错误不入 `errors.py` 四分类(四分类描述的是一次调用的失败),与 `_load_sources`/`types.py` 既有装配错误一致 |
+| `GatewaySettings` 字段名与类型 | **不动**。迁移兼容约束(CLAUDE.md §4.3 例外条款)只增不删不改名,本次零字段变更 |
+
+**有意放弃**:不提供 `strict=False` 之类的逃生开关。装出必然故障的配置没有正当用例。
+
+## 4. 对下游的承诺变化(人类门要审的就是这条)
+
+| 调用方式 | 影响 |
+|---|---|
+| `GatewayClient.from_env()` / `OcrClient.from_env()` / `EmbeddingClient.from_env()` | **零影响**,该路径本就跑这些守卫 |
+| `*.from_settings(settings)`,settings 来自 `from_env` | **零影响** |
+| 手工构造 `GatewaySettings(...)` 或 `dataclasses.replace(...)`,组合合法 | **零影响** |
+| 手工构造/`replace`,组合非法 | **行为变更**:构造期抛 `ValueError`,不再留到运行时表现为超配额/误判卡死/探针被接管 |
+
+已知受影响的下游:CHSAnalyzer 重建中的 YAML → 直接构造 → `from_settings()` 路径(PR#1 提交者正是在此撞上的)。该路径若配置合法则不受影响,若非法则从"静默故障"变为"启动即报错"——方向是收益。
+
+版本:**1.0.1**(patch,用户 2026-07-29 拍板)。设计初稿曾建议 minor(构造期新抛 `ValueError` 是可观测的收紧),用户判定受影响面仅限"手工拼出非法配置"这一本就故障的路径,按修复发 patch。CHANGELOG 必须把行为收紧单列小节,不能只混在"修复"里——patch 号不会给下游预警,changelog 是唯一的告知渠道。
+
+发版时按 `docs-convention` §2 末行过发布清单;wiki `参考-配置键` 页现有表述("须 ≤ `PGW_LEASE_TTL_S`""须 ≥ 最大源 TTFT")与新行为一致,**无需改动内容**。
+
+## 5. 非功能维度
+
+| 维度 | 回答 |
+|---|---|
+| 并发与取消 | **不适用但需写明**:`__post_init__` 是同步纯计算(只读自身字段做比较),无 I/O、无 await、无锁,不存在取消穿透点。不引入任何全局状态,纯 asyncio 中立铁律不受影响 |
+| 降级方向 | 装配期校验属**准入侧**,按库铁律"报错而非放行"。无后端依赖,无降级分支 |
+| 幂等与重复 | `__post_init__` 不修改任何字段(frozen 也不允许),重复构造同一配置得同一结果;校验本身无副作用 |
+| 持久化与原子性 | 不适用,配置对象不落盘 |
+| 性能 | 每次构造增加三次 `max()` 遍历 sources(典型 1-4 个源)。`GatewaySettings` 只在装配期构造,不在请求路径上,可忽略 |
+
+## 6. 测试策略
+
+`tests/unit/test_config.py` 新增一个测试类,覆盖矩阵为 **4 条不变量 × 2 条构造路径**:
+
+| 用例 | 断言 |
+|---|---|
+| 三条守卫各自:`dataclasses.replace` 构造出违反组合 | 抛 `ValueError`,消息含对应字段名 |
+| 三条守卫各自:边界值恰好相等(`timeout_s == lease_ttl_s` 等) | **构造成功**——守卫收紧的是错的那些,不是所有直接构造 |
+| `sources=()` | 抛 `ValueError`,消息点明"至少一个源",**且不是 `max() arg is an empty sequence`** |
+| `GatewayClient.from_settings(非法 settings)` | 抛 `ValueError`。**注意抛点**:方案 A 之下非法实例根本无法存在,异常发生在实参求值(构造 settings)那一刻,不在工厂内部——这正是构造期把关换来的性质,测试 docstring 须写明,以免后人误读为工厂自带校验 |
+| `OcrSettings` / `EmbeddingSettings` 直接构造包着非法 gateway | 抛 `ValueError`(证明三条 client 线一并覆盖) |
+| 既有 447 passed / 34 skipped | 全绿,零回归 |
+
+TDD 顺序:先写测试跑出预期失败(预计 3 条守卫 + 空源 + from_settings 端到端 共失败 6 条以上),再实现,再全绿。测试不新增 mock,全部用既有 `_env()` helper 构造真实 settings 再派生。
+
+## 7. 与 PR#1 的关系
+
+功能对齐,不是推翻。PR#1 的问题诊断完全正确,本设计沿用其核心结论(守卫属于类不变量,应在构造期生效),差异集中在:
+
+| 维度 | PR#1 | 本设计 |
+|---|---|---|
+| 覆盖的不变量 | 2 条 | 4 条(补 `probe_ttl_s`、空 sources) |
+| 代码形态 | 保留模块级 `_guard_*(settings)` | 改为 `_validate_*` 私有方法,同 `SourceConfig` |
+| docstring | 引用 `CLAUDE.md §4.5`(下游读者看不到该文件)、带论证口吻 | 只引 ARCHITECTURE §7.3 与自身概念,解释"为什么"不复述辩论 |
+| 错误消息 | 字段名 + 附 env 键模板 | 只点字段名(§2.3) |
+| 测试 | 4 条,全走 `replace`,其中 1 条同义反复 | 覆盖 4 不变量 × 2 路径 + 边界值 + 三条 client 线 |
+| 导入位置 | 两处函数内 `import dataclasses` | 文件顶部 |
+
+合并后应关闭 PR#1 并在其中说明:诊断被采纳,实现按库内规范重写并扩展了覆盖范围。
+
+## 8. 人类拍板结论(2026-07-29)
+
+| 问题 | 结论 |
+|---|---|
+| 主决策 | **接受方案 A**,构造期强制,承诺收紧 |
+| 范围 | **全量**:`probe_ttl_s` 与空 sources 一并纳入 |
+| 消息文案 | **去掉 env 键名**,只点字段名(§2.3) |
+| 版本 | **1.0.1**(patch);初稿建议的 minor 被否,理由与代偿见 §4 |
+| PR#1 处置 | 重写合并后关闭并说明,诊断归功于提交者 |
+
+## 9. 实施与验证留痕
+
+实施于 `fix/settings-invariant-guards`(5 commits)。TDD 证据:新测试类先 **6 failed / 3 passed**(3 条为边界护栏,本就应过),实现后全绿。
+
+独立 verifier(全新上下文)核验结论 **可以合并,无阻塞**,其中两项证据值得留档:
+
+- **变异测试 12/12 全杀**:逐个破坏实现(删各 `_validate_*` 调用、`>`↔`>=`、`<`↔`<=`、删空源检查、`_PROBE_GRACE_S` 归零)均有测试失败,无一存活。边界侧用例(恰好相等必过)对每条守卫都真实有效,差一错误可捕获。
+- **无热路径回归**:库内**没有任何地方**构造或 `replace` `GatewaySettings`(`src/` 中 4 处 `dataclasses.replace` 全在 `middleware/structured.py`,作用于 `ChatRequest`/`LLMResponse`)。单次构造实测 1.45 µs,装配期一次性成本。`pickle`/`deepcopy` 不触发 `__post_init__`,只有 `replace` 触发——序列化往返既无额外开销也不构成二次守卫点。
+
+### 9.1 verifier 发现的同族遗漏(范围外,另起任务)
+
+`GatewaySettings` 仍有 **14 条校验只挂在 `from_env`**,直接构造/`replace` 全部放行,与本设计所修的是同一个 bug 类:`limiter/breaker/cache_backend=redis` 但 `redis_url=None`、`telemetry_backend=sqlite/postgres` 但 path/dsn 为 None、`selector`/`quota_full`/各 backend 的枚举合法性、`structured_max_retries` 负值、`scope` 空串等。
+
+严重性高于本次所修的三条,因为 `client.py:262/282/302/312/316` 有 5 处 `assert ... # 内部不变量: config 已校验` **明文依赖这个前提**,而该前提在 `from_settings` 路上为假:断言开启时抛裸 `AssertionError`(不点字段不说原因),`python -O` 下断言消失、错误退化为 redis 库抛出的天书。后者同时违反 CLAUDE.md §4.3"禁止 assert 承担生产校验"。
+
+**有意不纳入本次交付**(避免任务外扩张),另起任务处理。

research-wiki/designs/settings-invariant-guards.md

@@ -0,0 +1,18 @@
+---
+type: design
+node_id: design:settings-invariant-guards
+title: "GatewaySettings 跨字段不变量守卫的生效范围"
+date: 2026-07-29
+---
+
+# GatewaySettings 跨字段不变量守卫的生效范围
+
+全文见 [2026-07-29-settings-invariant-guards-design.md](2026-07-29-settings-invariant-guards-design.md)。
+
+- **缘起**: 社区 PR#1 指出装配守卫只挂在 `from_env`,走 CLAUDE.md §4.5 的另一条官方路 `from_settings()` 能装出违反类不变量的配置且不报错。诊断采纳,实现按库内规范重写并扩大覆盖。
+- **选定方案**: A——四条跨字段不变量(lease/stall/probe_ttl/sources 非空)全部收进 `GatewaySettings.__post_init__`,拆 `_validate_*` 私有方法,与 `types.py` 同族五个 frozen dataclass 的既有笔迹一致;模块级 `_guard_lease/_guard_stall` 删除。
+- **关键理由**: 这三条约束是**类的定义**的一部分,不是 `from_env` 的输入检查;放在函数里类就失去自我描述能力。构造期一处覆盖六个工厂 + 直接构造 + `dataclasses.replace`。
+- **被否决备选**: B 六个工厂各调 `validate()`(六处永久同步,新增 client 必漏,`replace` 仍绕过);C 公共 `validate()` 自愿调用(把不变量降级为建议,违反 P5 与 ARCH §7.3"拒绝装配")。
+- **补 PR#1 的两个缺口**(实测):`probe_ttl_s ≥ 最慢 timeout + 5` 仍只在 `from_env`(直接构造未拦截);守卫上移后 `sources=()` 泄漏内置异常 `max() arg is an empty sequence`。
+- **承诺变化**: 经 `from_env` 装配的调用方零影响;手工构造/`replace` 出非法组合者由静默故障改为构造期 `ValueError`。发版走 1.0.1(patch,用户拍板;CHANGELOG 单列"行为收紧"小节代替版本号预警),wiki `参考-配置键` 表述与新行为一致无需改。
+- **子决策**: 错误消息只点字段名不列 env 键(`types.py` 既有笔迹 + 键名单一事实源在 `.env.example`/wiki)。

research-wiki/docs-convention.md

@@ -0,0 +1,44 @@
+# 文档组织与维护约定(Gitea Wiki)
+
+> **定位**: 用户文档站 = Gitea Wiki(`https://gitea.iomgaa.online/iomgaa/PolyGateway/wiki`);本文规定它的结构、更新时机与写作纪律。研发知识(设计/决策/验收)仍归 `research-wiki/`,两者职责不重叠。
+
+## 1. 结构:Diátaxis 四区(2026-07-23 建站,17 页)
+
+| 区 | 页面 | 职责(读者此刻要干什么) | 禁止 |
+|---|---|---|---|
+| 教程 | `教程-十分钟接入` | 新手被领着走通一遍 | 塞选项枚举与原理论述 |
+| 指南(How-to) | `指南-{多源与选源,限流与熔断,响应缓存,遥测与成本,结构化输出,OCR,Embedding,迁移既有项目}` | 一页一任务:配置片段+行为+坑 | 重复参考区的全量表 |
+| 参考 | `参考-{公共API,配置键,异常}` | 查表:签名/字段/键,**以源码实测为准** | 叙述与劝导 |
+| 解释 | `解释-{架构,错误四分类,治理行为,降级与取消}` | 讲为什么;机制挂回压测病灶 | 写成使用说明 |
+
+导航:`Home.md`(按意图分流表)+ `_Sidebar.md`(全页目录);页间互链用 Gitea `[[双括号]]` 语法。
+
+## 2. 更新时机(与代码变更绑定,发版检查清单)
+
+| 变更类型 | 必须同步的页 |
+|---|---|
+| 新公共 API / 新能力 | 对应指南页(新增或扩写)+ `参考-公共API` + 侧边栏 + CHANGELOG |
+| 新增/改名配置键 | `参考-配置键` + 相关指南页的配置片段 + 主仓库 `.env.example` |
+| 治理行为变更(重试/熔断/选源语义) | `解释-治理行为` + 受影响指南页;若改公共承诺另走 brainstorming 流程 |
+| 新异常/分类语义调整 | `参考-异常` + `解释-错误四分类` |
+| **发版(任何版本号)** | `Home.md` 版本号与安装命令 + 主仓库 `CHANGELOG.md` + `README.md` 版本相关处;过一遍上面各行 |
+
+**门**: 版本 bump 的提交不允许单独存在——同一次交付里必须包含对应的 wiki/CHANGELOG 同步(发布检查清单第一项)。
+
+## 3. 写作纪律
+
+- 中文;表格优先;单个代码块 ≤ 15 行;每个配置片段可直接复制运行。
+- **事实以源码为准**:参考区改动前先对照 `__init__.py` 导出面、`client.py`/`ocr.py`/`embedding.py` 签名与 `.env.example`;不确定就实测,不凭记忆写。
+- 深度内容(决策论证、迁移全文、验收数字)**只放指针**指向主仓库 `research-wiki/`,不复制——避免双处维护同一事实。
+- API 参考坚持**手写精选**(公共面小 + 只增不删承诺,手写比自动生成可读且低维护);若公共面显著膨胀再评估 mkdocstrings。
+
+## 4. 更新操作
+
+Wiki 是独立 git 仓库,两种改法:
+
+```bash
+git clone https://gitea.iomgaa.online/iomgaa/PolyGateway.wiki.git   # 批量改: clone→编辑→push
+# 或在 Gitea 网页 Wiki 页面上直接编辑(单页小改)
+```
+
+文件名即页名(中文文件名);`Home.md` 是落地页,`_Sidebar.md` 是导航,新增页必须同步进侧边栏与 Home 分流表。凭据在本机 osxkeychain(git)与 `~/.pypirc`(twine)。

research-wiki/graph/edges.json

@@ -90,6 +90,11 @@
       "id": "finding:m4-acceptance",
       "label": "M4 迁移验收(GovDoc+CHS)",
       "type": "finding"
+    },
+    {
+      "id": "design:settings-invariant-guards",
+      "label": "GatewaySettings 跨字段不变量守卫的生效范围",
+      "type": "design"
     }
   ],
   "links": [

research-wiki/index.md

@@ -1,13 +1,15 @@
 # Research Wiki 索引
 
-> 自动生成，更新时间：2026-07-22 14:36 UTC
+> 自动生成，更新时间：2026-07-30 03:44 UTC
 
-## design (10)
+## design (12)
 - [2026-07-20-m1-core-design](designs/2026-07-20-m1-core-design.md) `design:2026-07-20-m1-core-design`
 - [2026-07-20-m2-distributed-design](designs/2026-07-20-m2-distributed-design.md) `design:2026-07-20-m2-distributed-design`
 - [2026-07-21-m25-resilience-design](designs/2026-07-21-m25-resilience-design.md) `design:2026-07-21-m25-resilience-design`
 - [2026-07-21-m3-ocr-design](designs/2026-07-21-m3-ocr-design.md) `design:2026-07-21-m3-ocr-design`
 - [2026-07-22-m4-migration-design](designs/2026-07-22-m4-migration-design.md) `design:2026-07-22-m4-migration-design`
+- [2026-07-29-settings-invariant-guards-design](designs/2026-07-29-settings-invariant-guards-design.md) `design:2026-07-29-settings-invariant-guards-design`
+- [GatewaySettings 跨字段不变量守卫的生效范围](designs/settings-invariant-guards.md) `design:settings-invariant-guards`
 - [M1 核心里程碑设计:公共签名冻结与治理栈落地](designs/m1-core-design.md) `design:m1-core-design`
 - [M2 分布式:Redis 治理后端+背压+Postgres 遥测+pricing+Embedding+压测 harness](designs/m2-distributed.md) `design:m2-distributed`
 - [M2.5 治理韧性: 半死源隔离与健康感知调度](designs/m25-resilience.md) `design:m25-resilience`

research-wiki/log.md

@@ -46,3 +46,5 @@
 - [2026-07-22 09:33 UTC] 重建索引: 32 篇页面
 - [2026-07-22 14:36 UTC] 新增 finding: M4 迁移验收(GovDoc+CHS) (finding:m4-acceptance)
 - [2026-07-22 14:36 UTC] 重建索引: 34 篇页面
+- [2026-07-30 03:44 UTC] 新增 design: GatewaySettings 跨字段不变量守卫的生效范围 (design:settings-invariant-guards)
+- [2026-07-30 03:44 UTC] 重建索引: 36 篇页面

src/polygateway/__init__.py

@@ -31,7 +31,7 @@ from polygateway.types import (
     SourceConfig,
 )
 
-__version__ = "1.0.0"
+__version__ = "1.0.1"
 
 __all__ = [
     "DEFAULT_PROFILES",

src/polygateway/config.py

@@ -51,6 +51,7 @@ _QUOTA_FULL = frozenset({"wait", "fail_fast"})
 _DEFAULT_STALL_WINDOW_S = 300.0
 _DEFAULT_POLL_INTERVAL_S = 0.05
 _DEFAULT_LEASE_TTL_S = 1500.0  # CHS _DEFAULT_LEASE_TTL_MS 同源
+_PROBE_GRACE_S = 5.0  # 半开探针租约相对最慢调用的清理宽限(CHS container.py:274-275)
 
 
 def _cast(raw: str, kind: str, key: str) -> object:
@@ -88,7 +89,16 @@ def _require(env: Mapping[str, str], *keys: str) -> tuple[str, str]:
 
 @dataclass(frozen=True)
 class GatewaySettings:
-    """一个 scope 的完整装配配置;构造经 from_env 聚合并通过全部守卫。"""
+    """一个 scope 的完整装配配置;**任何**构造路径都通过全部装配守卫(ARCH §7.3)。
+
+    守卫校验的是**跨字段**不变量: 单看一个字段都合法,组合起来才会在运行时
+    咬人(租约先于请求过期、正常慢首包被误判卡死、半开探针在途被接管)。
+    types.py 各子配置的 `__post_init__` 只看得见自己的字段,故由本类把关。
+
+    放在 `__post_init__` 而非某个工厂里: 这些约束是本类定义的一部分,不是
+    某个入口的输入检查。挂在构造期,直接构造、`dataclasses.replace` 与全部
+    装配工厂一并覆盖;挂在工厂里则每加一个工厂就多一处要同步。
+    """
 
     scope: str
     sources: tuple[SourceConfig, ...]
@@ -111,6 +121,44 @@ class GatewaySettings:
     structured_max_retries: int
     lease_ttl_s: float
 
+    def __post_init__(self) -> None:
+        self._validate_sources()
+        self._validate_lease()
+        self._validate_stall()
+        self._validate_probe()
+
+    def _validate_sources(self) -> None:
+        """零源的配置装出来选源必然失败,构造期即拒。"""
+        if not self.sources:
+            raise ValueError("GatewaySettings.sources 不能为空: 至少一个源")
+
+    def _validate_lease(self) -> None:
+        """调用超时须 ≤ permit 租约 TTL,防租约先于请求过期使并发超出配额。"""
+        slowest = max(s.timeout_s for s in self.sources)
+        if slowest > self.lease_ttl_s:
+            raise ValueError(
+                f"源最大 timeout_s({slowest})超过 permit 租约 lease_ttl_s"
+                f"({self.lease_ttl_s});调大 lease_ttl_s 或调小源的 timeout_s"
+            )
+
+    def _validate_stall(self) -> None:
+        """stall 窗口须 ≥ 最慢源 TTFT 上限,防把正常慢首包误判为卡死。"""
+        ttfts = [s.ttft_timeout_s for s in self.sources if s.ttft_timeout_s is not None]
+        if ttfts and self.backpressure.stall_window_s < max(ttfts):
+            raise ValueError(
+                f"backpressure.stall_window_s({self.backpressure.stall_window_s})须 ≥ "
+                f"最大源 ttft_timeout_s({max(ttfts)});调大 stall_window_s 或调小 ttft_timeout_s"
+            )
+
+    def _validate_probe(self) -> None:
+        """半开探针租约须撑过一次最慢调用,否则探针在途即被接管(M2 设计 §3)。"""
+        floor = max(s.timeout_s for s in self.sources) + _PROBE_GRACE_S
+        if self.breaker.probe_ttl_s < floor:
+            raise ValueError(
+                f"breaker.probe_ttl_s({self.breaker.probe_ttl_s})须 ≥ 最慢源 "
+                f"timeout_s + {_PROBE_GRACE_S}({floor});调大 probe_ttl_s 或调小源的 timeout_s"
+            )
+
     @classmethod
     def from_env(
         cls,
@@ -119,7 +167,7 @@ class GatewaySettings:
         *,
         env_file: str = ".env",
     ) -> GatewaySettings:
-        """聚合 env(缺省 .env + os.environ,后者优先)并执行装配守卫。"""
+        """聚合 env(缺省 .env + os.environ,后者优先);守卫由 `__post_init__` 执行。"""
         if env is None:
             env = {
                 k: v for k, v in {**dotenv_values(env_file), **os.environ}.items() if v is not None
@@ -129,7 +177,7 @@ class GatewaySettings:
         global_limits = _load_global_limits(scope_u, env)
         retry = _load_retry(scope_u, env)
         breaker = _load_breaker(scope_u, env, sources, global_limits)
-        settings = cls(
+        return cls(
             scope=scope_u.lower(),
             sources=tuple(sources),
             global_limits=global_limits,
@@ -140,9 +188,6 @@ class GatewaySettings:
             quota_full=_load_choice(env, f"{scope_u}__QUOTA_FULL", _QUOTA_FULL, "wait"),
             **_load_pgw(env),
         )
-        _guard_lease(settings)
-        _guard_stall(settings)
-        return settings
 
 
 def _load_sources(scope: str, env: Mapping[str, str]) -> list[SourceConfig]:
@@ -217,16 +262,12 @@ def _load_breaker(
     if concurrency > 0:
         threshold = max(threshold, concurrency * 2)
     slowest = max(s.timeout_s for s in sources)
-    probe_floor = slowest + 5.0  # CHS container.py:274-275: 最慢调用 + 清理宽限
+    probe_floor = slowest + _PROBE_GRACE_S
     probe = _first(env, f"{scope}__BREAKER__PROBE_TTL_S")
     if probe is not None:
+        # 配置值不在此校验: 探针租约下限是跨字段不变量,由 GatewaySettings._validate_probe
+        # 统一把关(否则直接构造那条装配路会绕过)
         probe_ttl_s = float(_cast(probe[1], "float", probe[0]))
-        # 装配守卫(M2 设计 §3): 探针租约必须撑过一次最慢调用,否则半开探针在途即被接管
-        if probe_ttl_s < probe_floor:
-            raise ValueError(
-                f"probe_ttl_s({probe_ttl_s})须 ≥ 最大源 timeout_s + 5({probe_floor});"
-                f"调大 {probe[0]} 或调小源超时"
-            )
     else:
         # 派生规则: 探针租约须撑过一次最慢调用,且不短于冷却期(第三项保证守卫恒成立)
         probe_ttl_s = max(2 * slowest, cooldown_s, probe_floor)
@@ -339,26 +380,6 @@ def _load_structured_retries(env: Mapping[str, str]) -> int:
     return value
 
 
-def _guard_lease(settings: GatewaySettings) -> None:
-    """装配守卫: 调用超时须 ≤ permit 租约 TTL,防租约先于请求过期(ARCH §7.3)。"""
-    slowest = max(s.timeout_s for s in settings.sources)
-    if slowest > settings.lease_ttl_s:
-        raise ValueError(
-            f"源最大 timeout_s({slowest})超过 permit 租约 TTL({settings.lease_ttl_s});"
-            f"调大 PGW_LEASE_TTL_S 或调小超时"
-        )
-
-
-def _guard_stall(settings: GatewaySettings) -> None:
-    """装配守卫: stall 窗口须 ≥ 最慢源 TTFT 上限,防把正常慢首包误判为卡死(ARCH §7.3)。"""
-    ttfts = [s.ttft_timeout_s for s in settings.sources if s.ttft_timeout_s is not None]
-    if ttfts and settings.backpressure.stall_window_s < max(ttfts):
-        raise ValueError(
-            f"stall_window_s({settings.backpressure.stall_window_s})须 ≥ 最大源 "
-            f"ttft_timeout_s({max(ttfts)});调大 BACKPRESSURE__STALL_WINDOW_S 或调小 TTFT"
-        )
-
-
 def _load_lease_ttl(env: Mapping[str, str]) -> float:
     found = _first(env, "PGW_LEASE_TTL_S")
     return float(_cast(found[1], "float", found[0])) if found else _DEFAULT_LEASE_TTL_S

tests/integration/test_monkey_ocr_live.py

@@ -46,6 +46,10 @@ def _env(sources: dict[int, str], **extra: str) -> dict[str, str]:
             f"OCR__MONKEY__{n}__API_KEY": "none",
             f"OCR__MONKEY__{n}__MODEL": "monkey-ocr",
             f"OCR__MONKEY__{n}__TIMEOUT_S": "300",
+            # 服务在 LAN,开发机若开着系统代理(httpx trust_env 读 macOS 系统配置,
+            # 不是环境变量),代理会对内网地址回 403 —— 与本文件 raw httpx 用例
+            # 显式传 trust_env=False 同因
+            f"OCR__MONKEY__{n}__TRUST_ENV": "false",
         }
     env.update(extra)
     return env

tests/unit/test_config.py

@@ -1,8 +1,11 @@
 """config.py 配置聚合测试(设计 §8): 多源命名、键优先级、缺失报错。"""
 
+import dataclasses
+
 import pytest
 
-from polygateway.config import GatewaySettings
+from polygateway.client import GatewayClient
+from polygateway.config import GatewaySettings, OcrSettings
 
 _BASE_ENV = {
     "LLM__QWEN__1__BASE_URL": "https://gw-a.example/v1",
@@ -319,3 +322,94 @@ class TestOcrSettings:
         env = {k: v for k, v in self._OCR_ENV.items() if k != "OCR__MONKEY__1__BASE_URL"}
         with pytest.raises(ValueError):
             OcrSettings.from_env("OCR", env=env)
+
+
+class TestCrossFieldInvariants:
+    """四条跨字段不变量必须在**任何**构造路径上生效(设计 2026-07-29)。
+
+    这些约束单看一个字段都合法,组合起来才非法,因此 types.py 各子配置的
+    __post_init__ 看不见——只能由聚合层 GatewaySettings 把关。守卫若只挂在
+    from_env 上,from_settings 这条同等官方的装配路(CLAUDE.md §4.5)就能
+    装出违反不变量的配置,类会存在于自己 docstring 声称不可能的状态。
+
+    每条不变量测两侧: 越界必拒、边界值(恰好相等)必过——收紧的是错的组合,
+    不是所有直接构造。
+    """
+
+    def _base(self, **overrides) -> GatewaySettings:
+        return GatewaySettings.from_env("LLM", env=_env(**overrides))
+
+    def _with_watchdog(self) -> GatewaySettings:
+        """带看门狗的基准: TTFT/inter-token 成对配置才满足 SourceConfig 不变式。"""
+        return self._base(
+            **{
+                "LLM__QWEN__1__TTFT_TIMEOUT_S": "30",
+                "LLM__QWEN__1__INTER_TOKEN_TIMEOUT_S": "15",
+                "LLM__BACKPRESSURE__STALL_WINDOW_S": "300",
+            }
+        )
+
+    # —— 源超时 ≤ permit 租约 TTL(ARCH §7.3: 防租约先于请求过期,并发悄悄超配额)——
+
+    def test_lease_rejects_timeout_above_ttl_on_direct_construction(self):
+        base = self._base()  # 源 timeout_s=120
+        with pytest.raises(ValueError, match="lease_ttl_s"):
+            dataclasses.replace(base, lease_ttl_s=1.0)
+
+    def test_lease_accepts_timeout_equal_to_ttl(self):
+        base = self._base()
+        assert dataclasses.replace(base, lease_ttl_s=120.0).lease_ttl_s == 120.0
+
+    # —— stall 窗口 ≥ 最大源 TTFT(ARCH §7.3: 防正常慢首包被误判卡死掐断)——
+
+    def test_stall_rejects_window_below_max_ttft_on_direct_construction(self):
+        base = self._with_watchdog()  # 源 ttft_timeout_s=30
+        narrowed = dataclasses.replace(base.backpressure, stall_window_s=20.0)
+        with pytest.raises(ValueError, match="stall_window_s"):
+            dataclasses.replace(base, backpressure=narrowed)
+
+    def test_stall_accepts_window_equal_to_max_ttft(self):
+        base = self._with_watchdog()
+        exact = dataclasses.replace(base.backpressure, stall_window_s=30.0)
+        assert dataclasses.replace(base, backpressure=exact).backpressure.stall_window_s == 30.0
+
+    # —— 探针租约 ≥ 最慢源超时 + 5(M2 设计 §3: 防半开探针在途即被接管)——
+
+    def test_probe_rejects_ttl_below_floor_on_direct_construction(self):
+        base = self._base()  # 最慢 timeout_s=120,故下限 125
+        shortened = dataclasses.replace(base.breaker, probe_ttl_s=100.0)
+        with pytest.raises(ValueError, match="probe_ttl_s"):
+            dataclasses.replace(base, breaker=shortened)
+
+    def test_probe_accepts_ttl_at_floor(self):
+        base = self._base()
+        at_floor = dataclasses.replace(base.breaker, probe_ttl_s=125.0)
+        assert dataclasses.replace(base, breaker=at_floor).breaker.probe_ttl_s == 125.0
+
+    # —— sources 非空 ——
+
+    def test_empty_sources_rejected_with_actionable_message(self):
+        """零源装出来的 client 选源必然失败;消息须点明原因,不能泄漏 max() 的内置异常。"""
+        base = self._base()
+        with pytest.raises(ValueError) as exc:
+            dataclasses.replace(base, sources=())
+        assert "至少一个源" in str(exc.value)
+        assert "empty sequence" not in str(exc.value)
+
+    # —— 装配路径覆盖 ——
+
+    def test_factory_cannot_receive_invalid_settings(self):
+        """from_settings 这条路吃不到非法配置。
+
+        异常实际抛在实参求值(构造 settings)那一刻,而不是工厂内部——这正是
+        把守卫放构造期换来的性质: 非法实例根本不存在,无需每个工厂各自设防。
+        """
+        base = self._base()
+        with pytest.raises(ValueError, match="lease_ttl_s"):
+            GatewayClient.from_settings(dataclasses.replace(base, lease_ttl_s=1.0))
+
+    def test_ocr_settings_cannot_wrap_invalid_gateway(self):
+        """OcrSettings/EmbeddingSettings 只是包一层 GatewaySettings,自动继承同一把关。"""
+        base = self._base()
+        with pytest.raises(ValueError, match="lease_ttl_s"):
+            OcrSettings(gateway=dataclasses.replace(base, lease_ttl_s=1.0))