omp packages

@yandy0725/pi-vision-tools0.3.1

pi package adding a describe_image tool that lets non-multimodal models delegate image analysis to a vision model

GitHub Actions Published 15 days ago MIT ~503 downloads/mo

Untested on omp

This is a pi package. No one has reported whether it works on omp yet. If you try it, add your result below.

Did it work for you?

Result

One report per person. A new report replaces your old one.

Reports 0

No reports yet.

Readme

pi-vision-tools

让非多模态模型通过委托给配置好的视觉模型来分析图像。提供一个 describe_image 工具 + /vision 命令。

功能

  • 一个工具（describe_image），将图像 + 提示词发送给支持视觉的模型，并将文本结果返回给调用方模型
  • 调用方模型按需控制成本/质量：compress（开关）、thinkLevel（从 off 到 xhigh）以及提示词本身——无需预配置
  • 模糊模型选择：按名称（"haiku"、"qwen vl"）或精确 provider/id 配置视觉模型；只考虑支持图像输入的模型
  • 始终按调用方模型模态自动开关：如果当前模型已支持图像输入，工具自动禁用；否则启用
  • 页脚指示器（👁 provider/model），在工具激活且视觉模型已配置时可见
  • 无需 /reload：配置更改即时生效

工作原理

调用方模型  →  describe_image  →  视觉模型  →  文本返回给调用方模型
（无视觉能力）     （图像+提示词）      （能看图像）
  1. 调用方模型调用 describe_image，传入图像和提示词
  2. 工具解码图像，可选使用 sharp 压缩，然后调用配置好的视觉模型
  3. 视觉模型的文本回答作为工具结果返回

前缀缓存

切换模型时自身的 prefix cache 已因 model 变化而失效，setActiveTools 增删 describe_image 只是新 model 系统提示的正常组成部分，不会额外造成 cache 抖动。

对同一个 model，tool 列表是确定的（无视觉一定带 describe_image，有视觉一定不带），所以中间切换到其他 model 再切回来时，前缀内容与先前一致，仍然能命中原有缓存。

安装

pi install npm:@yandy0725/pi-vision-tools

或在 ~/.pi/agent/settings.json 中添加：

{
  "packages": ["npm:@yandy0725/pi-vision-tools"]
}

配置

/vision 命令

命令 功能
/vision 或 /vision status 显示当前配置：解析后的 provider/model、默认 think level、工具是否激活、调用方模型是否支持视觉
/vision config model <m> 设置视觉模型：精确 provider/id（如 openai/gpt-4o）或模糊名（如 haiku、qwen vl）
/vision config default-think-level <level> 设置默认 think level：off、minimal、low、medium、high、xhigh。工具参数 thinkLevel 优先于它；非法值会被拒绝且不写盘

配置持久化到 ~/.pi/agent/vision-tools.json，即时生效——无需 /reload。

工具启停是自动的：调用方模型自带图像输入时 describe_image 会从工具列表中移除，否则启用——没有任何强制开关。 老配置键（enabled、defaultReasoning）在加载时被忽略；升级后如需固定 think level，请重新设置一次。

模型选择

model 可以填精确的 provider/id，也可以填模糊名。模糊匹配会对所有可用且支持图像输入的模型打分：精确 id > id/完整名包含 > 展示名包含 > 所有分词都出现。因此 haiku、qwen vl、anthropic haiku 都能解析到具体模型（前提是它已配置鉴权）。不支持图像输入的模型永远不会被选中；没有任何匹配时，报错会列出所有可用的视觉模型。

/vision status、/vision config model 的确认信息和页脚指示器都显示解析后的 provider/id，所以用模糊名时你始终能看到它实际选了什么：

{ "model": "haiku" }

配置只读取 model 与 defaultThinkLevel 两个字段——没有单独的 provider 配置。想锁定某个 provider 时把它写进值里："model": "anthropic/claude-haiku-4-5"。

可选：sharp

安装 sharp 以在发送前自动压缩图像：

npm install sharp

sharp 是可选的。没有它，图像将原样发送（不报错）。压缩会将最长边降采样至 ≤1568px，去除 alpha 通道，并转换为 JPEG 格式。

环境变量

变量 默认值 说明
PI_VISION_MAX_DIM 1568 最长边像素上限（1–10000）
PI_VISION_JPEG_QUALITY 85 JPEG 质量（1–100）

在任何调用中设置 compress: false 可跳过压缩，用于需要像素级精度的场景（读取坐标、检查微小 UI 元素）。

工具参考

describe_image(image_path: string, prompt: string, compress?: boolean, thinkLevel?: string)
参数 必填 默认值 说明
image_path 是 — 文件路径、data: URL 或原始 base64（>100 字符）
prompt 是 — 给视觉模型的指令
compress 否 true 发送前是否压缩；设为 false 以获取像素级精度
thinkLevel 否 off think level：off、minimal、low、medium、high、xhigh

示例工具调用

{
  "image_path": "/home/user/screenshot.png",
  "prompt": "请描述这张截图中看到的内容。",
  "compress": true,
  "thinkLevel": "high"
}

示例提示词

用途 提示词
描述图像 "请详细描述这张图片。"
读取坐标/位置 "提交按钮的像素坐标是多少？"
提取文字（OCR） "提取这张图片中所有可见的文字。"
查找 UI 缺陷 "检查这张截图中是否存在布局、对齐或文字溢出问题。"
解释图表 "请逐步解释这个架构图。"
分析错误 "这个错误信息是什么意思，如何修复？"

think level

级别 适用场景
off 简单描述、文字提取、基础问答
minimal 快速浏览，"这是什么？"
low 略多思考、中等细节
medium 详细描述、UI 检查
high 复杂分析、架构图、代码截图
xhigh 深度推理、bug 排查、多步骤视觉谜题

支持的图像格式

支持：PNG、JPEG、GIF、WebP、BMP。

输入可以是：

  • 文件路径（/path/to/image.png、./relative.png，支持 ~ 前缀）
  • data: URL（data:image/png;base64,...）
  • 原始 base64（字符串 >100 字符，自动检测）

许可证

MIT