whosellm 0.3.0__tar.gz → 0.4.0__tar.gz

{whosellm-0.3.0 → whosellm-0.4.0}/.bumpversion.toml

@@ -2,7 +2,7 @@
 # 文档 / Documentation: https://callowayproject.github.io/bump-my-version/
 
 [tool.bumpversion]
-current_version = "0.3.0"
+current_version = "0.4.0"
 parse = """(?x)
     (?P<major>0|[1-9]\\d*)\\.
     (?P<minor>0|[1-9]\\d*)\\.

{whosellm-0.3.0 → whosellm-0.4.0}/CHANGELOG.md

@@ -2,6 +2,16 @@
 
 All notable changes to this project will be documented in this file.
 
+## [Unreleased]
+
+### Added
+- **工具结果多模态能力（TFROB-856）**：新增 `LLMApiSurface`（str 枚举：`claude_messages` / `openai_chat_completions` / `openai_responses` / `gemini` / `dashscope` / `glm` / `deepseek` / `deepseek_responses`）与 `ToolResultSurfaceCapability`（`modalities` / `max_inline_bytes` / `mime_types`）。`ModelCapabilities.tool_result_surfaces` 以 surface 为键登记工具结果的原生媒体能力：缺键 = 未声明，空元组 = 明确不支持。
+- 新增文档上限字段：`max_pdf_size_mb`、`max_pdf_pages`、`max_document_size_mb`（预留）、`supported_document_mime_type`。`None` 表示未声明（未知），不代表“不限”；单文件与请求级上限分层登记。
+- 新增单请求内联媒体总预算 `max_inline_media_bytes` 与文件类媒体合计上限 `max_inline_file_bytes`（媒体计数字段继续复用 `media_count_limit`）。
+- 预留 `FileApiCapability` / `ModelCapabilities.file_api`，本版本不消费。
+- 数据登记（官方文档核实 + 2026-10-29 抓取日期；未逐模型 API 实测的已显式标注）：Claude 4.x/5 工具结果支持 image + PDF；OpenAI Chat Completions tool 消息 text-only、Responses `function_call_output` 支持 image/file；Gemini 3 系支持 image，Gemini 2.x 显式标为不支持；DeepSeek Chat Completions tool 消息 text-only，Responses `function_call_output` 支持 image，PDF `input_file` 经 2026-10-29 实测为静默不投递（登记为不支持）。DashScope / GLM 的官方 API 参考将 tool 消息 content 定义为字符串，登记为显式不支持（空元组）。
+- 修正 OpenAI gpt-5.1 及更新视觉模型缺失的 `supports_pdf=True`（官方 PDF 解析要求视觉模型，gpt-4o 及更新）。
+
 ## [0.2.4] - Unreleased
 
 ### Added

{whosellm-0.3.0 → whosellm-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: whosellm
-Version: 0.3.0
+Version: 0.4.0
 Summary: A unified LLM model version and capability management library
 Author-email: JQQ <jqq1716@gmail.com>
 License: MIT
@@ -146,6 +146,35 @@ print(model.capabilities.max_video_size_mb)  # 20.0
 validated_params = model.validate_params(your_params)
 ```
 
+### 工具结果的多模态能力 / Multimodal Tool Results
+
+工具结果能否原生承载图片/文档，取决于 **provider × API surface**，而不是模型名字前缀。能力数据以 `LLMApiSurface` 为键，缺键表示「未声明」，空元组表示「明确不支持」——两者都应按不支持处理。
+
+Whether a tool result can natively carry images/documents depends on **provider × API surface**, not on a model-name prefix. Capability data is keyed by `LLMApiSurface`; a missing key means "undeclared" and an empty tuple means "explicitly unsupported" — treat both as unsupported.
+
+```python
+from whosellm import LLMApiSurface, LLMeta
+
+caps = LLMeta("claude-opus-5-5").capabilities
+surface = caps.tool_result_surfaces.get(LLMApiSurface.CLAUDE_MESSAGES)
+print(surface.modalities)          # ("image", "document")
+print(surface.supports("document"))  # True
+
+# Gemini 3 系支持；2.5 系明确不支持（会返回 400）
+print(LLMeta("gemini-3.8-flash").capabilities.tool_result_surfaces[LLMApiSurface.GEMINI].modalities)  # ("image",)
+print(LLMeta("gemini-2.5-pro").capabilities.tool_result_surfaces[LLMApiSurface.GEMINI].modalities)    # ()
+
+# DeepSeek 的 Chat Completions 与 Responses 是两个 surface：
+# Chat Completions tool 消息只能放文本；Responses 的 function_call_output 支持图片，
+# 但 PDF input_file 实测被静默丢弃（2026-10-29 探针）
+print(LLMeta("deepseek-flash").capabilities.tool_result_surfaces[LLMApiSurface.DEEPSEEK].modalities)           # ()
+print(LLMeta("deepseek-flash").capabilities.tool_result_surfaces[LLMApiSurface.DEEPSEEK_RESPONSES].modalities)  # ("image",)
+```
+
+用户消息能力仍由 `supports_vision` / `supports_audio` / `supports_video` / `supports_pdf` 表示，工具结果能力只走 `tool_result_surfaces`。文档上限见 `max_pdf_size_mb`、`max_pdf_pages`、`supported_document_mime_type`；单请求内联媒体预算见 `max_inline_media_bytes`，文件类媒体的请求级合计上限见 `max_inline_file_bytes`。
+
+User-message capability remains on `supports_vision` / `supports_audio` / `supports_video` / `supports_pdf`; tool-result capability lives only in `tool_result_surfaces`. Document limits are exposed via `max_pdf_size_mb`, `max_pdf_pages`, and `supported_document_mime_type`; the per-request inline-media budget is `max_inline_media_bytes`, and the request-level combined cap for file-type media is `max_inline_file_bytes`.
+
 ### 非法名称也不会炸 / Lenient on Unknown Names
 
 我们不想打断你的流程，即便名称不在我们的数据库里也能返回一个「未知模型占位符」。

{whosellm-0.3.0 → whosellm-0.4.0}/README.md

@@ -121,6 +121,35 @@ print(model.capabilities.max_video_size_mb)  # 20.0
 validated_params = model.validate_params(your_params)
 ```
 
+### 工具结果的多模态能力 / Multimodal Tool Results
+
+工具结果能否原生承载图片/文档，取决于 **provider × API surface**，而不是模型名字前缀。能力数据以 `LLMApiSurface` 为键，缺键表示「未声明」，空元组表示「明确不支持」——两者都应按不支持处理。
+
+Whether a tool result can natively carry images/documents depends on **provider × API surface**, not on a model-name prefix. Capability data is keyed by `LLMApiSurface`; a missing key means "undeclared" and an empty tuple means "explicitly unsupported" — treat both as unsupported.
+
+```python
+from whosellm import LLMApiSurface, LLMeta
+
+caps = LLMeta("claude-opus-5-5").capabilities
+surface = caps.tool_result_surfaces.get(LLMApiSurface.CLAUDE_MESSAGES)
+print(surface.modalities)          # ("image", "document")
+print(surface.supports("document"))  # True
+
+# Gemini 3 系支持；2.5 系明确不支持（会返回 400）
+print(LLMeta("gemini-3.8-flash").capabilities.tool_result_surfaces[LLMApiSurface.GEMINI].modalities)  # ("image",)
+print(LLMeta("gemini-2.5-pro").capabilities.tool_result_surfaces[LLMApiSurface.GEMINI].modalities)    # ()
+
+# DeepSeek 的 Chat Completions 与 Responses 是两个 surface：
+# Chat Completions tool 消息只能放文本；Responses 的 function_call_output 支持图片，
+# 但 PDF input_file 实测被静默丢弃（2026-10-29 探针）
+print(LLMeta("deepseek-flash").capabilities.tool_result_surfaces[LLMApiSurface.DEEPSEEK].modalities)           # ()
+print(LLMeta("deepseek-flash").capabilities.tool_result_surfaces[LLMApiSurface.DEEPSEEK_RESPONSES].modalities)  # ("image",)
+```
+
+用户消息能力仍由 `supports_vision` / `supports_audio` / `supports_video` / `supports_pdf` 表示，工具结果能力只走 `tool_result_surfaces`。文档上限见 `max_pdf_size_mb`、`max_pdf_pages`、`supported_document_mime_type`；单请求内联媒体预算见 `max_inline_media_bytes`，文件类媒体的请求级合计上限见 `max_inline_file_bytes`。
+
+User-message capability remains on `supports_vision` / `supports_audio` / `supports_video` / `supports_pdf`; tool-result capability lives only in `tool_result_surfaces`. Document limits are exposed via `max_pdf_size_mb`, `max_pdf_pages`, and `supported_document_mime_type`; the per-request inline-media budget is `max_inline_media_bytes`, and the request-level combined cap for file-type media is `max_inline_file_bytes`.
+
 ### 非法名称也不会炸 / Lenient on Unknown Names
 
 我们不想打断你的流程，即便名称不在我们的数据库里也能返回一个「未知模型占位符」。

{whosellm-0.3.0 → whosellm-0.4.0}/docs/add_new_model_family.md

@@ -197,6 +197,19 @@ __all__ = [
 | `max_image_pixels` | `tuple[int, int] \| None` | 最大图片像素(宽, 高) / Max image pixels (width, height) |
 | `max_video_size_mb` | `float \| None` | 最大视频大小(MB) / Max video size in MB |
 | `max_video_duration_seconds` | `int \| None` | 最大视频时长(秒) / Max video duration in seconds |
+| `media_count_limit` | `MediaCountLimit` | 单请求媒体数量上限 / Per-request media count caps |
+| `max_inline_media_bytes` | `int \| None` | 单请求内联媒体字节总预算 / Per-request inline-media byte budget |
+| `max_inline_file_bytes` | `int \| None` | 单请求文件类媒体字节合计上限 / Combined per-request file-type media byte cap |
+| `max_pdf_size_mb` | `float \| None` | PDF 大小上限(MB) / Max PDF size in MB |
+| `max_pdf_pages` | `int \| None` | PDF 页数上限 / Max PDF pages per request |
+| `max_document_size_mb` | `float \| None` | 非 PDF 文档大小上限(MB，预留) / Max non-PDF document size |
+| `supported_document_mime_type` | `list[str]` | 支持的文档 MIME / Supported document MIME types |
+| `tool_result_surfaces` | `dict[LLMApiSurface, ToolResultSurfaceCapability]` | 工具结果按 API surface 的原生媒体能力；缺键 = 未声明，空元组 = 明确不支持 / Native tool-result media capability per surface; missing = undeclared, empty tuple = unsupported |
+| `file_api` | `FileApiCapability \| None` | 文件 API 能力（预留）/ File API capability (reserved) |
+
+工具结果能力是 **provider × API surface** 维度，而不是模型维度。新增模型时应按官方文档登记 `tool_result_surfaces`，并注明来源与抓取日期；未查证的 surface 请保持缺键（内核按不支持处理），不要乐观填写。
+
+Tool-result capability is **provider × API surface**, not per-model. When adding models, register `tool_result_surfaces` from official docs with source and fetch date; leave unverified surfaces undeclared (consumers treat them as unsupported) instead of guessing.
 
 ---
 

{whosellm-0.3.0 → whosellm-0.4.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "whosellm"
-version = "0.3.0"
+version = "0.4.0"
 description = "A unified LLM model version and capability management library"
 authors = [
     {name = "JQQ", email = "jqq1716@gmail.com"}

{whosellm-0.3.0 → whosellm-0.4.0}/tests/e2e/test_anthropic.py

@@ -2,6 +2,7 @@
 
 来源: https://platform.claude.com/docs/en/docs/about-claude/models
 采集日期: 2026-04-12（2026-09-04 增补 Fable 5.1 / Mythos 5.1）
+          2026-09-23 增补 Opus 5.5
 """
 
 import pytest
