iomgaa
f76a89b1a1
_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>
2.9 KiB
2.9 KiB
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)。
- M1 核心: types/errors/ports 内核、OpenAI 兼容 httpx transport(SSE + 非流式)、三层活性看门狗、自研重试(错误四分类驱动,换源/退避/Retry-After)、多源多账号 + 选源 + 源冷却、内存限流/熔断、Redis/内存响应缓存(key 含 namespace/salt/多模态摘要)、SQLite 遥测(18 字段必录)、结构化输出阶梯(json_repair/原生 schema + 有界重问)、provider 注册表、
from_env装配。 - M2 分布式: Redis 六道闸限流(Lua,契约测试双后端共用)、跨进程熔断(单探针租约 + epoch fencing)、背压 stall 双条件判定、Postgres 遥测、pricing 成本、EmbeddingClient(分批/维度校验)。
- M2.5 治理韧性: 双通道熔断(失败率窗 + 连败 + 健康证据抑制)、健康感知选源(EWMA×在途 P2C 缺省)、AIMD 自适应并发、429 免重试预算、健康门槛降权;故障混编 soak 同场景 58.1%→98.96%。
- M3 OCR: OcrTextPort/OcrLayoutPort 端口族 + MonkeyOCR 双端点 transport(数值防御下沉)、OcrClient 独立治理循环、
check_health()逐源预检;OCR soak 1500 调用 99.73%。 - M4 迁移验证: GovDoc 与 CHS 全量迁移(合计约 −6800 行项目治理代码由库继任),原测试全绿 + 真实冒烟 + 50 样本回归;Gitea PyPI 分发。
安装(实验室 Gitea PyPI):
pip install --index-url https://gitea.iomgaa.online/api/packages/iomgaa/pypi/simple/ \
--extra-index-url https://pypi.org/simple/ "polygateway[redis,postgres,structured]==1.0.*"