fix(config): 装配守卫挪进 __post_init__,任何构造路径都生效

_guard_lease 与 _guard_stall 原先只写在 GatewaySettings.from_env 里,
而 CLAUDE.md §4.5 规定装配有两条官方路径。结果是走 from_settings() 能装出
一个违反类不变量的 settings —— 这个类的 docstring 声称「构造经 from_env 聚合
并通过全部守卫」,但它可以合法地存在于自己声称不可能的状态。

守卫挪进 __post_init__,与同族的 SourceConfig 一致。放构造期而不是在每个工厂里
各加一行:三个 client(Gateway/Ocr/Embedding)各有两个工厂,共六个入口,
挂构造期是一处,挂工厂是六处要保持同步——那正是「每个调用方各维护一份副本」
的毛病,只是挪进了库里。OcrSettings 与 EmbeddingSettings 都包着一个
GatewaySettings,因此一并覆盖。

两个守卫的报错文案改为点字段名,环境变量键降为补充信息。守卫现在每次构造都跑,
而走 from_settings 的调用方从没设过那些键,让他「调大 PGW_LEASE_TTL_S」
是句没法执行的建议。

行为收紧:直接构造或 dataclasses.replace 出非法组合,现在构造期就抛 ValueError,
而不是留到运行时表现为租约先于请求过期、或正常慢首包被误判为卡死。
经 from_env 装配的调用方不受影响——那条路本来就跑这两个守卫。

测试:新增 TestGuardsRunOnEveryConstruction 四条(先失败 3 条后全过)。
既有 447 passed / 34 skipped 全部保持,无回归;ruff check、ruff format --check、
lint-imports 三门均通过。

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This commit is contained in:
2026-07-29 11:32:03 -04:00
parent f17044dead
commit f76a89b1a1
3 changed files with 107 additions and 9 deletions
+19
View File
@@ -1,5 +1,24 @@
# Changelog
## 未发布
### 修复
- **装配守卫在任何构造路径上都生效,不再只在 `from_env` 上。** `_guard_lease`
(源超时须 ≤ permit 租约 TTL)与 `_guard_stall`(stall 窗口须 ≥ 最大 TTFT)原先只写在
`GatewaySettings.from_env` 里,而 CLAUDE.md §4.5 规定装配有两条官方路径
——走 `from_settings()` 的调用方能装出违反类不变量的配置,且不报任何错。
守卫已挪进 `GatewaySettings.__post_init__`,与 `SourceConfig` 的做法一致。
三个 client(Gateway/Ocr/Embedding)各有两个工厂,共六个入口,一并覆盖。
**行为收紧,可能影响下游**: 直接构造 `GatewaySettings`(或对它做
`dataclasses.replace`)时若组合非法,现在会在构造期抛 `ValueError`,
而不是留到运行时表现为租约先于请求过期、或正常慢首包被误判为卡死。
`from_env` 装配的调用方不受影响——那条路本来就跑这两个守卫。
- 两个守卫的报错文案改为点字段名(`lease_ttl_s``backpressure.stall_window_s`),
环境变量键降为补充信息。原文案只点环境变量键,而不走 env 的调用方从没设过它们。
## 1.0.0(2026-07-22)
首个正式版。统一 LLM/VLM/OCR/Embedding 调度与中转库,治理单位为一次模型调用;经 GovDoc-SaaS 与 CHSAnalyzer 两个真实项目全量迁移验收(ARCHITECTURE §11)。