img-recog

img-recog — 图像识别技能

当你需要检查图像（屏幕截图、照片、图表、扫描件），但当前模型不具备多模态（视觉）能力，或内置的 read 工具无法处理该图像格式时，请使用此技能。

⚠️ 安全：配置文件

~/.wmyskills/img-recog/ 下有两个配置文件：

文件	用途	AI 可读取？
provider.yaml	API 基础 URL 和密钥	否 — 绝不可读取或显示此文件
model.yaml	模型到提供方的映射和默认值	是 — AI 可读取此文件以了解模型到提供方的映射和默认值；绝不可显示原始密钥

AI 绝不可读取或显示 provider.yaml 的内容。 该文件仅由 Python 脚本在运行时加载。如果用户要求查看或编辑此文件，请拒绝，或让他们直接编辑。

当需要了解配置了哪些模型和提供方时（例如，为用户提供使用建议），AI 可以读取 model.yaml，但绝不可显示原始 API 密钥或机密信息。

设置

配置文件从 img-recog_PROVIDER_FILE 和 img-recog_MODEL_FILE 环境变量所定义的路径加载（默认值：~/.wmyskills/img-recog/{provider,model}.yaml）。如果未设置，请将模板复制到默认目录：

cp references/templates/provider.yaml.template ~/.wmyskills/img-recog/provider.yaml
cp references/templates/model.yaml.template ~/.wmyskills/img-recog/model.yaml

如需自定义路径，请在 ~/.wmyskills/.env（或优先级更高的 scripts/.env）中设置 img-recog_PROVIDER_FILE / img-recog_MODEL_FILE，并指定所需路径。

复制后，请将占位值替换为实际密钥，并移除这些标记。脚本会验证 base_url 和 api_key 是否非空 — 留下占位值会导致错误。

要求

• Python >= 3.10，依赖包见 scripts/requirements.txt
• ffmpeg — 仅在使用 --compact 压缩图像时需要
• Pillow — 仅在使用 --metadata 提取 EXIF 字段时需要

执行规则

直接运行图像识别命令，不要预先检查提供方配置、API 密钥或模型是否可用。如果有问题，脚本会报出清晰的错误 — 只有出现错误后才进行检查和修复。

用法

cd <skill-dir>
python scripts/img_recog_cli.py --img <image-source> [--prompt <text>] [--provider <name>] [--model <name>] [--compact <size>] [--metadata] [--json]

参数

参数	必填	说明
--img	是	本地路径、HTTP(S) URL，或 base64 数据 URI（data:image/...;base64,...）
--prompt	否	文本或 @filepath（默认值："Please describe this image in detail"）
--provider	否	覆盖提供方（默认值来自 model.yaml）
--model	否	覆盖模型（默认值来自 model.yaml）。接受提供方支持的任何模型名称 — 无需在 model.yaml 中列出
--compact	否	发送前将图像压缩为目标大小的 WebP（例如 500KB、0.5MB、512000B；不带单位的数字按 KB 处理）。
--metadata	否	在识别的同时提取图像元数据（大小/宽度/高度/颜色/设备/应用/时间/位置）。元数据不会发送给模型 — 而是发送给 Agent（JSON：顶层 metadata 键；非 JSON：stderr 上的 [metadata] 块，获取后立即打印）。缺失字段为 null；获取失败时会发出警告并继续
--max-tokens	否	最大输出 token 数（默认值：4096）。必须是正整数
--json	否	输出包含全面信息的 JSON

快速示例

# Describe a local screenshot
python scripts/img_recog_cli.py --img screenshot.png

# Extract text from a photo with specific prompt
python scripts/img_recog_cli.py --img photo.jpg --prompt "Extract all text from this image"

# Fetch and describe an online image
python scripts/img_recog_cli.py --img https://example.com/diagram.png

# Use custom model
python scripts/img_recog_cli.py --provider openai --model gpt-5.6-terra --img chart.png

# Read prompt from file
python scripts/img_recog_cli.py --img graph.png --prompt @prompt.txt

# Structured JSON output
python scripts/img_recog_cli.py --img screenshot.png --json

# Compress a large screenshot to ≤ 500KB before sending
python scripts/img_recog_cli.py --img screenshot.png --compact 500KB

# Recognize + extract metadata
python scripts/img_recog_cli.py --img photo.jpg --metadata

参考文件

位置	用途
references/templates/	配置文件模板（复制到 ~/.wmyskills/img-recog/）
references/prompts/	常见任务的预置提示词模板（通过 --prompt @ 使用）
references/prompts/_system.md	系统提示词 — 脚本会自动将其作为 system 消息加载，告知视觉模型其输出将由另一个 AI 使用。它不是用户提示词预设；不要与 --prompt @ 搭配使用
references/prompts/index.yaml	提示词预设索引 — 技能加载时请先阅读，以了解可用预设及各自的使用场景

提示词预设

加载此技能时，首先读取 references/prompts/index.yaml，了解可用的预设（每个预设都有 name、lang 和 use_when）。

默认情况下，描述任务使用 describe.txt（用户要求“查看”“看”或“描述”图像时）。用户要求从图像中“读取”或“提取”文本时，使用 extract-text.txt。

# Example: describe in English
python scripts/img_recog_cli.py --img photo.jpg --prompt @references/prompts/describe.txt

# Example: extract text in Chinese
python scripts/img_recog_cli.py --img scan.png --prompt @references/prompts/extract-text-zh.txt

注意事项

• 脚本会自动检测 Windows 编码，并将 stdout 切换为 UTF-8
• 超时：连接 10s，读取 120s
• 对于本地图像，文件会在内存中读取并转换为 base64，不会创建临时文件
• 对于 URL 图像，图像会被下载并转换为 data URI，以实现最大的 API 兼容性
• --compact 会通过 ffmpeg 将图像压缩为 WebP。动画图像（GIF 等）以及原本已符合目标要求的图像会跳过重新编码
• --metadata 会在后台线程中运行，同时进行识别，然后报告：通过 ffprobe 获取的 size（原始字节数）、width/height/color（pix_fmt），以及通过 Pillow EXIF 获取的 device/app/time/location（GPS → 十进制度）。即使同时使用 --compact，所有字段也都反映原始图像的信息
• 默认的非 JSON 输出分为两个区块：[metadata]（使用 --metadata 时输出到 stderr）和 [result]（视觉模型的输出，输出到 stdout）。不会显示模型名称和 token 用量
• 可通过 img-recog_PROVIDER_FILE 和 img-recog_MODEL_FILE 环境变量覆盖配置文件路径（在 ~/.wmyskills/.env 或 scripts/.env 中设置）；默认路径仍为 ~/.wmyskills/img-recog/

故障排除

错误	可能原因
"Authentication failed"	检查 provider.yaml 中的 api_key
"Model not found at provider endpoint"	该模型名称在此 provider 上不存在
"Cannot connect to API"	检查 provider.yaml 中的 base_url 或网络连接
"Bad request / model may not support image input"	所选模型不支持视觉功能
"Request timed out"	图像过大或网络较慢
"ffmpeg not found"	安装 ffmpeg（参见 Requirements）
"Pillow is required for --metadata"	安装 Pillow（参见 Requirements）

添加提示词预设

添加新的提示词预设：

1. 在 references/prompts/ 中创建提示词文件
2. 在 references/prompts/index.yaml 中添加条目，包含 name、lang 和 use_when 字段
3. 在此 SKILL.md 的 Prompt Presets 部分添加用法示例