caomeiyouren vision-augment skill
为无视觉能力的 LLM 提供多模态能力（本地优先，视觉理解走视觉模型）。本 skill 负责使用引导：触发时机、环境探测与自动配置、MCP 调用方法；能力本体由 MCP server 提供。
安装
# 从 GitHub 安装到全局（opencode / hermes-agent 等，按需调整 -a）
npx skills add CaoMeiYouRen/vision-augment -g -a opencode -a hermes-agent -y
# 或项目级（不指定 -g）：npx skills add CaoMeiYouRen/vision-augment
同时需注册 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就断言"配置齐全" → 环境可能已变化，探测是唯一可靠来源