vision-bridge：按需视觉桥接
一、定位
本技能是纯文本主模型的视觉适配器，不是所有模型的默认视觉增强层。
它解决的问题是：主模型无法接收或理解图片时，先由本技能识别图片，再把与当前问题相关的最小结构化结果交给主模型继续推理。
基本链路：
用户图片 + 问题
↓
判断主模型视觉能力
├─ 原生多模态：主模型直接看图，不调用本技能
└─ 纯文本/无法访问图片：按需 OCR 或视觉 API
↓
只输出回答当前问题所需的信息
二、自动判断规则（不依赖模型名称）
每次遇到图片任务时，先根据当前运行环境和对话上下文判断能力，不要只根据 DeepSeek、GPT、Qwen 等名称猜测：
-
明确支持视觉输入，且当前图片已可被主模型访问：
- 不调用本技能；
- 让主模型直接理解原图；
- 不要把图片先转成文字再重复喂给主模型。 -
明确不支持视觉输入，或系统提示当前模型无法读取图片：
- 自动调用本技能；
- 用户不需要手动说“使用 vision-bridge”。 -
模型能力未知：
- 如果当前对话已经把图片作为模型可见输入提供，优先让主模型直接处理；
- 只有主模型明确表示无法查看、无法访问，或输出明显不能基于图片作答时，才调用本技能；
- 如果图片只有本地路径/URL，而当前主模型无法实际访问该资源，则直接按桥接场景处理。 -
用户明确指定外部视觉 API、本地 OCR、第二模型复核或高精度 OCR：
- 即使主模型支持视觉，也可以调用本技能；
- 将其视为专项复核，不是默认流程。 -
主模型切换后重新判断：
- 不要沿用上一模型的能力结论；
- 以当前模型实际可见输入能力和运行时信息为准。
判断依据优先级：
运行时明确能力信息 > 当前对话中图片是否可见 > 主模型实际反馈 > 模型名称推断
三、任务分流
1. 纯文字提取
例如“读取截图文字”“提取表格文字”“识别文档内容”：
- 本地 OCR 后端可用时，优先本地 OCR；
- OCR 输出为空、明显残缺、顺序混乱或包含关键数字不确定时，必须用视觉 API 复核；
- 不要因为 OCR 有部分结果就把残缺结果当作完整内容。
2. 需要视觉语义
例如图表趋势、页面布局、场景、物体关系、颜色、箭头、按钮位置、复杂表格结构：
- 直接调用视觉 API；
- 本地 OCR 只能作为辅助，不能替代视觉理解。
3. 关键数据任务
涉及课表、成绩、费用、财务、证件、合同、表格等：
- 识别结果必须区分“已确认”和“无法确认”；
- 不得补猜模糊字符、数字或日期；
- 必要时要求视觉 API 对关键区域复核，并提示人工抽查；
- 后续求和、筛选、匹配等确定性操作交给代码，不让模型逐行猜算。
四、最小输出原则
不要默认生成“图片全景报告”。视觉提示词应围绕用户问题生成，只提取回答所需内容：
| 用户意图 | 输出重点 |
|---|---|
| 读取文字 | 原文、段落和表格结构；不额外描述场景 |
| 查找数字/日期 | 目标值及其上下文；标注模糊字符 |
| 图表解读 | 标题、坐标、图例、关键数值和趋势 |
| 表格转数据 | 列名、行数据、无法确认的单元格 |
| 二维码/条形码 | 仅尝试解码并返回结果 |
| 截图排错 | 错误信息、页面状态、相关按钮和线索 |
| 照片描述 | 只描述与问题相关的对象和关系 |
如果用户没有提出具体问题，才使用简短的通用识别：图片类型、可读文字、关键结构和不确定部分。
结果建议采用以下结构，避免无依据扩写：
## 与问题相关的识别结果
...
## 无法确认的部分
...
## 是否需要复核
是/否；说明原因
五、多轮复用
同一张图片在后续追问中，优先复用已经得到的识别结果，不重复调用视觉 API。
只有以下情况才重新识别：
- 图片发生变化；
- 用户提出了需要新视觉证据的问题；
- 上一次结果明确不完整或需要更高精度复核。
六、执行方式
# 视觉 API：按问题定制提示词
python <SKILL_DIR>/scripts/vision.py --image "<图片路径或URL>" --prompt "<只提取当前问题所需内容>"
# 低成本本地 OCR：仅本地图片，依赖可用时执行
python <SKILL_DIR>/scripts/ocr.py --image "<本地图片路径>"
# 高精度视觉模式（端点支持时）
python <SKILL_DIR>/scripts/vision.py --image "<图片>" --detail high --prompt "<任务>"
脚本从 <SKILL_DIR>/config.json 读取配置，环境变量可覆盖：
VISION_BASE_URLVISION_API_KEYVISION_MODELVISION_TIMEOUTVISION_RETRIES
API Key 优先放在环境变量中，不要写入技能包、日志或对话。分发技能时必须清空密钥。
七、错误处理与重试
- 网络超时、429、500、502、503、504：最多自动重试 1 次；
- 401、403、404、图片不存在、格式不支持：不重试，直接给出明确排查信息；
- OCR 未安装或不可用：不要报成系统故障，直接降级到视觉 API；
- 视觉结果为空、格式异常或关键内容可疑：明确说明，并在必要时切换高精度模式或提示人工核对；
- 任何识别失败都不得猜测图片内容。
八、与其他技能协作
local-whisper是语音转文字技能，不是图片 OCR，不应被用于图片识别；- 现有 WPS 发票 OCR 实现使用
pytesseract，主要面向发票入账，不是通用 OCR；本技能提供独立的可选通用 OCR 入口； - 与 token 优化策略协作时，只把检索、OCR、计算或复核后的必要结果交给主模型，不回传无关的整图描述。