@@ -10,6 +11,33 @@ from whosellm import ModelFamily, Provider
 
 from .conftest import assert_model_metadata
 
+# ============================================================================
+# Claude Family — Version 5.5 (2026-09-22 发布 / Released 2026-09-22)
+# 来源: https://platform.claude.com/docs/en/release-notes/overview
+# ============================================================================
+
+CLAUDE_55_MODELS = [
+    (
+        "claude-opus-5-5",
+        {
+            # 1M ctx (默认且最大) / 128K out；adaptive thinking 常开且不可关闭
+            # 1M ctx (default & max) / 128K out; adaptive thinking always on, cannot be disabled
+            "provider": Provider.ANTHROPIC,
+            "family": ModelFamily.CLAUDE,
+            "version": "5.5",
+            "variant": "opus",
+            "supports_thinking": True,
+            "supports_vision": True,
+            "supports_streaming": True,
+            "supports_function_calling": True,
+            "supports_structured_outputs": True,
+            "supports_computer_use": True,
+            "context_window": 1_000_000,
+            "max_tokens": 128_000,
+        },
+    ),
+]
+
 # ============================================================================
 # Claude Family — Version 5.1 (2026-09-01 发布 / Released 2026-09-01)
 # 来源: https://platform.claude.com/docs/en/models/fable-5-1/overview
@@ -234,7 +262,13 @@ CLAUDE_30_MODELS = [
 # ============================================================================
 
 ALL_MODELS = (
-    CLAUDE_51_MODELS + CLAUDE_LATEST_MODELS + CLAUDE_45_MODELS + CLAUDE_41_MODELS + CLAUDE_40_MODELS + CLAUDE_30_MODELS
+    CLAUDE_55_MODELS
+    + CLAUDE_51_MODELS
+    + CLAUDE_LATEST_MODELS
+    + CLAUDE_45_MODELS
+    + CLAUDE_41_MODELS
+    + CLAUDE_40_MODELS
+    + CLAUDE_30_MODELS
 )
 
 

whosellm-0.4.0/tests/e2e/test_deepseek.py

@@ -0,0 +1,151 @@
+# filename: test_deepseek.py
+"""
+DeepSeek 官方模型元数据 E2E 测试 / DeepSeek official model metadata E2E tests.
+
+来源 / Sources:
+  https://api-docs.deepseek.com/zh-cn/updates/（2026-09-10 DeepSeek-V4.1-Flash 发布）
+  https://api-docs.deepseek.com/zh-cn/quick_start/pricing
+  https://api-docs.deepseek.com/zh-cn/guides/vision
+采集日期 / Collected: 2026-09-28（含 api.deepseek.com 实探复核 / verified against the live API）
+
+约定 / Conventions:
+  * 旧名（deepseek-v4-flash / -vision-exp / deepseek-chat / deepseek-reasoner）版本仍按名字解析为
+    4.0，能力按当前实际服务模型（转发到 DeepSeek-V4.1-Flash）标注。
+    Legacy names keep their name-derived version (4.0) while capabilities follow the
+    currently serving model (routed to DeepSeek-V4.1-Flash).
+  * deepseek-v4-pro 未被路由，保持纯文本（无图像输入）。
+"""
+
+import pytest
+
+from whosellm import ModelFamily, Provider
+
+from .conftest import assert_model_metadata
+
+# ============================================================================
+# DeepSeek V4.1-Flash 正式名（2026-09-10 发布）/ Canonical name of DeepSeek-V4.1-Flash
+# 官方："将模型名称更改为 deepseek-flash 即可调用最新的 V4.1 Flash 模型"
+# ============================================================================
+
+V41_FLASH_MODELS = [
+    (
+        "deepseek-flash",
+        {
+            "provider": Provider.DEEPSEEK,
+            "family": ModelFamily.DEEPSEEK,
+            # 名字无版本号 → 按官方模型版本 DeepSeek-V4.1-Flash 标注
+            "version": "4.1",
+            "variant": "flash",
+            "supports_thinking": True,  # 默认开启，effort 默认 high
+            "supports_vision": True,  # 原生多模态视觉理解
+            "supports_function_calling": True,
+            "supports_streaming": True,
+            "supports_json_outputs": True,
+            "supports_structured_outputs": False,  # 仅 json_object，无 json_schema
+            "context_window": 1_000_000,
+            "max_tokens": 384_000,
+        },
+    ),
+]
+
+# ============================================================================
+# 兼容路由旧名（官方措辞"暂时路由"）/ Routed legacy names ("temporarily routed" per vendor)
+# ============================================================================
+
+ROUTED_LEGACY_MODELS = [
+    (
+        "deepseek-v4-flash",
+        {
+            "provider": Provider.DEEPSEEK,
+            "family": ModelFamily.DEEPSEEK,
+            "version": "4.0",  # 版本轴按名字 / version parses from the name
+            "variant": "flash",
+            "supports_thinking": True,
+            "supports_vision": True,  # 能力轴跟实际服务模型 / capabilities follow the serving model
+            "supports_function_calling": True,
+            "supports_streaming": True,
+            "context_window": 1_000_000,
+            "max_tokens": 384_000,
+        },
+    ),
+    (
+        "deepseek-v4-flash-vision-exp",
+        {
+            "provider": Provider.DEEPSEEK,
+            "family": ModelFamily.DEEPSEEK,
+            "version": "4.0",
+            "variant": "flash-vision-exp",
+            "supports_thinking": True,
+            "supports_vision": True,
+            "context_window": 1_000_000,
+            "max_tokens": 384_000,
+        },
+    ),
+    (
+        "deepseek-chat",
+        {
+            "provider": Provider.DEEPSEEK,
+            "family": ModelFamily.DEEPSEEK,
+            "version": "4.0",
+            "variant": "chat",
+            "supports_thinking": False,  # 别名默认非思考模式 / alias defaults to non-thinking
+            "supports_vision": True,
+            "context_window": 1_000_000,
+            "max_tokens": 384_000,
+        },
+    ),
+    (
+        "deepseek-reasoner",
+        {
+            "provider": Provider.DEEPSEEK,
+            "family": ModelFamily.DEEPSEEK,
+            "version": "4.0",
+            "variant": "reasoner",
+            "supports_thinking": True,  # 别名默认思考模式 / alias defaults to thinking
+            "supports_vision": True,
+            "context_window": 1_000_000,
+            "max_tokens": 384_000,
+        },
+    ),
+]
+
+# ============================================================================
+# 未被路由：deepseek-v4-pro 仍是 DeepSeek-V4-Pro-0813，纯文本
+# Not routed: deepseek-v4-pro is still DeepSeek-V4-Pro-0813, text-only
+# 实探 2026-09-28：带图不报错但静默忽略并编造答案 → supports_vision 必须为 False
+# ============================================================================
+
+TEXT_ONLY_MODELS = [
+    (
+        "deepseek-v4-pro",
+        {
+            "provider": Provider.DEEPSEEK,
+            "family": ModelFamily.DEEPSEEK,
+            "version": "4.0",
+            "variant": "pro",
+            "supports_thinking": True,
+            "supports_vision": False,
+            "supports_function_calling": True,
+            "supports_streaming": True,
+            "context_window": 1_000_000,
+            "max_tokens": 384_000,
+        },
+    ),
+]
+
+# ============================================================================
+# 聚合 + 参数化 / Aggregation & parametrization
+# ============================================================================
+
+ALL_MODELS = V41_FLASH_MODELS + ROUTED_LEGACY_MODELS + TEXT_ONLY_MODELS
+
+
+@pytest.mark.e2e
+@pytest.mark.parametrize(
+    "model_name,expected",
+    ALL_MODELS,
+    ids=[m[0] for m in ALL_MODELS],
+)
+def test_model_metadata(model_name: str, expected: dict) -> None:  # type: ignore[type-arg]
+    """验证 DeepSeek 模型元数据与官方文档一致。"""
+    assert_model_metadata(model_name, expected)

{whosellm-0.3.0 → whosellm-0.4.0}/tests/e2e/test_openai.py

@@ -15,6 +15,7 @@ from .conftest import assert_model_metadata
 # 来源: https://developers.openai.com/api/docs/models/gpt-5.4（2026-04-12 采集）
 #       https://developers.openai.com/api/docs/models/gpt-5.6-sol（2026-08-20 采集 5.5/5.6）
 #       https://developers.openai.com/api/docs/models/gpt-6-astra（2026-09-04 采集 6-astra/5.6-cyber）
+#       https://developers.openai.com/api/docs/models/gpt-6-sol（2026-09-23 采集 6-sol/6-luna）
 # ============================================================================
 
 GPT_MODELS = [
@@ -219,7 +220,7 @@ GPT_MODELS = [
         },
     ),
     # ------------------------------------------------------------------
-    # GPT-6 Astra 系列（2026-09-04 采集）
+    # GPT-6 天体档位系列（2026-09-04 采集 astra）
     # 来源: https://developers.openai.com/api/docs/models/gpt-6-astra
     # ------------------------------------------------------------------
     (
@@ -239,6 +240,45 @@ GPT_MODELS = [
             "max_tokens": 128_000,
         },
     ),
+    # ------------------------------------------------------------------
+    # GPT-6 Sol / Luna（2026-09-22 发布，2026-09-23 采集）
+    # 与 astra 同窗口同工具面；sol 中档主力、luna 低成本档，GPT-6 无 terra 档
+    # 来源: https://developers.openai.com/api/docs/models/gpt-6-sol
+    # ------------------------------------------------------------------
+    (
+        "gpt-6-sol",
+        {
+            "provider": Provider.OPENAI,
+            "family": ModelFamily.GPT,
+            "version": "6.0",
+            "variant": "sol",
+            "supports_thinking": True,
+            "supports_vision": True,
+            "supports_streaming": True,
+            "supports_function_calling": True,
+            "supports_structured_outputs": True,
+            "supports_computer_use": True,
+            "context_window": 1_050_000,
+            "max_tokens": 128_000,
+        },
+    ),
+    (
+        "gpt-6-luna",
+        {
+            "provider": Provider.OPENAI,
+            "family": ModelFamily.GPT,
+            "version": "6.0",
+            "variant": "luna",
+            "supports_thinking": True,
+            "supports_vision": True,
+            "supports_streaming": True,
+            "supports_function_calling": True,
+            "supports_structured_outputs": True,
+            "supports_computer_use": True,
+            "context_window": 1_050_000,
+            "max_tokens": 128_000,
+        },
+    ),
 ]
 
 # ============================================================================

