GenericAgent Vision API SOP 实战指南截图驱动 GUI 自动化中视觉模型的最小化调用规范【免费下载链接】GenericAgentSelf-evolving agent: grows skill tree from 3.3K-line seed, achieving full system control with 6x less token consumption项目地址: https://gitcode.com/GitHub_Trending/pc/GenericAgent导读memory/vision_sop.md是 GenericAgent 项目中视觉模型VLM调用的标准操作规程SOP它定义了三个核心问题什么时候才能用 vision API、怎么安全高效地调用ask_vision、以及没有现成vision_api.py时如何从模板初始化视觉能力。本指南以该 SOP 为骨架结合仓库内memory/vision_api.template.py、memory/ljqCtrl.py、memory/ocr_utils.py与memory/computer_use.md的源码级细节帮助你掌握一条窗口枚举 → 局部截图 → 本地 OCR → 最后才上 vision的省 token、高可靠的 GUI 自动化链路并能在任何环境Claude / OpenAI 兼容 / ModelScope下快速接通视觉能力。一、三条前置规则Vision 是最后手段而非首选vision_sop.md开篇即强调三条必须遵守的硬性规则它们决定了整个 GUI 自动化的资源使用策略先枚举窗口调用 vision 前必须先用pygetwindow枚举窗口标题确认目标窗口存在且已激活到前台。窗口不存在就不截图——这避免了对不存在或后台窗口做无意义的视觉分析。禁止全屏截图必须先利用ljqCtrl截取窗口区域。能截局部如标题栏就不截整窗口能截窗口就绝不全屏。全屏截图在任何场景下都不允许。这既是出于 token 成本控制也是因为全屏图包含大量无关像素会稀释 VLM 对目标区域的注意力。能不用 vision 就不用如果窗口标题或本地 OCRocr_utils.py能获取所需信息就不要调用 vision API省 token 且更可靠。Vision 是最后手段。这条规则链并非孤立设计它与仓库中memory/computer_use.md定义的探测/定位四工具优先级完全一致优先级工具定位限制0win32gui窗口枚举始终先行确定目标窗口、前台状态、客户区原点仅定位窗口不进控件1Python UIA控件树首选探测与免坐标点击游戏禁用一旦对该窗口无效则弃用2ui_detect.pyljqCtrl截图视觉检测控件返回 bbox OCR 文本bbox 为截图内坐标需转屏幕物理坐标3vision (VLM)仅语义理解、确认界面状态、辅助判断目标不可信其坐标从源码结构看vision 处于优先级链条的最末端其定位是语义理解与状态确认而不是坐标定位工具——这正是 SOP 要求能不用就不用的根本原因。二、快速用法ask_vision单函数入口当确需调用视觉能力时SOP 给出了最小可用调用方式from vision_api import ask_vision result ask_vision(image, prompt描述图片内容, timeout60, max_pixels1_440_000) # image: 文件路径(str/Path) 或 PIL Image # backend: claude(默认) | openai | modelscope # 返回 str成功为模型回复失败为 Error: ...对照memory/vision_api.template.py中ask_vision的完整签名第 25 行可以对每个参数做更精确的说明image_input接受文件路径str/Path或 PILImage对象。模板实现里会先做类型检查其他类型直接抛出TypeError并返回Error: 图片处理失败 - ...。prompt默认值为详细描述这张图片的内容。建议按任务写具体指令因为该 prompt 会原样拼入多模态消息。timeout请求超时秒数默认 60。模板对requests.exceptions.Timeout单独捕获返回Error: 请求超时 ({timeout}s)。max_pixels图片像素上限默认1_440_000约 1200×1200。超过该值时模板会自动等比缩放这是控制 token 消耗的关键参数。backend后端选择claude默认、openai、modelscope三选一分别路由到_call_claude/_call_openai_compat/_call_openai_compat(modelscope 配置)。返回值统一为str成功返回模型回复文本任何失败图片处理异常、超时、网络错误、配置缺失、响应解析失败都以Error: ...前缀返回方便调用方在 GUI 自动化脚本中直接判断成败而无需 try/except 包裹。三、没有vision_api.py从模板初始化视觉能力SOP 给出了一套自举式的初始化流程适用于任何全新环境例如新部署的机器或新克隆的仓库复制模板memory/vision_api.template.py→memory/vision_api.py。只改头部用户配置区去mykey.py里扫描变量名⚠️ 只看名字禁止输出 apikey 值尝试找能用配置名填入CLAUDE_CONFIG_KEY/OPENAI_CONFIG_KEYDEFAULT_BACKEND选后端并测试。保底方案没有可用 config 时去 ModelScope 申请 token 填入MODELSCOPE_API_KEY。3.1 配置区字段逐一说明模板第 516 行的用户配置区是唯一需要修改的地方CLAUDE_CONFIG_KEY claude_config141 # mykey.py 中 Claude 配置的变量名 OPENAI_CONFIG_KEY oai_config1 # mykey.py 中 OpenAI 配置的变量名 MODELSCOPE_API_KEY # 直接填你的 ModelScope token DEFAULT_BACKEND claude # 默认后端: claude / openai / modelscope模板注释中明确提示mykey.py中的配置变量名不固定可能形如xxx_config {apibase: ..., apikey: ..., model: ..., proxy: None}因此 SOP 强调只打印变量名/字段名/model/apibase 域名路径/HTTP 状态码/错误类型禁止打印完整 dict 和 apikey/token——这是安全红线。仓库中的mykey_template.py给出了典型配置的结构佐证apikey必填且前缀决定鉴权方式如sk-ant-*走x-api-key头其它sk-*、cr_*、amp_*走 Bearerapibase必填且遵循自动拼接规则model必填[1m]后缀触发 1m 上下文 beta。这意味着vision_api.py中读取的cfg[apibase] / cfg[apikey] / cfg[model] / cfg.get(proxy)与项目主 LLM 配置体系是同一套凭据源无需为视觉能力单独申请密钥。3.2 ModelScope 保底通道当mykey.py中没有任何可用配置时模板提供了开箱即用的保底后端第 1819 行MODELSCOPE_API_BASE https://api-inference.modelscope.cn MODELSCOPE_MODEL Qwen/Qwen3-VL-235B-A22B-Instruct只需在MODELSCOPE_API_KEY填入从 ModelScope 申请的 token并把DEFAULT_BACKEND设为modelscope即可工作模型为 Qwen3-VL 系列视觉大模型。四、源码级原理一次ask_vision调用内部发生了什么4.1 图片预处理管线_prepare_image所有后端共用同一条预处理管线memory/vision_api.template.py第 5578 行这也是max_pixels参数的实际作用点加载PILImage对象直接使用str/Path用Image.open打开其他类型抛TypeError。等比缩放若w * h max_pixels按scale (max_pixels / (w * h)) ** 0.5计算缩放比用LANCZOS重采样并打印 缩放: 原尺寸 → 新尺寸日志。这是将任意分辨率截图收敛到 token 可控范围的关键。通道归一化RGBA/LA/P模式统一转 RGB以白底合成透明通道避免后续 JPEG 编码报错或出现黑底。JPEG 编码quality80, optimizeTrue压缩后 base64 编码打印 Base64: xx.xKB便于估算请求体积。4.2 三个后端的请求差异Claude 后端_call_claudePOST 到cfg[apibase] /v1/messages请求体使用 Anthropic Messages 格式图片以{type: image, source: {type: base64, media_type: image/jpeg, data: b64}}放在content数组首位、prompt 文本在后鉴权头为x-api-keyanthropic-version: 2023-06-01返回解析resp.json()[content][0][text]。模板注释特别提示不同的中转 apibase 可能已含/v1或路径不同需按实际状态码和响应结构修正 endpoint。OpenAI 兼容后端_call_openai_compatPOST 到apibase.rstrip(/) /v1/chat/completions请求体为标准 Chat Completions 多模态格式——content数组里文本在前、图片 URL 使用data:image/jpeg;base64,前缀的 data URI鉴权头为Authorization: Bearer apikey。proxy参数会透传给requests的proxies{https: proxy, http: proxy}用于中转代理场景。ModelScope 后端复用同一函数只是换成了MODELSCOPE_API_BASE / MODELSCOPE_API_KEY / MODELSCOPE_MODEL三个常量。4.3 统一的错误返回协议模板对四类异常做了归一化处理调用方只需判断返回值是否以Error:开头图片处理失败Error: 图片处理失败 - 异常类型: 详情超时Error: 请求超时 ({timeout}s)网络错误Error: API请求失败 - 异常类型: 详情配置缺失 / 响应解析失败KeyError/ValueErrorError: 响应解析失败 - 详情另有兜底分支未知 backend 返回Error: 未知backend name可选: claude, openai, modelscope。五、与截图链路协同vision 之前应该做什么SOP 的禁止全屏截图规则与ljqCtrl的窗口截图能力强绑定。参考memory/ljqCtrl_sop.mdvision 的输入图片应来自以下链路激活并定位窗口ljqCtrl.Activate(hwnd)memory/ljqCtrl.py第 85 行先把目标窗口置于前台这是截图的先决条件。窗口级截图ljqCtrl.GrabWindow(hwnd_or_name)第 102 行前台截图返回 PIL Image直接可作为ask_vision的输入GrabWindowBg(hwnd_or_name, timeout5)第 112 行则是 Win10 的 WGC 后台截图。必要时先试本地 OCRmemory/ocr_utils.py基于rapidocr-onnxruntime约 1 秒/次中英文准确率高、带 bbox提供ocr_image/ocr_screen/ocr_window三个入口。其中ocr_window(hwnd)使用PrintWindowAPI支持远程桌面RDP断开后ImageGrab截图全黑的情况。只要 OCR 能给出文本信息如按钮文字、弹窗内容就完全没有必要调用 vision。从computer_use.md的节奏建议看完整流程是进入新界面先只探测不操作枚举窗口 UIA ljqCtrl 截图 ui_detect读完实际输出再决定下一步仅当ui_detect的视觉检测与 OCR 都不足以判断界面语义时才把截图交给ask_vision做语义理解、确认界面状态、辅助判断目标。此外要牢记vision 返回的文本不可用于坐标定位——如果确实需要点击必须回到ui_detectbbox ClientToScreen(hwnd, (0,0)) / ljqCtrl.dpi_scale的物理坐标转换链路详见 ljqCtrl 使用与坐标转换 SOP。六、macOS 平台的对应适配SOP 针对 Windows 主链路给出但仓库为 macOS 提供了完整的镜像实现memory/maclijqCtrl.pyvision 的调用方式完全不变只是截图来源替换为控制层import macljqCtrl as ljqCtrlAPI 镜像Quartz/screencapture 实现窗口枚举ListWindows()返回 id/app/title/bbox/pid区域截图GrabWindow(window_id)或ScreenCapAt(x, y, radius)物理坐标权限首次使用需授予辅助功能权限可用AXIsProcessTrusted()检测。在这些平台上ask_vision(image, ...)依然接收 PIL Image 或文件路径ljqCtrl.GrabWindow的返回可直接传入无需改动 vision 侧代码——这正是vision 只关心拿到什么图不关心图从哪来的设计价值。七、实践清单与常见误区标准调用流程推荐顺序# 1. 枚举窗口确认目标存在且在前台 # (pygetwindow 枚举标题 → ljqCtrl.Activate(hwnd)) # 2. 窗口级截图绝不全屏 # img ljqCtrl.GrabWindow(hwnd) # 或 ljqCtrl.GrabWindowBg(hwnd) # 3. 优先本地 OCR能拿到文本就不用 vision # from ocr_utils import ocr_image # info ocr_image(img) # if not info[text]: # # 4. 兜底才调 vision # result ask_vision(img, prompt描述图片内容, timeout60, max_pixels1_440_000) # if result.startswith(Error:): # # 按 Error 前缀分流超时重试、配置修正、换 backend常见误区❌ 直接把全屏ImageGrab.grab()结果传给ask_vision——违反禁止全屏截图规则❌ 对不存在的窗口/未激活窗口截图再送 vision——应先枚举并激活❌ 把 vision 返回的内容当作坐标依据点击——vision 只负责语义理解点击坐标必须走ui_detect 物理坐标转换❌ 在日志中打印完整 config dict 或 apikey——SOP 与模板均明确禁止只允许打印变量名/字段名/model/域名/状态码❌ 忽略max_pixels缩放——大图不仅费 token还可能因超出模型输入上限而报错。八、总结vision_sop.md的本质是一份成本与可靠性优先的视觉调用规范通过先枚举窗口、只截窗口、能本地 OCR 就不上 VLM三条规则把 vision API 的使用压缩到最少必要次数再通过ask_vision的统一入口和三个后端Claude / OpenAI 兼容 / ModelScope 保底的透明切换保证任何环境下都能以最低成本获得视觉理解能力。配合memory/vision_api.template.py的自举初始化流程、memory/ljqCtrl_sop.md的截图链路和memory/ocr_utils.py的本地 OCR这套 SOP 构成了 GenericAgent 桌面自动化体系中最后一公里的语义确认环节——准确、省 token、且可审计。延伸阅读GUI 操作的整体节奏与工具优先级见 computer_use.md窗口截图与 DPI 物理坐标换算见 ljqCtrl_sop.md视觉能力模板实现见 vision_api.template.py本地 OCR 能力见 ocr_utils.py。【免费下载链接】GenericAgentSelf-evolving agent: grows skill tree from 3.3K-line seed, achieving full system control with 6x less token consumption项目地址: https://gitcode.com/GitHub_Trending/pc/GenericAgent创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
GenericAgent Vision API SOP 实战指南：截图驱动 GUI 自动化中视觉模型的最小化调用规范
GenericAgent Vision API SOP 实战指南截图驱动 GUI 自动化中视觉模型的最小化调用规范【免费下载链接】GenericAgentSelf-evolving agent: grows skill tree from 3.3K-line seed, achieving full system control with 6x less token consumption项目地址: https://gitcode.com/GitHub_Trending/pc/GenericAgent导读memory/vision_sop.md是 GenericAgent 项目中视觉模型VLM调用的标准操作规程SOP它定义了三个核心问题什么时候才能用 vision API、怎么安全高效地调用ask_vision、以及没有现成vision_api.py时如何从模板初始化视觉能力。本指南以该 SOP 为骨架结合仓库内memory/vision_api.template.py、memory/ljqCtrl.py、memory/ocr_utils.py与memory/computer_use.md的源码级细节帮助你掌握一条窗口枚举 → 局部截图 → 本地 OCR → 最后才上 vision的省 token、高可靠的 GUI 自动化链路并能在任何环境Claude / OpenAI 兼容 / ModelScope下快速接通视觉能力。一、三条前置规则Vision 是最后手段而非首选vision_sop.md开篇即强调三条必须遵守的硬性规则它们决定了整个 GUI 自动化的资源使用策略先枚举窗口调用 vision 前必须先用pygetwindow枚举窗口标题确认目标窗口存在且已激活到前台。窗口不存在就不截图——这避免了对不存在或后台窗口做无意义的视觉分析。禁止全屏截图必须先利用ljqCtrl截取窗口区域。能截局部如标题栏就不截整窗口能截窗口就绝不全屏。全屏截图在任何场景下都不允许。这既是出于 token 成本控制也是因为全屏图包含大量无关像素会稀释 VLM 对目标区域的注意力。能不用 vision 就不用如果窗口标题或本地 OCRocr_utils.py能获取所需信息就不要调用 vision API省 token 且更可靠。Vision 是最后手段。这条规则链并非孤立设计它与仓库中memory/computer_use.md定义的探测/定位四工具优先级完全一致优先级工具定位限制0win32gui窗口枚举始终先行确定目标窗口、前台状态、客户区原点仅定位窗口不进控件1Python UIA控件树首选探测与免坐标点击游戏禁用一旦对该窗口无效则弃用2ui_detect.pyljqCtrl截图视觉检测控件返回 bbox OCR 文本bbox 为截图内坐标需转屏幕物理坐标3vision (VLM)仅语义理解、确认界面状态、辅助判断目标不可信其坐标从源码结构看vision 处于优先级链条的最末端其定位是语义理解与状态确认而不是坐标定位工具——这正是 SOP 要求能不用就不用的根本原因。二、快速用法ask_vision单函数入口当确需调用视觉能力时SOP 给出了最小可用调用方式from vision_api import ask_vision result ask_vision(image, prompt描述图片内容, timeout60, max_pixels1_440_000) # image: 文件路径(str/Path) 或 PIL Image # backend: claude(默认) | openai | modelscope # 返回 str成功为模型回复失败为 Error: ...对照memory/vision_api.template.py中ask_vision的完整签名第 25 行可以对每个参数做更精确的说明image_input接受文件路径str/Path或 PILImage对象。模板实现里会先做类型检查其他类型直接抛出TypeError并返回Error: 图片处理失败 - ...。prompt默认值为详细描述这张图片的内容。建议按任务写具体指令因为该 prompt 会原样拼入多模态消息。timeout请求超时秒数默认 60。模板对requests.exceptions.Timeout单独捕获返回Error: 请求超时 ({timeout}s)。max_pixels图片像素上限默认1_440_000约 1200×1200。超过该值时模板会自动等比缩放这是控制 token 消耗的关键参数。backend后端选择claude默认、openai、modelscope三选一分别路由到_call_claude/_call_openai_compat/_call_openai_compat(modelscope 配置)。返回值统一为str成功返回模型回复文本任何失败图片处理异常、超时、网络错误、配置缺失、响应解析失败都以Error: ...前缀返回方便调用方在 GUI 自动化脚本中直接判断成败而无需 try/except 包裹。三、没有vision_api.py从模板初始化视觉能力SOP 给出了一套自举式的初始化流程适用于任何全新环境例如新部署的机器或新克隆的仓库复制模板memory/vision_api.template.py→memory/vision_api.py。只改头部用户配置区去mykey.py里扫描变量名⚠️ 只看名字禁止输出 apikey 值尝试找能用配置名填入CLAUDE_CONFIG_KEY/OPENAI_CONFIG_KEYDEFAULT_BACKEND选后端并测试。保底方案没有可用 config 时去 ModelScope 申请 token 填入MODELSCOPE_API_KEY。3.1 配置区字段逐一说明模板第 516 行的用户配置区是唯一需要修改的地方CLAUDE_CONFIG_KEY claude_config141 # mykey.py 中 Claude 配置的变量名 OPENAI_CONFIG_KEY oai_config1 # mykey.py 中 OpenAI 配置的变量名 MODELSCOPE_API_KEY # 直接填你的 ModelScope token DEFAULT_BACKEND claude # 默认后端: claude / openai / modelscope模板注释中明确提示mykey.py中的配置变量名不固定可能形如xxx_config {apibase: ..., apikey: ..., model: ..., proxy: None}因此 SOP 强调只打印变量名/字段名/model/apibase 域名路径/HTTP 状态码/错误类型禁止打印完整 dict 和 apikey/token——这是安全红线。仓库中的mykey_template.py给出了典型配置的结构佐证apikey必填且前缀决定鉴权方式如sk-ant-*走x-api-key头其它sk-*、cr_*、amp_*走 Bearerapibase必填且遵循自动拼接规则model必填[1m]后缀触发 1m 上下文 beta。这意味着vision_api.py中读取的cfg[apibase] / cfg[apikey] / cfg[model] / cfg.get(proxy)与项目主 LLM 配置体系是同一套凭据源无需为视觉能力单独申请密钥。3.2 ModelScope 保底通道当mykey.py中没有任何可用配置时模板提供了开箱即用的保底后端第 1819 行MODELSCOPE_API_BASE https://api-inference.modelscope.cn MODELSCOPE_MODEL Qwen/Qwen3-VL-235B-A22B-Instruct只需在MODELSCOPE_API_KEY填入从 ModelScope 申请的 token并把DEFAULT_BACKEND设为modelscope即可工作模型为 Qwen3-VL 系列视觉大模型。四、源码级原理一次ask_vision调用内部发生了什么4.1 图片预处理管线_prepare_image所有后端共用同一条预处理管线memory/vision_api.template.py第 5578 行这也是max_pixels参数的实际作用点加载PILImage对象直接使用str/Path用Image.open打开其他类型抛TypeError。等比缩放若w * h max_pixels按scale (max_pixels / (w * h)) ** 0.5计算缩放比用LANCZOS重采样并打印 缩放: 原尺寸 → 新尺寸日志。这是将任意分辨率截图收敛到 token 可控范围的关键。通道归一化RGBA/LA/P模式统一转 RGB以白底合成透明通道避免后续 JPEG 编码报错或出现黑底。JPEG 编码quality80, optimizeTrue压缩后 base64 编码打印 Base64: xx.xKB便于估算请求体积。4.2 三个后端的请求差异Claude 后端_call_claudePOST 到cfg[apibase] /v1/messages请求体使用 Anthropic Messages 格式图片以{type: image, source: {type: base64, media_type: image/jpeg, data: b64}}放在content数组首位、prompt 文本在后鉴权头为x-api-keyanthropic-version: 2023-06-01返回解析resp.json()[content][0][text]。模板注释特别提示不同的中转 apibase 可能已含/v1或路径不同需按实际状态码和响应结构修正 endpoint。OpenAI 兼容后端_call_openai_compatPOST 到apibase.rstrip(/) /v1/chat/completions请求体为标准 Chat Completions 多模态格式——content数组里文本在前、图片 URL 使用data:image/jpeg;base64,前缀的 data URI鉴权头为Authorization: Bearer apikey。proxy参数会透传给requests的proxies{https: proxy, http: proxy}用于中转代理场景。ModelScope 后端复用同一函数只是换成了MODELSCOPE_API_BASE / MODELSCOPE_API_KEY / MODELSCOPE_MODEL三个常量。4.3 统一的错误返回协议模板对四类异常做了归一化处理调用方只需判断返回值是否以Error:开头图片处理失败Error: 图片处理失败 - 异常类型: 详情超时Error: 请求超时 ({timeout}s)网络错误Error: API请求失败 - 异常类型: 详情配置缺失 / 响应解析失败KeyError/ValueErrorError: 响应解析失败 - 详情另有兜底分支未知 backend 返回Error: 未知backend name可选: claude, openai, modelscope。五、与截图链路协同vision 之前应该做什么SOP 的禁止全屏截图规则与ljqCtrl的窗口截图能力强绑定。参考memory/ljqCtrl_sop.mdvision 的输入图片应来自以下链路激活并定位窗口ljqCtrl.Activate(hwnd)memory/ljqCtrl.py第 85 行先把目标窗口置于前台这是截图的先决条件。窗口级截图ljqCtrl.GrabWindow(hwnd_or_name)第 102 行前台截图返回 PIL Image直接可作为ask_vision的输入GrabWindowBg(hwnd_or_name, timeout5)第 112 行则是 Win10 的 WGC 后台截图。必要时先试本地 OCRmemory/ocr_utils.py基于rapidocr-onnxruntime约 1 秒/次中英文准确率高、带 bbox提供ocr_image/ocr_screen/ocr_window三个入口。其中ocr_window(hwnd)使用PrintWindowAPI支持远程桌面RDP断开后ImageGrab截图全黑的情况。只要 OCR 能给出文本信息如按钮文字、弹窗内容就完全没有必要调用 vision。从computer_use.md的节奏建议看完整流程是进入新界面先只探测不操作枚举窗口 UIA ljqCtrl 截图 ui_detect读完实际输出再决定下一步仅当ui_detect的视觉检测与 OCR 都不足以判断界面语义时才把截图交给ask_vision做语义理解、确认界面状态、辅助判断目标。此外要牢记vision 返回的文本不可用于坐标定位——如果确实需要点击必须回到ui_detectbbox ClientToScreen(hwnd, (0,0)) / ljqCtrl.dpi_scale的物理坐标转换链路详见 ljqCtrl 使用与坐标转换 SOP。六、macOS 平台的对应适配SOP 针对 Windows 主链路给出但仓库为 macOS 提供了完整的镜像实现memory/maclijqCtrl.pyvision 的调用方式完全不变只是截图来源替换为控制层import macljqCtrl as ljqCtrlAPI 镜像Quartz/screencapture 实现窗口枚举ListWindows()返回 id/app/title/bbox/pid区域截图GrabWindow(window_id)或ScreenCapAt(x, y, radius)物理坐标权限首次使用需授予辅助功能权限可用AXIsProcessTrusted()检测。在这些平台上ask_vision(image, ...)依然接收 PIL Image 或文件路径ljqCtrl.GrabWindow的返回可直接传入无需改动 vision 侧代码——这正是vision 只关心拿到什么图不关心图从哪来的设计价值。七、实践清单与常见误区标准调用流程推荐顺序# 1. 枚举窗口确认目标存在且在前台 # (pygetwindow 枚举标题 → ljqCtrl.Activate(hwnd)) # 2. 窗口级截图绝不全屏 # img ljqCtrl.GrabWindow(hwnd) # 或 ljqCtrl.GrabWindowBg(hwnd) # 3. 优先本地 OCR能拿到文本就不用 vision # from ocr_utils import ocr_image # info ocr_image(img) # if not info[text]: # # 4. 兜底才调 vision # result ask_vision(img, prompt描述图片内容, timeout60, max_pixels1_440_000) # if result.startswith(Error:): # # 按 Error 前缀分流超时重试、配置修正、换 backend常见误区❌ 直接把全屏ImageGrab.grab()结果传给ask_vision——违反禁止全屏截图规则❌ 对不存在的窗口/未激活窗口截图再送 vision——应先枚举并激活❌ 把 vision 返回的内容当作坐标依据点击——vision 只负责语义理解点击坐标必须走ui_detect 物理坐标转换❌ 在日志中打印完整 config dict 或 apikey——SOP 与模板均明确禁止只允许打印变量名/字段名/model/域名/状态码❌ 忽略max_pixels缩放——大图不仅费 token还可能因超出模型输入上限而报错。八、总结vision_sop.md的本质是一份成本与可靠性优先的视觉调用规范通过先枚举窗口、只截窗口、能本地 OCR 就不上 VLM三条规则把 vision API 的使用压缩到最少必要次数再通过ask_vision的统一入口和三个后端Claude / OpenAI 兼容 / ModelScope 保底的透明切换保证任何环境下都能以最低成本获得视觉理解能力。配合memory/vision_api.template.py的自举初始化流程、memory/ljqCtrl_sop.md的截图链路和memory/ocr_utils.py的本地 OCR这套 SOP 构成了 GenericAgent 桌面自动化体系中最后一公里的语义确认环节——准确、省 token、且可审计。延伸阅读GUI 操作的整体节奏与工具优先级见 computer_use.md窗口截图与 DPI 物理坐标换算见 ljqCtrl_sop.md视觉能力模板实现见 vision_api.template.py本地 OCR 能力见 ocr_utils.py。【免费下载链接】GenericAgentSelf-evolving agent: grows skill tree from 3.3K-line seed, achieving full system control with 6x less token consumption项目地址: https://gitcode.com/GitHub_Trending/pc/GenericAgent创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考