AstrBot Plugin: Image Context Helper (v1.1.5)
此插件专为 AstrBot 设计，旨在解决大语言模型（LLM）调用 MCP 工具时，因无法获取上下文图像数据（特别是受限的 Telegram 链接）而导致的调用失败问题。
核心特性
1. 轻量优先策略 (Default URL Mode)
- 默认行为：插件默认仅向 LLM 返回图片的 URL 链接。
- 优势：极速响应，零 Token 浪费。适用于公网可访问的图片链接（如百度图片、微博等）。
2. 智能重试机制 (Retry Base64 Mode)
- 场景：当 MCP 工具因网络原因（如 Telegram API 无法访问）报错时，LLM 会根据引导，主动调用工具并请求 Base64 模式。
- 魔术占位符：为了节省 Token，插件在 Base64 模式下仍不回传原始数据，而是返回一个特殊信号：
base64://ASTRBOT_PLUGIN_CACHE_PENDING。
3. 拦截注入技术 (Pre-Execution Injection)
- 底层拦截：使用 AstrBot 的
on_using_llm_tool钩子，在工具执行的前一刻进行拦截。 - 透明注入：插件自动识别占位符，并从 本地缓存（优先）或 强制下载 渠道获取真实图片数据，直接注入到 MCP 工具的参数中。
- 对模型透明：大模型从未“经手”庞大的 Base64 文本，既省钱又避免了因上下文过长导致的截断。
工作优先级 (数据提取)
插件获取图片数据的优先级如下：
- 内存 Base64：消息体中已有的原生数据。
- 本地缓存 (Local Cache)：AstrBot 核心已下载的本地文件（解决 Telegram 图片问题的最佳路径）。
- 网络下载 (15s 超时)：作为最后兜底手段。
安装与使用
- 将插件放置在
data/plugins/目录下。 - 在 WebUI 中重载插件。
- 使用示例：
* 用户发送图片。 * 用户：“用 MCP 分析这张图”。 * LLM 第一步：调用 get_image_from_context 获取 URL。 * LLM 第二步：尝试用 URL 调用 MCP。 * （若失败）LLM 第三步：调用 get_image_from_context(return_type='base64')。 * LLM 第四步：使用占位符再次调用 MCP，插件自动完成注入并执行成功。
更新日志
- v1.1.5: 修正了无法获取工具来源的问题。
- v1.1.4: 优化提示词引导，强制 LLM 优先使用轻量化的 URL 模式。
- v1.1.1 - v1.1.3: 引入
on_using_llm_tool拦截器，解决占位符注入失败问题。 - v1.0.8: 增加下载超时控制（15s），防止网络波动导致卡死。
- v1.0.4: 优先读取本地缓存文件，大幅提升 Telegram 图片处理稳定性。