CyberStrikeAI 视觉分析指南掌握 analyze_image MCP 工具的图片理解、预处理与合规实践【免费下载链接】CyberStrikeAIThe system of action for AI-native cybersecurity—where intent becomes governed execution, evidence becomes operational memory, and every operation improves the next.项目地址: https://gitcode.com/GitHub_Trending/cy/CyberStrikeAI导读本指南系统讲解 CyberStrikeAI 内置视觉分析能力——analyze_imageMCP 工具。该工具为 Agent 提供读图但不存图的图片理解通道读取本地图片经缩放与 JPEG 压缩预处理后调用独立 Vision 多模态模型最终只把纯文本摘要交还给 Agent图片字节绝不写入对话历史。读完本文你将掌握完整的vision配置节每个参数的含义与默认值、图片预处理与压缩的底层算法、路径安全校验规则以及在实际授权安全测试流程中合规使用该工具的边界。功能概述Agent 的读图能力如何工作analyze_image是 CyberStrikeAI 内置注册的 MCP 工具工具名常量定义于 internal/mcp/builtin/constants.go。当vision.enabled: true且配置了视觉模型后该工具才会被注册到 MCP 服务器其注册入口为 internal/app/vision_tools.go具体逻辑实现在 internal/vision/tool.go。从 internal/vision/tool.go 中的工具定义可见其核心行为是一条清晰的数据流水线本地图片路径 → 路径校验 → 图片预处理缩放 / JPEG 压缩 → 独立 Vision 模型调用 → 纯文本返回 Agent输入path必填图片绝对路径或相对进程工作目录的路径以及可选的question希望模型重点回答的问题例如验证码场景可要求只输出验证码字符。输出仅文本包含图片路径、预处理元信息原始/输出尺寸、JPEG 质量、字节数、passthrough 或 jpeg 模式与模型生成的文字摘要见formatAnalysisResult实现internal/vision/tool.go。上下文隔离图片字节只出现在单次 Vision 模型调用中Agent 的历史上下文只保留文字摘要。这一设计同时压缩了上下文体积、避免原始图片在多个 Agent 间意外传播。analyze_image作为内置工具还受到 MCP 权限体系的约束在 internal/app/mcp_authorization.go 中调用它需要agent:execute权限即与普通 Agent 执行动作同级而非任意访客可调用。配置详解vision 配置节逐参数说明完整配置样例位于仓库根目录的 config.example.yaml。以下为完整配置块并附每个参数的取值范围与默认行为# 视觉分析analyze_image MCP 工具图片仅在单次 VL 调用中出现Agent 上下文只保留文字摘要 vision: enabled: false # true 且 model 非空时注册 analyze_image model: qwen-vl # VL 模型名enabled 时必填 api_key: # 留空则复用默认 AI 通道 api_key base_url: # 留空则复用默认 AI 通道 base_url provider: # 留空则复用默认 AI 通道 provideropenai_compatible | claude max_image_bytes: 5242880 # 原始文件上限字节默认 5MB max_dimension: 2048 # 长边缩放像素 jpeg_quality: 82 max_payload_bytes: 524288 # 编码后送 VL API 上限默认 512KB skip_preprocess_below_bytes: 2097152 # 低于 2MB 且长边max_dimension 且max_payload 时原图直传0始终压缩 detail: auto # low | high | autoEino ImageURLDetail timeout_seconds: 60各参数说明参数类型默认行为说明enabledboolfalse为false时不注册analyze_image工具modelstring必填enabled 时视觉模型名如qwen-vl、qwen-vl-max为空时即使enabled: true也会跳过注册并记录警告api_keystring继承默认 AI 通道留空/省略时复用主openai配置的 api_keybase_urlstring继承默认 AI 通道留空/省略时复用主openai配置的 base_urlproviderstring继承默认 AI 通道openai_compatible或claude决定走 Eino OpenAI 兼容客户端还是 Claude 原生通道max_image_bytesint645MB5242880原始图片文件大小上限超出直接拒绝max_dimensionint2048长边缩放目标像素jpeg_qualityint82JPEG 重编码质量有效范围 1-100max_payload_bytesint64512KB524288编码后送入 VL API 的字节上限压缩结果必须收敛到该值以下skip_preprocess_below_bytesint642MB2097152低于该阈值且长边 ≤ max_dimension 且 ≤ max_payload 时原图直传0表示始终 JPEG 压缩detailstringlowlow/high/auto映射到 EinoImageURLDetail控制送入模型的图片细节档位timeout_secondsint60单次 VL 调用超时参数默认值的源码保证这些默认行为并非仅靠文档约束而是由 internal/config/vision.go 中的一系列Effective方法在运行时兜底TimeoutSecondsEffective()timeout_seconds 0时返回 60MaxImageBytesEffective() 0时返回 5MBMaxDimensionEffective() 0时返回 2048JPEGQualityEffective() 0 或 100时回退到 82MaxPayloadBytesEffective() 0时返回 512KBSkipPreprocessBelowBytesEffective()负值按 0始终压缩处理DetailEffective()只接受high/low/auto其他值一律回退为low。通道继承与合并逻辑视觉通道与主 AI 通道的合并实现在OpenAICfgEffective(main OpenAIConfig)internal/config/vision.go先以主openai配置为基底然后仅当vision.api_key、base_url、model、provider非空时才用视觉配置覆盖对应字段最后强制Reasoning.Mode off视觉识别不需要推理链。Ready()方法则判定已启用且模型名非空作为工具注册前提。图片预处理从原图到 VL 载荷的完整链路预处理是analyze_image的减肥环节实现在 internal/vision/preprocess.go核心函数为PreprocessImageFile整体逻辑分三步文件大小闸门os.Stat取得文件大小超过max_image_bytes直接报错拒绝internal/vision/preprocess.go。尝试原图直传passthroughtryPassthrough仅在skip_preprocess_below_bytes 0、文件大小低于该阈值、长边 ≤max_dimension、大小 ≤max_payload_bytes四条同时成立时才返回原图字节与原始 MIMEinternal/vision/preprocess.go。小图不折腾大图才压缩这正是skip_preprocess_below_bytes存在的意义。imaging 缩放 JPEG 渐进压缩否则走compressWithImaging——先用imaging.Fit(src, maxDim, maxDim, imaging.Lanczos)将长边缩放到max_dimensionLanczos 重采样保证缩放质量再做先降尺寸、后降质量的双循环收敛internal/vision/preprocess.go外层循环最多 6 次每次把目标尺寸乘以 0.85下限 256px重新Fit内层循环从jpeg_quality起以 5 为步长递减质量不低于 60只要编码后字节数 ≤max_payload_bytes即返回最终输出统一为image/jpeg。若双循环耗尽仍无法收敛到载荷上限返回明确错误could not compress image under max_payload_bytes。预处理结果会通过PreprocessMeta完整记录原始/输出尺寸、字节数、JPEG 质量与模式passthrough/jpeg并格式化进工具返回文本方便排障与审计。上述行为均有测试用例固化internal/vision/preprocess_test.go 覆盖了3000×2000 大图缩放至 1024 内且载荷 ≤ 600KB、400×300 小图 passthrough 直传且 MIME 为 image/png、skip_preprocess_below_bytes0 时小图也强制 JPEG 压缩、超过 max_image_bytes 被拒绝四种典型场景。视觉客户端双通道模型适配预处理后的图片由 internal/vision/client.go 的Client.Analyze送入 VL 模型。该客户端在调用前会再次校验 api_key 与 model 非空并按timeout_seconds设置超时HTTP 客户端超时在timeout 15s拨号与响应头超时也单独兜底随后将图片字节 base64 编码依据detail档位映射到 Eino 的ImageURLDetailLow/High/Auto构造文本提示词 图片块的多模态消息。通道选择取决于providerClaude 通道provider: claude通过llm.NewClaudeAgenticModel构建原生 Claude 模型消息使用schema.AgenticMessage携带UserInputText与UserInputImageBase64 MIME Detail两个内容块OpenAI 兼容通道默认通过openai.NewEinoHTTPClient与einoopenai.NewChatModel构建 Eino OpenAI 兼容模型消息使用UserInputMultiContent同时携带文本与image_url类型图片块。提示词构建buildVisionPromptinternal/vision/client.go内置了安全测试导向默认要求侧重授权安全测试场景可见文本、表单、按钮、验证码、错误信息、技术栈线索且当问题命中验证码关键词验证码 / captcha / verification code / vcode / 图形码或只输出字符句式时会自动追加仅输出辨认出的字符序列不要空格、标点、解释的指令looksLikeCaptchaQuestion。模型返回空内容会被视为错误。路径解析与安全校验analyze_image可读取服务器上任意可读图片路径绝对路径或相对进程工作目录的相对路径但必须通过 internal/vision/path.go 的ResolveImagePath校验扩展名校验仅允许png / jpg / jpeg / webp / gif / bmp / tif / tiff八类目录与常规文件校验目录路径直接拒绝大小闸门磁盘文件超过 1GB130拒绝符号链接规范化通过filepath.EvalSymlinks解析符号链接后的真实路径防止路径逃逸类绕过。也就是说路径自由度大支持任意目录但文件类型、常规性、体积都有硬约束。适用与禁用场景依据文档与工具描述analyze_image面向授权安全测试工作流中的以下场景适用UI 截图Web 控制台、工具界面、报表页面的状态确认视觉漏洞证据报错弹窗、越权返回的可见信息、前端校验绕过后的异常状态验证码或基于图片的提示授权测试中需要识别图形码字符解读工具截图扫描器、代理工具、取证工具的输出界面。不适用 / 禁止与任务无关的个人图片未经授权的敏感截图当文字摘要已足够时长期存放原始证据——文档明确建议能用文字摘要就不存原始图。Agent 集成与 Web 设置系统提示约束系统提示已向 Agent 声明——遇到图片应调用analyze_image不要用read_file直接读取二进制图片期望理解内容。这是因为 MCP 工具返回的是结构化文本描述而read_file只会返回无法理解的原始字节。工具可见性建议在multi_agent.eino_middleware.tool_search_always_visible_tools中显式包含analyze_image使该工具在 Agent 的工具搜索中始终可见仓库中对应实现见 internal/multiagent/tool_always_visible.go避免 Agent 因工具检索排序而漏选图片理解能力。Web 配置入口系统设置 → 基本设置 → 视觉分析analyze_image提供图形化配置——启用开关、视觉模型、API Key / Base URL留空复用默认 AI 通道、预处理参数。点击保存并应用后写入config.yaml并重新注册 MCP 工具。合规边界启用视觉分析意味着图片字节会被发送到vision配置的上游 Vision API。因此敏感环境涉密内网、客户生产数据应使用可信网关代理或将enabled保持为false从数据流设计看图片字节仅存在于单次 VL 调用中Agent 上下文与数据库只保留文字摘要这是本模块内置的隐私削减设计实际使用时仍需遵循授权测试的边界只处理与当前任务直接相关的图片不把工具当作通用图片浏览通道。源码锚点速查工具注册入口internal/app/vision_tools.go工具定义与 MCP 注册internal/vision/tool.go预处理实现internal/vision/preprocess.go、测试 internal/vision/preprocess_test.goVL 客户端internal/vision/client.go路径校验internal/vision/path.go配置结构internal/config/vision.go配置示例config.example.yaml工具常量与内置工具清单internal/mcp/builtin/constants.go权限绑定agent:executeinternal/app/mcp_authorization.go注册时机internal/app/app.go【免费下载链接】CyberStrikeAIThe system of action for AI-native cybersecurity—where intent becomes governed execution, evidence becomes operational memory, and every operation improves the next.项目地址: https://gitcode.com/GitHub_Trending/cy/CyberStrikeAI创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考