feat: let one call ask for a different tier than its source defaults to

The three-layer priority (call > source > enable_thinking sugar > silence)
now lives in one pure function, thinking.effective_effort(). The assembly
guard and the request hot path used to each carry their own inline copy of
the sugar conversion; two copies of the same judgement drift into the worst
shape there is - passes at assembly, raises at runtime.

The guard now also honours effort_fallback, so a source that opted into
nearest is no longer sentenced at assembly for a tier it could have mapped.

tests/unit/test_client.py

@@ -198,6 +198,57 @@ class TestSamplingOverlay:
         assert [c["seed"] for c in captured] == [1, 2]
 
 
+class TestReasoningEffortPriority:
+    """三层优先级: 请求级 > 源级 > `enable_thinking` 语法糖 > 不表态(设计 §4.2)。
+
+    一律抓**真实请求体**而非只查 `ChatRequest` 字段: 档位的价值全在发出去的那几个
+    字节上,只断言中间态会让"字段填了但一路没人读"这种缺口继续通过测试——issue #20
+    的 `extra_body` 绕行正是这么长出来的。
+    """
+
+    def _capturing_client(self, captured, **overrides):
+        def handler(request):
+            captured.append(json.loads(request.content))
+            return _sse()
+
+        return _client(handler=handler, **overrides)
+
+    def _zhipu(self, **overrides):
+        # glm-5.3 的档位是 low/high/max(能力表已登记),zhipu 的 wire 三样俱全,
+        # 是唯一能同时看清"开启形态"与"档位键"的组合
+        overrides.setdefault("model", "glm-5.3")
+        return _source(provider="zhipu", **overrides)
+
+    @pytest.mark.parametrize(
+        ("provider", "model", "fragment"),
+        [
+            ("qwen", "qwen-max", {"enable_thinking": True}),
+            ("deepseek", "deepseek-v4-pro", {"thinking": {"type": "enabled"}}),
+            ("zhipu", "glm-5.3", {"thinking": {"type": "enabled"}}),
+            ("moonshot", "kimi-k3", {"thinking": {"type": "enabled"}}),
+        ],
+    )
+    async def test_legacy_on_tier_matches_old_fragment(self, provider, model, fragment):
+        """存量 `ENABLE_THINKING=true` 的回归门: 发出去的字节逐字不变。
+
+        **只覆盖 `on_base` 自己就说全了"开"的四段**。minimax/openai/anthropic/google
+        的开档旧版硬编码 `{"reasoning_effort": "medium"}`,新版不注入任何档位——那是
+        设计 §4.2 声明过的**有意变更**(medium 在 GLM/kimi/deepseek 的档位表里根本
+        不存在,是库替下游做的档位判断),不是本门要守的不变量。
+
+        qwen/deepseek 两条字面量逐字取自升级前的 `ProviderProfile.thinking_on`;
+        zhipu/moonshot 升级前没有对应段,断言的是它们 2026-09-04 登记的形态。
+        """
+        captured = []
+        source = _source(provider=provider, model=model, enable_thinking=True)
+        async with self._capturing_client(captured, sources=[source]) as client:
+            await client.chat([{"role": "user", "content": "hi"}])
+        body = captured[0]
+        assert {k: body[k] for k in fragment} == fragment
+        # `auto` = 开启但不指定强度: 语法糖不得替调用方挑一个档
+        assert "reasoning_effort" not in body
+
+
 class _MemoryRecorder:
     """收下遥测行原样存起来;断言"哪些行被写了"必须能看到零行的情形。"""