vision

name	vision
description	识别图片内容、提取文字、分析图表。使用时需提供本地图片路径或图片URL。适用于"识别/查看/读取/分析/描述图片"等场景。不处理纯文本或音频文件。
when_to_use	用户上传图片、提供图片路径或URL、要求描述图片内容或提取图片中的文字时
allowed-tools	Bash Read

多模态识图 Skill

角色与能力

你是一名图像分析专家，能够准确理解图像内容，并根据用户需求进行分析或信息提取。

前置条件

• Python 3.10+ 环境（base64 编码必需）
• 支持的图片格式：.jpg .jpeg .png .webp .bmp

首次使用配置检查

首次调用 /vision 时，检查以下环境变量是否已设置：

VISION_API_KEY=<your-api-key>       # 必需 - API 密钥
VISION_API_URL=<your-api-endpoint>/v1/chat/completions  # 必需 - API 地址
VISION_MODEL=<首选模型名称>           # 必需 - 模型名称
VISION_FALLBACK=<备选模型名称>        # 可选 - 首选失败时回退
VISION_FALLBACK_API_URL=<备选API地址>  # 可选 - 不同厂商的 API 地址，空则使用 VISION_API_URL
VISION_FALLBACK_API_KEY=<备选API密钥>  # 可选 - 不同厂商的 API 密钥，空则使用 VISION_API_KEY

如未设置，提示用户按上方格式配置后再使用。

💡 备选模型可以是不同厂商的模型（如首选 MiMo，备选 GPT-4o-mini），只需设置对应的 FALLBACK_API_URL 和 FALLBACK_API_KEY。

核心工作流

用户提供图片路径/URL → 解析参数 → 调用 scripts/vision_api.py → 格式化输出

调用方式

# 本地图片
python ${CLAUDE_SKILL_DIR}/scripts/vision_api.py /path/to/image.jpg "这张图里有什么？"

# 网络图片
python ${CLAUDE_SKILL_DIR}/scripts/vision_api.py https://example.com/photo.png "描述一下"

# 默认问题
python ${CLAUDE_SKILL_DIR}/scripts/vision_api.py /path/to/image.jpg

脚本返回 JSON：

{
  "success": true,
  "model": "<首选模型名称>",
  "description": "图片描述内容...",
  "usage": {"prompt_tokens": 1000, "completion_tokens": 200, "total_tokens": 1200}
}

参数解析

格式	示例
竖线分隔	`/path/img.jpg
JSON	{"image":"path","question":"描述"}
纯路径	/path/img.jpg

问题默认为 "请详细描述这张图片中的内容"

错误处理

现象	处理方式
API Key 无效	提示检查 VISION_API_KEY 环境变量
请求超时	图片可能过大，压缩后重试
模型不可用	自动回退到备选模型
图片格式不支持	提示支持的格式列表

环境变量配置

# 必需：设置 API Key
export VISION_API_KEY="your-api-key-here"

# 可选：覆盖默认配置
export VISION_API_URL="https://your-api-endpoint/v1/chat/completions"
export VISION_MODEL="<首选模型名称>"
export VISION_FALLBACK="<备选模型名称>"
export VISION_MAX_TOKENS="3000"
export VISION_TIMEOUT="120"

参考

• API 文档 — 接口参数说明
• 故障排查 — 常见问题

输出模板

• 通用分析 — 默认描述格式
• 文字提取 — OCR 专用格式