pi-vlm-proxy

让不认识图片的模型，也能看懂图片

给 pi 用的视觉代理扩展 —— 把图片识别委托给任意 OpenAI 兼容的多模态模型

_{主模型 deepseek-v4-flash 不支持视觉，图片识别被自动委托给 doubao-seed-2-1-turbo}

这是什么

DeepSeek 这类模型很强，但看不见图片。你丢一张截图过去，它只能干瞪眼。

本扩展给它加一个 describe_image 工具：图片先送到你指定的多模态模型那里转成文字，再交回主模型继续对话。你不必为了看一张图就切换主模型。

flowchart LR
    A["🖼️ 丢一张图"] --> B{"主模型<br/>支持视觉？"}
    B -->|"支持"| C["图片原生直发主模型<br/>自动隐藏工具 · 零额外开销"]
    B -->|"不支持"| D["调用 describe_image"]
    D --> E["转发给你配置的 VLM"]
    E --> F["📝 返回文字描述"]
    F --> G["主模型据此继续对话"]

关键在于它会自己判断该不该出场：主模型本身支持视觉时，扩展自动隐藏工具、让图片原生透传，不产生任何额外 API 调用。切换模型时自动同步，你不需要手动开关。

快速开始

pi install npm:pi-vlm-proxy

装好后在 pi 里跑 /vision add，依次填四样东西：

模型名称:   doubao                                      ← 自己起的代号
API 地址:   https://ark.cn-beijing.volces.com/api/v3    ← 自动补 /chat/completions
API Key:    $ARK_API_KEY                                ← 支持环境变量引用
模型 ID:    doubao-seed-2-1-turbo-260628

完事。之后主模型遇到图片会自动调用，无需任何额外操作。

# 从 GitHub 装（可指定版本）
pi install git:github.com/lawrencewzen/pi-vlm-proxy@v0.1.1

# 临时试用，只对本次运行生效，退出即消失
pi -e npm:pi-vlm-proxy

{ "extensions": ["/path/to/pi-vlm-proxy"] }

特性

命令

[name] 可省略 —— 省略时弹出选择列表，带参数时支持 Tab 补全。

Vision 设置面板
⚙️ 主模型 deepseek-chat 不支持视觉 → 由 describe_image 委托下面的模型识别

📋 视觉模型 (2):
  ● doubao  (doubao-seed-2-1-turbo-260628 @ https://ark.cn-beijing.volces.com/api/v3)
    stepfun (step-3.7-flash @ https://api.stepfun.ai/v1)

  1. 切换当前模型 (use)
  2. 添加模型 (add)
  3. 编辑模型 (edit)
  4. 删除模型 (remove)
  0. 退出

配置

配置存在 ~/.pi/agent/vision-config.json，包本身不含任何厂商信息。

{
  "current": "volcengine",
  "providers": {
    "volcengine": {
      "baseUrl": "https://ark.cn-beijing.volces.com/api/v3",
      "apiKey": "$VOLC_ARK_KEY",
      "model": "doubao-seed-2-1-turbo-260628"
    },
    "stepfun": {
      "baseUrl": "https://api.stepfun.ai/v1",
      "apiKey": "$STEPFUN_KEY",
      "model": "step-3.7-flash"
    }
  }
}

透传模式

模式在模型切换时自动同步（/model、Ctrl+P、会话恢复），切换即生效并提示。

auto 覆盖绝大多数情况，所以没做子命令。留这个字段是给 auto 判断失灵时的逃生阀 —— 主模型元数据没标 image、或标了却调不通，手改配置即可强制。

工具用法

主模型看到图片时自动调用，两种传参方式：

describe_image(path: "/path/to/screenshot.png")
describe_image(data: "data:image/png;base64,...", mimeType: "image/png")

• 粘贴的截图 —— pi 会写入 /tmp/pi-clipboard-*.png 并插入路径文本，主模型拿着路径调用
• 磁盘上的图 —— 直接把路径告诉主模型即可

开发

npm run typecheck            # 类型检查
npm test                     # 61 项单元测试
pi -e ./extensions/index.ts  # 在 pi 里加载本地扩展试用

测试跑在隔离的临时 HOME + 本地假 HTTP 端点上，不发真实请求、不触碰真实配置：

• test/config.test.ts —— 读写、校验、脱敏、原子写、损坏恢复
• test/vision.test.ts —— 鉴权头、超时、响应形态、体积上限、类型嗅探
• test/commands.test.ts —— 用假 ExtensionAPI 驱动真实 /vision 命令与 describe_image 工具

License

MIT © lawrence