| name | vision-augment |
| description | 视觉增强 MCP —— 为无视觉能力的 LLM（如 DeepSeek、GLM）提供看图、OCR 与文档解析。当用户需要分析图片/截图内容、识别图片中的文字、解析 docx/pdf/pptx/xlsx/html 文档时使用。工具：mcp_vision_augment_vision（task_type=reasoning|ocr|document）、mcp_vision_augment_health（环境探测）、mcp_vision_augment_clear_cache。 |
vision-augment skill
为无视觉能力的 LLM 提供多模态能力（本地优先，视觉理解走视觉模型）。本 skill 负责使用引导：触发时机、环境探测与自动配置、MCP 调用方法；能力本体由 MCP server 提供。
安装
npx skills add CaoMeiYouRen/vision-augment -g -a opencode -a hermes-agent -y
同时需注册 MCP server（uvx vision-augment，stdio 或 streamable-http），配置见仓库 README。
环境探测与自动配置（推荐先做）
第一步总是调用 mcp_vision_augment_health，拿到环境状态后按下表向用户反馈还缺什么、给什么命令。不要凭空猜测配置。
| health 字段 | 状态 | 向用户反馈（含命令） |
|---|
channels 为空 且 ollama.reachable=false | 视觉理解不可用 | 二选一：① 配置 VISION_AUGMENT_CHANNELS（OpenAI 兼容端点 JSON 数组，base_url/api_key/model）；② ollama pull llava 启动本地 Ollama VL 模型 |
channels 非空 | 视觉理解已配置 | 无需操作（通道按序降级，失败自动兜底 Ollama） |
ollama.reachable=true | 本地兜底可用 | 无需操作 |
ocr_engine.available=false | OCR 引擎缺失 | 安装 extra：uvx vision-augment[ocr]（或重装：uv tool install "vision-augment[ocr] @ git+..."） |
document_engine.available=false | 文档引擎缺失 | 安装 extra：uvx vision-augment[document] |
transport / cache / input_limits | 信息项 | 一般无需反馈；cache.ttl_seconds=0 表示缓存关闭 |
若调用 mcp_vision_augment_health 失败（工具不存在/连不上），按顺序排查：MCP server 是否已注册（检查 harness 的 mcp_servers 配置，stdio 用 command: uvx, args: [vision-augment]）→ 服务端进程是否存活 → HTTP 模式端点 /mcp 是否可达。把排查结果与注册配置片段一并反馈用户。
MCP 使用方法
工具
| 工具 | 说明 |
|---|
mcp_vision_augment_vision | 主入口：task_type（reasoning 看图问答 / ocr 图片文字 / document 文档解析）+ source（路径 / file:// / http(s)://（需服务端开启）/ data:URL）+ task（reasoning 提问）+ language（OCR 语言，默认 ch） |
mcp_vision_augment_health | 环境探测（见上节） |
mcp_vision_augment_clear_cache | 清除本地结果缓存 |
任务选择
- 用户要求"看这张图/截图/描述图片内容/截图里的按钮" →
task_type=reasoning + task 提问
- 用户要求"提取图片里的文字/OCR/识别票据" →
task_type=ocr（language 默认 ch）
- 用户要求"解析/总结这个文档（docx/pdf/pptx/xlsx/html）" →
task_type=document
- 多步编排：文档内容含图表 → 先
document 解析全文，再对图页/截图单独 ocr 或 reasoning
调用示例
mcp_vision_augment_vision(task_type="reasoning", source="C:\\Users\\me\\截图.png", task="描述这张截图的内容，并指出按钮布局")
mcp_vision_augment_vision(task_type="ocr", source="C:\\Users\\me\\票据.png", language="ch")
mcp_vision_augment_vision(task_type="document", source="C:\\Users\\me\\报告.docx")
返回值（统一 JSON envelope）
{task_type, tool_used, code, error, result, confidence, metadata}：
code=0：成功；result 为结果文本；metadata.truncated=true 表示被截断code=1 通道失败 / code=2 超时 → 检查通道配置或 Ollama；可重试code=3 输入无效 → 检查 source 路径/格式/大小code=4 本地引擎未安装 → 按 error 提示安装对应 extras（见环境探测表）code=5 内部错误 → 反馈用户查看服务端日志（VISION_AUGMENT_DEBUG=true）
反模式
- 扫描版 PDF / 复杂表格 → 不要用
document，改用 ocr 逐页提取（或提示用户这是文档引擎边界）
- 不要重复调用
reasoning 问同一张图同一问题（结果已缓存）
- 未先跑
health 就断言"配置齐全" → 环境可能已变化，探测是唯一可靠来源
