在日常工作中，从设计稿或截图中提取UI结构、识别文字、定位控件位置、理解界面逻辑关系，每一步都可能成为效率瓶颈。CodeBuddy的视觉理解能力正是针对这些场景设计，让像素直接转化为可编辑的语义数据。
上传图像并触发视觉理解
在CodeBuddy CLI终端中，先确保已进入目标项目目录，然后输入codebuddy vision并回车。终端会提示“Waiting for image…”，此时直接将PNG或JPEG格式的设计图拖入终端窗口，松手即完成上传。
需要注意一点：尽量避免截图带有半透明阴影或模糊边缘，这类图像会导致实体定位精度下降15%以上。
上传成功后，CLI会自动调用多模态模型进行解析，大约3到8秒后会返回结构化响应。
提取UI组件结构与层级关系
在返回结果中，找到"ui_hierarchy"字段——它以嵌套JSON的形式描述了所有可识别控件，包含id、type、bounds（x/y/width/height）、text（如有）和parent_id。
将整个ui_hierarchy内容复制出来，粘贴到VS Code的新建JSON文件中，用Prettify插件格式化一下，就能直观地查看层级树。如果发现某个Button没有被识别为可点击元素，大概率是其像素对比度低于阈值，需要在原图中手动加粗边框再重新尝试。
【bounds坐标系以左上角为原点，单位为像素，非CSS中的relative定位】
识别图中文字并保留排版上下文
有三种方式可以获取图中文字：
方法一：直接读取返回结果中的"ocr_text"数组，每个元素包含text、confidence和bounding_box。confidence低于0.85的文字建议人工核对，小字号或斜体字尤其容易误识。
方法二：如果需要导出带位置标记的文本文件，可以执行codebuddy vision --export-ocr=txt，生成vision_ocr_export.txt文件，每行格式为[x,y,w,h] 文本内容。
方法三：对于中英文混排的截图，建议启用--lang=zh,en参数，否则默认只识别英文，中文字符可能会被拆成单字且丢失标点。
定位特定视觉元素并生成CSS选择器
第一步：在vision返回结果中找到"entities"列表，筛选label字段匹配你关注的对象，比如“提交按钮”、“头像区域”、“价格标签”等。
第二步：取出对应项的bounding_box，计算其中心点坐标：center_x = x + w/2，center_y = y + h/2。
第三步：运行codebuddy css-selector --x={center_x} --y={center_y}，工具会基于DOM结构推测最稳定的选择器路径，例如main > .product-card:nth-child(2) .price-tag。
这一步不能跳过中心点计算——直接传原始bounds会导致选择器命中多个相似区域，尤其在重复卡片布局中极易出错。
分析图像空间关系与交互逻辑
返回结果中的"spatial_reasoning"字段包含三类关键推断：
• "alignment"：指出元素是否左对齐、居中或右对齐，适用于快速校验设计规范的一致性；
• "proximity"：标注哪些控件存在操作耦合，比如搜索框紧邻放大镜图标，暗示应绑定同一事件；
• "interactive_flow"：按视觉动线推测用户操作路径，例如从顶部导航栏→下滑至商品列表→点击第二项→进入详情页。该路径已通过GUI交互多模态推理验证，不是简单的热区排序。
如果"interactive_flow"为空，说明图像缺乏明确的操作锚点（比如没有箭头、高亮状态或悬停效果示意），此时需要补一张带交互态标注的截图再分析。