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 内置 MCP 工具analyze_image为核心完整讲解视觉分析功能在授权安全测试场景中的启用配置、Web 端操作、Agent 调用约定与底层实现原理。读完本文你将掌握如何通过config.yaml或 Web 控制台启用独立 Vision 模型、理解图片预处理与直传的降级策略、正确引导 Agent 识别验证码/UI/报错截图并了解图片数据流出边界与合规要点。一、功能概述analyze_image是什么analyze_image是 CyberStrikeAI 注册在 MCP 服务器上的内置工具工具常量定义见 internal/mcp/builtin/constants.go。它解决的是一类非常具体的 Agent 能力缺口当 Agent 在授权测试流程中遇到本地图片文件时无法用文本模型直接看懂二进制内容而传统的read_file只适合读取文本。该工具的完整行为链路是输入服务器上的图片文件路径绝对路径或相对进程工作目录的路径预处理读取本地图片 → 使用imaging库缩放 / JPEG 压缩或满足条件时原图直传推理调用独立配置的 Vision 模型与主对话模型解耦输出返回纯文本描述给 Agent。其设计上有两个非常关键的安全特征见 internal/vision/tool.go 的工具描述与输入输出约定图片字节不会写入对话历史原始图像数据只存在于单次 VLVision-Language模型调用中Agent 上下文中仅保留图片路径 文字摘要避免大体积 base64 图像撑爆上下文窗口输出仅为文本工具返回mcp.ToolResult的text内容IsError区分成败Agent 拿到的是结构化文字而非图片数据。从源码结构看这一设计刻意把图像理解与对话记忆隔离图片只服务一次性的视觉推理后续 Agent 记忆依赖的是摘要文字这既节省 token 又降低敏感图像在上下文中的留存面。工具输入参数工具 Schema 定义internal/vision/tool.go参数类型必填说明pathstring是图片绝对路径或相对于进程工作目录的路径questionstring否期望模型重点回答的问题验证码场景建议写明只输出验证码字符不要空格和解释工具描述中明确告知 Agent 的适用场景验证码、UI 元素、报错信息、架构图要点等见 internal/vision/tool.go。二、配置config.yaml中的vision段2.1 完整配置示例仓库根目录的 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关联文档 docs/zh-CN/VISION.md 中给出的是等价的精简版核心参数含义如下参数默认值作用enabledfalse是否启用视觉分析false时不注册analyze_image工具model必填Vision 模型名如qwen-vl-max启用时若为空则跳过注册api_key/base_url/provider留空留空则复用默认 AI 通道openai段的对应字段max_image_bytes52428805MB原始文件大小上限超出直接拒绝max_dimension2048长边缩放目标像素jpeg_quality82JPEG 重编码质量1-100max_payload_bytes524288512KB编码后送往 VL API 的字节上限skip_preprocess_below_bytes20971522MB低于该字节且长边≤max_dimension 且≤max_payload 时原图直传0 始终 JPEG 压缩detaillowlow/high/auto对应 Eino 的 ImageURLDetailtimeout_seconds60单次 VL 调用超时2.2 默认值与配置合并逻辑源码级配置结构定义在 internal/config/vision.go每个字段都提供了*Effective()方法用于把未填写/非法值规整为安全默认值例如TimeoutSecondsEffective()≤0 时返回 60 秒vision.goMaxImageBytesEffective()≤0 时返回 5MBvision.goJPEGQualityEffective()超出 1-100 范围时回退 82vision.goDetailEffective()非high/low/auto一律回退lowvision.go。关键合并逻辑在OpenAICfgEffective()vision.goVision 段以openai主配置为基底仅对显式填写的api_key/base_url/model/provider做字段级覆盖并强制关闭 Reasoningout.Reasoning.Mode off。这意味着你只需要在主openai段配好通道Vision 段填一个model即可工作若希望视觉走独立通道如不同供应商的 VL 模型可单独覆盖api_key/base_url/provider。Ready()vision.go是注册的开关判断enabled model 非空才真正注册工具若enabled: true但model为空internal/vision/tool.go 会打印告警日志vision.enabled 但 vision.model 为空跳过注册 analyze_image并跳过注册。2.3 注册入口工具注册从应用装配层发起internal/app/vision_tools.go 调用vision.RegisterAnalyzeImageTool(mcpServer, cfg, logger)最终在 internal/vision/tool.go 通过mcpServer.RegisterTool完成注册并输出调试日志vision: analyze_image 工具已注册。工具同时被纳入内置工具授权清单见 internal/app/mcp_authorization.go受既有 MCP 授权体系约束。三、Web 端设置系统设置 → 基本设置除直接编辑配置文件外还可以通过 Web 控制台可视化配置。界面位于系统设置 → 基本设置 → 视觉分析analyze_image模板源码见 web/templates/index.html前端文案见 web/static/i18n/zh-CN.json启用开关勾选启用视觉分析工具 analyze_image下方提示明确说明启用后注册 MCP 工具图片仅在单次 VL 调用中出现Agent 上下文只保留文字摘要提供商可选默认 AI 通道留空复用、OpenAI / 兼容 OpenAI 协议、Claude (Anthropic Messages API)Base URL / API Key留空则复用 OpenAI 通道对应字段视觉模型必填文本框默认占位qwen-vl-max并提供获取列表按钮fetchModelList(vision)从当前通道拉取可用模型高级预处理与限制details折叠面板原始文件上限字节、长边缩放像素、JPEG 质量等参数均可在此设置。保存并应用后配置会写入config.yaml并触发 MCP 工具重新注册无需重启进程即可让新参数生效。此外后端还提供了视觉通道连通性测试接口POST /config/test-vision路由注册见 internal/app/app.go实现见 internal/handler/config.go。TestVisionRequest允许在vision.api_key/base_url留空时传入openai段作为回退执行一次最小 chat completion 来验证视觉模型 API 是否可用可用于排查工具已注册但调用失败的配置问题。四、路径规则与安全校验analyze_image可以读取服务器上任意可读的图片文件路径绝对路径或相对于进程工作目录的相对路径包括用户上传到chat_uploads目录的文件、工具截图路径等。但并非无限制路径解析与校验逻辑在 internal/vision/path.go扩展名白名单仅允许.png、.jpg、.jpeg、.webp、.gif、.bmp、.tif、.tiffpath.go其余扩展名返回unsupported image extension常规文件校验必须是普通文件而非目录not a regular file磁盘大小上限文件超过 1GB130直接拒绝file too large on disk符号链接规范化通过filepath.EvalSymlinks解析最终真实路径path.go避免路径混淆。注意这里的路径校验只约束扩展名 常规文件并不限定目录范围因此该工具具备全服务器读图能力。是否允许 Agent 使用它仍由 MCP 授权与 RBAC 体系共同把关。五、Agent 使用约定何时、如何调用5.1 系统提示自动注入启用视觉分析后系统会在单/多代理的系统提示中注入## 图片分析章节内容由 internal/project/vision_image_prompt.go 生成包含三条核心约定遇到图片文件截图、验证码、登录页、报告配图时若存在工具analyze_image传入服务器上的文件路径进行分析不要对二进制图片使用read_file指望理解内容用户消息中形如「 xxx.png: /path」的即为可传给analyze_image的路径验证码类场景若已从页面或接口保存为本地图片如captcha.png用analyze_image且question写明只输出验证码字符识别失败则刷新验证码后重新保存再识别复杂滑块/行为验证码勿指望单次识图成功。注入仅在vision.enabled model 非空时发生AppendVisionImageAnalysisIfReady见 vision_image_prompt.go与工具注册条件保持一致。5.2 建议加入常驻工具列表对于多代理编排场景建议将analyze_image加入常驻工具列表使工具搜索始终可见multi_agent: eino_middleware: tool_search_always_visible_tools: [read_file, glob, grep, analyze_image, ...]仓库示例配置见 config.example.yaml其中已包含analyze_image。这可以避免 Agent 因工具搜索未命中而绕道read_file去读二进制文件。5.3 子代理委派当委派子代理处理含验证码/截图识读的子任务时应在 task description 中写明图片路径与期望输出格式见 vision_image_prompt.go保证子代理能直接调用analyze_image并返回规范化结果。六、底层实现原理6.1 图片预处理直传 vs 压缩的降级策略预处理入口为 internal/vision/preprocess.go 的PreprocessImageFile流程如下os.Stat校验文件大小超过max_image_bytes直接报错file size %d exceeds max_image_bytes %d通过image.DecodeConfig读取原始宽高与格式imageDimensions先尝试tryPassthroughpreprocess.goskip_preprocess_below_bytes 0且文件 ≤ 阈值长边 ≤max_dimension文件 ≤max_payload_bytes格式可映射为 MIMEimage/jpeg、image/png、image/gif、image/webp、image/bmp、image/tiff。全部满足时原图字节直传VL APIPreprocessMode passthrough省去一次重编码的开销与画质损失否则进入compressWithImagingpreprocess.go压缩链路用imaging.Fit(src, maxDim, maxDim, imaging.Lanczos)将长边缩放到max_dimension以jpeg_quality起始编码 JPEG若仍超过max_payload_bytes则质量每次递减 5下限 60重试质量降到 60 仍超限时把缩放边长乘以 0.85下限 256继续缩小最多 6 轮全部失败才返回could not compress image under max_payload_bytes %d。这套直传优先、逐级降质的策略保证了小图不损失画质、大图必然被压进 512KB 载荷上限、极端情况下仍有兜底失败而非把超大载荷硬塞给模型。6.2 预处理结果的工具输出analyze_image返回的正文由 internal/vision/tool.go 的formatAnalysisResult格式化包含## Image analysispathpreprocess元信息passthrough 模式输出passthrough WxH, mime, XKB (original YKB)压缩模式输出WxH → WxH, jpeg qN, XKB (original YKB)### Summary视觉模型的文字摘要。这段元信息对排障非常有用——Agent 或人工可以直接看到图片是否被重编码、压缩比多少从而判断识别质量问题的成因。6.3 VL 模型调用双通道实现视觉调用核心在 internal/vision/client.go 的Client.Analyze超时控制timeout_seconds作用于上下文context.WithTimeoutHTTP 客户端额外留有 15 秒余量并设置 60 秒拨号/保活与timeout10s的响应头超时base64 编码图片字节base64.StdEncoding后随 MIME 与 detail 一起组装进多模态消息provider 分流provider为 Claudellm.IsClaudeProvider时走原生 Claude Agentic Model构造AgenticMessage的UserInputTextUserInputImage块client.go其余情况走 OpenAI 兼容通道einoopenai.NewChatModel构造 ChatModel消息为ChatMessagePartTypeTextChatMessagePartTypeImageURLclient.go。空结果防护模型返回空内容时抛错vision model returned empty content避免把空摘要写进上下文。6.4 内置 Prompt 与验证码识别增强client.go 的buildVisionPrompt内置了角色约束你是授权安全测试助手。请根据图片回答用户问题只描述你能从图中确认的内容不要编造。——这直接呼应了本文档定位的授权测试场景。默认无question时描述方向侧重可见文本、表单、按钮、验证码、错误信息、技术栈线索。而当question命中验证码关键词验证码、captcha、verification code、vcode、图形码或只输出字符组合见looksLikeCaptchaQuestion会追加强约束若为验证码仅输出你辨认出的字符序列不要空格、标点、解释看不清则明确说无法识别。这大幅提升了验证码识别的输出规范性。七、合规与数据边界启用analyze_image后图片内容会发往 Vision API 配置的上游服务OpenAI 兼容通道或 Anthropic因此敏感环境请使用可信网关转发视觉请求或在需要时保持enabled: false关闭该能力图片字节只参与单次 VL 调用Agent 上下文仅保留路径与文字摘要见 config.example.yaml 顶部注释这本身就是一项缓解措施工具具备全服务器读图能力路径白名单仅限扩展名与常规文件应结合 MCP 授权与 RBAC 评估使用边界。八、快速启用清单在 config.example.yaml 的vision段填写enabled: true与 VLmodel如qwen-vl-maxapi_key/base_url 留空即复用主 AI 通道可选调整max_dimension、jpeg_quality、skip_preprocess_below_bytes等预处理参数或用 Web 控制台「系统设置 → 基本设置 → 视觉分析」可视化配置并保存应用用POST /config/test-vision验证视觉通道连通性确认multi_agent.eino_middleware.tool_search_always_visible_tools包含analyze_image在对话中给 Agent 传图片路径如 captcha.png: /path/to/captcha.pngAgent 将按系统提示自动调用analyze_image返回文字摘要对合规要求严格的部署评估上游 Vision API 的可信度必要时保持enabled: false。参考与延伸阅读官方中文文档docs/zh-CN/VISION.md本文档源头、docs/zh-CN/README.md配置模板config.example.yaml核心实现配置解析 internal/config/vision.go、工具注册 internal/vision/tool.go、预处理 internal/vision/preprocess.go、VL 调用 internal/vision/client.go、路径校验 internal/vision/path.go系统提示注入internal/project/vision_image_prompt.go装配与接口工具装配 internal/app/vision_tools.go、连通性测试路由 internal/app/app.go 与处理器 internal/handler/config.go前端设置界面web/templates/index.html、web/static/i18n/zh-CN.json单元测试预处理与路径校验的配套测试见 internal/vision/preprocess_test.go 与 internal/vision/path_test.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），仅供参考