feat: wire the tier through the transport and keep each tier's warning distinct

The transport now hands back the tier it actually sent, and that tier
rides TransportResult into LLMResponse. It is not the requested one:
under EFFORT_FALLBACK=nearest a medium request goes out as low, and
telemetry grouping by the requested tier would file the row under a tier
that never left the process.

Reconciliation judges the same tier instead of the old enable_thinking
bool, and the warning throttle keys on it. Keyed on the bool, every tier
of one model shared a single key, so the second contradiction was
silenced for the lifetime of the transport. The predicate is an identity
check against Effort.NONE on purpose -- the member's value is the
non-empty string "none", so any truthiness test would send every strength
tier down the "asked to disable" branch and invert the alarm.

src/polygateway/middleware/retry.py

@@ -395,6 +395,9 @@ class RetryMW:
             reasoning_tokens=result.reasoning_tokens,
             # 裁定归 transport(它才见得到原始信号),本层只搬运不改判
             thinking_observation=result.thinking_observation,
+            # 同理: 实际档由做注入的那一层裁定(`nearest` 映射后与请求档分叉),
+            # 本层若"顺手"改读 request.reasoning_effort,记的就是从未发出过的档
+            applied_effort=result.applied_effort,
         )
 
     async def _emit(

src/polygateway/thinking.py

@@ -575,7 +575,7 @@ def _warn_unregistered(
 
 def reconcile_thinking(
     *,
-    enable_thinking: bool | None,
+    effort: Effort | None,
     observation: ThinkingObservation,
     capability: ThinkingCapability | None,
     model: str,
@@ -585,6 +585,17 @@ def reconcile_thinking(
     能力表过期是必然事件(M3 的 evidence 曾停在 8-02 整整 23 天),而过期的
     表现是静默错觉。本函数把它变成可报警事件,代价是一次枚举比较。
 
+    **判据是档位而非布尔**(2026-09-05,设计 §4.3): `Effort.NONE` 走"要求关闭"
+    一支,其余任何档走"要求开启"一支,`None`(不表态)仍沉默。判据必须写成
+    `is Effort.NONE` 的**身份比较**——它的取值是非空串 `"none"`,任何靠真值性
+    的写法(`if not effort`)都恒为假,会把每个强度档送进关闭分支,告警方向整个
+    颠倒。传入的应是**实际发出去**的那一档(`nearest` 映射后与请求档分叉),
+    否则文案会说一个从未发出过的档。
+
+    **不新增**「档位高低 vs `reasoning_tokens` 多少」的对账(设计 §4.3/§11 第 1
+    条): 二者没有可判定的函数关系(实测同一档 rt 在 8~56 之间跳),拿它报警必然
+    是噪声,而噪声等于没有告警。该问题归 §11 的压测,不进库。
+
     **只判定、不打日志**: 文案作为返回值交给调用点,单测才能直接断言告警内容,
     而不必去解析日志格式;节流也才能留在握有实例状态的 transport 里。
 
@@ -593,24 +604,26 @@ def reconcile_thinking(
     与遥测落地,处置权归下游。
     """
     # Phase 1: 调用方不表态 —— 没提要求就无从谈"违背"
-    if enable_thinking is None:
+    if effort is None:
         return None
     # Phase 2: 要求关闭 —— 只有 OBSERVED 能证伪。UNKNOWN 没有证伪力,拿它报警
     # 等于每次关闭调用都喊一遍(M3 关闭档恒落此档),噪声即等于没有告警
-    if enable_thinking is False:
+    if effort is Effort.NONE:
         if observation is not ThinkingObservation.OBSERVED:
             return None
         return _off_but_observed(model, capability)
-    # Phase 3: 要求开启 —— ABSENT 是正面证伪,UNKNOWN 是"看不见",两者文案不可混
+    # Phase 3: 要求开启(含 auto 与各强度档)—— ABSENT 是正面证伪,UNKNOWN 是
+    # "看不见",两者文案不可混。文案写出**是哪一档**: transport 的节流键正按档
+    # 分离,文案不分档的话,两条告警长得一模一样,看的人分不出是哪一档出的问题
     if observation is ThinkingObservation.ABSENT:
         return (
-            f"模型 {model!r} 的 enable_thinking=True 未生效: 已注入开启参数,"
+            f"模型 {model!r} 的 reasoning_effort={effort.value!r} 未生效: 已注入开启参数,"
             f"上游却明确上报本次未推理(reasoning_tokens=0)"
         )
     if observation is ThinkingObservation.UNKNOWN:
         return (
-            f"模型 {model!r} 的 enable_thinking=True 无法确认是否生效: 已注入开启参数,"
-            f"但本次响应观测不到任何推理信号(推理正文与 usage 明细双缺)。"
+            f"模型 {model!r} 的 reasoning_effort={effort.value!r} 无法确认是否生效: "
+            f"已注入开启参数,但本次响应观测不到任何推理信号(推理正文与 usage 明细双缺)。"
             f"若走的是非流式路径,推理内容可能已计费却不回传"
         )
     return None
@@ -624,12 +637,12 @@ def _off_but_observed(model: str, capability: ThinkingCapability | None) -> str:
     """
     if capability is None:
         return (
-            f"模型 {model!r} 的 enable_thinking=False 未被满足: 实测观测到推理发生,"
+            f"模型 {model!r} 的 reasoning_effort='none' 未被满足: 实测观测到推理发生,"
             f"且该模型的推理能力尚未登记(本次按 provider 形态尽力注入)。"
             f"请实测后用 register_capability 登记其真实能力"
         )
     return (
-        f"模型 {model!r} 的 enable_thinking=False 未被满足: 实测观测到推理发生,"
+        f"模型 {model!r} 的 reasoning_effort='none' 未被满足: 实测观测到推理发生,"
         f"而能力表登记 can_disable={capability.can_disable}(evidence: {capability.evidence})。"
         f"能力表可能已过期——请复测后用 register_capability 更新登记"
     )

src/polygateway/transports/openai_compat.py

@@ -11,6 +11,7 @@ from __future__ import annotations
 import json
 import re
 import time
+from dataclasses import replace
 from typing import TYPE_CHECKING, Any
 
 import httpx
@@ -333,7 +334,7 @@ class OpenAICompatTransport:
         # 一个容器会让两种告警的生命周期纠缠在一起——将来任一侧想加清空/过期策略,
         # 都会连带改掉另一侧的行为。(键空间恰好不相交,故当下**不会**互相压制;
         # 分开维护的理由是语义,不是碰撞)
-        self._warned_mismatches: set[tuple[str, str, bool | None]] = set()
+        self._warned_mismatches: set[tuple[str, str, Effort | None]] = set()
         self._client_factory = client_factory or _default_client_factory
         self._clients: dict[str, httpx.AsyncClient] = {}
 
@@ -353,7 +354,13 @@ class OpenAICompatTransport:
         stream: bool,
         overlay: dict[str, Any],
         reasoning_effort: Effort | None,
-    ) -> dict[str, Any]:
+    ) -> tuple[dict[str, Any], Effort | None]:
+        """组装请求体,并交回本次**实际**发出去的档位(`None` = 未表态,不注入)。
+
+        返回二元组而非只返回 payload: 实际档在 `nearest` 映射后与请求档分叉,而
+        除本函数外没有第二处知道映射结果——不交出去,遥测就只能事后再算一遍,
+        算出来必是请求档。
+        """
         payload: dict[str, Any] = {"model": source.model, "messages": messages, "stream": stream}
         if stream:
             payload["stream_options"] = {"include_usage": True}  # 强制 usage 帧(三项目同款)
@@ -364,25 +371,26 @@ class OpenAICompatTransport:
         self._warned_models.add(source.model)
         # 三层优先级在此汇合: 请求级 > 源级 > enable_thinking 语法糖(设计 §4.2)。
         # 判定与装配守卫共用同一个纯函数,两处分叉就会变成"装配期放行、运行期报错"
-        payload.update(
-            resolve_thinking(
-                profile,
-                capability,
-                effective_effort(
-                    request_effort=reasoning_effort,
-                    source_effort=source.reasoning_effort,
-                    enable_thinking=source.enable_thinking,
-                ),
-                model=source.model,
-                fallback=source.effort_fallback,
-                warn_unregistered=first_time,
-            ).payload
+        resolution = resolve_thinking(
+            profile,
+            capability,
+            effective_effort(
+                request_effort=reasoning_effort,
+                source_effort=source.reasoning_effort,
+                enable_thinking=source.enable_thinking,
+            ),
+            model=source.model,
+            # 源级 `EFFORT_FALLBACK` 必须真的走到这里: 硬编码 "error" 会让人类明确
+            # 要求实现的 `nearest` 在零告警下变成死代码(2026-09-05 独立验证查出)
+            fallback=source.effort_fallback,
+            warn_unregistered=first_time,
         )
+        payload.update(resolution.payload)
         # 顺序即优先级(issue #4 设计决策 A): 配置级 extra_body 在前,调用级
         # overlay(含结构化注入)在后覆盖之。两行不可调换
         payload.update(source.extra_body)
         payload.update(overlay)
-        return payload
+        return payload, resolution.applied_effort
 
     async def complete(
         self,
@@ -401,7 +409,7 @@ class OpenAICompatTransport:
         """
         profile = get_provider(source.provider, registry=self._registry)
         try:
-            payload = self._build_payload(
+            payload, applied_effort = self._build_payload(
                 messages=messages,
                 source=source,
                 profile=profile,
@@ -432,27 +440,37 @@ class OpenAICompatTransport:
         except httpx.TransportError as exc:
             # VT 宽集: 覆盖断连/协议错误/读写失败(设计 §9 行 8)
             raise TransientError(f"{source.name} 网络错误: {exc}", **ctx) from exc
-        # 此处是唯一同时握有请求方向与响应结果的地方,对账只能落在这里
+        # 实际发出去的档只有 `_build_payload` 知道,而组装 TransportResult 的两条
+        # 路径都在更深一层。在此唯一汇合点补齐,好过给两条路径各加一个参数——那正是
+        # 遥测那边被明令禁止的"复制参数列表"形态,两条路径迟早只改一条
+        result = replace(result, applied_effort=applied_effort)
+        # 此处是唯一同时握有请求档位与响应结果的地方,对账只能落在这里
         self._warn_on_thinking_mismatch(source, result)
         return result
 
     def _warn_on_thinking_mismatch(self, source: SourceConfig, result: TransportResult) -> None:
-        """声明与观测矛盾即 warning;按 (source, model, direction) 节流,同组合只喊一次。
+        """声明与观测矛盾即 warning;按 (source, model, 实际档位) 节流,同组合只喊一次。
 
-        三段缺一不可。**方向**: 同一模型的开、关两档是两个独立的矛盾。**源名**:
-        多源多账号是本库的核心场景,同一 model 跨 N 个源是常态,而每个源背后是
-        独立的账号/网关,一个源的行为不代表另一个——漏掉源名,5 个源里第一个出
-        问题的喊完一次,其余四个永久静音。逐次调用刷屏会把告警变成噪声,噪声等于
-        没有告警。
+        三段缺一不可。**档位**: 同一模型的 low 与 max 是两个独立的矛盾,共用一个
+        键会让第二个永久静音(旧版拿 `enable_thinking` 当第三段,而档位根本不经过
+        那个字段,于是同一模型的所有档共用一个键)。**源名**: 多源多账号是本库的
+        核心场景,同一 model 跨 N 个源是常态,而每个源背后是独立的账号/网关,一个
+        源的行为不代表另一个——漏掉源名,5 个源里第一个出问题的喊完一次,其余四个
+        永久静音。逐次调用刷屏会把告警变成噪声,噪声等于没有告警。
+
+        档位取 `result.applied_effort`(真正发出去的那一档)而非请求档: `nearest`
+        映射后二者分叉,而对账问的是"我发出去的要求有没有被满足"——拿一个从未发出
+        过的档去对账,文案与键都指向了一次不存在的请求。被映射到同一档的两个请求
+        因此共用一个键,这正是它们该有的关系(同一条实际要求,同一个矛盾)。
 
         **先判键再对账**: `reconcile_thinking` 会拼含完整 `evidence` 的长字符串,
         而非流式档每次调用都命中这一分支,节流后再拼是纯粹的热路径浪费。
         """
-        key = (source.name, source.model, source.enable_thinking)
+        key = (source.name, source.model, result.applied_effort)
         if key in self._warned_mismatches:
             return
         message = reconcile_thinking(
-            enable_thinking=source.enable_thinking,
+            effort=result.applied_effort,
             observation=result.thinking_observation,
             capability=get_capability(source.model, table=self._capabilities),
             model=source.model,

src/polygateway/types.py

@@ -326,6 +326,16 @@ class LLMResponse:
     实测开启档 completion 53 vs 关闭档 3),该档即为 `UNKNOWN`。
     要判"确实没推理"只认 `ABSENT`(上游明确上报 0)。"""
 
+    applied_effort: Effort | None = None
+    """本次调用**真正发出去**的推理档位(issue #20);`None` = 调用方未表态。
+
+    与 `ChatRequest.reasoning_effort`(请求档)可能分叉: 源上配了
+    `EFFORT_FALLBACK=nearest` 时,请求 `medium` 而模型只有 low/high/max,实际发
+    出的是 `low`。遥测按本字段分组,记请求档会把整行挂在一个从未发出过的档下。
+
+    `None` 不是"没推理": 库不表态时也不推定模型自己的默认档——"没看见"不许说成
+    "发生了"(同 `thinking_observation` 的 `UNKNOWN` 一脉)。"""
+
 
 @dataclass(frozen=True)
 class ChatRequest:
@@ -438,6 +448,13 @@ class TransportResult:
     默认 `UNKNOWN` 而非 `ABSENT`: 不做裁定的 transport(OCR/embedding 等)沉默
     时,不该替上游做出"没推理"这个它从未做过的声明。"""
 
+    applied_effort: Effort | None = None
+    """本次调用真正发出去的推理档位(issue #20),由做注入的 transport 填。
+
+    只有做了注入的那一层知道它: `nearest` 映射后请求档与实际档分叉(请求
+    `medium` → 实发 `low`),中间件事后再算一遍必然算成请求档。默认 `None` 是
+    "未表态/不注入推理参数"(OCR、embedding 等 transport 沉默即此)。"""
+
 
 @dataclass(frozen=True)
 class SourceConfig: