fix(core): 将空 list modalities 视为未配置，修复图片无法传递到模型的问题

[Sisyphbaous-DT-Project]

问题描述

从 v4.24.5 升级到 v4.25.2 后，所有未在 WebUI 中手动配置模型能力（modalities） 的 provider 出现以下问题：

1. QQ 群聊中发送图片（包括引用图片），多模态主模型完全收不到图片，无法进行识图
2. 第三方插件通过 event.request_llm(image_urls=...) 主动调用 LLM 时，传入的图片被静默丢弃
3. 配置了专用图片转述模型后，引用图片的 captioning 流程被跳过
4. 部分场景下工具调用（tool_use）被错误清除

而 v4.24.5 中一切正常。

根本原因分析

问题的根源是 modalities 字段的语义不一致，由两个因素叠加导致：

因素一：配置迁移将未配置的 modalities 写为 []

migra_helper.py 在迁移 provider 配置时，对未设置 modalities 的 provider 统一写入空列表：

if "modalities" not in provider:
    provider["modalities"] = []

升级前 modalities 字段不存在时为 None，升级后被改写为 []。

因素二：多处代码对 [] 与 None 的处理不一致

v4.25.2 新增的 _provider_supports_modality() 以及原有的 _assemble_request_context_for_provider() 等函数，对 [] 和 None 存在两种截然不同的分支：

modalities 值	_provider_supports_modality("image")	_assemble_request_context_for_provider
None	False	isinstance(None, list) → False → 保留图片
[]	False	isinstance([], list) → True → "image" in [] → False → 清空图片

在 v4.24.5 中，modalities 通常为 None（字段未定义），图片能正常传递。升级后变为 []，上述函数进入「明确配置了不支持图片」的分支，导致 image_urls 被静默清空、工具被错误清除。

完整因果链：

migra_helper: modalities=None → modalities=[]
    ↓
_provider_supports_modality("image") → False
    ↓
_select_image_chat_provider() 找不到 fallback，但仍使用主模型
    ↓
_assemble_request_context_for_provider()
    → isinstance([], list) → True
    → "image" in [] → False
    → image_urls 被替换为 []
    ↓
模型请求中完全不包含图片内容

修复方案

将空列表 [] 视为「未配置」，与 None 保持一致行为。只有当 modalities 为非空 list 时，才启用过滤/修复逻辑。

涉及以下 5 处修改（共 2 个文件）：

astrbot/core/astr_main_agent.py

_provider_supports_modality()： 对空列表返回 True（默认支持），而非 False

def _provider_supports_modality(provider: Provider, modality: str) -> bool:
    modalities = provider.provider_config.get("modalities", None)
    if modalities == []:
        return True  # 空列表视为未配置，默认支持，保持向后兼容
    return isinstance(modalities, list) and modality in modalities

astrbot/core/agent/runners/tool_loop_agent_runner.py

_assemble_request_context_for_provider()： not isinstance(modalities, list) → not modalities，空列表也走「保留图片」分支

_should_fix_modalities_for_provider()： 增加 and modalities 条件，空列表不触发历史上下文修复

_func_tool_for_provider()： 增加 and modalities 条件，空列表不清除工具

tool loop 中 cached images 处理： "image" in modalities → not modalities or "image" in modalities

验证步骤

1. 复现脚本验证

编写了独立的复现脚本 reproduce_issue.py，模拟从 ProviderRequest 到最终上下文的完整链路

修复前 modalities=[] 的 image_urls 为 []（已清空），修复后正确保留。

2. 单元测试

82 passed, 0 failed, 0 skipped

所有现有测试通过，其中包括 _provider_supports_modality 相关的边界条件测试。

3. 各场景行为对比

场景	modalities	修复前	修复后	预期
用户消息带图片	[]	图片被清空 ❌	图片正常传递 ✅	正常
引用图片消息	[]	captioning 被跳过 ❌	正常传原图 ✅	正常
主动消息插件传图	[]	图片被清空 ❌	图片正常传递 ✅	正常
tool call 返回图片	[]	cached images 不追加 ❌	正常追加 ✅	正常
明确配置 ["text"]	["text"]	图片被清空 ✅	图片被清空 ✅	正常
明确配置 ["text","image"]	["text","image"]	图片正常 ✅	图片正常 ✅	正常

• This is NOT a breaking change. / 这不是一个破坏性变更。

Screenshots or Test Results / 运行截图或测试结果

修复前（当前版本）

修复后

• 复现脚本：编写了独立的复现脚本，模拟从 ProviderRequest 到最终上下文的完整链路。修复前 modalities=[] 时 image_urls 被清空为 []，修复后正确保留所有传入的图片路径，Bug 不再复现。
• 代码质量：ruff check 和 ruff format --check 全部通过，无格式或 lint 问题。
• 单元测试：pytest tests/unit/test_astr_main_agent.py 82 项全部通过，覆盖了 _provider_supports_modality 的边界条件测试。

---

Checklist / 检查清单

• 😊 If there are new features added in the PR, I have discussed it with the authors through issues/emails, etc.
  / 如果 PR 中有新加入的功能，已经通过 Issue / 邮件等方式和作者讨论过。

• 👀 My changes have been well-tested, and "Verification Steps" and "Screenshots" have been provided above.
  / 我的更改经过了良好的测试，并已在上方提供了“验证步骤”和“运行截图”。

• 🤓 I have ensured that no new dependencies are introduced, OR if new dependencies are introduced, they have been added to the appropriate locations in requirements.txt and pyproject.toml.
  / 我确保没有引入新依赖库，或者引入了新依赖库的同时将其添加到 requirements.txt 和 pyproject.toml 文件相应位置。

• 😮 My changes do not introduce malicious code.
  / 我的更改没有引入恶意代码。

Summary by Sourcery

Treat empty provider modality lists as unconfigured to restore backward-compatible multimodal behavior and image handling.

Bug Fixes:

• Ensure image URLs are preserved and passed through for providers whose modalities are unset or migrated to empty lists.
• Prevent unintended clearing of tools when provider modalities are an empty list.
• Allow cached images from tool calls to be appended for providers with empty modality lists instead of being treated as non-image-capable.

Enhancements:

• Align modality handling across core agents so that only non-empty modality lists restrict supported capabilities.

[gemini-code-assist]

Code Review

This pull request updates the handling of provider modalities to treat an empty list or None as unconfigured, defaulting to supporting all modalities for backward compatibility. However, in astrbot/core/astr_main_agent.py, the _provider_supports_modality function treats None and [] inconsistently, where None returns False and [] returns True. It is recommended to update this function to return True for both cases to ensure consistent behavior and prevent unnecessary fallback switches.

[sourcery-ai]

Hey - I've left some high level feedback:

• The logic for treating an empty modalities list as "unconfigured" is duplicated in several places; consider extracting a small helper (e.g., is_unconfigured_modalities(modalities)) to centralize this backward-compatibility rule and avoid drift in future changes.
• In _provider_supports_modality you check modalities == [] while other call sites use not modalities; aligning on one approach (and clearly documenting it) would make the semantics around empty lists vs. other falsy values easier to reason about.

Prompt for AI Agents

Please address the comments from this code review:

## Overall Comments
- The logic for treating an empty modalities list as "unconfigured" is duplicated in several places; consider extracting a small helper (e.g., `is_unconfigured_modalities(modalities)`) to centralize this backward-compatibility rule and avoid drift in future changes.
- In `_provider_supports_modality` you check `modalities == []` while other call sites use `not modalities`; aligning on one approach (and clearly documenting it) would make the semantics around empty lists vs. other falsy values easier to reason about.

---

Sourcery is free for open source - if you like our reviews please consider sharing them ✨

• X
• Mastodon
• LinkedIn
• Facebook

_{Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.}