{whosellm-0.3.0 → whosellm-0.4.0}/tests/models/families/test_anthropic.py

@@ -253,7 +253,7 @@ class TestClaudeMythosClassOrdering:
         assert LLMeta("claude-mythos-5") > LLMeta("claude-fable-5")
 
     def test_mythos5_is_top(self):
-        """mythos-5 为当前最高 / mythos-5 is the highest among current Claude models"""
+        """mythos-5 在所列模型中最高 / mythos-5 is the highest among the models listed"""
         models = [
             LLMeta("claude-mythos-5"),
             LLMeta("claude-fable-5"),
@@ -264,6 +264,57 @@ class TestClaudeMythosClassOrdering:
         assert max(models).variant == "mythos"
 
 
+class TestClaudeOpus55:
+    """Claude Opus 5.5 测试（2026-09-22 发布，当前最新） / Claude Opus 5.5 tests (released 2026-09-22)"""
+
+    def test_specific_model_config(self):
+        """验证 claude-opus-5-5 配置 / Validate claude-opus-5-5 config"""
+        config = get_specific_model_config("claude-opus-5-5")
+        assert config is not None
+        version, variant, capabilities = config
+        assert version == "5.5"
+        assert variant == "opus"
+        assert capabilities is not None
+        assert capabilities.supports_vision is True
+        assert capabilities.supports_thinking is True  # 自适应思考常开且不可关闭 / always on, cannot be disabled
+        assert capabilities.supports_function_calling is True
+        assert capabilities.supports_streaming is True
+        assert capabilities.supports_structured_outputs is True
+        assert capabilities.supports_computer_use is True
+        assert capabilities.max_tokens == 128000
+        assert capabilities.context_window == 1000000
+
+    def test_pattern_match(self):
+        """验证 claude-opus-5-5 模式匹配 / Validate claude-opus-5-5 pattern match"""
+        matched = match_model_pattern("claude-opus-5-5")
+        assert matched is not None
+        assert matched["family"] == ModelFamily.CLAUDE
+        assert matched["variant"] == "opus"
+        assert matched["provider"] == Provider.ANTHROPIC
+        assert matched["_from_specific_model"] == "claude-opus-5-5"
+
+    @pytest.mark.parametrize("model_name", ["claude-opus-5-5-20260921", "claude-opus-5-5@20260921"])
+    def test_pattern_with_snapshot(self, model_name: str):
+        """验证带 snapshot 的解析（- 与 @ 两种格式，版本号不被吞） / Validate snapshot forms keep version 5.5"""
+        meta = LLMeta(model_name)
+        assert meta.family == ModelFamily.CLAUDE
+        assert meta.version == "5.5"
+        assert meta.variant == "opus"
+
+    def test_not_swallowed_by_opus5(self):
+        """claude-opus-5-5 不得被 claude-opus-5 的配置吞掉 / opus-5-5 must not be captured by opus-5
+
+        回归保护：opus-5 的子模式在 opus-5-5 之前注册，若 snapshot 宽度匹配不当会退化为 5.0
+        Regression guard: opus-5's sub-patterns register before opus-5-5's; a loose snapshot
+        width would silently degrade opus-5-5 to version 5.0
+        """
+        meta = LLMeta("claude-opus-5-5")
+        assert meta.version == "5.5"
+        assert meta.variant == "opus"
+        assert meta.capabilities.context_window == 1000000
+        assert meta.capabilities.max_tokens == 128000
+
+
 class TestClaudeOpus5:
     """Claude Opus 5 测试（2026-07-24 GA） / Claude Opus 5 tests"""
 
@@ -345,6 +396,19 @@ class TestClaude5Ordering:
         """opus-5 (v5.0) 高于 opus-4-8 (v4.8) / opus-5 outranks opus-4-8 by version"""
         assert LLMeta("claude-opus-5") > LLMeta("claude-opus-4-8")
 
+    def test_opus55_outranks_opus5(self):
+        """opus-5-5 (v5.5) 高于 opus-5 (v5.0) / opus-5-5 outranks opus-5 by version"""
+        assert LLMeta("claude-opus-5-5") > LLMeta("claude-opus-5")
+        assert LLMeta("claude-opus-5-5") > LLMeta("claude-fable-5-1")
+
+    def test_opus55_outranks_mythos5_by_version(self):
+        """版本优先于档位：opus-5-5 (v5.5) 高于 mythos-5 (v5.0)，尽管 mythos 变体档更高
+        Version precedes tier: opus-5-5 outranks mythos-5 despite mythos's higher variant tier
+        """
+        assert LLMeta("claude-opus-5-5") > LLMeta("claude-mythos-5")
+        # 同版本 5.0 内档位排序不受影响 / tier ordering within v5.0 is unaffected
+        assert LLMeta("claude-mythos-5") > LLMeta("claude-fable-5")
+
     def test_sonnet5_outranks_sonnet46(self):
         """sonnet-5 (v5.0) 高于 sonnet-4-6 (v4.6) / sonnet-5 outranks sonnet-4-6 by version"""
         assert LLMeta("claude-sonnet-5") > LLMeta("claude-sonnet-4-6")
@@ -358,7 +422,9 @@ class TestClaude5Ordering:
         assert LLMeta("claude-fable-5") > LLMeta("claude-opus-5")
 
     def test_mythos5_is_top(self):
-        """mythos-5 仍为当前最高 / mythos-5 remains the highest among current Claude models"""
+        """同代 v5.0 内 mythos 档最高（v5.1/v5.5 按版本另行比较）
+        mythos is the top tier within the v5.0 generation (v5.1/v5.5 compare by version)
+        """
         models = [
             LLMeta("claude-mythos-5"),
             LLMeta("claude-fable-5"),

{whosellm-0.3.0 → whosellm-0.4.0}/tests/models/families/test_deepseek.py

@@ -209,3 +209,102 @@ def test_deepseek_v4_flash_vision_exp_llmeta() -> None:
     assert model.variant == "flash-vision-exp"
     assert model.capabilities.context_window == 1_000_000
     assert model.capabilities.supports_vision is True
+
+
+class TestDeepSeekRouting:
+    """DeepSeek 旧模型名的路由实况 / Routing reality of DeepSeek legacy names.
+
+    官方原文（2026-09-10 changelog）："旧版本模型 V4 Flash 与 V4 Flash Vision Exp 现已下线，
+    出于兼容考虑，模型名 deepseek-v4-flash、deepseek-v4-flash-vision-exp 将被暂时路由到 V4.1 Flash。"
+    Official: legacy V4 Flash / V4 Flash Vision Exp are offline; their model names are
+    *temporarily* routed to V4.1 Flash.
+
+    实探证据（2026-09-28，api.deepseek.com，见 /tmp/probe_deepseek.py）：
+      - GET /models 仅返回 deepseek-flash 与 deepseek-v4-pro
+      - deepseek-v4-flash / deepseek-v4-flash-vision-exp / deepseek-chat / deepseek-reasoner
+        的响应 model 字段均回显 deepseek-flash，且能正确读出白底红方块
+      - deepseek-v4-pro 回显自身，带图不报错但静默忽略并编造答案
+
+    ⚠️ 路由是"暂时"的：官方撤销后本类测试会失败，届时需重新探针并回改配置
+    （能力轴跟端点现状，版本轴跟名字血统）。/ The routing is temporary: when the vendor
+    removes it these tests fail on purpose, prompting a re-probe and a config rollback.
+    """
+
+    def test_deepseek_flash_canonical_name(self) -> None:
+        """deepseek-flash 为官方正式名（无版本号），对应 DeepSeek-V4.1-Flash"""
+        from whosellm import LLMeta
+
+        model = LLMeta("deepseek-flash")
+        assert model.provider == Provider.DEEPSEEK
+        assert model.family == ModelFamily.DEEPSEEK
+        # 名字无版本号 → 按官方模型版本标注 4.1
+        assert model.version == "4.1"
+        assert model.variant == "flash"
+
+        caps = model.capabilities
+        assert caps.supports_vision is True
+        assert caps.supports_thinking is True  # 默认开启 / on by default
+        assert caps.media_count_limit.get("image") == 600
+        assert caps.context_window == 1_000_000
+        assert caps.max_tokens == 384_000
+
+    def test_v4_flash_routed_to_v41_flash(self) -> None:
+        """deepseek-v4-flash 已被路由到 V4.1 Flash，视觉能力随之可用"""
+        from whosellm import LLMeta
+
+        model = LLMeta("deepseek-v4-flash")
+        # 版本轴仍按名字解析为 4.0 / version still parses from the name (4.0)
+        assert model.version == "4.0"
+        assert model.variant == "flash"
+        # 能力轴跟随实际服务模型 / capabilities follow the serving model
+        assert model.capabilities.supports_vision is True
+        assert model.capabilities.media_count_limit.get("image") == 600
+
+    def test_vision_exp_routed_to_v41_flash(self) -> None:
+        """deepseek-v4-flash-vision-exp 同样被路由到 V4.1 Flash"""
+        from whosellm import LLMeta
+
+        model = LLMeta("deepseek-v4-flash-vision-exp")
+        assert model.version == "4.0"
+        assert model.capabilities.supports_vision is True
+        assert model.capabilities.media_count_limit.get("image") == 600
+
+    def test_chat_and_reasoner_routed_have_vision(self) -> None:
+        """deepseek-chat / deepseek-reasoner 路由到 flash，同样可读图
+
+        两者保留各自的默认思考模式语义（chat 非思考、reasoner 思考），
+        但视觉能力跟随实际服务模型。
+        """
+        from whosellm import LLMeta
+
+        chat = LLMeta("deepseek-chat")
+        assert chat.capabilities.supports_thinking is False  # 默认非思考 / non-thinking by default
+        assert chat.capabilities.supports_vision is True
+        assert chat.capabilities.media_count_limit.get("image") == 600
+
+        reasoner = LLMeta("deepseek-reasoner")
+        assert reasoner.capabilities.supports_thinking is True
+        assert reasoner.capabilities.supports_vision is True
+        assert reasoner.capabilities.media_count_limit.get("image") == 600
+
+    def test_v4_pro_not_routed_stays_text_only(self) -> None:
+        """deepseek-v4-pro 未被路由，保持纯文本（带图会静默幻觉，绝不能标 True）
+
+        实探：带图请求返回 200，图片被静默忽略，答案系编造；无图对照亦编造；
+        直接追问时模型承认"看不到图片 / [Unsupported Image]"。
+        来源：https://api-docs.deepseek.com/zh-cn/quick_start/pricing（图像理解 不支持）
+        """
+        from whosellm import LLMeta
+
+        model = LLMeta("deepseek-v4-pro")
+        assert model.version == "4.0"
+        assert model.variant == "pro"
+        assert model.capabilities.supports_vision is False
+        assert model.capabilities.media_count_limit.get("image") == 0  # 键缺失视同不支持
+
+    def test_version_axis_orders_flash_above_pro(self) -> None:
+        """版本优先于档位：V4.1 Flash > V4 Pro（与官方"全面超越 V4 Pro"表述一致）"""
+        from whosellm import LLMeta
+
+        assert LLMeta("deepseek-flash") > LLMeta("deepseek-v4-pro")
+        assert LLMeta("deepseek-v4-pro") > LLMeta("deepseek-v4-flash")