pi-vision-tools

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

功能

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

工作原理

调用方模型  →  describe_image  →  视觉模型  →  文本返回给调用方模型
（无视觉能力）     （图像+提示词）      （能看图像）

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

安装

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

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

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

配置

/vision 命令

| 命令 | 功能 | |---------|------| | /vision 或 /vision status | 显示当前配置：provider/model、启用状态、生效开关、调用方模型是否支持视觉 | | /vision config provider <p> | 设置视觉模型提供商（如 openai、anthropic） | | /vision config model <m> | 设置视觉模型 ID（如 gpt-4o、claude-sonnet-4-20250514） | | /vision config default-reasoning <level> | 设置默认推理深度：off、minimal、low、medium、high、xhigh | | /vision on | 强制启用工具（即使调用方模型支持视觉） | | /vision off | 强制禁用工具 | | /vision auto | 自动模式：仅当调用方模型不支持图像输入时启用（默认） |

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

可选：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, reasoning?: string)

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

示例工具调用

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

示例提示词

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

推理级别

| 级别 | 适用场景 | |-------|------| | 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