图像上下文助手插件

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 文本，既省钱又避免了因上下文过长导致的截断。

工作优先级 (数据提取)

插件获取图片数据的优先级如下：

1. 内存 Base64：消息体中已有的原生数据。
2. 本地缓存 (Local Cache)：AstrBot 核心已下载的本地文件（解决 Telegram 图片问题的最佳路径）。
3. 网络下载 (15s 超时)：作为最后兜底手段。

安装与使用

1. 将插件放置在 data/plugins/ 目录下。
2. 在 WebUI 中重载插件。
3. 使用示例：
   • 用户发送图片。
   • 用户：“用 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 图片处理稳定性。