ARTICLE DETAIL

资讯详情

深耕商务建站与企业官网运营的一线实战洞察。

Strix 沙箱视觉能力解析:view_image 工具的加载原理、截图工作流与容错恢复机制

Strix 沙箱视觉能力解析:view_image 工具的加载原理、截图工作流与容错恢复机制 Strix 沙箱视觉能力解析view_image 工具的加载原理、截图工作流与容错恢复机制【免费下载链接】strixOpen-source AI penetration testing tool to find and fix your app’s vulnerabilities.项目地址: https://gitcode.com/GitHub_Trending/strix/strix本文面向想要理解 Strix 安全扫描 Agent 如何看见浏览器截图的技术读者深入剖析 SDK 内建view_image工具在沙箱中的定位、接线方式、截图默认目录约定、实战调用链以及当视觉模型不支持或拒绝图像输入时Strix 内置的自动剥离与恢复机制。读完你既能上手完成截图→查看→理解的完整链路也能读懂源码中每一环的设计用意。view_image 是什么为视觉模型输送图像内容的沙箱工具view_image不是 Strix 自行实现的工具而是上游agentsSDK 提供的能力。在 strix/tools/view_image/README.md 中对其定义如下SDK-provided tool that loads an image from the sandbox workspace and returns it as an image content block for vision-capable models.拆开看有三个关键点来源是沙箱工作区它只能加载 sandbox 工作区内的图片文件天然限定在扫描容器可访问的范围内产出是 image content block调用结果会被打包成对话中的input_image内容块直接进入模型上下文消费方必须是视觉模型只有支持 vision 的模型如具备图像输入能力的多模态大模型才能理解这个内容块纯文本模型会拒收并触发后续的容错流程见下文。为什么需要这样一个工具Strix 的安全扫描依赖 agent-browser基于 headless Chromium 的浏览器自动化 CLI来做 Web 交互式测试。浏览器交互中大量信息只有看见像素才能判断页面视觉布局是否符合预期、验证码图形、自定义控件其可访问性树不完整等。但关键约束在 skill 文档中写得很直白agent_browser.mdagent-browser screenshotwrites a PNG to disk in the sandbox. The shell command alone doesnotput the image into your context — chain it with the SDKview_imagetool to actually see it.也就是说截图命令只负责把 PNG 写到磁盘把图片送入模型上下文的唯一途径是view_image。二者是同一流程中不可互相替代的两环这正是view_image在 Strix 工具栈中的核心价值——它充当磁盘文件 → 模型视觉上下文的桥。接线方式随 Filesystem 能力在每次运行时注入view_image并非常驻的基础工具集成员而是通过 SDK 的Filesystemcapability 在构建 agent 时动态装配。源码位置在 strix/agents/factory.pyreturn SandboxAgent( namename, instructionsinstructions, toolstools, tool_use_behavior_finish_tool_use_behavior, modelNone, capabilities[ Filesystem( configure_tools_make_filesystem_configurator( chat_completionschat_completions_tools, strict_schemasstrict_tool_schemas, ), ), Shell( configure_tools_make_shell_configurator( chat_completionschat_completions_tools, strict_schemasstrict_tool_schemas, ), ), ], )build_strix_agent在工厂模块的 factory.py 中定义root agent 与子 agentchild agent都走同一构建路径因此每次运行的每一个沙箱 Agent 都会获得Filesystem能力view_image随之注入。值得留意的是装配细节_make_filesystem_configurator返回的 configure 回调会对 filesystem 工具集做统一包装factory.py其行为取决于目标后端路由chat_completions 路径SDK 的CustomTool会被包成FunctionTool_custom_tool_as_function_tool并加_function_tool_with_error_result—— 工具抛出的异常会以文本错误形式返回给模型而不是中断会话Responses / 原生路径CustomTool走_bound_custom_tool结果上限封装两条路径都会统一施加_with_coerced_arguments参数类型矫正包括 JSON 数组/对象字符串解码与_with_strictness。这套包装层对view_image的直接影响是它享受与 Strix 自定义工具一致的参数矫正、结果尺寸上限context.tool_output_max_lines/tool_output_max_bytes见 factory.py与错误转文本策略。这也是为什么 SDK 原生工具能在 Strix 的统一工具治理模型下工作。Strix 默认约定截图的落盘目录与容器级配置view_image读取的图片通常由 agent-browser 截图产生Strix 在容器镜像层面就把两者的默认目录约定固化了下来1. Dockerfile 声明环境变量containers/Dockerfile 中设置了一组AGENT_BROWSER_*环境变量ENV AGENT_BROWSER_EXECUTABLE_PATH/usr/bin/chromium ENV AGENT_BROWSER_USER_AGENTMozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36 ENV AGENT_BROWSER_ARGS--disable-blink-featuresAutomationControlled,--no-first-run,--no-default-browser-check,--langen-US ENV AGENT_BROWSER_SCREENSHOT_DIR/workspace/.agent-browser-screenshots ENV AGENT_BROWSER_IDLE_TIMEOUT_MS180000其中与本文最相关的是AGENT_BROWSER_SCREENSHOT_DIR/workspace/.agent-browser-screenshots——它把 agent-browser 的默认截图输出目录固定在/workspace沙箱根之内。这些变量随后被写入/etc/profile.d/agent-browser.sh容器内各 shell 会话登录即可继承。2. entrypoint 在容器启动时创建目录containers/docker-entrypoint.sh 在每次容器启动时执行mkdir -p /workspace/.agent-browser-screenshots保证目录必然存在截图命令可直接落盘。3. 为什么目录必须落在/workspace内skill 文档在 agent_browser.md 中给出了一条硬性约束Default output directory is/workspace/.agent-browser-screenshots/, whichview_imagecan read. ... Never write screenshots to/tmp—view_imagerejects anything outside the workspace root.即view_image会拒绝工作区根workspace root之外的路径例如/tmp下的文件无法被读取。这既是沙箱边界的体现也是安全设计的必然——工具的能力被限定在扫描容器自己的工作区内。实战工作流两段式调用让模型真正看到页面在 agent_browser.md 的 Skill 文档中截图的推荐姿势是先截图拿到路径、再把路径交给view_imageexec_command: agent-browser screenshot view_image: {path: path printed on stdout}screenshot 命令的常用形态agent-browser screenshot # 无参形式路径打印到 stdout agent-browser screenshot /workspace/.agent-browser-screenshots/page.png # 显式指定文件名 agent-browser screenshot --full # 整页滚动高度截图 agent-browser screenshot --annotate # 编号标注 与 snapshot ref 对应的图例实践要点优先无参形式CLI 会把完整路径打印到 stdout将 stdout 输出的路径原样传给view_image即可避免路径拼接出错自定义文件名需守规矩若需指定文件名应放在默认截图目录或/workspace下同级的隐藏目录中绝不能写到/tmp--annotate专为多模态模型设计每个标注[N]对应快照snapshot中的 refeN。先拍标注截图再用view_image查看就能把视觉布局与快照 DOM 结构两张视图关联起来——例如定位某个可疑按钮时视觉上对应哪个 DOM 节点一目了然见 agent_browser.md。Token 成本意识先快照、必要时才像素skill 文档明确给出了成本提示agent_browser.mdSnapshots (snapshot -i) give you a compact text view that costs ~200-400 tokens; screenshots cost more. Usesnapshotfirst; reach forscreenshot view_imageonly when you actually need pixels.推荐策略是优先用文本形态的snapshot -i获取 DOM 概览只有遇到视觉布局、验证码、可访问性树不完整的自定义控件等真正需要像素的问题时才动用screenshot view_image。这从根上控制多模态内容的上下文开销。文本模型的降级路径skill 文档也写明了view_image的失败语义agent_browser.mdIfview_imageerrors back at you (rejected image, vision not supported, or similar), you are running on a text-only model — stop calling it and stop taking screenshots.一旦view_image返回拒绝类错误说明当前模型不支持视觉输入Agent 应当停止截图与view_image调用完全改用snapshot -i的 ref、eval读取任何需要的 DOM/JS 状态与text ref/get text做内容抽取。这套降级说明被写进了 skill 提示词模型在遇到报错时能据此自纠正。渲染落地截图在 TUI 与 Viewer 中的呈现view_image的结果不仅在模型上下文生效也会被 Strix 的两套人机界面消费保证人类审计者与 Agent 看到同一画面。终端 TUI在 strix/interface/tui/internal/render/registry.go 中view_image被路由到专门渲染器case view_image: return renderViewImage(args, result)其实现位于 strix/interface/tui/internal/render/image.go。该渲染器会从view_image的工具结果中抽取 base64 图像负载extractImageDataURI并在终端能力允许时借助Kitty graphics protocol直接内联显示图像占位/预览。对应测试 strix/interface/tui/internal/render/image_kitty_test.go 验证了两种分支支持 Kitty 时渲染占位符、不支持时TestViewImageWithoutKittySupportShowsNoPreview则不做图像预览。由此可推断TUI 的图像呈现能力是检测到终端协议才启用的自适应设计而非依赖固定终端类型。Web Viewer在前端侧ViewImageRenderer.tsx 负责把view_image的返回结果渲染为内联图片其在工具注册表中的归属也印证了它是 SDK filesystem 家族成员——index.ts 把apply_patch、view_image、str_replace_editor、list_files、search_files一并归入filesystem分组。容错机制视觉拒绝的自动恢复与上下文预算view_image输出的是图像内容块体积大且不是所有模型都支持。Strix 在运行层内置了两道防线拒收自动剥离与上下文图像预算。二者的实现主体都位于 strix/core/sessions.py。场景一模型拒收图像输入自动恢复多模态场景下模型/供应商可能因「vision not supported」等原因直接拒绝包含图像的输入。执行循环在 strix/core/execution.py 中捕获到这类异常时启动恢复except Exception as exc: if ( image_strips 3 and session is not None and getattr(exc, status_code, None) in _INPUT_REJECTION_CODES ): try: stripped await strip_all_images_from_session(session) ... if stripped: image_strips 1 ... input_data [] continue其中_INPUT_REJECTION_CODES frozenset({400, 404, 422})execution.py最多执行3 次图像剥离后重试image_strips 3。strip_all_images_from_session的具体实现见 sessions.py遍历会话条目把每个含图像的工具输出替换为文本占位符_IMAGE_REJECTED_TEXT [image rejected by the model]替换逻辑是块级、保兄弟的_elided_output只把output列表中type input_image的块换成文本块同一条function_call_output里其他文本块原样保留sessions.py。判定函数_output_has_image则专门匹配function_call_output且其 output 列表中含input_image块的条目sessions.py。所有会话改写都在session_write_lock写锁内以读-改-写方式进行失败时恢复原条目sessions.py避免在 Agent 并发写会话时互相覆盖。整个恢复流程的效果是视觉模型不可用时扫描不会中断——图像被文本占位符替代后会话继续推进Agent 转入纯文本驱动模式。场景二上下文图像预算裁剪即使模型支持视觉大量截图也会撑爆上下文。执行循环在每轮开跑前按上下文配置执行图像预算execution.pymax_images context.get(max_context_images) if isinstance(max_images, int): try: await enforce_image_budget(session, max_images) ...enforce_image_budgetsessions.py只保留最近max_images张图像输出更早的截图被替换为提示文本_IMAGE_ELIDED_TEXT [older screenshot elided to bound context memory]从而把多模态内容对上下文的占用控制在预算内同时保留最近的视觉状态供模型引用。场景三继承上下文中的图像脱敏当子 Agent 需要继承父级上下文时图像不会盲目拷贝。scrub_images_from_itemssessions.py递归扫描输入条目把每个input_image块替换成_INHERITED_IMAGE_TEXT [screenshot omitted from inherited context]这让上下文继承以文本摘要进行避免子 Agent 的上下文被父级的整页截图污染。三种占位符文本rejected / elided / omitted各司其职分别对应拒收恢复、预算裁剪、继承脱敏三条链路从源码层面看是一个相当完整的图像上下文治理体系。结语与延伸阅读view_image虽只是 SDK 提供的一个小工具却在 Strix 的视觉闭环中扮演承上启下的角色上承 agent-browser 截图能力把像素送入多模态模型下接 TUI / Viewer 渲染与上下文治理让视觉内容既可审计又可管理再辅以容器目录约定与运行层自动恢复让视觉能力成为可平滑降级的可选增强项而非扫描的脆弱依赖。想继续深入可优先阅读以下文件文档主体strix/tools/view_image/README.md工具装配strix/agents/factory.pyFilesystemcapability 注入截图工作流 Skillstrix/skills/tooling/agent_browser.md容器默认目录containers/Dockerfile、containers/docker-entrypoint.sh容错与预算实现strix/core/sessions.py、调用点 strix/core/execution.py界面呈现registry.go、ViewImageRenderer.tsx、测试 image_kitty_test.go【免费下载链接】strixOpen-source AI penetration testing tool to find and fix your app’s vulnerabilities.项目地址: https://gitcode.com/GitHub_Trending/strix/strix创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考
返回列表
PREV
查看更多资讯
NEXT
返回资讯列表