feat: accept sampling overlay on chat() and per-source extra_body

Priority is structured injection > per-call overlay > per-source config,
and extra_body now takes part in the cache fingerprint.

tests/unit/test_client.py

@@ -19,6 +19,7 @@ from polygateway.backends.memory.cache import InMemoryCache
 from polygateway.backends.memory.limiter import InMemoryLimiter
 from polygateway.sources import RoundRobinSelector
 from polygateway.structured.json_repair import JsonRepairStrategy
+from polygateway.structured.native_schema import NativeSchemaStrategy
 from polygateway.transports.openai_compat import OpenAICompatTransport
 from polygateway.types import (
     BackpressurePolicy,
@@ -117,6 +118,106 @@ class TestChatEndToEnd:
                 await client.chat([{"role": "user", "content": "hi"}], structured="json")
 
 
+class TestSamplingOverlay:
+    """调用级采样参数入口(issue #4 Task 3)。"""
+
+    def _capturing_client(self, captured, **overrides):
+        def handler(request):
+            captured.append(json.loads(request.content))
+            return _sse()
+
+        return _client(handler=handler, **overrides)
+
+    async def test_overlay_reaches_request_body(self):
+        captured = []
+        async with self._capturing_client(captured) as client:
+            await client.chat([{"role": "user", "content": "hi"}], overlay={"seed": 42})
+        assert captured[0]["seed"] == 42
+
+    async def test_call_level_beats_config_level(self):
+        """优先级: 调用级 > 配置级(设计决策 A)。"""
+        captured = []
+        source = _source(extra_body={"temperature": 0, "top_p": 0.9})
+        async with self._capturing_client(captured, sources=[source]) as client:
+            await client.chat([{"role": "user", "content": "hi"}], overlay={"temperature": 1})
+        assert captured[0]["temperature"] == 1  # 调用级覆盖
+        assert captured[0]["top_p"] == 0.9  # 配置级未被顶掉的键保留
+
+    async def test_structured_injection_beats_call_level(self):
+        """结构化注入优先级最高: 它关系到响应能否被解析(设计决策 A)。"""
+        captured = []
+        client = self._capturing_client(captured, structured_strategy=NativeSchemaStrategy())
+        async with client:
+            await client.chat(
+                [{"role": "user", "content": "hi"}],
+                structured="json",
+                overlay={"response_format": {"type": "text"}},
+            )
+        assert captured[0]["response_format"] != {"type": "text"}
+
+    async def test_protected_key_rejected_before_onion(self):
+        """保护键在进洋葱之前就报错,transport 一次都不该被碰到。"""
+        captured = []
+        async with self._capturing_client(captured) as client:
+            with pytest.raises(ValueError, match="stream"):
+                await client.chat([{"role": "user", "content": "hi"}], overlay={"stream": False})
+        assert captured == []
+
+    async def test_unserializable_value_rejected_before_onion(self):
+        """裸 TypeError 会在 CacheMW 的降级 try 之外炸且无遥测(设计决策 B)。"""
+        captured = []
+        async with self._capturing_client(captured) as client:
+            with pytest.raises(ValueError, match="JSON"):
+                await client.chat(
+                    [{"role": "user", "content": "hi"}], overlay={"temperature": object()}
+                )
+        assert captured == []
+
+    async def test_caller_dict_mutation_does_not_leak(self):
+        """调用方逐次改 seed 复用同一 dict 是预期模式(设计决策 E)。"""
+        captured = []
+        caller_overlay = {"seed": 1}
+        async with self._capturing_client(captured) as client:
+            await client.chat([{"role": "user", "content": "hi"}], overlay=caller_overlay)
+            caller_overlay["seed"] = 2
+            await client.chat([{"role": "user", "content": "hi"}], overlay=caller_overlay)
+        assert [c["seed"] for c in captured] == [1, 2]
+
+
+class TestModelFingerprint:
+    """配置级采样参数须进缓存身份,否则改 temperature 后仍读旧缓存(决策 C)。"""
+
+    def test_empty_extra_body_keeps_legacy_fingerprint(self):
+        """全源无 extra_body 时字面量与旧实现逐字相同,不触发存量缓存冷启动。"""
+        from polygateway.client import build_model_fingerprint
+
+        sources = [_source(), _source(name="qwen_2", model="qwen-plus")]
+        assert build_model_fingerprint(sources) == "qwen-max,qwen-plus"
+
+    def test_extra_body_changes_fingerprint(self):
+        from polygateway.client import build_model_fingerprint
+
+        plain = build_model_fingerprint([_source()])
+        tuned = build_model_fingerprint([_source(extra_body={"temperature": 0})])
+        assert plain != tuned
+        assert tuned.startswith("qwen-max|")  # 旧字面量仍是前缀,便于人眼辨认
+
+    def test_source_rename_does_not_change_fingerprint(self):
+        """指纹按 (model, extra_body) 而非源名: 改名不该误触全量冷启动。"""
+        from polygateway.client import build_model_fingerprint
+
+        a = build_model_fingerprint([_source(name="qwen_1", extra_body={"temperature": 0})])
+        b = build_model_fingerprint([_source(name="renamed", extra_body={"temperature": 0})])
+        assert a == b
+
+    def test_differing_extra_body_across_sources_is_distinguished(self):
+        from polygateway.client import build_model_fingerprint
+
+        a = build_model_fingerprint([_source(extra_body={"temperature": 0})])
+        b = build_model_fingerprint([_source(extra_body={"temperature": 1})])
+        assert a != b
+
+
 class TestFactories:
     def test_from_env_assembles(self):
         client = GatewayClient.from_env("LLM", env=_ENV)

tests/unit/test_openai_compat.py

@@ -445,6 +445,27 @@ class TestRequestShaping:
         )
         assert seen["response_format"] == {"type": "json_object"}
 
+    async def test_extra_body_merged_and_outranked_by_overlay(self):
+        """顺序即优先级: thinking profile → extra_body → overlay(issue #4)。"""
+        seen = {}
+
+        def handler(request):
+            seen.update(json.loads(request.content))
+            return _sse_stream(_chunk(content="x"), _chunk(usage=_USAGE))
+
+        await _complete(
+            _transport_for(handler),
+            _source(extra_body={"temperature": 0, "top_p": 0.9}),
+            overlay={"temperature": 1},
+        )
+        assert seen["temperature"] == 1  # 调用级覆盖配置级
+        assert seen["top_p"] == 0.9  # 未被顶掉的配置级键保留
+
+    async def test_extra_body_cannot_break_governed_keys(self):
+        """治理键由 payload 骨架拥有;extra_body 的保护键在构造期已被拦下。"""
+        with pytest.raises(ValueError, match="stream"):
+            _source(extra_body={"stream": False})
+
 
 class TestErrorTranslation:
     @pytest.mark.parametrize(