docs: correct the equivalence claim T2 disproved

2026-09-05 00:48:01 -04:00
parent 7fabc792b2
commit 3cb5331950
2 changed files with 11 additions and 2 deletions
@@ -156,7 +156,16 @@ request.reasoning_effort > source.reasoning_effort > source.enable_thinking(语
 | 旧写法 | 等价于 |
 |---|---|
 | `enable_thinking=False` | `reasoning_effort=Effort.NONE` |
-| `enable_thinking=True` | `reasoning_effort=Effort.AUTO`(注入 `on_base`,不附档位)——与旧行为逐字节等价,且不依赖能力表 |
+| `enable_thinking=True` | `reasoning_effort=Effort.AUTO`(注入 `on_base`,不附档位),不依赖能力表 |
+
+**`True` 的等价性分两种**(2026-09-04 实现时发现,更正初稿「与旧行为逐字节等价」的说法):
+
+| provider 类型 | 旧 `thinking_on` | 新 `AUTO` 注入 | 是否等价 |
+|---|---|---|---|
+| `on_base` 完整表达「开」(qwen/deepseek/zhipu/moonshot) | `{"enable_thinking": True}` 等 | 同左 | **逐字节等价** |
+| 靠档位表达「开」(minimax/openai/anthropic/google) | `{"reasoning_effort": "medium"}` | `{}`(不注入) | **行为变更** |
+
+后者是**有意的**: 旧版那个 `medium` 是库替下游做的档位判断(profile 注释自己承认「取 medium 是因为它是五档里语义最接近厂商正常强度的一档」),而 `medium` 在 GLM/kimi/deepseek 的档位表里根本不存在——正是本设计要消灭的东西。语义仍是「开」(这些模型默认即推理),只是不再强制一个档;要指定强度请显式配 `REASONING_EFFORT`。须进 CHANGELOG 的行为变更条目。
 | `enable_thinking=None` | 不表态 |

 **同源同时配 `enable_thinking` 与 `reasoning_effort` 且语义矛盾**(如 `True` + `none`)→ **构造期 `ValueError`**。不做「后者赢」的静默兜底: 两个字段表达同一件事时,矛盾是配置错误,不是优先级问题。
@@ -262,7 +262,7 @@ def effective_effort(

 **验收**: 三层优先级各自生效;请求级 `None` 不会覆盖源级已配的档;只配 `enable_thinking=True` 的存量源解析为 `AUTO` 且最终 payload 与升级前逐字节相同。

-**测试**(先失败后通过): `::test_request_effort_wins_over_source`、`::test_none_request_does_not_clear_source`、`::test_enable_thinking_true_is_auto`、`::test_legacy_payload_byte_identical`(回归门: 存量下游行为不变)。
+**测试**(先失败后通过): `::test_request_effort_wins_over_source`、`::test_none_request_does_not_clear_source`、`::test_enable_thinking_true_is_auto`、`::test_legacy_on_tier_matches_old_fragment`(回归门: **仅**对 `on_base` 完整表达「开」的 provider——qwen/deepseek/zhipu/moonshot——断言逐字节不变;minimax/openai/anthropic/google 的开档旧版硬编码 `medium`、新版不注入,是设计 §4.2 声明过的有意变更)。

 **验证**: `conda run -n PolyGateway pytest tests/unit/test_client.py -v` → PASS