@wbline/pi-vision0.2.1

Vision capabilities for Pi coding agent — image understanding and visual analysis

wongbin Published 3 days ago MIT ~579 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.

Reports 0

No reports yet.

Readme

pi-vision

Pi coding agent 的视觉能力扩展 —— 安装后即获得 read_image 工具，自动把图片交给支持视觉的模型描述。零配置，开箱即用。

pi install npm:@wbline/pi-vision

使用方法

直接让 agent 看图即可，例如：

看一下 ./error.png 这张截图，告诉我报错内容是什么。

LLM 会调用 read_image 工具：

{
  "path": "./error.png",
  "prompt": "转录截图中的报错信息并给出修复建议，用用户的语言回答。"
}

参数	必填	说明
`path`	✓	图片路径（绝对路径或工作区相对路径）
`prompt`	✓	关注点描述，用用户的语言（如"转录报错"、"描述场景"）

成功时的返回示例：

截图显示一个 TypeScript 编译错误:TS2345 "Argument of type 'string' is not
assignable to parameter of type 'number'",位于 src/utils.ts:42 ...

[image: PNG, 148.3 KB, described by opencode/exo-free]

工作原理

就近优先：优先使用当前会话模型（若支持图像输入，零额外开销）
自动降级：失败时按轮次回退——每轮遍历各 provider 最好的视觉模型，同 provider 备选模型在后几轮，最多 3 轮
纯净请求：视觉请求固定不携带思考参数（reasoning: "off"、不发 reasoning_effort），从根源上避开部分网关的 reasoning_effort 校验问题

状态反馈

位置	行为
底部状态栏	`👁 模型名` 实时显示当前视觉模型，随识图与模型切换自动刷新；手动固定时带 `(pinned)` 标注
`/vision` 命令	无参数时弹出交互式选择框（方向键选择、回车确认）；也支持直接传模型名固定
识图播报	`read_image` 真正执行时才提示实际服务的模型；模型变化时才再次提示，不刷屏
启动提示	编辑器上方显示一次加载信息，首次输入后消失

手动指定视觉模型

默认自动选择（就近优先 + 失败降级）。需要固定某个模型时：

/vision —— 弹出选择框：列出 auto 和所有可用视觉模型（标注当前服务的 ← current 与已固定的 ← pinned），方向键选择、回车确认，Esc 取消
/vision <provider/model> —— 直接固定视觉模型（支持只写模型 id 或部分名称，唯一匹配即生效；也可用输入框的下拉补全）
/vision auto —— 恢复自动选择

固定的模型仍享有失败降级：它不可用或识图失败时，会自动回退到其他视觉模型。固定为会话级，重启 pi 后恢复自动。

TUI 与 ACP 客户端（如 JetBrains IDE）均适用。

支持格式与限制

格式：png、jpg、jpeg、gif、webp、bmp（仅位图 —— 不支持 SVG）
大小：单张图片最大 5 MB
需至少一个已配置认证且支持图像输入的模型（内置 provider 通过 /login 登录即可）

自定义模型

Pi 未内置的兼容端点，在 ~/.pi/agent/models.json 中为模型声明 "input": ["text", "image"]，即可参与识图：

{
  "providers": {
    "my-provider": {
      "baseUrl": "https://your-server.com/v1",
      "api": "openai-completions",
      "apiKey": "sk-...",
      "models": [
        { "id": "my-vision-model", "input": ["text", "image"] }
      ]
    }
  }
}