通用 Vision Tool

让 pi 主模型（即便本身不支持图片输入）也能「看」图片的扩展：主模型调用 vision 工具，把图片交给任意 OpenAI 兼容格式的多模态模型识别，返回文本结果。

每次发布递增版本号并记录变更，完整更新日志见 CHANGELOG.md。

最新更新

0.6.0

• 超大图自动缩放：本地图片的宽或高超过 maxImageSize（默认 2048，多数 OpenAI 兼容视觉模型的事实上限）时，上传前自动等比缩放到限制内，使用 pi 自带的 Photon WASM 缩放器。大截图、大 ER 图不再报 HTTP 400 input size exceed limit。
• 可按 Provider 配置 maxImageSize（范围 256–8192），留空用默认 2048，填 0 关闭自动缩放。
• 尺寸拒绝兜底：若请求被 HTTP 400 拒绝且错误信息里带尺寸上限（如 exceed limit 2048x2048、max 1024），vision 解析出限制、缩放所有图片后重试一次。覆盖那些上限与你配置不同的 Provider，无需手动调参。

0.5.0

• 流式分析（SSE）：请求带 stream: true，按 text/event-stream 增量读取。心跳（如 : PING）或任何数据块都算「有活动」，会重置空闲看门狗——一个持续慢速吐字但稳定推进的响应不会再被掐断。
• 空闲超时取代固定总时长：只有当 timeoutSeconds 内完全没有数据传输时才中断。响应可以流式传输数分钟仍成功。
• 多图结构化提示词：2 张图时先逐张描述再对比；3 张及以上按顺序描述并按序号引用。
• 超时上限从 600 秒放宽到 1800 秒（空闲超时让长上限变得安全）。
• 重试策略优化：仅在载荷小于 256 KB 时对 429/5xx 重试一次，大图请求不再二次冲击限流器；尊重服务端 Retry-After（上限 10 秒）。
• 清理 images.ts 中未使用的 win32/posix 导入；配置解析加入 schema 版本守卫与迁移占位。

0.4.0

• image_path 兜底参数：vision 工具新增可选 image_path。当用户消息或某个工具结果引用了本地图片文件，但当前回合没有附件时，主模型可直接传本地路径，由 vision 读取、校验并上传。支持 C:\x.png、/home/a.jpg、./pic.webp、~/x.gif，含空格的中文路径也认。
• 按模型能力自动开关：若主模型本身已支持图片输入（ctx.model.input 含 image）且未传 image_path，vision 返回提示让模型直接用原生视觉，避免冗余代理调用。
• 工具描述与 prompt 规则改写，明确告诉主模型在「read 返回了图但看不了」「image_generate 等保存了文件」「消息里有本地图片路径」时，用 vision({ image_path }) 兜底，不要自行 read 图字节。

0.3.2

• Provider 配置改为用户级全局配置，所有项目共享同一组 Provider。
• 自动迁移旧项目中的 .pi/vision.json。
• 根据 Base64 实际内容重新计算图片大小，避免限制被错误元数据绕过。
• 脱敏自定义请求 Header 中的敏感值。

0.3.1

• 模型列表支持搜索和分页。
• 增加快速 Provider 配置流程。
• Provider 列表显示凭据状态。
• 连接测试显示请求阶段、耗时和失败原因。
• 自定义 Header 支持逐项添加、修改和清空。

适用于 Pi >= 0.84.2 的项目扩展。入口为 index.ts，实现 vision Tool、/vision 和 /vision-config。已在 Pi 0.84.2、Node.js 20.3+ 验证。

使用

1. 启动 Pi 后运行 /vision-config。
2. 选择“新建 Provider”，填写名称、OpenAI-compatible Base URL、API Key、Vision Model；可选填写 Temperature、Max Tokens 和 Timeout。
3. 选择“测试当前 Provider”，确认连接成功。
4. 选择“保存并关闭”。
5. 让主模型看图即可。有三种方式让 vision 拿到图：
   • 附件：在同一条用户消息中附加图片并提问，例如“帮我看看这个截图为什么返回 403”。主模型自行决定调用 vision，不改变 /model。
   • Pi Ctrl+V：粘贴图片会生成 pi-clipboard-<uuid>.<ext> 临时文件，扩展只读取系统临时目录中符合该命名规则的真实图片并校验文件签名。
   • 本地路径（0.4.0+）：直接在消息里写出本地图片路径，或当 read/image_generate 等工具产生了图片文件，主模型可调用 vision({ image_path: "..." }) 让 vision 读取该文件。

图片来源与安全

• 支持来源：Pi 原生 ImageContent 附件、Pi Ctrl+V 临时文件、image_path 指定的本地文件。
• 支持格式：PNG、JPEG/JPG、WebP、GIF（实际是否接受 GIF 由后端模型决定）。
• 校验：每张图片校验扩展名、大小、文件签名（魔数），不匹配则拒绝发送。单张最多 20 MB，总计最多 40 MB，单条消息最多 16 张。

配置

配置默认保存在用户级 ~/.pi/agent/vision.json，因此所有项目共享同一组 Provider。也支持通过 PI_CODING_AGENT_DIR 修改 Pi 用户配置目录。旧版本项目中的 .pi/vision.json 会在首次打开时自动迁移到全局配置。API Key 也可使用环境变量引用。迁移前请勿提交包含 API Key 的旧 .pi/vision.json。

请求与超时

• 协议：OpenAI-compatible /chat/completions + data:image/*;base64,...，0.5.0 起默认走 SSE 流式（stream: true）。不支持流式或返回非 SSE 响应的 Provider 会自动回落到缓冲模式。
• 超时语义（0.5.0）：空闲超时。仅当 timeoutSeconds 内无任何数据传输才中断；只要有心跳或数据块持续到达，请求会一直跑下去。上限 1800 秒。
• 认证：支持 Bearer Token、API Key Header、无认证三种模式。
• 自定义：可配置 chat/models 路径、自定义 Headers；一次有限重试（仅对小于 256 KB 的小载荷）。
• 新增协议时，实现 VisionProvider 接口并在 createProvider() 的分支选择处增加适配即可，无需改动 Tool 或配置向导的数据流。